windows-development-sandbox 1.4.3 → 1.7.0

package/node_modules/zod/v4/package.json

@@ -0,0 +1,7 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts",
+  "sideEffects": false
+}

package/node_modules/zod/v4-mini/index.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+const z = __importStar(require("../v4/mini/external.cjs"));
+exports.z = z;
+__exportStar(require("../v4/mini/external.cjs"), exports);
+
+// seal-cjs-exports
+(function () {
+  var keys = Object.getOwnPropertyNames(exports);
+  for (var i = 0; i < keys.length; i++) {
+    var desc = Object.getOwnPropertyDescriptor(exports, keys[i]);
+    if (!desc || !desc.get || !desc.configurable) continue;
+    var value;
+    try {
+      value = desc.get();
+    } catch (e) {
+      continue;
+    }
+    // a circular require may not have settled this one yet, so leave it live
+    if (value === undefined) continue;
+    Object.defineProperty(exports, keys[i], { value: value, writable: false, enumerable: desc.enumerable, configurable: false });
+  }
+  Object.freeze(exports);
+})();

package/node_modules/zod/v4-mini/index.d.cts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.cjs";
+export * from "../v4/mini/external.cjs";
+export { z };

package/node_modules/zod/v4-mini/index.d.ts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/node_modules/zod/v4-mini/index.js

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/node_modules/zod/v4-mini/package.json

@@ -0,0 +1,7 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts",
+  "sideEffects": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windows-development-sandbox",
-  "version": "1.4.3",
+  "version": "1.7.0",
   "description": "A disposable Windows Sandbox for development, with or without an AI agent (Claude Code, Codex, Gemini, opencode, ...): the folder you run it from is the workspace, toolchains and databases for your project install themselves, and nothing else on your PC is reachable.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs && node scripts/schemas.mjs",
+    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs && node scripts/bundle-web.mjs && node scripts/schemas.mjs",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "rebuild": "npm run clean && npm run build",
     "test": "npm run build && node dist/bin/agent-sandbox.js self-test",
@@ -53,9 +53,9 @@
     "install:global": "node scripts/install-global.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
     "doctor": "node dist/bin/agent-sandbox.js doctor",
-    "lint": "eslint src scripts",
-    "format": "prettier --write src scripts",
-    "format:check": "prettier --check src scripts"
+    "lint": "eslint src scripts web",
+    "format": "prettier --write src scripts web",
+    "format:check": "prettier --check src scripts web"
   },
   "publishConfig": {
     "access": "public"
@@ -79,15 +79,33 @@
     "ignore": "^7.0.12",
     "jsonc-parser": "^3.3.1",
     "lodash": "^4.18.1",
+    "ws": "^8.22.0",
     "zod": "^4.6.5"
   },
+  "bundleDependencies": [
+    "@inquirer/prompts",
+    "commander",
+    "ignore",
+    "jsonc-parser",
+    "lodash",
+    "ws",
+    "zod"
+  ],
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@types/lodash": "^4.17.26",
     "@types/node": "^22.0.0",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "@types/ws": "^8.18.2",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "bootstrap": "^5.3.8",
     "esbuild": "^0.28.2",
     "eslint": "^9.39.5",
     "prettier": "^3.9.10",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.71.2"
   },

package/sandbox/boot/bootstrap/drives.ps1

