windows-development-sandbox 1.5.0 → 1.9.0

package/sandbox/csharp/PtyHost.cs

@@ -79,7 +79,7 @@ sealed class SessionHost
         log.Write("starting: " + command);
         while (true)
         {
-            using (PseudoConsole console = PseudoConsole.Start(command, hub.Cols, hub.Rows, hub.Broadcast))
+            using (PseudoConsole console = PseudoConsole.Start(command, hub.Cols, hub.Rows, hub.Broadcast, log))
             {
                 hub.Attach(console);
                 log.Write("pseudo console: " + Native.ConsoleKind);
@@ -856,7 +856,7 @@ sealed class PseudoConsole : IDisposable
         this.pump = pump;
     }
 
-    public static PseudoConsole Start(string commandLine, short cols, short rows, Action<byte[]> onOutput)
+    public static PseudoConsole Start(string commandLine, short cols, short rows, Action<byte[]> onOutput, Log log)
     {
         SafeFileHandle inRead;
         SafeFileHandle inWrite;
@@ -872,7 +872,7 @@ sealed class PseudoConsole : IDisposable
         }
         inRead.Dispose();
         outWrite.Dispose();
-        IntPtr process = Native.Spawn(commandLine, handle);
+        IntPtr process = Native.Spawn(commandLine, handle, log);
         FileStream output = new FileStream(outRead, FileAccess.Read);
         Thread pump = new Thread(() => Pump(output, onOutput));
         pump.IsBackground = true;
@@ -1085,6 +1085,12 @@ sealed class Log
 static class Native
 {
     private const uint ExtendedStartupInfoPresent = 0x00080000;
+    private const uint CreateSuspended = 0x00000004;
+    // The shared job of everything the agents start (the memory governor in the daemon opens it by this name).
+    private const string AgentJobName = "Local\\AgentSandboxAgentsJob";
+    private const int JobObjectExtendedLimitInformation = 9;
+    private const uint JobObjectLimitJobMemory = 0x00000200;
+    private const long BytesPerMb = 1024L * 1024L;
     private const int UseStdHandles = 0x00000100;
     private static readonly IntPtr PseudoConsoleAttribute = (IntPtr)0x00020016;
 
@@ -1125,6 +1131,43 @@ static class Native
         public IntPtr lpAttributeList;
     }
 
+    // JOBOBJECT_BASIC_LIMIT_INFORMATION, IO_COUNTERS and JOBOBJECT_EXTENDED_LIMIT_INFORMATION.
+    [StructLayout(LayoutKind.Sequential)]
+    private struct JobBasicLimit
+    {
+        public long PerProcessUserTimeLimit;
+        public long PerJobUserTimeLimit;
+        public uint LimitFlags;
+        public UIntPtr MinimumWorkingSetSize;
+        public UIntPtr MaximumWorkingSetSize;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint PriorityClass;
+        public uint SchedulingClass;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct IoCounters
+    {
+        public ulong ReadOperationCount;
+        public ulong WriteOperationCount;
+        public ulong OtherOperationCount;
+        public ulong ReadTransferCount;
+        public ulong WriteTransferCount;
+        public ulong OtherTransferCount;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct JobExtendedLimit
+    {
+        public JobBasicLimit BasicLimitInformation;
+        public IoCounters IoInfo;
+        public UIntPtr ProcessMemoryLimit;
+        public UIntPtr JobMemoryLimit;
+        public UIntPtr PeakProcessMemoryUsed;
+        public UIntPtr PeakJobMemoryUsed;
+    }
+
     [StructLayout(LayoutKind.Sequential)]
     private struct ProcessInformation
     {
@@ -1182,6 +1225,18 @@ static class Native
         [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
         public static extern bool CreateProcessW(string lpApplicationName, StringBuilder lpCommandLine, IntPtr lpProcessAttributes, IntPtr lpThreadAttributes, bool bInheritHandles, uint dwCreationFlags, IntPtr lpEnvironment, string lpCurrentDirectory, ref StartupInfoEx lpStartupInfo, out ProcessInformation lpProcessInformation);
 
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        public static extern IntPtr CreateJobObjectW(IntPtr attributes, string name);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool SetInformationJobObject(IntPtr job, int infoClass, ref JobExtendedLimit info, int length);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool AssignProcessToJobObject(IntPtr job, IntPtr process);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern uint ResumeThread(IntPtr thread);
+
         [DllImport("kernel32.dll", SetLastError = true)]
         public static extern uint WaitForSingleObject(IntPtr hHandle, uint dwMilliseconds);
 
@@ -1241,9 +1296,51 @@ static class Native
         return NativeMethods.CreatePipe(out read, out write, IntPtr.Zero, 0);
     }
 
+    private static IntPtr agentJob;
+    private static bool agentJobTried;
+
+    /// <summary>
+    /// The shared job of everything the agents start, with a memory limit for all of it together (PTYHOST_JOB_MB, set
+    /// by the daemon from sandbox.agentMemoryHeadroomMb): a runaway build then gets out-of-memory errors in its own
+    /// session instead of using up the whole sandbox. Zero when no limit is asked for or the job cannot be made; ptyhost
+    /// itself is never in it. The handle stays open for ptyhost's whole life (the job lives while a handle is open).
+    /// </summary>
+    private static IntPtr AgentJob(Log log)
+    {
+        if (agentJobTried)
+        {
+            return agentJob;
+        }
+        agentJobTried = true;
+        long limitMb;
+        if (!long.TryParse(Environment.GetEnvironmentVariable("PTYHOST_JOB_MB"), out limitMb) || limitMb < 512)
+        {
+            return IntPtr.Zero;
+        }
+        IntPtr job = NativeMethods.CreateJobObjectW(IntPtr.Zero, AgentJobName);
+        if (job == IntPtr.Zero)
+        {
+            log.Write("agent job: CreateJobObject failed (" + Marshal.GetLastWin32Error() + "); no memory limit");
+            return IntPtr.Zero;
+        }
+        JobExtendedLimit info = new JobExtendedLimit();
+        info.BasicLimitInformation.LimitFlags = JobObjectLimitJobMemory;
+        info.JobMemoryLimit = new UIntPtr((ulong)(limitMb * BytesPerMb));
+        if (!NativeMethods.SetInformationJobObject(job, JobObjectExtendedLimitInformation, ref info, Marshal.SizeOf(typeof(JobExtendedLimit))))
+        {
+            log.Write("agent job: setting the limit failed (" + Marshal.GetLastWin32Error() + "); no memory limit");
+            NativeMethods.CloseHandle(job);
+            return IntPtr.Zero;
+        }
+        log.Write("agent job: everything the agent starts may use " + limitMb + " MB together");
+        agentJob = job;
+        return job;
+    }
+
     /// <summary>Starts `commandLine` attached to the pseudo console. Null std handles: never leak our own stdio into the child.</summary>
-    public static IntPtr Spawn(string commandLine, IntPtr pseudoConsole)
+    public static IntPtr Spawn(string commandLine, IntPtr pseudoConsole, Log log)
     {
+        IntPtr job = AgentJob(log);
         IntPtr size = IntPtr.Zero;
         NativeMethods.InitializeProcThreadAttributeList(IntPtr.Zero, 1, 0, ref size);
         IntPtr attributes = Marshal.AllocHGlobal(size);
@@ -1256,10 +1353,19 @@ static class Native
             info.StartupInfo.dwFlags = UseStdHandles;
             info.lpAttributeList = attributes;
             ProcessInformation pi;
-            if (!NativeMethods.CreateProcessW(null, new StringBuilder(commandLine), IntPtr.Zero, IntPtr.Zero, false, ExtendedStartupInfoPresent, IntPtr.Zero, null, ref info, out pi))
+            if (!NativeMethods.CreateProcessW(null, new StringBuilder(commandLine), IntPtr.Zero, IntPtr.Zero, false, ExtendedStartupInfoPresent | (job != IntPtr.Zero ? CreateSuspended : 0), IntPtr.Zero, null, ref info, out pi))
             {
                 throw new IOException("CreateProcess failed (" + Marshal.GetLastWin32Error() + "): " + commandLine);
             }
+            if (job != IntPtr.Zero)
+            {
+                // Suspended until it is in the job, so nothing it starts can be outside.
+                if (!NativeMethods.AssignProcessToJobObject(job, pi.hProcess))
+                {
+                    log.Write("agent job: could not add the agent (" + Marshal.GetLastWin32Error() + "); it runs without the memory limit");
+                }
+                NativeMethods.ResumeThread(pi.hThread);
+            }
             NativeMethods.CloseHandle(pi.hThread);
             return pi.hProcess;
         }

package/sandbox/scripts/install-shell-path.ps1

@@ -0,0 +1,73 @@
+#Requires -Version 5.1
+# Every new shell starts with the CURRENT machine + user PATH, whatever its parent had: tools added later in the boot
+# (python, rust, pwsh, agents ...) reach Windows Terminal tabs, Explorer launches and every other shell this way. The
+# start-up files call pathsync.exe (sandbox\csharp\PathSync.cs, built each boot):
+#   Windows PowerShell and PowerShell 7: the all-users profile.ps1
+#   cmd.exe: HKLM\Software\Microsoft\Command Processor AutoRun -> shell-path.cmd (does nothing for `cmd /c`)
+#   Git Bash: etc\profile.d\agent-sandbox-path.sh
+# -Helper is pathsync.exe. -PwshDir and -GitRoot are optional. -Root writes under that folder instead of the machine
+# (tests): no registry is touched then.
+param(
+    [Parameter(Mandatory = $true)][string]$Helper,
+    [string]$PwshDir = '',
+    [string]$GitRoot = '',
+    [string]$Root = ''
+)
+$ErrorActionPreference = 'Stop'
+
+$marker = 'agent-sandbox path sync'
+
+function Write-Ours([string]$file, [string]$text) {
+    if (Test-Path -LiteralPath $file) {
+        if (-not (Select-String -LiteralPath $file -SimpleMatch $marker -Quiet)) { return }
+    } else {
+        New-Item -ItemType Directory -Force -Path (Split-Path -Parent $file) | Out-Null
+    }
+    [IO.File]::WriteAllText($file, $text, (New-Object Text.UTF8Encoding($false)))
+}
+
+$profileText = "# $marker`r`n" +
+    "try { `$p = & '$Helper'; if (`$p) { `$env:Path = `$p } } catch { }`r`n"
+
+$windowsProfileDir = if ($Root) { Join-Path $Root 'windowspowershell' } else { Join-Path $env:windir 'System32\WindowsPowerShell\v1.0' }
+Write-Ours (Join-Path $windowsProfileDir 'profile.ps1') $profileText
+if ($PwshDir -and (Test-Path -LiteralPath $PwshDir)) { Write-Ours (Join-Path $PwshDir 'profile.ps1') $profileText }
+
+# cmd: interactive only. `cmd /c ...` (what programs and for /f start) has /c in its command line and leaves at once, which
+# also stops the loop of the for /f below.
+$cmdFile = Join-Path (Split-Path -Parent $Helper) 'shell-path.cmd'
+$cmdText = "@echo off`r`n" +
+    "rem $marker`r`n" +
+    "setlocal enabledelayedexpansion`r`n" +
+    "set `"_L=!cmdcmdline!`"`r`n" +
+    "if not `"!_L:/c=!`"==`"!_L!`" exit /b 0`r`n" +
+    "if not `"!_L:/r=!`"==`"!_L!`" exit /b 0`r`n" +
+    "set `"_P=`"`r`n" +
+    "for /f `"delims=`" %%P in ('`"$Helper`"') do set `"_P=%%P`"`r`n" +
+    "if not defined _P exit /b 0`r`n" +
+    "endlocal & set `"PATH=%_P%`"`r`n"
+if (-not (Test-Path -LiteralPath $cmdFile) -or (Select-String -LiteralPath $cmdFile -SimpleMatch $marker -Quiet)) {
+    [IO.File]::WriteAllText($cmdFile, $cmdText, [Text.Encoding]::ASCII)
+}
+if (-not $Root) {
+    $key = 'HKLM:\Software\Microsoft\Command Processor'
+    $current = (Get-ItemProperty -Path $key -Name AutoRun -ErrorAction SilentlyContinue).AutoRun
+    if (-not $current -or $current -like '*shell-path.cmd*') {
+        if (-not (Test-Path $key)) { New-Item -Path $key -Force | Out-Null }
+        Set-ItemProperty -Path $key -Name AutoRun -Value "if exist `"$cmdFile`" call `"$cmdFile`""
+    }
+}
+
+if ($GitRoot -and (Test-Path -LiteralPath (Join-Path $GitRoot 'etc\profile.d'))) {
+    $posixHelper = $Helper -replace '\\', '/'
+    $shText = "# $marker`n" +
+        "_w=`"`$('$posixHelper' 2>/dev/null)`"`n" +
+        "if [ -n `"`$_w`" ]; then`n" +
+        "  _n=`"`$(cygpath -u -p `"`$_w`" 2>/dev/null)`"`n" +
+        "  _o=`$IFS; IFS=:`n" +
+        "  for _d in `$_n; do case `":`$PATH:`" in *`":`$_d:`"*) ;; *) PATH=`"`$PATH:`$_d`" ;; esac; done`n" +
+        "  IFS=`$_o; export PATH`n" +
+        "fi`n" +
+        "unset _w _n _o _d`n"
+    Write-Ours (Join-Path $GitRoot 'etc\profile.d\agent-sandbox-path.sh') $shText
+}

package/sandbox/scripts/set-machine-environment.ps1

@@ -2,28 +2,61 @@
 # Machine-wide environment variables and PATH folders, so every new terminal tab and anything an agent starts sees the
 # same tools (guest/setup/environment.ts). -SettingsFile is JSON written by the runtime:
 #   vars: { name: value }   set machine-wide (with additive: only the ones not set yet)
-#   path: string | null      replaces the machine PATH
+#   path: string | null      replaces the machine PATH (already ordered and de-duplicated by the runtime)
 #   add: [folders]           added to PATH when missing: in front, or (additive) at the end
+#   create: [folders]        created first (folders a tool fills in later, such as pip's Scripts)
+# The PATH is always saved without duplicates (case, trailing slash) and Explorer / Windows Terminal are told.
 param([Parameter(Mandatory = $true)][string]$SettingsFile)
 $ErrorActionPreference = 'Stop'
 
 $settings = Get-Content -LiteralPath $SettingsFile -Raw -Encoding UTF8 | ConvertFrom-Json
 $additive = [bool]$settings.additive
 
+function Get-Key([string]$folder) {
+    $key = $folder.Trim().Trim('"')
+    if ($key.Length -gt 3) { $key = $key.TrimEnd('\', '/') }
+    return $key.ToLowerInvariant()
+}
+
+function Join-Folders([string[]]$folders) {
+    $seen = @{}
+    $kept = foreach ($folder in $folders) {
+        if ([string]::IsNullOrWhiteSpace($folder)) { continue }
+        $key = Get-Key $folder
+        if ($seen.ContainsKey($key)) { continue }
+        $seen[$key] = $true
+        $folder.Trim()
+    }
+    return ($kept -join ';')
+}
+
+foreach ($folder in @($settings.create)) {
+    if ($folder) { New-Item -ItemType Directory -Force -Path $folder | Out-Null }
+}
+
 foreach ($variable in $settings.vars.PSObject.Properties) {
     if ($additive -and [Environment]::GetEnvironmentVariable($variable.Name, 'Machine')) { continue }
     [Environment]::SetEnvironmentVariable($variable.Name, [string]$variable.Value, 'Machine')
 }
 
 if ($null -ne $settings.path) {
-    [Environment]::SetEnvironmentVariable('Path', [string]$settings.path, 'Machine')
+    [Environment]::SetEnvironmentVariable('Path', (Join-Folders ([string]$settings.path -split ';')), 'Machine')
 }
 
 if ($settings.add) {
     $current = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';'
-    $missing = @($settings.add | Where-Object { $current -notcontains $_ })
+    $known = @{}
+    foreach ($folder in $current) { $known[(Get-Key $folder)] = $true }
+    $missing = @($settings.add | Where-Object { -not $known.ContainsKey((Get-Key $_)) })
     if ($missing.Count) {
         $combined = if ($additive) { $current + $missing } else { $missing + $current }
-        [Environment]::SetEnvironmentVariable('Path', ($combined -join ';'), 'Machine')
+        [Environment]::SetEnvironmentVariable('Path', (Join-Folders $combined), 'Machine')
     }
 }
+
+try {
+    Add-Type -Path (Join-Path $PSScriptRoot '..\csharp\EnvBroadcast.cs')
+    [AgentSandbox.EnvBroadcast]::Notify()
+} catch {
+    # Programs started later read the registry anyway; only windows that are already open miss the news.
+}

package/schemas/config.schema.json

@@ -120,6 +120,14 @@
     "sandbox": {
       "type": "object",
       "properties": {
+        "engine": {
+          "type": "string",
+          "enum": [
+            "windows-sandbox",
+            "hcs"
+          ],
+          "description": "(alpha) What runs the sandbox. \"windows-sandbox\" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). \"hcs\" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it."
+        },
         "memoryMb": {
           "anyOf": [
             {
@@ -170,11 +178,33 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991,
-          "description": "RAM always left for this PC when memoryMb is \"auto\"."
+          "description": "Memory always left for this PC when memoryMb is \"auto\": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this."
+        },
+        "agentMemoryHeadroomMb": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "auto"
+            },
+            {
+              "type": "string",
+              "const": "none"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            }
+          ],
+          "description": "Memory kept out of the agents reach inside the sandbox, in MB: everything the agents start (their builds, tests, tools) together may use at most the sandbox memory minus this; a runaway parallel build then gets out-of-memory errors in its own session instead of freezing or crashing the whole sandbox. \"auto\" = the larger of 2048 MB and 10 % of the sandbox memory; \"none\" = no limit. Yours only: a project file cannot change it."
+        },
+        "pressureResponse": {
+          "type": "boolean",
+          "description": "When the sandbox (or this PC) runs low on memory, slow the heaviest build programs down (lower priority) and, if that is not enough, pause the biggest compiler for a few seconds at a time, so heavy parallel builds slow down instead of closing the sandbox. Never touches the agents themselves. Yours only: a project file cannot change it."
         },
         "vGpu": {
           "type": "boolean",
-          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."
+          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."
         },
         "networking": {
           "type": "boolean",
@@ -182,7 +212,7 @@
         },
         "clipboard": {
           "type": "boolean",
-          "description": "Shared clipboard between this PC and the sandbox."
+          "description": "Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."
         },
         "audioInput": {
           "type": "boolean",
@@ -227,7 +257,7 @@
         "root": {
           "type": "string",
           "minLength": 1,
-          "description": "Where everything is kept on this PC (tools, databases, logins, launches)."
+          "description": "Where everything is kept on this PC (tools, databases, logins, launches). The default is a private folder for you under %ProgramData%\\AgentSandbox\\users, which works for installs for one user and for everyone. sandbox storage move <folder> moves it."
         },
         "persistAgentState": {
           "type": "boolean",
@@ -242,6 +272,20 @@
           "type": "boolean",
           "description": "Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows' \"downloaded from the internet\" mark, so SmartScreen and PowerShell ask before they run on this PC."
         },
+        "contained": {
+          "type": "string",
+          "enum": [
+            "off",
+            "vhdx"
+          ],
+          "description": "(beta) Keep the sandbox tools, state and logs inside one disk image file (vhdx) instead of loose folders, so scanning programs on this PC see one file. Not yet tried on a real PC. Turn it on with sandbox storage contained on (it moves your files and asks first); Windows asks for permission to mount the image when a sandbox starts. \"off\" = loose folders, as always. Yours only: a project file (.sandbox-config.json) cannot set it."
+        },
+        "containedMaxGb": {
+          "type": "integer",
+          "minimum": 8,
+          "maximum": 4096,
+          "description": "(beta) Largest size, in GB, the disk image of storage.contained may grow to."
+        },
         "warnDataGb": {
           "type": "number",
           "minimum": 0,
@@ -313,6 +357,46 @@
       },
       "additionalProperties": false
     },
+    "vpn": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."
+        },
+        "provider": {
+          "type": "string",
+          "enum": [
+            "nordvpn",
+            "openvpn-file",
+            "wireguard-file"
+          ],
+          "description": "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company."
+        },
+        "protocol": {
+          "type": "string",
+          "enum": [
+            "udp",
+            "tcp"
+          ],
+          "description": "udp is faster; tcp gets through networks that block udp."
+        },
+        "country": {
+          "type": "string",
+          "pattern": "^([A-Za-z][A-Za-z .'-]{0,39})?$",
+          "description": "nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere."
+        },
+        "configFile": {
+          "type": "string",
+          "description": "openvpn-file / wireguard-file: the .ovpn or .conf file on this PC (an .ovpn has its certificates inside it). Files that run programs (script-security, up, down, plugin, PostUp ...) are refused. A WireGuard file holds your private key: it is read when a sandbox starts and handed over in a one-shot file. A project's file can never set this."
+        },
+        "killSwitch": {
+          "type": "boolean",
+          "description": "Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off."
+        }
+      },
+      "additionalProperties": false
+    },
     "provisioning": {
       "type": "object",
       "properties": {
@@ -1147,6 +1231,22 @@
       },
       "additionalProperties": false
     },
+    "web": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "(Beta) Allow the web UI: your sandbox sessions in a browser on this PC. Off by default, and nothing starts it by itself yet: sandbox web start works either way and runs it until sandbox web stop (or a restart of the PC)."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 65535,
+          "description": "Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken."
+        }
+      },
+      "additionalProperties": false
+    },
     "agentCommands": {
       "type": "object",
       "properties": {
@@ -1236,6 +1336,7 @@
               "sourcegit",
               "githubdesktop",
               "lazygit",
+              "jj",
               "7zip",
               "winmerge",
               "everything",
@@ -1288,7 +1389,9 @@
               "ffmpeg",
               "sqlite",
               "shellcheck",
-              "gitleaks"
+              "gitleaks",
+              "ast-grep",
+              "rust-analyzer"
             ]
           },
           "description": "Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."
