windows-development-sandbox 1.4.3 → 1.7.0

package/sandbox/csharp/VtInput.cs

@@ -0,0 +1,63 @@
+// Turns on ENABLE_VIRTUAL_TERMINAL_INPUT on another process's console. Loaded by scripts\enable-vt-input.ps1 (Add-Type). C# 5.
+using System;
+using System.Runtime.InteropServices;
+
+public static class SbxVtInput
+{
+    private const uint GenericReadWrite = 0xC0000000;
+    private const uint ShareReadWrite = 3;
+    private const uint OpenExisting = 3;
+    private const uint EnableVirtualTerminalInput = 0x200;
+    private static readonly IntPtr InvalidHandle = new IntPtr(-1);
+
+    private static class NativeMethods
+    {
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool FreeConsole();
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool AttachConsole(uint pid);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        public static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool GetConsoleMode(IntPtr handle, out uint mode);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool SetConsoleMode(IntPtr handle, uint mode);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        public static extern bool CloseHandle(IntPtr handle);
+    }
+
+    /// <summary>
+    /// Attaches to the console of process pid and adds virtual-terminal input to its input mode. 0 = done, 2 = could
+    /// not attach, 3 = no console input, 4 = the mode could not be read or set.
+    /// </summary>
+    public static int On(uint pid)
+    {
+        NativeMethods.FreeConsole();
+        if (!NativeMethods.AttachConsole(pid))
+        {
+            return 2;
+        }
+        IntPtr input = NativeMethods.CreateFileW("CONIN$", GenericReadWrite, ShareReadWrite, IntPtr.Zero, OpenExisting, 0, IntPtr.Zero);
+        if (input == InvalidHandle)
+        {
+            return 3;
+        }
+        bool ok;
+        try
+        {
+            uint mode;
+            ok = NativeMethods.GetConsoleMode(input, out mode) && NativeMethods.SetConsoleMode(input, mode | EnableVirtualTerminalInput);
+        }
+        finally
+        {
+            NativeMethods.CloseHandle(input);
+            NativeMethods.FreeConsole();
+        }
+        return ok ? 0 : 4;
+    }
+}

package/sandbox/scripts/enable-vt-input.ps1

@@ -0,0 +1,9 @@
+#Requires -Version 5.1
+# Lets the terminal's own input (mouse reports, focus, keys) reach process -ProcessId, which reads its console in raw
+# mode (shared/pty/console-input.ts). Started hidden in a console of its own, it switches to that process's console.
+# Exit code: 0 = done, 2-4 = see SbxVtInput.On in csharp\VtInput.cs.
+param([Parameter(Mandatory = $true)][uint32]$ProcessId)
+$ErrorActionPreference = 'Stop'
+
+Add-Type -Path (Join-Path $PSScriptRoot '..\csharp\VtInput.cs')
+exit [SbxVtInput]::On($ProcessId)

package/sandbox/scripts/expand-archive.ps1

@@ -0,0 +1,9 @@
+#Requires -Version 5.1
+# Extracts a .zip when Windows' tar.exe could not (shared/download/archive.ts, on this PC and in the sandbox).
+param(
+    [Parameter(Mandatory = $true)][string]$Archive,
+    [Parameter(Mandatory = $true)][string]$Destination
+)
+$ErrorActionPreference = 'Stop'
+
+Expand-Archive -LiteralPath $Archive -DestinationPath $Destination -Force

package/sandbox/scripts/get-gpu-names.ps1

@@ -0,0 +1,5 @@
+#Requires -Version 5.1
+# Prints the name of every display adapter, one per line (guest/toolchains/native/mesa.ts: is there a real GPU?).
+$ErrorActionPreference = 'Stop'
+
+(Get-CimInstance Win32_VideoController).Name

package/sandbox/scripts/get-signer.ps1

@@ -0,0 +1,8 @@
+#Requires -Version 5.1
+# Prints the subject of a file's Authenticode signature when it is valid; prints nothing when the file is unsigned or
+# was tampered with (guest/toolchains/native/vcruntime.ts checks Microsoft's signature before running an installer).
+param([Parameter(Mandatory = $true)][string]$Path)
+$ErrorActionPreference = 'Stop'
+
+$signature = Get-AuthenticodeSignature -LiteralPath $Path
+if ($signature.Status -eq 'Valid') { $signature.SignerCertificate.Subject }

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/link-profile-dirs.ps1

