windows-development-sandbox 1.0.5 → 1.4.0

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

@@ -0,0 +1,43 @@
+// `sandbox setup`: checks this PC can run Windows Sandbox and offers to turn the feature on.
+import { spawnSync } from 'node:child_process';
+import { askYesNo } from '../../../core/prompt.js';
+import { fail, isWin } from '../../../core/util.js';
+import { refuseInSelfTest } from '../../../host/test-guard.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { c } from '../../colors.js';
+import { table } from '../context.js';
+import { buildChecks, canEnableFeature } from './checks.js';
+import { ENABLE_COMMAND, gatherFacts } from './facts.js';
+const LABEL = { ok: c.green('OK'), warn: c.yellow('WARNING'), action: c.red('ACTION NEEDED') };
+const print = (checks) => table(checks.map((check) => [LABEL[check.status], check.name, check.detail]));
+/** Runs the enable command in an elevated PowerShell (Windows asks for permission); true if it worked. */
+const enableFeature = () => {
+    refuseInSelfTest('turn on Windows features');
+    const inner = "'-NoProfile','-Command','" + ENABLE_COMMAND + " | Out-Null'";
+    const outer = "try { $p = Start-Process -FilePath '" + SYSTEM.powershell() + "' -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList " + inner + '; exit $p.ExitCode } catch { exit 1 }';
+    return spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', outer], { stdio: 'inherit' }).status === 0;
+};
+export const setup = async (ctx) => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Run sandbox setup on a Windows 10/11 Pro, Enterprise or Education PC.');
+    console.log('Checking this PC for Windows Sandbox...\n');
+    const facts = gatherFacts(ctx.storageRoot);
+    let checks = buildChecks(facts);
+    print(checks);
+    if (canEnableFeature(facts)) {
+        console.log('');
+        if (await askYesNo('Turn on Windows Sandbox now? Windows will ask for admin permission.')) {
+            console.log('Enabling Windows Sandbox (this can take a minute)...');
+            if (!enableFeature())
+                fail('Windows Sandbox could not be enabled (or the admin prompt was declined).', 'In an admin PowerShell run: ' + ENABLE_COMMAND + ', then restart Windows.');
+            console.log('Done. Restart Windows to finish, then run sandbox setup again.\n');
+            checks = buildChecks(gatherFacts(ctx.storageRoot));
+            print(checks);
+        }
+        else
+            console.log('To do it yourself, in an admin PowerShell run:\n  ' + ENABLE_COMMAND + '\nthen restart Windows.');
+    }
+    const todo = checks.filter((check) => check.status === 'action').length;
+    console.log('\n' + (todo ? todo + ' thing(s) to fix before the sandbox can start (see ACTION NEEDED above).' : 'This PC is ready. cd into a project and run sandbox claude (or sandbox for no agent).'));
+    return todo ? 1 : 0;
+};

package/dist/cli/commands/user-config.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from './context.js';
+export declare const configFile: (ctx: Context) => string;
+/** The value as written in your file (not merged with the defaults). */
+export declare const fileSetting: <T>(ctx: Context, key: string[], fallback: T) => T;
+export declare const setSetting: (ctx: Context, key: string[], value: unknown) => void;
+/** Adds a folder to a list setting (projects.roots, projects.exclude, ...) unless it is there already. */
+export declare const addToList: (ctx: Context, key: string[], folder: string) => boolean;
+export declare const removeFromList: (ctx: Context, key: string[], folder: string) => boolean;

package/dist/cli/commands/user-config.js

@@ -0,0 +1,41 @@
+// Changing your own config file from a command (sandbox projects ..., the "add this root?" question): one setting at
+// a time through the settings editor, so comments and formatting stay and an invalid result is never written.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'jsonc-parser';
+import _ from 'lodash';
+import { userConfigPath } from '../../core/config.js';
+import { fail } from '../../core/util.js';
+import { editConfigText } from '../menu/settings/config-file.js';
+export const configFile = (ctx) => ctx.loaded.configPath ?? userConfigPath();
+/** The value as written in your file (not merged with the defaults). */
+export const fileSetting = (ctx, key, fallback) => {
+    const file = configFile(ctx);
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    return _.get(parse(text) ?? {}, key) ?? fallback;
+};
+export const setSetting = (ctx, key, value) => {
+    const file = configFile(ctx);
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const result = editConfigText(text, key, value);
+    if ('problems' in result)
+        fail('Could not change ' + key.join('.') + ':\n  ' + result.problems.join('\n  '));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, result.text, 'utf8');
+};
+/** Adds a folder to a list setting (projects.roots, projects.exclude, ...) unless it is there already. */
+export const addToList = (ctx, key, folder) => {
+    const list = fileSetting(ctx, key, []);
+    if (list.some((p) => path.resolve(p).toLowerCase() === path.resolve(folder).toLowerCase()))
+        return false;
+    setSetting(ctx, key, [...list, folder]);
+    return true;
+};
+export const removeFromList = (ctx, key, folder) => {
+    const list = fileSetting(ctx, key, []);
+    const rest = list.filter((p) => path.resolve(p).toLowerCase() !== path.resolve(folder).toLowerCase());
+    if (rest.length === list.length)
+        return false;
+    setSetting(ctx, key, rest);
+    return true;
+};

