windows-development-sandbox 1.4.0 → 1.4.1

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 { allowedAnswer, allowRequests, allowStorePath, applyOverrides, describeOverrides, isTrusted, loosenedRequests, saveAllowed, 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, plainText } 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,11 +90,12 @@ 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:');
@@ -96,16 +108,51 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
             saveTrust(store, local.path, local.hash);
             notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
         }
-        // A project may only tighten. What it asks for beyond that is used only if you allowed it for this project (asked
-        // once, interactively, never by --trust-config); otherwise it is named here instead of dropped silently.
+        // 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 loosenedRequests(config, overrides)) {
-            let ok = allowedAnswer(allowStore, local.path, ask.key, ask.wanted);
-            if (ok === null && req.ask && process.stdin.isTTY) {
-                ok = await req.ask('This project asks for ' + ask.key + ' = ' + JSON.stringify(ask.wanted) + ', which is looser than your settings (' + JSON.stringify(ask.yours) + '). Allow it for this project only?');
-                saveAllowed(allowStore, local.path, ask.key, ask.wanted, ok);
-            }
+        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 + ').');
@@ -126,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])
@@ -141,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/env.d.ts

@@ -1,5 +1,6 @@
 import { type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
 import type { GuestSession, SandboxStatus } from '../core/types.js';
+import type { BootProgressT } from '../shared/schema.js';
 export declare const isWin: boolean;
 export declare const dryRun: boolean;
 /** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
@@ -34,8 +35,11 @@ export declare const errMsg: (e: unknown) => string;
 export declare const exists: (p: string) => boolean;
 export declare const mkdirp: (p: string) => string;
 export declare const logPath: string;
-/** Best-effort: progress reporting must never be what breaks the boot. */
-export declare const setSandboxStatus: (phase: SandboxStatus["phase"], message: string) => void;
+/**
+ * Best-effort: progress reporting must never be what breaks the boot. `update` changes the structured progress
+ * (a new step, what is being set up); it stays as it was otherwise.
+ */
+export declare const setSandboxStatus: (phase: SandboxStatus["phase"], message: string, update?: Partial<BootProgressT>) => void;
 /** Runs a program, streaming output, and throws with a readable message when it fails. */
 export declare const exec: (file: string, args: string[], options?: SpawnSyncOptions) => void;
 /** exec without blocking: other toolchains keep downloading while this one runs an installer. */

package/dist/guest/env.js

@@ -36,18 +36,30 @@ export const errMsg = (e) => (e instanceof Error ? e.message : String(e));
 export const exists = (p) => fs.existsSync(p);
 export const mkdirp = (p) => { fs.mkdirSync(p, { recursive: true }); return p; };
 export const logPath = logFile;
-/** Best-effort: progress reporting must never be what breaks the boot. */
-export const setSandboxStatus = (phase, message) => {
+/** The boot's structured progress (the host shows it as one line); kept between status writes. */
+let progress;
+/**
+ * Best-effort: progress reporting must never be what breaks the boot. `update` changes the structured progress
+ * (a new step, what is being set up); it stays as it was otherwise.
+ */
+export const setSandboxStatus = (phase, message, update) => {
     try {
+        if (update)
+            progress = fitProgress({ step: 1, steps: 1, title: '', active: [], done: 0, total: 0, ...progress, ...update });
         writeJsonAtomicChecked(phase, message);
     }
     catch (e) {
         warn('Could not update sandbox status: ' + errMsg(e));
     }
 };
+/** Within the limits the host accepts (it drops a progress that is not). */
+const fitProgress = (p) => ({
+    ...p, title: p.title.slice(0, 120), done: Math.min(p.done, 1000), total: Math.min(p.total, 1000),
+    active: p.active.slice(0, 8).map((a) => ({ name: a.name.slice(0, 64), ...(a.percent === undefined ? {} : { percent: Math.max(0, Math.min(100, Math.round(a.percent))) }) })),
+});
 const ownAddresses = () => Object.values(os.networkInterfaces()).flat().filter((i) => Boolean(i) && i.family === 'IPv4' && !i.internal).map((i) => i.address).slice(0, 8);
 const writeJsonAtomicChecked = (phase, message) => {
-    writeJsonAtomic(run.sandbox, { launchId: session.launchId, phase, message, updatedAt: now(), workspaceHost: session.workspaceHost, guestWorkspace: workspace, headless: session.headless, addresses: ownAddresses() });
+    writeJsonAtomic(run.sandbox, { launchId: session.launchId, phase, message, updatedAt: now(), workspaceHost: session.workspaceHost, guestWorkspace: workspace, headless: session.headless, addresses: ownAddresses(), ...(progress ? { progress } : {}) });
 };
 /** Runs a program, streaming output, and throws with a readable message when it fails. */
 export const exec = (file, args, options = {}) => {

package/dist/guest/main.js

@@ -23,7 +23,11 @@ import { saveBootEnv } from './boot-env.js';
 import { primaryProject, saveProjectStatus } from './project-status.js';
 import { dataDir, dryRun, errMsg, isWin, localDir, log, logPath, logsDir, mkdirp, run, session, setSandboxStatus, toolsDir, warn, workspace } from './env.js';
 const STEPS = 8;
-const step = (n, title) => { log('\n\x1b[36m[' + n + '/' + STEPS + '] ' + title + '\x1b[0m'); setSandboxStatus(n === 1 ? 'booting' : 'provisioning', '[' + n + '/' + STEPS + '] ' + title); };
+const step = (n, title) => {
+    log('\n\x1b[36m[' + n + '/' + STEPS + '] ' + title + '\x1b[0m');
+    // The host shows the short title ("Developer tools") with what is being set up in it.
+    setSandboxStatus(n === 1 ? 'booting' : 'provisioning', '[' + n + '/' + STEPS + '] ' + title, { step: n, steps: STEPS, title: title.replace(/ \(.*\)$/, ''), active: [], done: 0, total: 0 });
+};
 const soft = async (what, work) => { try {
     await work();
 }

package/dist/guest/toolchains/index.js

@@ -1,8 +1,17 @@
+// Every developer toolchain and database the sandbox provides (the list is in plan.ts). Installers run in parallel (a
+// few at a time; downloads and installers do not block each other) and each is independent: one failing never blocks
+// the rest. A step that needs another (Rust links with MinGW's gcc, uv installs the Python tools) waits for it.
+// The boot runs it once for the launch folder; the session daemon runs it again for each project registered later,
+// possibly several at once, so the same kind of step (two Node installs, two Go installs) never runs twice at a time.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { watchDownloads } from '../../shared/download.js';
 import { log, mkdirp, setSandboxStatus } from '../env.js';
 import { emptyEnv, step, tool } from './common.js';
 import { plan } from './plan.js';
 /** How many installers run at once: enough to overlap downloads with installs, few enough not to thrash the disk. */
 const PARALLEL = 4;
+/** The step a download belongs to (several run at once), for its progress. */
+const currentStep = new AsyncLocalStorage();
 /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
 const locks = new Map();
 const lockKey = (name) => name.split(' ')[0].toLowerCase();
@@ -30,9 +39,17 @@ const runSteps = async (steps, o) => {
     const running = new Set();
     const waiting = [];
     let done = 0;
-    const say = o.report ?? ((message) => setSandboxStatus('provisioning', message));
+    // The boot (no `report`) also publishes structured progress: what runs now, how far its download is, how many are done.
+    const percent = new Map();
+    const active = () => [...running].map((name) => ({ name, ...(percent.has(name) ? { percent: percent.get(name) } : {}) }));
+    const say = o.report ?? ((message) => setSandboxStatus('provisioning', message, { active: active(), done, total: steps.length }));
     const report = () => { if (running.size)
         say('Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)'); };
+    if (!o.report)
+        watchDownloads(() => {
+            const name = currentStep.getStore();
+            return name ? (fraction) => { percent.set(name, Math.round(fraction * 100)); report(); } : null;
+        });
     for (const s of steps) {
         // Dependencies first (they are earlier in the plan, so their promises exist), then a free slot.
         finished.set(s.name, (async () => {
@@ -48,17 +65,26 @@ const runSteps = async (steps, o) => {
             running.add(s.name);
             report();
             try {
-                await exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name))));
+                await currentStep.run(s.name, () => exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name)))));
             }
             finally {
                 running.delete(s.name);
+                percent.delete(s.name);
                 done++;
                 report();
                 waiting.shift()?.();
             }
         })());
     }