@@ -0,0 +1,35 @@
+#Requires -Version 5.1
+# Agents that keep their login in the user profile (guest/agents/profile-links.ts): each profile folder becomes a
+# junction to a folder in the persistent state. -PairsFile is a JSON array of {link, target}.
+# A real folder already at the link is moved into the target first (files already in the target win).
+param([Parameter(Mandatory = $true)][string]$PairsFile)
+$ErrorActionPreference = 'Stop'
+
+function Test-Junction([string]$Path) {
+    $item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
+    return ($null -ne $item) -and (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)
+}
+
+# Not wrapped in @(): Windows PowerShell 5.1 would make one element of the whole array.
+$pairs = ConvertFrom-Json -InputObject (Get-Content -LiteralPath $PairsFile -Raw)
+foreach ($pair in $pairs) {
+    $link = [string]$pair.link
+    $target = [string]$pair.target
+    New-Item -ItemType Directory -Force -Path $target | Out-Null
+    if (Test-Path -LiteralPath $link) {
+        if (Test-Junction $link) {
+            $current = (Get-Item -LiteralPath $link -Force).Target
+            if ($current -and ([string]$current).TrimEnd('\') -ieq $target.TrimEnd('\')) { continue }
+            (Get-Item -LiteralPath $link -Force).Delete()
+        }
+        else {
+            Get-ChildItem -LiteralPath $link -Force | ForEach-Object {
+                $dest = Join-Path $target $_.Name
+                if (-not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $_.FullName -Destination $dest }
+            }
+            Remove-Item -LiteralPath $link -Recurse -Force
+        }
+    }
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $link) | Out-Null
+    New-Item -ItemType Junction -Path $link -Value $target | Out-Null
+}

package/sandbox/scripts/new-shortcuts.ps1

@@ -0,0 +1,15 @@
+#Requires -Version 5.1
+# Creates .lnk shortcuts (desktop, Start menu) in one call (guest/apps, the VS Code step). -ListFile is JSON written by
+# the runtime: [{ link, target, workingDirectory?, arguments? }].
+param([Parameter(Mandatory = $true)][string]$ListFile)
+$ErrorActionPreference = 'Stop'
+
+$shell = New-Object -ComObject WScript.Shell
+foreach ($entry in @(Get-Content -LiteralPath $ListFile -Raw -Encoding UTF8 | ConvertFrom-Json)) {
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $entry.link) | Out-Null
+    $shortcut = $shell.CreateShortcut($entry.link)
+    $shortcut.TargetPath = $entry.target
+    if ($entry.workingDirectory) { $shortcut.WorkingDirectory = $entry.workingDirectory }
+    if ($entry.arguments) { $shortcut.Arguments = $entry.arguments }
+    $shortcut.Save()
+}

package/sandbox/scripts/set-desktop.ps1

@@ -0,0 +1,16 @@
+#Requires -Version 5.1
+# Applies the desktop look imported from the PC (guest/setup/desktop.ts): the wallpaper copied in, then Explorer
+# restarts (it starts again by itself) so taskbar and theme changes show.
+param([string]$Wallpaper = '')
+$ErrorActionPreference = 'Stop'
+
+if ($Wallpaper) {
+    Set-ItemProperty -Path 'HKCU:\Control Panel\Desktop' -Name WallPaper -Value $Wallpaper
+    Add-Type -Path (Join-Path $PSScriptRoot '..\csharp\Desktop.cs')
+    try {
+        [AgentSandbox.Desk]::SetWallpaper($Wallpaper)
+    } catch {
+        # The registry value above still applies at the next sign-in.
+    }
+}
+Stop-Process -Name explorer -Force -ErrorAction SilentlyContinue

package/sandbox/scripts/set-dns-servers.ps1

@@ -0,0 +1,8 @@
+#Requires -Version 5.1
+# network.dns: these DNS servers on every connected adapter (guest/network/firewall.ts). -Servers is a comma-separated
+# list of IPv4 addresses, checked by the runtime.
+param([Parameter(Mandatory = $true)][string]$Servers)
+$ErrorActionPreference = 'Stop'
+
+$addresses = @($Servers -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+Get-NetAdapter | Where-Object Status -eq 'Up' | Set-DnsClientServerAddress -ServerAddresses $addresses

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

@@ -0,0 +1,62 @@
+#Requires -Version 5.1
+# 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 (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', (Join-Folders ([string]$settings.path -split ';')), 'Machine')
+}
+
+if ($settings.add) {
+    $current = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';'
+    $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', (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

@@ -211,13 +211,23 @@
       },
       "additionalProperties": false
     },
