@corbat-tech/coco 2.7.0 → 2.8.0

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import * as fs49 from 'fs';
-import fs49__default, { readFileSync, constants } from 'fs';
-import * as path34 from 'path';
-import path34__default, { join, dirname, resolve, basename } from 'path';
+import * as fs50 from 'fs';
+import fs50__default, { readFileSync, constants } from 'fs';
+import * as path35 from 'path';
+import path35__default, { join, dirname, resolve, basename } from 'path';
 import { URL as URL$1, fileURLToPath } from 'url';
 import { z } from 'zod';
 import * as os4 from 'os';
 import os4__default, { homedir } from 'os';
-import * as fs32 from 'fs/promises';
-import fs32__default, { mkdir, writeFile, readFile, access, readdir, rm } from 'fs/promises';
+import * as fs33 from 'fs/promises';
+import fs33__default, { mkdir, writeFile, readFile, access, readdir, rm } from 'fs/promises';
 import JSON5 from 'json5';
 import { Logger } from 'tslog';
 import Anthropic from '@anthropic-ai/sdk';
@@ -282,6 +282,9 @@ var init_schema = __esm({
 });
 
 // src/utils/errors.ts
+function isCocoError(error) {
+  return error instanceof CocoError;
+}
 function formatError(error) {
   if (error instanceof CocoError) {
     let message = `[${error.code}] ${error.message}`;
@@ -506,7 +509,7 @@ async function loadConfig(configPath) {
 async function loadConfigFile(configPath, options = {}) {
   const { strict = true } = options;
   try {
-    const content = await fs32__default.readFile(configPath, "utf-8");
+    const content = await fs33__default.readFile(configPath, "utf-8");
     const parsed = JSON5.parse(content);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       if (!strict) {
@@ -562,7 +565,7 @@ function deepMergeConfig(base, override) {
   };
 }
 function getProjectConfigPath() {
-  return path34__default.join(process.cwd(), ".coco", "config.json");
+  return path35__default.join(process.cwd(), ".coco", "config.json");
 }
 async function saveConfig(config, configPath, global = false) {
   const result = CocoConfigSchema.safeParse(config);
@@ -577,10 +580,10 @@ async function saveConfig(config, configPath, global = false) {
     });
   }
   const resolvedPath = configPath || (global ? CONFIG_PATHS.config : getProjectConfigPath());
-  const dir = path34__default.dirname(resolvedPath);
-  await fs32__default.mkdir(dir, { recursive: true });
+  const dir = path35__default.dirname(resolvedPath);
+  await fs33__default.mkdir(dir, { recursive: true });
   const content = JSON.stringify(result.data, null, 2);
-  await fs32__default.writeFile(resolvedPath, content, "utf-8");
+  await fs33__default.writeFile(resolvedPath, content, "utf-8");
 }
 function createDefaultConfig(projectName, language = "typescript") {
   return createDefaultConfigObject(projectName, language);
@@ -589,20 +592,20 @@ async function findConfigPath(cwd) {
   const envPath = process.env["COCO_CONFIG_PATH"];
   if (envPath) {
     try {
-      await fs32__default.access(envPath);
+      await fs33__default.access(envPath);
       return envPath;
     } catch {
     }
   }
   const basePath = cwd || process.cwd();
-  const projectConfigPath = path34__default.join(basePath, ".coco", "config.json");
+  const projectConfigPath = path35__default.join(basePath, ".coco", "config.json");
   try {
-    await fs32__default.access(projectConfigPath);
+    await fs33__default.access(projectConfigPath);
     return projectConfigPath;
   } catch {
   }
   try {
-    await fs32__default.access(CONFIG_PATHS.config);
+    await fs33__default.access(CONFIG_PATHS.config);
     return CONFIG_PATHS.config;
   } catch {
     return void 0;
@@ -611,14 +614,14 @@ async function findConfigPath(cwd) {
 async function findAllConfigPaths(cwd) {
   const result = {};
   try {
-    await fs32__default.access(CONFIG_PATHS.config);
+    await fs33__default.access(CONFIG_PATHS.config);
     result.global = CONFIG_PATHS.config;
   } catch {
   }
   const basePath = cwd || process.cwd();
-  const projectConfigPath = path34__default.join(basePath, ".coco", "config.json");
+  const projectConfigPath = path35__default.join(basePath, ".coco", "config.json");
   try {
-    await fs32__default.access(projectConfigPath);
+    await fs33__default.access(projectConfigPath);
     result.project = projectConfigPath;
   } catch {
   }
@@ -627,7 +630,7 @@ async function findAllConfigPaths(cwd) {
 async function configExists(configPath, scope = "any") {
   if (configPath) {
     try {
-      await fs32__default.access(configPath);
+      await fs33__default.access(configPath);
       return true;
     } catch {
       return false;
@@ -635,7 +638,7 @@ async function configExists(configPath, scope = "any") {
   }
   if (scope === "project" || scope === "any") {
     try {
-      await fs32__default.access(getProjectConfigPath());
+      await fs33__default.access(getProjectConfigPath());
       return true;
     } catch {
       if (scope === "project") return false;
@@ -643,7 +646,7 @@ async function configExists(configPath, scope = "any") {
   }
   if (scope === "global" || scope === "any") {
     try {
-      await fs32__default.access(CONFIG_PATHS.config);
+      await fs33__default.access(CONFIG_PATHS.config);
       return true;
     } catch {
       return false;
@@ -651,8 +654,8 @@ async function configExists(configPath, scope = "any") {
   }
   return false;
 }
-function getConfigValue(config, path54) {
-  const keys = path54.split(".");
+function getConfigValue(config, path55) {
+  const keys = path55.split(".");
   let current = config;
   for (const key of keys) {
     if (current === null || current === void 0 || typeof current !== "object") {
@@ -799,13 +802,13 @@ function createLogger(config = {}) {
   return logger;
 }
 function setupFileLogging(logger, logDir, name) {
-  if (!fs49__default.existsSync(logDir)) {
-    fs49__default.mkdirSync(logDir, { recursive: true });
+  if (!fs50__default.existsSync(logDir)) {
+    fs50__default.mkdirSync(logDir, { recursive: true });
   }
-  const logFile = path34__default.join(logDir, `${name}.log`);
+  const logFile = path35__default.join(logDir, `${name}.log`);
   logger.attachTransport((logObj) => {
     const line = JSON.stringify(logObj) + "\n";
-    fs49__default.appendFileSync(logFile, line);
+    fs50__default.appendFileSync(logFile, line);
   });
 }
 function createChildLogger(parent, name) {
@@ -821,7 +824,7 @@ function setLogger(logger) {
   globalLogger = logger;
 }
 function initializeLogging(projectPath, level = "info") {
-  const logDir = path34__default.join(projectPath, ".coco", "logs");
+  const logDir = path35__default.join(projectPath, ".coco", "logs");
   const logger = createLogger({
     name: "coco",
     level,
@@ -2230,18 +2233,18 @@ async function refreshAccessToken(provider, refreshToken) {
 }
 function getTokenStoragePath(provider) {
   const home = process.env.HOME || process.env.USERPROFILE || "";
-  return path34.join(home, ".coco", "tokens", `${provider}.json`);
+  return path35.join(home, ".coco", "tokens", `${provider}.json`);
 }
 async function saveTokens(provider, tokens) {
   const filePath = getTokenStoragePath(provider);
-  const dir = path34.dirname(filePath);
-  await fs32.mkdir(dir, { recursive: true, mode: 448 });
-  await fs32.writeFile(filePath, JSON.stringify(tokens, null, 2), { mode: 384 });
+  const dir = path35.dirname(filePath);
+  await fs33.mkdir(dir, { recursive: true, mode: 448 });
+  await fs33.writeFile(filePath, JSON.stringify(tokens, null, 2), { mode: 384 });
 }
 async function loadTokens(provider) {
   const filePath = getTokenStoragePath(provider);
   try {
-    const content = await fs32.readFile(filePath, "utf-8");
+    const content = await fs33.readFile(filePath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -2250,7 +2253,7 @@ async function loadTokens(provider) {
 async function deleteTokens(provider) {
   const filePath = getTokenStoragePath(provider);
   try {
-    await fs32.unlink(filePath);
+    await fs33.unlink(filePath);
   } catch {
   }
 }
@@ -3214,7 +3217,7 @@ function getADCPath() {
   if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
     return process.env.GOOGLE_APPLICATION_CREDENTIALS;
   }
-  return path34.join(home, ".config", "gcloud", "application_default_credentials.json");
+  return path35.join(home, ".config", "gcloud", "application_default_credentials.json");
 }
 async function isGcloudInstalled() {
   try {
@@ -3227,7 +3230,7 @@ async function isGcloudInstalled() {
 async function hasADCCredentials() {
   const adcPath = getADCPath();
   try {
-    await fs32.access(adcPath);
+    await fs33.access(adcPath);
     return true;
   } catch {
     return false;
@@ -4607,8 +4610,8 @@ function loadGlobalCocoEnv() {
   try {
     const home = process.env.HOME || process.env.USERPROFILE || "";
     if (!home) return;
-    const globalEnvPath = path34.join(home, ".coco", ".env");
-    const content = fs49.readFileSync(globalEnvPath, "utf-8");
+    const globalEnvPath = path35.join(home, ".coco", ".env");
+    const content = fs50.readFileSync(globalEnvPath, "utf-8");
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
       if (trimmed && !trimmed.startsWith("#")) {
@@ -4743,7 +4746,7 @@ function loadUserPreferences() {
     return cachedPreferences;
   }
   try {
-    const content = fs49.readFileSync(CONFIG_PATHS.config, "utf-8");
+    const content = fs50.readFileSync(CONFIG_PATHS.config, "utf-8");
     cachedPreferences = JSON.parse(content);
     return cachedPreferences;
   } catch {
@@ -4761,9 +4764,9 @@ async function saveUserPreferences(prefs) {
       authMethods: { ...existing.authMethods, ...prefs.authMethods },
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    const dir = path34.dirname(CONFIG_PATHS.config);
-    await fs49.promises.mkdir(dir, { recursive: true });
-    await fs49.promises.writeFile(CONFIG_PATHS.config, JSON.stringify(updated, null, 2), "utf-8");
+    const dir = path35.dirname(CONFIG_PATHS.config);
+    await fs50.promises.mkdir(dir, { recursive: true });
+    await fs50.promises.writeFile(CONFIG_PATHS.config, JSON.stringify(updated, null, 2), "utf-8");
     cachedPreferences = updated;
   } catch {
   }
@@ -5235,8 +5238,8 @@ var init_registry = __esm({
       /**
        * Ensure directory exists
        */
-      async ensureDir(path54) {
-        await mkdir(dirname(path54), { recursive: true });
+      async ensureDir(path55) {
+        await mkdir(dirname(path55), { recursive: true });
       }
     };
   }
@@ -5311,7 +5314,7 @@ __export(markdown_loader_exports, {
 });
 async function isMarkdownSkill(skillDir) {
   try {
-    await fs32__default.access(path34__default.join(skillDir, SKILL_FILENAME));
+    await fs33__default.access(path35__default.join(skillDir, SKILL_FILENAME));
     return true;
   } catch {
     return false;
@@ -5319,16 +5322,16 @@ async function isMarkdownSkill(skillDir) {
 }
 async function loadMarkdownMetadata(skillDir, scope) {
   try {
-    const skillPath = path34__default.join(skillDir, SKILL_FILENAME);
-    const raw = await fs32__default.readFile(skillPath, "utf-8");
+    const skillPath = path35__default.join(skillDir, SKILL_FILENAME);
+    const raw = await fs33__default.readFile(skillPath, "utf-8");
     const { data } = matter(raw);
     const parsed = SkillFrontmatterSchema.safeParse(data);
     if (!parsed.success) {
       return null;
     }
     const fm = parsed.data;
-    const dirName = path34__default.basename(skillDir);
-    const parentDir = path34__default.basename(path34__default.dirname(skillDir));
+    const dirName = path35__default.basename(skillDir);
+    const parentDir = path35__default.basename(path35__default.dirname(skillDir));
     const namespace = isNamespaceDirectory(parentDir) ? parentDir : void 0;
     const baseId = toKebabCase(fm.name || dirName);
     const fullId = namespace ? `${namespace}/${baseId}` : baseId;
@@ -5368,8 +5371,8 @@ async function loadMarkdownMetadata(skillDir, scope) {
 }
 async function loadMarkdownContent(skillDir) {
   try {
-    const skillPath = path34__default.join(skillDir, SKILL_FILENAME);
-    const raw = await fs32__default.readFile(skillPath, "utf-8");
+    const skillPath = path35__default.join(skillDir, SKILL_FILENAME);
+    const raw = await fs33__default.readFile(skillPath, "utf-8");
     const { content } = matter(raw);
     const references = await listSubdirectory(skillDir, "references");
     const scripts = await listSubdirectory(skillDir, "scripts");
@@ -5391,9 +5394,9 @@ async function loadMarkdownContent(skillDir) {
 }
 async function listSubdirectory(skillDir, subdir) {
   try {
-    const dir = path34__default.join(skillDir, subdir);
-    const entries = await fs32__default.readdir(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isFile()).map((e) => path34__default.join(dir, e.name));
+    const dir = path35__default.join(skillDir, subdir);
+    const entries = await fs33__default.readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isFile()).map((e) => path35__default.join(dir, e.name));
   } catch {
     return [];
   }
@@ -5470,8 +5473,8 @@ async function loadSkillFromDirectory(skillDir, scope) {
   if (await isMarkdownSkill(skillDir)) {
     return loadMarkdownMetadata(skillDir, scope);
   }
-  const hasTs = await fileExists(path34__default.join(skillDir, "index.ts"));
-  const hasJs = await fileExists(path34__default.join(skillDir, "index.js"));
+  const hasTs = await fileExists(path35__default.join(skillDir, "index.ts"));
+  const hasJs = await fileExists(path35__default.join(skillDir, "index.js"));
   if (hasTs || hasJs) {
     return null;
   }
@@ -5491,7 +5494,7 @@ async function loadFullSkill(metadata) {
 }
 async function fileExists(filePath) {
   try {
-    await fs32__default.access(filePath);
+    await fs33__default.access(filePath);
     return true;
   } catch {
     return false;
@@ -5516,7 +5519,7 @@ async function discoverAllSkills(projectPath, builtinSkills = [], options) {
   for (const meta of globalSkills) {
     applyWithPriority(allSkills, meta);
   }
-  const projectDirs = opts.projectDir ? [opts.projectDir] : PROJECT_SKILLS_DIRNAMES.map((d) => path34__default.join(projectPath, d));
+  const projectDirs = opts.projectDir ? [opts.projectDir] : PROJECT_SKILLS_DIRNAMES.map((d) => path35__default.join(projectPath, d));
   for (const dir of projectDirs) {
     const projectSkills = await scanSkillsDirectory(dir, "project");
     for (const meta of projectSkills) {
@@ -5527,13 +5530,13 @@ async function discoverAllSkills(projectPath, builtinSkills = [], options) {
 }
 async function scanSkillsDirectory(dir, scope) {
   try {
-    const entries = await fs32__default.readdir(dir, { withFileTypes: true });
+    const entries = await fs33__default.readdir(dir, { withFileTypes: true });
     const skillDirs = entries.filter((e) => e.isDirectory() && !e.isSymbolicLink());
     const results = [];
     for (const entry of skillDirs) {
-      const entryPath = path34__default.join(dir, entry.name);
+      const entryPath = path35__default.join(dir, entry.name);
       try {
-        const stat2 = await fs32__default.lstat(entryPath);
+        const stat2 = await fs33__default.lstat(entryPath);
         if (stat2.isSymbolicLink()) continue;
       } catch {
         continue;
@@ -5561,13 +5564,13 @@ async function scanSkillsDirectory(dir, scope) {
 async function scanNestedSkills(dir, scope, depth) {
   if (depth >= MAX_NESTING_DEPTH) return [];
   try {
-    const subEntries = await fs32__default.readdir(dir, { withFileTypes: true });
+    const subEntries = await fs33__default.readdir(dir, { withFileTypes: true });
     const subDirs = subEntries.filter((e) => e.isDirectory() && !e.isSymbolicLink());
     const results = await Promise.all(
       subDirs.map(async (sub) => {
-        const subPath = path34__default.join(dir, sub.name);
+        const subPath = path35__default.join(dir, sub.name);
         try {
-          const stat2 = await fs32__default.lstat(subPath);
+          const stat2 = await fs33__default.lstat(subPath);
           if (stat2.isSymbolicLink()) return null;
         } catch {
           return null;
@@ -5594,7 +5597,7 @@ var init_discovery = __esm({
     init_typescript_loader();
     init_paths();
     init_logger();
-    GLOBAL_SKILLS_DIR = path34__default.join(COCO_HOME, "skills");
+    GLOBAL_SKILLS_DIR = path35__default.join(COCO_HOME, "skills");
     PROJECT_SKILLS_DIRNAMES = [
       ".claude/skills",
       // Claude compat — read for migration/interop (lowest project priority)
@@ -6700,9 +6703,9 @@ function createEmptyMemoryContext() {
     errors: []
   };
 }
-function createMissingMemoryFile(path54, level) {
+function createMissingMemoryFile(path55, level) {
   return {
-    path: path54,
+    path: path55,
     level,
     content: "",
     sections: [],
@@ -6933,7 +6936,7 @@ function clearSession(session) {
 }
 async function loadTrustSettings() {
   try {
-    const content = await fs32__default.readFile(TRUST_SETTINGS_FILE, "utf-8");
+    const content = await fs33__default.readFile(TRUST_SETTINGS_FILE, "utf-8");
     const raw = JSON.parse(content);
     return {
       globalTrusted: raw.globalTrusted ?? [],
@@ -6952,9 +6955,9 @@ async function loadTrustSettings() {
 }
 async function saveTrustSettings(settings) {
   try {
-    await fs32__default.mkdir(TRUST_SETTINGS_DIR, { recursive: true });
+    await fs33__default.mkdir(TRUST_SETTINGS_DIR, { recursive: true });
     settings.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await fs32__default.writeFile(TRUST_SETTINGS_FILE, JSON.stringify(settings, null, 2), "utf-8");
+    await fs33__default.writeFile(TRUST_SETTINGS_FILE, JSON.stringify(settings, null, 2), "utf-8");
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     console.warn(`[Trust] Failed to save trust settings: ${msg}`);
@@ -7097,7 +7100,7 @@ var init_session = __esm({
     init_manager();
     init_compactor();
     MAX_SKILL_INSTRUCTIONS_CHARS = 16e3;
-    TRUST_SETTINGS_DIR = path34__default.dirname(CONFIG_PATHS.trustedTools);
+    TRUST_SETTINGS_DIR = path35__default.dirname(CONFIG_PATHS.trustedTools);
     TRUST_SETTINGS_FILE = CONFIG_PATHS.trustedTools;
     CATEGORY_LABELS = {
       file: "File Operations",
@@ -7220,6 +7223,21 @@ After completing a task, ALWAYS suggest logical next steps based on what you did
 
 Keep suggestions brief (1-2 bullet points max) and actionable.
 
+## Error Recovery
+
+When a tool fails, do NOT blindly retry with the same arguments. Instead:
+- **File not found**: Use **glob** with a pattern like \`**/*partial-name*\` or **list_dir** to explore nearby directories. Check the error for "Did you mean?" suggestions.
+- **Text not found in edit_file**: Use **read_file** to see the actual content. The error shows the closest matching lines \u2014 use those as reference for the correct oldText.
+- **web_fetch HTTP error (404, 403, etc.)**: Do NOT retry the same URL. Use **web_search** to find the correct or alternative URL. If the page requires authentication, look for a public alternative.
+- **web_search failure**: Try a different search engine parameter, simplify the query, or rephrase with different keywords.
+- **Timeout errors**: Do NOT immediately retry. Simplify the request, try a different source, or inform the user.
+- **After 2 failures with the same tool**: Stop, rethink your approach, try an alternative tool or strategy, or explain the issue to the user.
+- **Git errors**: If git_commit, git_push, etc. fail, read the error carefully. Use git_status to understand the current state. For "not a git repository", verify the working directory with list_dir.
+- **Build/test failures**: Read the stderr output and the hint field in the result. Use read_file to inspect the failing file. Never retry the same build without fixing the underlying code first.
+- **Permission denied**: Do NOT retry. Explain to the user that the operation requires different permissions.
+- **Command not found**: Use command_exists to verify availability before suggesting alternatives.
+- **Database errors**: Use inspect_schema to understand table structure before retrying queries.
+
 ## File Access
 File operations are restricted to the project directory by default.
 When you need to access a path outside the project, use the **authorize_path** tool first \u2014 it will ask the user for permission interactively. Once authorized, proceed with the file operation.
@@ -7382,13 +7400,13 @@ var init_types4 = __esm({
   }
 });
 function getStatePath(projectPath) {
-  return path34.join(projectPath, ".coco", "state.json");
+  return path35.join(projectPath, ".coco", "state.json");
 }
 function createStateManager() {
   async function load(projectPath) {
     const statePath = getStatePath(projectPath);
     try {
-      const content = await fs32.readFile(statePath, "utf-8");
+      const content = await fs33.readFile(statePath, "utf-8");
       const file = JSON.parse(content);
       if (file.version !== STATE_VERSION) {
         console.warn(`State version mismatch: ${file.version} vs ${STATE_VERSION}`);
@@ -7407,7 +7425,7 @@ function createStateManager() {
   }
   async function save(state) {
     const statePath = getStatePath(state.path);
-    await fs32.mkdir(path34.dirname(statePath), { recursive: true });
+    await fs33.mkdir(path35.dirname(statePath), { recursive: true });
     const file = {
       version: STATE_VERSION,
       state: {
@@ -7415,19 +7433,19 @@ function createStateManager() {
         updatedAt: (/* @__PURE__ */ new Date()).toISOString()
       }
     };
-    await fs32.writeFile(statePath, JSON.stringify(file, null, 2), "utf-8");
+    await fs33.writeFile(statePath, JSON.stringify(file, null, 2), "utf-8");
   }
   async function clear(projectPath) {
     const statePath = getStatePath(projectPath);
     try {
-      await fs32.unlink(statePath);
+      await fs33.unlink(statePath);
     } catch {
     }
   }
   async function exists(projectPath) {
     const statePath = getStatePath(projectPath);
     try {
-      await fs32.access(statePath);
+      await fs33.access(statePath);
       return true;
     } catch {
       return false;
@@ -7555,8 +7573,8 @@ __export(trust_store_exports, {
   saveTrustStore: () => saveTrustStore,
   updateLastAccessed: () => updateLastAccessed
 });
-async function ensureDir(path54) {
-  await mkdir(dirname(path54), { recursive: true });
+async function ensureDir(path55) {
+  await mkdir(dirname(path55), { recursive: true });
 }
 async function loadTrustStore(storePath = TRUST_STORE_PATH) {
   try {
@@ -7634,8 +7652,8 @@ function canPerformOperation(store, projectPath, operation) {
   };
   return permissions[level]?.includes(operation) ?? false;
 }
-function normalizePath(path54) {
-  return join(path54);
+function normalizePath(path55) {
+  return join(path55);
 }
 function createTrustStore(storePath = TRUST_STORE_PATH) {
   let store = null;
@@ -7952,6 +7970,14 @@ function extractQuotedPath(msg) {
 function humanizeError(message, toolName) {
   const msg = message.trim();
   if (!msg) return msg;
+  if (/Use (glob|list_dir|read_file|git_init|git_status|git_add|git_commit|git_log|git_branch|git_checkout|git_push|git_pull|web_search|inspect_schema|list_checkpoints|command_exists|edit_file|run_linter|run_tests|run_script|bash_exec)\b/.test(
+    msg
+  )) {
+    return msg;
+  }
+  if (/run git_init\b/.test(msg)) {
+    return msg;
+  }
   if (/ECONNREFUSED/i.test(msg)) {
     return "Connection refused \u2014 the server may not be running";
   }
@@ -7973,13 +7999,22 @@ function humanizeError(message, toolName) {
   if (/fetch failed|network error|Failed to fetch/i.test(msg)) {
     return "Network request failed \u2014 check your internet connection";
   }
+  if (/File not found:/.test(msg) && /Did you mean/.test(msg)) {
+    return msg;
+  }
+  if (/Directory not found:/.test(msg) && /Did you mean/.test(msg)) {
+    return msg;
+  }
+  if (/^HTTP \d{3}:/.test(msg) && /Try/.test(msg)) {
+    return msg;
+  }
   if (/ENOENT/i.test(msg)) {
-    const path54 = extractQuotedPath(msg);
-    return path54 ? `File or directory not found: ${path54}` : "File or directory not found";
+    const path55 = extractQuotedPath(msg);
+    return path55 ? `File or directory not found: ${path55}` : "File or directory not found";
   }
   if (/EACCES/i.test(msg)) {
-    const path54 = extractQuotedPath(msg);
-    return path54 ? `Permission denied: ${path54}` : "Permission denied \u2014 check file permissions";
+    const path55 = extractQuotedPath(msg);
+    return path55 ? `Permission denied: ${path55}` : "Permission denied \u2014 check file permissions";
   }
   if (/EISDIR/i.test(msg)) {
     return "Expected a file but found a directory at the specified path";
@@ -8062,6 +8097,12 @@ function humanizeError(message, toolName) {
   if (/invalid.*api.?key|api.?key.*invalid|api.?key.*not.*found/i.test(msg)) {
     return "Invalid or missing API key \u2014 check your provider credentials";
   }
+  if (/TS\d{4}:/.test(msg)) {
+    return `TypeScript error \u2014 check the referenced file and line number. ${msg}`;
+  }
+  if (/SQLITE_ERROR/i.test(msg)) {
+    return `Database error \u2014 use inspect_schema to verify the table structure. ${msg}`;
+  }
   return msg;
 }
 function looksLikeTechnicalJargon(message) {
@@ -8161,6 +8202,7 @@ var init_registry4 = __esm({
   "src/tools/registry.ts"() {
     init_logger();
     init_error_humanizer();
+    init_errors();
     ToolRegistry = class {
       tools = /* @__PURE__ */ new Map();
       logger = getLogger();
@@ -8264,6 +8306,14 @@ var init_registry4 = __esm({
             if (allUndefined && error.issues.length > 1) {
               errorMessage += ". All parameters are missing \u2014 this is likely a JSON serialization error on our side. Please retry with the same arguments.";
             }
+          } else if (isCocoError(error)) {
+            const causeMsg = error.cause instanceof Error ? error.cause.message : "";
+            const combined = causeMsg && !error.message.includes(causeMsg) ? `${error.message} \u2014 ${causeMsg}` : error.message;
+            errorMessage = humanizeError(combined, name);
+            if (error.suggestion && !errorMessage.includes(error.suggestion)) {
+              errorMessage += `
+Suggestion: ${error.suggestion}`;
+            }
           } else {
             const rawMessage = error instanceof Error ? error.message : String(error);
             errorMessage = humanizeError(rawMessage, name);
@@ -8297,7 +8347,7 @@ var init_registry4 = __esm({
 });
 async function fileExists2(filePath) {
   try {
-    await fs32__default.access(filePath);
+    await fs33__default.access(filePath);
     return true;
   } catch {
     return false;
@@ -8699,9 +8749,9 @@ var init_diff_renderer = __esm({
     getTerminalWidth = () => process.stdout.columns || 80;
   }
 });
-async function fileExists3(path54) {
+async function fileExists3(path55) {
   try {
-    await access(path54);
+    await access(path55);
     return true;
   } catch {
     return false;
@@ -8791,7 +8841,7 @@ async function detectMaturity(cwd) {
   if (!hasLintConfig && hasPackageJson) {
     try {
       const pkgRaw = await import('fs/promises').then(
-        (fs52) => fs52.readFile(join(cwd, "package.json"), "utf-8")
+        (fs53) => fs53.readFile(join(cwd, "package.json"), "utf-8")
       );
       const pkg = JSON.parse(pkgRaw);
       if (pkg.scripts?.lint || pkg.scripts?.["lint:fix"]) {
@@ -8991,10 +9041,10 @@ var init_coverage = __esm({
           join(this.projectPath, ".coverage", "coverage-summary.json"),
           join(this.projectPath, "coverage", "lcov-report", "coverage-summary.json")
         ];
-        for (const path54 of possiblePaths) {
+        for (const path55 of possiblePaths) {
           try {
-            await access(path54, constants.R_OK);
-            const content = await readFile(path54, "utf-8");
+            await access(path55, constants.R_OK);
+            const content = await readFile(path55, "utf-8");
             const report = JSON.parse(content);
             return parseCoverageSummary(report);
           } catch {
@@ -9728,7 +9778,7 @@ var init_build_verifier = __esm({
       async verifyTypes() {
         const startTime = Date.now();
         try {
-          const hasTsConfig = await this.fileExists(path34.join(this.projectPath, "tsconfig.json"));
+          const hasTsConfig = await this.fileExists(path35.join(this.projectPath, "tsconfig.json"));
           if (!hasTsConfig) {
             return {
               success: true,
@@ -9778,8 +9828,8 @@ var init_build_verifier = __esm({
        */
       async detectBuildCommand() {
         try {
-          const packageJsonPath = path34.join(this.projectPath, "package.json");
-          const content = await fs32.readFile(packageJsonPath, "utf-8");
+          const packageJsonPath = path35.join(this.projectPath, "package.json");
+          const content = await fs33.readFile(packageJsonPath, "utf-8");
           const packageJson = JSON.parse(content);
           if (packageJson.scripts?.build) {
             return "npm run build";
@@ -9855,7 +9905,7 @@ var init_build_verifier = __esm({
        */
       async fileExists(filePath) {
         try {
-          await fs32.access(filePath);
+          await fs33.access(filePath);
           return true;
         } catch {
           return false;
@@ -11477,9 +11527,9 @@ function detectProjectLanguage(files) {
   return { language: dominant, confidence, evidence };
 }
 function getFileExtension(filePath) {
-  const base = path34.basename(filePath);
+  const base = path35.basename(filePath);
   if (base.endsWith(".d.ts")) return ".d.ts";
-  return path34.extname(filePath).toLowerCase();
+  return path35.extname(filePath).toLowerCase();
 }
 function buildEvidence(dominant, counts, totalSourceFiles, files) {
   const evidence = [];
@@ -11487,7 +11537,7 @@ function buildEvidence(dominant, counts, totalSourceFiles, files) {
   evidence.push(`${dominantCount} of ${totalSourceFiles} source files are ${dominant}`);
   const configFiles = ["tsconfig.json", "pom.xml", "build.gradle", "Cargo.toml", "go.mod"];
   for (const cfg of configFiles) {
-    if (files.some((f) => path34.basename(f) === cfg)) {
+    if (files.some((f) => path35.basename(f) === cfg)) {
       evidence.push(`Found ${cfg}`);
     }
   }
@@ -12957,8 +13007,8 @@ var init_evaluator = __esm({
 });
 async function detectLinter2(cwd) {
   try {
-    const pkgPath = path34__default.join(cwd, "package.json");
-    const pkgContent = await fs32__default.readFile(pkgPath, "utf-8");
+    const pkgPath = path35__default.join(cwd, "package.json");
+    const pkgContent = await fs33__default.readFile(pkgPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     const deps = {
       ...pkg.dependencies,
@@ -13093,7 +13143,9 @@ Examples:
             warnings: 0,
             fixable: 0,
             issues: [],
-            score: 100
+            score: null,
+            linter: "none",
+            message: "No linter detected (looked for: eslint, oxlint, biome). Install one or use bash_exec to run a custom linter."
           };
         }
         try {
@@ -13173,7 +13225,7 @@ Examples:
           let totalFunctions = 0;
           let complexFunctions = 0;
           for (const file of targetFiles) {
-            const content = await fs32__default.readFile(file, "utf-8");
+            const content = await fs33__default.readFile(file, "utf-8");
             const fileComplexity = analyzeFileComplexity(content, file);
             fileResults.push(fileComplexity);
             totalComplexity += fileComplexity.complexity;
@@ -13196,8 +13248,9 @@ Examples:
             files: fileResults
           };
         } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
           throw new ToolError(
-            `Complexity analysis failed: ${error instanceof Error ? error.message : String(error)}`,
+            `Complexity analysis failed: ${msg}. Try read_file to inspect the code manually.`,
             { tool: "analyze_complexity", cause: error instanceof Error ? error : void 0 }
           );
         }
@@ -13230,8 +13283,9 @@ Examples:
           const evaluation = await evaluator.evaluate(files);
           return evaluation.scores;
         } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
           throw new ToolError(
-            `Quality calculation failed: ${error instanceof Error ? error.message : String(error)}`,
+            `Quality calculation failed: ${msg}. Run run_linter and run_tests separately for partial results.`,
             { tool: "calculate_quality", cause: error instanceof Error ? error : void 0 }
           );
         }
@@ -13245,6 +13299,7 @@ function getGit(cwd) {
 }
 async function getDiff(git, baseBranch, includeUncommitted) {
   const diffs = [];
+  const warnings = [];
   try {
     const branchDiff = await git.diff([`${baseBranch}...HEAD`]);
     if (branchDiff) diffs.push(branchDiff);
@@ -13253,6 +13308,7 @@ async function getDiff(git, baseBranch, includeUncommitted) {
       const directDiff = await git.diff([baseBranch]);
       if (directDiff) diffs.push(directDiff);
     } catch {
+      warnings.push(`Could not diff against base branch '${baseBranch}' \u2014 it may not exist.`);
     }
   }
   if (includeUncommitted) {
@@ -13260,14 +13316,16 @@ async function getDiff(git, baseBranch, includeUncommitted) {
       const uncommitted = await git.diff();
       if (uncommitted) diffs.push(uncommitted);
     } catch {
+      warnings.push("Could not read unstaged changes.");
     }
     try {
       const staged = await git.diff(["--staged"]);
       if (staged) diffs.push(staged);
     } catch {
+      warnings.push("Could not read staged changes.");
     }
   }
-  return diffs.join("\n");
+  return { raw: diffs.join("\n"), warnings };
 }
 function analyzePatterns(diff) {
   const findings = [];
@@ -13314,7 +13372,7 @@ async function checkTestCoverage(diff, cwd) {
     );
     if (!hasTestChange) {
       const ext = src.path.match(/\.(ts|tsx|js|jsx)$/)?.[0] ?? ".ts";
-      const testExists = await fileExists2(path34__default.join(cwd, `${baseName}.test${ext}`)) || await fileExists2(path34__default.join(cwd, `${baseName}.spec${ext}`));
+      const testExists = await fileExists2(path35__default.join(cwd, `${baseName}.test${ext}`)) || await fileExists2(path35__default.join(cwd, `${baseName}.spec${ext}`));
       if (testExists) {
         if (src.additions >= TEST_COVERAGE_LARGE_CHANGE_THRESHOLD) {
           findings.push({
@@ -13537,10 +13595,14 @@ Examples:
         try {
           const status = await git.status();
           const currentBranch = status.current ?? "HEAD";
-          const rawDiff = await getDiff(git, baseBranch, includeUncommitted);
+          const { raw: rawDiff, warnings: diffWarnings } = await getDiff(
+            git,
+            baseBranch,
+            includeUncommitted
+          );
           const diff = parseDiff(rawDiff);
           if (diff.files.length === 0) {
-            return {
+            const emptyResult = {
               summary: {
                 branch: currentBranch,
                 baseBranch,
@@ -13554,6 +13616,10 @@ Examples:
               maturity: "new",
               diff
             };
+            if (diffWarnings.length > 0) {
+              emptyResult.warnings = diffWarnings;
+            }
+            return emptyResult;
           }
           const maturityInfo = await detectMaturity(projectDir);
           const maturity = maturityInfo.level;
@@ -13575,6 +13641,7 @@ Examples:
                 }
               }
             } catch {
+              diffWarnings.push("Linter not available \u2014 code style was not checked.");
             }
           }
           allFindings.push(...getMaturityRecommendations(maturity, diff));
@@ -13587,7 +13654,7 @@ Examples:
             (f) => f.severity === "minor" || f.severity === "info"
           );
           const status_result = required.some((f) => f.severity === "critical") ? "needs_work" : required.length > 0 ? "needs_work" : "approved";
-          return {
+          const result = {
             summary: {
               branch: currentBranch,
               baseBranch,
@@ -13601,6 +13668,10 @@ Examples:
             maturity,
             diff
           };
+          if (diffWarnings.length > 0) {
+            result.warnings = diffWarnings;
+          }
+          return result;
         } catch (error) {
           throw new ToolError(
             `Code review failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -13891,10 +13962,16 @@ Examples:
             rendered: true
           };
         } catch (error) {
-          throw new ToolError(
-            `Diff failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "show_diff", cause: error instanceof Error ? error : void 0 }
-          );
+          const msg = error instanceof Error ? error.message : String(error);
+          let hint = `Diff failed: ${msg}`;
+          if (/not a git repository/i.test(msg))
+            hint = "Not a git repository. Use list_dir to verify you're in the right directory.";
+          else if (/unknown revision|bad revision/i.test(msg))
+            hint = `Reference not found: ${msg}. Use git_log or git_branch to find valid refs.`;
+          throw new ToolError(hint, {
+            tool: "show_diff",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -13968,6 +14045,27 @@ var init_diff2 = __esm({
     };
   }
 });
+function enrichGitError(operation, error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  if (/not a git repository/i.test(msg))
+    return `Not a git repository. Run git_init first or verify you're in the correct directory.`;
+  if (/nothing to commit/i.test(msg))
+    return `Nothing to commit \u2014 working tree is clean. Use git_status to verify your changes were saved.`;
+  if (/CONFLICT|merge conflict/i.test(msg))
+    return `Merge conflict detected. Use read_file to see the conflicting file, resolve manually with edit_file, then git_add and git_commit.`;
+  if (/non-fast-forward|\[rejected\]/i.test(msg))
+    return `Push rejected \u2014 remote has new commits. Run git_pull first, resolve any conflicts, then retry git_push.`;
+  if (/authentication failed/i.test(msg))
+    return `Git authentication failed. Check your credentials, SSH key, or access token.`;
+  if (/branch.*already exists/i.test(msg))
+    return `Branch already exists. Use git_checkout to switch to it, or choose a different name.`;
+  if (/does not exist|unknown revision|bad revision/i.test(msg))
+    return `Git reference not found. Use git_branch to list available branches, or git_log to find the correct commit.`;
+  if (/pathspec.*did not match/i.test(msg))
+    return `File not tracked by git. Use glob to verify the file exists, then git_add it first.`;
+  if (/already up to date/i.test(msg)) return `Already up to date \u2014 no changes to pull.`;
+  return `Git ${operation} failed: ${msg}`;
+}
 function getGit3(cwd) {
   const baseDir = cwd ?? process.cwd();
   return simpleGit({ baseDir });
@@ -14004,10 +14102,10 @@ Examples:
             isClean: status.isClean()
           };
         } catch (error) {
-          throw new ToolError(
-            `Git status failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_status", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("status", error), {
+            tool: "git_status",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14041,10 +14139,10 @@ Examples:
             deletions: diffStat.deletions
           };
         } catch (error) {
-          throw new ToolError(
-            `Git diff failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_diff", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("diff", error), {
+            tool: "git_diff",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14067,10 +14165,10 @@ Examples:
           await git.add(files);
           return { added: files };
         } catch (error) {
-          throw new ToolError(
-            `Git add failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_add", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("add", error), {
+            tool: "git_add",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14100,10 +14198,10 @@ Examples:
             summary: result.summary.changes ? `${result.summary.insertions} insertions, ${result.summary.deletions} deletions` : "No changes"
           };
         } catch (error) {
-          throw new ToolError(
-            `Git commit failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_commit", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("commit", error), {
+            tool: "git_commit",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14140,10 +14238,10 @@ Examples:
             }))
           };
         } catch (error) {
-          throw new ToolError(
-            `Git log failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_log", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("log", error), {
+            tool: "git_log",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14184,10 +14282,10 @@ Examples:
             current: status.current ?? "HEAD"
           };
         } catch (error) {
-          throw new ToolError(
-            `Git branch failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_branch", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("branch", error), {
+            tool: "git_branch",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14214,10 +14312,10 @@ Examples:
           }
           return { branch };
         } catch (error) {
-          throw new ToolError(
-            `Git checkout failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_checkout", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("checkout", error), {
+            tool: "git_checkout",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14252,10 +14350,10 @@ Examples:
             branch: pushBranch
           };
         } catch (error) {
-          throw new ToolError(
-            `Git push failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_push", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("push", error), {
+            tool: "git_push",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14287,10 +14385,10 @@ Examples:
             summary: result.summary ? `${result.summary.insertions} insertions, ${result.summary.deletions} deletions` : "Already up to date"
           };
         } catch (error) {
-          throw new ToolError(
-            `Git pull failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_pull", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("pull", error), {
+            tool: "git_pull",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14316,10 +14414,10 @@ Examples:
             path: cwd ?? process.cwd()
           };
         } catch (error) {
-          throw new ToolError(
-            `Git init failed: ${error instanceof Error ? error.message : String(error)}`,
-            { tool: "git_init", cause: error instanceof Error ? error : void 0 }
-          );
+          throw new ToolError(enrichGitError("init", error), {
+            tool: "git_init",
+            cause: error instanceof Error ? error : void 0
+          });
         }
       }
     });
@@ -14449,40 +14547,24 @@ var init_bash = __esm({
     DEFAULT_TIMEOUT_MS = 12e4;
     MAX_OUTPUT_SIZE = 1024 * 1024;
     DANGEROUS_PATTERNS_FULL = [
-      /\brm\s+-rf\s+\/(?!\w)/,
-      // rm -rf / (root)
-      /\bsudo\s+rm\s+-rf/,
-      // sudo rm -rf
-      /\b:?\(\)\s*\{.*\}/,
-      // Fork bomb pattern
-      /\bdd\s+if=.*of=\/dev\//,
-      // dd to device
-      /\bmkfs\./,
-      // Format filesystem
-      /\bformat\s+/,
-      // Windows format
-      />\s*\/etc\//,
-      // Write to /etc
-      />\s*\/root\//,
-      // Write to /root
-      /\bchmod\s+777/,
-      // Overly permissive chmod
-      /\bchown\s+root/,
-      // chown to root
-      /\bcurl\s+.*\|\s*(ba)?sh/,
-      // curl | sh pattern
-      /\bwget\s+.*\|\s*(ba)?sh/
-      // wget | sh pattern
+      { pattern: /\brm\s+-rf\s+\/(?!\w)/, rule: "rm -rf on root filesystem" },
+      { pattern: /\bsudo\s+rm\s+-rf/, rule: "sudo rm -rf (destructive with elevated privileges)" },
+      { pattern: /\b:?\(\)\s*\{.*\}/, rule: "fork bomb pattern" },
+      { pattern: /\bdd\s+if=.*of=\/dev\//, rule: "dd write to device" },
+      { pattern: /\bmkfs\./, rule: "filesystem format command" },
+      { pattern: /\bformat\s+/, rule: "format command" },
+      { pattern: />\s*\/etc\//, rule: "write redirect to /etc/" },
+      { pattern: />\s*\/root\//, rule: "write redirect to /root/" },
+      { pattern: /\bchmod\s+777/, rule: "overly permissive chmod 777" },
+      { pattern: /\bchown\s+root/, rule: "chown to root" },
+      { pattern: /\bcurl\s+.*\|\s*(ba)?sh/, rule: "curl pipe to shell (untrusted code execution)" },
+      { pattern: /\bwget\s+.*\|\s*(ba)?sh/, rule: "wget pipe to shell (untrusted code execution)" }
     ];
     DANGEROUS_PATTERNS_SHELL_ONLY = [
-      /`[^`]+`/,
-      // Backtick command substitution
-      /\$\([^)]+\)/,
-      // $() command substitution
-      /\beval\s+/,
-      // eval command (shell eval, not JS eval())
-      /\bsource\s+/
-      // source command (can execute arbitrary scripts)
+      { pattern: /`[^`]+`/, rule: "backtick command substitution" },
+      { pattern: /\$\([^)]+\)/, rule: "$() command substitution" },
+      { pattern: /\beval\s+/, rule: "eval command (arbitrary code execution)" },
+      { pattern: /\bsource\s+/, rule: "source command (can execute arbitrary scripts)" }
     ];
     SAFE_ENV_VARS = /* @__PURE__ */ new Set([
       // System info (non-sensitive)
@@ -14551,18 +14633,20 @@ Examples:
       }),
       async execute({ command, cwd, timeout, env: env2 }) {
         const shellPart = getShellCommandPart(command);
-        for (const pattern of DANGEROUS_PATTERNS_FULL) {
+        for (const { pattern, rule } of DANGEROUS_PATTERNS_FULL) {
           if (pattern.test(command)) {
-            throw new ToolError(`Potentially dangerous command blocked: ${command.slice(0, 100)}`, {
-              tool: "bash_exec"
-            });
+            throw new ToolError(
+              `Command blocked by safety rule: "${rule}". Rewrite the command to avoid this pattern, or use a safer alternative.`,
+              { tool: "bash_exec" }
+            );
           }
         }
-        for (const pattern of DANGEROUS_PATTERNS_SHELL_ONLY) {
+        for (const { pattern, rule } of DANGEROUS_PATTERNS_SHELL_ONLY) {
           if (pattern.test(shellPart)) {
-            throw new ToolError(`Potentially dangerous command blocked: ${command.slice(0, 100)}`, {
-              tool: "bash_exec"
-            });
+            throw new ToolError(
+              `Command blocked by safety rule: "${rule}". Rewrite the command to avoid this pattern, or use a safer alternative.`,
+              { tool: "bash_exec" }
+            );
           }
         }
         const startTime = performance.now();
@@ -14647,18 +14731,20 @@ Examples:
       }),
       async execute({ command, cwd, env: env2 }) {
         const shellPart = getShellCommandPart(command);
-        for (const pattern of DANGEROUS_PATTERNS_FULL) {
+        for (const { pattern, rule } of DANGEROUS_PATTERNS_FULL) {
           if (pattern.test(command)) {
-            throw new ToolError(`Potentially dangerous command blocked: ${command.slice(0, 100)}`, {
-              tool: "bash_background"
-            });
+            throw new ToolError(
+              `Command blocked by safety rule: "${rule}". Rewrite the command to avoid this pattern, or use a safer alternative.`,
+              { tool: "bash_background" }
+            );
           }
         }
-        for (const pattern of DANGEROUS_PATTERNS_SHELL_ONLY) {
+        for (const { pattern, rule } of DANGEROUS_PATTERNS_SHELL_ONLY) {
           if (pattern.test(shellPart)) {
-            throw new ToolError(`Potentially dangerous command blocked: ${command.slice(0, 100)}`, {
-              tool: "bash_background"
-            });
+            throw new ToolError(
+              `Command blocked by safety rule: "${rule}". Rewrite the command to avoid this pattern, or use a safer alternative.`,
+              { tool: "bash_background" }
+            );
           }
         }
         try {
@@ -14941,7 +15027,7 @@ var init_github = __esm({
 });
 async function detectVersionFile(cwd) {
   for (const { file, stack, field } of VERSION_FILES) {
-    const fullPath = path34__default.join(cwd, file);
+    const fullPath = path35__default.join(cwd, file);
     if (await fileExists2(fullPath)) {
       const version = await readVersionFromFile(fullPath, stack, field);
       if (version) {
@@ -14987,7 +15073,7 @@ function bumpVersion(current, bump) {
   }
 }
 async function writeVersion(cwd, versionFile, newVersion) {
-  const fullPath = path34__default.join(cwd, versionFile.path);
+  const fullPath = path35__default.join(cwd, versionFile.path);
   const content = await readFile(fullPath, "utf-8");
   let updated;
   switch (versionFile.stack) {
@@ -15046,7 +15132,7 @@ var init_version_detector = __esm({
 });
 async function detectChangelog(cwd) {
   for (const name of CHANGELOG_NAMES) {
-    const fullPath = path34__default.join(cwd, name);
+    const fullPath = path35__default.join(cwd, name);
     if (await fileExists2(fullPath)) {
       const content = await readFile(fullPath, "utf-8");
       const format = detectFormat(content);
@@ -15068,7 +15154,7 @@ function detectFormat(content) {
   return "custom";
 }
 async function insertChangelogEntry(cwd, changelog, version, entries, date) {
-  const fullPath = path34__default.join(cwd, changelog.path);
+  const fullPath = path35__default.join(cwd, changelog.path);
   const content = await readFile(fullPath, "utf-8");
   const dateStr = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const entry = buildEntry(changelog.format, version, entries, dateStr);
@@ -15129,11 +15215,11 @@ var init_changelog = __esm({
   }
 });
 async function detectStack(cwd) {
-  if (await fileExists2(path34__default.join(cwd, "package.json"))) return "node";
-  if (await fileExists2(path34__default.join(cwd, "Cargo.toml"))) return "rust";
-  if (await fileExists2(path34__default.join(cwd, "pyproject.toml"))) return "python";
-  if (await fileExists2(path34__default.join(cwd, "go.mod"))) return "go";
-  if (await fileExists2(path34__default.join(cwd, "pom.xml"))) return "java";
+  if (await fileExists2(path35__default.join(cwd, "package.json"))) return "node";
+  if (await fileExists2(path35__default.join(cwd, "Cargo.toml"))) return "rust";
+  if (await fileExists2(path35__default.join(cwd, "pyproject.toml"))) return "python";
+  if (await fileExists2(path35__default.join(cwd, "go.mod"))) return "go";
+  if (await fileExists2(path35__default.join(cwd, "pom.xml"))) return "java";
   return "unknown";
 }
 async function detectPackageManager(cwd, stack) {
@@ -15141,15 +15227,15 @@ async function detectPackageManager(cwd, stack) {
   if (stack === "python") return "pip";
   if (stack === "go") return "go";
   if (stack === "node") {
-    if (await fileExists2(path34__default.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-    if (await fileExists2(path34__default.join(cwd, "yarn.lock"))) return "yarn";
-    if (await fileExists2(path34__default.join(cwd, "bun.lockb"))) return "bun";
+    if (await fileExists2(path35__default.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+    if (await fileExists2(path35__default.join(cwd, "yarn.lock"))) return "yarn";
+    if (await fileExists2(path35__default.join(cwd, "bun.lockb"))) return "bun";
     return "npm";
   }
   return null;
 }
 async function detectCI(cwd) {
-  const ghDir = path34__default.join(cwd, ".github", "workflows");
+  const ghDir = path35__default.join(cwd, ".github", "workflows");
   if (await fileExists2(ghDir)) {
     let workflowFiles = [];
     let hasCodeQL = false;
@@ -15173,7 +15259,7 @@ async function detectCI(cwd) {
     }
     return { type: "github-actions", workflowFiles, hasCodeQL, hasLinting };
   }
-  if (await fileExists2(path34__default.join(cwd, ".gitlab-ci.yml"))) {
+  if (await fileExists2(path35__default.join(cwd, ".gitlab-ci.yml"))) {
     return {
       type: "gitlab-ci",
       workflowFiles: [".gitlab-ci.yml"],
@@ -15181,7 +15267,7 @@ async function detectCI(cwd) {
       hasLinting: false
     };
   }
-  if (await fileExists2(path34__default.join(cwd, ".circleci"))) {
+  if (await fileExists2(path35__default.join(cwd, ".circleci"))) {
     return { type: "circle-ci", workflowFiles: [], hasCodeQL: false, hasLinting: false };
   }
   return { type: "none", workflowFiles: [], hasCodeQL: false, hasLinting: false };
@@ -16552,8 +16638,8 @@ function hasNullByte(str) {
 }
 function isBlockedPath(absolute) {
   for (const blocked of BLOCKED_PATHS) {
-    const normalizedBlocked = path34__default.normalize(blocked);
-    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path34__default.sep)) {
+    const normalizedBlocked = path35__default.normalize(blocked);
+    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path35__default.sep)) {
       return blocked;
     }
   }
@@ -16571,7 +16657,7 @@ function getInterpreter(ext) {
 }
 async function isExecutable(filePath) {
   try {
-    await fs32__default.access(filePath, fs32__default.constants.X_OK);
+    await fs33__default.access(filePath, fs33__default.constants.X_OK);
     return true;
   } catch {
     return false;
@@ -16647,7 +16733,7 @@ Examples:
           throw new ToolError("Invalid file path", { tool: "open_file" });
         }
         const workDir = cwd ?? process.cwd();
-        const absolute = path34__default.isAbsolute(filePath) ? path34__default.normalize(filePath) : path34__default.resolve(workDir, filePath);
+        const absolute = path35__default.isAbsolute(filePath) ? path35__default.normalize(filePath) : path35__default.resolve(workDir, filePath);
         const blockedBy = isBlockedPath(absolute);
         if (blockedBy) {
           throw new ToolError(`Access to system path '${blockedBy}' is not allowed`, {
@@ -16655,7 +16741,7 @@ Examples:
           });
         }
         try {
-          await fs32__default.access(absolute);
+          await fs33__default.access(absolute);
         } catch {
           throw new ToolError(`File not found: ${absolute}`, { tool: "open_file" });
         }
@@ -16670,14 +16756,14 @@ Examples:
           };
         }
         if (isBlockedExecFile(absolute)) {
-          throw new ToolError(`Execution of sensitive file is blocked: ${path34__default.basename(absolute)}`, {
+          throw new ToolError(`Execution of sensitive file is blocked: ${path35__default.basename(absolute)}`, {
             tool: "open_file"
           });
         }
         if (args.length > 0 && hasDangerousArgs(args)) {
           throw new ToolError("Arguments contain dangerous patterns", { tool: "open_file" });
         }
-        const ext = path34__default.extname(absolute);
+        const ext = path35__default.extname(absolute);
         const interpreter = getInterpreter(ext);
         const executable = await isExecutable(absolute);
         let command;
@@ -16690,7 +16776,7 @@ Examples:
           cmdArgs = [...args];
         } else {
           throw new ToolError(
-            `Cannot execute '${path34__default.basename(absolute)}': no known interpreter for '${ext || "(no extension)"}' and file is not executable`,
+            `Cannot execute '${path35__default.basename(absolute)}': no known interpreter for '${ext || "(no extension)"}' and file is not executable`,
             { tool: "open_file" }
           );
         }
@@ -16862,10 +16948,10 @@ function getAllowedPaths() {
   return [...sessionAllowedPaths];
 }
 function isWithinAllowedPath(absolutePath, operation) {
-  const normalizedTarget = path34__default.normalize(absolutePath);
+  const normalizedTarget = path35__default.normalize(absolutePath);
   for (const entry of sessionAllowedPaths) {
-    const normalizedAllowed = path34__default.normalize(entry.path);
-    if (normalizedTarget === normalizedAllowed || normalizedTarget.startsWith(normalizedAllowed + path34__default.sep)) {
+    const normalizedAllowed = path35__default.normalize(entry.path);
+    if (normalizedTarget === normalizedAllowed || normalizedTarget.startsWith(normalizedAllowed + path35__default.sep)) {
       if (operation === "read") return true;
       if (entry.level === "write") return true;
     }
@@ -16873,8 +16959,8 @@ function isWithinAllowedPath(absolutePath, operation) {
   return false;
 }
 function addAllowedPathToSession(dirPath, level) {
-  const absolute = path34__default.resolve(dirPath);
-  if (sessionAllowedPaths.some((e) => path34__default.normalize(e.path) === path34__default.normalize(absolute))) {
+  const absolute = path35__default.resolve(dirPath);
+  if (sessionAllowedPaths.some((e) => path35__default.normalize(e.path) === path35__default.normalize(absolute))) {
     return;
   }
   sessionAllowedPaths.push({
@@ -16884,14 +16970,14 @@ function addAllowedPathToSession(dirPath, level) {
   });
 }
 function removeAllowedPathFromSession(dirPath) {
-  const absolute = path34__default.resolve(dirPath);
-  const normalized = path34__default.normalize(absolute);
+  const absolute = path35__default.resolve(dirPath);
+  const normalized = path35__default.normalize(absolute);
   const before = sessionAllowedPaths.length;
-  sessionAllowedPaths = sessionAllowedPaths.filter((e) => path34__default.normalize(e.path) !== normalized);
+  sessionAllowedPaths = sessionAllowedPaths.filter((e) => path35__default.normalize(e.path) !== normalized);
   return sessionAllowedPaths.length < before;
 }
 async function loadAllowedPaths(projectPath) {
-  currentProjectPath = path34__default.resolve(projectPath);
+  currentProjectPath = path35__default.resolve(projectPath);
   const store = await loadStore();
   const entries = store.projects[currentProjectPath] ?? [];
   for (const entry of entries) {
@@ -16900,14 +16986,14 @@ async function loadAllowedPaths(projectPath) {
 }
 async function persistAllowedPath(dirPath, level) {
   if (!currentProjectPath) return;
-  const absolute = path34__default.resolve(dirPath);
+  const absolute = path35__default.resolve(dirPath);
   const store = await loadStore();
   if (!store.projects[currentProjectPath]) {
     store.projects[currentProjectPath] = [];
   }
   const entries = store.projects[currentProjectPath];
-  const normalized = path34__default.normalize(absolute);
-  if (entries.some((e) => path34__default.normalize(e.path) === normalized)) {
+  const normalized = path35__default.normalize(absolute);
+  if (entries.some((e) => path35__default.normalize(e.path) === normalized)) {
     return;
   }
   entries.push({
@@ -16919,13 +17005,13 @@ async function persistAllowedPath(dirPath, level) {
 }
 async function removePersistedAllowedPath(dirPath) {
   if (!currentProjectPath) return false;
-  const absolute = path34__default.resolve(dirPath);
-  const normalized = path34__default.normalize(absolute);
+  const absolute = path35__default.resolve(dirPath);
+  const normalized = path35__default.normalize(absolute);
   const store = await loadStore();
   const entries = store.projects[currentProjectPath];
   if (!entries) return false;
   const before = entries.length;
-  store.projects[currentProjectPath] = entries.filter((e) => path34__default.normalize(e.path) !== normalized);
+  store.projects[currentProjectPath] = entries.filter((e) => path35__default.normalize(e.path) !== normalized);
   if (store.projects[currentProjectPath].length < before) {
     await saveStore(store);
     return true;
@@ -16934,7 +17020,7 @@ async function removePersistedAllowedPath(dirPath) {
 }
 async function loadStore() {
   try {
-    const content = await fs32__default.readFile(STORE_FILE, "utf-8");
+    const content = await fs33__default.readFile(STORE_FILE, "utf-8");
     return { ...DEFAULT_STORE, ...JSON.parse(content) };
   } catch {
     return { ...DEFAULT_STORE };
@@ -16942,8 +17028,8 @@ async function loadStore() {
 }
 async function saveStore(store) {
   try {
-    await fs32__default.mkdir(path34__default.dirname(STORE_FILE), { recursive: true });
-    await fs32__default.writeFile(STORE_FILE, JSON.stringify(store, null, 2), "utf-8");
+    await fs33__default.mkdir(path35__default.dirname(STORE_FILE), { recursive: true });
+    await fs33__default.writeFile(STORE_FILE, JSON.stringify(store, null, 2), "utf-8");
   } catch {
   }
 }
@@ -16951,7 +17037,7 @@ var STORE_FILE, DEFAULT_STORE, sessionAllowedPaths, currentProjectPath;
 var init_allowed_paths = __esm({
   "src/tools/allowed-paths.ts"() {
     init_paths();
-    STORE_FILE = path34__default.join(CONFIG_PATHS.home, "allowed-paths.json");
+    STORE_FILE = path35__default.join(CONFIG_PATHS.home, "allowed-paths.json");
     DEFAULT_STORE = {
       version: 1,
       projects: {}
@@ -17007,7 +17093,7 @@ function shouldAutoApprove(command, cwd) {
 }
 async function loadFullAccessPreference() {
   try {
-    const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+    const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
     const config = JSON.parse(content);
     if (typeof config.fullAccessMode === "boolean") {
       fullAccessEnabled = config.fullAccessMode;
@@ -17021,12 +17107,12 @@ async function saveFullAccessPreference(enabled) {
   try {
     let config = {};
     try {
-      const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+      const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
       config = JSON.parse(content);
     } catch {
     }
     config.fullAccessMode = enabled;
-    await fs32__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
+    await fs33__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
   } catch {
   }
 }
@@ -18142,7 +18228,7 @@ function shouldFullPowerApprove(command) {
 }
 async function loadFullPowerRiskPreference() {
   try {
-    const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+    const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
     const config = JSON.parse(content);
     if (typeof config.fullPowerRiskMode === "boolean") {
       fullPowerRiskEnabled = config.fullPowerRiskMode;
@@ -18156,12 +18242,12 @@ async function saveFullPowerRiskPreference(enabled) {
   try {
     let config = {};
     try {
-      const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+      const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
       config = JSON.parse(content);
     } catch {
     }
     config.fullPowerRiskMode = enabled;
-    await fs32__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
+    await fs33__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
   } catch {
   }
 }
@@ -18213,7 +18299,7 @@ __export(allow_path_prompt_exports, {
   promptAllowPath: () => promptAllowPath
 });
 async function promptAllowPath(dirPath) {
-  const absolute = path34__default.resolve(dirPath);
+  const absolute = path35__default.resolve(dirPath);
   console.log();
   console.log(chalk25.yellow("  \u26A0 Access denied \u2014 path is outside the project directory"));
   console.log(chalk25.dim(`  \u{1F4C1} ${absolute}`));
@@ -18448,13 +18534,13 @@ __export(stack_detector_exports, {
   detectProjectStack: () => detectProjectStack
 });
 async function detectStack2(cwd) {
-  if (await fileExists2(path34__default.join(cwd, "package.json"))) return "node";
-  if (await fileExists2(path34__default.join(cwd, "Cargo.toml"))) return "rust";
-  if (await fileExists2(path34__default.join(cwd, "pyproject.toml"))) return "python";
-  if (await fileExists2(path34__default.join(cwd, "go.mod"))) return "go";
-  if (await fileExists2(path34__default.join(cwd, "pom.xml"))) return "java";
-  if (await fileExists2(path34__default.join(cwd, "build.gradle"))) return "java";
-  if (await fileExists2(path34__default.join(cwd, "build.gradle.kts"))) return "java";
+  if (await fileExists2(path35__default.join(cwd, "package.json"))) return "node";
+  if (await fileExists2(path35__default.join(cwd, "Cargo.toml"))) return "rust";
+  if (await fileExists2(path35__default.join(cwd, "pyproject.toml"))) return "python";
+  if (await fileExists2(path35__default.join(cwd, "go.mod"))) return "go";
+  if (await fileExists2(path35__default.join(cwd, "pom.xml"))) return "java";
+  if (await fileExists2(path35__default.join(cwd, "build.gradle"))) return "java";
+  if (await fileExists2(path35__default.join(cwd, "build.gradle.kts"))) return "java";
   return "unknown";
 }
 async function detectPackageManager3(cwd, stack) {
@@ -18462,25 +18548,25 @@ async function detectPackageManager3(cwd, stack) {
   if (stack === "python") return "pip";
   if (stack === "go") return "go";
   if (stack === "java") {
-    if (await fileExists2(path34__default.join(cwd, "build.gradle")) || await fileExists2(path34__default.join(cwd, "build.gradle.kts"))) {
+    if (await fileExists2(path35__default.join(cwd, "build.gradle")) || await fileExists2(path35__default.join(cwd, "build.gradle.kts"))) {
       return "gradle";
     }
-    if (await fileExists2(path34__default.join(cwd, "pom.xml"))) {
+    if (await fileExists2(path35__default.join(cwd, "pom.xml"))) {
       return "maven";
     }
   }
   if (stack === "node") {
-    if (await fileExists2(path34__default.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-    if (await fileExists2(path34__default.join(cwd, "yarn.lock"))) return "yarn";
-    if (await fileExists2(path34__default.join(cwd, "bun.lockb"))) return "bun";
+    if (await fileExists2(path35__default.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+    if (await fileExists2(path35__default.join(cwd, "yarn.lock"))) return "yarn";
+    if (await fileExists2(path35__default.join(cwd, "bun.lockb"))) return "bun";
     return "npm";
   }
   return null;
 }
 async function parsePackageJson(cwd) {
-  const packageJsonPath = path34__default.join(cwd, "package.json");
+  const packageJsonPath = path35__default.join(cwd, "package.json");
   try {
-    const content = await fs32__default.readFile(packageJsonPath, "utf-8");
+    const content = await fs33__default.readFile(packageJsonPath, "utf-8");
     const pkg = JSON.parse(content);
     const allDeps = {
       ...pkg.dependencies,
@@ -18510,7 +18596,7 @@ async function parsePackageJson(cwd) {
     if (allDeps["@playwright/test"]) testingFrameworks.push("playwright");
     if (allDeps.cypress) testingFrameworks.push("cypress");
     const languages = ["JavaScript"];
-    if (allDeps.typescript || await fileExists2(path34__default.join(cwd, "tsconfig.json"))) {
+    if (allDeps.typescript || await fileExists2(path35__default.join(cwd, "tsconfig.json"))) {
       languages.push("TypeScript");
     }
     return {
@@ -18531,9 +18617,9 @@ async function parsePackageJson(cwd) {
   }
 }
 async function parsePomXml(cwd) {
-  const pomPath = path34__default.join(cwd, "pom.xml");
+  const pomPath = path35__default.join(cwd, "pom.xml");
   try {
-    const content = await fs32__default.readFile(pomPath, "utf-8");
+    const content = await fs33__default.readFile(pomPath, "utf-8");
     const dependencies = {};
     const frameworks = [];
     const buildTools2 = ["maven"];
@@ -18568,9 +18654,9 @@ async function parsePomXml(cwd) {
   }
 }
 async function parsePyprojectToml(cwd) {
-  const pyprojectPath = path34__default.join(cwd, "pyproject.toml");
+  const pyprojectPath = path35__default.join(cwd, "pyproject.toml");
   try {
-    const content = await fs32__default.readFile(pyprojectPath, "utf-8");
+    const content = await fs33__default.readFile(pyprojectPath, "utf-8");
     const dependencies = {};
     const frameworks = [];
     const buildTools2 = ["pip"];
@@ -20075,26 +20161,26 @@ var init_input_echo = __esm({
 // src/cli/index.ts
 init_version();
 async function createProjectStructure(projectPath, info) {
-  const cocoPath = path34__default.join(projectPath, ".coco");
+  const cocoPath = path35__default.join(projectPath, ".coco");
   const directories = [
     cocoPath,
-    path34__default.join(cocoPath, "state"),
-    path34__default.join(cocoPath, "checkpoints"),
-    path34__default.join(cocoPath, "logs"),
-    path34__default.join(cocoPath, "discovery"),
-    path34__default.join(cocoPath, "spec"),
-    path34__default.join(cocoPath, "architecture"),
-    path34__default.join(cocoPath, "architecture", "adrs"),
-    path34__default.join(cocoPath, "architecture", "diagrams"),
-    path34__default.join(cocoPath, "planning"),
-    path34__default.join(cocoPath, "planning", "epics"),
-    path34__default.join(cocoPath, "execution"),
-    path34__default.join(cocoPath, "versions"),
-    path34__default.join(cocoPath, "reviews"),
-    path34__default.join(cocoPath, "delivery")
+    path35__default.join(cocoPath, "state"),
+    path35__default.join(cocoPath, "checkpoints"),
+    path35__default.join(cocoPath, "logs"),
+    path35__default.join(cocoPath, "discovery"),
+    path35__default.join(cocoPath, "spec"),
+    path35__default.join(cocoPath, "architecture"),
+    path35__default.join(cocoPath, "architecture", "adrs"),
+    path35__default.join(cocoPath, "architecture", "diagrams"),
+    path35__default.join(cocoPath, "planning"),
+    path35__default.join(cocoPath, "planning", "epics"),
+    path35__default.join(cocoPath, "execution"),
+    path35__default.join(cocoPath, "versions"),
+    path35__default.join(cocoPath, "reviews"),
+    path35__default.join(cocoPath, "delivery")
   ];
   for (const dir of directories) {
-    await fs32__default.mkdir(dir, { recursive: true });
+    await fs33__default.mkdir(dir, { recursive: true });
   }
   await createInitialConfig(cocoPath, info);
   await createProjectState(cocoPath, info);
@@ -20127,7 +20213,7 @@ async function createInitialConfig(cocoPath, info) {
       maxCheckpoints: 50
     }
   };
-  await fs32__default.writeFile(path34__default.join(cocoPath, "config.json"), JSON.stringify(config, null, 2), "utf-8");
+  await fs33__default.writeFile(path35__default.join(cocoPath, "config.json"), JSON.stringify(config, null, 2), "utf-8");
 }
 async function createProjectState(cocoPath, info) {
   const state = {
@@ -20144,8 +20230,8 @@ async function createProjectState(cocoPath, info) {
     qualityHistory: [],
     lastCheckpoint: null
   };
-  await fs32__default.writeFile(
-    path34__default.join(cocoPath, "state", "project.json"),
+  await fs33__default.writeFile(
+    path35__default.join(cocoPath, "state", "project.json"),
     JSON.stringify(state, null, 2),
     "utf-8"
   );
@@ -20166,7 +20252,7 @@ checkpoints/
 state/session.json
 state/lock.json
 `;
-  await fs32__default.writeFile(path34__default.join(cocoPath, ".gitignore"), content, "utf-8");
+  await fs33__default.writeFile(path35__default.join(cocoPath, ".gitignore"), content, "utf-8");
 }
 async function createReadme(cocoPath, info) {
   const content = `# Corbat-Coco Project: ${info.name}
@@ -20213,13 +20299,13 @@ Edit \`config.json\` to customize:
 ---
 Generated by Corbat-Coco v0.1.0
 `;
-  await fs32__default.writeFile(path34__default.join(cocoPath, "README.md"), content, "utf-8");
+  await fs33__default.writeFile(path35__default.join(cocoPath, "README.md"), content, "utf-8");
 }
 
 // src/cli/commands/init.ts
 function registerInitCommand(program2) {
-  program2.command("init").description("Initialize a new Corbat-Coco project").argument("[path]", "Project directory path", ".").option("-t, --template <template>", "Project template to use").option("-y, --yes", "Skip prompts and use defaults").option("--skip-discovery", "Skip the discovery phase (use existing spec)").action(async (path54, options) => {
-    await runInit(path54, options);
+  program2.command("init").description("Initialize a new Corbat-Coco project").argument("[path]", "Project directory path", ".").option("-t, --template <template>", "Project template to use").option("-y, --yes", "Skip prompts and use defaults").option("--skip-discovery", "Skip the discovery phase (use existing spec)").action(async (path55, options) => {
+    await runInit(path55, options);
   });
 }
 async function runInit(projectPath, options) {
@@ -20298,18 +20384,18 @@ async function gatherProjectInfo() {
     language
   };
 }
-function getDefaultProjectInfo(path54) {
-  const name = path54 === "." ? "my-project" : path54.split("/").pop() || "my-project";
+function getDefaultProjectInfo(path55) {
+  const name = path55 === "." ? "my-project" : path55.split("/").pop() || "my-project";
   return {
     name,
     description: "",
     language: "typescript"
   };
 }
-async function checkExistingProject(path54) {
+async function checkExistingProject(path55) {
   try {
-    const fs52 = await import('fs/promises');
-    await fs52.access(`${path54}/.coco`);
+    const fs53 = await import('fs/promises');
+    await fs53.access(`${path55}/.coco`);
     return true;
   } catch {
     return false;
@@ -21517,13 +21603,13 @@ function createSpecificationGenerator(llm, config) {
 // src/phases/converge/persistence.ts
 init_errors();
 function getPersistencePaths(projectPath) {
-  const baseDir = path34__default.join(projectPath, ".coco", "spec");
+  const baseDir = path35__default.join(projectPath, ".coco", "spec");
   return {
     baseDir,
-    sessionFile: path34__default.join(baseDir, "discovery-session.json"),
-    specFile: path34__default.join(baseDir, "spec.md"),
-    conversationLog: path34__default.join(baseDir, "conversation.jsonl"),
-    checkpointFile: path34__default.join(baseDir, "checkpoint.json")
+    sessionFile: path35__default.join(baseDir, "discovery-session.json"),
+    specFile: path35__default.join(baseDir, "spec.md"),
+    conversationLog: path35__default.join(baseDir, "conversation.jsonl"),
+    checkpointFile: path35__default.join(baseDir, "checkpoint.json")
   };
 }
 var SessionPersistence = class {
@@ -21536,7 +21622,7 @@ var SessionPersistence = class {
    */
   async ensureDir() {
     try {
-      await fs32__default.mkdir(this.paths.baseDir, { recursive: true });
+      await fs33__default.mkdir(this.paths.baseDir, { recursive: true });
     } catch {
       throw new FileSystemError(`Failed to create persistence directory: ${this.paths.baseDir}`, {
         path: this.paths.baseDir,
@@ -21551,7 +21637,7 @@ var SessionPersistence = class {
     await this.ensureDir();
     try {
       const data = JSON.stringify(session, null, 2);
-      await fs32__default.writeFile(this.paths.sessionFile, data, "utf-8");
+      await fs33__default.writeFile(this.paths.sessionFile, data, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save discovery session", {
         path: this.paths.sessionFile,
@@ -21564,7 +21650,7 @@ var SessionPersistence = class {
    */
   async loadSession() {
     try {
-      const data = await fs32__default.readFile(this.paths.sessionFile, "utf-8");
+      const data = await fs33__default.readFile(this.paths.sessionFile, "utf-8");
       const parsed = JSON.parse(data);
       parsed.startedAt = new Date(parsed.startedAt);
       parsed.updatedAt = new Date(parsed.updatedAt);
@@ -21590,7 +21676,7 @@ var SessionPersistence = class {
    */
   async hasSession() {
     try {
-      await fs32__default.access(this.paths.sessionFile);
+      await fs33__default.access(this.paths.sessionFile);
       return true;
     } catch {
       return false;
@@ -21601,7 +21687,7 @@ var SessionPersistence = class {
    */
   async deleteSession() {
     try {
-      await fs32__default.unlink(this.paths.sessionFile);
+      await fs33__default.unlink(this.paths.sessionFile);
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw new FileSystemError("Failed to delete discovery session", {
@@ -21617,7 +21703,7 @@ var SessionPersistence = class {
   async saveSpecification(content) {
     await this.ensureDir();
     try {
-      await fs32__default.writeFile(this.paths.specFile, content, "utf-8");
+      await fs33__default.writeFile(this.paths.specFile, content, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save specification", {
         path: this.paths.specFile,
@@ -21630,7 +21716,7 @@ var SessionPersistence = class {
    */
   async loadSpecification() {
     try {
-      return await fs32__default.readFile(this.paths.specFile, "utf-8");
+      return await fs33__default.readFile(this.paths.specFile, "utf-8");
     } catch {
       return null;
     }
@@ -21646,7 +21732,7 @@ var SessionPersistence = class {
       content
     };
     try {
-      await fs32__default.appendFile(this.paths.conversationLog, JSON.stringify(entry) + "\n", "utf-8");
+      await fs33__default.appendFile(this.paths.conversationLog, JSON.stringify(entry) + "\n", "utf-8");
     } catch {
       throw new FileSystemError("Failed to append to conversation log", {
         path: this.paths.conversationLog,
@@ -21659,7 +21745,7 @@ var SessionPersistence = class {
    */
   async loadConversationLog() {
     try {
-      const data = await fs32__default.readFile(this.paths.conversationLog, "utf-8");
+      const data = await fs33__default.readFile(this.paths.conversationLog, "utf-8");
       const lines = data.trim().split("\n");
       return lines.filter((line) => line.trim()).map((line) => JSON.parse(line));
     } catch {
@@ -21673,7 +21759,7 @@ var SessionPersistence = class {
     await this.ensureDir();
     try {
       const data = JSON.stringify(checkpoint, null, 2);
-      await fs32__default.writeFile(this.paths.checkpointFile, data, "utf-8");
+      await fs33__default.writeFile(this.paths.checkpointFile, data, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save checkpoint", {
         path: this.paths.checkpointFile,
@@ -21686,7 +21772,7 @@ var SessionPersistence = class {
    */
   async loadCheckpoint() {
     try {
-      const data = await fs32__default.readFile(this.paths.checkpointFile, "utf-8");
+      const data = await fs33__default.readFile(this.paths.checkpointFile, "utf-8");
       const parsed = JSON.parse(data);
       parsed.timestamp = new Date(parsed.timestamp);
       return parsed;
@@ -21699,7 +21785,7 @@ var SessionPersistence = class {
    */
   async clearAll() {
     try {
-      await fs32__default.rm(this.paths.baseDir, { recursive: true, force: true });
+      await fs33__default.rm(this.paths.baseDir, { recursive: true, force: true });
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw new FileSystemError("Failed to clear persistence data", {
@@ -23627,8 +23713,8 @@ var OrchestrateExecutor = class {
   }
   async loadSpecification(projectPath) {
     try {
-      const jsonPath = path34__default.join(projectPath, ".coco", "spec", "spec.json");
-      const jsonContent = await fs32__default.readFile(jsonPath, "utf-8");
+      const jsonPath = path35__default.join(projectPath, ".coco", "spec", "spec.json");
+      const jsonContent = await fs33__default.readFile(jsonPath, "utf-8");
       return JSON.parse(jsonContent);
     } catch {
       return this.createMinimalSpec(projectPath);
@@ -23639,7 +23725,7 @@ var OrchestrateExecutor = class {
       version: "1.0.0",
       generatedAt: /* @__PURE__ */ new Date(),
       overview: {
-        name: path34__default.basename(projectPath),
+        name: path35__default.basename(projectPath),
         description: "Project specification",
         goals: [],
         targetUsers: ["developers"],
@@ -23666,53 +23752,53 @@ var OrchestrateExecutor = class {
     };
   }
   async saveArchitecture(projectPath, architecture) {
-    const dir = path34__default.join(projectPath, ".coco", "architecture");
-    await fs32__default.mkdir(dir, { recursive: true });
-    const mdPath = path34__default.join(dir, "ARCHITECTURE.md");
-    await fs32__default.writeFile(mdPath, generateArchitectureMarkdown(architecture), "utf-8");
-    const jsonPath = path34__default.join(dir, "architecture.json");
-    await fs32__default.writeFile(jsonPath, JSON.stringify(architecture, null, 2), "utf-8");
+    const dir = path35__default.join(projectPath, ".coco", "architecture");
+    await fs33__default.mkdir(dir, { recursive: true });
+    const mdPath = path35__default.join(dir, "ARCHITECTURE.md");
+    await fs33__default.writeFile(mdPath, generateArchitectureMarkdown(architecture), "utf-8");
+    const jsonPath = path35__default.join(dir, "architecture.json");
+    await fs33__default.writeFile(jsonPath, JSON.stringify(architecture, null, 2), "utf-8");
     return mdPath;
   }
   async saveADRs(projectPath, adrs) {
-    const dir = path34__default.join(projectPath, ".coco", "architecture", "adrs");
-    await fs32__default.mkdir(dir, { recursive: true });
+    const dir = path35__default.join(projectPath, ".coco", "architecture", "adrs");
+    await fs33__default.mkdir(dir, { recursive: true });
     const paths = [];
-    const indexPath = path34__default.join(dir, "README.md");
-    await fs32__default.writeFile(indexPath, generateADRIndexMarkdown(adrs), "utf-8");
+    const indexPath = path35__default.join(dir, "README.md");
+    await fs33__default.writeFile(indexPath, generateADRIndexMarkdown(adrs), "utf-8");
     paths.push(indexPath);
     for (const adr of adrs) {
       const filename = getADRFilename(adr);
-      const adrPath = path34__default.join(dir, filename);
-      await fs32__default.writeFile(adrPath, generateADRMarkdown(adr), "utf-8");
+      const adrPath = path35__default.join(dir, filename);
+      await fs33__default.writeFile(adrPath, generateADRMarkdown(adr), "utf-8");
       paths.push(adrPath);
     }
     return paths;
   }
   async saveBacklog(projectPath, backlogResult) {
-    const dir = path34__default.join(projectPath, ".coco", "planning");
-    await fs32__default.mkdir(dir, { recursive: true });
-    const mdPath = path34__default.join(dir, "BACKLOG.md");
-    await fs32__default.writeFile(mdPath, generateBacklogMarkdown(backlogResult.backlog), "utf-8");
-    const jsonPath = path34__default.join(dir, "backlog.json");
-    await fs32__default.writeFile(jsonPath, JSON.stringify(backlogResult, null, 2), "utf-8");
+    const dir = path35__default.join(projectPath, ".coco", "planning");
+    await fs33__default.mkdir(dir, { recursive: true });
+    const mdPath = path35__default.join(dir, "BACKLOG.md");
+    await fs33__default.writeFile(mdPath, generateBacklogMarkdown(backlogResult.backlog), "utf-8");
+    const jsonPath = path35__default.join(dir, "backlog.json");
+    await fs33__default.writeFile(jsonPath, JSON.stringify(backlogResult, null, 2), "utf-8");
     return mdPath;
   }
   async saveSprint(projectPath, sprint, backlogResult) {
-    const dir = path34__default.join(projectPath, ".coco", "planning", "sprints");
-    await fs32__default.mkdir(dir, { recursive: true });
+    const dir = path35__default.join(projectPath, ".coco", "planning", "sprints");
+    await fs33__default.mkdir(dir, { recursive: true });
     const filename = `${sprint.id}.md`;
-    const sprintPath = path34__default.join(dir, filename);
-    await fs32__default.writeFile(sprintPath, generateSprintMarkdown(sprint, backlogResult.backlog), "utf-8");
-    const jsonPath = path34__default.join(dir, `${sprint.id}.json`);
-    await fs32__default.writeFile(jsonPath, JSON.stringify(sprint, null, 2), "utf-8");
+    const sprintPath = path35__default.join(dir, filename);
+    await fs33__default.writeFile(sprintPath, generateSprintMarkdown(sprint, backlogResult.backlog), "utf-8");
+    const jsonPath = path35__default.join(dir, `${sprint.id}.json`);
+    await fs33__default.writeFile(jsonPath, JSON.stringify(sprint, null, 2), "utf-8");
     return sprintPath;
   }
   async saveDiagram(projectPath, id, mermaid) {
-    const dir = path34__default.join(projectPath, ".coco", "architecture", "diagrams");
-    await fs32__default.mkdir(dir, { recursive: true });
-    const diagramPath = path34__default.join(dir, `${id}.mmd`);
-    await fs32__default.writeFile(diagramPath, mermaid, "utf-8");
+    const dir = path35__default.join(projectPath, ".coco", "architecture", "diagrams");
+    await fs33__default.mkdir(dir, { recursive: true });
+    const diagramPath = path35__default.join(dir, `${id}.mmd`);
+    await fs33__default.writeFile(diagramPath, mermaid, "utf-8");
     return diagramPath;
   }
 };
@@ -23857,20 +23943,20 @@ async function createCliPhaseContext(projectPath, _onUserInput) {
     },
     tools: {
       file: {
-        async read(path54) {
-          const fs52 = await import('fs/promises');
-          return fs52.readFile(path54, "utf-8");
+        async read(path55) {
+          const fs53 = await import('fs/promises');
+          return fs53.readFile(path55, "utf-8");
         },
-        async write(path54, content) {
-          const fs52 = await import('fs/promises');
+        async write(path55, content) {
+          const fs53 = await import('fs/promises');
           const nodePath = await import('path');
-          await fs52.mkdir(nodePath.dirname(path54), { recursive: true });
-          await fs52.writeFile(path54, content, "utf-8");
+          await fs53.mkdir(nodePath.dirname(path55), { recursive: true });
+          await fs53.writeFile(path55, content, "utf-8");
         },
-        async exists(path54) {
-          const fs52 = await import('fs/promises');
+        async exists(path55) {
+          const fs53 = await import('fs/promises');
           try {
-            await fs52.access(path54);
+            await fs53.access(path55);
             return true;
           } catch {
             return false;
@@ -24109,16 +24195,16 @@ async function loadTasks(_options) {
   ];
 }
 async function checkProjectState() {
-  const fs52 = await import('fs/promises');
+  const fs53 = await import('fs/promises');
   let hasProject = false;
   let hasPlan = false;
   try {
-    await fs52.access(".coco");
+    await fs53.access(".coco");
     hasProject = true;
   } catch {
   }
   try {
-    await fs52.access(".coco/planning/backlog.json");
+    await fs53.access(".coco/planning/backlog.json");
     hasPlan = true;
   } catch {
   }
@@ -24225,24 +24311,24 @@ function getPhaseStatusForPhase(phase) {
   return "in_progress";
 }
 async function loadProjectState(cwd, config) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const statePath = path54.join(cwd, ".coco", "state.json");
-  const backlogPath = path54.join(cwd, ".coco", "planning", "backlog.json");
-  const checkpointDir = path54.join(cwd, ".coco", "checkpoints");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const statePath = path55.join(cwd, ".coco", "state.json");
+  const backlogPath = path55.join(cwd, ".coco", "planning", "backlog.json");
+  const checkpointDir = path55.join(cwd, ".coco", "checkpoints");
   let currentPhase = "idle";
   let metrics;
   let sprint;
   let checkpoints = [];
   try {
-    const stateContent = await fs52.readFile(statePath, "utf-8");
+    const stateContent = await fs53.readFile(statePath, "utf-8");
     const stateData = JSON.parse(stateContent);
     currentPhase = stateData.currentPhase || "idle";
     metrics = stateData.metrics;
   } catch {
   }
   try {
-    const backlogContent = await fs52.readFile(backlogPath, "utf-8");
+    const backlogContent = await fs53.readFile(backlogPath, "utf-8");
     const backlogData = JSON.parse(backlogContent);
     if (backlogData.currentSprint) {
       const tasks = backlogData.tasks || [];
@@ -24264,7 +24350,7 @@ async function loadProjectState(cwd, config) {
   } catch {
   }
   try {
-    const files = await fs52.readdir(checkpointDir);
+    const files = await fs53.readdir(checkpointDir);
     checkpoints = files.filter((f) => f.endsWith(".json")).sort().reverse();
   } catch {
   }
@@ -24400,8 +24486,8 @@ async function restoreFromCheckpoint(_checkpoint) {
 }
 async function checkProjectExists() {
   try {
-    const fs52 = await import('fs/promises');
-    await fs52.access(".coco");
+    const fs53 = await import('fs/promises');
+    await fs53.access(".coco");
     return true;
   } catch {
     return false;
@@ -25440,9 +25526,9 @@ var DEFAULT_CONFIG2 = {
   }
 };
 async function loadConfig2() {
-  const fs52 = await import('fs/promises');
+  const fs53 = await import('fs/promises');
   try {
-    const raw = await fs52.readFile(CONFIG_PATH, "utf-8");
+    const raw = await fs53.readFile(CONFIG_PATH, "utf-8");
     const parsed = JSON.parse(raw);
     return { ...DEFAULT_CONFIG2, ...parsed };
   } catch {
@@ -25450,13 +25536,13 @@ async function loadConfig2() {
   }
 }
 async function saveConfig2(config) {
-  const fs52 = await import('fs/promises');
+  const fs53 = await import('fs/promises');
   const dir = join(CONFIG_PATH, "..");
-  await fs52.mkdir(dir, { recursive: true });
-  await fs52.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2));
+  await fs53.mkdir(dir, { recursive: true });
+  await fs53.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2));
 }
-function getNestedValue(obj, path54) {
-  const keys = path54.split(".");
+function getNestedValue(obj, path55) {
+  const keys = path55.split(".");
   let current = obj;
   for (const key of keys) {
     if (current === null || current === void 0 || typeof current !== "object") {
@@ -25466,8 +25552,8 @@ function getNestedValue(obj, path54) {
   }
   return current;
 }
-function setNestedValue(obj, path54, value) {
-  const keys = path54.split(".");
+function setNestedValue(obj, path55, value) {
+  const keys = path55.split(".");
   let current = obj;
   for (let i = 0; i < keys.length - 1; i++) {
     const key = keys[i];
@@ -25807,13 +25893,13 @@ async function runAdd(source, options) {
   const isGithubShorthand = source.includes("/") && !isGitUrl;
   const isLocalPath = source.startsWith(".") || source.startsWith("/");
   if (isLocalPath) {
-    const targetDir = options.global ? CONFIG_PATHS.skills : path34__default.join(process.cwd(), ".coco", "skills");
-    const sourcePath = path34__default.resolve(source);
-    const skillName = path34__default.basename(sourcePath);
-    const destPath = path34__default.join(targetDir, skillName);
+    const targetDir = options.global ? CONFIG_PATHS.skills : path35__default.join(process.cwd(), ".coco", "skills");
+    const sourcePath = path35__default.resolve(source);
+    const skillName = path35__default.basename(sourcePath);
+    const destPath = path35__default.join(targetDir, skillName);
     try {
-      await fs32__default.mkdir(targetDir, { recursive: true });
-      await fs32__default.cp(sourcePath, destPath, { recursive: true });
+      await fs33__default.mkdir(targetDir, { recursive: true });
+      await fs33__default.cp(sourcePath, destPath, { recursive: true });
       p25.log.success(`Installed "${skillName}" to ${destPath}`);
     } catch (error) {
       p25.log.error(
@@ -25843,10 +25929,10 @@ async function runAdd(source, options) {
       p25.log.info("Try installing manually: git clone the repo into .coco/skills/");
     }
   } else if (isGitUrl) {
-    const targetDir = options.global ? CONFIG_PATHS.skills : path34__default.join(process.cwd(), ".coco", "skills");
-    await fs32__default.mkdir(targetDir, { recursive: true });
+    const targetDir = options.global ? CONFIG_PATHS.skills : path35__default.join(process.cwd(), ".coco", "skills");
+    await fs33__default.mkdir(targetDir, { recursive: true });
     const skillName = source.split("/").pop()?.replace(".git", "") ?? "skill";
-    const skillDir = path34__default.join(targetDir, skillName);
+    const skillDir = path35__default.join(targetDir, skillName);
     const spinner19 = p25.spinner();
     spinner19.start(`Cloning ${source}...`);
     try {
@@ -25871,10 +25957,10 @@ async function runAdd(source, options) {
 }
 async function runRemove(name, options) {
   p25.intro(chalk25.magenta("Remove Skill"));
-  const targetDir = options.global ? CONFIG_PATHS.skills : path34__default.join(process.cwd(), ".coco", "skills");
-  const skillPath = path34__default.join(targetDir, name);
+  const targetDir = options.global ? CONFIG_PATHS.skills : path35__default.join(process.cwd(), ".coco", "skills");
+  const skillPath = path35__default.join(targetDir, name);
   try {
-    await fs32__default.access(skillPath);
+    await fs33__default.access(skillPath);
   } catch {
     p25.log.error(`Skill "${name}" not found at ${skillPath}`);
     p25.outro("");
@@ -25890,7 +25976,7 @@ async function runRemove(name, options) {
       return;
     }
   }
-  await fs32__default.rm(skillPath, { recursive: true });
+  await fs33__default.rm(skillPath, { recursive: true });
   p25.log.success(`Removed "${name}"`);
   p25.outro("");
 }
@@ -25951,10 +26037,10 @@ async function runInfo(name) {
 }
 async function runCreate(name, options) {
   p25.intro(chalk25.magenta("Create Skill"));
-  const targetDir = options.global ? CONFIG_PATHS.skills : path34__default.join(process.cwd(), ".coco", "skills");
-  const skillDir = path34__default.join(targetDir, name);
+  const targetDir = options.global ? CONFIG_PATHS.skills : path35__default.join(process.cwd(), ".coco", "skills");
+  const skillDir = path35__default.join(targetDir, name);
   try {
-    await fs32__default.access(skillDir);
+    await fs33__default.access(skillDir);
     p25.log.error(`Skill "${name}" already exists at ${skillDir}`);
     p25.outro("");
     return;
@@ -25983,7 +26069,7 @@ async function runCreate(name, options) {
     p25.outro("Cancelled.");
     return;
   }
-  await fs32__default.mkdir(skillDir, { recursive: true });
+  await fs33__default.mkdir(skillDir, { recursive: true });
   const skillMd = `---
 name: "${name}"
 description: "${description}"
@@ -26005,10 +26091,10 @@ when this skill is activated (automatically via matching or manually via /${name
 2. Include examples when helpful
 3. Keep instructions under 500 lines
 `;
-  await fs32__default.writeFile(path34__default.join(skillDir, "SKILL.md"), skillMd, "utf-8");
-  await fs32__default.mkdir(path34__default.join(skillDir, "references"), { recursive: true });
+  await fs33__default.writeFile(path35__default.join(skillDir, "SKILL.md"), skillMd, "utf-8");
+  await fs33__default.mkdir(path35__default.join(skillDir, "references"), { recursive: true });
   p25.log.success(`Created skill at ${skillDir}`);
-  p25.log.info(`Edit ${path34__default.join(skillDir, "SKILL.md")} to add instructions.`);
+  p25.log.info(`Edit ${path35__default.join(skillDir, "SKILL.md")} to add instructions.`);
   p25.outro("");
 }
 
@@ -26372,10 +26458,10 @@ function registerCheckCommand(program2) {
 
 // src/swarm/spec-parser.ts
 async function parseSwarmSpec(filePath) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const rawContent = await fs52.readFile(filePath, "utf-8");
-  const ext = path54.extname(filePath).toLowerCase();
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const rawContent = await fs53.readFile(filePath, "utf-8");
+  const ext = path55.extname(filePath).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") {
     return parseYamlSpec(rawContent);
   }
@@ -26704,11 +26790,11 @@ var DEFAULT_AGENT_CONFIG = {
   integrator: { maxTurns: 20, temperature: 0.2 }
 };
 async function loadAgentConfig(projectPath) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const configPath = path54.join(projectPath, ".coco", "swarm", "agents.json");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const configPath = path55.join(projectPath, ".coco", "swarm", "agents.json");
   try {
-    const raw = await fs52.readFile(configPath, "utf-8");
+    const raw = await fs53.readFile(configPath, "utf-8");
     const parsed = JSON.parse(raw);
     const merged = { ...DEFAULT_AGENT_CONFIG };
     for (const role of Object.keys(DEFAULT_AGENT_CONFIG)) {
@@ -26896,19 +26982,19 @@ async function createBoard(projectPath, spec) {
   return board;
 }
 async function loadBoard(projectPath) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const boardPath = path54.join(projectPath, ".coco", "swarm", "task-board.json");
-  const raw = await fs52.readFile(boardPath, "utf-8");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const boardPath = path55.join(projectPath, ".coco", "swarm", "task-board.json");
+  const raw = await fs53.readFile(boardPath, "utf-8");
   return JSON.parse(raw);
 }
 async function saveBoard(projectPath, board) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const boardDir = path54.join(projectPath, ".coco", "swarm");
-  const boardPath = path54.join(boardDir, "task-board.json");
-  await fs52.mkdir(boardDir, { recursive: true });
-  await fs52.writeFile(boardPath, JSON.stringify(board, null, 2), "utf-8");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const boardDir = path55.join(projectPath, ".coco", "swarm");
+  const boardPath = path55.join(boardDir, "task-board.json");
+  await fs53.mkdir(boardDir, { recursive: true });
+  await fs53.writeFile(boardPath, JSON.stringify(board, null, 2), "utf-8");
 }
 function markTaskInProgress(board, taskId, role) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -27073,11 +27159,11 @@ async function defaultPromptHandler(q) {
   }
 }
 async function writeAssumptionsFile(projectPath, projectName, questions, assumptions) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const swarmDir = path54.join(projectPath, ".coco", "swarm");
-  const assumptionsPath = path54.join(swarmDir, "assumptions.md");
-  await fs52.mkdir(swarmDir, { recursive: true });
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const swarmDir = path55.join(projectPath, ".coco", "swarm");
+  const assumptionsPath = path55.join(swarmDir, "assumptions.md");
+  await fs53.mkdir(swarmDir, { recursive: true });
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const content = [
     `# Swarm Assumptions \u2014 ${projectName}`,
@@ -27093,18 +27179,18 @@ async function writeAssumptionsFile(projectPath, projectName, questions, assumpt
     assumptions.length > 0 ? assumptions.join("\n\n") : `_(none)_`,
     ``
   ].join("\n");
-  await fs52.writeFile(assumptionsPath, content, "utf-8");
+  await fs53.writeFile(assumptionsPath, content, "utf-8");
   return assumptionsPath;
 }
 
 // src/swarm/events.ts
 async function appendSwarmEvent(projectPath, event) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const eventsDir = path54.join(projectPath, ".coco", "swarm");
-  const eventsFile = path54.join(eventsDir, "events.jsonl");
-  await fs52.mkdir(eventsDir, { recursive: true });
-  await fs52.appendFile(eventsFile, JSON.stringify(event) + "\n", "utf-8");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const eventsDir = path55.join(projectPath, ".coco", "swarm");
+  const eventsFile = path55.join(eventsDir, "events.jsonl");
+  await fs53.mkdir(eventsDir, { recursive: true });
+  await fs53.appendFile(eventsFile, JSON.stringify(event) + "\n", "utf-8");
 }
 function createEventId() {
   return `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -27112,12 +27198,12 @@ function createEventId() {
 
 // src/swarm/knowledge.ts
 async function appendKnowledge(projectPath, entry) {
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const knowledgeDir = path54.join(projectPath, ".coco", "swarm");
-  const knowledgeFile = path54.join(knowledgeDir, "knowledge.jsonl");
-  await fs52.mkdir(knowledgeDir, { recursive: true });
-  await fs52.appendFile(knowledgeFile, JSON.stringify(entry) + "\n", "utf-8");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const knowledgeDir = path55.join(projectPath, ".coco", "swarm");
+  const knowledgeFile = path55.join(knowledgeDir, "knowledge.jsonl");
+  await fs53.mkdir(knowledgeDir, { recursive: true });
+  await fs53.appendFile(knowledgeFile, JSON.stringify(entry) + "\n", "utf-8");
 }
 
 // src/swarm/agents/prompts.ts
@@ -27421,11 +27507,11 @@ async function runSwarmLifecycle(options) {
 }
 async function stageInit(ctx) {
   const { projectPath, spec } = ctx.options;
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  await fs52.mkdir(path54.join(projectPath, ".coco", "swarm"), { recursive: true });
-  await fs52.mkdir(ctx.options.outputPath, { recursive: true });
-  const specSummaryPath = path54.join(projectPath, ".coco", "swarm", "spec-summary.json");
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  await fs53.mkdir(path55.join(projectPath, ".coco", "swarm"), { recursive: true });
+  await fs53.mkdir(ctx.options.outputPath, { recursive: true });
+  const specSummaryPath = path55.join(projectPath, ".coco", "swarm", "spec-summary.json");
   const specSummary = {
     projectName: spec.projectName,
     description: spec.description,
@@ -27439,7 +27525,7 @@ async function stageInit(ctx) {
     })),
     qualityConfig: spec.qualityConfig
   };
-  await fs52.writeFile(specSummaryPath, JSON.stringify(specSummary, null, 2), "utf-8");
+  await fs53.writeFile(specSummaryPath, JSON.stringify(specSummary, null, 2), "utf-8");
   await emitEvent(projectPath, {
     agentRole: "pm",
     agentTurn: 0,
@@ -27496,10 +27582,10 @@ async function stagePlan(ctx) {
     })
   ]);
   await createBoard(projectPath, spec);
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
-  const planPath = path54.join(projectPath, ".coco", "swarm", "plan.json");
-  await fs52.writeFile(
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
+  const planPath = path55.join(projectPath, ".coco", "swarm", "plan.json");
+  await fs53.writeFile(
     planPath,
     JSON.stringify({ pm: pmResult, architect: archResult, bestPractices: bpResult }, null, 2),
     "utf-8"
@@ -27714,8 +27800,8 @@ async function stageIntegrate(ctx) {
 }
 async function stageOutput(ctx) {
   const { projectPath, outputPath } = ctx.options;
-  const fs52 = await import('fs/promises');
-  const path54 = await import('path');
+  const fs53 = await import('fs/promises');
+  const path55 = await import('path');
   const board = await loadBoard(projectPath);
   const featureResults = Array.from(ctx.featureResults.values());
   const summary = {
@@ -27729,9 +27815,9 @@ async function stageOutput(ctx) {
     },
     globalScore: computeGlobalScore(featureResults)
   };
-  await fs52.mkdir(outputPath, { recursive: true });
-  const summaryPath = path54.join(outputPath, "swarm-summary.json");
-  await fs52.writeFile(summaryPath, JSON.stringify(summary, null, 2), "utf-8");
+  await fs53.mkdir(outputPath, { recursive: true });
+  const summaryPath = path55.join(outputPath, "swarm-summary.json");
+  await fs53.writeFile(summaryPath, JSON.stringify(summary, null, 2), "utf-8");
   const passed = summary.globalScore >= ctx.options.minScore;
   await emitGate(projectPath, "global-score", passed, `Global score: ${summary.globalScore}`);
   await emitEvent(projectPath, {
@@ -28077,8 +28163,8 @@ var SwarmOrchestrator = class {
       noQuestions = false,
       onProgress
     } = options;
-    const path54 = await import('path');
-    const projectPath = path54.dirname(path54.resolve(specFile));
+    const path55 = await import('path');
+    const projectPath = path55.dirname(path55.resolve(specFile));
     onProgress?.("init", `Parsing spec file: ${specFile}`);
     const spec = await parseSwarmSpec(specFile);
     onProgress?.("init", `Initializing provider: ${providerType}`);
@@ -28089,7 +28175,7 @@ var SwarmOrchestrator = class {
     await runSwarmLifecycle({
       spec,
       projectPath,
-      outputPath: path54.resolve(outputPath),
+      outputPath: path55.resolve(outputPath),
       provider,
       agentConfig,
       minScore,
@@ -29589,15 +29675,15 @@ async function saveConfiguration(result) {
 }
 async function saveEnvVars(filePath, vars, createDir = false) {
   if (createDir) {
-    const dir = path34.dirname(filePath);
+    const dir = path35.dirname(filePath);
     try {
-      await fs32.mkdir(dir, { recursive: true, mode: 448 });
+      await fs33.mkdir(dir, { recursive: true, mode: 448 });
     } catch {
     }
   }
   let existingVars = {};
   try {
-    const content = await fs32.readFile(filePath, "utf-8");
+    const content = await fs33.readFile(filePath, "utf-8");
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
       if (trimmed && !trimmed.startsWith("#")) {
@@ -29620,7 +29706,7 @@ async function saveEnvVars(filePath, vars, createDir = false) {
   for (const [key, value] of Object.entries(allVars)) {
     lines.push(`${key}=${value}`);
   }
-  await fs32.writeFile(filePath, lines.join("\n") + "\n", { mode: 384 });
+  await fs33.writeFile(filePath, lines.join("\n") + "\n", { mode: 384 });
 }
 async function handleLocalProviderUnavailable(providerType, config) {
   const cfg = LOCAL_PROVIDER_CONFIG[providerType];
@@ -30727,8 +30813,8 @@ async function listTrustedProjects2(trustStore) {
   p25.log.message("");
   for (const project of projects) {
     const level = project.approvalLevel.toUpperCase().padEnd(5);
-    const path54 = project.path.length > 50 ? "..." + project.path.slice(-47) : project.path;
-    p25.log.message(`  [${level}] ${path54}`);
+    const path55 = project.path.length > 50 ? "..." + project.path.slice(-47) : project.path;
+    p25.log.message(`  [${level}] ${path55}`);
     p25.log.message(`      Last accessed: ${new Date(project.lastAccessed).toLocaleString()}`);
   }
   p25.log.message("");
@@ -30966,8 +31052,8 @@ var buildCommand = {
 };
 async function loadBacklog(projectPath) {
   try {
-    const backlogPath = path34.join(projectPath, ".coco", "planning", "backlog.json");
-    const content = await fs32.readFile(backlogPath, "utf-8");
+    const backlogPath = path35.join(projectPath, ".coco", "planning", "backlog.json");
+    const content = await fs33.readFile(backlogPath, "utf-8");
     const data = JSON.parse(content);
     return data.backlog;
   } catch {
@@ -30976,25 +31062,25 @@ async function loadBacklog(projectPath) {
 }
 async function loadSprint(projectPath, sprintId) {
   try {
-    const sprintsDir = path34.join(projectPath, ".coco", "planning", "sprints");
-    const files = await fs32.readdir(sprintsDir);
+    const sprintsDir = path35.join(projectPath, ".coco", "planning", "sprints");
+    const files = await fs33.readdir(sprintsDir);
     const jsonFiles = files.filter((f) => f.endsWith(".json"));
     if (jsonFiles.length === 0) return null;
     const targetFile = sprintId ? jsonFiles.find((f) => f.includes(sprintId)) : jsonFiles[0];
     if (!targetFile) return null;
-    const sprintPath = path34.join(sprintsDir, targetFile);
-    const content = await fs32.readFile(sprintPath, "utf-8");
+    const sprintPath = path35.join(sprintsDir, targetFile);
+    const content = await fs33.readFile(sprintPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
 async function saveBacklog(projectPath, backlog) {
-  const backlogPath = path34.join(projectPath, ".coco", "planning", "backlog.json");
-  const content = await fs32.readFile(backlogPath, "utf-8");
+  const backlogPath = path35.join(projectPath, ".coco", "planning", "backlog.json");
+  const content = await fs33.readFile(backlogPath, "utf-8");
   const data = JSON.parse(content);
   data.backlog = backlog;
-  await fs32.writeFile(backlogPath, JSON.stringify(data, null, 2), "utf-8");
+  await fs33.writeFile(backlogPath, JSON.stringify(data, null, 2), "utf-8");
 }
 function getStatusEmoji(status) {
   const emojis = {
@@ -31905,7 +31991,7 @@ async function getCheckpoint(session, checkpointId) {
   return store.checkpoints.find((cp) => cp.id === checkpointId) ?? null;
 }
 async function restoreFiles(checkpoint, excludeFiles) {
-  const fs52 = await import('fs/promises');
+  const fs53 = await import('fs/promises');
   const restored = [];
   const failed = [];
   for (const fileCheckpoint of checkpoint.files) {
@@ -31913,7 +31999,7 @@ async function restoreFiles(checkpoint, excludeFiles) {
       continue;
     }
     try {
-      await fs52.writeFile(fileCheckpoint.filePath, fileCheckpoint.originalContent, "utf-8");
+      await fs53.writeFile(fileCheckpoint.filePath, fileCheckpoint.originalContent, "utf-8");
       restored.push(fileCheckpoint.filePath);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
@@ -31995,8 +32081,8 @@ function displayRewindResult(result) {
     const fileName = filePath.split("/").pop() ?? filePath;
     console.log(`${chalk25.green(String.fromCodePoint(10003))} Restored: ${fileName}`);
   }
-  for (const { path: path54, error } of result.filesFailed) {
-    const fileName = path54.split("/").pop() ?? path54;
+  for (const { path: path55, error } of result.filesFailed) {
+    const fileName = path55.split("/").pop() ?? path55;
     console.log(`${chalk25.red(String.fromCodePoint(10007))} Failed: ${fileName} (${error})`);
   }
   if (result.conversationRestored) {
@@ -32634,8 +32720,8 @@ var NPM_REGISTRY_URL = "https://registry.npmjs.org/@corbat-tech/coco/latest";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 5e3;
 var STARTUP_TIMEOUT_MS = 5500;
-var CACHE_DIR = path34__default.join(os4__default.homedir(), ".coco");
-var CACHE_FILE = path34__default.join(CACHE_DIR, "version-check-cache.json");
+var CACHE_DIR = path35__default.join(os4__default.homedir(), ".coco");
+var CACHE_FILE = path35__default.join(CACHE_DIR, "version-check-cache.json");
 function compareVersions(a, b) {
   const partsA = a.replace(/^v/, "").split(".").map((p45) => Number(p45.replace(/-.*$/, "")));
   const partsB = b.replace(/^v/, "").split(".").map((p45) => Number(p45.replace(/-.*$/, "")));
@@ -33488,8 +33574,8 @@ function formatToolSummary(toolName, input) {
     case "grep":
     case "search_files": {
       const pattern = String(input.pattern || "");
-      const path54 = input.path ? ` in ${input.path}` : "";
-      return `"${pattern}"${path54}`;
+      const path55 = input.path ? ` in ${input.path}` : "";
+      return `"${pattern}"${path55}`;
     }
     case "bash_exec": {
       const cmd = String(input.command || "");
@@ -33703,7 +33789,7 @@ async function readClipboardImage() {
   return null;
 }
 async function readClipboardImageMacOS() {
-  const tmpFile = path34.join(os4.tmpdir(), `coco-clipboard-${Date.now()}.png`);
+  const tmpFile = path35.join(os4.tmpdir(), `coco-clipboard-${Date.now()}.png`);
   try {
     const script = `
 set theFile to POSIX file "${tmpFile}"
@@ -33724,7 +33810,7 @@ end try
     if (!result.startsWith("ok")) {
       return null;
     }
-    const buffer = await fs32.readFile(tmpFile);
+    const buffer = await fs33.readFile(tmpFile);
     return {
       data: buffer.toString("base64"),
       media_type: "image/png"
@@ -33733,7 +33819,7 @@ end try
     return null;
   } finally {
     try {
-      await fs32.unlink(tmpFile);
+      await fs33.unlink(tmpFile);
     } catch {
     }
   }
@@ -33759,7 +33845,7 @@ async function readClipboardImageLinux() {
   }
 }
 async function readClipboardImageWindows() {
-  const tmpFile = path34.join(os4.tmpdir(), `coco-clipboard-${Date.now()}.png`);
+  const tmpFile = path35.join(os4.tmpdir(), `coco-clipboard-${Date.now()}.png`);
   try {
     const escapedPath = tmpFile.replace(/'/g, "''");
     const script = `
@@ -33777,7 +33863,7 @@ if ($img -ne $null) {
       timeout: 1e4
     }).trim();
     if (result !== "ok") return null;
-    const buffer = await fs32.readFile(tmpFile);
+    const buffer = await fs33.readFile(tmpFile);
     return {
       data: buffer.toString("base64"),
       media_type: "image/png"
@@ -33786,7 +33872,7 @@ if ($img -ne $null) {
     return null;
   } finally {
     try {
-      await fs32.unlink(tmpFile);
+      await fs33.unlink(tmpFile);
     } catch {
     }
   }
@@ -33874,9 +33960,9 @@ var allowPathCommand = {
   }
 };
 async function addPath(dirPath, session) {
-  const absolute = path34__default.resolve(dirPath);
+  const absolute = path35__default.resolve(dirPath);
   try {
-    const stat2 = await fs32__default.stat(absolute);
+    const stat2 = await fs33__default.stat(absolute);
     if (!stat2.isDirectory()) {
       p25.log.error(`Not a directory: ${absolute}`);
       return;
@@ -33886,19 +33972,19 @@ async function addPath(dirPath, session) {
     return;
   }
   for (const blocked of BLOCKED_SYSTEM_PATHS) {
-    const normalizedBlocked = path34__default.normalize(blocked);
-    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path34__default.sep)) {
+    const normalizedBlocked = path35__default.normalize(blocked);
+    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path35__default.sep)) {
       p25.log.error(`System path '${blocked}' cannot be allowed`);
       return;
     }
   }
-  const normalizedCwd = path34__default.normalize(session.projectPath);
-  if (absolute === normalizedCwd || absolute.startsWith(normalizedCwd + path34__default.sep)) {
+  const normalizedCwd = path35__default.normalize(session.projectPath);
+  if (absolute === normalizedCwd || absolute.startsWith(normalizedCwd + path35__default.sep)) {
     p25.log.info("That path is already within the project directory");
     return;
   }
   const existing = getAllowedPaths();
-  if (existing.some((e) => path34__default.normalize(e.path) === path34__default.normalize(absolute))) {
+  if (existing.some((e) => path35__default.normalize(e.path) === path35__default.normalize(absolute))) {
     p25.log.info(`Already allowed: ${absolute}`);
     return;
   }
@@ -33969,7 +34055,7 @@ async function revokePath(dirPath, _session) {
     }
     dirPath = selected;
   }
-  const absolute = path34__default.resolve(dirPath);
+  const absolute = path35__default.resolve(dirPath);
   const removed = removeAllowedPathFromSession(absolute);
   await removePersistedAllowedPath(absolute);
   if (removed) {
@@ -34322,7 +34408,7 @@ var RECOMMENDED_DENY = [
 ];
 async function loadPermissionPreferences() {
   try {
-    const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+    const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
     const config = JSON.parse(content);
     return {
       recommendedAllowlistApplied: config.recommendedAllowlistApplied,
@@ -34336,13 +34422,13 @@ async function savePermissionPreference(key, value) {
   try {
     let config = {};
     try {
-      const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+      const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
       config = JSON.parse(content);
     } catch {
     }
     config[key] = value;
-    await fs32__default.mkdir(path34__default.dirname(CONFIG_PATHS.config), { recursive: true });
-    await fs32__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2), "utf-8");
+    await fs33__default.mkdir(path35__default.dirname(CONFIG_PATHS.config), { recursive: true });
+    await fs33__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2), "utf-8");
   } catch {
   }
 }
@@ -34576,7 +34662,7 @@ async function resetPermissions(session) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
-    await fs32__default.writeFile(CONFIG_PATHS.trustedTools, JSON.stringify(emptySettings, null, 2), "utf-8");
+    await fs33__default.writeFile(CONFIG_PATHS.trustedTools, JSON.stringify(emptySettings, null, 2), "utf-8");
   } catch {
   }
   await savePermissionPreference("recommendedAllowlistApplied", false);
@@ -34658,7 +34744,7 @@ function formatQualityResult(result) {
 }
 async function loadQualityLoopPreference() {
   try {
-    const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+    const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
     const config = JSON.parse(content);
     const value = config.qualityLoop ?? config.cocoMode;
     if (typeof value === "boolean") {
@@ -34673,12 +34759,12 @@ async function saveQualityLoopPreference(enabled) {
   try {
     let config = {};
     try {
-      const content = await fs32__default.readFile(CONFIG_PATHS.config, "utf-8");
+      const content = await fs33__default.readFile(CONFIG_PATHS.config, "utf-8");
       config = JSON.parse(content);
     } catch {
     }
     config.qualityLoop = enabled;
-    await fs32__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
+    await fs33__default.writeFile(CONFIG_PATHS.config, JSON.stringify(config, null, 2) + "\n");
   } catch {
   }
 }
@@ -35514,9 +35600,9 @@ Response format (JSON only, no prose):
       cancel5("Build cancelled.");
     }
   }
-  const cocoDir = path34__default.join(outputPath, ".coco");
-  await fs32__default.mkdir(cocoDir, { recursive: true });
-  await fs32__default.writeFile(path34__default.join(cocoDir, "backlog.json"), JSON.stringify(spec, null, 2), "utf-8");
+  const cocoDir = path35__default.join(outputPath, ".coco");
+  await fs33__default.mkdir(cocoDir, { recursive: true });
+  await fs33__default.writeFile(path35__default.join(cocoDir, "backlog.json"), JSON.stringify(spec, null, 2), "utf-8");
   p25.outro("  Spec saved \u2014 starting sprints");
   return spec;
 }
@@ -36066,8 +36152,8 @@ init_errors();
 init_subprocess_registry();
 async function detectTestFramework2(cwd) {
   try {
-    const pkgPath = path34__default.join(cwd, "package.json");
-    const pkgContent = await fs32__default.readFile(pkgPath, "utf-8");
+    const pkgPath = path35__default.join(cwd, "package.json");
+    const pkgContent = await fs33__default.readFile(pkgPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     const deps = {
       ...pkg.dependencies,
@@ -36155,8 +36241,9 @@ Examples:
         duration
       );
     } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
       throw new ToolError(
-        `Test execution failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Test execution failed: ${msg}. Use command_exists to verify the test framework is installed, or run_script with a custom command.`,
         { tool: "run_tests", cause: error instanceof Error ? error : void 0 }
       );
     }
@@ -36247,13 +36334,13 @@ Examples:
     const projectDir = cwd ?? process.cwd();
     try {
       const coverageLocations = [
-        path34__default.join(projectDir, "coverage", "coverage-summary.json"),
-        path34__default.join(projectDir, "coverage", "coverage-final.json"),
-        path34__default.join(projectDir, ".nyc_output", "coverage-summary.json")
+        path35__default.join(projectDir, "coverage", "coverage-summary.json"),
+        path35__default.join(projectDir, "coverage", "coverage-final.json"),
+        path35__default.join(projectDir, ".nyc_output", "coverage-summary.json")
       ];
       for (const location of coverageLocations) {
         try {
-          const content = await fs32__default.readFile(location, "utf-8");
+          const content = await fs33__default.readFile(location, "utf-8");
           const coverage = JSON.parse(content);
           if (coverage.total) {
             return {
@@ -36272,8 +36359,9 @@ Examples:
       });
     } catch (error) {
       if (error instanceof ToolError) throw error;
+      const msg = error instanceof Error ? error.message : String(error);
       throw new ToolError(
-        `Failed to read coverage: ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to read coverage: ${msg}. Run run_tests with coverage: true first to generate coverage data.`,
         { tool: "get_coverage", cause: error instanceof Error ? error : void 0 }
       );
     }
@@ -36311,6 +36399,61 @@ init_registry4();
 init_registry4();
 init_errors();
 init_allowed_paths();
+
+// src/utils/file-suggestions.ts
+init_matcher();
+var MAX_DIR_ENTRIES = 200;
+var MAX_SUGGESTIONS = 5;
+async function suggestSimilarFiles(missingPath, options) {
+  const absPath = path35__default.resolve(missingPath);
+  const dir = path35__default.dirname(absPath);
+  const target = path35__default.basename(absPath);
+  const maxResults = MAX_SUGGESTIONS;
+  try {
+    const entries = await fs33__default.readdir(dir);
+    const limited = entries.slice(0, MAX_DIR_ENTRIES);
+    const scored = limited.map((name) => ({
+      path: path35__default.join(dir, name),
+      distance: levenshtein(target.toLowerCase(), name.toLowerCase())
+    })).filter((s) => s.distance <= Math.max(target.length * 0.6, 3)).sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, maxResults);
+  } catch {
+    return [];
+  }
+}
+async function suggestSimilarPaths(missingPath, options) {
+  const fileSuggestions = await suggestSimilarFiles(missingPath);
+  if (fileSuggestions.length > 0) return fileSuggestions;
+  const absPath = path35__default.resolve(missingPath);
+  const grandparent = path35__default.dirname(path35__default.dirname(absPath));
+  const parentBasename = path35__default.basename(path35__default.dirname(absPath));
+  const maxResults = MAX_SUGGESTIONS;
+  try {
+    const entries = await fs33__default.readdir(grandparent, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).slice(0, MAX_DIR_ENTRIES);
+    const scored = dirs.map((d) => ({
+      path: path35__default.join(grandparent, d.name),
+      distance: levenshtein(parentBasename.toLowerCase(), d.name.toLowerCase())
+    })).filter((s) => s.distance <= Math.max(parentBasename.length * 0.6, 3)).sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, maxResults);
+  } catch {
+    return [];
+  }
+}
+function formatSuggestions(suggestions, baseDir) {
+  if (suggestions.length === 0) return "";
+  const base = baseDir ?? process.cwd();
+  const lines = suggestions.map((s) => {
+    const rel = path35__default.relative(base, s.path);
+    return `  - ${rel}`;
+  });
+  return `
+Did you mean?
+${lines.join("\n")}`;
+}
+
+// src/tools/file.ts
+init_matcher();
 var SENSITIVE_PATTERNS = [
   /\.env(?:\.\w+)?$/,
   // .env, .env.local, etc.
@@ -36335,7 +36478,7 @@ function hasNullByte2(str) {
 }
 function normalizePath2(filePath) {
   let normalized = filePath.replace(/\0/g, "");
-  normalized = path34__default.normalize(normalized);
+  normalized = path35__default.normalize(normalized);
   return normalized;
 }
 function isPathAllowed(filePath, operation) {
@@ -36343,31 +36486,31 @@ function isPathAllowed(filePath, operation) {
     return { allowed: false, reason: "Path contains invalid characters" };
   }
   const normalized = normalizePath2(filePath);
-  const absolute = path34__default.resolve(normalized);
+  const absolute = path35__default.resolve(normalized);
   const cwd = process.cwd();
   for (const blocked of BLOCKED_PATHS2) {
-    const normalizedBlocked = path34__default.normalize(blocked);
-    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path34__default.sep)) {
+    const normalizedBlocked = path35__default.normalize(blocked);
+    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path35__default.sep)) {
       return { allowed: false, reason: `Access to system path '${blocked}' is not allowed` };
     }
   }
   const home = process.env.HOME;
   if (home) {
-    const normalizedHome = path34__default.normalize(home);
-    const normalizedCwd = path34__default.normalize(cwd);
+    const normalizedHome = path35__default.normalize(home);
+    const normalizedCwd = path35__default.normalize(cwd);
     if (absolute.startsWith(normalizedHome) && !absolute.startsWith(normalizedCwd)) {
       if (isWithinAllowedPath(absolute, operation)) ; else if (operation === "read") {
         const allowedHomeReads = [".gitconfig", ".zshrc", ".bashrc"];
-        const basename4 = path34__default.basename(absolute);
+        const basename4 = path35__default.basename(absolute);
         if (!allowedHomeReads.includes(basename4)) {
-          const targetDir = path34__default.dirname(absolute);
+          const targetDir = path35__default.dirname(absolute);
           return {
             allowed: false,
             reason: `Reading files outside project directory is not allowed. Use /allow-path ${targetDir} to grant access.`
           };
         }
       } else {
-        const targetDir = path34__default.dirname(absolute);
+        const targetDir = path35__default.dirname(absolute);
         return {
           allowed: false,
           reason: `${operation} operations outside project directory are not allowed. Use /allow-path ${targetDir} to grant access.`
@@ -36376,7 +36519,7 @@ function isPathAllowed(filePath, operation) {
     }
   }
   if (operation === "write" || operation === "delete") {
-    const basename4 = path34__default.basename(absolute);
+    const basename4 = path35__default.basename(absolute);
     for (const pattern of SENSITIVE_PATTERNS) {
       if (pattern.test(basename4)) {
         return {
@@ -36395,6 +36538,24 @@ function validatePath(filePath, operation) {
   }
 }
 var DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+function isENOENT(error) {
+  return error.code === "ENOENT";
+}
+async function enrichENOENT(filePath, operation) {
+  const absPath = path35__default.resolve(filePath);
+  const suggestions = await suggestSimilarFiles(absPath);
+  const hint = formatSuggestions(suggestions, path35__default.dirname(absPath));
+  const action = operation === "read" ? "Use glob or list_dir to find the correct path." : "Check that the parent directory exists.";
+  return `File not found: ${filePath}${hint}
+${action}`;
+}
+async function enrichDirENOENT(dirPath) {
+  const absPath = path35__default.resolve(dirPath);
+  const suggestions = await suggestSimilarPaths(absPath);
+  const hint = formatSuggestions(suggestions, path35__default.dirname(absPath));
+  return `Directory not found: ${dirPath}${hint}
+Use list_dir or glob to find the correct path.`;
+}
 var readFileTool = defineTool({
   name: "read_file",
   description: `Read the contents of a file.
@@ -36412,13 +36573,13 @@ Examples:
   async execute({ path: filePath, encoding, maxSize }) {
     validatePath(filePath, "read");
     try {
-      const absolutePath = path34__default.resolve(filePath);
-      const stats = await fs32__default.stat(absolutePath);
+      const absolutePath = path35__default.resolve(filePath);
+      const stats = await fs33__default.stat(absolutePath);
       const maxBytes = maxSize ?? DEFAULT_MAX_FILE_SIZE;
       let truncated = false;
       let content;
       if (stats.size > maxBytes) {
-        const handle = await fs32__default.open(absolutePath, "r");
+        const handle = await fs33__default.open(absolutePath, "r");
         try {
           const buffer = Buffer.alloc(maxBytes);
           await handle.read(buffer, 0, maxBytes, 0);
@@ -36428,7 +36589,7 @@ Examples:
           await handle.close();
         }
       } else {
-        content = await fs32__default.readFile(absolutePath, encoding);
+        content = await fs33__default.readFile(absolutePath, encoding);
       }
       return {
         content,
@@ -36437,6 +36598,14 @@ Examples:
         truncated
       };
     } catch (error) {
+      if (isENOENT(error)) {
+        const enriched = await enrichENOENT(filePath, "read");
+        throw new FileSystemError(enriched, {
+          path: filePath,
+          operation: "read",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to read file: ${filePath}`, {
         path: filePath,
         operation: "read",
@@ -36463,10 +36632,10 @@ Examples:
   async execute({ path: filePath, content, createDirs, dryRun }) {
     validatePath(filePath, "write");
     try {
-      const absolutePath = path34__default.resolve(filePath);
+      const absolutePath = path35__default.resolve(filePath);
       let wouldCreate = false;
       try {
-        await fs32__default.access(absolutePath);
+        await fs33__default.access(absolutePath);
       } catch {
         wouldCreate = true;
       }
@@ -36479,10 +36648,10 @@ Examples:
         };
       }
       if (createDirs) {
-        await fs32__default.mkdir(path34__default.dirname(absolutePath), { recursive: true });
+        await fs33__default.mkdir(path35__default.dirname(absolutePath), { recursive: true });
       }
-      await fs32__default.writeFile(absolutePath, content, "utf-8");
-      const stats = await fs32__default.stat(absolutePath);
+      await fs33__default.writeFile(absolutePath, content, "utf-8");
+      const stats = await fs33__default.stat(absolutePath);
       return {
         path: absolutePath,
         size: stats.size,
@@ -36490,6 +36659,14 @@ Examples:
         wouldCreate
       };
     } catch (error) {
+      if (isENOENT(error)) {
+        const enriched = await enrichENOENT(filePath, "write");
+        throw new FileSystemError(enriched, {
+          path: filePath,
+          operation: "write",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to write file: ${filePath}`, {
         path: filePath,
         operation: "write",
@@ -36517,8 +36694,8 @@ Examples:
   async execute({ path: filePath, oldText, newText, all, dryRun }) {
     validatePath(filePath, "write");
     try {
-      const absolutePath = path34__default.resolve(filePath);
-      let content = await fs32__default.readFile(absolutePath, "utf-8");
+      const absolutePath = path35__default.resolve(filePath);
+      let content = await fs33__default.readFile(absolutePath, "utf-8");
       let replacements = 0;
       if (all) {
         const regex = new RegExp(escapeRegex(oldText), "g");
@@ -36532,7 +36709,31 @@ Examples:
         }
       }
       if (replacements === 0) {
-        throw new Error(`Text not found in file: "${oldText.slice(0, 50)}..."`);
+        const lines = content.split("\n");
+        const searchLine = (oldText.split("\n")[0] ?? oldText).trim().slice(0, 80);
+        let bestIdx = -1;
+        let bestDist = Infinity;
+        for (let i = 0; i < lines.length; i++) {
+          const dist = levenshtein(lines[i].trim().slice(0, 80), searchLine);
+          if (dist < bestDist) {
+            bestDist = dist;
+            bestIdx = i;
+          }
+        }
+        let context = "";
+        if (bestIdx >= 0 && bestDist < searchLine.length * 0.6) {
+          const start = Math.max(0, bestIdx - 2);
+          const end = Math.min(lines.length, bestIdx + 3);
+          const snippet = lines.slice(start, end).map((l, i) => `  ${start + i + 1}: ${l}`).join("\n");
+          context = `
+
+Closest match near line ${bestIdx + 1}:
+${snippet}`;
+        }
+        throw new Error(
+          `Text not found in file: "${oldText.slice(0, 50)}..."${context}
+Hint: Use read_file first to verify the exact content.`
+        );
       }
       if (dryRun) {
         const preview = content.length > 500 ? content.slice(0, 500) + "..." : content;
@@ -36543,7 +36744,7 @@ Examples:
           preview
         };
       }
-      await fs32__default.writeFile(absolutePath, content, "utf-8");
+      await fs33__default.writeFile(absolutePath, content, "utf-8");
       return {
         path: absolutePath,
         replacements,
@@ -36584,6 +36785,14 @@ Examples:
         count: files.length
       };
     } catch (error) {
+      if (isENOENT(error) && cwd) {
+        const enriched = await enrichDirENOENT(cwd);
+        throw new FileSystemError(`Glob search failed \u2014 ${enriched}`, {
+          path: cwd,
+          operation: "glob",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Glob search failed: ${pattern}`, {
         path: cwd ?? process.cwd(),
         operation: "glob",
@@ -36606,8 +36815,8 @@ Examples:
   }),
   async execute({ path: filePath }) {
     try {
-      const absolutePath = path34__default.resolve(filePath);
-      const stats = await fs32__default.stat(absolutePath);
+      const absolutePath = path35__default.resolve(filePath);
+      const stats = await fs33__default.stat(absolutePath);
       return {
         exists: true,
         isFile: stats.isFile(),
@@ -36637,12 +36846,12 @@ Examples:
   }),
   async execute({ path: dirPath, recursive }) {
     try {
-      const absolutePath = path34__default.resolve(dirPath);
+      const absolutePath = path35__default.resolve(dirPath);
       const entries = [];
       async function listDir(dir, prefix = "") {
-        const items = await fs32__default.readdir(dir, { withFileTypes: true });
+        const items = await fs33__default.readdir(dir, { withFileTypes: true });
         for (const item of items) {
-          const fullPath = path34__default.join(dir, item.name);
+          const fullPath = path35__default.join(dir, item.name);
           const relativePath = prefix ? `${prefix}/${item.name}` : item.name;
           if (item.isDirectory()) {
             entries.push({ name: relativePath, type: "directory" });
@@ -36650,7 +36859,7 @@ Examples:
               await listDir(fullPath, relativePath);
             }
           } else if (item.isFile()) {
-            const stats = await fs32__default.stat(fullPath);
+            const stats = await fs33__default.stat(fullPath);
             entries.push({ name: relativePath, type: "file", size: stats.size });
           }
         }
@@ -36658,6 +36867,14 @@ Examples:
       await listDir(absolutePath);
       return { entries };
     } catch (error) {
+      if (isENOENT(error)) {
+        const enriched = await enrichDirENOENT(dirPath);
+        throw new FileSystemError(enriched, {
+          path: dirPath,
+          operation: "read",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to list directory: ${dirPath}`, {
         path: dirPath,
         operation: "read",
@@ -36689,23 +36906,23 @@ Examples:
     }
     validatePath(filePath, "delete");
     try {
-      const absolutePath = path34__default.resolve(filePath);
-      const stats = await fs32__default.stat(absolutePath);
+      const absolutePath = path35__default.resolve(filePath);
+      const stats = await fs33__default.stat(absolutePath);
       if (stats.isDirectory()) {
         if (!recursive) {
           throw new ToolError("Cannot delete directory without recursive: true", {
             tool: "delete_file"
           });
         }
-        await fs32__default.rm(absolutePath, { recursive: true });
+        await fs33__default.rm(absolutePath, { recursive: true });
       } else {
-        await fs32__default.unlink(absolutePath);
+        await fs33__default.unlink(absolutePath);
       }
       return { deleted: true, path: absolutePath };
     } catch (error) {
       if (error instanceof ToolError) throw error;
       if (error.code === "ENOENT") {
-        return { deleted: false, path: path34__default.resolve(filePath) };
+        return { deleted: false, path: path35__default.resolve(filePath) };
       }
       throw new FileSystemError(`Failed to delete: ${filePath}`, {
         path: filePath,
@@ -36733,11 +36950,11 @@ Examples:
     validatePath(source, "read");
     validatePath(destination, "write");
     try {
-      const srcPath = path34__default.resolve(source);
-      const destPath = path34__default.resolve(destination);
+      const srcPath = path35__default.resolve(source);
+      const destPath = path35__default.resolve(destination);
       if (!overwrite) {
         try {
-          await fs32__default.access(destPath);
+          await fs33__default.access(destPath);
           throw new ToolError(
             `Destination already exists: ${destination}. Use overwrite: true to replace.`,
             {
@@ -36750,9 +36967,9 @@ Examples:
           }
         }
       }
-      await fs32__default.mkdir(path34__default.dirname(destPath), { recursive: true });
-      await fs32__default.copyFile(srcPath, destPath);
-      const stats = await fs32__default.stat(destPath);
+      await fs33__default.mkdir(path35__default.dirname(destPath), { recursive: true });
+      await fs33__default.copyFile(srcPath, destPath);
+      const stats = await fs33__default.stat(destPath);
       return {
         source: srcPath,
         destination: destPath,
@@ -36760,6 +36977,14 @@ Examples:
       };
     } catch (error) {
       if (error instanceof ToolError) throw error;
+      if (isENOENT(error)) {
+        const enriched = await enrichENOENT(source, "read");
+        throw new FileSystemError(`Failed to copy \u2014 ${enriched}`, {
+          path: source,
+          operation: "read",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to copy file: ${source} -> ${destination}`, {
         path: source,
         operation: "read",
@@ -36786,11 +37011,11 @@ Examples:
     validatePath(source, "delete");
     validatePath(destination, "write");
     try {
-      const srcPath = path34__default.resolve(source);
-      const destPath = path34__default.resolve(destination);
+      const srcPath = path35__default.resolve(source);
+      const destPath = path35__default.resolve(destination);
       if (!overwrite) {
         try {
-          await fs32__default.access(destPath);
+          await fs33__default.access(destPath);
           throw new ToolError(
             `Destination already exists: ${destination}. Use overwrite: true to replace.`,
             {
@@ -36803,14 +37028,22 @@ Examples:
           }
         }
       }
-      await fs32__default.mkdir(path34__default.dirname(destPath), { recursive: true });
-      await fs32__default.rename(srcPath, destPath);
+      await fs33__default.mkdir(path35__default.dirname(destPath), { recursive: true });
+      await fs33__default.rename(srcPath, destPath);
       return {
         source: srcPath,
         destination: destPath
       };
     } catch (error) {
       if (error instanceof ToolError) throw error;
+      if (isENOENT(error)) {
+        const enriched = await enrichENOENT(source, "read");
+        throw new FileSystemError(`Failed to move \u2014 ${enriched}`, {
+          path: source,
+          operation: "write",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to move file: ${source} -> ${destination}`, {
         path: source,
         operation: "write",
@@ -36838,13 +37071,13 @@ Examples:
   }),
   async execute({ path: dirPath, depth, showHidden, dirsOnly }) {
     try {
-      const absolutePath = path34__default.resolve(dirPath ?? ".");
+      const absolutePath = path35__default.resolve(dirPath ?? ".");
       let totalFiles = 0;
       let totalDirs = 0;
-      const lines = [path34__default.basename(absolutePath) + "/"];
+      const lines = [path35__default.basename(absolutePath) + "/"];
       async function buildTree(dir, prefix, currentDepth) {
         if (currentDepth > (depth ?? 4)) return;
-        let items = await fs32__default.readdir(dir, { withFileTypes: true });
+        let items = await fs33__default.readdir(dir, { withFileTypes: true });
         if (!showHidden) {
           items = items.filter((item) => !item.name.startsWith("."));
         }
@@ -36864,7 +37097,7 @@ Examples:
           if (item.isDirectory()) {
             totalDirs++;
             lines.push(`${prefix}${connector}${item.name}/`);
-            await buildTree(path34__default.join(dir, item.name), prefix + childPrefix, currentDepth + 1);
+            await buildTree(path35__default.join(dir, item.name), prefix + childPrefix, currentDepth + 1);
           } else {
             totalFiles++;
             lines.push(`${prefix}${connector}${item.name}`);
@@ -36878,6 +37111,14 @@ Examples:
         totalDirs
       };
     } catch (error) {
+      if (isENOENT(error)) {
+        const enriched = await enrichDirENOENT(dirPath ?? ".");
+        throw new FileSystemError(enriched, {
+          path: dirPath ?? ".",
+          operation: "read",
+          cause: error instanceof Error ? error : void 0
+        });
+      }
       throw new FileSystemError(`Failed to generate tree: ${dirPath}`, {
         path: dirPath ?? ".",
         operation: "read",
@@ -37185,7 +37426,7 @@ Examples:
     caseSensitive,
     wholeWord
   }) {
-    const targetPath = searchPath ? path34__default.resolve(searchPath) : process.cwd();
+    const targetPath = searchPath ? path35__default.resolve(searchPath) : process.cwd();
     const matches = [];
     let filesSearched = 0;
     const filesWithMatches = /* @__PURE__ */ new Set();
@@ -37207,7 +37448,7 @@ Examples:
           tool: "grep"
         });
       }
-      const stats = await fs32__default.stat(targetPath);
+      const stats = await fs33__default.stat(targetPath);
       let filesToSearch;
       if (stats.isFile()) {
         filesToSearch = [targetPath];
@@ -37229,7 +37470,7 @@ Examples:
         }
         filesSearched++;
         try {
-          const content = await fs32__default.readFile(file, "utf-8");
+          const content = await fs33__default.readFile(file, "utf-8");
           const lines = content.split("\n");
           let fileHasMatch = false;
           for (let i = 0; i < lines.length; i++) {
@@ -37252,7 +37493,7 @@ Examples:
                 contextAfter.push(lines[j] ?? "");
               }
               matches.push({
-                file: path34__default.relative(process.cwd(), file),
+                file: path35__default.relative(process.cwd(), file),
                 line: i + 1,
                 column: match.index + 1,
                 content: line,
@@ -37303,8 +37544,8 @@ Examples:
   }),
   async execute({ file, pattern, caseSensitive }) {
     try {
-      const absolutePath = path34__default.resolve(file);
-      const content = await fs32__default.readFile(absolutePath, "utf-8");
+      const absolutePath = path35__default.resolve(file);
+      const content = await fs33__default.readFile(absolutePath, "utf-8");
       const lines = content.split("\n");
       const matches = [];
       const flags = caseSensitive ? "" : "i";
@@ -37320,6 +37561,11 @@ Examples:
       }
       return { matches, count: matches.length };
     } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new ToolError(`File not found: ${file}. Use glob to find the correct path.`, {
+          tool: "find_in_file"
+        });
+      }
       throw new ToolError(
         `Find in file failed: ${error instanceof Error ? error.message : String(error)}`,
         { tool: "find_in_file", cause: error instanceof Error ? error : void 0 }
@@ -37480,6 +37726,22 @@ init_registry4();
 init_errors();
 var DEFAULT_TIMEOUT_MS3 = 6e5;
 var MAX_OUTPUT_SIZE2 = 2 * 1024 * 1024;
+function getBuildHint(stderr, tool) {
+  if (/MODULE_NOT_FOUND|Cannot find module/i.test(stderr))
+    return "A dependency is missing. Run install_deps first.";
+  if (/ENOENT|no such file/i.test(stderr))
+    return "A file or directory was not found. Use glob or list_dir to verify paths.";
+  if (/EACCES|permission denied/i.test(stderr)) return "Permission denied. Check file permissions.";
+  if (/SyntaxError|Unexpected token/i.test(stderr))
+    return "Syntax error in the code. Use read_file to check the problematic file.";
+  if (/TS\d{4}:/i.test(stderr))
+    return "TypeScript compilation error. Read the error details above and use edit_file to fix.";
+  if (/ERR!/i.test(stderr) && tool === "install_deps")
+    return "Package install failed. Check if the package name is correct or if there are network issues.";
+  if (/No Makefile/i.test(stderr) || /No rule to make target/i.test(stderr))
+    return "Makefile target not found. Check available targets with 'make -n' or list_dir.";
+  return `${tool} failed. Check stderr output above for details.`;
+}
 async function detectPackageManager2(cwd) {
   const lockfiles = [
     { file: "pnpm-lock.yaml", pm: "pnpm" },
@@ -37489,7 +37751,7 @@ async function detectPackageManager2(cwd) {
   ];
   for (const { file, pm } of lockfiles) {
     try {
-      await fs32__default.access(path34__default.join(cwd, file));
+      await fs33__default.access(path35__default.join(cwd, file));
       return pm;
     } catch {
     }
@@ -37572,7 +37834,7 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult2 = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
@@ -37580,6 +37842,10 @@ ${message}
         duration: performance.now() - startTime,
         packageManager: pm
       };
+      if (!buildResult2.success) {
+        buildResult2.hint = getBuildHint(stderrBuffer || stdoutBuffer, "run_script");
+      }
+      return buildResult2;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`Script '${script}' timed out after ${timeoutMs}ms`, {
@@ -37693,7 +37959,7 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult2 = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
@@ -37701,6 +37967,10 @@ ${message}
         duration: performance.now() - startTime,
         packageManager: pm
       };
+      if (!buildResult2.success) {
+        buildResult2.hint = getBuildHint(stderrBuffer || stdoutBuffer, "install_deps");
+      }
+      return buildResult2;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`Install timed out after ${timeoutMs}ms`, {
@@ -37754,7 +38024,7 @@ ${message}
     });
     try {
       try {
-        await fs32__default.access(path34__default.join(projectDir, "Makefile"));
+        await fs33__default.access(path35__default.join(projectDir, "Makefile"));
       } catch {
         throw new ToolError("No Makefile found in directory", { tool: "make" });
       }
@@ -37791,13 +38061,17 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult2 = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
         exitCode: result.exitCode ?? 0,
         duration: performance.now() - startTime
       };
+      if (!buildResult2.success) {
+        buildResult2.hint = getBuildHint(stderrBuffer || stdoutBuffer, "make");
+      }
+      return buildResult2;
     } catch (error) {
       if (error instanceof ToolError) throw error;
       if (error.timedOut) {
@@ -37890,13 +38164,17 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult2 = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
         exitCode: result.exitCode ?? 0,
         duration: performance.now() - startTime
       };
+      if (!buildResult2.success) {
+        buildResult2.hint = getBuildHint(stderrBuffer || stdoutBuffer, "tsc");
+      }
+      return buildResult2;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`TypeScript compile timed out after ${timeoutMs}ms`, {
@@ -38099,9 +38377,10 @@ async function searchDuckDuckGo(query, maxResults, timeout) {
     });
     clearTimeout(timeoutId);
     if (!response.ok) {
-      throw new ToolError(`DuckDuckGo search failed with status ${response.status}`, {
-        tool: "web_search"
-      });
+      throw new ToolError(
+        `DuckDuckGo search failed with status ${response.status}. Try a different search engine (brave, serpapi) or simplify the query.`,
+        { tool: "web_search" }
+      );
     }
     const html = await response.text();
     return parseDuckDuckGoResults(html, maxResults);
@@ -38132,9 +38411,10 @@ async function searchBrave(query, maxResults, timeout) {
     });
     clearTimeout(timeoutId);
     if (!response.ok) {
-      throw new ToolError(`Brave search failed with status ${response.status}`, {
-        tool: "web_search"
-      });
+      throw new ToolError(
+        `Brave search failed with status ${response.status}. Try a different search engine (duckduckgo, serpapi) or check your BRAVE_SEARCH_API_KEY.`,
+        { tool: "web_search" }
+      );
     }
     const data = await response.json();
     return (data.web?.results ?? []).slice(0, maxResults).map((r) => ({
@@ -38168,9 +38448,10 @@ async function searchSerpApi(query, maxResults, timeout) {
     });
     clearTimeout(timeoutId);
     if (!response.ok) {
-      throw new ToolError(`SerpAPI search failed with status ${response.status}`, {
-        tool: "web_search"
-      });
+      throw new ToolError(
+        `SerpAPI search failed with status ${response.status}. Try a different search engine (duckduckgo, brave) or check your SERPAPI_KEY.`,
+        { tool: "web_search" }
+      );
     }
     const data = await response.json();
     return (data.organic_results ?? []).slice(0, maxResults).map((r) => ({
@@ -38260,6 +38541,27 @@ var PRIVATE_IP_PATTERNS = [
   /^https?:\/\/0\.0\.0\.0/,
   /^https?:\/\/\[::1\]/
 ];
+function getHttpErrorHint(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "\nThis page requires authentication. Try using web_search to find a publicly accessible alternative.";
+    case 404:
+      return "\nPage not found. The URL may be outdated or misspelled. Try web_search to find the correct URL.";
+    case 429:
+      return "\nRate limited. Wait a moment before retrying, or try an alternative source.";
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return "\nServer error (temporary). Try again in a moment, or use web_search to find an alternative source.";
+    default:
+      if (status >= 400 && status < 500) {
+        return "\nClient error. Check the URL is correct or try web_search to find the right page.";
+      }
+      return "";
+  }
+}
 function validateUrl(url) {
   for (const scheme of BLOCKED_SCHEMES) {
     if (url.toLowerCase().startsWith(scheme)) {
@@ -38478,7 +38780,8 @@ Examples:
       });
       clearTimeout(timeoutId);
       if (!response.ok) {
-        throw new ToolError(`HTTP ${response.status}: ${response.statusText}`, {
+        const hint = getHttpErrorHint(response.status);
+        throw new ToolError(`HTTP ${response.status}: ${response.statusText} \u2014 ${url}${hint}`, {
           tool: "web_fetch"
         });
       }
@@ -38568,8 +38871,8 @@ init_review();
 // src/tools/codebase-map.ts
 init_registry4();
 init_errors();
-var fs35 = await import('fs/promises');
-var path37 = await import('path');
+var fs36 = await import('fs/promises');
+var path38 = await import('path');
 var { glob: glob14 } = await import('glob');
 var DEFAULT_MAX_FILES = 200;
 var LANGUAGE_EXTENSIONS = {
@@ -38595,7 +38898,7 @@ var DEFAULT_EXCLUDES = [
   "**/*.d.ts"
 ];
 function detectLanguage3(filePath) {
-  const ext = path37.extname(filePath).toLowerCase();
+  const ext = path38.extname(filePath).toLowerCase();
   for (const [lang, extensions] of Object.entries(LANGUAGE_EXTENSIONS)) {
     if (extensions.includes(ext)) return lang;
   }
@@ -39004,9 +39307,9 @@ Examples:
   }),
   async execute({ path: rootPath, include, exclude, languages, maxFiles, depth }) {
     const startTime = performance.now();
-    const absPath = path37.resolve(rootPath);
+    const absPath = path38.resolve(rootPath);
     try {
-      const stat2 = await fs35.stat(absPath);
+      const stat2 = await fs36.stat(absPath);
       if (!stat2.isDirectory()) {
         throw new ToolError(`Path is not a directory: ${absPath}`, {
           tool: "codebase_map"
@@ -39043,14 +39346,14 @@ Examples:
     let totalDefinitions = 0;
     let exportedSymbols = 0;
     for (const file of limitedFiles) {
-      const fullPath = path37.join(absPath, file);
+      const fullPath = path38.join(absPath, file);
       const language = detectLanguage3(file);
       if (!language) continue;
       if (languages && !languages.includes(language)) {
         continue;
       }
       try {
-        const content = await fs35.readFile(fullPath, "utf-8");
+        const content = await fs36.readFile(fullPath, "utf-8");
         const lineCount = content.split("\n").length;
         const parsed = parseFile(content, language);
         const definitions = depth === "overview" ? parsed.definitions.filter((d) => d.exported) : parsed.definitions;
@@ -39087,23 +39390,23 @@ var codebaseMapTools = [codebaseMapTool];
 init_registry4();
 init_errors();
 init_paths();
-var fs36 = await import('fs/promises');
-var path38 = await import('path');
+var fs37 = await import('fs/promises');
+var path39 = await import('path');
 var crypto2 = await import('crypto');
-var GLOBAL_MEMORIES_DIR = path38.join(COCO_HOME, "memories");
+var GLOBAL_MEMORIES_DIR = path39.join(COCO_HOME, "memories");
 var PROJECT_MEMORIES_DIR = ".coco/memories";
 var DEFAULT_MAX_MEMORIES = 1e3;
 async function ensureDir2(dirPath) {
-  await fs36.mkdir(dirPath, { recursive: true });
+  await fs37.mkdir(dirPath, { recursive: true });
 }
 function getMemoriesDir(scope) {
   return scope === "global" ? GLOBAL_MEMORIES_DIR : PROJECT_MEMORIES_DIR;
 }
 async function loadIndex(scope) {
   const dir = getMemoriesDir(scope);
-  const indexPath = path38.join(dir, "index.json");
+  const indexPath = path39.join(dir, "index.json");
   try {
-    const content = await fs36.readFile(indexPath, "utf-8");
+    const content = await fs37.readFile(indexPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return [];
@@ -39112,14 +39415,14 @@ async function loadIndex(scope) {
 async function saveIndex(scope, index) {
   const dir = getMemoriesDir(scope);
   await ensureDir2(dir);
-  const indexPath = path38.join(dir, "index.json");
-  await fs36.writeFile(indexPath, JSON.stringify(index, null, 2), "utf-8");
+  const indexPath = path39.join(dir, "index.json");
+  await fs37.writeFile(indexPath, JSON.stringify(index, null, 2), "utf-8");
 }
 async function loadMemory(scope, id) {
   const dir = getMemoriesDir(scope);
-  const memPath = path38.join(dir, `${id}.json`);
+  const memPath = path39.join(dir, `${id}.json`);
   try {
-    const content = await fs36.readFile(memPath, "utf-8");
+    const content = await fs37.readFile(memPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -39128,8 +39431,8 @@ async function loadMemory(scope, id) {
 async function saveMemory(scope, memory) {
   const dir = getMemoriesDir(scope);
   await ensureDir2(dir);
-  const memPath = path38.join(dir, `${memory.id}.json`);
-  await fs36.writeFile(memPath, JSON.stringify(memory, null, 2), "utf-8");
+  const memPath = path39.join(dir, `${memory.id}.json`);
+  await fs37.writeFile(memPath, JSON.stringify(memory, null, 2), "utf-8");
 }
 var createMemoryTool = defineTool({
   name: "create_memory",
@@ -39285,17 +39588,17 @@ var memoryTools = [createMemoryTool, recallMemoryTool, listMemoriesTool];
 // src/tools/checkpoint.ts
 init_registry4();
 init_errors();
-var fs37 = await import('fs/promises');
+var fs38 = await import('fs/promises');
 var crypto3 = await import('crypto');
 var CHECKPOINT_FILE = ".coco/checkpoints.json";
 var DEFAULT_MAX_CHECKPOINTS = 50;
 var STASH_PREFIX = "coco-cp";
 async function ensureCocoDir() {
-  await fs37.mkdir(".coco", { recursive: true });
+  await fs38.mkdir(".coco", { recursive: true });
 }
 async function loadCheckpoints() {
   try {
-    const content = await fs37.readFile(CHECKPOINT_FILE, "utf-8");
+    const content = await fs38.readFile(CHECKPOINT_FILE, "utf-8");
     return JSON.parse(content);
   } catch {
     return [];
@@ -39303,7 +39606,7 @@ async function loadCheckpoints() {
 }
 async function saveCheckpoints(checkpoints) {
   await ensureCocoDir();
-  await fs37.writeFile(CHECKPOINT_FILE, JSON.stringify(checkpoints, null, 2), "utf-8");
+  await fs38.writeFile(CHECKPOINT_FILE, JSON.stringify(checkpoints, null, 2), "utf-8");
 }
 async function execGit(args) {
   const { execaCommand } = await import('execa');
@@ -39314,10 +39617,11 @@ async function execGit(args) {
     });
     return result.stdout;
   } catch (error) {
-    throw new ToolError(
-      `Git command failed: git ${args.join(" ")}: ${error instanceof Error ? error.message : String(error)}`,
-      { tool: "checkpoint" }
-    );
+    const msg = error instanceof Error ? error.message : String(error);
+    let hint = `Git command failed (${args[0] ?? "unknown"}): ${msg}`;
+    if (/not a git repository/i.test(msg))
+      hint = "Not a git repository. Checkpoints require a git repo \u2014 run git_init first.";
+    throw new ToolError(hint, { tool: "checkpoint" });
   }
 }
 async function getChangedFiles() {
@@ -39435,8 +39739,9 @@ Examples:
         message: `Restored checkpoint '${checkpoint.description}' (${checkpoint.fileCount} files)`
       };
     } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
       throw new ToolError(
-        `Failed to restore checkpoint: ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to restore checkpoint: ${msg}. Use list_checkpoints to see available checkpoints.`,
         { tool: "restore_checkpoint" }
       );
     }
@@ -39466,8 +39771,8 @@ var checkpointTools = [createCheckpointTool, restoreCheckpointTool, listCheckpoi
 
 // src/tools/semantic-search.ts
 init_registry4();
-var fs38 = await import('fs/promises');
-var path39 = await import('path');
+var fs39 = await import('fs/promises');
+var path40 = await import('path');
 var { glob: glob15 } = await import('glob');
 var INDEX_DIR = ".coco/search-index";
 var DEFAULT_CHUNK_SIZE = 20;
@@ -39573,6 +39878,7 @@ function simpleEmbedding(text13) {
   return vector;
 }
 var embedFn = null;
+var usingFallbackEmbedding = false;
 async function getEmbedding(text13) {
   if (!embedFn) {
     try {
@@ -39587,26 +39893,27 @@ async function getEmbedding(text13) {
       };
     } catch {
       embedFn = async (t) => simpleEmbedding(t);
+      usingFallbackEmbedding = true;
     }
   }
   return embedFn(text13);
 }
 async function loadIndex2(indexDir) {
   try {
-    const indexPath = path39.join(indexDir, "index.json");
-    const content = await fs38.readFile(indexPath, "utf-8");
+    const indexPath = path40.join(indexDir, "index.json");
+    const content = await fs39.readFile(indexPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
 async function saveIndex2(indexDir, index) {
-  await fs38.mkdir(indexDir, { recursive: true });
-  const indexPath = path39.join(indexDir, "index.json");
-  await fs38.writeFile(indexPath, JSON.stringify(index), "utf-8");
+  await fs39.mkdir(indexDir, { recursive: true });
+  const indexPath = path40.join(indexDir, "index.json");
+  await fs39.writeFile(indexPath, JSON.stringify(index), "utf-8");
 }
 function isBinary(filePath) {
-  return BINARY_EXTENSIONS.has(path39.extname(filePath).toLowerCase());
+  return BINARY_EXTENSIONS.has(path40.extname(filePath).toLowerCase());
 }
 var semanticSearchTool = defineTool({
   name: "semantic_search",
@@ -39631,9 +39938,10 @@ Examples:
     const effectivePath = rootPath ?? ".";
     const effectiveMaxResults = maxResults ?? 10;
     const effectiveThreshold = threshold ?? 0.3;
-    const absPath = path39.resolve(effectivePath);
-    const indexDir = path39.join(absPath, INDEX_DIR);
+    const absPath = path40.resolve(effectivePath);
+    const indexDir = path40.join(absPath, INDEX_DIR);
     let index = reindex ? null : await loadIndex2(indexDir);
+    let warnings = [];
     if (!index) {
       const pattern = include ?? "**/*";
       const files = await glob15(pattern, {
@@ -39643,12 +39951,14 @@ Examples:
         absolute: false
       });
       const chunks = [];
+      let skippedFiles = 0;
+      let indexSaveWarning = "";
       for (const file of files) {
         if (isBinary(file)) continue;
-        const fullPath = path39.join(absPath, file);
+        const fullPath = path40.join(absPath, file);
         try {
-          const stat2 = await fs38.stat(fullPath);
-          const content = await fs38.readFile(fullPath, "utf-8");
+          const stat2 = await fs39.stat(fullPath);
+          const content = await fs39.readFile(fullPath, "utf-8");
           if (content.length > 1e5) continue;
           const fileChunks = chunkContent(content, DEFAULT_CHUNK_SIZE);
           for (const chunk of fileChunks) {
@@ -39663,6 +39973,7 @@ Examples:
             });
           }
         } catch {
+          skippedFiles++;
           continue;
         }
       }
@@ -39675,6 +39986,18 @@ Examples:
       try {
         await saveIndex2(indexDir, index);
       } catch {
+        indexSaveWarning = "Index could not be saved to disk \u2014 next search will rebuild it.";
+      }
+      if (usingFallbackEmbedding) {
+        warnings.push(
+          "Using basic text matching (transformer model unavailable). Results may be less accurate."
+        );
+      }
+      if (skippedFiles > 0) {
+        warnings.push(`${skippedFiles} file(s) could not be read (binary or permission issues).`);
+      }
+      if (indexSaveWarning) {
+        warnings.push(indexSaveWarning);
       }
     }
     const queryVector = await getEmbedding(query);
@@ -39698,12 +40021,16 @@ Examples:
     const ageMs = Date.now() - indexDate.getTime();
     const ageMinutes = Math.round(ageMs / 6e4);
     const indexAge = ageMinutes < 60 ? `${ageMinutes}m ago` : `${Math.round(ageMinutes / 60)}h ago`;
-    return {
+    const output = {
       results,
       totalIndexed: index.chunks.length,
       indexAge,
       duration: performance.now() - startTime
     };
+    if (warnings.length > 0) {
+      output.warning = warnings.join(" ");
+    }
+    return output;
   }
 });
 var semanticSearchTools = [semanticSearchTool];
@@ -39711,8 +40038,8 @@ var semanticSearchTools = [semanticSearchTool];
 // src/tools/diagram.ts
 init_registry4();
 init_errors();
-var fs39 = await import('fs/promises');
-var path40 = await import('path');
+var fs40 = await import('fs/promises');
+var path41 = await import('path');
 var { glob: glob16 } = await import('glob');
 async function parseClassRelationships(rootPath, include) {
   const pattern = include ?? "**/*.{ts,tsx,js,jsx}";
@@ -39725,7 +40052,7 @@ async function parseClassRelationships(rootPath, include) {
   const interfaces = [];
   for (const file of files.slice(0, 100)) {
     try {
-      const content = await fs39.readFile(path40.join(rootPath, file), "utf-8");
+      const content = await fs40.readFile(path41.join(rootPath, file), "utf-8");
       const lines = content.split("\n");
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -39844,14 +40171,14 @@ async function generateClassDiagram(rootPath, include) {
   };
 }
 async function generateArchitectureDiagram(rootPath) {
-  const entries = await fs39.readdir(rootPath, { withFileTypes: true });
+  const entries = await fs40.readdir(rootPath, { withFileTypes: true });
   const dirs = entries.filter(
     (e) => e.isDirectory() && !e.name.startsWith(".") && !["node_modules", "dist", "build", "coverage", "__pycache__", "target"].includes(e.name)
   );
   const lines = ["graph TD"];
   let nodeCount = 0;
   let edgeCount = 0;
-  const rootName = path40.basename(rootPath);
+  const rootName = path41.basename(rootPath);
   lines.push(`  ROOT["${rootName}"]`);
   nodeCount++;
   for (const dir of dirs) {
@@ -39861,7 +40188,7 @@ async function generateArchitectureDiagram(rootPath) {
     nodeCount++;
     edgeCount++;
     try {
-      const subEntries = await fs39.readdir(path40.join(rootPath, dir.name), {
+      const subEntries = await fs40.readdir(path41.join(rootPath, dir.name), {
         withFileTypes: true
       });
       const subDirs = subEntries.filter(
@@ -39984,7 +40311,7 @@ Examples:
         tool: "generate_diagram"
       });
     }
-    const absPath = rootPath ? path40.resolve(rootPath) : process.cwd();
+    const absPath = rootPath ? path41.resolve(rootPath) : process.cwd();
     switch (type) {
       case "class":
         return generateClassDiagram(absPath, include);
@@ -40049,8 +40376,8 @@ var diagramTools = [generateDiagramTool];
 // src/tools/pdf.ts
 init_registry4();
 init_errors();
-var fs40 = await import('fs/promises');
-var path41 = await import('path');
+var fs41 = await import('fs/promises');
+var path42 = await import('path');
 var DEFAULT_MAX_PAGES = 20;
 var MAX_FILE_SIZE = 50 * 1024 * 1024;
 function parsePageRange(rangeStr, totalPages) {
@@ -40085,9 +40412,9 @@ Examples:
   }),
   async execute({ path: filePath, pages, maxPages }) {
     const startTime = performance.now();
-    const absPath = path41.resolve(filePath);
+    const absPath = path42.resolve(filePath);
     try {
-      const stat2 = await fs40.stat(absPath);
+      const stat2 = await fs41.stat(absPath);
       if (!stat2.isFile()) {
         throw new ToolError(`Path is not a file: ${absPath}`, {
           tool: "read_pdf"
@@ -40118,7 +40445,7 @@ Examples:
     }
     try {
       const pdfParse = await import('pdf-parse');
-      const dataBuffer = await fs40.readFile(absPath);
+      const dataBuffer = await fs41.readFile(absPath);
       const pdfData = await pdfParse.default(dataBuffer, {
         max: maxPages
       });
@@ -40156,8 +40483,9 @@ Examples:
           tool: "read_pdf"
         });
       }
+      const msg = error instanceof Error ? error.message : String(error);
       throw new ToolError(
-        `Failed to parse PDF: ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to parse PDF: ${msg}. The file may be encrypted, password-protected, or corrupted. Try opening it locally to verify.`,
         { tool: "read_pdf", cause: error instanceof Error ? error : void 0 }
       );
     }
@@ -40168,8 +40496,8 @@ var pdfTools = [readPdfTool];
 // src/tools/image.ts
 init_registry4();
 init_errors();
-var fs41 = await import('fs/promises');
-var path42 = await import('path');
+var fs42 = await import('fs/promises');
+var path43 = await import('path');
 var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"]);
 var MAX_IMAGE_SIZE = 20 * 1024 * 1024;
 var MIME_TYPES = {
@@ -40197,15 +40525,15 @@ Examples:
   async execute({ path: filePath, prompt, provider }) {
     const startTime = performance.now();
     const effectivePrompt = prompt ?? "Describe this image in detail. If it's code or a UI, identify the key elements.";
-    const absPath = path42.resolve(filePath);
+    const absPath = path43.resolve(filePath);
     const cwd = process.cwd();
-    if (!absPath.startsWith(cwd + path42.sep) && absPath !== cwd) {
+    if (!absPath.startsWith(cwd + path43.sep) && absPath !== cwd) {
       throw new ToolError(
         `Path traversal denied: '${filePath}' resolves outside the project directory`,
         { tool: "read_image" }
       );
     }
-    const ext = path42.extname(absPath).toLowerCase();
+    const ext = path43.extname(absPath).toLowerCase();
     if (!SUPPORTED_FORMATS.has(ext)) {
       throw new ToolError(
         `Unsupported image format '${ext}'. Supported: ${Array.from(SUPPORTED_FORMATS).join(", ")}`,
@@ -40213,7 +40541,7 @@ Examples:
       );
     }
     try {
-      const stat2 = await fs41.stat(absPath);
+      const stat2 = await fs42.stat(absPath);
       if (!stat2.isFile()) {
         throw new ToolError(`Path is not a file: ${absPath}`, {
           tool: "read_image"
@@ -40234,7 +40562,7 @@ Examples:
       if (error instanceof ToolError) throw error;
       throw error;
     }
-    const imageBuffer = await fs41.readFile(absPath);
+    const imageBuffer = await fs42.readFile(absPath);
     const base64 = imageBuffer.toString("base64");
     const mimeType = MIME_TYPES[ext] ?? "image/png";
     const selectedProvider = provider ?? "anthropic";
@@ -40326,10 +40654,15 @@ Examples:
     } catch (error) {
       if (error instanceof ToolError) throw error;
       if (error.message?.includes("Cannot find module") || error.message?.includes("MODULE_NOT_FOUND")) {
-        throw new ToolError(
-          `Provider SDK not installed for '${selectedProvider}'. Check your dependencies.`,
-          { tool: "read_image" }
-        );
+        const pkgMap = {
+          anthropic: "@anthropic-ai/sdk",
+          openai: "openai",
+          gemini: "@google/generative-ai"
+        };
+        const pkg = pkgMap[selectedProvider] ?? selectedProvider;
+        throw new ToolError(`Provider SDK not installed. Run: pnpm add ${pkg}`, {
+          tool: "read_image"
+        });
       }
       throw new ToolError(
         `Image analysis failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -40351,7 +40684,7 @@ var imageTools = [readImageTool];
 // src/tools/database.ts
 init_registry4();
 init_errors();
-var path43 = await import('path');
+var path44 = await import('path');
 var DANGEROUS_PATTERNS = [
   /\bDROP\s+(?:TABLE|DATABASE|INDEX|VIEW)\b/i,
   /\bTRUNCATE\b/i,
@@ -40382,7 +40715,7 @@ Examples:
   async execute({ database, query, params, readonly: isReadonlyParam }) {
     const isReadonly = isReadonlyParam ?? true;
     const startTime = performance.now();
-    const absPath = path43.resolve(database);
+    const absPath = path44.resolve(database);
     if (isReadonly && isDangerousSql(query)) {
       throw new ToolError(
         "Write operations (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE) are blocked in readonly mode. Set readonly: false to allow writes.",
@@ -40434,10 +40767,20 @@ Examples:
           { tool: "sql_query" }
         );
       }
-      throw new ToolError(
-        `SQL query failed: ${error instanceof Error ? error.message : String(error)}`,
-        { tool: "sql_query", cause: error instanceof Error ? error : void 0 }
-      );
+      const msg = error instanceof Error ? error.message : String(error);
+      let hint = `SQL query failed: ${msg}`;
+      if (/no such table/i.test(msg))
+        hint = `Table not found: ${msg}. Use inspect_schema to see available tables.`;
+      else if (/syntax error|near "/i.test(msg))
+        hint = `SQL syntax error: ${msg}. Check your query syntax.`;
+      else if (/SQLITE_BUSY|database is locked/i.test(msg))
+        hint = `Database is locked by another process. Wait and retry, or close other connections.`;
+      else if (/unable to open database/i.test(msg))
+        hint = `Cannot open database file. Use glob to verify the file path exists.`;
+      throw new ToolError(hint, {
+        tool: "sql_query",
+        cause: error instanceof Error ? error : void 0
+      });
     }
   }
 });
@@ -40455,7 +40798,7 @@ Examples:
   }),
   async execute({ database, table }) {
     const startTime = performance.now();
-    const absPath = path43.resolve(database);
+    const absPath = path44.resolve(database);
     try {
       const { default: Database } = await import('better-sqlite3');
       const db = new Database(absPath, { readonly: true, fileMustExist: true });
@@ -40500,10 +40843,16 @@ Examples:
           { tool: "inspect_schema" }
         );
       }
-      throw new ToolError(
-        `Schema inspection failed: ${error instanceof Error ? error.message : String(error)}`,
-        { tool: "inspect_schema", cause: error instanceof Error ? error : void 0 }
-      );
+      const msg = error instanceof Error ? error.message : String(error);
+      let hint = `Schema inspection failed: ${msg}`;
+      if (/unable to open database/i.test(msg))
+        hint = `Cannot open database file. Use glob to verify the file path exists.`;
+      else if (/no such table/i.test(msg))
+        hint = `Table '${table ?? ""}' not found. Run inspect_schema without a table name to list all tables.`;
+      throw new ToolError(hint, {
+        tool: "inspect_schema",
+        cause: error instanceof Error ? error : void 0
+      });
     }
   }
 });
@@ -40632,14 +40981,14 @@ var astValidatorTools = [validateCodeTool, findMissingImportsTool];
 
 // src/tools/code-analyzer.ts
 init_registry4();
-var fs42 = await import('fs/promises');
-var path44 = await import('path');
+var fs43 = await import('fs/promises');
+var path45 = await import('path');
 var AnalyzeFileSchema = z.object({
   filePath: z.string().describe("Path to file to analyze"),
   includeAst: z.boolean().default(false).describe("Include AST in result")
 });
 async function analyzeFile(filePath, includeAst = false) {
-  const content = await fs42.readFile(filePath, "utf-8");
+  const content = await fs43.readFile(filePath, "utf-8");
   const lines = content.split("\n").length;
   const functions = [];
   const classes = [];
@@ -40743,10 +41092,10 @@ async function analyzeDirectory(dirPath) {
     try {
       const analysis = await analyzeFile(file, false);
       totalLines += analysis.lines;
-      const ext = path44.extname(file);
+      const ext = path45.extname(file);
       filesByType[ext] = (filesByType[ext] || 0) + 1;
       fileStats.push({
-        file: path44.relative(dirPath, file),
+        file: path45.relative(dirPath, file),
         lines: analysis.lines,
         complexity: analysis.complexity.cyclomatic
       });
@@ -41108,13 +41457,13 @@ var agentCoordinatorTools = [createAgentPlanTool, delegateTaskTool, aggregateRes
 
 // src/tools/smart-suggestions.ts
 init_registry4();
-var fs43 = await import('fs/promises');
+var fs44 = await import('fs/promises');
 var SuggestImprovementsSchema = z.object({
   filePath: z.string().describe("File to analyze for improvement suggestions"),
   context: z.string().optional().describe("Additional context about the code")
 });
 async function analyzeAndSuggest(filePath, _context) {
-  const content = await fs43.readFile(filePath, "utf-8");
+  const content = await fs44.readFile(filePath, "utf-8");
   const lines = content.split("\n");
   const suggestions = [];
   for (let i = 0; i < lines.length; i++) {
@@ -41206,7 +41555,7 @@ async function analyzeAndSuggest(filePath, _context) {
     if (filePath.endsWith(".ts") && !filePath.includes("test") && !filePath.includes(".d.ts") && line.includes("export ")) {
       const testPath = filePath.replace(".ts", ".test.ts");
       try {
-        await fs43.access(testPath);
+        await fs44.access(testPath);
       } catch {
         suggestions.push({
           type: "testing",
@@ -41263,7 +41612,7 @@ var calculateCodeScoreTool = defineTool({
   async execute(input) {
     const { filePath } = input;
     const suggestions = await analyzeAndSuggest(filePath);
-    const content = await fs43.readFile(filePath, "utf-8");
+    const content = await fs44.readFile(filePath, "utf-8");
     const lines = content.split("\n");
     const nonEmptyLines = lines.filter((l) => l.trim()).length;
     let score = 100;
@@ -41300,8 +41649,8 @@ var smartSuggestionsTools = [suggestImprovementsTool, calculateCodeScoreTool];
 
 // src/tools/context-enhancer.ts
 init_registry4();
-var fs44 = await import('fs/promises');
-var path45 = await import('path');
+var fs45 = await import('fs/promises');
+var path46 = await import('path');
 var ContextMemoryStore = class {
   items = /* @__PURE__ */ new Map();
   learnings = /* @__PURE__ */ new Map();
@@ -41313,7 +41662,7 @@ var ContextMemoryStore = class {
   }
   async load() {
     try {
-      const content = await fs44.readFile(this.storePath, "utf-8");
+      const content = await fs45.readFile(this.storePath, "utf-8");
       const data = JSON.parse(content);
       this.items = new Map(Object.entries(data.items || {}));
       this.learnings = new Map(Object.entries(data.learnings || {}));
@@ -41321,15 +41670,15 @@ var ContextMemoryStore = class {
     }
   }
   async save() {
-    const dir = path45.dirname(this.storePath);
-    await fs44.mkdir(dir, { recursive: true });
+    const dir = path46.dirname(this.storePath);
+    await fs45.mkdir(dir, { recursive: true });
     const data = {
       sessionId: this.sessionId,
       items: Object.fromEntries(this.items),
       learnings: Object.fromEntries(this.learnings),
       savedAt: Date.now()
     };
-    await fs44.writeFile(this.storePath, JSON.stringify(data, null, 2));
+    await fs45.writeFile(this.storePath, JSON.stringify(data, null, 2));
   }
   addContext(id, item) {
     this.items.set(id, item);
@@ -41497,11 +41846,11 @@ var contextEnhancerTools = [
 
 // src/tools/skill-enhancer.ts
 init_registry4();
-var fs45 = await import('fs/promises');
-var path46 = await import('path');
+var fs46 = await import('fs/promises');
+var path47 = await import('path');
 async function discoverSkills(skillsDir) {
   try {
-    const files = await fs45.readdir(skillsDir);
+    const files = await fs46.readdir(skillsDir);
     return files.filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
   } catch {
     return [];
@@ -41509,12 +41858,12 @@ async function discoverSkills(skillsDir) {
 }
 async function loadSkillMetadata(skillPath) {
   try {
-    const content = await fs45.readFile(skillPath, "utf-8");
+    const content = await fs46.readFile(skillPath, "utf-8");
     const nameMatch = content.match(/@name\s+(\S+)/);
     const descMatch = content.match(/@description\s+(.+)/);
     const versionMatch = content.match(/@version\s+(\S+)/);
     return {
-      name: nameMatch?.[1] || path46.basename(skillPath, path46.extname(skillPath)),
+      name: nameMatch?.[1] || path47.basename(skillPath, path47.extname(skillPath)),
       description: descMatch?.[1] || "No description",
       version: versionMatch?.[1] || "1.0.0",
       dependencies: []
@@ -41558,7 +41907,7 @@ var discoverSkillsTool = defineTool({
     const { skillsDir } = input;
     const skills = await discoverSkills(skillsDir);
     const metadata = await Promise.all(
-      skills.map((s) => loadSkillMetadata(path46.join(skillsDir, s)))
+      skills.map((s) => loadSkillMetadata(path47.join(skillsDir, s)))
     );
     return {
       skillsDir,
@@ -41729,7 +42078,7 @@ Examples:
     reason: z.string().optional().describe("Why access is needed (shown to user for context)")
   }),
   async execute({ path: dirPath, reason }) {
-    const absolute = path34__default.resolve(dirPath);
+    const absolute = path35__default.resolve(dirPath);
     if (isWithinAllowedPath(absolute, "read")) {
       return {
         authorized: true,
@@ -41738,8 +42087,8 @@ Examples:
       };
     }
     for (const blocked of BLOCKED_SYSTEM_PATHS2) {
-      const normalizedBlocked = path34__default.normalize(blocked);
-      if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path34__default.sep)) {
+      const normalizedBlocked = path35__default.normalize(blocked);
+      if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path35__default.sep)) {
         return {
           authorized: false,
           path: absolute,
@@ -41748,7 +42097,7 @@ Examples:
       }
     }
     const cwd = process.cwd();
-    if (absolute === path34__default.normalize(cwd) || absolute.startsWith(path34__default.normalize(cwd) + path34__default.sep)) {
+    if (absolute === path35__default.normalize(cwd) || absolute.startsWith(path35__default.normalize(cwd) + path35__default.sep)) {
       return {
         authorized: true,
         path: absolute,
@@ -41756,7 +42105,7 @@ Examples:
       };
     }
     try {
-      const stat2 = await fs32__default.stat(absolute);
+      const stat2 = await fs33__default.stat(absolute);
       if (!stat2.isDirectory()) {
         return {
           authorized: false,
@@ -41772,7 +42121,7 @@ Examples:
       };
     }
     const existing = getAllowedPaths();
-    if (existing.some((e) => path34__default.normalize(e.path) === path34__default.normalize(absolute))) {
+    if (existing.some((e) => path35__default.normalize(e.path) === path35__default.normalize(absolute))) {
       return {
         authorized: true,
         path: absolute,
@@ -41857,9 +42206,9 @@ async function runSprints(options) {
     Object.entries(AGENT_ROLES).map(([role, def]) => [role, { ...def, maxTurns: 20 }])
   );
   const coordinator = createAgentCoordinator(executor, agentDefsMap);
-  await fs32__default.mkdir(spec.outputPath, { recursive: true });
-  const sprintsDir = path34__default.join(spec.outputPath, ".coco", "sprints");
-  await fs32__default.mkdir(sprintsDir, { recursive: true });
+  await fs33__default.mkdir(spec.outputPath, { recursive: true });
+  const sprintsDir = path35__default.join(spec.outputPath, ".coco", "sprints");
+  await fs33__default.mkdir(sprintsDir, { recursive: true });
   for (const sprint of spec.sprints) {
     onProgress(`Starting ${sprint.id}: ${sprint.name}`);
     const sprintStart = Date.now();
@@ -42112,8 +42461,8 @@ Assess: overall architecture, consistency, error handling, and production readin
   };
 }
 async function saveSprintResult(sprintsDir, result) {
-  const filePath = path34__default.join(sprintsDir, `${result.sprintId}.json`);
-  await fs32__default.writeFile(filePath, JSON.stringify(result, null, 2), "utf-8");
+  const filePath = path35__default.join(sprintsDir, `${result.sprintId}.json`);
+  await fs33__default.writeFile(filePath, JSON.stringify(result, null, 2), "utf-8");
 }
 
 // src/cli/repl/commands/build-app.ts
@@ -42138,9 +42487,9 @@ function parseArgs5(args) {
   return { description, specFile, outputDir, skipConfirmation };
 }
 function isWithinRoot(resolvedPath, rootDir) {
-  const normalRoot = path34__default.normalize(rootDir) + path34__default.sep;
-  const normalPath = path34__default.normalize(resolvedPath);
-  return normalPath === path34__default.normalize(rootDir) || normalPath.startsWith(normalRoot);
+  const normalRoot = path35__default.normalize(rootDir) + path35__default.sep;
+  const normalPath = path35__default.normalize(resolvedPath);
+  return normalPath === path35__default.normalize(rootDir) || normalPath.startsWith(normalRoot);
 }
 var buildAppCommand = {
   name: "build-app",
@@ -42163,20 +42512,20 @@ var buildAppCommand = {
     }
     let initialDescription = parsed.description;
     if (parsed.specFile) {
-      const specPath = path34__default.resolve(session.projectPath, parsed.specFile);
+      const specPath = path35__default.resolve(session.projectPath, parsed.specFile);
       if (!isWithinRoot(specPath, session.projectPath)) {
         p25.log.error(`--spec path must be within the project directory: ${specPath}`);
         return false;
       }
       try {
-        initialDescription = await fs32__default.readFile(specPath, "utf-8");
+        initialDescription = await fs33__default.readFile(specPath, "utf-8");
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         p25.log.error(`Error reading spec file: ${msg}`);
         return false;
       }
     }
-    const outputPath = parsed.outputDir ? path34__default.resolve(session.projectPath, parsed.outputDir) : path34__default.join(session.projectPath, "build-app-output");
+    const outputPath = parsed.outputDir ? path35__default.resolve(session.projectPath, parsed.outputDir) : path35__default.join(session.projectPath, "build-app-output");
     if (parsed.outputDir && !isWithinRoot(outputPath, session.projectPath)) {
       p25.log.error(`--output path must be within the project directory: ${outputPath}`);
       return false;
@@ -42383,11 +42732,11 @@ function getAllCommands() {
 }
 
 // src/cli/repl/input/handler.ts
-var HISTORY_FILE = path34.join(os4.homedir(), ".coco", "history");
+var HISTORY_FILE = path35.join(os4.homedir(), ".coco", "history");
 function loadHistory() {
   try {
-    if (fs49.existsSync(HISTORY_FILE)) {
-      const content = fs49.readFileSync(HISTORY_FILE, "utf-8");
+    if (fs50.existsSync(HISTORY_FILE)) {
+      const content = fs50.readFileSync(HISTORY_FILE, "utf-8");
       return content.split("\n").filter(Boolean).slice(-500);
     }
   } catch {
@@ -42396,12 +42745,12 @@ function loadHistory() {
 }
 function saveHistory(history) {
   try {
-    const dir = path34.dirname(HISTORY_FILE);
-    if (!fs49.existsSync(dir)) {
-      fs49.mkdirSync(dir, { recursive: true });
+    const dir = path35.dirname(HISTORY_FILE);
+    if (!fs50.existsSync(dir)) {
+      fs50.mkdirSync(dir, { recursive: true });
     }
     const toSave = history.slice(-500);
-    fs49.writeFileSync(HISTORY_FILE, toSave.join("\n") + "\n");
+    fs50.writeFileSync(HISTORY_FILE, toSave.join("\n") + "\n");
   } catch {
   }
 }
@@ -43729,7 +44078,7 @@ function formatDiffPreview(toolCall) {
 }
 async function checkFileExists(filePath) {
   try {
-    await fs32__default.access(filePath);
+    await fs33__default.access(filePath);
     return true;
   } catch {
     return false;
@@ -44511,6 +44860,21 @@ async function executeAgentTurn(session, userMessage, provider, toolRegistry, op
       content: toolResults
     });
     if (stuckInErrorLoop) {
+      try {
+        const finalMessages = getConversationContext(session, toolRegistry);
+        for await (const chunk of provider.streamWithTools(finalMessages, {
+          tools: [],
+          maxTokens: session.config.provider.maxTokens
+        })) {
+          if (options.signal?.aborted) break;
+          if (chunk.type === "text" && chunk.text) {
+            finalContent += chunk.text;
+            options.onStream?.(chunk);
+          }
+          if (chunk.type === "done") break;
+        }
+      } catch {
+      }
       break;
     }
   }
@@ -45048,8 +45412,8 @@ function formatContextUsage(percent) {
 }
 function formatStatusBar(projectPath, config, gitCtx, contextUsagePercent) {
   const parts = [];
-  const projectName = path34__default.basename(projectPath);
-  parts.push(chalk25.dim("\u{1F4C1}") + chalk25.magenta(projectName));
+  const projectName = path35__default.basename(projectPath);
+  parts.push(chalk25.dim("\u{1F4C1} ") + chalk25.magenta(projectName));
   const providerName = config.provider.type;
   const modelName = config.provider.model || "default";
   parts.push(chalk25.dim(`${providerName}/`) + chalk25.cyan(modelName));