@@ -0,0 +1,29 @@
+# Drive letters D: to Z: for mirrored guest paths (subst), for bootstrap.ps1 (dot-sourced).
+function Mount-MirrorDrives {
+    # Windows Sandbox can only map folders onto C:, so a guest path like F:\Games\X is mapped to C:\Mirror\F\Games\X
+    # and F: is made here with subst (session.substDrives, written by the host; see src/shared/guest-paths.ts).
+    # subst drives belong to the logon session: everything started from here (main.js, the daemon, ptyhost, hooks,
+    # Windows Terminal tabs) and Explorer share it, because the sandbox user has one full token (UAC is off).
+    # Returns the letters that could NOT be mounted; an existing drive is reported, never replaced.
+    $subst = Join-Path $env:SystemRoot 'System32\subst.exe'
+    $failed = @()
+    foreach ($drive in @($session.substDrives)) {
+        if ($null -eq $drive) { continue }
+        $letter = ([string]$drive.letter).ToUpperInvariant()
+        $target = [string]$drive.target
+        if ($letter -notmatch '^[D-Z]$' -or $target -ne "C:\Mirror\$letter") { throw "Invalid subst drive in session.json: '$letter' -> '$target'." }
+        $existing = (& $subst) | ForEach-Object { if ($_ -match "^${letter}:\\: => (.+)$") { $Matches[1].Trim() } } | Select-Object -First 1
+        if ($existing -and $existing -eq $target) { Write-Host "  ${letter}: already points to $target."; continue }
+        if ([IO.Directory]::GetLogicalDrives() | Where-Object { $_.Substring(0, 1).ToUpperInvariant() -eq $letter }) {
+            Write-Warning "Drive ${letter}: already exists in the sandbox, so it was left alone. Folders mapped to ${letter}:\... are at $target\... instead."
+            $failed += $letter
+            continue
+        }
+        if (-not (Test-Path -LiteralPath $target -PathType Container)) { New-Item -ItemType Directory -Path $target -Force | Out-Null }
+        # subst.exe exits 0 even when it fails, so check the drive itself.
+        & $subst "${letter}:" $target | Out-Host
+        if (Test-Path -LiteralPath "${letter}:\") { Write-Host "  ${letter}: -> $target" }
+        else { Write-Warning "subst ${letter}: $target did not work. Folders mapped to ${letter}:\... are at $target\... instead."; $failed += $letter }
+    }
+    return ,$failed
+}

package/sandbox/boot/bootstrap/files.ps1

@@ -0,0 +1,49 @@
+# Downloads, copies and folder moves for bootstrap.ps1 (dot-sourced).
+function Invoke-Download([string]$Uri, [string]$OutFile) {
+    # The sandbox network can take a few seconds to come up, so retry.
+    for ($attempt = 1; $attempt -le 5; $attempt++) {
+        try {
+            if ($OutFile) { Invoke-WebRequest -Uri $Uri -OutFile $OutFile -UseBasicParsing; return $null }
+            $response = Invoke-WebRequest -Uri $Uri -UseBasicParsing
+            if ($response.Content -is [byte[]]) { return [Text.Encoding]::UTF8.GetString($response.Content) }
+            return [string]$response.Content
+        }
+        catch {
+            if ($attempt -eq 5) { throw }
+            Write-Warning "Download failed (attempt $attempt of 5): $($_.Exception.Message). Retrying ..."
+            Start-Sleep -Seconds 4
+        }
+    }
+}
+
+function Publish-Directory([string]$Staging, [string]$Destination) {
+    if (Test-Path -LiteralPath $Destination) { Remove-Item -LiteralPath $Destination -Recurse -Force }
+    Move-Item -LiteralPath $Staging -Destination $Destination
+}
+
+function Get-Size([string]$Path) {
+    if (-not (Test-Path -LiteralPath $Path)) { return 0 }
+    $sum = (Get-ChildItem -LiteralPath $Path -Recurse -File -Force -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum).Sum
+    if ($null -eq $sum) { return 0 } else { return [long]$sum }
+}
+
+function Invoke-Robocopy([string]$Label, [string]$From, [string]$To, [string[]]$Options, [long]$Total) {
+    # Runs robocopy in the background and prints how far it has got, so a slow copy never looks frozen.
+    # /R:2 /W:1: robocopy's default is 1,000,000 retries 30 s apart, which hangs "forever" on one unreadable file.
+    $totalMb = [math]::Round($Total / 1MB, 1)
+    Write-Host "  $Label ($totalMb MB) ..."
+    $argList = @("`"$From`"", "`"$To`"") + $Options + @('/XJ', '/R:2', '/W:1', '/NFL', '/NDL', '/NJH', '/NJS', '/NP')
+    $process = Start-Process -FilePath 'robocopy.exe' -ArgumentList $argList -NoNewWindow -PassThru
+    $null = $process.Handle   # keeps ExitCode readable after the process exits
+    $started = Get-Date
+    while (-not $process.WaitForExit(2000)) {
+        $done = Get-Size $To
+        $pct = if ($Total -gt 0) { [math]::Min(100, [math]::Floor($done * 100 / $Total)) } else { 0 }
+        $secs = [int]((Get-Date) - $started).TotalSeconds
+        Write-Host ("  {0}: {1} of {2} MB ({3}%), {4}s" -f $Label, [math]::Round($done / 1MB, 1), $totalMb, $pct, $secs)
+    }
+    $code = $process.ExitCode
+    if ($code -ge 8) { Write-Warning "robocopy failed copying $Label (exit code $code)"; return $false }
+    Write-Host ("  {0}: done in {1}s" -f $Label, [int]((Get-Date) - $started).TotalSeconds)
+    return $true
+}

package/sandbox/boot/bootstrap/runner.ps1

@@ -0,0 +1,87 @@
+# The runner's Node in persistent storage (cached, copied from this PC, or downloaded), for bootstrap.ps1 (dot-sourced).
+function Set-Runner([string]$Version) {
+    $script:nodeDir = Join-Path $nvmDir ('v' + $Version.TrimStart('v'))
+    $script:nodeExe = Join-Path $script:nodeDir 'node.exe'
+}
+
+function Test-Node {
+    if (-not (Test-Path -LiteralPath $nodeExe)) { return $false }
+    try { $null = & $nodeExe --version; return ($LASTEXITCODE -eq 0) } catch { return $false }
+}
+
+function Find-CachedRunner {
+    # This PC's version first (nvm will want it anyway), else whichever version the last boot used.
+    $last = if (Test-Path -LiteralPath $runnerFile) { (Get-Content -LiteralPath $runnerFile -Raw -Encoding UTF8).Trim() } else { '' }
+    foreach ($version in @($hostVersion, $last)) {
+        if ($version -notmatch '^\d+\.\d+\.\d+$') { continue }
+        Set-Runner $version
+        if (Test-Node) { return $true }
+    }
+    return $false
+}
+
+function Copy-NodeFromHost {
+    # The host maps one of these: nvm (when this PC's Node is an nvm version) or the plain Node folder.
+    if ($hostVersion -notmatch '^\d+\.\d+\.\d+$') { return $false }
+    $hostNode = @((Join-Path $hostNvm "v$hostVersion"), $hostNodeDir) | Where-Object { Test-Path -LiteralPath (Join-Path $_ 'node.exe') } | Select-Object -First 1
+    if (-not $hostNode) { return $false }
+    # Only node.exe, the npm shims and node_modules\npm (same list as copyNode in src/guest/env.ts): nothing else is
+    # needed, and the folder can hold every global npm package, i.e. tens of thousands of small files over a slow mapping.
+    Write-Host "Copying Node $hostVersion from this PC ($hostNode) ..."
+    Set-Status 'booting' 'Copying Node from this PC'
+    $staging = Join-Path $toolsDir 'node-staging'
+    if (Test-Path -LiteralPath $staging) { Remove-Item -LiteralPath $staging -Recurse -Force }
+    $files = @('node.exe', 'npm', 'npm.cmd', 'npx', 'npx.cmd')
+    $filesSize = ($files | ForEach-Object { Get-Item -LiteralPath (Join-Path $hostNode $_) -ErrorAction SilentlyContinue } | Measure-Object -Property Length -Sum).Sum
+    $npmFrom = Join-Path $hostNode 'node_modules\npm'
+    $ok = (Invoke-Robocopy -Label 'node.exe' -From $hostNode -To $staging -Options ($files + '/J') -Total ([long]$filesSize)) -and
+          (Invoke-Robocopy -Label 'npm' -From $npmFrom -To (Join-Path $staging 'node_modules\npm') -Options @('/E', '/MT:16') -Total (Get-Size $npmFrom))
+    if (-not $ok) { return $false }
+    Set-Runner $hostVersion
+    Publish-Directory -Staging $staging -Destination $nodeDir
+    return (Test-Node)
+}
+
+function Update-Environment {
+    # main.js writes PATH and the tool variables machine-wide; reload them so this (-NoExit) shell has nvm, git, etc.
+    foreach ($scope in @('Machine', 'User')) {
+        $vars = [Environment]::GetEnvironmentVariables($scope)
+        foreach ($name in $vars.Keys) { if ($name -ne 'Path') { Set-Item -LiteralPath "env:$name" -Value ([string]$vars[$name]) } }
+    }
+    $env:PATH = ([Environment]::GetEnvironmentVariable('Path', 'Machine'), [Environment]::GetEnvironmentVariable('Path', 'User') | Where-Object { $_ }) -join ';'
+}
+
+function Install-NodeFromWeb {
+    $arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x64' }
+    Write-Host 'Looking up the Node LTS release ...'
+    $index = (Invoke-Download -Uri 'https://nodejs.org/dist/index.json') | ConvertFrom-Json
+    $release = $index | Where-Object { $_.lts -and ($_.files -contains "win-$arch-zip") } | Select-Object -First 1
+    if ($null -eq $release) { throw "No Node LTS release found ($arch)." }
+    $version = [string]$release.version
+    if ($version -notmatch '^v\d+\.\d+\.\d+$') { throw "Unexpected Node version string: $version" }
+    $zipName = "node-$version-win-$arch.zip"
+    $baseUrl = "https://nodejs.org/dist/$version"
+    $work = Join-Path $toolsDir ('node-work-' + [guid]::NewGuid().ToString('N'))
+    New-Item -ItemType Directory -Path $work -Force | Out-Null
+    try {
+        $zipPath = Join-Path $work $zipName
+        Write-Host "Downloading $zipName ..."
+        $null = Invoke-Download -Uri "$baseUrl/$zipName" -OutFile $zipPath
+        $sums = Invoke-Download -Uri "$baseUrl/SHASUMS256.txt"
+        $line = ($sums -split "`n") | Where-Object { $_.Trim() -like "*  $zipName" } | Select-Object -First 1
+        if (-not $line) { throw "No checksum entry for $zipName" }
+        $expected = ($line.Trim() -split '\s+')[0]
+        if ((Get-FileHash -LiteralPath $zipPath -Algorithm SHA256).Hash -ne $expected.ToUpper()) { throw 'Node download failed checksum verification.' }
+        $extractDir = Join-Path $work 'extracted'
+        New-Item -ItemType Directory -Path $extractDir -Force | Out-Null
+        & tar.exe -xf $zipPath -C $extractDir
+        if ($LASTEXITCODE -ne 0) { $global:LASTEXITCODE = 0; Expand-Archive -LiteralPath $zipPath -DestinationPath $extractDir -Force }
+        $inner = Join-Path $extractDir "node-$version-win-$arch"
+        if (-not (Test-Path -LiteralPath (Join-Path $inner 'node.exe'))) { throw 'Unexpected Node archive layout.' }
+        Set-Runner $version
+        Publish-Directory -Staging $inner -Destination $nodeDir
+    }
+    finally {
+        if (Test-Path -LiteralPath $work) { Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue }
+    }
+}

package/sandbox/boot/bootstrap/status.ps1

@@ -0,0 +1,8 @@
+# The boot status the host waits on (run\sandbox.json), for bootstrap.ps1 (dot-sourced).
+function Set-Status([string]$Phase, [string]$Message) {
+    # Same shape as SandboxStatus in src/shared/schema.ts; written atomically so the host never reads half a file.
+    $status = [ordered]@{ launchId = $session.launchId; phase = $Phase; message = $Message; updatedAt = (Get-Date).ToUniversalTime().ToString('o'); workspaceHost = $session.workspaceHost; guestWorkspace = $session.workspace; headless = [bool]$session.headless }
+    $file = Join-Path $runDir 'sandbox.json'
+    [IO.File]::WriteAllText("$file.tmp", ($status | ConvertTo-Json -Compress))
+    Move-Item -LiteralPath "$file.tmp" -Destination $file -Force
+}

package/sandbox/boot/bootstrap.ps1

@@ -0,0 +1,91 @@
+#Requires -Version 5.1
+# Runs INSIDE Windows Sandbox (Windows PowerShell 5.1) in the sandbox window, started by logon.cmd.
+# Its only job: make sure the runner's Node exists in persistent storage, then hand over to runtime\main.js.
+# (That Node only runs agent-sandbox itself; the agent's `node` comes from nvm.)
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'   # progress bars make PS 5.1 downloads extremely slow
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+$launchDir = 'C:\AgentLaunch'
+$dataDir = 'C:\AgentData'
+$hostNodeDir = 'C:\HostTools\node'
+$hostNvm = 'C:\HostTools\nvm'
+$toolsDir = Join-Path $dataDir 'tools'
+# The runner's Node lives with nvm's versions (tools\nvm\v<version>), so nvm reuses it instead of copying it again.
+$nvmDir = Join-Path $toolsDir 'nvm'
+$runnerFile = Join-Path $toolsDir 'runner-node.txt'
+$nodeDir = $null
+$nodeExe = $null
+$logsDir = Join-Path $dataDir 'logs'
+$runDir = Join-Path $dataDir 'run'
+foreach ($dir in @($logsDir, $toolsDir, $nvmDir, $runDir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
+$host.UI.RawUI.WindowTitle = 'Agent Sandbox'
+Write-Host 'Agent sandbox bootstrap started.' -ForegroundColor Cyan
+$transcript = Join-Path $logsDir ('bootstrap-' + (Get-Date -Format 'yyyyMMdd-HHmmss') + '.log')
+Start-Transcript -Path $transcript | Out-Null
+$transcriptStopped = $false
+# -Encoding UTF8: Windows PowerShell 5.1 otherwise reads it in the ANSI code page (non-ASCII paths and names break).
+$session = Get-Content -LiteralPath (Join-Path $launchDir 'session.json') -Raw -Encoding UTF8 | ConvertFrom-Json
+$hostVersion = [string]$session.hostTools.nodeVersion
+
+# The functions (dot-sourced: they run in this script's scope and see its variables).
+. (Join-Path $PSScriptRoot 'bootstrap\status.ps1')
+. (Join-Path $PSScriptRoot 'bootstrap\files.ps1')
+. (Join-Path $PSScriptRoot 'bootstrap\runner.ps1')
+. (Join-Path $PSScriptRoot 'bootstrap\drives.ps1')
+
+try {
+    # First: hooks, toolchains and the agent all run in (or below) the workspace, which may be on one of these drives.
+    $unmounted = Mount-MirrorDrives
+    $workspaceDrive = ([string]$session.workspace).Substring(0, 1).ToUpperInvariant()
+    if ($unmounted -contains $workspaceDrive) {
+        throw "The workspace $($session.workspace) needs drive ${workspaceDrive}:, which could not be created in the sandbox (see the warning above). Set guestWorkspace to ""auto"" (C:\Workspace\<name>) for this project."
+    }
+    Set-Status 'booting' 'Preparing the runner'
+    $provisioning = $session.provisioning
+    if (-not $provisioning.refresh -and (Find-CachedRunner)) {
+        Write-Host ('Runner Node ' + (& $nodeExe --version) + ' cached in persistent storage.')
+    }
+    else {
+        $ready = $false
+        if ($provisioning.copyFromHost) {
+            $ready = Copy-NodeFromHost
+            if (-not $ready) {
+                if (-not $provisioning.fallbackToInstall) { throw 'Could not copy Node from this PC and provisioning.fallbackToInstall is false.' }
+                Write-Warning 'Host Node unavailable; downloading Node instead.'
+            }
+        }
+        if (-not $ready) { Install-NodeFromWeb }
+        if (-not (Test-Node)) { throw 'Node is not runnable after provisioning.' }
+        Write-Host ('Runner Node ' + (& $nodeExe --version) + ' ready.')
+    }
+    [IO.File]::WriteAllText($runnerFile, (Split-Path -Leaf $nodeDir).TrimStart('v'))
+    # Older versions kept a full copy of the host's Node folder here.
+    $legacy = Join-Path $toolsDir 'node'
+    if (Test-Path -LiteralPath $legacy) { Remove-Item -LiteralPath $legacy -Recurse -Force -ErrorAction SilentlyContinue }
+
+    $env:PATH = "$nodeDir;$env:PATH"
+    Set-Location -LiteralPath $session.workspace
+    Stop-Transcript | Out-Null
+    $transcriptStopped = $true
+    & $nodeExe (Join-Path $launchDir 'runtime\main.js')
+    $code = $LASTEXITCODE
+    if ($code -ne 0) {
+        # main.js reports its own failures; this catches it dying before it could (e.g. a broken Node).
+        $current = Get-Content -LiteralPath (Join-Path $runDir 'sandbox.json') -Raw -Encoding UTF8 -ErrorAction SilentlyContinue | ConvertFrom-Json -ErrorAction SilentlyContinue
+        if ($null -eq $current -or $current.phase -ne 'failed') { Set-Status 'failed' ("The sandbox runner stopped (exit code $code). See C:\AgentData\logs.") }
+        Write-Host "The sandbox runner stopped with exit code $code. Logs: $logsDir" -ForegroundColor Red
+    }
+    Update-Environment
+    Write-Host "This window stays open in $($session.workspace)."
+}
+catch {
+    $report = ($_ | Format-List * -Force | Out-String) + "`r`n" + $_.ScriptStackTrace
+    Set-Content -Path (Join-Path $logsDir 'bootstrap-error.txt') -Value $report -Encoding UTF8
+    try { Set-Status 'failed' ('Bootstrap failed: ' + $_.Exception.Message) } catch { }
+    Write-Host $report -ForegroundColor Red
+    Write-Host "Saved to $logsDir\bootstrap-error.txt" -ForegroundColor Yellow
+}
+finally {
+    if (-not $transcriptStopped) { try { Stop-Transcript | Out-Null } catch { } }
+}

package/sandbox/{logon.cmd → boot/logon.cmd}

@@ -3,17 +3,23 @@ rem Windows Sandbox runs LogonCommand in a hidden window, so this opens the VISI
 rem (downloaded once by the host into persistent storage), or a plain PowerShell window if it is missing or fails.
 if not exist C:\AgentData\logs mkdir C:\AgentData\logs
 echo logon.cmd ran at %date% %time% > C:\AgentData\logs\logon-hit.txt
-call C:\AgentLaunch\sandbox\trust.cmd
+call C:\AgentLaunch\sandbox\boot\trust.cmd
 rem New Terminal tabs start in %AGENT_WORKSPACE%: Terminal must have it before the runtime sets it machine-wide.
 if exist C:\AgentLaunch\env.cmd call C:\AgentLaunch\env.cmd
 set "PS=%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe"
+rem SandboxTools.exe (sandbox\csharp\SandboxTools), built once per boot on the sandbox's own disk (no window: winexe).
+set "TOOLS=%TEMP%\agent-sandbox\SandboxTools.exe"
+if not exist "%TEMP%\agent-sandbox" mkdir "%TEMP%\agent-sandbox"
+if not exist "%TOOLS%" "%SystemRoot%\Microsoft.NET\Framework64\v4.0.30319\csc.exe" /nologo /optimize /target:winexe /out:"%TOOLS%" C:\AgentLaunch\sandbox\csharp\SandboxTools\*.cs >> C:\AgentData\logs\logon-hit.txt 2>&1
+if not exist "%TOOLS%" goto tools_done
 rem sandbox.cpuLimit: this window joins a CPU-capped job first, so everything started below inherits the cap.
-"%PS%" -NoLogo -NoProfile -ExecutionPolicy Bypass -File C:\AgentLaunch\sandbox\cpucap.ps1
+"%TOOLS%" cpu-cap
 rem sandbox.pageFileMb: room for many parallel builds (the sandbox starts with about 1 GB of paging file).
-"%PS%" -NoLogo -NoProfile -ExecutionPolicy Bypass -File C:\AgentLaunch\sandbox\pagefile.ps1
+"%TOOLS%" page-file
 rem The memory state every 30 s into the persistent logs, so a crash leaves evidence.
-start "" /min "%PS%" -NoLogo -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File C:\AgentLaunch\sandbox\memlog.ps1
-set "BOOT=%PS% -NoLogo -NoProfile -ExecutionPolicy Bypass -NoExit -File C:\AgentLaunch\sandbox\bootstrap.ps1"
+start "" "%TOOLS%" memory-log
+:tools_done
+set "BOOT=%PS% -NoLogo -NoProfile -ExecutionPolicy Bypass -NoExit -File C:\AgentLaunch\sandbox\boot\bootstrap.ps1"
 if not exist C:\AgentData\tools\terminal\wt.exe goto plain
 start "" C:\AgentData\tools\terminal\wt.exe --maximized new-tab --title "Agent Sandbox" -d C:\AgentLaunch %BOOT%
 rem If Windows Terminal could not start, fall back to PowerShell so there is always a window.

package/sandbox/{cargoshim.cs → csharp/CargoShim.cs}

@@ -17,11 +17,15 @@ static class CargoShim
             Console.Error.WriteLine("error: the real cargo was not found (AGENT_REAL_CARGO).");
             return 101;
         }
-        var start = new ProcessStartInfo(real, ArgumentsOf(Environment.CommandLine)) { UseShellExecute = false };
+        ProcessStartInfo start = new ProcessStartInfo(real, ArgumentsOf(Environment.CommandLine));
+        start.UseShellExecute = false;
         if (string.IsNullOrEmpty(Environment.GetEnvironmentVariable("CARGO_TARGET_DIR")))
         {
             string root = CheckoutOf(Environment.CurrentDirectory);
-            if (root != null) start.EnvironmentVariables["CARGO_TARGET_DIR"] = Path.Combine(root, "target", "sandbox");
+            if (root != null)
+            {
+                start.EnvironmentVariables["CARGO_TARGET_DIR"] = Path.Combine(root, "target", "sandbox");
+            }
         }
         // Ctrl+C reaches cargo too (same console); the shim only waits for it to finish.
         Console.CancelKeyPress += delegate(object sender, ConsoleCancelEventArgs e) { e.Cancel = true; };
@@ -35,11 +39,17 @@ static class CargoShim
     static string CheckoutOf(string dir)
     {
         string cargoRoot = null;
-        for (var d = new DirectoryInfo(dir); d != null; d = d.Parent)
+        for (DirectoryInfo d = new DirectoryInfo(dir); d != null; d = d.Parent)
         {
             string git = Path.Combine(d.FullName, ".git");
-            if (Directory.Exists(git) || File.Exists(git)) return d.FullName;
-            if (cargoRoot == null && File.Exists(Path.Combine(d.FullName, "Cargo.toml"))) cargoRoot = d.FullName;
+            if (Directory.Exists(git) || File.Exists(git))
+            {
+                return d.FullName;
+            }
+            if (cargoRoot == null && File.Exists(Path.Combine(d.FullName, "Cargo.toml")))
+            {
+                cargoRoot = d.FullName;
+            }
         }
         return cargoRoot;
     }
@@ -49,8 +59,19 @@ static class CargoShim
     {
         string s = commandLine.TrimStart();
         int end;
-        if (s.StartsWith("\"")) { end = s.IndexOf('"', 1); end = end < 0 ? s.Length : end + 1; }
-        else { end = s.IndexOf(' '); if (end < 0) end = s.Length; }
+        if (s.StartsWith("\""))
+        {
+            end = s.IndexOf('"', 1);
+            end = end < 0 ? s.Length : end + 1;
+        }
+        else
+        {
+            end = s.IndexOf(' ');
+            if (end < 0)
+            {
+                end = s.Length;
+            }
+        }
         return s.Substring(end).TrimStart();
     }
 }

package/sandbox/csharp/Desktop.cs

@@ -0,0 +1,33 @@
+// Applies a wallpaper the way the Settings app does. Loaded by scripts\set-desktop.ps1 (Add-Type). C# 5.
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+namespace AgentSandbox
+{
+    public static class Desk
+    {
+        private const int SetDesktopWallpaper = 20;
+        private const int UpdateIniFileAndBroadcast = 3;
+
+        private static class NativeMethods
+        {
+            [DllImport("user32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern int SystemParametersInfo(int action, int param, string value, int winIni);
+        }
+
+        /// <summary>The raw call (kept for scripts that used it): non-zero on success.</summary>
+        public static int SystemParametersInfo(int action, int param, string value, int winIni)
+        {
+            return NativeMethods.SystemParametersInfo(action, param, value, winIni);
+        }
+
+        /// <summary>Shows the image at path as the wallpaper and saves it to the profile. Throws on failure.</summary>
+        public static void SetWallpaper(string path)
+        {
+            if (NativeMethods.SystemParametersInfo(SetDesktopWallpaper, 0, path, UpdateIniFileAndBroadcast) == 0)
+            {
+                throw new Win32Exception(Marshal.GetLastWin32Error());
+            }
+        }
+    }
+}

package/sandbox/csharp/EnvBroadcast.cs

@@ -0,0 +1,33 @@
+// Tells running programs (Explorer, Windows Terminal) that the machine environment changed, so new windows and tabs
+// read the current PATH. Loaded by scripts\set-machine-environment.ps1 (Add-Type). C# 5.
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+namespace AgentSandbox
+{
+    public static class EnvBroadcast
+    {
+        private static readonly IntPtr HwndBroadcast = new IntPtr(0xffff);
+        private const uint WmSettingChange = 0x001A;
+        private const uint SmtoAbortIfHung = 0x0002;
+        private const uint TimeoutMs = 2000;
+
+        private static class NativeMethods
+        {
+            [DllImport("user32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, UIntPtr wParam, string lParam, uint flags, uint timeout, out UIntPtr result);
+        }
+
+        /// <summary>Broadcasts WM_SETTINGCHANGE "Environment". Throws on failure.</summary>
+        public static void Notify()
+        {
+            UIntPtr result;
+            IntPtr sent = NativeMethods.SendMessageTimeout(HwndBroadcast, WmSettingChange, UIntPtr.Zero, "Environment", SmtoAbortIfHung, TimeoutMs, out result);
+            if (sent == IntPtr.Zero)
+            {
+                throw new Win32Exception(Marshal.GetLastWin32Error());
+            }
+        }
+    }
+}

package/sandbox/{gitshim.cs → csharp/GitShim.cs}

@@ -15,7 +15,8 @@ static class GitShim
             Console.Error.WriteLine("fatal: git is not available in this sandbox.");
             return 128;
         }
-        var start = new ProcessStartInfo(node, "\"" + guard + "\" " + ArgumentsOf(Environment.CommandLine)) { UseShellExecute = false };
+        ProcessStartInfo start = new ProcessStartInfo(node, "\"" + guard + "\" " + ArgumentsOf(Environment.CommandLine));
+        start.UseShellExecute = false;
         using (Process p = Process.Start(start))
         {
             p.WaitForExit();
@@ -28,8 +29,19 @@ static class GitShim
     {
         string s = commandLine.TrimStart();
         int end;
-        if (s.StartsWith("\"")) { end = s.IndexOf('"', 1); end = end < 0 ? s.Length : end + 1; }
-        else { end = s.IndexOf(' '); if (end < 0) end = s.Length; }
+        if (s.StartsWith("\""))
+        {
+            end = s.IndexOf('"', 1);
+            end = end < 0 ? s.Length : end + 1;
+        }
+        else
+        {
+            end = s.IndexOf(' ');
+            if (end < 0)
+            {
+                end = s.Length;
+            }
+        }
         return s.Substring(end).TrimStart();
     }
 }