loom-agent 1.3.2 → 1.3.3

package/CHANGELOG.md

@@ -29,16 +29,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   modal: (1) Docker check — if missing, shows the platform install link with
   an "open download page" action and remembers the pending install; (2) OS
   pick — Alpine (~250 MB, apk), Debian Slim (~600 MB, apt) or Ubuntu
-  (~900 MB, apt); (3) live build with streamed logs. Setup pulls the chosen
-  `node:20-*` image, creates the single shared `loom-sandbox` container with
-  the project mounted at `/workspace`, installs essentials (git, bash, curl,
-  ripgrep, coreutils) plus a headless Chromium where offered (best-effort).
-  The container is global — every session and every agent routes commands
-  through it — and `ensureProjectMount()` re-creates it cheaply when the
-  active project changes. Isolation: project dir only, no host network, no
-  `--privileged`. The bash tool routes through `docker exec` when enabled;
-  `LOOM_SANDBOX=0` is a hard kill-switch. Saying "docker is ready" after
-  installing reopens the wizard at the OS step.
+  (~900 MB, apt); (3) live build with a real progress UI: per-stage
+  checklist (pull → create → start → essentials → browser → ready), a
+  percentage bar driven by actual docker-pull layer bytes, and streamed
+  install logs. Setup is fully asynchronous — the TUI never freezes — and
+  the wizard can be esc'd while setup continues in the background. Setup
+  pulls the chosen `node:20-*` image, creates the single shared
+  `loom-sandbox` container with the project mounted at `/workspace`,
+  installs essentials (git, bash, curl, ripgrep, coreutils) plus a headless
+  Chromium where offered (best-effort). Isolation: project dir only, no host
+  network, no `--privileged`. The container idles in the background; the
+  dedicated **`sandbox` tool** runs one command inside it only when the
+  agent decides isolation is needed (see Changed). `LOOM_SANDBOX=0` is a
+  hard kill-switch. Saying "docker is ready" after installing reopens the
+  wizard at the OS step.
 - **Drive-to-completion harness (`src/core/session.js`).** When the model ends
   a turn with todos still pending/in_progress (the "stops between tasks"
   failure), the loop injects a continuation listing the unfinished items — up
@@ -82,6 +86,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     todos are surfaced to the UI whenever the guard engaged.
 
 ### Changed
+- **Sandbox is now opt-in per command, not a global router.** Enabling the
+  sandbox no longer hijacks the bash tool — every host command keeps running
+  on your machine (Windows included) exactly as before. Instead, a dedicated
+  **`sandbox` tool** appears; the agent calls it only when isolation is
+  genuinely needed (you asked for the sandbox, the command is risky, or a
+  Linux-only environment is required). Each call revives the container if it
+  stopped (e.g. after a Docker Desktop restart) and re-mounts the current
+  project, then runs just that one command via `docker exec`. The container
+  idles in the background between calls; `/sandbox off` disables the tool
+  (not the host), `/sandbox on` re-enables it. The setup wizard's build step
+  also became fully non-blocking: docker pull streams per-layer progress
+  into a live percentage bar, package installs stream their output, and the
+  TUI stays responsive throughout (esc lets setup finish in the background).
 - **Slash popup decluttered.** The autocomplete popup and command palette
   now show a short one-line description per command — argument syntax is no
   longer appended (it lives in `/help` and the README table). Duplicate

package/README.md

