windows-development-sandbox 1.1.0 → 1.4.0

package/dist/core/schema/sandbox.js

@@ -13,6 +13,7 @@ export const Sandbox = z.strictObject({
     maxMemoryMb: z.number().int().positive().describe('Upper limit for memoryMb "auto".'),
     maxMemoryPercent: z.number().int().min(10).max(100).describe('memoryMb "auto" never takes more than this share of this PC\'s total RAM (percent).'),
     cpuLimit: z.union([z.literal('none'), z.number().int().min(5).max(100)]).describe('Most of this PC\'s CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; "none" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal).'),
+    pageFileMb: z.number().int().min(0).max(262144).describe('Size of the sandbox\'s paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows\' own.'),
     reserveHostMb: z.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
     vGpu: z.boolean().describe('Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface.'),
     networking: z.boolean().describe('Internet access. false is the only hard network isolation Windows Sandbox offers.'),
@@ -22,6 +23,32 @@ export const Sandbox = z.strictObject({
     printerRedirection: z.boolean().describe('Printers from this PC.'),
     protectedClient: z.boolean().describe('Run the sandbox window in Protected Client mode (recommended).'),
     headless: z.boolean().describe('Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.'),
+    keepAwake: z.boolean().describe('Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it).'),
+});
+const Port = z.number().int().min(1).max(65535);
+const HostEntry = z.string().max(253).regex(/^(@developer|(\*\.)?([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+)$/, 'a host name like example.com, *.example.com, or @developer');
+export const Network = z.strictObject({
+    blockPrivateRanges: z.boolean().describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.'),
+    allowOnly: z.array(HostEntry).describe('Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit.'),
+    blockHosts: z.array(z.string().max(253).regex(/^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/, 'a host name like telemetry.example.com')).describe('Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox\'s hosts file sends them nowhere).'),
+    forwardPorts: z.array(z.strictObject({
+        pc: Port.describe('The port on this PC (localhost only).'),
+        sandbox: Port.describe('The port inside the sandbox (a server there may listen on localhost only).'),
+    })).describe('Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them.'),
+    dns: z.array(z.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/, 'an IPv4 address like 1.1.1.1')).describe('DNS servers for the sandbox instead of your network\'s, e.g. 1.1.1.1 and 9.9.9.9.'),
+    proxy: z.string().regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port').describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
+});
+export const Audit = z.strictObject({
+    enabled: z.boolean().describe('Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit.'),
+    days: z.number().int().min(1).max(365).describe('Days the audit log is kept.'),
+    maxMb: z.number().int().min(5).max(5000).describe('Most space the audit log may take, in MB (older days go first). Days before today are compressed.'),
+    processes: z.boolean().describe('Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed).'),
+    files: z.boolean().describe('Record the files changed in the project while the sandbox runs.'),
+});
+export const WorkspaceFilter = z.strictObject({
+    enabled: z.boolean().describe('Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped.'),
+    exclude: z.array(z.string().max(500)).describe('Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/.'),
+    include: z.array(z.string().max(500)).describe('Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/.'),
 });
 export const Git = z.strictObject({ enabled: z.boolean().describe('Provide Git for Windows (and Git Bash, which Claude Code needs).'), access: GitAccess });
 export const Provisioning = z.strictObject({
@@ -30,6 +57,7 @@ export const Provisioning = z.strictObject({
     refresh: z.boolean().describe('Re-copy / re-download everything on the next launch.'),
     git: Git,
     terminal: toggle('Windows Terminal as the sandbox window (downloaded once).'),
+    conpty: toggle('Agent sessions use Microsoft\'s newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows.'),
 });
 export const Downloads = z.strictObject({
     requireChecksum: z.boolean().describe('Refuse any toolchain, database or tool download that has no published checksum (SHA-256/SHA-512) to verify it against. false = allow those, as before. Downloads that do have a published checksum are always verified. A project\'s .sandbox-config.json can only turn this on.'),

package/dist/core/schema/toolchains.d.ts

@@ -88,6 +88,9 @@ export declare const Toolchains: z.ZodObject<{
     }, z.core.$strict>;
     vscode: z.ZodObject<{
         enabled: z.ZodBoolean;
+        setup: z.ZodBoolean;
+        recommended: z.ZodBoolean;
+        extensions: z.ZodArray<z.ZodString>;
     }, z.core.$strict>;
     environment: z.ZodRecord<z.ZodString, z.ZodString>;
 }, z.core.$strict>;

package/dist/core/schema/toolchains.js

@@ -78,6 +78,11 @@ export const Toolchains = z.strictObject({
         enabled: z.boolean().describe('Mesa 3D (llvmpipe): OpenGL 4.5 in software for games and apps when there is no GPU (sandbox.vGpu off). Copy opengl32.dll and libgallium_wgl.dll from %MESA_DIR% next to the program\'s .exe.'),
         vulkan: z.boolean().describe('Also software Vulkan 1.4 (Mesa lavapipe) with the Khronos loader, registered for every program; for wgpu set WGPU_BACKEND=vulkan.'),
     }),
-    vscode: toggle('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
+    vscode: z.strictObject({
+        enabled: z.boolean().describe('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
+        setup: z.boolean().describe('Point VS Code at the sandbox\'s own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use.'),
+        recommended: z.boolean().describe('Also install the extensions a project recommends in its .vscode/extensions.json.'),
+        extensions: z.array(z.string().regex(/^[\w-]+\.[\w-]+$/, 'publisher.name, e.g. eamodio.gitlens')).describe('More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker.'),
+    }),
     environment: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'letters, digits and _ only'), z.string()).describe('Extra environment variables for the agent and every terminal, e.g. registry mirrors: {"NPM_CONFIG_REGISTRY": "https://...", "PIP_INDEX_URL": "https://..."}.'),
 });

package/dist/core/types.d.ts

@@ -187,4 +187,10 @@ export interface GuestSession {
     }[];
     /** sandbox.cpuLimit as a number (null = no cap); sandbox\cpucap.ps1 applies it before anything starts. */
     cpuLimitPercent?: number | null;
+    /** sandbox.pageFileMb (0 = Windows' own); sandbox\pagefile.ps1 applies it at logon. */
+    pageFileMb?: number;
+    /** Apps to install (catalogue ids and your own programs); missing in launch folders of older versions. */
+    apps?: Config['apps'];
+    /** audit.enabled and audit.processes: the sandbox reports the programs it starts (host keeps the log). */
+    auditProcesses?: boolean;
 }

package/dist/core/util.d.ts

@@ -34,6 +34,8 @@ export declare const isInsideOrEqual: (parent: string, child: string) => boolean
  * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
  */
 export declare const safeText: (text: string) => string;
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export declare const plainText: (text: string) => string;
 export declare const findOnPath: (names: string[]) => string | null;
 /** True if `p` itself is a symlink or junction (lstat; never follows it). */
 export declare const isLink: (p: string) => boolean;

package/dist/core/util.js

@@ -81,6 +81,8 @@ export const isInsideOrEqual = (parent, child) => {
  * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
  */
 export const safeText = (text) => text.replace(/\x1b\[[0-9;]*m|\x1b(\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (m) => (/^\x1b\[[0-9;]*m$/.test(m) ? m : ''));
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export const plainText = (text) => safeText(text).replace(/\x1b\[[0-9;]*m/g, '');
 export const findOnPath = (names) => {
     const dirs = (process.env.PATH ?? process.env.Path ?? '').split(path.delimiter).filter((d) => d !== '');
     for (const name of names)

package/dist/core/workspace.js

@@ -3,9 +3,9 @@ import path from 'node:path';
 import { z } from 'zod';
 import { planMirrorWorkspace } from '../shared/guest-paths.js';
 import { DATABASES } from './detect-databases.js';
-import { applyOverrides, describeOverrides, isTrusted, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
+import { allowedAnswer, allowRequests, allowStorePath, applyOverrides, describeOverrides, isTrusted, loosenedRequests, saveAllowed, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
 import { assertSafeWorkspace } from './safe-paths.js';
-import { dirExists, expandPath, fail, fileExists } from './util.js';
+import { dirExists, expandPath, fail, fileExists, plainText } from './util.js';
 /**
  * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
  * and claude-mem's project name match this PC instead of every project being "Workspace".
@@ -88,15 +88,32 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
             if (!trusted && req.ask) {
                 console.log('\nFound ' + local.path + ' which is not trusted yet. It would apply:');
                 for (const line of summary)
-                    console.log('  ' + line);
+                    console.log('  ' + plainText(line));
                 trusted = await req.ask('Trust and use this file?');
             }
             if (!trusted)
-                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
+                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.map(plainText).join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
             saveTrust(store, local.path, local.hash);
             notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
         }
-        config = applyOverrides(config, overrides);
+        // A project may only tighten. What it asks for beyond that is used only if you allowed it for this project (asked
+        // once, interactively, never by --trust-config); otherwise it is named here instead of dropped silently.
+        const allowStore = allowStorePath(storageRoot);
+        const allowed = [];
+        for (const ask of loosenedRequests(config, overrides)) {
+            let ok = allowedAnswer(allowStore, local.path, ask.key, ask.wanted);
+            if (ok === null && req.ask && process.stdin.isTTY) {
+                ok = await req.ask('This project asks for ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ', which is looser than your settings (' + JSON.stringify(ask.yours) + '). Allow it for this project only?');
+                saveAllowed(allowStore, local.path, ask.key, ask.wanted, ok);
+            }
+            if (ok) {
+                allowed.push(ask);
+                notes.push('Allowed for this project: ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ' (your answer is kept in ' + allowStore + ').');
+            }
+            else
+                notes.push('The project asks for ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ', but your settings say ' + JSON.stringify(ask.yours) + ', so it is not used. ' + (ok === false ? 'You said no (kept in ' + allowStore + ').' : 'Start it from an interactive terminal to allow it for this project.') + ' Or set ' + ask.key + ' in your own settings (sandbox, then Settings > All projects).');
+        }
+        config = applyOverrides(allowRequests(config, allowed), overrides);
         scripts.push(...(overrides.scripts ?? []));
         localConfigPath = local.path;
         notes.push('Using ' + local.path);

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

@@ -0,0 +1,10 @@
+import type { Config, GitAccess } from '../../core/types.js';
+import { type ToolEnv } from '../toolchains/common.js';
+export { appsNeedMesa } from '../../shared/apps.js';
+export interface AppsOptions {
+    gitAccess: GitAccess;
+    refresh: boolean;
+}
+/** The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). */
+export declare const findExe: (root: string, exe: string) => string | null;
+export declare const setupApps: (env: ToolEnv, apps: Config["apps"], o: AppsOptions) => Promise<void>;

package/dist/guest/apps/index.js

@@ -0,0 +1,206 @@
+// Installs the apps you chose (apps.install from the catalogue, apps.custom of your own) into C:\AgentData\tools\apps,
+// once each: later sandboxes find them there. Programs get a desktop and Start menu shortcut; command-line tools go on
+// PATH. Installers are never run: archives are unpacked, NSIS installers opened with 7-Zip and MSIs extracted
+// (msiexec /a), so nothing is registered and nothing is lost when the sandbox closes. One app failing never stops the
+// others.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { appsToInstall, exeMatcher } from '../../shared/apps.js';
+import { download, extractArchive, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.js';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, errMsg, execAsync, exists, log, mkdirp, powershell, warn } from '../env.js';
+import { arch, tool } from '../toolchains/common.js';
+import { RESOLVERS } from './resolvers.js';
+export { appsNeedMesa } from '../../shared/apps.js';
+const MARKER = '.agent-sandbox-app';
+/** How many apps download and unpack at once (they are big: a few at a time keeps the disk and network busy). */
+const PARALLEL = 3;
+const sevenZip = () => tool('apps', '7zip', '7z.exe');
+/** Where to download an entry from. */
+const resolve = async (entry) => {
+    const s = entry.source;
+    if ('github' in s) {
+        const a = await githubAsset(s.github, new RegExp(s.asset), true);
+        return { url: a.url, fileName: a.name, sha256: a.sha256 };
+    }
+    if ('url' in s) {
+        const name = decodeURIComponent(new URL(s.url).pathname.split('/').pop() || entry.id);
+        return { url: s.url, fileName: /\.\w{2,5}$/.test(name) ? name : name + '.zip' };
+    }
+    if ('resolve' in s && RESOLVERS[s.resolve])
+        return RESOLVERS[s.resolve]();
+    throw new Error('no download source for ' + entry.name);
+};
+/** The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). */
+export const findExe = (root, exe) => {
+    const match = exeMatcher(exe);
+    let queue = [root];
+    let seen = 0;
+    for (let depth = 0; depth < 7 && queue.length; depth++) {
+        const next = [];
+        for (const dir of queue) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            const hit = entries.find((e) => e.isFile() && match(e.name));
+            if (hit)
+                return path.join(dir, hit.name);
+            next.push(...entries.filter((e) => e.isDirectory() && !e.isSymbolicLink()).map((e) => path.join(dir, e.name)));
+            if ((seen += entries.length) > 50000)
+                return null;
+        }
+        queue = next;
+    }
+    return null;
+};
+/** Downloads and unpacks one entry into its folder (replaced in one step: never half there). */
+const installApp = async (entry, dest) => {
+    const work = stagingFolder(dest);
+    const out = path.join(work, 'out');
+    try {
+        if ('npm' in entry.source) {
+            const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+            log('Installing ' + entry.name + ' (npm) ...');
+            await execAsync(process.execPath, [npmCli, 'install', '--prefix', mkdirp(out), '--no-audit', '--no-fund', '--loglevel=error', entry.source.npm]);
+        }
+        else {
+            const d = await resolve(entry);
+            log('Downloading ' + entry.name + ' (' + d.fileName + ', ~' + entry.size + ' once) ...');
+            const file = path.join(mkdirp(work), d.fileName.replace(/[\\/:*?"<>|]/g, '_'));
+            await download(d.url, file, { sha256: d.sha256 ?? null });
+            await unpack(entry, file, out, d);
+        }
+        fs.writeFileSync(path.join(out, MARKER), JSON.stringify({ id: entry.id, at: new Date().toISOString() }));
+        moveIntoPlace(out, dest);
+    }
+    finally {
+        safeRemove(work, path.dirname(work));
+    }
+};
+const unpack = async (entry, file, out, d) => {
+    if (entry.id === '7zip') {
+        // 7zr.exe (the small standalone 7-Zip) opens the full 7-Zip's installer.
+        const sevenZr = path.join(path.dirname(file), '7zr.exe');
+        const zr = await githubAsset('ip7z/7zip', /^7zr\.exe$/);
+        await download(zr.url, sevenZr, zr.sha256);
+        await execAsync(sevenZr, ['x', '-y', '-o' + out, file], { stdio: 'ignore' });
+        return;
+    }
+    switch (entry.unpack ?? 'archive') {
+        case 'file': {
+            mkdirp(out);
+            fs.renameSync(file, path.join(out, /^\//.test(entry.exe) ? path.basename(file) : entry.exe));
+            return;
+        }
+        case 'nsis': {
+            if (!exists(sevenZip()))
+                throw new Error('7-Zip is needed to unpack ' + entry.name + ' and could not be installed');
+            const raw = path.join(path.dirname(out), 'raw');
+            await execAsync(sevenZip(), ['x', '-y', '-o' + raw, file], { stdio: 'ignore' });
+            // electron-builder installers carry the app as one more archive inside.
+            const inner = findExe(raw, '/^app-64\\.7z$/');
+            if (inner)
+                await execAsync(sevenZip(), ['x', '-y', '-o' + out, inner], { stdio: 'ignore' });
+            else
+                fs.renameSync(raw, out);
+            return;
+        }
+        case 'msi': {
+            // An administrative install only extracts the files: nothing is registered with Windows.
+            mkdirp(out);
+            await execAsync(SYSTEM.msiexec(), ['/a', file, '/qn', 'TARGETDIR=' + out], { stdio: 'ignore' });
+            return;
+        }
+        default:
+            await extractArchive(file, out, d.members);
+    }
+};
+/** Settings an app needs on every boot (the sandbox's registry is new each time), and files next to its program. */
+const afterInstall = async (entry, exe) => {
+    const dir = path.dirname(exe);
+    if (entry.needs?.includes('mesa')) {
+        const mesa = tool('mesa', arch === 'arm64' ? 'arm64' : 'x64');
+        for (const dll of ['opengl32.dll', 'libgallium_wgl.dll', 'dxil.dll']) {
+            if (exists(path.join(mesa, dll)) && !exists(path.join(dir, dll)))
+                fs.copyFileSync(path.join(mesa, dll), path.join(dir, dll));
+        }
+    }
+    // Godot and Sublime keep their settings next to the program instead of in the profile, which is wiped on close.
+    if (entry.id === 'godot' && !exists(path.join(dir, '._sc_')))
+        fs.writeFileSync(path.join(dir, '._sc_'), '');
+    if (entry.id === 'sublime')
+        mkdirp(path.join(dir, 'Data'));
+    if (entry.id === 'sysinternals') {
+        for (const name of ['Process Explorer', 'Process Monitor', 'Autoruns', 'TCPView', 'PsExec', 'PsList', 'PsKill', 'Handle', 'ListDLLs', 'Sigcheck', 'Strings', 'VMMap', 'RAMMap', 'DebugView', 'Disk2vhd', 'Du', 'ZoomIt']) {
+            await execAsync(SYSTEM.reg(), ['add', 'HKCU\\Software\\Sysinternals\\' + name, '/v', 'EulaAccepted', '/t', 'REG_DWORD', '/d', '1', '/f'], { stdio: 'ignore' }).catch(() => undefined);
+        }
+    }
+};
+/** Desktop and Start menu shortcuts, all in one PowerShell call. */
+const shortcuts = (apps) => {
+    if (!apps.length)
+        return;
+    const q = (s) => "'" + s.replace(/'/g, "''") + "'";
+    const desktop = path.join(os.homedir(), 'Desktop');
+    const start = path.join(process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Sandbox apps');
+    const lines = ['$w = New-Object -ComObject WScript.Shell', 'New-Item -ItemType Directory -Force -Path ' + q(start) + ' | Out-Null'];
+    for (const app of apps) {
+        for (const folder of [desktop, start]) {
+            const name = app.name.replace(/[\\/:*?"<>|]/g, '');
+            lines.push('$s = $w.CreateShortcut(' + q(path.join(folder, name + '.lnk')) + '); $s.TargetPath = ' + q(app.exe) + '; $s.WorkingDirectory = ' + q(path.dirname(app.exe)) + '; $s.Save()');
+        }
+    }
+    powershell(lines.join('\n'));
+};
+export const setupApps = async (env, apps, o) => {
+    const { entries, skipped } = appsToInstall(apps, o.gitAccess);
+    for (const s of skipped)
+        env.summary.push('app skipped: ' + s);
+    if (dryRun) {
+        log('(dry run) would install apps: ' + entries.map((e) => e.name).join(', '));
+        return;
+    }
+    const gui = [];
+    const installed = [];
+    const one = async (entry) => {
+        try {
+            const dest = tool('apps', ...entry.id.split('/'));
+            if (!exists(path.join(dest, MARKER)) || o.refresh)
+                await installApp(entry, dest);
+            const exe = findExe(dest, entry.exe);
+            if (!exe)
+                throw new Error(entry.exe + ' not found in the download');
+            await afterInstall(entry, exe);
+            if (entry.cli || entry.id === 'sysinternals')
+                env.prepend.push(path.dirname(exe));
+            if (!entry.cli)
+                gui.push({ name: entry.name, exe });
+            installed.push(entry.name);
+        }
+        catch (e) {
+            warn(entry.name + ' could not be installed and is skipped; the other apps are not affected. Reason: ' + errMsg(e));
+            env.summary.push(entry.name + ': FAILED');
+        }
+    };
+    // 7-Zip first: the NSIS apps need it to unpack.
+    const [first, rest] = entries[0]?.id === '7zip' ? [[entries[0]], entries.slice(1)] : [[], entries];
+    for (const e of first)
+        await one(e);
+    const queue = [...rest];
+    await Promise.all(Array.from({ length: Math.min(PARALLEL, queue.length) }, async () => { for (let e = queue.shift(); e; e = queue.shift())
+        await one(e); }));
+    try {
+        shortcuts(gui);
+    }
+    catch (e) {
+        warn('App shortcuts could not be created: ' + errMsg(e));
+    }
+    if (installed.length)
+        env.summary.push('apps: ' + installed.join(', ') + ' (shortcuts on the desktop and in Start > Sandbox apps)');
+};

package/dist/guest/apps/resolvers.d.ts

@@ -0,0 +1,8 @@
+export interface Download {
+    url: string;
+    fileName: string;
+    sha256?: string | null;
+    /** Only these paths of the archive (pgAdmin out of the PostgreSQL zip). */
+    members?: string[];
+}
+export declare const RESOLVERS: Record<string, () => Promise<Download>>;

package/dist/guest/apps/resolvers.js

@@ -0,0 +1,90 @@
+// Where the latest version of an app is, for apps that are not a plain GitHub release: each looks it up on the
+// vendor's own site (and its published checksum, where there is one). Named by AppSource.resolve in shared/apps.ts.
+import { fetchJson, fetchText, githubAsset, latestGithubTag } from '../../shared/download.js';
+/** The SHA-256 on the line of a SHA256SUMS-style file that names `file`. */
+const sumFor = (sums, file) => sums.split(/\r?\n/).map((l) => /^([0-9a-f]{64})\s+\*?(.+)$/i.exec(l.trim())).find((m) => m && m[2].trim().endsWith(file))?.[1].toLowerCase() ?? null;
+const firstHash = (text) => /\b([0-9a-f]{64})\b/i.exec(text)?.[1].toLowerCase() ?? null;
+const stripV = (tag) => tag.replace(/^v/, '');
+export const RESOLVERS = {
+    sublime: async () => {
+        // Sublime publishes no checksums; the download is HTTPS from sublimetext.com.
+        const { latest_version: build } = await fetchJson('https://www.sublimetext.com/updates/4/stable_update_check');
+        return { url: 'https://download.sublimetext.com/sublime_text_build_' + build + '_x64.zip', fileName: 'sublime_text_' + build + '.zip' };
+    },
+    pgadmin: async () => {
+        // pgAdmin is only an installer on pgadmin.org; EnterpriseDB's PostgreSQL binaries zip has a portable copy.
+        const versions = (await fetchJson('https://www.postgresql.org/versions.json')).filter((v) => v.supported);
+        const current = versions.find((v) => v.current) ?? versions[versions.length - 1];
+        const exact = current.major + '.' + current.latestMinor;
+        return { url: 'https://get.enterprisedb.com/postgresql/postgresql-' + exact + '-1-windows-x64-binaries.zip', fileName: 'postgresql-' + exact + '.zip', members: ['pgsql/pgAdmin 4'] };
+    },
+    everything: async () => {
+        const page = await fetchText('https://www.voidtools.com/downloads/');
+        const version = /Everything-([\d.]+)\.x64\.zip/.exec(page)?.[1];
+        if (!version)
+            throw new Error('could not find the Everything download on voidtools.com');
+        const file = 'Everything-' + version + '.x64.zip';
+        const sums = await fetchText('https://www.voidtools.com/Everything-' + version + '.sha256').catch(() => '');
+        return { url: 'https://www.voidtools.com/' + file, fileName: file, sha256: sumFor(sums, file) };
+    },
+    chrome: async () => {
+        const data = await fetchJson('https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json');
+        const hit = data.channels.Stable.downloads.chrome.find((d) => d.platform === 'win64');
+        if (!hit)
+            throw new Error('no win64 Chrome for Testing build listed');
+        return { url: hit.url, fileName: 'chrome-win64.zip' };
+    },
+    firefox: async () => {
+        const { LATEST_FIREFOX_VERSION: v } = await fetchJson('https://product-details.mozilla.org/1.0/firefox_versions.json');
+        const base = 'https://archive.mozilla.org/pub/firefox/releases/' + v + '/';
+        const sums = await fetchText(base + 'SHA256SUMS');
+        return { url: base + 'win64/en-US/Firefox%20Setup%20' + v + '.exe', fileName: 'firefox-setup-' + v + '.exe', sha256: sumFor(sums, 'win64/en-US/Firefox Setup ' + v + '.exe') };
+    },
+    blender: async () => {
+        const releases = await fetchText('https://download.blender.org/release/');
+        const series = [...releases.matchAll(/href="Blender(\d+)\.(\d+)\/"/g)].map((m) => [Number(m[1]), Number(m[2])]).sort((a, b) => a[0] - b[0] || a[1] - b[1]).pop();
+        if (!series)
+            throw new Error('could not list Blender releases');
+        const folder = 'https://download.blender.org/release/Blender' + series[0] + '.' + series[1] + '/';
+        const listing = await fetchText(folder);
+        const files = [...listing.matchAll(/href="(blender-([\d.]+)-windows-x64\.zip)"/g)].map((m) => ({ file: m[1], v: m[2].split('.').map(Number) }));
+        const latest = files.sort((a, b) => a.v[2] - b.v[2]).pop();
+        if (!latest)
+            throw new Error('no Windows build in ' + folder);
+        const sums = await fetchText(folder + 'blender-' + latest.v.join('.') + '.sha256').catch(() => '');
+        return { url: folder + latest.file, fileName: latest.file, sha256: sumFor(sums, latest.file) };
+    },
+    kubectl: async () => {
+        const v = (await fetchText('https://dl.k8s.io/release/stable.txt')).trim();
+        const url = 'https://dl.k8s.io/release/' + v + '/bin/windows/amd64/kubectl.exe';
+        return { url, fileName: 'kubectl.exe', sha256: firstHash(await fetchText(url + '.sha256')) };
+    },
+    helm: async () => {
+        const v = await latestGithubTag('helm/helm');
+        const url = 'https://get.helm.sh/helm-' + v + '-windows-amd64.zip';
+        return { url, fileName: 'helm-' + v + '.zip', sha256: firstHash(await fetchText(url + '.sha256sum')) };
+    },
+    terraform: async () => {
+        const { current_version: v } = await fetchJson('https://checkpoint-api.hashicorp.com/v1/check/terraform');
+        const base = 'https://releases.hashicorp.com/terraform/' + v + '/';
+        const file = 'terraform_' + v + '_windows_amd64.zip';
+        return { url: base + file, fileName: file, sha256: sumFor(await fetchText(base + 'terraform_' + v + '_SHA256SUMS'), file) };
+    },
+    mitmproxy: async () => {
+        // mitmproxy's GitHub releases have no files; its own download server has them (no published checksums).
+        const v = stripV(await latestGithubTag('mitmproxy/mitmproxy'));
+        return { url: 'https://downloads.mitmproxy.org/' + v + '/mitmproxy-' + v + '-windows-x86_64.zip', fileName: 'mitmproxy-' + v + '.zip' };
+    },
+    sqlite: async () => {
+        // The download page lists every file in a CSV comment: PRODUCT,<version>,<year>/<file>,<size>,<sha3>.
+        const page = await fetchText('https://sqlite.org/download.html');
+        const file = /PRODUCT,[^,]+,(\d{4}\/sqlite-tools-win-x64-\d+\.zip),/.exec(page)?.[1];
+        if (!file)
+            throw new Error('could not find the sqlite tools download on sqlite.org');
+        return { url: 'https://sqlite.org/' + file, fileName: file.split('/')[1] };
+    },
+    '7zip': async () => {
+        const asset = await githubAsset('ip7z/7zip', /^7z\d+-x64\.exe$/);
+        return { url: asset.url, fileName: asset.name, sha256: asset.sha256 };
+    },
+};

package/dist/guest/audit-parse.d.ts

@@ -0,0 +1,7 @@
+/** Background programs of Windows itself: never what an agent ran. */
+export declare const NOISE: Set<string>;
+/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
+export declare const parseProcessEvents: (xml: string) => {
+    lines: string[];
+    last: number;
+};

package/dist/guest/audit-parse.js

@@ -0,0 +1,24 @@
+// Reading Windows process-creation events (Security log, 4688, as wevtutil prints them) into audit lines. Pure, so
+// the self-test can check it on the PC side.
+import path from 'node:path';
+/** Background programs of Windows itself: never what an agent ran. */
+export const NOISE = new Set(['conhost.exe', 'svchost.exe', 'backgroundtaskhost.exe', 'runtimebroker.exe', 'wmiprvse.exe', 'dllhost.exe', 'searchprotocolhost.exe', 'searchfilterhost.exe', 'taskhostw.exe', 'sppsvc.exe', 'wermgr.exe', 'consent.exe', 'smartscreen.exe', 'mpcmdrun.exe', 'compattelrunner.exe', 'wevtutil.exe', 'audiodg.exe', 'ctfmon.exe', 'sihost.exe', 'werfault.exe', 'msmpeng.exe', 'nissrv.exe', 'usoclient.exe', 'musnotification.exe']);
+const decode = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+const field = (event, name) => decode(new RegExp("<Data Name='" + name + "'>([^<]*)</Data>").exec(event)?.[1] ?? '');
+/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
+export const parseProcessEvents = (xml) => {
+    const lines = [];
+    let last = 0;
+    for (const event of xml.split('</Event>')) {
+        const id = Number(/<EventRecordID>(\d+)<\/EventRecordID>/.exec(event)?.[1] ?? 0);
+        if (!id)
+            continue;
+        last = Math.max(last, id);
+        const program = field(event, 'NewProcessName');
+        if (!program || NOISE.has(path.win32.basename(program).toLowerCase()))
+            continue;
+        const t = /SystemTime='([^']+)'/.exec(event)?.[1] ?? new Date().toISOString();
+        lines.push(JSON.stringify({ t, k: 'proc', p: program.slice(0, 1024), c: field(event, 'CommandLine').slice(0, 2000), pp: field(event, 'ParentProcessName').slice(0, 1024) }));
+    }
+    return { lines, last };
+};

package/dist/guest/audit.d.ts

@@ -0,0 +1,4 @@
+/** Turns on process-creation auditing with command lines (the registry is new every boot). */
+export declare const enableProcessAudit: () => void;
+/** Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise). */
+export declare const startProcessCollector: () => void;

package/dist/guest/audit.js

@@ -0,0 +1,47 @@
+// audit.processes, sandbox side: Windows records every program started (Security log, event 4688, with its command
+// line); the daemon reads the new events every 15 s and leaves them in run\audit\ as small .jsonl files, which the
+// host takes into its own log (and deletes). Windows' own background programs are left out. The host treats all of it
+// as untrusted (it is checked line by line there).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../shared/system.js';
+import { parseProcessEvents } from './audit-parse.js';
+import { dryRun, errMsg, isWin, log, mkdirp, run, session, warn } from './env.js';
+/** The "Process Creation" audit subcategory (a GUID, so it works in every Windows language). */
+const PROCESS_CREATION = '{0CCE922B-69AE-11D9-BED3-505054503030}';
+const MAX_PER_PASS = 2000;
+const auditOn = () => Boolean(session.auditProcesses) && isWin && !dryRun;
+/** Turns on process-creation auditing with command lines (the registry is new every boot). */
+export const enableProcessAudit = () => {
+    if (!auditOn())
+        return;
+    spawnSync(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'auditpol.exe'), ['/set', '/subcategory:' + PROCESS_CREATION, '/success:enable'], { windowsHide: true, stdio: 'ignore' });
+    spawnSync(SYSTEM.reg(), ['add', 'HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\System\\Audit', '/v', 'ProcessCreationIncludeCmdLine_Enabled', '/t', 'REG_DWORD', '/d', '1', '/f'], { windowsHide: true, stdio: 'ignore' });
+    log('Audit: programs started in the sandbox are recorded (audit.processes).');
+};
+const wevtutil = () => path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'wevtutil.exe');
+const newestRecord = () => {
+    const r = spawnSync(wevtutil(), ['qe', 'Security', '/q:*[System[(EventID=4688)]]', '/f:xml', '/c:1', '/rd:true'], { encoding: 'utf8', windowsHide: true });
+    return parseProcessEvents(r.stdout ?? '').last;
+};
+/** Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise). */
+export const startProcessCollector = () => {
+    if (!auditOn())
+        return;
+    let last = newestRecord();
+    const pass = () => {
+        try {
+            const r = spawnSync(wevtutil(), ['qe', 'Security', '/q:*[System[(EventID=4688) and (EventRecordID>' + last + ')]]', '/f:xml', '/c:' + MAX_PER_PASS], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '');
+            if (newest)
+                last = newest;
+            if (lines.length)
+                fs.writeFileSync(path.join(mkdirp(run.audit), Date.now() + '-' + process.pid + '.jsonl'), lines.join('\n') + '\n');
+        }
+        catch (e) {
+            warn('audit: ' + errMsg(e));
+        }
+    };
+    setInterval(pass, 15000).unref?.();
+};

package/dist/guest/daemon/relays.d.ts

@@ -0,0 +1 @@
+export declare const startRelays: () => void;

package/dist/guest/daemon/relays.js

@@ -0,0 +1,18 @@
+// network.forwardPorts, sandbox side: one relay per forward, listening on its relay port (reachable only from the
+// sandbox's own subnet, i.e. the PC: see the firewall rule in setup/network.ts) and passing each connection on to
+// localhost:<sandbox port>. So a dev server that only listens on localhost is reachable from the PC too.
+import net from 'node:net';
+import { relayPort } from '../../shared/netpolicy.js';
+import { errMsg, log, session, warn } from '../env.js';
+export const startRelays = () => {
+    (session.network.forwardPorts ?? []).forEach((f, i) => {
+        const server = net.createServer((client) => {
+            const target = net.connect(f.sandbox, '127.0.0.1');
+            client.pipe(target).pipe(client);
+            target.on('error', () => client.destroy());
+            client.on('error', () => target.destroy());
+        });
+        server.on('error', (e) => warn('Port forward ' + f.pc + ' -> ' + f.sandbox + ' could not start: ' + errMsg(e)));
+        server.listen(relayPort(i), '0.0.0.0', () => log('Port forward: the PC\'s localhost:' + f.pc + ' reaches localhost:' + f.sandbox + ' here.'));
+    });
+};

package/dist/guest/daemon.js

@@ -6,6 +6,8 @@ import fs from 'node:fs';
 import { readSession, scanRequests } from '../shared/rundir.js';
 import { saveClaudeMem } from './setup/claude.js';
 import { execCommand } from './daemon/exec.js';
+import { startRelays } from './daemon/relays.js';
+import { startProcessCollector } from './audit.js';
 import { prepareProject, restartSessions, startSession } from './daemon/session.js';
 import { live, respond, safely } from './daemon/state.js';
 import { dataDir, errMsg, log, run, warn } from './env.js';
@@ -50,4 +52,6 @@ const loop = () => {
     }
 };
 log('Session daemon started (pid ' + process.pid + ').');
+safely('port forwards', startRelays);
+safely('audit', startProcessCollector);
 loop();

package/dist/guest/env.d.ts

@@ -18,6 +18,7 @@ export declare const run: {
     responses: string;
     sessions: string;
     projects: string;
+    audit: string;
     request: (id: string) => string;
     response: (id: string) => string;
     session: (id: string) => string;