windows-development-sandbox 1.4.0 → 1.4.1

package/dist/cli/progress.js

@@ -9,6 +9,58 @@ export const elapsed = (ms) => {
     const s = Math.round(ms / 1000);
     return s < 60 ? s + ' s' : Math.floor(s / 60) + ' min ' + (s % 60) + ' s';
 };
+/**
+ * Follows long work (a sandbox's boot): on a terminal one line redrawn in place with the time so far; without one a
+ * plain line each time `key` changes. When nothing changes for `stallMs` it says so (stall(what, ms)). A failure first
+ * prints where it stopped, then rethrows.
+ */
+export const follow = async (show, work, o) => {
+    const err = process.stderr;
+    const animate = canAnimate(process.env, Boolean(err.isTTY));
+    const colour = colorEnabled(process.env, true);
+    const start = Date.now();
+    const stallMs = o.stallMs ?? 3 * 60 * 1000;
+    let shown = show();
+    let lastKey = '';
+    let changedAt = start;
+    let noticedAt = start;
+    let frame = 0;
+    const clear = () => { if (animate)
+        err.write('\r\x1b[2K'); };
+    const tick = () => {
+        const now = show();
+        if (now.line !== shown.line)
+            changedAt = noticedAt = Date.now();
+        shown = now;
+        if (Date.now() - noticedAt >= stallMs) {
+            clear();
+            err.write(o.stall(shown.what, Date.now() - changedAt) + '\n');
+            noticedAt = Date.now();
+        }
+        if (animate) {
+            const time = Date.now() - start > 3000 ? ' (' + elapsed(Date.now() - start) + ')' : '';
+            err.write('\r\x1b[2K' + (colour ? '\x1b[36m' : '') + FRAMES[frame++ % FRAMES.length] + (colour ? '\x1b[0m' : '') + ' ' + shorten(shown.line, termWidth() - 4 - time.length) + time);
+        }
+        else if (shown.key !== lastKey) {
+            lastKey = shown.key;
+            err.write(shown.line + (Date.now() - start > 3000 ? ' (' + elapsed(Date.now() - start) + ')' : '') + '\n');
+        }
+    };
+    tick();
+    const timer = setInterval(tick, animate ? 150 : 1000);
+    try {
+        return await work();
+    }
+    catch (e) {
+        clear();
+        err.write('It stopped at: ' + shown.line + '\n');
+        throw e;
+    }
+    finally {
+        clearInterval(timer);
+        clear();
+    }
+};
 /**
  * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
  * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.

package/dist/core/config.js

@@ -72,7 +72,7 @@ export const DEFAULTS = {
         aider: { uvPackage: 'aider-chat', uvBin: 'aider', arguments: [], environment: {}, resumeArguments: ['--restore-chat-history'] },
     },
     hooks: { failFast: false },
-    projects: { all: false, exclude: [], roots: [], askToAddRoot: true, declinedRoots: [], wsbShare: true },
+    projects: { all: false, exclude: [], roots: [], askToAddRoot: true, declinedRoots: [], allowOutsideMappings: 'ask', wsbShare: true },
 };
 /** Per-user folder for config and hooks. Survives reinstalling the npm package. */
 export const userDir = () => process.env.AGENT_SANDBOX_HOME ?? path.join(homeDir(), '.agent-sandbox');

package/dist/core/local-config.d.ts

@@ -2,6 +2,15 @@ import type { Config, LocalConfigFile, Overrides } from './types.js';
 export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export declare const normalizeOverrides: (data: unknown, dir: string, source: string) => Overrides;
+/**
+ * The project file's mappings of folders outside the project (%VAR% expanded, links and short names followed). A repo
+ * ships this file, so these reach the rest of this PC: projects.allowOutsideMappings in YOUR settings decides.
+ */
+export declare const outsideMappings: <M extends {
+    host: string;
+}>(dir: string, mappings?: M[]) => M[];
+/** `folder` (also where it really is, through links) is inside the project folder `dir`. */
+export declare const insideProject: (dir: string, folder: string) => boolean;
 /**
  * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
  * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
@@ -19,7 +28,7 @@ export declare const loosenedRequests: (config: Config, ov: Overrides) => {
 /** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
 export declare const applyOverrides: (config: Config, ov: Overrides) => Config;
 /** Human-readable list of what a local config changes, with risky items flagged. */
