windows-development-sandbox 1.5.0 → 1.7.0

package/dist/guest/setup/claude-profile.js

@@ -57,7 +57,8 @@ export function mergeMcpServers(hostFile, guestFile, hostWorkspace, guestWorkspa
     writeJsonAtomic(guestFile, merged);
     return Object.keys(host.mcpServers ?? {}).length + Object.keys(hostProject).length;
 }
-export function syncClaudeProfile() {
+/** `credentials`: the text of this PC's .credentials.json, handed over in the one-shot secrets file. */
+export function syncClaudeProfile(credentials) {
     const profile = session.claudeProfile;
     if (profile.items.length === 0) {
         log('No Claude settings were staged from this PC.');
@@ -68,6 +69,16 @@ export function syncClaudeProfile() {
     for (const name of profile.items) {
         const from = path.join(source, name);
         const to = path.join(claudeDir, name);
+        if (name === '.credentials.json') {
+            // Never staged in the launch folder: it came in the secrets file.
+            if (credentials && !exists(to)) {
+                fs.writeFileSync(to, credentials, 'utf8');
+                log('Claude settings: copied ' + name + ' from this PC');
+            }
+            else
+                log("Claude settings: kept the sandbox's " + name);
+            continue;
+        }
         if (!exists(from))
             continue;
         if ((KEEP_SANDBOX_COPY.includes(name) || !profile.overwrite) && exists(to)) {

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

@@ -14,3 +14,9 @@ export declare function persistEnvironment(env: NodeJS.ProcessEnv, toolVars: str
  * the boot project's terminals see never changes; the project's own sessions get its full environment anyway.
  */
 export declare function addMachineEnvironment(vars: Record<string, string>, dirs: string[], additive?: boolean): void;
+/**
+ * The environment for a program the daemon starts (an agent session, `sandbox exec`): its own PATH, plus every machine
+ * and user PATH folder added since the daemon started (python, cargo, other agents ...) at the end. Never changes
+ * `env`; without Windows it is returned as it is.
+ */
+export declare function withRegistryPath(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/guest/setup/environment.js

@@ -2,10 +2,14 @@
 import path from 'node:path';
 import { claudeDir, session, stateDir, workspace } from '../runtime/session.js';
 import { dataDir, dryRun, isWin, testMode, toolsDir } from '../runtime/paths.js';
-import { mkdirp } from '../runtime/fs.js';
-import { runScriptWithJson } from '../runtime/process.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { execOutput, runScriptWithJson } from '../runtime/process.js';
+import { SYSTEM } from '../../shared/system.js';
 import { warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
+import { localStateVars } from '../agents/local-state.js';
+import { agentPaths } from '../agents/agent-files.js';
+import { appendMissing, expandVars, isPinnedNodeDir, parseRegPath, pathKey, planPath } from './path-plan.js';
 /** Older launch folders have no agentHomes: these two were always set. */
 const LEGACY_HOMES = { CODEX_HOME: 'codex', GEMINI_CLI_HOME: 'gemini' };
 /** Every agent's home variable (CODEX_HOME ...) with the folder it points to in the persistent state. */
@@ -31,6 +35,7 @@ export function agentEnv(tools, target = { workspace, project: session.project,
         ...tools.vars,
         CLAUDE_CONFIG_DIR: claudeDir,
         ...homes,
+        ...localStateVars(),
         npm_config_cache: path.join(toolsDir, 'npm-cache'),
         npm_config_update_notifier: 'false',
         AGENT_WORKSPACE: target.workspace,
@@ -41,7 +46,13 @@ export function agentEnv(tools, target = { workspace, project: session.project,
         AGENT_SANDBOX: '1',
         AGENT_SANDBOX_WORKSPACE: target.workspace,
     };
-    for (const dir of [env.CLAUDE_CONFIG_DIR, ...Object.keys(homes).map((n) => env[n]), env.npm_config_cache])
+    const local = Object.keys(localStateVars());
+    for (const dir of [
+        env.CLAUDE_CONFIG_DIR,
+        ...Object.keys(homes).map((n) => env[n]),
+        env.npm_config_cache,
+        ...local.map((n) => env[n]),
+    ])
         mkdirp(dir);
     // The runner's own Node (bootstrap.ps1 puts it first on PATH) is not exposed: `node` is whatever nvm selected.
     const runners = [path.join(toolsDir, 'node'), path.dirname(process.execPath)].map((d) => d.toLowerCase());
@@ -53,13 +64,17 @@ export function agentEnv(tools, target = { workspace, project: session.project,
 export function persistEnvironment(env, toolVars) {
     if (!isWin || dryRun || testMode)
         return;
-    const vars = Object.fromEntries([...toolVars, ...AGENT_VARS, ...Object.keys(agentHomes())]
+    const vars = Object.fromEntries([...toolVars, ...AGENT_VARS, ...Object.keys(agentHomes()), ...Object.keys(localStateVars())]
         .filter((n) => env[n] !== undefined)
         .map((n) => [n, env[n]]));
     try {
         runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', {
             vars,
-            path: env.PATH ?? '',
+            path: planPath({
+                entries: [env.PATH ?? '', ...installedAgentDirs()],
+                exists,
+                drop: (dir) => isPinnedNodeDir(dir, nvmHome()),
+            }).join(path.delimiter),
             add: [],
             additive: false,
         });
@@ -76,10 +91,45 @@ export function persistEnvironment(env, toolVars) {
 export function addMachineEnvironment(vars, dirs, additive = false) {
     if (!isWin || dryRun || testMode)
         return;
+    // Folders that do not exist stay out, and so does a pinned Node version (`nvm use` could not move it).
+    const planned = planPath({ entries: dirs, exists, drop: (dir) => isPinnedNodeDir(dir, nvmHome()) });
     try {
-        runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', { vars, path: null, add: dirs, additive });
+        runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', { vars, path: null, add: planned, additive });
     }
     catch (e) {
         warn('Could not add to the environment: ' + errMsg(e));
     }
 }
+const nvmHome = () => path.join(toolsDir, 'nvm');
+/** The folder of every configured agent that is installed: its command works in any terminal. */
+function installedAgentDirs() {
+    return Object.entries(session.agents ?? {}).flatMap(([name, harness]) => {
+        const p = agentPaths(toolsDir, name, harness);
+        return (p.exe && exists(p.exe)) || (p.cmd && exists(p.cmd)) ? [p.dir] : [];
+    });
+}
+const MACHINE_ENVIRONMENT_KEY = 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment';
+const USER_ENVIRONMENT_KEY = 'HKCU\\Environment';
+const registryPath = (key) => parseRegPath(execOutput(SYSTEM.reg(), ['query', key, '/v', 'Path']));
+/**
+ * The environment for a program the daemon starts (an agent session, `sandbox exec`): its own PATH, plus every machine
+ * and user PATH folder added since the daemon started (python, cargo, other agents ...) at the end. Never changes
+ * `env`; without Windows it is returned as it is.
+ */
+export function withRegistryPath(env) {
+    if (!isWin || dryRun || testMode)
+        return env;
+    try {
+        const registry = expandVars(registryPath(MACHINE_ENVIRONMENT_KEY) + ';' + registryPath(USER_ENVIRONMENT_KEY), env);
+        const runner = pathKey(path.join(toolsDir, 'node'));
+        const pathName = Object.keys(env).find((k) => k.toLowerCase() === 'path') ?? 'PATH';
+        return {
+            ...env,
+            [pathName]: appendMissing(env[pathName] ?? '', registry, (dir) => pathKey(dir) === runner || isPinnedNodeDir(dir, nvmHome())),
+        };
+    }
+    catch (e) {
+        warn('Could not read the machine PATH (the session keeps the one it has): ' + errMsg(e));
+        return env;
+    }
+}

package/dist/guest/setup/path-plan.d.ts

@@ -0,0 +1,32 @@
+/** A folder as a comparison key: one slash style, no trailing slash (a drive root keeps its one), lower case. */
+export declare function pathKey(folder: string): string;
+/** The folders of a PATH string: no empty parts, no quotes around a folder. */
+export declare function splitPath(value: string): string[];
+/** Replaces %NAME% with the variable's value (any case); a name that is not set stays as written. */
+export declare function expandVars(value: string, env: Readonly<Record<string, string | undefined>>): string;
+export interface PathPlanInput {
+    /** In the order they should have: earlier entries win. */
+    readonly entries: readonly string[];
+    readonly exists: (folder: string) => boolean;
+    /** Entries to leave out (a folder that must not be machine-wide, matched like pathKey). */
+    readonly drop?: (folder: string) => boolean;
+}
+/** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
+export declare function planPath(input: PathPlanInput): string[];
+/** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
+export declare function appendMissing(base: string, extra: string, skip?: (folder: string) => boolean): string;
+/**
+ * What a new shell gets: folders only this process has first (a parent put them there on purpose), then the machine
+ * and the user PATH with their %VARIABLES% expanded; no duplicates. `skip` leaves folders out (the runner's own Node).
+ */
+export declare function rebuildPath(o: {
+    readonly machine: string;
+    readonly user: string;
+    readonly process: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly skip?: (folder: string) => boolean;
+}): string;
+/** The value of `Path` in the output of `reg query <key> /v Path` ('' when there is none). */
+export declare function parseRegPath(output: string): string;
+/** A folder of one pinned Node version (nvm's `v24.22.0`): never machine-wide, `nvm use` would not move it. */
+export declare function isPinnedNodeDir(folder: string, nvmHome: string): boolean;

package/dist/guest/setup/path-plan.js

@@ -0,0 +1,67 @@
+// The one place that decides which folders are on the machine PATH, in what order, and how a process's PATH is brought
+// up to date with the registry. Pure (no side effects): the self-test imports this file. The shells' own start-up code
+// (sandbox\csharp\PathSync.cs) follows the same rules.
+import path from 'node:path';
+/** A folder as a comparison key: one slash style, no trailing slash (a drive root keeps its one), lower case. */
+export function pathKey(folder) {
+    const slashes = folder.trim().replace(/^"|"$/g, '').replace(/\//g, '\\');
+    return (slashes.length > 3 ? slashes.replace(/\\+$/, '') : slashes).toLowerCase();
+}
+/** The folders of a PATH string: no empty parts, no quotes around a folder. */
+export function splitPath(value) {
+    return value
+        .split(';')
+        .map((part) => part.trim().replace(/^"|"$/g, ''))
+        .filter(Boolean);
+}
+/** Replaces %NAME% with the variable's value (any case); a name that is not set stays as written. */
+export function expandVars(value, env) {
+    const lower = new Map(Object.entries(env).map(([k, v]) => [k.toLowerCase(), v]));
+    return value.replace(/%([^%;\\]+)%/g, (whole, name) => lower.get(name.toLowerCase()) ?? whole);
+}
+/** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
+export function planPath(input) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of input.entries.flatMap(splitPath)) {
+        const key = pathKey(entry);
+        if (seen.has(key) || input.drop?.(entry) || !input.exists(entry))
+            continue;
+        seen.add(key);
+        result.push(entry);
+    }
+    return result;
+}
+/** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
+export function appendMissing(base, extra, skip = () => false) {
+    const seen = new Set(splitPath(base).map(pathKey));
+    const added = splitPath(extra).filter((folder) => {
+        const key = pathKey(folder);
+        if (seen.has(key) || skip(folder))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return [...splitPath(base), ...added].join(';');
+}
+/**
+ * What a new shell gets: folders only this process has first (a parent put them there on purpose), then the machine
+ * and the user PATH with their %VARIABLES% expanded; no duplicates. `skip` leaves folders out (the runner's own Node).
+ */
+export function rebuildPath(o) {
+    const registry = splitPath(expandVars(o.machine, o.env) + ';' + expandVars(o.user, o.env));
+    const known = new Set(registry.map(pathKey));
+    const only = splitPath(o.process).filter((f) => !known.has(pathKey(f)) && !o.skip?.(f));
+    return planPath({ entries: [...only, ...registry], exists: () => true }).join(';');
+}
+/** The value of `Path` in the output of `reg query <key> /v Path` ('' when there is none). */
+export function parseRegPath(output) {
+    const line = output.split(/\r?\n/).find((l) => /^\s+Path\s+REG_(EXPAND_)?SZ\s/i.test(l));
+    return line ? line.replace(/^\s+Path\s+REG_(EXPAND_)?SZ\s+/i, '').trim() : '';
+}
+/** A folder of one pinned Node version (nvm's `v24.22.0`): never machine-wide, `nvm use` would not move it. */
+export function isPinnedNodeDir(folder, nvmHome) {
+    const key = pathKey(folder);
+    const home = pathKey(nvmHome);
+    return key.startsWith(home + '\\') && /^v\d/.test(path.win32.basename(key));
+}

package/dist/guest/setup/shell-path.d.ts

@@ -0,0 +1 @@
+export declare function installShellPath(): void;

package/dist/guest/setup/shell-path.js

@@ -0,0 +1,22 @@
+// New shells (PowerShell, PowerShell 7, cmd, Git Bash) start with the current machine PATH, whatever their parent had:
+// pathsync.exe is built and the shells' start-up files call it (sandbox\scripts\install-shell-path.ps1).
+import fs from 'node:fs';
+import path from 'node:path';
+import { dryRun, isWin, localDir, testMode, toolsDir } from '../runtime/paths.js';
+import { mkdirp } from '../runtime/fs.js';
+import { ensureCompiled } from '../runtime/csc.js';
+import { runScript } from '../runtime/process.js';
+export function installShellPath() {
+    if (!isWin || dryRun || testMode)
+        return;
+    const helper = path.join(mkdirp(path.join(localDir, 'bin')), 'pathsync.exe');
+    fs.copyFileSync(ensureCompiled('pathsync'), helper);
+    runScript('install-shell-path.ps1', [
+        '-Helper',
+        helper,
+        '-PwshDir',
+        path.join(toolsDir, 'pwsh'),
+        '-GitRoot',
+        path.join(toolsDir, 'git'),
+    ]);
+}

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

@@ -77,7 +77,7 @@ export async function setupPython(env, config, versions) {
     const py3 = await installPython('python', versions.python.spec);
     const shims = shimDir(py3);
     shimPair(shims, '3', py3);
-    env.prepend.push(py3, path.join(py3, 'Scripts'), shims);
+    env.prepend.push(py3, mkdirp(path.join(py3, 'Scripts')), shims);
     env.vars.PYTHONIOENCODING = 'utf-8';
     env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + '; py works too)');
     if (!config.python2) {

package/dist/guest/toolchains/runtimes.js

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

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

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

package/dist/guest/vpn/index.js

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

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

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

package/dist/guest/vpn/openvpn.js

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

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

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

package/dist/guest/vpn/tunnel.js

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

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

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

package/dist/guest/vpn/vpn.js

@@ -0,0 +1,126 @@
+// The VPN boot step (after the toolchains, before the agent): install OpenVPN, block everything that does not go
+// through the tunnel (the kill switch, applied BEFORE the tunnel starts), connect, check, delete the login, report. A
+// tunnel that fails never stops the boot: with the kill switch the sandbox stays offline and says so; without it, it
+// warns.
+import dns from 'node:dns';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { assertSafeOvpn } from '../../shared/vpn/ovpn.js';
+import { isIPv4 } from '../../shared/network/firewall-rules.js';
+import { killSwitchCommands, tunnelCommands } from '../../shared/vpn/kill-switch.js';
+import { errMsg } from '../../core/util/errors.js';
+import { run as netsh } from '../network/firewall.js';
+import { dryRun, isWin, launchDir, run } from '../runtime/paths.js';
+import { log, warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { ensureOpenVpn } from './openvpn.js';
+import { startTunnel } from './tunnel.js';
+/** Writes run\vpn.json (what `sandbox vpn status` and the launch show). Never throws. */
+export function setVpnStatus(state, message, extra = {}) {
+    try {
+        writeJsonAtomic(run.vpnFile, {
+            state,
+            message: message.slice(0, 1900),
+            killSwitch: session.vpn?.killSwitch ?? false,
+            updatedAt: now(),
+            ...(session.vpn ? { server: session.vpn.server.slice(0, 120) } : {}),
+            ...extra,
+        });
+    }
+    catch (e) {
+        warn('Could not write the VPN status: ' + errMsg(e));
+    }
+}
+/** IPv4 addresses of the servers the profile names: names are looked up now, before the kill switch closes DNS. */
+async function serverAddresses(remotes) {
+    const out = [];
+    for (const r of remotes) {
+        const ips = isIPv4(r.host)
+            ? [r.host]
+            : await dns.promises.lookup(r.host, { all: true, family: 4 }).then((all) => all.map((a) => a.address), () => []);
+        for (const ip of ips)
+            out.push({ ip, port: r.port, proto: r.proto });
+    }
+    return out;
+}
+/** What the sandbox looks like from outside, through the tunnel (null when it cannot be told quickly). */
+async function publicAddress() {
+    try {
+        const text = (await (await fetch('https://api.ipify.org', { signal: AbortSignal.timeout(10000) })).text()).trim();
+        return /^[0-9a-fA-F.:]{3,45}$/.test(text) ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+const hasAdapter = (ip) => Object.values(os.networkInterfaces()).some((list) => (list ?? []).some((i) => i.address === ip));
+/** The whole step. Returns true when the tunnel is up. */
+export async function setupVpn(secrets, ptyHostExe) {
+    const vpn = session.vpn;
+    if (!vpn)
+        return true;
+    const killSwitch = vpn.killSwitch;
+    let blocked = false;
+    const block = (servers) => {
+        if (isWin && !dryRun)
+            netsh(killSwitchCommands(servers, ptyHostExe));
+        blocked = true;
+        log('VPN: kill switch on: nothing leaves the sandbox except through the tunnel.');
+    };
+    setVpnStatus('starting', 'Starting the VPN');
+    try {
+        if (!session.networking)
+            throw new Error('networking is off for this sandbox');
+        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);
+        const result = await startTunnel({ exe, profile, username: credentials.username, password: credentials.password });
+        if (!result.ok)
+            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 } : {});
+        return true;
+    }
+    catch (e) {
+        const reason = errMsg(e);
+        // Without the kill switch the sandbox keeps its normal connection: the rest of the boot goes on, with a warning.
+        try {
+            if (killSwitch && !blocked)
+                block([]);
+        }
+        catch (blockError) {
+            warn('VPN: could not close the network after the failure: ' + errMsg(blockError));
+        }
+        const text = 'VPN failed: ' +
+            reason +
+            (killSwitch
+                ? ' The kill switch is on, so this sandbox has NO internet access.'
+                : ' The kill switch is off, so this sandbox is using your normal connection.');
+        warn(text);
+        setVpnStatus('failed', reason);
+        return false;
+    }
+}

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

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

package/dist/host/channel/attach.js

@@ -25,7 +25,7 @@ export function isSandboxAddress(ip, interfaces = os.networkInterfaces()) {
         }));
 }
 /** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
-const hostEndpoint = (session) => {
+export const hostEndpoint = (session) => {
     // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
     const addresses = insideSandbox()
         ? ['127.0.0.1']

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

@@ -1,5 +1,12 @@
 import type { GuestRequest, GuestResponse, Harness, SandboxStatus, SessionStatus } from '../../core/types.js';
 import type { ProjectSpec } from '../../shared/channel/index.js';
+/**
+ * The boot script writes its first status once Windows has booted the sandbox and logged on (a minute or two, longer on
+ * a slow PC or the very first start); none after this long means it never got going.
+ */
+export declare const FIRST_STATUS_MS: number;
+/** True when a boot is silent: no status of this launch yet, and the sandbox had its time to write one. */
+export declare function bootSilent(elapsedMs: number, seenStatus: boolean, limitMs?: number): boolean;
 /** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
 export declare const MAX_QUERIED_SESSIONS = 32;
 /** Where progress lines go: printed by default; a spinner passes its own. Text from the sandbox, made safe first. */