@@ -163,7 +163,7 @@ self-test client (`node scripts/acp-smoke.js`) live in **[docs/acp.md](docs/acp.
 | `/tasks` | — | Background tasks |
 | `/share` | — | Export chat as HTML |
 | `/worktree` | `<name>` | New git worktree |
-| `/sandbox` | `setup\|status\|on\|off\|rm` | Docker sandbox |
+| `/sandbox` | `setup\|status\|on\|off\|rm` | Docker sandbox (opt-in `sandbox` tool; host untouched) |
 | `/style` | `[preset\|text]` | Output style preset |
 | `/vim` | — | Toggle vim editing |
 | `/remember` | `<fact>` | Save a fact to LOOM.md |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loom-agent",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/toshalkumbhar8979-design/loomcode.git"

package/src/core/sandbox.js

@@ -1,4 +1,9 @@
-// Docker sandbox — a lightweight, isolated OS for the agent's shell commands.
+// Docker sandbox — a lightweight, isolated Linux OS the agent can use ON
+// DEMAND. It is NOT a routing layer: host commands (bash tool) keep running
+// on the user's machine exactly as before. When the agent needs isolation
+// (user asked for the sandbox, a risky command, a Linux-only tool), it calls
+// the dedicated `sandbox` tool, which runs that ONE command via `docker exec`
+// into a shared idle-running container.
 //
 // Flow (guided in the TUI via the /sandbox modal):
 //   1. Step 1 checks Docker. If missing, the modal shows the download link
@@ -8,13 +13,12 @@
 //      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
+//      and keeps the container idle-running in the background.
+//   3. With sandbox.enabled, the sandbox TOOL becomes available. Each call
+//      revives the container if it stopped (e.g. after a Docker restart) and
+//      re-mounts the current project, then runs just that command. 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.
+//      and writes are shared while side effects of the command stay contained.
 //
 // 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
@@ -179,20 +183,22 @@ function toSandboxPath(hostDir, projectRoot) {
 }
 
 /**
- * Run a shell command inside the sandbox container. Streams output via
- * onChunk('out'|'err') while running; resolves with { output, code } or
- * { error }.
+ * Run ONE shell command inside the sandbox container (used by the sandbox
+ * tool — host commands stay on the bash tool). Revives the container if it
+ * stopped and re-mounts the current project, then streams output via
+ * onChunk('out'|'err'); 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) {
+async 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 });
-  }
+  // Bring the container back if the daemon restarted, then make sure it
+  // mounts the CURRENT project (cheap no-op when both already match).
+  const alive = await ensureContainerAlive();
+  if (!alive.ok) return { error: alive.error };
+  const remount = await ensureProjectMount(o.projectRoot);
+  if (!remount.ok) return { error: 'sandbox re-mount failed: ' + remount.error };
   const wd = toSandboxPath(o.workdir, o.projectRoot);
   const timeoutMs = o.timeoutMs || 120000;
   return new Promise((resolve) => {
@@ -234,20 +240,114 @@ function runInSandbox(command, opts) {
   });
 }
 
+/**
+ * Spawn a host command, line-buffer its output, never block the event loop.
+ * Used by setupSandbox so the TUI keeps rendering (and the progress UI keeps
+ * updating) while docker pull / package installs run.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ timeoutMs?: number, onLine?: (line: string, stream: 'out'|'err') => void }} [opts]
+ * @returns {Promise<{ code: number, out: string }>}
+ */
+function spawnAsync(cmd, args, opts) {
+  const o = opts || {};
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: -1, out: (e && e.message) || String(e) });
+      return;
+    }
+    const timer = o.timeoutMs
+      ? setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, o.timeoutMs)
+      : null;
+    let out = '';
+    const MAX_OUT = 4 * 1024 * 1024;
+    const feed = (/** @type {Buffer} */ d, /** @type {'out'|'err'} */ stream) => {
+      const t = d.toString();
+      if (out.length < MAX_OUT) out += t;
+      if (!o.onLine) return;
+      // Line-buffer: docker writes progress with \r on TTYs and \n otherwise;
+      // treat both as separators so the UI gets fresh rows, not one blob.
+      const lines = t.split(/\r?\n/);
+      for (const line of lines) {
+        if (!line) continue;
+        try { o.onLine(line.replace(/\x1b\[[0-9;]*m/g, ''), stream); } catch {}
+      }
+    };
+    child.stdout.on('data', (d) => feed(d, 'out'));
+    child.stderr.on('data', (d) => feed(d, 'err'));
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({ code: -1, out: (out ? out + '\n' : '') + err.message });
+    });
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ code: code == null ? 1 : code, out });
+    });
+  });
+}
+
+// "12.34MB" / "951kB" / "1.2GB" → bytes (docker prints SI-style units).
+function parseBytes(str, unit) {
+  const n = parseFloat(str);
+  if (!isFinite(n)) return 0;
+  const u = String(unit || '').toLowerCase();
+  if (u === 'gb') return n * 1e9;
+  if (u === 'mb') return n * 1e6;
+  if (u === 'kb') return n * 1e3;
+  return n;
+}
+
+/**
+ * Fold one docker-pull stdout line into the per-layer progress map. Layers
+ * report "Downloading [bar] X/Y", "Extracting [bar] X/Y", then "Pull complete".
+ * @param {string} line
+ * @param {Map<string, number>} layers layer-id → fraction 0..1
+ */
+function trackPullLine(line, layers) {
+  const done = /^([0-9a-f]{8,64}):\s+(?:Download complete|Pull complete)\s*$/i.exec(line);
+  if (done) { layers.set(done[1], 1); return; }
+  // "Waiting" = queued layer, no bytes yet.
+  const waiting = /^([0-9a-f]{8,64}):\s+Waiting\s*$/i.exec(line);
+  if (waiting) { layers.set(waiting[1], 0); return; }
+  const active = /^([0-9a-f]{8,64}):\s+(?:Downloading|Extracting)\s+(?:\[[^\]]*\]\s+)?([\d.]+)([kmgt]?b)(?:\/([\d.]+)([kmgt]?b))?/i.exec(line);
+  if (active) {
+    const id = active[1];
+    if (active[4]) {
+      const total = parseBytes(active[4], active[5]);
+      const cur = parseBytes(active[2], active[3]);
+      if (total > 0) layers.set(id, Math.min(1, cur / total));
+    } else if (!layers.has(id)) {
+      layers.set(id, 0);
+    }
+  }
+}
+
+function pullPercent(layers) {
+  if (!layers.size) return null;
+  let sum = 0;
+  for (const frac of layers.values()) sum += frac;
+  return Math.min(99, Math.round((sum / layers.size) * 100));
+}
+
 /**
  * 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
+ * offers it). Fully ASYNC — every docker call streams, so the TUI never
+ * freezes and onProgress/onLog deliver live updates. 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]
+ * @param {{ osId?: string, projectRoot?: string, onLog?: (line: string) => void, onProgress?: (p: { stage: string, pct: number|null, step: number, total: number }) => 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 prog = o.onProgress || (() => {});
   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') {
@@ -256,77 +356,124 @@ async function setupSandbox(opts) {
   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).');
+  // Stages reported to onProgress: pull → create → start → essentials → browser → done.
+  const stages = ['pull', 'create', 'start', 'essentials'].concat(osEntry.browser ? ['browser'] : [], ['done']);
+  const stageIdx = (/** @type {string} */ s) => { const i = stages.indexOf(s); return i < 0 ? 0 : i; };
+  prog({ stage: 'pull', pct: 0, step: stageIdx('pull'), total: stages.length });
+
+  // ── Stage 1: pull the image (real per-layer progress, async + streamed) ──
+  log('Pulling ' + image + ' (first run only)…');
+  const layers = new Map();
+  let lastPct = -1;
+  const pull = await spawnAsync('docker', ['pull', image], {
+    timeoutMs: 600000,
+    onLine: (line) => {
+      trackPullLine(line, layers);
+      const pct = pullPercent(layers);
+      if (pct != null && pct !== lastPct) {
+        lastPct = pct;
+        prog({ stage: 'pull', pct, step: stageIdx('pull'), total: stages.length });
       }
-    }
-    const cfg = loadConfig();
-    cfg.sandbox = Object.assign({}, cfg.sandbox, {
-      enabled: true, pending: false, image, osId: osEntry.id, projectRoot: root,
+      if (/^status:|^digest:|up to date/i.test(line)) log(line);
+    },
+  });
+  if (pull.code !== 0) {
+    return { ok: false, error: 'docker pull failed (exit ' + pull.code + '): ' + pull.out.slice(-400) };
+  }
+  prog({ stage: 'pull', pct: 100, step: stageIdx('pull'), total: stages.length });
+
+  // ── Stage 2: recreate the container from scratch (image updates + mount) ──
+  prog({ stage: 'create', pct: null, step: stageIdx('create'), total: stages.length });
+  await spawnAsync('docker', ['rm', '-f', CONTAINER], { timeoutMs: 30000 });
+  log('Creating container ' + CONTAINER + ' with ' + root + ' mounted at /workspace…');
+  const create = await spawnAsync('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',
+  ], { timeoutMs: 60000 });
+  if (create.code !== 0) {
+    return { ok: false, error: 'docker create failed (exit ' + create.code + '): ' + create.out.slice(-300) };
+  }
+
+  // ── Stage 3: start it (stays idle in the background until the sandbox
+  // tool is explicitly invoked) ──
+  prog({ stage: 'start', pct: null, step: stageIdx('start'), total: stages.length });
+  const start = await spawnAsync('docker', ['start', CONTAINER], { timeoutMs: 60000 });
+  if (start.code !== 0) {
+    return { ok: false, error: 'docker start failed (exit ' + start.code + '): ' + start.out.slice(-300) };
+  }
+
+  // ── Stage 4: install essentials (streamed so the UI shows life) ──
+  prog({ stage: 'essentials', pct: null, step: stageIdx('essentials'), total: stages.length });
+  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 + ')…');
+  const install = await spawnAsync('docker', ['exec', CONTAINER, 'sh', '-lc', pkgCmd], {
+    timeoutMs: 600000,
+    onLine: (line) => { if (!/^\s*$/.test(line)) log(line); },
+  });
+  if (install.code !== 0) {
+    return { ok: false, error: 'package install failed (exit ' + install.code + '): ' + install.out.slice(-400) };
+  }
+
+  // ── Stage 5: headless browser when the OS offers one — best-effort, so a
+  // missing chromium package never fails the whole setup. ──
+  if (osEntry.browser) {
+    prog({ stage: 'browser', pct: null, step: stageIdx('browser'), total: stages.length });
+    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)…');
+    const browser = await spawnAsync('docker', ['exec', CONTAINER, 'sh', '-lc', browserCmd], {
+      timeoutMs: 600000,
+      onLine: (line) => { if (!/^\s*$/.test(line)) log(line); },
     });
