agent-dbg 0.1.0 → 0.1.2

package/.claude/settings.local.json

@@ -4,18 +4,20 @@
       "Bash(python3:*)",
       "Bash(npx tsx:*)",
       "Bash(bun run build:*)",
-      "Bash(timeout 15 ./dist/ndbg launch tsx:*)",
+      "Bash(timeout 15 ./dist/agent-dbg launch tsx:*)",
       "Bash(echo:*)",
       "Bash(timeout:*)",
-      "Bash(./dist/ndbg stop:*)",
+      "Bash(./dist/agent-dbg stop:*)",
       "Bash(npm install:*)",
       "Bash(tsx:*)",
-      "Bash(./dist/ndbg state:*)",
-      "Bash(./dist/ndbg:*)",
+      "Bash(./dist/agent-dbg state:*)",
+      "Bash(./dist/agent-dbg:*)",
       "Bash(bun test:*)",
       "Bash(bun:*)",
       "Bash(grep:*)",
-      "Bash(npm view:*)"
+      "Bash(npm view:*)",
+      "Bash(find:*)",
+      "Bash(xargs sed:*)"
     ]
   }
 }

package/.claude/skills/agent-dbg/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: agent-dbg
+description: >
+  Debug Node.js/TypeScript/JavaScript applications using the agent-dbg CLI debugger.
+  Use when: (1) investigating runtime bugs by stepping through code, (2) inspecting
+  variable values at specific execution points, (3) setting breakpoints and conditional
+  breakpoints, (4) evaluating expressions in a paused context, (5) hot-patching code
+  without restarting, (6) debugging test failures by attaching to a running process,
+  (7) any task where understanding runtime behavior requires a debugger.
+  Triggers: "debug this", "set a breakpoint", "step through", "inspect variables",
+  "why is this value wrong", "trace execution", "attach debugger", "runtime error".
+---
+
+# agent-dbg Debugger
+
+`agent-dbg` is a CLI debugger for Node.js wrapping the V8 Inspector (CDP). It uses short `@refs` for all entities -- use them instead of long IDs.
+
+## Core Debug Loop
+
+```bash
+# 1. Launch with breakpoint at first line
+agent-dbg launch --brk node app.js
+
+# 2. Set breakpoints at suspicious locations
+agent-dbg break src/handler.ts:42
+agent-dbg break src/utils.ts:15 --condition "count > 10"
+
+# 3. Run to breakpoint
+agent-dbg continue
+
+# 4. Inspect state (shows location, source, locals, stack)
+agent-dbg state
+
+# 5. Drill into values
+agent-dbg props @v1              # expand object
+agent-dbg props @v1 --depth 3    # expand nested 3 levels
+agent-dbg eval "items.filter(x => x.active)"
+
+# 6. Fix and verify
+agent-dbg set count 0            # change variable
+agent-dbg hotpatch src/utils.js  # live-edit (reads file from disk)
+agent-dbg continue               # verify fix
+```
+
+## Debugging Strategies
+
+### Bug investigation -- narrow down with breakpoints
+```bash
+agent-dbg launch --brk node app.js
+agent-dbg break src/api.ts:50                    # suspect line
+agent-dbg break src/api.ts:60 --condition "!user" # conditional
+agent-dbg continue
+agent-dbg vars                                    # check locals
+agent-dbg eval "JSON.stringify(req.body)"         # inspect deeply
+agent-dbg step over                               # advance one line
+agent-dbg state                                   # see new state
+```
+
+### Attach to running/test process
+```bash
+# Start node with inspector
+node --inspect app.js
+# Or attach by PID
+agent-dbg attach 12345
+agent-dbg state
+```
+
+### Trace execution flow with logpoints (no pause)
+```bash
+agent-dbg logpoint src/auth.ts:20 "login attempt: ${username}"
+agent-dbg logpoint src/auth.ts:45 "auth result: ${result}"
+agent-dbg continue
+agent-dbg console    # see logged output
+```
+
+### Exception debugging
+```bash
+agent-dbg catch uncaught          # pause on uncaught exceptions
+agent-dbg continue                # runs until exception
+agent-dbg state                   # see where it threw
+agent-dbg eval "err.message"      # inspect the error
+agent-dbg stack                   # full call stack
+```
+
+### TypeScript source map support
+agent-dbg automatically resolves `.ts` paths via source maps. Set breakpoints using `.ts` paths, see `.ts` source in output. Use `--generated` to see compiled `.js` if needed.
+
+## Ref System
+
+Every output assigns short refs. Use them everywhere:
+- `@v1..@vN` -- variables: `agent-dbg props @v1`, `agent-dbg set @v2 true`
+- `@f0..@fN` -- stack frames: `agent-dbg eval --frame @f1 "this"`
+- `BP#1..N` -- breakpoints: `agent-dbg break-rm BP#1`, `agent-dbg break-toggle BP#1`
+- `LP#1..N` -- logpoints: `agent-dbg break-rm LP#1`
+
+Refs `@v`/`@f` reset on each pause. `BP#`/`LP#` persist until removed.
+
+## Key Flags
+
+- `--json` -- machine-readable JSON output on any command
+- `--session NAME` -- target a specific session (default: "default")
+- `--generated` -- bypass source maps, show compiled JS (on state/source/stack)
+
+## Command Reference
+
+See [references/commands.md](references/commands.md) for full command details and options.
+
+## Tips
+
+- `agent-dbg state` after stepping always shows location + source + locals -- usually enough context
+- `agent-dbg state -c` for source only, `-v` for vars only, `-s` for stack only -- save tokens
+- `agent-dbg eval` supports `await` -- useful for async inspection
+- `agent-dbg blackbox "node_modules/**"` -- skip stepping into dependencies
+- `agent-dbg hotpatch file` reads the file from disk -- edit the file first, then hotpatch
+- Execution commands (`continue`, `step`, `pause`, `run-to`) auto-return status
+- `agent-dbg stop` kills the debugged process and daemon

