windows-development-sandbox 1.1.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/README.md

@@ -31,7 +31,7 @@ works too. [Other ways to install](docs/install.md)
 ```powershell
 cd C:\code\my-app
 
-sandbox            # menu: start an agent, a plain sandbox, diagnostics, cleanup ...
+sandbox            # the menu: start agents, sessions, apps, every setting, diagnostics ...
 sandbox claude     # Claude Code in a sandbox for this folder (or: claude-sandbox)
 sandbox claude -t  # ... in this terminal (Ctrl+] detaches, the session keeps running)
 sandbox start      # just the sandbox, no agent
@@ -49,6 +49,7 @@ The first start downloads what the project needs (a few minutes, once). After th
 |---|---|
 | **Safe by default** | The agent sees only your project folder. Credentials are stripped before anything is copied in, your LAN is blocked, and nothing the sandbox writes can run on your PC. |
 | **Languages** | Node, Python, Rust, C/C++ (GCC or MSVC), .NET (incl. .NET Framework targeting), Go, Java, Ruby, PHP, Deno, Bun, PowerShell 7, with pnpm, yarn, Volta, uv, pyenv, Maven, Gradle, Composer, gh ... |
+| **Apps and tools** | VS Code (set up for your languages, with their extensions) and Windows Terminal, plus 60 optional apps and tools by category: DBeaver, pgAdmin, Bruno, Godot, Blender, kubectl, jq, ripgrep ... and programs of your own |
 | **Databases** | PostgreSQL, MySQL, MongoDB, Redis and DynamoDB Local with a web UI, started when the project uses them, or any time with `--database` / `sandbox db` |
 | **Agents** | Claude Code, Codex, Gemini, opencode, Qwen, Crush, Copilot, Kilo, Amp, Cline, Continue, Kimi, Aider, DeepSeek agents |
 | **Smart** | Detects what the project needs from its files, respects version files, installs in parallel and reuses everything |
@@ -60,7 +61,7 @@ The first start downloads what the project needs (a few minutes, once). After th
 
 | Command | |
 |---|---|
-| `sandbox` | the interactive menu: repeat your last command, start agents, every option, and all settings |
+| `sandbox` | the menu, a full-screen app: start agents, attach to sessions, pick apps, edit every setting (yours and the project's), all commands, with search |
 | `sandbox <agent>`, `claude-sandbox` | start an agent; `-t` for this terminal, `--headless` for no window |
 | `sandbox start` | the sandbox without an agent |
 | `sandbox attach` / `sessions` / `status` | work with a running sandbox (this folder's project first) |

package/config.example.json

@@ -3,12 +3,25 @@
   "defaultHarness": "claude",
   "guestWorkspace": "auto",
   "readOnly": false,
+  "workspaceFilter": {
+    "enabled": false,
+    "exclude": [],
+    "include": []
+  },
+  "audit": {
+    "enabled": false,
+    "days": 14,
+    "maxMb": 100,
+    "processes": true,
+    "files": true
+  },
   "mappings": [],
   "sandbox": {
     "memoryMb": "auto",
     "maxMemoryMb": 32768,
     "maxMemoryPercent": 80,
     "cpuLimit": 80,
+    "pageFileMb": 16384,
     "reserveHostMb": 8192,
     "vGpu": false,
     "networking": true,
@@ -17,15 +30,23 @@
     "videoInput": false,
     "printerRedirection": false,
     "protectedClient": true,
-    "headless": false
+    "headless": false,
+    "keepAwake": true
   },
   "storage": {
     "root": "%LOCALAPPDATA%\\AgentSandbox",
     "persistAgentState": true,
-    "dataName": "default"
+    "dataName": "default",
+    "markSandboxFiles": true,
+    "warnDataGb": 50
   },
   "network": {
-    "blockPrivateRanges": true
+    "blockPrivateRanges": true,
+    "allowOnly": [],
+    "blockHosts": [],
+    "forwardPorts": [],
+    "dns": [],
+    "proxy": ""
   },
   "provisioning": {
     "copyFromHost": true,
@@ -37,6 +58,9 @@
     },
     "terminal": {
       "enabled": true
+    },
+    "conpty": {
+      "enabled": true
     }
   },
   "downloads": {
@@ -135,7 +159,10 @@
       "vulkan": false
     },
     "vscode": {
-      "enabled": true
+      "enabled": true,
+      "setup": true,
+      "recommended": true,
+      "extensions": []
     },
     "environment": {}
   },
@@ -188,6 +215,10 @@
   "personalization": {
     "enabled": true
   },
+  "apps": {
+    "install": [],
+    "custom": {}
+  },
   "claudeProfile": {
     "enabled": true,
     "hostDir": "auto",
@@ -203,7 +234,9 @@
     "copyCredentials": false,
     "overwrite": true,
     "syncHistory": true,
-    "syncClaudeMem": true
+    "historyScope": "project",
+    "syncClaudeMem": true,
+    "syncClaudeMemBack": false
   },
   "harnesses": {
     "claude": {
@@ -344,6 +377,7 @@
     "roots": [],
     "askToAddRoot": true,
     "declinedRoots": [],
+    "allowOutsideMappings": "ask",
     "wsbShare": true
   }
 }

package/dist/cli/args.d.ts

@@ -29,6 +29,9 @@ export interface CliOptions {
     all: boolean;
     /** launch --session <agent>@<folder> (repeatable): several sessions at once, folders made absolute. */
     sessions: SessionWant[];
+    /** audit: only events of this kind, and containing this text. */
+    kind?: string;
+    grep?: string;
 }
 /** One session to start: an agent in a folder, with arguments of its own (after the ones given after --). */
 export interface SessionWant {

package/dist/cli/args.js

@@ -134,7 +134,9 @@ export const parseCli = (argv, wrapper = false) => {
         all: Boolean(o.all),
         sessions: (o.session ?? []).map((s) => parseSessionWant(s)),
         timeout: o.timeout ?? 600,
-        days: o.days ?? 7,
+        days: o.days ?? (name === 'audit' ? 1 : 7),
+        kind: o.kind,
+        grep: o.grep,
     };
 };
 const defaults = () => ({

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/accounts.js

@@ -3,7 +3,7 @@ import { activateAccount, listAccounts, removeAccount, saveAccount, setDefaultAc
 import { restartSessions, runningSessions } from '../../host/channel.js';
 import { hostClaudeDir, hostGlobalStateFile } from '../../host/claude-profile.js';
 import { isSandboxRunning } from '../../host/platform.js';
-import { fail } from '../../core/util.js';
+import { fail, safeText } from '../../core/util.js';
 import { printJson, sandboxAlive, table } from './context.js';
 const label = (a) => '"' + a.name + '"' + (a.email ? ' (' + a.email + ')' : '');
 /** This PC's Claude login location (config folder + global state file). */
@@ -27,7 +27,7 @@ const use = async (ctx, name) => {
     console.log('Sandbox now uses ' + label(activateAccount(ctx.storageRoot, ctx.dataPath, name)) + '.');
     const claudeRunning = isSandboxRunning() && runningSessions(ctx.dataPath).some((s) => s.harness === 'claude');
     if (claudeRunning && !ctx.options.noRestart)
-        console.log((await restartSessions(ctx.dataPath, 'claude', sandboxAlive)).message + ' with --continue; the conversation carries on under the new account.');
+        console.log(safeText((await restartSessions(ctx.dataPath, 'claude', sandboxAlive)).message) + ' with --continue; the conversation carries on under the new account.');
     return 0;
 };
 export const account = async (ctx) => {

package/dist/cli/commands/agent-commands.js

@@ -7,7 +7,7 @@ import { agentCommands, commandsDir, reconcileAgentCommands } from '../../host/a
 import { insideSandbox } from '../../host/platform.js';
 import { writeFileAtomic } from '../../shared/rundir.js';
 import { c } from '../colors.js';
-import { editConfigText } from '../settings/edit.js';
+import { editConfigText } from '../menu/settings/config-file.js';
 import { table } from './context.js';
 const entryOf = (ctx) => path.join(ctx.packageRoot, 'dist', 'bin', 'sandbox.js');
 /** Brings this PC in line with agentCommands and says what changed (used after on/off, settings and launch). */

package/dist/cli/commands/context.js

@@ -36,8 +36,9 @@ export const table = (rows) => {
 };
 /** Prints `value` as JSON when --json was given; returns whether it did. */
 export const printJson = (ctx, value) => {
+    // JSON.stringify leaves C1 controls (U+0080-U+009F) as they are; text from the sandbox must not reach a terminal raw.
     if (ctx.options.json)
-        console.log(JSON.stringify(value, null, 2));
+        console.log(JSON.stringify(value, null, 2).replace(/[\u0080-\u009f]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0')));
     return ctx.options.json;
 };
 export const sandboxAlive = () => isSandboxRunning();

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

@@ -17,7 +17,7 @@ const ALL_WARNING = 'removes EVERYTHING the sandbox keeps: toolchains, databases
  * not a plain relative target inside the data folder: absolute paths, drive letters, `..`, wildcards, unknown areas.
  */
 export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
-    const usage = 'Targets: all | tools | tools/<name> | tools/agents/<name> | databases | databases/<name> | state | state/<agent> | logs | launches. See them with: sandbox data';
+    const usage = 'Targets: all | tools | tools/<name> | tools/agents/<name> | databases | databases/<name> | state | state/<agent> | logs | launches | views. See them with: sandbox data';
     if (!inputs.length)
         fail('Say what to remove.', usage);
     const resolved = inputs.map((raw) => {
@@ -39,6 +39,11 @@ export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
             return { target: 'all', path: dataPath, root: path.join(storageRoot, 'data'), warning: ALL_WARNING };
         if (area === 'launches')
             return { target, path: path.join(storageRoot, 'launches', ...rest), root: storageRoot };
+        if (area === 'views') {
+            if (rest.length)
+                fail('Remove all views ("views"), not single ones.', usage);
+            return { target, path: path.join(storageRoot, 'views'), root: storageRoot, warning: 'Views are the copies of your projects without their git-ignored files (workspaceFilter). Your projects are not touched; what the sandbox built or installed in them (node_modules, build output) goes, and the next start copies the projects again.' };
+        }
         if (area === 'accounts' || area === 'sync')
             fail('"' + area + '" is kept on this PC on purpose and is not removed here.', area === 'accounts' ? 'Remove a saved login with: sandbox account remove <name>' : usage);
         if (!DATA_AREAS.includes(area))

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

@@ -35,7 +35,7 @@ export const collectDataEntries = (dataPath, storageRoot) => {
     });
     const otherData = entriesOf(path.join(storageRoot, 'data')).filter((d) => d.isDirectory() && path.join(storageRoot, 'data', d.name).toLowerCase() !== path.resolve(dataPath).toLowerCase());
     const host = [
-        ...['launches', 'accounts', 'sync', 'logs', 'run', 'host'].map((name) => ({ area: 'host', name, path: path.join(storageRoot, name), bytes: sizeOf(path.join(storageRoot, name)) })),
+        ...['launches', 'views', 'accounts', 'sync', 'logs', 'run', 'host'].map((name) => ({ area: 'host', name, path: path.join(storageRoot, name), bytes: sizeOf(path.join(storageRoot, name)) })),
         ...otherData.map((d) => ({ area: 'host', name: 'other data folder: ' + d.name, path: path.join(storageRoot, 'data', d.name), bytes: sizeOf(path.join(storageRoot, 'data', d.name)) })),
     ].filter((r) => fs.existsSync(r.path));
     return _.sortBy([...rows, ...host], (r) => AREA_ORDER.indexOf(r.area), (r) => -r.bytes, (r) => r.name.toLowerCase());
@@ -48,7 +48,7 @@ export const cleanTargetOf = (entry) => {
         return entry.name;
     if (entry.area === 'logs')
         return 'logs';
-    if (entry.area === 'host' && entry.name === 'launches')
-        return 'launches';
+    if (entry.area === 'host' && (entry.name === 'launches' || entry.name === 'views'))
+        return entry.name;
     return null;
 };

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

@@ -6,5 +6,5 @@ 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 { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
 export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/index.js

@@ -6,5 +6,5 @@ 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 { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
 export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

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,25 +12,35 @@ 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 { 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';
+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 { 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';
 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())
@@ -39,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++) {
@@ -51,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) => {
@@ -64,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.
@@ -210,12 +232,39 @@ 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);
     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;
@@ -224,12 +273,45 @@ 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(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 };
+};
+/**
+ * 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;
@@ -271,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) {
@@ -282,9 +367,9 @@ 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 ? [['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; use Postgres or SQLite for local work)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
@@ -294,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)
@@ -302,18 +387,21 @@ 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);
     // 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;
+    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.
@@ -323,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.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>;