windows-development-sandbox 1.4.0 → 1.4.3

package/native/stop-events.ps1

@@ -0,0 +1,38 @@
+#Requires -Version 5.1
+# Prints, as JSON, the Windows events since -Since that can end a sandbox: restarts and shutdowns, power loss, sleep,
+# low memory, this PC's blue screens, and Windows inside the sandbox crashing. Read-only. Used by host/stops.ts.
+param([Parameter(Mandatory = $true)][datetime]$Since)
+$ErrorActionPreference = 'Stop'
+
+$filters = @(
+    @{ LogName = 'System'; Id = 1074, 6008, 41, 42, 2004; StartTime = $Since },
+    @{ LogName = 'System'; Id = 1001; ProviderName = 'Microsoft-Windows-WER-SystemErrorReporting'; StartTime = $Since },
+    @{ LogName = 'Microsoft-Windows-Hyper-V-Worker-Admin'; Id = 18590, 40001; StartTime = $Since }
+)
+$maxMessage = 390
+
+# What each event says beyond its id: the program that asked for a restart (1074), else the start of the message.
+function Get-EventDetail($record) {
+    if ($record.Id -eq 1074) { return [string]$record.Properties[0].Value }
+    if ($record.Id -in 18590, 40001, 1001) {
+        $message = [string]$record.Message
+        return $message.Substring(0, [math]::Min($maxMessage, $message.Length))
+    }
+    return ''
+}
+
+$events = foreach ($filter in $filters) {
+    try {
+        Get-WinEvent -FilterHashtable $filter -MaxEvents 100 | ForEach-Object {
+            [pscustomobject]@{
+                at       = $_.TimeCreated.ToUniversalTime().ToString('o')
+                id       = $_.Id
+                provider = $_.ProviderName
+                process  = Get-EventDetail $_
+            }
+        }
+    } catch {
+        # No matching events, or a log this PC does not have: nothing to add.
+    }
+}
+ConvertTo-Json -Compress -InputObject @($events)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windows-development-sandbox",
-  "version": "1.4.0",
+  "version": "1.4.3",
   "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",
