windows-development-sandbox 1.1.0 → 1.4.1

package/dist/guest/netproxy.js

@@ -0,0 +1,100 @@
+// The sandbox's own proxy for network.allowOnly (runs detached for the sandbox's life, as sbx-netproxy.exe so the
+// firewall can let only it out). HTTPS goes through CONNECT, plain HTTP as proxy requests; a host that is not allowed
+// gets 403 and a line in logs\netproxy.log. With network.proxy set it hands everything on to that proxy.
+// Usage: sbx-netproxy.exe netproxy.js
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { expandAllowList, hostAllowed, PROXY_PORT } from '../shared/netpolicy.js';
+import { logsDir, session } from './env.js';
+const allowed = expandAllowList(session.network.allowOnly ?? []);
+const upstream = session.network.proxy ? new URL(session.network.proxy) : null;
+const logFile = path.join(logsDir, 'netproxy.log');
+let logged = 0;
+/** Refusals, capped: a program retrying in a loop must not fill the disk. */
+const refuse = (host) => {
+    if (logged++ > 5000)
+        return;
+    try {
+        fs.appendFileSync(logFile, new Date().toISOString() + ' blocked ' + host + '\n');
+    }
+    catch { /* ignore */ }
+};
+/** Opens a TCP tunnel to host:port, directly or through the upstream proxy (CONNECT). */
+const tunnel = (host, port, onReady, onError) => {
+    if (!upstream) {
+        const socket = net.connect(port, host, () => onReady(socket));
+        socket.once('error', onError);
+        return;
+    }
+    const socket = net.connect(Number(upstream.port || 80), upstream.hostname, () => socket.write('CONNECT ' + host + ':' + port + ' HTTP/1.1\r\nHost: ' + host + ':' + port + '\r\n\r\n'));
+    socket.once('error', onError);
+    let head = '';
+    const onData = (chunk) => {
+        head += chunk.toString('latin1');
+        const end = head.indexOf('\r\n\r\n');
+        if (end < 0) {
+            if (head.length > 16384) {
+                socket.destroy();
+                onError();
+            }
+            return;
+        }
+        socket.off('data', onData);
+        if (!/^HTTP\/1\.\d 200/.test(head)) {
+            socket.destroy();
+            onError();
+            return;
+        }
+        const rest = Buffer.from(head.slice(end + 4), 'latin1');
+        if (rest.length)
+            socket.unshift(rest);
+        onReady(socket);
+    };
+    socket.on('data', onData);
+};
+const server = http.createServer((req, res) => {
+    // Plain HTTP: the request line has the full URL.
+    let target;
+    try {
+        target = new URL(req.url ?? '');
+    }
+    catch {
+        res.writeHead(400).end('bad proxy request');
+        return;
+    }
+    if (!hostAllowed(target.hostname, allowed)) {
+        refuse(target.hostname);
+        res.writeHead(403, { 'Content-Type': 'text/plain' }).end('Blocked by the sandbox (network.allowOnly): ' + target.hostname + '\n');
+        return;
+    }
+    const options = upstream
+        ? { host: upstream.hostname, port: Number(upstream.port || 80), path: target.href, method: req.method, headers: req.headers }
+        : { host: target.hostname, port: Number(target.port || 80), path: target.pathname + target.search, method: req.method, headers: req.headers };
+    const out = http.request(options, (up) => { res.writeHead(up.statusCode ?? 502, up.headers); up.pipe(res); });
+    out.on('error', () => { if (!res.headersSent)
+        res.writeHead(502).end('upstream error');
+    else
+        res.destroy(); });
+    req.pipe(out);
+});
+server.on('connect', (req, client, head) => {
+    const [host, portText] = (req.url ?? '').split(/:(?=\d+$)/);
+    const port = Number(portText || 443);
+    client.on('error', () => client.destroy());
+    if (!host || !(port > 0 && port < 65536) || !hostAllowed(host, allowed)) {
+        refuse(host ?? '?');
+        client.end('HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n\r\nBlocked by the sandbox (network.allowOnly): ' + host + '\n');
+        return;
+    }
+    tunnel(host, port, (remote) => {
+        client.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        if (head.length)
+            remote.write(head);
+        remote.pipe(client);
+        client.pipe(remote);
+        remote.on('error', () => client.destroy());
+    }, () => client.end('HTTP/1.1 502 Bad Gateway\r\n\r\n'));
+});
+server.listen(PROXY_PORT, '127.0.0.1');

package/dist/guest/ptyhost.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { ensureCompiled } from './helpers.js';
 import { portOpen } from './ports.js';
