textual-debugger 0.2.8__tar.gz → 0.2.12__tar.gz

{textual_debugger-0.2.8 → textual_debugger-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.8
+Version: 0.2.12
 Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -49,11 +49,11 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: textual>=8.0.0
-Requires-Dist: debugpy>=1.8.0
+Requires-Dist: debugpy>=1.8.12
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
-Requires-Dist: mcp<2.0.0,>=1.28.0
+Requires-Dist: mcp<3.0.0,>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -79,6 +79,8 @@ with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
 - Tcsh (via source instrumentation of a stock `tcsh`)
 - Ruby (via the [debug gem](https://github.com/ruby/debug)'s `rdbg`; debug ≥ 1.9)
 - OCaml (native via `lldb-dap`/`gdb`, bytecode via [ocamlearlybird](https://github.com/hackwaly/ocamlearlybird))
+- Go (via [Delve](https://github.com/go-delve/delve)'s `dlv dap`)
+- PowerShell 7 (via [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices); Linux/macOS, Windows experimental)
 
 `tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
 DAP to a pluggable debug adapter.
@@ -99,8 +101,9 @@ MIT License.  Copyright 2026 by Al Danial.
 the richest feature set), C/C++ (via `gdb -i dap` or `lldb-dap`), Rust (via `gdb` or
 `lldb-dap`), Perl (via `perl -d`),
 Bash (via bash's own `DEBUG` trap), Tcsh (via source instrumentation of a
-stock `tcsh`), Ruby (via the debug gem's `rdbg`), and OCaml (native via
-`lldb-dap`/`gdb`, bytecode via ocamlearlybird). Most languages are
+stock `tcsh`), Ruby (via the debug gem's `rdbg`), OCaml (native via
+`lldb-dap`/`gdb`, bytecode via ocamlearlybird), Go (via Delve's `dlv
+dap`), and PowerShell 7 (via PowerShell Editor Services). Most languages are
 auto-detected from the target; Rust intentionally requires `--lang rust`
 (ref. [Multi-Language Debugging](#multi-language-debugging)).
 
@@ -110,9 +113,9 @@ It specifically supports modules
     - `threading` (with a thread inspector)
     - `multiprocessing` / `concurrent.futures` (with automatic child process attachment and a process inspector)
 
-- supports remote attachment to Python, Perl, Ruby, Rust, and C/C++ programs
+- supports remote attachment to Python, Perl, Ruby, Rust, C/C++, and Go programs
 
-- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+- includes a JSON-RPC server mode, an MCP (v2) mode, and a `SKILL.md` file that enable
 programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
@@ -126,28 +129,6 @@ to have `tdb` pop open automatically at the first uncaught exception
 making it suitable for operation in non-graphical environments (mouse support is
 available in graphical environments)
 
-## Acknowledgments
-
-Thank you:
-
-- Will McGugan for the amazing `textual` module.
-`tdb` would be a pale shadow of itself had I used any other TUI framework.
-Fantastic work, Will.
-
-- Microsoft for the Debug Adapter Protocol (DAP) and releasing
-its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
-as open source.
-
-- Anthropic, for providing access to Claude Code through the
-[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
-`tdb` was made almost entirely with Claude Code.
-
-- OpenAI, for providing access to Codex through the
-[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
-
-This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
-Python debugger.
-
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -187,6 +168,10 @@ uvx --from textual-debugger tdb  my_program.py
 # show comprehensive documentation in a terminal-based Markdown viewer
 tdb --doc
 
+# show where tdb is installed, where its bundled Perl PadWalker module
+# lives, and the Help > About text
+tdb --info
+
 # debug a script (stops at first line by default)
 tdb my_program.py
 
@@ -212,6 +197,10 @@ tdb -k 20 -k 35 -k module.py:14 my_program.py arg1 arg2
 # sessions (-t is -k minus the persistence)
 tdb -t 20 my_program.py
 
+# no TUI: run at (almost) full speed, printing nr each time line 25 is
+# reached, then continuing (-e may be repeated; see "Eval Mode" below)
+tdb --eval my_program.py:25 "print(f'{nr=}')" my_program.py
+
 # use a specific virtualenv
 tdb --python /path/to/venv/bin/python my_program.py
 
@@ -238,6 +227,11 @@ tdb -r remotehost:5678  -k my_program.py:42
 # than code on the remote host
 tdb -r remotehost:5678 --local-root /my/code/dir --remote-root /app -k my_program.py:42
 
+# attach to a program that pauses itself (debugpy.breakpoint() right after
+# debugpy.wait_for_client()); without this flag tdb pauses the program on
+# attach, which can leave it suspended after tdb quits
+tdb -r remotehost:5678 --no-pause-on-attach
+
 # separate tdb arguments from debuggee arguments with `--` 
 tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
@@ -250,7 +244,7 @@ python -m tdb my_program.py
 
 ## Multi-Language Debugging
 
-`tdb` debugs any language that has a Debug Adapter Protocol backend. Eight
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Ten
 languages are supported out of the box:
 
 | Language | Adapter(s) | Dependencies           | Feature level |
@@ -262,33 +256,42 @@ languages are supported out of the box:
 | Bash | bash-tdb (bundled) | bash ≥ 4.4 on PATH  | core debugging (no remote attach) |
 | Tcsh | tcsh-tdb (bundled) | tcsh on PATH | core debugging (no remote attach, no conditional breakpoints, no pause) |
 | Ruby | `rdbg` (the [debug gem](https://github.com/ruby/debug)) | `rdbg` ≥ 1.9 on PATH | core debugging + remote attach |
-| OCaml (native executable) | `lldb-dap` (default), `gdb` (alternate) | OCaml ≥ 4.12; `lldb-dap` ships with LLVM ≥ 17; `gdb -i dap` requires GDB ≥ 14 | core debugging + domains-as-threads; Variables view shows no OCaml locals (upstream DWARF limitation); evaluate console is lldb/C-level, not OCaml |
-| OCaml (bytecode executable) | `ocamlearlybird` (default) | OCaml ≥ 4.12; `opam install earlybird` | core debugging + rich OCaml locals; no pause/`--run`, no evaluate responses, no fatal-error modal (ocamlearlybird 1.3.6 limitations); single-domain only |
+| OCaml (native executable) | `lldb-dap` (default), `gdb` (alternate) | `lldb-dap` ships with LLVM ≥ 17; `gdb -i dap` requires GDB ≥ 14 | core debugging + domains-as-threads; Variables view shows no OCaml locals (upstream DWARF limitation); evaluate console is lldb/C-level, not OCaml |
+| OCaml (bytecode executable) | `ocamlearlybird` (default) | `opam install earlybird` | core debugging + rich OCaml locals; no pause/`--run`, no evaluate responses, no fatal-error modal (ocamlearlybird 1.3.6 limitations); single-domain only |
+| Go | `dlv` (the [Delve](https://github.com/go-delve/delve) DAP server) | Delve ≥ 1.21 on PATH (`go install github.com/go-delve/delve/cmd/dlv@latest`) | core debugging + goroutine inspection (wait graph, findings) + remote attach (no `--terminal`) |
+| PowerShell 7 | `pses` (PowerShell Editor Services, driven by tdb's bundled proxy) | `pwsh` ≥ 7.2 on PATH + the PSES module (see [PowerShell](#powershell)) | core debugging (breakpoints incl. conditional/hit-count/log, stepping, stack, variables, evaluate console) + `--run`; no `--terminal`, no remote attach; Windows untested |
 
 ### Language detection and selection
 
 The language is auto-detected from the debug target:
 
-1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl; `.sh` / `.bash`
-   → Bash; `.csh` / `.tcsh` → Tcsh; `.rb` → Ruby. (`.ml` / `.mli` do *not*
-   auto-select OCaml, see point 5.)
-2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++, unless
-   byte-sniffing finds an OCaml marker, either a native binary's
+1. A directory → Go, if it contains any `*.go` file (a Go package
+   directory, e.g. `tdb ./pkg`); otherwise an error naming `--lang`.
+2. File extension: `.py` → Python; `.go` → Go; `.pl` / `.pm` / `.t` → Perl;
+   `.sh` / `.bash` → Bash; `.csh` / `.tcsh` → Tcsh; `.rb` → Ruby; `.ps1` /
+   `.psm1` → PowerShell. (`.ml` / `.mli` do *not* auto-select OCaml, see
+   point 6.)
+3. Native executables (ELF, Mach-O, PE magic bytes) → C/C++, unless
+   byte-checking finds an OCaml marker (a native binary's
    `caml_program`/`caml_startup` runtime symbols, a bytecode file's
-   trailing `Caml1999` marker, or a `#!...ocamlrun` shebang, in which case
-   → OCaml (native or bytecode respectively). A stripped native OCaml
-   binary that byte-sniffing can't identify falls back to C/C++; force it
-   with `--lang ocaml`. Rust is never inferred from an executable; select
-   it explicitly with `--lang rust`.
-3. A `#!...python`, `#!...perl`, `#!...bash`, `#!...csh`/`#!...tcsh`, or
-   `#!...ruby` shebang → Python / Perl / Bash / Tcsh / Ruby respectively.
-4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+   trailing `Caml1999` marker, or a `#!...ocamlrun` shebang) → OCaml
+   (native or bytecode respectively), or a Go buildinfo blob (the marker
+   `go version` itself locates, scanned in the first 16MB of the file) →
+   Go. A stripped native OCaml binary, or a Go binary whose buildinfo
+   blob sits beyond the 16MB scan window, that byte-checking can't
+   identify falls back to C/C++; force it with `--lang ocaml` or `--lang
+   go` respectively. Rust is never inferred from an executable; select it
+   explicitly with `--lang rust`.
+4. A `#!...python`, `#!...perl`, `#!...bash`, `#!...csh`/`#!...tcsh`,
+   `#!...ruby`, or `#!...pwsh` shebang → Python / Perl / Bash / Tcsh / Ruby /
+   PowerShell respectively.
+5. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
    hint: compile with debug info (`g++ -g -O0`) and debug the binary.
-5. `.ml` / `.mli` (OCaml source) produce an error too: build the project
+6. `.ml` / `.mli` (OCaml source) produce an error too: build the project
    first (dune's dev profile keeps debug info) and pass the **built
    executable** to `tdb` (`tdb ./_build/default/bin/main.exe`), never the
    `.ml` file.
-6. Anything else produces an error naming the `--lang` override.
+7. Anything else produces an error naming the `--lang` override.
 
 `--lang` forces the language; `--adapter` picks a non-default adapter within
 it (`tdb --lang cpp --adapter lldb-dap ./myprog`). Rust always requires the
@@ -316,23 +319,29 @@ non-standard location, or change a language's default adapter, add to
 Core debugging works identically for every language: breakpoints (incl.
 conditions and persistence), stepping, continue/pause, run-to-cursor, stack
 navigation, variable inspection, the evaluate console, syntax highlighting,
-and the JSON-RPC / MCP programmatic modes.
+and the JSON-RPC / MCP (v2) programmatic modes.
 
 Python-specific features are hidden or return "not supported for this
 language" message when debugging other languages: statement-granularity
-stepping (non-Python languages always step per line), the async task /
-process inspectors and wait graph, the evaluate console's trailing-`?` help,
+stepping (non-Python languages step at their debugger's native granularity
+— per line, except PowerShell, whose debugger stops per statement, see
+[PowerShell](#powershell)), the async task / process inspectors and wait
+graph, the evaluate console's trailing-`?` help,
 `--python`/`--pv`, `--no-subprocess`, automatic child-process attachment, and
 the post-mortem / `tdb.breakpoint()` hooks (those hooks live inside Python
 programs by nature). Remote attach (`-r`) also works for Perl (see
 [Perl](#perl), `Devel::TdbRemote` in place of `debugpy.listen()`), Ruby
-(see [Ruby](#ruby), `rdbg --open` in place of `debugpy.listen()`), and for
+(see [Ruby](#ruby), `rdbg --open` in place of `debugpy.listen()`), Go (see
+[Go](#go), `dlv dap --listen` in place of `debugpy.listen()`), and for
 Rust and C/C++ native binaries (against a gdbserver/lldb-server stub, with
 a local symbol-bearing executable; see [Rust](#rust) — the same flags work
-for a C/C++ target without `--lang`), but not for Bash, Tcsh, or OCaml. `--terminal` works for every launch-mode
+for a C/C++ target without `--lang`), but not for Bash, Tcsh, OCaml, or
+PowerShell. `--terminal` works for every launch-mode
 language — Python, Perl, Bash, Tcsh, Ruby, and C/C++, OCaml native, or Rust
 sessions via `--adapter lldb-dap` — see
-[External Terminal Support](#external-terminal-support).
+[External Terminal Support](#external-terminal-support). Go and PowerShell do
+not support `--terminal` yet (`dlv dap` and PSES have no terminal-routing
+mode).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature set than Python:
@@ -397,7 +406,30 @@ picture:
   reaches `tdb`). Run the program outside the debugger to see the
   backtrace instead.
 - No Windows support, no remote attach, and a stripped native binary that
-  byte-sniffing can't identify needs `--lang ocaml`.
+  byte-checking can't identify needs `--lang ocaml`.
+
+**Go limitations (v1):**
+
+- `--terminal` is not supported (`dlv dap` has no terminal-routing mode).
+- The Goroutines workspace's wait graph shows channel-send/-receive,
+  mutex, and `WaitGroup` edges; a goroutine parked in a `select` is
+  classified but contributes no wait edge (Delve can't tell which of the
+  `select`'s cases it's waiting on).
+- No mutex-holder identification: Go's `sync.Mutex` doesn't record an
+  owner at the runtime level, so unlike Python's Lock/Semaphore inspector
+  the wait graph can name what a goroutine is blocked on but never who
+  holds it.
+- Goroutines spawned by `exec.Command` (child OS processes) are not
+  automatically attached or debugged, unlike Python's automatic
+  multiprocessing child attach.
+- Detection of a Go binary via buildinfo check scans only the first
+  16MB of the file; a huge binary whose buildinfo blob sits beyond that
+  falls back to C/C++ — force it with `--lang go`.
+- `-a`/`--attach`'s language auto-detection (reading the target pid's
+  buildinfo from `/proc/PID/exe`) is Linux-only; on macOS/Windows pass
+  `--lang go` alongside `-a`.
+
+See [Go](#go) below for launch details.
 
 ### C/C++ tips
 
@@ -491,6 +523,24 @@ metadata for broader primitives and stronger ownership evidence.
 `perl` ≥ 5.18 on `PATH`. It drives stock `perl5db` under the
 hood, so it works with any Perl already on the system.
 
+The [PadWalker](https://metacpan.org/pod/PadWalker) module v2.5, by Robin Houston,
+is bundled with `tdb`.  PadWalker provides a more complete view of lexical variables
+in outer/caller frames and therefore provides a richer debugging experience.
+PadWalker is an XS (compiled) module, so the bundled copy has to be built
+against the exact perl that runs your program.  `tdb` does this for you on the
+first Perl launch: if the perl in use cannot already load PadWalker (from CPAN
+or a distro package), `tdb` compiles the bundled sources, caches the result
+per interpreter under its config directory (`~/.config/tdb/padwalker/` on
+Linux/macOS, `%APPDATA%\\tdb\\padwalker\\` on Windows), and prepends that
+directory to the debuggee's `PERL5LIB`.  The build takes about a second and
+needs perl's headers (`libperl-dev` on Debian/Ubuntu, `perl-devel` on
+Fedora/RHEL) plus a C compiler; Strawberry Perl on Windows ships both.  When
+the build is not possible, `tdb` prints a one-line notice on the console and
+falls back to a read-only pad walk, so outer-frame lexicals degrade but
+debugging otherwise proceeds.  `tdb --info` reports the source directory, the
+cache directory, and whether a build exists for the `perl` on your `PATH`.
+`TDB_PADWALKER_CACHE` overrides the cache location.
+
 **Launching a script:**
 
 ```bash
@@ -587,13 +637,6 @@ export PERL5LIB=/opt/tdb-perl:$PERL5LIB
 the two files in the same relative layout shown above; `helpers.pl` is a
 sibling of the `Devel/` directory, not inside it.)
 
-**PadWalker (optional but recommended):** inspecting lexical (`my`)
-variables in the *current* frame always works. Lexicals in outer/caller
-frames need the `PadWalker` module installed on the debuggee's Perl; without
-it, tdb falls back to a read-only pad walk that can't reach fully into
-enclosing scopes, and outer-frame variable listings degrade accordingly.
-Install with `cpanm PadWalker` (or your distro's package) for full fidelity.
-
 **Pause is unavailable in attach mode.** Launch-mode sessions (`tdb
 script.pl`) support pausing a running program at any time. Remote-attach
 sessions don't. Asynchronous pause (as Python gets via `debugpy`) needs a control channel
@@ -703,18 +746,35 @@ does). Always pass the **built executable** to `tdb`, never the `.ml`
 source, as in `tdb ./_build/default/bin/main.exe`, not `tdb main.ml` (which
 errors with this exact guidance).
 
+Earlybird additionally as a fragile relative path matching so for
+best results provide a fully quallified path to the source files.
+
+```
+ocamlc -g -o my_program.byte "$PWD/my_program.ml"
+```
+
+Then, to ensure transition from bytecode to OCaml source in the
+Code view, provide an explicit temporary breakpoint (`-t`) 
+at the first line of execution:
+
+```
+tdb --lang ocaml --adapter ocamlearlybird -t "$PWD/my_program.ml:2" ./my_program.byte
+```
+
 **OCaml version:** tdb requires **OCaml ≥ 4.12**. Older runtimes print
 `Printexc` backtraces without function names, which the fatal-error
 modal's parser does not understand (frames would be dropped and the
 modal would wrongly suggest recompiling with `-g`).
 
-```bash
-tdb ./_build/default/bin/main.exe          # native, lldb-dap
-tdb --adapter gdb ./_build/default/bin/main.exe   # native, gdb
-tdb ./_build/default/bin/main.byte         # bytecode, ocamlearlybird
-```
+With native GDB, the default entry stop is translated to the first
+executable line in project OCaml source; the generated C/ELF startup code is
+not shown.
+Unfortunately OCaml's native debug information does not always identify
+tihs line correctly.
+`--no-stop-on-entry` and explicit CLI breakpoints retain their
+usual behavior.
 
-A stripped native binary that byte-sniffing can't identify as OCaml falls
+A stripped native binary that byte-checking can't identify as OCaml falls
 back to C/C++; force it with `--lang ocaml`. Override the adapter or point
 at a non-`PATH` install in `config.json` (see
 [Configuration](#configuration)):
@@ -774,6 +834,139 @@ sessions can't `pause` a running program (so `--run` is unavailable for
 bytecode. Native sessions support `--run` normally); `Unix.fork` and Eio
 fibers are out of scope (only OCaml 5 domains are presented as threads).
 
+### Go
+
+`tdb` debugs Go through [Delve](https://github.com/go-delve/delve)'s own
+DAP server, `dlv dap` (Delve ≥ 1.21). Install it with:
+
+```bash
+go install github.com/go-delve/delve/cmd/dlv@latest
+```
+
+`dlv` must be on `PATH`, or point tdb at it with
+`{"adapters": {"dlv": "/path/to/dlv"}}` in `config.json`.
+
+**Launch modes** — `tdb` picks the right Delve mode automatically:
+
+```bash
+tdb main.go               # source file: `go run`-style debug mode
+tdb ./pkg                 # package directory: `go run`-style debug mode
+tdb ./binary               # pre-built Go binary (buildinfo-detected): exec mode
+tdb --test ./pkg          # Go test package: Delve test mode
+tdb -a PID                 # attach to a running local Go process by pid
+tdb -r host:port --lang go # attach to a `dlv dap --listen` already running remotely
+```
+
+`tdb --test ./pkg` debugs the package's tests under Delve's `test` mode;
+pass test-binary flags after `--`, e.g. `tdb --test ./pkg -- -run TestFoo`.
+`-a`/`--attach` currently supports Go only; on Linux, and only on Linux,
+`tdb` can identify the target as Go from `/proc/PID/exe`'s buildinfo
+without `--lang` (elsewhere pass `--lang go` alongside `-a`). Attaching
+stops the process immediately so you get control right away.
+
+**Remote attach:** start Delve's own DAP server against your program
+first —
+
+```bash
+dlv dap --listen=host:port ./binary
+```
+
+— then connect from `tdb`:
+
+```bash
+tdb -r host:port --lang go
+```
+
+Do not expose the port to an untrusted network; prefer an SSH tunnel.
+
+**Goroutine inspection:** in a Go session the Threads action (`Alt+T`, or
+the **Goroutines (N)** menu label) opens the Goroutines workspace while
+the debuggee is stopped — a fresh, bounded snapshot of goroutines, wait
+edges, and findings, the same shape as the Rust Concurrency workspace.
+Goroutines parked entirely in Go-runtime internals (GC workers,
+finalizers, netpoll) are hidden by default; press `a` to reveal them
+alongside the rest. The **Wait Graph** tab groups goroutines by the
+channel, mutex, or `WaitGroup` they're blocked on; the **Findings** tab
+surfaces stuck channels, mutex convoys, and likely leaks with a
+confidence level (`confirmed` vs `probable`) — Go mutexes never record an
+owner, so, unlike Python's Lock/Semaphore inspector, findings can name
+what's blocked but not who holds it. The snapshot collects up to 150
+goroutines; a busier program reports the header
+`Goroutines (150) — N more not collected` rather than silently truncating.
+Refresh (`r`) after the next stop to collect a new snapshot.
+
+**Limitations (v1):** `--terminal` is not supported (`dlv dap` has no
+terminal-routing mode); a goroutine parked in a `select` is classified but
+contributes no wait edge (Delve can't tell which case it's waiting on);
+no mutex-holder identification (impossible for Go's runtime); goroutines
+spawned indirectly via `exec.Command` child OS processes are not
+automatically attached; buildinfo-based binary detection scans only the
+first 16MB of the file (`--lang go` overrides for anything larger); `-a`'s
+`/proc`-based language auto-detection is Linux-only (pass `--lang go`
+alongside `-a` on macOS/Windows).
+
+### PowerShell
+
+tdb debugs PowerShell 7 scripts through [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices)
+(PSES), the Debug Adapter Protocol server behind the VS Code PowerShell
+extension. You need `pwsh` (>= 7.2; https://aka.ms/powershell) on PATH
+and the PSES module. tdb looks for the module in this order:
+
+1. `{"adapters": {"pses": "/path/to/PowerShellEditorServices"}}` in `config.json`
+2. the `TDB_PSES_PATH` environment variable
+3. the copy bundled with an installed VS Code PowerShell extension
+   (`~/.vscode/extensions/ms-vscode.powershell-*/modules/PowerShellEditorServices`)
+
+Without VS Code, download the release once:
+
+```bash
+mkdir -p ~/.local/share/tdb/pses && cd ~/.local/share/tdb/pses
+curl -sLO https://github.com/PowerShell/PowerShellEditorServices/releases/download/v4.7.0/PowerShellEditorServices.zip
+unzip -q PowerShellEditorServices.zip
+export TDB_PSES_PATH=~/.local/share/tdb/pses/PowerShellEditorServices
+```
+
+A `pwsh` that isn't on PATH can be named with `{"adapters": {"pwsh": "/path/to/pwsh"}}`.
+
+```bash
+tdb script.ps1               # launch, stop at the first statement
+tdb --run script.ps1         # run immediately, debug on demand (pause works)
+```
+
+Notes:
+
+- Entry stop lands on the first statement of your script (comments and
+  function definitions are skipped): PSES has no native `stopOnEntry` for
+  this launch shape, so tdb sets a synthetic breakpoint on the bundled
+  launcher, steps in, and clears it — no line-1 breakpoint appears in the
+  Breakpoint view.
+- The script runs inside that small bundled launcher (`tdb_launch.ps1`) so
+  tdb can report the script's exit code. In the Stack view, top to bottom:
+  PSES's `<Breakpoint>` marker frame (the frame to inspect — it tracks the
+  accurate current position), your script's own frames, the launcher's
+  `<ScriptBlock>`, and a source-less `Interactive Session` frame at the
+  bottom.
+- Stepping is statement-granular, as in VS Code: a line containing a
+  `$( ... )` subexpression takes two `next` presses to clear, and `stepIn`
+  first lands on the called function's declaration line before its body.
+- An uncaught terminating error ends the script with exit code 1 and opens
+  the fatal-error modal from pwsh's concise error text. Non-terminating
+  errors (`Write-Error`, failing cmdlets without `-ErrorAction Stop`) print
+  the same concise error block to the Console as stderr and let the script
+  continue with exit code 0, as in pwsh itself; there is no break-on-error
+  yet. The error block names the launcher's `& $Script` line rather than
+  your script's actual line for some error kinds (a known cosmetic
+  limitation).
+- The fatal-error modal is gated on a non-zero exit code, since pwsh prints
+  the identical block for terminating and non-terminating errors. A script
+  that reports a non-terminating error and then `exit 3` can therefore still
+  raise the modal, showing the last error block that names a file of yours;
+  blocks attributed to tdb's own `tdb_launch.ps1` are skipped, so a bare
+  `Write-Error` before the `exit` opens no modal at all.
+- `--terminal` and remote attach are not supported for PowerShell yet.
+- Windows PowerShell 5.1 is not supported (pwsh 7 only). Running tdb *on*
+  Windows against pwsh is designed for but not yet verified (experimental).
+
 ## Layout
 
 ```
@@ -900,7 +1093,9 @@ stops on each physical line--useful for inspecting how a complex expression is b
 The choice is saved to `~/.config/tdb/config.json`.
 
 Statement mode requires a source-language model and is currently Python-only;
-other languages always step per line (the Step Mode menu says so if you try).
+other languages step at their debugger's native granularity — per line,
+except PowerShell, whose debugger stops per statement, see
+[PowerShell](#powershell) (the Step Mode menu says so if you try).
 
 ### Breakpoints
 
@@ -1266,12 +1461,14 @@ sessions via `--adapter lldb-dap`. Neither `gdb -i dap` (the default C/C++
 adapter, and an alternate for native OCaml) nor `ocamlearlybird` (the
 bytecode OCaml adapter) has any terminal integration -- `tdb` rejects
 `--terminal` up front for both, with an error pointing at `--adapter
-lldb-dap` instead. `--terminal` also only applies when `tdb` launches the
-program itself; it is rejected for remote-attach (`-r`), since there's no
-program for `tdb` to spawn a terminal around.
+lldb-dap` instead. Go and PowerShell don't support `--terminal` either
+(`dlv dap` has no terminal-routing mode; PSES likewise). `--terminal` also
+only applies when `tdb` launches the program itself; it is rejected for
+remote-attach (`-r`), since there's no program for `tdb` to spawn a
+terminal around.
 
 The debuggee runs in a separate window of the specified terminal, including
-all of its stdin/stdout/stderr -- keyboard input, program output, and
+all of its stdin/stdout/stderr. Keyboard input, program output, and
 anything the program itself draws to the terminal all happen in that
 window, not in `tdb`'s Console View. Supported choices:
 `xterm`, `konsole`, `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`,
@@ -1309,10 +1506,58 @@ tdb --run my_program.py; echo $?   # my_program.py's own exit code
 **Interrupting:** press Ctrl-C in the terminal (any platform), or, on Unix, send
 `SIGUSR1` to `tdb`'s pid from another terminal: `kill -USR1 <tdb pid>`. Either one pauses
 the debuggee at its currently executing line and opens the TUI with full debugging
-available -- breakpoints, stepping, variable inspection, the evaluate console. The
+available (breakpoints, stepping, variable inspection, the evaluate console). The
 debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
 group), so its own `SIGINT` handling is undisturbed.
 
+**Examining without opening the TUI:** press `Ctrl-\` in the terminal (`Ctrl-Break` on
+Windows), or, on Unix, send `SIGUSR2` to `tdb`'s pid: `kill -USR2 <tdb pid>`.
+
+**Windows caveat:** the Ctrl-Break trigger is untested. Unlike Ctrl-C, a console
+Ctrl-Break is delivered to every process attached to the console, including the debug
+adapter and the program itself, so it may terminate the program instead of snapshotting
+it. There is no signal-based alternative on Windows.
+
+`tdb` pauses the program, writes one JSON line describing the call stack of every thread
+(plus asyncio tasks and multiprocessing children for Python, goroutines for Go, and
+the concurrency snapshot for Rust), and resumes the program. Ctrl-C behavior is
+unchanged. By default the line goes to stdout; `--examine-log DEST` sends it to a file
+instead (`-` means stdout; repeat the flag to write to several places):
+
+```bash
+tdb --run --examine-log hang.jsonl my_program.py     # file only, appended
+tdb --run --examine-log - --examine-log hang.jsonl my_program.py   # both
+```
+
+Each record looks like (abridged):
+
+```json
+{"schema":1,"seq":1,"trigger":"SIGQUIT","status":"ok",
+ "requested_at":"2026-09-07T14:02:11.482-07:00","landed_at":"2026-09-07T14:02:11.511-07:00",
+ "elapsed_s":87.3,"language":"python","program":"/home/al/work/app.py",
+ "processes":[{"pid":41213,"role":"parent","name":null,
+   "threads":[{"id":1,"name":"MainThread","frames":[
+     {"function":"wait","file":"/usr/lib/python3.13/threading.py","line":359},
+     {"function":"main","file":"/home/al/work/app.py","line":42}]}],
+   "tasks":[{"name":"worker-2","state":"PENDING","awaiting":"Lock.acquire","frames":["run (/home/al/work/app.py:18)"]}]}],
+ "errors":[]}
+```
+
+Frames are innermost first. `tasks` appears only for Python programs with live asyncio
+tasks; `goroutines` only for Go; `rust_concurrency` only for Rust. `status` is
+`"pending"` when the pause could not land within a few seconds (the program is blocked
+inside a single call) -- a second record with the same `seq` and `status: "ok"` follows
+when it does land. If you press Ctrl-C or the program exits before it lands, no
+completing record is written. `errors` lists any sub-collector that failed, so a partial
+record is explicit about what is missing. A stderr line confirms each capture and where
+it went.
+
+Narrow a long capture with `jq`, for example only threads with a frame in your own code:
+
+```bash
+jq -c '.processes[].threads[] | select(any(.frames[]; .file != null and (.file|test("/work/"))))' hang.jsonl
+```
+
 **Quitting an adopted session** adds a third choice to the usual quit dialog:
 - `d` (or `q`) -- detach and resume: the program keeps running headlessly; interrupt it
   again later the same way.
@@ -1327,18 +1572,61 @@ nonzero `sys.exit()`, which `debugpy` treats as an uncaught `SystemExit` -- `tdb
 the TUI at the point of failure instead of exiting silently, so you can inspect the
 crash. Exit-code passthrough applies only to a clean exit during the headless phase.
 
-Supported languages: Python, Perl, Bash, Tcsh, Ruby, C/C++ (both `gdb` and
-`lldb-dap`), and native OCaml (both `gdb` and `lldb-dap`; bytecode/
-`ocamlearlybird` sessions don't support pause, so `--run` is unavailable
-for those). `--run` is rejected up front for any other language.
+Supported languages: Python, Perl, Bash, Tcsh, Ruby, PowerShell 7, C/C++
+(both `gdb` and `lldb-dap`), and native OCaml (both `gdb` and `lldb-dap`;
+bytecode/`ocamlearlybird` sessions don't support pause, so `--run` is
+unavailable for those). `--run` is rejected up front for any other
+language.
 
 **Limitation:** pausing is cooperative. If the debuggee is blocked inside a single
 blocking external call or syscall, the pause can't land until that call returns --
 `tdb` prints a notice and opens the TUI once the stop actually arrives.
 
-**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--server`,
+**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--replay-tui`, `--server`,
 `--headless`, `--mcp`, `--terminal`.
 
+### Eval Mode (`-e`/`--eval`)
+
+Eval mode automates a common debugging loop--set a breakpoint, run to it,
+evaluate an expression in the Evaluate console, continue--without
+opening the TUI. `-e` takes two arguments, a location and an expression:
+
+```bash
+tdb --eval examples/digits_of_pi.py:25 "print(f'{nr=}')" examples/digits_of_pi.py
+```
+
+sets a breakpoint at line 25, runs the program, and each time that line is
+reached evaluates `print(f'{nr=}')` in the stopped frame, then continues.
+Program output and evaluation output both stream to the terminal; when the
+program exits, `tdb` exits with the same code (and with `1` if the session
+ends without one--as with a crash or killed adapter--so a scripted `tdb -e ...
+&& next` can trust the exit status). `Ctrl-C` stops the program and exits
+`130`. Under `multiprocessing`, an eval point placed in child code is
+evaluated in each child process that reaches it.
+
+- The location is `FILE:LINE`, or a bare `LINE` of the program being debugged,
+  and is snapped to the start of a logical statement just like `-k`.
+- `-e` may be repeated to plant several eval points in one run.
+- The expression is evaluated through the debug adapter (DAP `evaluate`,
+  context `repl`), just like the Evaluate console: side effects are real
+  and persist in the running program, for example 
+  `-e my_program.py:25 "limit = 10"` changes `limit` from line 25 onward.
+- A bare expression's result is printed to stdout; statement-style
+  expressions (`print(...)`, assignments) print nothing beyond their own
+  output. An expression error is reported on stderr and the run continues --
+  a typo isn't fatal, matching the Evaluate console.
+- Saved breakpoints are ignored, and any other stop (e.g. an
+  uncaught-exception stop) is continued untouched, so the program runs to
+  completion unattended.
+- For non-Python debuggees the expression must be in the debug adapter's
+  own syntax, for example gdb's `print x` / `set var x=3` for C/C++, and not
+  necessarily the debuggee's language. The adapter may bind the breakpoint
+  to the next executable line (gdb moves one off a declaration or brace);
+  the eval point matches that bound line, so the expression still runs.
+
+**Incompatible flags:** `--run`, `-r`, `-a`, `-k`/`-t`, `--record`,
+`--replay`, `--replay-tui`, `--server`, `--headless`, `--mcp`, `--terminal`.
+
 ### Keybinding Schemes
 
 ```bash
@@ -1459,14 +1747,29 @@ written to `session.jsonl` as
 JSON-RPC commands. Works with launch mode (any language) and `-r`
 remote attach.
 
-Replay it two ways:
-
+Replay it three ways:
+
+- `tdb --replay-tui session.jsonl` opens the normal TUI on the recorded
+  program and performs every recorded action in front of you, at the
+  recorded pace: breakpoints appear in the Code View, steps and continues
+  move the cursor, Evaluate entries echo into the console with their
+  results, stack navigation and variable expansion play out in their
+  panels. The title bar shows progress (`tdb ▶ session.jsonl 3/11`) and a
+  toast announces each action (`--replay-quiet` turns those toasts off).
+  A failed action raises an error toast and replay continues. When the recording does not end with `quit`, the
+  debugger stays open at the final stop for you to carry on by hand.
+  `--replay-interval S` waits a fixed S seconds before each action
+  instead of reproducing the recorded gaps. `--replay-timeout S` bounds
+  each stop-wait (default 30 s). Exit code 0
+  iff every action succeeded. Don't type into the TUI while it is
+  replaying: stray keystrokes interleave with the recorded actions.
 - `tdb --replay session.jsonl` launches the recorded
   program headless, feeds every recorded command through the same RPC
   dispatch `tdb --server` uses, and prints a transcript (recorded time,
   command, verbatim result, interleaved program output). Exit code 0 iff
   every command succeeded. Add `--timing` to reproduce the original
-  pacing, `--replay-timeout S` to bound each stop-wait (default 30 s).
+  pacing or `--replay-interval S` for a fixed delay before each command,
+  `--replay-timeout S` to bound each stop-wait (default 30 s).
 - Against a live server: start `tdb --server prog.py`, then feed line 2
   onward of the file to `POST /rpc` . Each line is a valid request body:
 
@@ -1483,9 +1786,10 @@ lists), breakpoint enable/disable toggles, variable expansions when the
 adapter reports no `evaluateName` (currently the Perl adapter), and
 File > Open program switches.
 
-## MCP Integration
+## MCP v2 Integration
 
-tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+tdb ships a Model Context Protocol (MCP), version 2,
+server (`tdb-mcp`) that exposes
 the debugger as a curated set of tools an AI agent can call. The MCP
 server is a third in-process consumer of the same dispatch handlers the
 TUI and the HTTP server use so an agent gets the same lock semantics,
@@ -1583,7 +1887,7 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
-           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text]
+           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text] [--info]
            [program] [args ...]
 ```
 
@@ -1610,6 +1914,14 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--server` | Enable JSON-RPC server alongside TUI |
 | `--headless` | JSON-RPC server only, no TUI |
 | `--server-port PORT` | Server port (default: 8150) |
+| `--record FILE` | Record this TUI session's debugging actions to FILE (JSON-RPC lines) |
+| `--replay FILE` | Replay a recording headless, printing a transcript (no program argument) |
+| `--replay-tui FILE` | Replay a recording inside the TUI at the recorded pace, so you can watch it |
+| `--replay-quiet` | With `--replay-tui`: no per-action toasts (errors and the final summary still show) |
+| `--timing` | With `--replay`: reproduce the recorded pacing (`--replay-tui` always does) |
+| `--replay-interval S` | With `--replay`/`--replay-tui`: fixed S-second delay before each action instead of the recorded gaps |
+| `--replay-timeout S` | With `--replay`/`--replay-tui`: per-action stop-wait timeout (default 30) |
+| `--examine-log DEST` | With --run: write each Ctrl-\ / SIGUSR2 stack snapshot to DEST (- = stdout; repeatable) |
 
 ## Configuration
 
@@ -1634,6 +1946,10 @@ found; it's Python code, not an external executable), so
 `{"adapters": {"perl": "/path/to/perl"}}`. Use this when the `perl` on
 `PATH` is too old (< 5.18) or you need a specific `perlbrew`/`plenv` version.
 
+**PowerShell** follows the same pattern with two keys: `adapters.pwsh` names
+the interpreter and `adapters.pses` names the PowerShell Editor Services
+module directory (see [PowerShell](#powershell)).
+
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent. Breakpoints set with
 `-t`/`--to-line` are the exception: they behave like `-k` breakpoints during
@@ -1666,6 +1982,28 @@ fires as expected.
 
 MIT
 
+## Acknowledgments
+
+Thank you:
+
+- Will McGugan for the amazing `textual` module.
+`tdb` would be a pale shadow of itself had I used any other TUI framework.
+Fantastic work, Will.
+
+- Microsoft for the Debug Adapter Protocol (DAP) and releasing
+its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
+as open source.
+
+- Anthropic, for providing access to Claude Code through the
+[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
+`tdb` was made almost entirely with Claude Code.
+
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
+Python debugger.
+
 
 ## Known Problems