@@ -33,6 +33,7 @@
   "files": [
     "dist",
     "sandbox",
+    "native",
     "schemas",
     "hooks",
     "config.example.json",
@@ -51,7 +52,10 @@
     "release:major": "npm version major && git push --follow-tags",
     "install:global": "node scripts/install-global.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
-    "doctor": "node dist/bin/agent-sandbox.js doctor"
+    "doctor": "node dist/bin/agent-sandbox.js doctor",
+    "lint": "eslint src scripts",
+    "format": "prettier --write src scripts",
+    "format:check": "prettier --check src scripts"
   },
   "publishConfig": {
     "access": "public"
@@ -78,10 +82,14 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@types/lodash": "^4.17.26",
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.2",
-    "typescript": "^5.8.0"
+    "eslint": "^9.39.5",
+    "prettier": "^3.9.10",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.71.2"
   },
   "repository": {
     "type": "git",

package/sandbox/linkgate.cs

@@ -0,0 +1,98 @@
+// The linker for Rust's GNU host inside the sandbox (CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER). It runs MinGW's gcc,
+// but only as many at once as AGENT_LINK_SLOTS allows across the whole sandbox, and with Rust's own lld when
+// AGENT_LLD_DIR is set: several agents linking big programs with GNU ld at the same time used 2 GB+ each and took
+// Windows down. Each slot is a named mutex, which Windows frees when its owner dies (a killed build never keeps a
+// slot). Compiled inside the sandbox with the .NET Framework csc.exe (C# 5).
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.Threading;
+
+static class LinkGate
+{
+    const string SlotPrefix = @"Global\AgentSandboxLinkSlot";
+
+    static int Main()
+    {
+        string real = Environment.GetEnvironmentVariable("AGENT_REAL_LINKER");
+        if (string.IsNullOrEmpty(real) || !File.Exists(real))
+        {
+            Console.Error.WriteLine("error: the real linker was not found (AGENT_REAL_LINKER).");
+            return 1;
+        }
+        string args = ArgumentsOf(Environment.CommandLine);
+        string lld = Environment.GetEnvironmentVariable("AGENT_LLD_DIR");
+        if (!string.IsNullOrEmpty(lld) && File.Exists(Path.Combine(lld, "ld.lld.exe")))
+        {
+            args = args + " -fuse-ld=lld \"-B" + lld + "\"";
+        }
+        Mutex[] slots = new Mutex[SlotCount()];
+        for (int i = 0; i < slots.Length; i++) slots[i] = new Mutex(false, SlotPrefix + i);
+        try
+        {
+            int held = Acquire(slots);
+            try
+            {
+                return Run(real, args);
+            }
+            finally
+            {
+                slots[held].ReleaseMutex();
+            }
+        }
+        finally
+        {
+            foreach (Mutex slot in slots) slot.Dispose();
+        }
+    }
+
+    /// <summary>Waits for any free slot and returns its index (a slot left by a killed linker counts as free).</summary>
+    static int Acquire(Mutex[] slots)
+    {
+        try
+        {
+            return WaitHandle.WaitAny(slots);
+        }
+        catch (AbandonedMutexException e)
+        {
+            return e.MutexIndex;
+        }
+    }
+
+    static int Run(string program, string args)
+    {
+        var start = new ProcessStartInfo(program, args) { UseShellExecute = false };
+        // Ctrl+C reaches the linker too (same console); the gate only waits for it to finish.
+        Console.CancelKeyPress += delegate(object sender, ConsoleCancelEventArgs e) { e.Cancel = true; };
+        using (Process p = Process.Start(start))
+        {
+            p.WaitForExit();
+            return p.ExitCode;
+        }
+    }
+
+    static int SlotCount()
+    {
+        int slots;
+        string value = Environment.GetEnvironmentVariable("AGENT_LINK_SLOTS");
+        return int.TryParse(value, out slots) && slots > 0 && slots <= 32 ? slots : 2;
+    }
+
+    // Everything after the program name, untouched, so quoting survives exactly as cargo wrote it.
+    static string ArgumentsOf(string commandLine)
+    {
+        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;
+        }
+        return s.Substring(end).TrimStart();
+    }
+}

package/sandbox/memlog.ps1

@@ -1,10 +1,12 @@
 #Requires -Version 5.1
-# Writes the sandbox's memory state to C:\AgentData\logs\memory-<time>.log every 30 seconds, while it runs. That folder
-# outlives the sandbox, so if Windows inside it ever crashes again, the last lines show what was using memory just
-# before. Bounded: a file is closed at 1 MB (about two days) and a new one started; only the newest 10 are kept, so
-# the logs never take more than about 10 MB. Started hidden by logon.cmd. Never stops the boot.
+# Writes the sandbox's memory state to C:\AgentData\logs\memory-<time>.log while it runs: every 30 seconds, and every
+# 5 when RAM or commit is above 60%. That folder outlives the sandbox, so if Windows inside it crashes, the last lines
+# show what used memory just before. memory-pressure.txt holds the latest state (ok, high, critical) for agents to
+# check before big builds. Bounded: a file is closed at 1 MB and a new one started; only the newest 10 are kept.
+# Started hidden by logon.cmd. Never stops the boot.
 $ErrorActionPreference = 'SilentlyContinue'
 $logFolder = 'C:\AgentData\logs'
+$pressureFile = Join-Path $logFolder 'memory-pressure.txt'
 $maxFileBytes = 1MB
 $keepFiles = 10
 