-import { logsDir } from './env.js';
+import { logsDir, session, toolsDir } from './env.js';
 export const ensurePtyHost = () => ensureCompiled('ptyhost');
 /** Resolves when ptyhost listens; rejects early if it exits first (e.g. the agent could not be started). */
 export const waitForPtyHost = async (child, port, timeoutMs) => {
@@ -30,7 +30,17 @@ export const ptyHostLogTail = (id, lines = 12) => {
         return '';
     }
 };
+/** conpty.dll (+ OpenConsole.exe) the host downloaded, when provisioning.conpty is on; ptyhost falls back to Windows' own. */
+const conptyDll = () => {
+    const dll = path.join(toolsDir, 'conpty', 'conpty.dll');
+    return session.provisioning.conpty?.enabled !== false && fs.existsSync(dll) && fs.existsSync(path.join(toolsDir, 'conpty', 'OpenConsole.exe')) ? dll : null;
+};
 /** Starts ptyhost detached, so closing a terminal tab never kills the agent; only the agent exiting ends it. */
-export const startPtyHost = (o) => spawn(o.exe, [String(o.port), o.token, String(o.cols), String(o.rows), ptyHostLog(o.id), o.command, o.restartCommand], {
-    cwd: o.cwd, env: { ...o.env, PTYHOST_BIND: o.remote ? 'any' : 'loopback' }, detached: true, stdio: 'ignore', windowsHide: true,
-});
+export const startPtyHost = (o) => {
+    const env = { ...o.env, PTYHOST_BIND: o.remote ? 'any' : 'loopback' };
+    delete env.PTYHOST_CONPTY;
+    const dll = conptyDll();
+    if (dll)
+        env.PTYHOST_CONPTY = dll;
+    return spawn(o.exe, [String(o.port), o.token, String(o.cols), String(o.rows), ptyHostLog(o.id), o.command, o.restartCommand], { cwd: o.cwd, env, detached: true, stdio: 'ignore', windowsHide: true });
+};

package/dist/guest/setup/claude.d.ts

@@ -14,8 +14,4 @@ export declare const claudeMemPaths: {
     local: string;
 };
 export declare const restoreClaudeMem: () => void;
-/**
- * Copies the live claude-mem folder back to persistent storage (staging folder + swap, never a half copy). Called from
- * the daemon tick: when no database changed since the last save it does nothing (no copy of the whole folder).
- */
 export declare const saveClaudeMem: () => void;

package/dist/guest/setup/claude.js

@@ -89,6 +89,17 @@ export const restoreClaudeMem = () => {
     const previous = claudeMemPaths.store + '.previous';
     if (!exists(claudeMemPaths.store) && exists(previous))
         fs.renameSync(previous, claudeMemPaths.store);
+    // A store that is gone or damaged: the newest backup that is a real database.
+    const backups = claudeMemPaths.store + '.backups';
+    if (!looksLikeSqlite(path.join(claudeMemPaths.store, 'claude-mem.db')) || !exists(claudeMemPaths.store)) {
+        const good = (exists(backups) ? fs.readdirSync(backups).sort().reverse() : []).find((b) => exists(path.join(backups, b, 'claude-mem.db')) && looksLikeSqlite(path.join(backups, b, 'claude-mem.db')));
+        if (good) {
+            if (exists(claudeMemPaths.store))
+                fs.renameSync(claudeMemPaths.store, claudeMemPaths.store + '.damaged-' + Date.now());
+            fs.cpSync(path.join(backups, good), claudeMemPaths.store, { recursive: true });
+            warn('claude-mem: the stored database was missing or damaged; restored the backup from ' + new Date(Number(good)).toISOString() + '.');
+        }
+    }
     if (!exists(claudeMemPaths.store))
         return;
     robocopy(claudeMemPaths.store, claudeMemPaths.local);
@@ -117,6 +128,36 @@ let lastSaved = null;
  * Copies the live claude-mem folder back to persistent storage (staging folder + swap, never a half copy). Called from
  * the daemon tick: when no database changed since the last save it does nothing (no copy of the whole folder).
  */
+const SQLITE_HEADER = 'SQLite format 3\0';
+/** A database file that starts like SQLite and is not empty (a missing one counts as fine: nothing to protect yet). */
+const looksLikeSqlite = (file) => {
+    if (!exists(file))
+        return true;
+    const fd = fs.openSync(file, 'r');
+    try {
+        const head = Buffer.alloc(16);
+        return fs.readSync(fd, head, 0, 16, 0) === 16 && head.toString('latin1') === SQLITE_HEADER;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+};
+const MAX_BACKUPS = 3;
+const BACKUP_EVERY_MS = 6 * 3600 * 1000;
+/** Moves the replaced copy into `dir` as a dated backup (at most one per 6 hours, the newest 3 kept); else deletes it. */
+const keepBackup = (previous, dir) => {
+    if (!exists(previous))
+        return;
+    const backups = exists(dir) ? fs.readdirSync(dir).filter((n) => /^\d{13}$/.test(n)).sort() : [];
+    const newest = Number(backups[backups.length - 1] ?? 0);
+    if (Date.now() - newest < BACKUP_EVERY_MS) {
+        fs.rmSync(previous, { recursive: true, force: true });
+        return;
+    }
+    fs.renameSync(previous, path.join(mkdirp(dir), String(Date.now())));
+    for (const old of [...backups, String(Date.now())].slice(0, -MAX_BACKUPS))
+        fs.rmSync(path.join(dir, old), { recursive: true, force: true });
+};
 export const saveClaudeMem = () => {
     if (!claudeMemEnabled() || !exists(claudeMemPaths.local))
         return;
@@ -124,12 +165,17 @@ export const saveClaudeMem = () => {
     const fingerprint = databaseFingerprint(local);
     if (fingerprint === lastSaved && exists(store))
         return;
+    // A damaged copy (zero-filled after a crash, cut short) must never replace the store: that once destroyed the only copy.
+    if (!looksLikeSqlite(path.join(local, 'claude-mem.db'))) {
+        warn('claude-mem: the local database does not look valid, so it was not saved over the stored copy (' + local + ').');
+        return;
+    }
     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) });
-    // Swap without a window where no copy exists: old aside, new in, then drop the old one.
+    // 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))
         fs.renameSync(store, previous);
@@ -141,6 +187,6 @@ export const saveClaudeMem = () => {
             fs.renameSync(previous, store);
         throw e;
     }
-    fs.rmSync(previous, { recursive: true, force: true });
+    keepBackup(previous, store + '.backups');
     lastSaved = fingerprint;
 };

