windows-development-sandbox 1.0.5 → 1.1.0

package/dist/cli/commands/data/index.js

@@ -0,0 +1,45 @@
+// `sandbox data`: what persists between sandboxes (toolchains, databases, agent state, logs, host storage) and
+// removing chosen parts of it. Everything under the data folder is sandbox-writable: sizes and deletes never follow
+// links, and targets resolve strictly inside the data folder.
+import _ from 'lodash';
+import { diskUsage, humanBytes } from '../../../core/disk.js';
+import { fail } from '../../../core/util.js';
+import { printJson, table } from '../context.js';
+import { working } from '../../progress.js';
+import { dataClean } from './clean.js';
+import { collectDataEntries } from './collect.js';
+const AREA_LABEL = { tools: 'Toolchains', databases: 'Databases', state: 'Agent state', logs: 'Logs', data: 'Other', host: 'On this PC' };
+export const dataInfo = async (ctx) => {
+    const entries = await working('Measuring the saved data (big folders take a moment)', () => collectDataEntries(ctx.dataPath, ctx.storageRoot), !ctx.options.json);
+    const total = _.sumBy(entries, 'bytes');
+    const disks = diskUsage(ctx.storageRoot);
+    if (printJson(ctx, { dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, totalBytes: total, entries, disks }))
+        return 0;
+    console.log('Disks\n');
+    table([['DRIVE', 'USED', 'FREE', 'SIZE', ''], ...disks.map((d) => [d.drive, humanBytes(d.usedBytes) + ' (' + Math.round((d.usedBytes / d.totalBytes) * 100) + '%)', humanBytes(d.freeBytes), humanBytes(d.totalBytes), d.holdsStorage ? '<- sandbox storage (' + humanBytes(total) + ' of it)' : ''])]);
+    console.log('');
+    console.log('Persistent data for the sandbox: ' + ctx.dataPath + ' (C:\\AgentData inside)\n');
+    if (!entries.length) {
+        console.log('Nothing stored yet. Toolchains, databases and agent logins appear here after the first start.');
+        return 0;
+    }
+    const rows = _.flatMap(_.groupBy(entries, 'area'), (group, area) => [
+        [AREA_LABEL[area], humanBytes(_.sumBy(group, 'bytes')), ''],
+        ...group.map((e) => ['  ' + e.name, humanBytes(e.bytes), e.path]),
+    ]);
+    table([...rows, ['', '', ''], ['Total', humanBytes(total), '']]);
+    console.log('\nFree space with: sandbox data clean <target...>  (e.g. tools/go, databases/postgres-18, logs, launches)');
+    return 0;
+};
+/** `sandbox data [info|clean] [targets...]`. */
+export const data = (ctx) => {
+    const [action = 'info'] = ctx.options.positionals;
+    switch (action) {
+        case 'info':
+        case 'show':
+        case 'list': return dataInfo(ctx);
+        case 'clean':
+        case 'remove': return dataClean(ctx);
+        default: return fail('Unknown data action "' + action + '".', 'Use: sandbox data  (what is stored)  or  sandbox data clean <target...>');
+    }
+};

package/dist/cli/commands/data/remove.d.ts

@@ -0,0 +1,2 @@
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export declare const removeTree: (p: string, root: string) => void;

package/dist/cli/commands/data/remove.js

@@ -0,0 +1,30 @@
+// Deleting inside the data folder. The sandbox can write there, so links are removed themselves and never followed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, isLink, removeLink } from '../../../core/util.js';
+import { removeRefusal, safeRemove } from '../../../shared/safe-remove.js';
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export const removeTree = (p, root) => {
+    const unlinkInside = (dir) => {
+        for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+            const child = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(child))
+                removeLink(child);
+            else if (d.isDirectory())
+                unlinkInside(child);
+        }
+    };
+    if (isLink(p)) {
+        removeLink(p);
+        return;
+    }
+    if (!fs.existsSync(p))
+        return;
+    // Refused before anything is touched (safeRemove below checks again).
+    const refusal = removeRefusal(p, root);
+    if (refusal)
+        throw new Error('Refusing to delete ' + p + ': ' + refusal);
+    if (dirExists(p))
+        unlinkInside(p);
+    safeRemove(p, root);
+};

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

