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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.10
+Version: 0.2.14
 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:
@@ -53,7 +53,9 @@ 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: edit
+Requires-Dist: textual[syntax]>=8.0.0; extra == "edit"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -115,7 +117,7 @@ It specifically supports modules
 
 - 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
 
@@ -123,34 +125,16 @@ automated, headless debugging workflows and AI-assisted debugging
 built with `textual`, `prompt-toolkit`, `urwid`, `curses`, `rich`, and so on
 
 - comes with a post-mortem exception hook that can be installed in Python programs
-to have `tdb` pop open automatically at the first uncaught exception
+to have `tdb` pop open automatically at the first uncaught exception, and a live
+breakpoint hook (`tdb.breakpoint()` in Python, `Devel::TdbRemote::breakpoint()`
+in Perl, `Tdb.breakpoint` in Ruby, `tdb.Breakpoint()` in Go, `tdb_breakpoint()`
+in C/C++, `tdb::breakpoint()` in Rust, `Tdb.breakpoint ()` in OCaml) that opens
+`tdb` paused at a line of your choosing
 
 - can be entirely keyboard-driven
 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">
@@ -190,7 +174,13 @@ uvx --from textual-debugger tdb  my_program.py
 # show comprehensive documentation in a terminal-based Markdown viewer
 tdb --doc
 
-# debug a script (stops at first line by default)
+# show the Help > About text, where tdb and its config, breakpoints and
+# log files live, and the path + version of each interpreter and native
+# debugger it would use (python, gdb, lldb-dap, perl, ruby, dlv,
+# ocamlearlybird, bash, tcsh, pwsh)
+tdb --info
+
+# debug a Python program (stops at first line by default)
 tdb my_program.py
 
 # debug with arguments
@@ -225,7 +215,7 @@ tdb --python /path/to/venv/bin/python my_program.py
 # step into, or stop at tracebacks in library code
 tdb --no-just-my-code --python /path/to/venv/bin/python my_program.py
 
-# run until first breakpoint or exit
+# run until first breakpoint (persisted during a prior run) or exit
 tdb --no-stop-on-entry my_program.py
 
 # run the debuggee in an external terminal
@@ -250,7 +240,7 @@ tdb -r remotehost:5678 --local-root /my/code/dir --remote-root /app -k my_progra
 # attach, which can leave it suspended after tdb quits
 tdb -r remotehost:5678 --no-pause-on-attach
 
-# separate tdb arguments from debuggee arguments with `--` 
+# separate tdb arguments from debuggee arguments with `--`
 tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
 
