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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.4
+Version: 0.2.8
 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:
@@ -73,16 +73,16 @@ 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))
 
 `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 +96,13 @@ 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`), and OCaml (native via
+`lldb-dap`/`gdb`, bytecode via ocamlearlybird). 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 +110,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, and C/C++ 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,6 +145,9 @@ 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/)
+Python debugger.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -244,32 +250,49 @@ 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. Eight
 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) | 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 |
 
 ### 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.
+   → 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
+   `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
    hint: compile with debug info (`g++ -g -O0`) and debug the binary.
-5. Anything else produces an error naming the `--lang` override.
+5. `.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.
 
 `--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`.
@@ -302,12 +325,17 @@ 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` is
-currently ignored for non-Python targets.
+[Perl](#perl), `Devel::TdbRemote` in place of `debugpy.listen()`), Ruby
+(see [Ruby](#ruby), `rdbg --open` 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
+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).
 
 **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.
@@ -351,9 +379,30 @@ 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-sniffing can't identify needs `--lang ocaml`.
+
 ### 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;
@@ -366,6 +415,75 @@ See [Tcsh](#tcsh) below for launch details.
   commands, so evaluate expressions with an explicit `print`, e.g.
   `print x` rather than bare `x` (bare `x` collides with GDB's
   examine-memory command). `lldb-dap` evaluates bare expressions directly.
+- `--terminal` (see [External Terminal Support](#external-terminal-support))
+  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
 
@@ -379,6 +497,9 @@ hood, so it works with any Perl already on the system.
 tdb script.pl
 ```
 
+`--terminal` is supported (see
+[External Terminal Support](#external-terminal-support)).
+
 **Compile-time code (`BEGIN` blocks):** Perl runs `BEGIN` blocks and the
 `use` statements that are themselves `BEGIN` blocks while it is still
 *compiling* your program, before stock `perl5db` ever stops. `tdb` arms the
@@ -500,7 +621,8 @@ Most notably, a breakpoint can't be set on a `func() {` line itself (the
 `DEBUG` trap never fires there), stops never land inside subshells or
 pipeline segments, child bash processes run uninstrumented, and only the
 innermost frame's locals are inspectable. There is no remote-attach mode for
-Bash.
+Bash. `--terminal` is supported (see
+[External Terminal Support](#external-terminal-support)).
 
 The Variables view shows three scopes for bash: Locals (innermost frame
 only), Globals (unexported shell variables), and Environment (exported
@@ -529,7 +651,8 @@ stack navigation across `source` nesting, variable inspection, and the
 evaluate console with the v1 caveats listed in
 [What works for non-Python languages](#what-works-for-non-python-languages),
 most notably: no conditional breakpoints, no pause of a free-running
-script, and stepping is per logical source line.
+script, and stepping is per logical source line. `--terminal` is supported
+(see [External Terminal Support](#external-terminal-support)).
 
 The Variables view shows four scopes for tcsh: Shell Variables (`set`),
 Environment (`setenv`), Aliases, and Arguments (`argv`). All of them show
@@ -538,6 +661,119 @@ 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).
+
+**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
+```
+
+A stripped native binary that byte-sniffing 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).
+
 ## Layout
 
 ```
@@ -593,6 +829,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
@@ -650,7 +891,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
@@ -760,6 +1001,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
 ```
 
@@ -808,6 +1050,7 @@ continuing--use `tdb.breakpoint()`:
 ```python
 import tdb
 
+
 def compute(n):
     total = sum(range(n))
     tdb.breakpoint()  # pause here and drop into tdb
@@ -950,6 +1193,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
@@ -1007,22 +1251,94 @@ application directory and a shared library directory) in one invocation.
 
 ### External Terminal Support
 
-Some Python programs, notably text user interfaces, use terminal control
-codes and require direct access to the terminal to function properly. 
-Such programs can be debugged with `tdb` by having it launch the debuggee in
-a separate terminal:
+Some programs, notably text user interfaces, use terminal control codes and
+require direct access to the terminal to function properly. Such programs
+can be debugged with `tdb` by having it launch the debuggee in a separate
+terminal:
 
 ```bash
 tdb --terminal xterm my_tui_app.py
 ```
 
-The debuggee runs in a separate window of the specified terminal. Supported choices:
+`--terminal` works for every language `tdb` can *launch* (as opposed to
+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. `--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
+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`,
 `wezterm`, `terminator`. The selected terminal must be on `PATH`. Debugging
-proceeds as usual in the terminal where `tdb` was invoked.
+(breakpoints, stepping, variable inspection, the evaluate console) proceeds
+as usual in the terminal where `tdb` was invoked.
 
 This feature only works in graphical environments where external terminals are available.
 
+### Run Mode (`--run`)
+
+`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...
+```
+
+The debuggee's stdout/stderr stream straight to the terminal. If the program exits on
+its own, `tdb` exits with the same code:
+
+```bash
+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
+debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
+group), so its own `SIGINT` handling is undisturbed.
+
+**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.
+- `t` -- terminate the program and quit `tdb`.
+- `Esc` -- cancel, stay in the TUI.
+
+A breakpoint set during one of these episodes stays live after you detach; if it's hit,
+`tdb` reopens the TUI there, just like an interrupt.
+
+If the program instead dies on an unhandled exception -- in Python this includes a
+nonzero `sys.exit()`, which `debugpy` treats as an uncaught `SystemExit` -- `tdb` opens
+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.
+
+**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`,
+`--headless`, `--mcp`, `--terminal`.
+
 ### Keybinding Schemes
 
 ```bash
@@ -1058,7 +1374,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
@@ -1116,6 +1434,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 |
 
@@ -1198,7 +1517,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 |
 |---------|-------|
@@ -1206,7 +1525,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
@@ -1217,9 +1536,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
 
@@ -1337,6 +1657,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