package/dist/guest/setup/network.d.ts

@@ -6,5 +6,14 @@ export type LanState = 'blocked' | 'open' | 'offline';
  * all, the block stays in place: being offline is never a reason to open the LAN.
  */
 export declare const applyNetworkPolicy: (ptyHostExe: string | null) => Promise<LanState>;
+/** HTTP_PROXY & co. for everything in the sandbox: its own proxy (allowOnly) or yours (network.proxy). */
+export declare const proxyEnv: () => Record<string, string>;
+/**
+ * network.allowOnly, after the tools are installed: the sandbox's proxy (a copy of Node named sbx-netproxy.exe, so the
+ * firewall can tell it apart) is the only program allowed out, besides DNS and DHCP; Windows and browsers use it as
+ * the system proxy, everything else through HTTP_PROXY. A guardrail for agents that behave: an admin in the sandbox
+ * could undo it, which is why sandbox.networking false is the only hard isolation.
+ */
+export declare const applyAllowOnly: () => Promise<boolean>;
 /** Guest IPv4 addresses the host can use to reach session ports. */
 export declare const guestAddresses: () => string[];

package/dist/guest/setup/network.js

@@ -1,10 +1,13 @@
 // Guest firewall: block the host's LAN (keeping DNS/DHCP to the gateway) and let the host reach session ports.
 import dns from 'node:dns';
+import fs from 'node:fs';
 import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { buildFirewallCommands, ipv4DnsServers, parseDefaultGateways, parseDnsServers } from '../../shared/netrules.js';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { expandAllowList, PROXY_PORT, relayPort, withBlockedHosts } from '../../shared/netpolicy.js';
+import { buildFirewallCommands, ipv4DnsServers, isIPv4, parseDefaultGateways, parseDnsServers } from '../../shared/netrules.js';
 import { SYSTEM } from '../../shared/system.js';