package/dist/cli/history.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+declare const History: z.ZodArray<z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    at: z.ZodString;
+}, z.core.$strict>>;
+export declare const readHistory: () => z.output<typeof History>;
+/** Remembers a command (menu or typed) so the menu can offer it again. Never fails the command itself. */
+export declare const recordHistory: (argv: string[]) => void;
+/** argv as you would type it (quoted where needed). */
+export declare const commandLine: (argv: string[]) => string;
+export {};

package/dist/cli/history.js

@@ -0,0 +1,21 @@
+// The last commands run (menu or typed), kept in ~/.agent-sandbox/history.json so the menu can offer them again.
+import path from 'node:path';
+import { z } from 'zod';
+import { userDir } from '../core/config.js';
+import { writeJson } from '../core/util.js';
+import { readValid } from '../shared/rundir.js';
+const History = z.array(z.strictObject({ argv: z.array(z.string()).max(200), at: z.string() })).max(20);
+const historyFile = () => path.join(userDir(), 'history.json');
+const HIDDEN = new Set(['menu', '_watch', 'self-test']);
+export const readHistory = () => readValid(History, historyFile()) ?? [];
+/** Remembers a command (menu or typed) so the menu can offer it again. Never fails the command itself. */
+export const recordHistory = (argv) => {
+    if (!argv.length || HIDDEN.has(argv[0]) || argv.includes('--help'))
+        return;
+    try {
+        writeJson(historyFile(), [{ argv, at: new Date().toISOString() }, ...readHistory().filter((h) => h.argv.join('\0') !== argv.join('\0'))].slice(0, 10));
+    }
+    catch { /* history is a convenience */ }
+};
+/** argv as you would type it (quoted where needed). */
+export const commandLine = (argv) => ['sandbox', ...argv].map((a) => (/[\s"]/.test(a) || a === '' ? '"' + a.replace(/"/g, '\\"') + '"' : a)).join(' ');

package/dist/cli/index.d.ts

@@ -4,11 +4,17 @@ export interface Preset {
     harness?: string;
     command?: string;
 }
+/** `--config <file>` right after the command name (where every command accepts it); argv unchanged without a config. */
+export declare const withConfig: (argv: string[], config: string | undefined) => string[];
+/** `sandbox --config f.json status` works like `sandbox status --config f.json`: a leading --config moves behind the command. */
+export declare const hoistConfig: (argv: string[]) => string[];
 /**
  * CLI entry. `preset` lets wrapper binaries fix the command/agent (sandbox claude = launch --harness claude). No arguments
  * opens the menu; `sandbox <agent> [agent args]` starts that agent.
  */
-export declare const main: (argv: string[], preset?: Preset) => Promise<number>;
+export declare const main: (rawArgv: string[], preset?: Preset) => Promise<number>;
+/** argv without `--config <file>` / `--config=<file>`. */
+export declare const withoutConfig: (argv: string[]) => string[];
 /** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
 export declare const report: (e: unknown) => number;
 export declare const run: (argv: string[], preset?: Preset) => void;

package/dist/cli/index.js

@@ -3,10 +3,13 @@ import { fileURLToPath } from 'node:url';
 import { CommanderError } from 'commander';
 import { buildProgram, parseCli } from './args.js';
 import { commandSpec } from './manifest.js';
-import { menu, recordHistory } from './menu.js';
+import { c } from './colors.js';
+import { recordHistory } from './history.js';
+import { menu } from './menu/index.js';
+import { validateOptions } from './validate.js';
 import { loadConfig } from '../core/config.js';
 import * as commands from './commands/index.js';
-import { UserError, errMsg, fail } from '../core/util.js';
+import { UserError, errMsg, fail, plainText } from '../core/util.js';
 /** The package folder (this file is dist/cli/index.js). */
 export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const entry = path.join(packageRoot, 'dist', 'bin', 'agent-sandbox.js');
@@ -17,14 +20,17 @@ const HANDLERS = {
     sessions: commands.sessions,
     status: commands.status,
     exec: commands.exec,
+    'agent-commands': commands.agentCommandsCommand,
     db: commands.db,
     restart: commands.restart,
     stop: commands.stop,
     show: commands.show,
     hide: commands.hide,
     account: commands.account,
+    projects: commands.projects,
     sync: commands.sync,
     logs: commands.logs,
+    audit: commands.audit,
     clean: commands.clean,
     config: commands.config,
     doctor: commands.doctor,
@@ -33,15 +39,27 @@ const HANDLERS = {
     'host-claude': commands.claudeHost,
     _watch: commands.watcher,
 };
-const red = (s) => '\x1b[31m' + s + '\x1b[0m';
-const dim = (s) => '\x1b[2m' + s + '\x1b[0m';
 /** Runs an argv from the menu exactly as if it had been typed, reporting errors instead of throwing. */
-const runFromMenu = (argv) => main(argv).catch((e) => report(e));
+const runFromMenu = (config) => (argv) => main(withConfig(argv, config)).catch((e) => report(e));
+/** `--config <file>` right after the command name (where every command accepts it); argv unchanged without a config. */
+export const withConfig = (argv, config) => (config && argv.length ? [argv[0], '--config', config, ...argv.slice(1)] : argv);
+/** `sandbox --config f.json status` works like `sandbox status --config f.json`: a leading --config moves behind the command. */
+export const hoistConfig = (argv) => {
+    const eq = argv[0]?.startsWith('--config=');
+    if (argv[0] !== '--config' && !eq)
+        return argv;
+    const value = eq ? argv[0].slice('--config='.length) : argv[1];
+    const rest = argv.slice(eq ? 1 : 2);
+    if (value === undefined || value === '')
+        return argv;
+    return rest.length ? withConfig(rest, value) : ['menu', '--config', value];
+};
 /**
  * CLI entry. `preset` lets wrapper binaries fix the command/agent (sandbox claude = launch --harness claude). No arguments
  * opens the menu; `sandbox <agent> [agent args]` starts that agent.
  */
-export const main = async (argv, preset = {}) => {
+export const main = async (rawArgv, preset = {}) => {
+    const argv = preset.command || preset.harness ? rawArgv : hoistConfig(rawArgv);
     const isAgent = (name) => {
         if (!name || name.startsWith('-') || commandSpec(name))
             return false;
@@ -62,32 +80,41 @@ export const main = async (argv, preset = {}) => {
     const options = parseCli(preset.command ? [preset.command, ...argv] : argv, Boolean(preset.harness));
     if (preset.harness)
         options.harness = preset.harness;
-    recordHistory(preset.harness ? ['launch', '--harness', preset.harness, ...argv] : preset.command ? [preset.command, ...argv] : argv);
+    const typed = preset.harness ? ['launch', '--harness', preset.harness, ...argv] : preset.command ? [preset.command, ...argv] : argv;
     if (options.command === 'menu')
-        return menu(commands.createContext(packageRoot, entry, options), runFromMenu);
+        return menu(commands.createContext(packageRoot, entry, options), runFromMenu(options.config));
     // Loaded only when asked for: normal commands never load test code.
     if (options.command === 'self-test')
-        return (await import('../selftest/index.js')).selfTest(packageRoot);
+        return (await import('../selftest/index.js')).selfTest(packageRoot, options.positionals);
     // repair must run even when the config file is broken (createContext would refuse it).
-    if (options.command === 'repair')
+    if (options.command === 'repair') {
+        recordHistory(withoutConfig(typed));
         return commands.repairCommand(packageRoot, entry, options);
+    }
     const handler = HANDLERS[options.command];
     if (!handler)
         return fail('Unknown command "' + options.command + '".', 'Run sandbox --help for the list of commands, or sandbox for the menu.');
-    return (await handler(commands.createContext(packageRoot, entry, options))) ?? 0;
+    const ctx = commands.createContext(packageRoot, entry, options);
+    validateOptions(ctx);
+    // Only what parsed and validated is offered again by the menu, without the --config (it is the same every time).
+    recordHistory(withoutConfig(typed));
+    return (await handler(ctx)) ?? 0;
 };
+/** argv without `--config <file>` / `--config=<file>`. */
+export const withoutConfig = (argv) => argv.filter((a, i) => a !== '--config' && argv[i - 1] !== '--config' && !a.startsWith('--config='));
 /** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
 export const report = (e) => {
     if (e instanceof CommanderError)
         return ['commander.helpDisplayed', 'commander.help', 'commander.version'].includes(e.code) ? 0 : e.exitCode || 1;
     if (e instanceof UserError) {
-        console.error(red('Error: ') + e.message);
+        // Messages can quote what the sandbox wrote (a session's status, an address): never with its control codes.
+        console.error(c.red('Error: ') + plainText(e.message));
         if (e.fix)
-            console.error('  Fix:  ' + e.fix);
+            console.error('  Fix:  ' + plainText(e.fix));
         return 1;
     }
-    console.error(red('Unexpected error: ') + errMsg(e));
-    console.error(dim('This is a bug in windows-development-sandbox. Details: ' + (e instanceof Error && e.stack ? e.stack.split('\n').slice(1, 4).join(' | ').trim() : 'none')));
+    console.error(c.red('Unexpected error: ') + errMsg(e));
+    console.error(c.dim('This is a bug in windows-development-sandbox. Details: ' + (e instanceof Error && e.stack ? e.stack.split('\n').slice(1, 4).join(' | ').trim() : 'none')));
     console.error('  Please report it with the output of: sandbox doctor');
     return 1;
 };

package/dist/cli/manifest.d.ts

@@ -17,6 +17,8 @@ export declare const OptionSpec: z.ZodObject<{
         accounts: "accounts";
     }>]>>;
     advanced: z.ZodOptional<z.ZodBoolean>;
+    when: z.ZodOptional<z.ZodString>;
+    noMenu: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const ArgSpec: z.ZodObject<{
     name: z.ZodString;
@@ -28,7 +30,10 @@ export declare const ArgSpec: z.ZodObject<{
         sessions: "sessions";
         accounts: "accounts";
     }>]>>;
+    when: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
+/** Is an argument or option with this `when` asked, given the first argument's answer? */
+export declare const askedWhen: (when: string | string[] | undefined, first: string) => boolean;
 export declare const Group: z.ZodEnum<{
     Agents: "Agents";
     Sandbox: "Sandbox";
@@ -60,6 +65,7 @@ export declare const CommandSpec: z.ZodObject<{
             sessions: "sessions";
             accounts: "accounts";
         }>]>>;
+        when: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>;
     options: z.ZodArray<z.ZodObject<{
         flag: z.ZodString;
@@ -79,6 +85,8 @@ export declare const CommandSpec: z.ZodObject<{
             accounts: "accounts";
         }>]>>;
         advanced: z.ZodOptional<z.ZodBoolean>;
+        when: z.ZodOptional<z.ZodString>;
+        noMenu: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     passthrough: z.ZodOptional<z.ZodEnum<{
         command: "command";

package/dist/cli/manifest.js

@@ -13,6 +13,10 @@ export const OptionSpec = z.strictObject({
     choices: Choices.optional(),
     /** Advanced options are only asked in the menu after "Show advanced options". */
     advanced: z.boolean().optional(),
+    /** Only asked in the menu when the command's first argument has this value (account save: --from-host). */
+    when: z.string().optional(),
+    /** Never offered in the menu (dangerous shortcuts such as --yes); typing it on the command line still works. */
+    noMenu: z.boolean().optional(),
 });
 export const ArgSpec = z.strictObject({
     name: z.string(),
@@ -20,7 +24,11 @@ export const ArgSpec = z.strictObject({
     required: z.boolean(),
     variadic: z.boolean().optional(),
     choices: Choices.optional(),
+    /** Only asked in the menu when the command's first argument has this value, or one of these (data clean: targets). */
+    when: z.union([z.string(), z.array(z.string())]).optional(),
 });
+/** Is an argument or option with this `when` asked, given the first argument's answer? */
+export const askedWhen = (when, first) => when === undefined || (Array.isArray(when) ? when.includes(first) : when === first);
 export const Group = z.enum(['Agents', 'Sandbox', 'Sessions', 'Accounts', 'Data', 'Health', 'Config']);
 export const CommandSpec = z.strictObject({
     name: z.string(),
@@ -38,49 +46,66 @@ export const CommandSpec = z.strictObject({
 const bool = (flag, description, extra = {}) => ({ flag, type: 'boolean', description, ...extra });
 const text = (flag, value, description, extra = {}) => ({ flag, type: 'string', value, description, ...extra });
 const SANDBOX_OPTIONS = [
-    bool('--terminal', 'run in THIS terminal (reattaches to this folder\'s session if nobody is watching it)', { short: '-t' }),
+    bool('--terminal', 'attach this terminal (reuses this folder\'s session if nobody is watching it)', { short: '-t' }),
     bool('--headless', 'hide the sandbox window (sbx-show brings it back)'),
-    bool('--new', 'always start a new session, even if this folder has one nobody is attached to'),
+    bool('--new', 'always start a new session, even if this folder has an unattached one'),
     text('--workspace', 'dir', 'use this folder instead of the current one'),
     text('--node', 'version', 'Node version for nvm (default: .sandbox-config.json > .nvmrc > this PC)', { advanced: true }),
     text('--python', 'version', 'Python 3 version (default: .sandbox-config.json > .python-version > config)', { advanced: true }),
-    { flag: '--database', type: 'list', value: 'name', description: 'also start this database (postgres, mysql, mongodb, redis, dynamodb; repeatable)', advanced: true },
+    { flag: '--database', type: 'list', value: 'name', description: 'also start this database (postgres, mysql, mongodb, redis, dynamodb; repeatable)', choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'], advanced: true },
     { flag: '--script', type: 'list', value: 'file', description: 'run this .ps1/.mjs/.cmd inside the sandbox first (repeatable)', advanced: true },
     bool('--window', 'show the sandbox window even if config says headless', { advanced: true }),
     bool('--trust-config', 'approve the folder\'s .sandbox-config.json without asking', { advanced: true }),
     bool('--no-local-config', 'ignore the folder\'s .sandbox-config.json', { advanced: true }),
+    bool('--yes', 'when this folder is not in the running sandbox and adding it needs a restart, restart without asking', { noMenu: true }),
 ];
 const AGENT_OPTIONS = [
     text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),
+    { flag: '--session', type: 'list', value: 'agent@folder', description: 'start several sessions at once, e.g. --session claude@C:\\code\\api --session "codex@C:\\code\\web|--model o3" (repeatable; after | = that agent\'s own arguments; -t attaches the first)', noMenu: true },
     text('--account', 'name', 'Claude account for this sandbox', { choices: 'accounts' }),
     ...SANDBOX_OPTIONS,
-    bool('--no-agent', 'provision the sandbox without starting an agent', { advanced: true }),
+    bool('--no-agent', 'set up the sandbox but do not start an agent', { advanced: true }),
 ];
 const json = true;
 export const COMMANDS = z.array(CommandSpec).parse([
     { name: 'launch', summary: 'start the sandbox and an agent (or another session in the running sandbox)', group: 'Agents', args: [], options: AGENT_OPTIONS, passthrough: 'agent', interactive: true },
-    { name: 'start', summary: 'start the sandbox WITHOUT an agent: just the machine, toolchains and databases', group: 'Sandbox', args: [], options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'), interactive: true },
-    { name: 'generate', summary: 'dry run: write the .wsb and launch folder and show what would happen, start nothing', group: 'Health', args: [], options: AGENT_OPTIONS, passthrough: 'agent' },
+    { name: 'start', summary: 'start a sandbox with no agent (tools and databases only)', group: 'Sandbox', args: [], options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'), interactive: true },
+    { name: 'generate', summary: 'show what a start would do, without starting anything', group: 'Health', args: [], options: AGENT_OPTIONS, passthrough: 'agent' },
     { name: 'attach', summary: 'show a running session in this terminal (Ctrl+] detaches)', group: 'Sessions', args: [{ name: 'id', description: 'session (default: the newest)', required: false, choices: 'sessions' }], options: [], interactive: true },
     { name: 'sessions', summary: 'list agent sessions and who is attached', group: 'Sessions', args: [], options: [], json },
-    { name: 'status', summary: 'sandbox overview', group: 'Sandbox', args: [], options: [], json },
+    { name: 'status', summary: 'show what the sandbox is doing', group: 'Sandbox', args: [], options: [], json },
     { name: 'db', summary: 'list, start or stop databases in the running sandbox', group: 'Sandbox', args: [{ name: 'action', description: 'list, start or stop', required: false, choices: ['list', 'start', 'stop'] }, { name: 'name', description: 'postgres, mysql, mongodb, redis or dynamodb', required: false, choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'] }], options: [] },
     { name: 'exec', summary: 'run a command inside the sandbox and print its output', group: 'Sandbox', args: [{ name: 'command', description: 'command and its arguments', required: true, variadic: true }], options: [{ flag: '--timeout', type: 'number', value: 'seconds', description: 'give up after this many seconds', default: 600 }, text('--workspace', 'dir', 'folder (inside the mapped workspace) to run in')], passthrough: 'command', json },
-    { name: 'restart', summary: 'restart running agents in place; they resume their conversation', group: 'Sessions', args: [], options: [text('--harness', 'name', 'only this agent', { choices: 'harnesses' })] },
-    { name: 'stop', summary: 'shut the sandbox down', group: 'Sandbox', args: [], options: [] },
+    { name: 'restart', summary: 'restart this project\'s running agents in place; they resume their conversation', group: 'Sessions', args: [], options: [text('--harness', 'name', 'only this agent', { choices: 'harnesses' }), bool('--all', 'every project\'s sessions, not only this folder\'s')] },
+    { name: 'stop', summary: 'shut the sandbox down (every project\'s sessions end)', group: 'Sandbox', args: [], options: [bool('--yes', 'do not ask when other projects\' sessions would end', { noMenu: true })] },
+    {
+        name: 'projects', summary: 'the projects a sandbox can open without a restart: list, choose, roots, all/exclude', group: 'Sandbox', json,
+        args: [
+            { name: 'action', description: 'list, choose, add, remove, include, exclude, all, roots', required: false, choices: ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'] },
+            { name: 'value', description: 'a folder (add, remove, include, exclude), on/off (all), or list/add/remove (roots)', required: false, when: ['add', 'remove', 'include', 'exclude', 'all', 'roots'] },
+            { name: 'folder', description: '(roots add/remove) the folder', required: false, when: 'roots' },
+        ],
+        options: [],
+    },
     { name: 'show', summary: 'show the sandbox window', group: 'Sandbox', args: [], options: [] },
     { name: 'hide', summary: 'hide the sandbox window (it keeps running)', group: 'Sandbox', args: [], options: [] },
-    { name: 'account', summary: 'Claude accounts: list, save, use, set the default, remove', group: 'Accounts', args: [{ name: 'action', description: 'what to do', required: false, choices: ['list', 'save', 'use', 'default', 'remove'] }, { name: 'name', description: 'account name', required: false, choices: 'accounts' }], options: [bool('--from-host', '(save) save this PC\'s login instead of the sandbox\'s'), bool('--no-restart', '(use) do not restart running sessions')], json },
-    { name: 'data', summary: 'what persists between sandboxes (tools, databases, logins, logs), and cleaning it', group: 'Data', args: [{ name: 'action', description: 'show or clean', required: false, choices: ['show', 'clean'] }, { name: 'targets', description: 'what to clean, e.g. tools/go databases logs', required: false, variadic: true }], options: [bool('--yes', 'do not ask before deleting')], json },
+    { name: 'account', summary: 'Claude logins: list, save, use, set the default, remove', group: 'Accounts', args: [{ name: 'action', description: 'what to do', required: false, choices: ['list', 'save', 'use', 'default', 'remove'] }, { name: 'name', description: 'account name', required: false, choices: 'accounts' }], options: [bool('--from-host', '(save) save this PC\'s login instead of the sandbox\'s', { when: 'save' }), bool('--no-restart', '(use) do not restart running sessions', { when: 'use' })], json },
+    { name: 'data', summary: 'show what is kept between sandboxes (tools, databases, logins, logs), or delete some of it', group: 'Data', args: [{ name: 'action', description: 'show or clean', required: false, choices: ['show', 'clean'] }, { name: 'targets', description: 'what to clean, e.g. tools/go databases logs', required: false, variadic: true, when: 'clean' }], options: [bool('--yes', 'do not ask before deleting', { noMenu: true })], json },
     { name: 'clean', summary: 'delete old launch folders, logs and leftovers', group: 'Data', args: [], options: [{ flag: '--days', type: 'number', value: 'n', description: 'launch folders older than this many days', default: 7 }] },
-    { name: 'sync', summary: 'copy history (and claude-mem, once closed) back to this PC now', group: 'Data', args: [], options: [] },
+    { name: 'sync', summary: 'copy conversation history back to this PC now', group: 'Data', args: [], options: [] },
+    {
+        name: 'audit', summary: 'what happened in your sandboxes: programs started, files changed, sessions, repo guard (audit.enabled)', group: 'Health', json,
+        args: [],
+        options: [{ flag: '--days', type: 'number', value: 'n', description: 'the last n days (default: today)', default: 1 }, text('--kind', 'kind', 'only proc, file, session or guard events', { choices: ['proc', 'file', 'session', 'guard'] }), text('--grep', 'text', 'only events containing this text')],
+    },
     { name: 'logs', summary: 'print the newest sandbox log', group: 'Health', args: [], options: [bool('--follow', 'keep printing new lines', { short: '-f' })] },
     { name: 'setup', summary: 'check this PC can run Windows Sandbox and offer to turn it on', group: 'Health', args: [], options: [] },
     { name: 'doctor', summary: 'check this PC and show what will be copied or downloaded', group: 'Health', args: [], options: [text('--harness', 'name', 'agent to check', { choices: 'harnesses' })] },
     { name: 'repair', summary: 'find and fix common problems (stale state, broken downloads, half-installed tools)', group: 'Health', args: [], options: [] },
-    { name: 'self-test', summary: 'run the built-in tests', group: 'Health', args: [], options: [] },
-    { name: 'config', summary: 'show the effective config, its path, create it, editor schemas, or check a project\'s .sandbox-config.json', group: 'Config', args: [{ name: 'action', description: 'what to do', required: false, choices: ['show', 'path', 'init', 'schema', 'check'] }], options: [text('--workspace', 'dir', '(check) the project folder; default: the current one')] },
-    { name: 'host-claude', summary: 'Claude on this PC (NOT sandboxed) with a separate profile', group: 'Agents', args: [], options: [bool('--personal', 'use your normal Claude profile')], passthrough: 'agent', interactive: true },
+    { name: 'self-test', summary: 'run the built-in tests', group: 'Health', args: [{ name: 'suite', description: 'run only these test suites, e.g. config live-daemon (default: all)', required: false, variadic: true }], options: [] },
+    { name: 'config', summary: 'show or create your settings file, or check a project\'s .sandbox-config.json', group: 'Config', args: [{ name: 'action', description: 'what to do', required: false, choices: ['show', 'path', 'init', 'schema', 'check'] }], options: [text('--workspace', 'dir', '(check) the project folder; default: the current one')] },
+    { name: 'agent-commands', summary: '(Beta) make claude, codex ... on this PC start in a hidden sandbox and attach', group: 'Agents', args: [{ name: 'action', description: 'on, off or status', required: false, choices: ['status', 'on', 'off'] }], options: [] },
+    { name: 'host-claude', summary: 'run Claude on this PC, NOT sandboxed, with its own profile', group: 'Agents', args: [], options: [bool('--personal', 'use your normal Claude profile')], passthrough: 'agent', interactive: true },
     { name: 'menu', summary: 'the interactive menu (what `sandbox` opens with no arguments)', group: 'Config', args: [], options: [], hidden: true, interactive: true },
     { name: '_watch', summary: 'background history sync', group: 'Data', args: [], options: [], hidden: true },
 ]);

package/dist/cli/menu/apps.d.ts

@@ -0,0 +1,21 @@
+import { App } from '../tui/index.js';
+import type { ConfigFile } from './settings/config-file.js';
+export declare class AppsCatalogue {
+    private readonly app;
+    private readonly file;
+    private readonly dataPath;
+    constructor(app: App, file: ConfigFile, dataPath: string);
+    /** Downloaded already (into this data folder), so the next sandbox starts it without a download. */
+    private installed;
+    /** Is this entry on now (its setting, or listed in apps.install)? */
+    private chosen;
+    private item;
+    /** Shows the catalogue until you save (Enter) or leave it (Esc); returns the notice to show afterwards. */
+    run(): Promise<string | undefined>;
+    private save;
+    /** Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not). */
+    private editCustom;
+}
+/** For the home screen: "12 apps chosen". */
+export declare const appsSummary: (file: ConfigFile) => string;
+export declare const appLabel: (id: string) => string;

package/dist/cli/menu/apps.js

@@ -0,0 +1,122 @@
+// The apps catalogue in the menu: every app by category, searchable, ticked = installed in every sandbox. VS Code and
+// Windows Terminal are listed too (they have settings of their own, which ticking changes). Your own programs
+// (apps.custom) are edited as a list of small forms. Saved to your config file (or, for catalogue apps only, the
+// project's .sandbox-config.json).
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { APP_CATEGORIES, APPS } from '../../shared/apps.js';
+import { Text, Theme } from '../tui/index.js';
+import { ValueEditor } from './settings/editors.js';
+const CUSTOM = '@custom';
+export class AppsCatalogue {
+    app;
+    file;
+    dataPath;
+    constructor(app, file, dataPath) {
+        this.app = app;
+        this.file = file;
+        this.dataPath = dataPath;
+    }
+    /** Downloaded already (into this data folder), so the next sandbox starts it without a download. */
+    installed(entry) {
+        if (entry.id === 'vscode')
+            return fs.existsSync(path.join(this.dataPath, 'tools', 'vscode', 'Code.exe'));
+        if (entry.id === 'windows-terminal')
+            return fs.existsSync(path.join(this.dataPath, 'tools', 'terminal', 'WindowsTerminal.exe'));
+        return fs.existsSync(path.join(this.dataPath, 'tools', 'apps', entry.id, '.agent-sandbox-app'));
+    }
+    /** Is this entry on now (its setting, or listed in apps.install)? */
+    chosen(entry, install) {
+        return entry.setting ? _.get(this.file.userConfig(), entry.setting) === true : install.includes(entry.id);
+    }
+    item(entry, install) {
+        const notes = [
+            Theme.muted('Download  ') + '~' + entry.size + ' once, kept in C:\\AgentData\\tools\\' + (entry.setting ? '' : 'apps\\') + entry.id,
+            Theme.muted('Starts    ') + (entry.cli ? 'from a terminal (on PATH)' : 'from the desktop or Start > Sandbox apps'),
+            ...(entry.needs?.includes('mesa') ? [Theme.muted('Graphics  ') + 'OpenGL on the CPU (Mesa) is added for it'] : []),
+            ...(entry.fullGitOnly ? [Theme.warn('Needs provisioning.git.access "full" (it pushes with its own git).')] : []),
+            ...(entry.setting ? [Theme.muted('Setting   ') + entry.setting] : []),
+        ];
+        return {
+            value: entry.id, label: entry.name, category: entry.category, description: entry.about, details: notes, keywords: entry.id,
+            hint: (this.installed(entry) ? Theme.ok('installed ') : '') + Theme.muted(entry.size), checked: this.chosen(entry, install),
+            ...(this.file.isProject && entry.setting ? { disabled: 'A project cannot change this; it is in your own settings.' } : {}),
+        };
+    }
+    /** Shows the catalogue until you save (Enter) or leave it (Esc); returns the notice to show afterwards. */
+    async run() {
+        for (;;) {
+            const install = (this.file.isProject ? this.file.valueInFile(['apps', 'install']) : this.file.userConfig().apps.install) ?? [];
+            const custom = this.file.isProject ? {} : this.file.userConfig().apps.custom;
+            const entries = APPS.filter((a) => !(this.file.isProject && a.setting));
+            const picked = await this.app.list({
+                path: [this.file.isProject ? 'Project settings' : 'Apps'],
+                intro: 'Tick the apps every sandbox should have (space), then Enter to save. Each is downloaded once and kept; c = your own programs.',
+                multi: true,
+                categories: [...APP_CATEGORIES, ...(this.file.isProject ? [] : [{ id: 'custom', label: 'Your own programs', description: 'Programs you added yourself (c to add or change them).' }])],
+                items: [
+                    ...entries.map((a) => this.item(a, install)),
+                    ...Object.entries(custom).map(([id, a]) => ({ value: CUSTOM + id, label: a.name, category: 'custom', description: a.github ? 'From the latest ' + a.github + ' release.' : 'From ' + a.url, hint: Theme.muted(a.cli ? 'command line' : 'desktop'), checked: true, disabled: 'Your own programs are always installed; c to change or remove them.' })),
+                ],
+                actions: this.file.isProject ? [] : [{ key: 'c', label: 'your own programs' }],
+            });
+            if (picked.kind === 'back')
+                return undefined;
+            if (picked.kind === 'action') {
+                const notice = await this.editCustom();
+                if (notice)
+                    return notice;
+                continue;
+            }
+            if (picked.kind !== 'multi')
+                continue;
+            return this.save(picked.values.filter((v) => !v.startsWith(CUSTOM)));
+        }
+    }
+    save(ids) {
+        const problems = [];
+        let changed = 0;
+        for (const entry of APPS.filter((a) => a.setting && !this.file.isProject)) {
+            const on = ids.includes(entry.id);
+            if (on === this.chosen(entry, []))
+                continue;
+            const result = this.file.set(entry.setting.split('.'), on);
+            if (typeof result === 'object')
+                problems.push(...result.problems);
+            else if (result === 'saved')
+                changed++;
+        }
+        const install = APPS.filter((a) => !a.setting && ids.includes(a.id)).map((a) => a.id);
+        const result = this.file.set(['apps', 'install'], install.length || this.file.isProject ? install : undefined);
+        if (typeof result === 'object')
+            problems.push(...result.problems);
+        else if (result === 'saved')
+            changed++;
+        if (problems.length)
+            return Theme.error(Theme.glyph.cross + ' Not saved: ' + problems.join('; '));
+        if (!changed)
+            return Theme.muted('Apps unchanged.');
+        return Theme.ok(Theme.glyph.ok + ' Saved: ' + (install.length ? install.length + ' app' + (install.length === 1 ? '' : 's') : 'no apps') + '.') + Theme.muted(this.file.isProject ? ' The next launch asks you to approve the project file again.' : ' The next sandbox installs what it does not have yet.');
+    }
+    /** Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not). */
+    async editCustom() {
+        const node = this.file.schema.child('apps')?.child('custom');
+        if (!node)
+            return undefined;
+        const edited = await new ValueEditor(this.app).edit(['Apps', 'Your own programs'], ['apps', 'custom'], node, this.file.userConfig().apps.custom);
+        if (!edited)
+            return undefined;
+        const result = this.file.set(['apps', 'custom'], edited.value);
+        if (typeof result === 'object')
+            return Theme.error(Theme.glyph.cross + ' Not saved: ' + result.problems.join('; '));
+        return result === 'saved' ? Theme.ok(Theme.glyph.ok + ' Saved your programs (' + Object.keys(edited.value).length + ').') : undefined;
+    }
+}
+/** For the home screen: "12 apps chosen". */
+export const appsSummary = (file) => {
+    const config = file.userConfig();
+    const n = config.apps.install.length + Object.keys(config.apps.custom).length;
+    return n ? n + ' chosen' : 'none chosen';
+};
+export const appLabel = (id) => APPS.find((a) => a.id === id)?.name ?? Text.humanize(id);

package/dist/cli/menu/command-form.d.ts

@@ -0,0 +1,28 @@
+import type { Context } from '../commands/context.js';
+import { type CommandSpecT, type OptionSpecT } from '../manifest.js';
+import { App } from '../tui/index.js';
+/** What an option accepts, checked while typing (undefined = fine). */
+export declare const optionProblem: (o: OptionSpecT, v: string) => string | undefined;
+export declare class CommandForm {
+    private readonly app;
+    private readonly ctx;
+    private readonly spec;
+    /** Answers by field id (arg:<name>, opt:<flag>, json, extra). */
+    private readonly values;
+    constructor(app: App, ctx: Context, spec: CommandSpecT, preset?: string[]);
+    /** Values a choices list names, filled in from config and the running sandbox. */
+    private choices;
+    private first;
+    private fields;
+    private id;
+    /** The command line the form stands for now. */
+    argv(): string[];
+    /** The name of a required argument that has no value yet. */
+    private missing;
+    private item;
+    /** Shows the form until you run the command (its argv) or go back (null). */
+    run(): Promise<string[] | null>;
+    private edit;
+    /** `data clean` targets, ticked from a list with their sizes (never "all": that is typed on purpose). */
+    private dataTargets;
+}