-    await Promise.all(finished.values());
+    try {
+        await Promise.all(finished.values());
+    }
+    finally {
+        if (!o.report)
+            watchDownloads(null);
+    }
+    if (!o.report)
+        setSandboxStatus('provisioning', 'Set up ' + steps.length + ' toolchains and databases', { active: [], done, total: steps.length });
     return envs;
 };
 /** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */

package/dist/host/channel.d.ts

@@ -2,8 +2,8 @@ import type { GuestRequest, GuestResponse, Harness, SandboxStatus, SessionStatus
 import type { ProjectSpecT } from '../shared/schema.js';
 /** Where progress lines go: printed by default; a spinner passes its own. Text from the sandbox, made safe first. */
 export type Progress = (line: string) => void;
-/** Waits until the sandbox finished provisioning, reporting each boot step. */
-export declare const waitForReady: (dataPath: string, launchId: string | null, isAlive: () => boolean, progress?: Progress) => Promise<SandboxStatus>;
+/** Waits until the sandbox finished provisioning, reporting each boot step (onStatus: every status read, validated). */
+export declare const waitForReady: (dataPath: string, launchId: string | null, isAlive: () => boolean, progress?: Progress, onStatus?: (status: SandboxStatus) => void) => Promise<SandboxStatus>;
 export declare const sendRequest: (dataPath: string, request: GuestRequest) => void;
 export declare const waitForResponse: (dataPath: string, requestId: string, isAlive: () => boolean, timeoutMs: number) => Promise<GuestResponse>;
 /** project: a project registered after boot (provisioned first). harnessSpec: the agent's definition, for an agent the sandbox did not boot with. */

package/dist/host/channel.js

@@ -22,13 +22,14 @@ const until = async (timeoutMs, isAlive, poll, timeoutMessage) => {
     fail(timeoutMessage, 'Check what the sandbox is doing with sandbox logs -f (or sbx-show to see its window).');
 };
 const printLine = (line) => console.log(line);
-/** Waits until the sandbox finished provisioning, reporting each boot step. */
-export const waitForReady = (dataPath, launchId, isAlive, progress = (m) => printLine('  [sandbox] ' + m)) => {
+/** Waits until the sandbox finished provisioning, reporting each boot step (onStatus: every status read, validated). */
+export const waitForReady = (dataPath, launchId, isAlive, progress = (m) => printLine('  [sandbox] ' + m), onStatus) => {
     let last = '';
     return until(BOOT_TIMEOUT_MS, isAlive, () => {
         const status = readSandboxStatus(dataPath);
         if (!status || (launchId !== null && status.launchId !== launchId))
             return null;
+        onStatus?.(status);
         if (status.message !== last) {
             progress(safeText(status.message).slice(0, 300));
             last = status.message;

package/dist/host/generate.d.ts

@@ -8,6 +8,6 @@ export declare const decideProjectToolchains: (o: Pick<GenerateOptions, "run" |
  * started. `%` is doubled for cmd; a Windows path holds no quotes.
  */
 export declare const logonEnv: (workspace: string) => string;
-export declare const generateSandbox: (o: GenerateOptions) => Generated & {
+export declare const generateSandbox: (given: GenerateOptions) => Generated & {
     personalization: string;
 };

package/dist/host/generate.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
 import { readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
+import { widenForProjects } from '../core/project-policy.js';
 import { dirExists, ensureDir, fail, writeJson } from '../core/util.js';
 import { substDrives } from '../shared/guest-paths.js';
 import { PROJECTS_GUEST, hubName } from '../shared/projects.js';
@@ -43,7 +44,12 @@ const hostToolsOf = (probe) => ({
  * started. `%` is doubled for cmd; a Windows path holds no quotes.
  */
 export const logonEnv = (workspace) => '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\n';
-export const generateSandbox = (o) => {
+export const generateSandbox = (given) => {
+    // Several projects at boot: the sandbox also gets what the others want and you allowed (core/project-policy.ts).
+    const others = given.bootWants?.projects ?? [];
+    const boot = planBootProjects({ run: given.run, packageRoot: given.packageRoot, extraProjects: given.extraProjects, knownProjects: given.knownProjects });
+    const wide = widenForProjects(given.run.config, others, { keepOff: given.bootWants?.keepOff, exists: dirExists });
+    const o = { ...given, run: { ...given.run, config: wide.config } };
     const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
     const harness = harnessName === 'none' ? null : config.harnesses[harnessName] ?? fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', '));
     if (!dirExists(workspaceHost))
@@ -51,13 +57,13 @@ export const generateSandbox = (o) => {
     assertTestWritable(storageRoot);
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
-    const memoryMb = resolveMemoryMb(config.sandbox, o.freeMemoryBytes);
+    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     ensureDir(launchPath);
     ensureDir(dataPath);
-    const boot = planBootProjects({ run: o.run, packageRoot: o.packageRoot, extraProjects: o.extraProjects, knownProjects: o.knownProjects });
-    const mappings = collectMappings(o, launchPath, boot);
+    const mappingNotes = [];
+    const mappings = collectMappings(o, launchPath, boot, mappingNotes);
     const profile = harnessName === 'claude' ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets) : NO_PROFILE;
     stageGitIdentity(launchPath);
     const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
@@ -70,7 +76,8 @@ export const generateSandbox = (o) => {
         workspace: config.guestWorkspace,
         workspaceHost,
         projectsDir: PROJECTS_GUEST,
-        roots: boot.roots.map((r) => r.guest),
+        // Every folder mapped for other projects (roots and projects mapped at boot): the guest accepts projects in them.
+        roots: [...boot.roots, ...boot.projects].map((r) => r.guest),
         ...(o.autoSession === false ? { autoSession: false } : {}),
         harnessName,
         harness,
@@ -104,5 +111,5 @@ export const generateSandbox = (o) => {
     stageHooks(o.packageRoot, launchPath, o.run.scripts);
     const wsbPath = path.join(launchPath, 'agent.wsb');
     fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
-    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, mappings, profile, personalization, databases, toolchains: toolchainDecisions, projects: boot };
+    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, bootConfig: config, widened: wide.widened, mappings, profile, personalization, databases, toolchains: toolchainDecisions, projects: { ...boot, notes: [...boot.notes, ...wide.notes] }, mappingNotes };
 };

package/dist/host/join.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedRun } from '../core/types.js';
+import { type Missing } from '../core/project-policy.js';
 import { type ProjectSpecT } from '../shared/schema.js';
 import { type ProjectMapper, type RegistryEntry } from './projects.js';
 /** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
@@ -10,7 +11,11 @@ export interface Joined {
     spec: ProjectSpecT | null;
     run: ResolvedRun | null;
     notes: string[];
+    /** What it wants at boot that the running sandbox started without (it joined without them). */
+    missing: Missing | null;
 }
+/** What to do when a joining project wants something the running sandbox started without. */
+export type MissingChoice = 'continue' | 'restart' | 'cancel';
 /** The project spec the guest provisions from (scans the project folder like a launch does). */
 export declare const projectSpec: (run: ResolvedRun, entry: RegistryEntry, hooks: boolean) => ProjectSpecT;
 /**
@@ -25,4 +30,6 @@ export declare const joinRunning: (o: {
     wsbShare: boolean;
     resolve: (projectRoot: string) => Promise<ResolvedRun>;
     mapper?: ProjectMapper;
+    /** Asked before anything is registered when something is missing (default: continue without it). */
+    decide?: (name: string, missing: Missing) => Promise<MissingChoice>;
 }) => Promise<Joined>;

package/dist/host/join.js

@@ -2,18 +2,20 @@
 // resolve it (its approved .sandbox-config.json, versions, toolchain detection, database plan), checked against the
 // running sandbox's machine-wide protections, made visible inside (host/projects.ts: a project root, a project
 // mapped at boot, or wsb share) and described to the guest, which provisions what is missing before its session.
-// When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart.
+// When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart. So does a project
+// that wants what the sandbox only gets at its start (a .wsb device, more memory, its mappings) when you choose to
+// restart for it; otherwise it joins without them and they are named.
 import fs from 'node:fs';
 import path from 'node:path';
-import { checkJoin, protectionsOf } from '../core/project-policy.js';
+import { checkJoin, missingAtBoot, nothingMissing, protectionsOf } from '../core/project-policy.js';
 import { resolveToolchains } from '../core/detect-toolchains.js';
-import { assertNoLinks, fail } from '../core/util.js';
+import { assertNoLinks, dirExists, fail } from '../core/util.js';
 import { Id } from '../shared/schema.js';
 import { readSandboxStatus } from '../shared/rundir.js';
 import { syncProjectIn } from '../sync/watcher.js';
 import { planDatabases } from './database-plan.js';
 import { decideProjectToolchains } from './generate.js';
-import { projectHere, projectMapper, readRegistry, rememberProject, rootHere } from './projects.js';
+import { bootRecordOf, NeedsRestart, projectHere, projectMapper, readRegistry, rememberProject, rootHere } from './projects.js';
 import { stageScripts } from './launch/stage.js';
 import { addRepoSnapshot } from './repo-guard.js';
 /** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
@@ -44,15 +46,27 @@ export const projectSpec = (run, entry, hooks) => {
 export const joinRunning = async (o) => {
     const here = projectHere(o.storageRoot, o.hostDir);
     if (here?.project.primary)
-        return { ...here, spec: null, run: null, notes: [] };
+        return { ...here, spec: null, run: null, notes: [], missing: null };
     const registry = readRegistry(o.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again.');
     // A folder below a project already in the sandbox uses that project; anything else becomes a project of its own.
     const root = here?.project.host ?? path.resolve(o.hostDir);
     const run = await o.resolve(root);
-    const check = checkJoin(registry.protections, protectionsOf(run.config));
+    const check = checkJoin(registry.protections, protectionsOf(run.config), Object.keys(registry.atBoot?.widened ?? {}));
     if (check.stricter.length) {
         fail('This project needs stricter protection than the running sandbox has, and those settings are machine-wide:\n  ' + check.stricter.join('\n  '), 'Its sessions cannot get them without changing them for the sessions already running. Stop the sandbox (sandbox stop) and start it from ' + root + '.');
     }
+    // Boot-only wishes (a .wsb device you allowed for it, more memory, its mappings) the running sandbox lacks.
+    const launchPath = runningLaunchPath(o.storageRoot, o.dataPath);
+    const boot = bootRecordOf(o.storageRoot, launchPath);
+    const found = boot ? missingAtBoot(registry.protections, boot, run.config, dirExists) : null;
+    const missing = found && !nothingMissing(found) ? found : null;
+    if (missing) {
+        const choice = o.decide ? await o.decide(here?.project.name ?? path.basename(root), missing) : 'continue';
+        if (choice === 'cancel')
+            fail('Cancelled: nothing changed.');
+        if (choice === 'restart')
+            throw new NeedsRestart(root, 'it wants what the sandbox only gets at its start', missing);
+    }
     const mapper = o.mapper ?? projectMapper({ storageRoot: o.storageRoot, packageRoot: o.packageRoot, wsbShare: o.wsbShare });
     // Guarded from now on. A folder the sandbox could already write (inside a root, or mapped at boot) and that has no
     // snapshot from the launch gets an empty one: what is there now may have been planted, so it counts as new.
@@ -60,7 +74,6 @@ export const joinRunning = async (o) => {
     addRepoSnapshot(o.dataPath, root, { empty: Boolean(here) || Boolean(rootHere(o.storageRoot, root)) });
     const entry = mapper.register(root);
     rememberProject(o.storageRoot, entry.host);
-    const launchPath = runningLaunchPath(o.storageRoot, o.dataPath);
     // Your hooks in ~/.agent-sandbox/hooks ran at boot (once per sandbox); the project's own scripts ("scripts" in its
     // .sandbox-config.json, --script) run before its first agent. The launch folder is read-only for the sandbox, but
     // this side can still add them to it.
@@ -71,6 +84,7 @@ export const joinRunning = async (o) => {
         syncProjectIn(o.dataPath, { hostWorkspace: entry.host, guestWorkspace: entry.guest });
     }
     catch { /* history is a convenience; never block the session */ }
-    const notes = [...run.notes, ...check.looser.map((l) => 'The running sandbox is stricter: ' + l + '.')];
-    return { project: entry, guestDir: here ? here.guestDir : entry.guest, spec: projectSpec(run, entry, hooks), run, notes };
+    const notes = [...run.notes, ...check.looser.map((l) => 'The running sandbox is stricter: ' + l + '.'),
+        ...check.shared.map((s) => s + ' is on in this sandbox for another of its projects (you allowed it there); this project shares it.')];
+    return { project: entry, guestDir: here ? here.guestDir : entry.guest, spec: projectSpec(run, entry, hooks), run, notes, missing };
 };

package/dist/host/launch/mappings.d.ts

@@ -1,3 +1,8 @@
 import type { GenerateOptions, ResolvedMapping } from '../../core/types.js';
-import type { BootProjects } from './projects.js';
-export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects) => ResolvedMapping[];
+import { type BootProjects } from './projects.js';
+/**
+ * Every mapping, placed. Your extra folders never stop a launch because of their guest path: one the sandbox cannot
+ * use (reserved, invalid, or already in use) goes to C:\Mapped\<drive>\<path>, and `notes` says where and why. What
+ * does stop it (a folder that is not there, a whole drive, this tool's own folders) is listed in one message.
+ */
+export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects, notes?: string[]) => ResolvedMapping[];

package/dist/host/launch/mappings.js

@@ -1,38 +1,84 @@
+// Which folders are mapped into the sandbox: the launch folder, the data folder, the workspace, your extra folders and
+// the tools copied from this PC. Everything is checked before it can reach the .wsb.
+import path from 'node:path';
 import { assertNoGuestOverlap } from '../../core/config.js';
 import { assertSafeMapping } from '../../core/safe-paths.js';
-import { dirExists, fail } from '../../core/util.js';
-import { isValidGuestPath, sandboxFolder } from '../../shared/guest-paths.js';
+import { dirExists, errMsg, fail, isInsideOrEqual, UserError } from '../../core/util.js';
+import { shownByRoot } from './projects.js';
+import { deriveGuest, isValidGuestPath, placeGuest, sandboxFolder, tidyGuestPath } from '../../shared/guest-paths.js';
+import { PROJECTS_GUEST } from '../../shared/projects.js';
 import { GUEST } from './wsb.js';
 import { guestGitDir, planView } from '../workspace-view/index.js';
-export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
+/**
+ * Every mapping, placed. Your extra folders never stop a launch because of their guest path: one the sandbox cannot
+ * use (reserved, invalid, or already in use) goes to C:\Mapped\<drive>\<path>, and `notes` says where and why. What
+ * does stop it (a folder that is not there, a whole drive, this tool's own folders) is listed in one message.
+ */
+export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }, notes = []) => {
     const { config, dataPath, workspaceHost, harnessName } = o.run;
     assertGuestPath(config.guestWorkspace, 'guestWorkspace');
     // workspaceFilter: the sandbox gets the project's filtered view (no git-ignored files) and its real .git beside it.
     const view = planView(config, o.run.storageRoot, workspaceHost);
+    // A launch folder inside a project root is shown by the root, at the place it has whichever project starts the sandbox.
+    const inRoot = !view && shownByRoot(boot.roots, workspaceHost, config.guestWorkspace);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
         { host: dataPath, guest: GUEST.data, readOnly: false },
-        { host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+        ...(inRoot ? [] : [{ host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly }]),
         ...(view?.hostGit ? [{ host: view.hostGit, guest: guestGitDir(config.guestWorkspace), readOnly: config.readOnly }] : []),
     ];
+    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
+    const projects = [];
+    for (const m of [...boot.roots, ...boot.projects]) {
+        assertGuestPath(m.guest, 'project folder for ' + m.host);
+        projects.push({ host: m.host, guest: m.guest, readOnly: false });
+    }
+    const taken = [
+        { guest: config.guestWorkspace, what: 'the project' },
+        ...(view?.hostGit ? [{ guest: guestGitDir(config.guestWorkspace), what: 'the project\'s .git' }] : []),
+        { guest: PROJECTS_GUEST, what: 'the other projects' },
+        ...projects.map((p) => ({ guest: p.guest, what: p.host })),
+    ];
+    const outside = new Set((o.run.outsideMappings ?? []).map((h) => path.resolve(h).toLowerCase()));
+    const problems = [];
+    const missing = [];
+    const extra = [];
     for (const m of config.mappings) {
         const host = m.host;
-        assertGuestPath(m.guest, 'mappings[].guest for ' + host);
         if (!dirExists(host)) {
-            if (m.optional) {
-                console.warn('Skipping optional mapping (folder not found): ' + host);
-                continue;
-            }
-            fail('A mapped folder does not exist: ' + host, 'Create it, fix the path in your config, or mark the mapping "optional": true.');
+            if (m.optional)
+                missing.push(host);
+            else
+                problems.push(host + ': the folder does not exist. Fix: create it, correct the path, or mark the mapping "optional": true.');
+            continue;
         }
-        assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
-        mappings.push({ host, guest: m.guest, readOnly: m.readOnly });
-    }
-    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
-    for (const m of [...boot.roots, ...boot.projects]) {
-        assertGuestPath(m.guest, 'project folder for ' + m.host);
-        mappings.push({ host: m.host, guest: m.guest, readOnly: false });
+        try {
+            assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
+        }
+        catch (e) {
+            problems.push(errMsg(e) + (e instanceof UserError && e.fix ? ' Fix: ' + e.fix : ''));
+            continue;
+        }
+        // A folder inside the project with no guest path of its own is already there (unless the filtered view hides it).
+        if (!m.guest && !view && isInsideOrEqual(workspaceHost, host)) {
+            notes.push(host + ' is inside the project, so it is already in the sandbox at ' + deriveGuest(host, workspaceHost, config.guestWorkspace) + '.');
+            continue;
+        }
+        const wanted = tidyGuestPath(m.guest ?? deriveGuest(host, workspaceHost, config.guestWorkspace));
+        // The same folder at the same place twice (your settings and the project file): once is enough.
+        if (extra.some((x) => x.host.toLowerCase() === host.toLowerCase() && x.guest.toLowerCase() === wanted.toLowerCase()))
+            continue;
+        const placed = placeGuest(host, wanted, [...taken, ...extra.map((x) => ({ guest: x.guest, what: x.host }))]);
+        if (placed.note)
+            notes.push(placed.note);
+        const label = outside.has(path.resolve(host).toLowerCase()) ? 'outside the project, allowed' : undefined;
+        extra.push({ host, guest: placed.guest, readOnly: m.readOnly, ...(label ? { label } : {}) });
     }
+    if (problems.length)
+        fail((problems.length === 1 ? 'A mapped folder cannot be used:\n  ' : problems.length + ' mapped folders cannot be used:\n  ') + problems.join('\n  '));
+    if (missing.length)
+        notes.push('Skipped ' + (missing.length === 1 ? 'an optional folder' : missing.length + ' optional folders') + ' not on this PC: ' + missing.join(', '));
+    mappings.push(...extra, ...projects);
     const { probe } = o;
     if (probe.nodeDir)
         mappings.push({ host: probe.nodeDir, guest: GUEST.hostTools + '\\node', readOnly: true });
@@ -42,8 +88,8 @@ export const collectMappings = (o, launchPath, boot = { roots: [], projects: [],
         mappings.push({ host: probe.gitDir, guest: GUEST.hostTools + '\\git', readOnly: true });
     if (probe.nvmDir)
         mappings.push({ host: probe.nvmDir, guest: GUEST.hostTools + '\\nvm', readOnly: true });
+    // Placement keeps extra folders apart; this guards the rest (and where the folders really are: F:\x is C:\Mirror\F\x).
     assertNoGuestOverlap(mappings);
-    // Same check on where the folders really are (F:\x and C:\Mirror\F\x are one place).
     assertNoGuestOverlap(mappings.map((m) => ({ guest: sandboxFolder(m.guest) })));
     return mappings;
 };