windows-development-sandbox 1.1.0 → 1.4.0

package/dist/runtime/view.js

@@ -5533,7 +5533,7 @@ var require_lodash = __commonJS({
 
 // src/shared/pty-client.ts
 import net from "node:net";
-var FrameType = { Hello: 1, Input: 2, Resize: 3, Restart: 4, Ping: 5, Output: 16, Exit: 17, Error: 18, Restarting: 19, Status: 20 };
+var FrameType = { Hello: 1, Input: 2, Resize: 3, Restart: 4, Ping: 5, Output: 16, Exit: 17, Error: 18, Restarting: 19, Status: 20, Console: 21 };
 var PING_INTERVAL_MS = 5e3;
 var encodeFrame = (type, payload = Buffer.alloc(0)) => {
   const header = Buffer.alloc(5);
@@ -5570,18 +5570,111 @@ var FrameReader = class {
     return frames;
   }
 };
+var KEPT_OSC = (body) => {
+  const number4 = /^(\d{1,4})(;|$)/.exec(body);
+  if (!number4) return false;
+  const n = Number(number4[1]);
+  return n <= 2 || n === 8 || n === 133 || n === 9 && body.startsWith(number4[1] + ";4;");
+};
+var MAX_KEPT_STRING = 4096;
 var OutputFilter = class {
-  carry = "";
+  /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+  state = "text";
+  /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+  body = null;
   push(chunk) {
-    let text = (this.carry + chunk.toString("latin1")).replace(/\x1b\]52;[^\x07\x1b]*(\x07|\x1b\\)/g, "");
-    this.carry = "";
-    const open2 = text.lastIndexOf("\x1B");
-    const tail = open2 === -1 ? "" : text.slice(open2);
-    if (tail.length < 1 << 16 && /^\x1b(\](5(2(;[^\x07\x1b]*)?)?)?)?$/.test(tail)) {
-      this.carry = tail;
-      text = text.slice(0, open2);
+    const out = Buffer.allocUnsafe(chunk.length + MAX_KEPT_STRING + 8);
+    let n = 0;
+    const put = (...bytes) => {
+      for (const b of bytes) out[n++] = b;
+    };
+    const opens = (b, c1) => {
+      if (b === (c1 ? 157 : 93)) {
+        this.body = c1 ? null : [];
+        this.state = "string";
+        return true;
+      }
+      if ((c1 ? [144, 152, 158, 159] : [80, 88, 94, 95]).includes(b)) {
+        this.body = null;
+        this.state = "string";
+        return true;
+      }
+      return false;
+    };
+    const endString = (terminator) => {
+      const body = this.body && Buffer.from(this.body).toString("latin1");
+      if (body !== null && KEPT_OSC(body)) {
+        put(27, 93);
+        out.write(body, n, "latin1");
+        n += body.length;
+        put(...terminator);
+      }
+      this.body = null;
+      this.state = "text";
+    };
+    const collect = (b) => {
+      if (this.body && this.body.push(b) > MAX_KEPT_STRING) this.body = null;
+    };
+    for (const b of chunk) {
+      switch (this.state) {
+        case "text":
+          if (b === 27) this.state = "esc";
+          else if (b === 194) this.state = "c2";
+          else put(b);
+          break;
+        case "esc":
+          if (opens(b, false)) break;
+          if (b !== 27) {
+            put(27, b);
+            this.state = "text";
+          } else put(27);
+          break;
+        case "c2":
+          if (opens(b, true)) break;
+          if (b === 27) {
+            put(194);
+            this.state = "esc";
+          } else if (b === 194) put(194);
+          else {
+            put(194, b);
+            this.state = "text";
+          }
+          break;
+        case "string":
+          if (b === 7) endString([7]);
+          else if (b === 27) this.state = "stringEsc";
+          else if (b === 194) this.state = "stringC2";
+          else if (b === 24 || b === 26) {
+            this.body = null;
+            this.state = "text";
+          } else collect(b);
+          break;
+        case "stringC2":
+          if (b === 156) endString([27, 92]);
+          else {
+            collect(194);
+            this.state = "string";
+            if (b === 7) endString([7]);
+            else if (b === 27) this.state = "stringEsc";
+            else if (b !== 194) collect(b);
+            else this.state = "stringC2";
+          }
+          break;
+        case "stringEsc":
+          if (b === 92) {
+            endString([27, 92]);
+            break;
+          }
+          this.body = null;
+          this.state = "esc";
+          if (!opens(b, false) && b !== 27) {
+            put(27, b);
+            this.state = "text";
+          }
+          break;
+      }
     }
-    return Buffer.from(text, "latin1");
+    return out.subarray(0, n);
   }
 };
 var connectOnce = (host, port, timeoutMs) => {
@@ -5652,11 +5745,12 @@ var runTerminalClient = (socket, token, options = {}) => {
       }
       socket.write(encodeFrame(FrameType.Input, swapKeys ? fixWindowsKeys(chunk) : chunk));
     };
+    let passthrough = false;
     const sendSize = () => {
       const [c2, r2] = size();
       if (c2 === sent[0] && r2 === sent[1]) return;
       sent = [c2, r2];
-      stdout.write("\x1B[H\x1B[J");
+      if (!passthrough) stdout.write("\x1B[H\x1B[J");
       socket.write(resizeFrame(c2, r2));
     };
     const onResize = () => {
@@ -5680,6 +5774,7 @@ var runTerminalClient = (socket, token, options = {}) => {
       }
       for (const frame of frames) {
         if (frame.type === FrameType.Output) stdout.write(filter.push(frame.payload));
+        else if (frame.type === FrameType.Console) passthrough = frame.payload.toString("latin1") === "conpty.dll";
         else if (frame.type === FrameType.Restarting) stdout.write("\x1B[2J\x1B[3J\x1B[H");
         else if (frame.type === FrameType.Exit) finish({ reason: "exit", exitCode: frame.payload.length >= 4 ? frame.payload.readInt32LE(0) : 1 });
         else if (frame.type === FrameType.Error) finish({ reason: "error", message: frame.payload.toString("utf8").slice(0, 500).replace(/[\x00-\x1f\x7f]/g, " ") });
@@ -25473,8 +25568,10 @@ var ClaudeProfile = external_exports.strictObject({
   globalStateFile: external_exports.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
   copyCredentials: external_exports.boolean().describe("Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead."),
   overwrite: external_exports.boolean().describe("Refresh these settings from this PC on every launch."),
-  syncHistory: external_exports.boolean().describe("Bring all conversation history in, and sync new history back (path-translated)."),
-  syncClaudeMem: external_exports.boolean().describe("Bring claude-mem data in, and its database back when the sandbox closes.")
+  syncHistory: external_exports.boolean().describe("Bring conversation history in, and sync new history back (path-translated)."),
+  historyScope: external_exports.enum(["project", "all"]).describe(`Which history comes in: "project" = only the projects in this sandbox (other projects' conversations, file backups and prompts stay on this PC), "all" = everything. Only this sandbox's projects ever sync back.`),
+  syncClaudeMem: external_exports.boolean().describe("Bring claude-mem data into the sandbox (its settings and backups stay on this PC)."),
+  syncClaudeMemBack: external_exports.boolean().describe("Also copy claude-mem's database back to this PC when the sandbox closes. Off by default: what is in it is loaded into every Claude session on this PC, so a compromised agent could plant instructions there.")
 });
 
 // src/core/schema/sandbox.ts
@@ -25490,6 +25587,7 @@ var Sandbox = external_exports.strictObject({
   maxMemoryMb: external_exports.number().int().positive().describe('Upper limit for memoryMb "auto".'),
   maxMemoryPercent: external_exports.number().int().min(10).max(100).describe(`memoryMb "auto" never takes more than this share of this PC's total RAM (percent).`),
   cpuLimit: external_exports.union([external_exports.literal("none"), external_exports.number().int().min(5).max(100)]).describe(`Most of this PC's CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; "none" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal).`),
+  pageFileMb: external_exports.number().int().min(0).max(262144).describe(`Size of the sandbox's paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows' own.`),
   reserveHostMb: external_exports.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
   vGpu: external_exports.boolean().describe("Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."),
   networking: external_exports.boolean().describe("Internet access. false is the only hard network isolation Windows Sandbox offers."),
@@ -25498,7 +25596,33 @@ var Sandbox = external_exports.strictObject({
   videoInput: external_exports.boolean().describe("Camera access."),
   printerRedirection: external_exports.boolean().describe("Printers from this PC."),
   protectedClient: external_exports.boolean().describe("Run the sandbox window in Protected Client mode (recommended)."),
-  headless: external_exports.boolean().describe("Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.")
+  headless: external_exports.boolean().describe("Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends."),
+  keepAwake: external_exports.boolean().describe("Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it).")
+});
+var Port2 = external_exports.number().int().min(1).max(65535);
+var HostEntry = external_exports.string().max(253).regex(/^(@developer|(\*\.)?([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+)$/, "a host name like example.com, *.example.com, or @developer");
+var Network = external_exports.strictObject({
+  blockPrivateRanges: external_exports.boolean().describe("Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox."),
+  allowOnly: external_exports.array(HostEntry).describe("Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit."),
+  blockHosts: external_exports.array(external_exports.string().max(253).regex(/^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/, "a host name like telemetry.example.com")).describe("Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox's hosts file sends them nowhere)."),
+  forwardPorts: external_exports.array(external_exports.strictObject({
+    pc: Port2.describe("The port on this PC (localhost only)."),
+    sandbox: Port2.describe("The port inside the sandbox (a server there may listen on localhost only).")
+  })).describe("Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them."),
+  dns: external_exports.array(external_exports.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/, "an IPv4 address like 1.1.1.1")).describe("DNS servers for the sandbox instead of your network's, e.g. 1.1.1.1 and 9.9.9.9."),
+  proxy: external_exports.string().regex(/^(https?:\/\/[^\s]+)?$/, "http://host:port").describe("An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.")
+});
+var Audit = external_exports.strictObject({
+  enabled: external_exports.boolean().describe("Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit."),
+  days: external_exports.number().int().min(1).max(365).describe("Days the audit log is kept."),
+  maxMb: external_exports.number().int().min(5).max(5e3).describe("Most space the audit log may take, in MB (older days go first). Days before today are compressed."),
+  processes: external_exports.boolean().describe("Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed)."),
+  files: external_exports.boolean().describe("Record the files changed in the project while the sandbox runs.")
+});
+var WorkspaceFilter = external_exports.strictObject({
+  enabled: external_exports.boolean().describe("Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped."),
+  exclude: external_exports.array(external_exports.string().max(500)).describe("Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/."),
+  include: external_exports.array(external_exports.string().max(500)).describe("Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/.")
 });
 var Git = external_exports.strictObject({ enabled: external_exports.boolean().describe("Provide Git for Windows (and Git Bash, which Claude Code needs)."), access: GitAccess });
 var Provisioning = external_exports.strictObject({
@@ -25506,7 +25630,8 @@ var Provisioning = external_exports.strictObject({
   fallbackToInstall: external_exports.boolean().describe("Download anything that cannot be copied from this PC."),
   refresh: external_exports.boolean().describe("Re-copy / re-download everything on the next launch."),
   git: Git,
-  terminal: toggle("Windows Terminal as the sandbox window (downloaded once).")
+  terminal: toggle("Windows Terminal as the sandbox window (downloaded once)."),
+  conpty: toggle("Agent sessions use Microsoft's newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows.")
 });
 var Downloads = external_exports.strictObject({
   requireChecksum: external_exports.boolean().describe("Refuse any toolchain, database or tool download that has no published checksum (SHA-256/SHA-512) to verify it against. false = allow those, as before. Downloads that do have a published checksum are always verified. A project's .sandbox-config.json can only turn this on.")
@@ -25590,10 +25715,119 @@ var Toolchains = external_exports.strictObject({
     enabled: external_exports.boolean().describe("Mesa 3D (llvmpipe): OpenGL 4.5 in software for games and apps when there is no GPU (sandbox.vGpu off). Copy opengl32.dll and libgallium_wgl.dll from %MESA_DIR% next to the program's .exe."),
     vulkan: external_exports.boolean().describe("Also software Vulkan 1.4 (Mesa lavapipe) with the Khronos loader, registered for every program; for wgpu set WGPU_BACKEND=vulkan.")
   }),
-  vscode: toggle("Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."),
+  vscode: external_exports.strictObject({
+    enabled: external_exports.boolean().describe("Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."),
+    setup: external_exports.boolean().describe("Point VS Code at the sandbox's own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use."),
+    recommended: external_exports.boolean().describe("Also install the extensions a project recommends in its .vscode/extensions.json."),
+    extensions: external_exports.array(external_exports.string().regex(/^[\w-]+\.[\w-]+$/, "publisher.name, e.g. eamodio.gitlens")).describe("More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker.")
+  }),
   environment: external_exports.record(external_exports.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "letters, digits and _ only"), external_exports.string()).describe('Extra environment variables for the agent and every terminal, e.g. registry mirrors: {"NPM_CONFIG_REGISTRY": "https://...", "PIP_INDEX_URL": "https://..."}.')
 });
 
+// src/shared/apps.ts
+var gh = (github, asset) => ({ github, asset });
+var APPS = [
+  // ---- editors
+  { id: "vscode", name: "Visual Studio Code", category: "editors", about: "Code editor with debugging, set up for the sandbox's languages.", size: "150 MB", source: { resolve: "setting" }, exe: "Code.exe", setting: "toolchains.vscode.enabled" },
+  { id: "windows-terminal", name: "Windows Terminal", category: "utilities", about: "The sandbox window: tabs, panes, PowerShell 7 profile.", size: "40 MB", source: { resolve: "setting" }, exe: "WindowsTerminal.exe", setting: "provisioning.terminal.enabled" },
+  { id: "notepadpp", name: "Notepad++", category: "editors", about: "Fast text and code editor.", size: "8 MB", source: gh("notepad-plus-plus/notepad-plus-plus", "^npp\\.[\\d.]+\\.portable\\.x64\\.zip$"), exe: "notepad++.exe" },
+  { id: "sublime", name: "Sublime Text", category: "editors", about: "Fast code editor (paid licence, free to evaluate).", size: "28 MB", source: { resolve: "sublime" }, exe: "sublime_text.exe" },
+  { id: "neovim", name: "Neovim", category: "editors", about: "Terminal text editor (nvim).", size: "12 MB", source: gh("neovim/neovim", "^nvim-win64\\.zip$"), exe: "nvim.exe", cli: true },
+  // ---- database clients
+  { id: "dbeaver", name: "DBeaver Community", category: "databases", about: "Universal database client: PostgreSQL, MySQL, SQLite, SQL Server and more.", size: "120 MB", source: gh("dbeaver/dbeaver", "^dbeaver-ce-[\\d.]+-windows-x86_64\\.zip$"), exe: "dbeaver.exe" },
+  { id: "pgadmin", name: "pgAdmin 4", category: "databases", about: "The PostgreSQL admin GUI (from the PostgreSQL binaries zip).", size: "330 MB", source: { resolve: "pgadmin" }, exe: "pgAdmin4.exe" },
+  { id: "heidisql", name: "HeidiSQL", category: "databases", about: "Light client for MySQL, MariaDB, PostgreSQL and SQL Server.", size: "28 MB", source: gh("HeidiSQL/HeidiSQL", "^HeidiSQL_[\\d.]+_64_Portable\\.zip$"), exe: "heidisql.exe" },
+  { id: "sqlitebrowser", name: "DB Browser for SQLite", category: "databases", about: "Open, browse and edit SQLite files.", size: "21 MB", source: gh("sqlitebrowser/sqlitebrowser", "^DB\\.Browser\\.for\\.SQLite-v?[\\d.]+-win64\\.zip$"), exe: "DB Browser for SQLite.exe" },
+  { id: "compass", name: "MongoDB Compass", category: "databases", about: "The MongoDB GUI.", size: "220 MB", source: gh("mongodb-js/compass", "^mongodb-compass-[\\d.]+-win32-x64\\.zip$"), exe: "MongoDBCompass.exe" },
+  { id: "redisinsight", name: "Redis Insight", category: "databases", about: "The Redis GUI.", size: "110 MB", source: gh("redis/RedisInsight", "^Redis-Insight-win-installer\\.exe$"), unpack: "nsis", exe: "Redis Insight.exe", needs: ["7zip"] },
+  { id: "dbgate", name: "DbGate", category: "databases", about: "Database manager for SQL and NoSQL databases.", size: "180 MB", source: gh("dbgate/dbgate", "^dbgate-[\\d.]+-win_x64\\.zip$"), exe: "DbGate.exe" },
+  { id: "beekeeper", name: "Beekeeper Studio", category: "databases", about: "SQL editor and database manager.", size: "245 MB", source: gh("beekeeper-studio/beekeeper-studio", "^Beekeeper-Studio-[\\d.]+-portable\\.exe$"), unpack: "nsis", exe: "Beekeeper Studio.exe", needs: ["7zip"] },
+  { id: "dynamodb-admin", name: "dynamodb-admin", category: "databases", about: "Web GUI for DynamoDB Local: run dynamodb-admin, then open http://localhost:8001.", size: "5 MB", source: { npm: "dynamodb-admin" }, exe: "dynamodb-admin.cmd", cli: true },
+  // ---- API clients
+  { id: "bruno", name: "Bruno", category: "api", about: "Offline, git-friendly API client (collections are files in your repo).", size: "175 MB", source: gh("usebruno/bruno", "^bruno_[\\d.]+_x64_win\\.zip$"), exe: "Bruno.exe" },
+  { id: "insomnia", name: "Insomnia", category: "api", about: "REST, GraphQL and gRPC client.", size: "590 MB", source: gh("Kong/insomnia", "^insomnia-[\\d.]+-full\\.nupkg$"), exe: "Insomnia.exe" },
+  // ---- git
+  { id: "sourcegit", name: "SourceGit", category: "git", about: "Fast open-source Git GUI.", size: "26 MB", source: gh("sourcegit-scm/sourcegit", "^sourcegit_[\\d.]+\\.win-x64\\.zip$"), exe: "SourceGit.exe" },
+  { id: "githubdesktop", name: "GitHub Desktop", category: "git", about: 'Simple Git GUI from GitHub. It has its own git, so it needs provisioning.git.access "full".', size: "300 MB", source: gh("desktop/desktop", "^GitHubDesktop-[\\d.]+-x64-full\\.nupkg$"), exe: "GitHubDesktop.exe", fullGitOnly: true },
+  { id: "lazygit", name: "lazygit", category: "git", about: "Git in the terminal.", size: "7 MB", source: gh("jesseduffield/lazygit", "^lazygit_[\\d.]+_windows_x86_64\\.zip$"), exe: "lazygit.exe", cli: true },
+  // ---- utilities
+  { id: "7zip", name: "7-Zip", category: "utilities", about: "Archive manager (7z, zip, rar, tar ...). Also unpacks installers for other apps.", size: "2 MB", source: { resolve: "7zip" }, exe: "7zFM.exe" },
+  { id: "winmerge", name: "WinMerge", category: "utilities", about: "Compare and merge files and folders.", size: "23 MB", source: gh("WinMerge/winmerge", "^winmerge-[\\d.]+-x64-exe\\.zip$"), exe: "WinMergeU.exe" },
+  { id: "everything", name: "Everything", category: "utilities", about: "Finds files by name instantly.", size: "2 MB", source: { resolve: "everything" }, exe: "Everything.exe" },
+  { id: "sysinternals", name: "Sysinternals Suite", category: "utilities", about: "Process Explorer, Process Monitor, Autoruns, TCPView and more (on PATH).", size: "200 MB", source: { url: "https://download.sysinternals.com/files/SysinternalsSuite.zip" }, exe: "procexp64.exe" },
+  { id: "imhex", name: "ImHex", category: "utilities", about: "Hex editor for reverse engineering and binary formats.", size: "80 MB", source: gh("WerWolv/ImHex", "^imhex-[\\d.]+-Windows-Portable-NoGPU-x86_64\\.zip$"), exe: "imhex-gui.exe" },
+  // ---- browsers
+  { id: "chrome", name: "Chrome for Testing", category: "browsers", about: "Chrome build made for automated tests (with chromedriver on PATH).", size: "170 MB", source: { resolve: "chrome" }, exe: "chrome.exe" },
+  { id: "firefox", name: "Firefox", category: "browsers", about: "Firefox for testing.", size: "75 MB", source: { resolve: "firefox" }, unpack: "nsis", exe: "firefox.exe", needs: ["7zip"] },
+  // ---- game development
+  { id: "godot", name: "Godot", category: "gamedev", about: "Open-source 2D and 3D game engine.", size: "80 MB", source: gh("godotengine/godot", "^Godot_v[\\d.]+-stable_win64\\.exe\\.zip$"), exe: "/^Godot_v[\\d.]+-stable_win64\\.exe$/", needs: ["mesa"] },
+  { id: "blender", name: "Blender", category: "gamedev", about: "3D modelling, animation and rendering.", size: "400 MB", source: { resolve: "blender" }, exe: "blender.exe", needs: ["mesa"] },
+  { id: "love", name: "L\xD6VE", category: "gamedev", about: "Lua framework for 2D games.", size: "4 MB", source: gh("love2d/love", "^love-[\\d.]+-win64\\.zip$"), exe: "love.exe", needs: ["mesa"] },
+  { id: "defold", name: "Defold", category: "gamedev", about: "Free 2D/3D game engine and editor.", size: "330 MB", source: gh("defold/defold", "^Defold-x86_64-win32\\.zip$"), exe: "Defold.exe", needs: ["mesa"] },
+  { id: "pixelorama", name: "Pixelorama", category: "gamedev", about: "Pixel-art and sprite editor.", size: "40 MB", source: gh("Orama-Interactive/Pixelorama", "^Pixelorama-Windows-64bit\\.zip$"), exe: "Pixelorama.exe", needs: ["mesa"] },
+  { id: "tiled", name: "Tiled", category: "gamedev", about: "Tile map editor.", size: "22 MB", source: gh("mapeditor/tiled", "^Tiled-[\\d.]+_Windows-10\\+_x86_64\\.msi$"), unpack: "msi", exe: "tiled.exe" },
+  // ---- cloud
+  { id: "kubectl", name: "kubectl", category: "cloud", about: "Kubernetes command line.", size: "60 MB", source: { resolve: "kubectl" }, unpack: "file", exe: "kubectl.exe", cli: true },
+  { id: "helm", name: "Helm", category: "cloud", about: "Kubernetes package manager.", size: "20 MB", source: { resolve: "helm" }, exe: "helm.exe", cli: true },
+  { id: "k9s", name: "k9s", category: "cloud", about: "Kubernetes cluster UI in the terminal.", size: "40 MB", source: gh("derailed/k9s", "^k9s_Windows_amd64\\.zip$"), exe: "k9s.exe", cli: true },
+  { id: "terraform", name: "Terraform", category: "cloud", about: "Infrastructure as code.", size: "30 MB", source: { resolve: "terraform" }, exe: "terraform.exe", cli: true },
+  { id: "azure-cli", name: "Azure CLI", category: "cloud", about: "Manage Azure (az).", size: "90 MB", source: { url: "https://aka.ms/installazurecliwindowszipx64" }, exe: "az.cmd", cli: true },
+  { id: "gcloud", name: "Google Cloud CLI", category: "cloud", about: "Manage Google Cloud (gcloud, gsutil, bq).", size: "120 MB", source: { url: "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip" }, exe: "gcloud.cmd", cli: true },
+  { id: "aws-cli", name: "AWS CLI", category: "cloud", about: "Manage AWS (aws).", size: "50 MB", source: { url: "https://awscli.amazonaws.com/AWSCLIV2.msi" }, unpack: "msi", exe: "aws.exe", cli: true },
+  // ---- diagrams and docs
+  { id: "drawio", name: "draw.io", category: "diagrams", about: "Diagram editor (flowcharts, architecture, UML).", size: "170 MB", source: gh("jgraph/drawio-desktop", "^draw\\.io-[\\d.]+-windows\\.zip$"), exe: "draw.io.exe" },
+  { id: "pandoc", name: "Pandoc", category: "diagrams", about: "Convert documents between Markdown, HTML, Word, PDF ...", size: "35 MB", source: gh("jgm/pandoc", "^pandoc-[\\d.]+-windows-x86_64\\.zip$"), exe: "pandoc.exe", cli: true },
+  // ---- network
+  { id: "mitmproxy", name: "mitmproxy", category: "network", about: "Intercepting HTTPS proxy (mitmweb opens a web UI).", size: "90 MB", source: { resolve: "mitmproxy" }, exe: "mitmweb.exe", cli: true },
+  { id: "xh", name: "xh", category: "network", about: "Friendly HTTP requests from the terminal (like HTTPie).", size: "5 MB", source: gh("ducaale/xh", "^xh-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "xh.exe", cli: true },
+  { id: "grpcurl", name: "grpcurl", category: "network", about: "curl for gRPC servers.", size: "10 MB", source: gh("fullstorydev/grpcurl", "^grpcurl_[\\d.]+_windows_x86_64\\.zip$"), exe: "grpcurl.exe", cli: true },
+  { id: "k6", name: "k6", category: "network", about: "Load testing with JavaScript scripts.", size: "30 MB", source: gh("grafana/k6", "^k6-v[\\d.]+-windows-amd64\\.zip$"), exe: "k6.exe", cli: true },
+  // ---- command-line tools
+  { id: "jq", name: "jq", category: "cli", about: "Query and reshape JSON.", size: "1 MB", source: gh("jqlang/jq", "^jq-windows-amd64\\.exe$"), unpack: "file", exe: "jq.exe", cli: true },
+  { id: "yq", name: "yq", category: "cli", about: "Query and edit YAML, JSON, XML and TOML.", size: "10 MB", source: gh("mikefarah/yq", "^yq_windows_amd64\\.exe$"), unpack: "file", exe: "yq.exe", cli: true },
+  { id: "ripgrep", name: "ripgrep", category: "cli", about: "Very fast recursive search (rg).", size: "2 MB", source: gh("BurntSushi/ripgrep", "^ripgrep-[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "rg.exe", cli: true },
+  { id: "fd", name: "fd", category: "cli", about: "Fast, friendly alternative to find.", size: "2 MB", source: gh("sharkdp/fd", "^fd-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "fd.exe", cli: true },
+  { id: "bat", name: "bat", category: "cli", about: "cat with syntax highlighting and git changes.", size: "3 MB", source: gh("sharkdp/bat", "^bat-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "bat.exe", cli: true },
+  { id: "fzf", name: "fzf", category: "cli", about: "Fuzzy finder for the terminal.", size: "2 MB", source: gh("junegunn/fzf", "^fzf-[\\d.]+-windows_amd64\\.zip$"), exe: "fzf.exe", cli: true },
+  { id: "delta", name: "delta", category: "cli", about: "Readable git diffs with syntax highlighting.", size: "3 MB", source: gh("dandavison/delta", "^delta-[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "delta.exe", cli: true },
+  { id: "just", name: "just", category: "cli", about: "Command runner (a simpler make for project tasks).", size: "2 MB", source: gh("casey/just", "^just-[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "just.exe", cli: true },
+  { id: "hyperfine", name: "hyperfine", category: "cli", about: "Benchmark commands.", size: "1 MB", source: gh("sharkdp/hyperfine", "^hyperfine-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "hyperfine.exe", cli: true },
+  { id: "watchexec", name: "watchexec", category: "cli", about: "Run a command when files change.", size: "5 MB", source: gh("watchexec/watchexec", "^watchexec-[\\d.]+-x86_64-pc-windows-msvc\\.zip$"), exe: "watchexec.exe", cli: true },
+  { id: "protoc", name: "protoc", category: "cli", about: "Protocol Buffers compiler.", size: "3 MB", source: gh("protocolbuffers/protobuf", "^protoc-[\\d.]+-win64\\.zip$"), exe: "protoc.exe", cli: true },
+  { id: "ninja", name: "Ninja", category: "cli", about: "Small, fast build system (CMake's favourite generator).", size: "1 MB", source: gh("ninja-build/ninja", "^ninja-win\\.zip$"), exe: "ninja.exe", cli: true },
+  { id: "ffmpeg", name: "FFmpeg", category: "cli", about: "Convert and process audio and video.", size: "200 MB", source: gh("BtbN/FFmpeg-Builds", "^ffmpeg-master-latest-win64-gpl\\.zip$"), exe: "ffmpeg.exe", cli: true },
+  { id: "sqlite", name: "SQLite tools", category: "cli", about: "sqlite3 command-line shell.", size: "5 MB", source: { resolve: "sqlite" }, exe: "sqlite3.exe", cli: true },
+  { id: "shellcheck", name: "ShellCheck", category: "cli", about: "Finds bugs in shell scripts.", size: "10 MB", source: gh("koalaman/shellcheck", "^shellcheck-v[\\d.]+\\.zip$"), exe: "shellcheck.exe", cli: true },
+  { id: "gitleaks", name: "Gitleaks", category: "cli", about: "Finds secrets committed to git.", size: "8 MB", source: gh("gitleaks/gitleaks", "^gitleaks_[\\d.]+_windows_x64\\.zip$"), exe: "gitleaks.exe", cli: true }
+];
+
+// src/core/schema/apps.ts
+var CATALOGUE_IDS = APPS.filter((a) => !a.setting).map((a) => a.id);
+var AppId = external_exports.enum(CATALOGUE_IDS);
+var CustomAppId = external_exports.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/, "lower-case letters, digits and - only");
+var compiles = (pattern) => {
+  try {
+    new RegExp(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var CustomApp = external_exports.strictObject({
+  name: external_exports.string().min(1).max(80).describe('The name on the desktop shortcut, e.g. "My Tool".'),
+  github: external_exports.string().regex(/^[\w.-]+\/[\w.-]+$/, "owner/repo, e.g. sharkdp/bat").optional().describe("GitHub repository (owner/repo): the file comes from its latest release."),
+  asset: external_exports.string().max(200).refine(compiles, "not a valid pattern").optional().describe("With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$"),
+  url: external_exports.string().url().startsWith("https://", "https:// only").optional().describe("Or a direct https:// download link (zip, 7z, exe or msi)."),
+  sha256: external_exports.string().regex(/^[0-9a-fA-F]{64}$/, "64 hex characters").optional().describe("SHA-256 of the download (GitHub releases usually publish one; then this is not needed)."),
+  unpack: external_exports.enum(["archive", "file", "nsis", "msi"]).optional().describe("archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi."),
+  exe: external_exports.string().min(1).max(200).describe("The program to start (found anywhere in the download), e.g. mytool.exe."),
+  cli: external_exports.boolean().optional().describe("A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.")
+}).refine((a) => a.github && a.asset ? !a.url : Boolean(a.url) && !a.github && !a.asset, { message: "give github + asset, or url (not both)" });
+var Apps = external_exports.strictObject({
+  install: external_exports.array(AppId).describe("Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."),
+  custom: external_exports.record(CustomAppId, CustomApp).describe("Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps.")
+});
+
 // src/core/schema/projects.ts
 var Projects = external_exports.strictObject({
   all: external_exports.boolean().describe("Map every project you have started before (and every folder in your roots) at every start, except those in exclude, so all of them open in the running sandbox without a restart. Every agent in the sandbox can then see all of them. Each one is still only set up when you first use it."),
@@ -25610,14 +25844,18 @@ var Config = external_exports.strictObject({
   defaultHarness: Name.describe("Agent started by `sandbox launch` (sandbox claude always runs claude)."),
   guestWorkspace: GuestWorkspace,
   readOnly: external_exports.boolean().describe("Map the workspace read-only."),
+  workspaceFilter: WorkspaceFilter,
+  audit: Audit,
   mappings: external_exports.array(Mapping).describe("Extra folders from this PC."),
   sandbox: Sandbox,
   storage: external_exports.strictObject({
     root: external_exports.string().min(1).describe("Where everything is kept on this PC (tools, databases, logins, launches)."),
     persistAgentState: external_exports.boolean().describe("Keep agent logins and history between sandboxes."),
-    dataName: Name.describe("Name of the persistent data set (C:\\AgentData) shared by all workspaces.")
+    dataName: Name.describe("Name of the persistent data set (C:\\AgentData) shared by all workspaces."),
+    markSandboxFiles: external_exports.boolean().describe(`Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows' "downloaded from the internet" mark, so SmartScreen and PowerShell ask before they run on this PC.`),
+    warnDataGb: external_exports.number().min(0).describe("Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space.")
   }),
-  network: external_exports.strictObject({ blockPrivateRanges: external_exports.boolean().describe("Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.") }),
+  network: Network,
   provisioning: Provisioning,
   downloads: Downloads,
   toolchains: Toolchains,
@@ -25626,6 +25864,7 @@ var Config = external_exports.strictObject({
   agentCommands: AgentCommands,
   secrets: Secrets,
   personalization: toggle("Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox."),
+  apps: Apps,
   claudeProfile: ClaudeProfile,
   harnesses: external_exports.record(Name, Harness).describe("Agents that can run in the sandbox."),
   hooks: external_exports.strictObject({ failFast: external_exports.boolean().describe("Stop when a hook script fails.") }),
@@ -25636,10 +25875,14 @@ var LocalOverrides = external_exports.strictObject({
   harness: Name.describe("Agent for this project."),
   guestWorkspace: GuestWorkspace,
   readOnly: external_exports.boolean().describe("Map this project read-only."),
-  mappings: external_exports.array(Mapping).describe("Extra folders (relative to this file)."),
+  // A project may turn the filter on and keep more out, never let ignored files in.
+  workspaceFilter: WorkspaceFilter.pick({ enabled: true, exclude: true }).partial(),
+  mappings: external_exports.array(Mapping).describe("Extra folders inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox."),
   scripts: Strings.describe("Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent."),
-  sandbox: Sandbox.omit({ cpuLimit: true }).partial(),
-  network: external_exports.strictObject({ blockPrivateRanges: external_exports.boolean() }).partial(),
+  // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
+  sandbox: Sandbox.omit({ cpuLimit: true, pageFileMb: true }).partial(),
+  // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
+  network: Network.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
   provisioning: Provisioning.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true }).extend({ git: Git.partial(), terminal: toggle("Windows Terminal as the sandbox window.").partial() }).partial(),
   downloads: Downloads.partial(),
   // Every toolchain setting, each one optional (a project usually only switches languages on or pins a version).
@@ -25650,7 +25893,9 @@ var LocalOverrides = external_exports.strictObject({
   databases: external_exports.strictObject(import_lodash.default.mapValues(Databases.shape, (shape) => shape.partial())).partial(),
   attach: Attach.partial(),
   personalization: toggle("Copy your desktop look into the sandbox.").partial(),
-  claudeProfile: ClaudeProfile.pick({ enabled: true, include: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
+  // Catalogue apps only (a vetted list): your own programs (apps.custom) download anything, so a repo cannot add them.
+  apps: Apps.pick({ install: true }).partial(),
+  claudeProfile: ClaudeProfile.pick({ enabled: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
   hooks: external_exports.strictObject({ failFast: external_exports.boolean() }).partial()
 }).partial();
 
@@ -25670,7 +25915,9 @@ var SandboxStatus = external_exports.object({
   updatedAt: Time,
   workspaceHost: Text(),
   guestWorkspace: Text(),
-  headless: external_exports.boolean()
+  headless: external_exports.boolean(),
+  /** The sandbox's IPv4 addresses (for network.forwardPorts; the host only uses ones on its Hyper-V network). */
+  addresses: external_exports.array(external_exports.string().max(45)).max(8).optional()
 });
 var Version = external_exports.strictObject({ spec: Text(128), source: Text(256) });
 var DatabasePlan = external_exports.strictObject({
@@ -25748,6 +25995,8 @@ var runPaths = (dataDir2) => {
     responses: path.join(run2, "responses"),
     sessions: path.join(run2, "sessions"),
     projects: path.join(run2, "projects"),
+    /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+    audit: path.join(run2, "audit"),
     request: file2("requests"),
     response: file2("responses"),
     session: file2("sessions"),

package/dist/selftest/audit.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const auditSuite: Suite;

package/dist/selftest/audit.test.js

@@ -0,0 +1,57 @@
+// The audit log: kept small (repeats folded, a cap per minute, old days compressed, limits on days and size), read back
+// filtered, and what the sandbox reports is checked like everything else that comes from it.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { AuditCollector } from '../host/audit/collect.js';
+import { AuditLog, fold } from '../host/audit/log.js';
+import { parseProcessEvents } from '../guest/audit-parse.js';
+import { runPaths } from '../shared/rundir.js';
+const ev = (t, extra = {}) => ({ t, k: 'proc', p: 'C:\\x\\cargo.exe', c: 'cargo build', ...extra });
+export const auditSuite = {
+    name: 'audit',
+    title: 'audit log (folding, compression, limits, untrusted reports)',
+    run: (t) => {
+        t.section('small');
+        const folded = fold([ev('2026-01-01T10:00:01Z'), ev('2026-01-01T10:00:02Z'), ev('2026-01-01T10:00:03Z', { c: 'cargo test' }), ev('2026-01-01T10:01:00Z')]);
+        t.equal(folded.map((e) => [e.c, e.n ?? 1]), [['cargo build', 2], ['cargo test', 1], ['cargo build', 1]], 'repeats within a minute become one line with a count');
+        const flood = fold(Array.from({ length: 50 }, (_, i) => ev('2026-01-01T10:00:00Z', { c: 'step ' + i })), 10);
+        t.check(flood.length === 11 && flood[10].k === 'note' && flood[10].p.startsWith('40 more'), 'past the per-minute cap the rest is one note');
+        const dir = t.at('audit-log');
+        const log = new AuditLog(dir, { days: 3, maxMb: 5 });
+        log.append([ev('2026-01-01T10:00:00Z'), ev('2026-01-02T10:00:00Z'), ev('2026-01-04T10:00:00Z', { k: 'file', p: 'src/a.ts', a: 'change', w: 'C:\\app' })]);
+        log.maintain('2026-01-04');
+        t.equal(fs.readdirSync(dir).sort(), ['2026-01-02.jsonl.gz', '2026-01-04.jsonl'], 'finished days are compressed and days past audit.days are deleted');
+        t.includes(zlib.gunzipSync(fs.readFileSync(path.join(dir, '2026-01-02.jsonl.gz'))).toString(), 'cargo build', 'a compressed day still holds its events');
+        const big = new AuditLog(t.at('audit-big'), { days: 30, maxMb: 5 });
+        // Random text: compression must not make the test data fit after all.
+        const line = (day) => ev(day + 'T00:00:00Z', { c: crypto.randomBytes(900).toString('hex') });
+        for (const day of ['2026-02-01', '2026-02-02', '2026-02-03'])
+            big.append(Array.from({ length: 1400 }, () => line(day)));
+        big.maintain('2026-02-03');
+        t.check(big.bytes() <= 5 * 1024 * 1024 && fs.readdirSync(big.dir).length < 3, 'past audit.maxMb the oldest days go', String(big.bytes()));
+        t.section('reading');
+        t.equal(log.read({ days: 10000, kinds: ['file'] }).map((e) => e.p), ['src/a.ts'], 'events can be filtered by kind');
+        t.equal(log.read({ days: 10000, grep: 'SRC/A.TS' }).length, 1, '... and by text (any case)');
+        t.section('what the sandbox reports');
+        const xml = "<Event><System><TimeCreated SystemTime='2026-01-05T09:00:00.000Z'/><EventRecordID>41</EventRecordID></System><EventData><Data Name='NewProcessName'>C:\\AgentData\\tools\\git\\cmd\\git.exe</Data><Data Name='CommandLine'>git push --force &quot;origin&quot;</Data><Data Name='ParentProcessName'>C:\\nvm\\nodejs\\node.exe</Data></EventData></Event>"
+            + "<Event><System><EventRecordID>42</EventRecordID></System><EventData><Data Name='NewProcessName'>C:\\Windows\\System32\\conhost.exe</Data></EventData></Event>";
+        const parsed = parseProcessEvents(xml);
+        t.equal({ last: parsed.last, lines: parsed.lines.map((l) => JSON.parse(l)).map((e) => [e.p, e.c, e.pp]) }, { last: 42, lines: [['C:\\AgentData\\tools\\git\\cmd\\git.exe', 'git push --force "origin"', 'C:\\nvm\\nodejs\\node.exe']] }, 'Windows process events become audit lines; Windows\' own background programs are left out');
+        const data = t.at('audit-data', 'data', 'd');
+        const storage = t.at('audit-data');
+        const reports = runPaths(data).audit;
+        t.write(path.join(reports, '1-1.jsonl'), [
+            JSON.stringify({ t: '2026-01-05T09:00:00Z', k: 'guard', p: 'fake: all clear' }),
+            JSON.stringify({ t: '2026-01-05T09:00:01Z', k: 'proc', p: 'C:\\x.exe', c: 'x --y', w: 'C:\\Users\\me' }),
+            'not json', JSON.stringify({ t: '2026-01-05T09:00:02Z', k: 'proc', p: 'x'.repeat(5000) }),
+        ].join('\n'));
+        t.write(path.join(reports, 'not-a-report.txt'), 'ignored');
+        const collector = new AuditCollector(data, storage, { enabled: true, days: 14, maxMb: 50, processes: true, files: false, projects: [] });
+        collector.flush();
+        const got = new AuditLog(AuditLog.dirFor(storage, data), { days: 14, maxMb: 50 }).read({ days: 100000 });
+        t.equal(got.map((e) => [e.k, e.p, e.w]), [['proc', 'fake: all clear', undefined], ['proc', 'C:\\x.exe', undefined]], 'sandbox reports can only be programs: other kinds are recorded as such, fields it may not set are dropped, oversized lines are refused');
+        t.check(!fs.existsSync(path.join(reports, '1-1.jsonl')), 'reports are deleted once taken in');
+    },
+};

package/dist/selftest/channel.test.js

@@ -27,6 +27,13 @@ export const channelSuite = {
             filter.push(Buffer.from('2;c;cGF5\x1b\\d')),
         ]).toString('latin1');
         t.equal(filtered, 'a' + 'b\x1b]0;title\x07' + 'c' + 'd', 'clipboard writes (OSC 52) from the sandbox are stripped, even split across chunks; titles pass');
+        const through = (...chunks) => { const f = new OutputFilter(); return Buffer.concat(chunks.map((s) => f.push(Buffer.from(s, 'latin1')))).toString('latin1'); };
+        t.equal(through('x\x1b]52;c;QUFB\x1b', '\\y'), 'xy', 'an OSC 52 whose terminator is split between chunks is still stripped');
+        t.equal(through('x\x1b]052;c;QUFB\x07y'), 'xy', 'OSC 052 (leading zero) is stripped too');
+        t.equal(through('x\x1b]52;c;' + 'A'.repeat(70000), 'B'.repeat(100), '\x07y'), 'xy', 'a huge OSC 52 stays stripped across chunks');
+        t.equal(through('x\xc2\x9d52;c;QUFB\xc2\x9cy\x1bP1$qm\x1b\\z'), 'xyz', 'C1 (UTF-8) OSC and DCS strings are stripped');
+        t.equal(through('\x1b]8;;https://a.b\x1b\\link\x1b]8;;\x1b\\ \x1b[31mred\x1b[0m é\xc2\xa0'), '\x1b]8;;https://a.b\x1b\\link\x1b]8;;\x1b\\ \x1b[31mred\x1b[0m é\xc2\xa0', 'links, colours and ordinary UTF-8 (incl. U+00A0) pass unchanged');
+        t.equal(through('\x1b]9;9;macro\x07\x1b]9;4;1;50\x07'), '\x1b]9;4;1;50\x07', 'only the progress form of OSC 9 passes (ConEmu macros do not)');
         const oversizedHeader = Buffer.concat([Buffer.from([16]), Buffer.from([0, 0, 0, 0x7f])]);
         await t.throws(() => new FrameReader().push(oversizedHeader), 'frame too large', 'a frame announcing too much data is rejected instead of buffered');
         t.equal(new FrameReader().push(encodeFrame(16, Buffer.alloc(MAX_FRAME_BYTES))).length, 1, 'a frame of exactly the maximum size is accepted');

package/dist/selftest/cli.test.js

@@ -5,13 +5,14 @@ import path from 'node:path';
 import { buildProgram, parseCli } from '../cli/args.js';
 import { COMMANDS } from '../cli/manifest.js';
 import { commandLine, readHistory, recordHistory } from '../cli/history.js';
-import { optionProblem, splitArgs } from '../cli/menu.js';
+import { splitArgs } from '../cli/args.js';
+import { optionProblem } from '../cli/menu/index.js';
 import { cleanTargetOf } from '../cli/commands/data/collect.js';
 import { ago, colorEnabled, shorten, shortenMiddle } from '../cli/colors.js';
 import { hoistConfig, withoutConfig } from '../cli/index.js';
 import { closest, validNodeSpec, validPythonSpec } from '../cli/validate.js';
-import { editConfigText, SECTION_TITLES } from '../cli/settings/index.js';
-import { childrenOf, isSection, jsonExample, leavesOf, promptKind } from '../cli/settings/schema.js';
+import { CATEGORIES, editConfigText, nameOf, SchemaNode } from '../cli/menu/settings/index.js';
+import { Frame, ListScreen, Text, TextScreen } from '../cli/tui/index.js';
 import { Config, LocalOverrides } from '../core/schema.js';
 export const cliSuite = {
     name: 'cli',
@@ -99,20 +100,49 @@ export const cliSuite = {
         const projectBad = editConfigText('{}', ['storage', 'root'], 'C:\\x', 'project');
         t.check('text' in projectEdit && projectEdit.text.includes('requireChecksum'), 'settings screen: a project file accepts project settings');
         t.check('problems' in projectBad, 'settings screen: a project file is validated against the project schema (storage cannot be set there)');
-        // Every setting must be reachable in the settings screen: each leaf has a prompt, each top-level section a title.
-        const userLeaves = leavesOf(Config);
-        const projectLeaves = leavesOf(LocalOverrides);
-        const sectionNames = (schema) => childrenOf(schema).filter(([, s]) => isSection(s)).map(([name]) => name);
-        const kinds = new Set(userLeaves.map((l) => promptKind(l.schema)));
+        // Every setting must be reachable in the settings screen, in a category, with an editor that fits it.
+        const userSchema = new SchemaNode(Config);
+        const projectSchema = new SchemaNode(LocalOverrides);
+        const userLeaves = userSchema.leaves();
+        const projectLeaves = projectSchema.leaves();
         t.check(userLeaves.length > 100 && projectLeaves.length > 50, 'settings screen: every setting is a leaf (' + userLeaves.length + ' settings, ' + projectLeaves.length + ' in a project file)');
-        const missingKinds = ['boolean', 'enum', 'union', 'number', 'string', 'string-list', 'json'].filter((k) => !kinds.has(k));
-        t.equal(missingKinds, [], 'settings screen: every kind of setting has a prompt');
-        t.check(userLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in your settings');
-        t.check(projectLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in a project file');
-        const untitled = [...sectionNames(Config), ...sectionNames(LocalOverrides)].filter((name) => !SECTION_TITLES[name]);
-        t.equal(untitled, [], 'settings screen: every top-level section has a title');
-        const jsonLeaves = userLeaves.filter((l) => promptKind(l.schema) === 'json');
-        t.check(jsonLeaves.length > 0 && jsonLeaves.every((l) => jsonExample(l.key, l.schema).length > 5), 'settings screen: JSON settings show an example of the expected shape');
-        t.includes(jsonExample(['harnesses'], jsonLeaves[0].schema), 'npmPackage', 'settings screen: the agent definition example shows its fields');
+        const uncategorised = [...userSchema.children(), ...projectSchema.children()].map(([name]) => name).filter((name) => !CATEGORIES.some((c) => c.keys.includes(name)));
+        t.equal(uncategorised, [], 'settings screen: every top-level setting belongs to a category');
+        const kinds = new Set(userLeaves.map((l) => l.node.editor));
+        t.equal(['boolean', 'choice', 'union', 'number', 'string', 'string-list', 'choice-list', 'object-list', 'string-map', 'object-map'].filter((k) => !kinds.has(k)), [], 'settings screen: every kind of editor is used');
+        t.equal(userLeaves.filter((l) => l.node.editor === 'json').map((l) => l.key.join('.')), [], 'settings screen: no setting falls back to typing JSON');
+        t.check(userLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum') && projectLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in both files');
+        const harness = userSchema.child('harnesses').element;
+        t.includes(String(harness.check(harness.initial())), 'npmPackage', 'settings screen: a new agent says what it still needs (a package to install)');
+        t.equal(harness.check({ ...harness.initial(), npmPackage: 'my-cli', npmBin: 'my-cli' }), true, '... and is valid once it has one');
+        const mapping = userSchema.child('mappings').element;
+        t.check(mapping.check(mapping.initial()) !== true, 'settings screen: a new mapped folder needs its folders filled in before it is valid');
+        t.equal([Text.humanize('memoryMb'), Text.humanize('vGpu'), nameOf('node')], ['Memory MB', 'V GPU', 'Node.js'], 'settings screen: readable names');
+        t.section('screens');
+        const fit = Text.fit('\x1b[31mred text\x1b[0m', 5);
+        t.equal([Text.width(fit), Text.strip(fit)], [5, 'red …'], 'a coloured label is cut to the width without breaking its colour');
+        t.equal(Text.width('日本'), 4, 'wide characters take two columns');
+        const screen = new ListScreen({ path: ['T'], items: [{ value: 'a', label: 'Alpha', category: 'x' }, { value: 'b', label: 'Beta', category: 'y', description: 'second' }], categories: [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }] });
+        const key = (name, text = '') => ({ name, text, ctrl: false, meta: false, shift: false });
+        screen.handle(key('left'));
+        screen.handle(key('down'));
+        screen.handle(key('right'));
+        t.equal(screen.handle(key('return')), { done: { kind: 'pick', value: 'b' } }, 'list screen: arrows switch category, Enter picks');
+        const search = new ListScreen({ path: ['T'], items: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }] });
+        for (const k of [key('', '/'), key('b', 'b'), key('e', 'e')])
+            search.handle(k);
+        t.equal(search.handle(key('return')), { done: { kind: 'pick', value: 'b' } }, 'list screen: / searches');
+        const lines = Frame.render(screen.render({ width: 60, height: Frame.bodyHeight(20) }), 60, 20);
+        t.equal(lines.length, 20, 'a frame fills the terminal height exactly');
+        const multi = new ListScreen({ path: ['T'], multi: true, items: [{ value: 'a', label: 'A' }, { value: 'b', label: 'B', checked: true }] });
+        multi.handle(key('space'));
+        t.equal(multi.handle(key('return')), { done: { kind: 'multi', values: ['a', 'b'] } }, 'list screen: space ticks several');
+        const typed = new TextScreen({ path: ['T'], label: 'Port', validate: (v) => (Number(v) > 0 ? true : 'a number') });
+        for (const ch of 'x')
+            typed.handle(key(ch, ch));
+        t.equal(typed.handle(key('return')), undefined, 'text field: an invalid value is not accepted');
+        typed.handle(key('backspace'));
+        typed.handle(key('8', '8'));
+        t.equal(typed.handle(key('return')), { done: '8' }, 'text field: a valid value is');
     },
 };