windows-development-sandbox 1.4.0 → 1.4.1

package/.sandbox-config.example.json

@@ -8,7 +8,8 @@
     "rust": { "enabled": false }
   },
   "mappings": [
-    { "host": "D:\\Assets\\textures", "guest": "C:\\Assets", "readOnly": true, "optional": true }
+    { "host": "./data", "guest": "C:\\Data", "readOnly": true, "optional": true },
+    { "host": "D:\\Assets\\textures", "readOnly": true, "optional": true }
   ],
   "scripts": []
 }

package/config.example.json

@@ -377,6 +377,7 @@
     "roots": [],
     "askToAddRoot": true,
     "declinedRoots": [],
+    "allowOutsideMappings": "ask",
     "wsbShare": true
   }
 }

package/dist/cli/boot-progress.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxStatus } from '../core/types.js';
+/** One progress line: `line` is shown, `key` changes only when the step or what runs changes, `what` names it. */
+export interface Shown {
+    line: string;
+    key: string;
+    what: string;
+}
+/** "[3/8] Developer tools: downloading rust 40%, setting up go (2 of 6 done)". */
+export declare const bootLine: (status: SandboxStatus | null, fallback?: string) => Shown;
+/** Nothing new for a while: say so, and where the details are. */
+export declare const stillWorking: (what: string, ms: number) => string;
+export declare const readyIn: (ms: number) => string;
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export declare const pendingDownloads: (wanted: string[], has: (dir: string) => boolean) => {
+    names: string[];
+    mb: number;
+};
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export declare const firstStartNotice: (first: boolean, pending: {
+    names: string[];
+    mb: number;
+}) => string | null;

package/dist/cli/boot-progress.js

@@ -0,0 +1,59 @@
+// What the terminal says while a sandbox starts: the first-start heads-up (what is downloaded, roughly how much) and
+// one line of progress from the guest's status. Pure: the status is guest-written, so every bit of it is made safe
+// and short here.
+import { plainText } from '../core/util.js';
+import { elapsed } from './progress.js';
+const clean = (text, max) => plainText(text).replace(/\s+/g, ' ').trim().slice(0, max);
+/** "[3/8] Developer tools: downloading rust 40%, setting up go (2 of 6 done)". */
+export const bootLine = (status, fallback = 'Starting Windows Sandbox') => {
+    if (!status)
+        return { line: fallback, key: fallback, what: fallback.toLowerCase() };
+    const p = status.progress;
+    if (!p) {
+        const line = clean(status.message, 200) || fallback;
+        return { line, key: line, what: line };
+    }
+    const title = clean(p.title, 60);
+    const items = p.active.slice(0, 8).map((a) => ({ name: clean(a.name, 40), percent: a.percent }));
+    const loading = items.filter((a) => a.percent !== undefined && a.percent < 100);
+    const others = items.filter((a) => !loading.includes(a));
+    const parts = [
+        ...(loading.length ? ['downloading ' + loading.map((a) => a.name + ' ' + a.percent + '%').join(', ')] : []),
+        ...(others.length ? ['setting up ' + others.map((a) => a.name).join(', ')] : []),
+    ];
+    const count = p.total > 0 && items.length ? ' (' + Math.min(p.done, p.total) + ' of ' + p.total + ' done)' : '';
+    const head = '[' + p.step + '/' + p.steps + '] ' + title;
+    return {
+        line: (head + (parts.length ? ': ' + parts.join('; ') : '') + count).slice(0, 240),
+        key: head + '|' + items.map((a) => a.name).sort().join(','),
+        what: items.length ? items.map((a) => a.name).join(', ') : title,
+    };
+};
+/** Nothing new for a while: say so, and where the details are. */
+export const stillWorking = (what, ms) => 'Still working on ' + clean(what, 80) + ' (' + Math.max(1, Math.round(ms / 60000)) + ' min). Full log: sandbox logs -f';
+export const readyIn = (ms) => 'Ready in ' + elapsed(ms) + '.';
+// ---- the first-start heads-up ----------------------------------------------------------------------------------------
+/** What a first start downloads, by setting name: its folder in <data>\tools, rough size and a readable name. */
+const DOWNLOADS = {
+    node: { dir: 'nvm', mb: 30 }, python: { dir: 'python', mb: 30 }, rust: { dir: 'rust', mb: 300 }, msvc: { dir: 'msvc', mb: 1500, label: 'MSVC' },
+    cpp: { dir: 'mingw', mb: 270, label: 'C/C++' }, dotnet: { dir: 'dotnet', mb: 250, label: '.NET' }, go: { dir: 'go', mb: 80 }, java: { dir: 'java', mb: 200 },
+    ruby: { dir: 'ruby', mb: 100 }, php: { dir: 'php', mb: 30 }, deno: { dir: 'deno', mb: 40 }, pwsh: { dir: 'pwsh', mb: 100, label: 'PowerShell 7' },
+    vscode: { dir: 'vscode', mb: 150, label: 'VS Code' },
+    postgres: { dir: 'postgres', mb: 330, label: 'PostgreSQL' }, mysql: { dir: 'mariadb', mb: 90, label: 'MariaDB' }, mongodb: { dir: 'mongodb', mb: 450, label: 'MongoDB' },
+    redis: { dir: 'redis', mb: 10 }, dynamodb: { dir: 'dynamodb-local', mb: 80, label: 'DynamoDB Local' },
+};
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export const pendingDownloads = (wanted, has) => {
+    const missing = [...new Set(wanted)].filter((w) => Object.hasOwn(DOWNLOADS, w) && !has(DOWNLOADS[w].dir));
+    return { names: missing.map((w) => DOWNLOADS[w].label ?? w), mb: missing.reduce((sum, w) => sum + DOWNLOADS[w].mb, 0) };
+};
+const roughSize = (mb) => (mb >= 950 ? (Math.round(mb / 100) / 10) + ' GB' : Math.max(10, Math.round(mb / 10) * 10) + ' MB');
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export const firstStartNotice = (first, pending) => {
+    if (!first && !pending.names.length)
+        return null;
+    const what = pending.names.length ? ' (about ' + roughSize(pending.mb) + ': ' + pending.names.slice(0, 8).join(', ') + (pending.names.length > 8 ? ', ...' : '') + ')' : '';
+    return first
+        ? 'First start: the sandbox downloads the tools this project needs once' + what + '. This can take 5-20 minutes depending on your connection; later starts take about a minute.'
+        : 'New tools for this project: the sandbox downloads them once' + what + '. This can take a few minutes; later starts skip it.';
+};