@@ -1,8 +1,10 @@
 export { createContext, type Context } from './context.js';
 export { launch } from './launch.js';
-export { setup } from './setup.js';
-export { data } from './data.js';
-export { repair, repairCommand } from './repair.js';
+export { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.js';
 export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
 export { account } from './accounts.js';
+export { projects } from './projects.js';
 export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/index.js

@@ -1,8 +1,10 @@
 export { createContext } from './context.js';
 export { launch } from './launch.js';
-export { setup } from './setup.js';
-export { data } from './data.js';
-export { repair, repairCommand } from './repair.js';
+export { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.js';
 export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
 export { account } from './accounts.js';
+export { projects } from './projects.js';
 export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

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

@@ -1,5 +1,29 @@
-import { attachTerminal } from '../../host/channel.js';
+import { attachTerminal } from '../../host/attach.js';
+import type { SandboxStatus } from '../../core/types.js';
 import { type Context } from './context.js';
+import { type Joined } from './project.js';
 /** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
 export declare const attachHere: (ctx: Context, session: Parameters<typeof attachTerminal>[0]) => Promise<number>;
-export declare const launch: (ctx: Context, generateOnly?: boolean) => 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>;
+/** The running sandbox, once it is ready. */
+export declare const readySandbox: (dataPath: string) => Promise<SandboxStatus>;
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export declare const openSession: (ctx: Context, ready: SandboxStatus, joined: Joined, o: {
+    attach: boolean;
+    harness?: string;
+    args?: string[];
+    reuse?: boolean;
+}) => Promise<number>;
+/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
+export interface LaunchExtras {
+    extraProjects?: string[];
+    autoSession?: boolean;
+    waitUntilReady?: boolean;
+}
+export declare const launch: (ctx: Context, generateOnly?: boolean, extras?: LaunchExtras) => Promise<number>;

package/dist/cli/commands/launch.js

@@ -1,20 +1,36 @@
-// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one.
+// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one. From a
+// folder the running sandbox does not have yet, the folder joins it (no restart) when it can, and otherwise a
+// restart that adds it is offered (restart.ts).
+import path from 'node:path';
+import fs from 'node:fs';
+import { select } from '@inquirer/prompts';
 import { activateAccount, activeAccount, defaultAccount } from '../../host/accounts.js';
-import { attachTerminal, findUnwatchedSession, requestSession, resetRunDir, waitForReady, waitForSession } from '../../host/channel.js';
+import { attachTerminal, findUnwatchedSession } from '../../host/attach.js';
+import { requestSession, resetRunDir, waitForReady, waitForSession } from '../../host/channel.js';
 import { describePrune, pruneStorage } from '../../host/cleanup.js';
 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 { ensureTerminal } from '../../host/terminal.js';
 import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
 import { readSandboxStatus } from '../../shared/rundir.js';
-import path from 'node:path';
-import fs from 'node:fs';
+import { isWithin } from '../../shared/projects.js';
 import { syncBeforeLaunch, watcherRunning } from '../../sync/watcher.js';
-import { errMsg, fail, sleep } from '../../core/util.js';
-import { askYesNo, resolveRun } from '../../core/workspace.js';
-import { currentGuestDir, sandboxAlive, table } from './context.js';
+import { protectionsOf } from '../../core/project-policy.js';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { errMsg, fail, isRootPath, sleep } from '../../core/util.js';
+import { syncAgentCommands } from './agent-commands.js';
+import { askYesNo } from '../../core/prompt.js';
+import { resolveRun } from '../../core/workspace.js';
+import { c } from '../colors.js';
+import { working } from '../progress.js';
+import { requireOnPc, sandboxAlive, table } from './context.js';
+import _ from 'lodash';
+import { hereDir, joinHere, readyHere } from './project.js';
+import { offerRestart } from './restart.js';
+import { addToList, setSetting } from './user-config.js';
 /** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
 export const attachHere = (ctx, session) => {
     if (ctx.loaded.config.attach.autoHide && !insideSandbox())
@@ -24,9 +40,9 @@ 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. Progress:';
+    'That takes a few minutes, once. Everything is kept, so every later start reuses it and takes seconds.';
 /** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
-const runningSandboxStatus = async (dataPath) => {
+export const runningSandboxStatus = async (dataPath) => {
     for (let i = 0; i < 60; i++) {
         const status = readSandboxStatus(dataPath);
         if (status)
@@ -35,28 +51,124 @@ 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.');
 };
-/** A sandbox is already running: open another agent session in it (new tab inside; optionally attach here). */
-const launchIntoRunning = async (ctx) => {
-    const { options, loaded, dataPath } = ctx;
+/** 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; }));
+};
+/** The running sandbox, once it is ready. */
+export const readySandbox = async (dataPath) => {
     const status = await runningSandboxStatus(dataPath);
-    const ready = status.phase === 'ready' ? status : await waitForReady(dataPath, status.launchId, sandboxAlive);
-    const cwd = currentGuestDir(ctx, ready.workspaceHost, ready.guestWorkspace);
-    const harness = options.harness ?? loaded.config.defaultHarness;
+    return status.phase === 'ready' ? status : waitForBoot(dataPath, status.launchId);
+};
+/** 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; }));
+};
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export const openSession = async (ctx, ready, joined, o) => {
+    const { options, loaded, dataPath } = ctx;
+    const cwd = joined.guestDir;
+    const harness = o.harness ?? options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+    const args = o.args ?? options.passthrough;
     // -t with nothing new for the agent: pick up this folder's session if no terminal on this PC shows it (its tab was
     // closed, or you detached). Someone already attached, --new, or agent arguments: a new session, as before.
-    const reuse = options.terminal && !options.newSession && options.passthrough.length === 0 && loaded.config.attach.reuseSession;
+    const reuse = (o.reuse ?? true) && o.attach && !options.newSession && args.length === 0 && loaded.config.attach.reuseSession;
     const existing = reuse ? await findUnwatchedSession(dataPath, harness, cwd) : null;
     if (existing) {
         console.log('Reattaching to ' + harness + ' session ' + existing.id + ' in ' + cwd + ' (no other terminal is attached; --new starts another).');
         return attachHere(ctx, existing);
     }
-    console.log('Sandbox already running: starting another ' + harness + ' session in ' + cwd);
-    const session = await waitForSession(dataPath, requestSession(dataPath, harness, options.passthrough, cwd), sandboxAlive);
-    if (options.terminal)
+    console.log(joined.spec
+        ? 'Starting ' + harness + ' for ' + joined.project?.host + ' in the running sandbox (' + cwd + '; the first time sets up what it needs).'
+        : 'Sandbox already running: starting another ' + harness + ' session in ' + cwd);
+    // The agent's definition goes along: the sandbox may have booted with another agent.
+    const harnessSpec = loaded.config.harnesses[harness];
+    const requestId = requestSession(dataPath, harness, args, cwd, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
+    const session = await waitForStart(ctx, requestId, 'Starting ' + harness + ' in ' + cwd);
+    if (o.attach)
         return attachHere(ctx, session);
     console.log('Session ' + session.id + ' opened in a new tab inside the sandbox. Attach here with: sandbox attach ' + session.id + (ready.headless ? '   (headless: sbx-show opens the window)' : ''));
     return 0;
 };
+/** The sessions a launch asks for: each --session, else one (the agent, in this folder). */
+const wantedSessions = (ctx) => ctx.options.sessions.length ? ctx.options.sessions : [{ harness: ctx.options.harness, folder: hereDir(ctx) }];
+/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
+const contextFor = (ctx, want) => ({ ...ctx, options: { ...ctx.options, workspace: want.folder, harness: want.harness, sessions: [], passthrough: [...ctx.options.passthrough, ...(want.args ?? [])] } });
+/** Several sessions at once: all requested together (projects set up in parallel), then listed; -t attaches the first. */
+const openSessions = async (ctx, ready, list) => {
+    const { dataPath, loaded, options } = ctx;
+    const requests = list.map(({ ctx: at, joined }) => {
+        const harness = at.options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+        const harnessSpec = loaded.config.harnesses[harness];
+        const id = requestSession(dataPath, harness, at.options.passthrough, joined.guestDir, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
+        return { id, harness, folder: at.options.workspace ?? joined.guestDir, cwd: joined.guestDir };
+    });
+    let started = 0;
+    const results = await working(() => 'Starting ' + requests.length + ' sessions (' + started + ' running)', () => Promise.allSettled(requests.map(async (r) => {
+        const s = await waitForSession(dataPath, r.id, sandboxAlive, 60 * 60 * 1000, () => undefined);
+        started++;
+        return s;
+    })));
+    table([['SESSION', 'AGENT', 'FOLDER', ''], ...requests.map((r, i) => {
+            const result = results[i];
+            return [r.id, r.harness, r.folder, result.status === 'fulfilled' ? 'running   sandbox attach ' + r.id : c.red('FAILED: ' + errMsg(result.reason))];
+        })]);
+    const first = results.find((r) => r.status === 'fulfilled');
+    if (options.terminal && first)
+        return attachHere(ctx, first.value);
+    if (!first)
+        return 1;
+    console.log('Each has its own tab inside the sandbox' + (ready.headless ? ' (headless: sbx-show opens the window)' : '') + '. Attach to any of them, from any terminal: sandbox attach');
+    return results.every((r) => r.status === 'fulfilled') ? 0 : 1;
+};
+/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
+const launchIntoRunning = async (ctx) => {
+    const ready = await readySandbox(ctx.dataPath);
+    const wants = wantedSessions(ctx);
+    // Every folder joins first: when one needs a restart, nothing has been started that the restart would end.
+    const joined = [];
+    const needs = [];
+    for (const want of wants) {
+        const at = ctx.options.sessions.length ? contextFor(ctx, want) : ctx;
+        try {
+            joined.push({ ctx: at, joined: await joinHere(at, ready) });
+        }
+        catch (e) {
+            if (!(e instanceof NeedsRestart))
+                throw e;
+            if (!needs.some((n) => n.hostDir.toLowerCase() === e.hostDir.toLowerCase()))
+                needs.push(e);
+        }
+    }
+    if (needs.length)
+        return offerRestart(ctx, needs, () => launchIntoRunning(ctx));
+    for (const note of _.uniq(joined.flatMap((j) => j.joined.notes)))
+        console.log(note);
+    if (joined.length === 1)
+        return openSession(joined[0].ctx, ready, joined[0].joined, { attach: ctx.options.terminal });
+    return openSessions(ctx, ready, joined);
+};
+/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
+const startIntoRunning = async (ctx) => {
+    const ready = await readySandbox(ctx.dataPath);
+    let joined;
+    try {
+        joined = await readyHere(ctx, ready);
+    }
+    catch (e) {
+        if (e instanceof NeedsRestart)
+            return offerRestart(ctx, [e], () => startIntoRunning(ctx));
+        throw e;
+    }
+    const where = joined.spec ? ' This folder is ready in it as ' + joined.guestDir + ' (sbx-shell ' + joined.spec.name + ' opens a terminal there inside).' : '';
+    console.log('A sandbox is already running' + (showSandboxWindow(ctx.storageRoot) ? '; its window is in front now.' : '.') + where + ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
+    return 0;
+};
 const syncSummary = (config, dataPath, workspaceHost) => {
     try {
         const s = syncBeforeLaunch(config, dataPath, workspaceHost);
@@ -66,6 +178,44 @@ const syncSummary = (config, dataPath, workspaceHost) => {
         return 'FAILED: ' + errMsg(e);
     }
 };
+/**
+ * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
+ * running sandbox without a restart. The answer is saved to your config.
+ */
+const maybeAddRoot = async (ctx, run) => {
+    const { projects } = run.config;
+    const parent = path.dirname(run.workspaceHost);
+    if (!projects.askToAddRoot || ctx.options.yes || !process.stdin.isTTY || !process.stdout.isTTY)
+        return;
+    if (projects.roots.some((r) => isWithin(r, run.workspaceHost)) || projects.declinedRoots.some((d) => isWithin(d, parent) && isWithin(parent, d)))
+        return;
+    if (isRootPath(parent))
+        return;
+    try {
+        assertSafeWorkspace(parent, ctx.packageRoot, run.storageRoot);
+        assertSafeMapping(parent, ctx.packageRoot, run.storageRoot);
+    }
+    catch {
+        return;
+    }
+    const answer = await select({
+        message: 'Map ' + parent + ' at every start, so other projects there (also new ones) open in the running sandbox without a restart? Agents in the sandbox can then see every project in it.',
+        choices: [
+            { name: 'Yes, from now on', value: 'yes' },
+            { name: 'No (and do not ask again for this folder)', value: 'no' },
+            { name: 'Never ask this again', value: 'never' },
+        ],
+    });
+    if (answer === 'yes') {
+        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).');
+    }
+    if (answer === 'no')
+        addToList(ctx, ['projects', 'declinedRoots'], parent);
+    if (answer === 'never')
+        setSetting(ctx, ['projects', 'askToAddRoot'], false);
+};
 /** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
 const prepare = async (ctx, run) => {
     const { options, dataPath, storageRoot } = ctx;
@@ -77,22 +227,38 @@ const prepare = async (ctx, run) => {
     const history = syncSummary(config, dataPath, run.workspaceHost);
     const guarded = checkRepo(dataPath);
     if (guarded.length)
-        console.warn('\x1b[33mSECURITY: neutralised ' + guarded.length + ' change(s) the last sandbox made that could run code on this PC (see sandbox status).\x1b[0m');
-    saveRepoSnapshot(dataPath, run.workspaceHost);
+        console.warn(c.yellow('SECURITY: neutralised ' + guarded.length + ' change(s) the last sandbox made that could run code on this PC (see sandbox status).'));
     resetRunDir(dataPath);
     return { account, terminal: terminal.message, history, pruned: describePrune(pruneStorage(storageRoot)) };
 };
-export const launch = async (ctx, generateOnly = false) => {
+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.
     if (loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
         options.terminal = true;
-    if (!generateOnly && isSandboxRunning()) {
-        if (!options.noAgent)
-            return launchIntoRunning(ctx);
-        // Only one Windows Sandbox can run: "start" on a running one brings its window up instead.
-        console.log('A sandbox is already running' + (showSandboxWindow(storageRoot) ? '; its window is in front now.' : '.') + ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
-        return 0;
+    if (!generateOnly)
+        requireOnPc('launch');
+    // agentCommands (Beta) follows the config: a setting changed in the file takes effect here too. Never blocks a launch.
+    if (!generateOnly) {
+        try {
+            syncAgentCommands(ctx, loaded.config);
+        }
+        catch (e) {
+            console.warn('Agent commands (Beta): ' + errMsg(e));
+        }
+    }
+    if (!generateOnly && isSandboxRunning())
+        return options.noAgent ? startIntoRunning(ctx) : launchIntoRunning(ctx);
+    // Several sessions: the sandbox starts from the first one's folder with the others' folders mapped too, then
+    // they all open in it (each project is set up on demand, in parallel). One --session is an ordinary launch.
+    const wants = options.sessions;
+    if (wants.length === 1)
+        return launch(contextFor(ctx, wants[0]), generateOnly, extras);
+    if (wants.length > 1) {
+        const first = contextFor(ctx, wants[0]);
+        const others = _.uniqBy(wants.slice(1).map((w) => w.folder).filter((f) => !isWithin(wants[0].folder, f)), (f) => f.toLowerCase());
+        const started = await launch({ ...first, options: { ...first.options, terminal: false } }, generateOnly, { ...extras, extraProjects: [...(extras.extraProjects ?? []), ...others], autoSession: false, waitUntilReady: true });
+        return generateOnly || started !== 0 ? started : launchIntoRunning(ctx);
     }
     const run = await resolveRun({
         packageRoot, loaded, cwd: process.cwd(), workspace: options.workspace, harness: options.harness, noAgent: options.noAgent,
@@ -102,45 +268,60 @@ export const launch = async (ctx, generateOnly = false) => {
     const { config } = run;
     if (!generateOnly)
         assertCanLaunch();
+    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) });
-    for (const note of run.notes)
+    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])
         console.log(note);
     const secretFiles = config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
-    if (secretFiles.length)
-        console.warn('\x1b[33mHeads-up: the agent can read these files in your workspace, which often hold secrets: ' + secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '') + '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.\x1b[0m');
+    if (secretFiles.length) {
+        const shown = secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '');
+        console.warn(c.yellow('Heads-up: the agent can read these files in your workspace, which often hold secrets: ' + shown + '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.'));
+    }
+    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   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: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
         ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
         ...(prepared ? [['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)'],
         ...(generated.databases.length
-            ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; see hostAccess.forwards)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
+            ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; use Postgres or SQLite for local work)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
             : [['Databases', 'none needed (databases.<name>.enabled = true adds one)']]),
         ['Desktop', generated.personalization],
         ['Claude', generated.profile.staged.length ? generated.profile.staged.join(', ') + (generated.profile.credentials ? '  (INCLUDING YOUR LOGIN)' : '') : 'no settings copied'],
         ['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'],
-        ...generated.mappings.slice(3).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest]),
+        ...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', generated.wsbPath],
     ]);
     if (generateOnly)
         return 0;
+    // 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 });
+    rememberProject(storageRoot, run.workspaceHost);
     startSandbox(generated.wsbPath);
     // Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently.
     if (!watcherRunning(dataPath))
         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;
-    if (options.terminal || options.noAgent) {
-        console.log(firstBoot(dataPath) ? FIRST_BOOT : 'Waiting for the sandbox (everything it needs is installed already; this takes seconds) ...');
-        await waitForReady(dataPath, generated.launchId, sandboxAlive);
+    if (options.terminal || options.noAgent || extras.waitUntilReady) {
+        if (firstBoot(dataPath))
+            console.log(FIRST_BOOT);
+        await waitForBoot(dataPath, generated.launchId);
+        if (extras.waitUntilReady)
+            return 0;
         // Without an agent there is no session to attach to: the sandbox itself is the result.
         if (options.noAgent) {
             console.log('Sandbox ready. Its window has a terminal in ' + config.guestWorkspace + '; from here: sandbox exec -- <command>, sandbox stop.');
             return 0;
         }
-        return attachHere(ctx, await waitForSession(dataPath, generated.launchId, sandboxAlive));
+        return attachHere(ctx, await waitForStart(ctx, generated.launchId, 'Starting ' + run.harnessName));
     }
     if (firstBoot(dataPath))
         console.log(FIRST_BOOT);

package/dist/cli/commands/maintenance.js

@@ -5,9 +5,11 @@ 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 { fail, safeText, sleep, writeJson } from '../../core/util.js';
+import { expandPath, fail, safeText, sleep, writeJson } from '../../core/util.js';
+import { readKnown, readRegistry } from '../../host/projects.js';
+import { detectWsb } from '../../host/wsb.js';
 import { describePrune, pruneStorage } from '../../host/cleanup.js';
-import { doctorRows, hostClaude, isSandboxRunning } from '../../host/platform.js';
+import { doctorRows, hostClaude, insideSandbox, isSandboxRunning } from '../../host/platform.js';
 import { readSandboxStatus } from '../../shared/rundir.js';
 import { syncBack, watch } from '../../sync/watcher.js';
 import { table } from './context.js';
@@ -44,6 +46,8 @@ export const logs = async (ctx) => {
         printed = from + buffer.length;
     };
     print();
+    if (ctx.options.follow)
+        console.error('(following; Ctrl+C to stop)');
     while (ctx.options.follow) {
         await sleep(1000);
         print();
@@ -103,8 +107,17 @@ const checkLocalConfig = (ctx) => {
     return 0;
 };
 export const config = (ctx) => {
-    const [action = 'show'] = ctx.options.positionals;
+    const [action = 'summary'] = ctx.options.positionals;
     switch (action) {
+        case 'summary':
+            table([
+                ['Settings file', ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet; sandbox config init creates it)'],
+                ['Default agent', ctx.loaded.config.defaultHarness],
+                ['Storage', ctx.storageRoot],
+                ['Memory', String(ctx.loaded.config.sandbox.memoryMb) + (ctx.loaded.config.sandbox.memoryMb === 'auto' ? '' : ' MB')],
+            ]);
+            console.log('\nChange settings in the menu (sandbox > Settings). All of them as JSON: sandbox config show');
+            return 0;
         case 'path':
             console.log(ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet)');
             return 0;
@@ -118,7 +131,23 @@ export const config = (ctx) => {
     }
 };
 export const doctor = (ctx) => {
-    table(doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath));
+    const rows = doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath);
+    // Inside a sandbox the feature and "running" rows describe the sandbox itself, and the host rows describe nothing useful.
+    if (insideSandbox()) {
+        table([['Where', 'inside a Windows Sandbox started by this tool (run doctor on your PC to check the PC)'], ...rows.filter(([name]) => name === 'Config file')]);
+        return 0;
+    }
+    // Several projects: the roots mapped at every start, what the running sandbox has, and whether wsb share is there.
+    const p = ctx.loaded.config.projects;
+    const registry = isSandboxRunning() ? readRegistry(ctx.storageRoot) : null;
+    const wsb = p.wsbShare ? detectWsb() : null;
+    table([
+        ...rows,
+        ['Project roots', p.roots.length ? p.roots.map((r) => expandPath(r, ctx.loaded.base)).join(', ') : 'none (sandbox projects roots add <folder>)'],
+        ['All projects', p.all ? 'on: ' + readKnown(ctx.storageRoot).length + ' known project(s) mapped at every start (' + p.exclude.length + ' excluded)' : 'off'],
+        ['Projects running', registry ? registry.projects.map((x) => x.name + ' (' + x.mechanism + ')').join(', ') : '-'],
+        ['wsb share', !p.wsbShare ? 'off (projects.wsbShare)' : wsb ? 'available: ' + wsb.exe + (wsb.version ? ' ' + wsb.version : '') + ' (untested; a failure offers a restart instead)' : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox): folders outside your roots need a restart'],
+    ]);
     return 0;
 };
 export const claudeHost = (ctx) => hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);

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

@@ -0,0 +1,29 @@
+import type { SandboxStatus } from '../../core/types.js';
+import { type RegistryEntry } from '../../host/projects.js';
+import type { ProjectSpecT } from '../../shared/schema.js';
+import { type Context } from './context.js';
+/** The folder the command is about: --workspace, else the current one. */
+export declare const hereDir: (ctx: Context) => string;
+export interface Located {
+    project: RegistryEntry | null;
+    guestDir: string | null;
+}
+/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
+export declare const locateHere: (ctx: Context, status: SandboxStatus | null) => Located;
+export interface Joined {
+    project: RegistryEntry | null;
+    guestDir: string;
+    spec: ProjectSpecT | null;
+    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>;
+/** 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. */
+export declare const readyHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;