@locusai/cli 0.17.9 → 0.17.11

package/bin/locus.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1321,7 +1325,7 @@ 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 = gh(`pr create --title ${JSON.stringify(title)} --body ${JSON.stringify(body)} --head ${JSON.stringify(head)} --base ${JSON.stringify(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}`);
@@ -1683,6 +1687,496 @@ var init_init = __esm(() => {
   ];
 });
 
+// src/packages/registry.ts
+import {
+  existsSync as existsSync6,
+  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";
+function getPackagesDir() {
+  const dir = join6(homedir2(), ".locus", "packages");
+  if (!existsSync6(dir)) {
+    mkdirSync6(dir, { recursive: true });
+  }
+  const pkgJson = join6(dir, "package.json");
+  if (!existsSync6(pkgJson)) {
+    writeFileSync5(pkgJson, `${JSON.stringify({ private: true }, null, 2)}
+`, "utf-8");
+  }
+  return dir;
+}
+function getRegistryPath() {
+  return join6(getPackagesDir(), "registry.json");
+}
+function loadRegistry() {
+  const registryPath = getRegistryPath();
+  if (!existsSync6(registryPath)) {
+    return { packages: {} };
+  }
+  try {
+    const raw = readFileSync5(registryPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "packages" in parsed && typeof parsed.packages === "object") {
+      return parsed;
+    }
+    return { packages: {} };
+  } catch {
+    return { packages: {} };
+  }
+}
+function saveRegistry(registry) {
+  const registryPath = getRegistryPath();
+  const tmp = `${registryPath}.tmp`;
+  writeFileSync5(tmp, `${JSON.stringify(registry, null, 2)}
+`, "utf-8");
+  renameSync(tmp, registryPath);
+}
+function resolvePackageBinary(packageName) {
+  const fullName = normalizePackageName(packageName);
+  const binPath = join6(getPackagesDir(), "node_modules", ".bin", fullName);
+  return existsSync6(binPath) ? binPath : null;
+}
+function normalizePackageName(input) {
+  if (input.startsWith("@")) {
+    return input;
+  }
+  if (input.startsWith("locus-")) {
+    return input;
+  }
+  return `locus-${input}`;
+}
+var init_registry = () => {};
+
+// src/commands/pkg.ts
+var exports_pkg = {};
+__export(exports_pkg, {
+  pkgCommand: () => pkgCommand,
+  listInstalledPackages: () => listInstalledPackages
+});
+import { spawn } from "node:child_process";
+import { existsSync as existsSync7 } from "node:fs";
+function listInstalledPackages() {
+  const registry = loadRegistry();
+  const entries = Object.values(registry.packages);
+  if (entries.length === 0) {
+    process.stderr.write(`${yellow("⚠")}  No packages installed.
+`);
+    process.stderr.write(`  Install one with: ${bold("locus install <package>")}
+`);
+    return;
+  }
+  process.stderr.write(`
+${bold("Installed packages:")}
+
+`);
+  for (const entry of entries) {
+    const { name, version, manifest } = entry;
+    const displayName = manifest.displayName || name;
+    process.stderr.write(`  ${bold(cyan(displayName))} ${dim(`v${version}`)}
+`);
+    if (manifest.description) {
+      process.stderr.write(`  ${dim(manifest.description)}
+`);
+    }
+    if (manifest.commands.length > 0) {
+      process.stderr.write(`  Commands: ${manifest.commands.map((c) => green(c)).join(", ")}
+`);
+    }
+    process.stderr.write(`  Run: ${bold(`locus pkg ${name.replace(/^locus-/, "")} --help`)}
+`);
+    process.stderr.write(`
+`);
+  }
+}
+function spawnPackageBinary(binaryPath, args) {
+  return new Promise((resolve) => {
+    const child = spawn(binaryPath, args, {
+      stdio: "inherit",
+      env: { ...process.env, LOCUS_PKG: "1" }
+    });
+    const onSigint = () => {
+      child.kill("SIGINT");
+    };
+    process.on("SIGINT", onSigint);
+    child.on("error", (err) => {
+      process.removeListener("SIGINT", onSigint);
+      process.stderr.write(`${red("✗")} Failed to spawn binary: ${err.message}
+`);
+      resolve(1);
+    });
+    child.on("close", (code, signal) => {
+      process.removeListener("SIGINT", onSigint);
+      if (signal) {
+        resolve(signal === "SIGINT" ? 130 : 1);
+      } else {
+        resolve(code ?? 0);
+      }
+    });
+  });
+}
+async function pkgCommand(args, _flags) {
+  const packageInput = args[0];
+  if (!packageInput) {
+    listInstalledPackages();
+    return;
+  }
+  const packageName = normalizePackageName(packageInput);
+  const registry = loadRegistry();
+  const entry = registry.packages[packageName];
+  if (!entry) {
+    process.stderr.write(`${red("✗")} Package ${bold(`'${packageInput}'`)} is not installed.
+`);
+    process.stderr.write(`  Run: ${bold(`locus install ${packageInput}`)}
+`);
+    process.exit(1);
+    return;
+  }
+  const binaryPath = entry.binaryPath;
+  if (!binaryPath || !existsSync7(binaryPath)) {
+    process.stderr.write(`${red("✗")} Binary for ${bold(packageName)} not found on disk.
+`);
+    if (binaryPath) {
+      process.stderr.write(`  Expected: ${dim(binaryPath)}
+`);
+    }
+    process.stderr.write(`  Try reinstalling: ${bold(`locus install ${packageInput} --upgrade`)}
+`);
+    process.exit(1);
+    return;
+  }
+  const remainingArgs = args.slice(1);
+  const exitCode = await spawnPackageBinary(binaryPath, remainingArgs);
+  process.exit(exitCode);
+}
+var init_pkg = __esm(() => {
+  init_terminal();
+  init_registry();
+});
+
+// src/commands/packages.ts
+var exports_packages = {};
+__export(exports_packages, {
+  packagesCommand: () => packagesCommand
+});
+import { spawnSync } from "node:child_process";
+function checkOutdated() {
+  const registry = loadRegistry();
+  const entries = Object.values(registry.packages);
+  if (entries.length === 0) {
+    process.stderr.write(`${yellow("⚠")}  No packages installed.
+`);
+    process.stderr.write(`  Install one with: ${bold("locus install <package>")}
+`);
+    return;
+  }
+  process.stderr.write(`
+Checking for updates...
+
+`);
+  const outdated = [];
+  const upToDate = [];
+  for (const entry of entries) {
+    const result = spawnSync("npm", ["view", entry.name, "version"], {
+      encoding: "utf-8",
+      shell: false
+    });
+    if (result.error || result.status !== 0) {
+      process.stderr.write(`${yellow("⚠")}  Could not check ${bold(entry.name)}: ${result.error?.message ?? "npm view failed"}
+`);
+      continue;
+    }
+    const latest = (result.stdout ?? "").trim();
+    if (!latest) {
+      process.stderr.write(`${yellow("⚠")}  Could not determine latest version for ${bold(entry.name)}
+`);
+      continue;
+    }
+    if (latest !== entry.version) {
+      outdated.push({ name: entry.name, installed: entry.version, latest });
+    } else {
+      upToDate.push(entry.name);
+    }
+  }
+  if (outdated.length === 0) {
+    process.stderr.write(`${green("✓")} All packages are up to date.
+
+`);
+    return;
+  }
+  process.stderr.write(`${bold("Outdated packages:")}
+
+`);
+  const nameWidth = Math.max("Package".length, ...outdated.map((e) => e.name.length));
+  const installedWidth = Math.max("Installed".length, ...outdated.map((e) => e.installed.length));
+  const latestWidth = Math.max("Latest".length, ...outdated.map((e) => e.latest.length));
+  const pad = (s, w) => s.padEnd(w);
+  process.stderr.write(`  ${bold(pad("Package", nameWidth))}  ${dim(pad("Installed", installedWidth))}  ${green(pad("Latest", latestWidth))}
+`);
+  process.stderr.write(`  ${"-".repeat(nameWidth)}  ${"-".repeat(installedWidth)}  ${"-".repeat(latestWidth)}
+`);
+  for (const entry of outdated) {
+    process.stderr.write(`  ${cyan(pad(entry.name, nameWidth))}  ${dim(pad(entry.installed, installedWidth))}  ${green(pad(entry.latest, latestWidth))}
+`);
+  }
+  process.stderr.write(`
+`);
+  process.stderr.write(`  Run ${bold("locus install <package> --upgrade")} to upgrade a package.
+
+`);
+  if (upToDate.length > 0) {
+    process.stderr.write(`  ${dim(`${upToDate.length} package(s) already up to date.`)}
+
+`);
+  }
+}
+async function packagesCommand(args, _flags) {
+  const subcommand = args[0] ?? "list";
+  switch (subcommand) {
+    case "list":
+      listInstalledPackages();
+      break;
+    case "outdated":
+      checkOutdated();
+      break;
+    default:
+      process.stderr.write(`${red("✗")} Unknown subcommand: ${bold(subcommand)}
+`);
+      process.stderr.write(`  Available: ${bold("list")}, ${bold("outdated")}
+`);
+      process.exit(1);
+  }
+}
+var init_packages = __esm(() => {
+  init_terminal();
+  init_registry();
+  init_pkg();
+});
+
+// src/commands/install.ts
+var exports_install = {};
+__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";
+function parsePackageArg(raw) {
+  if (raw.startsWith("@")) {
+    const slashIdx = raw.indexOf("/");
+    if (slashIdx !== -1) {
+      const afterSlash = raw.slice(slashIdx + 1);
+      const atIdx2 = afterSlash.indexOf("@");
+      if (atIdx2 !== -1) {
+        return {
+          name: raw.slice(0, slashIdx + 1 + atIdx2),
+          version: afterSlash.slice(atIdx2 + 1) || undefined
+        };
+      }
+    }
+    return { name: raw, version: undefined };
+  }
+  const atIdx = raw.indexOf("@");
+  if (atIdx !== -1) {
+    return {
+      name: raw.slice(0, atIdx),
+      version: raw.slice(atIdx + 1) || undefined
+    };
+  }
+  return { name: raw, version: undefined };
+}
+async function installCommand(args, flags) {
+  const rawArg = args[0];
+  if (!rawArg) {
+    process.stderr.write(`${red("✗")} Usage: locus install <package> [--version <ver>] [--upgrade]
+`);
+    process.exit(1);
+    return;
+  }
+  const { name: packageInput, version: inlineVersion } = parsePackageArg(rawArg);
+  const pinnedVersion = flags.version ?? inlineVersion;
+  const isUpgrade = flags.upgrade === "true";
+  const packageName = normalizePackageName(packageInput);
+  const versionSuffix = pinnedVersion ? `@${pinnedVersion}` : "@latest";
+  const packageSpec = `${packageName}${versionSuffix}`;
+  const registry = loadRegistry();
+  const existing = registry.packages[packageName];
+  if (existing && !isUpgrade) {
+    process.stderr.write(`${green("✓")} ${bold(packageName)} is already installed ${dim(`(v${existing.version})`)}
+`);
+    process.stderr.write(`  To upgrade, run: ${bold(`locus install ${packageInput} --upgrade`)}
+`);
+    return;
+  }
+  const packagesDir = getPackagesDir();
+  const action = existing ? "Upgrading" : "Installing";
+  process.stderr.write(`
+  ${action} ${bold(packageSpec)}...
+
+`);
+  const result = spawnSync2("npm", ["install", packageSpec], {
+    cwd: packagesDir,
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.error) {
+    process.stderr.write(`
+${red("✗")} Could not run npm: ${result.error.message}
+`);
+    process.stderr.write(`  Make sure npm is installed and available in your PATH.
+`);
+    process.exit(1);
+    return;
+  }
+  if (result.status !== 0) {
+    process.stderr.write(`
+${red("✗")} Failed to install ${bold(packageSpec)}.
+`);
+    process.stderr.write(`  Make sure the package exists on npm and you have network access.
+`);
+    process.exit(1);
+    return;
+  }
+  const installedPkgJsonPath = join7(packagesDir, "node_modules", packageName, "package.json");
+  if (!existsSync8(installedPkgJsonPath)) {
+    process.stderr.write(`
+${red("✗")} Package installed but package.json not found at:
+`);
+    process.stderr.write(`  ${dim(installedPkgJsonPath)}
+`);
+    process.exit(1);
+    return;
+  }
+  let installedPkgJson;
+  try {
+    installedPkgJson = JSON.parse(readFileSync6(installedPkgJsonPath, "utf-8"));
+  } catch {
+    process.stderr.write(`
+${red("✗")} Could not parse installed package.json.
+`);
+    process.exit(1);
+    return;
+  }
+  const installedVersion = installedPkgJson.version ?? "unknown";
+  const locusManifest = installedPkgJson.locus;
+  if (!locusManifest) {
+    process.stderr.write(`
+${yellow("⚠")}  ${bold(packageName)} does not have a "locus" field in package.json.
+`);
+    process.stderr.write(`  It may not integrate fully with the Locus CLI.
+`);
+  }
+  const binaryPath = resolvePackageBinary(packageName) ?? "";
+  if (!binaryPath) {
+    process.stderr.write(`
+${yellow("⚠")}  No binary found for ${bold(packageName)} in node_modules/.bin/.
+`);
+  }
+  const manifest = locusManifest ?? {
+    displayName: packageName,
+    description: "",
+    commands: [],
+    version: installedVersion
+  };
+  const entry = {
+    name: packageName,
+    version: installedVersion,
+    installedAt: new Date().toISOString(),
+    binaryPath,
+    manifest
+  };
+  registry.packages[packageName] = entry;
+  saveRegistry(registry);
+  const verb = existing ? "upgraded" : "installed";
+  process.stderr.write(`
+${green("✓")} Package ${verb} successfully!
+
+`);
+  process.stderr.write(`  Package: ${bold(cyan(packageName))}
+`);
+  process.stderr.write(`  Version: ${bold(installedVersion)}
+`);
+  if (manifest.commands.length > 0) {
+    process.stderr.write(`  Commands: ${manifest.commands.map((c) => bold(c)).join(", ")}
+`);
+  }
+  if (binaryPath) {
+    process.stderr.write(`  Binary:  ${dim(binaryPath)}
+`);
+  }
+  process.stderr.write(`
+`);
+}
+var init_install = __esm(() => {
+  init_terminal();
+  init_registry();
+});
+
+// src/commands/uninstall.ts
+var exports_uninstall = {};
+__export(exports_uninstall, {
+  uninstallCommand: () => uninstallCommand
+});
+import { spawnSync as spawnSync3 } from "node:child_process";
+async function uninstallCommand(args, _flags) {
+  const rawArg = args[0];
+  if (!rawArg) {
+    process.stderr.write(`${red("✗")} Usage: locus uninstall <package>
+`);
+    process.exit(1);
+    return;
+  }
+  const packageName = normalizePackageName(rawArg);
+  const registry = loadRegistry();
+  const existing = registry.packages[packageName];
+  if (!existing) {
+    process.stderr.write(`${red("✗")} Package ${bold(`'${rawArg}'`)} is not installed.
+`);
+    process.stderr.write(`  Run ${bold("locus packages list")} to see installed packages.
+`);
+    process.exit(1);
+    return;
+  }
+  const { version } = existing;
+  const packagesDir = getPackagesDir();
+  process.stderr.write(`
+  Uninstalling ${bold(cyan(packageName))} ${dim(`v${version}`)}...
+
+`);
+  const result = spawnSync3("npm", ["uninstall", packageName], {
+    cwd: packagesDir,
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.error) {
+    process.stderr.write(`
+${red("✗")} Could not run npm: ${result.error.message}
+`);
+    process.stderr.write(`  Make sure npm is installed and available in your PATH.
+`);
+    process.exit(1);
+    return;
+  }
+  if (result.status !== 0) {
+    process.stderr.write(`
+${red("✗")} npm uninstall failed for ${bold(packageName)}.
+`);
+    process.exit(1);
+    return;
+  }
+  delete registry.packages[packageName];
+  saveRegistry(registry);
+  process.stderr.write(`${green("✓")} Uninstalled ${bold(cyan(packageName))} ${dim(`v${version}`)}
+`);
+}
+var init_uninstall = __esm(() => {
+  init_terminal();
+  init_registry();
+});
+
 // src/commands/config.ts
 var exports_config = {};
 __export(exports_config, {
@@ -1822,16 +2316,16 @@ __export(exports_logs, {
   logsCommand: () => logsCommand
 });
 import {
-  existsSync as existsSync6,
+  existsSync as existsSync9,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync5,
+  readFileSync as readFileSync7,
   statSync as statSync2,
   unlinkSync as unlinkSync2
 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join8 } from "node:path";
 async function logsCommand(cwd, options) {
-  const logsDir = join6(cwd, ".locus", "logs");
-  if (!existsSync6(logsDir)) {
+  const logsDir = join8(cwd, ".locus", "logs");
+  if (!existsSync9(logsDir)) {
     process.stderr.write(`${dim("No logs found.")}
 `);
     return;
@@ -1851,7 +2345,7 @@ async function logsCommand(cwd, options) {
   return viewLog(logFiles[0], options.level, options.lines ?? 50);
 }
 function viewLog(logFile, levelFilter, maxLines) {
-  const content = readFileSync5(logFile, "utf-8");
+  const content = readFileSync7(logFile, "utf-8");
   const lines = content.trim().split(`
 `).filter(Boolean);
   process.stderr.write(`
@@ -1886,9 +2380,9 @@ async function tailLog(logFile, levelFilter) {
   process.stderr.write(`${bold("Tailing:")} ${dim(logFile)} ${dim("(Ctrl+C to stop)")}
 
 `);
-  let lastSize = existsSync6(logFile) ? statSync2(logFile).size : 0;
-  if (existsSync6(logFile)) {
-    const content = readFileSync5(logFile, "utf-8");
+  let lastSize = existsSync9(logFile) ? statSync2(logFile).size : 0;
+  if (existsSync9(logFile)) {
+    const content = readFileSync7(logFile, "utf-8");
     const lines = content.trim().split(`
 `).filter(Boolean);
     const recent = lines.slice(-10);
@@ -1906,12 +2400,12 @@ async function tailLog(logFile, levelFilter) {
   }
   return new Promise((resolve) => {
     const interval = setInterval(() => {
-      if (!existsSync6(logFile))
+      if (!existsSync9(logFile))
         return;
       const currentSize = statSync2(logFile).size;
       if (currentSize <= lastSize)
         return;
-      const content = readFileSync5(logFile, "utf-8");
+      const content = readFileSync7(logFile, "utf-8");
       const allLines = content.trim().split(`
 `).filter(Boolean);
       const oldContent = content.slice(0, lastSize);
@@ -1966,7 +2460,7 @@ function cleanLogs(logsDir) {
 `);
 }
 function getLogFiles(logsDir) {
-  return readdirSync2(logsDir).filter((f) => f.startsWith("locus-") && f.endsWith(".log")).map((f) => join6(logsDir, f)).sort((a, b) => statSync2(b).mtimeMs - statSync2(a).mtimeMs);
+  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);
 }
 function formatEntry(entry) {
   const time = dim(new Date(entry.ts).toLocaleTimeString());
@@ -2247,9 +2741,9 @@ var init_stream_renderer = __esm(() => {
 });
 
 // src/repl/image-detect.ts
-import { copyFileSync, existsSync as existsSync7, mkdirSync as mkdirSync6 } from "node:fs";
-import { homedir as homedir2, tmpdir } from "node:os";
-import { basename, extname, join as join7, resolve } from "node:path";
+import { copyFileSync, existsSync as existsSync10, mkdirSync as mkdirSync7 } from "node:fs";
+import { homedir as homedir3, tmpdir } from "node:os";
+import { basename, extname, join as join9, resolve } from "node:path";
 function detectImages(input) {
   const detected = [];
   const byResolved = new Map;
@@ -2347,7 +2841,7 @@ function addIfImage(rawPath, rawMatch, detected, byResolved) {
     return;
   let resolved = stripQuotes(rawPath).replace(/\\ /g, " ");
   if (resolved.startsWith("~/")) {
-    resolved = join7(homedir2(), resolved.slice(2));
+    resolved = join9(homedir3(), resolved.slice(2));
   }
   resolved = resolve(resolved);
   const existing = byResolved.get(resolved);
@@ -2360,7 +2854,7 @@ function addIfImage(rawPath, rawMatch, detected, byResolved) {
     ]);
     return;
   }
-  const exists = existsSync7(resolved);
+  const exists = existsSync10(resolved);
   let stablePath = resolved;
   if (exists) {
     stablePath = copyToStable(resolved);
@@ -2414,10 +2908,10 @@ function dedupeByResolvedPath(images) {
 }
 function copyToStable(sourcePath) {
   try {
-    if (!existsSync7(STABLE_DIR)) {
-      mkdirSync6(STABLE_DIR, { recursive: true });
+    if (!existsSync10(STABLE_DIR)) {
+      mkdirSync7(STABLE_DIR, { recursive: true });
     }
-    const dest = join7(STABLE_DIR, `${Date.now()}-${basename(sourcePath)}`);
+    const dest = join9(STABLE_DIR, `${Date.now()}-${basename(sourcePath)}`);
     copyFileSync(sourcePath, dest);
     return dest;
   } catch {
@@ -2437,7 +2931,7 @@ var init_image_detect = __esm(() => {
     ".tif",
     ".tiff"
   ]);
-  STABLE_DIR = join7(tmpdir(), "locus-images");
+  STABLE_DIR = join9(tmpdir(), "locus-images");
   PLACEHOLDER_ID_PATTERN = /\(locus:\/\/screenshot-(\d+)\)/g;
 });
 
@@ -2482,6 +2976,8 @@ class InputHandler {
       let pasteBuffer = "";
       let imageAttachments = [];
       let nextImageId = 1;
+      let pasteAttachments = [];
+      let nextPasteId = 1;
       const history = this.getHistory();
       let historyIndex = -1;
       let historyDraft = "";
@@ -2527,6 +3023,15 @@ class InputHandler {
         preferredColumn = null;
         resetHistoryNavigation();
       };
+      const insertRaw = (text) => {
+        if (!text)
+          return;
+        const next = buffer.slice(0, cursor) + text + buffer.slice(cursor);
+        cursor += text.length;
+        setBuffer(next);
+        preferredColumn = null;
+        resetHistoryNavigation();
+      };
       const deleteBeforeCursor = () => {
         if (cursor === 0)
           return;
@@ -2628,6 +3133,8 @@ class InputHandler {
         setBuffer(history[historyIndex] ?? "");
         imageAttachments = [];
         nextImageId = 1;
+        pasteAttachments = [];
+        nextPasteId = 1;
         cursor = buffer.length;
         preferredColumn = null;
       };
@@ -2639,12 +3146,16 @@ class InputHandler {
           setBuffer(history[historyIndex] ?? "");
           imageAttachments = [];
           nextImageId = 1;
+          pasteAttachments = [];
+          nextPasteId = 1;
         } else {
           historyIndex = -1;
           setBuffer(historyDraft);
           historyDraft = "";
           imageAttachments = [];
           nextImageId = 1;
+          pasteAttachments = [];
+          nextPasteId = 1;
         }
         cursor = buffer.length;
         preferredColumn = null;
@@ -2699,9 +3210,10 @@ class InputHandler {
         imageAttachments = normalized.attachments;
         nextImageId = normalized.nextId;
         const images = collectReferencedAttachments(buffer, imageAttachments);
+        const finalText = expandPastePlaceholders(buffer, pasteAttachments);
         out.write(`\r
 `);
-        finish({ type: "submit", text: buffer, images });
+        finish({ type: "submit", text: finalText, images });
       };
       const clearBufferOrInterrupt = () => {
         if (buffer.length > 0) {
@@ -2709,6 +3221,8 @@ class InputHandler {
           cursor = 0;
           imageAttachments = [];
           nextImageId = 1;
+          pasteAttachments = [];
+          nextPasteId = 1;
           preferredColumn = null;
           resetHistoryNavigation();
           render();
@@ -2729,11 +3243,19 @@ ${dim("Press Ctrl+C again to exit")}\r
       const maybeHeuristicPaste = (chunk) => {
         if (chunk.includes(ESC))
           return false;
-        if (!looksLikePaste(chunk) && !looksLikeImagePathChunk(chunk)) {
+        const isImagePath = looksLikeImagePathChunk(chunk);
+        if (!looksLikePaste(chunk) && !isImagePath) {
           return false;
         }
         const normalized = normalizeLineEndings(chunk);
-        insertText(normalized);
+        if (!isImagePath && normalized.includes(`
+`)) {
+          const id = nextPasteId++;
+          pasteAttachments.push({ id, content: normalized });
+          insertRaw(buildPastePlaceholder(id, normalized));
+        } else {
+          insertText(normalized);
+        }
         render();
         return true;
       };
@@ -2858,8 +3380,16 @@ ${dim("Press Ctrl+C again to exit")}\r
             pasteBuffer += pending.slice(0, endIdx);
             pending = pending.slice(endIdx + PASTE_END.length);
             isPasting = false;
-            insertText(normalizeLineEndings(pasteBuffer));
+            const pasteContent = normalizeLineEndings(pasteBuffer);
             pasteBuffer = "";
+            if (pasteContent.includes(`
+`)) {
+              const id = nextPasteId++;
+              pasteAttachments.push({ id, content: pasteContent });
+              insertRaw(buildPastePlaceholder(id, pasteContent));
+            } else {
+              insertText(pasteContent);
+            }
             render();
             continue;
           }
@@ -3016,6 +3546,19 @@ function looksLikePaste(chunk) {
   return chunk.includes(`
 `) || chunk.includes("\r");
 }
+function buildPastePlaceholder(id, content) {
+  const lines = content.split(`
+`);
+  const lineCount = content.endsWith(`
+`) ? lines.length - 1 : lines.length;
+  return `[Pasted text #${id} +${lineCount} lines]`;
+}
+function expandPastePlaceholders(text, attachments) {
+  return text.replace(/\[Pasted text #(\d+) \+\d+ lines\]/g, (_, idStr) => {
+    const id = parseInt(idStr, 10);
+    return attachments.find((a) => a.id === id)?.content ?? "";
+  });
+}
 function looksLikeImagePathChunk(chunk) {
   if (chunk.length <= 1)
     return false;
@@ -3112,10 +3655,13 @@ function listenForInterrupt(onInterrupt, onForceExit) {
   const wasRaw = stdin.isRaw;
   stdin.setRawMode(true);
   stdin.resume();
+  process.stderr.write(ENABLE_BRACKETED_PASTE);
   let interrupted = false;
   let interruptTime = 0;
   const handler = (data) => {
     const seq = data.toString();
+    if (seq.startsWith(PASTE_START) || seq === PASTE_END)
+      return;
     if (seq === "\x1B" || seq === "\x03") {
       const now = Date.now();
       if (interrupted && now - interruptTime < 2000 && onForceExit) {
@@ -3135,6 +3681,7 @@ ${dim("Press")} ${yellow("ESC")} ${dim("again to force exit")}\r
   stdin.on("data", handler);
   return () => {
     stdin.removeListener("data", handler);
+    process.stderr.write(DISABLE_BRACKETED_PASTE);
     if (wasRaw !== undefined && stdin.isTTY) {
       stdin.setRawMode(wasRaw);
     }
@@ -3202,7 +3749,7 @@ var init_input_handler = __esm(() => {
 });
 
 // src/ai/claude.ts
-import { execSync as execSync4, spawn } from "node:child_process";
+import { execSync as execSync4, spawn as spawn2 } from "node:child_process";
 
 class ClaudeRunner {
   name = "claude";
@@ -3248,7 +3795,7 @@ class ClaudeRunner {
       const env = { ...process.env };
       delete env.CLAUDECODE;
       delete env.CLAUDE_CODE;
-      this.process = spawn("claude", args, {
+      this.process = spawn2("claude", args, {
         cwd: options.cwd,
         stdio: ["pipe", "pipe", "pipe"],
         env
@@ -3330,7 +3877,7 @@ var init_claude = __esm(() => {
 });
 
 // src/ai/codex.ts
-import { execSync as execSync5, spawn as spawn2 } from "node:child_process";
+import { execSync as execSync5, spawn as spawn3 } from "node:child_process";
 function buildCodexArgs(model) {
   const args = ["exec", "--full-auto", "--skip-git-repo-check"];
   if (model) {
@@ -3374,7 +3921,7 @@ class CodexRunner {
     return new Promise((resolve2) => {
       let output = "";
       let errorOutput = "";
-      this.process = spawn2("codex", args, {
+      this.process = spawn3("codex", args, {
         cwd: options.cwd,
         stdio: ["pipe", "pipe", "pipe"],
         env: { ...process.env }
@@ -4964,8 +5511,8 @@ var init_sprint = __esm(() => {
 
 // src/core/prompt-builder.ts
 import { execSync as execSync6 } from "node:child_process";
-import { existsSync as existsSync8, readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync11, readdirSync as readdirSync3, readFileSync as readFileSync8 } from "node:fs";
+import { join as join10 } from "node:path";
 function buildExecutionPrompt(ctx) {
   const sections = [];
   sections.push(buildSystemContext(ctx.projectRoot));
@@ -4995,13 +5542,13 @@ function buildFeedbackPrompt(ctx) {
 }
 function buildReplPrompt(userMessage, projectRoot, _config, previousMessages) {
   const sections = [];
-  const locusmd = readFileSafe(join8(projectRoot, "LOCUS.md"));
+  const locusmd = readFileSafe(join10(projectRoot, "LOCUS.md"));
   if (locusmd) {
     sections.push(`# Project Instructions
 
 ${locusmd}`);
   }
-  const learnings = readFileSafe(join8(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join10(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     sections.push(`# Past Learnings
 
@@ -5027,24 +5574,24 @@ ${userMessage}`);
 }
 function buildSystemContext(projectRoot) {
   const parts = ["# System Context"];
-  const locusmd = readFileSafe(join8(projectRoot, "LOCUS.md"));
+  const locusmd = readFileSafe(join10(projectRoot, "LOCUS.md"));
   if (locusmd) {
     parts.push(`## Project Instructions (LOCUS.md)
 
 ${locusmd}`);
   }
-  const learnings = readFileSafe(join8(projectRoot, ".locus", "LEARNINGS.md"));
+  const learnings = readFileSafe(join10(projectRoot, ".locus", "LEARNINGS.md"));
   if (learnings) {
     parts.push(`## Past Learnings
 
 ${learnings}`);
   }
-  const discussionsDir = join8(projectRoot, ".locus", "discussions");
-  if (existsSync8(discussionsDir)) {
+  const discussionsDir = join10(projectRoot, ".locus", "discussions");
+  if (existsSync11(discussionsDir)) {
     try {
       const files = readdirSync3(discussionsDir).filter((f) => f.endsWith(".md")).slice(0, 3);
       for (const file of files) {
-        const content = readFileSafe(join8(discussionsDir, file));
+        const content = readFileSafe(join10(discussionsDir, file));
         if (content) {
           parts.push(`## Discussion: ${file.replace(".md", "")}
 
@@ -5190,9 +5737,9 @@ function buildFeedbackInstructions() {
 }
 function readFileSafe(path) {
   try {
-    if (!existsSync8(path))
+    if (!existsSync11(path))
       return null;
-    return readFileSync6(path, "utf-8");
+    return readFileSync8(path, "utf-8");
   } catch {
     return null;
   }
@@ -5622,7 +6169,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 join9 } from "node:path";
+import { basename as basename2, dirname as dirname3, join as join11 } from "node:path";
 
 class SlashCommandCompletion {
   commands;
@@ -5677,7 +6224,7 @@ class FilePathCompletion {
   }
   findMatches(partial) {
     try {
-      const dir = partial.includes("/") ? join9(this.projectRoot, dirname3(partial)) : this.projectRoot;
+      const dir = partial.includes("/") ? join11(this.projectRoot, dirname3(partial)) : this.projectRoot;
       const prefix = basename2(partial);
       const entries = readdirSync4(dir, { withFileTypes: true });
       return entries.filter((e) => {
@@ -5713,14 +6260,14 @@ class CombinedCompletion {
 var init_completions = () => {};
 
 // src/repl/input-history.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname4, join as join10 } from "node:path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync8, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname4, join as join12 } from "node:path";
 
 class InputHistory {
   entries = [];
   filePath;
   constructor(projectRoot) {
-    this.filePath = join10(projectRoot, ".locus", "sessions", ".input-history");
+    this.filePath = join12(projectRoot, ".locus", "sessions", ".input-history");
     this.load();
   }
   add(text) {
@@ -5759,9 +6306,9 @@ class InputHistory {
   }
   load() {
     try {
-      if (!existsSync9(this.filePath))
+      if (!existsSync12(this.filePath))
         return;
-      const content = readFileSync7(this.filePath, "utf-8");
+      const content = readFileSync9(this.filePath, "utf-8");
       this.entries = content.split(`
 `).map((line) => this.unescape(line)).filter(Boolean);
     } catch {}
@@ -5769,12 +6316,12 @@ class InputHistory {
   save() {
     try {
       const dir = dirname4(this.filePath);
-      if (!existsSync9(dir)) {
-        mkdirSync7(dir, { recursive: true });
+      if (!existsSync12(dir)) {
+        mkdirSync8(dir, { recursive: true });
       }
       const content = this.entries.map((e) => this.escape(e)).join(`
 `);
-      writeFileSync5(this.filePath, content, "utf-8");
+      writeFileSync6(this.filePath, content, "utf-8");
     } catch {}
   }
   escape(text) {
@@ -5801,21 +6348,21 @@ var init_model_config = __esm(() => {
 // src/repl/session-manager.ts
 import { randomBytes } from "node:crypto";
 import {
-  existsSync as existsSync10,
-  mkdirSync as mkdirSync8,
+  existsSync as existsSync13,
+  mkdirSync as mkdirSync9,
   readdirSync as readdirSync5,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync10,
   unlinkSync as unlinkSync3,
-  writeFileSync as writeFileSync6
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import { basename as basename3, join as join11 } from "node:path";
+import { basename as basename3, join as join13 } from "node:path";
 
 class SessionManager {
   sessionsDir;
   constructor(projectRoot) {
-    this.sessionsDir = join11(projectRoot, ".locus", "sessions");
-    if (!existsSync10(this.sessionsDir)) {
-      mkdirSync8(this.sessionsDir, { recursive: true });
+    this.sessionsDir = join13(projectRoot, ".locus", "sessions");
+    if (!existsSync13(this.sessionsDir)) {
+      mkdirSync9(this.sessionsDir, { recursive: true });
     }
   }
   create(options) {
@@ -5840,14 +6387,14 @@ class SessionManager {
   }
   isPersisted(sessionOrId) {
     const sessionId = typeof sessionOrId === "string" ? sessionOrId : sessionOrId.id;
-    return existsSync10(this.getSessionPath(sessionId));
+    return existsSync13(this.getSessionPath(sessionId));
   }
   load(idOrPrefix) {
     const files = this.listSessionFiles();
     const exactPath = this.getSessionPath(idOrPrefix);
-    if (existsSync10(exactPath)) {
+    if (existsSync13(exactPath)) {
       try {
-        return JSON.parse(readFileSync8(exactPath, "utf-8"));
+        return JSON.parse(readFileSync10(exactPath, "utf-8"));
       } catch {
         return null;
       }
@@ -5855,7 +6402,7 @@ class SessionManager {
     const matches = files.filter((f) => basename3(f, ".json").startsWith(idOrPrefix));
     if (matches.length === 1) {
       try {
-        return JSON.parse(readFileSync8(matches[0], "utf-8"));
+        return JSON.parse(readFileSync10(matches[0], "utf-8"));
       } catch {
         return null;
       }
@@ -5868,7 +6415,7 @@ class SessionManager {
   save(session) {
     session.updated = new Date().toISOString();
     const path = this.getSessionPath(session.id);
-    writeFileSync6(path, `${JSON.stringify(session, null, 2)}
+    writeFileSync7(path, `${JSON.stringify(session, null, 2)}
 `, "utf-8");
   }
   addMessage(session, message) {
@@ -5880,7 +6427,7 @@ class SessionManager {
     const sessions = [];
     for (const file of files) {
       try {
-        const session = JSON.parse(readFileSync8(file, "utf-8"));
+        const session = JSON.parse(readFileSync10(file, "utf-8"));
         sessions.push({
           id: session.id,
           created: session.created,
@@ -5895,7 +6442,7 @@ class SessionManager {
   }
   delete(sessionId) {
     const path = this.getSessionPath(sessionId);
-    if (existsSync10(path)) {
+    if (existsSync13(path)) {
       unlinkSync3(path);
       return true;
     }
@@ -5907,7 +6454,7 @@ class SessionManager {
     let pruned = 0;
     const withStats = files.map((f) => {
       try {
-        const session = JSON.parse(readFileSync8(f, "utf-8"));
+        const session = JSON.parse(readFileSync10(f, "utf-8"));
         return { path: f, updated: new Date(session.updated).getTime() };
       } catch {
         return { path: f, updated: 0 };
@@ -5925,7 +6472,7 @@ class SessionManager {
     const remaining = withStats.length - pruned;
     if (remaining > MAX_SESSIONS) {
       const toRemove = remaining - MAX_SESSIONS;
-      const alive = withStats.filter((e) => existsSync10(e.path));
+      const alive = withStats.filter((e) => existsSync13(e.path));
       for (let i = 0;i < toRemove && i < alive.length; i++) {
         try {
           unlinkSync3(alive[i].path);
@@ -5940,7 +6487,7 @@ class SessionManager {
   }
   listSessionFiles() {
     try {
-      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join11(this.sessionsDir, f));
+      return readdirSync5(this.sessionsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => join13(this.sessionsDir, f));
     } catch {
       return [];
     }
@@ -5949,7 +6496,7 @@ class SessionManager {
     return randomBytes(6).toString("hex");
   }
   getSessionPath(sessionId) {
-    return join11(this.sessionsDir, `${sessionId}.json`);
+    return join13(this.sessionsDir, `${sessionId}.json`);
   }
 }
 var MAX_SESSIONS = 50, SESSION_MAX_AGE_MS;
@@ -6734,22 +7281,22 @@ var init_conflict = __esm(() => {
 
 // src/core/run-state.ts
 import {
-  existsSync as existsSync11,
-  mkdirSync as mkdirSync9,
-  readFileSync as readFileSync9,
+  existsSync as existsSync14,
+  mkdirSync as mkdirSync10,
+  readFileSync as readFileSync11,
   unlinkSync as unlinkSync4,
-  writeFileSync as writeFileSync7
+  writeFileSync as writeFileSync8
 } from "node:fs";
-import { dirname as dirname5, join as join12 } from "node:path";
+import { dirname as dirname5, join as join14 } from "node:path";
 function getRunStatePath(projectRoot) {
-  return join12(projectRoot, ".locus", "run-state.json");
+  return join14(projectRoot, ".locus", "run-state.json");
 }
 function loadRunState(projectRoot) {
   const path = getRunStatePath(projectRoot);
-  if (!existsSync11(path))
+  if (!existsSync14(path))
     return null;
   try {
-    return JSON.parse(readFileSync9(path, "utf-8"));
+    return JSON.parse(readFileSync11(path, "utf-8"));
   } catch {
     getLogger().warn("Corrupted run-state.json, ignoring");
     return null;
@@ -6758,15 +7305,15 @@ function loadRunState(projectRoot) {
 function saveRunState(projectRoot, state) {
   const path = getRunStatePath(projectRoot);
   const dir = dirname5(path);
-  if (!existsSync11(dir)) {
-    mkdirSync9(dir, { recursive: true });
+  if (!existsSync14(dir)) {
+    mkdirSync10(dir, { recursive: true });
   }
-  writeFileSync7(path, `${JSON.stringify(state, null, 2)}
+  writeFileSync8(path, `${JSON.stringify(state, null, 2)}
 `, "utf-8");
 }
 function clearRunState(projectRoot) {
   const path = getRunStatePath(projectRoot);
-  if (existsSync11(path)) {
+  if (existsSync14(path)) {
     unlinkSync4(path);
   }
 }
@@ -6907,8 +7454,8 @@ var init_shutdown = __esm(() => {
 
 // src/core/worktree.ts
 import { execSync as execSync11 } from "node:child_process";
-import { existsSync as existsSync12, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
-import { join as join13 } from "node:path";
+import { existsSync as existsSync15, readdirSync as readdirSync6, realpathSync, statSync as statSync3 } from "node:fs";
+import { join as join15 } from "node:path";
 function git3(args, cwd) {
   return execSync11(`git ${args}`, {
     cwd,
@@ -6924,10 +7471,10 @@ function gitSafe2(args, cwd) {
   }
 }
 function getWorktreeDir(projectRoot) {
-  return join13(projectRoot, ".locus", "worktrees");
+  return join15(projectRoot, ".locus", "worktrees");
 }
 function getWorktreePath(projectRoot, issueNumber) {
-  return join13(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
+  return join15(getWorktreeDir(projectRoot), `issue-${issueNumber}`);
 }
 function generateBranchName(issueNumber) {
   const randomSuffix = Math.random().toString(36).slice(2, 8);
@@ -6947,7 +7494,7 @@ function getWorktreeBranch(worktreePath) {
 function createWorktree(projectRoot, issueNumber, baseBranch) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (existsSync12(worktreePath)) {
+  if (existsSync15(worktreePath)) {
     log.verbose(`Worktree already exists for issue #${issueNumber}`);
     const existingBranch = getWorktreeBranch(worktreePath) ?? `locus/issue-${issueNumber}`;
     return {
@@ -6974,7 +7521,7 @@ function createWorktree(projectRoot, issueNumber, baseBranch) {
 function removeWorktree(projectRoot, issueNumber) {
   const log = getLogger();
   const worktreePath = getWorktreePath(projectRoot, issueNumber);
-  if (!existsSync12(worktreePath)) {
+  if (!existsSync15(worktreePath)) {
     log.verbose(`Worktree for issue #${issueNumber} does not exist`);
     return;
   }
@@ -6993,7 +7540,7 @@ function removeWorktree(projectRoot, issueNumber) {
 function listWorktrees(projectRoot) {
   const log = getLogger();
   const worktreeDir = getWorktreeDir(projectRoot);
-  if (!existsSync12(worktreeDir)) {
+  if (!existsSync15(worktreeDir)) {
     return [];
   }
   const entries = readdirSync6(worktreeDir).filter((entry) => entry.startsWith("issue-"));
@@ -7013,7 +7560,7 @@ function listWorktrees(projectRoot) {
     if (!match)
       continue;
     const issueNumber = Number.parseInt(match[1], 10);
-    const path = join13(worktreeDir, entry);
+    const path = join15(worktreeDir, entry);
     const branch = getWorktreeBranch(path) ?? `locus/issue-${issueNumber}`;
     let resolvedPath;
     try {
@@ -7253,7 +7800,18 @@ ${bold("Summary:")}
       issue: t.issue,
       title: issues.find((i) => i.number === t.issue)?.title
     }));
-    await createSprintPR(projectRoot, config, sprintName, branchName, completedTasks);
+    const prNumber = await createSprintPR(projectRoot, config, sprintName, branchName, completedTasks);
+    if (prNumber !== undefined) {
+      try {
+        execSync12(`git checkout ${config.agent.baseBranch}`, {
+          cwd: projectRoot,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        process.stderr.write(`  ${dim(`Checked out ${config.agent.baseBranch}`)}
+`);
+      } catch {}
+    }
   }
   if (stats.failed === 0) {
     clearRunState(projectRoot);
@@ -7490,7 +8048,18 @@ ${bold("Resume complete:")} ${green(`✓ ${finalStats.done}`)} ${finalStats.fail
 `);
   if (isSprintRun && state.branch && state.sprint && finalStats.done > 0) {
     const completedTasks = state.tasks.filter((t) => t.status === "done").map((t) => ({ issue: t.issue }));
-    await createSprintPR(projectRoot, config, state.sprint, state.branch, completedTasks);
+    const prNumber = await createSprintPR(projectRoot, config, state.sprint, state.branch, completedTasks);
+    if (prNumber !== undefined) {
+      try {
+        execSync12(`git checkout ${config.agent.baseBranch}`, {
+          cwd: projectRoot,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        process.stderr.write(`  ${dim(`Checked out ${config.agent.baseBranch}`)}
+`);
+      } catch {}
+    }
   }
   if (finalStats.failed === 0) {
     clearRunState(projectRoot);
@@ -7696,20 +8265,20 @@ __export(exports_plan, {
   parsePlanArgs: () => parsePlanArgs
 });
 import {
-  existsSync as existsSync13,
-  mkdirSync as mkdirSync10,
+  existsSync as existsSync16,
+  mkdirSync as mkdirSync11,
   readdirSync as readdirSync7,
-  readFileSync as readFileSync10,
-  writeFileSync as writeFileSync8
+  readFileSync as readFileSync12,
+  writeFileSync as writeFileSync9
 } from "node:fs";
-import { join as join14 } from "node:path";
+import { join as join16 } from "node:path";
 function printHelp() {
   process.stderr.write(`
 ${bold("locus plan")} — AI-powered sprint planning
 
 ${bold("Usage:")}
   locus plan "<directive>"                 ${dim("# AI creates a plan file")}
-  locus plan approve <id>                  ${dim("# Create GitHub issues from saved plan")}
+  locus plan approve <id> [--sprint <name>] ${dim("# Create GitHub issues from saved plan")}
   locus plan list                          ${dim("# List saved plans")}
   locus plan show <id>                     ${dim("# Show a saved plan")}
   locus plan --from-issues --sprint <name> ${dim("# Organize existing issues")}
@@ -7723,6 +8292,7 @@ ${bold("Examples:")}
   locus plan "Build user authentication with OAuth"
   locus plan "Improve API performance" --sprint "Sprint 3"
   locus plan approve abc123
+  locus plan approve abc123 --sprint "Sprint 3"
   locus plan list
   locus plan --from-issues --sprint "Sprint 2"
 
@@ -7732,12 +8302,12 @@ function normalizeSprintName(name) {
   return name.trim().toLowerCase();
 }
 function getPlansDir(projectRoot) {
-  return join14(projectRoot, ".locus", "plans");
+  return join16(projectRoot, ".locus", "plans");
 }
 function ensurePlansDir(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync13(dir)) {
-    mkdirSync10(dir, { recursive: true });
+  if (!existsSync16(dir)) {
+    mkdirSync11(dir, { recursive: true });
   }
   return dir;
 }
@@ -7746,14 +8316,14 @@ function generateId() {
 }
 function loadPlanFile(projectRoot, id) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync13(dir))
+  if (!existsSync16(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 = readFileSync10(join14(dir, match), "utf-8");
+    const content = readFileSync12(join16(dir, match), "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -7771,7 +8341,8 @@ async function planCommand(projectRoot, args, flags = {}) {
     return handleShowPlan(projectRoot, args[1]);
   }
   if (args[0] === "approve") {
-    return handleApprovePlan(projectRoot, args[1], flags);
+    const approveArgs = parsePlanArgs(args.slice(2));
+    return handleApprovePlan(projectRoot, args[1], { ...flags, dryRun: flags.dryRun || approveArgs.dryRun }, approveArgs.sprintName);
   }
   const parsedArgs = parsePlanArgs(args);
   if (parsedArgs.error) {
@@ -7798,7 +8369,7 @@ async function planCommand(projectRoot, args, flags = {}) {
 }
 function handleListPlans(projectRoot) {
   const dir = getPlansDir(projectRoot);
-  if (!existsSync13(dir)) {
+  if (!existsSync16(dir)) {
     process.stderr.write(`${dim("No saved plans yet.")}
 `);
     return;
@@ -7816,7 +8387,7 @@ ${bold("Saved Plans:")}
   for (const file of files) {
     const id = file.replace(".json", "");
     try {
-      const content = readFileSync10(join14(dir, file), "utf-8");
+      const content = readFileSync12(join16(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;
@@ -7829,7 +8400,7 @@ ${bold("Saved Plans:")}
   }
   process.stderr.write(`
 `);
-  process.stderr.write(`  Approve a plan: ${bold("locus plan approve <id>")}
+  process.stderr.write(`  Approve a plan: ${bold("locus plan approve <id> --sprint <name>")}
 
 `);
 }
@@ -7870,11 +8441,11 @@ ${bold("Plan:")} ${cyan(plan.directive)}
   }
   process.stderr.write(`
 `);
-  process.stderr.write(`  Approve: ${bold(`locus plan approve ${plan.id.slice(0, 8)}`)}
+  process.stderr.write(`  Approve: ${bold(`locus plan approve ${plan.id.slice(0, 8)}`)}  ${dim("(--sprint <name> to assign to a sprint)")}
 
 `);
 }
-async function handleApprovePlan(projectRoot, id, flags) {
+async function handleApprovePlan(projectRoot, id, flags, sprintOverride) {
   if (!id) {
     process.stderr.write(`${red("✗")} Please provide a plan ID.
 `);
@@ -7898,11 +8469,12 @@ async function handleApprovePlan(projectRoot, id, flags) {
     return;
   }
   const config = loadConfig(projectRoot);
+  const sprintName = sprintOverride ?? plan.sprint ?? undefined;
   process.stderr.write(`
-${bold("Approving plan:")} ${cyan(plan.directive)}
+${bold("Approving plan:")}
 `);
-  if (plan.sprint) {
-    process.stderr.write(`  ${dim(`Sprint: ${plan.sprint}`)}
+  if (sprintName) {
+    process.stderr.write(`  ${dim(`Sprint: ${sprintName}`)}
 `);
   }
   process.stderr.write(`
@@ -7921,12 +8493,12 @@ ${bold("Approving plan:")} ${cyan(plan.directive)}
 `);
     return;
   }
-  await createPlannedIssues(projectRoot, config, plan.issues, plan.sprint ?? undefined);
+  await createPlannedIssues(projectRoot, config, plan.issues, sprintName);
 }
 async function handleAIPlan(projectRoot, config, directive, sprintName, flags) {
   const id = generateId();
   const plansDir = ensurePlansDir(projectRoot);
-  const planPath = join14(plansDir, `${id}.json`);
+  const planPath = join16(plansDir, `${id}.json`);
   const planPathRelative = `.locus/plans/${id}.json`;
   const displayDirective = directive;
   process.stderr.write(`
@@ -7958,7 +8530,7 @@ ${red("✗")} Planning failed: ${aiResult.error}
 `);
     return;
   }
-  if (!existsSync13(planPath)) {
+  if (!existsSync16(planPath)) {
     process.stderr.write(`
 ${yellow("⚠")} Plan file was not created at ${bold(planPathRelative)}.
 `);
@@ -7968,7 +8540,7 @@ ${yellow("⚠")} Plan file was not created at ${bold(planPathRelative)}.
   }
   let plan;
   try {
-    const content = readFileSync10(planPath, "utf-8");
+    const content = readFileSync12(planPath, "utf-8");
     plan = JSON.parse(content);
   } catch {
     process.stderr.write(`
@@ -7990,7 +8562,7 @@ ${yellow("⚠")} Plan file has no issues.
     plan.sprint = sprintName;
   if (!plan.createdAt)
     plan.createdAt = new Date().toISOString();
-  writeFileSync8(planPath, JSON.stringify(plan, null, 2), "utf-8");
+  writeFileSync9(planPath, JSON.stringify(plan, null, 2), "utf-8");
   process.stderr.write(`
 ${bold("Plan saved:")} ${cyan(id)}
 
@@ -8123,16 +8695,16 @@ function buildPlanningPrompt(projectRoot, config, directive, sprintName, id, pla
     parts.push(`SPRINT: ${sprintName}`);
   }
   parts.push("");
-  const locusPath = join14(projectRoot, "LOCUS.md");
-  if (existsSync13(locusPath)) {
-    const content = readFileSync10(locusPath, "utf-8");
+  const locusPath = join16(projectRoot, "LOCUS.md");
+  if (existsSync16(locusPath)) {
+    const content = readFileSync12(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT (LOCUS.md):");
     parts.push(content.slice(0, 3000));
     parts.push("");
   }
-  const learningsPath = join14(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync13(learningsPath)) {
-    const content = readFileSync10(learningsPath, "utf-8");
+  const learningsPath = join16(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync16(learningsPath)) {
+    const content = readFileSync12(learningsPath, "utf-8");
     parts.push("PAST LEARNINGS:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -8309,8 +8881,8 @@ __export(exports_review, {
   reviewCommand: () => reviewCommand
 });
 import { execSync as execSync13 } from "node:child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync11 } from "node:fs";
-import { join as join15 } from "node:path";
+import { existsSync as existsSync17, readFileSync as readFileSync13 } from "node:fs";
+import { join as join17 } from "node:path";
 function printHelp2() {
   process.stderr.write(`
 ${bold("locus review")} — AI-powered code review
@@ -8467,9 +9039,9 @@ function buildReviewPrompt(projectRoot, config, pr, diff, focus) {
   const parts = [];
   parts.push(`You are an expert code reviewer for the ${config.github.owner}/${config.github.repo} repository.`);
   parts.push("");
-  const locusPath = join15(projectRoot, "LOCUS.md");
-  if (existsSync14(locusPath)) {
-    const content = readFileSync11(locusPath, "utf-8");
+  const locusPath = join17(projectRoot, "LOCUS.md");
+  if (existsSync17(locusPath)) {
+    const content = readFileSync13(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -8771,14 +9343,14 @@ __export(exports_discuss, {
   discussCommand: () => discussCommand
 });
 import {
-  existsSync as existsSync15,
-  mkdirSync as mkdirSync11,
+  existsSync as existsSync18,
+  mkdirSync as mkdirSync12,
   readdirSync as readdirSync8,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync14,
   unlinkSync as unlinkSync5,
-  writeFileSync as writeFileSync9
+  writeFileSync as writeFileSync10
 } from "node:fs";
-import { join as join16 } from "node:path";
+import { join as join18 } from "node:path";
 function printHelp4() {
   process.stderr.write(`
 ${bold("locus discuss")} — AI-powered architectural discussions
@@ -8800,12 +9372,12 @@ ${bold("Examples:")}
 `);
 }
 function getDiscussionsDir(projectRoot) {
-  return join16(projectRoot, ".locus", "discussions");
+  return join18(projectRoot, ".locus", "discussions");
 }
 function ensureDiscussionsDir(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync15(dir)) {
-    mkdirSync11(dir, { recursive: true });
+  if (!existsSync18(dir)) {
+    mkdirSync12(dir, { recursive: true });
   }
   return dir;
 }
@@ -8839,7 +9411,7 @@ async function discussCommand(projectRoot, args, flags = {}) {
 }
 function listDiscussions(projectRoot) {
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync15(dir)) {
+  if (!existsSync18(dir)) {
     process.stderr.write(`${dim("No discussions yet.")}
 `);
     return;
@@ -8856,7 +9428,7 @@ ${bold("Discussions:")}
 `);
   for (const file of files) {
     const id = file.replace(".md", "");
-    const content = readFileSync12(join16(dir, file), "utf-8");
+    const content = readFileSync14(join18(dir, file), "utf-8");
     const titleMatch = content.match(/^#\s+(.+)/m);
     const title = titleMatch ? titleMatch[1] : id;
     const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/);
@@ -8874,7 +9446,7 @@ function showDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync15(dir)) {
+  if (!existsSync18(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -8886,7 +9458,7 @@ function showDiscussion(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync12(join16(dir, match), "utf-8");
+  const content = readFileSync14(join18(dir, match), "utf-8");
   process.stdout.write(`${content}
 `);
 }
@@ -8897,7 +9469,7 @@ function deleteDiscussion(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync15(dir)) {
+  if (!existsSync18(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -8909,7 +9481,7 @@ function deleteDiscussion(projectRoot, id) {
 `);
     return;
   }
-  unlinkSync5(join16(dir, match));
+  unlinkSync5(join18(dir, match));
   process.stderr.write(`${green("✓")} Deleted discussion: ${match.replace(".md", "")}
 `);
 }
@@ -8922,7 +9494,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
     return;
   }
   const dir = getDiscussionsDir(projectRoot);
-  if (!existsSync15(dir)) {
+  if (!existsSync18(dir)) {
     process.stderr.write(`${red("✗")} No discussions found.
 `);
     return;
@@ -8934,7 +9506,7 @@ async function convertDiscussionToPlan(projectRoot, id) {
 `);
     return;
   }
-  const content = readFileSync12(join16(dir, match), "utf-8");
+  const content = readFileSync14(join18(dir, match), "utf-8");
   const titleMatch = content.match(/^#\s+(.+)/m);
   const discussionTitle = titleMatch ? titleMatch[1].trim() : id;
   await planCommand(projectRoot, [
@@ -9046,7 +9618,7 @@ ${turn.content}`;
     ...conversation.length > 1 ? [`---`, ``, `## Discussion Transcript`, ``, transcript, ``] : []
   ].join(`
 `);
-  writeFileSync9(join16(dir, `${id}.md`), markdown, "utf-8");
+  writeFileSync10(join18(dir, `${id}.md`), markdown, "utf-8");
   process.stderr.write(`
 ${green("✓")} Discussion saved: ${cyan(id)} ${dim(`(${timer.formatted()})`)}
 `);
@@ -9060,16 +9632,16 @@ function buildDiscussionPrompt(projectRoot, config, topic, conversation, forceFi
   const parts = [];
   parts.push(`You are a senior software architect and consultant for the ${config.github.owner}/${config.github.repo} project.`);
   parts.push("");
-  const locusPath = join16(projectRoot, "LOCUS.md");
-  if (existsSync15(locusPath)) {
-    const content = readFileSync12(locusPath, "utf-8");
+  const locusPath = join18(projectRoot, "LOCUS.md");
+  if (existsSync18(locusPath)) {
+    const content = readFileSync14(locusPath, "utf-8");
     parts.push("PROJECT CONTEXT:");
     parts.push(content.slice(0, 3000));
     parts.push("");
   }
-  const learningsPath = join16(projectRoot, ".locus", "LEARNINGS.md");
-  if (existsSync15(learningsPath)) {
-    const content = readFileSync12(learningsPath, "utf-8");
+  const learningsPath = join18(projectRoot, ".locus", "LEARNINGS.md");
+  if (existsSync18(learningsPath)) {
+    const content = readFileSync14(learningsPath, "utf-8");
     parts.push("PAST LEARNINGS:");
     parts.push(content.slice(0, 2000));
     parts.push("");
@@ -9128,8 +9700,8 @@ __export(exports_artifacts, {
   formatDate: () => formatDate2,
   artifactsCommand: () => artifactsCommand
 });
-import { existsSync as existsSync16, readdirSync as readdirSync9, readFileSync as readFileSync13, statSync as statSync4 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync19, readdirSync as readdirSync9, readFileSync as readFileSync15, statSync as statSync4 } from "node:fs";
+import { join as join19 } from "node:path";
 function printHelp5() {
   process.stderr.write(`
 ${bold("locus artifacts")} — View and manage AI-generated artifacts
@@ -9149,14 +9721,14 @@ ${dim("Artifact names support partial matching.")}
 `);
 }
 function getArtifactsDir(projectRoot) {
-  return join17(projectRoot, ".locus", "artifacts");
+  return join19(projectRoot, ".locus", "artifacts");
 }
 function listArtifacts(projectRoot) {
   const dir = getArtifactsDir(projectRoot);
-  if (!existsSync16(dir))
+  if (!existsSync19(dir))
     return [];
   return readdirSync9(dir).filter((f) => f.endsWith(".md")).map((fileName) => {
-    const filePath = join17(dir, fileName);
+    const filePath = join19(dir, fileName);
     const stat = statSync4(filePath);
     return {
       name: fileName.replace(/\.md$/, ""),
@@ -9169,12 +9741,12 @@ function listArtifacts(projectRoot) {
 function readArtifact(projectRoot, name) {
   const dir = getArtifactsDir(projectRoot);
   const fileName = name.endsWith(".md") ? name : `${name}.md`;
-  const filePath = join17(dir, fileName);
-  if (!existsSync16(filePath))
+  const filePath = join19(dir, fileName);
+  if (!existsSync19(filePath))
     return null;
   const stat = statSync4(filePath);
   return {
-    content: readFileSync13(filePath, "utf-8"),
+    content: readFileSync15(filePath, "utf-8"),
     info: {
       name: fileName.replace(/\.md$/, ""),
       fileName,
@@ -9338,17 +9910,17 @@ init_context();
 init_logger();
 init_rate_limiter();
 init_terminal();
-import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
-import { join as join18 } from "node:path";
+import { existsSync as existsSync20, readFileSync as readFileSync16 } from "node:fs";
+import { join as join20 } from "node:path";
 import { fileURLToPath } from "node:url";
 function getCliVersion() {
   const fallbackVersion = "0.0.0";
-  const packageJsonPath = join18(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
-  if (!existsSync17(packageJsonPath)) {
+  const packageJsonPath = join20(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json");
+  if (!existsSync20(packageJsonPath)) {
     return fallbackVersion;
   }
   try {
-    const parsed = JSON.parse(readFileSync14(packageJsonPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync16(packageJsonPath, "utf-8"));
     return parsed.version ?? fallbackVersion;
   } catch {
     return fallbackVersion;
@@ -9366,7 +9938,9 @@ function parseArgs(argv) {
     clean: false,
     resume: false,
     dryRun: false,
-    check: false
+    check: false,
+    upgrade: false,
+    list: false
   };
   const positional = [];
   let i = 0;
@@ -9386,8 +9960,25 @@ function parseArgs(argv) {
         flags.help = true;
         break;
       case "--version":
-      case "-V":
-        flags.version = true;
+      case "-V": {
+        const nextToken = rawArgs[i + 1];
+        if (nextToken !== undefined && /^\d/.test(nextToken)) {
+          flags.installVersion = rawArgs[++i];
+        } else {
+          flags.version = true;
+        }
+        break;
+      }
+      case "-v":
+        flags.installVersion = rawArgs[++i];
+        break;
+      case "--upgrade":
+      case "-u":
+        flags.upgrade = true;
+        break;
+      case "--list":
+      case "-l":
+        flags.list = true;
         break;
       case "--json-stream":
         flags.jsonStream = true;
@@ -9456,6 +10047,10 @@ ${bold("Commands:")}
   ${cyan("status")}            Dashboard view of current state
   ${cyan("config")}            View and manage settings
   ${cyan("logs")}              View, tail, and manage execution logs
+  ${cyan("install")}           Install a community package
+  ${cyan("uninstall")}         Remove an installed package
+  ${cyan("packages")}          Manage installed packages (list, outdated)
+  ${cyan("pkg")} ${dim("<name> [cmd]")}   Run a command from an installed package
   ${cyan("upgrade")}           Check for and install updates
 
 ${bold("Options:")}
@@ -9501,7 +10096,7 @@ async function main() {
     try {
       const root = getGitRoot(cwd);
       if (isInitialized(root)) {
-        logDir = join18(root, ".locus", "logs");
+        logDir = join20(root, ".locus", "logs");
         getRateLimiter(root);
       }
     } catch {}
@@ -9531,6 +10126,43 @@ async function main() {
     logger.destroy();
     return;
   }
+  if (command === "install") {
+    if (parsed.flags.list) {
+      const { packagesCommand: packagesCommand2 } = await Promise.resolve().then(() => (init_packages(), exports_packages));
+      await packagesCommand2(["list"], {});
+      logger.destroy();
+      return;
+    }
+    const { installCommand: installCommand2 } = await Promise.resolve().then(() => (init_install(), exports_install));
+    const installFlags = {};
+    if (parsed.flags.installVersion) {
+      installFlags.version = parsed.flags.installVersion;
+    }
+    if (parsed.flags.upgrade) {
+      installFlags.upgrade = "true";
+    }
+    await installCommand2(parsed.args, installFlags);
+    logger.destroy();
+    return;
+  }
+  if (command === "uninstall") {
+    const { uninstallCommand: uninstallCommand2 } = await Promise.resolve().then(() => (init_uninstall(), exports_uninstall));
+    await uninstallCommand2(parsed.args, {});
+    logger.destroy();
+    return;
+  }
+  if (command === "packages") {
+    const { packagesCommand: packagesCommand2 } = await Promise.resolve().then(() => (init_packages(), exports_packages));
+    await packagesCommand2(parsed.args, {});
+    logger.destroy();
+    return;
+  }
+  if (command === "pkg") {
+    const { pkgCommand: pkgCommand2 } = await Promise.resolve().then(() => (init_pkg(), exports_pkg));
+    await pkgCommand2(parsed.args, {});
+    logger.destroy();
+    return;
+  }
   let projectRoot;
   try {
     projectRoot = getGitRoot(cwd);