package/dist/cli/commands/launch.d.ts

@@ -6,8 +6,11 @@ import { type Joined } from './project.js';
 export declare const attachHere: (ctx: Context, session: Parameters<typeof attachTerminal>[0]) => Promise<number>;
 /** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
 export declare const runningSandboxStatus: (dataPath: string) => Promise<SandboxStatus>;
-/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
-export declare const waitForBoot: (dataPath: string, launchId: string | null) => Promise<SandboxStatus>;
+/**
+ * Waits for the boot with its current step and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export declare const waitForBoot: (dataPath: string, launchId: string | null, timed?: boolean) => Promise<SandboxStatus>;
 /** The running sandbox, once it is ready. */
 export declare const readySandbox: (dataPath: string) => Promise<SandboxStatus>;
 /**

package/dist/cli/commands/launch.js

@@ -12,7 +12,7 @@ import { generateSandbox } from '../../host/generate.js';
 import { findSecretFiles } from '../../host/secrets.js';
 import { checkRepo, saveRepoSnapshot } from '../../host/repo-guard.js';
 import { assertCanLaunch, insideSandbox, isSandboxRunning, probeHost, spawnDetached, startSandbox } from '../../host/platform.js';
-import { NeedsRestart, rememberProject, startRegistry } from '../../host/projects.js';
+import { NeedsRestart, readKnown, rememberProject, startRegistry } from '../../host/projects.js';
 import { ensureConpty, ensureTerminal } from '../../host/terminal.js';
 import { planView, saveActiveViews, viewSkipped, WorkspaceView } from '../../host/workspace-view/index.js';
 import { saveForwards } from '../../host/port-forward.js';
@@ -23,14 +23,18 @@ import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
 import { readSandboxStatus } from '../../shared/rundir.js';
 import { isWithin } from '../../shared/projects.js';
 import { syncBeforeLaunch, watcherRunning } from '../../sync/watcher.js';
-import { protectionsOf } from '../../core/project-policy.js';
+import { BOOT_SETTINGS, protectionsOf } from '../../core/project-policy.js';
+import { LOCAL_CONFIG_NAME } from '../../core/local-config.js';
 import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
-import { errMsg, fail, isRootPath, sleep } from '../../core/util.js';
+import { dirExists, errMsg, fail, fileExists, isRootPath, sleep } from '../../core/util.js';
+import { planBootProjects } from '../../host/launch/projects.js';
 import { syncAgentCommands } from './agent-commands.js';
 import { askYesNo } from '../../core/prompt.js';
-import { resolveRun } from '../../core/workspace.js';
+import { autoGuestWorkspace, placeInRoot, resolveRun } from '../../core/workspace.js';
+import { planMirrorWorkspace } from '../../shared/guest-paths.js';
 import { c } from '../colors.js';
-import { working } from '../progress.js';
+import { follow, working } from '../progress.js';
+import { bootLine, firstStartNotice, pendingDownloads, readyIn, stillWorking } from '../boot-progress.js';
 import { requireOnPc, sandboxAlive, table } from './context.js';
 import _ from 'lodash';
 import { hereDir, joinHere, readyHere } from './project.js';
@@ -45,8 +49,11 @@ export const attachHere = (ctx, session) => {
 };
 /** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
 const firstBoot = (dataPath) => !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
-const FIRST_BOOT = 'First start for this storage: the sandbox downloads and installs the toolchains, databases and agent this project needs.\n' +
-    'That takes a few minutes, once. Everything is kept, so every later start reuses it and takes seconds.';
+/** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
+const FIRST_BOOT = (dataPath, generated, config) => {
+    const wanted = ['node', ...Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name]) => name), ...(config.toolchains.vscode.enabled ? ['vscode'] : []), ...generated.databases.map((d) => d.database)];
+    return firstStartNotice(firstBoot(dataPath), pendingDownloads(wanted, (dir) => fs.existsSync(path.join(dataPath, 'tools', dir))));
+};
 /** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
 export const runningSandboxStatus = async (dataPath) => {
     for (let i = 0; i < 60; i++) {
@@ -57,10 +64,18 @@ export const runningSandboxStatus = async (dataPath) => {
     }
     return fail('A Windows Sandbox is running that this tool did not start (or that uses another storage.dataName).', 'Close that sandbox window first, then run sandbox claude again.');
 };
-/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
-export const waitForBoot = (dataPath, launchId) => {
-    let step = 'starting Windows Sandbox';
-    return working(() => 'Waiting for the sandbox: ' + step, () => waitForReady(dataPath, launchId, sandboxAlive, (m) => { step = m; }));
+/**
+ * Waits for the boot with its current step and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export const waitForBoot = async (dataPath, launchId, timed = false) => {
+    let status = null;
+    const start = Date.now();
+    const ready = await follow(() => bootLine(status), () => waitForReady(dataPath, launchId, sandboxAlive, () => undefined, (s) => { if (s.phase !== 'failed')
+        status = s; }), { stall: stillWorking });
+    if (timed)
+        console.log(readyIn(Date.now() - start));
+    return ready;
 };
 /** The running sandbox, once it is ready. */
 export const readySandbox = async (dataPath) => {
@@ -70,7 +85,8 @@ export const readySandbox = async (dataPath) => {
 /** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
 const waitForStart = (ctx, requestId, what) => {
     let step = 'starting';
-    return working(() => what + ': ' + step, () => waitForSession(ctx.dataPath, requestId, sandboxAlive, 60 * 60 * 1000, (m) => { step = m; }));
+    const shown = () => ({ line: what + ': ' + step, key: step, what: step });
+    return follow(shown, () => waitForSession(ctx.dataPath, requestId, sandboxAlive, 60 * 60 * 1000, (m) => { step = m; }), { stall: stillWorking });
 };
 /**
  * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
@@ -216,6 +232,14 @@ const maybeAddRoot = async (ctx, run) => {
         addToList(ctx, ['projects', 'roots'], parent);
         run.config.projects.roots.push(parent);
         console.log('Added ' + parent + ' to projects.roots (sandbox projects roots remove ' + parent + ' undoes it).');
+        // From now on this project is under the root's folder inside the sandbox, from this start on (one move, not two).
+        const before = run.config.guestWorkspace;
+        const derived = [autoGuestWorkspace(run.workspaceHost), planMirrorWorkspace(run.workspaceHost, autoGuestWorkspace(run.workspaceHost)).guest];
+        // In place: the caller holds run.config already.
+        if (derived.some((g) => g.toLowerCase() === before.toLowerCase()))
+            run.config.guestWorkspace = placeInRoot(run.config, run.workspaceHost, Boolean(run.mirror), run.notes).guestWorkspace;
+        if (run.config.guestWorkspace !== before)
+            console.log('Inside the sandbox this project is now at ' + run.config.guestWorkspace + ' (was ' + before + '): git worktrees made at the old place need `git worktree repair` once.');
     }
     if (answer === 'no')
         addToList(ctx, ['projects', 'declinedRoots'], parent);
@@ -263,6 +287,32 @@ const prepare = async (ctx, run) => {
     const filter = await prepareWorkspaceView(ctx, run);
     return { account, terminal: terminal.message + '; pseudo console: ' + conpty, history, pruned: describePrune(pruneStorage(storageRoot)), filter };
 };
+/**
+ * The other projects mapped at boot (a restart's, --session's, projects.all's, and the known projects in your roots),
+ * with their effective configs: only approved .sandbox-config.json files and the looser values you allowed for each
+ * (nothing is asked here). The sandbox boots with what they want too (generate.ts).
+ */
+const bootWantsFor = async (ctx, run, extraProjects) => {
+    const { roots } = run.config.projects;
+    const planned = planBootProjects({ run, packageRoot: ctx.packageRoot, extraProjects }).projects.map((p) => p.host);
+    const inRoots = readKnown(run.storageRoot).map((k) => k.host).filter((h) => roots.some((r) => isWithin(path.resolve(r), h)));
+    const folders = _.uniqBy([...(extraProjects ?? []).map((p) => path.resolve(p)), ...planned, ...inRoots], (f) => f.toLowerCase())
+        .filter((f) => !isWithin(run.workspaceHost, f) && dirExists(f)).slice(0, 200);
+    const projects = [];
+    const notes = [];
+    for (const folder of folders) {
+        try {
+            const other = await resolveRun({ packageRoot: ctx.packageRoot, loaded: ctx.loaded, cwd: folder, workspace: folder, noAgent: true, noLocalConfig: false, trustConfig: false, scripts: [] });
+            projects.push({ name: path.basename(folder), config: other.config });
+        }
+        catch (e) {
+            if (fileExists(path.join(folder, LOCAL_CONFIG_NAME)))
+                notes.push('What ' + path.basename(folder) + ' asks for at boot is not included: ' + errMsg(e).split('\n')[0]);
+        }
+    }
+    const keepOff = BOOT_SETTINGS.filter((s) => _.get(ctx.loaded.config, s) === true && _.get(run.config, s) === false);
+    return { wants: { projects, keepOff }, notes };
+};
 export const launch = async (ctx, generateOnly = false, extras = {}) => {
     const { options, loaded, packageRoot, dataPath, storageRoot } = ctx;
     // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
@@ -303,8 +353,11 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
     if (!generateOnly && !extras.extraProjects)
         await maybeAddRoot(ctx, run);
     const prepared = generateOnly ? null : await prepare(ctx, run);
-    const generated = generateSandbox({ packageRoot, run, harnessArgs: options.passthrough, probe: probeHost(config, run.harnessName), extraProjects: extras.extraProjects, autoSession: extras.autoSession });
-    for (const note of [...run.notes, ...generated.projects.notes])
+    const bootWants = await bootWantsFor(ctx, run, extras.extraProjects);
+    const generated = generateSandbox({ packageRoot, run, harnessArgs: options.passthrough, probe: probeHost(config, run.harnessName), extraProjects: extras.extraProjects, autoSession: extras.autoSession, bootWants: bootWants.wants });
+    // What the sandbox boots with (the launch folder's settings plus what the other projects at boot want).
+    const booted = generated.bootConfig;
+    for (const note of [...run.notes, ...bootWants.notes, ...generated.projects.notes, ...generated.mappingNotes])
         console.log(note);
     const secretFiles = config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
     if (secretFiles.length) {
@@ -314,7 +367,7 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
     const { roots, projects } = generated.projects;
     table([
         ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
-        ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   CPU: ' + (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') + '   Network: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
+        ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   CPU: ' + (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') + '   Network: ' + booted.sandbox.networking + (booted.sandbox.vGpu ? '   vGPU' : '') + (config.sandbox.headless ? '   HEADLESS' : '')],
         ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
         ...(prepared ? [['Ignored files', prepared.filter], ['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
         ['Toolchains', Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name, d]) => name + ' (' + d.reason + ')').join(', ') || 'Node only (nothing else used by this project)'],
@@ -326,7 +379,7 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
         ['Secrets', !config.secrets.strip ? 'NOT stripped (secrets.strip is off)' : generated.profile.secretsRemoved.length ? 'kept on this PC: ' + generated.profile.secretsRemoved.join(', ') + '  (secrets.allow lets one through)' : 'none found in what is copied'],
         ...roots.map((r, i) => [i ? '' : 'Project roots', r.host + '  ->  ' + r.guest + '  (every project in it opens without a restart)']),
         ...projects.map((p, i) => [i ? '' : 'Projects', p.host + '  ->  ' + p.guest]),
-        ...generated.mappings.slice(3).filter((m) => ![...roots, ...projects].some((p) => p.guest === m.guest)).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest]),
+        ...generated.mappings.slice(2).filter((m) => m.guest !== config.guestWorkspace && ![...roots, ...projects].some((p) => p.guest === m.guest)).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest + (m.label ? '  (' + m.label + ')' : '')]),
         ['Generated', generated.wsbPath],
     ]);
     if (generateOnly)