@@ -27,8 +29,15 @@ while ($true) {
     $processes = @(Get-Process)
     $biggest = $processes | Sort-Object PrivateMemorySize64 -Descending | Select-Object -First 5 |
         ForEach-Object { '{0} {1}' -f $_.ProcessName, [math]::Round($_.PrivateMemorySize64 / 1MB) }
-    '{0:HH:mm:ss} | {1}/{2} | {3}/{4} | {5} processes; {6}' -f (Get-Date), $ramUsedMb, $ramTotalMb, $commitUsedMb, $commitLimitMb, $processes.Count, ($biggest -join ', ') |
+    $now = Get-Date
+    '{0:HH:mm:ss} | {1}/{2} | {3}/{4} | {5} processes; {6}' -f $now, $ramUsedMb, $ramTotalMb, $commitUsedMb, $commitLimitMb, $processes.Count, ($biggest -join ', ') |
         Add-Content -LiteralPath $logPath
+
+    $usedShare = [math]::Max($ramUsedMb / [math]::Max($ramTotalMb, 1), $commitUsedMb / [math]::Max($commitLimitMb, 1))
+    $level = if ($usedShare -ge 0.85) { 'critical' } elseif ($usedShare -ge 0.6) { 'high' } else { 'ok' }
+    '{0} {1:yyyy-MM-ddTHH:mm:ss} RAM {2}/{3} MB, commit {4}/{5} MB' -f $level, $now, $ramUsedMb, $ramTotalMb, $commitUsedMb, $commitLimitMb |
+        Set-Content -LiteralPath $pressureFile
+
     if ((Get-Item -LiteralPath $logPath).Length -ge $maxFileBytes) { $logPath = New-MemoryLog }
-    Start-Sleep -Seconds 30
+    Start-Sleep -Seconds $(if ($level -eq 'ok') { 30 } else { 5 })
 }

package/sandbox/ptyhost.cs

@@ -18,7 +18,8 @@
 //                  20 STATUS  [viewers:2][remoteViewers:2]  viewers heard from recently (remote = not loopback, i.e. the PC)
 //                  21 CONSOLE utf8 "conpty.dll" or "windows", sent after HELLO. With conpty.dll the output is passed
 //                             through (real scrollback, no repaint on resize): a viewer that joins later is sent the
-//                             output since the last screen clear instead, and must not clear its screen on a resize.
+//                             terminal modes in force (mouse tracking ...) and the output since the last screen clear
+//                             instead, and must not clear its screen on a resize.
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
@@ -265,7 +266,12 @@ sealed class ClientHub
             // Taken and queued under the replay lock, so no output falls between the replay and the live stream.
             lock (replayGate)
             {
-                if (Native.ConsoleKind.StartsWith("conpty") && replay.Length > 0) Send(client, Frame.Output, replay.ToArray());
+                if (Native.ConsoleKind.StartsWith("conpty"))
+                {
+                    byte[] prefix = ModePrefix();
+                    if (prefix.Length > 0) Send(client, Frame.Output, prefix);
+                    if (replay.Length > 0) Send(client, Frame.Output, replay.ToArray());
+                }
                 lock (gate) clients.Add(client);
             }
             TakeOwnership(client);
@@ -319,6 +325,7 @@ sealed class ClientHub
     void Record(byte[] output)
     {
         if (!Native.ConsoleKind.StartsWith("conpty")) return;
+        TrackModes(output);
         int clear = LastClear(output);
         if (clear >= 0) { replay.SetLength(0); replay.Write(output, clear, output.Length - clear); }
         else replay.Write(output, 0, output.Length);
@@ -330,6 +337,56 @@ sealed class ClientHub
         if (from + 1 < all.Length) replay.Write(all, from + 1, all.Length - from - 1);
     }
 
