windows-development-sandbox 1.1.0 → 1.4.1

package/dist/cli/commands/maintenance.js

@@ -4,15 +4,19 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import _ from 'lodash';
 import { DEFAULTS, userConfigPath, userDir } from '../../core/config.js';
-import { describeOverrides, isTrusted, LOCAL_CONFIG_NAME, normalizeOverrides, readLocalConfig, trustStorePath } from '../../core/local-config.js';
-import { expandPath, fail, safeText, sleep, writeJson } from '../../core/util.js';
+import { allowedAnswer, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, trustStorePath } from '../../core/local-config.js';
+import { guestWorkspaceOf, previewGuest } from '../../core/workspace.js';
+import { assertNoLinks, dirExists, expandPath, fail, plainText, safeText, sleep, writeJson } from '../../core/util.js';
+import { humanBytes } from '../../core/disk.js';
+import { AuditLog } from '../../host/audit/log.js';
 import { readKnown, readRegistry } from '../../host/projects.js';
 import { detectWsb } from '../../host/wsb.js';
 import { describePrune, pruneStorage } from '../../host/cleanup.js';
 import { doctorRows, hostClaude, insideSandbox, isSandboxRunning } from '../../host/platform.js';
 import { readSandboxStatus } from '../../shared/rundir.js';
 import { syncBack, watch } from '../../sync/watcher.js';