+    "sharing": {
+      "type": "object",
+      "properties": {
+        "otherUsers": {
+          "type": "boolean",
+          "description": "Let other Windows users of this PC use a sandbox you start: list its sessions, attach, run commands and stop it. They use the agent logins inside it, and history goes to your account."
+        }
+      },
+      "additionalProperties": false
+    },
     "storage": {
       "type": "object",
       "properties": {
         "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",
@@ -303,6 +313,45 @@
       },
       "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"
+          ],
+          "description": "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile)."
+        },
+        "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: the .ovpn file on this PC (its certificates inside it). Files that run programs (script-security, up, down, plugin ...) are refused. 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": {
@@ -841,8 +890,16 @@
           "type": "object",
           "properties": {
             "enabled": {
-              "type": "boolean",
-              "description": "Bun runtime (claude-mem needs it)."
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "string",
+                  "const": "auto"
+                }
+              ],
+              "description": "Bun (JavaScript runtime and package manager; claude-mem needs it). true, false, or \"auto\" = only when the project has bun.lock, bun.lockb or bunfig.toml."
             }
           },
           "additionalProperties": false
@@ -851,8 +908,16 @@
           "type": "object",
           "properties": {
             "enabled": {
-              "type": "boolean",
-              "description": "uv, the Python package manager (claude-mem needs it)."
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "string",
+                  "const": "auto"
+                }
+              ],
+              "description": "uv (fast Python package and tool manager; claude-mem needs it for its search index). true, false, or \"auto\" = only when the project has uv.lock, a [tool.uv] pyproject.toml, toolchains.python.tools, or an agent installed with uv."
             }
           },
           "additionalProperties": false
@@ -885,8 +950,16 @@
           "type": "object",
           "properties": {
             "enabled": {
-              "type": "boolean",
-              "description": "Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "string",
+                  "const": "auto"
+                }
+              ],
+              "description": "Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist. true, false, or \"auto\" = when VS Code is installed on this PC."
             },
             "setup": {
               "type": "boolean",
@@ -1113,6 +1186,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": {
@@ -1202,6 +1291,7 @@
               "sourcegit",
               "githubdesktop",
               "lazygit",
+              "jj",
               "7zip",
               "winmerge",
               "everything",
@@ -1254,7 +1344,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."
@@ -1354,6 +1446,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)."
@@ -1423,9 +1519,62 @@
               "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).",
+            "type": "object",
+            "properties": {
+              "env": {
+                "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._ -]+)*$"
+                },
+                "description": "Environment variable -> folder (below the sandbox state folder) the agent keeps its data in."
+              },
+              "profileDirs": {
+                "description": "Folders below the sandbox's user profile (e.g. .qwen, .config/opencode) the agent keeps its data in: each becomes a link to state\\<agent>\\profile\\<folder>, so it survives between sandboxes.",
+                "maxItems": 8,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
+                }
+              },
+              "loginFiles": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
+                },
+                "description": "Files that make up the login, relative to the agent's own state folder (state\\<agent>)."
+              },
+              "hostDir": {
+                "description": "The agent's own folder on this PC (e.g. ~/.codex): loginFiles are read from it to save this PC's login.",
+                "type": "string"
+              }
+            },
+            "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._ -]+)*$"
+            }
           },
           "resumeArguments": {
             "description": "Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.",
@@ -1433,6 +1582,13 @@
             "items": {
               "type": "string"
             }
+          },
+          "resumeOneArguments": {
+            "description": "Arguments that reopen one conversation, with {id} where its id goes (claude: --resume {id}). Used instead of resumeArguments when the conversation of a session is known.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "additionalProperties": false
@@ -1503,6 +1659,27 @@
       },
       "additionalProperties": false,
       "description": "Several projects in one sandbox: folders of projects mapped at every start, and adding folders while it runs."
+    },
+    "resume": {
+      "type": "object",
+      "properties": {
+        "sessions": {
+          "type": "string",
+          "enum": [
+            "ask",
+            "always",
+            "afterCrash",
+            "never"
+          ],
+          "description": "When a sandbox starts after one that had agent sessions: \"ask\" lists them and asks whether to reopen them (without a terminal it prints the command sandbox resume), \"always\" reopens them, \"afterCrash\" reopens them only when the last sandbox ended unexpectedly, \"never\" leaves it to sandbox resume. Terminal tabs you opened yourself in the sandbox are never reopened."
+        },
+        "restartAfterCrash": {
+          "type": "boolean",
+          "description": "When the sandbox ends because Windows Sandbox crashed or ran out of memory, start it again by itself and reopen its sessions (at most 3 times in 6 hours)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Reopening the sessions of the last sandbox when a new one starts."
     }
   },
   "additionalProperties": false