+    /**
+     * Terminal modes the program (or conpty.dll) turned on that a late viewer's terminal must have too, or its clicks and
+     * wheel never reach the program: mouse tracking (1000, 1002, 1003, 1005, 1006, 1015), focus events (1004), bracketed
+     * paste (2004), win32 input (9001), application cursor keys (1), cursor visibility (25), the alternate screen (1049).
+     * The replay is cut at the last screen clear, which may come after the program turned them on.
+     */
+    static readonly int[] ReplayedModes = { 1, 25, 1000, 1002, 1003, 1004, 1005, 1006, 1015, 1049, 2004, 9001 };
+    readonly Dictionary<int, bool> modes = new Dictionary<int, bool>();
+    /** DECSET / DECRST parser, kept across chunks: 0 text, 1 after ESC, 2 after ESC[, 3 in ESC[? parameters. */
+    int modeState;
+    readonly StringBuilder modeParams = new StringBuilder();
+
+    void TrackModes(byte[] output)
+    {
+        foreach (byte b in output)
+        {
+            if (b == 0x1b) { modeState = 1; continue; }
+            switch (modeState)
+            {
+                case 1: modeState = b == (byte)'[' ? 2 : 0; break;
+                case 2: modeState = b == (byte)'?' ? 3 : 0; modeParams.Length = 0; break;
+                case 3:
+                    if ((b >= (byte)'0' && b <= (byte)'9') || b == (byte)';') { if (modeParams.Length < 64) modeParams.Append((char)b); }
+                    else
+                    {
+                        if (b == (byte)'h' || b == (byte)'l')
+                            foreach (string p in modeParams.ToString().Split(';'))
+                            {
+                                int mode;
+                                if (int.TryParse(p, out mode) && Array.IndexOf(ReplayedModes, mode) >= 0) modes[mode] = b == (byte)'h';
+                            }
+                        modeState = 0;
+                    }
+                    break;
+            }
+        }
+    }
+
+    /** The modes to set before the replay, e.g. ESC[?1000h ESC[?1006h. */
+    byte[] ModePrefix()
+    {
+        var text = new StringBuilder();
+        foreach (int mode in ReplayedModes)
+        {
+            bool on;
+            if (modes.TryGetValue(mode, out on)) text.Append("\x1b[?" + mode + (on ? "h" : "l"));
+        }
+        return Encoding.ASCII.GetBytes(text.ToString());
+    }
+
     /** Where the last ESC[2J (clear screen) or ESC c (reset) starts in `data`, or -1. */
     static int LastClear(byte[] data)
     {
@@ -364,7 +421,7 @@ sealed class ClientHub
     }
 
     /** A restarted program starts on a clean screen (viewers clear theirs on RESTARTING). */
-    public void ResetReplay() { lock (replayGate) replay.SetLength(0); }
+    public void ResetReplay() { lock (replayGate) { replay.SetLength(0); modes.Clear(); modeState = 0; } }
 
     public void Notify(byte type)
     {

package/schemas/config.schema.json

@@ -99,8 +99,10 @@
             "description": "Folder on this PC (relative paths are relative to the config file)."
           },
           "guest": {
+            "description": "Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A full path only; one the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) stops the launch with the fix.",
             "type": "string",
-            "description": "Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot."
+            "minLength": 1,
+            "maxLength": 1024
           },
           "readOnly": {
             "type": "boolean",
@@ -508,6 +510,28 @@
               "type": "string",
               "minLength": 1,
               "description": "\"shared\": cargo's default target\\ (shared with builds on this PC, so builds on either side invalidate the other), \"separate\": <workspace>\\target\\sandbox (kept, no cross-talk), \"local\": on the sandbox's own disk (fastest, lost every boot), or a guest path."
+            },
+            "linker": {
+              "type": "string",
+              "enum": [
+                "lld",
+                "gnu"
+              ],
+              "description": "GNU host: \"lld\" links with Rust's own lld through MinGW's gcc (much less memory than GNU ld), \"gnu\" with GNU ld."
+            },
+            "linkSlots": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "const": "auto"
+                },
+                {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 32
+                }
+              ],
+              "description": "GNU host: how many programs may link at the same time in the whole sandbox (other links wait). \"auto\" = one per 8 GB of sandbox memory, 2 to 4. Several agents linking big programs at once can take Windows down."
             }
           },
           "additionalProperties": false
@@ -1204,6 +1228,17 @@
               "xh",
               "grpcurl",
               "k6",
+              "rea",
+              "ghidra",
+              "x64dbg",
+              "ilspy",
+              "dnspy",
+              "die",
+              "pe-bear",
+              "cutter",
+              "radare2",
+              "jadx",
+              "system-informer",
               "jq",
               "yq",
               "ripgrep",