@@ -334,7 +387,8 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
     // Every folder the sandbox can write is snapshotted before it starts (the guard compares against this), and the
     // projects it starts with are recorded host-side for the commands that run later.
     saveRepoSnapshot(dataPath, run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
-    startRegistry(storageRoot, { launchId: generated.launchId, protections: protectionsOf(config), primary: { host: run.workspaceHost, guest: config.guestWorkspace }, roots, boot: projects });
+    startRegistry(storageRoot, { launchId: generated.launchId, protections: protectionsOf(booted), primary: { host: run.workspaceHost, guest: config.guestWorkspace }, roots, boot: projects,
+        atBoot: { memoryMb: generated.memoryMb, mappings: generated.mappings, widened: generated.widened } });
     rememberProject(storageRoot, run.workspaceHost);
     startLife(storageRoot, dataPath, config.sandbox.keepAwake);
     startSandbox(generated.wsbPath);
@@ -343,10 +397,11 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
         spawnDetached(ctx.entry, ['_watch', ...(options.config ? ['--config', path.resolve(options.config)] : [])]);
     // Hiding runs alongside; a failure to find the window must never break the launch or an attach.
     const hidden = config.sandbox.headless ? hideSandboxWindow(storageRoot).catch(() => false) : null;
+    const headsUp = FIRST_BOOT(dataPath, generated, config);
     if (options.terminal || options.noAgent || extras.waitUntilReady) {
-        if (firstBoot(dataPath))
-            console.log(FIRST_BOOT);
-        await waitForBoot(dataPath, generated.launchId);
+        if (headsUp)
+            console.log(headsUp);
+        await waitForBoot(dataPath, generated.launchId, Boolean(headsUp));
         if (extras.waitUntilReady)
             return 0;
         // Without an agent there is no session to attach to: the sandbox itself is the result.
@@ -356,8 +411,8 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
         }
         return attachHere(ctx, await waitForStart(ctx, generated.launchId, 'Starting ' + run.harnessName));
     }
