windows-development-sandbox 1.1.0 → 1.4.0

package/README.md

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

package/config.example.json

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

package/dist/cli/args.d.ts

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

package/dist/cli/args.js

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

package/dist/cli/commands/accounts.js

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

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

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

package/dist/cli/commands/context.js

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

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

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

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

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

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

@@ -6,5 +6,5 @@ export { repairCommand } from './repair/index.js';
 export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
 export { account } from './accounts.js';
 export { projects } from './projects.js';
-export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
 export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/index.js

@@ -6,5 +6,5 @@ export { repairCommand } from './repair/index.js';
 export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
 export { account } from './accounts.js';
 export { projects } from './projects.js';
-export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
 export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/launch.js

@@ -13,7 +13,12 @@ import { findSecretFiles } from '../../host/secrets.js';
 import { checkRepo, saveRepoSnapshot } from '../../host/repo-guard.js';
 import { assertCanLaunch, insideSandbox, isSandboxRunning, probeHost, spawnDetached, startSandbox } from '../../host/platform.js';
 import { NeedsRestart, rememberProject, startRegistry } from '../../host/projects.js';
-import { ensureTerminal } from '../../host/terminal.js';
+import { ensureConpty, ensureTerminal } from '../../host/terminal.js';
+import { planView, saveActiveViews, viewSkipped, WorkspaceView } from '../../host/workspace-view/index.js';
+import { saveForwards } from '../../host/port-forward.js';
+import { saveAuditSettings } from '../../host/audit/collect.js';
+import { readDataSize, saveMarkedProjects } from '../../host/motw.js';
+import { humanBytes } from '../../core/disk.js';
 import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
 import { readSandboxStatus } from '../../shared/rundir.js';
 import { isWithin } from '../../shared/projects.js';
@@ -31,6 +36,7 @@ import _ from 'lodash';
 import { hereDir, joinHere, readyHere } from './project.js';
 import { offerRestart } from './restart.js';
 import { addToList, setSetting } from './user-config.js';
+import { lastStopWarning, startLife, UPDATE_RESTART_WARNING, updateRestartPending } from '../../host/stops.js';
 /** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
 export const attachHere = (ctx, session) => {
     if (ctx.loaded.config.attach.autoHide && !insideSandbox())
@@ -216,6 +222,25 @@ const maybeAddRoot = async (ctx, run) => {
     if (answer === 'never')
         setSetting(ctx, ['projects', 'askToAddRoot'], false);
 };
+/**
+ * workspaceFilter: brings the project's filtered view in step before the sandbox maps it, and tells the background
+ * watcher to keep it in step while the sandbox runs. Returns the line for the launch table.
+ */
+const prepareWorkspaceView = async (ctx, run) => {
+    const plan = planView(run.config, ctx.storageRoot, run.workspaceHost);
+    saveActiveViews(ctx.storageRoot, ctx.dataPath, plan ? [plan.options] : []);
+    saveForwards(ctx.storageRoot, ctx.dataPath, run.config.sandbox.networking ? run.config.network.forwardPorts : []);
+    saveAuditSettings(ctx.storageRoot, ctx.dataPath, { ...run.config.audit, projects: [run.workspaceHost] });
+    saveMarkedProjects(ctx.storageRoot, ctx.dataPath, run.config.storage.markSandboxFiles ? [run.workspaceHost] : []);
+    const size = readDataSize(ctx.storageRoot, ctx.dataPath);
+    const limit = run.config.storage.warnDataGb;
+    if (limit > 0 && size && size.bytes > limit * 1024 ** 3)
+        console.warn(c.yellow('The persisted data takes ' + humanBytes(size.bytes) + ' (more than storage.warnDataGb, ' + limit + ' GB). See what: sandbox data; free space: sandbox data clean <what>.'));
+    if (!plan)
+        return viewSkipped(run.config, run.workspaceHost) ?? 'off (git-ignored files are visible in the sandbox; workspaceFilter.enabled keeps them out)';
+    const stats = await working('Preparing the workspace without its git-ignored files', () => new WorkspaceView(plan.options).prepare());
+    return 'on: git-ignored files stay on this PC' + (stats.toView || stats.toHost ? ' (' + stats.toView + ' copied in, ' + stats.toHost + ' out' + (stats.conflicts ? ', ' + stats.conflicts + ' conflicts kept next to the file' : '') + ')' : '') + '; ' + plan.options.view;
+};
 /** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
 const prepare = async (ctx, run) => {
     const { options, dataPath, storageRoot } = ctx;
@@ -224,12 +249,19 @@ const prepare = async (ctx, run) => {
     if (account && run.harnessName === 'claude' && account !== activeAccount(dataPath))
         activateAccount(storageRoot, dataPath, account);
     const terminal = config.provisioning.terminal.enabled ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false }) : { exe: null, message: 'disabled' };
+    const conpty = config.provisioning.conpty.enabled ? await ensureConpty(dataPath, config.provisioning.refresh) : 'off';
     const history = syncSummary(config, dataPath, run.workspaceHost);
     const guarded = checkRepo(dataPath);
     if (guarded.length)
         console.warn(c.yellow('SECURITY: neutralised ' + guarded.length + ' change(s) the last sandbox made that could run code on this PC (see sandbox status).'));
+    const stopped = lastStopWarning(storageRoot, dataPath, watcherRunning(dataPath));
+    if (stopped)
+        console.warn(c.yellow(stopped));
+    if (updateRestartPending())
+        console.warn(c.yellow(UPDATE_RESTART_WARNING));
     resetRunDir(dataPath);
-    return { account, terminal: terminal.message, history, pruned: describePrune(pruneStorage(storageRoot)) };
+    const filter = await prepareWorkspaceView(ctx, run);
+    return { account, terminal: terminal.message + '; pseudo console: ' + conpty, history, pruned: describePrune(pruneStorage(storageRoot)), filter };
 };
 export const launch = async (ctx, generateOnly = false, extras = {}) => {
     const { options, loaded, packageRoot, dataPath, storageRoot } = ctx;
@@ -284,7 +316,7 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
         ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
         ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   CPU: ' + (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') + '   Network: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
         ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
-        ...(prepared ? [['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
+        ...(prepared ? [['Ignored files', prepared.filter], ['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
         ['Toolchains', Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name, d]) => name + ' (' + d.reason + ')').join(', ') || 'Node only (nothing else used by this project)'],
         ...(generated.databases.length
             ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; use Postgres or SQLite for local work)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
@@ -304,6 +336,7 @@ export const launch = async (ctx, generateOnly = false, extras = {}) => {
     saveRepoSnapshot(dataPath, run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
     startRegistry(storageRoot, { launchId: generated.launchId, protections: protectionsOf(config), primary: { host: run.workspaceHost, guest: config.guestWorkspace }, roots, boot: projects });
     rememberProject(storageRoot, run.workspaceHost);
+    startLife(storageRoot, dataPath, config.sandbox.keepAwake);
     startSandbox(generated.wsbPath);
     // Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently.
     if (!watcherRunning(dataPath))

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

@@ -6,3 +6,5 @@ export declare const config: (ctx: Context) => number;
 export declare const doctor: (ctx: Context) => number;
 export declare const claudeHost: (ctx: Context) => number;
 export declare const watcher: (ctx: Context) => Promise<void>;
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export declare const audit: (ctx: Context) => Promise<number>;

package/dist/cli/commands/maintenance.js

@@ -5,14 +5,17 @@ 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 { assertNoLinks, 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 +31,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;
@@ -152,3 +157,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/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,7 +155,7 @@ 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) => {
@@ -210,7 +210,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

@@ -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;