@locusai/cli 0.20.1 → 0.20.2

package/bin/locus.js

@@ -1280,6 +1280,177 @@ var init_version_check = __esm(() => {
   CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 });
 
+// src/core/ecosystem.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join5 } from "node:path";
+function detectProjectEcosystem(projectRoot) {
+  for (const signal of ECOSYSTEM_SIGNALS) {
+    for (const marker of signal.markers) {
+      if (marker.startsWith("*")) {
+        continue;
+      }
+      if (existsSync5(join5(projectRoot, marker))) {
+        return signal.ecosystem;
+      }
+    }
+  }
+  return "unknown";
+}
+function isJavaScriptEcosystem(ecosystem) {
+  return ecosystem === "javascript";
+}
+function generateSandboxSetupTemplate(ecosystem) {
+  switch (ecosystem) {
+    case "javascript":
+      return null;
+    case "rust":
+      return `#!/bin/sh
+# Sandbox setup for Rust projects
+# This script runs inside the Docker sandbox after creation.
+# Uncomment or modify the commands below for your project.
+
+# Install Rust toolchain (if not pre-installed)
+# curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+# . "$HOME/.cargo/env"
+
+# Build the project
+# cargo build
+
+echo "Rust sandbox setup complete"
+`;
+    case "go":
+      return `#!/bin/sh
+# Sandbox setup for Go projects
+# This script runs inside the Docker sandbox after creation.
+
+# Download dependencies
+# go mod download
+
+# Build the project
+# go build ./...
+
+echo "Go sandbox setup complete"
+`;
+    case "python":
+      return `#!/bin/sh
+# Sandbox setup for Python projects
+# This script runs inside the Docker sandbox after creation.
+
+# Create virtual environment and install dependencies
+# python3 -m venv .venv
+# . .venv/bin/activate
+# pip install -r requirements.txt
+# OR: pip install -e .
+
+echo "Python sandbox setup complete"
+`;
+    case "java":
+      return `#!/bin/sh
+# Sandbox setup for Java/JVM projects
+# This script runs inside the Docker sandbox after creation.
+
+# Maven
+# mvn install -DskipTests
+
+# Gradle
+# ./gradlew build -x test
+
+echo "Java sandbox setup complete"
+`;
+    case "ruby":
+      return `#!/bin/sh
+# Sandbox setup for Ruby projects
+# This script runs inside the Docker sandbox after creation.
+
+# Install dependencies
+# bundle install
+
+echo "Ruby sandbox setup complete"
+`;
+    case "elixir":
+      return `#!/bin/sh
+# Sandbox setup for Elixir projects
+# This script runs inside the Docker sandbox after creation.
+
+# Install dependencies
+# mix deps.get
+# mix compile
+
+echo "Elixir sandbox setup complete"
+`;
+    case "dotnet":
+      return `#!/bin/sh
+# Sandbox setup for .NET projects
+# This script runs inside the Docker sandbox after creation.
+
+# Restore packages
+# dotnet restore
+
+# Build
+# dotnet build
+
+echo ".NET sandbox setup complete"
+`;
+    case "unknown":
+      return `#!/bin/sh
+# Sandbox setup script
+# This script runs inside the Docker sandbox after creation.
+# Add any commands needed to prepare the build environment.
+
+# Example: install system dependencies
+# apt-get update && apt-get install -y <packages>
+
+# Example: install project dependencies
+# <your-package-manager> install
+
+echo "Sandbox setup complete"
+`;
+  }
+}
+var ECOSYSTEM_SIGNALS;
+var init_ecosystem = __esm(() => {
+  ECOSYSTEM_SIGNALS = [
+    {
+      ecosystem: "javascript",
+      markers: ["package.json"]
+    },
+    {
+      ecosystem: "rust",
+      markers: ["Cargo.toml"]
+    },
+    {
+      ecosystem: "go",
+      markers: ["go.mod"]
+    },
+    {
+      ecosystem: "python",
+      markers: [
+        "pyproject.toml",
+        "setup.py",
+        "setup.cfg",
+        "Pipfile",
+        "requirements.txt"
+      ]
+    },
+    {
+      ecosystem: "java",
+      markers: ["pom.xml", "build.gradle", "build.gradle.kts"]
+    },
+    {
+      ecosystem: "ruby",
+      markers: ["Gemfile"]
+    },
+    {
+      ecosystem: "elixir",
+      markers: ["mix.exs"]
+    },
+    {
+      ecosystem: "dotnet",
+      markers: ["*.csproj", "*.fsproj", "*.sln"]
+    }
+  ];
+});
+
 // src/core/github.ts
 import {
   execFileSync,
@@ -1476,7 +1647,18 @@ function reopenMilestone(owner, repo, milestoneNumber, options = {}) {
   gh(`api repos/${owner}/${repo}/milestones/${milestoneNumber} -X PATCH -f state=open`, options);
 }
 function createPR(title, body, head, base, options = {}) {
-  const result = ghExec(["pr", "create", "--title", title, "--body", body, "--head", head, "--base", base], options);
+  const result = ghExec([
+    "pr",
+    "create",
+    "--title",
+    title,
+    "--body",
+    body,
+    "--head",
+    head,
+    "--base",
+    base
+  ], options);
   const match = result.match(/\/pull\/(\d+)/);
   if (!match) {
     throw new Error(`Could not extract PR number from: ${result}`);
@@ -1630,8 +1812,8 @@ var exports_init = {};
 __export(exports_init, {
   initCommand: () => initCommand
 });
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join6 } from "node:path";
 async function initCommand(cwd) {
   const log = getLogger();
   process.stderr.write(`
@@ -1675,17 +1857,17 @@ ${bold("Initializing Locus...")}
   }
   process.stderr.write(`${green("✓")} Repository: ${bold(`${context.owner}/${context.repo}`)} (branch: ${context.defaultBranch})
 `);
-  const locusDir = join5(cwd, ".locus");
+  const locusDir = join6(cwd, ".locus");
   const dirs = [
     locusDir,
-    join5(locusDir, "sessions"),
-    join5(locusDir, "discussions"),
-    join5(locusDir, "artifacts"),
-    join5(locusDir, "plans"),
-    join5(locusDir, "logs")
+    join6(locusDir, "sessions"),
+    join6(locusDir, "discussions"),
+    join6(locusDir, "artifacts"),
+    join6(locusDir, "plans"),
+    join6(locusDir, "logs")
   ];
   for (const dir of dirs) {
-    if (!existsSync5(dir)) {
+    if (!existsSync6(dir)) {
       mkdirSync5(dir, { recursive: true });
     }
   }
@@ -1706,7 +1888,7 @@ ${bold("Initializing Locus...")}
   };
   if (isReInit) {
     try {
-      const existing = JSON.parse(readFileSync4(join5(locusDir, "config.json"), "utf-8"));
+      const existing = JSON.parse(readFileSync4(join6(locusDir, "config.json"), "utf-8"));
       if (existing.ai)
         config.ai = { ...config.ai, ...existing.ai };
       if (existing.agent)
@@ -1725,8 +1907,8 @@ ${bold("Initializing Locus...")}
 `);
   }
   saveConfig(cwd, config);
-  const locusMdPath = join5(locusDir, "LOCUS.md");
-  if (!existsSync5(locusMdPath)) {
+  const locusMdPath = join6(locusDir, "LOCUS.md");
+  if (!existsSync6(locusMdPath)) {
     writeFileSync4(locusMdPath, LOCUS_MD_TEMPLATE, "utf-8");
     process.stderr.write(`${green("✓")} Generated LOCUS.md (edit to add project context)
 `);
@@ -1734,8 +1916,8 @@ ${bold("Initializing Locus...")}
     process.stderr.write(`${dim("○")} LOCUS.md already exists (preserved)
 `);
   }
-  const learningsMdPath = join5(locusDir, "LEARNINGS.md");
-  if (!existsSync5(learningsMdPath)) {
+  const learningsMdPath = join6(locusDir, "LEARNINGS.md");
+  if (!existsSync6(learningsMdPath)) {
     writeFileSync4(learningsMdPath, LEARNINGS_MD_TEMPLATE, "utf-8");
     process.stderr.write(`${green("✓")} Generated LEARNINGS.md
 `);
@@ -1743,13 +1925,29 @@ ${bold("Initializing Locus...")}
     process.stderr.write(`${dim("○")} LEARNINGS.md already exists (preserved)
 `);
   }
-  const sandboxIgnorePath = join5(cwd, ".sandboxignore");
-  if (!existsSync5(sandboxIgnorePath)) {
+  const sandboxIgnorePath = join6(cwd, ".sandboxignore");
+  if (!existsSync6(sandboxIgnorePath)) {
     writeFileSync4(sandboxIgnorePath, SANDBOXIGNORE_TEMPLATE, "utf-8");
     process.stderr.write(`${green("✓")} Generated .sandboxignore
 `);
   } else {
     process.stderr.write(`${dim("○")} .sandboxignore already exists (preserved)
+`);
+  }
+  const ecosystem = detectProjectEcosystem(cwd);
+  const sandboxSetupPath = join6(locusDir, "sandbox-setup.sh");
+  if (!existsSync6(sandboxSetupPath)) {
+    const template = generateSandboxSetupTemplate(ecosystem);
+    if (template) {
+      writeFileSync4(sandboxSetupPath, template, {
+        encoding: "utf-8",
+        mode: 493
+      });
+      process.stderr.write(`${green("✓")} Generated .locus/sandbox-setup.sh (${ecosystem} project detected)
+`);
+    }
+  } else {
+    process.stderr.write(`${dim("○")} sandbox-setup.sh already exists (preserved)
 `);
   }
   process.stderr.write(`${cyan("●")} Creating GitHub labels...`);
@@ -1761,9 +1959,9 @@ ${bold("Initializing Locus...")}
     process.stderr.write(`\r${yellow("⚠")} Some labels could not be created: ${e.message}
 `);
   }
-  const gitignorePath = join5(cwd, ".gitignore");
+  const gitignorePath = join6(cwd, ".gitignore");
   let gitignoreContent = "";
-  if (existsSync5(gitignorePath)) {
+  if (existsSync6(gitignorePath)) {
     gitignoreContent = readFileSync4(gitignorePath, "utf-8");
   }
   const entriesToAdd = GITIGNORE_ENTRIES.filter((entry) => entry && !gitignoreContent.includes(entry.trim()));
@@ -1996,6 +2194,7 @@ It is read by AI agents before every task to avoid repeating mistakes and to fol
 var init_init = __esm(() => {
   init_config();
   init_context();
+  init_ecosystem();
   init_github();
   init_logger();
   init_terminal();
@@ -2017,33 +2216,33 @@ var init_init = __esm(() => {
 
 // src/packages/registry.ts
 import {
-  existsSync as existsSync6,
+  existsSync as existsSync7,
   mkdirSync as mkdirSync6,
   readFileSync as readFileSync5,
   renameSync,
   writeFileSync as writeFileSync5
 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function getPackagesDir() {
   const home = process.env.HOME || homedir2();
-  const dir = join6(home, ".locus", "packages");
-  if (!existsSync6(dir)) {
+  const dir = join7(home, ".locus", "packages");
+  if (!existsSync7(dir)) {
     mkdirSync6(dir, { recursive: true });
   }
-  const pkgJson = join6(dir, "package.json");
-  if (!existsSync6(pkgJson)) {
+  const pkgJson = join7(dir, "package.json");
+  if (!existsSync7(pkgJson)) {
     writeFileSync5(pkgJson, `${JSON.stringify({ private: true }, null, 2)}
 `, "utf-8");
   }
   return dir;
 }
 function getRegistryPath() {
-  return join6(getPackagesDir(), "registry.json");
+  return join7(getPackagesDir(), "registry.json");
 }
 function loadRegistry() {
   const registryPath = getRegistryPath();
-  if (!existsSync6(registryPath)) {
+  if (!existsSync7(registryPath)) {
     return { packages: {} };
   }
   try {
@@ -2066,8 +2265,8 @@ function saveRegistry(registry) {
 }
 function resolvePackageBinary(packageName) {
   const fullName = normalizePackageName(packageName);
-  const binPath = join6(getPackagesDir(), "node_modules", ".bin", fullName);
-  return existsSync6(binPath) ? binPath : null;
+  const binPath = join7(getPackagesDir(), "node_modules", ".bin", fullName);
+  return existsSync7(binPath) ? binPath : null;
 }
 function normalizePackageName(input) {
   if (input.startsWith("@")) {
@@ -2087,7 +2286,7 @@ __export(exports_pkg, {
   listInstalledPackages: () => listInstalledPackages
 });
 import { spawn } from "node:child_process";
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync8 } from "node:fs";
 function listInstalledPackages() {
   const registry = loadRegistry();
   const entries = Object.values(registry.packages);
@@ -2165,7 +2364,7 @@ async function pkgCommand(args, _flags) {
     return;
   }
   const binaryPath = entry.binaryPath;
-  if (!binaryPath || !existsSync7(binaryPath)) {
+  if (!binaryPath || !existsSync8(binaryPath)) {
     process.stderr.write(`${red("✗")} Binary for ${bold(packageName)} not found on disk.
 `);
     if (binaryPath) {
@@ -2291,8 +2490,8 @@ __export(exports_install, {
   installCommand: () => installCommand
 });
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+import { join as join8 } from "node:path";
 function parsePackageArg(raw) {
   if (raw.startsWith("@")) {
     const slashIdx = raw.indexOf("/");
@@ -2369,8 +2568,8 @@ ${red("✗")} Failed to install ${bold(packageSpec)}.
     process.exit(1);
     return;
   }
-  const installedPkgJsonPath = join7(packagesDir, "node_modules", packageName, "package.json");
-  if (!existsSync8(installedPkgJsonPath)) {
+  const installedPkgJsonPath = join8(packagesDir, "node_modules", packageName, "package.json");
+  if (!existsSync9(installedPkgJsonPath)) {
     process.stderr.write(`
 ${red("✗")} Package installed but package.json not found at:
 `);
@@ -2645,16 +2844,16 @@ __export(exports_logs, {
   logsCommand: () => logsCommand
 });
 import {
-  existsSync as existsSync9,
+  existsSync as existsSync10,
   readdirSync as readdirSync2,
   readFileSync as readFileSync7,
   statSync as statSync2,
   unlinkSync as unlinkSync2
 } from "node:fs";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 async function logsCommand(cwd, options) {
-  const logsDir = join8(cwd, ".locus", "logs");
-  if (!existsSync9(logsDir)) {
+  const logsDir = join9(cwd, ".locus", "logs");
+  if (!existsSync10(logsDir)) {
     process.stderr.write(`${dim("No logs found.")}
 `);
     return;
@@ -2709,8 +2908,8 @@ async function tailLog(logFile, levelFilter) {
   process.stderr.write(`${bold("Tailing:")} ${dim(logFile)} ${dim("(Ctrl+C to stop)")}
 
 `);
-  let lastSize = existsSync9(logFile) ? statSync2(logFile).size : 0;
-  if (existsSync9(logFile)) {
+  let lastSize = existsSync10(logFile) ? statSync2(logFile).size : 0;
+  if (existsSync10(logFile)) {
     const content = readFileSync7(logFile, "utf-8");
     const lines = content.trim().split(`
 `).filter(Boolean);
@@ -2729,7 +2928,7 @@ async function tailLog(logFile, levelFilter) {
   }
   return new Promise((resolve) => {
     const interval = setInterval(() => {
-      if (!existsSync9(logFile))
+      if (!existsSync10(logFile))
         return;
       const currentSize = statSync2(logFile).size;
       if (currentSize <= lastSize)
@@ -2789,7 +2988,7 @@ function cleanLogs(logsDir) {
 `);
 }
 function getLogFiles(logsDir) {
-  return readdirSync2(logsDir).filter((f) => f.startsWith("locus-") && f.endsWith(".log")).map((f) => join8(logsDir, f)).sort((a, b) => statSync2(b).mtimeMs - statSync2(a).mtimeMs);
+  return readdirSync2(logsDir).filter((f) => f.startsWith("locus-") && f.endsWith(".log")).map((f) => join9(logsDir, f)).sort((a, b) => statSync2(b).mtimeMs - statSync2(a).mtimeMs);
 }
 function formatEntry(entry) {
   const time = dim(new Date(entry.ts).toLocaleTimeString());
@@ -3099,9 +3298,9 @@ var init_stream_renderer = __esm(() => {
 
 // src/repl/clipboard.ts
 import { execSync as execSync4 } from "node:child_process";
-import { existsSync as existsSync10, mkdirSync as mkdirSync7 } from "node:fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync7 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 function readClipboardImage() {
   if (process.platform === "darwin") {
     return readMacOSClipboardImage();
@@ -3112,14 +3311,14 @@ function readClipboardImage() {
   return null;
 }
 function ensureStableDir() {
-  if (!existsSync10(STABLE_DIR)) {
+  if (!existsSync11(STABLE_DIR)) {
     mkdirSync7(STABLE_DIR, { recursive: true });
   }
 }
 function readMacOSClipboardImage() {
   try {
     ensureStableDir();
-    const destPath = join9(STABLE_DIR, `clipboard-${Date.now()}.png`);
+    const destPath = join10(STABLE_DIR, `clipboard-${Date.now()}.png`);
     const script = [
       `set destPath to POSIX file "${destPath}"`,
       "try",
@@ -3143,7 +3342,7 @@ function readMacOSClipboardImage() {
       timeout: 5000,
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    if (result === "ok" && existsSync10(destPath)) {
+    if (result === "ok" && existsSync11(destPath)) {
       return destPath;
     }
   } catch {}
@@ -3156,9 +3355,9 @@ function readLinuxClipboardImage() {
       return null;
     }
     ensureStableDir();
-    const destPath = join9(STABLE_DIR, `clipboard-${Date.now()}.png`);
+    const destPath = join10(STABLE_DIR, `clipboard-${Date.now()}.png`);
     execSync4(`xclip -selection clipboard -t image/png -o > "${destPath}" 2>/dev/null`, { timeout: 5000 });
-    if (existsSync10(destPath)) {
+    if (existsSync11(destPath)) {
       return destPath;
     }
   } catch {}
@@ -3166,13 +3365,13 @@ function readLinuxClipboardImage() {
 }
 var STABLE_DIR;
 var init_clipboard = __esm(() => {
-  STABLE_DIR = join9(tmpdir(), "locus-images");
+  STABLE_DIR = join10(tmpdir(), "locus-images");
 });
 
 // src/repl/image-detect.ts
-import { copyFileSync, existsSync as existsSync11, mkdirSync as mkdirSync8 } from "node:fs";
+import { copyFileSync, existsSync as existsSync12, mkdirSync as mkdirSync8 } from "node:fs";
 import { homedir as homedir3, tmpdir as tmpdir2 } from "node:os";
-import { basename, extname, join as join10, resolve } from "node:path";
+import { basename, extname, join as join11, resolve } from "node:path";
 function detectImages(input) {
   const detected = [];
   const byResolved = new Map;
@@ -3266,15 +3465,15 @@ function collectReferencedAttachments(input, attachments) {
   return dedupeByResolvedPath(selected);
 }
 function relocateImages(images, projectRoot) {
-  const targetDir = join10(projectRoot, ".locus", "tmp", "images");
+  const targetDir = join11(projectRoot, ".locus", "tmp", "images");
   for (const img of images) {
     if (!img.exists)
       continue;
     try {
-      if (!existsSync11(targetDir)) {
+      if (!existsSync12(targetDir)) {
         mkdirSync8(targetDir, { recursive: true });
       }
-      const dest = join10(targetDir, basename(img.stablePath));
+      const dest = join11(targetDir, basename(img.stablePath));
       copyFileSync(img.stablePath, dest);
       img.stablePath = dest;
     } catch {}
@@ -3286,7 +3485,7 @@ function addIfImage(rawPath, rawMatch, detected, byResolved) {
     return;
   let resolved = stripQuotes(rawPath).replace(/\\ /g, " ");
   if (resolved.startsWith("~/")) {
-    resolved = join10(homedir3(), resolved.slice(2));
+    resolved = join11(homedir3(), resolved.slice(2));
   }
   resolved = resolve(resolved);
   const existing = byResolved.get(resolved);
@@ -3299,7 +3498,7 @@ function addIfImage(rawPath, rawMatch, detected, byResolved) {
     ]);
     return;
   }
-  const exists = existsSync11(resolved);
+  const exists = existsSync12(resolved);
   let stablePath = resolved;
   if (exists) {
     stablePath = copyToStable(resolved);
@@ -3353,10 +3552,10 @@ function dedupeByResolvedPath(images) {
 }
 function copyToStable(sourcePath) {
   try {
-    if (!existsSync11(STABLE_DIR2)) {
+    if (!existsSync12(STABLE_DIR2)) {
       mkdirSync8(STABLE_DIR2, { recursive: true });
     }
-    const dest = join10(STABLE_DIR2, `${Date.now()}-${basename(sourcePath)}`);
+    const dest = join11(STABLE_DIR2, `${Date.now()}-${basename(sourcePath)}`);
     copyFileSync(sourcePath, dest);
     return dest;
   } catch {
@@ -3376,7 +3575,7 @@ var init_image_detect = __esm(() => {
     ".tif",
     ".tiff"
   ]);
-  STABLE_DIR2 = join10(tmpdir2(), "locus-images");
+  STABLE_DIR2 = join11(tmpdir2(), "locus-images");
   PLACEHOLDER_ID_PATTERN = /\(locus:\/\/screenshot-(\d+)\)/g;
 });
 
@@ -4160,10 +4359,7 @@ __export(exports_claude, {
 });
 import { execSync as execSync5, spawn as spawn2 } from "node:child_process";
 function buildClaudeArgs(options) {
-  const args = [
-    "--dangerously-skip-permissions",
-    "--no-session-persistence"
-  ];
+  const args = ["--dangerously-skip-permissions", "--no-session-persistence"];
   if (options.model) {
     args.push("--model", options.model);
   }
@@ -4355,11 +4551,11 @@ var init_claude = __esm(() => {
 
 // src/core/sandbox-ignore.ts
 import { exec } from "node:child_process";
-import { existsSync as existsSync12, readFileSync as readFileSync8 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync13, readFileSync as readFileSync8 } from "node:fs";
+import { join as join12 } from "node:path";
 import { promisify } from "node:util";
 function parseIgnoreFile(filePath) {
-  if (!existsSync12(filePath))
+  if (!existsSync13(filePath))
     return [];
   const content = readFileSync8(filePath, "utf-8");
   const rules = [];
@@ -4406,7 +4602,7 @@ function buildCleanupScript(rules, workspacePath) {
 }
 async function enforceSandboxIgnore(sandboxName, projectRoot) {
   const log = getLogger();
-  const ignorePath = join11(projectRoot, ".sandboxignore");
+  const ignorePath = join12(projectRoot, ".sandboxignore");
   const rules = parseIgnoreFile(ignorePath);
   if (rules.length === 0)
     return;
@@ -6685,8 +6881,8 @@ var init_sprint = __esm(() => {
 
 // src/core/prompt-builder.ts
 import { execSync as execSync7 } from "node:child_process";
-import { existsSync as existsSync13, readdirSync as readdirSync3, readFileSync as readFileSync9 } from "node:fs";
-import { join as join12 } from "node:path";
+import { existsSync as existsSync14, readdirSync as readdirSync3, readFileSync as readFileSync9 } from "node:fs";
+import { join as join13 } from "node:path";
 function buildExecutionPrompt(ctx) {
   const sections = [];
   sections.push(buildSystemContext(ctx.projectRoot));
@@ -6716,13 +6912,13 @@ function buildFeedbackPrompt(ctx) {
 }
 function buildReplPrompt(userMessage, projectRoot, _config, previousMessages) {
   const sections = [];
-  const locusmd = readFileSafe(join12(projectRoot, ".locus", "LOCUS.md"));
+  const locusmd = readFileSafe(join13(projectRoot, ".locus", "LOCUS.md"));
   if (locusmd) {
     sections.push(`<project-instructions>
 ${locusmd}
 </project-instructions>`);
   }
-  const learnings = readFileSafe(join12(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join13(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     sections.push(`<past-learnings>
 ${learnings}
@@ -6748,24 +6944,24 @@ ${userMessage}
 }
 function buildSystemContext(projectRoot) {
   const parts = [];
-  const locusmd = readFileSafe(join12(projectRoot, ".locus", "LOCUS.md"));
+  const locusmd = readFileSafe(join13(projectRoot, ".locus", "LOCUS.md"));
   if (locusmd) {
     parts.push(`<project-instructions>
 ${locusmd}
 </project-instructions>`);
   }
-  const learnings = readFileSafe(join12(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join13(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     parts.push(`<past-learnings>
 ${learnings}
 </past-learnings>`);
   }
-  const discussionsDir = join12(projectRoot, ".locus", "discussions");
-  if (existsSync13(discussionsDir)) {
+  const discussionsDir = join13(projectRoot, ".locus", "discussions");
+  if (existsSync14(discussionsDir)) {
     try {
       const files = readdirSync3(discussionsDir).filter((f) => f.endsWith(".md")).slice(0, 3);
       for (const file of files) {
-        const content = readFileSafe(join12(discussionsDir, file));
+        const content = readFileSafe(join13(discussionsDir, file));
         if (content) {
           const name = file.replace(".md", "");
           parts.push(`<discussion name="${name}">
@@ -6916,7 +7112,7 @@ function buildFeedbackInstructions() {
 }
 function readFileSafe(path) {
   try {
-    if (!existsSync13(path))
+    if (!existsSync14(path))
       return null;
     return readFileSync9(path, "utf-8");
   } catch {
@@ -7382,7 +7578,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 join13 } from "node:path";
+import { basename as basename2, dirname as dirname3, join as join14 } from "node:path";
 
 class SlashCommandCompletion {
   commands;
@@ -7437,7 +7633,7 @@ class FilePathCompletion {
   }
   findMatches(partial) {
     try {
-      const dir = partial.includes("/") ? join13(this.projectRoot, dirname3(partial)) : this.projectRoot;
+      const dir = partial.includes("/") ? join14(this.projectRoot, dirname3(partial)) : this.projectRoot;
       const prefix = basename2(partial);
       const entries = readdirSync4(dir, { withFileTypes: true });
       return entries.filter((e) => {
@@ -7473,14 +7669,14 @@ class CombinedCompletion {
 var init_completions = () => {};
 
 // src/repl/input-history.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync9, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join14 } from "node:path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync9, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname4, join as join15 } from "node:path";
 
 class InputHistory {
   entries = [];
   filePath;
   constructor(projectRoot) {
-    this.filePath = join14(projectRoot, ".locus", "sessions", ".input-history");
+    this.filePath = join15(projectRoot, ".locus", "sessions", ".input-history");
     this.load();
   }
   add(text) {
@@ -7519,7 +7715,7 @@ class InputHistory {
   }
   load() {
     try {
-      if (!existsSync14(this.filePath))
+      if (!existsSync15(this.filePath))
         return;
       const content = readFileSync10(this.filePath, "utf-8");
       this.entries = content.split(`
@@ -7529,7 +7725,7 @@ class InputHistory {
   save() {
     try {
       const dir = dirname4(this.filePath);
-      if (!existsSync14(dir)) {
+      if (!existsSync15(dir)) {
         mkdirSync9(dir, { recursive: true });
       }
       const content = this.entries.map((e) => this.escape(e)).join(`
@@ -7560,20 +7756,20 @@ var init_model_config = __esm(() => {
 
 // src/repl/session-manager.ts
 import {
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync5,
   readFileSync as readFileSync11,
   unlinkSync as unlinkSync3,
   writeFileSync as writeFileSync7
 } from "node:fs";
-import { basename as basename3, join as join15 } from "node:path";
+import { basename as basename3, join as join16 } from "node:path";
 
 class SessionManager {
   sessionsDir;
   constructor(projectRoot) {
-    this.sessionsDir = join15(projectRoot, ".locus", "sessions");
-    if (!existsSync15(this.sessionsDir)) {
+    this.sessionsDir = join16(projectRoot, ".locus", "sessions");
+    if (!existsSync16(this.sessionsDir)) {
       mkdirSync10(this.sessionsDir, { recursive: true });
     }
   }
@@ -7599,12 +7795,12 @@ class SessionManager {
   }
   isPersisted(sessionOrId) {
     const sessionId = typeof sessionOrId === "string" ? sessionOrId : sessionOrId.id;
-    return existsSync15(this.getSessionPath(sessionId));
+    return existsSync16(this.getSessionPath(sessionId));
   }
   load(idOrPrefix) {
     const files = this.listSessionFiles();
     const exactPath = this.getSessionPath(idOrPrefix);
-    if (existsSync15(exactPath)) {
+    if (existsSync16(exactPath)) {
       try {
         return JSON.parse(readFileSync11(exactPath, "utf-8"));
       } catch {
@@ -7654,7 +7850,7 @@ class SessionManager {
   }
   delete(sessionId) {
     const path = this.getSessionPath(sessionId);
-    if (existsSync15(path)) {
+    if (existsSync16(path)) {
       unlinkSync3(path);
       return true;
     }
@@ -7684,7 +7880,7 @@ class SessionManager {
     const remaining = withStats.length - pruned;
     if (remaining > MAX_SESSIONS) {
       const toRemove = remaining - MAX_SESSIONS;
-      const alive = withStats.filter((e) => existsSync15(e.path));
+      const alive = withStats.filter((e) => existsSync16(e.path));
       for (let i = 0;i < toRemove && i < alive.length; i++) {
         try {
           unlinkSync3(alive[i].path);
@@ -7699,7 +7895,7 @@ class SessionManager {
   }
   listSessionFiles() {
     try {
-      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join15(this.sessionsDir, f));
+      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join16(this.sessionsDir, f));
     } catch {
       return [];
     }
@@ -7708,7 +7904,7 @@ class SessionManager {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
   getSessionPath(sessionId) {
-    return join15(this.sessionsDir, `${sessionId}.json`);
+    return join16(this.sessionsDir, `${sessionId}.json`);
   }
 }
 var MAX_SESSIONS = 50, SESSION_MAX_AGE_MS;
@@ -8185,8 +8381,167 @@ var init_exec = __esm(() => {
   init_session_manager();
 });
 
-// src/core/agent.ts
+// src/core/submodule.ts
 import { execSync as execSync10 } from "node:child_process";
+import { existsSync as existsSync17 } from "node:fs";
+import { join as join17 } from "node:path";
+function git2(args, cwd) {
+  return execSync10(`git ${args}`, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function gitSafe(args, cwd) {
+  try {
+    return git2(args, cwd);
+  } catch {
+    return null;
+  }
+}
+function hasSubmodules(cwd) {
+  return existsSync17(join17(cwd, ".gitmodules"));
+}
+function listSubmodules(cwd) {
+  if (!hasSubmodules(cwd))
+    return [];
+  const log = getLogger();
+  const submodules = [];
+  try {
+    const output = git2("submodule status", cwd);
+    for (const line of output.trim().split(`
+`)) {
+      if (!line.trim())
+        continue;
+      const dirty = line.startsWith("+");
+      const parts = line.trim().replace(/^[+-]/, "").split(/\s+/);
+      const path = parts[1];
+      if (!path)
+        continue;
+      submodules.push({
+        path,
+        absolutePath: join17(cwd, path),
+        dirty
+      });
+    }
+  } catch (e) {
+    log.warn(`Failed to list submodules: ${e}`);
+  }
+  return submodules;
+}
+function getDirtySubmodules(cwd) {
+  const submodules = listSubmodules(cwd);
+  const dirty = [];
+  for (const sub of submodules) {
+    if (!existsSync17(sub.absolutePath))
+      continue;
+    const status = gitSafe("status --porcelain", sub.absolutePath);
+    if (status && status.trim().length > 0) {
+      dirty.push({ ...sub, dirty: true });
+    }
+  }
+  return dirty;
+}
+function commitDirtySubmodules(cwd, issueNumber, issueTitle) {
+  const log = getLogger();
+  const dirtySubmodules = getDirtySubmodules(cwd);
+  if (dirtySubmodules.length === 0)
+    return [];
+  const committed = [];
+  for (const sub of dirtySubmodules) {
+    try {
+      git2("add -A", sub.absolutePath);
+      const message = `chore: complete #${issueNumber} - ${issueTitle}
+
+Co-Authored-By: LocusAgent <agent@locusai.team>`;
+      execSync10("git commit -F -", {
+        input: message,
+        cwd: sub.absolutePath,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      committed.push(sub.path);
+      log.info(`Committed submodule changes: ${sub.path} for #${issueNumber}`);
+    } catch {
+      log.verbose(`No committable changes in submodule ${sub.path}`);
+    }
+  }
+  if (committed.length > 0) {
+    for (const subPath of committed) {
+      gitSafe(`add ${subPath}`, cwd);
+    }
+  }
+  return committed;
+}
+function initSubmodules(cwd) {
+  if (!hasSubmodules(cwd))
+    return;
+  const log = getLogger();
+  try {
+    git2("submodule update --init --recursive", cwd);
+    log.info("Initialized submodules");
+  } catch (e) {
+    log.warn(`Failed to initialize submodules: ${e}`);
+  }
+}
+function updateSubmodulesAfterRebase(cwd) {
+  if (!hasSubmodules(cwd))
+    return;
+  const log = getLogger();
+  try {
+    git2("submodule update --recursive", cwd);
+    log.info("Updated submodules after rebase");
+  } catch (e) {
+    log.warn(`Failed to update submodules after rebase: ${e}`);
+  }
+}
+function getSubmoduleChangeSummary(cwd, baseBranch) {
+  if (!hasSubmodules(cwd))
+    return null;
+  const diff = gitSafe(`diff origin/${baseBranch}..HEAD --submodule=short`, cwd);
+  if (!diff || !diff.trim())
+    return null;
+  const submoduleChanges = [];
+  for (const line of diff.split(`
+`)) {
+    if (line.startsWith("Submodule ")) {
+      submoduleChanges.push(line.trim());
+    }
+  }
+  if (submoduleChanges.length === 0)
+    return null;
+  return `### Submodule Changes
+${submoduleChanges.map((c) => `- ${c}`).join(`
+`)}`;
+}
+function pushSubmoduleBranches(cwd) {
+  if (!hasSubmodules(cwd))
+    return;
+  const log = getLogger();
+  const submodules = listSubmodules(cwd);
+  for (const sub of submodules) {
+    if (!existsSync17(sub.absolutePath))
+      continue;
+    const branch = gitSafe("rev-parse --abbrev-ref HEAD", sub.absolutePath)?.trim();
+    if (!branch || branch === "HEAD")
+      continue;
+    const unpushed = gitSafe(`log origin/${branch}..HEAD --oneline`, sub.absolutePath)?.trim();
+    if (unpushed) {
+      try {
+        git2(`push origin ${branch}`, sub.absolutePath);
+        log.info(`Pushed submodule ${sub.path} branch ${branch}`);
+      } catch (e) {
+        log.warn(`Failed to push submodule ${sub.path}: ${e}`);
+      }
+    }
+  }
+}
+var init_submodule = __esm(() => {
+  init_logger();
+});
+
+// src/core/agent.ts
+import { execSync as execSync11 } from "node:child_process";
 async function executeIssue(projectRoot, options) {
   const log = getLogger();
   const timer = createTimer();
@@ -8215,7 +8570,7 @@ ${cyan("●")} ${bold(`#${issueNumber}`)} ${issue.title}
   }
   let issueComments = [];
   try {
-    const commentsRaw = execSync10(`gh issue view ${issueNumber} --json comments --jq '.comments[].body'`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const commentsRaw = execSync11(`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);
@@ -8379,12 +8734,12 @@ ${aiResult.success ? green("✓") : red("✗")} Iteration ${aiResult.success ? "
 }
 async function createIssuePR(projectRoot, config, issue) {
   try {
-    const currentBranch = execSync10("git rev-parse --abbrev-ref HEAD", {
+    const currentBranch = execSync11("git rev-parse --abbrev-ref HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    const diff = execSync10(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
+    const diff = execSync11(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8393,17 +8748,25 @@ async function createIssuePR(projectRoot, config, issue) {
       getLogger().verbose("No changes to create PR for");
       return;
     }
-    execSync10(`git push -u origin ${currentBranch}`, {
+    pushSubmoduleBranches(projectRoot);
+    execSync11(`git push -u origin ${currentBranch}`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
-    const prTitle = `${issue.title} (#${issue.number})`;
-    const prBody = `Closes #${issue.number}
+    const submoduleSummary = getSubmoduleChangeSummary(projectRoot, config.agent.baseBranch);
+    let prBody = `Closes #${issue.number}`;
+    if (submoduleSummary) {
+      prBody += `
+
+${submoduleSummary}`;
+    }
+    prBody += `
 
 ---
 
 \uD83E\uDD16 Automated by [Locus](https://github.com/locusai/locus)`;
+    const prTitle = `${issue.title} (#${issue.number})`;
     const prNumber = createPR(prTitle, prBody, currentBranch, config.agent.baseBranch, { cwd: projectRoot });
     process.stderr.write(`  ${green("✓")} Created PR #${prNumber}
 `);
@@ -8437,20 +8800,21 @@ var init_agent = __esm(() => {
   init_logger();
   init_prompt_builder();
   init_sandbox();
+  init_submodule();
 });
 
 // src/core/conflict.ts
-import { execSync as execSync11 } from "node:child_process";
-function git2(args, cwd) {
-  return execSync11(`git ${args}`, {
+import { execSync as execSync12 } from "node:child_process";
+function git3(args, cwd) {
+  return execSync12(`git ${args}`, {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
   });
 }
-function gitSafe(args, cwd) {
+function gitSafe2(args, cwd) {
   try {
-    return git2(args, cwd);
+    return git3(args, cwd);
   } catch {
     return null;
   }
@@ -8458,7 +8822,7 @@ function gitSafe(args, cwd) {
 function checkForConflicts(cwd, baseBranch) {
   const log = getLogger();
   try {
-    git2(`fetch origin ${baseBranch}`, cwd);
+    git3(`fetch origin ${baseBranch}`, cwd);
     log.debug("Fetched latest from origin", { baseBranch });
   } catch (e) {
     log.warn(`Could not fetch origin/${baseBranch}: ${e}`);
@@ -8469,8 +8833,8 @@ function checkForConflicts(cwd, baseBranch) {
       newCommits: 0
     };
   }
-  const currentBranch = gitSafe("rev-parse --abbrev-ref HEAD", cwd)?.trim() ?? "";
-  const mergeBase = gitSafe(`merge-base ${currentBranch} origin/${baseBranch}`, cwd)?.trim();
+  const currentBranch = gitSafe2("rev-parse --abbrev-ref HEAD", cwd)?.trim() ?? "";
+  const mergeBase = gitSafe2(`merge-base ${currentBranch} origin/${baseBranch}`, cwd)?.trim();
   if (!mergeBase) {
     log.debug("Could not find merge base — branches may be unrelated");
     return {
@@ -8480,7 +8844,7 @@ function checkForConflicts(cwd, baseBranch) {
       newCommits: 0
     };
   }
-  const remoteTip = gitSafe(`rev-parse origin/${baseBranch}`, cwd)?.trim();
+  const remoteTip = gitSafe2(`rev-parse origin/${baseBranch}`, cwd)?.trim();
   if (!remoteTip || remoteTip === mergeBase) {
     log.debug("Base branch has not advanced");
     return {
@@ -8490,16 +8854,16 @@ function checkForConflicts(cwd, baseBranch) {
       newCommits: 0
     };
   }
-  const newCommitsOutput = gitSafe(`rev-list --count ${mergeBase}..origin/${baseBranch}`, cwd)?.trim() ?? "0";
+  const newCommitsOutput = gitSafe2(`rev-list --count ${mergeBase}..origin/${baseBranch}`, cwd)?.trim() ?? "0";
   const newCommits = Number.parseInt(newCommitsOutput, 10);
   log.verbose(`Base branch has ${newCommits} new commits`, {
     baseBranch,
     mergeBase: mergeBase.slice(0, 8),
     remoteTip: remoteTip.slice(0, 8)
   });
-  const ourChanges = gitSafe(`diff --name-only ${mergeBase}..HEAD`, cwd)?.trim().split(`
+  const ourChanges = gitSafe2(`diff --name-only ${mergeBase}..HEAD`, cwd)?.trim().split(`
 `).filter(Boolean) ?? [];
-  const theirChanges = gitSafe(`diff --name-only ${mergeBase}..origin/${baseBranch}`, cwd)?.trim().split(`
+  const theirChanges = gitSafe2(`diff --name-only ${mergeBase}..origin/${baseBranch}`, cwd)?.trim().split(`
 `).filter(Boolean) ?? [];
   const overlapping = ourChanges.filter((f) => theirChanges.includes(f));
   return {
@@ -8512,18 +8876,19 @@ function checkForConflicts(cwd, baseBranch) {
 function attemptRebase(cwd, baseBranch) {
   const log = getLogger();
   try {
-    git2(`rebase origin/${baseBranch}`, cwd);
+    git3(`rebase origin/${baseBranch}`, cwd);
     log.info(`Successfully rebased onto origin/${baseBranch}`);
+    updateSubmodulesAfterRebase(cwd);
     return { success: true };
   } catch (_e) {
     log.warn("Rebase failed, aborting");
     const conflicts = [];
     try {
-      const status = git2("diff --name-only --diff-filter=U", cwd);
+      const status = git3("diff --name-only --diff-filter=U", cwd);
       conflicts.push(...status.trim().split(`
 `).filter(Boolean));
     } catch {}
-    gitSafe("rebase --abort", cwd);
+    gitSafe2("rebase --abort", cwd);
     return { success: false, conflicts };
   }
 }
@@ -8565,23 +8930,24 @@ ${bold(yellow("⚠"))} Base branch has ${result.newCommits} new commit${result.n
 var init_conflict = __esm(() => {
   init_terminal();
   init_logger();
+  init_submodule();
 });
 
 // src/core/run-state.ts
 import {
-  existsSync as existsSync16,
+  existsSync as existsSync18,
   mkdirSync as mkdirSync11,
   readFileSync as readFileSync12,
   unlinkSync as unlinkSync4,
   writeFileSync as writeFileSync8
 } from "node:fs";
-import { dirname as dirname5, join as join16 } from "node:path";
+import { dirname as dirname5, join as join18 } from "node:path";
 function getRunStatePath(projectRoot) {
-  return join16(projectRoot, ".locus", "run-state.json");
+  return join18(projectRoot, ".locus", "run-state.json");
 }
 function loadRunState(projectRoot) {
   const path = getRunStatePath(projectRoot);
-  if (!existsSync16(path))
+  if (!existsSync18(path))
     return null;
   try {
     return JSON.parse(readFileSync12(path, "utf-8"));
@@ -8593,7 +8959,7 @@ function loadRunState(projectRoot) {
 function saveRunState(projectRoot, state) {
   const path = getRunStatePath(projectRoot);
   const dir = dirname5(path);
-  if (!existsSync16(dir)) {
+  if (!existsSync18(dir)) {
     mkdirSync11(dir, { recursive: true });
   }
   writeFileSync8(path, `${JSON.stringify(state, null, 2)}
@@ -8601,7 +8967,7 @@ function saveRunState(projectRoot, state) {
 }
 function clearRunState(projectRoot) {
   const path = getRunStatePath(projectRoot);
-  if (existsSync16(path)) {
+  if (existsSync18(path)) {
     unlinkSync4(path);
   }
 }
@@ -8741,28 +9107,28 @@ var init_shutdown = __esm(() => {
 });
 
 // src/core/worktree.ts
-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 execSync12(`git ${args}`, {
+import { execSync as execSync13 } from "node:child_process";
+import { existsSync as existsSync19, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
+import { join as join19 } from "node:path";
+function git4(args, cwd) {
+  return execSync13(`git ${args}`, {
     cwd,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"]
   });
 }
-function gitSafe2(args, cwd) {
+function gitSafe3(args, cwd) {
   try {
-    return git3(args, cwd);
+    return git4(args, cwd);
   } catch {
     return null;
   }
 }
 function getWorktreeDir(projectRoot) {
-  return join17(projectRoot, ".locus", "worktrees");
+  return join19(projectRoot, ".locus", "worktrees");
 }
 function getWorktreePath(projectRoot, issueNumber) {
-  return join17(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
+  return join19(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
 }
 function generateBranchName(issueNumber) {
   const randomSuffix = Math.random().toString(36).slice(2, 8);
@@ -8770,7 +9136,7 @@ function generateBranchName(issueNumber) {
 }
 function getWorktreeBranch(worktreePath) {
   try {
-    return execSync12("git branch --show-current", {
+    return execSync13("git branch --show-current", {
       cwd: worktreePath,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -8782,7 +9148,7 @@ function getWorktreeBranch(worktreePath) {
 function createWorktree(projectRoot, issueNumber, baseBranch) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (existsSync17(worktreePath)) {
+  if (existsSync19(worktreePath)) {
     log.verbose(`Worktree already exists for issue #${issueNumber}`);
     const existingBranch = getWorktreeBranch(worktreePath) ?? `locus/issue-${issueNumber}`;
     return {
@@ -8793,7 +9159,8 @@ function createWorktree(projectRoot, issueNumber, baseBranch) {
     };
   }
   const branch = generateBranchName(issueNumber);
-  git3(`worktree add ${JSON.stringify(worktreePath)} -b ${branch} ${baseBranch}`, projectRoot);
+  git4(`worktree add ${JSON.stringify(worktreePath)} -b ${branch} ${baseBranch}`, projectRoot);
+  initSubmodules(worktreePath);
   log.info(`Created worktree for issue #${issueNumber}`, {
     path: worktreePath,
     branch,
@@ -8809,30 +9176,30 @@ function createWorktree(projectRoot, issueNumber, baseBranch) {
 function removeWorktree(projectRoot, issueNumber) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (!existsSync17(worktreePath)) {
+  if (!existsSync19(worktreePath)) {
     log.verbose(`Worktree for issue #${issueNumber} does not exist`);
     return;
   }
   const branch = getWorktreeBranch(worktreePath);
   try {
-    git3(`worktree remove ${JSON.stringify(worktreePath)} --force`, projectRoot);
+    git4(`worktree remove ${JSON.stringify(worktreePath)} --force`, projectRoot);
     log.info(`Removed worktree for issue #${issueNumber}`);
   } catch (e) {
     log.warn(`Failed to remove worktree: ${e}`);
-    gitSafe2(`worktree remove ${JSON.stringify(worktreePath)} --force`, projectRoot);
+    gitSafe3(`worktree remove ${JSON.stringify(worktreePath)} --force`, projectRoot);
   }
   if (branch) {
-    gitSafe2(`branch -D ${branch}`, projectRoot);
+    gitSafe3(`branch -D ${branch}`, projectRoot);
   }
 }
 function listWorktrees(projectRoot) {
   const log = getLogger();
   const worktreeDir = getWorktreeDir(projectRoot);
-  if (!existsSync17(worktreeDir)) {
+  if (!existsSync19(worktreeDir)) {
     return [];
   }
   const entries = readdirSync6(worktreeDir).filter((entry) => entry.startsWith("issue-"));
-  const gitWorktreeList = gitSafe2("worktree list --porcelain", projectRoot);
+  const gitWorktreeList = gitSafe3("worktree list --porcelain", projectRoot);
   const activeWorktrees = new Set;
   if (gitWorktreeList) {
     for (const line of gitWorktreeList.split(`
@@ -8848,7 +9215,7 @@ function listWorktrees(projectRoot) {
     if (!match)
       continue;
     const issueNumber = Number.parseInt(match[1], 10);
-    const path = join17(worktreeDir, entry);
+    const path = join19(worktreeDir, entry);
     const branch = getWorktreeBranch(path) ?? `locus/issue-${issueNumber}`;
     let resolvedPath;
     try {
@@ -8882,12 +9249,13 @@ function cleanupStaleWorktrees(projectRoot) {
     }
   }
   if (cleaned > 0) {
-    gitSafe2("worktree prune", projectRoot);
+    gitSafe3("worktree prune", projectRoot);
   }
   return cleaned;
 }
 var init_worktree = __esm(() => {
   init_logger();
+  init_submodule();
 });
 
 // src/commands/run.ts
@@ -8895,7 +9263,7 @@ var exports_run = {};
 __export(exports_run, {
   runCommand: () => runCommand
 });
-import { execSync as execSync13 } from "node:child_process";
+import { execSync as execSync14 } from "node:child_process";
 function resolveExecutionContext(config, modelOverride) {
   const model = modelOverride ?? config.ai.model;
   const provider = inferProviderFromModel(model) ?? config.ai.provider;
@@ -9046,7 +9414,7 @@ ${yellow("⚠")} A sprint run is already in progress.
   }
   if (!flags.dryRun) {
     try {
-      execSync13(`git checkout -B ${branchName}`, {
+      execSync14(`git checkout -B ${branchName}`, {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -9096,7 +9464,7 @@ ${red("✗")} Auto-rebase failed. Resolve manually.
     let sprintContext;
     if (i > 0 && !flags.dryRun) {
       try {
-        sprintContext = execSync13(`git diff origin/${config.agent.baseBranch}..HEAD`, {
+        sprintContext = execSync14(`git diff origin/${config.agent.baseBranch}..HEAD`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9161,7 +9529,7 @@ ${bold("Summary:")}
     const prNumber = await createSprintPR(projectRoot, config, sprintName, branchName, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync13(`git checkout ${config.agent.baseBranch}`, {
+        execSync14(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9176,6 +9544,7 @@ ${bold("Summary:")}
   }
 }
 async function handleSingleIssue(projectRoot, config, issueNumber, flags, sandboxed) {
+  const log = getLogger();
   const execution = resolveExecutionContext(config, flags.model);
   let isSprintIssue = false;
   try {
@@ -9184,7 +9553,7 @@ async function handleSingleIssue(projectRoot, config, issueNumber, flags, sandbo
   } catch {}
   if (isSprintIssue) {
     process.stderr.write(`
-${bold("Running sprint issue")} ${cyan(`#${issueNumber}`)} ${dim("(sequential, no worktree)")}
+${bold("Running sprint issue")} ${cyan(`#${issueNumber}`)} ${dim("(sequential)")}
 
 `);
     await executeIssue(projectRoot, {
@@ -9197,42 +9566,48 @@ ${bold("Running sprint issue")} ${cyan(`#${issueNumber}`)} ${dim("(sequential, n
     });
     return;
   }
+  const randomSuffix = Math.random().toString(36).slice(2, 8);
+  const branchName = `locus/issue-${issueNumber}-${randomSuffix}`;
   process.stderr.write(`
-${bold("Running issue")} ${cyan(`#${issueNumber}`)} ${dim("(worktree)")}
+${bold("Running issue")} ${cyan(`#${issueNumber}`)} ${dim(`(branch: ${branchName})`)}
 
 `);
-  let worktreePath;
   if (!flags.dryRun) {
     try {
-      const wt = createWorktree(projectRoot, issueNumber, config.agent.baseBranch);
-      worktreePath = wt.path;
-      process.stderr.write(`  ${dim(`Worktree: ${wt.branch}`)}
-
-`);
+      execSync14(`git checkout -B ${branchName} ${config.agent.baseBranch}`, {
+        cwd: projectRoot,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      log.info(`Checked out branch ${branchName}`);
     } catch (e) {
-      process.stderr.write(`${yellow("⚠")} Could not create worktree: ${e}
+      process.stderr.write(`${yellow("⚠")} Could not create branch: ${e}
 `);
-      process.stderr.write(`  ${dim("Falling back to running in project root.")}
+      process.stderr.write(`  ${dim("Running on current branch instead.")}
 
 `);
     }
   }
   const result = await executeIssue(projectRoot, {
     issueNumber,
-    worktreePath,
     provider: execution.provider,
     model: execution.model,
     dryRun: flags.dryRun,
     sandboxed,
     sandboxName: execution.sandboxName
   });
-  if (worktreePath && !flags.dryRun) {
+  if (!flags.dryRun) {
     if (result.success) {
-      removeWorktree(projectRoot, issueNumber);
-      process.stderr.write(`  ${dim("Worktree cleaned up.")}
-`);
+      try {
+        execSync14(`git checkout ${config.agent.baseBranch}`, {
+          cwd: projectRoot,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        log.info(`Checked out ${config.agent.baseBranch}`);
+      } catch {}
     } else {
-      process.stderr.write(`  ${yellow("⚠")} Worktree preserved for debugging: ${dim(worktreePath)}
+      process.stderr.write(`  ${yellow("⚠")} Branch ${dim(branchName)} preserved for debugging.
 `);
     }
   }
@@ -9361,13 +9736,13 @@ ${bold("Resuming")} ${state.type} run ${dim(state.runId)}
 `);
   if (state.type === "sprint" && state.branch) {
     try {
-      const currentBranch = execSync13("git rev-parse --abbrev-ref HEAD", {
+      const currentBranch = execSync14("git rev-parse --abbrev-ref HEAD", {
         cwd: projectRoot,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
       }).trim();
       if (currentBranch !== state.branch) {
-        execSync13(`git checkout ${state.branch}`, {
+        execSync14(`git checkout ${state.branch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9434,7 +9809,7 @@ ${bold("Resume complete:")} ${green(`✓ ${finalStats.done}`)} ${finalStats.fail
     const prNumber = await createSprintPR(projectRoot, config, state.sprint, state.branch, completedTasks);
     if (prNumber !== undefined) {
       try {
-        execSync13(`git checkout ${config.agent.baseBranch}`, {
+        execSync14(`git checkout ${config.agent.baseBranch}`, {
           cwd: projectRoot,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
@@ -9465,14 +9840,19 @@ function getOrder2(issue) {
 }
 function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
   try {
-    const status = execSync13("git status --porcelain", {
+    const committedSubmodules = commitDirtySubmodules(projectRoot, issueNumber, issueTitle);
+    if (committedSubmodules.length > 0) {
+      process.stderr.write(`  ${dim(`Committed submodule changes: ${committedSubmodules.join(", ")}`)}
+`);
+    }
+    const status = execSync14("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
     if (!status)
       return;
-    execSync13("git add -A", {
+    execSync14("git add -A", {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -9480,7 +9860,7 @@ function ensureTaskCommit(projectRoot, issueNumber, issueTitle) {
     const message = `chore: complete #${issueNumber} - ${issueTitle}
 
 Co-Authored-By: LocusAgent <agent@locusai.team>`;
-    execSync13(`git commit -F -`, {
+    execSync14(`git commit -F -`, {
       input: message,
       cwd: projectRoot,
       encoding: "utf-8",
@@ -9494,7 +9874,7 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
   if (!config.agent.autoPR)
     return;
   try {
-    const diff = execSync13(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
+    const diff = execSync14(`git diff origin/${config.agent.baseBranch}..HEAD --stat`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -9504,16 +9884,24 @@ async function createSprintPR(projectRoot, config, sprintName, branchName, tasks
 `);
       return;
     }
-    execSync13(`git push -u origin ${branchName}`, {
+    pushSubmoduleBranches(projectRoot);
+    execSync14(`git push -u origin ${branchName}`, {
       cwd: projectRoot,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
     const taskLines = tasks.map((t) => `- Closes #${t.issue}${t.title ? `: ${t.title}` : ""}`).join(`
 `);
-    const prBody = `## Sprint: ${sprintName}
+    const submoduleSummary = getSubmoduleChangeSummary(projectRoot, config.agent.baseBranch);
+    let prBody = `## Sprint: ${sprintName}
 
-${taskLines}
+${taskLines}`;
+    if (submoduleSummary) {
+      prBody += `
+
+${submoduleSummary}`;
+    }
+    prBody += `
 
 ---
 
@@ -9530,8 +9918,8 @@ ${taskLines}
   }
 }
 var init_run = __esm(() => {
-  init_ai_models();
   init_agent();
+  init_ai_models();
   init_config();
   init_conflict();
   init_github();
@@ -9540,6 +9928,7 @@ var init_run = __esm(() => {
   init_run_state();
   init_sandbox();
   init_shutdown();
+  init_submodule();
   init_worktree();
   init_progress();
   init_terminal();
@@ -9654,13 +10043,13 @@ __export(exports_plan, {
   parsePlanArgs: () => parsePlanArgs
 });
 import {
-  existsSync as existsSync18,
+  existsSync as existsSync20,
   mkdirSync as mkdirSync12,
   readdirSync as readdirSync7,
   readFileSync as readFileSync13,
   writeFileSync as writeFileSync9
 } from "node:fs";
-import { join as join18 } from "node:path";
+import { join as join20 } from "node:path";
 function printHelp() {
   process.stderr.write(`
 ${bold("locus plan")} — AI-powered sprint planning
@@ -9691,11 +10080,11 @@ function normalizeSprintName(name) {
   return name.trim().toLowerCase();
 }
 function getPlansDir(projectRoot) {
-  return join18(projectRoot, ".locus", "plans");
+  return join20(projectRoot, ".locus", "plans");
 }
 function ensurePlansDir(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync20(dir)) {
     mkdirSync12(dir, { recursive: true });
   }
   return dir;
@@ -9705,14 +10094,14 @@ function generateId() {
 }
 function loadPlanFile(projectRoot, id) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync18(dir))
+  if (!existsSync20(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 = readFileSync13(join18(dir, match), "utf-8");
+    const content = readFileSync13(join20(dir, match), "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -9758,7 +10147,7 @@ async function planCommand(projectRoot, args, flags = {}) {
 }
 function handleListPlans(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync18(dir)) {
+  if (!existsSync20(dir)) {
     process.stderr.write(`${dim("No saved plans yet.")}
 `);
     return;
@@ -9776,7 +10165,7 @@ ${bold("Saved Plans:")}
   for (const file of files) {
     const id = file.replace(".json", "");
     try {
-      const content = readFileSync13(join18(dir, file), "utf-8");
+      const content = readFileSync13(join20(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;
@@ -9887,7 +10276,7 @@ ${bold("Approving plan:")}
 async function handleAIPlan(projectRoot, config, directive, sprintName, flags) {
   const id = generateId();
   const plansDir = ensurePlansDir(projectRoot);
-  const planPath = join18(plansDir, `${id}.json`);
+  const planPath = join20(plansDir, `${id}.json`);
   const planPathRelative = `.locus/plans/${id}.json`;
   const displayDirective = directive;
   process.stderr.write(`
@@ -9921,7 +10310,7 @@ ${red("✗")} Planning failed: ${aiResult.error}
 `);
     return;
   }
-  if (!existsSync18(planPath)) {
+  if (!existsSync20(planPath)) {
     process.stderr.write(`
 ${yellow("⚠")} Plan file was not created at ${bold(planPathRelative)}.
 `);
@@ -10094,15 +10483,15 @@ ${directive}${sprintName ? `
 
 **Sprint:** ${sprintName}` : ""}
 </directive>`);
-  const locusPath = join18(projectRoot, ".locus", "LOCUS.md");
-  if (existsSync18(locusPath)) {
+  const locusPath = join20(projectRoot, ".locus", "LOCUS.md");
+  if (existsSync20(locusPath)) {
     const content = readFileSync13(locusPath, "utf-8");
     parts.push(`<project-context>
 ${content.slice(0, 3000)}
 </project-context>`);
   }
-  const learningsPath = join18(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync18(learningsPath)) {
+  const learningsPath = join20(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync20(learningsPath)) {
     const content = readFileSync13(learningsPath, "utf-8");
     parts.push(`<past-learnings>
 ${content.slice(0, 2000)}
@@ -10273,8 +10662,8 @@ var init_plan = __esm(() => {
   init_run_ai();
   init_config();
   init_github();
-  init_terminal();
   init_sandbox();
+  init_terminal();
 });
 
 // src/commands/review.ts
@@ -10282,9 +10671,9 @@ var exports_review = {};
 __export(exports_review, {
   reviewCommand: () => reviewCommand
 });
-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";
+import { execSync as execSync15 } from "node:child_process";
+import { existsSync as existsSync21, readFileSync as readFileSync14 } from "node:fs";
+import { join as join21 } from "node:path";
 function printHelp2() {
   process.stderr.write(`
 ${bold("locus review")} — AI-powered code review
@@ -10360,7 +10749,7 @@ ${bold("Review complete:")} ${green(`✓ ${reviewed}`)}${failed > 0 ? ` ${red(`
 async function reviewSinglePR(projectRoot, config, prNumber, focus, flags) {
   let prInfo;
   try {
-    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 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 raw = JSON.parse(result);
     prInfo = {
       number: raw.number,
@@ -10426,7 +10815,7 @@ ${output.slice(0, 60000)}
 
 ---
 _Reviewed by Locus AI (${config.ai.provider}/${flags.model ?? config.ai.model})_`;
-      execSync14(`gh pr comment ${pr.number} --body ${JSON.stringify(reviewBody)}`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+      execSync15(`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) {
@@ -10444,8 +10833,8 @@ function buildReviewPrompt(projectRoot, config, pr, diff, focus) {
   parts.push(`<role>
 You are an expert code reviewer for the ${config.github.owner}/${config.github.repo} repository.
 </role>`);
-  const locusPath = join19(projectRoot, ".locus", "LOCUS.md");
-  if (existsSync19(locusPath)) {
+  const locusPath = join21(projectRoot, ".locus", "LOCUS.md");
+  if (existsSync21(locusPath)) {
     const content = readFileSync14(locusPath, "utf-8");
     parts.push(`<project-context>
 ${content.slice(0, 2000)}
@@ -10506,7 +10895,7 @@ var exports_iterate = {};
 __export(exports_iterate, {
   iterateCommand: () => iterateCommand
 });
-import { execSync as execSync15 } from "node:child_process";
+import { execSync as execSync16 } from "node:child_process";
 function printHelp3() {
   process.stderr.write(`
 ${bold("locus iterate")} — Re-execute tasks with PR feedback
@@ -10716,12 +11105,12 @@ ${bold("Summary:")} ${green(`✓ ${succeeded}`)}${failed > 0 ? ` ${red(`✗ ${fa
 }
 function findPRForIssue(projectRoot, issueNumber) {
   try {
-    const result = execSync15(`gh pr list --search "Closes #${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const result = execSync16(`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 = execSync15(`gh pr list --head "locus/issue-${issueNumber}" --json number --state open`, { cwd: projectRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const branchResult = execSync16(`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;
@@ -10756,14 +11145,14 @@ __export(exports_discuss, {
   discussCommand: () => discussCommand
 });
 import {
-  existsSync as existsSync20,
+  existsSync as existsSync22,
   mkdirSync as mkdirSync13,
   readdirSync as readdirSync8,
   readFileSync as readFileSync15,
   unlinkSync as unlinkSync5,
   writeFileSync as writeFileSync10
 } from "node:fs";
-import { join as join20 } from "node:path";
+import { join as join22 } from "node:path";
 function printHelp4() {
   process.stderr.write(`
 ${bold("locus discuss")} — AI-powered architectural discussions
@@ -10785,11 +11174,11 @@ ${bold("Examples:")}
 `);
 }
 function getDiscussionsDir(projectRoot) {
-  return join20(projectRoot, ".locus", "discussions");
+  return join22(projectRoot, ".locus", "discussions");
 }
 function ensureDiscussionsDir(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync20(dir)) {
+  if (!existsSync22(dir)) {
     mkdirSync13(dir, { recursive: true });
   }
   return dir;
@@ -10824,7 +11213,7 @@ async function discussCommand(projectRoot, args, flags = {}) {
 }
 function listDiscussions(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync20(dir)) {
+  if (!existsSync22(dir)) {
     process.stderr.write(`${dim("No discussions yet.")}
 `);
     return;
@@ -10841,7 +11230,7 @@ ${bold("Discussions:")}
 `);
   for (const file of files) {
     const id = file.replace(".md", "");
-    const content = readFileSync15(join20(dir, file), "utf-8");
+    const content = readFileSync15(join22(dir, file), "utf-8");
     const titleMatch = content.match(/^#\s+(.+)/m);
     const title = titleMatch ? titleMatch[1] : id;
     const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/);
@@ -10859,7 +11248,7 @@ function showDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync20(dir)) {
+  if (!existsSync22(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -10871,7 +11260,7 @@ function showDiscussion(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync15(join20(dir, match), "utf-8");
+  const content = readFileSync15(join22(dir, match), "utf-8");
   process.stdout.write(`${content}
 `);
 }
@@ -10882,7 +11271,7 @@ function deleteDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync20(dir)) {
+  if (!existsSync22(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -10894,7 +11283,7 @@ function deleteDiscussion(projectRoot, id) {
 `);
     return;
   }
-  unlinkSync5(join20(dir, match));
+  unlinkSync5(join22(dir, match));
   process.stderr.write(`${green("✓")} Deleted discussion: ${match.replace(".md", "")}
 `);
 }
@@ -10907,7 +11296,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync20(dir)) {
+  if (!existsSync22(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -10919,7 +11308,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync15(join20(dir, match), "utf-8");
+  const content = readFileSync15(join22(dir, match), "utf-8");
   const titleMatch = content.match(/^#\s+(.+)/m);
   const discussionTitle = titleMatch ? titleMatch[1].trim() : id;
   await planCommand(projectRoot, [
@@ -11033,7 +11422,7 @@ ${turn.content}`;
     ...conversation.length > 1 ? [`---`, ``, `## Discussion Transcript`, ``, transcript, ``] : []
   ].join(`
 `);
-  writeFileSync10(join20(dir, `${id}.md`), markdown, "utf-8");
+  writeFileSync10(join22(dir, `${id}.md`), markdown, "utf-8");
   process.stderr.write(`
 ${green("✓")} Discussion saved: ${cyan(id)} ${dim(`(${timer.formatted()})`)}
 `);
@@ -11048,15 +11437,15 @@ function buildDiscussionPrompt(projectRoot, config, topic, conversation, forceFi
   parts.push(`<role>
 You are a senior software architect and consultant for the ${config.github.owner}/${config.github.repo} project.
 </role>`);
-  const locusPath = join20(projectRoot, ".locus", "LOCUS.md");
-  if (existsSync20(locusPath)) {
+  const locusPath = join22(projectRoot, ".locus", "LOCUS.md");
+  if (existsSync22(locusPath)) {
     const content = readFileSync15(locusPath, "utf-8");
     parts.push(`<project-context>
 ${content.slice(0, 3000)}
 </project-context>`);
   }
-  const learningsPath = join20(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync20(learningsPath)) {
+  const learningsPath = join22(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync22(learningsPath)) {
     const content = readFileSync15(learningsPath, "utf-8");
     parts.push(`<past-learnings>
 ${content.slice(0, 2000)}
@@ -11128,8 +11517,8 @@ __export(exports_artifacts, {
   formatDate: () => formatDate2,
   artifactsCommand: () => artifactsCommand
 });
-import { existsSync as existsSync21, readdirSync as readdirSync9, readFileSync as readFileSync16, statSync as statSync4 } from "node:fs";
-import { join as join21 } from "node:path";
+import { existsSync as existsSync23, readdirSync as readdirSync9, readFileSync as readFileSync16, statSync as statSync4 } from "node:fs";
+import { join as join23 } from "node:path";
 function printHelp5() {
   process.stderr.write(`
 ${bold("locus artifacts")} — View and manage AI-generated artifacts
@@ -11149,14 +11538,14 @@ ${dim("Artifact names support partial matching.")}
 `);
 }
 function getArtifactsDir(projectRoot) {
-  return join21(projectRoot, ".locus", "artifacts");
+  return join23(projectRoot, ".locus", "artifacts");
 }
 function listArtifacts(projectRoot) {
   const dir = getArtifactsDir(projectRoot);
-  if (!existsSync21(dir))
+  if (!existsSync23(dir))
     return [];
   return readdirSync9(dir).filter((f) => f.endsWith(".md")).map((fileName) => {
-    const filePath = join21(dir, fileName);
+    const filePath = join23(dir, fileName);
     const stat = statSync4(filePath);
     return {
       name: fileName.replace(/\.md$/, ""),
@@ -11169,8 +11558,8 @@ function listArtifacts(projectRoot) {
 function readArtifact(projectRoot, name) {
   const dir = getArtifactsDir(projectRoot);
   const fileName = name.endsWith(".md") ? name : `${name}.md`;
-  const filePath = join21(dir, fileName);
-  if (!existsSync21(filePath))
+  const filePath = join23(dir, fileName);
+  if (!existsSync23(filePath))
     return null;
   const stat = statSync4(filePath);
   return {
@@ -11340,10 +11729,10 @@ __export(exports_sandbox2, {
   parseSandboxInstallArgs: () => parseSandboxInstallArgs,
   parseSandboxExecArgs: () => parseSandboxExecArgs
 });
-import { execSync as execSync16, spawn as spawn6 } from "node:child_process";
+import { execSync as execSync17, spawn as spawn6 } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync as existsSync22, readFileSync as readFileSync17 } from "node:fs";
-import { basename as basename4, join as join22 } from "node:path";
+import { existsSync as existsSync24, readFileSync as readFileSync17 } from "node:fs";
+import { basename as basename4, join as join24 } from "node:path";
 function printSandboxHelp() {
   process.stderr.write(`
 ${bold("locus sandbox")} — Manage Docker sandbox lifecycle
@@ -11519,7 +11908,7 @@ function handleRemove(projectRoot) {
     process.stderr.write(`Removing sandbox ${bold(sandboxName)}...
 `);
     try {
-      execSync16(`docker sandbox rm ${sandboxName}`, {
+      execSync17(`docker sandbox rm ${sandboxName}`, {
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"],
         timeout: 15000
@@ -11793,7 +12182,7 @@ async function handleLogs(projectRoot, args) {
 }
 function detectPackageManager(projectRoot) {
   try {
-    const raw = readFileSync17(join22(projectRoot, "package.json"), "utf-8");
+    const raw = readFileSync17(join24(projectRoot, "package.json"), "utf-8");
     const pkgJson = JSON.parse(raw);
     if (typeof pkgJson.packageManager === "string") {
       const name = pkgJson.packageManager.split("@")[0];
@@ -11802,13 +12191,13 @@ function detectPackageManager(projectRoot) {
       }
     }
   } catch {}
-  if (existsSync22(join22(projectRoot, "bun.lock")) || existsSync22(join22(projectRoot, "bun.lockb"))) {
+  if (existsSync24(join24(projectRoot, "bun.lock")) || existsSync24(join24(projectRoot, "bun.lockb"))) {
     return "bun";
   }
-  if (existsSync22(join22(projectRoot, "yarn.lock"))) {
+  if (existsSync24(join24(projectRoot, "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync22(join22(projectRoot, "pnpm-lock.yaml"))) {
+  if (existsSync24(join24(projectRoot, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
   return "npm";
@@ -11826,31 +12215,39 @@ function getInstallCommand(pm) {
   }
 }
 async function runSandboxSetup(sandboxName, projectRoot) {
-  const pm = detectPackageManager(projectRoot);
-  if (pm !== "npm") {
-    await ensurePackageManagerInSandbox(sandboxName, pm);
-  }
-  const installCmd = getInstallCommand(pm);
-  process.stderr.write(`
+  const ecosystem = detectProjectEcosystem(projectRoot);
+  const isJS = isJavaScriptEcosystem(ecosystem);
+  if (isJS) {
+    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)}.
+    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)}.
+      return false;
+    }
+    process.stderr.write(`${green("✓")} Dependencies installed in sandbox ${dim(sandboxName)}.
+`);
+  } else {
+    process.stderr.write(`
+${dim(`Detected ${ecosystem} project — skipping JS package install.`)}
 `);
-  const setupScript = join22(projectRoot, ".locus", "sandbox-setup.sh");
-  if (existsSync22(setupScript)) {
+  }
+  const setupScript = join24(projectRoot, ".locus", "sandbox-setup.sh");
+  if (existsSync24(setupScript)) {
     process.stderr.write(`Running ${bold(".locus/sandbox-setup.sh")} in sandbox ${dim(sandboxName)}...
 `);
     const hookOk = await runInteractiveCommand("docker", [
@@ -11866,6 +12263,11 @@ Installing dependencies (${bold(installCmd.join(" "))}) in sandbox ${dim(sandbox
       process.stderr.write(`${yellow("⚠")} Setup hook failed in sandbox ${dim(sandboxName)}.
 `);
     }
+  } else if (!isJS) {
+    process.stderr.write(`${yellow("⚠")} No ${bold(".locus/sandbox-setup.sh")} found. Create one to install ${ecosystem} toolchain in the sandbox.
+`);
+    process.stderr.write(`  Re-run ${cyan("locus init")} to auto-generate a template, or create it manually.
+`);
   }
   return true;
 }
@@ -11933,7 +12335,7 @@ function runInteractiveCommand(command, args) {
 }
 async function createProviderSandbox(provider, sandboxName, projectRoot) {
   try {
-    execSync16(`docker sandbox create --name ${sandboxName} claude ${projectRoot}`, {
+    execSync17(`docker sandbox create --name ${sandboxName} claude ${projectRoot}`, {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 120000
     });
@@ -11949,7 +12351,7 @@ async function createProviderSandbox(provider, sandboxName, projectRoot) {
 }
 async function ensurePackageManagerInSandbox(sandboxName, pm) {
   try {
-    execSync16(`docker sandbox exec ${sandboxName} which ${pm}`, {
+    execSync17(`docker sandbox exec ${sandboxName} which ${pm}`, {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000
     });
@@ -11958,7 +12360,7 @@ async function ensurePackageManagerInSandbox(sandboxName, pm) {
     process.stderr.write(`Installing ${bold(pm)} in sandbox...
 `);
     try {
-      execSync16(`docker sandbox exec ${sandboxName} npm install -g ${npmPkg}`, {
+      execSync17(`docker sandbox exec ${sandboxName} npm install -g ${npmPkg}`, {
         stdio: "inherit",
         timeout: 120000
       });
@@ -11970,7 +12372,7 @@ async function ensurePackageManagerInSandbox(sandboxName, pm) {
 }
 async function ensureCodexInSandbox(sandboxName) {
   try {
-    execSync16(`docker sandbox exec ${sandboxName} which codex`, {
+    execSync17(`docker sandbox exec ${sandboxName} which codex`, {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000
     });
@@ -11978,7 +12380,7 @@ async function ensureCodexInSandbox(sandboxName) {
     process.stderr.write(`Installing codex in sandbox...
 `);
     try {
-      execSync16(`docker sandbox exec ${sandboxName} npm install -g @openai/codex`, { stdio: "inherit", timeout: 120000 });
+      execSync17(`docker sandbox exec ${sandboxName} npm install -g @openai/codex`, { stdio: "inherit", timeout: 120000 });
     } catch {
       process.stderr.write(`${red("✗")} Failed to install codex in sandbox.
 `);
@@ -11987,7 +12389,7 @@ async function ensureCodexInSandbox(sandboxName) {
 }
 function isSandboxAlive(name) {
   try {
-    const output = execSync16("docker sandbox ls", {
+    const output = execSync17("docker sandbox ls", {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000
@@ -12000,6 +12402,7 @@ function isSandboxAlive(name) {
 var PROVIDERS;
 var init_sandbox2 = __esm(() => {
   init_config();
+  init_ecosystem();
   init_sandbox();
   init_sandbox_ignore();
   init_terminal();
@@ -12012,13 +12415,13 @@ init_context();
 init_logger();
 init_rate_limiter();
 init_terminal();
-import { existsSync as existsSync23, readFileSync as readFileSync18 } from "node:fs";
-import { join as join23 } from "node:path";
+import { existsSync as existsSync25, readFileSync as readFileSync18 } from "node:fs";
+import { join as join25 } from "node:path";
 import { fileURLToPath } from "node:url";
 function getCliVersion() {
   const fallbackVersion = "0.0.0";
-  const packageJsonPath = join23(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
-  if (!existsSync23(packageJsonPath)) {
+  const packageJsonPath = join25(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
+  if (!existsSync25(packageJsonPath)) {
     return fallbackVersion;
   }
   try {
@@ -12283,7 +12686,7 @@ async function main() {
     try {
       const root = getGitRoot(cwd);
       if (isInitialized(root)) {
-        logDir = join23(root, ".locus", "logs");
+        logDir = join25(root, ".locus", "logs");
         getRateLimiter(root);
       }
     } catch {}