-    if (firstBoot(dataPath))
-        console.log(FIRST_BOOT);
+    if (headsUp)
+        console.log(headsUp + '\nFollow along: sandbox logs -f');
     if (hidden)
         console.log(await hidden ? 'Sandbox running headless. Open the window: sbx-show   Attach here: sandbox claude -t' : 'Could not find the sandbox window to hide (it may still be starting); run sandbox hide in a moment.');
     else

package/dist/cli/commands/maintenance.js

@@ -4,8 +4,9 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import _ from 'lodash';
 import { DEFAULTS, userConfigPath, userDir } from '../../core/config.js';
-import { describeOverrides, isTrusted, LOCAL_CONFIG_NAME, normalizeOverrides, readLocalConfig, trustStorePath } from '../../core/local-config.js';
-import { assertNoLinks, expandPath, fail, plainText, safeText, sleep, writeJson } from '../../core/util.js';
+import { allowedAnswer, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, trustStorePath } from '../../core/local-config.js';
+import { guestWorkspaceOf, previewGuest } from '../../core/workspace.js';
+import { assertNoLinks, dirExists, expandPath, fail, plainText, safeText, sleep, writeJson } from '../../core/util.js';
 import { humanBytes } from '../../core/disk.js';
 import { AuditLog } from '../../host/audit/log.js';
 import { readKnown, readRegistry } from '../../host/projects.js';