@@ -1388,6 +1491,10 @@
           "type": "boolean",
           "description": "Refresh these settings from this PC on every launch."
         },
+        "sharePluginsAcrossAccounts": {
+          "type": "boolean",
+          "description": "When you switch Claude accounts, copy your Claude plugins (and which ones are enabled) into a data set that has none yet. Off by default: plugins are code that runs in your sessions."
+        },
         "syncHistory": {
           "type": "boolean",
           "description": "Bring conversation history in, and sync new history back (path-translated)."
@@ -1457,9 +1564,10 @@
               "type": "string"
             },
             "additionalProperties": {
-              "type": "string"
+              "type": "string",
+              "secret": true
             },
-            "description": "Environment variables for the agent."
+            "description": "Environment variables for the agent (API keys go here). Their values are shown as *** and are handed to the sandbox in a one-shot file, never kept in the launch folder. The agent can read its own environment."
           },
           "home": {
             "description": "Where its login lives inside the sandbox; leave out when the agent cannot be pointed at a folder (then its login is not kept between sandboxes).",
@@ -1501,6 +1609,27 @@
             },
             "additionalProperties": false
           },
+          "localState": {
+            "description": "Environment variable -> folder below the agent's own state folder (state\\<agent>) for SQLite databases. SQLite cannot run in a mapped folder, so the agent runs from a copy on the sandbox's disk (the variable points to it) that is copied from and back to that folder.",
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "additionalProperties": {
+              "type": "string",
+              "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
+            }
+          },
+          "bootReset": {
+            "description": "Files and folders below the agent's own state folder (state\\<agent>) that only work on the machine that wrote them (keys sealed with Windows DPAPI, local accounts it created). Every sandbox is a new machine, so they are deleted at each boot and the agent sets them up again.",
+            "maxItems": 32,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
+            }
+          },
           "resumeArguments": {
             "description": "Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.",
             "type": "array",

package/schemas/sandbox-config.schema.json

@@ -123,11 +123,11 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991,
-          "description": "RAM always left for this PC when memoryMb is \"auto\"."
+          "description": "Memory always left for this PC when memoryMb is \"auto\": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this."
         },
         "vGpu": {
           "type": "boolean",
-          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."
+          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."
         },
         "networking": {
           "type": "boolean",
@@ -135,7 +135,7 @@
         },
         "clipboard": {
           "type": "boolean",
-          "description": "Shared clipboard between this PC and the sandbox."
+          "description": "Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."
         },
         "audioInput": {
           "type": "boolean",
@@ -183,6 +183,16 @@
       },
       "additionalProperties": false
     },
+    "vpn": {
+      "type": "object",
+      "properties": {
+        "killSwitch": {
+          "type": "boolean",
+          "description": "Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off."
+        }
+      },
+      "additionalProperties": false
+    },
     "provisioning": {
       "type": "object",
       "properties": {
@@ -1040,6 +1050,7 @@
               "sourcegit",
               "githubdesktop",
               "lazygit",
+              "jj",
               "7zip",
               "winmerge",
               "everything",
@@ -1092,7 +1103,9 @@
               "ffmpeg",
               "sqlite",
               "shellcheck",
-              "gitleaks"
+              "gitleaks",
+              "ast-grep",
+              "rust-analyzer"
             ]
           },
           "description": "Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."

package/dist/cli/commands/repair/checks.d.ts

@@ -1,2 +0,0 @@
-import { type RepairCheck } from './types.js';
-export declare const CHECKS: RepairCheck[];