windows-development-sandbox 1.1.0 → 1.4.1

package/dist/core/schema/config.js

@@ -6,22 +6,27 @@ import { Name, SchemaRef, Strings, toggle } from './common.js';
 import { Databases } from './databases.js';
 import { Harness } from './harness.js';
 import { AgentCommands, Attach, ClaudeProfile, Secrets } from './profile.js';
-import { Downloads, Git, GuestWorkspace, Mapping, Provisioning, Sandbox } from './sandbox.js';
+import { Audit, Downloads, Git, GuestWorkspace, Mapping, Network, Provisioning, Sandbox, WorkspaceFilter } from './sandbox.js';
 import { Toolchains } from './toolchains.js';
+import { Apps } from './apps.js';
 import { Projects } from './projects.js';
 export const Config = z.strictObject({
     $schema: SchemaRef.optional(),
     defaultHarness: Name.describe('Agent started by `sandbox launch` (sandbox claude always runs claude).'),
     guestWorkspace: GuestWorkspace,
     readOnly: z.boolean().describe('Map the workspace read-only.'),
+    workspaceFilter: WorkspaceFilter,
+    audit: Audit,
     mappings: z.array(Mapping).describe('Extra folders from this PC.'),
     sandbox: Sandbox,
     storage: z.strictObject({
         root: z.string().min(1).describe('Where everything is kept on this PC (tools, databases, logins, launches).'),
         persistAgentState: z.boolean().describe('Keep agent logins and history between sandboxes.'),
         dataName: Name.describe('Name of the persistent data set (C:\\AgentData) shared by all workspaces.'),
+        markSandboxFiles: z.boolean().describe('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.'),
+        warnDataGb: z.number().min(0).describe('Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space.'),
     }),
-    network: z.strictObject({ blockPrivateRanges: z.boolean().describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.') }),
+    network: Network,
     provisioning: Provisioning,
     downloads: Downloads,
     toolchains: Toolchains,
@@ -30,6 +35,7 @@ export const Config = z.strictObject({
     agentCommands: AgentCommands,
     secrets: Secrets,
     personalization: toggle('Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox.'),
+    apps: Apps,
     claudeProfile: ClaudeProfile,
     harnesses: z.record(Name, Harness).describe('Agents that can run in the sandbox.'),
     hooks: z.strictObject({ failFast: z.boolean().describe('Stop when a hook script fails.') }),
@@ -44,10 +50,14 @@ export const LocalOverrides = z.strictObject({
     harness: Name.describe('Agent for this project.'),
     guestWorkspace: GuestWorkspace,
     readOnly: z.boolean().describe('Map this project read-only.'),
-    mappings: z.array(Mapping).describe('Extra folders (relative to this file).'),
+    // A project may turn the filter on and keep more out, never let ignored files in.
+    workspaceFilter: WorkspaceFilter.pick({ enabled: true, exclude: true }).partial(),
+    mappings: z.array(Mapping).describe('Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once).'),
     scripts: Strings.describe('Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent.'),
-    sandbox: Sandbox.omit({ cpuLimit: true }).partial(),
-    network: z.strictObject({ blockPrivateRanges: z.boolean() }).partial(),
+    // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
+    sandbox: Sandbox.omit({ cpuLimit: true, pageFileMb: true }).partial(),
+    // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
+    network: Network.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
     provisioning: Provisioning.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true }).extend({ git: Git.partial(), terminal: toggle('Windows Terminal as the sandbox window.').partial() }).partial(),
     downloads: Downloads.partial(),
     // Every toolchain setting, each one optional (a project usually only switches languages on or pins a version).
@@ -58,6 +68,8 @@ export const LocalOverrides = z.strictObject({
     databases: z.strictObject(_.mapValues(Databases.shape, (shape) => shape.partial())).partial(),
     attach: Attach.partial(),
     personalization: toggle('Copy your desktop look into the sandbox.').partial(),
-    claudeProfile: ClaudeProfile.pick({ enabled: true, include: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
+    // Catalogue apps only (a vetted list): your own programs (apps.custom) download anything, so a repo cannot add them.
+    apps: Apps.pick({ install: true }).partial(),
+    claudeProfile: ClaudeProfile.pick({ enabled: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
     hooks: z.strictObject({ failFast: z.boolean() }).partial(),
 }).partial();

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

@@ -23,5 +23,10 @@ export declare const ClaudeProfile: z.ZodObject<{
     copyCredentials: z.ZodBoolean;
     overwrite: z.ZodBoolean;
     syncHistory: z.ZodBoolean;
+    historyScope: z.ZodEnum<{
+        project: "project";
+        all: "all";
+    }>;
     syncClaudeMem: z.ZodBoolean;
+    syncClaudeMemBack: z.ZodBoolean;
 }, z.core.$strict>;

package/dist/core/schema/profile.js

@@ -24,6 +24,8 @@ export const ClaudeProfile = z.strictObject({
     globalStateFile: z.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
     copyCredentials: z.boolean().describe('Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead.'),
     overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
-    syncHistory: z.boolean().describe('Bring all conversation history in, and sync new history back (path-translated).'),
-    syncClaudeMem: z.boolean().describe('Bring claude-mem data in, and its database back when the sandbox closes.'),
+    syncHistory: z.boolean().describe('Bring conversation history in, and sync new history back (path-translated).'),
+    historyScope: z.enum(['project', 'all']).describe('Which history comes in: "project" = only the projects in this sandbox (other projects\' conversations, file backups and prompts stay on this PC), "all" = everything. Only this sandbox\'s projects ever sync back.'),
+    syncClaudeMem: z.boolean().describe('Bring claude-mem data into the sandbox (its settings and backups stay on this PC).'),
+    syncClaudeMemBack: z.boolean().describe('Also copy claude-mem\'s database back to this PC when the sandbox closes. Off by default: what is in it is loaded into every Claude session on this PC, so a compromised agent could plant instructions there.'),
 });

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

@@ -5,5 +5,6 @@ export declare const Projects: z.ZodObject<{
     roots: z.ZodArray<z.ZodString>;
     askToAddRoot: z.ZodBoolean;
     declinedRoots: z.ZodArray<z.ZodString>;
+    allowOutsideMappings: z.ZodUnion<readonly [z.ZodLiteral<"ask">, z.ZodBoolean]>;
     wsbShare: z.ZodBoolean;
 }, z.core.$strict>;

package/dist/core/schema/projects.js

@@ -7,5 +7,6 @@ export const Projects = z.strictObject({
     roots: z.array(z.string().min(1)).describe('Folders whose subfolders are your projects (e.g. "F:\\\\Code"), mapped read/write at every start. Any project inside one, including ones you create later, opens in the running sandbox at once, without a restart. Every agent in the sandbox can see all of them.'),
     askToAddRoot: z.boolean().describe('When you start a project whose parent folder is not a root yet, ask once whether to add it.'),
     declinedRoots: z.array(z.string().min(1)).describe('Parent folders you said no to (not asked again).'),
+    allowOutsideMappings: z.union([z.literal('ask'), z.boolean()]).describe('A project\'s .sandbox-config.json may map folders from outside the project (e.g. a game folder on another drive). "ask" = an interactive launch asks once per project and set of folders, and remembers your answer; true = always allowed (still listed when you approve the file); false = never (the launch stops and says which folders). Only your own settings decide this, never a project file.'),
     wsbShare: z.boolean().describe('On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart.'),
 });

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

@@ -2,7 +2,7 @@ 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<{
     host: z.ZodString;
-    guest: z.ZodString;
+    guest: z.ZodOptional<z.ZodString>;
     readOnly: z.ZodBoolean;
     optional: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
@@ -11,6 +11,7 @@ export declare const Sandbox: z.ZodObject<{
     maxMemoryMb: z.ZodNumber;
     maxMemoryPercent: z.ZodNumber;
     cpuLimit: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodNumber]>;
+    pageFileMb: z.ZodNumber;
     reserveHostMb: z.ZodNumber;
     vGpu: z.ZodBoolean;
     networking: z.ZodBoolean;
@@ -20,6 +21,30 @@ export declare const Sandbox: z.ZodObject<{
     printerRedirection: z.ZodBoolean;
     protectedClient: z.ZodBoolean;
     headless: z.ZodBoolean;
+    keepAwake: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const Network: z.ZodObject<{
+    blockPrivateRanges: z.ZodBoolean;
+    allowOnly: z.ZodArray<z.ZodString>;
+    blockHosts: z.ZodArray<z.ZodString>;
+    forwardPorts: z.ZodArray<z.ZodObject<{
+        pc: z.ZodNumber;
+        sandbox: z.ZodNumber;
+    }, z.core.$strict>>;
+    dns: z.ZodArray<z.ZodString>;
+    proxy: z.ZodString;
+}, z.core.$strict>;
+export declare const Audit: 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<{
+    enabled: z.ZodBoolean;
+    exclude: z.ZodArray<z.ZodString>;
+    include: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export declare const Git: z.ZodObject<{
     enabled: z.ZodBoolean;
@@ -44,6 +69,9 @@ export declare const Provisioning: z.ZodObject<{
     terminal: z.ZodObject<{
         enabled: z.ZodBoolean;
     }, z.core.$strict>;
+    conpty: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 export declare const Downloads: z.ZodObject<{
     requireChecksum: z.ZodBoolean;

package/dist/core/schema/sandbox.js

@@ -4,7 +4,7 @@ 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({
     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 path the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) goes to C:\\Mapped\\<drive>\\<path> instead, and the launch says so.'),
     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.'),
 });
@@ -13,6 +13,7 @@ export const Sandbox = z.strictObject({
     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.'),
     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,6 +23,32 @@ export const Sandbox = z.strictObject({
     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).'),
+});
+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.'),
+});
+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.'),
+    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).'),
+    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 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({
@@ -30,6 +57,7 @@ export const Provisioning = z.strictObject({
     refresh: z.boolean().describe('Re-copy / re-download everything on the next launch.'),
     git: Git,
     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.'),
 });
 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.'),

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

@@ -88,6 +88,9 @@ export declare const Toolchains: z.ZodObject<{
     }, z.core.$strict>;
     vscode: z.ZodObject<{
         enabled: z.ZodBoolean;
+        setup: z.ZodBoolean;
+        recommended: z.ZodBoolean;
+        extensions: z.ZodArray<z.ZodString>;
     }, z.core.$strict>;
     environment: z.ZodRecord<z.ZodString, z.ZodString>;
 }, z.core.$strict>;

package/dist/core/schema/toolchains.js

@@ -78,6 +78,11 @@ export const Toolchains = 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.'),
     }),
-    vscode: toggle('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
+    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.'),
+    }),
     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

@@ -8,10 +8,12 @@ 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 +41,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 +56,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 {
@@ -100,6 +106,11 @@ export interface GenerateOptions {
     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: import('./project-policy.js').BootWant[];
+        keepOff: string[];
+    };
 }
 export interface Generated {
     wsbPath: string;
@@ -107,6 +118,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[];
@@ -123,6 +138,8 @@ export interface Generated {
         notes: string[];
     };
     toolchains: Record<import('./detect-toolchains.js').AutoToolchain, import('./detect-toolchains.js').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 {
@@ -140,7 +157,7 @@ export interface GuestSession {
     workspaceHost: string;
     /** 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). */
@@ -187,4 +204,10 @@ export interface GuestSession {
     }[];
     /** sandbox.cpuLimit as a number (null = no cap); sandbox\cpucap.ps1 applies it before anything starts. */
     cpuLimitPercent?: number | null;
+    /** sandbox.pageFileMb (0 = Windows' own); sandbox\pagefile.ps1 applies it at logon. */
+    pageFileMb?: number;
+    /** Apps to install (catalogue ids and your own programs); missing in launch folders of older versions. */
+    apps?: Config['apps'];
+    /** audit.enabled and audit.processes: the sandbox reports the programs it starts (host keeps the log). */
+    auditProcesses?: boolean;
 }

package/dist/core/util.d.ts

@@ -34,6 +34,8 @@ export declare const isInsideOrEqual: (parent: string, child: string) => boolean
  * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
  */
 export declare const safeText: (text: string) => string;
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export declare const plainText: (text: string) => string;
 export declare const findOnPath: (names: string[]) => string | null;
 /** True if `p` itself is a symlink or junction (lstat; never follows it). */
 export declare const isLink: (p: string) => boolean;

package/dist/core/util.js

@@ -81,6 +81,8 @@ export const isInsideOrEqual = (parent, child) => {
  * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
  */
 export const safeText = (text) => text.replace(/\x1b\[[0-9;]*m|\x1b(\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (m) => (/^\x1b\[[0-9;]*m$/.test(m) ? m : ''));
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export const plainText = (text) => safeText(text).replace(/\x1b\[[0-9;]*m/g, '');
 export const findOnPath = (names) => {
     const dirs = (process.env.PATH ?? process.env.Path ?? '').split(path.delimiter).filter((d) => d !== '');
     for (const name of names)

package/dist/core/workspace.d.ts

@@ -1,9 +1,13 @@
-import type { Config, Overrides, ResolvedRun, RunRequest, ToolVersions } from './types.js';
+import type { Config, Mapping, Overrides, ResolvedRun, RunRequest, ToolVersions } from './types.js';
+/** 'auto' guest workspace: C:\Workspace\<folder name> (shared/projects.ts, where every project's place is decided). */
+export declare const autoGuestWorkspace: (hostDir: string) => string;
 /**
- * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
- * and claude-mem's project name match this PC instead of every project being "Workspace".
+ * A launch folder inside a project root appears under the root's folder (C:\Projects\<root>\<name>, or its PC path
+ * with "mirror"), where it also is when another project started the sandbox, so git worktrees and Claude's project
+ * folders keep working whichever project starts it. Only for "auto" / "mirror"; a filtered or read-only workspace
+ * keeps its own mapping (the root would show the folder unfiltered and writable at that place).
  */
-export declare const autoGuestWorkspace: (workspaceHost: string) => string;
+export declare const placeInRoot: (config: Config, workspaceHost: string, mirror: boolean, notes: string[]) => Config;
 /** The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too. */
 export declare const voltaNode: (workspace: string) => string | null;
 /**
@@ -16,3 +20,16 @@ export declare const resolveVersions: (config: Config, workspace: string, local:
 }, hostNodeVersion: string) => ToolVersions;
 /** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
 export declare const resolveRun: (req: RunRequest, hostNodeVersion?: string) => Promise<ResolvedRun>;
+/** Where the workspace appears: guestWorkspace "auto", "mirror" (with a note when it falls back) or a path. */
+export declare const guestWorkspaceOf: (config: Pick<Config, "guestWorkspace">, workspaceHost: string) => {
+    guest: string;
+    note: string | null;
+};
+/**
+ * Where a mapping will most likely appear, before the launch knows every other folder (the prompt and config check
+ * show it; the launch places it for real in host/launch/mappings.ts with the same rules).
+ */
+export declare const previewGuest: (m: Pick<Mapping, "host" | "guest">, workspaceHost: string, workspaceGuest: string) => {
+    guest: string;
+    note: string | null;
+};

package/dist/core/workspace.js

@@ -1,18 +1,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
-import { planMirrorWorkspace } from '../shared/guest-paths.js';
+import { deriveGuest, placeGuest, planMirrorWorkspace } from '../shared/guest-paths.js';
+import { autoGuestFolder, PROJECTS_GUEST, rootGuestDir, usableRoots } from '../shared/projects.js';
 import { DATABASES } from './detect-databases.js';
-import { applyOverrides, describeOverrides, isTrusted, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
+import { allowedAnswer, allowRequests, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, saveAllowed, saveTrust, trustStorePath } from './local-config.js';
 import { assertSafeWorkspace } from './safe-paths.js';
-import { dirExists, expandPath, fail, fileExists } from './util.js';
+import { dirExists, expandPath, fail, fileExists, isInsideOrEqual, plainText } from './util.js';
+/** 'auto' guest workspace: C:\Workspace\<folder name> (shared/projects.ts, where every project's place is decided). */
+export const autoGuestWorkspace = autoGuestFolder;
 /**
- * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
- * and claude-mem's project name match this PC instead of every project being "Workspace".
+ * A launch folder inside a project root appears under the root's folder (C:\Projects\<root>\<name>, or its PC path
+ * with "mirror"), where it also is when another project started the sandbox, so git worktrees and Claude's project
+ * folders keep working whichever project starts it. Only for "auto" / "mirror"; a filtered or read-only workspace
+ * keeps its own mapping (the root would show the folder unfiltered and writable at that place).
  */
-export const autoGuestWorkspace = (workspaceHost) => {
-    const name = path.basename(workspaceHost).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
-    return 'C:\\Workspace\\' + (name || 'project');
+export const placeInRoot = (config, workspaceHost, mirror, notes) => {
+    const guest = rootGuestDir(usableRoots(config.projects.roots, dirExists), mirror, workspaceHost);
+    if (!guest)
+        return config;
+    if (config.workspaceFilter.enabled || config.readOnly) {
+        notes.push(workspaceHost + ' is inside a project root, but ' + (config.readOnly ? 'readOnly' : 'workspaceFilter') + ' is on, so it is mapped on its own at ' + config.guestWorkspace + ' (when another project starts the sandbox it is at ' + guest + ').');
+        return config;
+    }
+    return { ...config, guestWorkspace: guest };
 };
 const firstLine = (file) => {
     if (!fileExists(file))
@@ -79,24 +90,77 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
     let localConfigPath = null;
     let overrides = {};
     const local = req.noLocalConfig ? null : readLocalConfig(workspaceHost);
+    let outsideAllowed = [];
     if (local) {
         overrides = normalizeOverrides(local.data, workspaceHost, local.path);
         const store = trustStorePath(storageRoot);
         if (!isTrusted(store, local.path, local.hash)) {
-            const summary = describeOverrides(overrides);
+            const summary = describeOverrides(overrides, workspaceHost);
             let trusted = req.trustConfig;
             if (!trusted && req.ask) {
                 console.log('\nFound ' + local.path + ' which is not trusted yet. It would apply:');
                 for (const line of summary)
-                    console.log('  ' + line);
+                    console.log('  ' + plainText(line));
                 trusted = await req.ask('Trust and use this file?');
             }
             if (!trusted)
-                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
+                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.map(plainText).join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
             saveTrust(store, local.path, local.hash);
             notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
         }
-        config = applyOverrides(config, overrides);
+        // A project may only tighten. What it asks for beyond that (a looser setting, a folder outside the project) is used
+        // only if you allowed it for this project: asked once, in one question, at an interactive launch, never by
+        // --trust-config. Folders outside the project follow projects.allowOutsideMappings (your settings only). A looser
+        // setting you did not allow is named in the notes instead of dropped silently.
+        const allowStore = allowStorePath(storageRoot);
+        const policy = config.projects.allowOutsideMappings;
+        // An optional folder that is not on this PC is skipped at launch, so it needs no answer (yet).
+        const outside = outsideMappings(workspaceHost, overrides.mappings).filter((m) => !m.optional || dirExists(m.host));
+        const name = path.basename(workspaceHost) + '\'s ' + LOCAL_CONFIG_NAME;
+        const preview = guestWorkspaceOf(applyOverrides(config, overrides), workspaceHost).guest;
+        const describe = (m) => (m.readOnly ? 'read-only  ' : 'READ/WRITE ') + m.host + '  ->  ' + previewGuest(m, workspaceHost, preview).guest;
+        if (outside.length && policy === false) {
+            fail(name + ' maps ' + outside.length + ' folder' + (outside.length === 1 ? '' : 's') + ' outside the project, and your settings do not allow that:\n  ' + outside.map(describe).join('\n  '), 'Allow it: set projects.allowOutsideMappings to "ask" or true in your settings (sandbox > Settings, or the file sandbox config path shows). Or remove those mappings from the file.');
+        }
+        const looser = loosenedRequests(config, overrides);
+        const interactive = Boolean(req.ask) && (req.interactive ?? Boolean(process.stdin.isTTY));
+        const openOutside = policy === 'ask' ? outside.filter((m) => allowedAnswer(allowStore, local.path, OUTSIDE_FOLDER, outsideKey(m)) !== true) : [];
+        const openLooser = looser.filter((a) => allowedAnswer(allowStore, local.path, a.key, a.wanted) === null);
+        let declinedOutside = false;
+        if (interactive && req.ask && (openOutside.length || openLooser.length)) {
+            console.log('\n' + name + ' asks for more than your settings allow:');
+            if (openOutside.length)
+                console.log('  Folders outside the project:\n' + openOutside.map((m) => '    ' + plainText(describe(m))).join('\n'));
+            for (const a of openLooser)
+                console.log('  ' + a.key + ' = ' + JSON.stringify(a.wanted) + '  (your settings: ' + JSON.stringify(a.yours) + ')');
+            const ok = await req.ask('Allow ' + (openOutside.length + openLooser.length === 1 ? 'it' : 'these') + ' for this project?');
+            for (const a of openLooser)
+                saveAllowed(allowStore, local.path, a.key, a.wanted, ok);
+            // A "no" to folders is not kept: the next interactive launch asks again.
+            if (ok)
+                for (const m of openOutside)
+                    saveAllowed(allowStore, local.path, OUTSIDE_FOLDER, outsideKey(m), true);
+            declinedOutside = !ok && openOutside.length > 0;
+        }
+        const notAllowed = policy === 'ask' ? outside.filter((m) => allowedAnswer(allowStore, local.path, OUTSIDE_FOLDER, outsideKey(m)) !== true) : [];
+        if (notAllowed.length) {
+            const what = name + ' maps ' + notAllowed.length + ' folder' + (notAllowed.length === 1 ? '' : 's') + ' outside the project:\n  ' + notAllowed.map(describe).join('\n  ');
+            fail(what + (declinedOutside ? '\nYou did not allow ' + (notAllowed.length === 1 ? 'it' : 'them') + ', so the sandbox was not started.' : '\nThat needs your OK once (a repo ships this file), and this launch cannot ask (no interactive terminal).'), 'Allow ' + (notAllowed.length === 1 ? 'it' : 'them') + ': start it from an interactive terminal and answer y, or set projects.allowOutsideMappings to true in your settings (sandbox > Settings, or the file sandbox config path shows).');
+        }
+        outsideAllowed = [...new Set(outside.map((m) => m.host))];
+        if (outside.length)
+            notes.push('Folders outside the project allowed for ' + name + ' (' + (policy === true ? 'projects.allowOutsideMappings is true' : 'your answer is kept in ' + allowStore) + '): ' + outsideAllowed.join(', '));
+        const allowed = [];
+        for (const ask of looser) {
+            const ok = allowedAnswer(allowStore, local.path, ask.key, ask.wanted);
+            if (ok) {
+                allowed.push(ask);
+                notes.push('Allowed for this project: ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ' (your answer is kept in ' + allowStore + ').');
+            }
+            else
+                notes.push('The project asks for ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ', but your settings say ' + JSON.stringify(ask.yours) + ', so it is not used. ' + (ok === false ? 'You said no (kept in ' + allowStore + ').' : 'Start it from an interactive terminal to allow it for this project.') + ' Or set ' + ask.key + ' in your own settings (sandbox, then Settings > All projects).');
+        }
+        config = applyOverrides(allowRequests(config, allowed), overrides);
         scripts.push(...(overrides.scripts ?? []));
         localConfigPath = local.path;
         notes.push('Using ' + local.path);
@@ -109,14 +173,12 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
             fail('Unknown database "' + name + '".', 'Choose from: ' + DATABASES.join(', '));
         config = { ...config, databases: { ...config.databases, [db]: { ...config.databases[db], enabled: true } } };
     }
-    if (config.guestWorkspace === 'auto')
-        config = { ...config, guestWorkspace: autoGuestWorkspace(workspaceHost) };
-    else if (config.guestWorkspace === 'mirror') {
-        const plan = planMirrorWorkspace(workspaceHost, autoGuestWorkspace(workspaceHost));
-        if (plan.note)
-            notes.push(plan.note);
-        config = { ...config, guestWorkspace: plan.guest };
-    }
+    // auto / mirror: a project inside a root is where the root shows it, whichever project starts the sandbox.
+    const guest = guestWorkspaceOf(config, workspaceHost);
+    const placed = config.guestWorkspace === 'auto' || mirror ? placeInRoot({ ...config, guestWorkspace: guest.guest }, workspaceHost, mirror, notes) : { ...config, guestWorkspace: guest.guest };
+    if (guest.note && placed.guestWorkspace === guest.guest)
+        notes.push(guest.note);
+    config = placed;
     scripts.push(...req.scripts.map((s) => path.resolve(s)));
     const harnessName = req.noAgent ? 'none' : (req.harness ?? config.defaultHarness);
     if (harnessName !== 'none' && !config.harnesses[harnessName])
@@ -124,5 +186,21 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
     const versions = resolveVersions(config, workspaceHost, overrides, req, hostNodeVersion);
     const dataPath = path.join(storageRoot, 'data', config.storage.dataName);
     // A project file may ask for "mirror" too (it decides only its own path); project roots follow the user's choice.
-    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions, mirror };
+    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions, mirror, outsideMappings: outsideAllowed };
+};
+/** Where the workspace appears: guestWorkspace "auto", "mirror" (with a note when it falls back) or a path. */
+export const guestWorkspaceOf = (config, workspaceHost) => {
+    if (config.guestWorkspace === 'auto')
+        return { guest: autoGuestWorkspace(workspaceHost), note: null };
+    if (config.guestWorkspace === 'mirror')
+        return planMirrorWorkspace(workspaceHost, autoGuestWorkspace(workspaceHost));
+    return { guest: config.guestWorkspace, note: null };
 };
+/**
+ * Where a mapping will most likely appear, before the launch knows every other folder (the prompt and config check
+ * show it; the launch places it for real in host/launch/mappings.ts with the same rules).
+ */
+export const previewGuest = (m, workspaceHost, workspaceGuest) => placeGuest(m.host, m.guest ?? deriveGuest(m.host, workspaceHost, workspaceGuest), [
+    ...(m.guest || !isInsideOrEqual(workspaceHost, m.host) ? [{ guest: workspaceGuest, what: 'the project' }] : []),
+    { guest: PROJECTS_GUEST, what: 'other projects' },
+]);

package/dist/guest/apps/index.d.ts

@@ -0,0 +1,10 @@
+import type { Config, GitAccess } from '../../core/types.js';
+import { type ToolEnv } from '../toolchains/common.js';
+export { appsNeedMesa } from '../../shared/apps.js';
+export interface AppsOptions {
+    gitAccess: GitAccess;
+    refresh: boolean;
+}
+/** The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). */
+export declare const findExe: (root: string, exe: string) => string | null;
+export declare const setupApps: (env: ToolEnv, apps: Config["apps"], o: AppsOptions) => Promise<void>;