@corbat-tech/coco 2.7.0 → 2.8.1

package/dist/index.js

@@ -1,10 +1,10 @@
 import { homedir } from 'os';
-import * as path15 from 'path';
-import path15__default, { dirname, join, basename, resolve } from 'path';
+import * as path16 from 'path';
+import path16__default, { dirname, join, basename, resolve } from 'path';
 import * as fs4 from 'fs';
 import fs4__default, { readFileSync, constants } from 'fs';
-import * as fs14 from 'fs/promises';
-import fs14__default, { readFile, access, readdir } from 'fs/promises';
+import * as fs15 from 'fs/promises';
+import fs15__default, { readFile, access, readdir } from 'fs/promises';
 import chalk3 from 'chalk';
 import * as p3 from '@clack/prompts';
 import { fileURLToPath } from 'url';
@@ -23,6 +23,7 @@ import 'http';
 import { GoogleGenerativeAI, FunctionCallingMode } from '@google/generative-ai';
 import JSON5 from 'json5';
 import 'events';
+import 'minimatch';
 import { simpleGit } from 'simple-git';
 import hljs from 'highlight.js/lib/core';
 import bash from 'highlight.js/lib/languages/bash';
@@ -90,7 +91,7 @@ function loadGlobalCocoEnv() {
   try {
     const home = process.env.HOME || process.env.USERPROFILE || "";
     if (!home) return;
-    const globalEnvPath = path15.join(home, ".coco", ".env");
+    const globalEnvPath = path16.join(home, ".coco", ".env");
     const content = fs4.readFileSync(globalEnvPath, "utf-8");
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
@@ -255,10 +256,10 @@ function getAllowedPaths() {
   return [...sessionAllowedPaths];
 }
 function isWithinAllowedPath(absolutePath, operation) {
-  const normalizedTarget = path15__default.normalize(absolutePath);
+  const normalizedTarget = path16__default.normalize(absolutePath);
   for (const entry of sessionAllowedPaths) {
-    const normalizedAllowed = path15__default.normalize(entry.path);
-    if (normalizedTarget === normalizedAllowed || normalizedTarget.startsWith(normalizedAllowed + path15__default.sep)) {
+    const normalizedAllowed = path16__default.normalize(entry.path);
+    if (normalizedTarget === normalizedAllowed || normalizedTarget.startsWith(normalizedAllowed + path16__default.sep)) {
       if (operation === "read") return true;
       if (entry.level === "write") return true;
     }
@@ -266,8 +267,8 @@ function isWithinAllowedPath(absolutePath, operation) {
   return false;
 }
 function addAllowedPathToSession(dirPath, level) {
-  const absolute = path15__default.resolve(dirPath);
-  if (sessionAllowedPaths.some((e) => path15__default.normalize(e.path) === path15__default.normalize(absolute))) {
+  const absolute = path16__default.resolve(dirPath);
+  if (sessionAllowedPaths.some((e) => path16__default.normalize(e.path) === path16__default.normalize(absolute))) {
     return;
   }
   sessionAllowedPaths.push({
@@ -278,14 +279,14 @@ function addAllowedPathToSession(dirPath, level) {
 }
 async function persistAllowedPath(dirPath, level) {
   if (!currentProjectPath) return;
-  const absolute = path15__default.resolve(dirPath);
+  const absolute = path16__default.resolve(dirPath);
   const store = await loadStore();
   if (!store.projects[currentProjectPath]) {
     store.projects[currentProjectPath] = [];
   }
   const entries = store.projects[currentProjectPath];
-  const normalized = path15__default.normalize(absolute);
-  if (entries.some((e) => path15__default.normalize(e.path) === normalized)) {
+  const normalized = path16__default.normalize(absolute);
+  if (entries.some((e) => path16__default.normalize(e.path) === normalized)) {
     return;
   }
   entries.push({
@@ -297,7 +298,7 @@ async function persistAllowedPath(dirPath, level) {
 }
 async function loadStore() {
   try {
-    const content = await fs14__default.readFile(STORE_FILE, "utf-8");
+    const content = await fs15__default.readFile(STORE_FILE, "utf-8");
     return { ...DEFAULT_STORE, ...JSON.parse(content) };
   } catch {
     return { ...DEFAULT_STORE };
@@ -305,8 +306,8 @@ async function loadStore() {
 }
 async function saveStore(store) {
   try {
-    await fs14__default.mkdir(path15__default.dirname(STORE_FILE), { recursive: true });
-    await fs14__default.writeFile(STORE_FILE, JSON.stringify(store, null, 2), "utf-8");
+    await fs15__default.mkdir(path16__default.dirname(STORE_FILE), { recursive: true });
+    await fs15__default.writeFile(STORE_FILE, JSON.stringify(store, null, 2), "utf-8");
   } catch {
   }
 }
@@ -314,7 +315,7 @@ var STORE_FILE, DEFAULT_STORE, sessionAllowedPaths, currentProjectPath;
 var init_allowed_paths = __esm({
   "src/tools/allowed-paths.ts"() {
     init_paths();
-    STORE_FILE = path15__default.join(CONFIG_PATHS.home, "allowed-paths.json");
+    STORE_FILE = path16__default.join(CONFIG_PATHS.home, "allowed-paths.json");
     DEFAULT_STORE = {
       version: 1,
       projects: {}
@@ -395,7 +396,7 @@ __export(allow_path_prompt_exports, {
   promptAllowPath: () => promptAllowPath
 });
 async function promptAllowPath(dirPath) {
-  const absolute = path15__default.resolve(dirPath);
+  const absolute = path16__default.resolve(dirPath);
   console.log();
   console.log(chalk3.yellow("  \u26A0 Access denied \u2014 path is outside the project directory"));
   console.log(chalk3.dim(`  \u{1F4C1} ${absolute}`));
@@ -824,6 +825,9 @@ var TimeoutError = class extends CocoError {
     this.operation = options.operation;
   }
 };
+function isCocoError(error) {
+  return error instanceof CocoError;
+}
 function normalizeComplexity(value) {
   const normalized = value?.toLowerCase();
   if (normalized === "simple") return "simple";
@@ -1773,13 +1777,13 @@ function createSpecificationGenerator(llm, config) {
   return new SpecificationGenerator(llm, config);
 }
 function getPersistencePaths(projectPath) {
-  const baseDir = path15__default.join(projectPath, ".coco", "spec");
+  const baseDir = path16__default.join(projectPath, ".coco", "spec");
   return {
     baseDir,
-    sessionFile: path15__default.join(baseDir, "discovery-session.json"),
-    specFile: path15__default.join(baseDir, "spec.md"),
-    conversationLog: path15__default.join(baseDir, "conversation.jsonl"),
-    checkpointFile: path15__default.join(baseDir, "checkpoint.json")
+    sessionFile: path16__default.join(baseDir, "discovery-session.json"),
+    specFile: path16__default.join(baseDir, "spec.md"),
+    conversationLog: path16__default.join(baseDir, "conversation.jsonl"),
+    checkpointFile: path16__default.join(baseDir, "checkpoint.json")
   };
 }
 var SessionPersistence = class {
@@ -1792,7 +1796,7 @@ var SessionPersistence = class {
    */
   async ensureDir() {
     try {
-      await fs14__default.mkdir(this.paths.baseDir, { recursive: true });
+      await fs15__default.mkdir(this.paths.baseDir, { recursive: true });
     } catch {
       throw new FileSystemError(`Failed to create persistence directory: ${this.paths.baseDir}`, {
         path: this.paths.baseDir,
@@ -1807,7 +1811,7 @@ var SessionPersistence = class {
     await this.ensureDir();
     try {
       const data = JSON.stringify(session, null, 2);
-      await fs14__default.writeFile(this.paths.sessionFile, data, "utf-8");
+      await fs15__default.writeFile(this.paths.sessionFile, data, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save discovery session", {
         path: this.paths.sessionFile,
@@ -1820,7 +1824,7 @@ var SessionPersistence = class {
    */
   async loadSession() {
     try {
-      const data = await fs14__default.readFile(this.paths.sessionFile, "utf-8");
+      const data = await fs15__default.readFile(this.paths.sessionFile, "utf-8");
       const parsed = JSON.parse(data);
       parsed.startedAt = new Date(parsed.startedAt);
       parsed.updatedAt = new Date(parsed.updatedAt);
@@ -1846,7 +1850,7 @@ var SessionPersistence = class {
    */
   async hasSession() {
     try {
-      await fs14__default.access(this.paths.sessionFile);
+      await fs15__default.access(this.paths.sessionFile);
       return true;
     } catch {
       return false;
@@ -1857,7 +1861,7 @@ var SessionPersistence = class {
    */
   async deleteSession() {
     try {
-      await fs14__default.unlink(this.paths.sessionFile);
+      await fs15__default.unlink(this.paths.sessionFile);
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw new FileSystemError("Failed to delete discovery session", {
@@ -1873,7 +1877,7 @@ var SessionPersistence = class {
   async saveSpecification(content) {
     await this.ensureDir();
     try {
-      await fs14__default.writeFile(this.paths.specFile, content, "utf-8");
+      await fs15__default.writeFile(this.paths.specFile, content, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save specification", {
         path: this.paths.specFile,
@@ -1886,7 +1890,7 @@ var SessionPersistence = class {
    */
   async loadSpecification() {
     try {
-      return await fs14__default.readFile(this.paths.specFile, "utf-8");
+      return await fs15__default.readFile(this.paths.specFile, "utf-8");
     } catch {
       return null;
     }
@@ -1902,7 +1906,7 @@ var SessionPersistence = class {
       content
     };
     try {
-      await fs14__default.appendFile(this.paths.conversationLog, JSON.stringify(entry) + "\n", "utf-8");
+      await fs15__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,
@@ -1915,7 +1919,7 @@ var SessionPersistence = class {
    */
   async loadConversationLog() {
     try {
-      const data = await fs14__default.readFile(this.paths.conversationLog, "utf-8");
+      const data = await fs15__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 {
@@ -1929,7 +1933,7 @@ var SessionPersistence = class {
     await this.ensureDir();
     try {
       const data = JSON.stringify(checkpoint, null, 2);
-      await fs14__default.writeFile(this.paths.checkpointFile, data, "utf-8");
+      await fs15__default.writeFile(this.paths.checkpointFile, data, "utf-8");
     } catch {
       throw new FileSystemError("Failed to save checkpoint", {
         path: this.paths.checkpointFile,
@@ -1942,7 +1946,7 @@ var SessionPersistence = class {
    */
   async loadCheckpoint() {
     try {
-      const data = await fs14__default.readFile(this.paths.checkpointFile, "utf-8");
+      const data = await fs15__default.readFile(this.paths.checkpointFile, "utf-8");
       const parsed = JSON.parse(data);
       parsed.timestamp = new Date(parsed.timestamp);
       return parsed;
@@ -1955,7 +1959,7 @@ var SessionPersistence = class {
    */
   async clearAll() {
     try {
-      await fs14__default.rm(this.paths.baseDir, { recursive: true, force: true });
+      await fs15__default.rm(this.paths.baseDir, { recursive: true, force: true });
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw new FileSystemError("Failed to clear persistence data", {
@@ -3809,8 +3813,8 @@ var OrchestrateExecutor = class {
   }
   async loadSpecification(projectPath) {
     try {
-      const jsonPath = path15__default.join(projectPath, ".coco", "spec", "spec.json");
-      const jsonContent = await fs14__default.readFile(jsonPath, "utf-8");
+      const jsonPath = path16__default.join(projectPath, ".coco", "spec", "spec.json");
+      const jsonContent = await fs15__default.readFile(jsonPath, "utf-8");
       return JSON.parse(jsonContent);
     } catch {
       return this.createMinimalSpec(projectPath);
@@ -3821,7 +3825,7 @@ var OrchestrateExecutor = class {
       version: "1.0.0",
       generatedAt: /* @__PURE__ */ new Date(),
       overview: {
-        name: path15__default.basename(projectPath),
+        name: path16__default.basename(projectPath),
         description: "Project specification",
         goals: [],
         targetUsers: ["developers"],
@@ -3848,53 +3852,53 @@ var OrchestrateExecutor = class {
     };
   }
   async saveArchitecture(projectPath, architecture) {
-    const dir = path15__default.join(projectPath, ".coco", "architecture");
-    await fs14__default.mkdir(dir, { recursive: true });
-    const mdPath = path15__default.join(dir, "ARCHITECTURE.md");
-    await fs14__default.writeFile(mdPath, generateArchitectureMarkdown(architecture), "utf-8");
-    const jsonPath = path15__default.join(dir, "architecture.json");
-    await fs14__default.writeFile(jsonPath, JSON.stringify(architecture, null, 2), "utf-8");
+    const dir = path16__default.join(projectPath, ".coco", "architecture");
+    await fs15__default.mkdir(dir, { recursive: true });
+    const mdPath = path16__default.join(dir, "ARCHITECTURE.md");
+    await fs15__default.writeFile(mdPath, generateArchitectureMarkdown(architecture), "utf-8");
+    const jsonPath = path16__default.join(dir, "architecture.json");
+    await fs15__default.writeFile(jsonPath, JSON.stringify(architecture, null, 2), "utf-8");
     return mdPath;
   }
   async saveADRs(projectPath, adrs) {
-    const dir = path15__default.join(projectPath, ".coco", "architecture", "adrs");
-    await fs14__default.mkdir(dir, { recursive: true });
+    const dir = path16__default.join(projectPath, ".coco", "architecture", "adrs");
+    await fs15__default.mkdir(dir, { recursive: true });
     const paths = [];
-    const indexPath = path15__default.join(dir, "README.md");
-    await fs14__default.writeFile(indexPath, generateADRIndexMarkdown(adrs), "utf-8");
+    const indexPath = path16__default.join(dir, "README.md");
+    await fs15__default.writeFile(indexPath, generateADRIndexMarkdown(adrs), "utf-8");
     paths.push(indexPath);
     for (const adr of adrs) {
       const filename = getADRFilename(adr);
-      const adrPath = path15__default.join(dir, filename);
-      await fs14__default.writeFile(adrPath, generateADRMarkdown(adr), "utf-8");
+      const adrPath = path16__default.join(dir, filename);
+      await fs15__default.writeFile(adrPath, generateADRMarkdown(adr), "utf-8");
       paths.push(adrPath);
     }
     return paths;
   }
   async saveBacklog(projectPath, backlogResult) {
-    const dir = path15__default.join(projectPath, ".coco", "planning");
-    await fs14__default.mkdir(dir, { recursive: true });
-    const mdPath = path15__default.join(dir, "BACKLOG.md");
-    await fs14__default.writeFile(mdPath, generateBacklogMarkdown(backlogResult.backlog), "utf-8");
-    const jsonPath = path15__default.join(dir, "backlog.json");
-    await fs14__default.writeFile(jsonPath, JSON.stringify(backlogResult, null, 2), "utf-8");
+    const dir = path16__default.join(projectPath, ".coco", "planning");
+    await fs15__default.mkdir(dir, { recursive: true });
+    const mdPath = path16__default.join(dir, "BACKLOG.md");
+    await fs15__default.writeFile(mdPath, generateBacklogMarkdown(backlogResult.backlog), "utf-8");
+    const jsonPath = path16__default.join(dir, "backlog.json");
+    await fs15__default.writeFile(jsonPath, JSON.stringify(backlogResult, null, 2), "utf-8");
     return mdPath;
   }
   async saveSprint(projectPath, sprint, backlogResult) {
-    const dir = path15__default.join(projectPath, ".coco", "planning", "sprints");
-    await fs14__default.mkdir(dir, { recursive: true });
+    const dir = path16__default.join(projectPath, ".coco", "planning", "sprints");
+    await fs15__default.mkdir(dir, { recursive: true });
     const filename = `${sprint.id}.md`;
-    const sprintPath = path15__default.join(dir, filename);
-    await fs14__default.writeFile(sprintPath, generateSprintMarkdown(sprint, backlogResult.backlog), "utf-8");
-    const jsonPath = path15__default.join(dir, `${sprint.id}.json`);
-    await fs14__default.writeFile(jsonPath, JSON.stringify(sprint, null, 2), "utf-8");
+    const sprintPath = path16__default.join(dir, filename);
+    await fs15__default.writeFile(sprintPath, generateSprintMarkdown(sprint, backlogResult.backlog), "utf-8");
+    const jsonPath = path16__default.join(dir, `${sprint.id}.json`);
+    await fs15__default.writeFile(jsonPath, JSON.stringify(sprint, null, 2), "utf-8");
     return sprintPath;
   }
   async saveDiagram(projectPath, id, mermaid) {
-    const dir = path15__default.join(projectPath, ".coco", "architecture", "diagrams");
-    await fs14__default.mkdir(dir, { recursive: true });
-    const diagramPath = path15__default.join(dir, `${id}.mmd`);
-    await fs14__default.writeFile(diagramPath, mermaid, "utf-8");
+    const dir = path16__default.join(projectPath, ".coco", "architecture", "diagrams");
+    await fs15__default.mkdir(dir, { recursive: true });
+    const diagramPath = path16__default.join(dir, `${id}.mmd`);
+    await fs15__default.writeFile(diagramPath, mermaid, "utf-8");
     return diagramPath;
   }
 };
@@ -4049,10 +4053,10 @@ var CoverageAnalyzer = class {
       join(this.projectPath, ".coverage", "coverage-summary.json"),
       join(this.projectPath, "coverage", "lcov-report", "coverage-summary.json")
     ];
-    for (const path38 of possiblePaths) {
+    for (const path39 of possiblePaths) {
       try {
-        await access(path38, constants.R_OK);
-        const content = await readFile(path38, "utf-8");
+        await access(path39, constants.R_OK);
+        const content = await readFile(path39, "utf-8");
         const report = JSON.parse(content);
         return parseCoverageSummary(report);
       } catch {
@@ -4771,7 +4775,7 @@ var BuildVerifier = class {
   async verifyTypes() {
     const startTime = Date.now();
     try {
-      const hasTsConfig = await this.fileExists(path15.join(this.projectPath, "tsconfig.json"));
+      const hasTsConfig = await this.fileExists(path16.join(this.projectPath, "tsconfig.json"));
       if (!hasTsConfig) {
         return {
           success: true,
@@ -4821,8 +4825,8 @@ var BuildVerifier = class {
    */
   async detectBuildCommand() {
     try {
-      const packageJsonPath = path15.join(this.projectPath, "package.json");
-      const content = await fs14.readFile(packageJsonPath, "utf-8");
+      const packageJsonPath = path16.join(this.projectPath, "package.json");
+      const content = await fs15.readFile(packageJsonPath, "utf-8");
       const packageJson = JSON.parse(content);
       if (packageJson.scripts?.build) {
         return "npm run build";
@@ -4898,7 +4902,7 @@ var BuildVerifier = class {
    */
   async fileExists(filePath) {
     try {
-      await fs14.access(filePath);
+      await fs15.access(filePath);
       return true;
     } catch {
       return false;
@@ -6444,9 +6448,9 @@ function detectProjectLanguage(files) {
   return { language: dominant, confidence, evidence };
 }
 function getFileExtension(filePath) {
-  const base = path15.basename(filePath);
+  const base = path16.basename(filePath);
   if (base.endsWith(".d.ts")) return ".d.ts";
-  return path15.extname(filePath).toLowerCase();
+  return path16.extname(filePath).toLowerCase();
 }
 function buildEvidence(dominant, counts, totalSourceFiles, files) {
   const evidence = [];
@@ -6454,7 +6458,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) => path15.basename(f) === cfg)) {
+    if (files.some((f) => path16.basename(f) === cfg)) {
       evidence.push(`Found ${cfg}`);
     }
   }
@@ -8166,7 +8170,7 @@ function setupFileLogging(logger, logDir, name) {
   if (!fs4__default.existsSync(logDir)) {
     fs4__default.mkdirSync(logDir, { recursive: true });
   }
-  const logFile = path15__default.join(logDir, `${name}.log`);
+  const logFile = path16__default.join(logDir, `${name}.log`);
   logger.attachTransport((logObj) => {
     const line = JSON.stringify(logObj) + "\n";
     fs4__default.appendFileSync(logFile, line);
@@ -8190,6 +8194,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";
   }
@@ -8211,13 +8223,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 path38 = extractQuotedPath(msg);
-    return path38 ? `File or directory not found: ${path38}` : "File or directory not found";
+    const path39 = extractQuotedPath(msg);
+    return path39 ? `File or directory not found: ${path39}` : "File or directory not found";
   }
   if (/EACCES/i.test(msg)) {
-    const path38 = extractQuotedPath(msg);
-    return path38 ? `Permission denied: ${path38}` : "Permission denied \u2014 check file permissions";
+    const path39 = extractQuotedPath(msg);
+    return path39 ? `Permission denied: ${path39}` : "Permission denied \u2014 check file permissions";
   }
   if (/EISDIR/i.test(msg)) {
     return "Expected a file but found a directory at the specified path";
@@ -8300,6 +8321,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;
 }
 
@@ -8407,6 +8434,14 @@ var ToolRegistry = class {
         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);
@@ -9688,14 +9723,14 @@ var CompleteExecutor = class {
    */
   async checkpoint(context) {
     if (this.checkpointState && this.currentSprint) {
-      const checkpointPath = path15__default.join(
+      const checkpointPath = path16__default.join(
         context.projectPath,
         ".coco",
         "checkpoints",
         `complete-${this.currentSprint.id}.json`
       );
-      await fs14__default.mkdir(path15__default.dirname(checkpointPath), { recursive: true });
-      await fs14__default.writeFile(checkpointPath, JSON.stringify(this.checkpointState, null, 2), "utf-8");
+      await fs15__default.mkdir(path16__default.dirname(checkpointPath), { recursive: true });
+      await fs15__default.writeFile(checkpointPath, JSON.stringify(this.checkpointState, null, 2), "utf-8");
     }
     return {
       phase: "complete",
@@ -9715,13 +9750,13 @@ var CompleteExecutor = class {
     const sprintId = checkpoint.resumePoint;
     if (sprintId === "start") return;
     try {
-      const checkpointPath = path15__default.join(
+      const checkpointPath = path16__default.join(
         context.projectPath,
         ".coco",
         "checkpoints",
         `complete-${sprintId}.json`
       );
-      const content = await fs14__default.readFile(checkpointPath, "utf-8");
+      const content = await fs15__default.readFile(checkpointPath, "utf-8");
       this.checkpointState = JSON.parse(content);
       this.completedTaskIds = new Set(this.checkpointState.completedTaskIds);
     } catch {
@@ -9968,14 +10003,14 @@ var CompleteExecutor = class {
     };
     const saveFiles = async (files) => {
       for (const file of files) {
-        const filePath = path15__default.join(context.projectPath, file.path);
-        const dir = path15__default.dirname(filePath);
-        await fs14__default.mkdir(dir, { recursive: true });
+        const filePath = path16__default.join(context.projectPath, file.path);
+        const dir = path16__default.dirname(filePath);
+        await fs15__default.mkdir(dir, { recursive: true });
         if (file.action === "delete") {
-          await fs14__default.unlink(filePath).catch(() => {
+          await fs15__default.unlink(filePath).catch(() => {
           });
         } else {
-          await fs14__default.writeFile(filePath, file.content, "utf-8");
+          await fs15__default.writeFile(filePath, file.content, "utf-8");
         }
       }
     };
@@ -10101,8 +10136,8 @@ var CompleteExecutor = class {
    */
   async loadBacklog(projectPath) {
     try {
-      const backlogPath = path15__default.join(projectPath, ".coco", "planning", "backlog.json");
-      const content = await fs14__default.readFile(backlogPath, "utf-8");
+      const backlogPath = path16__default.join(projectPath, ".coco", "planning", "backlog.json");
+      const content = await fs15__default.readFile(backlogPath, "utf-8");
       const data = JSON.parse(content);
       return data.backlog;
     } catch {
@@ -10114,12 +10149,12 @@ var CompleteExecutor = class {
    */
   async loadCurrentSprint(projectPath) {
     try {
-      const sprintsDir = path15__default.join(projectPath, ".coco", "planning", "sprints");
-      const files = await fs14__default.readdir(sprintsDir);
+      const sprintsDir = path16__default.join(projectPath, ".coco", "planning", "sprints");
+      const files = await fs15__default.readdir(sprintsDir);
       const jsonFiles = files.filter((f) => f.endsWith(".json"));
       if (jsonFiles.length === 0) return null;
-      const sprintPath = path15__default.join(sprintsDir, jsonFiles[0] || "");
-      const content = await fs14__default.readFile(sprintPath, "utf-8");
+      const sprintPath = path16__default.join(sprintsDir, jsonFiles[0] || "");
+      const content = await fs15__default.readFile(sprintPath, "utf-8");
       const sprint = JSON.parse(content);
       sprint.startDate = new Date(sprint.startDate);
       return sprint;
@@ -10131,12 +10166,12 @@ var CompleteExecutor = class {
    * Save sprint results
    */
   async saveSprintResults(projectPath, result) {
-    const resultsDir = path15__default.join(projectPath, ".coco", "results");
-    await fs14__default.mkdir(resultsDir, { recursive: true });
-    const resultsPath = path15__default.join(resultsDir, `${result.sprintId}-results.json`);
-    await fs14__default.writeFile(resultsPath, JSON.stringify(result, null, 2), "utf-8");
-    const mdPath = path15__default.join(resultsDir, `${result.sprintId}-results.md`);
-    await fs14__default.writeFile(mdPath, this.generateResultsMarkdown(result), "utf-8");
+    const resultsDir = path16__default.join(projectPath, ".coco", "results");
+    await fs15__default.mkdir(resultsDir, { recursive: true });
+    const resultsPath = path16__default.join(resultsDir, `${result.sprintId}-results.json`);
+    await fs15__default.writeFile(resultsPath, JSON.stringify(result, null, 2), "utf-8");
+    const mdPath = path16__default.join(resultsDir, `${result.sprintId}-results.md`);
+    await fs15__default.writeFile(mdPath, this.generateResultsMarkdown(result), "utf-8");
     return resultsPath;
   }
   /**
@@ -11360,9 +11395,9 @@ var OutputExecutor = class {
       const cicdGenerator = new CICDGenerator(metadata, cicdConfig);
       const cicdFiles = cicdGenerator.generate();
       for (const file of cicdFiles) {
-        const filePath = path15__default.join(context.projectPath, file.path);
-        await this.ensureDir(path15__default.dirname(filePath));
-        await fs14__default.writeFile(filePath, file.content, "utf-8");
+        const filePath = path16__default.join(context.projectPath, file.path);
+        await this.ensureDir(path16__default.dirname(filePath));
+        await fs15__default.writeFile(filePath, file.content, "utf-8");
         artifacts.push({
           type: "cicd",
           path: filePath,
@@ -11372,16 +11407,16 @@ var OutputExecutor = class {
       if (this.config.docker.enabled) {
         const dockerGenerator = new DockerGenerator(metadata);
         const dockerfile2 = dockerGenerator.generateDockerfile();
-        const dockerfilePath = path15__default.join(context.projectPath, "Dockerfile");
-        await fs14__default.writeFile(dockerfilePath, dockerfile2, "utf-8");
+        const dockerfilePath = path16__default.join(context.projectPath, "Dockerfile");
+        await fs15__default.writeFile(dockerfilePath, dockerfile2, "utf-8");
         artifacts.push({
           type: "deployment",
           path: dockerfilePath,
           description: "Dockerfile"
         });
         const dockerignore = dockerGenerator.generateDockerignore();
-        const dockerignorePath = path15__default.join(context.projectPath, ".dockerignore");
-        await fs14__default.writeFile(dockerignorePath, dockerignore, "utf-8");
+        const dockerignorePath = path16__default.join(context.projectPath, ".dockerignore");
+        await fs15__default.writeFile(dockerignorePath, dockerignore, "utf-8");
         artifacts.push({
           type: "deployment",
           path: dockerignorePath,
@@ -11389,8 +11424,8 @@ var OutputExecutor = class {
         });
         if (this.config.docker.compose) {
           const compose = dockerGenerator.generateDockerCompose();
-          const composePath = path15__default.join(context.projectPath, "docker-compose.yml");
-          await fs14__default.writeFile(composePath, compose, "utf-8");
+          const composePath = path16__default.join(context.projectPath, "docker-compose.yml");
+          await fs15__default.writeFile(composePath, compose, "utf-8");
           artifacts.push({
             type: "deployment",
             path: composePath,
@@ -11401,8 +11436,8 @@ var OutputExecutor = class {
       const docsGenerator = new DocsGenerator(metadata);
       const docs = docsGenerator.generate();
       if (this.config.docs.readme) {
-        const readmePath = path15__default.join(context.projectPath, "README.md");
-        await fs14__default.writeFile(readmePath, docs.readme, "utf-8");
+        const readmePath = path16__default.join(context.projectPath, "README.md");
+        await fs15__default.writeFile(readmePath, docs.readme, "utf-8");
         artifacts.push({
           type: "documentation",
           path: readmePath,
@@ -11410,8 +11445,8 @@ var OutputExecutor = class {
         });
       }
       if (this.config.docs.contributing) {
-        const contributingPath = path15__default.join(context.projectPath, "CONTRIBUTING.md");
-        await fs14__default.writeFile(contributingPath, docs.contributing, "utf-8");
+        const contributingPath = path16__default.join(context.projectPath, "CONTRIBUTING.md");
+        await fs15__default.writeFile(contributingPath, docs.contributing, "utf-8");
         artifacts.push({
           type: "documentation",
           path: contributingPath,
@@ -11419,8 +11454,8 @@ var OutputExecutor = class {
         });
       }
       if (this.config.docs.changelog) {
-        const changelogPath = path15__default.join(context.projectPath, "CHANGELOG.md");
-        await fs14__default.writeFile(changelogPath, docs.changelog, "utf-8");
+        const changelogPath = path16__default.join(context.projectPath, "CHANGELOG.md");
+        await fs15__default.writeFile(changelogPath, docs.changelog, "utf-8");
         artifacts.push({
           type: "documentation",
           path: changelogPath,
@@ -11428,11 +11463,11 @@ var OutputExecutor = class {
         });
       }
       if (this.config.docs.api) {
-        const docsDir = path15__default.join(context.projectPath, "docs");
+        const docsDir = path16__default.join(context.projectPath, "docs");
         await this.ensureDir(docsDir);
         if (docs.api) {
-          const apiPath = path15__default.join(docsDir, "api.md");
-          await fs14__default.writeFile(apiPath, docs.api, "utf-8");
+          const apiPath = path16__default.join(docsDir, "api.md");
+          await fs15__default.writeFile(apiPath, docs.api, "utf-8");
           artifacts.push({
             type: "documentation",
             path: apiPath,
@@ -11440,8 +11475,8 @@ var OutputExecutor = class {
           });
         }
         if (docs.deployment) {
-          const deployPath = path15__default.join(docsDir, "deployment.md");
-          await fs14__default.writeFile(deployPath, docs.deployment, "utf-8");
+          const deployPath = path16__default.join(docsDir, "deployment.md");
+          await fs15__default.writeFile(deployPath, docs.deployment, "utf-8");
           artifacts.push({
             type: "documentation",
             path: deployPath,
@@ -11449,8 +11484,8 @@ var OutputExecutor = class {
           });
         }
         if (docs.development) {
-          const devPath = path15__default.join(docsDir, "development.md");
-          await fs14__default.writeFile(devPath, docs.development, "utf-8");
+          const devPath = path16__default.join(docsDir, "development.md");
+          await fs15__default.writeFile(devPath, docs.development, "utf-8");
           artifacts.push({
             type: "documentation",
             path: devPath,
@@ -11515,16 +11550,16 @@ var OutputExecutor = class {
    */
   async loadMetadata(projectPath) {
     try {
-      const packagePath = path15__default.join(projectPath, "package.json");
-      const content = await fs14__default.readFile(packagePath, "utf-8");
+      const packagePath = path16__default.join(projectPath, "package.json");
+      const content = await fs15__default.readFile(packagePath, "utf-8");
       const pkg = JSON.parse(content);
       let packageManager = "npm";
       try {
-        await fs14__default.access(path15__default.join(projectPath, "pnpm-lock.yaml"));
+        await fs15__default.access(path16__default.join(projectPath, "pnpm-lock.yaml"));
         packageManager = "pnpm";
       } catch {
         try {
-          await fs14__default.access(path15__default.join(projectPath, "yarn.lock"));
+          await fs15__default.access(path16__default.join(projectPath, "yarn.lock"));
           packageManager = "yarn";
         } catch {
         }
@@ -11536,7 +11571,7 @@ var OutputExecutor = class {
         repository = pkg.repository.url;
       }
       return {
-        name: pkg.name || path15__default.basename(projectPath),
+        name: pkg.name || path16__default.basename(projectPath),
         description: pkg.description || "",
         version: pkg.version || "0.1.0",
         language: "typescript",
@@ -11550,7 +11585,7 @@ var OutputExecutor = class {
       };
     } catch {
       return {
-        name: path15__default.basename(projectPath),
+        name: path16__default.basename(projectPath),
         description: "",
         version: "0.1.0",
         language: "typescript",
@@ -11566,7 +11601,7 @@ var OutputExecutor = class {
    * Ensure directory exists
    */
   async ensureDir(dir) {
-    await fs14__default.mkdir(dir, { recursive: true });
+    await fs15__default.mkdir(dir, { recursive: true });
   }
 };
 function createOutputExecutor(config) {
@@ -11749,22 +11784,38 @@ var AnthropicProvider = class {
   async *stream(messages, options) {
     this.ensureInitialized();
     try {
-      const stream = await this.client.messages.stream({
-        model: options?.model ?? this.config.model ?? DEFAULT_MODEL,
-        max_tokens: options?.maxTokens ?? this.config.maxTokens ?? 8192,
-        temperature: options?.temperature ?? this.config.temperature ?? 0,
-        system: this.extractSystem(messages, options?.system),
-        messages: this.convertMessages(messages)
-      });
-      for await (const event of stream) {
-        if (event.type === "content_block_delta") {
-          const delta = event.delta;
-          if (delta.type === "text_delta" && delta.text) {
-            yield { type: "text", text: delta.text };
+      const stream = await this.client.messages.stream(
+        {
+          model: options?.model ?? this.config.model ?? DEFAULT_MODEL,
+          max_tokens: options?.maxTokens ?? this.config.maxTokens ?? 8192,
+          temperature: options?.temperature ?? this.config.temperature ?? 0,
+          system: this.extractSystem(messages, options?.system),
+          messages: this.convertMessages(messages)
+        },
+        { signal: options?.signal }
+      );
+      const streamTimeout = this.config.timeout ?? 12e4;
+      let lastActivityTime = Date.now();
+      const checkTimeout = () => {
+        if (Date.now() - lastActivityTime > streamTimeout) {
+          throw new Error(`Stream timeout: No response from LLM for ${streamTimeout / 1e3}s`);
+        }
+      };
+      const timeoutInterval = setInterval(checkTimeout, 5e3);
+      try {
+        for await (const event of stream) {
+          lastActivityTime = Date.now();
+          if (event.type === "content_block_delta") {
+            const delta = event.delta;
+            if (delta.type === "text_delta" && delta.text) {
+              yield { type: "text", text: delta.text };
+            }
           }
         }
+        yield { type: "done" };
+      } finally {
+        clearInterval(timeoutInterval);
       }
-      yield { type: "done" };
     } catch (error) {
       throw this.handleError(error);
     }
@@ -11775,90 +11826,106 @@ var AnthropicProvider = class {
   async *streamWithTools(messages, options) {
     this.ensureInitialized();
     try {
-      const stream = await this.client.messages.stream({
-        model: options?.model ?? this.config.model ?? DEFAULT_MODEL,
-        max_tokens: options?.maxTokens ?? this.config.maxTokens ?? 8192,
-        temperature: options?.temperature ?? this.config.temperature ?? 0,
-        system: this.extractSystem(messages, options?.system),
-        messages: this.convertMessages(messages),
-        tools: this.convertTools(options.tools),
-        tool_choice: options.toolChoice ? this.convertToolChoice(options.toolChoice) : void 0
-      });
+      const stream = await this.client.messages.stream(
+        {
+          model: options?.model ?? this.config.model ?? DEFAULT_MODEL,
+          max_tokens: options?.maxTokens ?? this.config.maxTokens ?? 8192,
+          temperature: options?.temperature ?? this.config.temperature ?? 0,
+          system: this.extractSystem(messages, options?.system),
+          messages: this.convertMessages(messages),
+          tools: this.convertTools(options.tools),
+          tool_choice: options.toolChoice ? this.convertToolChoice(options.toolChoice) : void 0
+        },
+        { signal: options?.signal }
+      );
       let currentToolCall = null;
       let currentToolInputJson = "";
-      for await (const event of stream) {
-        if (event.type === "content_block_start") {
-          const contentBlock = event.content_block;
-          if (contentBlock.type === "tool_use") {
+      const streamTimeout = this.config.timeout ?? 12e4;
+      let lastActivityTime = Date.now();
+      const checkTimeout = () => {
+        if (Date.now() - lastActivityTime > streamTimeout) {
+          throw new Error(`Stream timeout: No response from LLM for ${streamTimeout / 1e3}s`);
+        }
+      };
+      const timeoutInterval = setInterval(checkTimeout, 5e3);
+      try {
+        for await (const event of stream) {
+          lastActivityTime = Date.now();
+          if (event.type === "content_block_start") {
+            const contentBlock = event.content_block;
+            if (contentBlock.type === "tool_use") {
+              if (currentToolCall) {
+                getLogger().warn(
+                  `[Anthropic] content_block_stop missing for tool '${currentToolCall.name}' \u2014 finalizing early to prevent data bleed.`
+                );
+                try {
+                  currentToolCall.input = currentToolInputJson ? JSON.parse(currentToolInputJson) : {};
+                } catch {
+                  currentToolCall.input = {};
+                }
+                yield {
+                  type: "tool_use_end",
+                  toolCall: { ...currentToolCall }
+                };
+              }
+              currentToolCall = {
+                id: contentBlock.id,
+                name: contentBlock.name
+              };
+              currentToolInputJson = "";
+              yield {
+                type: "tool_use_start",
+                toolCall: { ...currentToolCall }
+              };
+            }
+          } else if (event.type === "content_block_delta") {
+            const delta = event.delta;
+            if (delta.type === "text_delta" && delta.text) {
+              yield { type: "text", text: delta.text };
+            } else if (delta.type === "input_json_delta" && delta.partial_json) {
+              currentToolInputJson += delta.partial_json;
+              yield {
+                type: "tool_use_delta",
+                toolCall: {
+                  ...currentToolCall
+                },
+                text: delta.partial_json
+              };
+            }
+          } else if (event.type === "content_block_stop") {
             if (currentToolCall) {
-              getLogger().warn(
-                `[Anthropic] content_block_stop missing for tool '${currentToolCall.name}' \u2014 finalizing early to prevent data bleed.`
-              );
               try {
                 currentToolCall.input = currentToolInputJson ? JSON.parse(currentToolInputJson) : {};
               } catch {
-                currentToolCall.input = {};
+                let repaired = false;
+                if (currentToolInputJson) {
+                  try {
+                    currentToolCall.input = JSON.parse(jsonrepair(currentToolInputJson));
+                    repaired = true;
+                    getLogger().debug(`Repaired JSON for tool ${currentToolCall.name}`);
+                  } catch {
+                  }
+                }
+                if (!repaired) {
+                  getLogger().warn(
+                    `Failed to parse tool call arguments for ${currentToolCall.name}: ${currentToolInputJson?.slice(0, 300)}`
+                  );
+                  currentToolCall.input = {};
+                }
               }
               yield {
                 type: "tool_use_end",
                 toolCall: { ...currentToolCall }
               };
+              currentToolCall = null;
+              currentToolInputJson = "";
             }
-            currentToolCall = {
-              id: contentBlock.id,
-              name: contentBlock.name
-            };
-            currentToolInputJson = "";
-            yield {
-              type: "tool_use_start",
-              toolCall: { ...currentToolCall }
-            };
-          }
-        } else if (event.type === "content_block_delta") {
-          const delta = event.delta;
-          if (delta.type === "text_delta" && delta.text) {
-            yield { type: "text", text: delta.text };
-          } else if (delta.type === "input_json_delta" && delta.partial_json) {
-            currentToolInputJson += delta.partial_json;
-            yield {
-              type: "tool_use_delta",
-              toolCall: {
-                ...currentToolCall
-              },
-              text: delta.partial_json
-            };
-          }
-        } else if (event.type === "content_block_stop") {
-          if (currentToolCall) {
-            try {
-              currentToolCall.input = currentToolInputJson ? JSON.parse(currentToolInputJson) : {};
-            } catch {
-              let repaired = false;
-              if (currentToolInputJson) {
-                try {
-                  currentToolCall.input = JSON.parse(jsonrepair(currentToolInputJson));
-                  repaired = true;
-                  getLogger().debug(`Repaired JSON for tool ${currentToolCall.name}`);
-                } catch {
-                }
-              }
-              if (!repaired) {
-                getLogger().warn(
-                  `Failed to parse tool call arguments for ${currentToolCall.name}: ${currentToolInputJson?.slice(0, 300)}`
-                );
-                currentToolCall.input = {};
-              }
-            }
-            yield {
-              type: "tool_use_end",
-              toolCall: { ...currentToolCall }
-            };
-            currentToolCall = null;
-            currentToolInputJson = "";
           }
         }
+        yield { type: "done" };
+      } finally {
+        clearInterval(timeoutInterval);
       }
-      yield { type: "done" };
     } catch (error) {
       throw this.handleError(error);
     }
@@ -12896,18 +12963,18 @@ async function refreshAccessToken(provider, refreshToken) {
 }
 function getTokenStoragePath(provider) {
   const home = process.env.HOME || process.env.USERPROFILE || "";
-  return path15.join(home, ".coco", "tokens", `${provider}.json`);
+  return path16.join(home, ".coco", "tokens", `${provider}.json`);
 }
 async function saveTokens(provider, tokens) {
   const filePath = getTokenStoragePath(provider);
-  const dir = path15.dirname(filePath);
-  await fs14.mkdir(dir, { recursive: true, mode: 448 });
-  await fs14.writeFile(filePath, JSON.stringify(tokens, null, 2), { mode: 384 });
+  const dir = path16.dirname(filePath);
+  await fs15.mkdir(dir, { recursive: true, mode: 448 });
+  await fs15.writeFile(filePath, JSON.stringify(tokens, null, 2), { mode: 384 });
 }
 async function loadTokens(provider) {
   const filePath = getTokenStoragePath(provider);
   try {
-    const content = await fs14.readFile(filePath, "utf-8");
+    const content = await fs15.readFile(filePath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -12916,7 +12983,7 @@ async function loadTokens(provider) {
 async function deleteTokens(provider) {
   const filePath = getTokenStoragePath(provider);
   try {
-    await fs14.unlink(filePath);
+    await fs15.unlink(filePath);
   } catch {
   }
 }
@@ -13914,9 +13981,9 @@ function createInitialState(config) {
 }
 async function loadExistingState(projectPath) {
   try {
-    const fs36 = await import('fs/promises');
+    const fs37 = await import('fs/promises');
     const statePath = `${projectPath}/.coco/state/project.json`;
-    const content = await fs36.readFile(statePath, "utf-8");
+    const content = await fs37.readFile(statePath, "utf-8");
     const data = JSON.parse(content);
     data.createdAt = new Date(data.createdAt);
     data.updatedAt = new Date(data.updatedAt);
@@ -13926,13 +13993,13 @@ async function loadExistingState(projectPath) {
   }
 }
 async function saveState(state) {
-  const fs36 = await import('fs/promises');
+  const fs37 = await import('fs/promises');
   const statePath = `${state.path}/.coco/state`;
-  await fs36.mkdir(statePath, { recursive: true });
+  await fs37.mkdir(statePath, { recursive: true });
   const filePath = `${statePath}/project.json`;
   const tmpPath = `${filePath}.tmp.${Date.now()}`;
-  await fs36.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
-  await fs36.rename(tmpPath, filePath);
+  await fs37.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+  await fs37.rename(tmpPath, filePath);
 }
 function getPhaseExecutor(phase) {
   switch (phase) {
@@ -13991,20 +14058,20 @@ async function createPhaseContext(config, state) {
   };
   const tools = {
     file: {
-      async read(path38) {
-        const fs36 = await import('fs/promises');
-        return fs36.readFile(path38, "utf-8");
+      async read(path39) {
+        const fs37 = await import('fs/promises');
+        return fs37.readFile(path39, "utf-8");
       },
-      async write(path38, content) {
-        const fs36 = await import('fs/promises');
+      async write(path39, content) {
+        const fs37 = await import('fs/promises');
         const nodePath = await import('path');
-        await fs36.mkdir(nodePath.dirname(path38), { recursive: true });
-        await fs36.writeFile(path38, content, "utf-8");
+        await fs37.mkdir(nodePath.dirname(path39), { recursive: true });
+        await fs37.writeFile(path39, content, "utf-8");
       },
-      async exists(path38) {
-        const fs36 = await import('fs/promises');
+      async exists(path39) {
+        const fs37 = await import('fs/promises');
         try {
-          await fs36.access(path38);
+          await fs37.access(path39);
           return true;
         } catch {
           return false;
@@ -14153,9 +14220,9 @@ async function createSnapshot(state) {
 var MAX_CHECKPOINT_VERSIONS = 5;
 async function getCheckpointFiles(state, phase) {
   try {
-    const fs36 = await import('fs/promises');
+    const fs37 = await import('fs/promises');
     const checkpointDir = `${state.path}/.coco/checkpoints`;
-    const files = await fs36.readdir(checkpointDir);
+    const files = await fs37.readdir(checkpointDir);
     const phaseFiles = files.filter((f) => f.startsWith(`snapshot-pre-${phase}-`) && f.endsWith(".json")).sort((a, b) => {
       const tsA = parseInt(a.split("-").pop()?.replace(".json", "") ?? "0", 10);
       const tsB = parseInt(b.split("-").pop()?.replace(".json", "") ?? "0", 10);
@@ -14168,11 +14235,11 @@ async function getCheckpointFiles(state, phase) {
 }
 async function cleanupOldCheckpoints(state, phase) {
   try {
-    const fs36 = await import('fs/promises');
+    const fs37 = await import('fs/promises');
     const files = await getCheckpointFiles(state, phase);
     if (files.length > MAX_CHECKPOINT_VERSIONS) {
       const filesToDelete = files.slice(MAX_CHECKPOINT_VERSIONS);
-      await Promise.all(filesToDelete.map((f) => fs36.unlink(f).catch(() => {
+      await Promise.all(filesToDelete.map((f) => fs37.unlink(f).catch(() => {
       })));
     }
   } catch {
@@ -14180,13 +14247,13 @@ async function cleanupOldCheckpoints(state, phase) {
 }
 async function saveSnapshot(state, snapshotId) {
   try {
-    const fs36 = await import('fs/promises');
+    const fs37 = await import('fs/promises');
     const snapshotPath = `${state.path}/.coco/checkpoints/snapshot-${snapshotId}.json`;
     const snapshotDir = `${state.path}/.coco/checkpoints`;
-    await fs36.mkdir(snapshotDir, { recursive: true });
+    await fs37.mkdir(snapshotDir, { recursive: true });
     const createdAt = state.createdAt instanceof Date ? state.createdAt.toISOString() : String(state.createdAt);
     const updatedAt = state.updatedAt instanceof Date ? state.updatedAt.toISOString() : String(state.updatedAt);
-    await fs36.writeFile(
+    await fs37.writeFile(
       snapshotPath,
       JSON.stringify(
         {
@@ -14498,7 +14565,7 @@ async function loadConfig(configPath) {
 async function loadConfigFile(configPath, options = {}) {
   const { strict = true } = options;
   try {
-    const content = await fs14__default.readFile(configPath, "utf-8");
+    const content = await fs15__default.readFile(configPath, "utf-8");
     const parsed = JSON5.parse(content);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       if (!strict) {
@@ -14554,7 +14621,7 @@ function deepMergeConfig(base, override) {
   };
 }
 function getProjectConfigPath2() {
-  return path15__default.join(process.cwd(), ".coco", "config.json");
+  return path16__default.join(process.cwd(), ".coco", "config.json");
 }
 async function saveConfig(config, configPath, global = false) {
   const result = CocoConfigSchema.safeParse(config);
@@ -14569,10 +14636,10 @@ async function saveConfig(config, configPath, global = false) {
     });
   }
   const resolvedPath = configPath || (global ? CONFIG_PATHS.config : getProjectConfigPath2());
-  const dir = path15__default.dirname(resolvedPath);
-  await fs14__default.mkdir(dir, { recursive: true });
+  const dir = path16__default.dirname(resolvedPath);
+  await fs15__default.mkdir(dir, { recursive: true });
   const content = JSON.stringify(result.data, null, 2);
-  await fs14__default.writeFile(resolvedPath, content, "utf-8");
+  await fs15__default.writeFile(resolvedPath, content, "utf-8");
 }
 function createDefaultConfig(projectName, language = "typescript") {
   return createDefaultConfigObject(projectName, language);
@@ -14580,7 +14647,7 @@ function createDefaultConfig(projectName, language = "typescript") {
 async function configExists(configPath, scope = "any") {
   if (configPath) {
     try {
-      await fs14__default.access(configPath);
+      await fs15__default.access(configPath);
       return true;
     } catch {
       return false;
@@ -14588,7 +14655,7 @@ async function configExists(configPath, scope = "any") {
   }
   if (scope === "project" || scope === "any") {
     try {
-      await fs14__default.access(getProjectConfigPath2());
+      await fs15__default.access(getProjectConfigPath2());
       return true;
     } catch {
       if (scope === "project") return false;
@@ -14596,7 +14663,7 @@ async function configExists(configPath, scope = "any") {
   }
   if (scope === "global" || scope === "any") {
     try {
-      await fs14__default.access(CONFIG_PATHS.config);
+      await fs15__default.access(CONFIG_PATHS.config);
       return true;
     } catch {
       return false;
@@ -14609,6 +14676,83 @@ z.string().regex(
   "Version must be in semver format (e.g., 1.0.0)"
 );
 init_allowed_paths();
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j] + 1,
+        // deletion
+        prev + 1,
+        // insertion
+        row[j - 1] + cost
+        // substitution
+      );
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[b.length] = prev;
+  }
+  return row[b.length];
+}
+
+// src/utils/file-suggestions.ts
+var MAX_DIR_ENTRIES = 200;
+var MAX_SUGGESTIONS = 5;
+async function suggestSimilarFiles(missingPath, options) {
+  const absPath = path16__default.resolve(missingPath);
+  const dir = path16__default.dirname(absPath);
+  const target = path16__default.basename(absPath);
+  const maxResults = MAX_SUGGESTIONS;
+  try {
+    const entries = await fs15__default.readdir(dir);
+    const limited = entries.slice(0, MAX_DIR_ENTRIES);
+    const scored = limited.map((name) => ({
+      path: path16__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 = path16__default.resolve(missingPath);
+  const grandparent = path16__default.dirname(path16__default.dirname(absPath));
+  const parentBasename = path16__default.basename(path16__default.dirname(absPath));
+  const maxResults = MAX_SUGGESTIONS;
+  try {
+    const entries = await fs15__default.readdir(grandparent, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).slice(0, MAX_DIR_ENTRIES);
+    const scored = dirs.map((d) => ({
+      path: path16__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 = path16__default.relative(base, s.path);
+    return `  - ${rel}`;
+  });
+  return `
+Did you mean?
+${lines.join("\n")}`;
+}
+
+// src/tools/file.ts
 var SENSITIVE_PATTERNS = [
   /\.env(?:\.\w+)?$/,
   // .env, .env.local, etc.
@@ -14633,7 +14777,7 @@ function hasNullByte(str) {
 }
 function normalizePath(filePath) {
   let normalized = filePath.replace(/\0/g, "");
-  normalized = path15__default.normalize(normalized);
+  normalized = path16__default.normalize(normalized);
   return normalized;
 }
 function isPathAllowed(filePath, operation) {
@@ -14641,31 +14785,31 @@ function isPathAllowed(filePath, operation) {
     return { allowed: false, reason: "Path contains invalid characters" };
   }
   const normalized = normalizePath(filePath);
-  const absolute = path15__default.resolve(normalized);
+  const absolute = path16__default.resolve(normalized);
   const cwd = process.cwd();
   for (const blocked of BLOCKED_PATHS) {
-    const normalizedBlocked = path15__default.normalize(blocked);
-    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path15__default.sep)) {
+    const normalizedBlocked = path16__default.normalize(blocked);
+    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path16__default.sep)) {
       return { allowed: false, reason: `Access to system path '${blocked}' is not allowed` };
     }
   }
   const home = process.env.HOME;
   if (home) {
-    const normalizedHome = path15__default.normalize(home);
-    const normalizedCwd = path15__default.normalize(cwd);
+    const normalizedHome = path16__default.normalize(home);
+    const normalizedCwd = path16__default.normalize(cwd);
     if (absolute.startsWith(normalizedHome) && !absolute.startsWith(normalizedCwd)) {
       if (isWithinAllowedPath(absolute, operation)) ; else if (operation === "read") {
         const allowedHomeReads = [".gitconfig", ".zshrc", ".bashrc"];
-        const basename5 = path15__default.basename(absolute);
+        const basename5 = path16__default.basename(absolute);
         if (!allowedHomeReads.includes(basename5)) {
-          const targetDir = path15__default.dirname(absolute);
+          const targetDir = path16__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 = path15__default.dirname(absolute);
+        const targetDir = path16__default.dirname(absolute);
         return {
           allowed: false,
           reason: `${operation} operations outside project directory are not allowed. Use /allow-path ${targetDir} to grant access.`
@@ -14674,7 +14818,7 @@ function isPathAllowed(filePath, operation) {
     }
   }
   if (operation === "write" || operation === "delete") {
-    const basename5 = path15__default.basename(absolute);
+    const basename5 = path16__default.basename(absolute);
     for (const pattern of SENSITIVE_PATTERNS) {
       if (pattern.test(basename5)) {
         return {
@@ -14693,6 +14837,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 = path16__default.resolve(filePath);
+  const suggestions = await suggestSimilarFiles(absPath);
+  const hint = formatSuggestions(suggestions, path16__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 = path16__default.resolve(dirPath);
+  const suggestions = await suggestSimilarPaths(absPath);
+  const hint = formatSuggestions(suggestions, path16__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.
@@ -14710,13 +14872,13 @@ Examples:
   async execute({ path: filePath, encoding, maxSize }) {
     validatePath(filePath, "read");
     try {
-      const absolutePath = path15__default.resolve(filePath);
-      const stats = await fs14__default.stat(absolutePath);
+      const absolutePath = path16__default.resolve(filePath);
+      const stats = await fs15__default.stat(absolutePath);
       const maxBytes = maxSize ?? DEFAULT_MAX_FILE_SIZE;
       let truncated = false;
       let content;
       if (stats.size > maxBytes) {
-        const handle = await fs14__default.open(absolutePath, "r");
+        const handle = await fs15__default.open(absolutePath, "r");
         try {
           const buffer = Buffer.alloc(maxBytes);
           await handle.read(buffer, 0, maxBytes, 0);
@@ -14726,7 +14888,7 @@ Examples:
           await handle.close();
         }
       } else {
-        content = await fs14__default.readFile(absolutePath, encoding);
+        content = await fs15__default.readFile(absolutePath, encoding);
       }
       return {
         content,
@@ -14735,6 +14897,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",
@@ -14761,10 +14931,10 @@ Examples:
   async execute({ path: filePath, content, createDirs, dryRun }) {
     validatePath(filePath, "write");
     try {
-      const absolutePath = path15__default.resolve(filePath);
+      const absolutePath = path16__default.resolve(filePath);
       let wouldCreate = false;
       try {
-        await fs14__default.access(absolutePath);
+        await fs15__default.access(absolutePath);
       } catch {
         wouldCreate = true;
       }
@@ -14777,10 +14947,10 @@ Examples:
         };
       }
       if (createDirs) {
-        await fs14__default.mkdir(path15__default.dirname(absolutePath), { recursive: true });
+        await fs15__default.mkdir(path16__default.dirname(absolutePath), { recursive: true });
       }
-      await fs14__default.writeFile(absolutePath, content, "utf-8");
-      const stats = await fs14__default.stat(absolutePath);
+      await fs15__default.writeFile(absolutePath, content, "utf-8");
+      const stats = await fs15__default.stat(absolutePath);
       return {
         path: absolutePath,
         size: stats.size,
@@ -14788,6 +14958,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",
@@ -14815,8 +14993,8 @@ Examples:
   async execute({ path: filePath, oldText, newText, all, dryRun }) {
     validatePath(filePath, "write");
     try {
-      const absolutePath = path15__default.resolve(filePath);
-      let content = await fs14__default.readFile(absolutePath, "utf-8");
+      const absolutePath = path16__default.resolve(filePath);
+      let content = await fs15__default.readFile(absolutePath, "utf-8");
       let replacements = 0;
       if (all) {
         const regex = new RegExp(escapeRegex(oldText), "g");
@@ -14830,7 +15008,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;
@@ -14841,7 +15043,7 @@ Examples:
           preview
         };
       }
-      await fs14__default.writeFile(absolutePath, content, "utf-8");
+      await fs15__default.writeFile(absolutePath, content, "utf-8");
       return {
         path: absolutePath,
         replacements,
@@ -14882,6 +15084,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",
@@ -14904,8 +15114,8 @@ Examples:
   }),
   async execute({ path: filePath }) {
     try {
-      const absolutePath = path15__default.resolve(filePath);
-      const stats = await fs14__default.stat(absolutePath);
+      const absolutePath = path16__default.resolve(filePath);
+      const stats = await fs15__default.stat(absolutePath);
       return {
         exists: true,
         isFile: stats.isFile(),
@@ -14935,12 +15145,12 @@ Examples:
   }),
   async execute({ path: dirPath, recursive }) {
     try {
-      const absolutePath = path15__default.resolve(dirPath);
+      const absolutePath = path16__default.resolve(dirPath);
       const entries = [];
       async function listDir(dir, prefix = "") {
-        const items = await fs14__default.readdir(dir, { withFileTypes: true });
+        const items = await fs15__default.readdir(dir, { withFileTypes: true });
         for (const item of items) {
-          const fullPath = path15__default.join(dir, item.name);
+          const fullPath = path16__default.join(dir, item.name);
           const relativePath = prefix ? `${prefix}/${item.name}` : item.name;
           if (item.isDirectory()) {
             entries.push({ name: relativePath, type: "directory" });
@@ -14948,7 +15158,7 @@ Examples:
               await listDir(fullPath, relativePath);
             }
           } else if (item.isFile()) {
-            const stats = await fs14__default.stat(fullPath);
+            const stats = await fs15__default.stat(fullPath);
             entries.push({ name: relativePath, type: "file", size: stats.size });
           }
         }
@@ -14956,6 +15166,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",
@@ -14987,23 +15205,23 @@ Examples:
     }
     validatePath(filePath, "delete");
     try {
-      const absolutePath = path15__default.resolve(filePath);
-      const stats = await fs14__default.stat(absolutePath);
+      const absolutePath = path16__default.resolve(filePath);
+      const stats = await fs15__default.stat(absolutePath);
       if (stats.isDirectory()) {
         if (!recursive) {
           throw new ToolError("Cannot delete directory without recursive: true", {
             tool: "delete_file"
           });
         }
-        await fs14__default.rm(absolutePath, { recursive: true });
+        await fs15__default.rm(absolutePath, { recursive: true });
       } else {
-        await fs14__default.unlink(absolutePath);
+        await fs15__default.unlink(absolutePath);
       }
       return { deleted: true, path: absolutePath };
     } catch (error) {
       if (error instanceof ToolError) throw error;
       if (error.code === "ENOENT") {
-        return { deleted: false, path: path15__default.resolve(filePath) };
+        return { deleted: false, path: path16__default.resolve(filePath) };
       }
       throw new FileSystemError(`Failed to delete: ${filePath}`, {
         path: filePath,
@@ -15031,11 +15249,11 @@ Examples:
     validatePath(source, "read");
     validatePath(destination, "write");
     try {
-      const srcPath = path15__default.resolve(source);
-      const destPath = path15__default.resolve(destination);
+      const srcPath = path16__default.resolve(source);
+      const destPath = path16__default.resolve(destination);
       if (!overwrite) {
         try {
-          await fs14__default.access(destPath);
+          await fs15__default.access(destPath);
           throw new ToolError(
             `Destination already exists: ${destination}. Use overwrite: true to replace.`,
             {
@@ -15048,9 +15266,9 @@ Examples:
           }
         }
       }
-      await fs14__default.mkdir(path15__default.dirname(destPath), { recursive: true });
-      await fs14__default.copyFile(srcPath, destPath);
-      const stats = await fs14__default.stat(destPath);
+      await fs15__default.mkdir(path16__default.dirname(destPath), { recursive: true });
+      await fs15__default.copyFile(srcPath, destPath);
+      const stats = await fs15__default.stat(destPath);
       return {
         source: srcPath,
         destination: destPath,
@@ -15058,6 +15276,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",
@@ -15084,11 +15310,11 @@ Examples:
     validatePath(source, "delete");
     validatePath(destination, "write");
     try {
-      const srcPath = path15__default.resolve(source);
-      const destPath = path15__default.resolve(destination);
+      const srcPath = path16__default.resolve(source);
+      const destPath = path16__default.resolve(destination);
       if (!overwrite) {
         try {
-          await fs14__default.access(destPath);
+          await fs15__default.access(destPath);
           throw new ToolError(
             `Destination already exists: ${destination}. Use overwrite: true to replace.`,
             {
@@ -15101,14 +15327,22 @@ Examples:
           }
         }
       }
-      await fs14__default.mkdir(path15__default.dirname(destPath), { recursive: true });
-      await fs14__default.rename(srcPath, destPath);
+      await fs15__default.mkdir(path16__default.dirname(destPath), { recursive: true });
+      await fs15__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",
@@ -15136,13 +15370,13 @@ Examples:
   }),
   async execute({ path: dirPath, depth, showHidden, dirsOnly }) {
     try {
-      const absolutePath = path15__default.resolve(dirPath ?? ".");
+      const absolutePath = path16__default.resolve(dirPath ?? ".");
       let totalFiles = 0;
       let totalDirs = 0;
-      const lines = [path15__default.basename(absolutePath) + "/"];
+      const lines = [path16__default.basename(absolutePath) + "/"];
       async function buildTree(dir, prefix, currentDepth) {
         if (currentDepth > (depth ?? 4)) return;
-        let items = await fs14__default.readdir(dir, { withFileTypes: true });
+        let items = await fs15__default.readdir(dir, { withFileTypes: true });
         if (!showHidden) {
           items = items.filter((item) => !item.name.startsWith("."));
         }
@@ -15162,7 +15396,7 @@ Examples:
           if (item.isDirectory()) {
             totalDirs++;
             lines.push(`${prefix}${connector}${item.name}/`);
-            await buildTree(path15__default.join(dir, item.name), prefix + childPrefix, currentDepth + 1);
+            await buildTree(path16__default.join(dir, item.name), prefix + childPrefix, currentDepth + 1);
           } else {
             totalFiles++;
             lines.push(`${prefix}${connector}${item.name}`);
@@ -15176,6 +15410,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",
@@ -15202,40 +15444,24 @@ function escapeRegex(str) {
 var DEFAULT_TIMEOUT_MS = 12e4;
 var MAX_OUTPUT_SIZE = 1024 * 1024;
 var 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)" }
 ];
 var 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)" }
 ];
 function getShellCommandPart(command) {
   const firstNewline = command.indexOf("\n");
@@ -15313,18 +15539,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();
@@ -15409,18 +15637,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 {
@@ -15528,6 +15758,27 @@ function truncateOutput(output, maxLength = 5e4) {
 
 [Output truncated - ${output.length - maxLength} more characters]`;
 }
+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 getGit(cwd) {
   const baseDir = cwd ?? process.cwd();
   return simpleGit({ baseDir });
@@ -15559,10 +15810,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
+      });
     }
   }
 });
@@ -15596,10 +15847,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
+      });
     }
   }
 });
@@ -15622,10 +15873,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
+      });
     }
   }
 });
@@ -15655,10 +15906,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
+      });
     }
   }
 });
@@ -15695,10 +15946,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
+      });
     }
   }
 });
@@ -15739,10 +15990,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
+      });
     }
   }
 });
@@ -15769,10 +16020,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
+      });
     }
   }
 });
@@ -15807,10 +16058,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
+      });
     }
   }
 });
@@ -15842,10 +16093,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
+      });
     }
   }
 });
@@ -15871,10 +16122,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
+      });
     }
   }
 });
@@ -16150,8 +16401,8 @@ var checkAgentCapabilityTool = defineTool({
 var simpleAgentTools = [spawnSimpleAgentTool, checkAgentCapabilityTool];
 async function detectTestFramework2(cwd) {
   try {
-    const pkgPath = path15__default.join(cwd, "package.json");
-    const pkgContent = await fs14__default.readFile(pkgPath, "utf-8");
+    const pkgPath = path16__default.join(cwd, "package.json");
+    const pkgContent = await fs15__default.readFile(pkgPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     const deps = {
       ...pkg.dependencies,
@@ -16239,8 +16490,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 }
       );
     }
@@ -16331,13 +16583,13 @@ Examples:
     const projectDir = cwd ?? process.cwd();
     try {
       const coverageLocations = [
-        path15__default.join(projectDir, "coverage", "coverage-summary.json"),
-        path15__default.join(projectDir, "coverage", "coverage-final.json"),
-        path15__default.join(projectDir, ".nyc_output", "coverage-summary.json")
+        path16__default.join(projectDir, "coverage", "coverage-summary.json"),
+        path16__default.join(projectDir, "coverage", "coverage-final.json"),
+        path16__default.join(projectDir, ".nyc_output", "coverage-summary.json")
       ];
       for (const location of coverageLocations) {
         try {
-          const content = await fs14__default.readFile(location, "utf-8");
+          const content = await fs15__default.readFile(location, "utf-8");
           const coverage = JSON.parse(content);
           if (coverage.total) {
             return {
@@ -16356,8 +16608,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 }
       );
     }
@@ -16389,8 +16642,8 @@ Examples:
 var testTools = [runTestsTool, getCoverageTool, runTestFileTool];
 async function detectLinter2(cwd) {
   try {
-    const pkgPath = path15__default.join(cwd, "package.json");
-    const pkgContent = await fs14__default.readFile(pkgPath, "utf-8");
+    const pkgPath = path16__default.join(cwd, "package.json");
+    const pkgContent = await fs15__default.readFile(pkgPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     const deps = {
       ...pkg.dependencies,
@@ -16429,7 +16682,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 {
@@ -16546,7 +16801,7 @@ Examples:
       let totalFunctions = 0;
       let complexFunctions = 0;
       for (const file of targetFiles) {
-        const content = await fs14__default.readFile(file, "utf-8");
+        const content = await fs15__default.readFile(file, "utf-8");
         const fileComplexity = analyzeFileComplexity(content, file);
         fileResults.push(fileComplexity);
         totalComplexity += fileComplexity.complexity;
@@ -16569,8 +16824,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 }
       );
     }
@@ -16656,8 +16912,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 }
       );
     }
@@ -16695,7 +16952,7 @@ Examples:
     caseSensitive,
     wholeWord
   }) {
-    const targetPath = searchPath ? path15__default.resolve(searchPath) : process.cwd();
+    const targetPath = searchPath ? path16__default.resolve(searchPath) : process.cwd();
     const matches = [];
     let filesSearched = 0;
     const filesWithMatches = /* @__PURE__ */ new Set();
@@ -16717,7 +16974,7 @@ Examples:
           tool: "grep"
         });
       }
-      const stats = await fs14__default.stat(targetPath);
+      const stats = await fs15__default.stat(targetPath);
       let filesToSearch;
       if (stats.isFile()) {
         filesToSearch = [targetPath];
@@ -16739,7 +16996,7 @@ Examples:
         }
         filesSearched++;
         try {
-          const content = await fs14__default.readFile(file, "utf-8");
+          const content = await fs15__default.readFile(file, "utf-8");
           const lines = content.split("\n");
           let fileHasMatch = false;
           for (let i = 0; i < lines.length; i++) {
@@ -16762,7 +17019,7 @@ Examples:
                 contextAfter.push(lines[j] ?? "");
               }
               matches.push({
-                file: path15__default.relative(process.cwd(), file),
+                file: path16__default.relative(process.cwd(), file),
                 line: i + 1,
                 column: match.index + 1,
                 content: line,
@@ -16813,8 +17070,8 @@ Examples:
   }),
   async execute({ file, pattern, caseSensitive }) {
     try {
-      const absolutePath = path15__default.resolve(file);
-      const content = await fs14__default.readFile(absolutePath, "utf-8");
+      const absolutePath = path16__default.resolve(file);
+      const content = await fs15__default.readFile(absolutePath, "utf-8");
       const lines = content.split("\n");
       const matches = [];
       const flags = caseSensitive ? "" : "i";
@@ -16830,6 +17087,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 }
@@ -16981,6 +17243,22 @@ Examples:
 var httpTools = [httpFetchTool, httpJsonTool];
 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 detectPackageManager(cwd) {
   const lockfiles = [
     { file: "pnpm-lock.yaml", pm: "pnpm" },
@@ -16990,7 +17268,7 @@ async function detectPackageManager(cwd) {
   ];
   for (const { file, pm } of lockfiles) {
     try {
-      await fs14__default.access(path15__default.join(cwd, file));
+      await fs15__default.access(path16__default.join(cwd, file));
       return pm;
     } catch {
     }
@@ -17073,7 +17351,7 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
@@ -17081,6 +17359,10 @@ ${message}
         duration: performance.now() - startTime,
         packageManager: pm
       };
+      if (!buildResult.success) {
+        buildResult.hint = getBuildHint(stderrBuffer || stdoutBuffer, "run_script");
+      }
+      return buildResult;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`Script '${script}' timed out after ${timeoutMs}ms`, {
@@ -17194,7 +17476,7 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
@@ -17202,6 +17484,10 @@ ${message}
         duration: performance.now() - startTime,
         packageManager: pm
       };
+      if (!buildResult.success) {
+        buildResult.hint = getBuildHint(stderrBuffer || stdoutBuffer, "install_deps");
+      }
+      return buildResult;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`Install timed out after ${timeoutMs}ms`, {
@@ -17255,7 +17541,7 @@ ${message}
     });
     try {
       try {
-        await fs14__default.access(path15__default.join(projectDir, "Makefile"));
+        await fs15__default.access(path16__default.join(projectDir, "Makefile"));
       } catch {
         throw new ToolError("No Makefile found in directory", { tool: "make" });
       }
@@ -17292,13 +17578,17 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
         exitCode: result.exitCode ?? 0,
         duration: performance.now() - startTime
       };
+      if (!buildResult.success) {
+        buildResult.hint = getBuildHint(stderrBuffer || stdoutBuffer, "make");
+      }
+      return buildResult;
     } catch (error) {
       if (error instanceof ToolError) throw error;
       if (error.timedOut) {
@@ -17391,13 +17681,17 @@ ${message}
         heartbeat.activity();
       });
       const result = await subprocess;
-      return {
+      const buildResult = {
         success: result.exitCode === 0,
         stdout: truncateOutput2(stdoutBuffer),
         stderr: truncateOutput2(stderrBuffer),
         exitCode: result.exitCode ?? 0,
         duration: performance.now() - startTime
       };
+      if (!buildResult.success) {
+        buildResult.hint = getBuildHint(stderrBuffer || stdoutBuffer, "tsc");
+      }
+      return buildResult;
     } catch (error) {
       if (error.timedOut) {
         throw new TimeoutError(`TypeScript compile timed out after ${timeoutMs}ms`, {
@@ -17452,7 +17746,7 @@ z.object({
 });
 
 // src/cli/repl/session.ts
-path15__default.dirname(CONFIG_PATHS.trustedTools);
+path16__default.dirname(CONFIG_PATHS.trustedTools);
 CONFIG_PATHS.trustedTools;
 
 // src/cli/repl/recommended-permissions.ts
@@ -17968,9 +18262,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);
@@ -18001,9 +18296,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) => ({
@@ -18037,9 +18333,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) => ({
@@ -18124,6 +18421,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)) {
@@ -18342,7 +18660,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"
         });
       }
@@ -18870,25 +19189,31 @@ 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
+      });
     }
   }
 });
 var diffTools = [showDiffTool];
 async function fileExists(filePath) {
   try {
-    await fs14__default.access(filePath);
+    await fs15__default.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
-async function fileExists2(path38) {
+async function fileExists2(path39) {
   try {
-    await access(path38);
+    await access(path39);
     return true;
   } catch {
     return false;
@@ -18978,7 +19303,7 @@ async function detectMaturity(cwd) {
   if (!hasLintConfig && hasPackageJson) {
     try {
       const pkgRaw = await import('fs/promises').then(
-        (fs36) => fs36.readFile(join(cwd, "package.json"), "utf-8")
+        (fs37) => fs37.readFile(join(cwd, "package.json"), "utf-8")
       );
       const pkg = JSON.parse(pkgRaw);
       if (pkg.scripts?.lint || pkg.scripts?.["lint:fix"]) {
@@ -19073,6 +19398,7 @@ function getGit3(cwd) {
 }
 async function getDiff(git, baseBranch, includeUncommitted) {
   const diffs = [];
+  const warnings = [];
   try {
     const branchDiff = await git.diff([`${baseBranch}...HEAD`]);
     if (branchDiff) diffs.push(branchDiff);
@@ -19081,6 +19407,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) {
@@ -19088,14 +19415,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 = [];
@@ -19143,7 +19472,7 @@ async function checkTestCoverage(diff, cwd) {
     );
     if (!hasTestChange) {
       const ext = src.path.match(/\.(ts|tsx|js|jsx)$/)?.[0] ?? ".ts";
-      const testExists = await fileExists(path15__default.join(cwd, `${baseName}.test${ext}`)) || await fileExists(path15__default.join(cwd, `${baseName}.spec${ext}`));
+      const testExists = await fileExists(path16__default.join(cwd, `${baseName}.test${ext}`)) || await fileExists(path16__default.join(cwd, `${baseName}.spec${ext}`));
       if (testExists) {
         if (src.additions >= TEST_COVERAGE_LARGE_CHANGE_THRESHOLD) {
           findings.push({
@@ -19288,10 +19617,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,
@@ -19305,6 +19638,10 @@ Examples:
           maturity: "new",
           diff
         };
+        if (diffWarnings.length > 0) {
+          emptyResult.warnings = diffWarnings;
+        }
+        return emptyResult;
       }
       const maturityInfo = await detectMaturity(projectDir);
       const maturity = maturityInfo.level;
@@ -19326,6 +19663,7 @@ Examples:
             }
           }
         } catch {
+          diffWarnings.push("Linter not available \u2014 code style was not checked.");
         }
       }
       allFindings.push(...getMaturityRecommendations(maturity, diff));
@@ -19338,7 +19676,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,
@@ -19352,6 +19690,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)}`,
@@ -19361,8 +19703,8 @@ Examples:
   }
 });
 var reviewTools = [reviewCodeTool];
-var fs23 = await import('fs/promises');
-var path25 = await import('path');
+var fs24 = await import('fs/promises');
+var path26 = await import('path');
 var { glob: glob14 } = await import('glob');
 var DEFAULT_MAX_FILES = 200;
 var LANGUAGE_EXTENSIONS = {
@@ -19388,7 +19730,7 @@ var DEFAULT_EXCLUDES = [
   "**/*.d.ts"
 ];
 function detectLanguage3(filePath) {
-  const ext = path25.extname(filePath).toLowerCase();
+  const ext = path26.extname(filePath).toLowerCase();
   for (const [lang, extensions] of Object.entries(LANGUAGE_EXTENSIONS)) {
     if (extensions.includes(ext)) return lang;
   }
@@ -19797,9 +20139,9 @@ Examples:
   }),
   async execute({ path: rootPath, include, exclude, languages, maxFiles, depth }) {
     const startTime = performance.now();
-    const absPath = path25.resolve(rootPath);
+    const absPath = path26.resolve(rootPath);
     try {
-      const stat2 = await fs23.stat(absPath);
+      const stat2 = await fs24.stat(absPath);
       if (!stat2.isDirectory()) {
         throw new ToolError(`Path is not a directory: ${absPath}`, {
           tool: "codebase_map"
@@ -19836,14 +20178,14 @@ Examples:
     let totalDefinitions = 0;
     let exportedSymbols = 0;
     for (const file of limitedFiles) {
-      const fullPath = path25.join(absPath, file);
+      const fullPath = path26.join(absPath, file);
       const language = detectLanguage3(file);
       if (!language) continue;
       if (languages && !languages.includes(language)) {
         continue;
       }
       try {
-        const content = await fs23.readFile(fullPath, "utf-8");
+        const content = await fs24.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;
@@ -19876,23 +20218,23 @@ Examples:
 });
 var codebaseMapTools = [codebaseMapTool];
 init_paths();
-var fs24 = await import('fs/promises');
-var path26 = await import('path');
+var fs25 = await import('fs/promises');
+var path27 = await import('path');
 var crypto2 = await import('crypto');
-var GLOBAL_MEMORIES_DIR = path26.join(COCO_HOME, "memories");
+var GLOBAL_MEMORIES_DIR = path27.join(COCO_HOME, "memories");
 var PROJECT_MEMORIES_DIR = ".coco/memories";
 var DEFAULT_MAX_MEMORIES = 1e3;
 async function ensureDir(dirPath) {
-  await fs24.mkdir(dirPath, { recursive: true });
+  await fs25.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 = path26.join(dir, "index.json");
+  const indexPath = path27.join(dir, "index.json");
   try {
-    const content = await fs24.readFile(indexPath, "utf-8");
+    const content = await fs25.readFile(indexPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return [];
@@ -19901,14 +20243,14 @@ async function loadIndex(scope) {
 async function saveIndex(scope, index) {
   const dir = getMemoriesDir(scope);
   await ensureDir(dir);
-  const indexPath = path26.join(dir, "index.json");
-  await fs24.writeFile(indexPath, JSON.stringify(index, null, 2), "utf-8");
+  const indexPath = path27.join(dir, "index.json");
+  await fs25.writeFile(indexPath, JSON.stringify(index, null, 2), "utf-8");
 }
 async function loadMemory(scope, id) {
   const dir = getMemoriesDir(scope);
-  const memPath = path26.join(dir, `${id}.json`);
+  const memPath = path27.join(dir, `${id}.json`);
   try {
-    const content = await fs24.readFile(memPath, "utf-8");
+    const content = await fs25.readFile(memPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -19917,8 +20259,8 @@ async function loadMemory(scope, id) {
 async function saveMemory(scope, memory) {
   const dir = getMemoriesDir(scope);
   await ensureDir(dir);
-  const memPath = path26.join(dir, `${memory.id}.json`);
-  await fs24.writeFile(memPath, JSON.stringify(memory, null, 2), "utf-8");
+  const memPath = path27.join(dir, `${memory.id}.json`);
+  await fs25.writeFile(memPath, JSON.stringify(memory, null, 2), "utf-8");
 }
 var createMemoryTool = defineTool({
   name: "create_memory",
@@ -20070,17 +20412,17 @@ Examples:
   }
 });
 var memoryTools = [createMemoryTool, recallMemoryTool, listMemoriesTool];
-var fs25 = await import('fs/promises');
+var fs26 = 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 fs25.mkdir(".coco", { recursive: true });
+  await fs26.mkdir(".coco", { recursive: true });
 }
 async function loadCheckpoints() {
   try {
-    const content = await fs25.readFile(CHECKPOINT_FILE, "utf-8");
+    const content = await fs26.readFile(CHECKPOINT_FILE, "utf-8");
     return JSON.parse(content);
   } catch {
     return [];
@@ -20088,7 +20430,7 @@ async function loadCheckpoints() {
 }
 async function saveCheckpoints(checkpoints) {
   await ensureCocoDir();
-  await fs25.writeFile(CHECKPOINT_FILE, JSON.stringify(checkpoints, null, 2), "utf-8");
+  await fs26.writeFile(CHECKPOINT_FILE, JSON.stringify(checkpoints, null, 2), "utf-8");
 }
 async function execGit(args) {
   const { execaCommand } = await import('execa');
@@ -20099,10 +20441,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() {
@@ -20220,8 +20563,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" }
       );
     }
@@ -20248,8 +20592,8 @@ Examples:
   }
 });
 var checkpointTools = [createCheckpointTool, restoreCheckpointTool, listCheckpointsTool];
-var fs26 = await import('fs/promises');
-var path27 = await import('path');
+var fs27 = await import('fs/promises');
+var path28 = await import('path');
 var { glob: glob15 } = await import('glob');
 var INDEX_DIR = ".coco/search-index";
 var DEFAULT_CHUNK_SIZE = 20;
@@ -20355,6 +20699,7 @@ function simpleEmbedding(text) {
   return vector;
 }
 var embedFn = null;
+var usingFallbackEmbedding = false;
 async function getEmbedding(text) {
   if (!embedFn) {
     try {
@@ -20369,26 +20714,27 @@ async function getEmbedding(text) {
       };
     } catch {
       embedFn = async (t) => simpleEmbedding(t);
+      usingFallbackEmbedding = true;
     }
   }
   return embedFn(text);
 }
 async function loadIndex2(indexDir) {
   try {
-    const indexPath = path27.join(indexDir, "index.json");
-    const content = await fs26.readFile(indexPath, "utf-8");
+    const indexPath = path28.join(indexDir, "index.json");
+    const content = await fs27.readFile(indexPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
 async function saveIndex2(indexDir, index) {
-  await fs26.mkdir(indexDir, { recursive: true });
-  const indexPath = path27.join(indexDir, "index.json");
-  await fs26.writeFile(indexPath, JSON.stringify(index), "utf-8");
+  await fs27.mkdir(indexDir, { recursive: true });
+  const indexPath = path28.join(indexDir, "index.json");
+  await fs27.writeFile(indexPath, JSON.stringify(index), "utf-8");
 }
 function isBinary(filePath) {
-  return BINARY_EXTENSIONS.has(path27.extname(filePath).toLowerCase());
+  return BINARY_EXTENSIONS.has(path28.extname(filePath).toLowerCase());
 }
 var semanticSearchTool = defineTool({
   name: "semantic_search",
@@ -20413,9 +20759,10 @@ Examples:
     const effectivePath = rootPath ?? ".";
     const effectiveMaxResults = maxResults ?? 10;
     const effectiveThreshold = threshold ?? 0.3;
-    const absPath = path27.resolve(effectivePath);
-    const indexDir = path27.join(absPath, INDEX_DIR);
+    const absPath = path28.resolve(effectivePath);
+    const indexDir = path28.join(absPath, INDEX_DIR);
     let index = reindex ? null : await loadIndex2(indexDir);
+    let warnings = [];
     if (!index) {
       const pattern = include ?? "**/*";
       const files = await glob15(pattern, {
@@ -20425,12 +20772,14 @@ Examples:
         absolute: false
       });
       const chunks = [];
+      let skippedFiles = 0;
+      let indexSaveWarning = "";
       for (const file of files) {
         if (isBinary(file)) continue;
-        const fullPath = path27.join(absPath, file);
+        const fullPath = path28.join(absPath, file);
         try {
-          const stat2 = await fs26.stat(fullPath);
-          const content = await fs26.readFile(fullPath, "utf-8");
+          const stat2 = await fs27.stat(fullPath);
+          const content = await fs27.readFile(fullPath, "utf-8");
           if (content.length > 1e5) continue;
           const fileChunks = chunkContent(content, DEFAULT_CHUNK_SIZE);
           for (const chunk of fileChunks) {
@@ -20445,6 +20794,7 @@ Examples:
             });
           }
         } catch {
+          skippedFiles++;
           continue;
         }
       }
@@ -20457,6 +20807,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);
@@ -20480,17 +20842,21 @@ 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];
-var fs27 = await import('fs/promises');
-var path28 = await import('path');
+var fs28 = await import('fs/promises');
+var path29 = await import('path');
 var { glob: glob16 } = await import('glob');
 async function parseClassRelationships(rootPath, include) {
   const pattern = include ?? "**/*.{ts,tsx,js,jsx}";
@@ -20503,7 +20869,7 @@ async function parseClassRelationships(rootPath, include) {
   const interfaces = [];
   for (const file of files.slice(0, 100)) {
     try {
-      const content = await fs27.readFile(path28.join(rootPath, file), "utf-8");
+      const content = await fs28.readFile(path29.join(rootPath, file), "utf-8");
       const lines = content.split("\n");
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -20622,14 +20988,14 @@ async function generateClassDiagram(rootPath, include) {
   };
 }
 async function generateArchitectureDiagram(rootPath) {
-  const entries = await fs27.readdir(rootPath, { withFileTypes: true });
+  const entries = await fs28.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 = path28.basename(rootPath);
+  const rootName = path29.basename(rootPath);
   lines.push(`  ROOT["${rootName}"]`);
   nodeCount++;
   for (const dir of dirs) {
@@ -20639,7 +21005,7 @@ async function generateArchitectureDiagram(rootPath) {
     nodeCount++;
     edgeCount++;
     try {
-      const subEntries = await fs27.readdir(path28.join(rootPath, dir.name), {
+      const subEntries = await fs28.readdir(path29.join(rootPath, dir.name), {
         withFileTypes: true
       });
       const subDirs = subEntries.filter(
@@ -20762,7 +21128,7 @@ Examples:
         tool: "generate_diagram"
       });
     }
-    const absPath = rootPath ? path28.resolve(rootPath) : process.cwd();
+    const absPath = rootPath ? path29.resolve(rootPath) : process.cwd();
     switch (type) {
       case "class":
         return generateClassDiagram(absPath, include);
@@ -20823,8 +21189,8 @@ Examples:
   }
 });
 var diagramTools = [generateDiagramTool];
-var fs28 = await import('fs/promises');
-var path29 = await import('path');
+var fs29 = await import('fs/promises');
+var path30 = await import('path');
 var DEFAULT_MAX_PAGES = 20;
 var MAX_FILE_SIZE = 50 * 1024 * 1024;
 function parsePageRange(rangeStr, totalPages) {
@@ -20859,9 +21225,9 @@ Examples:
   }),
   async execute({ path: filePath, pages, maxPages }) {
     const startTime = performance.now();
-    const absPath = path29.resolve(filePath);
+    const absPath = path30.resolve(filePath);
     try {
-      const stat2 = await fs28.stat(absPath);
+      const stat2 = await fs29.stat(absPath);
       if (!stat2.isFile()) {
         throw new ToolError(`Path is not a file: ${absPath}`, {
           tool: "read_pdf"
@@ -20892,7 +21258,7 @@ Examples:
     }
     try {
       const pdfParse = await import('pdf-parse');
-      const dataBuffer = await fs28.readFile(absPath);
+      const dataBuffer = await fs29.readFile(absPath);
       const pdfData = await pdfParse.default(dataBuffer, {
         max: maxPages
       });
@@ -20930,16 +21296,17 @@ 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 }
       );
     }
   }
 });
 var pdfTools = [readPdfTool];
-var fs29 = await import('fs/promises');
-var path30 = await import('path');
+var fs30 = await import('fs/promises');
+var path31 = 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 = {
@@ -20967,15 +21334,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 = path30.resolve(filePath);
+    const absPath = path31.resolve(filePath);
     const cwd = process.cwd();
-    if (!absPath.startsWith(cwd + path30.sep) && absPath !== cwd) {
+    if (!absPath.startsWith(cwd + path31.sep) && absPath !== cwd) {
       throw new ToolError(
         `Path traversal denied: '${filePath}' resolves outside the project directory`,
         { tool: "read_image" }
       );
     }
-    const ext = path30.extname(absPath).toLowerCase();
+    const ext = path31.extname(absPath).toLowerCase();
     if (!SUPPORTED_FORMATS.has(ext)) {
       throw new ToolError(
         `Unsupported image format '${ext}'. Supported: ${Array.from(SUPPORTED_FORMATS).join(", ")}`,
@@ -20983,7 +21350,7 @@ Examples:
       );
     }
     try {
-      const stat2 = await fs29.stat(absPath);
+      const stat2 = await fs30.stat(absPath);
       if (!stat2.isFile()) {
         throw new ToolError(`Path is not a file: ${absPath}`, {
           tool: "read_image"
@@ -21004,7 +21371,7 @@ Examples:
       if (error instanceof ToolError) throw error;
       throw error;
     }
-    const imageBuffer = await fs29.readFile(absPath);
+    const imageBuffer = await fs30.readFile(absPath);
     const base64 = imageBuffer.toString("base64");
     const mimeType = MIME_TYPES[ext] ?? "image/png";
     const selectedProvider = provider ?? "anthropic";
@@ -21096,10 +21463,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)}`,
@@ -21117,7 +21489,7 @@ Examples:
   }
 });
 var imageTools = [readImageTool];
-var path31 = await import('path');
+var path32 = await import('path');
 var DANGEROUS_PATTERNS = [
   /\bDROP\s+(?:TABLE|DATABASE|INDEX|VIEW)\b/i,
   /\bTRUNCATE\b/i,
@@ -21148,7 +21520,7 @@ Examples:
   async execute({ database, query, params, readonly: isReadonlyParam }) {
     const isReadonly = isReadonlyParam ?? true;
     const startTime = performance.now();
-    const absPath = path31.resolve(database);
+    const absPath = path32.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.",
@@ -21200,10 +21572,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
+      });
     }
   }
 });
@@ -21221,7 +21603,7 @@ Examples:
   }),
   async execute({ database, table }) {
     const startTime = performance.now();
-    const absPath = path31.resolve(database);
+    const absPath = path32.resolve(database);
     try {
       const { default: Database } = await import('better-sqlite3');
       const db = new Database(absPath, { readonly: true, fileMustExist: true });
@@ -21266,22 +21648,28 @@ 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
+      });
     }
   }
 });
 var databaseTools = [sqlQueryTool, inspectSchemaTool];
-var fs30 = await import('fs/promises');
-var path32 = await import('path');
+var fs31 = await import('fs/promises');
+var path33 = 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 fs30.readFile(filePath, "utf-8");
+  const content = await fs31.readFile(filePath, "utf-8");
   const lines = content.split("\n").length;
   const functions = [];
   const classes = [];
@@ -21385,10 +21773,10 @@ async function analyzeDirectory(dirPath) {
     try {
       const analysis = await analyzeFile(file, false);
       totalLines += analysis.lines;
-      const ext = path32.extname(file);
+      const ext = path33.extname(file);
       filesByType[ext] = (filesByType[ext] || 0) + 1;
       fileStats.push({
-        file: path32.relative(dirPath, file),
+        file: path33.relative(dirPath, file),
         lines: analysis.lines,
         complexity: analysis.complexity.cyclomatic
       });
@@ -21711,13 +22099,13 @@ ${completed.map((r) => `- ${r.agentId}: Success`).join("\n")}`;
   }
 });
 var agentCoordinatorTools = [createAgentPlanTool, delegateTaskTool, aggregateResultsTool];
-var fs31 = await import('fs/promises');
+var fs32 = 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 fs31.readFile(filePath, "utf-8");
+  const content = await fs32.readFile(filePath, "utf-8");
   const lines = content.split("\n");
   const suggestions = [];
   for (let i = 0; i < lines.length; i++) {
@@ -21809,7 +22197,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 fs31.access(testPath);
+        await fs32.access(testPath);
       } catch {
         suggestions.push({
           type: "testing",
@@ -21866,7 +22254,7 @@ var calculateCodeScoreTool = defineTool({
   async execute(input) {
     const { filePath } = input;
     const suggestions = await analyzeAndSuggest(filePath);
-    const content = await fs31.readFile(filePath, "utf-8");
+    const content = await fs32.readFile(filePath, "utf-8");
     const lines = content.split("\n");
     const nonEmptyLines = lines.filter((l) => l.trim()).length;
     let score = 100;
@@ -21900,8 +22288,8 @@ var calculateCodeScoreTool = defineTool({
   }
 });
 var smartSuggestionsTools = [suggestImprovementsTool, calculateCodeScoreTool];
-var fs32 = await import('fs/promises');
-var path33 = await import('path');
+var fs33 = await import('fs/promises');
+var path34 = await import('path');
 var ContextMemoryStore = class {
   items = /* @__PURE__ */ new Map();
   learnings = /* @__PURE__ */ new Map();
@@ -21913,7 +22301,7 @@ var ContextMemoryStore = class {
   }
   async load() {
     try {
-      const content = await fs32.readFile(this.storePath, "utf-8");
+      const content = await fs33.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 || {}));
@@ -21921,15 +22309,15 @@ var ContextMemoryStore = class {
     }
   }
   async save() {
-    const dir = path33.dirname(this.storePath);
-    await fs32.mkdir(dir, { recursive: true });
+    const dir = path34.dirname(this.storePath);
+    await fs33.mkdir(dir, { recursive: true });
     const data = {
       sessionId: this.sessionId,
       items: Object.fromEntries(this.items),
       learnings: Object.fromEntries(this.learnings),
       savedAt: Date.now()
     };
-    await fs32.writeFile(this.storePath, JSON.stringify(data, null, 2));
+    await fs33.writeFile(this.storePath, JSON.stringify(data, null, 2));
   }
   addContext(id, item) {
     this.items.set(id, item);
@@ -22094,11 +22482,11 @@ var contextEnhancerTools = [
   recordLearningTool,
   getLearnedPatternsTool
 ];
-var fs33 = await import('fs/promises');
-var path34 = await import('path');
+var fs34 = await import('fs/promises');
+var path35 = await import('path');
 async function discoverSkills(skillsDir) {
   try {
-    const files = await fs33.readdir(skillsDir);
+    const files = await fs34.readdir(skillsDir);
     return files.filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
   } catch {
     return [];
@@ -22106,12 +22494,12 @@ async function discoverSkills(skillsDir) {
 }
 async function loadSkillMetadata(skillPath) {
   try {
-    const content = await fs33.readFile(skillPath, "utf-8");
+    const content = await fs34.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] || path34.basename(skillPath, path34.extname(skillPath)),
+      name: nameMatch?.[1] || path35.basename(skillPath, path35.extname(skillPath)),
       description: descMatch?.[1] || "No description",
       version: versionMatch?.[1] || "1.0.0",
       dependencies: []
@@ -22155,7 +22543,7 @@ var discoverSkillsTool = defineTool({
     const { skillsDir } = input;
     const skills = await discoverSkills(skillsDir);
     const metadata = await Promise.all(
-      skills.map((s) => loadSkillMetadata(path34.join(skillsDir, s)))
+      skills.map((s) => loadSkillMetadata(path35.join(skillsDir, s)))
     );
     return {
       skillsDir,
@@ -22656,8 +23044,8 @@ function hasNullByte2(str) {
 }
 function isBlockedPath(absolute) {
   for (const blocked of BLOCKED_PATHS2) {
-    const normalizedBlocked = path15__default.normalize(blocked);
-    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path15__default.sep)) {
+    const normalizedBlocked = path16__default.normalize(blocked);
+    if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path16__default.sep)) {
       return blocked;
     }
   }
@@ -22675,7 +23063,7 @@ function getInterpreter(ext) {
 }
 async function isExecutable(filePath) {
   try {
-    await fs14__default.access(filePath, fs14__default.constants.X_OK);
+    await fs15__default.access(filePath, fs15__default.constants.X_OK);
     return true;
   } catch {
     return false;
@@ -22715,7 +23103,7 @@ Examples:
       throw new ToolError("Invalid file path", { tool: "open_file" });
     }
     const workDir = cwd ?? process.cwd();
-    const absolute = path15__default.isAbsolute(filePath) ? path15__default.normalize(filePath) : path15__default.resolve(workDir, filePath);
+    const absolute = path16__default.isAbsolute(filePath) ? path16__default.normalize(filePath) : path16__default.resolve(workDir, filePath);
     const blockedBy = isBlockedPath(absolute);
     if (blockedBy) {
       throw new ToolError(`Access to system path '${blockedBy}' is not allowed`, {
@@ -22723,7 +23111,7 @@ Examples:
       });
     }
     try {
-      await fs14__default.access(absolute);
+      await fs15__default.access(absolute);
     } catch {
       throw new ToolError(`File not found: ${absolute}`, { tool: "open_file" });
     }
@@ -22738,14 +23126,14 @@ Examples:
       };
     }
     if (isBlockedExecFile(absolute)) {
-      throw new ToolError(`Execution of sensitive file is blocked: ${path15__default.basename(absolute)}`, {
+      throw new ToolError(`Execution of sensitive file is blocked: ${path16__default.basename(absolute)}`, {
         tool: "open_file"
       });
     }
     if (args.length > 0 && hasDangerousArgs(args)) {
       throw new ToolError("Arguments contain dangerous patterns", { tool: "open_file" });
     }
-    const ext = path15__default.extname(absolute);
+    const ext = path16__default.extname(absolute);
     const interpreter = getInterpreter(ext);
     const executable = await isExecutable(absolute);
     let command;
@@ -22758,7 +23146,7 @@ Examples:
       cmdArgs = [...args];
     } else {
       throw new ToolError(
-        `Cannot execute '${path15__default.basename(absolute)}': no known interpreter for '${ext || "(no extension)"}' and file is not executable`,
+        `Cannot execute '${path16__default.basename(absolute)}': no known interpreter for '${ext || "(no extension)"}' and file is not executable`,
         { tool: "open_file" }
       );
     }
@@ -22810,7 +23198,7 @@ Examples:
     reason: z.string().optional().describe("Why access is needed (shown to user for context)")
   }),
   async execute({ path: dirPath, reason }) {
-    const absolute = path15__default.resolve(dirPath);
+    const absolute = path16__default.resolve(dirPath);
     if (isWithinAllowedPath(absolute, "read")) {
       return {
         authorized: true,
@@ -22819,8 +23207,8 @@ Examples:
       };
     }
     for (const blocked of BLOCKED_SYSTEM_PATHS) {
-      const normalizedBlocked = path15__default.normalize(blocked);
-      if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path15__default.sep)) {
+      const normalizedBlocked = path16__default.normalize(blocked);
+      if (absolute === normalizedBlocked || absolute.startsWith(normalizedBlocked + path16__default.sep)) {
         return {
           authorized: false,
           path: absolute,
@@ -22829,7 +23217,7 @@ Examples:
       }
     }
     const cwd = process.cwd();
-    if (absolute === path15__default.normalize(cwd) || absolute.startsWith(path15__default.normalize(cwd) + path15__default.sep)) {
+    if (absolute === path16__default.normalize(cwd) || absolute.startsWith(path16__default.normalize(cwd) + path16__default.sep)) {
       return {
         authorized: true,
         path: absolute,
@@ -22837,7 +23225,7 @@ Examples:
       };
     }
     try {
-      const stat2 = await fs14__default.stat(absolute);
+      const stat2 = await fs15__default.stat(absolute);
       if (!stat2.isDirectory()) {
         return {
           authorized: false,
@@ -22853,7 +23241,7 @@ Examples:
       };
     }
     const existing = getAllowedPaths();
-    if (existing.some((e) => path15__default.normalize(e.path) === path15__default.normalize(absolute))) {
+    if (existing.some((e) => path16__default.normalize(e.path) === path16__default.normalize(absolute))) {
       return {
         authorized: true,
         path: absolute,