debug-run 0.5.7 → 0.5.9

package/.claude/skills/debug-run/SKILL.md

@@ -34,6 +34,25 @@ Check available adapters:
 npx debug-run list-adapters
 ```
 
+## Installing the Skill
+
+To install this skill for AI coding assistants:
+
+```bash
+# Install to Claude Code (~/.claude/skills/)
+npx debug-run install-skill --claude
+
+# Install to GitHub Copilot (~/.copilot/skills/)
+npx debug-run install-skill --copilot
+
+# Install to project directory (for project-specific skills)
+npx debug-run install-skill --claude --project
+npx debug-run install-skill --copilot --project
+
+# Install to custom directory
+npx debug-run install-skill --dir /path/to/skills
+```
+
 ## Language-Specific Guides
 
 For detailed setup, examples, and troubleshooting for each language:

package/README.md

@@ -143,6 +143,8 @@ Options:
   --attach                          Attach to running process
   --pid <id>                        Process ID to attach to
   --env <key=value...>              Environment variables
+  --compact                         Enable compact output for reduced token usage
+  --stack-limit <N>                 Max stack frames to include (default: 3 in compact)
 
 Commands:
   list-adapters                     List available debug adapters
@@ -178,6 +180,35 @@ debug-run outputs newline-delimited JSON (NDJSON) events:
 {"type":"session_end","summary":{"breakpointsHit":1,"duration":1234}}
 ```
 
+### Breakpoint Set Event (with Diagnostics)
+
+When a breakpoint cannot be verified (e.g., source mapping issues, missing debug symbols), the event includes actionable diagnostics:
+
+```json
+{
+  "type": "breakpoint_set",
+  "id": 1,
+  "file": "src/handler.ts",
+  "line": 45,
+  "verified": false,
+  "message": "Could not resolve source location",
+  "diagnostics": {
+    "requestedFile": "src/handler.ts",
+    "requestedLine": 45,
+    "adapterMessage": "Could not resolve source location",
+    "suggestions": [
+      "Ensure \"sourceMap\": true in tsconfig.json",
+      "Rebuild with source maps: tsc --sourceMap (or your build command)",
+      "Verify .map files exist in your output directory (e.g., dist/**/*.map)"
+    ],
+    "adapterType": "node",
+    "fileExtension": ".ts"
+  }
+}
+```
+
+Suggestions are context-aware based on the adapter and file type.
+
 ### Breakpoint Hit Event
 
 ```json
@@ -307,6 +338,35 @@ When an assertion fails, you get an `assertion_failed` event with:
 
 Assertions are checked at breakpoints, during stepping, and during trace mode.
 
+### Compact output mode (for AI agents)
+
+Reduce token usage by 40-60% with compact output:
+
+```bash
+npx debug-run ./app.dll \
+  -a dotnet \
+  -b "src/OrderService.cs:45" \
+  --compact \
+  --pretty
+```
+
+Compact mode applies these optimizations:
+- **Stack trace limiting**: Only top 3 frames by default (configurable with `--stack-limit`)
+- **Internal frame filtering**: Removes node_modules, runtime internals, webpack frames
+- **Path abbreviation**: `~/project/src/file.ts` instead of `/Users/name/project/src/file.ts`
+- **Variable diffing**: On repeated breakpoint hits, only reports changed variables (`_diff` key)
+- **Trace path collapsing**: Consecutive identical locations collapsed to `functionName (x5)`
+
+Example compact output vs verbose:
+
+```json
+// Compact (~60 tokens)
+{"type":"breakpoint_hit","location":{"file":".../src/OrderService.cs","line":45,"function":"ProcessOrder"},"stackTrace":[{"function":"ProcessOrder","file":".../src/OrderService.cs","line":45}],"locals":{"order":{"type":"OrderDto","value":{"Id":"abc-123","Total":150}}}}
+
+// Verbose (~180 tokens)
+{"type":"breakpoint_hit","timestamp":"2025-01-15T10:30:01.234Z","id":1,"threadId":1,"location":{"file":"/home/user/project/src/OrderService.cs","line":45,"column":12,"function":"ProcessOrder","module":"MyApp"},"stackTrace":[{"frameId":1,"function":"ProcessOrder","file":"/home/user/project/src/OrderService.cs","line":45,"column":12,"module":"MyApp"},{"frameId":2,"function":"Main","file":"/home/user/project/src/Program.cs","line":10,"column":5},...],"locals":{"order":{"type":"OrderDto","value":{"Id":"abc-123","Total":150,"CreatedAt":"2025-01-15T00:00:00Z","Status":"pending",...}},"this":{...}}}
+```
+
 ### Trace mode (follow execution path)
 
 Automatically step through code after hitting a breakpoint:

package/dist/index.cjs

@@ -3066,7 +3066,6 @@ var path = __toESM(require("node:path"), 1);
 var os = __toESM(require("node:os"), 1);
 var import_promises2 = require("node:stream/promises");
 var import_node_stream = require("node:stream");
-var import_node_url = require("node:url");
 var execAsync = (0, import_node_util.promisify)(import_node_child_process.exec);
 var NETCOREDBG_VERSION = "3.1.3-1062";
 var NETCOREDBG_BASE_URL = `https://github.com/Samsung/netcoredbg/releases/download/${NETCOREDBG_VERSION}`;
@@ -3119,10 +3118,14 @@ function getDownloadUrl() {
   const filename = `netcoredbg-${info.os}-${info.arch}.${info.archiveExt}`;
   return `${NETCOREDBG_BASE_URL}/${filename}`;
 }
