windows-development-sandbox 0.0.0-stage → 1.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

@@ -0,0 +1,20 @@
+/** The package folder (this file is dist/cli/index.js). */
+export declare const packageRoot: string;
+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: (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

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CommanderError } from 'commander';
+import { buildProgram, parseCli } from './args.js';
+import { commandSpec } from './manifest.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';
+/** 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');
+const HANDLERS = {
+    launch: (ctx) => commands.launch(ctx),
+    generate: (ctx) => commands.launch(ctx, true),
+    attach: commands.attach,
+    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,
+    config: commands.config,
+    doctor: commands.doctor,
+    setup: commands.setup,
+    data: commands.data,
+    'host-claude': commands.claudeHost,
+    _watch: commands.watcher,
+};
+/** Runs an argv from the menu exactly as if it had been typed, reporting errors instead of throwing. */
+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 (rawArgv, preset = {}) => {
+    const argv = preset.command || preset.harness ? rawArgv : hoistConfig(rawArgv);
+    const isAgent = (name) => {
+        if (!name || name.startsWith('-') || commandSpec(name))
+            return false;
+        const at = argv.indexOf('--config');
+        try {
+            return Boolean(loadConfig(at >= 0 ? argv[at + 1] : undefined).config.harnesses[name]);
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!preset.command && !preset.harness) {
+        if (argv.length === 0)
+            return process.stdin.isTTY ? main(['menu']) : (buildProgram(() => undefined).outputHelp(), 0);
+        if (isAgent(argv[0]))
+            return main(argv.slice(1), { harness: argv[0] });
+    }
+    const options = parseCli(preset.command ? [preset.command, ...argv] : argv, Boolean(preset.harness));
+    if (preset.harness)
+        options.harness = preset.harness;
+    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(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, options.positionals);
+    // repair must run even when the config file is broken (createContext would refuse it).
+    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.');
+    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(c.red('Error: ') + e.message);
+        if (e.fix)
+            console.error('  Fix:  ' + e.fix);
+        return 1;
+    }
+    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;
+};
+export const run = (argv, preset) => {
+    main(argv, preset).then((code) => { process.exitCode = code; }, (e) => { process.exitCode = report(e); });
+};

package/dist/cli/manifest.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+export declare const OptionSpec: z.ZodObject<{
+    flag: z.ZodString;
+    short: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        list: "list";
+    }>;
+    value: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+        harnesses: "harnesses";
+        sessions: "sessions";
+        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;
+    description: z.ZodString;
+    required: z.ZodBoolean;
+    variadic: z.ZodOptional<z.ZodBoolean>;
+    choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+        harnesses: "harnesses";
+        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";
+    Sessions: "Sessions";
+    Accounts: "Accounts";
+    Data: "Data";
+    Health: "Health";
+    Config: "Config";
+}>;
+export declare const CommandSpec: z.ZodObject<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    group: z.ZodEnum<{
+        Agents: "Agents";
+        Sandbox: "Sandbox";
+        Sessions: "Sessions";
+        Accounts: "Accounts";
+        Data: "Data";
+        Health: "Health";
+        Config: "Config";
+    }>;
+    args: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodBoolean;
+        variadic: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+            harnesses: "harnesses";
+            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;
+        short: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            list: "list";
+        }>;
+        value: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+            harnesses: "harnesses";
+            sessions: "sessions";
+            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";
+        agent: "agent";
+    }>>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type OptionSpecT = z.output<typeof OptionSpec>;
+export type ArgSpecT = z.output<typeof ArgSpec>;
+export type CommandSpecT = z.output<typeof CommandSpec>;
+export declare const COMMANDS: CommandSpecT[];
+export declare const commandSpec: (name: string) => CommandSpecT | undefined;

package/dist/cli/manifest.js

@@ -0,0 +1,107 @@
+// Every command, defined once: name, group, arguments and options with their types. args.ts builds the commander
+// parser from it and menu.ts builds the interactive menu from it, so a command added here works both ways.
+import { z } from 'zod';
+const Choices = z.union([z.array(z.string()), z.enum(['harnesses', 'accounts', 'sessions'])])
+    .describe('Fixed values, or a list the menu fills in at run time.');
+export const OptionSpec = z.strictObject({
+    flag: z.string().regex(/^--[a-z][a-z0-9-]*$/).describe('Long flag, e.g. --terminal.'),
+    short: z.string().regex(/^-[a-zA-Z]$/).optional(),
+    type: z.enum(['boolean', 'string', 'number', 'list']).describe('list = repeatable string option.'),
+    value: z.string().optional().describe('Placeholder shown in help, e.g. name for --account <name>.'),
+    description: z.string(),
+    default: z.union([z.string(), z.number()]).optional(),
+    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(),
+    description: z.string(),
+    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(),
+    summary: z.string(),
+    group: Group,
+    args: z.array(ArgSpec),
+    options: z.array(OptionSpec),
+    /** Unknown options and extra arguments are passed on to the agent (launch) or the program (exec). */
+    passthrough: z.enum(['agent', 'command']).optional(),
+    json: z.boolean().optional(),
+    /** Takes over the terminal or ends the session: the menu does not come back afterwards. */
+    interactive: z.boolean().optional(),
+    hidden: z.boolean().optional(),
+});
+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', '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 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)', 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', '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 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: '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 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 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 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: [{ 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 },
+]);
+export const commandSpec = (name) => COMMANDS.find((c) => c.name === name);

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

@@ -0,0 +1,14 @@
+import type { Context } from './commands/context.js';
+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 { 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>;
+/**
+ * Runs the menu until Exit, or until a command that takes over the terminal (launch, attach) has run. `run` executes
+ * an argv exactly like typing it.
+ */
+export declare const menu: (ctx: Context, run: (argv: string[]) => Promise<number>) => Promise<number>;