-export declare const describeOverrides: (ov: Overrides) => string[];
+export declare const describeOverrides: (ov: Overrides, dir?: string) => string[];
 export declare const readLocalConfig: (dir: string) => LocalConfigFile | null;
 export declare const trustStorePath: (storageRoot: string) => string;
 export declare const isTrusted: (store: string, file: string, hash: string) => boolean;
@@ -28,6 +37,12 @@ export declare const allowStorePath: (storageRoot: string) => string;
 /** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
 export declare const allowedAnswer: (store: string, file: string, setting: string, value: unknown) => boolean | null;
 export declare const saveAllowed: (store: string, file: string, setting: string, value: unknown, allow: boolean) => void;
+/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
+export declare const OUTSIDE_FOLDER = "folder outside the project";
+export declare const outsideKey: (m: {
+    host: string;
+    readOnly: boolean;
+}) => string;
 /** Your config with these requests let through, so applyOverrides' "strictest wins" keeps the project's value. */
 export declare const allowRequests: (config: Config, allowed: {
     key: string;

package/dist/core/local-config.js

@@ -20,14 +20,15 @@ export const normalizeOverrides = (data, dir, source) => {
     if (missing.length)
         fail(source + ' is not valid:\n  - scripts: file not found: ' + missing.join(', '));
     const mappings = overrides.mappings?.map((m) => ({ ...m, host: expandPath(m.host, dir) }));
-    // A repo ships this file, so it must not reach the rest of this PC: its extra folders stay inside the project.
-    const outside = mappings?.filter((m) => !insideProject(dir, m.host)) ?? [];
-    if (outside.length)
-        fail(source + ' is not valid:\n  - mappings: a project file may only map folders inside the project, not ' + outside.map((m) => m.host).join(', '), 'Map other folders in your own settings (sandbox config path shows where they are).');
     return { ...overrides, scripts, mappings };
 };
+/**
+ * The project file's mappings of folders outside the project (%VAR% expanded, links and short names followed). A repo
+ * ships this file, so these reach the rest of this PC: projects.allowOutsideMappings in YOUR settings decides.
+ */
+export const outsideMappings = (dir, mappings = []) => mappings.filter((m) => !insideProject(dir, m.host));
 /** `folder` (also where it really is, through links) is inside the project folder `dir`. */
-const insideProject = (dir, folder) => {
+export const insideProject = (dir, folder) => {
     // Where a path really is: the nearest existing folder resolved (links, 8.3 short names), plus the part not created yet.
     const real = (p) => {
         const full = path.resolve(p);
@@ -75,17 +76,19 @@ export const applyOverrides = (config, ov) => {
         next.network.blockHosts = _.union(config.network.blockHosts, rest.network.blockHosts);
     if (rest.workspaceFilter?.exclude)
         next.workspaceFilter.exclude = _.union(config.workspaceFilter.exclude, rest.workspaceFilter.exclude);
+    const sameGuest = (a, b) => Boolean(a && b && a.toLowerCase() === b.toLowerCase());
     if (mappings)
-        next.mappings = [..._.reject(config.mappings, (m) => mappings.some((o) => o.guest.toLowerCase() === m.guest.toLowerCase())), ...mappings];
+        next.mappings = [..._.reject(config.mappings, (m) => mappings.some((o) => sameGuest(o.guest, m.guest))), ...mappings];
     return next;
 };
 const flatten = (value, prefix = '') => _.isPlainObject(value) ? Object.entries(value).flatMap(([k, v]) => flatten(v, prefix ? prefix + '.' + k : k)) : [prefix + ' = ' + JSON.stringify(value)];
 /** Human-readable list of what a local config changes, with risky items flagged. */
-export const describeOverrides = (ov) => {
+export const describeOverrides = (ov, dir) => {
     const { harness, mappings = [], scripts = [], $schema: _schema, ...sections } = ov;
+    const outside = dir ? outsideMappings(dir, mappings) : [];
     const lines = [
         ...(harness ? ['agent = ' + harness] : []),
-        ...mappings.map((m) => (m.readOnly ? 'read-only' : 'READ/WRITE') + ' folder ' + m.host + '  ->  ' + m.guest),
+        ...mappings.map((m) => (m.readOnly ? 'read-only' : 'READ/WRITE') + ' folder ' + m.host + '  ->  ' + (m.guest ?? 'the same path') + (outside.includes(m) ? '  (outside the project)' : '')),
         ...scripts.map((s) => 'runs inside the sandbox: ' + s),
         ...flatten(sections),
     ];
@@ -114,7 +117,7 @@ export const saveTrust = (store, file, hash) => writeJson(store, { ...loadTrust(
 // is kept here, per project file and per "setting = value", so only that value is ever let through for that project.
 export const allowStorePath = (storageRoot) => path.join(storageRoot, 'allowed-requests.json');
 const loadAllowed = (store) => {
-    const parsed = z.record(z.string(), z.array(z.string().max(300)).max(50)).safeParse(tryReadJson(store) ?? {});
+    const parsed = z.record(z.string(), z.array(z.string().max(2000)).max(500)).safeParse(tryReadJson(store) ?? {});
     return parsed.success ? parsed.data : {};
 };
 const allowKey = (setting, value) => setting + ' = ' + JSON.stringify(value);
@@ -128,6 +131,9 @@ export const saveAllowed = (store, file, setting, value, allow) => {
     const entry = allowKey(setting, value);
     writeJson(store, { ...all, [key(file)]: _.union(_.without(all[key(file)] ?? [], entry, 'no: ' + entry), [(allow ? '' : 'no: ') + entry]) });
 };
+/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
+export const OUTSIDE_FOLDER = 'folder outside the project';
+export const outsideKey = (m) => (m.readOnly ? 'read-only ' : 'read/write ') + path.resolve(m.host).toLowerCase();
 /** Your config with these requests let through, so applyOverrides' "strictest wins" keeps the project's value. */
 export const allowRequests = (config, allowed) => {
     const next = _.cloneDeep(config);

package/dist/core/project-policy.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from './types.js';
+import type { Config, ResolvedMapping } from './types.js';
 /** The protections of a running sandbox, by setting path (`sandbox.networking`, `provisioning.git.access`, ...). */
 export type Protections = Record<string, boolean | string>;
 export declare const protectionsOf: (config: Config) => Protections;
@@ -7,9 +7,56 @@ export interface JoinCheck {
     stricter: string[];
     /** Settings it would have looser: it gets the sandbox's (stricter) value; shown as a note. */
     looser: string[];
+    /** Settings the sandbox turned on at its start for another project you allowed them for: shared, shown as a note. */
+    shared: string[];
 }
 /**
  * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
- * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter. `widened`: the boot
+ * settings the sandbox turned on for another of its projects (with your consent); a project that has them off
+ * shares them instead of being refused.
  */
-export declare const checkJoin: (running: Protections, wanted: Protections) => JoinCheck;
+export declare const checkJoin: (running: Protections, wanted: Protections, widened?: string[]) => JoinCheck;
+/** .wsb devices a project may want on (only when your settings or your answer for that project allow it). */
+export declare const BOOT_SETTINGS: string[];
+/** What the running sandbox booted with (host-only registry). */
+export interface BootRecord {
+    memoryMb: number | null;
+    mappings: ResolvedMapping[];
+}
+/** What a project wants that the running sandbox started without. */
+export interface Missing {
+    settings: string[];
+    memoryMb: number | null;
+    mappings: ResolvedMapping[];
+}
+/**
+ * The boot-only things `config` (a project's effective config: your settings, its approved file, your answers) asks
+ * for that the running sandbox lacks. `exists`: optional mappings whose folder is missing are no wish.
+ */
+export declare const missingAtBoot: (running: Protections, boot: BootRecord, config: Config, exists?: (folder: string) => boolean) => Missing;
+export declare const nothingMissing: (m: Missing) => boolean;
+/** "mw2-agent wants vGPU and 2 folders (C:\Steam\..., F:\SteamLibrary\...), but this sandbox started without them." */
+export declare const describeMissing: (project: string, m: Missing) => string;
+/** "Set sandbox.vGpu (or the mappings) in your own settings to have them in every sandbox." */
+export declare const missingTip: (m: Missing) => string;
+/** A project mapped at boot besides the launch folder, with its effective config. */
+export interface BootWant {
+    name: string;
+    config: Config;
+}
+export interface Widened {
+    config: Config;
+    /** Setting -> the project it was turned on for. */
+    widened: Record<string, string>;
+    notes: string[];
+}
+/**
+ * The launch folder's config plus what the other projects mapped at boot want: their allowed .wsb devices, a fixed
+ * memory size larger than the launch's, and their mappings (placed with every other mapping at launch).
+ * `keepOff`: devices the launch folder's own .sandbox-config.json switched off; they stay off.
+ */
+export declare const widenForProjects: (launch: Config, others: BootWant[], opts?: {
+    keepOff?: string[];
+    exists?: (folder: string) => boolean;
+}) => Widened;

package/dist/core/project-policy.js

@@ -3,6 +3,9 @@
 // A second project may never loosen them, and a project that needs a STRICTER setting than the running sandbox has
 // cannot get it there without changing it for the sessions already running, so that launch is refused with a clear
 // message. A project asking for less than the sandbox has simply runs with the sandbox's (stricter) setting.
+// The other direction: what a project WANTS at boot (a .wsb device you allowed for it, more memory, its mappings) and
+// the running sandbox started without. Those can only come with a restart, so they are named (missingAtBoot), and a
+// sandbox started with several projects boots with all of their allowed wants (widenForProjects).
 // Pure: the host checks it before registering a project, the tests drive it directly.
 import _ from 'lodash';
 import { GIT_STRICTNESS, NEVER_LOOSER, OFF_IS_SAFER, ON_IS_SAFER } from './local-config.js';
@@ -19,17 +22,100 @@ const compare = (setting, running, wanted) => {
 };
 /**
  * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
- * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter. `widened`: the boot
+ * settings the sandbox turned on for another of its projects (with your consent); a project that has them off
+ * shares them instead of being refused.
  */
-export const checkJoin = (running, wanted) => {
+export const checkJoin = (running, wanted, widened = []) => {
     const stricter = [];
     const looser = [];
+    const shared = [];
     for (const setting of NEVER_LOOSER) {
         const result = compare(setting, setting === 'readOnly' ? false : running[setting], wanted[setting]);
-        if (result > 0)
+        if (result > 0 && widened.includes(setting))
+            shared.push(setting);
+        else if (result > 0)
             stricter.push(setting + ' = ' + JSON.stringify(wanted[setting]) + ' (the running sandbox has ' + JSON.stringify(setting === 'readOnly' ? false : running[setting]) + ')');
         if (result < 0)
             looser.push(setting + ' stays ' + JSON.stringify(running[setting]));
     }
-    return { stricter, looser };
+    return { stricter, looser, shared };
+};
+// ---- what a project wants at boot ---------------------------------------------------------------------------------
+/** .wsb devices a project may want on (only when your settings or your answer for that project allow it). */
+export const BOOT_SETTINGS = ['sandbox.vGpu', 'sandbox.networking', 'sandbox.clipboard', 'sandbox.audioInput', 'sandbox.videoInput', 'sandbox.printerRedirection'];
+const LABELS = {
+    'sandbox.vGpu': 'vGPU', 'sandbox.networking': 'networking', 'sandbox.clipboard': 'the shared clipboard',
+    'sandbox.audioInput': 'the microphone', 'sandbox.videoInput': 'the camera', 'sandbox.printerRedirection': 'printers',
+};
+const sameHost = (a, b) => a.toLowerCase().replace(/\\+$/, '') === b.toLowerCase().replace(/\\+$/, '');
+/** `m`'s folder is mapped, wherever the launch placed it (read-only is enough for a read-only wish). */
+const isMapped = (mapped, m) => mapped.some((x) => sameHost(x.host, m.host) && (m.readOnly || !x.readOnly));
+/**
+ * The boot-only things `config` (a project's effective config: your settings, its approved file, your answers) asks
+ * for that the running sandbox lacks. `exists`: optional mappings whose folder is missing are no wish.
+ */
+export const missingAtBoot = (running, boot, config, exists = () => true) => ({
+    settings: BOOT_SETTINGS.filter((s) => _.get(config, s) === true && running[s] === false),
+    memoryMb: typeof config.sandbox.memoryMb === 'number' && boot.memoryMb !== null && config.sandbox.memoryMb > boot.memoryMb ? config.sandbox.memoryMb : null,
+    mappings: config.mappings.filter((m) => (!m.optional || exists(m.host)) && !isMapped(boot.mappings, m)).map((m) => ({ host: m.host, guest: m.guest ?? m.host, readOnly: m.readOnly })),
+});
+export const nothingMissing = (m) => m.settings.length === 0 && m.memoryMb === null && m.mappings.length === 0;
+const listing = (items) => items.length <= 1 ? items.join('') : items.slice(0, -1).join(', ') + ' and ' + items[items.length - 1];
+/** "mw2-agent wants vGPU and 2 folders (C:\Steam\..., F:\SteamLibrary\...), but this sandbox started without them." */
+export const describeMissing = (project, m) => {
+    const items = [
+        ...m.settings.map((s) => LABELS[s] ?? s),
+        ...(m.memoryMb !== null ? [m.memoryMb + ' MB of memory'] : []),
+        ...(m.mappings.length ? [m.mappings.length + ' folder' + (m.mappings.length === 1 ? '' : 's') + ' (' + m.mappings.map((x) => x.host).join(', ') + ')'] : []),
+    ];
+    return project + ' wants ' + listing(items) + ', but this sandbox started without ' + (items.length === 1 && !m.mappings.length ? 'it' : 'them') + '.';
+};
+/** "Set sandbox.vGpu (or the mappings) in your own settings to have them in every sandbox." */
+export const missingTip = (m) => {
+    const keys = [...m.settings, ...(m.memoryMb !== null ? ['sandbox.memoryMb'] : [])];
+    const what = keys.length ? listing(keys) + (m.mappings.length ? ' (or the mappings)' : '') : 'the mappings';
+    return 'Set ' + what + ' in your own settings to have them in every sandbox.';
+};
+/**
+ * The launch folder's config plus what the other projects mapped at boot want: their allowed .wsb devices, a fixed
+ * memory size larger than the launch's, and their mappings (placed with every other mapping at launch).
+ * `keepOff`: devices the launch folder's own .sandbox-config.json switched off; they stay off.
+ */
+export const widenForProjects = (launch, others, opts = {}) => {
+    const keepOff = opts.keepOff ?? [];
+    const exists = opts.exists ?? (() => true);
+    const config = _.cloneDeep(launch);
+    const widened = {};
+    const notes = [];
+    for (const setting of BOOT_SETTINGS) {
+        const by = others.find((o) => _.get(o.config, setting) === true);
+        if (!by || _.get(config, setting) === true)
+            continue;
+        if (keepOff.includes(setting)) {
+            notes.push(by.name + ' wants ' + (LABELS[setting] ?? setting) + ', but the launch folder\'s .sandbox-config.json switches it off, so it stays off.');
+            continue;
+        }
+        _.set(config, setting, true);
+        widened[setting] = by.name;
+        notes.push((LABELS[setting] ?? setting) + ' is on in this sandbox (for every project in it): ' + by.name + ' asks for it and you allowed it.');
+    }
+    for (const o of others) {
+        const mem = o.config.sandbox.memoryMb;
+        if (typeof mem === 'number' && typeof config.sandbox.memoryMb === 'number' && mem > config.sandbox.memoryMb)
+            config.sandbox.memoryMb = mem;
+        for (const m of o.config.mappings) {
+            if (config.mappings.some((x) => sameHost(x.host, m.host)))
+                continue;
+            if (m.optional && !exists(m.host))
+                continue;
+            if (!exists(m.host)) {
+                notes.push(o.name + ': mapped folder not found, skipped: ' + m.host);
+                continue;
+            }
+            // Where it appears (and moving it when that place is taken) is decided with every other mapping at launch.
+            config.mappings.push({ ...m, optional: true });
+        }
+    }
+    return { config, widened, notes };
 };

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

@@ -18,7 +18,7 @@ export declare const Config: z.ZodObject<{
     }, z.core.$strict>;
     mappings: z.ZodArray<z.ZodObject<{
         host: z.ZodString;
-        guest: z.ZodString;
+        guest: z.ZodOptional<z.ZodString>;
         readOnly: z.ZodBoolean;
         optional: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
@@ -278,6 +278,7 @@ export declare const Config: 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>;
 }, z.core.$strict>;
@@ -296,7 +297,7 @@ export declare const LocalOverrides: z.ZodObject<{
     }, z.core.$strict>>;
     mappings: z.ZodOptional<z.ZodArray<z.ZodObject<{
         host: z.ZodString;
-        guest: z.ZodString;
+        guest: z.ZodOptional<z.ZodString>;
         readOnly: z.ZodBoolean;
         optional: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;

package/dist/core/schema/config.js

@@ -52,7 +52,7 @@ export const LocalOverrides = z.strictObject({
     readOnly: z.boolean().describe('Map this project read-only.'),
     // 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 inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox.'),
+    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.'),
     // 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(),

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>;

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.'),
 });

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). */

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;
+};