windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/stops.js

@@ -1,126 +0,0 @@
-// Why the last sandbox stopped, when nobody stopped it. The background watcher writes a host-only "life" record (when
-// the sandbox started, when it was last seen running, how it ended) and keeps this PC awake while it runs
-// (sandbox.keepAwake). When the PC restarts, sleeps or crashes, the watcher stops too and the record has no end: the
-// next launch reads Windows' System log from that moment on and says what happened, and what keeps it from happening.
-import { spawn, spawnSync } from 'node:child_process';
-import path from 'node:path';
-import { z } from 'zod';
-import { SYSTEM } from '../shared/system.js';
-import { readValid, writeJsonAtomic } from '../shared/rundir.js';
-import { isWin } from '../core/util.js';
-import { refuseInSelfTest } from './test-guard.js';
-const Iso = z.string().max(40);
-const Life = z.object({
-    started: Iso, lastSeen: Iso, keepAwake: z.boolean(),
-    ended: z.object({ at: Iso, cause: z.object({ kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']), at: Iso, text: z.string().max(400) }).nullable() }).optional(),
-    reported: z.boolean().optional(),
-});
-const lifeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-life.json');
-export const readLife = (storageRoot, dataPath) => readValid(Life, lifeFile(storageRoot, dataPath));
-const writeLife = (storageRoot, dataPath, life) => writeJsonAtomic(lifeFile(storageRoot, dataPath), life);
-/** At launch: a fresh record (the previous one has been reported by then). */
-export const startLife = (storageRoot, dataPath, keepAwake, now = new Date()) => writeLife(storageRoot, dataPath, { started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
-/** Every minute while the sandbox runs. */
-export const beatLife = (storageRoot, dataPath, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, lastSeen: now.toISOString() });
-};
-/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
-export const endLife = (storageRoot, dataPath, cause, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, ended: { at: now.toISOString(), cause } });
-};
-const StopEvents = z.array(z.object({ at: Iso, id: z.number().int(), provider: z.string().max(200), process: z.string().max(400).nullable().transform((p) => p ?? '') })).max(100);
-const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
-/**
- * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
- * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching
- * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
- */
-export const explainStop = (events) => {
-    const causes = events.flatMap((e) => {
-        const p = e.provider.toLowerCase();
-        if (e.id === 1074 && p.includes('user32')) {
-            const exe = e.process.split(/[\\/]/).pop()?.replace(/\s*\(.*$/, '') ?? '';
-            return UPDATERS.test(exe)
-                ? [{ kind: 'updates', at: e.at, text: 'Windows restarted this PC to install updates' }]
-                : [{ kind: 'restart', at: e.at, text: 'this PC was restarted or shut down' + (exe ? ' (by ' + exe + ')' : '') }];
-        }
-        if ((e.id === 41 && p.includes('kernel-power')) || (e.id === 6008 && p.includes('eventlog')))
-            return [{ kind: 'crash', at: e.at, text: 'Windows stopped unexpectedly (a crash, a power cut, or the power button held down)' }];
-        if (e.id === 42 && p.includes('kernel-power'))
-            return [{ kind: 'sleep', at: e.at, text: 'this PC went to sleep or hibernated' }];
-        if (e.id === 2004 && p.includes('resource-exhaustion'))
-            return [{ kind: 'memory', at: e.at, text: 'this PC ran out of memory' }];
-        if (e.id === 18590 && p.includes('hyper-v-worker')) {
-            const code = /ErrorCode0:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
-            const sub = /ErrorCode1:\s*(0x[0-9a-f]{1,16})/i.exec(e.process)?.[1];
-            return [{ kind: 'sandboxCrash', at: e.at, text: 'Windows inside the sandbox crashed' + (code ? ' (stop code ' + code + (sub ? ', ' + sub : '') + ')' : '') }];
-        }
-        return [];
-    });
-    return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;
-};
-const ADVICE = {
-    updates: 'Before leaving agents overnight, restart for pending updates first or pause them (Settings > Windows Update > Pause updates).',
-    restart: 'If that was not you, check Settings > Windows Update and Event Viewer > Windows Logs > System.',
-    crash: 'Event Viewer > Windows Logs > System has the details; a laptop also needs to stay plugged in.',
-    sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
-    sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
-    memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
-};
-/** System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be read). */
-export const readStopEvents = (since) => {
-    if (!isWin)
-        return [];
-    refuseInSelfTest('read the Windows event log');
-    const script = "$ErrorActionPreference='SilentlyContinue'; $t=[datetime]::Parse('" + since.toISOString() + "').ToLocalTime(); $e = Get-WinEvent -FilterHashtable @(@{LogName='System'; Id=1074,6008,41,42,2004; StartTime=$t}, @{LogName='Microsoft-Windows-Hyper-V-Worker-Admin'; Id=18590; StartTime=$t}) -MaxEvents 100 | ForEach-Object { [pscustomobject]@{ at=$_.TimeCreated.ToUniversalTime().ToString('o'); id=$_.Id; provider=$_.ProviderName; process=$(if ($_.Id -eq 1074) { [string]$_.Properties[0].Value } elseif ($_.Id -eq 18590) { ([string]$_.Message).Substring(0, [math]::Min(390, ([string]$_.Message).Length)) } else { '' }) } }; ConvertTo-Json -Compress -InputObject @($e)";
-    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { encoding: 'utf8', windowsHide: true, timeout: 60000 });
-    try {
-        return StopEvents.parse(JSON.parse(result.stdout || '[]'));
-    }
-    catch {
-        return [];
-    }
-};
-/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
-export const causeSince = (lastSeen) => explainStop(readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000)));
-const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
-/**
- * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or ran
- * out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not end).
- */
-export const lastStopWarning = (storageRoot, dataPath, watcherAlive, find = causeSince) => {
-    const life = readLife(storageRoot, dataPath);
-    if (!life || life.reported || watcherAlive)
-        return null;
-    writeLife(storageRoot, dataPath, { ...life, reported: true });
-    if (life.ended && !life.ended.cause)
-        return null;
-    const cause = life.ended ? life.ended.cause : find(life.lastSeen);
-    const what = cause ? cause.text + ' at ' + when(cause.at) + '. ' + ADVICE[cause.kind] : 'this PC stopped (Windows logged no reason). ' + ADVICE.crash;
-    return 'The last sandbox did not close normally: it was last seen running at ' + when(life.lastSeen) + ', and ' + what + ' Agent conversations are kept: /resume in Claude picks one up.';
-};
-// ---- Windows Update and keeping awake ----------------------------------------------------------------------------
-/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
-export const updateRestartPending = () => isWin && [
-    'HKLM\\SOFTWARE\\Microsoft\\WindowsUpdate\\Auto Update\\RebootRequired',
-    'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
-].some((key) => spawnSync(SYSTEM.reg(), ['query', key], { windowsHide: true, stdio: 'ignore', timeout: 15000 }).status === 0);
-export const UPDATE_RESTART_WARNING = 'Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.';
-/**
- * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
- * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
- */
-export const keepAwake = (ownerPid) => {
-    if (!isWin)
-        return null;
-    refuseInSelfTest('keep this PC awake');
-    const script = "Add-Type -Name Power -Namespace AgentSandbox -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; "
-        + '[void][AgentSandbox.Power]::SetThreadExecutionState([uint32]2147483649); Wait-Process -Id ' + Math.trunc(ownerPid) + ' -ErrorAction SilentlyContinue';
-    const child = spawn(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
-    child.on('error', () => undefined);
-    return child;
-};

package/dist/shared/apps.js

@@ -1,114 +0,0 @@
-export const APP_CATEGORIES = [
-    { id: 'editors', label: 'Editors & IDEs', description: 'Code and text editors (VS Code is a setting of its own and on by default).' },
-    { id: 'databases', label: 'Database clients', description: 'GUIs for the databases the sandbox runs (PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB).' },
-    { id: 'api', label: 'API clients', description: 'Send HTTP, REST and GraphQL requests to what you are building.' },
-    { id: 'git', label: 'Git tools', description: 'Git GUIs and terminal UIs. They use the sandbox\'s git, so its git access rules apply.' },
-    { id: 'utilities', label: 'Utilities', description: 'Archives, comparing files, finding files, process tools, hex editing.' },
-    { id: 'browsers', label: 'Browsers', description: 'Browsers for testing web apps (Edge is already in Windows).' },
-    { id: 'gamedev', label: 'Game development', description: 'Engines and editors. They draw with OpenGL on the CPU (Mesa) when the sandbox has no GPU.' },
-    { id: 'cloud', label: 'Cloud & Kubernetes', description: 'Command-line tools for clouds, Kubernetes and infrastructure as code.' },
-    { id: 'diagrams', label: 'Diagrams & docs', description: 'Diagrams and document conversion.' },
-    { id: 'network', label: 'Network & HTTP', description: 'Inspect and test HTTP traffic and APIs.' },
-    { id: 'cli', label: 'Command-line tools', description: 'Small tools developers reach for: JSON and YAML, search, diff, builds, media, load testing ...' },
-];
-const gh = (github, asset) => ({ github, asset });
-export const APPS = [
-    // ---- editors
-    { id: 'vscode', name: 'Visual Studio Code', category: 'editors', about: 'Code editor with debugging, set up for the sandbox\'s languages.', size: '150 MB', source: { resolve: 'setting' }, exe: 'Code.exe', setting: 'toolchains.vscode.enabled' },
-    { id: 'windows-terminal', name: 'Windows Terminal', category: 'utilities', about: 'The sandbox window: tabs, panes, PowerShell 7 profile.', size: '40 MB', source: { resolve: 'setting' }, exe: 'WindowsTerminal.exe', setting: 'provisioning.terminal.enabled' },
-    { id: 'notepadpp', name: 'Notepad++', category: 'editors', about: 'Fast text and code editor.', size: '8 MB', source: gh('notepad-plus-plus/notepad-plus-plus', '^npp\\.[\\d.]+\\.portable\\.x64\\.zip$'), exe: 'notepad++.exe' },
-    { id: 'sublime', name: 'Sublime Text', category: 'editors', about: 'Fast code editor (paid licence, free to evaluate).', size: '28 MB', source: { resolve: 'sublime' }, exe: 'sublime_text.exe' },
-    { id: 'neovim', name: 'Neovim', category: 'editors', about: 'Terminal text editor (nvim).', size: '12 MB', source: gh('neovim/neovim', '^nvim-win64\\.zip$'), exe: 'nvim.exe', cli: true },
-    // ---- database clients
-    { id: 'dbeaver', name: 'DBeaver Community', category: 'databases', about: 'Universal database client: PostgreSQL, MySQL, SQLite, SQL Server and more.', size: '120 MB', source: gh('dbeaver/dbeaver', '^dbeaver-ce-[\\d.]+-windows-x86_64\\.zip$'), exe: 'dbeaver.exe' },
-    { id: 'pgadmin', name: 'pgAdmin 4', category: 'databases', about: 'The PostgreSQL admin GUI (from the PostgreSQL binaries zip).', size: '330 MB', source: { resolve: 'pgadmin' }, exe: 'pgAdmin4.exe' },
-    { id: 'heidisql', name: 'HeidiSQL', category: 'databases', about: 'Light client for MySQL, MariaDB, PostgreSQL and SQL Server.', size: '28 MB', source: gh('HeidiSQL/HeidiSQL', '^HeidiSQL_[\\d.]+_64_Portable\\.zip$'), exe: 'heidisql.exe' },
-    { id: 'sqlitebrowser', name: 'DB Browser for SQLite', category: 'databases', about: 'Open, browse and edit SQLite files.', size: '21 MB', source: gh('sqlitebrowser/sqlitebrowser', '^DB\\.Browser\\.for\\.SQLite-v?[\\d.]+-win64\\.zip$'), exe: 'DB Browser for SQLite.exe' },
-    { id: 'compass', name: 'MongoDB Compass', category: 'databases', about: 'The MongoDB GUI.', size: '220 MB', source: gh('mongodb-js/compass', '^mongodb-compass-[\\d.]+-win32-x64\\.zip$'), exe: 'MongoDBCompass.exe' },
-    { id: 'redisinsight', name: 'Redis Insight', category: 'databases', about: 'The Redis GUI.', size: '110 MB', source: gh('redis/RedisInsight', '^Redis-Insight-win-installer\\.exe$'), unpack: 'nsis', exe: 'Redis Insight.exe', needs: ['7zip'] },
-    { id: 'dbgate', name: 'DbGate', category: 'databases', about: 'Database manager for SQL and NoSQL databases.', size: '180 MB', source: gh('dbgate/dbgate', '^dbgate-[\\d.]+-win_x64\\.zip$'), exe: 'DbGate.exe' },
-    { id: 'beekeeper', name: 'Beekeeper Studio', category: 'databases', about: 'SQL editor and database manager.', size: '245 MB', source: gh('beekeeper-studio/beekeeper-studio', '^Beekeeper-Studio-[\\d.]+-portable\\.exe$'), unpack: 'nsis', exe: 'Beekeeper Studio.exe', needs: ['7zip'] },
-    { id: 'dynamodb-admin', name: 'dynamodb-admin', category: 'databases', about: 'Web GUI for DynamoDB Local: run dynamodb-admin, then open http://localhost:8001.', size: '5 MB', source: { npm: 'dynamodb-admin' }, exe: 'dynamodb-admin.cmd', cli: true },
-    // ---- API clients
-    { id: 'bruno', name: 'Bruno', category: 'api', about: 'Offline, git-friendly API client (collections are files in your repo).', size: '175 MB', source: gh('usebruno/bruno', '^bruno_[\\d.]+_x64_win\\.zip$'), exe: 'Bruno.exe' },
-    { id: 'insomnia', name: 'Insomnia', category: 'api', about: 'REST, GraphQL and gRPC client.', size: '590 MB', source: gh('Kong/insomnia', '^insomnia-[\\d.]+-full\\.nupkg$'), exe: 'Insomnia.exe' },
-    // ---- git
-    { id: 'sourcegit', name: 'SourceGit', category: 'git', about: 'Fast open-source Git GUI.', size: '26 MB', source: gh('sourcegit-scm/sourcegit', '^sourcegit_[\\d.]+\\.win-x64\\.zip$'), exe: 'SourceGit.exe' },
-    { id: 'githubdesktop', name: 'GitHub Desktop', category: 'git', about: 'Simple Git GUI from GitHub. It has its own git, so it needs provisioning.git.access "full".', size: '300 MB', source: gh('desktop/desktop', '^GitHubDesktop-[\\d.]+-x64-full\\.nupkg$'), exe: 'GitHubDesktop.exe', fullGitOnly: true },
-    { id: 'lazygit', name: 'lazygit', category: 'git', about: 'Git in the terminal.', size: '7 MB', source: gh('jesseduffield/lazygit', '^lazygit_[\\d.]+_windows_x86_64\\.zip$'), exe: 'lazygit.exe', cli: true },
-    // ---- utilities
-    { id: '7zip', name: '7-Zip', category: 'utilities', about: 'Archive manager (7z, zip, rar, tar ...). Also unpacks installers for other apps.', size: '2 MB', source: { resolve: '7zip' }, exe: '7zFM.exe' },
-    { id: 'winmerge', name: 'WinMerge', category: 'utilities', about: 'Compare and merge files and folders.', size: '23 MB', source: gh('WinMerge/winmerge', '^winmerge-[\\d.]+-x64-exe\\.zip$'), exe: 'WinMergeU.exe' },
-    { id: 'everything', name: 'Everything', category: 'utilities', about: 'Finds files by name instantly.', size: '2 MB', source: { resolve: 'everything' }, exe: 'Everything.exe' },
-    { id: 'sysinternals', name: 'Sysinternals Suite', category: 'utilities', about: 'Process Explorer, Process Monitor, Autoruns, TCPView and more (on PATH).', size: '200 MB', source: { url: 'https://download.sysinternals.com/files/SysinternalsSuite.zip' }, exe: 'procexp64.exe' },
-    { id: 'imhex', name: 'ImHex', category: 'utilities', about: 'Hex editor for reverse engineering and binary formats.', size: '80 MB', source: gh('WerWolv/ImHex', '^imhex-[\\d.]+-Windows-Portable-NoGPU-x86_64\\.zip$'), exe: 'imhex-gui.exe' },
-    // ---- browsers
-    { id: 'chrome', name: 'Chrome for Testing', category: 'browsers', about: 'Chrome build made for automated tests (with chromedriver on PATH).', size: '170 MB', source: { resolve: 'chrome' }, exe: 'chrome.exe' },
-    { id: 'firefox', name: 'Firefox', category: 'browsers', about: 'Firefox for testing.', size: '75 MB', source: { resolve: 'firefox' }, unpack: 'nsis', exe: 'firefox.exe', needs: ['7zip'] },
-    // ---- game development
-    { id: 'godot', name: 'Godot', category: 'gamedev', about: 'Open-source 2D and 3D game engine.', size: '80 MB', source: gh('godotengine/godot', '^Godot_v[\\d.]+-stable_win64\\.exe\\.zip$'), exe: '/^Godot_v[\\d.]+-stable_win64\\.exe$/', needs: ['mesa'] },
-    { id: 'blender', name: 'Blender', category: 'gamedev', about: '3D modelling, animation and rendering.', size: '400 MB', source: { resolve: 'blender' }, exe: 'blender.exe', needs: ['mesa'] },
-    { id: 'love', name: 'LÖVE', category: 'gamedev', about: 'Lua framework for 2D games.', size: '4 MB', source: gh('love2d/love', '^love-[\\d.]+-win64\\.zip$'), exe: 'love.exe', needs: ['mesa'] },
-    { id: 'defold', name: 'Defold', category: 'gamedev', about: 'Free 2D/3D game engine and editor.', size: '330 MB', source: gh('defold/defold', '^Defold-x86_64-win32\\.zip$'), exe: 'Defold.exe', needs: ['mesa'] },
-    { id: 'pixelorama', name: 'Pixelorama', category: 'gamedev', about: 'Pixel-art and sprite editor.', size: '40 MB', source: gh('Orama-Interactive/Pixelorama', '^Pixelorama-Windows-64bit\\.zip$'), exe: 'Pixelorama.exe', needs: ['mesa'] },
-    { id: 'tiled', name: 'Tiled', category: 'gamedev', about: 'Tile map editor.', size: '22 MB', source: gh('mapeditor/tiled', '^Tiled-[\\d.]+_Windows-10\\+_x86_64\\.msi$'), unpack: 'msi', exe: 'tiled.exe' },
-    // ---- cloud
-    { id: 'kubectl', name: 'kubectl', category: 'cloud', about: 'Kubernetes command line.', size: '60 MB', source: { resolve: 'kubectl' }, unpack: 'file', exe: 'kubectl.exe', cli: true },
-    { id: 'helm', name: 'Helm', category: 'cloud', about: 'Kubernetes package manager.', size: '20 MB', source: { resolve: 'helm' }, exe: 'helm.exe', cli: true },
-    { id: 'k9s', name: 'k9s', category: 'cloud', about: 'Kubernetes cluster UI in the terminal.', size: '40 MB', source: gh('derailed/k9s', '^k9s_Windows_amd64\\.zip$'), exe: 'k9s.exe', cli: true },
-    { id: 'terraform', name: 'Terraform', category: 'cloud', about: 'Infrastructure as code.', size: '30 MB', source: { resolve: 'terraform' }, exe: 'terraform.exe', cli: true },
-    { id: 'azure-cli', name: 'Azure CLI', category: 'cloud', about: 'Manage Azure (az).', size: '90 MB', source: { url: 'https://aka.ms/installazurecliwindowszipx64' }, exe: 'az.cmd', cli: true },
-    { id: 'gcloud', name: 'Google Cloud CLI', category: 'cloud', about: 'Manage Google Cloud (gcloud, gsutil, bq).', size: '120 MB', source: { url: 'https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip' }, exe: 'gcloud.cmd', cli: true },
-    { id: 'aws-cli', name: 'AWS CLI', category: 'cloud', about: 'Manage AWS (aws).', size: '50 MB', source: { url: 'https://awscli.amazonaws.com/AWSCLIV2.msi' }, unpack: 'msi', exe: 'aws.exe', cli: true },
-    // ---- diagrams and docs
-    { id: 'drawio', name: 'draw.io', category: 'diagrams', about: 'Diagram editor (flowcharts, architecture, UML).', size: '170 MB', source: gh('jgraph/drawio-desktop', '^draw\\.io-[\\d.]+-windows\\.zip$'), exe: 'draw.io.exe' },
-    { id: 'pandoc', name: 'Pandoc', category: 'diagrams', about: 'Convert documents between Markdown, HTML, Word, PDF ...', size: '35 MB', source: gh('jgm/pandoc', '^pandoc-[\\d.]+-windows-x86_64\\.zip$'), exe: 'pandoc.exe', cli: true },
-    // ---- network
-    { id: 'mitmproxy', name: 'mitmproxy', category: 'network', about: 'Intercepting HTTPS proxy (mitmweb opens a web UI).', size: '90 MB', source: { resolve: 'mitmproxy' }, exe: 'mitmweb.exe', cli: true },
-    { id: 'xh', name: 'xh', category: 'network', about: 'Friendly HTTP requests from the terminal (like HTTPie).', size: '5 MB', source: gh('ducaale/xh', '^xh-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'xh.exe', cli: true },
-    { id: 'grpcurl', name: 'grpcurl', category: 'network', about: 'curl for gRPC servers.', size: '10 MB', source: gh('fullstorydev/grpcurl', '^grpcurl_[\\d.]+_windows_x86_64\\.zip$'), exe: 'grpcurl.exe', cli: true },
-    { id: 'k6', name: 'k6', category: 'network', about: 'Load testing with JavaScript scripts.', size: '30 MB', source: gh('grafana/k6', '^k6-v[\\d.]+-windows-amd64\\.zip$'), exe: 'k6.exe', cli: true },
-    // ---- command-line tools
-    { id: 'jq', name: 'jq', category: 'cli', about: 'Query and reshape JSON.', size: '1 MB', source: gh('jqlang/jq', '^jq-windows-amd64\\.exe$'), unpack: 'file', exe: 'jq.exe', cli: true },
-    { id: 'yq', name: 'yq', category: 'cli', about: 'Query and edit YAML, JSON, XML and TOML.', size: '10 MB', source: gh('mikefarah/yq', '^yq_windows_amd64\\.exe$'), unpack: 'file', exe: 'yq.exe', cli: true },
-    { id: 'ripgrep', name: 'ripgrep', category: 'cli', about: 'Very fast recursive search (rg).', size: '2 MB', source: gh('BurntSushi/ripgrep', '^ripgrep-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'rg.exe', cli: true },
-    { id: 'fd', name: 'fd', category: 'cli', about: 'Fast, friendly alternative to find.', size: '2 MB', source: gh('sharkdp/fd', '^fd-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'fd.exe', cli: true },
-    { id: 'bat', name: 'bat', category: 'cli', about: 'cat with syntax highlighting and git changes.', size: '3 MB', source: gh('sharkdp/bat', '^bat-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'bat.exe', cli: true },
-    { id: 'fzf', name: 'fzf', category: 'cli', about: 'Fuzzy finder for the terminal.', size: '2 MB', source: gh('junegunn/fzf', '^fzf-[\\d.]+-windows_amd64\\.zip$'), exe: 'fzf.exe', cli: true },
-    { id: 'delta', name: 'delta', category: 'cli', about: 'Readable git diffs with syntax highlighting.', size: '3 MB', source: gh('dandavison/delta', '^delta-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'delta.exe', cli: true },
-    { id: 'just', name: 'just', category: 'cli', about: 'Command runner (a simpler make for project tasks).', size: '2 MB', source: gh('casey/just', '^just-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'just.exe', cli: true },
-    { id: 'hyperfine', name: 'hyperfine', category: 'cli', about: 'Benchmark commands.', size: '1 MB', source: gh('sharkdp/hyperfine', '^hyperfine-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'hyperfine.exe', cli: true },
-    { id: 'watchexec', name: 'watchexec', category: 'cli', about: 'Run a command when files change.', size: '5 MB', source: gh('watchexec/watchexec', '^watchexec-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'watchexec.exe', cli: true },
-    { id: 'protoc', name: 'protoc', category: 'cli', about: 'Protocol Buffers compiler.', size: '3 MB', source: gh('protocolbuffers/protobuf', '^protoc-[\\d.]+-win64\\.zip$'), exe: 'protoc.exe', cli: true },
-    { id: 'ninja', name: 'Ninja', category: 'cli', about: 'Small, fast build system (CMake\'s favourite generator).', size: '1 MB', source: gh('ninja-build/ninja', '^ninja-win\\.zip$'), exe: 'ninja.exe', cli: true },
-    { id: 'ffmpeg', name: 'FFmpeg', category: 'cli', about: 'Convert and process audio and video.', size: '200 MB', source: gh('BtbN/FFmpeg-Builds', '^ffmpeg-master-latest-win64-gpl\\.zip$'), exe: 'ffmpeg.exe', cli: true },
-    { id: 'sqlite', name: 'SQLite tools', category: 'cli', about: 'sqlite3 command-line shell.', size: '5 MB', source: { resolve: 'sqlite' }, exe: 'sqlite3.exe', cli: true },
-    { id: 'shellcheck', name: 'ShellCheck', category: 'cli', about: 'Finds bugs in shell scripts.', size: '10 MB', source: gh('koalaman/shellcheck', '^shellcheck-v[\\d.]+\\.zip$'), exe: 'shellcheck.exe', cli: true },
-    { id: 'gitleaks', name: 'Gitleaks', category: 'cli', about: 'Finds secrets committed to git.', size: '8 MB', source: gh('gitleaks/gitleaks', '^gitleaks_[\\d.]+_windows_x64\\.zip$'), exe: 'gitleaks.exe', cli: true },
-];
-export const appById = (id) => APPS.find((a) => a.id === id);
-/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
-export const exeMatcher = (exe) => {
-    const regex = /^\/(.+)\/$/.exec(exe);
-    if (regex) {
-        const r = new RegExp(regex[1], 'i');
-        return (name) => r.test(name);
-    }
-    return (name) => name.toLowerCase() === exe.toLowerCase();
-};
-/** Your own program as a catalogue entry (its folder is apps\custom\<id>). */
-const customEntry = (id, app) => ({
-    id: 'custom/' + id, name: app.name, category: 'utilities', about: 'Your own program.', size: '?',
-    source: app.github && app.asset ? { github: app.github, asset: app.asset } : { url: app.url },
-    unpack: app.unpack, exe: app.exe, cli: app.cli,
-});
-/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
-export const appsToInstall = (apps, gitAccess) => {
-    const chosen = apps.install.flatMap((id) => { const e = appById(id); return e && !e.setting ? [e] : []; });
-    const skipped = chosen.filter((e) => e.fullGitOnly && gitAccess !== 'full').map((e) => e.name + ' (needs provisioning.git.access "full")');
-    const allowed = [...chosen.filter((e) => !(e.fullGitOnly && gitAccess !== 'full')), ...Object.entries(apps.custom).map(([id, app]) => customEntry(id, app))];
-    const needs7zip = allowed.some((e) => e.needs?.includes('7zip') || e.unpack === 'nsis') && !allowed.some((e) => e.id === '7zip');
-    return { entries: [...(needs7zip ? [appById('7zip')] : []), ...allowed], skipped };
-};
-/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
-export const appsNeedMesa = (apps) => Boolean(apps?.install.some((id) => appById(id)?.needs?.includes('mesa')));

package/dist/shared/download.d.ts

@@ -1,60 +0,0 @@
-/**
- * A fresh `<destination>.staging-<hex>` folder next to `destination`: fill it, then moveIntoPlace. An interrupted copy
- * or extraction leaves only the staging folder (cleanup/repair remove those), never a half-filled destination.
- */
-export declare const stagingFolder: (destination: string) => string;
-/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
-export declare const moveIntoPlace: (work: string, destination: string) => void;
-/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
-export declare const fetchRetry: (url: string, init?: RequestInit, attempts?: number, timeoutMs?: number) => Promise<Response>;
-/** Small lookups fail fast (2 tries, 20 s each) so an offline boot falls back to cached versions quickly. */
-export declare const fetchJson: <T>(url: string) => Promise<T>;
-export declare const fetchText: (url: string) => Promise<string>;
-/** Expected checksums of a download; any that are given must match. */
-export interface Checksums {
-    sha256?: string | null;
-    sha512?: string | null;
-}
-/** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
-export declare const setChecksumRequired: (on: boolean) => void;
-/**
- * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
- * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
- */
-export declare const download: (url: string, destination: string, expected?: string | null | Checksums) => Promise<void>;
-/** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */
-export declare const spawnAsync: (file: string, args: string[], options?: import("node:child_process").SpawnOptions) => Promise<number>;
-export interface ReleaseAsset {
-    url: string;
-    name: string;
-    sha256: string | null;
-}
-/**
- * Finds an asset in the latest GitHub release of `repo` (with its published sha256 when available). With
- * `searchOlder`, falls back to the newest stable release that still ships a matching asset (projects drop assets).
- */
-export declare const githubAsset: (repo: string, pattern: RegExp, searchOlder?: boolean) => Promise<ReleaseAsset>;
-/** A release's assets from github.com's expanded_assets page (no API rate limit): each download link, then its sha256. */
-export declare const parseReleasePage: (html: string) => ReleaseAsset[];
-/** The latest release's tag, from github.com's own redirect (no API, no rate limit). */
-export declare const latestGithubTag: (repo: string) => Promise<string>;
-/** Release tags in the order github.com's /<repo>/releases page lists them (newest first), without duplicates. */
-export declare const parseReleaseTags: (html: string, repo: string) => string[];
-/**
- * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
- * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).
- */
-export declare const extractArchive: (archive: string, destination: string, members?: string[]) => Promise<void>;
-export declare const findFile: (root: string, name: string, maxDepth?: number) => string | null;
-/**
- * Downloads + extracts into `destination` atomically (staging folder, then rename). With `locate`, only the folder holding
- * that file is kept (`up` folders above it, e.g. locate ruby.exe with up 1 keeps the folder around bin).
- */
-export declare const installArchive: (url: string, destination: string, options?: {
-    sha256?: string | null;
-    sha512?: string | null;
-    locate?: string;
-    up?: number;
-    fileName?: string;
-    members?: string[];
-}) => Promise<void>;

package/dist/shared/download.js

@@ -1,215 +0,0 @@
-// Download/extract helpers shared by the host (Windows Terminal pre-download) and the guest (toolchains).
-// Node built-ins only, so it stays small in both bundles (the CLI and the guest runtime).
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { Readable, Transform } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { safeRemove } from './safe-remove.js';
-import { SYSTEM } from './system.js';
-const USER_AGENT = 'windows-development-sandbox';
-/**
- * A fresh `<destination>.staging-<hex>` folder next to `destination`: fill it, then moveIntoPlace. An interrupted copy
- * or extraction leaves only the staging folder (cleanup/repair remove those), never a half-filled destination.
- */
-export const stagingFolder = (destination) => destination + '.staging-' + crypto.randomBytes(3).toString('hex');
-/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
-export const moveIntoPlace = (work, destination) => {
-    safeRemove(destination, path.dirname(destination));
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    fs.renameSync(work, destination);
-};
-/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
-export const fetchRetry = async (url, init = {}, attempts = 5, timeoutMs = 60000) => {
-    let last;
-    for (let i = 1; i <= attempts; i++) {
-        try {
-            const response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs), headers: { 'User-Agent': USER_AGENT, ...(init.headers ?? {}) } });
-            if (response.ok)
-                return response;
-            last = new Error('HTTP ' + response.status + ' for ' + url);
-            if (response.status === 404)
-                break;
-        }
-        catch (e) {
-            last = e;
-        }
-        if (i < attempts)
-            await new Promise((r) => setTimeout(r, 3000));
-    }
-    throw last instanceof Error ? last : new Error(String(last));
-};
-/** Small lookups fail fast (2 tries, 20 s each) so an offline boot falls back to cached versions quickly. */
-export const fetchJson = async (url) => await (await fetchRetry(url, { headers: { Accept: 'application/json' } }, 2, 20000)).json();
-export const fetchText = async (url) => await (await fetchRetry(url)).text();
-let checksumRequired = false;
-/** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
-export const setChecksumRequired = (on) => { checksumRequired = on; };
-/**
- * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
- * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
- */
-export const download = async (url, destination, expected = null) => {
-    const sums = typeof expected === 'string' || expected === null ? { sha256: expected } : expected;
-    if (checksumRequired && !sums.sha256?.trim() && !sums.sha512?.trim()) {
-        throw new Error('Refusing to download ' + path.basename(destination) + ' (' + url + '): no checksum is published for it, and downloads.requireChecksum is on. Turn that setting off to allow downloads that cannot be verified.');
-    }
-    const response = await fetchRetry(url, {}, 3, 20 * 60 * 1000);
-    if (!response.body)
-        throw new Error('Empty response for ' + url);
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    // Only the hashes that will be checked (sha512 of a 330 MB archive is not free).
-    const checks = ['sha256', 'sha512'].flatMap((kind) => {
-        const want = sums[kind]?.trim().toLowerCase();
-        return want ? [{ want, hash: crypto.createHash(kind) }] : [];
-    });
-    const tap = new Transform({ transform(chunk, _encoding, done) { for (const c of checks)
-            c.hash.update(chunk); done(null, chunk); } });
-    // Written to <destination>.part and moved into place only once complete and verified, so an interrupted download never
-    // leaves a partial file under the real name.
-    const partial = destination + '.part';
-    try {
-        await pipeline(Readable.fromWeb(response.body), tap, fs.createWriteStream(partial));
-        if (checks.some((c) => c.hash.digest('hex') !== c.want))
-            throw new Error('Checksum mismatch for ' + url);
-        // Mapped folders refuse rename-over, so the old file goes first.
-        fs.rmSync(destination, { force: true });
-        fs.renameSync(partial, destination);
-    }
-    finally {
-        fs.rmSync(partial, { force: true });
-    }
-};
-/** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */
-export const spawnAsync = (file, args, options = {}) => new Promise((resolve, reject) => {
-    const child = spawn(file, args, { stdio: 'ignore', windowsHide: true, ...options });
-    child.once('error', reject);
-    child.once('close', (code) => resolve(code ?? -1));
-});
-const toAsset = (asset) => ({ url: asset.browser_download_url, name: asset.name, sha256: asset.digest?.startsWith('sha256:') ? asset.digest.slice(7) : null });
-/**
- * Finds an asset in the latest GitHub release of `repo` (with its published sha256 when available). With
- * `searchOlder`, falls back to the newest stable release that still ships a matching asset (projects drop assets).
- */
-export const githubAsset = async (repo, pattern, searchOlder = false) => {
-    let latest;
-    try {
-        latest = await fetchJson('https://api.github.com/repos/' + repo + '/releases/latest');
-    }
-    catch (e) {
-        // The API allows 60 requests an hour per IP without a token; a first boot alone makes a dozen. The release page has
-        // the same assets and digests and no such limit.
-        if (!/HTTP (403|429)/.test(e instanceof Error ? e.message : ''))
-            throw e;
-        return githubAssetFromPage(repo, pattern, searchOlder);
-    }
-    const hit = latest.assets.find((a) => pattern.test(a.name));
-    if (hit)
-        return toAsset(hit);
-    if (searchOlder) {
-        const releases = await fetchJson('https://api.github.com/repos/' + repo + '/releases?per_page=100');
-        for (const release of releases.filter((r) => !r.prerelease && !r.draft)) {
-            const older = release.assets.find((a) => pattern.test(a.name));
-            if (older)
-                return toAsset(older);
-        }
-    }
-    throw new Error('No asset matching ' + pattern + ' in the ' + (searchOlder ? 'stable' : 'latest') + ' ' + repo + ' release(s)');
-};
-/** A release's assets from github.com's expanded_assets page (no API rate limit): each download link, then its sha256. */
-export const parseReleasePage = (html) => {
-    const links = [...html.matchAll(/href="(\/[^"]+\/releases\/download\/[^"]+)"/g)];
-    return links.map((link, i) => {
-        const digest = /sha256:([0-9a-f]{64})/.exec(html.slice(link.index, links[i + 1]?.index ?? html.length))?.[1] ?? null;
-        return { url: 'https://github.com' + link[1], name: decodeURIComponent(link[1].split('/').pop()), sha256: digest };
-    });
-};
-/** The latest release's tag, from github.com's own redirect (no API, no rate limit). */
-export const latestGithubTag = async (repo) => {
-    const latest = await fetchRetry('https://github.com/' + repo + '/releases/latest', {}, 2, 20000);
-    const tag = decodeURIComponent(latest.url.split('/releases/tag/')[1] ?? '');
-    return tag || Promise.reject(new Error('Could not find the latest release of ' + repo));
-};
-/** Release tags in the order github.com's /<repo>/releases page lists them (newest first), without duplicates. */
-export const parseReleaseTags = (html, repo) => {
-    const escaped = repo.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
-    const tags = [...html.matchAll(new RegExp('href="/' + escaped + '/releases/tag/([^"?#]+)"', 'gi'))].map((m) => decodeURIComponent(m[1]));
-    return [...new Set(tags)];
-};
-/** How many releases the rate-limit fallback looks through for `searchOlder` (one page request each). */
-const OLDER_RELEASES = 10;
-const githubAssetFromPage = async (repo, pattern, searchOlder) => {
-    const assetsOf = async (tag) => parseReleasePage(await fetchText('https://github.com/' + repo + '/releases/expanded_assets/' + encodeURIComponent(tag))).find((a) => pattern.test(a.name));
-    const latest = await latestGithubTag(repo);
-    const hit = await assetsOf(latest);
-    if (hit)
-        return hit;
-    // nvm-windows' portable zip and winlibs' builds only exist in older releases: walk the release list like the API path does.
-    if (searchOlder) {
-        const older = parseReleaseTags(await fetchText('https://github.com/' + repo + '/releases'), repo).filter((t) => t !== latest);
-        for (const tag of older.slice(0, OLDER_RELEASES)) {
-            const found = await assetsOf(tag);
-            if (found)
-                return found;
-        }
-    }
-    throw new Error('No asset matching ' + pattern + ' in ' + repo + ' ' + latest + (searchOlder ? ' or the releases before it' : ''));
-};
-/**
- * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
- * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).
- */
-export const extractArchive = async (archive, destination, members = []) => {
-    fs.mkdirSync(destination, { recursive: true });
-    let status = await spawnAsync(SYSTEM.tar(), ['-xf', archive, '-C', destination, ...members]);
-    if (status !== 0 && /\.(zip|nupkg)$/i.test(archive)) {
-        const zip = archive.endsWith('.zip') ? archive : archive + '.zip';
-        if (zip !== archive)
-            fs.copyFileSync(archive, zip);
-        status = await spawnAsync(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command', "Expand-Archive -LiteralPath '" + zip.replace(/'/g, "''") + "' -DestinationPath '" + destination.replace(/'/g, "''") + "' -Force"]);
-    }
-    if (status !== 0)
-        throw new Error('Could not extract ' + archive);
-};
-export const findFile = (root, name, maxDepth = 4) => {
-    if (maxDepth < 0 || !fs.existsSync(root))
-        return null;
-    const entries = fs.readdirSync(root, { withFileTypes: true });
-    for (const entry of entries)
-        if (entry.isFile() && entry.name.toLowerCase() === name.toLowerCase())
-            return path.join(root, entry.name);
-    for (const entry of entries)
-        if (entry.isDirectory()) {
-            const found = findFile(path.join(root, entry.name), name, maxDepth - 1);
-            if (found)
-                return found;
-        }
-    return null;
-};
-/**
- * Downloads + extracts into `destination` atomically (staging folder, then rename). With `locate`, only the folder holding
- * that file is kept (`up` folders above it, e.g. locate ruby.exe with up 1 keeps the folder around bin).
- */
-export const installArchive = async (url, destination, options = {}) => {
-    const work = stagingFolder(destination);
-    try {
-        const archive = path.join(work, options.fileName ?? path.basename(new URL(url).pathname));
-        await download(url, archive, { sha256: options.sha256, sha512: options.sha512 });
-        const extracted = path.join(work, 'x');
-        await extractArchive(archive, extracted, options.members);
-        let root = extracted;
-        if (options.locate) {
-            const found = findFile(extracted, options.locate);
-            if (!found)
-                throw new Error(options.locate + ' not found in ' + url);
-            root = path.dirname(found);
-            for (let i = 0; i < (options.up ?? 0) && path.dirname(root).startsWith(extracted); i++)
-                root = path.dirname(root);
-        }
-        moveIntoPlace(root, destination);
-    }
-    finally {
-        safeRemove(work, path.dirname(work));
-    }
-};

package/dist/shared/guest-paths.js

@@ -1,61 +0,0 @@
-// Guest paths on drive letters other than C:. Windows Sandbox can only map folders onto its own C: drive, so a
-// guest path like F:\SteamLibrary\x is mapped to C:\Mirror\F\SteamLibrary\x and, at boot (bootstrap.ps1, before
-// anything else uses the workspace), `subst F: C:\Mirror\F` makes it appear at F:\SteamLibrary\x.
-// Pure functions only: used by the schema, the host (.wsb, session.json) and history sync.
-/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
-export const RESERVED_GUEST = /^C:\\(?:Windows|Program Files|Program Files \(x86\)|ProgramData|Users|AgentLaunch|AgentData|HostTools|nvm|Mirror)(?:\\|$)/i;
-/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
-export const MIRROR_ROOT = 'C:\\Mirror';
-/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
-export const MIRROR_LETTER = /^[D-Z]$/;
-const DRIVE_PATH = /^([A-Za-z]):\\(.*)$/;
-// No other ':' (alternate data streams), no wildcards or pipes, no control characters, no forward slashes.
-const BAD_CHARS = /[<>:"|?*/\x00-\x1f]/;
-/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
-export const guestDrive = (guest) => DRIVE_PATH.exec(guest)?.[1].toUpperCase() ?? null;
-/**
- * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
- * no '..' or empty segments, no characters Windows rejects in paths.
- */
-export const isValidGuestPath = (guest) => {
-    const m = DRIVE_PATH.exec(guest);
-    if (!m)
-        return false;
-    const letter = m[1].toUpperCase();
-    const rest = m[2].replace(/\\+$/, '');
-    if (rest === '' || BAD_CHARS.test(rest))
-        return false;
-    if (rest.split('\\').some((segment) => segment === '' || segment === '.' || segment === '..' || /[. ]$/.test(segment)))
-        return false;
-    if (letter === 'C')
-        return !RESERVED_GUEST.test('C:\\' + rest);
-    return MIRROR_LETTER.test(letter);
-};
-/** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
-export const sandboxFolder = (guest) => {
-    const m = DRIVE_PATH.exec(guest);
-    if (!m || m[1].toUpperCase() === 'C')
-        return guest;
-    return MIRROR_ROOT + '\\' + m[1].toUpperCase() + (m[2] ? '\\' + m[2] : '');
-};
-/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
-export const substDrives = (guests) => {
-    const letters = [...new Set(guests.map(guestDrive).filter((l) => l !== null && l !== 'C'))].sort();
-    return letters.map((letter) => ({ letter, target: MIRROR_ROOT + '\\' + letter }));
-};
-/**
- * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
- * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
- * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
- */
-export const planMirrorWorkspace = (workspaceHost, fallback) => {
-    const host = workspaceHost.replace(/\\+$/, '');
-    if (isValidGuestPath(host)) {
-        const letter = guestDrive(host);
-        return { guest: letter + host.slice(1), note: letter === 'C' ? null : 'guestWorkspace "mirror": ' + host + ' is mapped to ' + sandboxFolder(letter + host.slice(1)) + ' and shown as ' + letter + ': (subst) inside the sandbox.' };
-    }
-    const why = !guestDrive(host) ? 'it is not on a drive letter'
-        : guestDrive(host) === 'C' && RESERVED_GUEST.test(host) ? 'that folder is reserved inside the sandbox (Windows, Program Files, Users, ...)'
-            : 'the sandbox cannot show a folder at that path';
-    return { guest: fallback, note: 'guestWorkspace "mirror": ' + host + ' cannot appear at the same path (' + why + '); using ' + fallback + ' instead.' };
-};