@@ -268,7 +258,7 @@ 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 + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14 built with Python (RHEL 8/9: `dnf install gcc-toolset-14-gdb`, see [C/C++ tips](#cc-tips)); `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) |
@@ -315,6 +305,23 @@ The language is auto-detected from the debug target:
 it (`tdb --lang cpp --adapter lldb-dap ./myprog`). Rust always requires the
 explicit language selection (`tdb --lang rust target/debug/app`).
 
+`--adapter` also accepts a full path to a `gdb`, `lldb-dap`, or `dlv`
+executable (`tdb --adapter /opt/llvm/bin/lldb-dap ./myprog`,
+`tdb --adapter /usr/bin/gdb-multiarch ./myprog`,
+`tdb --adapter ~/go/bin/dlv ./main.go`). The adapter id is taken from the
+file's basename — versioned and variant names such as `lldb-dap-21` and
+`gdb-multiarch` work — and that exact executable is used for the session,
+ahead of anything on `$PATH` or in `config.json`'s `adapters` map.
+`tdb --info` shows which `gdb` and `lldb-dap` would be used otherwise.
+
+`gdb`'s DAP mode needs GDB ≥ 14, so `tdb` checks `gdb --version` before
+starting a session. A `gdb` that is provably too old is refused with a
+message naming its path and version; when that `gdb` came from `PATH`
+(not from `--adapter` or `config.json`), `tdb` first looks for a newer one
+installed by Red Hat's Software Collections
+(`/opt/rh/gcc-toolset-*/root/usr/bin/gdb`, `/opt/rh/devtoolset-*/...`) and
+uses the newest that qualifies. See [C/C++ tips](#cc-tips) for RHEL 8.
+
 > **Migration note:** extensionless Python scripts without a `python` shebang
 > were previously assumed to be Python; they now require `--lang python`.
 
@@ -337,7 +344,7 @@ 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
@@ -359,7 +366,10 @@ 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).
+mode). Typing into the Console view to feed the program's stdin works for
+Python, Perl, Bash, Tcsh, Ruby, and PowerShell, but not for C/C++, Rust,
+OCaml, or Go, whose adapters spawn the debuggee themselves — see
+[Console Output and Input](#console-output-and-input).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature set than Python:
@@ -425,10 +435,16 @@ picture:
   backtrace instead.
 - No Windows support, no remote attach, and a stripped native binary that
   byte-checking can't identify needs `--lang ocaml`.
+- No stdin forwarding from the Console view (both adapters spawn the
+  program themselves); a program that reads stdin needs `--terminal`
+  (native, `--adapter lldb-dap`) or input from a file.
 
 **Go limitations (v1):**
 
 - `--terminal` is not supported (`dlv dap` has no terminal-routing mode).
+- No stdin forwarding from the Console view: `dlv dap` spawns the program
+  itself, so a program that reads stdin must get it from a file or pipe on
+  its command line.
 - 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
@@ -455,9 +471,17 @@ See [Go](#go) below for launch details.
   If no breakpoint in a file can be
   bound, `tdb` prints a console warning suggesting the program may lack
   debug info.
+- The Console view's stdin line is not available: `gdb -i dap` and
+  `lldb-dap` spawn the program themselves, so `tdb` has no handle on its
+  stdin. A program that reads stdin needs `--terminal` (with
+  `--adapter lldb-dap`) or its input from a file.
 - Stack frames pointing into system libraries often have no source on disk;
   the Code View shows a `<Could not read …>` placeholder while the stack,
   variables, and evaluate console remain fully usable.
+- For compiled executables, the Code View shows shows a brief note while
+  it attempts to load the associated source file.  The note will identify
+  the failure reason if the source cannot be loaded (executable was built
+  without `-g`, or the adapter is not working, e.g. a GDB too old for DAP).
 - GDB (the default adapter) has the most complete libstdc++
   pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
   GCC-built binaries fine.  DWARF is compiler-neutral.
@@ -468,6 +492,80 @@ See [Go](#go) below for launch details.
 - `--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.
+- **GDB source-location quirk:** some GDB builds (RHEL 8 among them)
+  report no source file for a stopped frame -- `info source` answers
+  "No current source file" -- until a `list` command has selected the
+  default source file. `tdb` therefore sends `list` once, before its
+  first stack query, so the Code View can find the source. This is why a
+  fresh gdb session shows `Current source file is …` in `info source`
+  from the evaluate console without you having typed `list`.
+- **RHEL 8 (and 9) gdb is too old for DAP:** the stock `/usr/bin/gdb` is
+  8.2 on RHEL 8 (10.2 on RHEL 9) and answers `gdb -i dap` with
+  ``Interpreter `dap' unrecognized``. Install a newer one from the
+  GCC Toolset, which leaves `/usr/bin/gdb` alone:
+
+  ```bash
+  sudo dnf install gcc-toolset-14-gdb   # gdb 14.2 under /opt/rh/gcc-toolset-14
+  ```
+
+  `tdb` then finds `/opt/rh/gcc-toolset-14/root/usr/bin/gdb` by itself
+  whenever the `gdb` on `PATH` is missing or too old — no `scl enable`
+  needed (`tdb --info` shows it as `gdb used instead`). Two things pin
+  the old one and must be changed by hand: `--adapter /usr/bin/gdb`, and
+  an `"adapters": {"gdb": "/usr/bin/gdb"}` entry in `config.json` (`tdb`
+  seeds that entry with whatever `gdb` was on `PATH` the first time it
+  wrote the file). Either delete the entry or point it at the toolset
+  gdb. A GDB ≥ 14 that was built without Python support gives the same
+  ``Interpreter `dap' unrecognized`` error (`gdb --configuration` shows
+  `--without-python`); use `--adapter lldb-dap` or a gdb built with
+  Python.
+
+**Attach to a running process:** `tdb -a PID` attaches gdb (or `--adapter
+lldb-dap`) to a live native process and stops it. On Linux tdb reads
+`/proc/PID/exe` to identify the language (Go, OCaml, Rust, otherwise
+C/C++) and to load symbols; pass the executable path as well to use a
+different symbol file, and pass `--lang` off Linux. `--no-pause-on-attach`
+leaves the process running, for a program about to stop itself. An
+interpreter process (python3, perl, ruby, bash) is attached as C/C++; for
+Python, Perl, and Ruby programs use `--remote-attach` instead.
+
+**Live breakpoint hook:** the C/C++ counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Include `tdb.h` (its directory
+is the `tdb.h dir` row of `tdb --info`) and call `tdb_breakpoint()`:
+
+```c
+#include "tdb.h"
+
+int compute(int n) {
+    int total = 0;
+    for (int i = 0; i < n; i++) total += i;
+    tdb_breakpoint();   /* tdb opens here, paused on the next line */
+    return total;
+}
+```
+
+```bash
+gcc -g -O0 -I "$(tdb --info | awk -F': ' '/tdb.h dir/ {print $2}')" -o prog prog.c
+./prog    # run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang cpp -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's gdb or lldb to attach, and stops in the
+hook; tdb steps out so the stop lands on the line after the call, in your
+own frame. Later calls reuse the running tdb. Quitting tdb (`Ctrl+q`)
+detaches and the program runs on; the next call opens a fresh tdb. The
+call is a no-op when stdin or stdout is not a terminal, and it warns and
+continues when `tdb` cannot be found, exits before attaching, or cannot
+attach within 60 s (Yama `ptrace_scope` 2 or 3, or a container without
+`SYS_PTRACE`, blocks attaching). If a tdb whose attach failed is still
+running, later calls warn once and return rather than open another tdb
+over it. Build with `-g -O0` so locals stay
+inspectable; a stripped binary attaches but never stops, because the hook's
+stop symbol cannot be resolved. The header is C99 and C++ compatible and
+header-only. Linux only: the hook grants ptrace access to tdb's debugger
+with `PR_SET_PTRACER`; elsewhere it warns once and returns. See
+`examples/C/breakpoint_hook_demo.c` and `examples/C++/breakpoint_hook_demo.cpp`.
 
 ### Rust
 
@@ -489,7 +587,9 @@ 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
+As for C/C++, the Console view cannot feed the program's stdin (the gdb and
+lldb adapters spawn it themselves); use `--terminal` with `--adapter
+lldb-dap` for interactive programs. 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.
 
@@ -520,6 +620,50 @@ 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`.
 
+**Attach to a running process:** `tdb --lang rust -a PID` attaches gdb (or
+`--adapter lldb-dap`) to a live Rust process and stops it; tdb loads
+symbols from `/proc/PID/exe`, or from an executable path you pass as well.
+Without `--lang`, tdb recognizes a non-stripped Rust binary by its runtime
+symbols; a stripped one is debugged as C/C++.
+
+**Live breakpoint hook:** the Rust counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Depend on the `tdb` crate from
+this repository (it has no dependencies) and call `tdb::breakpoint()`:
+
+```toml
+[dependencies]
+tdb = { git = "https://github.com/AlDanial/tdb" }   # or path = ".../rust/tdb"
+```
+
+```rust
+fn compute(n: u64) -> u64 {
+    let total: u64 = (0..n).sum();
+    tdb::breakpoint(); // tdb opens here
+    total
+}
+```
+
+```bash
+cargo build && ./target/debug/prog    # dev profile; run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang rust -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's gdb or lldb to attach, and stops in the
+hook; tdb steps out so the stop lands in your own frame on, or just after,
+the call line, as the compiler's line table attributes the return address.
+Later calls reuse the running tdb. Quitting tdb (`Ctrl+q`)
+detaches and the program runs on; the next call opens a fresh tdb. The
+call is a no-op when stdin or stdout is not a terminal, and it warns and
+continues when `tdb` cannot be found, exits before attaching, or cannot
+attach within 60 s (Yama `ptrace_scope` 2 or 3, or a container without
+`SYS_PTRACE`, blocks attaching). If a tdb whose attach failed is still
+running, later calls warn once and return rather than open another tdb
+over it. Use the dev profile so locals stay
+inspectable. Linux only: the hook grants ptrace access to tdb's debugger
+with `PR_SET_PTRACER`; elsewhere it warns once and returns. See
+`examples/Rust/breakpoint_hook_demo/`.
+
 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
@@ -541,6 +685,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
@@ -637,18 +799,48 @@ 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 in attach mode** uses a control channel: after the debug connection
+is up, `tdb` opens a second connection to the same port and asks
+`Devel::TdbRemote` to accept it. From then on `pause` (or the `p` key) writes a
+byte on that connection, the kernel delivers `SIGIO` to the debuggee, and the
+program stops at its next statement -- the same mechanism `perl5db` uses for
+Ctrl-C, so a program blocked in `sleep` or `select` is interrupted too. The
+second connection reuses the debug port, so an SSH tunnel that forwards that
+one port carries both. Requirements: the `Devel/TdbRemote.pm` copied to the
+remote host must be at least the version shipped with this feature (an older
+copy still attaches fine, but `pause` returns a "not available" error and the
+Console view says why), and the remote perl must support `O_ASYNC` (Linux,
+macOS, BSD; not Windows).
+
+**Live breakpoint hook:** the Perl counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Run your program normally (not
+under `tdb`) and have it open `tdb` on itself when it reaches a line of
+interest:
+
+```perl
+use Devel::TdbRemote;                 # first line of your program
+...
+Devel::TdbRemote::breakpoint();       # tdb opens here, paused on the next line
+```
 
-**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
-`Devel::TdbRemote` doesn't implement yet; `pause` in attach mode returns a
-"not available" error instead of hanging.
+On the first call the program listens on an ephemeral loopback port, spawns
+`tdb --lang perl -r 127.0.0.1:PORT` on the same terminal, waits for it to
+attach, and stops on the statement after the call, in your own frame. Later
+calls reuse the running `tdb`, which simply receives another stop. Quitting
+`tdb` (`Ctrl+q`) detaches and lets the program run on; a `breakpoint()` reached
+after that spawns a fresh `tdb`. The call is a no-op when stdin/stdout are not
+a tty, so it is safe in code that sometimes runs headless, and if `tdb` cannot
+be started (not on `PATH`, or it exits before attaching) it warns and the
+program continues. `tdb` is found on `PATH`, or via the `TDB` environment
+variable. The same arming caveat as above applies: `use Devel::TdbRemote;`
+must be the first line (or use `PERL5OPT=-d:TdbRemote`), and `Devel::TdbRemote`
+has to be on `@INC`, e.g.
+
+```bash
+PERL5LIB=$(tdb --info | sed -n 's/.*Devel::TdbRemote dir *: *//p') perl prog.pl
+```
+
+See [`examples/Perl/breakpoint_hook_demo.pl`](https://github.com/AlDanial/tdb/blob/main/examples/Perl/breakpoint_hook_demo.pl).
 
 ### Bash
 
@@ -738,6 +930,33 @@ exec` integration yet.
 > race on launch; tdb detects a stalled/corrupted handshake and retries
 > once automatically with a fresh `rdbg`, so this is usually invisible.
 
+**Live breakpoint hook:** the Ruby counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Run your program normally (not
+under `tdb`) and have it open `tdb` on itself when it reaches a line of
+interest:
+
+```ruby
+require 'tdb'
+...
+Tdb.breakpoint          # tdb opens here, paused on the next line
+```
+
+The first call starts the debug gem's own debug server on an ephemeral
+loopback port and plants the gem's usual one-shot breakpoint on the next
+line. When that fires, the program parks and `tdb --lang ruby -r 127.0.0.1:PORT`
+is spawned on the same terminal, attaches, and shows the stop in your own
+frame. Later calls reuse the running `tdb`. Quitting `tdb` (`Ctrl+q`) detaches
+and lets the program run on; a `Tdb.breakpoint` reached after that spawns a
+fresh `tdb`. The call is a no-op when stdin/stdout are not a tty, and if `tdb`
+is not on `PATH` (or in the `TDB` environment variable) it warns and the
+program continues. Put `tdb.rb` on the load path, e.g.
+
+```bash
+RUBYLIB=$(tdb --info | sed -n 's/.*tdb.rb dir *: *//p') ruby prog.rb
+```
+
+See [`examples/Ruby/breakpoint_hook_demo.rb`](https://github.com/AlDanial/tdb/blob/main/examples/Ruby/breakpoint_hook_demo.rb).
+
 ### OCaml
 
 `tdb` debugs OCaml through two independent adapters, chosen automatically
@@ -761,7 +980,7 @@ 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`) 
+Code view, provide an explicit temporary breakpoint (`-t`)
 at the first line of execution:
 
 ```
@@ -841,6 +1060,52 @@ 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).
 
+**Attach to a running process:** `tdb -a PID` attaches lldb-dap (or
+`--adapter gdb`) to a live native OCaml process and stops it; tdb
+recognizes the OCaml runtime in `/proc/PID/exe` and always picks a native
+adapter (bytecode programs cannot be attached to). `--no-pause-on-attach`
+leaves the process running, for a program about to stop itself.
+
+**Live breakpoint hook:** the OCaml counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook), for native code. Vendor the
+`ocaml/tdb` directory from this repository (or `opam pin` it), add
+`(libraries tdb)` to your executable's dune stanza, and call
+`Tdb.breakpoint ()`:
+
+```ocaml
+let compute n =
+  let total = ref 0 in
+  for i = 0 to n - 1 do total := !total + i done;
+  Tdb.breakpoint ();   (* tdb opens paused on this line *)
+  !total
+```
+
+```bash
+dune build && ./_build/default/prog.exe   # dev profile; run it directly, not under tdb
+```
+
+Without dune: copy `tdb.ml`, `tdb.mli`, `tdb_stubs.c`, and `tdb.h` from
+`ocaml/tdb` next to your source and build with
+`ocamlopt -g -o prog tdb_stubs.c tdb.mli tdb.ml prog.ml`.
+
+When the call is reached, the program starts `tdb --lang ocaml -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's lldb or gdb to attach, and stops in the
+hook, and tdb steps out of the hook's frames into your own. Unlike the
+other languages' hooks, the stop lands on the `Tdb.breakpoint ()` call
+line itself rather than the line after: both lldb and gdb map the hook's
+return address back to the call. ocamlopt also emits no debug info
+for locals, so the Variables view shows none for OCaml frames (globals
+and the stack are still available). Later calls reuse the running tdb.
+Quitting tdb (`Ctrl+q`) detaches and the program runs on; the next call
+opens a fresh tdb. The call is a no-op when stdin or stdout is not a
+terminal, and it warns and continues when `tdb` cannot be found, exits
+before attaching, or cannot attach within 60 s (Yama `ptrace_scope` 2 or
+3, or a container without `SYS_PTRACE`, blocks attaching). Keep debug
+info (`-g`, dune's dev profile). Linux only: the hook grants ptrace
+access to tdb's debugger with `PR_SET_PTRACER`; elsewhere it warns once
+and returns. See `examples/OCaml/breakpoint_hook_demo.ml`.
+
 ### Go
 
 `tdb` debugs Go through [Delve](https://github.com/go-delve/delve)'s own
@@ -866,10 +1131,53 @@ tdb -r host:port --lang go # attach to a `dlv dap --listen` already running remo
 
 `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
+`-a`/`--attach` works for Go and, through gdb/lldb-dap, for C/C++, Rust,
+and OCaml; on Linux `tdb` identifies the language from `/proc/PID/exe`
 without `--lang` (elsewhere pass `--lang go` alongside `-a`). Attaching
-stops the process immediately so you get control right away.
+stops the process immediately so you get control right away;
+`--no-pause-on-attach` leaves it running instead, for a program that is
+about to stop itself (see the live breakpoint hook below).
+
+**Entry stop:** Delve's own `stopOnEntry` halts at the process entry point
+before any goroutine exists (no stack, no source). `tdb` instead runs to
+`main.main`, so the default entry stop lands on your program's first line
+with its source on screen; `--no-stop-on-entry` skips it as usual.
+
+**Live breakpoint hook:** the Go counterpart of Python's
+`tdb.breakpoint()`. Import the `tdb` module from this repository and call
+`tdb.Breakpoint()` where you want the debugger to open:
+
+```go
+import "github.com/AlDanial/tdb/go/tdb"
+
+func compute(n int) int {
+    total := 0
+    for i := 0; i < n; i++ {
+        total += i
+    }
+    tdb.Breakpoint() // tdb opens here, paused on the next line
+    return total
+}
+```
+
+```bash
+go get github.com/AlDanial/tdb/go/tdb
+go build -gcflags=all=-N -l -o prog . && ./prog   # run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang go -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's Delve to attach, and traps with
+`runtime.Breakpoint()`; tdb steps out of the trap so the stop lands on the
+line after the call, in your own frame. Later `tdb.Breakpoint()` calls
+reuse the running tdb. Quitting tdb (`Ctrl+q`) detaches and the program
+runs on; the next call opens a fresh tdb. The call is a no-op when stdin
+or stdout is not a terminal, and it warns and continues when `tdb`
+cannot be found or exits before attaching. Build with
+`-gcflags=all=-N -l` so locals stay inspectable. Linux only: the hook
+grants ptrace access to tdb's Delve with `PR_SET_PTRACER` (Yama
+`ptrace_scope=1`); elsewhere it warns once and returns. See
+`examples/Go/breakpoint_hook_demo/`.
 
 **Remote attach:** start Delve's own DAP server against your program
 first —
@@ -971,6 +1279,12 @@ Notes:
   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.
+- `Read-Host`, `$Host.UI.ReadLine()`, and `[Console]::ReadLine()` read
+  from the Console view's stdin line (pwsh is no longer started with
+  `-NonInteractive`, so mandatory-parameter and `-Confirm` prompts now wait
+  for your input there instead of failing). pwsh echoes the prompt and the
+  answer together once the line completes, so a bare `Read-Host` prompt
+  appears only after you answer it; a preceding `Write-Host` shows at once.
 - Windows PowerShell 5.1 is not supported (pwsh 7 only). Running tdb *on*
   Windows against pwsh is designed for but not yet verified (experimental).
 
@@ -980,7 +1294,7 @@ Notes:
 ┌─ Header ──────────────────────────────────────────────┐
 ├─ Menu Bar (File / Configure / Help)───────────────────┤
 │                           │                           │
-│   Code View               │  Console View (stdout)    │
+│   Code View               │  Console View (stdio)     │
 │   (source + breakpoints)  ├───────────────────────────┤
 │                           │  Variable View (tree)     │
 │                           ├───────────────────────────┤
@@ -1023,6 +1337,7 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | Key | Menu |
 |-----|------|
 | `Alt+F` | File (open a different script to debug) |
+| `Alt+E` | Edit (Save, Revert to Disk, Discard and Exit Edit Mode, Open in $EDITOR) |
 | `Alt+C` | Configure (Color Theme, Keybindings, Step Mode) |
 | `Alt+T` | Threads |
 | `Alt+P` | Processes |
@@ -1036,7 +1351,7 @@ 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
+By default the Code View is in Debug mode.  `Escape` cycles Debug → Navigate → Edit → Debug.
 In Navigate mode, you can move around the file with the following keys:
 
 | Key | Action |
@@ -1050,7 +1365,43 @@ In Navigate mode, you can move around the file with the following keys:
 | `n` / `N` | Next / previous search result |
 | `PageUp` / `PageDown` | Scroll by page |
 
-Switch from Navigate back to Debug mode with `Escape`.
+Press `Escape` again to enter Edit mode (below), and once more to return to Debug mode.
+
+**Edit mode:**
+
+Press `Escape` twice from Debug mode to open the current file in an editor
+inside the Code View. The pane title shows `[Edit]`, with `*` while there
+are unsaved changes. Editing keys follow the keybinding scheme:
+
+| Scheme | Editing style | Save | Leave Edit mode |
+|--------|---------------|------|-----------------|
+| `vim` | vim-lite: normal / insert modes, counts, `h j k l w b e 0 ^ $ gg G`, `x dd dw D yy p P u Ctrl+R J`, `i a I A o O`, `/ ? n N` | `:w` or `Ctrl+S` | `Esc` (from normal mode), `:q`, `:wq`, `:q!` |
+| `emacs` | `Ctrl+N/P/F/B`, `Alt+F/B`, `Ctrl+A/E`, `Ctrl+K` / `Ctrl+Y`, `Ctrl+_` undo, `Ctrl+S` / `Ctrl+R` search | `Ctrl+X Ctrl+S` | `Esc` or `Ctrl+X Ctrl+C` |
+| `default` (Notepad-style) | arrows, Home/End, PgUp/PgDn, Delete/Backspace, Shift+arrows to select, `Ctrl+Z`/`Ctrl+Y`, `Ctrl+X`/`Ctrl+C`/`Ctrl+V` | `Ctrl+S` | `Esc` |
+
+Leaving Edit mode, quitting, restarting, or opening another file with
+unsaved changes prompts: `s` save, `d` discard, `Esc` keep editing.
+
+Saving does not change the running program. tdb shifts your breakpoints
+to their new lines, clears the current-line marker, and (when restart is
+available) reminds you to press `R` to restart with the new code. In
+`tdb --run` sessions, which cannot restart, you will see only "Saved
+`<file>`." Edit mode is unavailable when no file is loaded, for sources
+that are not on this machine (remote attach), during replay, and in
+post-mortem mode.
+
+The `Edit` menu (`Alt+E`) offers Save, Revert to Disk, Discard and Exit
+Edit Mode, and Open in $EDITOR, which suspends tdb, runs `$VISUAL` /
+`$EDITOR` (`notepad` on Windows, `vi` otherwise) on the file, and reloads
+it when the editor exits.
+
+Syntax highlighting inside the editor needs tree-sitter, an optional
+extra: `uv pip install "textual-debugger[edit]"` (highlights Python, Bash,
+Go, and Rust; other languages edit as plain text). Highlighting in the
+normal Code View is unaffected.
+
+CRLF source files are written back with LF line endings after a save in
+Edit mode (a v1 limitation — no CRLF round-trip yet).
 
 > **Note:** Many terminals send the byte sequence `ESC+f` for `Alt+F`, which Textual's
 ANSI parser rewrites to `Ctrl+Right` (the readline "forward-word" convention).
@@ -1122,6 +1473,15 @@ Set a Python expression (e.g., `x > 10`) and/or a hit count (pause on the Nth hi
 
 Breakpoints persist across session restarts.
 
+**Breakpoints set at the debugger's own prompt (gdb):** when debugging native code
+with `gdb`, commands typed in the Evaluate Console such as `b 83` or `delete 2`
+go straight to gdb. Switching to the Breakpoint View (`Ctrl+B`, or clicking it)
+synchronizes tdb's table with gdb's list: breakpoints created at the gdb prompt
+are adopted (with their conditions and enabled state) and become ordinary tdb
+breakpoints, and breakpoints deleted at the prompt are dropped. Watchpoints,
+catchpoints and `tbreak` temporaries are left to gdb. `lldb-dap` has no such
+prompt-level breakpoint channel, so nothing to sync there.
+
 ### Variable Inspection
 
 The Variable View shows a tree of scopes with all variables in the current frame. The scopes
@@ -1135,6 +1495,39 @@ the Variables View and press `Enter`
 to display that variable in a modal.  This simplifies inspection of
 large or deeply nested data structures.
 
+#### Display list
+
+Like `gdb`'s `display` command, a variable (or any expression) can be
+pinned so its value is re-read at every stop. Pinned entries appear
+under a **Display** scope at the top of the Variables View, but only
+while they are defined in the current frame: step out of the function
+that owns `b` and the entry vanishes, step back into it and the entry
+returns. Two ways to pin, two ways to unpin:
+
+| | Evaluate Console | Variables View |
+|---|---|---|
+| pin | `display b` | right-click the variable's row |
+| unpin | `undisplay b` | left-click its row under **Display** |
+
+```
+>>> display b
+```
+
+```
+▼ Display
+    b = 6
+▼ Locals
+    a = 3
+    b = 6
+```
+
+Right-clicking a child of an expanded object pins the full path
+(`obj.count`, `items[2]`), and a bare `display` lists everything pinned.
+A click in the Variables View is recorded exactly as the typed command,
+so `--record`/`--replay` sessions reproduce it. Some terminals keep
+right-click for their own paste or context menu (Windows Terminal and
+the VS Code terminal do by default); use the `display` command there.
+
 ### Call Stack
 
 The Stack View shows the full call stack. Click a frame to navigate to its source
@@ -1162,6 +1555,45 @@ interactive evaluation of expressions in the current scope:
 ```
 
 Variable values set here are reflected in the running code.
+The Variables View redraws after every entry, so an assignment typed at
+the prompt shows up immediately rather than at the next stop.
+
+#### Interactive variables
+
+A variable *created* at the prompt is tracked and listed under an extra
+**Interactive** scope in the Variables View, alongside Locals, Globals and
+the other language-specific scopes. The value is re-read at every stop,
+so it works like a watch list of the names you introduced:
+
+```
+>>> newvar = 42
+```
+
+```
+▼ Locals
+    a = 3
+    b = 6
+▼ Interactive
+    newvar = 42
+```
+
+What counts as "created" depends on the language, and so does how long the
+variable lives:
+
+| Language | Creates an interactive variable | Lifetime |
+|---|---|---|
+| Python | `name = …` | the current frame (gone once it returns) |
+| Perl | `$name = …`, `@name = …`, `%name = …`, `our …` | the whole run (`my` lexicals vanish with the eval and are not tracked) |
+| Bash | `name=…`, `local`/`declare`/`export …` | the whole run; `local` follows the function |
+| tcsh | `set name …`, `setenv NAME …` | the whole run |
+| Ruby | `name = …`, `$name = …`, `@name = …` | globals and instance variables persist; plain locals live only in the eval's binding and read back as unavailable after the next step |
+| PowerShell | `$name = …`, `$global:name = …` | the function scope, or the whole run for `$global:` |
+| C/C++/Rust/OCaml under gdb | `set $name = …` (a gdb convenience variable) | the whole run |
+| C/C++/Rust/OCaml under lldb-dap | `int $name = …` (an lldb persistent variable) | the whole run |
+| Go (dlv), OCaml under ocamlearlybird | not possible: their evaluate cannot create variables | — |
+
+A tracked name that no longer resolves (a Python local after its frame
+returned, for example) stays in the list and shows as `<unavailable>`.
 
 ### Cut / Paste
 
@@ -1172,12 +1604,35 @@ capture mouse events for their own use.
 Instead, hold the `Shift` key while performing your conventional cut/paste keystrokes or mouse
 operation to get the expected behavior.
 
-### Console Output
+### Console Output and Input
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
 in real time.
 
-If your program prints a lot, or prompts for input, or uses colors or
+Programs that read from stdin (`input()`, `<STDIN>`, `read`, `gets`, …) get
+their input from the same view: while the program runs, an input line sits
+under the output log. `Ctrl+O` focuses it, `Enter` sends the line (plus a
+newline) to the program and echoes it in cyan next to the program's prompt,
+and `Ctrl+D` sends end-of-file. A bare `Enter` sends an empty line, which is
+a real answer to `input()`. The line disappears when the program exits or
+when the session has no stdin to feed.
+
+Stdin forwarding works for the languages whose program `tdb` launches on a
+pipe it owns: Python, Perl, Bash, Tcsh, Ruby, and PowerShell. It is not
+available for the compiled languages — C/C++, Rust, OCaml, and Go — because
+their adapters (`gdb -i dap`, `lldb-dap`, `dlv dap`) spawn the debuggee
+themselves and give `tdb` no handle on its stdin; the input line stays
+hidden there. It is also unavailable for remote attach (`-r`), where the
+program's stdin belongs to whoever started it, and under `--terminal`,
+where the program reads from its own terminal window. For those cases run
+the program in an external terminal with `--terminal` (launch mode only),
+or give it its input another way (a file, a pipe on the command line).
+
+Every line typed here is captured by `--record` as a `stdin` gesture and
+replayed by `--replay`/`--replay-tui`, and the JSON-RPC server exposes the
+same thing as the `stdin` / `stdin_eof` actions.
+
+If your program prints a lot, or uses colors or
 terminal control codes, run the program in an external terminal
 with `--terminal` for a better experience.
 The `--terminal` switch requires a graphical environment and a compatible
@@ -1289,6 +1744,12 @@ This behavior matches hitting `c` while in a conventional (that is, the Python
 standard library's) `breakpoint()` session.
 If you want to kill the program instead, use `Ctrl+c` in the terminal running the debuggee.
 
+Perl, Ruby, Go, C/C++, Rust, and OCaml programs get the same hook as
+`Devel::TdbRemote::breakpoint()`, `Tdb.breakpoint`, `tdb.Breakpoint()`,
+`tdb_breakpoint()`, `tdb::breakpoint()`, and `Tdb.breakpoint ()`; see
+[Perl](#perl), [Ruby](#ruby), [Go](#go), [C/C++ tips](#cc-tips),
+[Rust](#rust), and [OCaml](#ocaml).
+
 ### Async Task Inspector
 
 For programs using `asyncio`, the menu bar shows an **Async Tasks (N)** label with the count of
@@ -1477,7 +1938,8 @@ 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:
+window, not in `tdb`'s Console View (whose stdin line is hidden in this
+mode). Supported choices:
 `xterm`, `konsole`, `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`,
 `wezterm`, `terminator`. The selected terminal must be on `PATH`. Debugging
 (breakpoints, stepping, variable inspection, the evaluate console) proceeds
@@ -1487,35 +1949,75 @@ This feature only works in graphical environments where external terminals are a
 
 ### 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.
+`tdb`'s run mode acts as a job shepherd.
+It runs your unmodified program at nearly full speed, without bringing up the TUI,
+and listens for two interrupt signals:
 
-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.
+- `Ctrl-C` pauses the program and brings up TUI, placing you at the currently
+active line of code.  From there you can debug interactively as usual.  When
+you quit the TUI, you can either detach and let the program continue running, or terminate it.
+
+- `Ctrl-\` temporarily pauses the program and prints a JSON-formatted stack trace to stdout
+or a log file, then resumes the program.
 
 ```bash
 tdb --run my_program.py args...
 ```
 
-The debuggee's stdout/stderr stream straight to the terminal. If the program exits on
+The debuggee's stdout/stderr stream straight to the terminal, and for the
+languages with stdin forwarding (see
+[Console Output and Input](#console-output-and-input)) the program reads
+its stdin from that terminal too. 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.
+**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
@@ -1541,14 +2043,19 @@ language.
 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:
+Eval mode is essentially a code injection mechanism.  Rather than injecting
+native code though, only expressions that are valid in the Evaluate View
+can be injected (in Python, native expressions are processed correctly
+in the Evaluate View).
+
+In this way, Eval mode automates the common debugging action of setting a
+breakpoint, running to it, evaluating (and printing the result of) an expression, then
+resuming execution, all 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
@@ -1568,7 +2075,7 @@ evaluated in each child process that reaches it.
 - `-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 
+  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
@@ -1584,14 +2091,14 @@ evaluated in each child process that reaches it.
   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`.
+`--replay`, `--replay-tui`, `--server`, `--headless`, `--mcp`, `--terminal`.
 
 ### Keybinding Schemes
 
 ```bash
 tdb --keybindings vim my_program.py    # default
 tdb --keybindings emacs my_program.py
-tdb --keybindings default my_program.py
+tdb --keybindings default my_program.py   # Notepad-style editing
 ```
 
 The keybinding choice is saved to `~/.config/tdb/config.json` and remembered for subsequent
@@ -1673,6 +2180,8 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `stack_down` | `[]` | Move down the call stack |
 | `get_stack_trace` | `[]` | Full call stack |
 | `get_output` | `[]` | Drain buffered stdout/stderr |
+| `stdin` | `["line"]` | Send a line (newline appended) to the program's stdin; errors when the session has no stdin (compiled languages, `--terminal`, remote attach) |
+| `stdin_eof` | `[]` | Close the program's stdin (Ctrl+D) |
 | `get_source` | `["file_path"]` | Read a source file |
 | `list_threads` | `[]` | List all threads |
 | `inspect_thread` | `[thread_id]` | Inspect a specific thread |
@@ -1700,20 +2209,36 @@ Each is JSON with `event`, `data`, and `timestamp` fields.
 
 `tdb --record session.jsonl prog.py` runs a normal TUI session and captures
 your debugging actions including breakpoints (including `-k`/`-t` and persisted
-ones), stepping, continue/pause, Evaluate-console entries, stack-frame
+ones), stepping, continue/pause, Evaluate-console entries, lines typed into
+the Console view for the program's stdin (and Ctrl+D), stack-frame
 navigation, variable expansion, restart, quit. The session is
 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:
 
@@ -1730,9 +2255,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,
@@ -1830,13 +2356,14 @@ 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 ...]
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-r HOST:PORT` | Attach to a remote debugpy server |
+| `-a`, `--attach PID` | Attach to a running local process by pid: Go (Delve) or a native C/C++, Rust, or OCaml program (gdb or lldb-dap). Linux identifies the language from `/proc/PID/exe`; elsewhere pass `--lang` and, for native programs, the executable path. |
 | `--local-root PATH` | Local directory containing a copy of remote code (repeat to mirror multiple trees). Pair with `--remote-root`; counts must match. Required when `-k` sets a breakpoint against a remote debuggee whose code lives at a different path. |
 | `--remote-root PATH` | Remote directory matched to `--local-root` (same CLI position via `zip()`). |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
@@ -1846,17 +2373,25 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--python PATH` | Python interpreter for the debuggee (Python targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
 | `--lang LANGUAGE` | Debuggee language (`python`, `cpp`, `perl`); default: auto-detect from the target |
-| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`); default: the language's standard adapter |
+| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`), or a full path to a `gdb`/`lldb-dap`/`dlv` executable to use instead of the one on `PATH`; default: the language's standard adapter |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
   (default: skipped). On uncaught exceptions, the crash modal always shows the full traceback
   including library frames, regardless of this flag. |
 | `--no-subprocess` | Disable debugpy's subprocess tracking (use when debugging `tdb` itself) |
 | `--terminal TERM` | Run debuggee in the named external terminal: `xterm`, `konsole`,
   `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`, `wezterm`, or `terminator` |
-| `--keybindings SCHEME` | `default`, `vim`, or `emacs` (saved to config) |
+| `--keybindings SCHEME` | `vim`, `emacs`, or `default` (Notepad-style editing); saved to config |
 | `--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
 
@@ -1869,10 +2404,63 @@ On Windows, it uses `%APPDATA%\tdb\`.
 | `config.json` | User preferences (keybinding scheme, color theme, step mode, adapter overrides) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
+### Sample `config.json`
+
+Every key `tdb` reads, with its default or a representative value. Copy
+this to restore a deleted or corrupted file, then delete the entries you
+don't need: a missing key takes its default, an unknown key is ignored,
+and an invalid value (say a misspelled `step_mode`) falls back to the
+default instead of stopping `tdb`.
+
+```json
+{
+  "keybindings": "vim",
+  "theme": null,
+  "step_mode": "statement",
+  "adapters": {
+    "gdb": "/usr/bin/gdb",
+    "lldb-dap": null,
+    "dlv": "/home/me/go/bin/dlv",
+    "perl": "/usr/bin/perl",
+    "rdbg": "/usr/local/bin/rdbg",
+    "bash": "/usr/bin/bash",
+    "tcsh": "/usr/bin/tcsh",
+    "pwsh": "/usr/bin/pwsh",
+    "pses": "/home/me/.local/share/PowerShellEditorServices",
+    "ocamlearlybird": "/home/me/.opam/default/bin/ocamlearlybird"
+  },
+  "default_adapters": {
+    "cpp": "gdb",
+    "rust": "gdb",
+    "ocaml": "lldb-dap"
+  }
+}
+```
+
+| Key | Values | Meaning |
+|-----|--------|---------|
+| `keybindings` | `"vim"` (default), `"emacs"`, `"default"` | Code View keybinding scheme; also set by `--keybindings` |
+| `theme` | `null` (default) or a Textual theme name such as `"textual-dark"`, `"textual-light"`, `"nord"`, `"gruvbox"`, `"dracula"`, `"monokai"`, `"tokyo-night"`, `"catppuccin-mocha"` | Color theme; the names offered under **Configure > Theme** are the valid ones, and an unknown name is ignored |
+| `step_mode` | `"statement"` (default), `"line"` | How `n`/`s` treat multi-line statements (see **Step mode** below) |
+| `adapters` | adapter id → executable path, or `null` | Where to find a debugger or interpreter instead of searching `PATH`. Ids: `gdb`, `lldb-dap`, `dlv` (debuggers); `perl`, `rdbg`, `bash`, `tcsh`, `pwsh` (interpreters `tdb` spawns); `pses` (the PowerShell Editor Services module directory); `ocamlearlybird`. Only list the ones you need |
+| `default_adapters` | language id → adapter id | Which adapter a language uses when `--adapter` isn't given. Languages with a choice: `cpp` and `rust` (`gdb` or `lldb-dap`), `ocaml` (`lldb-dap`, `gdb`, or `ocamlearlybird`) |
+
+The file is plain JSON: no comments, no trailing commas. `tdb` rewrites it
+when you change a setting from the **Configure** menu, so hand edits made
+while `tdb` is running may be overwritten.
+
 Adapter-related keys in `config.json`: `adapters` maps an adapter id to an
 executable path (`{"adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"}}`), and
 `default_adapters` picks a language's default adapter
-(`{"default_adapters": {"cpp": "lldb-dap"}}`).
+(`{"default_adapters": {"cpp": "lldb-dap"}}`). For a one-off run,
+`--adapter /path/to/gdb` (or `lldb-dap`, `dlv`) overrides the `adapters` entry
+without editing the file; `tdb --info` reports the `gdb` and `lldb-dap`
+currently resolved (config override first, then `PATH`) with their versions.
+
+When `tdb` creates `config.json` for the first time it seeds `adapters` with
+`gdb` and `lldb-dap` entries pointing at the executables found on `PATH`
+(`null` when one isn't installed) so the keys are there to edit. A `null`
+entry behaves like a missing one: `tdb` falls back to `PATH`.
 
 **Perl is a special case:** `perl-tdb` is tdb's own bundled adapter (always
 found; it's Python code, not an external executable), so
@@ -1917,6 +2505,29 @@ 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.
+Codex was used to implement tcsh and Rust support.
+
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
+Python debugger.
+
 
 ## Known Problems