windows-development-sandbox 1.0.5 → 1.1.0

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

@@ -0,0 +1,60 @@
+// What `sandbox setup` learns about this PC: the Windows edition, CPU virtualization and the Windows Sandbox feature.
+import os from 'node:os';
+import _ from 'lodash';
+import { z } from 'zod';
+import { freeBytesAt } from '../../../core/disk.js';
+import { captureOutput, fileExists } from '../../../core/util.js';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+const FEATURE = 'Containers-DisposableClientVM';
+export const ENABLE_COMMAND = 'Enable-WindowsOptionalFeature -Online -FeatureName ' + FEATURE + ' -All -NoRestart';
+/** `reg query <key>` output to { valueName: data }. */
+export const parseRegQuery = (text) => Object.fromEntries(_.compact(text.split(/\r?\n/).map((line) => /^\s+(\S+)\s+REG_\w+\s+(.*)$/.exec(line)?.slice(1, 3))));
+/** The "State : ..." line of `Dism /Get-FeatureInfo` (English output only; anything else is unknown). */
+export const parseDismState = (text) => {
+    const state = /^State\s*:\s*(.+?)\s*$/im.exec(text)?.[1].toLowerCase() ?? '';
+    if (state === 'enabled')
+        return 'enabled';
+    if (state.includes('pending'))
+        return 'pending';
+    return state.startsWith('disabled') ? 'disabled' : 'unknown';
+};
+/** Win32_OptionalFeature.InstallState: 1 enabled, 2 disabled, 3 absent. */
+export const featureFromInstallState = (state) => state === 1 ? 'enabled' : state === 2 || state === 3 ? 'disabled' : 'unknown';
+// Fixed script (no outside data): CPU/hypervisor facts and the feature state, readable without admin rights.
+const PROBE = [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    '$cpu = @(Get-CimInstance Win32_Processor)',
+    '$cs = Get-CimInstance Win32_ComputerSystem',
+    '$f = Get-CimInstance Win32_OptionalFeature -Filter "Name=\'' + FEATURE + '\'"',
+    '$v = $null; if ($cpu.Count) { $v = [bool]($cpu | Where-Object { $_.VirtualizationFirmwareEnabled }) }',
+    '$h = $null; if ($cs) { $h = [bool]$cs.HypervisorPresent }',
+    '$s = $null; if ($f) { $s = [int]$f.InstallState }',
+    '@{ virtualizationFirmware = $v; hypervisorPresent = $h; installState = $s } | ConvertTo-Json -Compress',
+].join('; ');
+const Probe = z.object({ virtualizationFirmware: z.boolean().nullable(), hypervisorPresent: z.boolean().nullable(), installState: z.number().nullable() }).partial();
+export const parseProbe = (text) => {
+    try {
+        return Probe.parse(JSON.parse(_.last(text.trim().split(/\r?\n/)) ?? ''));
+    }
+    catch {
+        return {};
+    }
+};
+export const gatherFacts = (storageRoot) => {
+    const reg = parseRegQuery(captureOutput(SYSTEM.reg(), ['query', 'HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion']));
+    const probe = parseProbe(captureOutput(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', PROBE]));
+    // DISM knows about a pending restart but needs admin rights; the CIM state works for everyone.
+    const dism = parseDismState(captureOutput(SYSTEM.dism(), ['/English', '/Online', '/Get-FeatureInfo', '/FeatureName:' + FEATURE]));
+    return {
+        edition: reg.EditionID ?? null,
+        build: Number(reg.CurrentBuildNumber ?? reg.CurrentBuild) || null,
+        feature: dism === 'unknown' ? featureFromInstallState(probe.installState) : dism,
+        sandboxExe: fileExists(system32('WindowsSandbox.exe')),
+        virtualizationFirmware: probe.virtualizationFirmware ?? null,
+        hypervisorPresent: probe.hypervisorPresent ?? null,
+        totalRamBytes: os.totalmem(),
+        freeDiskBytes: freeBytesAt(storageRoot),
+        storageRoot,
+        nodeVersion: process.version,
+    };
+};

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

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare const setup: (ctx: Context) => Promise<number>;

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 '../settings/edit.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,7 +3,10 @@ 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.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';
@@ -17,12 +20,14 @@ 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,
     clean: commands.clean,
@@ -33,15 +38,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 +79,40 @@ 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);
+        console.error(c.red('Error: ') + e.message);
         if (e.fix)
             console.error('  Fix:  ' + 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,61 @@ 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: '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-multi.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from './commands/context.js';
+/** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
+export declare const candidateFolders: (ctx: Context, cwd?: string) => string[];
+/** The command line for several sessions: one --session per (agent, folder), with the shared options. */
+export declare const severalAgentsArgv: (sessions: {
+    harness: string;
+    folder: string;
+}[], o: {
+    headless: boolean;
+    attachFirst: boolean;
+}) => string[];
+export declare const askSeveralAgents: (ctx: Context) => Promise<string[] | null>;

package/dist/cli/menu-multi.js

@@ -0,0 +1,82 @@
+// The menu's "Start several agents": projects, then agents for each, then options; it only builds a command line
+// (sandbox launch --session <agent>@<folder> ...), so "repeat last" works and typing it does the same.
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkbox, confirm, input, select } from '@inquirer/prompts';
+import { assertSafeWorkspace } from '../core/safe-paths.js';
+import { expandPath, errMsg } from '../core/util.js';
+import { readKnown } from '../host/projects.js';
+import { isWithin } from '../shared/projects.js';
+import { c, pageSizeFor, shortenMiddle, termWidth } from './colors.js';
+import { commandLine } from './history.js';
+const ADD = '@add';
+/** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
+export const candidateFolders = (ctx, cwd = process.cwd()) => {
+    const roots = ctx.loaded.config.projects.roots.map((r) => expandPath(r, ctx.loaded.base));
+    const inRoots = roots.flatMap((r) => { try {
+        return fs.readdirSync(r, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.')).slice(0, 200).map((e) => path.join(r, e.name));
+    }
+    catch {
+        return [];
+    } });
+    const all = [path.resolve(cwd), ...readKnown(ctx.storageRoot).map((k) => k.host), ...inRoots];
+    return all.filter((f, i) => all.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i && fs.existsSync(f));
+};
+/** The command line for several sessions: one --session per (agent, folder), with the shared options. */
+export const severalAgentsArgv = (sessions, o) => ['launch', ...sessions.flatMap((s) => ['--session', s.harness + '@' + s.folder]), ...(o.headless ? ['--headless'] : []), ...(o.attachFirst ? ['-t'] : [])];
+export const askSeveralAgents = async (ctx) => {
+    const here = path.resolve(process.cwd());
+    const width = Math.max(20, termWidth() - 14);
+    let folders = await checkbox({
+        message: 'Which projects? (each gets its sessions; all of them are mapped into one sandbox)',
+        pageSize: pageSizeFor(16),
+        choices: [
+            ...candidateFolders(ctx).map((f) => ({ value: f, name: shortenMiddle(f, width) + (isWithin(f, here) && isWithin(here, f) ? c.dim('  (this folder)') : ''), checked: f.toLowerCase() === here.toLowerCase() })),
+            { value: ADD, name: 'Add a folder...' },
+        ],
+    });
+    if (folders.includes(ADD)) {
+        const extra = await input({
+            message: 'Folder to add:',
+            validate: (v) => {
+                const dir = path.resolve(v.trim());
+                if (!v.trim() || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+                    return 'Not a folder: ' + dir;
+                try {
+                    assertSafeWorkspace(dir, ctx.packageRoot, ctx.storageRoot);
+                    return true;
+                }
+                catch (e) {
+                    return errMsg(e);
+                }
+            },
+        });
+        folders = [...folders.filter((f) => f !== ADD), path.resolve(extra.trim())];
+    }
+    if (!folders.length)
+        return null;
+    const agents = Object.keys(ctx.loaded.config.harnesses);
+    const sessions = [];
+    for (const folder of folders) {
+        const picked = await checkbox({
+            message: 'Agents for ' + shortenMiddle(folder, width - 10) + ' (one session each):',
+            pageSize: pageSizeFor(agents.length),
+            choices: agents.map((a) => ({ value: a, name: a, checked: a === ctx.loaded.config.defaultHarness })),
+            required: true,
+        });
+        sessions.push(...picked.map((harness) => ({ harness, folder })));
+    }
+    const headless = await confirm({ message: 'Hide the sandbox window (headless)?', default: ctx.loaded.config.sandbox.headless });
+    const attach = await select({
+        message: 'Attach this terminal to:',
+        choices: [{ name: 'none (each has a tab inside; sandbox attach shows any of them)', value: -1 }, ...sessions.map((s, i) => ({ name: s.harness + ' in ' + shortenMiddle(s.folder, width - 20), value: i }))],
+        default: 0,
+    });
+    // The one to attach goes first: -t attaches the first session.
+    const ordered = attach >= 0 ? [sessions[attach], ...sessions.filter((_s, i) => i !== attach)] : sessions;
+    const projects = [...new Set(sessions.map((s) => path.basename(s.folder)))];
+    console.log('Start 1 sandbox with ' + sessions.length + ' session' + (sessions.length === 1 ? '' : 's') + ': ' + ordered.map((s) => s.harness + ' in ' + path.basename(s.folder)).join(', ') + ' - map ' + projects.join(' and '));
+    const argv = severalAgentsArgv(ordered, { headless, attachFirst: attach >= 0 });
+    console.log(c.dim('  ' + commandLine(argv)));
+    return await confirm({ message: 'Start them?', default: true }) ? argv : null;
+};

package/dist/cli/menu.d.ts

@@ -1,17 +1,10 @@
-import { z } from 'zod';
 import type { Context } from './commands/context.js';
-import { type CommandSpecT } from './manifest.js';
-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;
+import { splitArgs } from './args.js';
+import { type CommandSpecT, type OptionSpecT } from './manifest.js';
 /** Splits "a b 'c d'" like a shell would (enough for agent arguments and exec commands). */
-export declare const splitArgs: (text: string) => string[];
+export { splitArgs };
+/** What this option accepts, checked while typing (undefined = anything). */
+export declare const optionProblem: (o: OptionSpecT, v: string) => string | undefined;
 /** Asks everything a command takes and returns its argv (or null when the user backs out). */
 export declare const askCommand: (ctx: Context, spec: CommandSpecT, preset?: string[]) => Promise<string[] | null>;
 /**
@@ -19,4 +12,3 @@ export declare const askCommand: (ctx: Context, spec: CommandSpecT, preset?: str
  * an argv exactly like typing it.
  */
 export declare const menu: (ctx: Context, run: (argv: string[]) => Promise<number>) => Promise<number>;
-export {};