windows-development-sandbox 1.4.0 → 1.4.3

package/dist/guest/network/allow-only.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { expandAllowList, PROXY_PORT } from '../../shared/network/policy.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, isWin, launchDir, toolsDir } from '../runtime/paths.js';
+import { log } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { run } from './firewall.js';
+const ALLOW_RULES = [
+    'AgentSandbox-Proxy-Out',
+    'AgentSandbox-DNS-Out-UDP',
+    'AgentSandbox-DNS-Out-TCP',
+    'AgentSandbox-DHCP-Out',
+];
+/** 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;
+};

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

@@ -0,0 +1,9 @@
+/** What the agent's manifest says about the LAN. */
+export type LanState = 'blocked' | 'open' | 'offline';
+export declare const run: (commands: string[][]) => void;
+/**
+ * Applies the LAN block. Internet is checked first; if it works before the rules but not after, the rules (not the
+ * internet) are the problem, so they are removed and the agent is told the LAN is open. If there is no internet at
+ * 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>;

package/dist/guest/{setup/network.js → network/firewall.js}

@@ -1,13 +1,15 @@
 // 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 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 { spawnSync } from 'node:child_process';
+import { relayPort, withBlockedHosts } from '../../shared/network/policy.js';
+import { buildFirewallCommands, ipv4DnsServers, isIPv4, parseDefaultGateways, parseDnsServers, } from '../../shared/network/firewall-rules.js';
 import { SYSTEM } from '../../shared/system.js';
-import { dryRun, errMsg, isWin, launchDir, log, session, toolsDir, warn } from '../env.js';
+import { dryRun, isWin } from '../runtime/paths.js';
+import { log, warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { errMsg } from '../../core/util/errors.js';
 const ATTACH_RULE = 'AgentSandbox-Attach';
 const netsh = (args) => {
     const r = spawnSync(SYSTEM.netsh(), args, { encoding: 'utf8', windowsHide: true });
@@ -24,7 +26,9 @@ const discoverExemptIps = () => {
     try {
         servers = ipv4DnsServers(dns.getServers());
     }
-    catch { /* fall back below */ }
+    catch {
+        /* fall back below */
+    }
     if (!servers.length)
         servers = parseDnsServers(spawnSync(SYSTEM.ipconfig(), ['/all'], { encoding: 'utf8', windowsHide: true }).stdout ?? '');
     return [...parseDefaultGateways(route.stdout ?? ''), ...servers];