-import { dryRun, isWin, log, session, warn } from '../env.js';
+import { dryRun, errMsg, isWin, launchDir, log, session, toolsDir, warn } from '../env.js';
 const ATTACH_RULE = 'AgentSandbox-Attach';
 const netsh = (args) => {
     const r = spawnSync(SYSTEM.netsh(), args, { encoding: 'utf8', windowsHide: true });
@@ -68,7 +71,21 @@ export const applyNetworkPolicy = async (ptyHostExe) => {
     const block = session.network.blockPrivateRanges;
     const exempt = block ? discoverExemptIps() : [];
     const lanRules = block ? buildFirewallCommands(exempt) : [];
-    const commands = [...lanRules, ...(ptyHostExe && session.attach.enabled ? attachRule(ptyHostExe) : [])];
+    const commands = [...lanRules, ...(ptyHostExe && session.attach.enabled ? attachRule(ptyHostExe) : []), ...forwardRule()];
+    if (isWin && !dryRun) {
+        try {
+            applyBlockedHosts();
+        }
+        catch (e) {
+            warn('network.blockHosts could not be applied: ' + errMsg(e));
+        }
+        try {
+            applyDns();
+        }
+        catch (e) {
+            warn('network.dns could not be applied: ' + errMsg(e));
+        }
+    }
     if (!block)
         log('Private-range blocking disabled by config.');
     if (block)
@@ -95,5 +112,81 @@ export const applyNetworkPolicy = async (ptyHostExe) => {
     log('LAN blocked in the guest firewall (10/8, 172.16/12, 192.168/16, 100.64/10, link-local, multicast, IPv6 local, SMB); DNS/DHCP to the gateway allowed.');
     return 'blocked';
 };
+// ---- the rest of the network settings -----------------------------------------------------------------------------
+const FORWARD_RULE = 'AgentSandbox-Forward';
+const ALLOW_RULES = ['AgentSandbox-Proxy-Out', 'AgentSandbox-DNS-Out-UDP', 'AgentSandbox-DNS-Out-TCP', 'AgentSandbox-DHCP-Out'];
+const HOSTS_FILE = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'drivers', 'etc', 'hosts');
+/** network.blockHosts: those names go nowhere (the sandbox's hosts file; the registry and files are new every boot). */
+const applyBlockedHosts = () => {
+    const hosts = session.network.blockHosts ?? [];
+    if (!hosts.length)
+        return;
+    const text = fs.existsSync(HOSTS_FILE) ? fs.readFileSync(HOSTS_FILE, 'utf8') : '';
+    fs.writeFileSync(HOSTS_FILE, withBlockedHosts(text, hosts));
+    log('Blocked hosts (network.blockHosts): ' + hosts.join(', '));
+};
+/** network.dns: these servers on every connected adapter. */
+const applyDns = () => {
+    const servers = (session.network.dns ?? []).filter(isIPv4);
+    if (!servers.length)
+        return;
+    const r = spawnSync(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command', "Get-NetAdapter | Where-Object Status -eq 'Up' | Set-DnsClientServerAddress -ServerAddresses " + servers.map((s) => "'" + s + "'").join(',')], { encoding: 'utf8', windowsHide: true });
+    if (r.status !== 0)
+        throw new Error('could not set the DNS servers: ' + (r.stderr ?? '').trim().slice(0, 300));
+    log('DNS servers (network.dns): ' + servers.join(', '));
+};
+/** network.forwardPorts: the relays (in the daemon) take connections from the PC only, i.e. the sandbox's own subnet. */
+const forwardRule = () => {
+    const forwards = session.network.forwardPorts ?? [];
+    return forwards.length ? [
+        ['advfirewall', 'firewall', 'delete', 'rule', 'name=' + FORWARD_RULE],
+        ['advfirewall', 'firewall', 'add', 'rule', 'name=' + FORWARD_RULE, 'dir=in', 'action=allow', 'enable=yes', 'profile=any', 'protocol=tcp', 'remoteip=LocalSubnet', 'localport=' + forwards.map((_f, i) => relayPort(i)).join(',')],
+    ] : [];
+};
+/** HTTP_PROXY & co. for everything in the sandbox: its own proxy (allowOnly) or yours (network.proxy). */
+export const proxyEnv = () => {
+    const own = (session.network.allowOnly ?? []).length > 0;
+    const url = own ? 'http://127.0.0.1:' + PROXY_PORT : session.network.proxy ?? '';
+    if (!url)
+        return {};
+    const noProxy = 'localhost,127.0.0.1,::1';
+    return { HTTP_PROXY: url, HTTPS_PROXY: url, http_proxy: url, https_proxy: url, NO_PROXY: noProxy, no_proxy: noProxy };
+};
+/**
+ * network.allowOnly, after the tools are installed: the sandbox's proxy (a copy of Node named sbx-netproxy.exe, so the
+ * firewall can tell it apart) is the only program allowed out, besides DNS and DHCP; Windows and browsers use it as
+ * the system proxy, everything else through HTTP_PROXY. A guardrail for agents that behave: an admin in the sandbox
+ * could undo it, which is why sandbox.networking false is the only hard isolation.
+ */
+export const applyAllowOnly = async () => {
+    const hosts = session.network.allowOnly ?? [];
+    if (!session.networking || !hosts.length)
+        return false;
+    if (!isWin || dryRun) {
+        log('(dry run) would allow only: ' + hosts.join(', '));
+        return false;
+    }
+    const exe = path.join(toolsDir, 'netproxy', 'sbx-netproxy.exe');
+    fs.mkdirSync(path.dirname(exe), { recursive: true });
+    if (!fs.existsSync(exe) || fs.statSync(exe).size !== fs.statSync(process.execPath).size)
+        fs.copyFileSync(process.execPath, exe);
+    spawn(exe, [path.join(launchDir, 'runtime', 'netproxy.js')], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    const add = (name, extra) => ['advfirewall', 'firewall', 'add', 'rule', 'name=' + name, 'dir=out', 'action=allow', 'enable=yes', 'profile=any', ...extra];
+    run([
+        ...ALLOW_RULES.map((n) => ['advfirewall', 'firewall', 'delete', 'rule', 'name=' + n]),
+        add('AgentSandbox-Proxy-Out', ['program=' + exe]),
+        add('AgentSandbox-DNS-Out-UDP', ['protocol=udp', 'remoteport=53']),
+        add('AgentSandbox-DNS-Out-TCP', ['protocol=tcp', 'remoteport=53']),
+        add('AgentSandbox-DHCP-Out', ['protocol=udp', 'remoteport=67', 'localport=68']),
+        ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,blockoutbound'],
+        ['winhttp', 'set', 'proxy', '127.0.0.1:' + PROXY_PORT, '<local>'],
+    ]);
+    const internet = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings';
+    for (const [name, type, value] of [['ProxyEnable', 'REG_DWORD', '1'], ['ProxyServer', 'REG_SZ', '127.0.0.1:' + PROXY_PORT], ['ProxyOverride', 'REG_SZ', '<local>']]) {
+        spawnSync(SYSTEM.reg(), ['add', internet, '/v', name, '/t', type, '/d', value, '/f'], { windowsHide: true, stdio: 'ignore' });
+    }
+    log('Only these hosts can be reached now (network.allowOnly): ' + expandAllowList(hosts).join(', ') + '. Refused ones are listed in logs\\netproxy.log.');
+    return true;
+};
 /** Guest IPv4 addresses the host can use to reach session ports. */
 export const guestAddresses = () => Object.values(os.networkInterfaces()).flat().filter((i) => Boolean(i) && i.family === 'IPv4' && !i.internal).map((i) => i.address);

package/dist/guest/setup/user.js

@@ -44,4 +44,8 @@ export const setupGitConfig = (env) => {
     spawnSync(git, ['config', '--global', '--add', 'safe.directory', '*'], { env: rest, windowsHide: true, stdio: 'ignore' });
     // Windows long paths are on in the sandbox, but git skips files over 260 characters unless told.
     spawnSync(git, ['config', '--global', 'core.longpaths', 'true'], { env: rest, windowsHide: true, stdio: 'ignore' });
+    // Git for Windows' system config says autocrlf=true: checkouts made in the sandbox (worktrees, clones) got CRLF and
+    // tools that want LF (rustfmt, shellcheck, prettier) failed on every file. "input" keeps the line endings the repo
+    // has, and a checkout from your PC (CRLF in the folder) still shows as unchanged.
+    spawnSync(git, ['config', '--global', 'core.autocrlf', 'input'], { env: rest, windowsHide: true, stdio: 'ignore' });
 };

package/dist/guest/toolchains/index.js

@@ -1,8 +1,17 @@
+// Every developer toolchain and database the sandbox provides (the list is in plan.ts). Installers run in parallel (a
+// few at a time; downloads and installers do not block each other) and each is independent: one failing never blocks
+// the rest. A step that needs another (Rust links with MinGW's gcc, uv installs the Python tools) waits for it.
+// The boot runs it once for the launch folder; the session daemon runs it again for each project registered later,
+// possibly several at once, so the same kind of step (two Node installs, two Go installs) never runs twice at a time.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { watchDownloads } from '../../shared/download.js';
 import { log, mkdirp, setSandboxStatus } from '../env.js';
 import { emptyEnv, step, tool } from './common.js';
 import { plan } from './plan.js';
 /** How many installers run at once: enough to overlap downloads with installs, few enough not to thrash the disk. */
 const PARALLEL = 4;
+/** The step a download belongs to (several run at once), for its progress. */
+const currentStep = new AsyncLocalStorage();
 /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
 const locks = new Map();
 const lockKey = (name) => name.split(' ')[0].toLowerCase();
@@ -30,9 +39,17 @@ const runSteps = async (steps, o) => {
     const running = new Set();
     const waiting = [];
     let done = 0;
-    const say = o.report ?? ((message) => setSandboxStatus('provisioning', message));
+    // The boot (no `report`) also publishes structured progress: what runs now, how far its download is, how many are done.
+    const percent = new Map();
+    const active = () => [...running].map((name) => ({ name, ...(percent.has(name) ? { percent: percent.get(name) } : {}) }));
+    const say = o.report ?? ((message) => setSandboxStatus('provisioning', message, { active: active(), done, total: steps.length }));
     const report = () => { if (running.size)
         say('Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)'); };
+    if (!o.report)
+        watchDownloads(() => {
+            const name = currentStep.getStore();
+            return name ? (fraction) => { percent.set(name, Math.round(fraction * 100)); report(); } : null;
+        });
     for (const s of steps) {
         // Dependencies first (they are earlier in the plan, so their promises exist), then a free slot.
         finished.set(s.name, (async () => {
@@ -48,17 +65,26 @@ const runSteps = async (steps, o) => {
             running.add(s.name);
             report();
             try {
-                await exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name))));
+                await currentStep.run(s.name, () => exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name)))));
             }
             finally {
                 running.delete(s.name);
+                percent.delete(s.name);
                 done++;
                 report();
                 waiting.shift()?.();
             }
         })());
     }