-import { table } from './context.js';
+import { printJson, table } from './context.js';
+import { c } from '../colors.js';
 export const sync = (ctx) => {
     const running = isSandboxRunning();
     const result = syncBack(ctx.dataPath, !running);
@@ -28,6 +32,8 @@ const newestLog = (dir) => {
 };
 export const logs = async (ctx) => {
     const dir = path.join(ctx.dataPath, 'logs');
+    // The sandbox writes this folder: never read through a link it planted there.
+    assertNoLinks(ctx.dataPath, dir);
     const file = newestLog(dir) ?? fail('No sandbox logs yet in ' + dir + '.', 'Logs appear after the first start (sandbox claude).');
     console.log('== ' + file + ' ==');
     let printed = 0;
@@ -102,8 +108,40 @@ const checkLocalConfig = (ctx) => {
     const overrides = normalizeOverrides(file.data, dir, file.path);
     const approved = isTrusted(trustStorePath(ctx.storageRoot), file.path, file.hash);
     console.log(file.path + ': valid. ' + (approved ? 'Approved (this exact version).' : 'Not approved yet: the next launch asks you.') + '\n');
-    for (const line of describeOverrides(overrides))
+    for (const line of describeOverrides(overrides, dir))
         console.log('  ' + safeText(line));
+    // What a launch from here would do with each folder and each looser setting, without launching.
+    const config = ctx.loaded.config;
+    const store = allowStorePath(ctx.storageRoot);
+    const workspaceGuest = guestWorkspaceOf(applyOverrides(config, overrides), dir).guest;
+    const outside = outsideMappings(dir, overrides.mappings);
+    const policy = config.projects.allowOutsideMappings;
+    const rows = (overrides.mappings ?? []).map((m) => {
+        const where = previewGuest(m, dir, workspaceGuest);
+        const status = !dirExists(m.host) ? (m.optional ? 'not on this PC: skipped' : c.red('the folder does not exist: create it, fix the path, or add "optional": true'))
+            : !outside.includes(m) ? (m.guest ? 'inside the project' : 'inside the project (already in the sandbox there)')
+                : policy === true ? 'outside the project, allowed (projects.allowOutsideMappings is true)'
+                    : policy === false ? c.red('outside the project: refused (projects.allowOutsideMappings is false)')
+                        : allowedAnswer(store, file.path, OUTSIDE_FOLDER, outsideKey(m)) === true ? 'outside the project, allowed (you said yes)'
+                            : c.yellow('outside the project: the next interactive launch asks you');
+        return [(m.readOnly ? 'ro ' : 'rw ') + safeText(m.host), '->  ' + safeText(where.guest), status];
+    });
+    if (rows.length) {
+        console.log('\nFolders (where they appear in the sandbox):');
+        table(rows);
+    }
+    for (const m of overrides.mappings ?? []) {
+        const note = dirExists(m.host) ? previewGuest(m, dir, workspaceGuest).note : null;
+        if (note)
+            console.log('  ' + safeText(note));
+    }
+    const looser = loosenedRequests(config, overrides);
+    if (looser.length)
+        console.log('\nLooser than your settings (used only if you allow it for this project):');
+    for (const a of looser) {
+        const answer = allowedAnswer(store, file.path, a.key, a.wanted);
+        console.log('  ' + a.key + ' = ' + JSON.stringify(a.wanted) + ': ' + (answer === true ? 'allowed (you said yes)' : answer === false ? 'not used (you said no)' : 'the next interactive launch asks you'));
+    }
     return 0;
 };
 export const config = (ctx) => {
@@ -152,3 +190,31 @@ export const doctor = (ctx) => {
 };
 export const claudeHost = (ctx) => hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);
 export const watcher = (ctx) => watch(ctx.dataPath);
+const KINDS = ['proc', 'file', 'session', 'guard', 'note'];
+const KIND_LABEL = { proc: 'program', file: 'file', session: 'session', guard: 'GUARD', note: 'note' };
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export const audit = async (ctx) => {
+    const settings = ctx.loaded.config.audit;
+    const kind = ctx.options.kind;
+    if (kind && !KINDS.includes(kind))
+        fail('Unknown kind "' + kind + '".', 'Use one of: ' + KINDS.join(', '));
+    const log = new AuditLog(AuditLog.dirFor(ctx.storageRoot, ctx.dataPath), settings);
+    const events = log.read({ days: ctx.options.days, kinds: kind ? [kind] : undefined, grep: ctx.options.grep });
+    if (printJson(ctx, events))
+        return 0;
+    if (!events.length) {
+        console.log(settings.enabled ? 'Nothing in the audit log for the last ' + ctx.options.days + ' day(s).' : 'The audit log is off. Turn it on in the menu (Settings > Security & privacy > Audit log) or with audit.enabled in your config.');
+        return 0;
+    }
+    for (const e of events) {
+        // What the sandbox reported is text from the sandbox: no control codes reach your terminal.
+        const [p, cmd, parent, dir, act] = [e.p, e.c, e.pp, e.w, e.a].map((v) => plainText(v ?? ''));
+        const what = e.k === 'proc' ? (cmd || p) + (parent ? c.dim('  <- ' + path.win32.basename(parent)) : '')
+            : e.k === 'file' ? act + ' ' + p + c.dim('  in ' + dir)
+                : e.k === 'session' ? act + ' ' + p + c.dim('  ' + dir + ' ' + cmd)
+                    : p;
+        console.log(c.dim(new Date(e.t).toLocaleString()) + '  ' + (e.k === 'guard' ? c.yellow(KIND_LABEL[e.k].padEnd(8)) : KIND_LABEL[e.k].padEnd(8)) + what + (e.n && e.n > 1 ? c.dim('  x' + e.n) : ''));
+    }
+    console.log(c.dim('\n' + events.length + ' event(s); the log takes ' + humanBytes(log.bytes()) + ' (' + AuditLog.dirFor(ctx.storageRoot, ctx.dataPath) + ').'));
+    return 0;
+};

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

@@ -1,4 +1,5 @@
 import type { SandboxStatus } from '../../core/types.js';
+import { type Missing } from '../../core/project-policy.js';
 import { type RegistryEntry } from '../../host/projects.js';
 import type { ProjectSpecT } from '../../shared/schema.js';
 import { type Context } from './context.js';
@@ -17,12 +18,15 @@ export interface Joined {
     harness: string | null;
     notes: string[];
 }
-/**
- * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
- * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
- * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
- */
-export declare const joinHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;
+/** restart.ts: the sandbox was restarted for a project in this command. */
+export declare const markRestarted: () => void;
+export declare const joinHere: (ctx: Context, status: SandboxStatus, o?: {
+    noRestart?: boolean;
+}) => Promise<Joined>;
+/** The command that restarts the running sandbox with this folder's boot wishes (consent given by --yes). */
+export declare const restartCommand: (ctx: Context, host: string) => string;
+/** Joined without what it wants at boot: what is missing, how to restart with it, and how to always have it. */
+export declare const missingNotes: (ctx: Context, name: string, host: string, missing: Missing, shown?: boolean) => string[];
 /** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
 export declare const provisionJoined: (ctx: Context, joined: Joined) => Promise<void>;
 /** joinHere, then (for another project) waits until the sandbox has set it up. */

package/dist/cli/commands/project.js

@@ -2,13 +2,17 @@
 // these, so they all agree: `locateHere` only looks (attach, sessions, status, restart), `joinHere` also makes the
 // folder a project of the running sandbox when it can without a restart (launch, start, exec, db).
 import path from 'node:path';
+import { select } from '@inquirer/prompts';
+import { describeMissing, missingTip } from '../../core/project-policy.js';
 import { askYesNo } from '../../core/prompt.js';
 import { isInsideOrEqual } from '../../core/util.js';
 import { resolveRun } from '../../core/workspace.js';
-import { prepareProject } from '../../host/channel.js';
+import { currentSessions, prepareProject } from '../../host/channel.js';
 import { projectHere, readRegistry } from '../../host/projects.js';
 import { joinRunning } from '../../host/join.js';
+import { c } from '../colors.js';
 import { working } from '../progress.js';
+import { describeSessions } from './restart.js';
 import { guestPathFor, sandboxAlive } from './context.js';
 /** The folder the command is about: --workspace, else the current one. */
 export const hereDir = (ctx) => path.resolve(ctx.options.workspace ?? process.cwd());
@@ -28,12 +32,16 @@ export const locateHere = (ctx, status) => {
  * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
  * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
  */
-export const joinHere = async (ctx, status) => {
+let restartedOnce = false;
+/** restart.ts: the sandbox was restarted for a project in this command. */
+export const markRestarted = () => { restartedOnce = true; };
+export const joinHere = async (ctx, status, o = {}) => {
     const { options, loaded, packageRoot, storageRoot, dataPath } = ctx;
     const dir = hereDir(ctx);
     // A sandbox started before projects existed: only its launch folder (guestPathFor explains why otherwise).
     if (!readRegistry(storageRoot))
         return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace), spec: null, harness: null, notes: [] };
+    let shown = false;
     const joined = await joinRunning({
         storageRoot, dataPath, packageRoot, hostDir: dir, wsbShare: loaded.config.projects.wsbShare,
         resolve: (root) => resolveRun({
@@ -41,10 +49,41 @@ export const joinHere = async (ctx, status) => {
             noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases,
             nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
         }),
+        // Something it wants only comes with a restart: --yes restarts, a terminal asks, anything else continues.
+        decide: async (name, missing) => {
+            // Once per command: what a restart could not give (see the launch notes) never restarts it again.
+            if (o.noRestart || restartedOnce)
+                return 'continue';
+            if (options.yes)
+                return 'restart';
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                return 'continue';
+            console.log(c.yellow(describeMissing(name, missing)));
+            shown = true;
+            const sessions = currentSessions(dataPath);
+            return select({
+                message: 'What now?',
+                choices: [
+                    { name: 'Continue anyway (join without them)', value: 'continue' },
+                    { name: 'Restart with them (' + (sessions.length ? describeSessions(sessions) + ' will end' : 'no session is running') + ')', value: 'restart' },
+                    { name: 'Cancel', value: 'cancel' },
+                ],
+                default: 'continue',
+            });
+        },
     });
     const harness = joined.run && joined.run.harnessName !== 'none' ? joined.run.harnessName : null;
-    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes: joined.notes };
+    const notes = joined.missing ? [...joined.notes, ...missingNotes(ctx, joined.project.name, joined.project.host, joined.missing, shown)] : joined.notes;
+    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes };
 };
+/** The command that restarts the running sandbox with this folder's boot wishes (consent given by --yes). */
+export const restartCommand = (ctx, host) => 'sandbox ' + (ctx.options.noAgent ? 'start' : ctx.options.harness ?? ctx.loaded.config.defaultHarness) + ' --workspace "' + host + '" --yes';
+/** Joined without what it wants at boot: what is missing, how to restart with it, and how to always have it. */
+export const missingNotes = (ctx, name, host, missing, shown = false) => [
+    ...(shown ? [] : [c.yellow(describeMissing(name, missing))]),
+    'Joined without them. To restart the sandbox with them (its sessions end): ' + restartCommand(ctx, host),
+    c.dim(missingTip(missing)),
+];
 /** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
 export const provisionJoined = async (ctx, joined) => {
     if (!joined.spec)

package/dist/cli/commands/restart.js

@@ -5,6 +5,7 @@
 // where the agent supports it) and then starts the new project's session.
 import path from 'node:path';
 import _ from 'lodash';
+import { missingTip } from '../../core/project-policy.js';
 import { askYesNo } from '../../core/prompt.js';
 import { fail, safeText, sleep } from '../../core/util.js';
 import { currentSessions, execInSandbox } from '../../host/channel.js';
@@ -44,14 +45,20 @@ export const offerRestart = async (ctx, needs, then) => {
     const registry = readRegistry(ctx.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again from ' + folders[0] + '.');
     const primary = registry.projects.find((p) => p.primary) ?? fail('The running sandbox has no launch folder on record.', 'Stop it (sandbox stop) and start it again.');
     const sessions = currentSessions(ctx.dataPath);
-    for (const need of needs)
+    // A project that only wants boot settings or folders: you already chose the restart (or gave --yes) when asked.
+    const hidden = needs.filter((n) => !n.missing);
+    for (const need of hidden)
         console.log(c.yellow('Windows Sandbox cannot add ' + need.hostDir + ' while it runs: ' + need.reason + '.'));
-    console.log('A restart maps ' + (needs.length === 1 ? 'it' : 'them') + ' as well (and keeps ' + registry.projects.map((p) => p.host).join(', ') + '). ' +
+    console.log((hidden.length ? 'A restart maps ' + (hidden.length === 1 ? 'it' : 'them') + ' as well' : 'Restarting with what ' + needs.map((n) => path.basename(n.hostDir)).join(', ') + ' wants') +
+        ' (and keeps ' + registry.projects.map((p) => p.host).join(', ') + '). ' +
         (sessions.length ? describeSessions(sessions) + ' will end' : 'No session is running') + '; your files, tools, databases and logins are kept. It takes about a minute.');
-    for (const parent of _.uniq(folders.map((f) => path.dirname(f))))
+    for (const parent of _.uniq(hidden.map((n) => path.dirname(n.hostDir))))
         console.log(c.dim('No restart next time for folders in ' + parent + ': sandbox projects roots add "' + parent + '"'));
+    for (const need of needs)
+        if (need.missing)
+            console.log(c.dim(missingTip(need.missing)));
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    if (!ctx.options.yes) {
+    if (!ctx.options.yes && hidden.length) {
         if (!interactive)
             fail('Not restarting without your consent.', 'Run it again with --yes to restart: ' + againWithYes(ctx));
         if (!(await askYesNo('Restart the sandbox now?'))) {
@@ -62,9 +69,10 @@ export const offerRestart = async (ctx, needs, then) => {
     const reopen = sessionsToReopen(registry, sessions);
     const resume = reopen.length > 0 && (ctx.options.yes || (await askYesNo('Reopen the ' + reopen.length + ' session(s) afterwards (continuing their conversations where the agent supports it)?', true)));
     await stopAndWait(ctx);
-    // Imported here: launch.ts imports this file.
+    // Imported here: launch.ts imports this file (and project.ts imports describeSessions).
     const { launch, openSession, readySandbox } = await import('./launch.js');
-    const { joinHere } = await import('./project.js');
+    const { joinHere, markRestarted } = await import('./project.js');
+    markRestarted();
     const keep = registry.projects.filter((p) => !p.primary && p.mechanism !== 'root').map((p) => p.host);
     const relaunch = { ...ctx, options: { ...ctx.options, workspace: primary.host, harness: ctx.options.harness ?? ctx.options.sessions[0]?.harness, terminal: false, noAgent: false, newSession: true, passthrough: [], sessions: [] } };
     await launch(relaunch, false, { extraProjects: [...keep, ...folders], autoSession: false, waitUntilReady: true });
@@ -73,7 +81,9 @@ export const offerRestart = async (ctx, needs, then) => {
         for (const s of reopen) {
             const at = { ...ctx, options: { ...ctx.options, workspace: s.hostDir, harness: s.harness, terminal: false, newSession: true, passthrough: [], sessions: [] } };
             try {
-                const joined = await joinHere(at, ready);
+                const joined = await joinHere(at, ready, { noRestart: true });
+                for (const note of joined.notes)
+                    console.log(note);
                 await openSession(at, ready, joined, { attach: false, harness: s.harness, args: ctx.loaded.config.harnesses[s.harness]?.resumeArguments ?? [], reuse: false });
             }
             catch (e) {

package/dist/cli/commands/sessions.js

@@ -40,7 +40,7 @@ export const attach = async (ctx) => {
         const projects = readRegistry(ctx.storageRoot)?.projects ?? [];
         const chosen = await select({
             message: 'Which session?' + (here.project ? ' (' + here.project.name + ' first)' : ''),
-            choices: running.map((s) => ({ value: s.id, name: (here.guestDir && isWithin(here.guestDir, s.cwd) ? '* ' : '  ') + safeText(s.harness).padEnd(9) + ' ' + projectOf(projects, s).padEnd(16) + ' ' + ago(s.startedAt).padEnd(11) + ' ' + s.id })),
+            choices: running.map((s) => ({ value: s.id, name: (here.guestDir && isWithin(here.guestDir, s.cwd) ? '* ' : '  ') + safeText(s.harness).padEnd(9) + ' ' + safeText(projectOf(projects, s)).padEnd(16) + ' ' + ago(s.startedAt).padEnd(11) + ' ' + s.id })),
         });
         return attachHere(ctx, pickSession(ctx.dataPath, chosen));
     }
@@ -155,13 +155,14 @@ const printExecResult = (result) => {
     if (result.stderr)
         process.stderr.write(safeText(result.stderr));
     if (!result.ok && !result.stdout && !result.stderr)
-        console.error(result.message);
+        console.error(safeText(result.message));
 };
 /** The guest folder for this folder, joining the running sandbox (and setting the project up) when needed. */
 const guestFolderHere = async (ctx, what) => {
     const ready = await readySandbox(ctx.dataPath);
     try {
-        const joined = await joinHere(ctx, ready);
+        // A command needs no restart for what the project wants at boot: it runs without them (and says so).
+        const joined = await joinHere(ctx, ready, { noRestart: true });
         for (const note of joined.notes)
             console.error(note);
         await provisionJoined(ctx, joined);
@@ -210,7 +211,7 @@ export const restart = async (ctx) => {
     const scope = ctx.options.all || !here.project ? undefined : here.project.guest;
     if (!scope && !ctx.options.all)
         console.log(c.dim(hereDir(ctx) + ' is not a project of the running sandbox: restarting every session.'));
-    console.log((await working('Restarting the agents' + (scope ? ' of ' + here.project?.name : ''), () => restartSessions(ctx.dataPath, ctx.options.harness ?? null, sandboxAlive, scope))).message);
+    console.log(safeText((await working('Restarting the agents' + (scope ? ' of ' + here.project?.name : ''), () => restartSessions(ctx.dataPath, ctx.options.harness ?? null, sandboxAlive, scope))).message));
     return 0;
 };
 export const stop = async (ctx) => {

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

@@ -6,7 +6,7 @@ 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';
+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) => {

package/dist/cli/index.js

@@ -5,11 +5,11 @@ 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 { 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');
@@ -30,6 +30,7 @@ const HANDLERS = {
     projects: commands.projects,
     sync: commands.sync,
     logs: commands.logs,
+    audit: commands.audit,
     clean: commands.clean,
     config: commands.config,
     doctor: commands.doctor,
@@ -106,9 +107,10 @@ 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);
+        // 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(c.red('Unexpected error: ') + errMsg(e));

package/dist/cli/manifest.js

@@ -57,7 +57,7 @@ const SANDBOX_OPTIONS = [
     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 }),
+    bool('--yes', 'when this folder is not in the running sandbox, or wants what it started without (vGPU, folders), restart without asking', { noMenu: true }),
 ];
 const AGENT_OPTIONS = [
     text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),
@@ -93,6 +93,11 @@ export const COMMANDS = z.array(CommandSpec).parse([
     { 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: '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' })] },

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