@@ -49,9 +53,22 @@ const waitForInternet = async (seconds) => {
 /** Inbound rule for ptyhost only, and only from the sandbox's own subnet (where the host's Hyper-V adapter is). */
 const attachRule = (ptyHostExe) => [
     ['advfirewall', 'firewall', 'delete', 'rule', 'name=' + ATTACH_RULE],
-    ['advfirewall', 'firewall', 'add', 'rule', 'name=' + ATTACH_RULE, 'dir=in', 'action=allow', 'enable=yes', 'profile=any', 'protocol=tcp', 'remoteip=LocalSubnet', 'program=' + ptyHostExe],
+    [
+        'advfirewall',
+        'firewall',
+        'add',
+        'rule',
+        'name=' + ATTACH_RULE,
+        'dir=in',
+        'action=allow',
+        'enable=yes',
+        'profile=any',
+        'protocol=tcp',
+        'remoteip=LocalSubnet',
+        'program=' + ptyHostExe,
+    ],
 ];
-const run = (commands) => {
+export const run = (commands) => {
     for (const c of commands) {
         const r = netsh(c);
         if (r.status !== 0 && c[2] !== 'delete')
@@ -71,7 +88,11 @@ 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) : []), ...forwardRule()];
+    const commands = [
+        ...lanRules,
+        ...(ptyHostExe && session.attach.enabled ? attachRule(ptyHostExe) : []),
+        ...forwardRule(),
+    ];
     if (isWin && !dryRun) {
         try {
             applyBlockedHosts();
@@ -89,7 +110,8 @@ export const applyNetworkPolicy = async (ptyHostExe) => {
     if (!block)
         log('Private-range blocking disabled by config.');
     if (block)
-        log('Gateway/DNS addresses kept reachable for DNS only: ' + (exempt.length ? [...new Set(exempt)].join(', ') : '(none found)'));
+        log('Gateway/DNS addresses kept reachable for DNS only: ' +
+            (exempt.length ? [...new Set(exempt)].join(', ') : '(none found)'));
     if (!isWin || dryRun) {
         log('(dry run) firewall plan:');
         for (const c of commands)
@@ -114,7 +136,6 @@ export const applyNetworkPolicy = async (ptyHostExe) => {
 };
 // ---- 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 = () => {
@@ -130,7 +151,13 @@ 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 });
+    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(', '));
@@ -138,55 +165,23 @@ const applyDns = () => {
 /** 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;
+    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(','),
+            ],
+        ]
+        : [];
 };
-/** 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/network/proxy-server.d.ts

@@ -0,0 +1,2 @@
+import http from 'node:http';
+export declare const server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

package/dist/guest/{netproxy.js → network/proxy-server.js}

@@ -1,13 +1,10 @@
-// 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';
+import { expandAllowList, hostAllowed } from '../../shared/network/policy.js';
+import { logsDir } from '../runtime/paths.js';
+import { session } from '../runtime/session.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');
@@ -19,7 +16,9 @@ const refuse = (host) => {
     try {
         fs.appendFileSync(logFile, new Date().toISOString() + ' blocked ' + host + '\n');
     }
-    catch { /* ignore */ }
+    catch {
+        /* ignore */
+    }
 };
 /** Opens a TCP tunnel to host:port, directly or through the upstream proxy (CONNECT). */
 const tunnel = (host, port, onReady, onError) => {
@@ -54,7 +53,7 @@ const tunnel = (host, port, onReady, onError) => {
     };
     socket.on('data', onData);
 };
-const server = http.createServer((req, res) => {
+export const server = http.createServer((req, res) => {
     // Plain HTTP: the request line has the full URL.
     let target;
     try {
@@ -66,17 +65,36 @@ const server = http.createServer((req, res) => {
     }
     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');
+        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(); });
+        ? {
+            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) => {
@@ -85,7 +103,9 @@ server.on('connect', (req, client, head) => {
     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');
+        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) => {
@@ -97,4 +117,3 @@ server.on('connect', (req, client, head) => {
         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/{helpers.d.ts → runtime/csc.d.ts}

@@ -1,3 +1,3 @@
-export type Helper = 'ptyhost' | 'gitshim' | 'vswhere' | 'openssl' | 'cargoshim';
+export type Helper = 'ptyhost' | 'gitshim' | 'vswhere' | 'openssl' | 'cargoshim' | 'linkgate';
 /** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's sandbox\<name>.cs the first time it is needed. */
 export declare const ensureCompiled: (name: Helper) => string;

package/dist/guest/{helpers.js → runtime/csc.js}

@@ -8,9 +8,14 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { exists, launchDir, mkdirp } from './env.js';
+import { exists, mkdirp } from './fs.js';
+import { launchDir } from './paths.js';
 const CSC = path.join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
-const sourceHash = (name) => crypto.createHash('sha256').update(fs.readFileSync(path.join(launchDir, 'sandbox', name + '.cs'))).digest('hex').slice(0, 12);
+const sourceHash = (name) => crypto
+    .createHash('sha256')
+    .update(fs.readFileSync(path.join(launchDir, 'sandbox', name + '.cs')))
+    .digest('hex')
+    .slice(0, 12);
 /** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's sandbox\<name>.cs the first time it is needed. */
 export const ensureCompiled = (name) => {
     const exe = path.join(os.tmpdir(), 'agent-sandbox', name + '-' + sourceHash(name) + '.exe');

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

@@ -0,0 +1,2 @@
+export declare const exists: (p: string) => boolean;
+export declare const mkdirp: (p: string) => string;

package/dist/guest/runtime/fs.js

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+export const exists = (p) => fs.existsSync(p);
+export const mkdirp = (p) => {
+    fs.mkdirSync(p, { recursive: true });
+    return p;
+};

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

@@ -0,0 +1,3 @@
+export declare const log: (message: string) => void;
+export declare const warn: (message: string) => void;
+export declare const logPath: string;

package/dist/guest/runtime/log.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logsDir } from './paths.js';
+fs.mkdirSync(logsDir, { recursive: true });
+const logFile = path.join(logsDir, (process.env.AGENT_LOG_PREFIX ?? 'guest') + '-' + new Date().toISOString().replace(/[:.]/g, '-') + '.log');
+const append = (line) => {
+    try {
+        fs.appendFileSync(logFile, line + '\n');
+    }
+    catch {
+        /* logging must never break the run */
+    }
+};
+export const log = (message) => {
+    console.log(message);
+    append(message);
+};
+export const warn = (message) => {
+    console.warn('\x1b[33mWARNING: ' + message + '\x1b[0m');
+    append('WARNING: ' + message);
+};
+export const logPath = logFile;

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

@@ -0,0 +1,13 @@
+import { RunDir } from '../../shared/channel/run-dir.js';
+export declare const isWin: boolean;
+export declare const dryRun: boolean;
+/** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
+export declare const testMode: boolean;
+export declare const launchDir: string;
+export declare const dataDir: string;
+export declare const hostToolsDir: string;
+/** Folders that must stay on the sandbox's own disk (symlinks, SQLite) rather than in a mapped folder. */
+export declare const localDir: string;
+export declare const toolsDir: string;
+export declare const logsDir: string;
+export declare const run: RunDir;

package/dist/guest/runtime/paths.js

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import { RunDir } from '../../shared/channel/run-dir.js';
+export const isWin = process.platform === 'win32';
+export const dryRun = process.env.AGENT_DRY_RUN === '1';
+/** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
+export const testMode = process.env.AGENT_SANDBOX_TEST === '1';
+export const launchDir = process.env.AGENT_LAUNCH_DIR ?? 'C:\\AgentLaunch';
+export const dataDir = process.env.AGENT_DATA_DIR ?? 'C:\\AgentData';
+export const hostToolsDir = process.env.AGENT_HOST_TOOLS_DIR ?? 'C:\\HostTools';
+/** Folders that must stay on the sandbox's own disk (symlinks, SQLite) rather than in a mapped folder. */
+export const localDir = process.env.AGENT_LOCAL_DIR ?? 'C:\\nvm';
+export const toolsDir = path.join(dataDir, 'tools');
+export const logsDir = path.join(dataDir, 'logs');
+export const run = new RunDir(dataDir);

package/dist/guest/{ports.js → runtime/ports.js}

@@ -4,11 +4,17 @@ import net from 'node:net';
 export const freePort = () => new Promise((resolve, reject) => {
     const server = net.createServer();
     server.once('error', reject);
-    server.listen(0, '127.0.0.1', () => { const { port } = server.address(); server.close(() => resolve(port)); });
+    server.listen(0, '127.0.0.1', () => {
+        const { port } = server.address();
+        server.close(() => resolve(port));
+    });
 });
 /** Whether something accepts connections on 127.0.0.1:port. */
 export const portOpen = (port) => new Promise((resolve) => {
-    const socket = net.connect({ host: '127.0.0.1', port }, () => { socket.destroy(); resolve(true); });
+    const socket = net.connect({ host: '127.0.0.1', port }, () => {
+        socket.destroy();
+        resolve(true);
+    });
     socket.once('error', () => resolve(false));
 });
 /** Polls until the port accepts connections; false when `seconds` pass first. */

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

@@ -0,0 +1,15 @@
+import { type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
+/** Runs a program, streaming output, and throws with a readable message when it fails. */
+export declare const exec: (file: string, args: string[], options?: SpawnSyncOptions) => void;
+/** exec without blocking: other toolchains keep downloading while this one runs an installer. */
+export declare const execAsync: (file: string, args: string[], options?: SpawnOptions) => Promise<void>;
+export declare const execOutput: (file: string, args: string[], options?: SpawnSyncOptions) => string;
+export declare const powershell: (script: string) => void;
+/** Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success. */
+export declare const robocopy: (from: string, to: string, files?: string[]) => void;
+/**
+ * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,
+ * which is what made copying from this PC slow). Same file list as Copy-NodeFromHost in sandbox/bootstrap.ps1.
+ * Copied into a staging folder and renamed into place: node.exe alone (an interrupted copy) must not look like a full install.
+ */
+export declare const copyNode: (from: string, to: string) => void;

package/dist/guest/runtime/process.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+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 { SYSTEM } from '../../shared/system.js';
+import { isWin } from './paths.js';
+/** Runs a program, streaming output, and throws with a readable message when it fails. */
+export const exec = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { stdio: 'inherit', windowsHide: true, ...options });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(path.basename(file) + ' ' + args.slice(0, 3).join(' ') + ' failed with exit code ' + result.status);
+};
+/** exec without blocking: other toolchains keep downloading while this one runs an installer. */
+export const execAsync = async (file, args, options = {}) => {
+    const code = await spawnAsync(file, args, { stdio: 'inherit', ...options });
+    if (code !== 0)
+        throw new Error(path.basename(file) + ' ' + args.slice(0, 3).join(' ') + ' failed with exit code ' + code);
+};
+export const execOutput = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, ...options });
+    return result.status === 0 ? String(result.stdout ?? '').trim() : '';
+};
+export const powershell = (script) => exec(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script]);
+/** Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success. */
+export const robocopy = (from, to, files = []) => {
+    if (!isWin) {
+        if (!files.length) {
+            fs.cpSync(from, to, { recursive: true });
+            return;
+        }
+        fs.mkdirSync(to, { recursive: true });
+        for (const f of files.filter((f) => fs.existsSync(path.join(from, f))))
+            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 + ')');
+};
+/**
+ * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,
+ * which is what made copying from this PC slow). Same file list as Copy-NodeFromHost in sandbox/bootstrap.ps1.
+ * Copied into a staging folder and renamed into place: node.exe alone (an interrupted copy) must not look like a full install.
+ */
+export const copyNode = (from, to) => {
+    const work = stagingFolder(to);
+    try {
+        robocopy(from, work, ['node.exe', 'npm', 'npm.cmd', 'npx', 'npx.cmd']);
+        robocopy(path.join(from, 'node_modules', 'npm'), path.join(work, 'node_modules', 'npm'));
+        moveIntoPlace(work, to);
+    }
+    finally {
+        safeRemove(work, path.dirname(work));
+    }
+};

package/dist/guest/{project-context.js → runtime/project-context.js}

@@ -3,7 +3,7 @@
 // files and markers from projectWorkspace(), and duringSession() tells them to leave machine-wide state alone (the
 // nvm symlink, shims, compiled helpers in use) because sessions of other projects depend on it.
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { workspace } from './env.js';
+import { workspace } from './session.js';
 const store = new AsyncLocalStorage();
 export const withProject = (context, work) => store.run(context, work);
 export const projectWorkspace = () => store.getStore()?.workspace ?? workspace;

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

@@ -0,0 +1,5 @@
+import type { GuestSession } from '../../core/types.js';
+export declare const session: GuestSession;
+export declare const workspace: string;
+export declare const stateDir: string;
+export declare const claudeDir: string;

package/dist/guest/runtime/session.js

@@ -0,0 +1,10 @@
+// Shared state for the guest scripts (main, daemon, view): fixed paths, the session description, logging, status.
+import fs from 'node:fs';
+import path from 'node:path';
+import { downloader } from '../../shared/download/index.js';
+import { launchDir, dataDir } from './paths.js';
+export const session = JSON.parse(fs.readFileSync(path.join(launchDir, 'session.json'), 'utf8').replace(/^\uFEFF/, ''));
+downloader.requireChecksum = session.downloads?.requireChecksum === true;
+export const workspace = process.env.AGENT_WORKSPACE ?? session.workspace;
+export const stateDir = path.join(dataDir, session.persistAgentState ? 'state' : 'state-session');
+export const claudeDir = path.join(stateDir, 'claude');

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

@@ -0,0 +1,7 @@
+import type { SandboxStatus } from '../../core/types.js';
+import type { BootProgress } from '../../shared/channel/schema.js';
+/**
+ * Best-effort: progress reporting must never be what breaks the boot. `update` changes the structured progress
+ * (a new step, what is being set up); it stays as it was otherwise.
+ */
+export declare function setSandboxStatus(phase: SandboxStatus['phase'], message: string, update?: Partial<BootProgress>): void;