@@ -107,8 +108,40 @@ const checkLocalConfig = (ctx) => {
     const overrides = normalizeOverrides(file.data, dir, file.path);
     const approved = isTrusted(trustStorePath(ctx.storageRoot), file.path, file.hash);
     console.log(file.path + ': valid. ' + (approved ? 'Approved (this exact version).' : 'Not approved yet: the next launch asks you.') + '\n');
-    for (const line of describeOverrides(overrides))
+    for (const line of describeOverrides(overrides, dir))
         console.log('  ' + safeText(line));
+    // What a launch from here would do with each folder and each looser setting, without launching.
+    const config = ctx.loaded.config;
+    const store = allowStorePath(ctx.storageRoot);
+    const workspaceGuest = guestWorkspaceOf(applyOverrides(config, overrides), dir).guest;
+    const outside = outsideMappings(dir, overrides.mappings);
+    const policy = config.projects.allowOutsideMappings;
+    const rows = (overrides.mappings ?? []).map((m) => {
+        const where = previewGuest(m, dir, workspaceGuest);
+        const status = !dirExists(m.host) ? (m.optional ? 'not on this PC: skipped' : c.red('the folder does not exist: create it, fix the path, or add "optional": true'))
+            : !outside.includes(m) ? (m.guest ? 'inside the project' : 'inside the project (already in the sandbox there)')
+                : policy === true ? 'outside the project, allowed (projects.allowOutsideMappings is true)'
+                    : policy === false ? c.red('outside the project: refused (projects.allowOutsideMappings is false)')
+                        : allowedAnswer(store, file.path, OUTSIDE_FOLDER, outsideKey(m)) === true ? 'outside the project, allowed (you said yes)'
+                            : c.yellow('outside the project: the next interactive launch asks you');
+        return [(m.readOnly ? 'ro ' : 'rw ') + safeText(m.host), '->  ' + safeText(where.guest), status];
+    });
+    if (rows.length) {
+        console.log('\nFolders (where they appear in the sandbox):');
+        table(rows);
+    }
+    for (const m of overrides.mappings ?? []) {
+        const note = dirExists(m.host) ? previewGuest(m, dir, workspaceGuest).note : null;
+        if (note)
+            console.log('  ' + safeText(note));
+    }
+    const looser = loosenedRequests(config, overrides);
+    if (looser.length)
+        console.log('\nLooser than your settings (used only if you allow it for this project):');
+    for (const a of looser) {
+        const answer = allowedAnswer(store, file.path, a.key, a.wanted);
+        console.log('  ' + a.key + ' = ' + JSON.stringify(a.wanted) + ': ' + (answer === true ? 'allowed (you said yes)' : answer === false ? 'not used (you said no)' : 'the next interactive launch asks you'));
+    }
     return 0;
 };
 export const config = (ctx) => {

package/dist/cli/commands/project.d.ts

@@ -1,4 +1,5 @@
 import type { SandboxStatus } from '../../core/types.js';
+import { type Missing } from '../../core/project-policy.js';
 import { type RegistryEntry } from '../../host/projects.js';
 import type { ProjectSpecT } from '../../shared/schema.js';
 import { type Context } from './context.js';
@@ -17,12 +18,15 @@ export interface Joined {
     harness: string | null;
     notes: string[];
 }
-/**
- * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
- * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
- * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
- */
-export declare const joinHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;
+/** restart.ts: the sandbox was restarted for a project in this command. */
+export declare const markRestarted: () => void;
+export declare const joinHere: (ctx: Context, status: SandboxStatus, o?: {
+    noRestart?: boolean;
+}) => Promise<Joined>;
+/** The command that restarts the running sandbox with this folder's boot wishes (consent given by --yes). */
+export declare const restartCommand: (ctx: Context, host: string) => string;
+/** Joined without what it wants at boot: what is missing, how to restart with it, and how to always have it. */
+export declare const missingNotes: (ctx: Context, name: string, host: string, missing: Missing, shown?: boolean) => string[];
 /** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
 export declare const provisionJoined: (ctx: Context, joined: Joined) => Promise<void>;
 /** joinHere, then (for another project) waits until the sandbox has set it up. */

package/dist/cli/commands/project.js

@@ -2,13 +2,17 @@
 // these, so they all agree: `locateHere` only looks (attach, sessions, status, restart), `joinHere` also makes the
 // folder a project of the running sandbox when it can without a restart (launch, start, exec, db).
 import path from 'node:path';
+import { select } from '@inquirer/prompts';
+import { describeMissing, missingTip } from '../../core/project-policy.js';
 import { askYesNo } from '../../core/prompt.js';
 import { isInsideOrEqual } from '../../core/util.js';
 import { resolveRun } from '../../core/workspace.js';
-import { prepareProject } from '../../host/channel.js';
+import { currentSessions, prepareProject } from '../../host/channel.js';
 import { projectHere, readRegistry } from '../../host/projects.js';
 import { joinRunning } from '../../host/join.js';
+import { c } from '../colors.js';
 import { working } from '../progress.js';
+import { describeSessions } from './restart.js';
 import { guestPathFor, sandboxAlive } from './context.js';
 /** The folder the command is about: --workspace, else the current one. */
 export const hereDir = (ctx) => path.resolve(ctx.options.workspace ?? process.cwd());
@@ -28,12 +32,16 @@ export const locateHere = (ctx, status) => {
  * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
  * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
  */
-export const joinHere = async (ctx, status) => {
+let restartedOnce = false;
+/** restart.ts: the sandbox was restarted for a project in this command. */
+export const markRestarted = () => { restartedOnce = true; };
+export const joinHere = async (ctx, status, o = {}) => {
     const { options, loaded, packageRoot, storageRoot, dataPath } = ctx;
     const dir = hereDir(ctx);
     // A sandbox started before projects existed: only its launch folder (guestPathFor explains why otherwise).
     if (!readRegistry(storageRoot))
         return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace), spec: null, harness: null, notes: [] };
+    let shown = false;
     const joined = await joinRunning({
         storageRoot, dataPath, packageRoot, hostDir: dir, wsbShare: loaded.config.projects.wsbShare,
         resolve: (root) => resolveRun({
@@ -41,10 +49,41 @@ export const joinHere = async (ctx, status) => {
             noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases,
             nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
         }),
+        // Something it wants only comes with a restart: --yes restarts, a terminal asks, anything else continues.
+        decide: async (name, missing) => {
+            // Once per command: what a restart could not give (see the launch notes) never restarts it again.
+            if (o.noRestart || restartedOnce)
+                return 'continue';
+            if (options.yes)
+                return 'restart';
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                return 'continue';
+            console.log(c.yellow(describeMissing(name, missing)));
+            shown = true;
+            const sessions = currentSessions(dataPath);
+            return select({
+                message: 'What now?',
+                choices: [
+                    { name: 'Continue anyway (join without them)', value: 'continue' },
+                    { name: 'Restart with them (' + (sessions.length ? describeSessions(sessions) + ' will end' : 'no session is running') + ')', value: 'restart' },
+                    { name: 'Cancel', value: 'cancel' },
+                ],
+                default: 'continue',
+            });
+        },
     });
     const harness = joined.run && joined.run.harnessName !== 'none' ? joined.run.harnessName : null;
-    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes: joined.notes };
+    const notes = joined.missing ? [...joined.notes, ...missingNotes(ctx, joined.project.name, joined.project.host, joined.missing, shown)] : joined.notes;
+    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes };
 };