-    await Promise.all(finished.values());
+    try {
+        await Promise.all(finished.values());
+    }
+    finally {
+        if (!o.report)
+            watchDownloads(null);
+    }
+    if (!o.report)
+        setSandboxStatus('provisioning', 'Set up ' + steps.length + ' toolchains and databases', { active: [], done, total: steps.length });
     return envs;
 };
 /** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */

package/dist/guest/toolchains/native/mesa.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import { installArchive } from '../../../shared/download.js';
 import { SYSTEM } from '../../../shared/system.js';
-import { dryRun, execAsync, exists, log } from '../../env.js';
+import { dryRun, execAsync, execOutput, exists, log } from '../../env.js';
 import { arch, installFromGithub, tool } from '../common.js';
 /**
  * Mesa 3D for Windows (llvmpipe): OpenGL 4.5 on the CPU when the sandbox has no GPU. Windows only offers OpenGL 1.1 in
@@ -40,7 +40,17 @@ const setupLavapipe = async (env, mesaDir) => {
         // The zip has x86 and x64 folders: only the 64-bit loader (and vulkaninfo) is extracted.
         await installArchive(VULKAN_RUNTIME, dir, { locate: 'vulkan-1.dll', fileName: 'vulkan-runtime.zip', members: ['*/x64/*'] });
     }
-    await execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', icd, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
+    const register = (file) => execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', file, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
+    await register(icd);
+    // sandbox.vGpu: the sandbox sees this PC's GPU through Direct3D 12, and Dozen runs Vulkan on it. Programs prefer it
+    // over lavapipe (a GPU before a CPU device); lavapipe stays for the ones that need it.
+    const dozen = path.join(mesaDir, arch === 'arm64' ? 'dzn_icd.aarch64.json' : 'dzn_icd.x86_64.json');
+    const gpu = hasGpu();
+    if (gpu && exists(dozen))
+        await register(dozen);
     env.prepend.push(dir);
-    env.summary.push('vulkan: lavapipe (software Vulkan 1.4 on the CPU), vulkaninfo on PATH; WGPU_BACKEND=vulkan for wgpu');
+    env.summary.push('vulkan: ' + (gpu && exists(dozen) ? 'Dozen (Vulkan on the GPU via Direct3D 12) and ' : '') + 'lavapipe (software Vulkan 1.4 on the CPU), vulkaninfo on PATH; WGPU_BACKEND=vulkan for wgpu');
 };
+/** A real display adapter (sandbox.vGpu on), not only the remote display or basic render driver. */
+const hasGpu = () => execOutput(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', '(Get-CimInstance Win32_VideoController).Name'], { timeout: 30000 })
+    .split(/\r?\n/).map((n) => n.trim()).some((n) => n && !/^Microsoft (Remote Display|Basic (Render|Display))/i.test(n));

package/dist/guest/toolchains/plan.d.ts

@@ -1,11 +1,13 @@
-import type { DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
+import type { Config, DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
 import { type ToolEnv } from './common.js';
+/** apps: the boot only (apps are machine-wide; a project that joins later shares them). */
 export interface ToolchainOptions {
     gitEnabled: boolean;
     gitAccess: GitAccess;
     hostGit: boolean;
     refresh: boolean;
     databases: DatabasePlan[];
+    apps?: Config['apps'];
 }
 /**
  * shared: the step's effect is machine-wide and the same for every project (an installer, a registry entry, a

package/dist/guest/toolchains/plan.js

@@ -1,8 +1,11 @@
 // Which toolchain and database steps this sandbox runs, in the order their PATH entries are listed, and what each
 // step depends on. The scheduler (index.ts) runs them.
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { dataDir, execAsync, exists, localDir } from '../env.js';
-import { projectWorkspace } from '../project-context.js';
+import { appsNeedMesa, setupApps } from '../apps/index.js';
+import { dataDir, dryRun, execAsync, exists, localDir, mkdirp } from '../env.js';
+import { ensureCompiled } from '../helpers.js';
 import { arch, installOnce, tool, wanted } from './common.js';
 import { DATABASE_NAMES, setupDatabase } from './databases/index.js';
 import { setupGit } from './git.js';
@@ -30,16 +33,46 @@ const setupPythonTools = async (env, tools) => {
         throw new Error('toolchains.python.tools needs uv (toolchains.uv.enabled)');
     await installOnce(env, 'uv tool', tools, (pkg) => execAsync(uv, ['tool', 'install', pkg], { env: { ...process.env, ...uvVars() } }));
 };
-/** Where cargo builds: shared with the PC's target\, a separate folder next to it, one on the sandbox's disk, or a path. */
+/**
+ * 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/cargoshim.cs) gives every checkout its own target\sandbox, so git worktrees of several agents
+ * never overwrite each other's builds.
+ */
 const cargoTarget = (targetDir) => {
-    if (targetDir === 'shared')
+    if (targetDir === 'shared' || targetDir === 'separate')
         return null;
-    if (targetDir === 'separate')
-        return path.join(projectWorkspace(), 'target', 'sandbox');
     if (targetDir === 'local')
         return path.join(localDir, 'cargo-target');
     return targetDir;
 };
+/** "separate": tools\shims\cargo\cargo.exe in front of the real cargo, which it runs with the checkout's target dir. */
+const cargoShim = (env, rust) => {
+    const real = path.join(tool('rust', 'cargo', 'bin'), 'cargo.exe');
+    if (rust.targetDir !== 'separate' || !exists(real))
+        return;
+    const dir = mkdirp(tool('shims', 'cargo'));
+    fs.copyFileSync(ensureCompiled('cargoshim'), path.join(dir, 'cargo.exe'));
+    env.prepend.unshift(dir);
+    env.vars.AGENT_REAL_CARGO = real;
+};
+/**
+ * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
+ * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made
+ * test executables bigger than the 2 GB Windows allows).
+ */
+const 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)));
+    const gnu = host.endsWith('-gnu');
+    fs.writeFileSync(file, [
+        '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',
+        '[build]', 'jobs = ' + jobs, '',
+        ...(gnu ? ['[profile.dev]', 'debug = "line-tables-only"', '', '[profile.test]', 'debug = "line-tables-only"', ''] : []),
+    ].join('\n'));
+};
 /**
  * Where cargo builds and where sccache keeps its cache. Cargo fingerprints hold absolute paths and the host toolchain,
  * so a target\\ shared with builds on the PC rebuilds every time the side changes: "separate" (the default) keeps a
@@ -57,6 +90,7 @@ const rustHost = (config) => {
     return cpu + (wanted(config.msvc.enabled, 'msvc') ? '-pc-windows-msvc' : '-pc-windows-gnu');
 };
 export const plan = (config, versions, o) => {
+    const apps = Boolean(o.apps && (o.apps.install.length || Object.keys(o.apps.custom).length));
     const java = wanted(config.java.enabled, 'java');
     const python = wanted(config.python.enabled, 'python');
     return [
@@ -71,14 +105,22 @@ export const plan = (config, versions, o) => {
         // Rust links with MSVC (msvc host) or MinGW's gcc (GNU host): whichever it uses goes first.
         {
             name: 'Rust', on: wanted(config.rust.enabled, 'rust'), after: ['C/C++', 'MSVC'],
-            run: async (env) => { await setupRust(env, { ...config.rust, host: rustHost(config) }, o.refresh); Object.assign(env.vars, rustCaches(config.rust)); },
+            run: async (env) => {
+                await setupRust(env, { ...config.rust, host: rustHost(config) }, o.refresh);
+                Object.assign(env.vars, rustCaches(config.rust));
+                if (!dryRun) {
+                    cargoDefaults(rustHost(config));
+                    cargoShim(env, config.rust);
+                }
+            },
         },
         { name: '.NET', on: wanted(config.dotnet.enabled, 'dotnet'), run: (env) => setupDotnet(env, config.dotnet, o.refresh) },
         { name: 'Go', on: wanted(config.go.enabled, 'go'), run: (env) => setupGo(env, config.go) },
         { name: 'Java', on: java, run: (env) => setupJava(env, config.java) },
         { name: 'Ruby', on: wanted(config.ruby.enabled, 'ruby'), run: (env) => setupRuby(env, config.ruby) },
         // PHP installs the Visual C++ runtime itself: one installer at a time.
-        { name: 'Visual C++ runtime', on: config.vcRuntime.enabled, shared: true, run: async (env) => { await setupVcRuntime(env); } },
+        // Many apps (bat, delta, Neovim, most GUIs, your own programs) are built against it too.
+        { name: 'Visual C++ runtime', on: config.vcRuntime.enabled || apps, shared: true, run: async (env) => { await setupVcRuntime(env); } },
         { name: 'PHP', on: wanted(config.php.enabled, 'php'), after: ['Visual C++ runtime'], run: (env) => setupPhp(env, config.php) },
         { name: 'Deno', on: wanted(config.deno.enabled, 'deno'), run: (env) => setupDeno(env) },
         { name: 'Bun', on: config.bun.enabled, run: (env) => setupBun(env) },
@@ -86,8 +128,10 @@ export const plan = (config, versions, o) => {
         { name: 'PowerShell 7', on: wanted(config.pwsh.enabled, 'pwsh'), run: (env) => setupPwsh(env, o.refresh) },
         // The openssl tool comes from Git's install: after Git.
         { name: 'CLI tools', on: Object.values(config.cli).some((v) => v !== false), after: ['Git'], run: (env) => setupCli(env, config.cli, o.gitAccess, o.refresh) },
-        { name: 'Mesa 3D', on: config.mesa.enabled, shared: true, run: (env) => setupMesa(env, config.mesa) },
+        { name: 'Mesa 3D', on: config.mesa.enabled || appsNeedMesa(o.apps), shared: true, run: (env) => setupMesa(env, config.mesa) },
         { name: 'VS Code', on: config.vscode.enabled, shared: true, run: (env) => setupVscode(env, o.refresh) },
+        // Desktop apps and extra tools (apps.install / apps.custom); games and 3D apps copy Mesa's OpenGL next to them.
+        { name: 'Apps', on: apps, shared: true, after: ['Mesa 3D', 'Visual C++ runtime'], run: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }) },
         { name: 'Python tools', on: python && config.python.tools.length > 0, after: ['Python', 'uv'], run: (env) => setupPythonTools(env, config.python.tools) },
         // DynamoDB Local runs on Java: the Java step installs the JDK first instead of racing it.
         // One server per database in the sandbox: a project that joins later shares the one the boot started.

package/dist/guest/toolchains/python.js

@@ -35,6 +35,27 @@ const shimPair = (folder, version, dir) => {
     shim(folder, 'python' + version, python);
     shim(folder, 'pip' + version, python + ' -m pip');
 };
+/**
+ * `py` like the Python launcher Windows installs: `py -3 x.py`, `py -3.12 ...`, `py -2 ...`, `py x.py`. The launcher
+ * itself is not portable, so py.cmd runs a small script that picks the interpreter (cmd's %* ignores shift).
+ */
+const pyLauncher = (folder, py3, py2) => {
+    const script = path.join(mkdirp(folder), 'py-launcher.py');
+    fs.writeFileSync(script, [
+        'import subprocess, sys',
+        'PY3, PY2 = ' + JSON.stringify(path.join(py3, 'python.exe')) + ', ' + JSON.stringify(py2 ? path.join(py2, 'python.exe') : null),
+        'args = sys.argv[1:]',
+        'exe = PY3',
+        "if args and args[0].startswith('-2'):",
+        '    if not PY2: sys.exit("py: Python 2 is not installed (toolchains.python.python2)")',
+        '    exe, args = PY2, args[1:]',
+        "elif args and (args[0] == '-3' or args[0].startswith('-3.') or args[0].startswith('-3-')):",
+        '    args = args[1:]',
+        'sys.exit(subprocess.call([exe] + args))',
+        '',
+    ].join('\n'));
+    shim(folder, 'py', '"' + path.join(py3, 'python.exe') + '" "' + script + '"');
+};
 export const setupPython = async (env, config, versions) => {
     if (dryRun) {
         log('(dry run) would provision Python ' + versions.python.spec + (config.python2 ? ' and Python 2.7' : ''));
@@ -45,10 +66,13 @@ export const setupPython = async (env, config, versions) => {
     shimPair(shims, '3', py3);
     env.prepend.push(py3, path.join(py3, 'Scripts'), shims);
     env.vars.PYTHONIOENCODING = 'utf-8';
-    env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + ')');
-    if (!config.python2)
+    env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + '; py works too)');
+    if (!config.python2) {
+        pyLauncher(shims, py3, null);
         return;
+    }
     const py2 = await installPython('python2', '2.7');
     shimPair(shims, '2', py2);
+    pyLauncher(shims, py3, py2);
     env.summary.push('python2: ' + path.basename(py2).replace('python2-', ''));
 };