windows-development-sandbox 1.4.0 → 1.4.3

package/dist/core/schema/sandbox.d.ts

@@ -1,12 +1,12 @@
 import { z } from 'zod';
-export declare const GuestWorkspace: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"mirror">, z.ZodString]>;
-export declare const Mapping: z.ZodObject<{
+export declare const GuestWorkspaceSchema: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"mirror">, z.ZodString]>;
+export declare const MappingSchema: z.ZodObject<{
     host: z.ZodString;
-    guest: z.ZodString;
+    guest: z.ZodOptional<z.ZodString>;
     readOnly: z.ZodBoolean;
     optional: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
-export declare const Sandbox: z.ZodObject<{
+export declare const SandboxSchema: z.ZodObject<{
     memoryMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
     maxMemoryMb: z.ZodNumber;
     maxMemoryPercent: z.ZodNumber;
@@ -23,7 +23,7 @@ export declare const Sandbox: z.ZodObject<{
     headless: z.ZodBoolean;
     keepAwake: z.ZodBoolean;
 }, z.core.$strict>;
-export declare const Network: z.ZodObject<{
+export declare const NetworkSchema: z.ZodObject<{
     blockPrivateRanges: z.ZodBoolean;
     allowOnly: z.ZodArray<z.ZodString>;
     blockHosts: z.ZodArray<z.ZodString>;
@@ -34,27 +34,27 @@ export declare const Network: z.ZodObject<{
     dns: z.ZodArray<z.ZodString>;
     proxy: z.ZodString;
 }, z.core.$strict>;
-export declare const Audit: z.ZodObject<{
+export declare const AuditSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     days: z.ZodNumber;
     maxMb: z.ZodNumber;
     processes: z.ZodBoolean;
     files: z.ZodBoolean;
 }, z.core.$strict>;
-export declare const WorkspaceFilter: z.ZodObject<{
+export declare const WorkspaceFilterSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     exclude: z.ZodArray<z.ZodString>;
     include: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
-export declare const Git: z.ZodObject<{
+export declare const GitSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     access: z.ZodEnum<{
         readonly: "readonly";
-        full: "full";
         none: "none";
+        full: "full";
     }>;
 }, z.core.$strict>;
-export declare const Provisioning: z.ZodObject<{
+export declare const ProvisioningSchema: z.ZodObject<{
     copyFromHost: z.ZodBoolean;
     fallbackToInstall: z.ZodBoolean;
     refresh: z.ZodBoolean;
@@ -62,8 +62,8 @@ export declare const Provisioning: z.ZodObject<{
         enabled: z.ZodBoolean;
         access: z.ZodEnum<{
             readonly: "readonly";
-            full: "full";
             none: "none";
+            full: "full";
         }>;
     }, z.core.$strict>;
     terminal: z.ZodObject<{
@@ -73,6 +73,6 @@ export declare const Provisioning: z.ZodObject<{
         enabled: z.ZodBoolean;
     }, z.core.$strict>;
 }, z.core.$strict>;
-export declare const Downloads: z.ZodObject<{
+export declare const DownloadsSchema: z.ZodObject<{
     requireChecksum: z.ZodBoolean;
 }, z.core.$strict>;

package/dist/core/schema/sandbox.js

@@ -1,19 +1,40 @@
 // The sandbox machine, folders mapped into it, and what is provisioned (Git, terminal).
 import { z } from 'zod';
-import { GitAccess, GuestPath, toggle } from './common.js';
-export const GuestWorkspace = z.union([z.literal('auto'), z.literal('mirror'), GuestPath]).describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
-export const Mapping = z.strictObject({
+import { GitAccessSchema, GuestPathSchema, toggle } from './common.js';
+export const GuestWorkspaceSchema = z
+    .union([z.literal('auto'), z.literal('mirror'), GuestPathSchema])
+    .describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
+export const MappingSchema = z.strictObject({
     host: z.string().min(1).describe('Folder on this PC (relative paths are relative to the config file).'),
-    guest: GuestPath.describe('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.'),
+    guest: z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .describe('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.'),
     readOnly: z.boolean().describe('true = the agent can only read it.'),
     optional: z.boolean().optional().describe('true = skip it quietly when the host folder does not exist.'),
 });
-export const Sandbox = z.strictObject({
-    memoryMb: z.union([z.literal('auto'), z.number().int().min(2048)]).describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
+export const SandboxSchema = z.strictObject({
+    memoryMb: z
+        .union([z.literal('auto'), z.number().int().min(2048)])
+        .describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
     maxMemoryMb: z.number().int().positive().describe('Upper limit for memoryMb "auto".'),
-    maxMemoryPercent: z.number().int().min(10).max(100).describe('memoryMb "auto" never takes more than this share of this PC\'s total RAM (percent).'),
-    cpuLimit: z.union([z.literal('none'), z.number().int().min(5).max(100)]).describe('Most of this PC\'s CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; "none" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal).'),
-    pageFileMb: z.number().int().min(0).max(262144).describe('Size of the sandbox\'s paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows\' own.'),
+    maxMemoryPercent: z
+        .number()
+        .int()
+        .min(10)
+        .max(100)
+        .describe('memoryMb "auto" never takes more than this share of this PC\'s total RAM (percent).'),
+    cpuLimit: z
+        .union([z.literal('none'), z.number().int().min(5).max(100)])
+        .describe('Most of this PC\'s CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; "none" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal).'),
+    pageFileMb: z
+        .number()
+        .int()
+        .min(0)
+        .max(262144)
+        .describe('Size of the sandbox\'s paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows\' own.'),
     reserveHostMb: z.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
     vGpu: z.boolean().describe('Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface.'),
     networking: z.boolean().describe('Internet access. false is the only hard network isolation Windows Sandbox offers.'),
@@ -22,43 +43,86 @@ export const Sandbox = z.strictObject({
     videoInput: z.boolean().describe('Camera access.'),
     printerRedirection: z.boolean().describe('Printers from this PC.'),
     protectedClient: z.boolean().describe('Run the sandbox window in Protected Client mode (recommended).'),
-    headless: z.boolean().describe('Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.'),
-    keepAwake: z.boolean().describe('Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it).'),
+    headless: z
+        .boolean()
+        .describe('Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.'),
+    keepAwake: z
+        .boolean()
+        .describe('Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it).'),
 });
-const Port = z.number().int().min(1).max(65535);
-const HostEntry = z.string().max(253).regex(/^(@developer|(\*\.)?([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+)$/, 'a host name like example.com, *.example.com, or @developer');
-export const Network = z.strictObject({
-    blockPrivateRanges: z.boolean().describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.'),
-    allowOnly: z.array(HostEntry).describe('Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit.'),
-    blockHosts: z.array(z.string().max(253).regex(/^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/, 'a host name like telemetry.example.com')).describe('Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox\'s hosts file sends them nowhere).'),
-    forwardPorts: z.array(z.strictObject({
-        pc: Port.describe('The port on this PC (localhost only).'),
-        sandbox: Port.describe('The port inside the sandbox (a server there may listen on localhost only).'),
-    })).describe('Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them.'),
-    dns: z.array(z.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/, 'an IPv4 address like 1.1.1.1')).describe('DNS servers for the sandbox instead of your network\'s, e.g. 1.1.1.1 and 9.9.9.9.'),
-    proxy: z.string().regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port').describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
+const PortSchema = z.number().int().min(1).max(65535);
+const HostEntrySchema = z
+    .string()
+    .max(253)
+    .regex(/^(@developer|(\*\.)?([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+)$/, 'a host name like example.com, *.example.com, or @developer');
+export const NetworkSchema = z.strictObject({
+    blockPrivateRanges: z
+        .boolean()
+        .describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.'),
+    allowOnly: z
+        .array(HostEntrySchema)
+        .describe('Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit.'),
+    blockHosts: z
+        .array(z
+        .string()
+        .max(253)
+        .regex(/^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/, 'a host name like telemetry.example.com'))
+        .describe("Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox's hosts file sends them nowhere)."),
+    forwardPorts: z
+        .array(z.strictObject({
+        pc: PortSchema.describe('The port on this PC (localhost only).'),
+        sandbox: PortSchema.describe('The port inside the sandbox (a server there may listen on localhost only).'),
+    }))
+        .describe('Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them.'),
+    dns: z
+        .array(z.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/, 'an IPv4 address like 1.1.1.1'))
+        .describe("DNS servers for the sandbox instead of your network's, e.g. 1.1.1.1 and 9.9.9.9."),
+    proxy: z
+        .string()
+        .regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port')
+        .describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
 });
-export const Audit = z.strictObject({
-    enabled: z.boolean().describe('Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit.'),
+export const AuditSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe('Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit.'),
     days: z.number().int().min(1).max(365).describe('Days the audit log is kept.'),
-    maxMb: z.number().int().min(5).max(5000).describe('Most space the audit log may take, in MB (older days go first). Days before today are compressed.'),
-    processes: z.boolean().describe('Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed).'),
+    maxMb: z
+        .number()
+        .int()
+        .min(5)
+        .max(5000)
+        .describe('Most space the audit log may take, in MB (older days go first). Days before today are compressed.'),
+    processes: z
+        .boolean()
+        .describe('Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed).'),
     files: z.boolean().describe('Record the files changed in the project while the sandbox runs.'),
 });
-export const WorkspaceFilter = z.strictObject({
-    enabled: z.boolean().describe('Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped.'),
-    exclude: z.array(z.string().max(500)).describe('Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/.'),
-    include: z.array(z.string().max(500)).describe('Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/.'),
+export const WorkspaceFilterSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe('Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped.'),
+    exclude: z
+        .array(z.string().max(500))
+        .describe('Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/.'),
+    include: z
+        .array(z.string().max(500))
+        .describe('Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/.'),
 });
-export const Git = z.strictObject({ enabled: z.boolean().describe('Provide Git for Windows (and Git Bash, which Claude Code needs).'), access: GitAccess });
-export const Provisioning = z.strictObject({
+export const GitSchema = z.strictObject({
+    enabled: z.boolean().describe('Provide Git for Windows (and Git Bash, which Claude Code needs).'),
+    access: GitAccessSchema,
+});
+export const ProvisioningSchema = z.strictObject({
     copyFromHost: z.boolean().describe('Copy Node, Git, nvm and the agent from this PC when they are installed here.'),
     fallbackToInstall: z.boolean().describe('Download anything that cannot be copied from this PC.'),
     refresh: z.boolean().describe('Re-copy / re-download everything on the next launch.'),
-    git: Git,
+    git: GitSchema,
     terminal: toggle('Windows Terminal as the sandbox window (downloaded once).'),
-    conpty: toggle('Agent sessions use Microsoft\'s newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows.'),
+    conpty: toggle("Agent sessions use Microsoft's newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows."),
 });
-export const Downloads = z.strictObject({
-    requireChecksum: z.boolean().describe('Refuse any toolchain, database or tool download that has no published checksum (SHA-256/SHA-512) to verify it against. false = allow those, as before. Downloads that do have a published checksum are always verified. A project\'s .sandbox-config.json can only turn this on.'),
+export const DownloadsSchema = z.strictObject({
+    requireChecksum: z
+        .boolean()
+        .describe("Refuse any toolchain, database or tool download that has no published checksum (SHA-256/SHA-512) to verify it against. false = allow those, as before. Downloads that do have a published checksum are always verified. A project's .sandbox-config.json can only turn this on."),
 });

package/dist/core/schema/toolchains.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare const Toolchains: z.ZodObject<{
+export declare const ToolchainsSchema: z.ZodObject<{
     node: z.ZodObject<{
         version: z.ZodString;
         extraVersions: z.ZodArray<z.ZodString>;
@@ -22,6 +22,11 @@ export declare const Toolchains: z.ZodObject<{
         targets: z.ZodArray<z.ZodString>;
         crates: z.ZodArray<z.ZodString>;
         targetDir: z.ZodString;
+        linker: z.ZodEnum<{
+            lld: "lld";
+            gnu: "gnu";
+        }>;
+        linkSlots: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
     }, z.core.$strict>;
     msvc: z.ZodObject<{
         enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;

package/dist/core/schema/toolchains.js

@@ -1,58 +1,90 @@
 // Languages and tools installed inside the sandbox.
 import { z } from 'zod';
-import { enabled, Enabled, Packages, Strings, toggle } from './common.js';
-export const Toolchains = z.strictObject({
+import { enabled, EnabledSchema, Packages, StringsSchema, toggle } from './common.js';
+export const ToolchainsSchema = z.strictObject({
     node: z.strictObject({
-        version: z.string().min(1).describe('Default Node version for nvm. "host" = the Node on this PC. A project\'s .nvmrc / .node-version wins.'),
-        extraVersions: Strings.describe('More Node versions to install (switch with nvm use). On top of the up to 3 versions copied from this PC\'s nvm, not counted towards that limit.'),
-        corepack: z.boolean().describe('pnpm and yarn through corepack (a project\'s "packageManager" in package.json picks the version).'),
-        volta: Enabled.describe('Volta: true, false, or "auto" = when the project\'s package.json has "volta" pins or this PC uses Volta. With pins, Volta\'s node/npm/yarn/pnpm come first on PATH.'),
+        version: z
+            .string()
+            .min(1)
+            .describe('Default Node version for nvm. "host" = the Node on this PC. A project\'s .nvmrc / .node-version wins.'),
+        extraVersions: StringsSchema.describe("More Node versions to install (switch with nvm use). On top of the up to 3 versions copied from this PC's nvm, not counted towards that limit."),
+        corepack: z
+            .boolean()
+            .describe('pnpm and yarn through corepack (a project\'s "packageManager" in package.json picks the version).'),
+        volta: EnabledSchema.describe('Volta: true, false, or "auto" = when the project\'s package.json has "volta" pins or this PC uses Volta. With pins, Volta\'s node/npm/yarn/pnpm come first on PATH.'),
         globalPackages: Packages('npm packages installed globally into the default Node version', '["typescript", "npm-check-updates"]'),
     }),
     python: z.strictObject({
         enabled: enabled('Python 3 (CPython with pip).', 'pyproject.toml, requirements.txt, setup.py, Pipfile or .python-version'),
-        version: z.string().min(1).describe('Python 3 version prefix, e.g. "3" or "3.12". A project\'s .python-version wins.'),
+        version: z
+            .string()
+            .min(1)
+            .describe('Python 3 version prefix, e.g. "3" or "3.12". A project\'s .python-version wins.'),
         python2: z.boolean().describe('Also install Python 2.7 as python2 / pip2.'),
-        pyenv: Enabled.describe('pyenv-win (pyenv install / local / global): true, false, or "auto" = when this PC uses pyenv. .python-version is honoured either way, and `uv python install` always works.'),
+        pyenv: EnabledSchema.describe('pyenv-win (pyenv install / local / global): true, false, or "auto" = when this PC uses pyenv. .python-version is honoured either way, and `uv python install` always works.'),
         tools: Packages('Python command-line tools installed with `uv tool install` (needs uv)', '["poetry", "ruff", "pre-commit"]'),
     }),
     rust: z.strictObject({
         enabled: enabled('Rust via rustup (cargo, rustc).', 'Cargo.toml or rust-toolchain(.toml)'),
         toolchain: z.string().min(1).describe('Default toolchain, e.g. "stable". rust-toolchain.toml in a project wins.'),
-        host: z.string().min(1).describe('Host triple, or "auto": x86_64-pc-windows-msvc when the MSVC toolchain is on (like most PCs), else x86_64-pc-windows-gnu (MinGW is its linker).'),
+        host: z
+            .string()
+            .min(1)
+            .describe('Host triple, or "auto": x86_64-pc-windows-msvc when the MSVC toolchain is on (like most PCs), else x86_64-pc-windows-gnu (MinGW is its linker).'),
         components: Packages('Extra rustup components', '["rust-src", "llvm-tools"]'),
         targets: Packages('Extra rustup targets', '["wasm32-unknown-unknown"]'),
         crates: Packages('Binaries for cargo: prebuilt via cargo-binstall when the crate publishes a Windows build, else compiled with `cargo install --locked` (slow the first time)', '["sccache", "cargo-nextest", "cargo-deny"]'),
-        targetDir: z.string().min(1).describe('"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.'),
+        targetDir: z
+            .string()
+            .min(1)
+            .describe('"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: z
+            .enum(['lld', 'gnu'])
+            .describe('GNU host: "lld" links with Rust\'s own lld through MinGW\'s gcc (much less memory than GNU ld), "gnu" with GNU ld.'),
+        linkSlots: z
+            .union([z.literal('auto'), z.number().int().min(1).max(32)])
+            .describe('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.'),
     }),
     msvc: z.strictObject({
-        enabled: enabled('MSVC (cl, link) and the Windows SDK, portable from Microsoft\'s Visual Studio manifest (~1-2 GB once), with vcvars64.bat and vswhere.', 'a .vcxproj, CMakePresets.json, a script calling vcvars/vswhere, or a Rust project when this PC builds Rust with MSVC'),
-        acceptLicense: z.boolean().describe('Required to install MSVC: you accept the Visual Studio licence terms (https://visualstudio.microsoft.com/license-terms/), which need a Visual Studio licence.'),
+        enabled: enabled("MSVC (cl, link) and the Windows SDK, portable from Microsoft's Visual Studio manifest (~1-2 GB once), with vcvars64.bat and vswhere.", 'a .vcxproj, CMakePresets.json, a script calling vcvars/vswhere, or a Rust project when this PC builds Rust with MSVC'),
+        acceptLicense: z
+            .boolean()
+            .describe('Required to install MSVC: you accept the Visual Studio licence terms (https://visualstudio.microsoft.com/license-terms/), which need a Visual Studio licence.'),
         msvcVersion: z.string().min(1).describe('"latest" or an MSVC tools version prefix, e.g. "14.44".'),
         sdkVersion: z.string().min(1).describe('"latest" or a Windows SDK build, e.g. "26100" or "10.0.22621".'),
     }),
     cpp: z.strictObject({
-        enabled: enabled('MinGW-w64 GCC with CMake, Ninja, premake5 and mingw32-make (also Rust\'s linker).', 'CMakeLists.txt, Makefile, meson.build, premake5.lua or Cargo.toml'),
-        flexBison: z.boolean().describe('win_flex / win_bison, the parser generators many C/C++ projects (game engines among them) need; CMake finds them.'),
+        enabled: enabled("MinGW-w64 GCC with CMake, Ninja, premake5 and mingw32-make (also Rust's linker).", 'CMakeLists.txt, Makefile, meson.build, premake5.lua or Cargo.toml'),
+        flexBison: z
+            .boolean()
+            .describe('win_flex / win_bison, the parser generators many C/C++ projects (game engines among them) need; CMake finds them.'),
     }),
     dotnet: z.strictObject({
         enabled: enabled('.NET SDK (C#, F#).', 'a .sln, .slnx, .csproj, .fsproj or global.json'),
-        channels: Strings.describe('SDK channels, e.g. ["LTS", "8.0"]. A project\'s global.json is installed too.'),
+        channels: StringsSchema.describe('SDK channels, e.g. ["LTS", "8.0"]. A project\'s global.json is installed too.'),
         tools: Packages('Global .NET tools (`dotnet tool install -g`)', '["dotnet-ef", "csharpier"]'),
         workloads: Packages('SDK workloads (`dotnet workload install`)', '["aspire", "wasm-tools"]'),
-        frameworkTargets: Strings.describe('.NET Framework reference assemblies (targeting packs) from NuGet, so net4x and old-style .csproj projects build without Visual Studio, e.g. ["net48", "net472", "net462"]. The 4.8 runtime itself ships with Windows.'),
-        netfx35: z.boolean().describe('.NET Framework 3.5 runtime (a Windows feature, enabled from Windows Update on every boot; a few minutes).'),
+        frameworkTargets: StringsSchema.describe('.NET Framework reference assemblies (targeting packs) from NuGet, so net4x and old-style .csproj projects build without Visual Studio, e.g. ["net48", "net472", "net462"]. The 4.8 runtime itself ships with Windows.'),
+        netfx35: z
+            .boolean()
+            .describe('.NET Framework 3.5 runtime (a Windows feature, enabled from Windows Update on every boot; a few minutes).'),
     }),
     go: z.strictObject({
         enabled: enabled('Go.', 'go.mod or go.work'),
-        version: z.string().min(1).describe('"stable" or a version prefix such as "1.23". A go.mod asking for newer fetches it itself (GOTOOLCHAIN=auto).'),
+        version: z
+            .string()
+            .min(1)
+            .describe('"stable" or a version prefix such as "1.23". A go.mod asking for newer fetches it itself (GOTOOLCHAIN=auto).'),
         tools: Packages('Go tools (`go install <path>@<version>`)', '["golang.org/x/tools/gopls@latest"]'),
     }),
     java: z.strictObject({
         enabled: enabled('Java: Eclipse Temurin JDK.', 'pom.xml, build.gradle(.kts), settings.gradle(.kts), mvnw, gradlew or .java-version'),
-        version: z.string().min(1).describe('"lts" (newest LTS) or a major version such as "21". A project\'s .java-version or .sdkmanrc wins.'),
-        maven: z.boolean().describe('Apache Maven (mvn). A project\'s mvnw works either way.'),
-        gradle: z.boolean().describe('Gradle (gradle). A project\'s gradlew works either way.'),
+        version: z
+            .string()
+            .min(1)
+            .describe('"lts" (newest LTS) or a major version such as "21". A project\'s .java-version or .sdkmanrc wins.'),
+        maven: z.boolean().describe("Apache Maven (mvn). A project's mvnw works either way."),
+        gradle: z.boolean().describe("Gradle (gradle). A project's gradlew works either way."),
     }),
     ruby: z.strictObject({
         enabled: enabled('Ruby (RubyInstaller, with gem and bundler). Gems with C extensions need MSYS2, which is not included.', 'Gemfile, a .gemspec or .ruby-version'),
@@ -65,24 +97,42 @@ export const Toolchains = z.strictObject({
         composer: z.boolean().describe('Composer.'),
     }),
     deno: z.strictObject({ enabled: enabled('Deno.', 'deno.json, deno.jsonc or deno.lock') }),
-    pwsh: z.strictObject({ enabled: Enabled.describe('PowerShell 7 (pwsh), portable (~110 MB once); `powershell` stays Windows PowerShell 5.1. true, false, or "auto" = when a .ps1 at the root or one folder down has #Requires -Version 7 / -PSEdition Core or a `pwsh ...` usage line, or, in a folder that is no project yet, when this PC has PowerShell 7.') }),
-    cli: z.strictObject({
-        gh: Enabled.describe('GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR). "auto" = when the project has a .github folder.'),
-        zstd: Enabled.describe('Zstandard (zstd). "auto" = off; set true to get it.'),
-        openssl: Enabled.describe('`openssl` on PATH, from the copy Git for Windows ships (its mingw64\\bin is not put on PATH, so it cannot shadow MinGW\'s gcc). "auto" = on.'),
-    }).describe('Small portable command-line tools from their GitHub releases, installed once into tools\\cli.'),
+    pwsh: z.strictObject({
+        enabled: EnabledSchema.describe('PowerShell 7 (pwsh), portable (~110 MB once); `powershell` stays Windows PowerShell 5.1. true, false, or "auto" = when a .ps1 at the root or one folder down has #Requires -Version 7 / -PSEdition Core or a `pwsh ...` usage line, or, in a folder that is no project yet, when this PC has PowerShell 7.'),
+    }),
+    cli: z
+        .strictObject({
+        gh: EnabledSchema.describe('GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR). "auto" = when the project has a .github folder.'),
+        zstd: EnabledSchema.describe('Zstandard (zstd). "auto" = off; set true to get it.'),
+        openssl: EnabledSchema.describe('`openssl` on PATH, from the copy Git for Windows ships (its mingw64\\bin is not put on PATH, so it cannot shadow MinGW\'s gcc). "auto" = on.'),
+    })
+        .describe('Small portable command-line tools from their GitHub releases, installed once into tools\\cli.'),
     bun: toggle('Bun runtime (claude-mem needs it).'),
     uv: toggle('uv, the Python package manager (claude-mem needs it).'),
     vcRuntime: toggle('Microsoft Visual C++ runtime for tools that need it (a real installer, so it runs on every boot, ~15 s). PHP installs it regardless.'),
     mesa: z.strictObject({
-        enabled: z.boolean().describe('Mesa 3D (llvmpipe): OpenGL 4.5 in software for games and apps when there is no GPU (sandbox.vGpu off). Copy opengl32.dll and libgallium_wgl.dll from %MESA_DIR% next to the program\'s .exe.'),
-        vulkan: z.boolean().describe('Also software Vulkan 1.4 (Mesa lavapipe) with the Khronos loader, registered for every program; for wgpu set WGPU_BACKEND=vulkan.'),
+        enabled: z
+            .boolean()
+            .describe("Mesa 3D (llvmpipe): OpenGL 4.5 in software for games and apps when there is no GPU (sandbox.vGpu off). Copy opengl32.dll and libgallium_wgl.dll from %MESA_DIR% next to the program's .exe."),
+        vulkan: z
+            .boolean()
+            .describe('Also software Vulkan 1.4 (Mesa lavapipe) with the Khronos loader, registered for every program; for wgpu set WGPU_BACKEND=vulkan.'),
     }),
     vscode: z.strictObject({
-        enabled: z.boolean().describe('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
-        setup: z.boolean().describe('Point VS Code at the sandbox\'s own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use.'),
-        recommended: z.boolean().describe('Also install the extensions a project recommends in its .vscode/extensions.json.'),
-        extensions: z.array(z.string().regex(/^[\w-]+\.[\w-]+$/, 'publisher.name, e.g. eamodio.gitlens')).describe('More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker.'),
+        enabled: z
+            .boolean()
+            .describe('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
+        setup: z
+            .boolean()
+            .describe("Point VS Code at the sandbox's own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use."),
+        recommended: z
+            .boolean()
+            .describe('Also install the extensions a project recommends in its .vscode/extensions.json.'),
+        extensions: z
+            .array(z.string().regex(/^[\w-]+\.[\w-]+$/, 'publisher.name, e.g. eamodio.gitlens'))
+            .describe('More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker.'),
     }),
-    environment: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'letters, digits and _ only'), z.string()).describe('Extra environment variables for the agent and every terminal, e.g. registry mirrors: {"NPM_CONFIG_REGISTRY": "https://...", "PIP_INDEX_URL": "https://..."}.'),
+    environment: z
+        .record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'letters, digits and _ only'), z.string())
+        .describe('Extra environment variables for the agent and every terminal, e.g. registry mirrors: {"NPM_CONFIG_REGISTRY": "https://...", "PIP_INDEX_URL": "https://..."}.'),
 });

package/dist/core/types.d.ts

@@ -1,17 +1,21 @@
 import type { z } from 'zod';
-import type { Config as ConfigSchema, GitAccess as GitAccessSchema, Harness as HarnessSchema, LocalOverrides, Mapping as MappingSchema } from './schema.js';
-export type { AttachEndpointT as AttachEndpoint, GuestRequestT as GuestRequest, GuestResponseT as GuestResponse, SandboxStatusT as SandboxStatus, SessionStatusT as SessionStatus } from '../shared/schema.js';
+import type { AutoToolchain, ToolchainDecision } from './detect/index.js';
+import type { BootWant } from './local-config/index.js';
+import type { ConfigSchema, GitAccessSchema, HarnessSchema, LocalOverridesSchema, MappingSchema } from './schema/index.js';
+export type { AttachEndpoint, GuestRequest, GuestResponse, SandboxStatus, SessionStatus, } from '../shared/channel/index.js';
 export type Config = z.output<typeof ConfigSchema>;
-export type Overrides = z.output<typeof LocalOverrides>;
+export type Overrides = z.output<typeof LocalOverridesSchema>;
 export type GitAccess = z.output<typeof GitAccessSchema>;
 export type Harness = z.output<typeof HarnessSchema>;
 export type Mapping = z.output<typeof MappingSchema>;
 export type Toolchains = Config['toolchains'];
 export type ClaudeProfileConfig = Config['claudeProfile'];
+/** label: shown in the launch table, e.g. "outside the project, allowed". */
 export interface ResolvedMapping {
     host: string;
     guest: string;
     readOnly: boolean;
+    label?: string;
 }
 export interface LocalConfigFile {
     path: string;
@@ -39,6 +43,8 @@ export interface RunRequest {
     nodeVersion?: string;
     pythonVersion?: string;
     ask?: (question: string) => Promise<boolean>;
+    /** `ask` can reach you (default: stdin is a terminal). Tests set it. */
+    interactive?: boolean;
 }
 export interface ResolvedRun {
     config: Config;
@@ -52,6 +58,8 @@ export interface ResolvedRun {
     versions: ToolVersions;
     /** Your config asks for guestWorkspace "mirror" (project roots then appear at their PC paths too). */
     mirror?: boolean;
+    /** The project file's folders outside the project that you allowed (host paths; the launch table marks them). */
+    outsideMappings?: string[];
 }
 /** A requested version plus where the request came from (shown to the user). */
 export interface VersionSpec {
@@ -94,12 +102,20 @@ export interface GenerateOptions {
     probe: HostProbe;
     freeMemoryBytes?: number;
     databases?: DatabasePlan[];
-    pcLanguages?: import('./detect-toolchains.js').AutoToolchain[];
-    /** More projects to map (a restart that adds one keeps the ones in use); knownProjects: instead of known-projects.json (tests). */
+    pcLanguages?: AutoToolchain[];
+    /**
+     * More projects to map (a restart that adds one keeps the ones in use); knownProjects: instead of known-projects.json
+     * (tests).
+     */
     extraProjects?: string[];
     knownProjects?: string[];
     /** false: no agent session at boot. */
     autoSession?: boolean;
+    /** The other projects mapped at boot with their effective configs: the sandbox boots with what they want too. */
+    bootWants?: {
+        projects: BootWant[];
+        keepOff: string[];
+    };
 }
 export interface Generated {
     wsbPath: string;
@@ -107,6 +123,10 @@ export interface Generated {
     launchId: string;
     sessionPath: string;
     memoryMb: number;
+    /** The config the sandbox boots with: the launch folder's plus what the other projects mapped at boot want. */
+    bootConfig: Config;
+    /** Boot settings turned on for another project (setting -> project). */
+    widened: Record<string, string>;
     mappings: ResolvedMapping[];
     profile: ProfileResult;
     databases: DatabasePlan[];
@@ -122,7 +142,9 @@ export interface Generated {
         }[];
         notes: string[];
     };
-    toolchains: Record<import('./detect-toolchains.js').AutoToolchain, import('./detect-toolchains.js').ToolchainDecision>;
+    toolchains: Record<AutoToolchain, ToolchainDecision>;
+    /** Where extra folders went when their own path could not be used, and the optional ones skipped. */
+    mappingNotes: string[];
 }
 /** secretsRemoved: what secrets.strip kept on this PC, e.g. "settings.json env.AWS_SECRET_ACCESS_KEY". */
 export interface ProfileResult {
@@ -138,9 +160,11 @@ export interface GuestSession {
     project: string;
     workspace: string;
     workspaceHost: string;
-    /** The launch folder's project id (file-name safe; status files and sessions use it). Older launch folders lack it. */
+    /**
+     * The launch folder's project id (file-name safe; status files and sessions use it). Older launch folders lack it.
+     */
     projectId?: string;
-    /** Where other projects appear (C:\Projects), and the project roots' guest folders. Older launch folders lack them. */
+    /** Where project roots appear (C:\Projects), and the guest folders of the roots and the projects mapped at boot. Older launch folders lack them. */
     projectsDir?: string;
     roots?: string[];
     /** false: start no agent session at boot (a restart that adds a project opens its sessions itself). */
@@ -180,7 +204,10 @@ export interface GuestSession {
         syncClaudeMem: boolean;
     };
     personalization: boolean;
-    /** Drives other than C: that bootstrap.ps1 makes with subst before anything uses them: letter D-Z onto C:\Mirror\<letter>. */
+    /**
+     * Drives other than C: that bootstrap.ps1 makes with subst before anything uses them: letter D-Z onto
+     * C:\Mirror\<letter>.
+     */
     substDrives?: {
         letter: string;
         target: string;

package/dist/core/util/errors.d.ts

@@ -0,0 +1,8 @@
+/** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
+export declare class UserError extends Error {
+    readonly fix?: string | undefined;
+    constructor(message: string, fix?: string | undefined);
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export declare const fail: (message: string, fix?: string) => never;
+export declare const errMsg: (e: unknown) => string;

package/dist/core/util/errors.js

@@ -0,0 +1,14 @@
+/** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
+export class UserError extends Error {
+    fix;
+    constructor(message, fix) {
+        super(message);
+        this.fix = fix;
+        this.name = 'UserError';
+    }
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export const fail = (message, fix) => {
+    throw new UserError(message, fix);
+};
+export const errMsg = (e) => (e instanceof Error ? e.message : String(e));

package/dist/core/util/fs.d.ts

@@ -0,0 +1,8 @@
+export declare const ensureDir: (p: string) => void;
+export declare const dirExists: (p: string) => boolean;
+export declare const fileExists: (p: string) => boolean;
+export declare const readJson: <T>(p: string) => T;
+export declare const tryReadJson: <T>(p: string) => T | null;
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
+export declare const writeJson: (p: string, value: unknown) => void;
+export declare const realPath: (p: string) => string;