+function getDebugRunHome() {
+  if (process.env.DEBUG_RUN_HOME) {
+    return process.env.DEBUG_RUN_HOME;
+  }
+  return path.join(os.homedir(), ".debug-run");
+}
 function getAdaptersDir() {
-  const currentFilePath = (0, import_node_url.fileURLToPath)(__importMetaUrl);
-  const packageRoot = path.resolve(path.dirname(currentFilePath), "..", "..");
-  return path.join(packageRoot, "bin", "adapters");
+  return path.join(getDebugRunHome(), "adapters");
 }
 function getNetcoredbgPath() {
   const info = getPlatformInfo();
@@ -3144,6 +3147,9 @@ async function installNetcoredbg(onProgress) {
   if (!response.ok) {
     throw new Error(`Failed to download netcoredbg: ${response.statusText}`);
   }
+  if (!response.body) {
+    throw new Error("Response body is null");
+  }
   const fileStream = (0, import_node_fs.createWriteStream)(archivePath);
   await (0, import_promises2.pipeline)(import_node_stream.Readable.fromWeb(response.body), fileStream);
   log("Extracting...");
@@ -3177,6 +3183,9 @@ async function installJsDebug(onProgress) {
   if (!response.ok) {
     throw new Error(`Failed to download js-debug: ${response.statusText}`);
   }
+  if (!response.body) {
+    throw new Error("Response body is null");
+  }
   const fileStream = (0, import_node_fs.createWriteStream)(archivePath);
   await (0, import_promises2.pipeline)(import_node_stream.Readable.fromWeb(response.body), fileStream);
   log("Extracting...");
@@ -3294,7 +3303,7 @@ function findVsdbg() {
     const arch3 = os2.arch();
     const vsdbgDirs = [];
     if (platform3 === "win32") {
-      vsdbgDirs.push("vsdbg", "win32", "x64", "x86");
+      vsdbgDirs.push("vsdbg", "win32", "x64", "x86", "x86_64");
     } else if (platform3 === "darwin") {
       vsdbgDirs.push(
         arch3 === "arm64" ? "arm64" : "x86_64",
@@ -3356,6 +3365,13 @@ function findVsdbg() {
   return null;
 }
 function findDebugpy() {
+  const debugpyExt = findExtension("ms-python.debugpy");
+  if (debugpyExt) {
+    const debugpyPath = path3.join(debugpyExt, "bundled", "libs", "debugpy");
+    if ((0, import_node_fs2.existsSync)(debugpyPath)) {
+      return debugpyPath;
+    }
+  }
   const pythonExt = findExtension("ms-python.python");
   if (pythonExt) {
     const possiblePaths = [
@@ -3517,6 +3533,16 @@ var debugpyAdapter = {
   get args() {
     return ["-m", "debugpy.adapter"];
   },
+  get env() {
+    if (cachedSource === "vscode" && cachedDebugpyPath) {
+      const debugpyParentDir = path5.dirname(cachedDebugpyPath);
+      const existingPythonPath = process.env.PYTHONPATH || "";
+      return {
+        PYTHONPATH: existingPythonPath ? `${debugpyParentDir}:${existingPythonPath}` : debugpyParentDir
+      };
+    }
+    return void 0;
+  },
   detect: async () => {
     const pythonCmd = await findPythonCommand();
     if (!pythonCmd) {
@@ -3957,7 +3983,7 @@ var DapTransport = class extends import_node_events.EventEmitter {
       command,
       arguments: args
     };
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve9, reject) => {
       const timeout = setTimeout(() => {
         this.pendingRequests.delete(seq);
         reject(new Error(`Request '${command}' timed out after ${this.requestTimeout}ms`));
@@ -3966,7 +3992,7 @@ var DapTransport = class extends import_node_events.EventEmitter {
         resolve: (response) => {
           clearTimeout(timeout);
           if (response.success) {
-            resolve10(response.body);
+            resolve9(response.body);
           } else {
             reject(new Error(response.message || `Request '${command}' failed`));
           }
@@ -4272,8 +4298,8 @@ var DapClient = class extends import_node_events2.EventEmitter {
   async initialize(args = {}) {
     this.ensureConnected();
     let initializedResolve;
-    const initializedPromise = new Promise((resolve10) => {
-      initializedResolve = resolve10;
+    const initializedPromise = new Promise((resolve9) => {
+      initializedResolve = resolve9;
     });
     this.once("initialized", () => initializedResolve());
     const response = await this.transport.sendRequest("initialize", {
@@ -4291,7 +4317,7 @@ var DapClient = class extends import_node_events2.EventEmitter {
     });
     this.capabilities = response?.capabilities || response || {};
     const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error("Timeout waiting for initialized event")), 1e4);
+      setTimeout(() => reject(new Error("Timeout waiting for initialized event")), 500);
     });
     try {
       await Promise.race([initializedPromise, timeoutPromise]);
@@ -4484,7 +4510,7 @@ var SocketDapTransport = class extends import_node_events3.EventEmitter {
    * Connect to the DAP server
    */
   async connect() {
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve9, reject) => {
       this.socket = (0, import_node_net.connect)({
         host: this.options.host,
         port: this.options.port
@@ -4496,7 +4522,7 @@ var SocketDapTransport = class extends import_node_events3.EventEmitter {
       const onConnect = () => {
         this.socket?.removeListener("error", onError);
         this.setupSocket();
-        resolve10();
+        resolve9();
       };
       this.socket.once("error", onError);
       this.socket.once("connect", onConnect);
@@ -4530,7 +4556,7 @@ var SocketDapTransport = class extends import_node_events3.EventEmitter {
       command,
       arguments: args
     };
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve9, reject) => {
       const timeout = setTimeout(() => {
         this.pendingRequests.delete(seq);
         reject(new Error(`Request '${command}' timed out after ${this.requestTimeout}ms`));
@@ -4539,7 +4565,7 @@ var SocketDapTransport = class extends import_node_events3.EventEmitter {
         resolve: (response) => {
           clearTimeout(timeout);
           if (response.success) {
-            resolve10(response.body);
+            resolve9(response.body);
           } else {
             reject(new Error(response.message || `Request '${command}' failed`));
           }
@@ -4721,7 +4747,7 @@ var SocketDapClient = class extends import_node_events4.EventEmitter {
       this.emit("serverError", error);
     });
     const delay = this.options.connectDelay ?? 1e3;
-    await new Promise((resolve10) => setTimeout(resolve10, delay));
+    await new Promise((resolve9) => setTimeout(resolve9, delay));
     this.transport = new SocketDapTransport({
       host: this.options.host || "localhost",
       port: this.options.port,
@@ -5060,20 +5086,20 @@ var SocketDapClient = class extends import_node_events4.EventEmitter {
     if (process.env.DEBUG_DAP) {
       console.error("[DAP child] Initialize response received, waiting for initialized event...");
     }
-    await new Promise((resolve10) => {
+    await new Promise((resolve9) => {
       let resolved = false;
       const onInitialized = () => {
         if (resolved) return;
         resolved = true;
         this.childTransport?.removeListener("event:initialized", onInitialized);
-        resolve10();
+        resolve9();
       };
       this.childTransport.on("event:initialized", onInitialized);
       setTimeout(() => {
         if (resolved) return;
         resolved = true;
         this.childTransport?.removeListener("event:initialized", onInitialized);
-        resolve10();
+        resolve9();
       }, 500);
     });
     if (process.env.DEBUG_DAP) {
@@ -5112,16 +5138,38 @@ var SocketDapClient = class extends import_node_events4.EventEmitter {
 };
 
 // src/output/formatter.ts
+var INTERNAL_PATTERNS = [
+  /^node:/,
+  /node_modules/,
+  /internal\//,
+  /<anonymous>/,
+  /^native /,
+  /\[native code\]/,
+  /webpack:/,
+  /^async /,
+  /^Module\./,
+  /processTicksAndRejections/,
+  /^RunMain$/,
+  /^bootstrap_node\.js$/,
+  /^_compile$/,
+  /^\.js$/
+];
 var OutputFormatter = class {
   stream;
   pretty;
   include;
   exclude;
+  compact;
+  stackLimit;
+  /** Track previous locals for variable diffing in compact mode */
+  previousLocals = {};
   constructor(options = {}) {
     this.stream = options.stream ?? process.stdout;
     this.pretty = options.pretty ?? false;
     this.include = options.include ? new Set(options.include) : void 0;
     this.exclude = options.exclude ? new Set(options.exclude) : void 0;
+    this.compact = options.compact ?? false;
+    this.stackLimit = options.stackLimit ?? (options.compact ? 3 : Infinity);
   }
   /**
    * Check if an event type should be emitted based on include/exclude filters
@@ -5142,9 +5190,248 @@ var OutputFormatter = class {
     if (!this.shouldEmit(event.type)) {
       return;
     }
-    const json = this.pretty ? JSON.stringify(event, null, 2) : JSON.stringify(event);
+    const outputEvent = this.compact ? this.compactifyEvent(event) : event;
+    const json = this.pretty ? JSON.stringify(outputEvent, null, 2) : JSON.stringify(outputEvent);
     this.stream.write(json + "\n");
   }
+  /**
+   * Check if a stack frame is an internal/runtime frame
+   */
+  isInternalFrame(frame) {
+    const file = frame.file ?? "";
+    const fn = frame.function ?? "";
+    return INTERNAL_PATTERNS.some((pattern) => pattern.test(file) || pattern.test(fn));
+  }
+  /**
+   * Filter and limit stack frames for compact output
+   */
+  compactifyStackTrace(frames) {
+    const userFrames = frames.filter((frame) => !this.isInternalFrame(frame));
+    const relevantFrames = userFrames.length > 0 ? userFrames : frames.slice(0, 1);
+    const limitedFrames = relevantFrames.slice(0, this.stackLimit);
+    return limitedFrames.map((frame) => ({
+      ...frame,
+      file: frame.file ? this.abbreviatePath(frame.file) : null
+    }));
+  }
+  /**
+   * Abbreviate a file path for compact output
+   */
+  abbreviatePath(filePath) {
+    let abbreviated = filePath;
+    const nodeModulesMatch = abbreviated.match(/node_modules\/(.+)/);
+    if (nodeModulesMatch) {
+      const modulePath = nodeModulesMatch[1];
+      const moduleSegments = modulePath.split("/");
+      if (moduleSegments.length > 3) {
+        abbreviated = `<node_modules>/${moduleSegments.slice(0, 2).join("/")}/...`;
+      } else {
+        abbreviated = `<node_modules>/${modulePath}`;
+      }
+      return abbreviated;
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    if (homeDir && abbreviated.startsWith(homeDir)) {
+      abbreviated = "~" + abbreviated.slice(homeDir.length);
+    }
+    const segments = abbreviated.split("/");
+    if (segments.length > 4) {
+      abbreviated = ".../" + segments.slice(-3).join("/");
+    }
+    return abbreviated;
+  }
+  /**
+   * Abbreviate a source location for compact output
+   */
+  compactifyLocation(location) {
+    return {
+      ...location,
+      file: this.abbreviatePath(location.file),
+      // Remove module in compact mode as it's often redundant
+      module: void 0
+    };
+  }
+  /**
+   * Compact locals by computing diff from previous state
+   * Returns only changed variables
+   */
+  compactifyLocals(locals) {
+    const isFirstCapture = Object.keys(this.previousLocals).length === 0;
+    if (isFirstCapture) {
+      this.previousLocals = { ...locals };
+      return this.abbreviateLocals(locals);
+    }
+    const diff = {};
+    let hasChanges = false;
+    for (const [name, value] of Object.entries(locals)) {
+      const previousValue = this.previousLocals[name];
+      const currentJson = JSON.stringify(value);
+      const previousJson = previousValue !== void 0 ? JSON.stringify(previousValue) : void 0;
+      if (currentJson !== previousJson) {
+        diff[name] = value;
+        hasChanges = true;
+      }
+    }
+    for (const name of Object.keys(this.previousLocals)) {
+      if (!(name in locals)) {
+        hasChanges = true;
+        diff[name] = { type: "deleted", value: null };
+      }
+    }
+    this.previousLocals = { ...locals };
+    if (hasChanges) {
+      return { _diff: this.abbreviateLocals(diff) };
+    }
+    return {};
+  }
+  /**
+   * Abbreviate local variable values for compact output
+   */
+  abbreviateLocals(locals) {
+    const abbreviated = {};
+    for (const [name, value] of Object.entries(locals)) {
+      abbreviated[name] = this.abbreviateValue(value);
+    }
+    return abbreviated;
+  }
+  /**
+   * Abbreviate a single variable value for compact output
+   */
+  abbreviateValue(value) {
+    if (typeof value.value === "string" && value.value.length > 100) {
+      return {
+        ...value,
+        value: value.value.slice(0, 100) + "..."
+      };
+    }
+    if (Array.isArray(value.value) && value.value.length > 5) {
+      const abbreviated = value.value.slice(0, 3);
+      return {
+        ...value,
+        value: `[${abbreviated.join(", ")}, ... (${value.value.length} items)]`
+      };
+    }
+    return value;
+  }
+  /**
+   * Apply compact transformations to an event
+   */
+  compactifyEvent(event) {
+    switch (event.type) {
+      case "breakpoint_hit": {
+        const compacted = {
+          ...event,
+          location: this.compactifyLocation(event.location),
+          stackTrace: this.compactifyStackTrace(event.stackTrace)
+        };
+        if (event.locals && Object.keys(event.locals).length > 0) {
+          const compactedLocals = this.compactifyLocals(event.locals);
+          compacted.locals = compactedLocals;
+        }
+        return compacted;
+      }
+      case "exception_thrown": {
+        const compacted = {
+          ...event,
+          location: this.compactifyLocation(event.location)
+        };
+        if (event.exception.stackTrace) {
+          compacted.exception = {
+            ...event.exception,
+            stackTrace: this.abbreviateStackTraceString(event.exception.stackTrace)
+          };
+        }
+        if (event.locals && Object.keys(event.locals).length > 0) {
+          const compactedLocals = this.compactifyLocals(event.locals);
+          compacted.locals = compactedLocals;
+        }
+        return compacted;
+      }
+      case "step_completed": {
+        return {
+          ...event,
+          location: this.compactifyLocation(event.location),
+          stackTrace: this.compactifyStackTrace(event.stackTrace),
+          locals: this.abbreviateLocals(event.locals)
+        };
+      }
+      case "trace_step": {
+        return {
+          ...event,
+          location: this.compactifyLocation(event.location)
+        };
+      }
+      case "trace_completed": {
+        const compactedPath = event.path.map((loc) => this.compactifyLocation(loc));
+        const collapsedPath = [];
+        let repeatCount = 1;
+        for (let i = 0; i < compactedPath.length; i++) {
+          const current = compactedPath[i];
+          const next = compactedPath[i + 1];
+          if (next && current.file === next.file && current.line === next.line && current.function === next.function) {
+            repeatCount++;
+          } else {
+            if (repeatCount > 1) {
+              collapsedPath.push({
+                ...current,
+                function: `${current.function} (x${repeatCount})`
+              });
+            } else {
+              collapsedPath.push(current);
+            }
+            repeatCount = 1;
+          }
+        }
+        return {
+          ...event,
+          path: collapsedPath,
+          finalLocation: this.compactifyLocation(event.finalLocation),
+          stackTrace: this.compactifyStackTrace(event.stackTrace),
+          locals: this.abbreviateLocals(event.locals)
+        };
+      }
+      case "assertion_failed": {
+        return {
+          ...event,
+          location: this.compactifyLocation(event.location),
+          stackTrace: this.compactifyStackTrace(event.stackTrace),
+          locals: this.abbreviateLocals(event.locals)
+        };
+      }
+      case "session_start": {
+        const compacted = { ...event };
+        if (compacted.program) {
+          compacted.program = this.abbreviatePath(compacted.program);
+        }
+        if (compacted.cwd) {
+          compacted.cwd = this.abbreviatePath(compacted.cwd);
+        }
+        return compacted;
+      }
+      default:
+        return event;
+    }
+  }
+  /**
+   * Abbreviate a stack trace string (from exception)
+   */
+  abbreviateStackTraceString(stackTrace) {
+    const lines = stackTrace.split("\n");
+    const userLines = lines.filter((line) => {
+      return !INTERNAL_PATTERNS.some((pattern) => pattern.test(line));
+    });
+    const limitedLines = userLines.slice(0, this.stackLimit);
+    return limitedLines.map((line) => this.abbreviatePathsInLine(line)).join("\n");
+  }
+  /**
+   * Abbreviate file paths within a line of text
+   */
+  abbreviatePathsInLine(line) {
+    return line.replace(/(?:at\s+)?(\/[^\s:]+)/g, (match, path12) => {
+      const abbreviated = this.abbreviatePath(path12);
+      return match.replace(path12, abbreviated);
+    });
+  }
   /**
    * Create an event with timestamp
    */
@@ -5189,7 +5476,7 @@ var OutputFormatter = class {
   /**
    * Emit a breakpoint_set event
    */
-  breakpointSet(id, file, line, verified, condition, message) {
+  breakpointSet(id, file, line, verified, condition, message, diagnostics) {
     this.emit(
       this.createEvent("breakpoint_set", {
         id,
@@ -5197,7 +5484,8 @@ var OutputFormatter = class {
         line,
         verified,
         condition,
-        message
+        message,
+        diagnostics
       })
     );
   }
@@ -5224,12 +5512,161 @@ function resolveBreakpointPath(file, options = {}) {
   if (options.cwd) {
     return path10.resolve(options.cwd, file);
   }
-  if (options.programPath) {
-    const programDir = path10.dirname(options.programPath);
-    return path10.resolve(programDir, file);
-  }
   return path10.resolve(file);
 }
+function validateBreakpointSpec(spec) {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: "Breakpoint specification cannot be empty",
+      spec
+    };
+  }
+  if (!trimmed.includes(":")) {
+    return {
+      valid: false,
+      error: `Invalid breakpoint format "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  const match = trimmed.match(/^(.+):(\d+)(?:\?(.+)|#(\d+))?$/);
+  if (!match) {
+    const colonIdx = trimmed.lastIndexOf(":");
+    if (colonIdx !== -1) {
+      const linePartRaw = trimmed.slice(colonIdx + 1);
+      const linePart = linePartRaw.split("?")[0].split("#")[0];
+      if (linePart === "") {
+        return {
+          valid: false,
+          error: `Missing line number in breakpoint "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+          spec
+        };
+      }
+      if (!/^\d+$/.test(linePart)) {
+        return {
+          valid: false,
+          error: `Invalid line number "${linePart}" in breakpoint "${spec}". Line must be a positive integer`,
+          spec
+        };
+      }
+    }
+    return {
+      valid: false,
+      error: `Invalid breakpoint format "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  const [, file, lineStr] = match;
+  const line = parseInt(lineStr, 10);
+  if (!file || !file.trim()) {
+    return {
+      valid: false,
+      error: `Missing file path in breakpoint "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  if (isNaN(line) || line < 1) {
+    return {
+      valid: false,
+      error: `Invalid line number "${lineStr}" in breakpoint "${spec}". Line must be a positive integer`,
+      spec
+    };
+  }
+  return { valid: true };
+}
+function validateLogpointSpec(spec) {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: "Logpoint specification cannot be empty",
+      spec
+    };
+  }
+  if (!trimmed.includes("|")) {
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const pipeIdx = trimmed.indexOf("|");
+  const beforePipe = trimmed.slice(0, pipeIdx);
+  if (!beforePipe.includes(":")) {
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const match = trimmed.match(/^(.+):(\d+)\|(.+)$/);
+  if (!match) {
+    const colonIdx = beforePipe.lastIndexOf(":");
+    if (colonIdx !== -1) {
+      const linePart = beforePipe.slice(colonIdx + 1);
+      if (linePart === "") {
+        return {
+          valid: false,
+          error: `Missing line number in logpoint "${spec}". Expected "file:line|message"`,
+          spec
+        };
+      }
+      if (!/^\d+$/.test(linePart)) {
+        return {
+          valid: false,
+          error: `Invalid line number "${linePart}" in logpoint "${spec}". Line must be a positive integer`,
+          spec
+        };
+      }
+    }
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const [, file, lineStr, message] = match;
+  const line = parseInt(lineStr, 10);
+  if (!file || !file.trim()) {
+    return {
+      valid: false,
+      error: `Missing file path in logpoint "${spec}". Expected "file:line|message"`,
+      spec
+    };
+  }
+  if (isNaN(line) || line < 1) {
+    return {
+      valid: false,
+      error: `Invalid line number "${lineStr}" in logpoint "${spec}". Line must be a positive integer`,
+      spec
+    };
+  }
+  if (!message || !message.trim()) {
+    return {
+      valid: false,
+      error: `Missing log message in logpoint "${spec}". Expected "file:line|message"`,
+      spec
+    };
+  }
+  return { valid: true };
+}
+function validateAllBreakpoints(breakpoints, logpoints = []) {
+  const errors = [];
+  for (const bp of breakpoints) {
+    const result = validateBreakpointSpec(bp);
+    if (!result.valid && result.error) {
+      errors.push(result.error);
+    }
+  }
+  for (const lp of logpoints) {
+    const result = validateLogpointSpec(lp);
+    if (!result.valid && result.error) {
+      errors.push(result.error);
+    }
+  }
+  return errors;
+}
 function parseBreakpointSpec(spec, pathOptions = {}) {
   const match = spec.match(/^(.+):(\d+)(?:\?(.+)|#(\d+))?$/);
   if (!match) {
@@ -5271,10 +5708,12 @@ var BreakpointManager = class {
   breakpoints = /* @__PURE__ */ new Map();
   nextId = 1;
   pathOptions;
-  constructor(client, formatter, pathOptions = {}) {
+  adapterType;
+  constructor(client, formatter, options = {}) {
     this.client = client;
     this.formatter = formatter;
-    this.pathOptions = pathOptions;
+    this.pathOptions = options;
+    this.adapterType = options.adapterType;
   }
   /**
    * Add a breakpoint from a spec string
@@ -5321,6 +5760,7 @@ var BreakpointManager = class {
       hitCondition: spec.hitCondition,
       logMessage: spec.logMessage
     }));
+    const requestedLines = specs.map((spec) => spec.line);
     try {
       const response = await this.client.setBreakpoints({
         source: { path: file },
@@ -5333,22 +5773,34 @@ var BreakpointManager = class {
           specs[i].verified = bp.verified;
           specs[i].message = bp.message;
           specs[i].line = bp.line ?? specs[i].line;
+          const diagnostics = !bp.verified ? this.generateDiagnostics(file, requestedLines[i], bp.message) : void 0;
           this.formatter.breakpointSet(
             specs[i].id,
             file,
             specs[i].line,
             specs[i].verified,
             specs[i].condition,
-            specs[i].message
+            specs[i].message,
+            diagnostics
           );
         }
       }
     } catch (error) {
-      for (const spec of specs) {
+      for (let i = 0; i < specs.length; i++) {
+        const spec = specs[i];
         spec.id = this.nextId++;
         spec.verified = false;
         spec.message = error instanceof Error ? error.message : "Failed to set breakpoint";
-        this.formatter.breakpointSet(spec.id, file, spec.line, false, spec.condition, spec.message);
+        const diagnostics = this.generateDiagnostics(file, requestedLines[i], spec.message);
+        this.formatter.breakpointSet(
+          spec.id,
+          file,
+          spec.line,
+          false,
+          spec.condition,
+          spec.message,
+          diagnostics
+        );
       }
     }
   }
@@ -5378,7 +5830,103 @@ var BreakpointManager = class {
   getHitCount() {
     return 0;
   }
+  /**
+   * Generate diagnostics for an unverified breakpoint
+   */
+  generateDiagnostics(requestedFile, requestedLine, adapterMessage) {
+    const ext = path10.extname(requestedFile).toLowerCase();
+    const suggestions = getBreakpointSuggestions(this.adapterType, ext, adapterMessage);
+    return {
+      requestedFile,
+      requestedLine,
+      adapterMessage,
+      suggestions,
+      adapterType: this.adapterType,
+      fileExtension: ext || void 0
+    };
+  }
 };
+function normalizeAdapterType(adapterType) {
+  if (!adapterType) return void 0;
+  const lower = adapterType.toLowerCase();
+  if (["dotnet", "coreclr", "vsdbg", "netcoredbg"].includes(lower)) {
+    return "coreclr";
+  }
+  if (["node", "nodejs", "javascript", "js", "typescript", "ts"].includes(lower)) {
+    return "node";
+  }
+  if (["debugpy", "python", "py"].includes(lower)) {
+    return "python";
+  }
+  if (["lldb", "codelldb", "cpp", "c", "rust"].includes(lower)) {
+    return "lldb";
+  }
+  return lower;
+}
+function getBreakpointSuggestions(adapterType, fileExtension, adapterMessage) {
+  const suggestions = [];
+  const normalizedAdapter = normalizeAdapterType(adapterType);
+  const ext = fileExtension.toLowerCase();
+  const msgLower = (adapterMessage || "").toLowerCase();
+  const isSourceMapIssue = msgLower.includes("source map") || msgLower.includes("sourcemap") || msgLower.includes("cannot find");
+  const isPathIssue = msgLower.includes("not found") || msgLower.includes("cannot find file") || msgLower.includes("does not exist");
+  if (normalizedAdapter === "node") {
+    if (ext === ".ts" || ext === ".tsx") {
+      suggestions.push('Ensure "sourceMap": true in tsconfig.json');
+      suggestions.push("Rebuild with source maps: tsc --sourceMap (or your build command)");
+      suggestions.push("Verify .map files exist in your output directory (e.g., dist/**/*.map)");
+      suggestions.push(
+        'Check that "sourceMaps": true is set in your debug config and "outFiles" points to your built JS files'
+      );
+    } else if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+      suggestions.push(
+        "Confirm you are setting the breakpoint in the executed file (built output vs source)"
+      );
+      if (isSourceMapIssue) {
+        suggestions.push(
+          "If using bundlers (webpack/esbuild/vite), ensure source maps are generated and accessible"
+        );
+        suggestions.push("Verify source map files (.map) are not excluded from your output");
+      }
+    }
+  } else if (normalizedAdapter === "coreclr") {
+    if (ext === ".cs") {
+      suggestions.push("Build in Debug configuration to ensure PDB files are produced");
+      suggestions.push("Clean and rebuild to refresh symbols: dotnet clean && dotnet build");
+      suggestions.push(
+        "Confirm the running binary matches the source version (stale builds can break mapping)"
+      );
+      suggestions.push("Ensure PDB files are deployed alongside the DLL");
+    }
+  } else if (normalizedAdapter === "python") {
+    if (ext === ".py") {
+      suggestions.push("Confirm the Python interpreter and working directory match your project");
+      suggestions.push(
+        "If debugging remotely or in containers, configure path mappings (localRoot/remoteRoot)"
+      );
+      suggestions.push(
+        "Verify you are setting the breakpoint in code that actually executes (imported module vs different copy)"
+      );
+    }
+  } else if (normalizedAdapter === "lldb") {
+    if ([".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".rs", ".m", ".mm"].includes(ext)) {
+      suggestions.push("Compile with debug symbols (-g) and avoid stripping binaries");
+      suggestions.push("Ensure the running binary matches the source used to compile");
+      suggestions.push("For Rust, build with: cargo build (debug mode, not --release)");
+    }
+  }
+  if (isPathIssue) {
+    suggestions.push("Check the file path is correct and exists relative to the provided cwd");
+  }
+  if (suggestions.length === 0) {
+    suggestions.push("Check the file path is correct and exists relative to the provided cwd");
+    suggestions.push(
+      "Ensure the running program corresponds to this source (no stale build artifacts)"
+    );
+    suggestions.push("Verify the file has been compiled/built with debug information");
+  }
+  return suggestions;
+}
 
 // src/session/variables.ts
 var BLOCKED_PROPERTIES = /* @__PURE__ */ new Set([
@@ -6119,10 +6667,17 @@ var DebugSession = class {
   traceInitialStackDepth = 0;
   /** Previous locals for variable diffing (only used when diffVars is enabled) */
   previousLocals = {};
+  /** Whether we are stepping to evaluate expressions after line execution */
+  isEvalAfterStep = false;
+  /** Pending data for eval-after-step (original breakpoint data) */
+  evalAfterStepData = null;
   sessionPromise = null;
   sessionResolve = null;
-  _sessionReject = null;
   timeoutHandle = null;
+  /** Error that occurred during session (timeout, etc.) - used to avoid unhandled promise rejections */
+  sessionError = null;
+  /** Whether session_end event has been emitted (to prevent duplicate emissions) */
+  sessionEndEmitted = false;
   constructor(config, formatter) {
     this.config = config;
     this.formatter = formatter ?? new OutputFormatter();
@@ -6132,6 +6687,8 @@ var DebugSession = class {
    */
   async run() {
     this.startTime = Date.now();
+    this.sessionError = null;
+    this.sessionEndEmitted = false;
     if (this.config.attach && this.config.pid) {
       this.formatter.sessionStartAttach(this.config.adapter.name, this.config.pid);
     } else {
@@ -6142,9 +6699,8 @@ var DebugSession = class {
         this.config.cwd
       );
     }
-    this.sessionPromise = new Promise((resolve10, reject) => {
-      this.sessionResolve = resolve10;
-      this._sessionReject = reject;
+    this.sessionPromise = new Promise((resolve9) => {
+      this.sessionResolve = resolve9;
     });
     if (this.config.timeout) {
       this.timeoutHandle = setTimeout(() => {
@@ -6152,13 +6708,21 @@ var DebugSession = class {
       }, this.config.timeout);
     }
     try {
-      await this.start();
+      await Promise.race([this.start(), this.sessionPromise]);
+      if (this.sessionError) {
+        throw this.sessionError;
+      }
       await this.sessionPromise;
+      if (this.sessionError) {
+        throw this.sessionError;
+      }
     } catch (error) {
-      this.formatter.error(
-        "Session failed",
-        error instanceof Error ? error.message : String(error)
-      );
+      if (error !== this.sessionError) {
+        this.formatter.error(
+          "Session failed",
+          error instanceof Error ? error.message : String(error)
+        );
+      }
       throw error;
     } finally {
       await this.cleanup();
@@ -6171,7 +6735,7 @@ var DebugSession = class {
         command: this.config.adapter.command,
         args: this.config.adapter.args,
         cwd: this.config.cwd,
-        env: this.config.env,
+        env: { ...this.config.adapter.env, ...this.config.env },
         port: this.config.adapter.socketPort,
         timeout: this.config.timeout
       });
@@ -6180,7 +6744,7 @@ var DebugSession = class {
         command: this.config.adapter.command,
         args: this.config.adapter.args,
         cwd: this.config.cwd,
-        env: this.config.env,
+        env: { ...this.config.adapter.env, ...this.config.env },
         timeout: this.config.timeout
       });
     }
@@ -6192,7 +6756,8 @@ var DebugSession = class {
     });
     this.breakpointManager = new BreakpointManager(this.client, this.formatter, {
       cwd: this.config.cwd,
-      programPath: this.config.program
+      programPath: this.config.program,
+      adapterType: this.config.adapter.name
     });
     this.variableInspector = new VariableInspector(this.client, {
       compactServices: !this.config.expandServices,
@@ -6265,14 +6830,14 @@ var DebugSession = class {
    * Wait for the 'initialized' event from the debug adapter
    */
   async waitForInitialized() {
-    return new Promise((resolve10) => {
+    return new Promise((resolve9) => {
       const onInitialized = () => {
-        resolve10();
+        resolve9();
       };
       this.client.once("initialized", onInitialized);
       const timeout = setTimeout(() => {
         this.client.removeListener("initialized", onInitialized);
-        resolve10();
+        resolve9();
       }, 3e4);
       this.client.once("initialized", () => {
         clearTimeout(timeout);
@@ -6345,7 +6910,8 @@ var DebugSession = class {
         locals = await this.variableInspector.getLocals(topFrame.id);
       }
       let evaluations;
-      if (this.config.evaluations?.length && topFrame) {
+      const shouldDeferEval = this.config.evalAfterStep && reason === "breakpoint";
+      if (this.config.evaluations?.length && topFrame && !shouldDeferEval) {
         evaluations = await this.variableInspector.evaluateExpressions(
           topFrame.id,
           this.config.evaluations
@@ -6361,6 +6927,64 @@ var DebugSession = class {
         );
         return;
       }
+      if (reason === "step" && this.isEvalAfterStep && this.evalAfterStepData) {
+        this.isEvalAfterStep = false;
+        const pendingData = this.evalAfterStepData;
+        this.evalAfterStepData = null;
+        let evaluations2;
+        if (this.config.evaluations?.length && topFrame) {
+          evaluations2 = await this.variableInspector.evaluateExpressions(
+            topFrame.id,
+            this.config.evaluations
+          );
+        }
+        if (topFrame) {
+          const failed = await this.checkAssertions(topFrame.id);
+          if (failed) {
+            await this.emitAssertionFailed(
+              pendingData.threadId,
+              failed.assertion,
+              failed.value,
+              failed.error,
+              location,
+              stackTrace,
+              topFrame.id
+            );
+            this.endSession();
+            return;
+          }
+        }
+        const event2 = {
+          type: "breakpoint_hit",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          id: pendingData.breakpointId,
+          threadId: pendingData.threadId,
+          location: pendingData.originalLocation,
+          stackTrace: pendingData.originalStackTrace,
+          locals,
+          evaluations: evaluations2
+        };
+        this.formatter.emit(event2);
+        if (this.config.trace) {
+          await this.startTrace(
+            pendingData.threadId,
+            location,
+            stackResponse.stackFrames.length,
+            topFrame?.id
+          );
+          return;
+        }
+        if (this.config.steps && this.config.steps > 1) {
+          this.remainingSteps = this.config.steps - 1;
+          this.isStepping = true;
+          await this.client.next({ threadId });
+          this.state = "running";
+          return;
+        }
+        await this.client.continue({ threadId });
+        this.state = "running";
+        return;
+      }
       if (reason === "step" && this.isStepping) {
         this.stepsExecuted++;
         this.remainingSteps--;
@@ -6440,6 +7064,18 @@ var DebugSession = class {
           await this.endTrace(threadId, "breakpoint", stackTrace, topFrame?.id);
         }
         this.breakpointsHit++;
+        if (this.config.evalAfterStep && this.config.evaluations?.length) {
+          this.isEvalAfterStep = true;
+          this.evalAfterStepData = {
+            threadId,
+            originalLocation: location,
+            originalStackTrace: stackTrace,
+            breakpointId: body.hitBreakpointIds?.[0]
+          };
+          await this.client.next({ threadId });
+          this.state = "running";
+          return;
+        }
         if (topFrame) {
           const failed = await this.checkAssertions(topFrame.id);
           if (failed) {
@@ -6535,31 +7171,36 @@ var DebugSession = class {
     this.endSessionWithError(new Error(`Session timed out after ${this.config.timeout}ms`));
   }
   endSessionWithError(error) {
-    this.formatter.sessionEnd({
-      durationMs: Date.now() - this.startTime,
-      exitCode: this.exitCode,
-      breakpointsHit: this.breakpointsHit,
-      exceptionsCaught: this.exceptionsCaught,
-      stepsExecuted: this.stepsExecuted
-    });
-    if (this._sessionReject) {
-      this._sessionReject(error);
+    this.sessionError = error;
+    if (!this.sessionEndEmitted) {
+      this.sessionEndEmitted = true;
+      this.formatter.sessionEnd({
+        durationMs: Date.now() - this.startTime,
+        exitCode: this.exitCode,
+        breakpointsHit: this.breakpointsHit,
+        exceptionsCaught: this.exceptionsCaught,
+        stepsExecuted: this.stepsExecuted
+      });
+    }
+    if (this.sessionResolve) {
+      this.sessionResolve();
       this.sessionResolve = null;
-      this._sessionReject = null;
     }
   }
   endSession() {
-    this.formatter.sessionEnd({
-      durationMs: Date.now() - this.startTime,
-      exitCode: this.exitCode,
-      breakpointsHit: this.breakpointsHit,
-      exceptionsCaught: this.exceptionsCaught,
-      stepsExecuted: this.stepsExecuted
-    });
+    if (!this.sessionEndEmitted) {
+      this.sessionEndEmitted = true;
+      this.formatter.sessionEnd({
+        durationMs: Date.now() - this.startTime,
+        exitCode: this.exitCode,
+        breakpointsHit: this.breakpointsHit,
+        exceptionsCaught: this.exceptionsCaught,
+        stepsExecuted: this.stepsExecuted
+      });
+    }
     if (this.sessionResolve) {
       this.sessionResolve();
       this.sessionResolve = null;
-      this._sessionReject = null;
     }
   }
   async cleanup() {
@@ -6819,7 +7460,7 @@ async function launchTestRunner(config) {
   });
   const stdoutReader = readline.createInterface({ input: testProcess.stdout });
   const stderrReader = readline.createInterface({ input: testProcess.stderr });
-  return new Promise((resolve10, reject) => {
+  return new Promise((resolve9, reject) => {
     let foundPid = null;
     let exitedEarly = false;
     let sawDebugHint = false;
@@ -6834,7 +7475,7 @@ async function launchTestRunner(config) {
       if (match && !foundPid && sawDebugHint) {
         foundPid = parseInt(match[1], 10);
         onProgress?.(`Found testhost PID: ${foundPid} (process: ${match[2]})`);
-        resolve10({
+        resolve9({
           pid: foundPid,
           process: testProcess
         });
@@ -6932,6 +7573,10 @@ function createCli() {
     "--diff-vars",
     "Show only changed variables in trace steps instead of full dumps",
     false
+  ).option(
+    "--eval-after-step",
+    "Step once before evaluating expressions (useful for evaluating variables being assigned on the breakpoint line)",
+    false
   ).option("-o, --output <file>", "Write events to file instead of stdout").option("--include <types...>", "Only emit these event types (e.g., breakpoint_hit error)").option(
     "--exclude <types...>",
     "Suppress these event types (e.g., program_output exception_thrown)"
@@ -6962,6 +7607,14 @@ function createCli() {
     "Maximum depth to traverse exception chain (default: 10)",
     (val) => parseInt(val, 10),
     10
+  ).option(
+    "--compact",
+    "Enable compact output mode for reduced token usage (limits stack traces, filters internals, abbreviates paths)",
+    false
+  ).option(
+    "--stack-limit <count>",
+    "Maximum stack frames to include (default: 3 in compact mode, unlimited otherwise)",
+    (val) => parseInt(val, 10)
   ).action(
     async (programPath, options) => {
       if (options.testProject) {
@@ -6993,6 +7646,16 @@ function createCli() {
         console.error(`Available adapters: ${getAdapterNames().join(", ")}`);
         process.exit(1);
       }
+      const breakpointErrors = validateAllBreakpoints(
+        options.breakpoint || [],
+        options.logpoint || []
+      );
+      if (breakpointErrors.length > 0) {
+        for (const error of breakpointErrors) {
+          console.error(`Error: ${error}`);
+        }
+        process.exit(1);
+      }
       await runDebugSession({ ...options, program: programPath, adapter: options.adapter });
     }
   );
@@ -7027,6 +7690,13 @@ async function runTestDebugSession(options) {
     console.error('Example: -b "path/to/TestFile.cs:42"');
     process.exit(1);
   }
+  const breakpointErrors = validateAllBreakpoints(options.breakpoint || [], options.logpoint || []);
+  if (breakpointErrors.length > 0) {
+    for (const error of breakpointErrors) {
+      console.error(`Error: ${error}`);
+    }
+    process.exit(1);
+  }
   console.error(`Starting test runner for: ${options.testProject}`);
   if (options.testFilter) {
     console.error(`Test filter: ${options.testFilter}`);
@@ -7105,7 +7775,9 @@ async function runDebugSession(options) {
     pretty: options.pretty,
     stream: outputStream,
     include: options.include,
-    exclude: options.exclude
+    exclude: options.exclude,
+    compact: options.compact,
+    stackLimit: options.stackLimit
   });
   const session = new DebugSession(
     {
@@ -7130,6 +7802,7 @@ async function runDebugSession(options) {
       traceLimit: options.traceLimit,
       traceUntil: options.traceUntil,
       diffVars: options.diffVars,
+      evalAfterStep: options.evalAfterStep,
       // Token efficiency options
       expandServices: options.expandServices,
       showNullProps: options.showNullProps,
@@ -7253,8 +7926,8 @@ function getSkillTargets(options) {
 }
 async function installSkill(options = {}) {
   const path12 = await import("node:path");
-  const { fileURLToPath: fileURLToPath2 } = await import("node:url");
-  const moduleDir = path12.dirname(fileURLToPath2(__importMetaUrl));
+  const { fileURLToPath } = await import("node:url");
+  const moduleDir = path12.dirname(fileURLToPath(__importMetaUrl));
   const possibleSources = [
     path12.join(moduleDir, "..", ".claude", "skills", "debug-run"),
     path12.join(moduleDir, ".claude", "skills", "debug-run"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "debug-run",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "CLI tool enabling AI agents to programmatically debug code via DAP",
   "type": "module",
   "main": "dist/index.cjs",