-    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)) };
+    if (browser.code !== 0) {
+      log('Chromium unavailable in this image — browser tooling will be limited (sandbox continues).');
+    }
   }
+
+  prog({ stage: 'done', pct: 100, step: stageIdx('done'), total: stages.length });
+  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('Container ' + CONTAINER + ' idles in the background; the sandbox tool uses it only when the agent needs a Linux environment.');
+  return { ok: true, container: CONTAINER };
 }
 
 /**
  * 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.
+ * Cheap no-op when the mount already matches. Fully async (never blocks the
+ * TUI event loop).
  * @param {string} [projectRoot]
- * @returns {{ ok: true }|{ ok: false, error: string }}
+ * @returns {Promise<{ ok: true }|{ ok: false, error: string }>}
  */
-function ensureProjectMount(projectRoot) {
+async 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', [
+    await spawnAsync('docker', ['rm', '-f', CONTAINER], { timeoutMs: 30000 });
+    const create = await spawnAsync('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' });
+    ], { timeoutMs: 60000 });
+    if (create.code !== 0) return { ok: false, error: 're-mount create failed: ' + create.out.slice(-200) };
+    const start = await spawnAsync('docker', ['start', CONTAINER], { timeoutMs: 60000 });
+    if (start.code !== 0) return { ok: false, error: 're-mount start failed: ' + start.out.slice(-200) };
     cfg.sandbox.projectRoot = root;
     saveConfig(cfg);
     return { ok: true };
