@locusai/cli 0.17.15 → 0.18.0

package/bin/locus.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
@@ -14,6 +15,7 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/core/ai-models.ts
 function inferProviderFromModel(model) {
@@ -520,7 +522,7 @@ var init_config = __esm(() => {
   init_ai_models();
   init_logger();
   DEFAULT_CONFIG = {
-    version: "3.0.0",
+    version: "3.1.0",
     github: {
       owner: "",
       repo: "",
@@ -545,9 +547,28 @@ var init_config = __esm(() => {
       level: "normal",
       maxFiles: 20,
       maxTotalSizeMB: 50
+    },
+    sandbox: {
+      enabled: true,
+      extraWorkspaces: [],
+      readOnlyPaths: []
     }
   };
-  migrations = [];
+  migrations = [
+    {
+      from: "3.0",
+      to: "3.1.0",
+      migrate: (config) => {
+        config.sandbox ??= {
+          enabled: true,
+          extraWorkspaces: [],
+          readOnlyPaths: []
+        };
+        config.version = "3.1.0";
+        return config;
+      }
+    }
+  ];
 });
 
 // src/core/context.ts
@@ -1582,6 +1603,15 @@ ${bold("Initializing Locus...")}
 `);
   } else {
     process.stderr.write(`${dim("○")} LEARNINGS.md already exists (preserved)
+`);
+  }
+  const sandboxIgnorePath = join5(cwd, ".sandboxignore");
+  if (!existsSync5(sandboxIgnorePath)) {
+    writeFileSync4(sandboxIgnorePath, SANDBOXIGNORE_TEMPLATE, "utf-8");
+    process.stderr.write(`${green("✓")} Generated .sandboxignore
+`);
+  } else {
+    process.stderr.write(`${dim("○")} .sandboxignore already exists (preserved)
 `);
   }
   process.stderr.write(`${cyan("●")} Creating GitHub labels...`);
@@ -1627,6 +1657,23 @@ ${bold(green("Locus initialized!"))}
   process.stderr.write(`  ${gray("4.")} Start coding:  ${bold("locus exec")}
 `);
   process.stderr.write(`
+${bold("Sandbox mode")} ${dim("(recommended)")}
+`);
+  process.stderr.write(`  Run AI agents in an isolated Docker sandbox for safety.
+
+`);
+  process.stderr.write(`  ${gray("1.")} ${cyan("locus sandbox")}          ${dim("Create the sandbox environment")}
+`);
+  process.stderr.write(`  ${gray("2.")} ${cyan("locus sandbox claude")}   ${dim("Login to Claude inside the sandbox")}
+`);
+  process.stderr.write(`  ${gray("3.")} ${cyan("locus exec")}             ${dim("All commands now run sandboxed")}
+`);
+  process.stderr.write(`
+  ${dim("Using Codex? Run")} ${cyan("locus sandbox codex")} ${dim("instead of step 2.")}
+`);
+  process.stderr.write(`  ${dim("Learn more:")} ${cyan("locus sandbox help")}
+`);
+  process.stderr.write(`
 `);
   log.info("Locus initialized", {
     owner: context.owner,
@@ -1743,6 +1790,31 @@ Read ".locus/LEARNINGS.md" **before starting any task** to avoid repeating mista
 ## Development Workflow
 
 <!-- How to run, test, build, and deploy the project -->
+`, SANDBOXIGNORE_TEMPLATE = `# Files and directories to exclude from sandbox environments.
+# Patterns follow .gitignore syntax (one per line, # for comments).
+# These files will be removed from the sandbox after creation.
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Secrets and credentials
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+credentials.json
+service-account*.json
+
+# Cloud provider configs
+.aws/
+.gcp/
+.azure/
+
+# Docker secrets
+docker-compose.override.yml
 `, LEARNINGS_MD_TEMPLATE = `# Learnings
 
 This file captures important lessons, decisions, and corrections made during development.
@@ -2611,24 +2683,33 @@ var init_status_indicator = __esm(() => {
     startTime = 0;
     activity = "";
     frame = 0;
+    message = "";
     static BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
     static DIAMOND = "◆";
     start(message, options) {
       this.stop();
       this.startTime = Date.now();
       this.activity = options?.activity ?? "";
+      this.message = message;
       this.frame = 0;
       if (process.stderr.isTTY) {
         process.stderr.write("\x1B[?25l");
       }
+      this.render();
+      this.frame++;
       this.timer = setInterval(() => {
-        this.render(message);
+        this.render();
         this.frame++;
       }, 80);
     }
     setActivity(activity) {
       this.activity = activity;
     }
+    setMessage(message) {
+      this.message = message;
+      if (this.timer)
+        this.render();
+    }
     stop() {
       if (this.timer) {
         clearInterval(this.timer);
@@ -2641,7 +2722,8 @@ var init_status_indicator = __esm(() => {
     isActive() {
       return this.timer !== null;
     }
-    render(message) {
+    render() {
+      const message = this.message;
       const caps = getCapabilities();
       const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
       const elapsedStr = `${elapsed}s`;
@@ -2663,7 +2745,7 @@ var init_status_indicator = __esm(() => {
       }
       if (!process.stderr.isTTY)
         return;
-      process.stderr.write("\x1B[2K\r" + line);
+      process.stderr.write(`\x1B[2K\r${line}`);
     }
     renderShimmer() {
       const t = Date.now() / 1000;
@@ -3787,7 +3869,25 @@ var init_input_handler = __esm(() => {
 });
 
 // src/ai/claude.ts
+var exports_claude = {};
+__export(exports_claude, {
+  buildClaudeArgs: () => buildClaudeArgs,
+  ClaudeRunner: () => ClaudeRunner
+});
 import { execSync as execSync4, spawn as spawn2 } from "node:child_process";
+function buildClaudeArgs(options) {
+  const args = [
+    "--dangerously-skip-permissions",
+    "--no-session-persistence"
+  ];
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+  if (options.verbose) {
+    args.push("--verbose", "--output-format", "stream-json");
+  }
+  return args;
+}
 
 class ClaudeRunner {
   name = "claude";
@@ -3818,17 +3918,7 @@ class ClaudeRunner {
   async execute(options) {
     const log = getLogger();
     this.aborted = false;
-    const args = [
-      "--print",
-      "--dangerously-skip-permissions",
-      "--no-session-persistence"
-    ];
-    if (options.model) {
-      args.push("--model", options.model);
-    }
-    if (options.verbose) {
-      args.push("--verbose", "--output-format", "stream-json");
-    }
+    const args = ["--print", ...buildClaudeArgs(options)];
     log.debug("Spawning claude", { args: args.join(" "), cwd: options.cwd });
     return new Promise((resolve2) => {
       let output = "";
@@ -3979,224 +4069,1207 @@ var init_claude = __esm(() => {
   init_logger();
 });
 
-// src/ai/codex.ts
-import { execSync as execSync5, spawn as spawn3 } from "node:child_process";
-function buildCodexArgs(model) {
-  const args = ["exec", "--full-auto", "--skip-git-repo-check", "--json"];
-  if (model) {
-    args.push("--model", model);
+// src/core/sandbox-ignore.ts
+import { exec } from "node:child_process";
+import { existsSync as existsSync11, readFileSync as readFileSync8 } from "node:fs";
+import { join as join10 } from "node:path";
+import { promisify } from "node:util";
+function parseIgnoreFile(filePath) {
+  if (!existsSync11(filePath))
+    return [];
+  const content = readFileSync8(filePath, "utf-8");
+  const rules = [];
+  for (const rawLine of content.split(`
+`)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const negated = line.startsWith("!");
+    const raw = negated ? line.slice(1) : line;
+    const isDirectory = raw.endsWith("/");
+    const pattern = isDirectory ? raw.slice(0, -1) : raw;
+    rules.push({ pattern, negated, isDirectory });
   }
-  args.push("-");
-  return args;
+  return rules;
 }
-
-class CodexRunner {
-  name = "codex";
-  process = null;
-  aborted = false;
-  async isAvailable() {
-    try {
-      execSync5("codex --version", {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async getVersion() {
-    try {
-      const output = execSync5("codex --version", {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      }).trim();
-      return output.replace(/^codex\s*/i, "");
-    } catch {
-      return "unknown";
+function shellEscape(s) {
+  return s.replace(/'/g, "'\\''");
+}
+function buildCleanupScript(rules, workspacePath) {
+  const positive = rules.filter((r) => !r.negated);
+  const negated = rules.filter((r) => r.negated);
+  if (positive.length === 0)
+    return null;
+  const exclusions = negated.map((r) => `! -name '${shellEscape(r.pattern)}'`).join(" ");
+  const commands = [];
+  for (const rule of positive) {
+    const parts = ["find", `'${shellEscape(workspacePath)}'`];
+    if (rule.isDirectory) {
+      parts.push("-type d");
+    }
+    parts.push(`-name '${shellEscape(rule.pattern)}'`);
+    if (exclusions) {
+      parts.push(exclusions);
+    }
+    if (rule.isDirectory) {
+      parts.push("-exec rm -rf {} +");
+    } else {
+      parts.push("-delete");
     }
+    commands.push(parts.join(" "));
   }
-  async execute(options) {
-    const log = getLogger();
-    this.aborted = false;
-    const args = buildCodexArgs(options.model);
-    log.debug("Spawning codex", { args: args.join(" "), cwd: options.cwd });
-    return new Promise((resolve2) => {
-      let rawOutput = "";
-      let errorOutput = "";
-      this.process = spawn3("codex", args, {
-        cwd: options.cwd,
-        stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env }
-      });
-      let agentMessages = [];
-      const flushAgentMessages = () => {
-        if (agentMessages.length > 0) {
-          options.onOutput?.(agentMessages.join(`
-
-`));
-          agentMessages = [];
-        }
-      };
-      let lineBuffer = "";
-      this.process.stdout?.on("data", (chunk) => {
-        lineBuffer += chunk.toString();
-        const lines = lineBuffer.split(`
-`);
-        lineBuffer = lines.pop() ?? "";
-        for (const line of lines) {
-          if (!line.trim())
-            continue;
-          rawOutput += `${line}
-`;
-          log.debug("codex stdout line", { line });
-          try {
-            const event = JSON.parse(line);
-            const { type, item } = event;
-            if (type === "item.started" && item?.type === "command_execution") {
-              const cmd = (item.command ?? "").split(`
-`)[0].slice(0, 80);
-              options.onToolActivity?.(`running: ${cmd}`);
-            } else if (type === "item.completed" && item?.type === "command_execution") {
-              const code = item.exit_code;
-              options.onToolActivity?.(code === 0 ? "done" : `exit ${code}`);
-            } else if (type === "item.completed" && item?.type === "reasoning") {
-              const text = (item.text ?? "").trim().replace(/\*\*([^*]+)\*\*/g, "$1").replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
-              if (text)
-                options.onToolActivity?.(text);
-            } else if (type === "item.completed" && item?.type === "agent_message") {
-              const text = item.text ?? "";
-              if (text) {
-                agentMessages.push(text);
-                options.onToolActivity?.(text.split(`
-`)[0].slice(0, 80));
-              }
-            } else if (type === "turn.completed") {
-              flushAgentMessages();
-            }
-          } catch {
-            const newLine = `${line}
-`;
-            rawOutput += newLine;
-            options.onOutput?.(newLine);
-          }
-        }
-      });
-      this.process.stderr?.on("data", (chunk) => {
-        const text = chunk.toString();
-        errorOutput += text;
-        log.debug("codex stderr", { text: text.slice(0, 500) });
-      });
-      this.process.on("close", (code) => {
-        this.process = null;
-        flushAgentMessages();
-        if (this.aborted) {
-          resolve2({
-            success: false,
-            output: rawOutput,
-            error: "Aborted by user",
-            exitCode: code ?? 143
-          });
-          return;
-        }
-        if (code === 0) {
-          resolve2({
-            success: true,
-            output: rawOutput,
-            exitCode: 0
-          });
-        } else {
-          resolve2({
-            success: false,
-            output: rawOutput,
-            error: errorOutput || `codex exited with code ${code}`,
-            exitCode: code ?? 1
-          });
-        }
-      });
-      this.process.on("error", (err) => {
-        this.process = null;
-        resolve2({
-          success: false,
-          output: rawOutput,
-          error: `Failed to spawn codex: ${err.message}`,
-          exitCode: 1
-        });
-      });
-      if (options.signal) {
-        options.signal.addEventListener("abort", () => {
-          this.abort();
-        });
-      }
-      this.process.stdin?.write(options.prompt);
-      this.process.stdin?.end();
+  return `${commands.join(" 2>/dev/null ; ")} 2>/dev/null`;
+}
+async function enforceSandboxIgnore(sandboxName, projectRoot) {
+  const log = getLogger();
+  const ignorePath = join10(projectRoot, ".sandboxignore");
+  const rules = parseIgnoreFile(ignorePath);
+  if (rules.length === 0)
+    return;
+  const script = buildCleanupScript(rules, projectRoot);
+  if (!script)
+    return;
+  log.debug("Enforcing .sandboxignore", {
+    sandboxName,
+    ruleCount: rules.length
+  });
+  try {
+    await execAsync(`docker sandbox exec ${sandboxName} sh -c ${JSON.stringify(script)}`, { timeout: 15000 });
+    log.debug("sandbox-ignore enforcement complete", { sandboxName });
+  } catch (err) {
+    log.debug("sandbox-ignore enforcement failed (non-fatal)", {
+      sandboxName,
+      error: err instanceof Error ? err.message : String(err)
     });
   }
-  abort() {
-    if (!this.process)
-      return;
-    this.aborted = true;
-    const log = getLogger();
-    log.debug("Aborting codex process");
-    this.process.kill("SIGTERM");
-    const forceKillTimer = setTimeout(() => {
-      if (this.process) {
-        log.debug("Force killing codex process");
-        this.process.kill("SIGKILL");
-      }
-    }, 3000);
-    if (forceKillTimer.unref) {
-      forceKillTimer.unref();
-    }
-  }
 }
-var init_codex = __esm(() => {
+var execAsync;
+var init_sandbox_ignore = __esm(() => {
   init_logger();
+  execAsync = promisify(exec);
 });
 
-// src/ai/runner.ts
-async function createRunnerAsync(provider) {
-  switch (provider) {
-    case "claude":
-      return new ClaudeRunner;
-    case "codex":
-      return new CodexRunner;
-    default:
-      throw new Error(`Unknown AI provider: ${provider}`);
+// src/core/run-state.ts
+import {
+  existsSync as existsSync12,
+  mkdirSync as mkdirSync8,
+  readFileSync as readFileSync9,
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync6
+} from "node:fs";
+import { dirname as dirname3, join as join11 } from "node:path";
+function getRunStatePath(projectRoot) {
+  return join11(projectRoot, ".locus", "run-state.json");
+}
+function loadRunState(projectRoot) {
+  const path = getRunStatePath(projectRoot);
+  if (!existsSync12(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync9(path, "utf-8"));
+  } catch {
+    getLogger().warn("Corrupted run-state.json, ignoring");
+    return null;
   }
 }
-var init_runner = __esm(() => {
-  init_claude();
-  init_codex();
-});
-
-// src/ai/run-ai.ts
-var exports_run_ai = {};
-__export(exports_run_ai, {
-  runAI: () => runAI
-});
-async function runAI(options) {
-  const indicator = getStatusIndicator();
-  const renderer = options.silent ? null : new StreamRenderer;
-  let output = "";
-  let wasAborted = false;
-  let runner = null;
-  const resolvedProvider = inferProviderFromModel(options.model) || options.provider;
-  const abortController = new AbortController;
-  const cleanupInterrupt = options.noInterrupt ? () => {} : listenForInterrupt(() => {
-    if (wasAborted)
-      return;
-    wasAborted = true;
-    indicator.stop();
-    renderer?.stop();
-    process.stderr.write(`\r
-${yellow("⚡")} ${dim("Interrupting...")}\r
-`);
-    abortController.abort();
-    if (runner)
-      runner.abort();
-  }, () => {
-    indicator.stop();
+function saveRunState(projectRoot, state) {
+  const path = getRunStatePath(projectRoot);
+  const dir = dirname3(path);
+  if (!existsSync12(dir)) {
+    mkdirSync8(dir, { recursive: true });
+  }
+  writeFileSync6(path, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+}
+function clearRunState(projectRoot) {
+  const path = getRunStatePath(projectRoot);
+  if (existsSync12(path)) {
+    unlinkSync3(path);
+  }
+}
+function createSprintRunState(sprint, branch, issues) {
+  return {
+    runId: `run-${new Date().toISOString().slice(0, 19).replace(/[:.]/g, "-")}`,
+    type: "sprint",
+    sprint,
+    branch,
+    startedAt: new Date().toISOString(),
+    tasks: issues.map(({ number, order }) => ({
+      issue: number,
+      order,
+      status: "pending"
+    }))
+  };
+}
+function createParallelRunState(issueNumbers) {
+  return {
+    runId: `run-${new Date().toISOString().slice(0, 19).replace(/[:.]/g, "-")}`,
+    type: "parallel",
+    startedAt: new Date().toISOString(),
+    tasks: issueNumbers.map((issue, i) => ({
+      issue,
+      order: i + 1,
+      status: "pending"
+    }))
+  };
+}
+function markTaskInProgress(state, issueNumber) {
+  const task = state.tasks.find((t) => t.issue === issueNumber);
+  if (task) {
+    task.status = "in_progress";
+  }
+}
+function markTaskDone(state, issueNumber, prNumber) {
+  const task = state.tasks.find((t) => t.issue === issueNumber);
+  if (task) {
+    task.status = "done";
+    task.completedAt = new Date().toISOString();
+    if (prNumber)
+      task.pr = prNumber;
+  }
+}
+function markTaskFailed(state, issueNumber, error) {
+  const task = state.tasks.find((t) => t.issue === issueNumber);
+  if (task) {
+    task.status = "failed";
+    task.failedAt = new Date().toISOString();
+    task.error = error;
+  }
+}
+function getRunStats(state) {
+  const tasks = state.tasks;
+  return {
+    total: tasks.length,
+    done: tasks.filter((t) => t.status === "done").length,
+    failed: tasks.filter((t) => t.status === "failed").length,
+    pending: tasks.filter((t) => t.status === "pending").length,
+    inProgress: tasks.filter((t) => t.status === "in_progress").length
+  };
+}
+function getNextTask(state) {
+  const failed = state.tasks.find((t) => t.status === "failed");
+  if (failed)
+    return failed;
+  return state.tasks.find((t) => t.status === "pending") ?? null;
+}
+var init_run_state = __esm(() => {
+  init_logger();
+});
+
+// src/core/shutdown.ts
+import { execSync as execSync5 } from "node:child_process";
+function registerActiveSandbox(name) {
+  activeSandboxes.add(name);
+}
+function unregisterActiveSandbox(name) {
+  activeSandboxes.delete(name);
+}
+function cleanupActiveSandboxes() {
+  for (const name of activeSandboxes) {
+    try {
+      execSync5(`docker sandbox rm ${name}`, { timeout: 1e4 });
+    } catch {}
+  }
+  activeSandboxes.clear();
+}
+function registerShutdownHandlers(ctx) {
+  shutdownContext = ctx;
+  interruptCount = 0;
+  const handler = () => {
+    interruptCount++;
+    if (interruptCount >= 2) {
+      process.stderr.write(`
+Force exit.
+`);
+      process.exit(1);
+    }
+    process.stderr.write(`
+
+Interrupted. Saving state...
+`);
+    const state = shutdownContext?.getRunState?.();
+    if (state && shutdownContext) {
+      for (const task of state.tasks) {
+        if (task.status === "in_progress") {
+          task.status = "failed";
+          task.failedAt = new Date().toISOString();
+          task.error = "Interrupted by user";
+        }
+      }
+      try {
+        saveRunState(shutdownContext.projectRoot, state);
+        process.stderr.write(`State saved. Resume with: locus run --resume
+`);
+      } catch {
+        process.stderr.write(`Warning: Could not save run state.
+`);
+      }
+    }
+    cleanupActiveSandboxes();
+    shutdownContext?.onShutdown?.();
+    if (interruptTimer)
+      clearTimeout(interruptTimer);
+    interruptTimer = setTimeout(() => {
+      interruptCount = 0;
+    }, 2000);
+    setTimeout(() => {
+      process.exit(130);
+    }, 100);
+  };
+  if (!shutdownRegistered) {
+    process.on("SIGINT", handler);
+    process.on("SIGTERM", handler);
+    shutdownRegistered = true;
+  }
+  return () => {
+    process.removeListener("SIGINT", handler);
+    process.removeListener("SIGTERM", handler);
+    shutdownRegistered = false;
+    shutdownContext = null;
+    interruptCount = 0;
+    if (interruptTimer) {
+      clearTimeout(interruptTimer);
+      interruptTimer = null;
+    }
+  };
+}
+var shutdownRegistered = false, shutdownContext = null, interruptCount = 0, interruptTimer = null, activeSandboxes;
+var init_shutdown = __esm(() => {
+  init_run_state();
+  activeSandboxes = new Set;
+});
+
+// src/ai/claude-sandbox.ts
+import { execSync as execSync6, spawn as spawn3 } from "node:child_process";
+
+class SandboxedClaudeRunner {
+  name = "claude-sandboxed";
+  process = null;
+  aborted = false;
+  sandboxName = null;
+  persistent;
+  sandboxCreated = false;
+  userManaged = false;
+  constructor(persistentName, userManaged = false) {
+    if (persistentName) {
+      this.persistent = true;
+      this.sandboxName = persistentName;
+      this.userManaged = userManaged;
+      if (userManaged) {
+        this.sandboxCreated = true;
+      }
+    } else {
+      this.persistent = false;
+    }
+  }
+  async isAvailable() {
+    const { ClaudeRunner: ClaudeRunner2 } = await Promise.resolve().then(() => (init_claude(), exports_claude));
+    const delegate = new ClaudeRunner2;
+    return delegate.isAvailable();
+  }
+  async getVersion() {
+    const { ClaudeRunner: ClaudeRunner2 } = await Promise.resolve().then(() => (init_claude(), exports_claude));
+    const delegate = new ClaudeRunner2;
+    return delegate.getVersion();
+  }
+  async execute(options) {
+    const log = getLogger();
+    this.aborted = false;
+    const claudeArgs = ["-p", options.prompt, ...buildClaudeArgs(options)];
+    let dockerArgs;
+    if (this.persistent && !this.sandboxName) {
+      throw new Error("Sandbox name is required");
+    }
+    if (this.persistent && this.sandboxCreated && await this.isSandboxRunning()) {
+      const name = this.sandboxName;
+      if (!name) {
+        throw new Error("Sandbox name is required");
+      }
+      options.onStatusChange?.("Syncing sandbox...");
+      await enforceSandboxIgnore(name, options.cwd);
+      options.onStatusChange?.("Thinking...");
+      dockerArgs = [
+        "sandbox",
+        "exec",
+        "-w",
+        options.cwd,
+        name,
+        "claude",
+        ...claudeArgs
+      ];
+    } else {
+      if (!this.persistent) {
+        this.sandboxName = buildSandboxName(options);
+      }
+      const name = this.sandboxName;
+      if (!name) {
+        throw new Error("Sandbox name is required");
+      }
+      registerActiveSandbox(name);
+      options.onStatusChange?.("Syncing sandbox...");
+      dockerArgs = [
+        "sandbox",
+        "run",
+        "--name",
+        name,
+        "claude",
+        options.cwd,
+        "--",
+        ...claudeArgs
+      ];
+    }
+    log.debug("Spawning sandboxed claude", {
+      sandboxName: this.sandboxName,
+      persistent: this.persistent,
+      reusing: this.persistent && this.sandboxCreated,
+      args: dockerArgs.join(" "),
+      cwd: options.cwd
+    });
+    try {
+      return await new Promise((resolve2) => {
+        let output = "";
+        let errorOutput = "";
+        this.process = spawn3("docker", dockerArgs, {
+          stdio: ["ignore", "pipe", "pipe"],
+          env: process.env
+        });
+        if (this.persistent && !this.sandboxCreated) {
+          this.process.on("spawn", () => {
+            this.sandboxCreated = true;
+          });
+        }
+        if (options.verbose) {
+          let lineBuffer = "";
+          const seenToolIds = new Set;
+          this.process.stdout?.on("data", (chunk) => {
+            lineBuffer += chunk.toString();
+            const lines = lineBuffer.split(`
+`);
+            lineBuffer = lines.pop() ?? "";
+            for (const line of lines) {
+              if (!line.trim())
+                continue;
+              try {
+                const event = JSON.parse(line);
+                if (event.type === "assistant" && event.message?.content) {
+                  for (const item of event.message.content) {
+                    if (item.type === "tool_use" && item.id && !seenToolIds.has(item.id)) {
+                      seenToolIds.add(item.id);
+                      options.onToolActivity?.(formatToolCall2(item.name ?? "", item.input ?? {}));
+                    }
+                  }
+                } else if (event.type === "result") {
+                  const text = event.result ?? "";
+                  output = text;
+                  options.onOutput?.(text);
+                }
+              } catch {
+                const newLine = `${line}
+`;
+                output += newLine;
+                options.onOutput?.(newLine);
+              }
+            }
+          });
+        } else {
+          this.process.stdout?.on("data", (chunk) => {
+            const text = chunk.toString();
+            output += text;
+            options.onOutput?.(text);
+          });
+        }
+        this.process.stderr?.on("data", (chunk) => {
+          const text = chunk.toString();
+          errorOutput += text;
+          log.debug("sandboxed claude stderr", { text: text.slice(0, 500) });
+          options.onOutput?.(text);
+        });
+        this.process.on("close", (code) => {
+          this.process = null;
+          if (this.aborted) {
+            resolve2({
+              success: false,
+              output,
+              error: "Aborted by user",
+              exitCode: code ?? 143
+            });
+            return;
+          }
+          if (code === 0) {
+            resolve2({
+              success: true,
+              output,
+              exitCode: 0
+            });
+          } else {
+            resolve2({
+              success: false,
+              output,
+              error: errorOutput || `sandboxed claude exited with code ${code}`,
+              exitCode: code ?? 1
+            });
+          }
+        });
+        this.process.on("error", (err) => {
+          this.process = null;
+          if (this.persistent && !this.sandboxCreated) {}
+          resolve2({
+            success: false,
+            output,
+            error: `Failed to spawn docker sandbox: ${err.message}`,
+            exitCode: 1
+          });
+        });
+        if (options.signal) {
+          options.signal.addEventListener("abort", () => {
+            this.abort();
+          });
+        }
+      });
+    } finally {
+      if (!this.persistent) {
+        this.cleanupSandbox();
+      }
+    }
+  }
+  abort() {
+    this.aborted = true;
+    const log = getLogger();
+    if (this.persistent) {
+      log.debug("Aborting sandboxed claude (persistent — keeping sandbox)", {
+        sandboxName: this.sandboxName
+      });
+      if (this.process) {
+        this.process.kill("SIGTERM");
+        const timer = setTimeout(() => {
+          if (this.process) {
+            this.process.kill("SIGKILL");
+          }
+        }, 3000);
+        if (timer.unref)
+          timer.unref();
+      }
+    } else {
+      if (!this.sandboxName)
+        return;
+      log.debug("Aborting sandboxed claude (ephemeral — removing sandbox)", {
+        sandboxName: this.sandboxName
+      });
+      try {
+        execSync6(`docker sandbox rm ${this.sandboxName}`, { timeout: 60000 });
+      } catch {}
+    }
+  }
+  destroy() {
+    if (!this.sandboxName)
+      return;
+    if (this.userManaged) {
+      unregisterActiveSandbox(this.sandboxName);
+      return;
+    }
+    const log = getLogger();
+    log.debug("Destroying sandbox", { sandboxName: this.sandboxName });
+    try {
+      execSync6(`docker sandbox rm ${this.sandboxName}`, { timeout: 60000 });
+    } catch {}
+    unregisterActiveSandbox(this.sandboxName);
+    this.sandboxName = null;
+    this.sandboxCreated = false;
+  }
+  cleanupSandbox() {
+    if (!this.sandboxName)
+      return;
+    const log = getLogger();
+    log.debug("Cleaning up sandbox", { sandboxName: this.sandboxName });
+    try {
+      execSync6(`docker sandbox rm ${this.sandboxName}`, {
+        timeout: 60000
+      });
+    } catch {}
+    unregisterActiveSandbox(this.sandboxName);
+    this.sandboxName = null;
+  }
+  async isSandboxRunning() {
+    if (!this.sandboxName)
+      return false;
+    try {
+      const { promisify: promisify2 } = await import("node:util");
+      const { exec: exec2 } = await import("node:child_process");
+      const execAsync2 = promisify2(exec2);
+      const { stdout } = await execAsync2("docker sandbox ls", {
+        timeout: 5000
+      });
+      return stdout.includes(this.sandboxName);
+    } catch {
+      return false;
+    }
+  }
+  getSandboxName() {
+    return this.sandboxName;
+  }
+}
+function buildSandboxName(options) {
+  const ts = Date.now();
+  if (options.activity) {
+    const match = options.activity.match(/issue\s*#(\d+)/i);
+    if (match) {
+      return `locus-issue-${match[1]}-${ts}`;
+    }
+  }
+  const segment = options.cwd.split("/").pop() ?? "run";
+  return `locus-${segment}-${ts}`;
+}
+function buildPersistentSandboxName(cwd) {
+  const segment = cwd.split("/").pop() ?? "repl";
+  return `locus-${segment}-${Date.now()}`;
+}
+function formatToolCall2(name, input) {
+  switch (name) {
+    case "Read":
+      return `reading ${input.file_path ?? ""}`;
+    case "Write":
+      return `writing ${input.file_path ?? ""}`;
+    case "Edit":
+    case "MultiEdit":
+      return `editing ${input.file_path ?? ""}`;
+    case "Bash":
+      return `running: ${String(input.command ?? "").slice(0, 60)}`;
+    case "Glob":
+      return `glob ${input.pattern ?? ""}`;
+    case "Grep":
+      return `grep ${input.pattern ?? ""}`;
+    case "LS":
+      return `ls ${input.path ?? ""}`;
+    case "WebFetch":
+      return `fetching ${String(input.url ?? "").slice(0, 50)}`;
+    case "WebSearch":
+      return `searching: ${input.query ?? ""}`;
+    case "Task":
+      return `spawning agent`;
+    default:
+      return name;
+  }
+}
+var init_claude_sandbox = __esm(() => {
+  init_logger();
+  init_sandbox_ignore();
+  init_shutdown();
+  init_claude();
+});
+
+// src/ai/codex.ts
+import { execSync as execSync7, spawn as spawn4 } from "node:child_process";
+function buildCodexArgs(model) {
+  const args = ["exec", "--full-auto", "--skip-git-repo-check", "--json"];
+  if (model) {
+    args.push("--model", model);
+  }
+  args.push("-");
+  return args;
+}
+
+class CodexRunner {
+  name = "codex";
+  process = null;
+  aborted = false;
+  async isAvailable() {
+    try {
+      execSync7("codex --version", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getVersion() {
+    try {
+      const output = execSync7("codex --version", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      return output.replace(/^codex\s*/i, "");
+    } catch {
+      return "unknown";
+    }
+  }
+  async execute(options) {
+    const log = getLogger();
+    this.aborted = false;
+    const args = buildCodexArgs(options.model);
+    log.debug("Spawning codex", { args: args.join(" "), cwd: options.cwd });
+    return new Promise((resolve2) => {
+      let rawOutput = "";
+      let errorOutput = "";
+      this.process = spawn4("codex", args, {
+        cwd: options.cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env }
+      });
+      let agentMessages = [];
+      const flushAgentMessages = () => {
+        if (agentMessages.length > 0) {
+          options.onOutput?.(agentMessages.join(`
+
+`));
+          agentMessages = [];
+        }
+      };
+      let lineBuffer = "";
+      this.process.stdout?.on("data", (chunk) => {
+        lineBuffer += chunk.toString();
+        const lines = lineBuffer.split(`
+`);
+        lineBuffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim())
+            continue;
+          rawOutput += `${line}
+`;
+          log.debug("codex stdout line", { line });
+          try {
+            const event = JSON.parse(line);
+            const { type, item } = event;
+            if (type === "item.started" && item?.type === "command_execution") {
+              const cmd = (item.command ?? "").split(`
+`)[0].slice(0, 80);
+              options.onToolActivity?.(`running: ${cmd}`);
+            } else if (type === "item.completed" && item?.type === "command_execution") {
+              const code = item.exit_code;
+              options.onToolActivity?.(code === 0 ? "done" : `exit ${code}`);
+            } else if (type === "item.completed" && item?.type === "reasoning") {
+              const text = (item.text ?? "").trim().replace(/\*\*([^*]+)\*\*/g, "$1").replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
+              if (text)
+                options.onToolActivity?.(text);
+            } else if (type === "item.completed" && item?.type === "agent_message") {
+              const text = item.text ?? "";
+              if (text) {
+                agentMessages.push(text);
+                options.onToolActivity?.(text.split(`
+`)[0].slice(0, 80));
+              }
+            } else if (type === "turn.completed") {
+              flushAgentMessages();
+            }
+          } catch {
+            const newLine = `${line}
+`;
+            rawOutput += newLine;
+            options.onOutput?.(newLine);
+          }
+        }
+      });
+      this.process.stderr?.on("data", (chunk) => {
+        const text = chunk.toString();
+        errorOutput += text;
+        log.debug("codex stderr", { text: text.slice(0, 500) });
+      });
+      this.process.on("close", (code) => {
+        this.process = null;
+        flushAgentMessages();
+        if (this.aborted) {
+          resolve2({
+            success: false,
+            output: rawOutput,
+            error: "Aborted by user",
+            exitCode: code ?? 143
+          });
+          return;
+        }
+        if (code === 0) {
+          resolve2({
+            success: true,
+            output: rawOutput,
+            exitCode: 0
+          });
+        } else {
+          resolve2({
+            success: false,
+            output: rawOutput,
+            error: errorOutput || `codex exited with code ${code}`,
+            exitCode: code ?? 1
+          });
+        }
+      });
+      this.process.on("error", (err) => {
+        this.process = null;
+        resolve2({
+          success: false,
+          output: rawOutput,
+          error: `Failed to spawn codex: ${err.message}`,
+          exitCode: 1
+        });
+      });
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => {
+          this.abort();
+        });
+      }
+      this.process.stdin?.write(options.prompt);
+      this.process.stdin?.end();
+    });
+  }
+  abort() {
+    if (!this.process)
+      return;
+    this.aborted = true;
+    const log = getLogger();
+    log.debug("Aborting codex process");
+    this.process.kill("SIGTERM");
+    const forceKillTimer = setTimeout(() => {
+      if (this.process) {
+        log.debug("Force killing codex process");
+        this.process.kill("SIGKILL");
+      }
+    }, 3000);
+    if (forceKillTimer.unref) {
+      forceKillTimer.unref();
+    }
+  }
+}
+var init_codex = __esm(() => {
+  init_logger();
+});
+
+// src/ai/codex-sandbox.ts
+import { execSync as execSync8, spawn as spawn5 } from "node:child_process";
+
+class SandboxedCodexRunner {
+  name = "codex-sandboxed";
+  process = null;
+  aborted = false;
+  sandboxName = null;
+  persistent;
+  sandboxCreated = false;
+  userManaged = false;
+  codexInstalled = false;
+  constructor(persistentName, userManaged = false) {
+    if (persistentName) {
+      this.persistent = true;
+      this.sandboxName = persistentName;
+      this.userManaged = userManaged;
+      if (userManaged) {
+        this.sandboxCreated = true;
+      }
+    } else {
+      this.persistent = false;
+    }
+  }
+  async isAvailable() {
+    const delegate = new CodexRunner;
+    return delegate.isAvailable();
+  }
+  async getVersion() {
+    const delegate = new CodexRunner;
+    return delegate.getVersion();
+  }
+  async execute(options) {
+    const log = getLogger();
+    this.aborted = false;
+    const codexArgs = buildCodexArgs(options.model);
+    let dockerArgs;
+    if (this.persistent && !this.sandboxName) {
+      throw new Error("Sandbox name is required");
+    }
+    if (this.persistent && this.sandboxCreated && await this.isSandboxRunning()) {
+      const name = this.sandboxName;
+      if (!name) {
+        throw new Error("Sandbox name is required");
+      }
+      options.onStatusChange?.("Syncing sandbox...");
+      await enforceSandboxIgnore(name, options.cwd);
+      if (!this.codexInstalled) {
+        options.onStatusChange?.("Checking codex...");
+        await this.ensureCodexInstalled(name);
+        this.codexInstalled = true;
+      }
+      options.onStatusChange?.("Thinking...");
+      dockerArgs = [
+        "sandbox",
+        "exec",
+        "-i",
+        "-w",
+        options.cwd,
+        name,
+        "codex",
+        ...codexArgs
+      ];
+    } else {
+      if (!this.persistent) {
+        this.sandboxName = buildSandboxName2(options);
+      }
+      const name = this.sandboxName;
+      if (!name) {
+        throw new Error("Sandbox name is required");
+      }
+      registerActiveSandbox(name);
+      options.onStatusChange?.("Creating sandbox...");
+      await this.createSandboxWithClaude(name, options.cwd);
+      options.onStatusChange?.("Installing codex...");
+      await this.ensureCodexInstalled(name);
+      this.codexInstalled = true;
+      options.onStatusChange?.("Syncing sandbox...");
+      await enforceSandboxIgnore(name, options.cwd);
+      options.onStatusChange?.("Thinking...");
+      dockerArgs = [
+        "sandbox",
+        "exec",
+        "-i",
+        "-w",
+        options.cwd,
+        name,
+        "codex",
+        ...codexArgs
+      ];
+    }
+    log.debug("Spawning sandboxed codex", {
+      sandboxName: this.sandboxName,
+      persistent: this.persistent,
+      reusing: this.persistent && this.sandboxCreated,
+      args: dockerArgs.join(" "),
+      cwd: options.cwd
+    });
+    try {
+      return await new Promise((resolve2) => {
+        let rawOutput = "";
+        let errorOutput = "";
+        this.process = spawn5("docker", dockerArgs, {
+          stdio: ["pipe", "pipe", "pipe"],
+          env: process.env
+        });
+        if (this.persistent && !this.sandboxCreated) {
+          this.process.on("spawn", () => {
+            this.sandboxCreated = true;
+          });
+        }
+        let agentMessages = [];
+        const flushAgentMessages = () => {
+          if (agentMessages.length > 0) {
+            options.onOutput?.(agentMessages.join(`
+
+`));
+            agentMessages = [];
+          }
+        };
+        let lineBuffer = "";
+        this.process.stdout?.on("data", (chunk) => {
+          lineBuffer += chunk.toString();
+          const lines = lineBuffer.split(`
+`);
+          lineBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.trim())
+              continue;
+            rawOutput += `${line}
+`;
+            log.debug("sandboxed codex stdout line", { line });
+            try {
+              const event = JSON.parse(line);
+              const { type, item } = event;
+              if (type === "item.started" && item?.type === "command_execution") {
+                const cmd = (item.command ?? "").split(`
+`)[0].slice(0, 80);
+                options.onToolActivity?.(`running: ${cmd}`);
+              } else if (type === "item.completed" && item?.type === "command_execution") {
+                const code = item.exit_code;
+                options.onToolActivity?.(code === 0 ? "done" : `exit ${code}`);
+              } else if (type === "item.completed" && item?.type === "reasoning") {
+                const text = (item.text ?? "").trim().replace(/\*\*([^*]+)\*\*/g, "$1").replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
+                if (text)
+                  options.onToolActivity?.(text);
+              } else if (type === "item.completed" && item?.type === "agent_message") {
+                const text = item.text ?? "";
+                if (text) {
+                  agentMessages.push(text);
+                  options.onToolActivity?.(text.split(`
+`)[0].slice(0, 80));
+                }
+              } else if (type === "turn.completed") {
+                flushAgentMessages();
+              }
+            } catch {
+              const newLine = `${line}
+`;
+              rawOutput += newLine;
+              options.onOutput?.(newLine);
+            }
+          }
+        });
+        this.process.stderr?.on("data", (chunk) => {
+          const text = chunk.toString();
+          errorOutput += text;
+          log.debug("sandboxed codex stderr", { text: text.slice(0, 500) });
+        });
+        this.process.on("close", (code) => {
+          this.process = null;
+          flushAgentMessages();
+          if (this.aborted) {
+            resolve2({
+              success: false,
+              output: rawOutput,
+              error: "Aborted by user",
+              exitCode: code ?? 143
+            });
+            return;
+          }
+          if (code === 0) {
+            resolve2({
+              success: true,
+              output: rawOutput,
+              exitCode: 0
+            });
+          } else {
+            resolve2({
+              success: false,
+              output: rawOutput,
+              error: errorOutput || `sandboxed codex exited with code ${code}`,
+              exitCode: code ?? 1
+            });
+          }
+        });
+        this.process.on("error", (err) => {
+          this.process = null;
+          if (this.persistent && !this.sandboxCreated) {}
+          resolve2({
+            success: false,
+            output: rawOutput,
+            error: `Failed to spawn docker sandbox: ${err.message}`,
+            exitCode: 1
+          });
+        });
+        if (options.signal) {
+          options.signal.addEventListener("abort", () => {
+            this.abort();
+          });
+        }
+        this.process.stdin?.write(options.prompt);
+        this.process.stdin?.end();
+      });
+    } finally {
+      if (!this.persistent) {
+        this.cleanupSandbox();
+      }
+    }
+  }
+  abort() {
+    this.aborted = true;
+    const log = getLogger();
+    if (this.persistent) {
+      log.debug("Aborting sandboxed codex (persistent — keeping sandbox)", {
+        sandboxName: this.sandboxName
+      });
+      if (this.process) {
+        this.process.kill("SIGTERM");
+        const timer = setTimeout(() => {
+          if (this.process) {
+            this.process.kill("SIGKILL");
+          }
+        }, 3000);
+        if (timer.unref)
+          timer.unref();
+      }
+    } else {
+      if (!this.sandboxName)
+        return;
+      log.debug("Aborting sandboxed codex (ephemeral — removing sandbox)", {
+        sandboxName: this.sandboxName
+      });
+      try {
+        execSync8(`docker sandbox rm ${this.sandboxName}`, { timeout: 60000 });
+      } catch {}
+    }
+  }
+  destroy() {
+    if (!this.sandboxName)
+      return;
+    if (this.userManaged) {
+      unregisterActiveSandbox(this.sandboxName);
+      return;
+    }
+    const log = getLogger();
+    log.debug("Destroying sandbox", { sandboxName: this.sandboxName });
+    try {
+      execSync8(`docker sandbox rm ${this.sandboxName}`, { timeout: 60000 });
+    } catch {}
+    unregisterActiveSandbox(this.sandboxName);
+    this.sandboxName = null;
+    this.sandboxCreated = false;
+  }
+  cleanupSandbox() {
+    if (!this.sandboxName)
+      return;
+    const log = getLogger();
+    log.debug("Cleaning up sandbox", { sandboxName: this.sandboxName });
+    try {
+      execSync8(`docker sandbox rm ${this.sandboxName}`, {
+        timeout: 60000
+      });
+    } catch {}
+    unregisterActiveSandbox(this.sandboxName);
+    this.sandboxName = null;
+  }
+  async isSandboxRunning() {
+    if (!this.sandboxName)
+      return false;
+    try {
+      const { promisify: promisify2 } = await import("node:util");
+      const { exec: exec2 } = await import("node:child_process");
+      const execAsync2 = promisify2(exec2);
+      const { stdout } = await execAsync2("docker sandbox ls", {
+        timeout: 5000
+      });
+      return stdout.includes(this.sandboxName);
+    } catch {
+      return false;
+    }
+  }
+  async createSandboxWithClaude(name, cwd) {
+    const { promisify: promisify2 } = await import("node:util");
+    const { exec: exec2 } = await import("node:child_process");
+    const execAsync2 = promisify2(exec2);
+    try {
+      await execAsync2(`docker sandbox run --name ${name} claude ${cwd} -- --version`, { timeout: 120000 });
+    } catch {}
+  }
+  async ensureCodexInstalled(name) {
+    const { promisify: promisify2 } = await import("node:util");
+    const { exec: exec2 } = await import("node:child_process");
+    const execAsync2 = promisify2(exec2);
+    try {
+      await execAsync2(`docker sandbox exec ${name} which codex`, {
+        timeout: 5000
+      });
+    } catch {
+      await execAsync2(`docker sandbox exec ${name} npm install -g @openai/codex`, { timeout: 120000 });
+    }
+  }
+  getSandboxName() {
+    return this.sandboxName;
+  }
+}
+function buildSandboxName2(options) {
+  const ts = Date.now();
+  if (options.activity) {
+    const match = options.activity.match(/issue\s*#(\d+)/i);
+    if (match) {
+      return `locus-codex-issue-${match[1]}-${ts}`;
+    }
+  }
+  const segment = options.cwd.split("/").pop() ?? "run";
+  return `locus-codex-${segment}-${ts}`;
+}
+var init_codex_sandbox = __esm(() => {
+  init_logger();
+  init_sandbox_ignore();
+  init_shutdown();
+  init_codex();
+});
+
+// src/ai/runner.ts
+async function createRunnerAsync(provider, sandboxed) {
+  switch (provider) {
+    case "claude":
+      return sandboxed ? new SandboxedClaudeRunner : new ClaudeRunner;
+    case "codex":
+      return sandboxed ? new SandboxedCodexRunner : new CodexRunner;
+    default:
+      throw new Error(`Unknown AI provider: ${provider}`);
+  }
+}
+function createUserManagedSandboxRunner(provider, sandboxName) {
+  switch (provider) {
+    case "claude":
+      return new SandboxedClaudeRunner(sandboxName, true);
+    case "codex":
+      return new SandboxedCodexRunner(sandboxName, true);
+    default:
+      throw new Error(`Unknown AI provider: ${provider}`);
+  }
+}
+var init_runner = __esm(() => {
+  init_claude();
+  init_claude_sandbox();
+  init_codex();
+  init_codex_sandbox();
+});
+
+// src/ai/run-ai.ts
+var exports_run_ai = {};
+__export(exports_run_ai, {
+  runAI: () => runAI
+});
+function normalizeErrorMessage(error) {
+  if (!error)
+    return;
+  const trimmed = error.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function stripAnsi2(text) {
+  return text.replace(/\u001B\[[0-9;]*[A-Za-z]/g, "");
+}
+function extractErrorFromStructuredLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    const candidateValues = [
+      parsed.error,
+      parsed.message,
+      parsed.text,
+      typeof parsed.item === "object" && parsed.item ? parsed.item.error : undefined,
+      typeof parsed.item === "object" && parsed.item ? parsed.item.message : undefined,
+      typeof parsed.item === "object" && parsed.item ? parsed.item.text : undefined
+    ];
+    for (const value of candidateValues) {
+      if (typeof value !== "string")
+        continue;
+      const normalized = normalizeErrorMessage(stripAnsi2(value));
+      if (normalized)
+        return normalized;
+    }
+    return;
+  } catch {
+    return;
+  }
+}
+function extractErrorFromOutput(output) {
+  if (!output)
+    return;
+  const lines = output.split(`
+`);
+  for (let index = lines.length - 1;index >= 0; index--) {
+    const rawLine = lines[index] ?? "";
+    const line = normalizeErrorMessage(stripAnsi2(rawLine));
+    if (!line)
+      continue;
+    const structured = extractErrorFromStructuredLine(line);
+    if (structured)
+      return structured.slice(0, 500);
+    return line.slice(0, 500);
+  }
+  return;
+}
+async function runAI(options) {
+  const indicator = getStatusIndicator();
+  const renderer = options.silent ? null : new StreamRenderer;
+  let output = "";
+  let wasAborted = false;
+  let runner = null;
+  const resolvedProvider = inferProviderFromModel(options.model) || options.provider;
+  const abortController = new AbortController;
+  const cleanupInterrupt = options.noInterrupt ? () => {} : listenForInterrupt(() => {
+    if (wasAborted)
+      return;
+    wasAborted = true;
+    indicator.stop();
+    renderer?.stop();
+    process.stderr.write(`\r
+${yellow("⚡")} ${dim("Interrupting...")}\r
+`);
+    abortController.abort();
+    if (runner)
+      runner.abort();
+  }, () => {
+    indicator.stop();
     renderer?.stop();
     process.stderr.write(`\r
 ${red("✗")} ${dim("Force exit.")}\r
@@ -4207,7 +5280,13 @@ ${red("✗")} ${dim("Force exit.")}\r
     indicator.start("Thinking...", {
       activity: options.activity
     });
-    runner = await createRunnerAsync(resolvedProvider);
+    if (options.runner) {
+      runner = options.runner;
+    } else if (options.sandboxName) {
+      runner = createUserManagedSandboxRunner(resolvedProvider, options.sandboxName);
+    } else {
+      runner = await createRunnerAsync(resolvedProvider, options.sandboxed ?? true);
+    }
     const available = await runner.isAvailable();
     if (!available) {
       indicator.stop();
@@ -4227,6 +5306,7 @@ ${red("✗")} ${dim("Force exit.")}\r
       cwd: options.cwd,
       signal: abortController.signal,
       verbose: options.verbose,
+      activity: options.activity,
       onOutput: (chunk) => {
         if (wasAborted)
           return;
@@ -4237,6 +5317,9 @@ ${red("✗")} ${dim("Force exit.")}\r
         renderer?.push(chunk);
         output += chunk;
       },
+      onStatusChange: (message) => {
+        indicator.setMessage(message);
+      },
       onToolActivity: (() => {
         let lastActivityTime = 0;
         return (summary) => {
@@ -4261,20 +5344,25 @@ ${red("✗")} ${dim("Force exit.")}\r
         exitCode: result.exitCode
       };
     }
+    const normalizedRunnerError = normalizeErrorMessage(result.error);
+    const extractedOutputError = extractErrorFromOutput(result.output);
+    const fallbackError = `${runner.name} failed with exit code ${result.exitCode}.`;
     return {
       success: result.success,
       output,
-      error: result.error,
+      error: result.success ? undefined : normalizedRunnerError ?? extractedOutputError ?? fallbackError,
       interrupted: false,
       exitCode: result.exitCode
     };
   } catch (e) {
     indicator.stop();
     renderer?.stop();
+    const normalizedCaughtError = normalizeErrorMessage(e instanceof Error ? e.message : String(e));
+    const fallbackError = `${resolvedProvider} runner failed unexpectedly.`;
     return {
       success: false,
       output,
-      error: e instanceof Error ? e.message : String(e),
+      error: normalizedCaughtError ?? fallbackError,
       interrupted: wasAborted,
       exitCode: 1
     };
@@ -4517,7 +5605,9 @@ async function issueCreate(projectRoot, parsed) {
     model: config.ai.model,
     cwd: projectRoot,
     silent: true,
-    activity: "generating issue"
+    activity: "generating issue",
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name
   });
   if (!aiResult.success && !aiResult.interrupted) {
     process.stderr.write(`${red("✗")} Failed to generate issue: ${aiResult.error}
@@ -5675,9 +6765,9 @@ var init_sprint = __esm(() => {
 });
 
 // src/core/prompt-builder.ts
-import { execSync as execSync6 } from "node:child_process";
-import { existsSync as existsSync11, readdirSync as readdirSync3, readFileSync as readFileSync8 } from "node:fs";
-import { join as join10 } from "node:path";
+import { execSync as execSync9 } from "node:child_process";
+import { existsSync as existsSync13, readdirSync as readdirSync3, readFileSync as readFileSync10 } from "node:fs";
+import { join as join12 } from "node:path";
 function buildExecutionPrompt(ctx) {
   const sections = [];
   sections.push(buildSystemContext(ctx.projectRoot));
@@ -5707,13 +6797,13 @@ function buildFeedbackPrompt(ctx) {
 }
 function buildReplPrompt(userMessage, projectRoot, _config, previousMessages) {
   const sections = [];
-  const locusmd = readFileSafe(join10(projectRoot, "LOCUS.md"));
+  const locusmd = readFileSafe(join12(projectRoot, "LOCUS.md"));
   if (locusmd) {
     sections.push(`# Project Instructions
 
 ${locusmd}`);
   }
-  const learnings = readFileSafe(join10(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join12(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     sections.push(`# Past Learnings
 
@@ -5739,24 +6829,24 @@ ${userMessage}`);
 }
 function buildSystemContext(projectRoot) {
   const parts = ["# System Context"];
-  const locusmd = readFileSafe(join10(projectRoot, "LOCUS.md"));
+  const locusmd = readFileSafe(join12(projectRoot, "LOCUS.md"));
   if (locusmd) {
     parts.push(`## Project Instructions (LOCUS.md)
 
 ${locusmd}`);
   }
-  const learnings = readFileSafe(join10(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join12(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     parts.push(`## Past Learnings
 
 ${learnings}`);
   }
-  const discussionsDir = join10(projectRoot, ".locus", "discussions");
-  if (existsSync11(discussionsDir)) {
+  const discussionsDir = join12(projectRoot, ".locus", "discussions");
+  if (existsSync13(discussionsDir)) {
     try {
       const files = readdirSync3(discussionsDir).filter((f) => f.endsWith(".md")).slice(0, 3);
       for (const file of files) {
-        const content = readFileSafe(join10(discussionsDir, file));
+        const content = readFileSafe(join12(discussionsDir, file));
         if (content) {
           parts.push(`## Discussion: ${file.replace(".md", "")}
 
@@ -5819,7 +6909,7 @@ ${diffSummary}
 function buildRepoContext(projectRoot) {
   const parts = ["# Repository Context"];
   try {
-    const tree = execSync6("find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.locus/*' -not -path '*/dist/*' -not -path '*/build/*' | head -80", { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const tree = execSync9("find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.locus/*' -not -path '*/dist/*' -not -path '*/build/*' | head -80", { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     if (tree) {
       parts.push(`## File Tree
 
@@ -5829,7 +6919,7 @@ ${tree}
     }
   } catch {}
   try {
-    const gitLog = execSync6("git log --oneline -10", {
+    const gitLog = execSync9("git log --oneline -10", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -5843,7 +6933,7 @@ ${gitLog}
     }
   } catch {}
   try {
-    const branch = execSync6("git rev-parse --abbrev-ref HEAD", {
+    const branch = execSync9("git rev-parse --abbrev-ref HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -5857,7 +6947,7 @@ ${gitLog}
 function buildExecutionRules(config) {
   return `# Execution Rules
 
-1. **Commit format:** Use conventional commits: \`feat: <title> (#<issue>)\`, \`fix: ...\`, \`chore: ...\`. Always include a blank line followed by \`Co-Authored-By: LocusAgent <agent@locusai.team>\` as a trailer in every commit message.
+1. **Commit format:** Use conventional commits: \`feat: <title> (#<issue>)\`, \`fix: ...\`, \`chore: ...\`. Every commit message MUST be multi-line: the first line is the title, then a blank line, then \`Co-Authored-By: LocusAgent <agent@locusai.team>\` as a Git trailer. Use \`git commit -m "<title>" -m "Co-Authored-By: LocusAgent <agent@locusai.team>"\` (two separate -m flags) to ensure the trailer is on its own line.
 2. **Code quality:** Follow existing code style. Run linters/formatters if available.
 3. **Testing:** If test files exist for modified code, update them accordingly.
 4. **Do NOT:**
@@ -5902,9 +6992,9 @@ function buildFeedbackInstructions() {
 }
 function readFileSafe(path) {
   try {
-    if (!existsSync11(path))
+    if (!existsSync13(path))
       return null;
-    return readFileSync8(path, "utf-8");
+    return readFileSync10(path, "utf-8");
   } catch {
     return null;
   }
@@ -6096,7 +7186,7 @@ var init_diff_renderer = __esm(() => {
 });
 
 // src/repl/commands.ts
-import { execSync as execSync7 } from "node:child_process";
+import { execSync as execSync10 } from "node:child_process";
 function getSlashCommands() {
   return [
     {
@@ -6288,7 +7378,7 @@ function cmdModel(args, ctx) {
 }
 function cmdDiff(_args, ctx) {
   try {
-    const diff = execSync7("git diff", {
+    const diff = execSync10("git diff", {
       cwd: ctx.projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -6324,7 +7414,7 @@ function cmdDiff(_args, ctx) {
 }
 function cmdUndo(_args, ctx) {
   try {
-    const status = execSync7("git status --porcelain", {
+    const status = execSync10("git status --porcelain", {
       cwd: ctx.projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -6334,7 +7424,7 @@ function cmdUndo(_args, ctx) {
 `);
       return;
     }
-    execSync7("git checkout .", {
+    execSync10("git checkout .", {
       cwd: ctx.projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -6368,7 +7458,7 @@ var init_commands = __esm(() => {
 
 // src/repl/completions.ts
 import { readdirSync as readdirSync4 } from "node:fs";
-import { basename as basename2, dirname as dirname3, join as join11 } from "node:path";
+import { basename as basename2, dirname as dirname4, join as join13 } from "node:path";
 
 class SlashCommandCompletion {
   commands;
@@ -6423,7 +7513,7 @@ class FilePathCompletion {
   }
   findMatches(partial) {
     try {
-      const dir = partial.includes("/") ? join11(this.projectRoot, dirname3(partial)) : this.projectRoot;
+      const dir = partial.includes("/") ? join13(this.projectRoot, dirname4(partial)) : this.projectRoot;
       const prefix = basename2(partial);
       const entries = readdirSync4(dir, { withFileTypes: true });
       return entries.filter((e) => {
@@ -6434,7 +7524,7 @@ class FilePathCompletion {
         return e.name.startsWith(prefix);
       }).map((e) => {
         const name = e.isDirectory() ? `${e.name}/` : e.name;
-        return partial.includes("/") ? `${dirname3(partial)}/${name}` : name;
+        return partial.includes("/") ? `${dirname4(partial)}/${name}` : name;
       }).slice(0, 20);
     } catch {
       return [];
@@ -6459,14 +7549,14 @@ class CombinedCompletion {
 var init_completions = () => {};
 
 // src/repl/input-history.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync8, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join12 } from "node:path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
+import { dirname as dirname5, join as join14 } from "node:path";
 
 class InputHistory {
   entries = [];
   filePath;
   constructor(projectRoot) {
-    this.filePath = join12(projectRoot, ".locus", "sessions", ".input-history");
+    this.filePath = join14(projectRoot, ".locus", "sessions", ".input-history");
     this.load();
   }
   add(text) {
@@ -6505,22 +7595,22 @@ class InputHistory {
   }
   load() {
     try {
-      if (!existsSync12(this.filePath))
+      if (!existsSync14(this.filePath))
         return;
-      const content = readFileSync9(this.filePath, "utf-8");
+      const content = readFileSync11(this.filePath, "utf-8");
       this.entries = content.split(`
 `).map((line) => this.unescape(line)).filter(Boolean);
     } catch {}
   }
   save() {
     try {
-      const dir = dirname4(this.filePath);
-      if (!existsSync12(dir)) {
-        mkdirSync8(dir, { recursive: true });
+      const dir = dirname5(this.filePath);
+      if (!existsSync14(dir)) {
+        mkdirSync9(dir, { recursive: true });
       }
       const content = this.entries.map((e) => this.escape(e)).join(`
 `);
-      writeFileSync6(this.filePath, content, "utf-8");
+      writeFileSync7(this.filePath, content, "utf-8");
     } catch {}
   }
   escape(text) {
@@ -6545,23 +7635,22 @@ var init_model_config = __esm(() => {
 });
 
 // src/repl/session-manager.ts
-import { randomBytes } from "node:crypto";
 import {
-  existsSync as existsSync13,
-  mkdirSync as mkdirSync9,
+  existsSync as existsSync15,
+  mkdirSync as mkdirSync10,
   readdirSync as readdirSync5,
-  readFileSync as readFileSync10,
-  unlinkSync as unlinkSync3,
-  writeFileSync as writeFileSync7
+  readFileSync as readFileSync12,
+  unlinkSync as unlinkSync4,
+  writeFileSync as writeFileSync8
 } from "node:fs";
-import { basename as basename3, join as join13 } from "node:path";
+import { basename as basename3, join as join15 } from "node:path";
 
 class SessionManager {
   sessionsDir;
   constructor(projectRoot) {
-    this.sessionsDir = join13(projectRoot, ".locus", "sessions");
-    if (!existsSync13(this.sessionsDir)) {
-      mkdirSync9(this.sessionsDir, { recursive: true });
+    this.sessionsDir = join15(projectRoot, ".locus", "sessions");
+    if (!existsSync15(this.sessionsDir)) {
+      mkdirSync10(this.sessionsDir, { recursive: true });
     }
   }
   create(options) {
@@ -6586,14 +7675,14 @@ class SessionManager {
   }
   isPersisted(sessionOrId) {
     const sessionId = typeof sessionOrId === "string" ? sessionOrId : sessionOrId.id;
-    return existsSync13(this.getSessionPath(sessionId));
+    return existsSync15(this.getSessionPath(sessionId));
   }
   load(idOrPrefix) {
     const files = this.listSessionFiles();
     const exactPath = this.getSessionPath(idOrPrefix);
-    if (existsSync13(exactPath)) {
+    if (existsSync15(exactPath)) {
       try {
-        return JSON.parse(readFileSync10(exactPath, "utf-8"));
+        return JSON.parse(readFileSync12(exactPath, "utf-8"));
       } catch {
         return null;
       }
@@ -6601,7 +7690,7 @@ class SessionManager {
     const matches = files.filter((f) => basename3(f, ".json").startsWith(idOrPrefix));
     if (matches.length === 1) {
       try {
-        return JSON.parse(readFileSync10(matches[0], "utf-8"));
+        return JSON.parse(readFileSync12(matches[0], "utf-8"));
       } catch {
         return null;
       }
@@ -6614,7 +7703,7 @@ class SessionManager {
   save(session) {
     session.updated = new Date().toISOString();
     const path = this.getSessionPath(session.id);
-    writeFileSync7(path, `${JSON.stringify(session, null, 2)}
+    writeFileSync8(path, `${JSON.stringify(session, null, 2)}
 `, "utf-8");
   }
   addMessage(session, message) {
@@ -6626,7 +7715,7 @@ class SessionManager {
     const sessions = [];
     for (const file of files) {
       try {
-        const session = JSON.parse(readFileSync10(file, "utf-8"));
+        const session = JSON.parse(readFileSync12(file, "utf-8"));
         sessions.push({
           id: session.id,
           created: session.created,
@@ -6641,8 +7730,8 @@ class SessionManager {
   }
   delete(sessionId) {
     const path = this.getSessionPath(sessionId);
-    if (existsSync13(path)) {
-      unlinkSync3(path);
+    if (existsSync15(path)) {
+      unlinkSync4(path);
       return true;
     }
     return false;
@@ -6653,7 +7742,7 @@ class SessionManager {
     let pruned = 0;
     const withStats = files.map((f) => {
       try {
-        const session = JSON.parse(readFileSync10(f, "utf-8"));
+        const session = JSON.parse(readFileSync12(f, "utf-8"));
         return { path: f, updated: new Date(session.updated).getTime() };
       } catch {
         return { path: f, updated: 0 };
@@ -6663,7 +7752,7 @@ class SessionManager {
     for (const entry of withStats) {
       if (now - entry.updated > SESSION_MAX_AGE_MS) {
         try {
-          unlinkSync3(entry.path);
+          unlinkSync4(entry.path);
           pruned++;
         } catch {}
       }
@@ -6671,10 +7760,10 @@ class SessionManager {
     const remaining = withStats.length - pruned;
     if (remaining > MAX_SESSIONS) {
       const toRemove = remaining - MAX_SESSIONS;
-      const alive = withStats.filter((e) => existsSync13(e.path));
+      const alive = withStats.filter((e) => existsSync15(e.path));
       for (let i = 0;i < toRemove && i < alive.length; i++) {
         try {
-          unlinkSync3(alive[i].path);
+          unlinkSync4(alive[i].path);
           pruned++;
         } catch {}
       }
@@ -6686,16 +7775,16 @@ class SessionManager {
   }
   listSessionFiles() {
     try {
-      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join13(this.sessionsDir, f));
+      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join15(this.sessionsDir, f));
     } catch {
       return [];
     }
   }
   generateId() {
-    return randomBytes(6).toString("hex");
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
   getSessionPath(sessionId) {
-    return join13(this.sessionsDir, `${sessionId}.json`);
+    return join15(this.sessionsDir, `${sessionId}.json`);
   }
 }
 var MAX_SESSIONS = 50, SESSION_MAX_AGE_MS;
@@ -6705,7 +7794,7 @@ var init_session_manager = __esm(() => {
 });
 
 // src/repl/repl.ts
-import { execSync as execSync8 } from "node:child_process";
+import { execSync as execSync11 } from "node:child_process";
 async function startRepl(options) {
   const { projectRoot, config } = options;
   const sessionManager = new SessionManager(projectRoot);
@@ -6723,7 +7812,7 @@ async function startRepl(options) {
   } else {
     let branch = "main";
     try {
-      branch = execSync8("git rev-parse --abbrev-ref HEAD", {
+      branch = execSync11("git rev-parse --abbrev-ref HEAD", {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -6764,6 +7853,18 @@ async function executeOneShotPrompt(prompt, session, sessionManager, options) {
 }
 async function runInteractiveRepl(session, sessionManager, options) {
   const { projectRoot, config } = options;
+  let sandboxRunner = null;
+  if (config.sandbox.enabled && config.sandbox.name) {
+    const provider = inferProviderFromModel(config.ai.model) || config.ai.provider;
+    sandboxRunner = createUserManagedSandboxRunner(provider, config.sandbox.name);
+    process.stderr.write(`${dim("Using sandbox")} ${dim(config.sandbox.name)}
+`);
+  } else if (config.sandbox.enabled) {
+    const sandboxName = buildPersistentSandboxName(projectRoot);
+    sandboxRunner = new SandboxedClaudeRunner(sandboxName);
+    process.stderr.write(`${dim("Sandbox mode: prompts will share sandbox")} ${dim(sandboxName)}
+`);
+  }
   const history = new InputHistory(projectRoot);
   const completion = new CombinedCompletion([
     new SlashCommandCompletion(getAllCommandNames()),
@@ -6793,8 +7894,14 @@ async function runInteractiveRepl(session, sessionManager, options) {
       session.metadata.model = model;
       const inferredProvider = inferProviderFromModel(model);
       if (inferredProvider) {
+        const providerChanged = inferredProvider !== currentProvider;
         currentProvider = inferredProvider;
         session.metadata.provider = inferredProvider;
+        if (providerChanged && config.sandbox.enabled && config.sandbox.name) {
+          sandboxRunner = createUserManagedSandboxRunner(inferredProvider, config.sandbox.name);
+          process.stderr.write(`${dim("Switched sandbox agent to")} ${dim(inferredProvider)}
+`);
+        }
       }
       persistReplModelSelection(projectRoot, config, model);
       sessionManager.save(session);
@@ -6839,7 +7946,7 @@ async function runInteractiveRepl(session, sessionManager, options) {
               ...config,
               ai: { provider: currentProvider, model: currentModel }
             }
-          }, verbose);
+          }, verbose, sandboxRunner ?? undefined);
           sessionManager.addMessage(session, {
             role: "assistant",
             content: response,
@@ -6864,6 +7971,10 @@ ${red("✗")} ${msg}
         break;
     }
   }
+  if (sandboxRunner && "destroy" in sandboxRunner) {
+    const runner = sandboxRunner;
+    runner.destroy();
+  }
   const shouldPersistOnExit = session.messages.length > 0 || sessionManager.isPersisted(session);
   if (shouldPersistOnExit) {
     sessionManager.save(session);
@@ -6879,14 +7990,17 @@ ${red("✗")} ${msg}
   process.stdin.pause();
   process.exit(0);
 }
-async function executeAITurn(prompt, session, options, verbose = false) {
+async function executeAITurn(prompt, session, options, verbose = false, runner) {
   const { config, projectRoot } = options;
   const aiResult = await runAI({
     prompt,
     provider: config.ai.provider,
     model: config.ai.model,
     cwd: projectRoot,
-    verbose
+    verbose,
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name,
+    runner
   });
   if (aiResult.interrupted) {
     if (aiResult.output) {
@@ -6916,7 +8030,9 @@ function printWelcome(session) {
 `);
 }
 var init_repl = __esm(() => {
+  init_claude_sandbox();
   init_run_ai();
+  init_runner();
   init_ai_models();
   init_prompt_builder();
   init_terminal();
@@ -7059,7 +8175,7 @@ async function handleJsonStream(projectRoot, config, args, sessionId) {
   stream.emitStatus("thinking");
   try {
     const fullPrompt = buildReplPrompt(prompt, projectRoot, config);
-    const runner = await createRunnerAsync(config.ai.provider);
+    const runner = config.sandbox.name ? createUserManagedSandboxRunner(config.ai.provider, config.sandbox.name) : await createRunnerAsync(config.ai.provider, config.sandbox.enabled);
     const available = await runner.isAvailable();
     if (!available) {
       stream.emitError(`${config.ai.provider} CLI not available`, false);
@@ -7107,7 +8223,7 @@ var init_exec = __esm(() => {
 });
 
 // src/core/agent.ts
-import { execSync as execSync9 } from "node:child_process";
+import { execSync as execSync12 } from "node:child_process";
 async function executeIssue(projectRoot, options) {
   const log = getLogger();
   const timer = createTimer();
@@ -7136,7 +8252,7 @@ ${cyan("●")} ${bold(`#${issueNumber}`)} ${issue.title}
   }
   let issueComments = [];
   try {
-    const commentsRaw = execSync9(`gh issue view ${issueNumber} --json comments --jq '.comments[].body'`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const commentsRaw = execSync12(`gh issue view ${issueNumber} --json comments --jq '.comments[].body'`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     if (commentsRaw) {
       issueComments = commentsRaw.split(`
 `).filter(Boolean);
@@ -7171,7 +8287,9 @@ ${yellow("⚠")} ${bold("Dry run")} — would execute with:
     provider,
     model,
     cwd: options.worktreePath ?? projectRoot,
-    activity: `issue #${issueNumber}`
+    activity: `issue #${issueNumber}`,
+    sandboxed: options.sandboxed,
+    sandboxName: options.sandboxName
   });
   const output = aiResult.output;
   if (aiResult.interrupted) {
@@ -7275,7 +8393,9 @@ ${c.body}`),
     provider: config.ai.provider,
     model: config.ai.model,
     cwd: projectRoot,
-    activity: `iterating on PR #${prNumber}`
+    activity: `iterating on PR #${prNumber}`,
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name
   });
   if (aiResult.interrupted) {
     process.stderr.write(`
@@ -7296,12 +8416,12 @@ ${aiResult.success ? green("✓") : red("✗")} Iteration ${aiResult.success ? "
 }
 async function createIssuePR(projectRoot, config, issue) {
   try {
-    const currentBranch = execSync9("git rev-parse --abbrev-ref HEAD", {
+    const currentBranch = execSync12("git rev-parse --abbrev-ref HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    const diff = execSync9(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
+    const diff = execSync12(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -7310,7 +8430,7 @@ async function createIssuePR(projectRoot, config, issue) {
       getLogger().verbose("No changes to create PR for");
       return;
     }
-    execSync9(`git push -u origin ${currentBranch}`, {
+    execSync12(`git push -u origin ${currentBranch}`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -7356,9 +8476,9 @@ var init_agent = __esm(() => {
 });
 
 // src/core/conflict.ts
-import { execSync as execSync10 } from "node:child_process";
+import { execSync as execSync13 } from "node:child_process";
 function git2(args, cwd) {
-  return execSync10(`git ${args}`, {
+  return execSync13(`git ${args}`, {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -7483,185 +8603,144 @@ var init_conflict = __esm(() => {
   init_logger();
 });
 
-// src/core/run-state.ts
-import {
-  existsSync as existsSync14,
-  mkdirSync as mkdirSync10,
-  readFileSync as readFileSync11,
-  unlinkSync as unlinkSync4,
-  writeFileSync as writeFileSync8
-} from "node:fs";
-import { dirname as dirname5, join as join14 } from "node:path";
-function getRunStatePath(projectRoot) {
-  return join14(projectRoot, ".locus", "run-state.json");
-}
-function loadRunState(projectRoot) {
-  const path = getRunStatePath(projectRoot);
-  if (!existsSync14(path))
-    return null;
-  try {
-    return JSON.parse(readFileSync11(path, "utf-8"));
-  } catch {
-    getLogger().warn("Corrupted run-state.json, ignoring");
-    return null;
-  }
-}
-function saveRunState(projectRoot, state) {
-  const path = getRunStatePath(projectRoot);
-  const dir = dirname5(path);
-  if (!existsSync14(dir)) {
-    mkdirSync10(dir, { recursive: true });
-  }
-  writeFileSync8(path, `${JSON.stringify(state, null, 2)}
-`, "utf-8");
-}
-function clearRunState(projectRoot) {
-  const path = getRunStatePath(projectRoot);
-  if (existsSync14(path)) {
-    unlinkSync4(path);
-  }
-}
-function createSprintRunState(sprint, branch, issues) {
-  return {
-    runId: `run-${new Date().toISOString().slice(0, 19).replace(/[:.]/g, "-")}`,
-    type: "sprint",
-    sprint,
-    branch,
-    startedAt: new Date().toISOString(),
-    tasks: issues.map(({ number, order }) => ({
-      issue: number,
-      order,
-      status: "pending"
-    }))
-  };
-}
-function createParallelRunState(issueNumbers) {
-  return {
-    runId: `run-${new Date().toISOString().slice(0, 19).replace(/[:.]/g, "-")}`,
-    type: "parallel",
-    startedAt: new Date().toISOString(),
-    tasks: issueNumbers.map((issue, i) => ({
-      issue,
-      order: i + 1,
-      status: "pending"
-    }))
-  };
-}
-function markTaskInProgress(state, issueNumber) {
-  const task = state.tasks.find((t) => t.issue === issueNumber);
-  if (task) {
-    task.status = "in_progress";
-  }
-}
-function markTaskDone(state, issueNumber, prNumber) {
-  const task = state.tasks.find((t) => t.issue === issueNumber);
-  if (task) {
-    task.status = "done";
-    task.completedAt = new Date().toISOString();
-    if (prNumber)
-      task.pr = prNumber;
-  }
-}
-function markTaskFailed(state, issueNumber, error) {
-  const task = state.tasks.find((t) => t.issue === issueNumber);
-  if (task) {
-    task.status = "failed";
-    task.failedAt = new Date().toISOString();
-    task.error = error;
+// src/core/sandbox.ts
+import { execFile } from "node:child_process";
+async function detectSandboxSupport() {
+  if (cachedStatus)
+    return cachedStatus;
+  const log = getLogger();
+  log.debug("Detecting Docker sandbox support...");
+  const status = await runDetection();
+  cachedStatus = status;
+  if (status.available) {
+    log.verbose("Docker sandbox support detected");
+  } else {
+    log.verbose(`Docker sandbox not available: ${status.reason}`);
   }
+  return status;
 }
-function getRunStats(state) {
-  const tasks = state.tasks;
-  return {
-    total: tasks.length,
-    done: tasks.filter((t) => t.status === "done").length,
-    failed: tasks.filter((t) => t.status === "failed").length,
-    pending: tasks.filter((t) => t.status === "pending").length,
-    inProgress: tasks.filter((t) => t.status === "in_progress").length
-  };
-}
-function getNextTask(state) {
-  const failed = state.tasks.find((t) => t.status === "failed");
-  if (failed)
-    return failed;
-  return state.tasks.find((t) => t.status === "pending") ?? null;
-}
-var init_run_state = __esm(() => {
-  init_logger();
-});
-
-// src/core/shutdown.ts
-function registerShutdownHandlers(ctx) {
-  shutdownContext = ctx;
-  interruptCount = 0;
-  const handler = () => {
-    interruptCount++;
-    if (interruptCount >= 2) {
-      process.stderr.write(`
-Force exit.
-`);
-      process.exit(1);
-    }
-    process.stderr.write(`
-
-Interrupted. Saving state...
+function runDetection() {
+  return new Promise((resolve2) => {
+    let settled = false;
+    const child = execFile("docker", ["sandbox", "ls"], { timeout: TIMEOUT_MS }, (error, _stdout, stderr) => {
+      if (settled)
+        return;
+      settled = true;
+      if (!error) {
+        resolve2({ available: true });
+        return;
+      }
+      const code = error.code;
+      if (code === "ENOENT") {
+        resolve2({ available: false, reason: "Docker is not installed" });
+        return;
+      }
+      if (error.killed) {
+        resolve2({ available: false, reason: "Docker is not responding" });
+        return;
+      }
+      const stderrStr = (stderr ?? "").toLowerCase();
+      if (stderrStr.includes("unknown") || stderrStr.includes("not a docker command") || stderrStr.includes("is not a docker command")) {
+        resolve2({
+          available: false,
+          reason: "Docker Desktop 4.58+ with sandbox support required"
+        });
+        return;
+      }
+      resolve2({
+        available: false,
+        reason: "Docker Desktop 4.58+ with sandbox support required"
+      });
+    });
+    child.on?.("error", (err) => {
+      if (settled)
+        return;
+      settled = true;
+      if (err.code === "ENOENT") {
+        resolve2({ available: false, reason: "Docker is not installed" });
+      } else {
+        resolve2({
+          available: false,
+          reason: "Docker Desktop 4.58+ with sandbox support required"
+        });
+      }
+    });
+  });
+}
+async function cleanupStaleSandboxes() {
+  const log = getLogger();
+  try {
+    const { stdout } = await execFileAsync("docker", ["sandbox", "ls"], {
+      timeout: TIMEOUT_MS
+    });
+    const lines = stdout.trim().split(`
 `);
-    const state = shutdownContext?.getRunState?.();
-    if (state && shutdownContext) {
-      for (const task of state.tasks) {
-        if (task.status === "in_progress") {
-          task.status = "failed";
-          task.failedAt = new Date().toISOString();
-          task.error = "Interrupted by user";
-        }
+    if (lines.length <= 1)
+      return 0;
+    const staleNames = [];
+    for (const line of lines.slice(1)) {
+      const name = line.trim().split(/\s+/)[0];
+      if (name?.startsWith("locus-")) {
+        staleNames.push(name);
       }
+    }
+    if (staleNames.length === 0)
+      return 0;
+    log.verbose(`Found ${staleNames.length} stale sandbox(es) to clean up`);
+    let cleaned = 0;
+    for (const name of staleNames) {
       try {
-        saveRunState(shutdownContext.projectRoot, state);
-        process.stderr.write(`State saved. Resume with: locus run --resume
-`);
+        await execFileAsync("docker", ["sandbox", "rm", name], {
+          timeout: 1e4
+        });
+        log.debug(`Removed stale sandbox: ${name}`);
+        cleaned++;
       } catch {
-        process.stderr.write(`Warning: Could not save run state.
-`);
+        log.debug(`Failed to remove stale sandbox: ${name}`);
       }
     }
-    shutdownContext?.onShutdown?.();
-    if (interruptTimer)
-      clearTimeout(interruptTimer);
-    interruptTimer = setTimeout(() => {
-      interruptCount = 0;
-    }, 2000);
-    setTimeout(() => {
-      process.exit(130);
-    }, 100);
-  };
-  if (!shutdownRegistered) {
-    process.on("SIGINT", handler);
-    process.on("SIGTERM", handler);
-    shutdownRegistered = true;
+    return cleaned;
+  } catch {
+    return 0;
   }
-  return () => {
-    process.removeListener("SIGINT", handler);
-    process.removeListener("SIGTERM", handler);
-    shutdownRegistered = false;
-    shutdownContext = null;
-    interruptCount = 0;
-    if (interruptTimer) {
-      clearTimeout(interruptTimer);
-      interruptTimer = null;
+}
+function execFileAsync(file, args, options) {
+  return new Promise((resolve2, reject) => {
+    execFile(file, args, options, (error, stdout, stderr) => {
+      if (error)
+        reject(error);
+      else
+        resolve2({ stdout: stdout ?? "", stderr: stderr ?? "" });
+    });
+  });
+}
+function resolveSandboxMode(config, flags) {
+  if (flags.noSandbox) {
+    return "disabled";
+  }
+  if (flags.sandbox !== undefined) {
+    if (flags.sandbox === "require") {
+      return "required";
     }
-  };
+    throw new Error(`Invalid --sandbox value: "${flags.sandbox}". Valid values: require`);
+  }
+  if (!config.enabled) {
+    return "disabled";
+  }
+  return "auto";
 }
-var shutdownRegistered = false, shutdownContext = null, interruptCount = 0, interruptTimer = null;
-var init_shutdown = __esm(() => {
-  init_run_state();
+var TIMEOUT_MS = 5000, cachedStatus = null;
+var init_sandbox = __esm(() => {
+  init_terminal();
+  init_logger();
 });
 
 // src/core/worktree.ts
-import { execSync as execSync11 } from "node:child_process";
-import { existsSync as existsSync15, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
-import { join as join15 } from "node:path";
+import { execSync as execSync14 } from "node:child_process";
+import { existsSync as existsSync16, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
+import { join as join16 } from "node:path";
 function git3(args, cwd) {
-  return execSync11(`git ${args}`, {
+  return execSync14(`git ${args}`, {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -7675,10 +8754,10 @@ function gitSafe2(args, cwd) {
   }
 }
 function getWorktreeDir(projectRoot) {
-  return join15(projectRoot, ".locus", "worktrees");
+  return join16(projectRoot, ".locus", "worktrees");
 }
 function getWorktreePath(projectRoot, issueNumber) {
-  return join15(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
+  return join16(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
 }
 function generateBranchName(issueNumber) {
   const randomSuffix = Math.random().toString(36).slice(2, 8);
@@ -7686,7 +8765,7 @@ function generateBranchName(issueNumber) {
 }
 function getWorktreeBranch(worktreePath) {
   try {
-    return execSync11("git branch --show-current", {
+    return execSync14("git branch --show-current", {
       cwd: worktreePath,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -7698,7 +8777,7 @@ function getWorktreeBranch(worktreePath) {
 function createWorktree(projectRoot, issueNumber, baseBranch) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (existsSync15(worktreePath)) {
+  if (existsSync16(worktreePath)) {
     log.verbose(`Worktree already exists for issue #${issueNumber}`);
     const existingBranch = getWorktreeBranch(worktreePath) ?? `locus/issue-${issueNumber}`;
     return {
@@ -7725,7 +8804,7 @@ function createWorktree(projectRoot, issueNumber, baseBranch) {
 function removeWorktree(projectRoot, issueNumber) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (!existsSync15(worktreePath)) {
+  if (!existsSync16(worktreePath)) {
     log.verbose(`Worktree for issue #${issueNumber} does not exist`);
     return;
   }
@@ -7744,7 +8823,7 @@ function removeWorktree(projectRoot, issueNumber) {
 function listWorktrees(projectRoot) {
   const log = getLogger();
   const worktreeDir = getWorktreeDir(projectRoot);
-  if (!existsSync15(worktreeDir)) {
+  if (!existsSync16(worktreeDir)) {
     return [];
   }
   const entries = readdirSync6(worktreeDir).filter((entry) => entry.startsWith("issue-"));
@@ -7764,7 +8843,7 @@ function listWorktrees(projectRoot) {
     if (!match)
       continue;
     const issueNumber = Number.parseInt(match[1], 10);
-    const path = join15(worktreeDir, entry);
+    const path = join16(worktreeDir, entry);
     const branch = getWorktreeBranch(path) ?? `locus/issue-${issueNumber}`;
     let resolvedPath;
     try {
@@ -7811,8 +8890,44 @@ var exports_run = {};
 __export(exports_run, {
   runCommand: () => runCommand
 });
-import { execSync as execSync12 } from "node:child_process";
+import { execSync as execSync15 } from "node:child_process";
+function printRunHelp() {
+  process.stderr.write(`
+${bold("locus run")} — Execute issues using AI agents
+
+${bold("Usage:")}
+  locus run                           ${dim("# Run active sprint (sequential)")}
+  locus run <issue>                   ${dim("# Run single issue (worktree)")}
+  locus run <issue> <issue> ...       ${dim("# Run multiple issues (parallel)")}
+  locus run --resume                  ${dim("# Resume interrupted run")}
+
+${bold("Options:")}
+  --resume              Resume a previously interrupted run
+  --dry-run             Show what would happen without executing
+  --model <name>        Override the AI model for this run
+  --no-sandbox          Disable Docker sandbox isolation
+  --sandbox=require     Require Docker sandbox (fail if unavailable)
+
+${bold("Sandbox:")}
+  By default, agents run inside Docker Desktop sandboxes (4.58+) for
+  hypervisor-level isolation. If Docker is not available, agents run
+  unsandboxed with a warning.
+
+${bold("Examples:")}
+  locus run                           ${dim("# Execute active sprint")}
+  locus run 42                        ${dim("# Run single issue")}
+  locus run 42 43 44                  ${dim("# Run issues in parallel")}
+  locus run --resume                  ${dim("# Resume after failure")}
+  locus run 42 --no-sandbox           ${dim("# Run without sandbox")}
+  locus run 42 --sandbox=require      ${dim("# Require sandbox")}
+
+`);
+}
 async function runCommand(projectRoot, args, flags = {}) {
+  if (args[0] === "help") {
+    printRunHelp();
+    return;
+  }
   const config = loadConfig(projectRoot);
   const _log = getLogger();
   const cleanupShutdown = registerShutdownHandlers({
@@ -7820,22 +8935,50 @@ async function runCommand(projectRoot, args, flags = {}) {
     getRunState: () => loadRunState(projectRoot)
   });
   try {
+    const sandboxMode = resolveSandboxMode(config.sandbox, flags);
+    let sandboxed = false;
+    if (sandboxMode !== "disabled") {
+      const status = await detectSandboxSupport();
+      if (!status.available) {
+        if (sandboxMode === "required") {
+          process.stderr.write(`${red("✗")} Docker sandbox required but not available: ${status.reason}
+`);
+          process.stderr.write(`  Install Docker Desktop 4.58+ or remove --sandbox=require to continue.
+`);
+          process.exit(1);
+        }
+        process.stderr.write(`${yellow("⚠")} Docker sandbox not available: ${status.reason}. Running unsandboxed.
+`);
+      } else {
+        sandboxed = true;
+      }
+    } else if (flags.noSandbox) {
+      process.stderr.write(`${yellow("⚠")} Running without sandbox. The AI agent will have unrestricted access to your filesystem, network, and environment variables.
+`);
+    }
+    if (sandboxed) {
+      const staleCleaned = await cleanupStaleSandboxes();
+      if (staleCleaned > 0) {
+        process.stderr.write(`  ${dim(`Cleaned up ${staleCleaned} stale sandbox${staleCleaned === 1 ? "" : "es"}.`)}
+`);
+      }
+    }
     if (flags.resume) {
-      return handleResume(projectRoot, config);
+      return handleResume(projectRoot, config, sandboxed);
     }
     const issueNumbers = args.filter((a) => /^\d+$/.test(a)).map(Number);
     if (issueNumbers.length === 0) {
-      return handleSprintRun(projectRoot, config, flags);
+      return handleSprintRun(projectRoot, config, flags, sandboxed);
     }
     if (issueNumbers.length === 1) {
-      return handleSingleIssue(projectRoot, config, issueNumbers[0], flags);
+      return handleSingleIssue(projectRoot, config, issueNumbers[0], flags, sandboxed);
     }
-    return handleParallelRun(projectRoot, config, issueNumbers, flags);
+    return handleParallelRun(projectRoot, config, issueNumbers, flags, sandboxed);
   } finally {
     cleanupShutdown();
   }
 }
-async function handleSprintRun(projectRoot, config, flags) {
+async function handleSprintRun(projectRoot, config, flags, sandboxed) {
   const log = getLogger();
   if (!config.sprint.active) {
     process.stderr.write(`${red("✗")} No active sprint. Set one with: ${bold("locus sprint active <name>")}
@@ -7898,7 +9041,7 @@ ${yellow("⚠")} A sprint run is already in progress.
   }
   if (!flags.dryRun) {
     try {
-      execSync12(`git checkout -B ${branchName}`, {
+      execSync15(`git checkout -B ${branchName}`, {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -7948,7 +9091,7 @@ ${red("✗")} Auto-rebase failed. Resolve manually.
     let sprintContext;
     if (i > 0 && !flags.dryRun) {
       try {
-        sprintContext = execSync12(`git diff origin/${config.agent.baseBranch}..HEAD`, {
+        sprintContext = execSync15(`git diff origin/${config.agent.baseBranch}..HEAD`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -7967,7 +9110,9 @@ ${progressBar(i, state.tasks.length, { label: "Sprint Progress" })}
       model: flags.model ?? config.ai.model,
       dryRun: flags.dryRun,
       sprintContext,
-      skipPR: true
+      skipPR: true,
+      sandboxed,
+      sandboxName: config.sandbox.name
     });
     if (result.success) {
       if (!flags.dryRun) {
@@ -8007,7 +9152,7 @@ ${bold("Summary:")}
     const prNumber = await createSprintPR(projectRoot, config, sprintName, branchName, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync12(`git checkout ${config.agent.baseBranch}`, {
+        execSync15(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -8021,7 +9166,7 @@ ${bold("Summary:")}
     clearRunState(projectRoot);
   }
 }
-async function handleSingleIssue(projectRoot, config, issueNumber, flags) {
+async function handleSingleIssue(projectRoot, config, issueNumber, flags, sandboxed) {
   let isSprintIssue = false;
   try {
     const issue = getIssue(issueNumber, { cwd: projectRoot });
@@ -8036,7 +9181,9 @@ ${bold("Running sprint issue")} ${cyan(`#${issueNumber}`)} ${dim("(sequential, n
       issueNumber,
       provider: config.ai.provider,
       model: flags.model ?? config.ai.model,
-      dryRun: flags.dryRun
+      dryRun: flags.dryRun,
+      sandboxed,
+      sandboxName: config.sandbox.name
     });
     return;
   }
@@ -8065,7 +9212,9 @@ ${bold("Running issue")} ${cyan(`#${issueNumber}`)} ${dim("(worktree)")}
     worktreePath,
     provider: config.ai.provider,
     model: flags.model ?? config.ai.model,
-    dryRun: flags.dryRun
+    dryRun: flags.dryRun,
+    sandboxed,
+    sandboxName: config.sandbox.name
   });
   if (worktreePath && !flags.dryRun) {
     if (result.success) {
@@ -8078,7 +9227,7 @@ ${bold("Running issue")} ${cyan(`#${issueNumber}`)} ${dim("(worktree)")}
     }
   }
 }
-async function handleParallelRun(projectRoot, config, issueNumbers, flags) {
+async function handleParallelRun(projectRoot, config, issueNumbers, flags, sandboxed) {
   const log = getLogger();
   const maxConcurrent = config.agent.maxParallel;
   process.stderr.write(`
@@ -8133,7 +9282,9 @@ ${bold("Running")} ${cyan(`${issueNumbers.length} issues`)} ${dim(`(max ${maxCon
         worktreePath,
         provider: config.ai.provider,
         model: flags.model ?? config.ai.model,
-        dryRun: flags.dryRun
+        dryRun: flags.dryRun,
+        sandboxed,
+        sandboxName: config.sandbox.name
       });
       if (result.success) {
         markTaskDone(state, issueNumber, result.prNumber);
@@ -8145,9 +9296,19 @@ ${bold("Running")} ${cyan(`${issueNumbers.length} issues`)} ${dim(`(max ${maxCon
         markTaskFailed(state, issueNumber, result.error ?? "Unknown error");
       }
       saveRunState(projectRoot, state);
-      results.push({ issue: issueNumber, success: result.success });
+      return { issue: issueNumber, success: result.success };
     });
-    await Promise.all(promises);
+    const settled = await Promise.allSettled(promises);
+    for (const outcome of settled) {
+      if (outcome.status === "fulfilled") {
+        results.push(outcome.value);
+      } else {
+        const idx = settled.indexOf(outcome);
+        const issueNumber = batch[idx];
+        log.warn(`Parallel task #${issueNumber} threw: ${outcome.reason}`);
+        results.push({ issue: issueNumber, success: false });
+      }
+    }
   }
   const succeeded = results.filter((r) => r.success).length;
   const failed = results.filter((r) => !r.success).length;
@@ -8172,7 +9333,7 @@ ${yellow("⚠")} Failed worktrees preserved for debugging:
     clearRunState(projectRoot);
   }
 }
-async function handleResume(projectRoot, config) {
+async function handleResume(projectRoot, config, sandboxed) {
   const state = loadRunState(projectRoot);
   if (!state) {
     process.stderr.write(`${red("✗")} No run state found. Nothing to resume.
@@ -8188,13 +9349,13 @@ ${bold("Resuming")} ${state.type} run ${dim(state.runId)}
 `);
   if (state.type === "sprint" && state.branch) {
     try {
-      const currentBranch = execSync12("git rev-parse --abbrev-ref HEAD", {
+      const currentBranch = execSync15("git rev-parse --abbrev-ref HEAD", {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
       }).trim();
       if (currentBranch !== state.branch) {
-        execSync12(`git checkout ${state.branch}`, {
+        execSync15(`git checkout ${state.branch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -8220,7 +9381,9 @@ ${bold("Resuming")} ${state.type} run ${dim(state.runId)}
       issueNumber: task.issue,
       provider: config.ai.provider,
       model: config.ai.model,
-      skipPR: isSprintRun
+      skipPR: isSprintRun,
+      sandboxed,
+      sandboxName: config.sandbox.name
     });
     if (result.success) {
       if (isSprintRun) {
@@ -8255,7 +9418,7 @@ ${bold("Resume complete:")} ${green(`✓ ${finalStats.done}`)} ${finalStats.fail
     const prNumber = await createSprintPR(projectRoot, config, state.sprint, state.branch, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync12(`git checkout ${config.agent.baseBranch}`, {
+        execSync15(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -8286,14 +9449,14 @@ function getOrder2(issue) {
 }
 function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
   try {
-    const status = execSync12("git status --porcelain", {
+    const status = execSync15("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
     if (!status)
       return;
-    execSync12("git add -A", {
+    execSync15("git add -A", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8301,7 +9464,8 @@ function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
     const message = `chore: complete #${issueNumber} - ${issueTitle}
 
 Co-Authored-By: LocusAgent <agent@locusai.team>`;
-    execSync12(`git commit -m ${JSON.stringify(message)}`, {
+    execSync15(`git commit -F -`, {
+      input: message,
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8314,7 +9478,7 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
   if (!config.agent.autoPR)
     return;
   try {
-    const diff = execSync12(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
+    const diff = execSync15(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8324,7 +9488,7 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
 `);
       return;
     }
-    execSync12(`git push -u origin ${branchName}`, {
+    execSync15(`git push -u origin ${branchName}`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8357,6 +9521,7 @@ var init_run = __esm(() => {
   init_logger();
   init_rate_limiter();
   init_run_state();
+  init_sandbox();
   init_shutdown();
   init_worktree();
   init_progress();
@@ -8469,13 +9634,13 @@ __export(exports_plan, {
   parsePlanArgs: () => parsePlanArgs
 });
 import {
-  existsSync as existsSync16,
+  existsSync as existsSync17,
   mkdirSync as mkdirSync11,
   readdirSync as readdirSync7,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   writeFileSync as writeFileSync9
 } from "node:fs";
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 function printHelp() {
   process.stderr.write(`
 ${bold("locus plan")} — AI-powered sprint planning
@@ -8506,28 +9671,28 @@ function normalizeSprintName(name) {
   return name.trim().toLowerCase();
 }
 function getPlansDir(projectRoot) {
-  return join16(projectRoot, ".locus", "plans");
+  return join17(projectRoot, ".locus", "plans");
 }
 function ensurePlansDir(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync16(dir)) {
+  if (!existsSync17(dir)) {
     mkdirSync11(dir, { recursive: true });
   }
   return dir;
 }
 function generateId() {
-  return `${Math.random().toString(36).slice(2, 8)}`;
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
 function loadPlanFile(projectRoot, id) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync16(dir))
+  if (!existsSync17(dir))
     return null;
   const files = readdirSync7(dir).filter((f) => f.endsWith(".json"));
   const match = files.find((f) => f.startsWith(id));
   if (!match)
     return null;
   try {
-    const content = readFileSync12(join16(dir, match), "utf-8");
+    const content = readFileSync13(join17(dir, match), "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -8573,7 +9738,7 @@ async function planCommand(projectRoot, args, flags = {}) {
 }
 function handleListPlans(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync16(dir)) {
+  if (!existsSync17(dir)) {
     process.stderr.write(`${dim("No saved plans yet.")}
 `);
     return;
@@ -8591,7 +9756,7 @@ ${bold("Saved Plans:")}
   for (const file of files) {
     const id = file.replace(".json", "");
     try {
-      const content = readFileSync12(join16(dir, file), "utf-8");
+      const content = readFileSync13(join17(dir, file), "utf-8");
       const plan = JSON.parse(content);
       const date = plan.createdAt ? plan.createdAt.slice(0, 10) : "";
       const issueCount = Array.isArray(plan.issues) ? plan.issues.length : 0;
@@ -8702,7 +9867,7 @@ ${bold("Approving plan:")}
 async function handleAIPlan(projectRoot, config, directive, sprintName, flags) {
   const id = generateId();
   const plansDir = ensurePlansDir(projectRoot);
-  const planPath = join16(plansDir, `${id}.json`);
+  const planPath = join17(plansDir, `${id}.json`);
   const planPathRelative = `.locus/plans/${id}.json`;
   const displayDirective = directive;
   process.stderr.write(`
@@ -8720,7 +9885,9 @@ ${bold("Planning:")} ${cyan(displayDirective)}
     provider: config.ai.provider,
     model: flags.model ?? config.ai.model,
     cwd: projectRoot,
-    activity: "planning"
+    activity: "planning",
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name
   });
   if (aiResult.interrupted) {
     process.stderr.write(`
@@ -8734,7 +9901,7 @@ ${red("✗")} Planning failed: ${aiResult.error}
 `);
     return;
   }
-  if (!existsSync16(planPath)) {
+  if (!existsSync17(planPath)) {
     process.stderr.write(`
 ${yellow("⚠")} Plan file was not created at ${bold(planPathRelative)}.
 `);
@@ -8744,7 +9911,7 @@ ${yellow("⚠")} Plan file was not created at ${bold(planPathRelative)}.
   }
   let plan;
   try {
-    const content = readFileSync12(planPath, "utf-8");
+    const content = readFileSync13(planPath, "utf-8");
     plan = JSON.parse(content);
   } catch {
     process.stderr.write(`
@@ -8828,7 +9995,9 @@ Start with foundational/setup tasks, then core features, then integration/testin
     model: flags.model ?? config.ai.model,
     cwd: projectRoot,
     activity: "issue ordering",
-    silent: true
+    silent: true,
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name
   });
   if (aiResult.interrupted) {
     process.stderr.write(`
@@ -8899,16 +10068,16 @@ function buildPlanningPrompt(projectRoot, config, directive, sprintName, id, pla
     parts.push(`SPRINT: ${sprintName}`);
   }
   parts.push("");
-  const locusPath = join16(projectRoot, "LOCUS.md");
-  if (existsSync16(locusPath)) {
-    const content = readFileSync12(locusPath, "utf-8");
+  const locusPath = join17(projectRoot, "LOCUS.md");
+  if (existsSync17(locusPath)) {
+    const content = readFileSync13(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT (LOCUS.md):");
     parts.push(content.slice(0, 3000));
     parts.push("");
   }
-  const learningsPath = join16(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync16(learningsPath)) {
-    const content = readFileSync12(learningsPath, "utf-8");
+  const learningsPath = join17(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync17(learningsPath)) {
+    const content = readFileSync13(learningsPath, "utf-8");
     parts.push("PAST LEARNINGS:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -9084,9 +10253,9 @@ var exports_review = {};
 __export(exports_review, {
   reviewCommand: () => reviewCommand
 });
-import { execSync as execSync13 } from "node:child_process";
-import { existsSync as existsSync17, readFileSync as readFileSync13 } from "node:fs";
-import { join as join17 } from "node:path";
+import { execSync as execSync16 } from "node:child_process";
+import { existsSync as existsSync18, readFileSync as readFileSync14 } from "node:fs";
+import { join as join18 } from "node:path";
 function printHelp2() {
   process.stderr.write(`
 ${bold("locus review")} — AI-powered code review
@@ -9162,7 +10331,7 @@ ${bold("Review complete:")} ${green(`✓ ${reviewed}`)}${failed > 0 ? ` ${red(`
 async function reviewSinglePR(projectRoot, config, prNumber, focus, flags) {
   let prInfo;
   try {
-    const result = execSync13(`gh pr view ${prNumber} --json number,title,body,state,headRefName,baseRefName,labels,url,createdAt`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const result = execSync16(`gh pr view ${prNumber} --json number,title,body,state,headRefName,baseRefName,labels,url,createdAt`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
     const raw = JSON.parse(result);
     prInfo = {
       number: raw.number,
@@ -9205,7 +10374,9 @@ async function reviewPR(projectRoot, config, pr, focus, flags) {
     provider: config.ai.provider,
     model: flags.model ?? config.ai.model,
     cwd: projectRoot,
-    activity: `PR #${pr.number}`
+    activity: `PR #${pr.number}`,
+    sandboxed: config.sandbox.enabled,
+    sandboxName: config.sandbox.name
   });
   if (aiResult.interrupted) {
     process.stderr.write(`  ${yellow("⚡")} Review interrupted.
@@ -9226,7 +10397,7 @@ ${output.slice(0, 60000)}
 
 ---
 _Reviewed by Locus AI (${config.ai.provider}/${flags.model ?? config.ai.model})_`;
-      execSync13(`gh pr comment ${pr.number} --body ${JSON.stringify(reviewBody)}`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+      execSync16(`gh pr comment ${pr.number} --body ${JSON.stringify(reviewBody)}`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
       process.stderr.write(`  ${green("✓")} Review posted ${dim(`(${timer.formatted()})`)}
 `);
     } catch (e) {
@@ -9243,9 +10414,9 @@ function buildReviewPrompt(projectRoot, config, pr, diff, focus) {
   const parts = [];
   parts.push(`You are an expert code reviewer for the ${config.github.owner}/${config.github.repo} repository.`);
   parts.push("");
-  const locusPath = join17(projectRoot, "LOCUS.md");
-  if (existsSync17(locusPath)) {
-    const content = readFileSync13(locusPath, "utf-8");
+  const locusPath = join18(projectRoot, "LOCUS.md");
+  if (existsSync18(locusPath)) {
+    const content = readFileSync14(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -9297,7 +10468,7 @@ var exports_iterate = {};
 __export(exports_iterate, {
   iterateCommand: () => iterateCommand
 });
-import { execSync as execSync14 } from "node:child_process";
+import { execSync as execSync17 } from "node:child_process";
 function printHelp3() {
   process.stderr.write(`
 ${bold("locus iterate")} — Re-execute tasks with PR feedback
@@ -9507,12 +10678,12 @@ ${bold("Summary:")} ${green(`✓ ${succeeded}`)}${failed > 0 ? ` ${red(`✗ ${fa
 }
 function findPRForIssue(projectRoot, issueNumber) {
   try {
-    const result = execSync14(`gh pr list --search "Closes #${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const result = execSync17(`gh pr list --search "Closes #${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
     const parsed = JSON.parse(result);
     if (parsed.length > 0) {
       return parsed[0].number;
     }
-    const branchResult = execSync14(`gh pr list --head "locus/issue-${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const branchResult = execSync17(`gh pr list --head "locus/issue-${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
     const branchParsed = JSON.parse(branchResult);
     if (branchParsed.length > 0) {
       return branchParsed[0].number;
@@ -9547,14 +10718,14 @@ __export(exports_discuss, {
   discussCommand: () => discussCommand
 });
 import {
-  existsSync as existsSync18,
+  existsSync as existsSync19,
   mkdirSync as mkdirSync12,
   readdirSync as readdirSync8,
-  readFileSync as readFileSync14,
+  readFileSync as readFileSync15,
   unlinkSync as unlinkSync5,
   writeFileSync as writeFileSync10
 } from "node:fs";
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 function printHelp4() {
   process.stderr.write(`
 ${bold("locus discuss")} — AI-powered architectural discussions
@@ -9576,11 +10747,11 @@ ${bold("Examples:")}
 `);
 }
 function getDiscussionsDir(projectRoot) {
-  return join18(projectRoot, ".locus", "discussions");
+  return join19(projectRoot, ".locus", "discussions");
 }
 function ensureDiscussionsDir(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync19(dir)) {
     mkdirSync12(dir, { recursive: true });
   }
   return dir;
@@ -9615,7 +10786,7 @@ async function discussCommand(projectRoot, args, flags = {}) {
 }
 function listDiscussions(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync19(dir)) {
     process.stderr.write(`${dim("No discussions yet.")}
 `);
     return;
@@ -9632,7 +10803,7 @@ ${bold("Discussions:")}
 `);
   for (const file of files) {
     const id = file.replace(".md", "");
-    const content = readFileSync14(join18(dir, file), "utf-8");
+    const content = readFileSync15(join19(dir, file), "utf-8");
     const titleMatch = content.match(/^#\s+(.+)/m);
     const title = titleMatch ? titleMatch[1] : id;
     const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/);
@@ -9650,7 +10821,7 @@ function showDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync19(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -9662,7 +10833,7 @@ function showDiscussion(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync14(join18(dir, match), "utf-8");
+  const content = readFileSync15(join19(dir, match), "utf-8");
   process.stdout.write(`${content}
 `);
 }
@@ -9673,7 +10844,7 @@ function deleteDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync19(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -9685,7 +10856,7 @@ function deleteDiscussion(projectRoot, id) {
 `);
     return;
   }
-  unlinkSync5(join18(dir, match));
+  unlinkSync5(join19(dir, match));
   process.stderr.write(`${green("✓")} Deleted discussion: ${match.replace(".md", "")}
 `);
 }
@@ -9698,7 +10869,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync19(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -9710,7 +10881,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync14(join18(dir, match), "utf-8");
+  const content = readFileSync15(join19(dir, match), "utf-8");
   const titleMatch = content.match(/^#\s+(.+)/m);
   const discussionTitle = titleMatch ? titleMatch[1].trim() : id;
   await planCommand(projectRoot, [
@@ -9755,7 +10926,9 @@ ${bold("Discussion:")} ${cyan(topic)}
       provider: config.ai.provider,
       model: flags.model ?? config.ai.model,
       cwd: projectRoot,
-      activity: "discussion"
+      activity: "discussion",
+      sandboxed: config.sandbox.enabled,
+      sandboxName: config.sandbox.name
     });
     if (aiResult.interrupted) {
       process.stderr.write(`
@@ -9822,7 +10995,7 @@ ${turn.content}`;
     ...conversation.length > 1 ? [`---`, ``, `## Discussion Transcript`, ``, transcript, ``] : []
   ].join(`
 `);
-  writeFileSync10(join18(dir, `${id}.md`), markdown, "utf-8");
+  writeFileSync10(join19(dir, `${id}.md`), markdown, "utf-8");
   process.stderr.write(`
 ${green("✓")} Discussion saved: ${cyan(id)} ${dim(`(${timer.formatted()})`)}
 `);
@@ -9836,16 +11009,16 @@ function buildDiscussionPrompt(projectRoot, config, topic, conversation, forceFi
   const parts = [];
   parts.push(`You are a senior software architect and consultant for the ${config.github.owner}/${config.github.repo} project.`);
   parts.push("");
-  const locusPath = join18(projectRoot, "LOCUS.md");
-  if (existsSync18(locusPath)) {
-    const content = readFileSync14(locusPath, "utf-8");
+  const locusPath = join19(projectRoot, "LOCUS.md");
+  if (existsSync19(locusPath)) {
+    const content = readFileSync15(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT:");
     parts.push(content.slice(0, 3000));
     parts.push("");
   }
-  const learningsPath = join18(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync18(learningsPath)) {
-    const content = readFileSync14(learningsPath, "utf-8");
+  const learningsPath = join19(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync19(learningsPath)) {
+    const content = readFileSync15(learningsPath, "utf-8");
     parts.push("PAST LEARNINGS:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -9904,8 +11077,8 @@ __export(exports_artifacts, {
   formatDate: () => formatDate2,
   artifactsCommand: () => artifactsCommand
 });
-import { existsSync as existsSync19, readdirSync as readdirSync9, readFileSync as readFileSync15, statSync as statSync4 } from "node:fs";
-import { join as join19 } from "node:path";
+import { existsSync as existsSync20, readdirSync as readdirSync9, readFileSync as readFileSync16, statSync as statSync4 } from "node:fs";
+import { join as join20 } from "node:path";
 function printHelp5() {
   process.stderr.write(`
 ${bold("locus artifacts")} — View and manage AI-generated artifacts
@@ -9925,14 +11098,14 @@ ${dim("Artifact names support partial matching.")}
 `);
 }
 function getArtifactsDir(projectRoot) {
-  return join19(projectRoot, ".locus", "artifacts");
+  return join20(projectRoot, ".locus", "artifacts");
 }
 function listArtifacts(projectRoot) {
   const dir = getArtifactsDir(projectRoot);
-  if (!existsSync19(dir))
+  if (!existsSync20(dir))
     return [];
   return readdirSync9(dir).filter((f) => f.endsWith(".md")).map((fileName) => {
-    const filePath = join19(dir, fileName);
+    const filePath = join20(dir, fileName);
     const stat = statSync4(filePath);
     return {
       name: fileName.replace(/\.md$/, ""),
@@ -9945,12 +11118,12 @@ function listArtifacts(projectRoot) {
 function readArtifact(projectRoot, name) {
   const dir = getArtifactsDir(projectRoot);
   const fileName = name.endsWith(".md") ? name : `${name}.md`;
-  const filePath = join19(dir, fileName);
-  if (!existsSync19(filePath))
+  const filePath = join20(dir, fileName);
+  if (!existsSync20(filePath))
     return null;
   const stat = statSync4(filePath);
   return {
-    content: readFileSync15(filePath, "utf-8"),
+    content: readFileSync16(filePath, "utf-8"),
     info: {
       name: fileName.replace(/\.md$/, ""),
       fileName,
@@ -10108,23 +11281,276 @@ var init_artifacts = __esm(() => {
   init_terminal();
 });
 
+// src/commands/sandbox.ts
+var exports_sandbox = {};
+__export(exports_sandbox, {
+  sandboxCommand: () => sandboxCommand
+});
+import { execSync as execSync18, spawn as spawn6 } from "node:child_process";
+function printSandboxHelp() {
+  process.stderr.write(`
+${bold("locus sandbox")} — Manage Docker sandbox lifecycle
+
+${bold("Usage:")}
+  locus sandbox                     ${dim("# Create sandbox and enable sandbox mode")}
+  locus sandbox claude              ${dim("# Run claude interactively (for login)")}
+  locus sandbox codex               ${dim("# Run codex interactively (for login)")}
+  locus sandbox rm                  ${dim("# Destroy sandbox and disable sandbox mode")}
+  locus sandbox status              ${dim("# Show current sandbox state")}
+
+${bold("Flow:")}
+  1. ${cyan("locus sandbox")}          Create the sandbox environment
+  2. ${cyan("locus sandbox claude")}   Login to Claude inside the sandbox
+  3. ${cyan("locus exec")}             All commands now run inside the sandbox
+
+`);
+}
+async function sandboxCommand(projectRoot, args) {
+  const subcommand = args[0] ?? "";
+  switch (subcommand) {
+    case "help":
+      printSandboxHelp();
+      return;
+    case "claude":
+    case "codex":
+      return handleAgentLogin(projectRoot, subcommand);
+    case "rm":
+      return handleRemove(projectRoot);
+    case "status":
+      return handleStatus(projectRoot);
+    case "":
+      return handleCreate(projectRoot);
+    default:
+      process.stderr.write(`${red("✗")} Unknown sandbox subcommand: ${bold(subcommand)}
+`);
+      process.stderr.write(`  Available: ${cyan("claude")}, ${cyan("codex")}, ${cyan("rm")}, ${cyan("status")}
+`);
+  }
+}
+async function handleCreate(projectRoot) {
+  const config = loadConfig(projectRoot);
+  if (config.sandbox.name) {
+    const alive = isSandboxAlive(config.sandbox.name);
+    if (alive) {
+      process.stderr.write(`${green("✓")} Sandbox already exists: ${bold(config.sandbox.name)}
+`);
+      process.stderr.write(`  Run ${cyan("locus sandbox claude")} or ${cyan("locus sandbox codex")} to login.
+`);
+      return;
+    }
+    process.stderr.write(`${yellow("⚠")} Previous sandbox ${dim(config.sandbox.name)} is no longer running. Creating a new one.
+`);
+  }
+  const status = await detectSandboxSupport();
+  if (!status.available) {
+    process.stderr.write(`${red("✗")} Docker sandbox not available: ${status.reason}
+`);
+    process.stderr.write(`  Install Docker Desktop 4.58+ with sandbox support.
+`);
+    return;
+  }
+  const segment = projectRoot.split("/").pop() ?? "sandbox";
+  const sandboxName = `locus-${segment}-${Date.now()}`;
+  config.sandbox.enabled = true;
+  config.sandbox.name = sandboxName;
+  saveConfig(projectRoot, config);
+  process.stderr.write(`${green("✓")} Sandbox name reserved: ${bold(sandboxName)}
+`);
+  process.stderr.write(`  Next: run ${cyan("locus sandbox claude")} or ${cyan("locus sandbox codex")} to create the sandbox and login.
+`);
+}
+async function handleAgentLogin(projectRoot, agent) {
+  const config = loadConfig(projectRoot);
+  if (!config.sandbox.name) {
+    const status = await detectSandboxSupport();
+    if (!status.available) {
+      process.stderr.write(`${red("✗")} Docker sandbox not available: ${status.reason}
+`);
+      process.stderr.write(`  Install Docker Desktop 4.58+ with sandbox support.
+`);
+      return;
+    }
+    const segment = projectRoot.split("/").pop() ?? "sandbox";
+    config.sandbox.name = `locus-${segment}-${Date.now()}`;
+    config.sandbox.enabled = true;
+    saveConfig(projectRoot, config);
+  }
+  const sandboxName = config.sandbox.name;
+  const alive = isSandboxAlive(sandboxName);
+  let dockerArgs;
+  if (alive) {
+    if (agent === "codex") {
+      await ensureCodexInSandbox(sandboxName);
+    }
+    process.stderr.write(`Connecting to sandbox ${dim(sandboxName)}...
+`);
+    process.stderr.write(`${dim("Login and then exit when ready.")}
+
+`);
+    dockerArgs = [
+      "sandbox",
+      "exec",
+      "-it",
+      "-w",
+      projectRoot,
+      sandboxName,
+      agent
+    ];
+  } else if (agent === "codex") {
+    process.stderr.write(`Creating sandbox ${bold(sandboxName)} with workspace ${dim(projectRoot)}...
+`);
+    try {
+      execSync18(`docker sandbox run --name ${sandboxName} claude ${projectRoot} -- --version`, { stdio: ["pipe", "pipe", "pipe"], timeout: 120000 });
+    } catch {}
+    if (!isSandboxAlive(sandboxName)) {
+      process.stderr.write(`${red("✗")} Failed to create sandbox.
+`);
+      return;
+    }
+    await ensureCodexInSandbox(sandboxName);
+    process.stderr.write(`${dim("Login and then exit when ready.")}
+
+`);
+    dockerArgs = [
+      "sandbox",
+      "exec",
+      "-it",
+      "-w",
+      projectRoot,
+      sandboxName,
+      "codex"
+    ];
+  } else {
+    process.stderr.write(`Creating sandbox ${bold(sandboxName)} with workspace ${dim(projectRoot)}...
+`);
+    process.stderr.write(`${dim("Login and then exit when ready.")}
+
+`);
+    dockerArgs = ["sandbox", "run", "--name", sandboxName, agent, projectRoot];
+  }
+  const child = spawn6("docker", dockerArgs, {
+    stdio: "inherit"
+  });
+  await new Promise((resolve2) => {
+    child.on("close", async (code) => {
+      await enforceSandboxIgnore(sandboxName, projectRoot);
+      if (code === 0) {
+        process.stderr.write(`
+${green("✓")} ${agent} session ended. Auth should now be persisted in the sandbox.
+`);
+      } else {
+        process.stderr.write(`
+${yellow("⚠")} ${agent} exited with code ${code}.
+`);
+      }
+      resolve2();
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`${red("✗")} Failed to start ${agent}: ${err.message}
+`);
+      resolve2();
+    });
+  });
+}
+function handleRemove(projectRoot) {
+  const config = loadConfig(projectRoot);
+  if (!config.sandbox.name) {
+    process.stderr.write(`${dim("No sandbox to remove.")}
+`);
+    return;
+  }
+  const sandboxName = config.sandbox.name;
+  process.stderr.write(`Removing sandbox ${bold(sandboxName)}...
+`);
+  try {
+    execSync18(`docker sandbox rm ${sandboxName}`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 15000
+    });
+  } catch {}
+  config.sandbox.name = undefined;
+  config.sandbox.enabled = false;
+  saveConfig(projectRoot, config);
+  process.stderr.write(`${green("✓")} Sandbox removed. Sandbox mode disabled.
+`);
+}
+function handleStatus(projectRoot) {
+  const config = loadConfig(projectRoot);
+  process.stderr.write(`
+${bold("Sandbox Status")}
+
+`);
+  process.stderr.write(`  ${dim("Enabled:")}  ${config.sandbox.enabled ? green("yes") : red("no")}
+`);
+  process.stderr.write(`  ${dim("Name:")}     ${config.sandbox.name ? bold(config.sandbox.name) : dim("(none)")}
+`);
+  if (config.sandbox.name) {
+    const alive = isSandboxAlive(config.sandbox.name);
+    process.stderr.write(`  ${dim("Running:")}  ${alive ? green("yes") : red("no")}
+`);
+    if (!alive) {
+      process.stderr.write(`
+  ${yellow("⚠")} Sandbox is not running. Run ${bold("locus sandbox")} to create a new one.
+`);
+    }
+  }
+  process.stderr.write(`
+`);
+}
+async function ensureCodexInSandbox(sandboxName) {
+  try {
+    execSync18(`docker sandbox exec ${sandboxName} which codex`, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000
+    });
+  } catch {
+    process.stderr.write(`Installing codex in sandbox...
+`);
+    try {
+      execSync18(`docker sandbox exec ${sandboxName} npm install -g @openai/codex`, { stdio: "inherit", timeout: 120000 });
+    } catch {
+      process.stderr.write(`${red("✗")} Failed to install codex in sandbox.
+`);
+    }
+  }
+}
+function isSandboxAlive(name) {
+  try {
+    const output = execSync18("docker sandbox ls", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000
+    });
+    return output.includes(name);
+  } catch {
+    return false;
+  }
+}
+var init_sandbox2 = __esm(() => {
+  init_config();
+  init_sandbox();
+  init_sandbox_ignore();
+  init_terminal();
+});
+
 // src/cli.ts
 init_config();
 init_context();
 init_logger();
 init_rate_limiter();
 init_terminal();
-import { existsSync as existsSync20, readFileSync as readFileSync16 } from "node:fs";
-import { join as join20 } from "node:path";
+import { existsSync as existsSync21, readFileSync as readFileSync17 } from "node:fs";
+import { join as join21 } from "node:path";
 import { fileURLToPath } from "node:url";
 function getCliVersion() {
   const fallbackVersion = "0.0.0";
-  const packageJsonPath = join20(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
-  if (!existsSync20(packageJsonPath)) {
+  const packageJsonPath = join21(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
+  if (!existsSync21(packageJsonPath)) {
     return fallbackVersion;
   }
   try {
-    const parsed = JSON.parse(readFileSync16(packageJsonPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync17(packageJsonPath, "utf-8"));
     return parsed.version ?? fallbackVersion;
   } catch {
     return fallbackVersion;
@@ -10144,7 +11570,8 @@ function parseArgs(argv) {
     dryRun: false,
     check: false,
     upgrade: false,
-    list: false
+    list: false,
+    noSandbox: false
   };
   const positional = [];
   let i = 0;
@@ -10221,7 +11648,14 @@ function parseArgs(argv) {
       case "--target-version":
         flags.targetVersion = rawArgs[++i];
         break;
+      case "--no-sandbox":
+        flags.noSandbox = true;
+        break;
       default:
+        if (arg.startsWith("--sandbox=")) {
+          flags.sandbox = arg.slice("--sandbox=".length);
+          break;
+        }
         positional.push(arg);
     }
     i++;
@@ -10255,6 +11689,7 @@ ${bold("Commands:")}
   ${cyan("uninstall")}         Remove an installed package
   ${cyan("packages")}          Manage installed packages (list, outdated)
   ${cyan("pkg")} ${dim("<name> [cmd]")}   Run a command from an installed package
+  ${cyan("sandbox")}           Manage Docker sandbox lifecycle
   ${cyan("upgrade")}           Check for and install updates
 
 ${bold("Options:")}
@@ -10270,6 +11705,10 @@ ${bold("Examples:")}
   locus plan approve <id>             ${dim("# Create issues from saved plan")}
   locus run                           ${dim("# Execute active sprint")}
   locus run 42 43                     ${dim("# Run issues in parallel")}
+  locus run 42 --no-sandbox           ${dim("# Run without sandbox")}
+  locus run 42 --sandbox=require      ${dim("# Require Docker sandbox")}
+  locus sandbox                       ${dim("# Create Docker sandbox")}
+  locus sandbox claude                ${dim("# Login to Claude in sandbox")}
 
 `);
 }
@@ -10300,7 +11739,7 @@ async function main() {
     try {
       const root = getGitRoot(cwd);
       if (isInitialized(root)) {
-        logDir = join20(root, ".locus", "logs");
+        logDir = join21(root, ".locus", "logs");
         getRateLimiter(root);
       }
     } catch {}
@@ -10374,7 +11813,6 @@ async function main() {
     process.stderr.write(`${red("✗")} Not inside a git repository.
 `);
     process.exit(1);
-    return;
   }
   if (!isInitialized(projectRoot)) {
     process.stderr.write(`${red("✗")} Locus is not initialized in this project.
@@ -10382,7 +11820,6 @@ async function main() {
     process.stderr.write(`  Run: ${bold("locus init")}
 `);
     process.exit(1);
-    return;
   }
   switch (command) {
     case "config": {
@@ -10427,7 +11864,9 @@ async function main() {
       await runCommand2(projectRoot, runArgs, {
         resume: parsed.flags.resume,
         dryRun: parsed.flags.dryRun,
-        model: parsed.flags.model
+        model: parsed.flags.model,
+        sandbox: parsed.flags.sandbox,
+        noSandbox: parsed.flags.noSandbox
       });
       break;
     }
@@ -10477,6 +11916,12 @@ async function main() {
       await artifactsCommand2(projectRoot, artifactsArgs);
       break;
     }
+    case "sandbox": {
+      const { sandboxCommand: sandboxCommand2 } = await Promise.resolve().then(() => (init_sandbox2(), exports_sandbox));
+      const sandboxArgs = parsed.flags.help ? ["help"] : parsed.args;
+      await sandboxCommand2(projectRoot, sandboxArgs);
+      break;
+    }
     case "upgrade": {
       const { upgradeCommand: upgradeCommand2 } = await Promise.resolve().then(() => (init_upgrade(), exports_upgrade));
       await upgradeCommand2(projectRoot, parsed.args, {