@@ -1449,6 +1484,18 @@
           },
           "description": "Parent folders you said no to (not asked again)."
         },
+        "allowOutsideMappings": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ask"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "A project's .sandbox-config.json may map folders from outside the project (e.g. a game folder on another drive). \"ask\" = an interactive launch asks once per project and set of folders, and remembers your answer; true = always allowed (still listed when you approve the file); false = never (the launch stops and says which folders). Only your own settings decide this, never a project file."
+        },
         "wsbShare": {
           "type": "boolean",
           "description": "On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart."

package/schemas/sandbox-config.schema.json

@@ -61,8 +61,10 @@
             "description": "Folder on this PC (relative paths are relative to the config file)."
           },
           "guest": {
+            "description": "Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A full path only; one the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) stops the launch with the fix.",
             "type": "string",
-            "description": "Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot."
+            "minLength": 1,
+            "maxLength": 1024
           },
           "readOnly": {
             "type": "boolean",
@@ -75,12 +77,11 @@
         },
         "required": [
           "host",
-          "guest",
           "readOnly"
         ],
         "additionalProperties": false
       },
-      "description": "Extra folders inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox."
+      "description": "Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once)."
     },
     "scripts": {
       "type": "array",
@@ -379,6 +380,28 @@
               "type": "string",
               "minLength": 1,
               "description": "\"shared\": cargo's default target\\ (shared with builds on this PC, so builds on either side invalidate the other), \"separate\": <workspace>\\target\\sandbox (kept, no cross-talk), \"local\": on the sandbox's own disk (fastest, lost every boot), or a guest path."
+            },
+            "linker": {
+              "type": "string",
+              "enum": [
+                "lld",
+                "gnu"
+              ],
+              "description": "GNU host: \"lld\" links with Rust's own lld through MinGW's gcc (much less memory than GNU ld), \"gnu\" with GNU ld."
+            },
+            "linkSlots": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "const": "auto"
+                },
+                {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 32
+                }
+              ],
+              "description": "GNU host: how many programs may link at the same time in the whole sandbox (other links wait). \"auto\" = one per 8 GB of sandbox memory, 2 to 4. Several agents linking big programs at once can take Windows down."
             }
           },
           "additionalProperties": false
@@ -1019,6 +1042,17 @@
               "xh",
               "grpcurl",
               "k6",
+              "rea",
+              "ghidra",
+              "x64dbg",
+              "ilspy",
+              "dnspy",
+              "die",
+              "pe-bear",
+              "cutter",
+              "radare2",
+              "jadx",
+              "system-informer",
               "jq",
               "yq",
               "ripgrep",

package/dist/cli/commands/launch.d.ts

@@ -1,29 +0,0 @@
-import { attachTerminal } from '../../host/attach.js';
-import type { SandboxStatus } from '../../core/types.js';
-import { type Context } from './context.js';
-import { type Joined } from './project.js';
-/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
-export declare const attachHere: (ctx: Context, session: Parameters<typeof attachTerminal>[0]) => Promise<number>;
-/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
-export declare const runningSandboxStatus: (dataPath: string) => Promise<SandboxStatus>;
-/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
-export declare const waitForBoot: (dataPath: string, launchId: string | null) => Promise<SandboxStatus>;
-/** The running sandbox, once it is ready. */
-export declare const readySandbox: (dataPath: string) => Promise<SandboxStatus>;
-/**
- * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
- * Exported for restart.ts, which reopens the sessions a restart ended.
- */
-export declare const openSession: (ctx: Context, ready: SandboxStatus, joined: Joined, o: {
-    attach: boolean;
-    harness?: string;
-    args?: string[];
-    reuse?: boolean;
-}) => Promise<number>;
-/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
-export interface LaunchExtras {
-    extraProjects?: string[];
-    autoSession?: boolean;
-    waitUntilReady?: boolean;
-}
-export declare const launch: (ctx: Context, generateOnly?: boolean, extras?: LaunchExtras) => Promise<number>;