loom-agent 1.2.36 → 1.3.2

package/src/core/agents.js

@@ -60,9 +60,9 @@ function escapeRegExp(s) {
 const BUILTIN_AGENTS = {
   build: {
     id: 'build', name: 'Build', mode: 'primary',
-    description: 'Full development work with all tools enabled.',
+    description: 'Main orchestrator agent: full development work with all tools, drives tasks to completion.',
     tools: ['*'],
-    prompt: null,
+    prompt: 'You are the MAIN ORCHESTRATOR agent. For non-trivial, multi-step work: (1) capture the plan as a todowrite list up front, (2) keep working until every item is completed or explicitly cancelled — never stop mid-task with a summary while todos remain, (3) delegate independent/parallelizable packages via the task tool (research for deep investigation, coder for isolated implementation, reviewer for review, tester for tests, web for browser work, explore for fast code search), (4) verify your work (run tests/typecheck/lint the project actually uses) before declaring done, (5) finish with a terse summary of what changed.',
   },
   plan: {
     id: 'plan', name: 'Plan', mode: 'primary',
@@ -95,6 +95,36 @@ const BUILTIN_AGENTS = {
     tools: ['read', 'glob', 'grep', 'webfetch'],
     prompt: null,
   },
+  research: {
+    id: 'research', name: 'Research', mode: 'subagent',
+    description: 'Deep multi-source research: combines web search/fetch with local code and docs, cross-checks facts, and returns a structured findings report with sources and confidence levels.',
+    tools: ['read', 'glob', 'grep', 'webfetch', 'websearch', 'todowrite'],
+    prompt: 'You are the Research agent. Investigate the topic from multiple independent sources (websearch/webfetch AND local files when relevant). Never state a fact you have not verified in a source. Track your investigation with todowrite when it has many steps. Return a structured report: "## Findings" (numbered facts, each with its source: URL or file:line), "## Gaps" (what you could not verify), "## Recommendation".',
+  },
+  coder: {
+    id: 'coder', name: 'Coder', mode: 'subagent',
+    description: 'Implementation specialist: writes and edits code, runs commands, verifies results. Use for well-scoped feature/bugfix packages that can run independently.',
+    tools: ['*', '!task'],
+    prompt: 'You are the Coder agent. Implement exactly what was delegated — no scope creep. Follow the existing code conventions of the files you touch (imports, naming, JSDoc/typing style). Verify your work (run the relevant tests/typecheck) before reporting. Final report: files changed with line deltas, commands run and their outcomes, and anything left undone.',
+  },
+  reviewer: {
+    id: 'reviewer', name: 'Reviewer', mode: 'subagent',
+    description: 'Code review specialist: reads diffs and files, runs read-only git/inspection commands, returns severity-ranked findings with file:line references.',
+    tools: ['read', 'glob', 'grep', 'bash', 'webfetch'],
+    prompt: 'You are a strict code reviewer. Hunt for: correctness bugs, security issues, data loss risks, broken edge cases, missing tests, and convention violations. Inspect the actual diff/files (git diff, git log, read) — never review code you have not read. Findings first, ranked by severity (critical/major/minor), each with file:line and a concrete suggested fix. If there are no issues, say so explicitly and note what you checked.',
+  },
+  tester: {
+    id: 'tester', name: 'Tester', mode: 'subagent',
+    description: 'Test engineer: writes tests that reproduce the issue, runs them, iterates until green. Use for test creation, bug reproduction, and verification work.',
+    tools: ['read', 'write', 'edit', 'glob', 'grep', 'bash', 'todowrite'],
+    prompt: 'You are the Tester agent. First reproduce the behavior (write a failing test when possible), run it, then iterate until the outcome is deterministic and understood. Use the project\'s real test runner (inspect package.json/bunfig — never invent commands). Report: exact commands run, pass/fail counts, and what the tests prove.',
+  },
+  web: {
+    id: 'web', name: 'Web', mode: 'subagent',
+    description: 'Browser specialist: drives a real headless browser (navigate, click, fill, read DOM, screenshot) plus webfetch/websearch. Use for live-site inspection, rendered-page research, and end-to-end UI verification.',
+    tools: ['read', 'glob', 'grep', 'webfetch', 'websearch', 'browser', 'todowrite'],
+    prompt: 'You are the Web agent with a real headless browser (the browser tool). Prefer the browser over webfetch whenever the page needs JavaScript rendering, clicking, or form interaction. Verify claims by reading the ACTUAL DOM (browser text/eval/links) — never guess page content. Use screenshots to confirm visual state when relevant. Stay on http/https pages; do not use the browser to access local files.',
+  },
 };
 
 function readOnlyTools() {

package/src/core/cli.js

@@ -9,6 +9,10 @@ const { ProviderRouter, PROVIDERS } = require('../providers');
 const { saveSession, loadSession } = require('./session-store');
 const { defaultMcpInstall } = require('./plugin-cmd');
 
+// Single source of truth for every version string the CLI prints (banner,
+// --version). package.json is the only place to bump.
+const VERSION = require('../../package.json').version;
+
 const LOOM_BASE = `
  ██╗      ██████╗  ██████╗ ███╗   ███╗      ██████╗ ██████╗ ██████╗ ███████╗
  ██║     ██╔═══██╗██╔═══██╗████╗ ████║     ██╔════╝██╔═══██╗██╔══██╗██╔════╝
@@ -38,7 +42,7 @@ class LoomCLI {
       terminal: true,
     });
     console.log(LOOM_BASE);
-    console.log(`\n  Loom Code v1.2.28 — AI Coding Agent for the terminal`);
+    console.log(`\n  Loom Code v${VERSION} — AI Coding Agent for the terminal`);
     console.log(`  Press Ctrl+C or ESC to interrupt | /help for commands\n`);
 
     process.stdin.on('keypress', (str, key) => {
@@ -391,7 +395,13 @@ class LoomCLI {
    */
   async openGraphBrowser(graph) {
     const http = require('http');
-    const template = fs.readFileSync(path.join(__dirname, '..', 'web', 'graph-view.html'), 'utf8');
+    let template;
+    try {
+      template = fs.readFileSync(path.join(__dirname, '..', 'web', 'graph-view.html'), 'utf8');
+    } catch {
+      console.log('Browser graph view is not available (the web UI has been removed).');
+      return;
+    }
     const html = template.replace('window.__GRAPH__ || { nodes: [], edges: [] }', JSON.stringify(graph).replace(/<\/script/gi, '<\\/script'));
     const server = http.createServer((req, res) => {
       const p = req.url || '/';
@@ -509,7 +519,6 @@ async function main() {
   const cli = new LoomCLI();
 
   const args = process.argv.slice(2);
-  const VERSION = require('../../package.json').version;
 
   const printIdx = args.indexOf('-p');
   const printLongIdx = args.indexOf('--print');
@@ -530,8 +539,7 @@ if (args.includes('--help') || args.includes('-h')) {
     console.log('  loom --basic            Use basic line-mode REPL (no TUI)');
     console.log('  loom --auto             Auto-approve permission prompts');
     console.log('  loom acp                ACP server (JSON-RPC over stdio, for editor plugins)');
-    console.log('  loom web                Browser interface (HTTP server, opens the browser)');
-    console.log('  loom attach <url>       Attach the terminal to a running `loom web` server');
+    console.log('  loom add mcp <spec>     Add an MCP server (same syntax as /mcp add)');
     console.log('  loom -s <session-id>    Resume a saved session');
     console.log('  loom --version           Show version');
     console.log('  loom --help              Show this help');
@@ -551,6 +559,23 @@ if (args.includes('--help') || args.includes('-h')) {
     return;
   }
 
+  // loom add mcp <name> [--] <command> [args...] — register an MCP server from
+  // the shell with the same one-liner syntax as /mcp add (quote paths with
+  // spaces; -e KEY=V for env). Exits 0 on success.
+  if (args[0] === 'add' && args[1] === 'mcp') {
+    const spec = args.slice(2);
+    if (!spec.length) {
+      console.log('Usage: loom add mcp [-e KEY=V] <name> [--] <command> [args...]');
+      console.log('Example: loom add mcp fetch -- npx -y mcp-server-fetch');
+      process.exit(1);
+    }
+    const { mcpAddLineCmd } = require('./plugin-cmd');
+    const msg = mcpAddLineCmd(spec.join(' '));
+    const ok = typeof msg === 'string' && msg.startsWith('Added');
+    console.log(ok ? msg : 'Error: ' + msg);
+    process.exit(ok ? 0 : 1);
+  }
+
   if (sessionId && sIndex !== -1) {
     const data = loadSession(sessionId);
     if (data && data.messages && data.messages.length) {

package/src/core/permissions.js

@@ -34,7 +34,7 @@ const DANGER_PATTERNS = [
 // user config).
 const PERMISSION_KEYS = [
   'read', 'edit', 'glob', 'grep', 'bash', 'task', 'skill', 'lsp', 'question',
-  'webfetch', 'websearch',
+  'webfetch', 'websearch', 'browser',
   'external_directory', 'doom_loop',
 ];
 
@@ -53,6 +53,15 @@ const DEFAULT_PERMISSIONS = {
     '*.env.*': 'deny',
     '*.env.example': 'allow',
   },
+  // Browser: passive reads of live pages are as safe as webfetch (allow);
+  // INTERACTIVE actions (click/fill/press) can submit forms and change remote
+  // state, so they prompt by default. Patterns match "action arg".
+  browser: {
+    '*': 'allow',
+    'click*': 'ask',
+    'fill*': 'ask',
+    'press*': 'ask',
+  },
 };
 
 // Tools that write files map onto the "edit" permission (OpenCode semantics:
@@ -71,6 +80,7 @@ const TOOL_TO_PERMISSION = {
   ask: 'question',
   webfetch: 'webfetch',
   websearch: 'websearch',
+  browser: 'browser',
   todowrite: null,   // never prompts
   mcp: null,         // wired by the session (only the "add" action prompts)
 };
@@ -301,6 +311,7 @@ class PermissionManager {
       case 'ask': return String(inp.question ?? inp.text ?? '');
       case 'webfetch': return String(inp.url ?? '');
       case 'websearch': return String(inp.query ?? '');
+      case 'browser': return String(inp.action ?? '') + ' ' + String(inp.url ?? inp.selector ?? inp.key ?? inp.path ?? '');
       default: return String(inp.command ?? inp.filePath ?? inp.path ?? inp.pattern ?? inp.url ?? '');
     }
   }

package/src/core/plugin-cmd.js

@@ -123,6 +123,7 @@ function mcpHelp() {
     '',
     'Example (claude-compatible): /mcp add stm32 -- "C:\\stm32-mcp\\.venv\\Scripts\\python.exe" -m stm32_mcp.server',
     'Example with env: /mcp add -e BRAVE_API_KEY=x brave-search -- npx -y @modelcontextprotocol/server-brave-search',
+    'From the shell (same syntax): loom add mcp [-e KEY=V] <name> [--] <command> [args...]',
     'The "--" separator is optional; quote any path with spaces. Env keys are usable as $KEY in args.',
     'In the /mcp and /connectors browsers, press A to add with the same one-liner syntax.',
   ].join('\n');

package/src/core/sandbox.js

@@ -0,0 +1,400 @@
+// Docker sandbox — a lightweight, isolated OS for the agent's shell commands.
+//
+// Flow (guided in the TUI via the /sandbox modal):
+//   1. Step 1 checks Docker. If missing, the modal shows the download link
+//      (installLink) + "open download page", sets config.sandbox.pending,
+//      and the user can later say "docker is ready" or run /sandbox again.
+//   2. Step 2 picks an OS from OS_CATALOG (alpine/debian/ubuntu — all
+//      node images, ~250–900 MB). Step 3 pulls it, creates the single
+//      GLOBAL loom-sandbox container with the PROJECT mounted at /workspace,
+//      installs essentials (+ headless chromium when offered, best-effort)
+//      and keeps the container idle-running.
+//   3. With sandbox.enabled, the bash tool routes every command through
+//      `docker exec` into that container instead of the host shell. File
+//      tools stay on the host — the mount is the same directory, so reads
+//      and writes are shared while side effects of commands stay contained.
+//      ensureProjectMount() re-creates the container when the active project
+//      changes, so every session/agent shares one sandbox.
+//
+// Security posture: no --privileged, no host network, only the project dir
+// is mounted (rw), container runs as the image's default non-root user when
+// possible. It is a blast-radius reducer, not a hostile-VM boundary.
+const { spawn, execFileSync } = require('child_process');
+const path = require('path');
+const { loadConfig, saveConfig } = require('../config/settings');
+
+const CONTAINER = 'loom-sandbox';
+const DEFAULT_IMAGE = 'node:20-alpine';
+// Essentials installed on first setup: a POSIX shell with the tools the
+// agent actually reaches for. node is already in the image. Chromium is a
+// separate best-effort install (see setupSandbox).
+const BASE_PACKAGES = 'git bash curl ripgrep coreutils';
+
+/**
+ * OS catalog offered by the /sandbox modal. All are lightweight, rootless-
+ * friendly Linux userlands; the agent gets a full shell + headless browser
+ * inside whichever it picks. `pkg` selects the package manager path.
+ * @type {Array<{ id: string, label: string, image: string, sizeNote: string, pkg: 'apk'|'apt', browser: boolean }>}
+ */
+const OS_CATALOG = [
+  { id: 'alpine', label: 'Alpine Linux', image: 'node:20-alpine', sizeNote: 'smallest & fastest (~250 MB)', pkg: 'apk', browser: true },
+  { id: 'debian', label: 'Debian Slim', image: 'node:20-slim', sizeNote: 'broad binary compatibility (~600 MB)', pkg: 'apt', browser: true },
+  { id: 'ubuntu', label: 'Ubuntu', image: 'node:20', sizeNote: 'full userland (~900 MB)', pkg: 'apt', browser: false },
+];
+
+/** @typedef {'not_installed'|'no_daemon'|'ready'} DockerState */
+
+/**
+ * Detect the Docker CLI + daemon. Injectable runner for tests.
+ * @param {(cmd: string, args: string[]) => string} [runner]
+ * @returns {{ state: DockerState, version: string }}
+ */
+function detectDocker(runner) {
+  const run = runner || ((cmd, args) => execFileSync(cmd, args, {
+    encoding: 'utf8', windowsHide: true, timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim());
+  let version = '';
+  try {
+    version = run('docker', ['version', '--format', '{{.Server.Version}}']);
+  } catch {
+    // CLI missing entirely vs daemon down: `docker version` errors on both,
+    // but `docker --version` still succeeds when only the daemon is down.
+    try {
+      run('docker', ['--version']);
+      return { state: 'no_daemon', version: '' };
+    } catch {
+      return { state: 'not_installed', version: '' };
+    }
+  }
+  if (!version) return { state: 'no_daemon', version: '' };
+  return { state: 'ready', version };
+}
+
+/**
+ * Platform-appropriate Docker install guide shown before the user leaves to
+ * install. Mentions the restart when the installer requires one, and the
+ * exact phrase that resumes setup after they come back.
+ * @returns {string}
+ */
+function installGuide() {
+  const plat = process.platform;
+  const link = installLink();
+  const steps = [];
+  if (plat === 'win32') {
+    steps.push('1. Download Docker Desktop for Windows: ' + link);
+    steps.push('2. Run the installer. If it asks to enable WSL 2 / restart Windows — accept and RESTART your computer when it finishes.');
+    steps.push('3. Start Docker Desktop and wait for it to say "running" in the tray (first start can take a minute).');
+  } else if (plat === 'darwin') {
+    steps.push('1. Download Docker Desktop for Mac: ' + link + ' (Apple chip or Intel — pick yours).');
+    steps.push('2. Drag it to Applications and open it. Accept the terms; if macOS asks for a restart of privileges, let it.');
+    steps.push('3. Wait for the whale icon to settle — Docker is ready when the dashboard shows "running".');
+  } else {
+    steps.push('1. Install Docker Engine: ' + link + ' (Ubuntu: `curl -fsSL https://get.docker.com | sh` then `sudo usermod -aG docker $USER` and log out/in).');
+    steps.push('2. Start it: `sudo systemctl enable --now docker`.');
+  }
+  steps.push('4. Come back to THIS session and say: docker is ready');
+  steps.push('   (or run /sandbox setup). Loom will build the sandbox automatically.');
+  return [
+    'Docker is not set up yet — install it once and the sandbox becomes permanent.',
+    '',
+    ...steps,
+    '',
+    'Your session is kept: nothing is lost while you install. Say "docker is ready" when done.',
+  ].join('\n');
+}
+
+/**
+ * Download page for the current platform (shown in the /sandbox modal).
+ * @returns {string}
+ */
+function installLink() {
+  if (process.platform === 'win32') return 'https://docs.docker.com/desktop/setup/install/windows-install/';
+  if (process.platform === 'darwin') return 'https://docs.docker.com/desktop/setup/install/mac-install/';
+  return 'https://docs.docker.com/engine/install/';
+}
+
+/**
+ * Try to open the Docker download page in the user's default browser.
+ * Best-effort — the URL is always printed as a fallback.
+ * @returns {boolean} true if a browser spawn was attempted
+ */
+function openInstallPage() {
+  const url = installLink();
+  const { spawn } = require('child_process');
+  try {
+    if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { windowsHide: true, detached: true }).unref();
+    else if (process.platform === 'darwin') spawn('open', [url], { detached: true }).unref();
+    else spawn('xdg-open', [url], { detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Current sandbox lifecycle state for display + gating.
+ * @returns {{ docker: DockerState, dockerVersion: string, enabled: boolean, pending: boolean, container: 'running'|'stopped'|'absent', image: string, osId: string, projectRoot: string }}
+ */
+function sandboxStatus() {
+  const cfg = loadConfig();
+  const sandboxCfg = cfg.sandbox || {};
+  const { state, version } = detectDocker();
+  let container = /** @type {'running'|'stopped'|'absent'} */ ('absent');
+  if (state === 'ready') {
+    try {
+      const out = execFileSync('docker', ['inspect', '-f', '{{.State.Running}}', CONTAINER],
+        { encoding: 'utf8', windowsHide: true, timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+      container = out === 'true' ? 'running' : 'stopped';
+    } catch {
+      container = 'absent';
+    }
+  }
+  return {
+    docker: state,
+    dockerVersion: version,
+    enabled: !!sandboxCfg.enabled && container === 'running',
+    pending: !!sandboxCfg.pending,
+    container,
+    image: sandboxCfg.image || DEFAULT_IMAGE,
+    osId: sandboxCfg.osId || 'alpine',
+    projectRoot: sandboxCfg.projectRoot || '',
+  };
+}
+
+/**
+ * Map a host working directory to its path inside the container. The project
+ * root is mounted at /workspace; subdirectories map underneath it. Anything
+ * OUTSIDE the project falls back to /workspace (the container has no other
+ * mounts by design).
+ * @param {string} [hostDir]
+ * @param {string} [projectRoot]
+ * @returns {string}
+ */
+function toSandboxPath(hostDir, projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const dir = path.resolve(hostDir || root);
+  const rel = path.relative(root, dir);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return '/workspace';
+  return '/workspace/' + rel.split(path.sep).join('/');
+}
+
+/**
+ * Run a shell command inside the sandbox container. Streams output via
+ * onChunk('out'|'err') while running; resolves with { output, code } or
+ * { error }.
+ * @param {string} command
+ * @param {{ workdir?: string, projectRoot?: string, timeoutMs?: number, onChunk?: (text: string, stream: 'out'|'err') => void }} [opts]
+ * @returns {Promise<{ output: string, code: number }|{ error: string }>}
+ */
+function runInSandbox(command, opts) {
+  const o = opts || {};
+  // Shared container follows the active project (no-op when unchanged).
+  const remount = ensureProjectMount(o.projectRoot);
+  if (!remount.ok && remount.error !== 'sandbox disabled') {
+    return Promise.resolve({ error: 'sandbox re-mount failed: ' + remount.error });
+  }
+  const wd = toSandboxPath(o.workdir, o.projectRoot);
+  const timeoutMs = o.timeoutMs || 120000;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      // sh -lc keeps pipes/redirections working; -i is not needed because
+      // every exec is a fresh non-interactive shell.
+      child = spawn('docker', ['exec', '-w', wd, CONTAINER, 'sh', '-lc', String(command || '')],
+        { windowsHide: true });
+    } catch (e) {
+      resolve({ error: 'sandbox exec failed: ' + (e && e.message) });
+      return;
+    }
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch {}
+    }, timeoutMs);
+    let output = '';
+    const MAX_OUT = 10 * 1024 * 1024;
+    let truncated = false;
+    const push = (/** @type {Buffer} */ d, /** @type {'out'|'err'} */ stream) => {
+      const t = d.toString();
+      if (!truncated) {
+        if (output.length + t.length > MAX_OUT) { output = output.slice(0, MAX_OUT); truncated = true; }
+        else output += t;
+      }
+      if (o.onChunk) { try { o.onChunk(t, stream); } catch {} }
+    };
+    child.stdout.on('data', (d) => push(d, 'out'));
+    child.stderr.on('data', (d) => push(d, 'err'));
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (truncated) output += '\n[output truncated at 10 MB]';
+      resolve({ output: output || 'command completed', code: code == null ? 1 : code });
+    });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ error: 'sandbox exec failed: ' + err.message });
+    });
+  });
+}
+
+/**
+ * Build the sandbox: pull the chosen OS image, (re)create the container with
+ * the project mounted, install essentials (+ headless chromium when the OS
+ * offers it). Idempotent — re-running refreshes. The container is a single
+ * GLOBAL resource (~/.loom/config.json records it), so every session and
+ * every agent shares the same sandbox; only the mounted project follows the
+ * working directory via ensureProjectMount().
+ * @param {{ osId?: string, projectRoot?: string, onLog?: (line: string) => void }} [opts]
+ * @returns {Promise<{ ok: true, container: string }|{ ok: false, error: string }>}
+ */
+async function setupSandbox(opts) {
+  const o = opts || {};
+  const root = path.resolve(o.projectRoot || process.cwd());
+  const log = o.onLog || (() => {});
+  const { state, version } = detectDocker();
+  if (state === 'not_installed') return { ok: false, error: 'Docker is not installed. Run /sandbox guide for setup steps.' };
+  if (state === 'no_daemon') {
+    return { ok: false, error: 'Docker is installed but the daemon is not running. Start Docker Desktop (or `sudo systemctl start docker`), then run /sandbox setup again.' };
+  }
+  const osEntry = OS_CATALOG.find((x) => x.id === o.osId) || OS_CATALOG[0];
+  const image = osEntry.image;
+  log('Docker ' + version + ' detected — using ' + osEntry.label + ' (' + image + ').');
+  try {
+    log('Pulling ' + image + ' (first run only)…');
+    execFileSync('docker', ['pull', image], { encoding: 'utf8', windowsHide: true, timeout: 600000, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Recreate from scratch so image updates + mount changes always apply.
+    try { execFileSync('docker', ['rm', '-f', CONTAINER], { windowsHide: true, timeout: 30000, stdio: 'ignore' }); } catch {}
+    log('Creating container ' + CONTAINER + ' with ' + root + ' mounted at /workspace…');
+    execFileSync('docker', [
+      'create',
+      '--name', CONTAINER,
+      // Isolation: project dir only, no host network, no extra privileges.
+      '-v', root + ':/workspace',
+      '-w', '/workspace',
+      // Idle-forever main process; every agent command is a docker exec.
+      image, 'sleep', 'infinity',
+    ], { encoding: 'utf8', windowsHide: true, timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
+    execFileSync('docker', ['start', CONTAINER], { windowsHide: true, timeout: 60000, stdio: 'ignore' });
+    const pkgCmd = osEntry.pkg === 'apk'
+      ? 'apk add --no-cache ' + BASE_PACKAGES
+      : 'export DEBIAN_FRONTEND=noninteractive; apt-get update -qq && apt-get install -y -qq --no-install-recommends ' + BASE_PACKAGES + ' && rm -rf /var/lib/apt/lists/*';
+    log('Installing essentials (' + BASE_PACKAGES + ')…');
+    execFileSync('docker', ['exec', CONTAINER, 'sh', '-lc', pkgCmd],
+      { encoding: 'utf8', windowsHide: true, timeout: 600000, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Headless browser, when the chosen OS offers one — best-effort so a
+    // missing chromium package never fails the whole setup.
+    if (osEntry.browser) {
+      const browserCmd = osEntry.pkg === 'apk'
+        ? 'apk add --no-cache chromium'
+        : 'export DEBIAN_FRONTEND=noninteractive; apt-get update -qq && apt-get install -y -qq --no-install-recommends chromium && rm -rf /var/lib/apt/lists/*';
+      log('Installing a headless Chromium (best-effort)…');
+      try {
+        execFileSync('docker', ['exec', CONTAINER, 'sh', '-lc', browserCmd],
+          { encoding: 'utf8', windowsHide: true, timeout: 600000, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch {
+        log('Chromium unavailable in this image — browser tooling will be limited (sandbox continues).');
+      }
+    }
+    const cfg = loadConfig();
+    cfg.sandbox = Object.assign({}, cfg.sandbox, {
+      enabled: true, pending: false, image, osId: osEntry.id, projectRoot: root,
+    });
+    saveConfig(cfg);
+    log('Sandbox ready' + (osEntry.browser ? ' — including a headless Chromium for the browser tool' : '') + '.');
+    log('Agent commands now run inside ' + CONTAINER + ' (/workspace = this project). Every session and agent shares it.');
+    return { ok: true, container: CONTAINER };
+  } catch (e) {
+    return { ok: false, error: 'Sandbox setup failed: ' + (e && e.message ? e.message : String(e)) };
+  }
+}
+
+/**
+ * Make sure the shared container mounts the CURRENT project. Sessions in
+ * different directories share one sandbox — when the active project changes
+ * we just re-create the container with the new mount (image stays cached).
+ * Cheap no-op when the mount already matches.
+ * @param {string} [projectRoot]
+ * @returns {{ ok: true }|{ ok: false, error: string }}
+ */
+function ensureProjectMount(projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const cfg = loadConfig();
+  if (!cfg.sandbox || !cfg.sandbox.enabled) return { ok: false, error: 'sandbox disabled' };
+  if (cfg.sandbox.projectRoot === root) return { ok: true };
+  const image = cfg.sandbox.image || DEFAULT_IMAGE;
+  try {
+    try { execFileSync('docker', ['rm', '-f', CONTAINER], { windowsHide: true, timeout: 30000, stdio: 'ignore' }); } catch {}
+    execFileSync('docker', [
+      'create', '--name', CONTAINER,
+      '-v', root + ':/workspace', '-w', '/workspace',
+      image, 'sleep', 'infinity',
+    ], { encoding: 'utf8', windowsHide: true, timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
+    execFileSync('docker', ['start', CONTAINER], { windowsHide: true, timeout: 60000, stdio: 'ignore' });
+    cfg.sandbox.projectRoot = root;
+    saveConfig(cfg);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: 're-mount failed: ' + (e && e.message ? e.message : String(e)) };
+  }
+}
+
+/**
+ * Should the bash tool route this command through the sandbox? Cheap config
+ * check — container liveness is verified at setup time, and exec errors
+ * surface per command.
+ * @returns {boolean}
+ */
+function shouldUseSandbox() {
+  if (process.env.LOOM_SANDBOX === '0') return false;
+  const cfg = loadConfig();
+  return !!(cfg.sandbox && cfg.sandbox.enabled);
+}
+
+/**
+ * Toggle sandbox command routing (container keeps running either way).
+ * @param {boolean} on
+ */
+function setSandboxEnabled(on) {
+  const cfg = loadConfig();
+  cfg.sandbox = Object.assign({}, cfg.sandbox, { enabled: !!on });
+  saveConfig(cfg);
+}
+
+/**
+ * Arm the "waiting for Docker install" flow: the TUI shows the guide and
+ * tells the user to come back with "docker is ready".
+ */
+function markInstallPending() {
+  const cfg = loadConfig();
+  cfg.sandbox = Object.assign({}, cfg.sandbox, { pending: true });
+  saveConfig(cfg);
+}
+
+/**
+ * True when the user's message is the "docker is ready" resume signal while
+ * an install is pending (or they explicitly ask to set up the sandbox).
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isReadySignal(text) {
+  const t = String(text || '').trim().toLowerCase();
+  if (!t || t.length > 120) return false;
+  if (t.endsWith('?')) return false; // a question ("is docker ready yet?") is not an announcement
+  return /\bdocker\b/.test(t) && /\b(ready|installed|done|running|set ?up|finished)\b/.test(t);
+}
+
+module.exports = {
+  CONTAINER,
+  DEFAULT_IMAGE,
+  OS_CATALOG,
+  detectDocker,
+  installGuide,
+  installLink,
+  openInstallPage,
+  sandboxStatus,
+  toSandboxPath,
+  runInSandbox,
+  setupSandbox,
+  ensureProjectMount,
+  shouldUseSandbox,
+  setSandboxEnabled,
+  markInstallPending,
+  isReadySignal,
+};