windows-development-sandbox 1.0.5 → 1.4.0

package/dist/cli/commands/launch.js

@@ -1,20 +1,42 @@
-// `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 { ensureTerminal } from '../../host/terminal.js';
+import { NeedsRestart, 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';
+import { saveAuditSettings } from '../../host/audit/collect.js';
+import { readDataSize, saveMarkedProjects } from '../../host/motw.js';
+import { humanBytes } from '../../core/disk.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';
+import { lastStopWarning, startLife, UPDATE_RESTART_WARNING, updateRestartPending } from '../../host/stops.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 +46,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 +57,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 +184,63 @@ 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);
+};
+/**
+ * workspaceFilter: brings the project's filtered view in step before the sandbox maps it, and tells the background
+ * watcher to keep it in step while the sandbox runs. Returns the line for the launch table.
+ */
+const prepareWorkspaceView = async (ctx, run) => {
+    const plan = planView(run.config, ctx.storageRoot, run.workspaceHost);
+    saveActiveViews(ctx.storageRoot, ctx.dataPath, plan ? [plan.options] : []);
+    saveForwards(ctx.storageRoot, ctx.dataPath, run.config.sandbox.networking ? run.config.network.forwardPorts : []);
+    saveAuditSettings(ctx.storageRoot, ctx.dataPath, { ...run.config.audit, projects: [run.workspaceHost] });
+    saveMarkedProjects(ctx.storageRoot, ctx.dataPath, run.config.storage.markSandboxFiles ? [run.workspaceHost] : []);
+    const size = readDataSize(ctx.storageRoot, ctx.dataPath);
+    const limit = run.config.storage.warnDataGb;
+    if (limit > 0 && size && size.bytes > limit * 1024 ** 3)
+        console.warn(c.yellow('The persisted data takes ' + humanBytes(size.bytes) + ' (more than storage.warnDataGb, ' + limit + ' GB). See what: sandbox data; free space: sandbox data clean <what>.'));
+    if (!plan)
+        return viewSkipped(run.config, run.workspaceHost) ?? 'off (git-ignored files are visible in the sandbox; workspaceFilter.enabled keeps them out)';
+    const stats = await working('Preparing the workspace without its git-ignored files', () => new WorkspaceView(plan.options).prepare());
+    return 'on: git-ignored files stay on this PC' + (stats.toView || stats.toHost ? ' (' + stats.toView + ' copied in, ' + stats.toHost + ' out' + (stats.conflicts ? ', ' + stats.conflicts + ' conflicts kept next to the file' : '') + ')' : '') + '; ' + plan.options.view;
+};
 /** 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;
@@ -74,25 +249,48 @@ const prepare = async (ctx, run) => {
     if (account && run.harnessName === 'claude' && account !== activeAccount(dataPath))
         activateAccount(storageRoot, dataPath, account);
     const terminal = config.provisioning.terminal.enabled ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false }) : { exe: null, message: 'disabled' };
+    const conpty = config.provisioning.conpty.enabled ? await ensureConpty(dataPath, config.provisioning.refresh) : 'off';
     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).'));
+    const stopped = lastStopWarning(storageRoot, dataPath, watcherRunning(dataPath));
+    if (stopped)
+        console.warn(c.yellow(stopped));
+    if (updateRestartPending())
+        console.warn(c.yellow(UPDATE_RESTART_WARNING));
     resetRunDir(dataPath);
-    return { account, terminal: terminal.message, history, pruned: describePrune(pruneStorage(storageRoot)) };
+    const filter = await prepareWorkspaceView(ctx, run);
+    return { account, terminal: terminal.message + '; pseudo console: ' + conpty, history, pruned: describePrune(pruneStorage(storageRoot)), filter };
 };
-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 +300,61 @@ 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]] : []),
+        ...(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)'],
         ...(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);
+    startLife(storageRoot, dataPath, config.sandbox.keepAwake);
     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.d.ts

@@ -6,3 +6,5 @@ export declare const config: (ctx: Context) => number;
 export declare const doctor: (ctx: Context) => number;
 export declare const claudeHost: (ctx: Context) => number;
 export declare const watcher: (ctx: Context) => Promise<void>;
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export declare const audit: (ctx: Context) => Promise<number>;

package/dist/cli/commands/maintenance.js

@@ -5,12 +5,17 @@ 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 { assertNoLinks, 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';
+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';
+import { printJson, table } from './context.js';
+import { c } from '../colors.js';
 export const sync = (ctx) => {
     const running = isSandboxRunning();
     const result = syncBack(ctx.dataPath, !running);
@@ -26,6 +31,8 @@ const newestLog = (dir) => {
 };
 export const logs = async (ctx) => {
     const dir = path.join(ctx.dataPath, 'logs');
+    // The sandbox writes this folder: never read through a link it planted there.
+    assertNoLinks(ctx.dataPath, dir);
     const file = newestLog(dir) ?? fail('No sandbox logs yet in ' + dir + '.', 'Logs appear after the first start (sandbox claude).');
     console.log('== ' + file + ' ==');
     let printed = 0;
@@ -44,6 +51,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 +112,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,8 +136,52 @@ 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);
 export const watcher = (ctx) => watch(ctx.dataPath);
+const KINDS = ['proc', 'file', 'session', 'guard', 'note'];
+const KIND_LABEL = { proc: 'program', file: 'file', session: 'session', guard: 'GUARD', note: 'note' };
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export const audit = async (ctx) => {
+    const settings = ctx.loaded.config.audit;
+    const kind = ctx.options.kind;
+    if (kind && !KINDS.includes(kind))
+        fail('Unknown kind "' + kind + '".', 'Use one of: ' + KINDS.join(', '));
+    const log = new AuditLog(AuditLog.dirFor(ctx.storageRoot, ctx.dataPath), settings);
+    const events = log.read({ days: ctx.options.days, kinds: kind ? [kind] : undefined, grep: ctx.options.grep });
+    if (printJson(ctx, events))
+        return 0;
+    if (!events.length) {
+        console.log(settings.enabled ? 'Nothing in the audit log for the last ' + ctx.options.days + ' day(s).' : 'The audit log is off. Turn it on in the menu (Settings > Security & privacy > Audit log) or with audit.enabled in your config.');
+        return 0;
+    }
+    for (const e of events) {
+        // What the sandbox reported is text from the sandbox: no control codes reach your terminal.
+        const [p, cmd, parent, dir, act] = [e.p, e.c, e.pp, e.w, e.a].map((v) => plainText(v ?? ''));
+        const what = e.k === 'proc' ? (cmd || p) + (parent ? c.dim('  <- ' + path.win32.basename(parent)) : '')
+            : e.k === 'file' ? act + ' ' + p + c.dim('  in ' + dir)
+                : e.k === 'session' ? act + ' ' + p + c.dim('  ' + dir + ' ' + cmd)
+                    : p;
+        console.log(c.dim(new Date(e.t).toLocaleString()) + '  ' + (e.k === 'guard' ? c.yellow(KIND_LABEL[e.k].padEnd(8)) : KIND_LABEL[e.k].padEnd(8)) + what + (e.n && e.n > 1 ? c.dim('  x' + e.n) : ''));
+    }
+    console.log(c.dim('\n' + events.length + ' event(s); the log takes ' + humanBytes(log.bytes()) + ' (' + AuditLog.dirFor(ctx.storageRoot, ctx.dataPath) + ').'));
+    return 0;
+};

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

package/dist/cli/commands/project.js

@@ -0,0 +1,63 @@
+// Which project of the running sandbox a command is run from. Every command that works on a running sandbox uses
+// 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 { askYesNo } from '../../core/prompt.js';
+import { isInsideOrEqual } from '../../core/util.js';
+import { resolveRun } from '../../core/workspace.js';
+import { prepareProject } from '../../host/channel.js';
+import { projectHere, readRegistry } from '../../host/projects.js';
+import { joinRunning } from '../../host/join.js';
+import { working } from '../progress.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());
+/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
+export const locateHere = (ctx, status) => {
+    const dir = hereDir(ctx);
+    const here = projectHere(ctx.storageRoot, dir);
+    if (here)
+        return here;
+    // A sandbox started before projects existed: only its launch folder.
+    if (!readRegistry(ctx.storageRoot) && status && isInsideOrEqual(status.workspaceHost, dir))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace) };
+    return { project: null, guestDir: null };
+};
+/**
+ * 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 const joinHere = async (ctx, status) => {
+    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: [] };
+    const joined = await joinRunning({
+        storageRoot, dataPath, packageRoot, hostDir: dir, wsbShare: loaded.config.projects.wsbShare,
+        resolve: (root) => resolveRun({
+            packageRoot, loaded, cwd: root, workspace: root, harness: options.harness, noAgent: options.noAgent,
+            noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases,
+            nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
+        }),
+    });
+    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 };
+};
+/** 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)
+        return;
+    const spec = joined.spec;
+    let step = 'starting';
+    await working(() => 'Setting up ' + spec.name + ' in the running sandbox: ' + step, () => prepareProject(ctx.dataPath, spec, sandboxAlive, (m) => { step = m; }));
+};
+/** joinHere, then (for another project) waits until the sandbox has set it up. */
+export const readyHere = async (ctx, status) => {
+    const joined = await joinHere(ctx, status);
+    for (const note of joined.notes)
+        console.log(note);
+    await provisionJoined(ctx, joined);
+    return joined;
+};

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

@@ -0,0 +1,14 @@
+import { type Context } from './context.js';
+interface Row {
+    folder: string;
+    here: boolean;
+    known: boolean;
+    root: string | null;
+    excluded: boolean;
+    mappedAtStart: boolean;
+    running: string | null;
+}
+/** Every project worth listing: known ones, the running sandbox's, and this folder. */
+export declare const projectRows: (ctx: Context) => Row[];
+export declare const projects: (ctx: Context) => Promise<number>;
+export {};