@locusai/cli 0.19.1 → 0.20.0

package/bin/locus.js

@@ -280,7 +280,7 @@ function drawBox(lines, options) {
   return parts.join(`
 `);
 }
-var cachedCapabilities = null, enabled = () => getCapabilities().colorBasic, bold, dim, italic, underline, strikethrough, red, green, yellow, blue, magenta, cyan, white, gray, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, bgRed, bgGreen, bgYellow, bgBlue, box;
+var cachedCapabilities = null, enabled = () => getCapabilities().colorBasic, bold, dim, italic, underline, strikethrough, red, green, yellow, blue, magenta, cyan, white, gray, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, bgRed, bgGreen, bgYellow, bgBlue, bgGray, box;
 var init_terminal = __esm(() => {
   bold = wrap("\x1B[1m", "\x1B[22m");
   dim = wrap("\x1B[2m", "\x1B[22m");
@@ -305,6 +305,7 @@ var init_terminal = __esm(() => {
   bgGreen = wrap("\x1B[42m", "\x1B[49m");
   bgYellow = wrap("\x1B[43m", "\x1B[49m");
   bgBlue = wrap("\x1B[44m", "\x1B[49m");
+  bgGray = wrap("\x1B[100m", "\x1B[49m");
   box = {
     topLeft: "┌",
     topRight: "┐",
@@ -1714,6 +1715,8 @@ ${bold("Initializing Locus...")}
         config.sprint = { ...config.sprint, ...existing.sprint };
       if (existing.logging)
         config.logging = { ...config.logging, ...existing.logging };
+      if (existing.sandbox)
+        config.sandbox = { ...config.sandbox, ...existing.sandbox };
     } catch {}
     process.stderr.write(`${green("✓")} Updated config.json (preserved existing settings)
 `);
@@ -1817,14 +1820,27 @@ ${bold("Sandbox mode")} ${dim("(recommended)")}
 }
 var LOCUS_MD_TEMPLATE = `## Planning First
 
-Complex tasks must be planned before writing code. Create ".locus/plans/<task-name>.md" with:
+**Before writing any code** for complex or multi-step tasks, you **must** create a plan file at \`.locus/plans/<task-name>.md\`. Do NOT skip this step — write the plan file to disk first, then execute.
+
+**Plan file structure:**
 - **Goal**: What we're trying to achieve and why
 - **Approach**: Step-by-step strategy with technical decisions
 - **Affected files**: List of files to create/modify/delete
 - **Acceptance criteria**: Specific, testable conditions for completion
 - **Dependencies**: Required packages, APIs, or external services
 
-Delete the planning .md files after successful execution.
+**When to plan:**
+- Tasks that touch 3+ files
+- New features or architectural changes
+- Tasks with ambiguous requirements that need decomposition
+- Any task where multiple approaches exist
+
+**When you can skip planning:**
+- Single-file bug fixes with obvious root cause
+- Typo corrections, comment updates, or trivial changes
+- Tasks with very specific, step-by-step instructions already provided
+
+Delete the planning \`.md\` files after successful execution.
 
 ## Code Quality
 
@@ -1834,6 +1850,26 @@ Delete the planning .md files after successful execution.
 - **Test as you go**: If tests exist, run relevant ones. If breaking changes occur, update tests accordingly
 - **Comment complex logic**: Explain *why*, not *what*. Focus on business logic and non-obvious decisions
 
+## Parallel Execution with Subagents
+
+Use the **Task tool** to launch subagents for parallelizing independent work. Subagents run autonomously and return results when done.
+
+**When to use subagents:**
+- **Codebase exploration**: Use \`subagent_type: "Explore"\` to search for files, patterns, or understand architecture across multiple locations simultaneously
+- **Independent research**: Launch multiple explore agents in parallel when you need to understand different parts of the codebase at once
+- **Complex multi-area changes**: When a task touches unrelated areas, use explore agents to gather context from each area in parallel before making changes
+
+**How to use:**
+- Specify \`subagent_type\` — use \`"Explore"\` for codebase research, \`"general-purpose"\` for multi-step autonomous tasks
+- Launch multiple agents in a **single message** to run them concurrently
+- Provide clear, detailed prompts so agents can work autonomously
+- Do NOT duplicate work — if you delegate research to a subagent, wait for results instead of searching yourself
+
+**When NOT to use subagents:**
+- Simple, directed searches (use Glob or Grep directly)
+- Reading a specific known file (use Read directly)
+- Tasks that require sequential steps where each depends on the previous
+
 ## Artifacts
 
 When a task produces knowledge, analysis, or research output rather than (or in addition to) code changes, you **must** save results as Markdown in ".locus/artifacts/<descriptive-name>.md":
@@ -1990,7 +2026,8 @@ import {
 import { homedir as homedir2 } from "node:os";
 import { join as join6 } from "node:path";
 function getPackagesDir() {
-  const dir = join6(homedir2(), ".locus", "packages");
+  const home = process.env.HOME || homedir2();
+  const dir = join6(home, ".locus", "packages");
   if (!existsSync6(dir)) {
     mkdirSync6(dir, { recursive: true });
   }
@@ -2903,6 +2940,8 @@ class StreamRenderer {
   renderTimer = null;
   catchUpMode = false;
   totalLinesRendered = 0;
+  isFirstLine = true;
+  hasContent = false;
   onRender;
   constructor(onRender) {
     this.onRender = onRender ?? ((line) => process.stdout.write(`${line}\r
@@ -2918,6 +2957,12 @@ class StreamRenderer {
   }
   push(text) {
     this.buffer += text;
+    if (!this.hasContent) {
+      this.buffer = this.buffer.replace(/^\n+/, "");
+      if (this.buffer.length === 0)
+        return;
+      this.hasContent = true;
+    }
     const lines = this.buffer.split(`
 `);
     this.buffer = lines.pop() ?? "";
@@ -2930,6 +2975,9 @@ class StreamRenderer {
       clearInterval(this.renderTimer);
       this.renderTimer = null;
     }
+    while (this.lineQueue.length > 0 && this.lineQueue[this.lineQueue.length - 1]?.trim() === "") {
+      this.lineQueue.pop();
+    }
     while (this.lineQueue.length > 0) {
       const line = this.lineQueue.shift();
       if (line !== undefined)
@@ -2937,8 +2985,8 @@ class StreamRenderer {
     }
     if (this.buffer.trim()) {
       this.renderLine(this.buffer);
-      this.buffer = "";
     }
+    this.buffer = "";
     this.inTable = false;
   }
   getLinesRendered() {
@@ -2965,7 +3013,10 @@ class StreamRenderer {
     }
   }
   renderLine(raw) {
-    const formatted = this.formatMarkdown(raw);
+    const prefix = this.isFirstLine ? `${dim("●")} ` : "  ";
+    if (this.isFirstLine)
+      this.isFirstLine = false;
+    const formatted = `${prefix}${this.formatMarkdown(raw)}`;
     beginSync();
     this.onRender(formatted);
     endSync();
@@ -3016,7 +3067,7 @@ class StreamRenderer {
     result = result.replace(/\*\*([^*]+)\*\*/g, (_, content) => bold(content));
     result = result.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, (_, content) => italic(content));
     result = result.replace(/~~([^~]+)~~/g, (_, content) => dim(content));
-    result = result.replace(/`([^`]+)`/g, (_, content) => cyan(content));
+    result = result.replace(/`([^`]+)`/g, (_, content) => bold(cyan(content)));
     return result;
   }
   formatTableLine(line) {
@@ -5126,6 +5177,9 @@ ${red("✗")} ${dim("Force exit.")}\r
         if (!hasOutput) {
           hasOutput = true;
           indicator.stop();
+          if (!options.silent)
+            process.stdout.write(`
+`);
         }
         renderer?.push(chunk);
         output += chunk;
@@ -5148,6 +5202,10 @@ ${red("✗")} ${dim("Force exit.")}\r
     });
     renderer?.stop();
     indicator.stop();
+    if (hasOutput && !wasAborted && renderer) {
+      process.stdout.write(`
+`);
+    }
     if (wasAborted) {
       return {
         success: false,
@@ -7894,15 +7952,31 @@ ${red("✗")} ${aiResult.error}
 function printWelcome(session) {
   process.stderr.write(`
 `);
-  process.stderr.write(`${bold("Locus")} ${dim("REPL")} — session ${dim(session.id)}
+  const logoWidth = 10;
+  const gap = "    ";
+  const infoLines = [
+    `${bold("Locus")} ${dim("REPL")}`,
+    `${dim("Provider:")} ${session.metadata.provider} ${dim("/")} ${session.metadata.model}`,
+    `${dim("Session:")}  ${dim(session.id)}`
+  ];
+  const textOffset = 1;
+  const totalLines = Math.max(LOCUS_LOGO.length, infoLines.length + textOffset);
+  for (let i = 0;i < totalLines; i++) {
+    const logoLine = LOCUS_LOGO[i] ?? "";
+    const paddedLogo = logoLine.padEnd(logoWidth);
+    const infoIdx = i - textOffset;
+    const infoLine = infoIdx >= 0 && infoIdx < infoLines.length ? infoLines[infoIdx] : "";
+    process.stderr.write(`${bold(white(paddedLogo))}${gap}${infoLine}
 `);
-  process.stderr.write(`${dim(`Provider: ${session.metadata.provider} / ${session.metadata.model}`)}
+  }
+  process.stderr.write(`
 `);
-  process.stderr.write(`${dim("Type /help for commands, Shift+Enter for newline, Ctrl+C twice to exit")}
+  process.stderr.write(`  ${dim("Type /help for commands, Shift+Enter for newline, Ctrl+C twice to exit")}
 `);
   process.stderr.write(`
 `);
 }
+var LOCUS_LOGO;
 var init_repl = __esm(() => {
   init_run_ai();
   init_runner();
@@ -7917,6 +7991,18 @@ var init_repl = __esm(() => {
   init_input_history();
   init_model_config();
   init_session_manager();
+  LOCUS_LOGO = [
+    "      ▄█                 ",
+    "  ▄▄████▄▄▄▄             ",
+    "  ████▀ ████             ",
+    "  ████▄▄████             ",
+    "  ▀█▄█▀███▀▀ ▄▄██▄▄      ",
+    "  ████    ▄██████▀███▄   ",
+    "  ████▄██▀ ▀▀███ ▄████   ",
+    "  ▀▀██████▄    ██████▀   ",
+    "      ▀▀█████▄▄██▀▀      ",
+    "         ▀▀██▀▀          "
+  ];
 });
 
 // src/commands/exec.ts
@@ -8590,15 +8676,6 @@ var init_run_state = __esm(() => {
 });
 
 // src/core/shutdown.ts
-import { execSync as execSync12 } from "node:child_process";
-function cleanupActiveSandboxes() {
-  for (const name of activeSandboxes) {
-    try {
-      execSync12(`docker sandbox rm ${name}`, { timeout: 1e4 });
-    } catch {}
-  }
-  activeSandboxes.clear();
-}
 function registerShutdownHandlers(ctx) {
   shutdownContext = ctx;
   interruptCount = 0;
@@ -8632,7 +8709,6 @@ Interrupted. Saving state...
 `);
       }
     }
-    cleanupActiveSandboxes();
     shutdownContext?.onShutdown?.();
     if (interruptTimer)
       clearTimeout(interruptTimer);
@@ -8660,18 +8736,17 @@ Interrupted. Saving state...
     }
   };
 }
-var shutdownRegistered = false, shutdownContext = null, interruptCount = 0, interruptTimer = null, activeSandboxes;
+var shutdownRegistered = false, shutdownContext = null, interruptCount = 0, interruptTimer = null;
 var init_shutdown = __esm(() => {
   init_run_state();
-  activeSandboxes = new Set;
 });
 
 // src/core/worktree.ts
-import { execSync as execSync13 } from "node:child_process";
+import { execSync as execSync12 } from "node:child_process";
 import { existsSync as existsSync17, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
 import { join as join17 } from "node:path";
 function git3(args, cwd) {
-  return execSync13(`git ${args}`, {
+  return execSync12(`git ${args}`, {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
@@ -8696,7 +8771,7 @@ function generateBranchName(issueNumber) {
 }
 function getWorktreeBranch(worktreePath) {
   try {
-    return execSync13("git branch --show-current", {
+    return execSync12("git branch --show-current", {
       cwd: worktreePath,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8821,7 +8896,7 @@ var exports_run = {};
 __export(exports_run, {
   runCommand: () => runCommand
 });
-import { execSync as execSync14 } from "node:child_process";
+import { execSync as execSync13 } from "node:child_process";
 function resolveExecutionContext(config, modelOverride) {
   const model = modelOverride ?? config.ai.model;
   const provider = inferProviderFromModel(model) ?? config.ai.provider;
@@ -8972,7 +9047,7 @@ ${yellow("⚠")} A sprint run is already in progress.
   }
   if (!flags.dryRun) {
     try {
-      execSync14(`git checkout -B ${branchName}`, {
+      execSync13(`git checkout -B ${branchName}`, {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -9022,7 +9097,7 @@ ${red("✗")} Auto-rebase failed. Resolve manually.
     let sprintContext;
     if (i > 0 && !flags.dryRun) {
       try {
-        sprintContext = execSync14(`git diff origin/${config.agent.baseBranch}..HEAD`, {
+        sprintContext = execSync13(`git diff origin/${config.agent.baseBranch}..HEAD`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9087,7 +9162,7 @@ ${bold("Summary:")}
     const prNumber = await createSprintPR(projectRoot, config, sprintName, branchName, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync14(`git checkout ${config.agent.baseBranch}`, {
+        execSync13(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9287,13 +9362,13 @@ ${bold("Resuming")} ${state.type} run ${dim(state.runId)}
 `);
   if (state.type === "sprint" && state.branch) {
     try {
-      const currentBranch = execSync14("git rev-parse --abbrev-ref HEAD", {
+      const currentBranch = execSync13("git rev-parse --abbrev-ref HEAD", {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
       }).trim();
       if (currentBranch !== state.branch) {
-        execSync14(`git checkout ${state.branch}`, {
+        execSync13(`git checkout ${state.branch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9360,7 +9435,7 @@ ${bold("Resume complete:")} ${green(`✓ ${finalStats.done}`)} ${finalStats.fail
     const prNumber = await createSprintPR(projectRoot, config, state.sprint, state.branch, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync14(`git checkout ${config.agent.baseBranch}`, {
+        execSync13(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9391,14 +9466,14 @@ function getOrder2(issue) {
 }
 function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
   try {
-    const status = execSync14("git status --porcelain", {
+    const status = execSync13("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
     if (!status)
       return;
-    execSync14("git add -A", {
+    execSync13("git add -A", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -9406,7 +9481,7 @@ function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
     const message = `chore: complete #${issueNumber} - ${issueTitle}
 
 Co-Authored-By: LocusAgent <agent@locusai.team>`;
-    execSync14(`git commit -F -`, {
+    execSync13(`git commit -F -`, {
       input: message,
       cwd: projectRoot,
       encoding: "utf-8",
@@ -9420,7 +9495,7 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
   if (!config.agent.autoPR)
     return;
   try {
-    const diff = execSync14(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
+    const diff = execSync13(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -9430,7 +9505,7 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
 `);
       return;
     }
-    execSync14(`git push -u origin ${branchName}`, {
+    execSync13(`git push -u origin ${branchName}`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -10208,7 +10283,7 @@ var exports_review = {};
 __export(exports_review, {
   reviewCommand: () => reviewCommand
 });
-import { execSync as execSync15 } from "node:child_process";
+import { execSync as execSync14 } from "node:child_process";
 import { existsSync as existsSync19, readFileSync as readFileSync14 } from "node:fs";
 import { join as join19 } from "node:path";
 function printHelp2() {
@@ -10286,7 +10361,7 @@ ${bold("Review complete:")} ${green(`✓ ${reviewed}`)}${failed > 0 ? ` ${red(`
 async function reviewSinglePR(projectRoot, config, prNumber, focus, flags) {
   let prInfo;
   try {
-    const result = execSync15(`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 = execSync14(`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,
@@ -10352,7 +10427,7 @@ ${output.slice(0, 60000)}
 
 ---
 _Reviewed by Locus AI (${config.ai.provider}/${flags.model ?? config.ai.model})_`;
-      execSync15(`gh pr comment ${pr.number} --body ${JSON.stringify(reviewBody)}`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+      execSync14(`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) {
@@ -10432,7 +10507,7 @@ var exports_iterate = {};
 __export(exports_iterate, {
   iterateCommand: () => iterateCommand
 });
-import { execSync as execSync16 } from "node:child_process";
+import { execSync as execSync15 } from "node:child_process";
 function printHelp3() {
   process.stderr.write(`
 ${bold("locus iterate")} — Re-execute tasks with PR feedback
@@ -10642,12 +10717,12 @@ ${bold("Summary:")} ${green(`✓ ${succeeded}`)}${failed > 0 ? ` ${red(`✗ ${fa
 }
 function findPRForIssue(projectRoot, issueNumber) {
   try {
-    const result = execSync16(`gh pr list --search "Closes #${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const result = execSync15(`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 = execSync16(`gh pr list --head "locus/issue-${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const branchResult = execSync15(`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;
@@ -11266,9 +11341,10 @@ __export(exports_sandbox2, {
   parseSandboxInstallArgs: () => parseSandboxInstallArgs,
   parseSandboxExecArgs: () => parseSandboxExecArgs
 });
-import { execSync as execSync17, spawn as spawn6 } from "node:child_process";
+import { execSync as execSync16, spawn as spawn6 } from "node:child_process";
 import { createHash } from "node:crypto";
-import { basename as basename4 } from "node:path";
+import { existsSync as existsSync22, readFileSync as readFileSync17 } from "node:fs";
+import { basename as basename4, join as join22 } from "node:path";
 function printSandboxHelp() {
   process.stderr.write(`
 ${bold("locus sandbox")} — Manage Docker sandbox lifecycle
@@ -11277,15 +11353,15 @@ ${bold("Usage:")}
   locus sandbox                     ${dim("# Create claude/codex sandboxes and enable sandbox mode")}
   locus sandbox claude              ${dim("# Run claude interactively (for login)")}
   locus sandbox codex               ${dim("# Run codex interactively (for login)")}
+  locus sandbox setup               ${dim("# Re-run dependency install in sandbox(es)")}
   locus sandbox install <pkg>       ${dim("# npm install -g package(s) in sandbox(es)")}
-  locus sandbox exec <provider> -- <cmd...> ${dim("# Run one command inside provider sandbox")}
   locus sandbox shell <provider>    ${dim("# Open interactive shell in provider sandbox")}
   locus sandbox logs <provider>     ${dim("# Show provider sandbox logs")}
   locus sandbox rm                  ${dim("# Destroy all provider sandboxes and disable sandbox mode")}
   locus sandbox status              ${dim("# Show current sandbox state")}
 
 ${bold("Flow:")}
-  1. ${cyan("locus sandbox")}          Create provider sandboxes
+  1. ${cyan("locus sandbox")}          Create sandboxes (auto-installs dependencies)
   2. ${cyan("locus sandbox claude")}   Login Claude inside its sandbox
   3. ${cyan("locus sandbox codex")}    Login Codex inside its sandbox
   4. ${cyan("locus sandbox install bun")}  Install extra tools (optional)
@@ -11301,10 +11377,10 @@ async function sandboxCommand(projectRoot, args) {
     case "claude":
     case "codex":
       return handleAgentLogin(projectRoot, subcommand);
+    case "setup":
+      return handleSetup(projectRoot);
     case "install":
       return handleInstall(projectRoot, args.slice(1));
-    case "exec":
-      return handleExec(projectRoot, args.slice(1));
     case "shell":
       return handleShell(projectRoot, args.slice(1));
     case "logs":
@@ -11318,7 +11394,7 @@ async function sandboxCommand(projectRoot, args) {
     default:
       process.stderr.write(`${red("✗")} Unknown sandbox subcommand: ${bold(subcommand)}
 `);
-      process.stderr.write(`  Available: ${cyan("claude")}, ${cyan("codex")}, ${cyan("install")}, ${cyan("exec")}, ${cyan("shell")}, ${cyan("logs")}, ${cyan("rm")}, ${cyan("status")}
+      process.stderr.write(`  Available: ${cyan("claude")}, ${cyan("codex")}, ${cyan("setup")}, ${cyan("install")}, ${cyan("exec")}, ${cyan("shell")}, ${cyan("logs")}, ${cyan("rm")}, ${cyan("status")}
 `);
   }
 }
@@ -11334,14 +11410,14 @@ async function handleCreate(projectRoot) {
   }
   const sandboxNames = buildProviderSandboxNames(projectRoot);
   const readySandboxes = {};
+  const newlyCreated = new Set;
   let failed = false;
-  for (const provider of PROVIDERS) {
+  const createResults = await Promise.all(PROVIDERS.map(async (provider) => {
     const name = sandboxNames[provider];
     if (isSandboxAlive(name)) {
       process.stderr.write(`${green("✓")} ${provider} sandbox ready: ${bold(name)}
 `);
-      readySandboxes[provider] = name;
-      continue;
+      return { provider, name, created: false, existed: true };
     }
     process.stderr.write(`Creating ${bold(provider)} sandbox ${dim(name)} with workspace ${dim(projectRoot)}...
 `);
@@ -11349,16 +11425,28 @@ async function handleCreate(projectRoot) {
     if (!created) {
       process.stderr.write(`${red("✗")} Failed to create ${provider} sandbox (${name}).
 `);
-      failed = true;
-      continue;
+      return { provider, name, created: false, existed: false };
     }
     process.stderr.write(`${green("✓")} ${provider} sandbox created: ${bold(name)}
 `);
-    readySandboxes[provider] = name;
+    return { provider, name, created: true, existed: false };
+  }));
+  for (const result of createResults) {
+    if (result.created || result.existed) {
+      readySandboxes[result.provider] = result.name;
+      if (result.created)
+        newlyCreated.add(result.name);
+    } else {
+      failed = true;
+    }
   }
   config.sandbox.enabled = true;
   config.sandbox.providers = readySandboxes;
   saveConfig(projectRoot, config);
+  await Promise.all(PROVIDERS.filter((provider) => {
+    const sandboxName = readySandboxes[provider];
+    return sandboxName && newlyCreated.has(sandboxName);
+  }).map((provider) => runSandboxSetup(readySandboxes[provider], projectRoot)));
   if (failed) {
     process.stderr.write(`
 ${yellow("⚠")} Some sandboxes failed to create. Re-run ${cyan("locus sandbox")} after resolving Docker issues.
@@ -11432,7 +11520,7 @@ function handleRemove(projectRoot) {
     process.stderr.write(`Removing sandbox ${bold(sandboxName)}...
 `);
     try {
-      execSync17(`docker sandbox rm ${sandboxName}`, {
+      execSync16(`docker sandbox rm ${sandboxName}`, {
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"],
         timeout: 15000
@@ -11607,26 +11695,6 @@ function parseSandboxExecArgs(args) {
   }
   return { provider, command };
 }
-async function handleExec(projectRoot, args) {
-  const parsed = parseSandboxExecArgs(args);
-  if (parsed.error || !parsed.provider) {
-    process.stderr.write(`${red("✗")} ${parsed.error}
-`);
-    return;
-  }
-  const sandboxName = getActiveProviderSandbox(projectRoot, parsed.provider);
-  if (!sandboxName) {
-    return;
-  }
-  await runInteractiveCommand("docker", [
-    "sandbox",
-    "exec",
-    "-w",
-    projectRoot,
-    sandboxName,
-    ...parsed.command
-  ]);
-}
 async function handleShell(projectRoot, args) {
   const provider = args[0];
   if (provider !== "claude" && provider !== "codex") {
@@ -11724,6 +11792,104 @@ async function handleLogs(projectRoot, args) {
   dockerArgs.push(sandboxName);
   await runInteractiveCommand("docker", dockerArgs);
 }
+function detectPackageManager(projectRoot) {
+  try {
+    const raw = readFileSync17(join22(projectRoot, "package.json"), "utf-8");
+    const pkgJson = JSON.parse(raw);
+    if (typeof pkgJson.packageManager === "string") {
+      const name = pkgJson.packageManager.split("@")[0];
+      if (name === "bun" || name === "npm" || name === "yarn" || name === "pnpm") {
+        return name;
+      }
+    }
+  } catch {}
+  if (existsSync22(join22(projectRoot, "bun.lock")) || existsSync22(join22(projectRoot, "bun.lockb"))) {
+    return "bun";
+  }
+  if (existsSync22(join22(projectRoot, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync22(join22(projectRoot, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  return "npm";
+}
+function getInstallCommand(pm) {
+  switch (pm) {
+    case "bun":
+      return ["bun", "install"];
+    case "yarn":
+      return ["yarn", "install"];
+    case "pnpm":
+      return ["pnpm", "install"];
+    case "npm":
+      return ["npm", "install"];
+  }
+}
+async function runSandboxSetup(sandboxName, projectRoot) {
+  const pm = detectPackageManager(projectRoot);
+  if (pm !== "npm") {
+    await ensurePackageManagerInSandbox(sandboxName, pm);
+  }
+  const installCmd = getInstallCommand(pm);
+  process.stderr.write(`
+Installing dependencies (${bold(installCmd.join(" "))}) in sandbox ${dim(sandboxName)}...
+`);
+  const installOk = await runInteractiveCommand("docker", [
+    "sandbox",
+    "exec",
+    "-w",
+    projectRoot,
+    sandboxName,
+    ...installCmd
+  ]);
+  if (!installOk) {
+    process.stderr.write(`${red("✗")} Dependency install failed in sandbox ${dim(sandboxName)}.
+`);
+    return false;
+  }
+  process.stderr.write(`${green("✓")} Dependencies installed in sandbox ${dim(sandboxName)}.
+`);
+  const setupScript = join22(projectRoot, ".locus", "sandbox-setup.sh");
+  if (existsSync22(setupScript)) {
+    process.stderr.write(`Running ${bold(".locus/sandbox-setup.sh")} in sandbox ${dim(sandboxName)}...
+`);
+    const hookOk = await runInteractiveCommand("docker", [
+      "sandbox",
+      "exec",
+      "-w",
+      projectRoot,
+      sandboxName,
+      "sh",
+      setupScript
+    ]);
+    if (!hookOk) {
+      process.stderr.write(`${yellow("⚠")} Setup hook failed in sandbox ${dim(sandboxName)}.
+`);
+    }
+  }
+  return true;
+}
+async function handleSetup(projectRoot) {
+  const config = loadConfig(projectRoot);
+  const providers = config.sandbox.providers;
+  if (!providers.claude && !providers.codex) {
+    process.stderr.write(`${red("✗")} No sandboxes configured. Run ${cyan("locus sandbox")} first.
+`);
+    return;
+  }
+  for (const provider of PROVIDERS) {
+    const sandboxName = providers[provider];
+    if (!sandboxName)
+      continue;
+    if (!isSandboxAlive(sandboxName)) {
+      process.stderr.write(`${yellow("⚠")} ${provider} sandbox is not running: ${dim(sandboxName)}
+`);
+      continue;
+    }
+    await runSandboxSetup(sandboxName, projectRoot);
+  }
+}
 function buildProviderSandboxNames(projectRoot) {
   const segment = sanitizeSegment(basename4(projectRoot));
   const hash = createHash("sha1").update(projectRoot).digest("hex").slice(0, 8);
@@ -11768,7 +11934,7 @@ function runInteractiveCommand(command, args) {
 }
 async function createProviderSandbox(provider, sandboxName, projectRoot) {
   try {
-    execSync17(`docker sandbox run --name ${sandboxName} claude ${projectRoot} -- --version`, {
+    execSync16(`docker sandbox create --name ${sandboxName} claude ${projectRoot}`, {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 120000
     });
@@ -11782,9 +11948,30 @@ async function createProviderSandbox(provider, sandboxName, projectRoot) {
   await enforceSandboxIgnore(sandboxName, projectRoot);
   return true;
 }
+async function ensurePackageManagerInSandbox(sandboxName, pm) {
+  try {
+    execSync16(`docker sandbox exec ${sandboxName} which ${pm}`, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000
+    });
+  } catch {
+    const npmPkg = pm === "bun" ? "bun" : pm === "yarn" ? "yarn" : "pnpm";
+    process.stderr.write(`Installing ${bold(pm)} in sandbox...
+`);
+    try {
+      execSync16(`docker sandbox exec ${sandboxName} npm install -g ${npmPkg}`, {
+        stdio: "inherit",
+        timeout: 120000
+      });
+    } catch {
+      process.stderr.write(`${yellow("⚠")} Failed to install ${pm} in sandbox. Dependency install may fail.
+`);
+    }
+  }
+}
 async function ensureCodexInSandbox(sandboxName) {
   try {
-    execSync17(`docker sandbox exec ${sandboxName} which codex`, {
+    execSync16(`docker sandbox exec ${sandboxName} which codex`, {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000
     });
@@ -11792,7 +11979,7 @@ async function ensureCodexInSandbox(sandboxName) {
     process.stderr.write(`Installing codex in sandbox...
 `);
     try {
-      execSync17(`docker sandbox exec ${sandboxName} npm install -g @openai/codex`, { stdio: "inherit", timeout: 120000 });
+      execSync16(`docker sandbox exec ${sandboxName} npm install -g @openai/codex`, { stdio: "inherit", timeout: 120000 });
     } catch {
       process.stderr.write(`${red("✗")} Failed to install codex in sandbox.
 `);
@@ -11801,7 +11988,7 @@ async function ensureCodexInSandbox(sandboxName) {
 }
 function isSandboxAlive(name) {
   try {
-    const output = execSync17("docker sandbox ls", {
+    const output = execSync16("docker sandbox ls", {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000
@@ -11826,17 +12013,17 @@ init_context();
 init_logger();
 init_rate_limiter();
 init_terminal();
-import { existsSync as existsSync22, readFileSync as readFileSync17 } from "node:fs";
-import { join as join22 } from "node:path";
+import { existsSync as existsSync23, readFileSync as readFileSync18 } from "node:fs";
+import { join as join23 } from "node:path";
 import { fileURLToPath } from "node:url";
 function getCliVersion() {
   const fallbackVersion = "0.0.0";
-  const packageJsonPath = join22(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
-  if (!existsSync22(packageJsonPath)) {
+  const packageJsonPath = join23(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
+  if (!existsSync23(packageJsonPath)) {
     return fallbackVersion;
   }
   try {
-    const parsed = JSON.parse(readFileSync17(packageJsonPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync18(packageJsonPath, "utf-8"));
     return parsed.version ?? fallbackVersion;
   } catch {
     return fallbackVersion;
@@ -11950,9 +12137,41 @@ function parseArgs(argv) {
   const args = positional.slice(1);
   return { command, args, flags };
 }
+var LOCUS_LOGO2 = [
+  "    ▄█                  ",
+  "▄▄████▄▄▄▄              ",
+  "████▀ ████              ",
+  "████▄▄████              ",
+  "▀█▄█▀███▀▀ ▄▄██▄▄       ",
+  "████    ▄██████▀███▄    ",
+  "████▄██▀ ▀▀███ ▄████    ",
+  "▀▀██████▄    ██████▀    ",
+  "    ▀▀█████▄▄██▀▀       ",
+  "       ▀▀██▀▀           "
+];
+function printLogo() {
+  process.stderr.write(`
+`);
+  const logoWidth = 10;
+  const gap = "    ";
+  const infoLines = [
+    `${bold("Locus")} ${dim(`v${VERSION}`)}`,
+    `${dim("GitHub-native AI engineering assistant")}`
+  ];
+  const textOffset = 1;
+  const totalLines = Math.max(LOCUS_LOGO2.length, infoLines.length + textOffset);
+  for (let i = 0;i < totalLines; i++) {
+    const logoLine = LOCUS_LOGO2[i] ?? "";
+    const paddedLogo = logoLine.padEnd(logoWidth);
+    const infoIdx = i - textOffset;
+    const infoLine = infoIdx >= 0 && infoIdx < infoLines.length ? infoLines[infoIdx] : "";
+    process.stderr.write(`${bold(white(paddedLogo))}${gap}${infoLine}
+`);
+  }
+}
 function printHelp6() {
+  printLogo();
   process.stderr.write(`
-${bold("Locus")} ${dim(`v${VERSION}`)} — GitHub-native AI engineering assistant
 
 ${bold("Usage:")}
   locus <command> [options]
@@ -12065,7 +12284,7 @@ async function main() {
     try {
       const root = getGitRoot(cwd);
       if (isInitialized(root)) {
-        logDir = join22(root, ".locus", "logs");
+        logDir = join23(root, ".locus", "logs");
         getRateLimiter(root);
       }
     } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locusai/cli",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "GitHub-native AI engineering assistant",
   "type": "module",
   "bin": {