@@ -336,9 +483,35 @@ function ensureProjectMount(projectRoot) {
 }
 
 /**
- * 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.
+ * Make sure the container exists and is RUNNING before a sandbox-tool call.
+ * Revives a stopped container (Docker Desktop restart, reboot) with a quick
+ * `docker start`; never recreates (image/mount are setup-time concerns).
+ * @returns {Promise<{ ok: true }|{ ok: false, error: string }>}
+ */
+async function ensureContainerAlive() {
+  const cfg = loadConfig();
+  if (!cfg.sandbox || !cfg.sandbox.enabled) {
+    return { ok: false, error: 'Sandbox is not set up. Run /sandbox (or /sandbox setup) first — it only takes a minute and is needed once.' };
+  }
+  if (process.env.LOOM_SANDBOX === '0') {
+    return { ok: false, error: 'Sandbox disabled via LOOM_SANDBOX=0.' };
+  }
+  const inspect = await spawnAsync('docker', ['inspect', '-f', '{{.State.Running}}', CONTAINER], { timeoutMs: 15000 });
+  if (inspect.code !== 0 || !inspect.out.trim()) {
+    return { ok: false, error: 'Sandbox container is missing (deleted?). Run /sandbox setup again.' };
+  }
+  if (inspect.out.trim() === 'true') return { ok: true };
+  const start = await spawnAsync('docker', ['start', CONTAINER], { timeoutMs: 60000 });
+  if (start.code !== 0) {
+    return { ok: false, error: 'Sandbox container exists but could not be started: ' + start.out.slice(-200) + '. If Docker was restarted, start it and try again.' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Is the sandbox TOOL available (set up and not kill-switched)? Used by the
+ * sandbox tool to decide between running and a helpful "run /sandbox first"
+ * error — NOT to route ordinary bash commands (those stay on the host).
  * @returns {boolean}
  */
 function shouldUseSandbox() {
@@ -348,7 +521,7 @@ function shouldUseSandbox() {
 }
 
 /**
- * Toggle sandbox command routing (container keeps running either way).
+ * Toggle sandbox availability (the container idles either way).
  * @param {boolean} on
  */
 function setSandboxEnabled(on) {
@@ -393,7 +566,10 @@ module.exports = {
   runInSandbox,
   setupSandbox,
   ensureProjectMount,
+  ensureContainerAlive,
   shouldUseSandbox,
+  trackPullLine,
+  pullPercent,
   setSandboxEnabled,
   markInstallPending,
   isReadySignal,

package/src/core/session.js

@@ -263,6 +263,7 @@ ${this.loadSkills()}
 ## Mode
 You are in ${this.mode === 'build' ? 'BUILD MODE (full agent)' : this.mode === 'plan' ? 'PLAN MODE (read-only analysis)' : 'CHAT MODE (conversation only)'}.
 ${this.mode === 'build' ? `- You have all tools available: read, write, edit, bash, glob, grep, webfetch, and MCP tools.
+- bash runs on the user's machine. Only use the sandbox tool when isolation is genuinely needed (the user asked for it, or the command is risky/Linux-only); never for ordinary commands.
 - Inspect, edit, and verify the result yourself end-to-end.
 - When done, summarize in 1-2 sentences.` : ''}${this.mode === 'plan' ? `- Read-only tools only: read, glob, grep, webfetch, todowrite. No MCP tools.
 - Investigate thoroughly, then output a "## Plan" with ordered steps (exact file path + what changes each step makes). No narration.` : ''}${this.mode === 'chat' ? `- No tools available; answer conversationally.

package/src/tools/index.js

@@ -186,31 +186,13 @@ const TOOLS = {
   },
   bash: {
     name: 'bash',
-    description: 'Execute a shell command.',
+    description: 'Execute a shell command on the user\'s machine.',
     parameters: {
       command: { type: 'string', required: true, description: 'The command to execute' },
       workdir: { type: 'string', required: false, description: 'Working directory' },
       background: { type: 'boolean', required: false, description: 'Run without waiting (dev servers, long builds). Returns a task id immediately; check with the /tasks panel.' },
     },
     async execute(params, ctx) {
-      // Docker sandbox: when enabled (/sandbox setup), every command runs
-      // inside the loom-sandbox container instead of the host shell.
-      // Background tasks stay on the host (they outlive tool timeouts).
-      const sandbox = require('../core/sandbox');
-      if (!params.background && sandbox.shouldUseSandbox()) {
-        if (!pathAllowed(params.workdir || cwd)) return { error: sandboxDenied('bash', params.workdir || cwd) };
-        const risk = params._approved ? null : commandRiskLabel(params.command);
-        if (risk) return { error: `Blocked by safety filter: ${risk}. Approve it via the permission prompt to run it anyway.` };
-        const stream = ctx && typeof ctx.stream === 'function' ? ctx.stream : null;
-        const res = await sandbox.runInSandbox(params.command, {
-          workdir: params.workdir || cwd,
-          onChunk: stream ? (text, which) => stream(text, which) : undefined,
-        });
-        if ('error' in res) return { error: res.error };
-        let out = res.output;
-        if (res.code !== 0) out += `\n[exit code: ${res.code}]`;
-        return out || 'command completed';
-      }
       // Background mode: fire-and-forget via the task registry.
       if (params.background) {
         const bt = require('../core/background-tasks');
@@ -283,6 +265,32 @@ const TOOLS = {
       });
     }
   },
+  sandbox: {
+    name: 'sandbox',
+    description: 'Run a shell command INSIDE the Docker sandbox (isolated Linux container, project mounted at /workspace). Use ONLY when isolation is needed: the user asked for the sandbox, the command is risky (installs, deletions, untrusted scripts), or a Linux-only environment is required. For ordinary commands use bash (host). One command per call; the container idles in the background between calls.',
+    parameters: {
+      command: { type: 'string', required: true, description: 'The Linux shell command to run inside the container' },
+      workdir: { type: 'string', required: false, description: 'Working directory inside the container (host paths under the project map to /workspace/...)' },
+      timeoutMs: { type: 'number', required: false, description: 'Kill the command after this many ms (default 120000)' },
+    },
+    async execute(params, ctx) {
+      // Opt-in isolation path: nothing is routed here automatically. The
+      // container is revived/re-mounted on demand, then torn back to idle.
+      const sandbox = require('../core/sandbox');
+      const risk = params._approved ? null : commandRiskLabel(params.command);
+      if (risk) return { error: `Blocked by safety filter: ${risk}. Approve it via the permission prompt to run it anyway.` };
+      const stream = ctx && typeof ctx.stream === 'function' ? ctx.stream : null;
+      const res = await sandbox.runInSandbox(params.command, {
+        workdir: params.workdir || cwd,
+        timeoutMs: typeof params.timeoutMs === 'number' && params.timeoutMs > 0 ? params.timeoutMs : undefined,
+        onChunk: stream ? (text, which) => stream(text, which) : undefined,
+      });
+      if ('error' in res) return { error: res.error };
+      let out = res.output;
+      if (res.code !== 0) out += `\n[exit code: ${res.code}]`;
+      return out || 'command completed';
+    }
+  },
   grep: {
     name: 'grep',
     description: 'Search file contents using regular expressions.',

package/src/tui/App.tsx

@@ -1096,13 +1096,13 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
         if (ssub === "guide") { appendMessage({ role: "system", content: sandbox.installGuide() }); return; }
         if (ssub === "off") {
           sandbox.setSandboxEnabled(false);
-          appendMessage({ role: "system", content: "Sandbox off — agent commands run on the host again. The container is kept (run /sandbox on to re-enable, /sandbox rm to delete it)." });
+          appendMessage({ role: "system", content: "Sandbox off — the sandbox tool is disabled; the agent works on your machine as usual. The container is kept (run /sandbox on to re-enable, /sandbox rm to delete it)." });
           return;
         }
         if (ssub === "on") {
           if (st.container !== "running") { appendMessage({ role: "system", content: "Sandbox container is not running. Run /sandbox setup first." }); return; }
           sandbox.setSandboxEnabled(true);
-          appendMessage({ role: "system", content: "Sandbox on — agent commands now run inside " + sandbox.CONTAINER + "." });
+          appendMessage({ role: "system", content: "Sandbox on — the agent can use the sandbox tool for isolated commands inside " + sandbox.CONTAINER + " when needed. Everything else stays on your machine." });
           return;
         }
         if (ssub === "rm") {
@@ -1117,7 +1117,7 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
           var line = "Sandbox: ";
           if (st.docker === "not_installed") line += "Docker not installed";
           else if (st.docker === "no_daemon") line += "Docker installed, daemon not running";
-          else line += "Docker " + st.dockerVersion + " \u00b7 container " + st.container + (st.enabled ? " \u00b7 routing ON" : " \u00b7 routing off");
+          else line += "Docker " + st.dockerVersion + " \u00b7 container " + st.container + (st.enabled ? " \u00b7 sandbox tool on" : " \u00b7 sandbox tool off");
           if (st.pending) line += "\nWaiting for you to install Docker \u2014 when it's done say \"docker is ready\" (or run /sandbox).";
           else if (st.docker === "not_installed") line += "\nRun /sandbox for the setup wizard.";
           else if (st.container === "absent") line += "\nRun /sandbox to build it.";

package/src/tui/components/Modals.tsx

@@ -1,5 +1,5 @@
 // Modals -- provider picker, model picker, key input, base URL, settings, palette.
-import { createSignal, createMemo, onMount } from "solid-js";
+import { createSignal, createMemo, onMount, onCleanup } from "solid-js";
 import { useKeyboard, usePaste } from "@opentui/solid";
 import { palette } from "../theme.ts";
 import * as kbs from "../keybinds.ts";
@@ -663,8 +663,9 @@ export function ConnectorsModal() {
 
 // ── Sandbox setup wizard ──
 // Three steps: docker check (with install link when missing) → OS pick →
-// live setup. The container is global — once built, every session and every
-// agent routes commands through it.
+// live setup with a real progress bar (setup streams from the core layer —
+// the TUI never freezes). The container is global and idles in the
+// background; the agent's sandbox tool uses it on demand.
 export function SandboxModal() {
   const sb = require("../../core/sandbox.js");
   const [step, setStep] = createSignal<"docker" | "os" | "setup">("docker");
@@ -673,6 +674,30 @@ export function SandboxModal() {
   const [logs, setLogs] = createSignal<string[]>([]);
   const [busy, setBusy] = createSignal(false);
   const [err, setErr] = createSignal<string | null>(null);
+  const [prog, setProg] = createSignal<{ stage: string; pct: number | null; step: number; total: number } | null>(null);
+  const [spin, setSpin] = createSignal(0);
+  let spinTimer: ReturnType<typeof setInterval> | null = null;
+  onCleanup(() => { if (spinTimer) clearInterval(spinTimer); });
+
+  // Spinner frames while setup is busy (drives the "working…" indicator).
+  function startSpinner() {
+    if (spinTimer) clearInterval(spinTimer);
+    spinTimer = setInterval(() => setSpin((s) => (s + 1) % 10), 120);
+  }
+  function stopSpinner() {
+    if (spinTimer) clearInterval(spinTimer);
+    spinTimer = null;
+  }
+  const SPIN_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+
+  const STAGE_LABELS: Record<string, string> = {
+    pull: "Pulling image",
+    create: "Creating container",
+    start: "Starting container",
+    essentials: "Installing essentials",
+    browser: "Installing browser",
+    done: "Ready",
+  };
 
   // Docker already installed → advance straight to OS selection (with a
   // brief "installed" flash so the user sees the check happened).
@@ -693,14 +718,18 @@ export function SandboxModal() {
     setStep("setup");
     setBusy(true);
     setErr(null);
+    setProg(null);
+    startSpinner();
     setLogs(["Preparing " + os.label + " (" + os.image + ")…"]);
     sb.setupSandbox({
       osId: os.id,
       onLog: (/** @type {string} */ l) => setLogs((xs) => [...xs, l]),
+      onProgress: (/** @type {{ stage: string; pct: number | null; step: number; total: number }} */ p) => setProg(p),
     }).then((/** @type {{ ok: boolean, error?: string }} */ res) => {
       setBusy(false);
+      stopSpinner();
       if (res.ok) {
-        appendMessage({ role: "system", content: "Sandbox is live (" + os.label + "). Agent commands now run inside Docker; your project is mounted at /workspace. The sandbox is shared: every session and agent uses it." });
+        appendMessage({ role: "system", content: "Sandbox is live (" + os.label + "). The container idles in the background; the agent will use it via the sandbox tool whenever isolation is needed. Your project is mounted at /workspace." });
         showToast("Sandbox ready — " + os.label, "ok");
         closeModal();
       } else {
@@ -805,9 +834,39 @@ export function SandboxModal() {
         </box>
       ) : null}
       {step() === "setup" ? (
-        <box flexDirection="column" maxWidth={64}>
-          {logs().slice(-8).map((l) => <text fg={ui.fgMuted}>{"▸ " + l}</text>)}
-          {busy() ? <text fg={ui.primary}>…</text> : null}
+        <box flexDirection="column" maxWidth={72}>
+          {/* Stage checklist with a live pull-progress bar (pct from core). */}
+          {prog() ? (() => {
+            const p = prog()!;
+            const os = sb.OS_CATALOG[osSel()];
+            // Same stage order the core reports (browser only when offered).
+            const keys = ["pull", "create", "start", "essentials"]
+              .concat(os.browser ? ["browser"] : [], ["done"])
+              .slice(0, p.total);
+            return (
+              <box flexDirection="column" marginBottom={1}>
+                {keys.map((key, i) => {
+                  const done = i < p.step || p.stage === "done";
+                  const active = i === p.step && p.stage !== "done";
+                  const mark = done ? "✓" : active ? SPIN_FRAMES[spin()] : "○";
+                  const color = done ? ui.success : active ? ui.primary : ui.fgDim;
+                  let bar = "";
+                  if (active && p.pct != null) {
+                    const width = 20;
+                    const filled = Math.round((p.pct / 100) * width);
+                    bar = " [" + "█".repeat(filled) + "░".repeat(width - filled) + "] " + p.pct + "%";
+                  } else if (active) {
+                    bar = " …";
+                  }
+                  return (
+                    <text fg={color}>{mark + " " + STAGE_LABELS[key] + bar}</text>
+                  );
+                })}
+              </box>
+            );
+          })() : <text fg={ui.fgMuted}>Starting…</text>}
+          {logs().slice(-6).map((l) => <text fg={ui.fgMuted}>{"▸ " + l.slice(0, 68)}</text>)}
+          {busy() ? <text fg={ui.primary}>{SPIN_FRAMES[spin()] + " working — you can esc; setup continues in the background"}</text> : null}
           {err() ? (
             <box flexDirection="column" marginTop={1}>
               <text fg={ui.error}>{err()}</text>