package/.claude/skills/agent-dbg/references/commands.md

@@ -0,0 +1,173 @@
+# agent-dbg Command Reference
+
+## Table of Contents
+- [Session](#session)
+- [Execution](#execution)
+- [Inspection](#inspection)
+- [Breakpoints](#breakpoints)
+- [Mutation](#mutation)
+- [Blackboxing](#blackboxing)
+- [Source Maps](#source-maps)
+- [Global Flags](#global-flags)
+
+## Session
+
+```bash
+agent-dbg launch [--brk] <command...>     # Start + attach debugger (--brk pauses at first line)
+agent-dbg attach <pid|ws-url|port>        # Attach to running process
+agent-dbg stop                            # Kill process + daemon
+agent-dbg sessions [--cleanup]            # List active sessions
+agent-dbg status                          # Session info (pid, state, pause location)
+```
+
+## Execution
+
+All execution commands automatically return session status (state + pause info).
+
+```bash
+agent-dbg continue                        # Resume to next breakpoint or completion
+agent-dbg step [over|into|out]            # Step one statement (default: over)
+agent-dbg run-to <file>:<line>            # Continue to specific location
+agent-dbg pause                           # Interrupt running process
+agent-dbg restart-frame [@fN]             # Re-execute frame from beginning
+```
+
+## Inspection
+
+### state -- composite snapshot
+```bash
+agent-dbg state                           # Full snapshot: location, source, locals, stack, breakpoints
+agent-dbg state -v                        # Locals only
+agent-dbg state -s                        # Stack only
+agent-dbg state -c                        # Source code only
+agent-dbg state -b                        # Breakpoints only
+agent-dbg state --depth 3                 # Expand object values to depth 3
+agent-dbg state --lines 10                # Show 10 lines of source context
+agent-dbg state --frame @f1               # Inspect a different stack frame
+agent-dbg state --all-scopes              # Include closure scope variables
+agent-dbg state --compact                 # Compact output
+agent-dbg state --generated               # Show compiled JS paths instead of TS
+```
+
+### vars -- local variables
+```bash
+agent-dbg vars                            # All locals in current frame
+agent-dbg vars name1 name2                # Filter specific variables
+agent-dbg vars --frame @f1                # Variables from a different frame
+agent-dbg vars --all-scopes               # Include closure scope
+```
+
+### stack -- call stack
+```bash
+agent-dbg stack                           # Full call stack
+agent-dbg stack --async-depth 5           # Include async frames
+agent-dbg stack --generated               # Show compiled JS paths
+```
+
+### eval -- evaluate expression
+```bash
+agent-dbg eval <expression>               # Evaluate in current frame
+agent-dbg eval "await fetchUser(id)"      # Await supported
+agent-dbg eval --frame @f1 "this"         # Evaluate in different frame
+agent-dbg eval --silent "setup()"         # No output (side effects only)
+agent-dbg eval --side-effect-free "x + 1" # Abort if side effects detected
+agent-dbg eval --timeout 5000 "slowFn()"  # Custom timeout in ms
+```
+
+### props -- expand object
+```bash
+agent-dbg props @v1                       # Expand object properties
+agent-dbg props @v1 --depth 3             # Nested expansion
+agent-dbg props @v1 --own                 # Own properties only
+agent-dbg props @v1 --private             # Include private fields
+agent-dbg props @v1 --internal            # Include internal slots
+```
+
+### source -- view source code
+```bash
+agent-dbg source                          # Source around current line
+agent-dbg source --lines 20               # 20 lines of context
+agent-dbg source --file src/app.ts        # Source of a specific file
+agent-dbg source --all                    # Entire file
+agent-dbg source --generated              # Show compiled JS
+```
+
+### Other inspection
+```bash
+agent-dbg search "query"                  # Search loaded scripts
+agent-dbg search "pattern" --regex        # Regex search
+agent-dbg search "text" --case-sensitive  # Case-sensitive search
+agent-dbg search "text" --file <id>       # Search in specific script
+agent-dbg scripts                         # List loaded scripts
+agent-dbg scripts --filter "src/"         # Filter by pattern
+agent-dbg console                         # Show console output
+agent-dbg console --since 5               # Last 5 messages
+agent-dbg console --level error           # Filter by level
+agent-dbg console --clear                 # Clear console buffer
+agent-dbg exceptions                      # Show captured exceptions
+agent-dbg exceptions --since 3            # Last 3 exceptions
+```
+
+## Breakpoints
+
+```bash
+agent-dbg break <file>:<line>             # Set breakpoint
+agent-dbg break src/app.ts:42 --condition "x > 10"  # Conditional
+agent-dbg break src/app.ts:42 --hit-count 5         # Break on Nth hit
+agent-dbg break src/app.ts:42 --continue            # Log but don't pause
+agent-dbg break --pattern "handler":15              # Regex URL match
+agent-dbg break-rm BP#1                   # Remove specific breakpoint
+agent-dbg break-rm all                    # Remove all breakpoints
+agent-dbg break-ls                        # List all breakpoints
+agent-dbg break-toggle BP#1               # Disable/enable one breakpoint
+agent-dbg break-toggle all                # Disable/enable all
+agent-dbg breakable src/app.ts:10-50      # List valid breakpoint locations
+agent-dbg logpoint src/app.ts:20 "x=${x}" # Log without pausing
+agent-dbg logpoint src/app.ts:20 "x=${x}" --condition "x > 0"
+agent-dbg catch all                       # Pause on all exceptions
+agent-dbg catch uncaught                  # Pause on uncaught only
+agent-dbg catch none                      # Don't pause on exceptions
+```
+
+## Mutation
+
+```bash
+agent-dbg set <@ref|name> <value>         # Change variable value
+agent-dbg set count 0                     # By name
+agent-dbg set @v2 true                    # By ref
+agent-dbg set-return "newValue"           # Change return value (at return point)
+agent-dbg hotpatch <file>                 # Live-edit script from disk
+agent-dbg hotpatch <file> --dry-run       # Preview without applying
+```
+
+## Blackboxing
+
+Skip stepping into matching scripts (useful for node_modules).
+
+```bash
+agent-dbg blackbox "node_modules/**"      # Add pattern
+agent-dbg blackbox "lib/**" "vendor/**"   # Multiple patterns
+agent-dbg blackbox-ls                     # List patterns
+agent-dbg blackbox-rm "node_modules/**"   # Remove specific pattern
+agent-dbg blackbox-rm all                 # Remove all patterns
+```
+
+## Source Maps
+
+agent-dbg auto-detects source maps from `Debugger.scriptParsed` events. TypeScript `.ts` paths work transparently for breakpoints and display.
+
+```bash
+agent-dbg sourcemap                       # List all loaded source maps
+agent-dbg sourcemap src/app.ts            # Info for specific file
+agent-dbg sourcemap --disable             # Disable resolution globally
+```
+
+## Global Flags
+
+```bash
+--session NAME                       # Target session (default: "default")
+--json                               # JSON output
+--color                              # Enable ANSI colors
+--help-agent                         # LLM-optimized reference card
+--help                               # Human help
+```

package/.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "bun",
+            "request": "launch",
+            "name": "Debug Daemon",
+            "program": "src/main.ts",
+            "cwd": "${workspaceFolder}",
+            "stopOnEntry": false,
+            "watchMode": false,
+            "internalConsoleOptions": "neverOpen",
+            "args": [
+                "--daemon",
+                "default",
+            ]
+        },
+    ]
+}

package/CLAUDE.md

@@ -1,8 +1,8 @@
-# ndbg — Node.js Debugger CLI for AI Agents
+# agent-dbg — Node.js Debugger CLI for AI Agents
 
 ## Project Overview
 CLI debugger for Node.js built with Bun, optimized for AI agent consumption.
-See `ndbg-spec.md` for full specification, `PROGRESS.md` for implementation status.
+See `agent-dbg-spec.md` for full specification, `PROGRESS.md` for implementation status.
 
 ## Tech Stack
 - **Runtime**: Bun (compiled to standalone binary via `bun build --compile`)

package/PROGRESS.md

@@ -1,4 +1,4 @@
-# ndbg Development Progress
+# agent-dbg Development Progress
 
 > Status legend: `[ ]` Not started | `[~]` In progress | `[x]` Done | `[-]` Blocked
 
@@ -20,12 +20,12 @@
 ### 1.1 Daemon Architecture
 
 - [x] Daemon process spawning and backgrounding
-- [x] Unix socket server (listen on `$XDG_RUNTIME_DIR/ndbg/<session>.sock`)
+- [x] Unix socket server (listen on `$XDG_RUNTIME_DIR/agent-dbg/<session>.sock`)
 - [x] CLI-to-daemon request/response protocol (newline-delimited JSON)
 - [x] Daemon auto-termination on process exit
 - [x] Daemon idle timeout (configurable, default 300s)
 - [x] Lock file to prevent duplicate daemons per session
-- [x] Crash recovery: detect dead socket, suggest `ndbg attach`
+- [x] Crash recovery: detect dead socket, suggest `agent-dbg attach`
 
 ### 1.2 CDP (Chrome DevTools Protocol) Connection
 
@@ -45,7 +45,7 @@
 - [x] `LP#` refs — logpoint refs (persist until removed)
 - [x] `HS#` refs — heap snapshot refs (persist until session ends)
 - [x] Ref resolution: resolve `@ref` in CLI arguments to V8 IDs
-- [x] `ndbg gc-refs` — clear accumulated `@o` refs
+- [x] `agent-dbg gc-refs` — clear accumulated `@o` refs
 
 ### 1.4 Output Formatter
 
@@ -56,28 +56,28 @@
 - [x] Error output with actionable suggestions (`→ Try: ...`)
 - [x] `--color` flag for ANSI terminal colors
 - [x] `--json` flag for JSON output mode
-- [x] Truncation hints (`... (ndbg props @oN for more)`)
+- [x] Truncation hints (`... (agent-dbg props @oN for more)`)
 
 ---
 
 ## Phase 2 — Session Management
 
-- [x] `ndbg launch [--brk] [--session NAME] <command...>` — spawn + attach
-- [x] `ndbg launch --brk` — spawn with `--inspect-brk`, pause on first line
-- [x] `ndbg launch --port PORT` — use specific inspector port
-- [x] `ndbg launch --timeout SECS` — configure daemon idle timeout
-- [x] `ndbg attach <pid | ws-url | port>` — attach to running process
-- [x] `ndbg stop [--session NAME]` — kill process + daemon
-- [x] `ndbg sessions` — list active sessions (PID, status, name)
-- [x] `ndbg sessions --cleanup` — kill orphaned daemons
-- [x] `ndbg status` — session info (PID, pause state, breakpoints, memory, uptime)
+- [x] `agent-dbg launch [--brk] [--session NAME] <command...>` — spawn + attach
+- [x] `agent-dbg launch --brk` — spawn with `--inspect-brk`, pause on first line
+- [x] `agent-dbg launch --port PORT` — use specific inspector port
+- [x] `agent-dbg launch --timeout SECS` — configure daemon idle timeout
+- [x] `agent-dbg attach <pid | ws-url | port>` — attach to running process
+- [x] `agent-dbg stop [--session NAME]` — kill process + daemon
+- [x] `agent-dbg sessions` — list active sessions (PID, status, name)
+- [x] `agent-dbg sessions --cleanup` — kill orphaned daemons
+- [x] `agent-dbg status` — session info (PID, pause state, breakpoints, memory, uptime)
 - [x] Multi-session support (`--session NAME` on any command)
 
 ---
 
 ## Phase 3 — State Snapshot
 
-- [x] `ndbg state` — full state snapshot (source + locals + stack + breakpoints)
+- [x] `agent-dbg state` — full state snapshot (source + locals + stack + breakpoints)
 - [x] State filtering: `-v` / `--vars` (locals only)
 - [x] State filtering: `-s` / `--stack` (stack trace only)
 - [x] State filtering: `-b` / `--breakpoints` (breakpoints/logpoints only)
@@ -94,80 +94,80 @@
 
 ## Phase 4 — Breakpoints
 
-- [x] `ndbg break <file>:<line>` — set breakpoint (`Debugger.setBreakpointByUrl`)
-- [x] `ndbg break --condition <expr>` — conditional breakpoint
-- [x] `ndbg break --hit-count <n>` — pause on Nth hit
-- [x] `ndbg break --continue` — set breakpoint + immediately continue
-- [ ] `ndbg break --log <template>` — shortcut to logpoint
-- [x] `ndbg break --pattern <urlRegex>:<line>` — regex pattern breakpoint
-- [ ] `ndbg break-fn <expr>` — breakpoint on function call
-- [ ] `ndbg break-on-load [--sourcemap]` — break on new script parse
-- [x] `ndbg break-rm <BP# | LP# | all>` — remove breakpoints
-- [x] `ndbg break-ls` — list all breakpoints/logpoints with locations and conditions
-- [x] `ndbg break-toggle [BP# | all]` — enable/disable breakpoints
-- [x] `ndbg breakable <file>:<start>-<end>` — list valid breakpoint locations
-- [x] `ndbg logpoint <file>:<line> <template>` — set logpoint (no pause)
+- [x] `agent-dbg break <file>:<line>` — set breakpoint (`Debugger.setBreakpointByUrl`)
+- [x] `agent-dbg break --condition <expr>` — conditional breakpoint
+- [x] `agent-dbg break --hit-count <n>` — pause on Nth hit
+- [x] `agent-dbg break --continue` — set breakpoint + immediately continue
+- [ ] `agent-dbg break --log <template>` — shortcut to logpoint
+- [x] `agent-dbg break --pattern <urlRegex>:<line>` — regex pattern breakpoint
+- [ ] `agent-dbg break-fn <expr>` — breakpoint on function call
+- [ ] `agent-dbg break-on-load [--sourcemap]` — break on new script parse
+- [x] `agent-dbg break-rm <BP# | LP# | all>` — remove breakpoints
+- [x] `agent-dbg break-ls` — list all breakpoints/logpoints with locations and conditions
+- [x] `agent-dbg break-toggle [BP# | all]` — enable/disable breakpoints
+- [x] `agent-dbg breakable <file>:<start>-<end>` — list valid breakpoint locations
+- [x] `agent-dbg logpoint <file>:<line> <template>` — set logpoint (no pause)
 - [ ] Logpoint `--max <n>` — auto-pause after N emissions (default: 100)
 - [x] Logpoint `--condition <expr>` — conditional logpoint
-- [x] `ndbg catch [all | uncaught | caught | none]` — pause-on-exception config
+- [x] `agent-dbg catch [all | uncaught | caught | none]` — pause-on-exception config
 
 ---
 
 ## Phase 5 — Execution Control
 
-- [x] `ndbg continue` — resume execution (+ auto-state return)
-- [x] `ndbg step over` — step one statement over (default)
-- [x] `ndbg step into` — step into function call
-- [x] `ndbg step out` — step out of current function
-- [ ] `ndbg step into --break-on-async` — pause on first async task
-- [ ] `ndbg step --skip <pattern>` — inline blackboxing during step
-- [x] `ndbg run-to <file>:<line>` — continue to location (no persistent breakpoint)
-- [x] `ndbg restart-frame [@fN]` — re-execute frame from beginning
-- [x] `ndbg pause` — interrupt running process
-- [ ] `ndbg kill-execution` — terminate JS execution, keep session alive
+- [x] `agent-dbg continue` — resume execution (+ auto-state return)
+- [x] `agent-dbg step over` — step one statement over (default)
+- [x] `agent-dbg step into` — step into function call
+- [x] `agent-dbg step out` — step out of current function
+- [ ] `agent-dbg step into --break-on-async` — pause on first async task
+- [ ] `agent-dbg step --skip <pattern>` — inline blackboxing during step
+- [x] `agent-dbg run-to <file>:<line>` — continue to location (no persistent breakpoint)
+- [x] `agent-dbg restart-frame [@fN]` — re-execute frame from beginning
+- [x] `agent-dbg pause` — interrupt running process
+- [ ] `agent-dbg kill-execution` — terminate JS execution, keep session alive
 
 ---
 
 ## Phase 6 — Inspection
 
-- [x] `ndbg vars [name1, name2, ...]` — show local variables with `@v` refs
-- [x] `ndbg stack [--async-depth N]` — show call stack with `@f` refs
-- [x] `ndbg eval <expression>` — evaluate in current frame context
-- [x] `ndbg eval` with `await` support (CDP `awaitPromise`)
-- [x] `ndbg eval` with `@ref` interpolation
-- [x] `ndbg eval --frame @fN` — evaluate in specific frame
-- [x] `ndbg eval --silent` — suppress exception reporting
-- [x] `ndbg eval --timeout MS` — kill after N ms (default: 5000)
-- [x] `ndbg eval --side-effect-free` — throw on side effects
-- [x] `ndbg props <@ref>` — expand object properties (returns `@o` refs)
-- [x] `ndbg props --own` — only own properties
-- [x] `ndbg props --depth N` — recursive expansion
-- [x] `ndbg props --private` — include private fields
-- [x] `ndbg props --internal` — V8 internal properties (`[[PromiseState]]`)
-- [ ] `ndbg instances <expression>` — find all live instances of prototype
-- [ ] `ndbg globals` — list global let/const/class declarations
-- [x] `ndbg source [--lines N] [--file <path>] [--all]` — show source code
-- [x] `ndbg search <query> [--regex] [--case-sensitive] [--file <id>]` — search scripts
-- [x] `ndbg scripts [--filter <pattern>]` — list loaded scripts
-- [x] `ndbg console [--follow] [--since N] [--level] [--clear]` — console output
-- [x] `ndbg exceptions [--follow] [--since N]` — captured exceptions
+- [x] `agent-dbg vars [name1, name2, ...]` — show local variables with `@v` refs
+- [x] `agent-dbg stack [--async-depth N]` — show call stack with `@f` refs
+- [x] `agent-dbg eval <expression>` — evaluate in current frame context
+- [x] `agent-dbg eval` with `await` support (CDP `awaitPromise`)
+- [x] `agent-dbg eval` with `@ref` interpolation
+- [x] `agent-dbg eval --frame @fN` — evaluate in specific frame
+- [x] `agent-dbg eval --silent` — suppress exception reporting
+- [x] `agent-dbg eval --timeout MS` — kill after N ms (default: 5000)
+- [x] `agent-dbg eval --side-effect-free` — throw on side effects
+- [x] `agent-dbg props <@ref>` — expand object properties (returns `@o` refs)
+- [x] `agent-dbg props --own` — only own properties
+- [x] `agent-dbg props --depth N` — recursive expansion
+- [x] `agent-dbg props --private` — include private fields
+- [x] `agent-dbg props --internal` — V8 internal properties (`[[PromiseState]]`)
+- [ ] `agent-dbg instances <expression>` — find all live instances of prototype
+- [ ] `agent-dbg globals` — list global let/const/class declarations
+- [x] `agent-dbg source [--lines N] [--file <path>] [--all]` — show source code
+- [x] `agent-dbg search <query> [--regex] [--case-sensitive] [--file <id>]` — search scripts
+- [x] `agent-dbg scripts [--filter <pattern>]` — list loaded scripts
+- [x] `agent-dbg console [--follow] [--since N] [--level] [--clear]` — console output
+- [x] `agent-dbg exceptions [--follow] [--since N]` — captured exceptions
 
 ---
 
 ## Phase 7 — Mutation
 
-- [x] `ndbg set <@vRef | varName> <value>` — change variable value
-- [x] `ndbg set-return <value>` — change return value (at return point)
-- [x] `ndbg hotpatch <file>` — live-edit script source (`Debugger.setScriptSource`)
-- [x] `ndbg hotpatch --dry-run` — check without applying
+- [x] `agent-dbg set <@vRef | varName> <value>` — change variable value
+- [x] `agent-dbg set-return <value>` — change return value (at return point)
+- [x] `agent-dbg hotpatch <file>` — live-edit script source (`Debugger.setScriptSource`)
+- [x] `agent-dbg hotpatch --dry-run` — check without applying
 
 ---
 
 ## Phase 8 — Blackboxing
 
-- [x] `ndbg blackbox <pattern...>` — skip stepping into matching scripts
-- [x] `ndbg blackbox-ls` — list current patterns
-- [x] `ndbg blackbox-rm <pattern | all>` — remove patterns
+- [x] `agent-dbg blackbox <pattern...>` — skip stepping into matching scripts
+- [x] `agent-dbg blackbox-ls` — list current patterns
+- [x] `agent-dbg blackbox-rm <pattern | all>` — remove patterns
 
 ---
 
@@ -176,54 +176,54 @@
 - [x] Fetch and cache source maps from `Debugger.scriptParsed` events
 - [x] Resolve `.ts` locations to `.js` for breakpoint setting
 - [x] Display source-mapped paths in all output (stack traces, source, breakpoints)
-- [x] Show original source (TypeScript) in `ndbg source`
+- [x] Show original source (TypeScript) in `agent-dbg source`
 - [x] Graceful fallback when no source map exists
-- [x] `ndbg sourcemap <file>` — show source map info
-- [x] `ndbg sourcemap --disable` — disable resolution globally
+- [x] `agent-dbg sourcemap <file>` — show source map info
+- [x] `agent-dbg sourcemap --disable` — disable resolution globally
 - [x] `--generated` flag — bypass source map resolution per-command (state, source, stack)
 
 ---
 
 ## Phase 10 — CPU Profiling
 
-- [ ] `ndbg cpu start [--interval <us>]` — start V8 CPU profiler
-- [ ] `ndbg cpu stop [--top N]` — stop profiling + report (function, file:line, self%, total%, deopt)
+- [ ] `agent-dbg cpu start [--interval <us>]` — start V8 CPU profiler
+- [ ] `agent-dbg cpu stop [--top N]` — stop profiling + report (function, file:line, self%, total%, deopt)
 - [ ] Save full profile to file for external tools
-- [ ] `ndbg coverage start [--detailed]` — start code coverage
-- [ ] `ndbg coverage stop [--file] [--uncovered]` — stop + report
+- [ ] `agent-dbg coverage start [--detailed]` — start code coverage
+- [ ] `agent-dbg coverage stop [--file] [--uncovered]` — stop + report
 
 ---
 
 ## Phase 11 — Memory / Heap
 
-- [ ] `ndbg heap usage` — quick heap statistics
-- [ ] `ndbg heap snapshot [--tag <name>]` — full heap snapshot (assigns `HS#` ref)
-- [ ] `ndbg heap diff <HS#a> <HS#b> [--top N]` — compare snapshots
-- [ ] `ndbg heap sample start [--interval] [--include-gc]` — sampling profiler
-- [ ] `ndbg heap sample stop [--top N]` — stop sampling + report
-- [ ] `ndbg heap track start` — allocation tracking (timeline)
-- [ ] `ndbg heap track stop` — stop tracking + report
-- [ ] `ndbg heap inspect <heapObjectId>` — get runtime ref from snapshot node
-- [ ] `ndbg gc` — force garbage collection
+- [ ] `agent-dbg heap usage` — quick heap statistics
+- [ ] `agent-dbg heap snapshot [--tag <name>]` — full heap snapshot (assigns `HS#` ref)
+- [ ] `agent-dbg heap diff <HS#a> <HS#b> [--top N]` — compare snapshots
+- [ ] `agent-dbg heap sample start [--interval] [--include-gc]` — sampling profiler
+- [ ] `agent-dbg heap sample stop [--top N]` — stop sampling + report
+- [ ] `agent-dbg heap track start` — allocation tracking (timeline)
+- [ ] `agent-dbg heap track stop` — stop tracking + report
+- [ ] `agent-dbg heap inspect <heapObjectId>` — get runtime ref from snapshot node
+- [ ] `agent-dbg gc` — force garbage collection
 
 ---
 
 ## Phase 12 — Advanced / Utility
 
-- [ ] `ndbg inject-hook <name>` — create runtime binding (`__ndbg_<name>()`)
-- [ ] `ndbg hooks [--follow]` — view hook invocations
-- [ ] `ndbg contexts` — list V8 execution contexts
-- [ ] `ndbg async-depth <N>` — set async call stack depth
-- [ ] `ndbg config [key] [value]` — get/set daemon configuration
-- [ ] `ndbg gc-refs` — clear `@o` refs to free memory
-- [ ] `ndbg --help-agent` — compact LLM-optimized reference card
+- [ ] `agent-dbg inject-hook <name>` — create runtime binding (`__agent-dbg_<name>()`)
+- [ ] `agent-dbg hooks [--follow]` — view hook invocations
+- [ ] `agent-dbg contexts` — list V8 execution contexts
+- [ ] `agent-dbg async-depth <N>` — set async call stack depth
+- [ ] `agent-dbg config [key] [value]` — get/set daemon configuration
+- [ ] `agent-dbg gc-refs` — clear `@o` refs to free memory
+- [ ] `agent-dbg --help-agent` — compact LLM-optimized reference card
 
 ---
 
 ## Phase 13 — Distribution & Integration
 
 - [ ] `bun build --compile` producing standalone binaries (linux-x64, darwin-arm64, etc.)
-- [ ] npm package (`npx ndbg` support)
+- [ ] npm package (`npx agent-dbg` support)
 - [ ] SKILL.md for Claude Code agent integration
 - [ ] `--help-agent` output matching spec reference card
 - [ ] GitHub releases with prebuilt binaries