textual-debugger 0.2.6__tar.gz → 0.2.10__tar.gz

{textual_debugger-0.2.6 → textual_debugger-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.6
+Version: 0.2.10
 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,7 +49,7 @@ 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
@@ -73,16 +73,18 @@ a full-featured terminal-based debugger for Python and other languages
 with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
 `tdb` comes with built-in support for
 - C and C++ (via `gdb` or `lldb-dap`)
+- Rust (via `gdb` or `lldb-dap`, selected explicitly)
 - Perl (via `perl -d`)
 - Bash (via bash's own `DEBUG` trap; bash ≥ 4.4)
 - 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: [debugpy](https://github.com/microsoft/debugpy)
-(the engine behind VS Code's Python debugger) for Python,
-[GDB's DAP mode](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) or
-[lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)
-for compiled code. It provides a rich interactive interface for stepping through
+DAP to a pluggable debug adapter.
+It provides a rich interactive interface for stepping through
 code, inspecting variables, managing breakpoints, and evaluating expressions in
 complex programs.
 
@@ -96,10 +98,14 @@ MIT License.  Copyright 2026 by Al Danial.
 `tdb`:
 
 - debugs multiple languages through the Debug Adapter Protocol: Python (via `debugpy`,
-the richest feature set), C/C++ (via `gdb -i dap` or `lldb-dap`), Perl (via `perl -d`),
-Bash (via bash's own `DEBUG` trap), and Tcsh (via source instrumentation of a
-stock `tcsh`), with the language
-auto-detected from the target (ref. [Multi-Language Debugging](#multi-language-debugging)).
+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`), 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)).
 
 - supports debugging of synchronous, asynchronous, multi-threaded, and multi-process Python code.
 It specifically supports modules
@@ -107,7 +113,7 @@ 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 debugpy-enabled Python 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
 programmatic debug control, making it suitable for
@@ -142,7 +148,8 @@ as open source.
 - 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/) debugger.
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
+Python debugger.
 
 ## Gallery
 <p align="center">
@@ -208,6 +215,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
 
@@ -234,6 +245,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
 ```
@@ -246,32 +262,58 @@ python -m tdb my_program.py
 
 ## Multi-Language Debugging
 
-`tdb` debugs any language that has a Debug Adapter Protocol backend. Five
+`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 |
 |----------|------------|------------------------|---------------|
 | Python | `debugpy` (default) | Python ≥ 3.11 | everything in this README |
-| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
+| Rust (explicit `--lang rust`) | `gdb` (Linux default), `lldb-dap` (macOS default) | any rustc building with debug info; GDB ≥ 14 or LLVM `lldb-dap` ≥ 17 (concurrency ownership evidence additionally requires stable Rust 1.98) | core debugging + best-effort Rust concurrency inspection + remote attach |
 | Perl | perl-tdb (bundled) | perl ≥ 5.18 on PATH  | core debugging + remote attach |
 | 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) | `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.
-2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
-3. A `#!...python`, `#!...perl`, `#!...bash`, or `#!...csh`/`#!...tcsh`
-   shebang → Python / Perl / Bash / Tcsh respectively.
-4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+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) → 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. Anything else produces an error naming the `--lang` override.
+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.
+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`).
+it (`tdb --lang cpp --adapter lldb-dap ./myprog`). Rust always requires the
+explicit language selection (`tdb --lang rust target/debug/app`).
 
 > **Migration note:** extensionless Python scripts without a `python` shebang
 > were previously assumed to be Python; they now require `--lang python`.
@@ -299,18 +341,28 @@ and the JSON-RPC / MCP 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()`), but not
-for C/C++, Bash, or Tcsh. `--terminal` works for every launch-mode
-language — Python, Perl, Bash, Tcsh, and C/C++ via `--adapter lldb-dap` —
-see [External Terminal Support](#external-terminal-support).
+[Perl](#perl), `Devel::TdbRemote` in place of `debugpy.listen()`), Ruby
+(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, 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). 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 envelope than Python/Perl:
+has a smaller feature set than Python:
 
 - Debuggee code that installs its own `DEBUG` trap clobbers the harness;
   debugging silently degrades to free-running.
@@ -354,9 +406,53 @@ paths and line numbers are preserved in everything tdb displays):
 
 See [Tcsh](#tcsh) below for launch details.
 
+**OCaml limitations (v1):** OCaml has two independent adapters with
+different, non-overlapping gaps; see [OCaml](#ocaml) below for the full
+picture:
+
+- **Native (`lldb-dap`/`gdb`):** the Variables view shows no named OCaml
+  locals in an OCaml frame (only a `Registers` scope). This is an
+  upstream OCaml/DWARF limitation on stock OCaml 5.4, not a `tdb` bug; use
+  the bytecode adapter when you need to inspect locals. The evaluate
+  console evaluates lldb/C-level expressions (runtime spelunking), not
+  OCaml expressions.
+- **Bytecode (`ocamlearlybird`):** single-domain only (no multicore); no
+  `pause` while running (so `--run` is unavailable); the evaluate console
+  never gets a response for any expression (an `ocamlearlybird` 1.3.6
+  limitation); and the fatal-error modal doesn't appear for an uncaught
+  exception (`ocamlearlybird` swallows the real exception text before it
+  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-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
 
-- Compile with `-g` (ideally `-g -O0`). If no breakpoint in a file can be
+- Compile with `-g` (ideally `-g -O0` or `-g3 -O0`).
+  If no breakpoint in a file can be
   bound, `tdb` prints a console warning suggesting the program may lack
   debug info.
 - Stack frames pointing into system libraries often have no source on disk;
@@ -373,6 +469,72 @@ See [Tcsh](#tcsh) below for launch details.
   requires `--adapter lldb-dap`; GDB's DAP mode has no terminal integration
   and `tdb` refuses `--terminal` with the default `gdb` adapter.
 
+### Rust
+
+Rust debugging is intentionally explicit: build a normal debug executable,
+leave it unmodified, and pass that executable with `--lang rust`. Linux and
+macOS are supported; Windows is not yet (MSVC-toolchain binaries carry PDB
+debug info that neither `gdb -i dap` nor this release's probes read). `tdb` does
+not compile, instrument, or auto-detect Rust programs. Core debugging
+(breakpoints, stepping, stacks, variables, remote attach) works with any
+rustc that emits debug info; the concurrency inspector's layout-specific
+*ownership evidence* additionally requires the current stable Rust
+**1.98** standard-library layout — on other versions the workspace still
+opens with stack-based wait classification and a compatibility warning.
+Build with debug information and no optimization for the most useful
+source locations:
+
+```bash
+cargo rustc -- -C debuginfo=2 -C opt-level=0
+# Equivalent direct rustc settings: rustc -C debuginfo=2 -C opt-level=0 src/main.rs
+```
+
+A panic that terminates the debuggee opens the error modal with the parsed
+panic message and backtrace; `tdb` injects `RUST_BACKTRACE=1` into launched
+programs (your own value wins if you set one) so the frames are present.
+
+The common commands are:
+
+```bash
+cargo build
+tdb --lang rust target/debug/app
+tdb --lang rust --adapter lldb-dap --run target/debug/app
+tdb --lang rust --adapter lldb-dap --terminal xterm target/debug/app
+tdb --lang rust --adapter gdb --remote-attach host:2345 target/debug/app
+```
+
+`--run` and normal stopped-on-entry launch work with both adapters. On Linux,
+use GDB (the default) or `lldb-dap`; on macOS, use `lldb-dap` (the default).
+External terminals are LLDB-only: GDB's DAP mode cannot provide terminal
+integration. The mode/platform matrix is:
+
+| Platform | Normal / `--run` | `--terminal` | `--remote-attach` |
+|----------|------------------|--------------|-------------------|
+| Linux | GDB or `lldb-dap` | `lldb-dap` only | GDB or `lldb-dap` |
+| macOS | `lldb-dap` | `lldb-dap` only | `lldb-dap` |
+
+Remote attach connects to a GDB-remote server already running on the target.
+Pass the matching **local, unmodified executable with debug symbols** as the
+program argument; `tdb` requires it for symbols and Rust concurrency evidence.
+When source paths differ, pair `--local-root` with `--remote-root`. Do not
+expose the remote debug port to an untrusted network: prefer an SSH tunnel,
+for example `ssh -L 2345:127.0.0.1:2345 host`, then attach to `127.0.0.1:2345`.
+
+In a Rust session the Threads action (`Alt+T`, or the Threads menu entry)
+opens the Rust Concurrency workspace while the debuggee is stopped — a
+fresh, bounded snapshot of threads, wait edges, and findings. The graph is
+best effort: `confirmed` evidence is directly observed by the debugger,
+`probable` is a supported inference, and `unknown` means ownership could not
+be established. A deadlock is confirmed only when every edge in its cycle is
+confirmed. A suspected cycle or whole-program stall is a diagnostic lead, not
+a proof: it means a cycle has incomplete evidence, or all observed application
+threads are blocked while the graph cannot safely invent an owner. Refresh
+after the next stop to collect a new snapshot.
+
+The built-in evidence recognizes current `std` synchronization layouts. A
+future helper crate may expose stable, application-provided synchronization
+metadata for broader primitives and stronger ownership evidence.
+
 ### Perl
 
 `tdb` bundles its own Perl adapter (`perl-tdb`) so only need
@@ -549,6 +711,269 @@ text directly in the paused shell. It can inspect *and mutate* state
 (`set name = value` takes effect immediately), and a syntax error in
 evaluated text can terminate the debuggee; there is no isolation.
 
+### Ruby
+
+tdb debugs Ruby via the [debug gem](https://github.com/ruby/debug)'s
+`rdbg` (Ruby >= 3.1 ships it; otherwise `gem install debug`; tdb needs
+debug >= 1.9). `rdbg` must be on PATH, or point tdb at it with
+`{"adapters": {"rdbg": "/path/to/rdbg"}}` in config.json.
+
+```bash
+tdb script.rb                # launch, stop at first line
+tdb --run script.rb          # run immediately, debug on demand
+tdb --terminal script.rb     # program I/O in its own terminal
+```
+
+Remote attach: start the program with
+`rdbg --open --port 5678 --host 0.0.0.0 script.rb` (add `--nonstop` to
+let it run before you attach), then `tdb -r HOST:5678 --lang ruby`.
+Note: rdbg's `--cookie` authentication is not part of DAP and is not
+supported; bind to localhost and tunnel over SSH instead.
+`--local-root`/`--remote-root` path mappings are not supported for Ruby
+yet. Bundler projects work when your environment resolves `rdbg`
+(`gem install debug` into the project's Ruby); there is no `bundle
+exec` integration yet.
+
+> **Startup note:** the debug gem's `rdbg` has an occasional handshake
+> race on launch; tdb detects a stalled/corrupted handshake and retries
+> once automatically with a fresh `rdbg`, so this is usually invisible.
+
+### OCaml
+
+`tdb` debugs OCaml through two independent adapters, chosen automatically
+from how the executable was built:
+
+- **Native** (`ocamlopt`/dune's default build) → **`lldb-dap`** (default;
+  `--adapter gdb` also works). OCaml 5's domains show up as threads.
+- **Bytecode** (`ocamlc -g`) → **`ocamlearlybird`** (`opam install
+  earlybird`). Single-domain only, but with rich, real OCaml locals.
+
+**Build requirement:** compile with `-g` (dune's dev profile already
+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`).
+
+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-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)):
+
+```json
+{
+  "adapters": {"ocamlearlybird": "/path/to/ocamlearlybird"},
+  "default_adapters": {"ocaml": "gdb"}
+}
+```
+
+**Domains as threads (native only):** OCaml 5's domains are presented in
+the Threads modal (`Alt+T` or the **Threads (N)** menu label) as `Domain 0
+(main)`, `Domain 1`, and so on, in creation order. The runtime's internal
+"backup thread" (one per domain, used for I/O blocking) is hidden by
+default since it's never running user code; press `a` in the Threads
+modal to reveal it alongside the domains. Breakpoints, stepping, continue,
+and pause all work normally against any domain. In both the Stack view
+and the Threads modal, OCaml frame names are demangled from the
+runtime's raw `camlModule__name_NNN` convention into readable
+`Module.name` form (e.g. `camlOcaml_domains.worker_297` displays as
+`Ocaml_domains.worker`); runtime C frames (`caml_start_program`,
+`caml_callback_exn`, and the like) are shown as-is, unchanged.
+
+**Variables view (native):** stock OCaml 5.4 native DWARF shows **no
+named locals**. The `scopes`/`variables` round trip succeeds, but every
+OCaml frame's `Locals` and `Globals` scopes come back empty; only a
+`Registers` scope has data (the raw register file, not decoded OCaml
+values). This is an upstream OCaml compiler/DWARF limitation on the
+verified toolchain (OCaml 5.4.0 / lldb 21), not a `tdb` bug. If you need
+to inspect local variables, use the bytecode adapter instead.
+
+**Variables view (bytecode):** `ocamlearlybird` reports real local names
+and values, exactly like Python locals.
+
+**Evaluate console:** the two adapters give fundamentally different
+consoles. Native (`lldb-dap`) evaluates **lldb/C-level expressions**.
+This is runtime spelunking (registers, raw memory, C symbol names), not
+OCaml expression evaluation. Bytecode (`ocamlearlybird`) is meant to
+evaluate real OCaml expressions in scope, but in the verified
+`ocamlearlybird` 1.3.6 release its `evaluate` request never responds (a
+confirmed upstream limitation, not specific to `tdb`); the console
+silently returns nothing for any expression.
+
+**Uncaught exceptions:** native sessions set a breakpoint on
+`caml_fatal_uncaught_exception` so the debugger stops there, and `tdb`
+also parses the `OCAMLRUNPARAM=b` backtrace it injects into the debuggee's
+environment once the process exits, opening the same error modal Python
+tracebacks get. Bytecode sessions do **not** get this: `ocamlearlybird`
+intercepts the uncaught exception itself and only reports a generic
+"Program exited due to Uncaught_exc" message, so the real exception text
+never reaches `tdb`. Run the program outside the debugger
+(`OCAMLRUNPARAM=b ./main.byte`) to see its backtrace.
+
+**Limitations (v1):** no Windows support; no remote attach; bytecode
+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
 
 ```
@@ -604,6 +1029,11 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | `Alt+A` | Async Tasks |
 | `Alt+H` | Help (Documentation, About) |
 
+File > Open works for every supported language: the file picker filters to
+the current session's language (by extension) and refuses a pick that
+detects as a different language, so you can only switch to another script
+written in the same language as the one currently being debugged.
+
 **Navigation (vim-style by default):**
 
 By default the Code View is in Debug mode.  Hit `Escape` to switch to Navigate mode
@@ -661,7 +1091,7 @@ results = await asyncio.gather(
     fetch(2, 1),
     fetch(3, 3),
 )
-print(results)   # next stop lands here, not on each sub-line above
+print(results)  # next stop lands here, not on each sub-line above
 ```
 
 lands on `print(results)`, not on each interior sub-line of the `gather` call. Switch to
@@ -670,7 +1100,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
 
@@ -771,6 +1203,7 @@ need to launch through `tdb` up front. Install the hook once at the top of your
 ```python
 import sys
 import tdb
+
 sys.excepthook = tdb.exception_hook
 ```
 
@@ -819,6 +1252,7 @@ continuing--use `tdb.breakpoint()`:
 ```python
 import tdb
 
+
 def compute(n):
     total = sum(range(n))
     tdb.breakpoint()  # pause here and drop into tdb
@@ -961,6 +1395,7 @@ where you want to attach the debugger:
 ```python
 # In the target program:
 import debugpy
+
 debugpy.listen(("0.0.0.0", 5678))
 print("Waiting for tdb to attach on port 5678...")
 debugpy.wait_for_client()  # optional: pause until debugger connects
@@ -1028,15 +1463,19 @@ tdb --terminal xterm my_tui_app.py
 ```
 
 `--terminal` works for every language `tdb` can *launch* (as opposed to
-attach to): Python, Perl, Bash, Tcsh, and C/C++ via `--adapter lldb-dap`.
-The default C/C++ adapter, `gdb -i dap`, has no terminal integration --
-`tdb` rejects `--terminal` up front 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.
+attach to): Python, Perl, Bash, Tcsh, Ruby, and C/C++ or native OCaml
+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. 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`,
@@ -1048,9 +1487,17 @@ This feature only works in graphical environments where external terminals are a
 
 ### Run Mode (`--run`)
 
-For inspecting a program that appears hung: run it headless, at full speed, with no
-breakpoints installed and no stop-on-entry, then drop into the full TUI the moment you
-actually need it -- without paying for either up front.
+`tdb`'s run mode invokes an unmodified program nearly at full speed, without bringing up the TUI.
+At any point afterwards, hitting `Ctrl-C` in that terminal pauses the program
+and drops you into the full TUI.
+From there you can inspect the program's state, navigate the stack, set and continue
+to breakpoints, and so on.  After you finish inspecting, hitting `q` to quit brings up
+a modal that lets you either detach from the TUI and let the program resume running,
+or lets you terminate it.
+
+The primary use cases for run mode are: (1) allowing inspection of a program that
+appears hung, and (2) finding where a program execution path lands after it
+receives a problematic input.
 
 ```bash
 tdb --run my_program.py args...
@@ -1066,7 +1513,7 @@ 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.
 
@@ -1084,8 +1531,11 @@ 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, and C/C++ (both `gdb` and `lldb-dap`).
-`--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 --
@@ -1094,6 +1544,48 @@ blocking external call or syscall, the pause can't land until that call returns
 **Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--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`, `--server`, `--headless`, `--mcp`, `--terminal`.
+
 ### Keybinding Schemes
 
 ```bash
@@ -1129,7 +1621,9 @@ Both the interactive TUI and the JSON-RPC server run simultaneously.
 ### RPC Protocol
 
 Send POST requests with `{"action": "...", "params": [...]}`. Responses return
-`{"timestamp": "...", "success": true/false, "value": "..."}`.
+`{"timestamp": "...", "success": true/false, "value": "..."}`. Actions with a
+structured result (today only `rust_concurrency`) additionally carry a `data`
+object holding the full JSON payload; `value` then holds a one-line summary.
 
 ```bash
 # Check status
@@ -1187,6 +1681,7 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `list_tasks` | `[]` | List all asyncio tasks |
 | `inspect_task` | `["task_name"]` | Inspect a specific asyncio task |
 | `wait_graph` | `[]` | Show wait graph + any deadlock cycles |
+| `rust_concurrency` | `[]` | Structured Rust thread/wait/deadlock snapshot in `data` (Rust sessions, stopped) |
 | `restart` | `[]` | Restart session (preserves breakpoints) |
 | `quit` | `[]` | Shut down |
 
@@ -1269,7 +1764,7 @@ point), `tdb --mcp` (the main CLI with the `--mcp` switch), and
 `python -m tdb.mcp` (module form). Pick whichever matches how your MCP
 client expects to launch servers.
 
-### Tool surface (16 tools, curated)
+### Tool surface (17 tools, curated)
 
 | Cluster | Tools |
 |---------|-------|
@@ -1277,7 +1772,7 @@ client expects to launch servers.
 | Control | `control(action, timeout_s=30)` where `action ∈ {continue, next, step_in, step_out, pause, wait_for_stop}` |
 | Inspection | `inspect(expressions)`, `read_source(file_path)`, `stack_trace()`, `status()`, `get_output()` |
 | Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
-| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
+| Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()`, `rust_concurrency()` |
 
 `control` is intentionally one tool that takes an action enum. The six
 underlying RPC actions share a return shape, and agents perform
@@ -1288,9 +1783,10 @@ single optional argument for the same reason.
 `debug_launch` accepts optional `lang` and `adapter` parameters mirroring the
 CLI's `--lang`/`--adapter`; when omitted, the language is auto-detected from
 `program`, so an agent can hand it a compiled binary directly. The
-`tasks`/`processes`/`wait_graph` tools stay registered for every language but
+exception is Rust: compiled native binaries require explicit `lang="rust"`.
+The `tasks`/`processes`/`wait_graph` tools stay registered for every language but
 return a structured "not supported when debugging C/C++"-style error for
-non-Python debuggees.
+non-Python debuggees; `rust_concurrency` does the same for non-Rust debuggees.
 
 ### Agent flow for a long-running step
 
@@ -1385,6 +1881,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
@@ -1408,6 +1908,8 @@ fires as expected.
 - [textual](https://github.com/Textualize/textual) : TUI framework
 - [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation for Python
 - [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++
+- [debug gem](https://github.com/ruby/debug) (`rdbg`) : optional, user-installed DAP adapter for Ruby
+- [ocamlearlybird](https://github.com/hackwaly/ocamlearlybird) : optional, user-installed DAP adapter for OCaml bytecode (native OCaml reuses `gdb`/`lldb-dap`)
 - [pygments](https://pygments.org/) : Syntax highlighting
 - [FastAPI](https://fastapi.tiangolo.com/) + [uvicorn](https://www.uvicorn.org/) : JSON-RPC server