+/** The command that restarts the running sandbox with this folder's boot wishes (consent given by --yes). */
+export const restartCommand = (ctx, host) => 'sandbox ' + (ctx.options.noAgent ? 'start' : ctx.options.harness ?? ctx.loaded.config.defaultHarness) + ' --workspace "' + host + '" --yes';
+/** Joined without what it wants at boot: what is missing, how to restart with it, and how to always have it. */
+export const missingNotes = (ctx, name, host, missing, shown = false) => [
+    ...(shown ? [] : [c.yellow(describeMissing(name, missing))]),
+    'Joined without them. To restart the sandbox with them (its sessions end): ' + restartCommand(ctx, host),
+    c.dim(missingTip(missing)),
+];
 /** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
 export const provisionJoined = async (ctx, joined) => {
     if (!joined.spec)

package/dist/cli/commands/restart.js

@@ -5,6 +5,7 @@
 // where the agent supports it) and then starts the new project's session.
 import path from 'node:path';
 import _ from 'lodash';
+import { missingTip } from '../../core/project-policy.js';
 import { askYesNo } from '../../core/prompt.js';
 import { fail, safeText, sleep } from '../../core/util.js';
 import { currentSessions, execInSandbox } from '../../host/channel.js';
@@ -44,14 +45,20 @@ export const offerRestart = async (ctx, needs, then) => {
     const registry = readRegistry(ctx.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 from ' + folders[0] + '.');
     const primary = registry.projects.find((p) => p.primary) ?? fail('The running sandbox has no launch folder on record.', 'Stop it (sandbox stop) and start it again.');
     const sessions = currentSessions(ctx.dataPath);
-    for (const need of needs)
+    // A project that only wants boot settings or folders: you already chose the restart (or gave --yes) when asked.
+    const hidden = needs.filter((n) => !n.missing);
+    for (const need of hidden)
         console.log(c.yellow('Windows Sandbox cannot add ' + need.hostDir + ' while it runs: ' + need.reason + '.'));
-    console.log('A restart maps ' + (needs.length === 1 ? 'it' : 'them') + ' as well (and keeps ' + registry.projects.map((p) => p.host).join(', ') + '). ' +
+    console.log((hidden.length ? 'A restart maps ' + (hidden.length === 1 ? 'it' : 'them') + ' as well' : 'Restarting with what ' + needs.map((n) => path.basename(n.hostDir)).join(', ') + ' wants') +
+        ' (and keeps ' + registry.projects.map((p) => p.host).join(', ') + '). ' +
         (sessions.length ? describeSessions(sessions) + ' will end' : 'No session is running') + '; your files, tools, databases and logins are kept. It takes about a minute.');
-    for (const parent of _.uniq(folders.map((f) => path.dirname(f))))
+    for (const parent of _.uniq(hidden.map((n) => path.dirname(n.hostDir))))
         console.log(c.dim('No restart next time for folders in ' + parent + ': sandbox projects roots add "' + parent + '"'));
+    for (const need of needs)
+        if (need.missing)
+            console.log(c.dim(missingTip(need.missing)));
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    if (!ctx.options.yes) {
+    if (!ctx.options.yes && hidden.length) {
         if (!interactive)
             fail('Not restarting without your consent.', 'Run it again with --yes to restart: ' + againWithYes(ctx));
         if (!(await askYesNo('Restart the sandbox now?'))) {
@@ -62,9 +69,10 @@ export const offerRestart = async (ctx, needs, then) => {
     const reopen = sessionsToReopen(registry, sessions);
     const resume = reopen.length > 0 && (ctx.options.yes || (await askYesNo('Reopen the ' + reopen.length + ' session(s) afterwards (continuing their conversations where the agent supports it)?', true)));
     await stopAndWait(ctx);
-    // Imported here: launch.ts imports this file.
+    // Imported here: launch.ts imports this file (and project.ts imports describeSessions).
     const { launch, openSession, readySandbox } = await import('./launch.js');
-    const { joinHere } = await import('./project.js');
+    const { joinHere, markRestarted } = await import('./project.js');
+    markRestarted();
     const keep = registry.projects.filter((p) => !p.primary && p.mechanism !== 'root').map((p) => p.host);
     const relaunch = { ...ctx, options: { ...ctx.options, workspace: primary.host, harness: ctx.options.harness ?? ctx.options.sessions[0]?.harness, terminal: false, noAgent: false, newSession: true, passthrough: [], sessions: [] } };
     await launch(relaunch, false, { extraProjects: [...keep, ...folders], autoSession: false, waitUntilReady: true });
@@ -73,7 +81,9 @@ export const offerRestart = async (ctx, needs, then) => {
         for (const s of reopen) {
             const at = { ...ctx, options: { ...ctx.options, workspace: s.hostDir, harness: s.harness, terminal: false, newSession: true, passthrough: [], sessions: [] } };
             try {
-                const joined = await joinHere(at, ready);
+                const joined = await joinHere(at, ready, { noRestart: true });
+                for (const note of joined.notes)
+                    console.log(note);
                 await openSession(at, ready, joined, { attach: false, harness: s.harness, args: ctx.loaded.config.harnesses[s.harness]?.resumeArguments ?? [], reuse: false });
             }
             catch (e) {

package/dist/cli/commands/sessions.js

@@ -161,7 +161,8 @@ const printExecResult = (result) => {
 const guestFolderHere = async (ctx, what) => {
     const ready = await readySandbox(ctx.dataPath);
     try {
-        const joined = await joinHere(ctx, ready);
+        // A command needs no restart for what the project wants at boot: it runs without them (and says so).
+        const joined = await joinHere(ctx, ready, { noRestart: true });
         for (const note of joined.notes)
             console.error(note);
         await provisionJoined(ctx, joined);

package/dist/cli/manifest.js

@@ -57,7 +57,7 @@ const SANDBOX_OPTIONS = [
     bool('--window', 'show the sandbox window even if config says headless', { advanced: true }),
     bool('--trust-config', 'approve the folder\'s .sandbox-config.json without asking', { advanced: true }),
     bool('--no-local-config', 'ignore the folder\'s .sandbox-config.json', { advanced: true }),
-    bool('--yes', 'when this folder is not in the running sandbox and adding it needs a restart, restart without asking', { noMenu: true }),
+    bool('--yes', 'when this folder is not in the running sandbox, or wants what it started without (vGPU, folders), restart without asking', { noMenu: true }),
 ];
 const AGENT_OPTIONS = [
     text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),

package/dist/cli/progress.d.ts

@@ -2,6 +2,21 @@
 export declare const canAnimate: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
 /** "12 s", "2 min 5 s". */
 export declare const elapsed: (ms: number) => string;
+/** One line of progress: `line` is shown, `key` changes when it is worth a new plain line, `what` names what runs. */
+export interface Progressing {
+    line: string;
+    key: string;
+    what: string;
+}
+/**
+ * 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 declare const follow: <T>(show: () => Progressing, work: () => Promise<T>, o: {
+    stallMs?: number;
+    stall: (what: string, ms: number) => string;
+}) => Promise<T>;
 /**
  * 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.