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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.8
+Version: 0.2.10
 Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -49,7 +49,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: textual>=8.0.0
-Requires-Dist: debugpy>=1.8.0
+Requires-Dist: debugpy>=1.8.12
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
@@ -79,6 +79,8 @@ with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
 - Tcsh (via source instrumentation of a stock `tcsh`)
 - Ruby (via the [debug gem](https://github.com/ruby/debug)'s `rdbg`; debug ≥ 1.9)
 - OCaml (native via `lldb-dap`/`gdb`, bytecode via [ocamlearlybird](https://github.com/hackwaly/ocamlearlybird))
+- Go (via [Delve](https://github.com/go-delve/delve)'s `dlv dap`)
+- PowerShell 7 (via [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices); Linux/macOS, Windows experimental)
 
 `tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
 DAP to a pluggable debug adapter.
@@ -99,8 +101,9 @@ MIT License.  Copyright 2026 by Al Danial.
 the richest feature set), C/C++ (via `gdb -i dap` or `lldb-dap`), Rust (via `gdb` or
 `lldb-dap`), Perl (via `perl -d`),
 Bash (via bash's own `DEBUG` trap), Tcsh (via source instrumentation of a
-stock `tcsh`), Ruby (via the debug gem's `rdbg`), and OCaml (native via
-`lldb-dap`/`gdb`, bytecode via ocamlearlybird). Most languages are
+stock `tcsh`), Ruby (via the debug gem's `rdbg`), OCaml (native via
+`lldb-dap`/`gdb`, bytecode via ocamlearlybird), Go (via Delve's `dlv
+dap`), and PowerShell 7 (via PowerShell Editor Services). Most languages are
 auto-detected from the target; Rust intentionally requires `--lang rust`
 (ref. [Multi-Language Debugging](#multi-language-debugging)).
 
@@ -110,7 +113,7 @@ It specifically supports modules
     - `threading` (with a thread inspector)
     - `multiprocessing` / `concurrent.futures` (with automatic child process attachment and a process inspector)
 
-- supports remote attachment to Python, Perl, Ruby, Rust, and C/C++ programs
+- supports remote attachment to Python, Perl, Ruby, Rust, C/C++, and Go programs
 
 - includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
 programmatic debug control, making it suitable for
@@ -212,6 +215,10 @@ tdb -k 20 -k 35 -k module.py:14 my_program.py arg1 arg2
 # sessions (-t is -k minus the persistence)
 tdb -t 20 my_program.py
 
+# no TUI: run at (almost) full speed, printing nr each time line 25 is
+# reached, then continuing (-e may be repeated; see "Eval Mode" below)
+tdb --eval my_program.py:25 "print(f'{nr=}')" my_program.py
+
 # use a specific virtualenv
 tdb --python /path/to/venv/bin/python my_program.py
 
@@ -238,6 +245,11 @@ tdb -r remotehost:5678  -k my_program.py:42
 # than code on the remote host
 tdb -r remotehost:5678 --local-root /my/code/dir --remote-root /app -k my_program.py:42
 
+# attach to a program that pauses itself (debugpy.breakpoint() right after
+# debugpy.wait_for_client()); without this flag tdb pauses the program on
+# attach, which can leave it suspended after tdb quits
+tdb -r remotehost:5678 --no-pause-on-attach
+
 # separate tdb arguments from debuggee arguments with `--` 
 tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
@@ -250,7 +262,7 @@ python -m tdb my_program.py
 
 ## Multi-Language Debugging
 
-`tdb` debugs any language that has a Debug Adapter Protocol backend. Eight
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Ten
 languages are supported out of the box:
 
 | Language | Adapter(s) | Dependencies           | Feature level |
@@ -262,33 +274,42 @@ languages are supported out of the box:
 | Bash | bash-tdb (bundled) | bash ≥ 4.4 on PATH  | core debugging (no remote attach) |
 | Tcsh | tcsh-tdb (bundled) | tcsh on PATH | core debugging (no remote attach, no conditional breakpoints, no pause) |
 | Ruby | `rdbg` (the [debug gem](https://github.com/ruby/debug)) | `rdbg` ≥ 1.9 on PATH | core debugging + remote attach |
-| OCaml (native executable) | `lldb-dap` (default), `gdb` (alternate) | OCaml ≥ 4.12; `lldb-dap` ships with LLVM ≥ 17; `gdb -i dap` requires GDB ≥ 14 | core debugging + domains-as-threads; Variables view shows no OCaml locals (upstream DWARF limitation); evaluate console is lldb/C-level, not OCaml |
-| OCaml (bytecode executable) | `ocamlearlybird` (default) | OCaml ≥ 4.12; `opam install earlybird` | core debugging + rich OCaml locals; no pause/`--run`, no evaluate responses, no fatal-error modal (ocamlearlybird 1.3.6 limitations); single-domain only |
+| OCaml (native executable) | `lldb-dap` (default), `gdb` (alternate) | `lldb-dap` ships with LLVM ≥ 17; `gdb -i dap` requires GDB ≥ 14 | core debugging + domains-as-threads; Variables view shows no OCaml locals (upstream DWARF limitation); evaluate console is lldb/C-level, not OCaml |
+| OCaml (bytecode executable) | `ocamlearlybird` (default) | `opam install earlybird` | core debugging + rich OCaml locals; no pause/`--run`, no evaluate responses, no fatal-error modal (ocamlearlybird 1.3.6 limitations); single-domain only |
+| Go | `dlv` (the [Delve](https://github.com/go-delve/delve) DAP server) | Delve ≥ 1.21 on PATH (`go install github.com/go-delve/delve/cmd/dlv@latest`) | core debugging + goroutine inspection (wait graph, findings) + remote attach (no `--terminal`) |
+| PowerShell 7 | `pses` (PowerShell Editor Services, driven by tdb's bundled proxy) | `pwsh` ≥ 7.2 on PATH + the PSES module (see [PowerShell](#powershell)) | core debugging (breakpoints incl. conditional/hit-count/log, stepping, stack, variables, evaluate console) + `--run`; no `--terminal`, no remote attach; Windows untested |
 
 ### Language detection and selection
 
 The language is auto-detected from the debug target:
 
-1. File extension: `.py` → Python; `.pl` / `.pm` / `.t` → Perl; `.sh` / `.bash`
-   → Bash; `.csh` / `.tcsh` → Tcsh; `.rb` → Ruby. (`.ml` / `.mli` do *not*
-   auto-select OCaml, see point 5.)
-2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++, unless
-   byte-sniffing finds an OCaml marker, either a native binary's
+1. A directory → Go, if it contains any `*.go` file (a Go package
+   directory, e.g. `tdb ./pkg`); otherwise an error naming `--lang`.
+2. File extension: `.py` → Python; `.go` → Go; `.pl` / `.pm` / `.t` → Perl;
+   `.sh` / `.bash` → Bash; `.csh` / `.tcsh` → Tcsh; `.rb` → Ruby; `.ps1` /
+   `.psm1` → PowerShell. (`.ml` / `.mli` do *not* auto-select OCaml, see
+   point 6.)
+3. Native executables (ELF, Mach-O, PE magic bytes) → C/C++, unless
+   byte-checking finds an OCaml marker (a native binary's
    `caml_program`/`caml_startup` runtime symbols, a bytecode file's
-   trailing `Caml1999` marker, or a `#!...ocamlrun` shebang, in which case
-   → OCaml (native or bytecode respectively). A stripped native OCaml
-   binary that byte-sniffing can't identify falls back to C/C++; force it
-   with `--lang ocaml`. Rust is never inferred from an executable; select
-   it explicitly with `--lang rust`.
-3. A `#!...python`, `#!...perl`, `#!...bash`, `#!...csh`/`#!...tcsh`, or
-   `#!...ruby` shebang → Python / Perl / Bash / Tcsh / Ruby respectively.
-4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+   trailing `Caml1999` marker, or a `#!...ocamlrun` shebang) → OCaml
+   (native or bytecode respectively), or a Go buildinfo blob (the marker
+   `go version` itself locates, scanned in the first 16MB of the file) →
+   Go. A stripped native OCaml binary, or a Go binary whose buildinfo
+   blob sits beyond the 16MB scan window, that byte-checking can't
+   identify falls back to C/C++; force it with `--lang ocaml` or `--lang
+   go` respectively. Rust is never inferred from an executable; select it
+   explicitly with `--lang rust`.
+4. A `#!...python`, `#!...perl`, `#!...bash`, `#!...csh`/`#!...tcsh`,
+   `#!...ruby`, or `#!...pwsh` shebang → Python / Perl / Bash / Tcsh / Ruby /
+   PowerShell respectively.
+5. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
    hint: compile with debug info (`g++ -g -O0`) and debug the binary.
-5. `.ml` / `.mli` (OCaml source) produce an error too: build the project
+6. `.ml` / `.mli` (OCaml source) produce an error too: build the project
    first (dune's dev profile keeps debug info) and pass the **built
    executable** to `tdb` (`tdb ./_build/default/bin/main.exe`), never the
    `.ml` file.
-6. Anything else produces an error naming the `--lang` override.
+7. Anything else produces an error naming the `--lang` override.
 
 `--lang` forces the language; `--adapter` picks a non-default adapter within
 it (`tdb --lang cpp --adapter lldb-dap ./myprog`). Rust always requires the
@@ -320,19 +341,25 @@ and the JSON-RPC / MCP programmatic modes.
 
 Python-specific features are hidden or return "not supported for this
 language" message when debugging other languages: statement-granularity
-stepping (non-Python languages always step per line), the async task /
-process inspectors and wait graph, the evaluate console's trailing-`?` help,
+stepping (non-Python languages step at their debugger's native granularity
+— per line, except PowerShell, whose debugger stops per statement, see
+[PowerShell](#powershell)), the async task / process inspectors and wait
+graph, the evaluate console's trailing-`?` help,
 `--python`/`--pv`, `--no-subprocess`, automatic child-process attachment, and
 the post-mortem / `tdb.breakpoint()` hooks (those hooks live inside Python
 programs by nature). Remote attach (`-r`) also works for Perl (see
 [Perl](#perl), `Devel::TdbRemote` in place of `debugpy.listen()`), Ruby
-(see [Ruby](#ruby), `rdbg --open` in place of `debugpy.listen()`), and for
+(see [Ruby](#ruby), `rdbg --open` in place of `debugpy.listen()`), Go (see
+[Go](#go), `dlv dap --listen` in place of `debugpy.listen()`), and for
 Rust and C/C++ native binaries (against a gdbserver/lldb-server stub, with
 a local symbol-bearing executable; see [Rust](#rust) — the same flags work
-for a C/C++ target without `--lang`), but not for Bash, Tcsh, or OCaml. `--terminal` works for every launch-mode
+for a C/C++ target without `--lang`), but not for Bash, Tcsh, OCaml, or
+PowerShell. `--terminal` works for every launch-mode
 language — Python, Perl, Bash, Tcsh, Ruby, and C/C++, OCaml native, or Rust
 sessions via `--adapter lldb-dap` — see
-[External Terminal Support](#external-terminal-support).
+[External Terminal Support](#external-terminal-support). Go and PowerShell do
+not support `--terminal` yet (`dlv dap` and PSES have no terminal-routing
+mode).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature set than Python:
@@ -397,7 +424,30 @@ picture:
   reaches `tdb`). Run the program outside the debugger to see the
   backtrace instead.
 - No Windows support, no remote attach, and a stripped native binary that
-  byte-sniffing can't identify needs `--lang ocaml`.
+  byte-checking can't identify needs `--lang ocaml`.
+
+**Go limitations (v1):**
+
+- `--terminal` is not supported (`dlv dap` has no terminal-routing mode).
+- The Goroutines workspace's wait graph shows channel-send/-receive,
+  mutex, and `WaitGroup` edges; a goroutine parked in a `select` is
+  classified but contributes no wait edge (Delve can't tell which of the
+  `select`'s cases it's waiting on).
+- No mutex-holder identification: Go's `sync.Mutex` doesn't record an
+  owner at the runtime level, so unlike Python's Lock/Semaphore inspector
+  the wait graph can name what a goroutine is blocked on but never who
+  holds it.
+- Goroutines spawned by `exec.Command` (child OS processes) are not
+  automatically attached or debugged, unlike Python's automatic
+  multiprocessing child attach.
+- Detection of a Go binary via buildinfo check scans only the first
+  16MB of the file; a huge binary whose buildinfo blob sits beyond that
+  falls back to C/C++ — force it with `--lang go`.
+- `-a`/`--attach`'s language auto-detection (reading the target pid's
+  buildinfo from `/proc/PID/exe`) is Linux-only; on macOS/Windows pass
+  `--lang go` alongside `-a`.
+
+See [Go](#go) below for launch details.
 
 ### C/C++ tips
 
@@ -703,18 +753,35 @@ does). Always pass the **built executable** to `tdb`, never the `.ml`
 source, as in `tdb ./_build/default/bin/main.exe`, not `tdb main.ml` (which
 errors with this exact guidance).
 
+Earlybird additionally as a fragile relative path matching so for
+best results provide a fully quallified path to the source files.
+
+```
+ocamlc -g -o my_program.byte "$PWD/my_program.ml"
+```
+
+Then, to ensure transition from bytecode to OCaml source in the
+Code view, provide an explicit temporary breakpoint (`-t`) 
+at the first line of execution:
+
+```
+tdb --lang ocaml --adapter ocamlearlybird -t "$PWD/my_program.ml:2" ./my_program.byte
+```
+
 **OCaml version:** tdb requires **OCaml ≥ 4.12**. Older runtimes print
 `Printexc` backtraces without function names, which the fatal-error
 modal's parser does not understand (frames would be dropped and the
 modal would wrongly suggest recompiling with `-g`).
 
-```bash
-tdb ./_build/default/bin/main.exe          # native, lldb-dap
-tdb --adapter gdb ./_build/default/bin/main.exe   # native, gdb
-tdb ./_build/default/bin/main.byte         # bytecode, ocamlearlybird
-```
+With native GDB, the default entry stop is translated to the first
+executable line in project OCaml source; the generated C/ELF startup code is
+not shown.
+Unfortunately OCaml's native debug information does not always identify
+tihs line correctly.
+`--no-stop-on-entry` and explicit CLI breakpoints retain their
+usual behavior.
 
-A stripped native binary that byte-sniffing can't identify as OCaml falls
+A stripped native binary that byte-checking can't identify as OCaml falls
 back to C/C++; force it with `--lang ocaml`. Override the adapter or point
 at a non-`PATH` install in `config.json` (see
 [Configuration](#configuration)):
@@ -774,6 +841,139 @@ sessions can't `pause` a running program (so `--run` is unavailable for
 bytecode. Native sessions support `--run` normally); `Unix.fork` and Eio
 fibers are out of scope (only OCaml 5 domains are presented as threads).
 
+### Go
+
+`tdb` debugs Go through [Delve](https://github.com/go-delve/delve)'s own
+DAP server, `dlv dap` (Delve ≥ 1.21). Install it with:
+
+```bash
+go install github.com/go-delve/delve/cmd/dlv@latest
+```
+
+`dlv` must be on `PATH`, or point tdb at it with
+`{"adapters": {"dlv": "/path/to/dlv"}}` in `config.json`.
+
+**Launch modes** — `tdb` picks the right Delve mode automatically:
+
+```bash
+tdb main.go               # source file: `go run`-style debug mode
+tdb ./pkg                 # package directory: `go run`-style debug mode
+tdb ./binary               # pre-built Go binary (buildinfo-detected): exec mode
+tdb --test ./pkg          # Go test package: Delve test mode
+tdb -a PID                 # attach to a running local Go process by pid
+tdb -r host:port --lang go # attach to a `dlv dap --listen` already running remotely
+```
+
+`tdb --test ./pkg` debugs the package's tests under Delve's `test` mode;
+pass test-binary flags after `--`, e.g. `tdb --test ./pkg -- -run TestFoo`.
+`-a`/`--attach` currently supports Go only; on Linux, and only on Linux,
+`tdb` can identify the target as Go from `/proc/PID/exe`'s buildinfo
+without `--lang` (elsewhere pass `--lang go` alongside `-a`). Attaching
+stops the process immediately so you get control right away.
+
+**Remote attach:** start Delve's own DAP server against your program
+first —
+
+```bash
+dlv dap --listen=host:port ./binary
+```
+
+— then connect from `tdb`:
+
+```bash
+tdb -r host:port --lang go
+```
+
+Do not expose the port to an untrusted network; prefer an SSH tunnel.
+
+**Goroutine inspection:** in a Go session the Threads action (`Alt+T`, or
+the **Goroutines (N)** menu label) opens the Goroutines workspace while
+the debuggee is stopped — a fresh, bounded snapshot of goroutines, wait
+edges, and findings, the same shape as the Rust Concurrency workspace.
+Goroutines parked entirely in Go-runtime internals (GC workers,
+finalizers, netpoll) are hidden by default; press `a` to reveal them
+alongside the rest. The **Wait Graph** tab groups goroutines by the
+channel, mutex, or `WaitGroup` they're blocked on; the **Findings** tab
+surfaces stuck channels, mutex convoys, and likely leaks with a
+confidence level (`confirmed` vs `probable`) — Go mutexes never record an
+owner, so, unlike Python's Lock/Semaphore inspector, findings can name
+what's blocked but not who holds it. The snapshot collects up to 150
+goroutines; a busier program reports the header
+`Goroutines (150) — N more not collected` rather than silently truncating.
+Refresh (`r`) after the next stop to collect a new snapshot.
+
+**Limitations (v1):** `--terminal` is not supported (`dlv dap` has no
+terminal-routing mode); a goroutine parked in a `select` is classified but
+contributes no wait edge (Delve can't tell which case it's waiting on);
+no mutex-holder identification (impossible for Go's runtime); goroutines
+spawned indirectly via `exec.Command` child OS processes are not
+automatically attached; buildinfo-based binary detection scans only the
+first 16MB of the file (`--lang go` overrides for anything larger); `-a`'s
+`/proc`-based language auto-detection is Linux-only (pass `--lang go`
+alongside `-a` on macOS/Windows).
+
+### PowerShell
+
+tdb debugs PowerShell 7 scripts through [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices)
+(PSES), the Debug Adapter Protocol server behind the VS Code PowerShell
+extension. You need `pwsh` (>= 7.2; https://aka.ms/powershell) on PATH
+and the PSES module. tdb looks for the module in this order:
+
+1. `{"adapters": {"pses": "/path/to/PowerShellEditorServices"}}` in `config.json`
+2. the `TDB_PSES_PATH` environment variable
+3. the copy bundled with an installed VS Code PowerShell extension
+   (`~/.vscode/extensions/ms-vscode.powershell-*/modules/PowerShellEditorServices`)
+
+Without VS Code, download the release once:
+
+```bash
+mkdir -p ~/.local/share/tdb/pses && cd ~/.local/share/tdb/pses
+curl -sLO https://github.com/PowerShell/PowerShellEditorServices/releases/download/v4.7.0/PowerShellEditorServices.zip
+unzip -q PowerShellEditorServices.zip
+export TDB_PSES_PATH=~/.local/share/tdb/pses/PowerShellEditorServices
+```
+
+A `pwsh` that isn't on PATH can be named with `{"adapters": {"pwsh": "/path/to/pwsh"}}`.
+
+```bash
+tdb script.ps1               # launch, stop at the first statement
+tdb --run script.ps1         # run immediately, debug on demand (pause works)
+```
+
+Notes:
+
+- Entry stop lands on the first statement of your script (comments and
+  function definitions are skipped): PSES has no native `stopOnEntry` for
+  this launch shape, so tdb sets a synthetic breakpoint on the bundled
+  launcher, steps in, and clears it — no line-1 breakpoint appears in the
+  Breakpoint view.
+- The script runs inside that small bundled launcher (`tdb_launch.ps1`) so
+  tdb can report the script's exit code. In the Stack view, top to bottom:
+  PSES's `<Breakpoint>` marker frame (the frame to inspect — it tracks the
+  accurate current position), your script's own frames, the launcher's
+  `<ScriptBlock>`, and a source-less `Interactive Session` frame at the
+  bottom.
+- Stepping is statement-granular, as in VS Code: a line containing a
+  `$( ... )` subexpression takes two `next` presses to clear, and `stepIn`
+  first lands on the called function's declaration line before its body.
+- An uncaught terminating error ends the script with exit code 1 and opens
+  the fatal-error modal from pwsh's concise error text. Non-terminating
+  errors (`Write-Error`, failing cmdlets without `-ErrorAction Stop`) print
+  the same concise error block to the Console as stderr and let the script
+  continue with exit code 0, as in pwsh itself; there is no break-on-error
+  yet. The error block names the launcher's `& $Script` line rather than
+  your script's actual line for some error kinds (a known cosmetic
+  limitation).
+- The fatal-error modal is gated on a non-zero exit code, since pwsh prints
+  the identical block for terminating and non-terminating errors. A script
+  that reports a non-terminating error and then `exit 3` can therefore still
+  raise the modal, showing the last error block that names a file of yours;
+  blocks attributed to tdb's own `tdb_launch.ps1` are skipped, so a bare
+  `Write-Error` before the `exit` opens no modal at all.
+- `--terminal` and remote attach are not supported for PowerShell yet.
+- Windows PowerShell 5.1 is not supported (pwsh 7 only). Running tdb *on*
+  Windows against pwsh is designed for but not yet verified (experimental).
+
 ## Layout
 
 ```
@@ -900,7 +1100,9 @@ stops on each physical line--useful for inspecting how a complex expression is b
 The choice is saved to `~/.config/tdb/config.json`.
 
 Statement mode requires a source-language model and is currently Python-only;
-other languages always step per line (the Step Mode menu says so if you try).
+other languages step at their debugger's native granularity — per line,
+except PowerShell, whose debugger stops per statement, see
+[PowerShell](#powershell) (the Step Mode menu says so if you try).
 
 ### Breakpoints
 
@@ -1266,12 +1468,14 @@ sessions via `--adapter lldb-dap`. Neither `gdb -i dap` (the default C/C++
 adapter, and an alternate for native OCaml) nor `ocamlearlybird` (the
 bytecode OCaml adapter) has any terminal integration -- `tdb` rejects
 `--terminal` up front for both, with an error pointing at `--adapter
-lldb-dap` instead. `--terminal` also only applies when `tdb` launches the
-program itself; it is rejected for remote-attach (`-r`), since there's no
-program for `tdb` to spawn a terminal around.
+lldb-dap` instead. Go and PowerShell don't support `--terminal` either
+(`dlv dap` has no terminal-routing mode; PSES likewise). `--terminal` also
+only applies when `tdb` launches the program itself; it is rejected for
+remote-attach (`-r`), since there's no program for `tdb` to spawn a
+terminal around.
 
 The debuggee runs in a separate window of the specified terminal, including
-all of its stdin/stdout/stderr -- keyboard input, program output, and
+all of its stdin/stdout/stderr. Keyboard input, program output, and
 anything the program itself draws to the terminal all happen in that
 window, not in `tdb`'s Console View. Supported choices:
 `xterm`, `konsole`, `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`,
@@ -1309,7 +1513,7 @@ tdb --run my_program.py; echo $?   # my_program.py's own exit code
 **Interrupting:** press Ctrl-C in the terminal (any platform), or, on Unix, send
 `SIGUSR1` to `tdb`'s pid from another terminal: `kill -USR1 <tdb pid>`. Either one pauses
 the debuggee at its currently executing line and opens the TUI with full debugging
-available -- breakpoints, stepping, variable inspection, the evaluate console. The
+available (breakpoints, stepping, variable inspection, the evaluate console). The
 debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
 group), so its own `SIGINT` handling is undisturbed.
 
@@ -1327,10 +1531,11 @@ nonzero `sys.exit()`, which `debugpy` treats as an uncaught `SystemExit` -- `tdb
 the TUI at the point of failure instead of exiting silently, so you can inspect the
 crash. Exit-code passthrough applies only to a clean exit during the headless phase.
 
-Supported languages: Python, Perl, Bash, Tcsh, Ruby, C/C++ (both `gdb` and
-`lldb-dap`), and native OCaml (both `gdb` and `lldb-dap`; bytecode/
-`ocamlearlybird` sessions don't support pause, so `--run` is unavailable
-for those). `--run` is rejected up front for any other language.
+Supported languages: Python, Perl, Bash, Tcsh, Ruby, PowerShell 7, C/C++
+(both `gdb` and `lldb-dap`), and native OCaml (both `gdb` and `lldb-dap`;
+bytecode/`ocamlearlybird` sessions don't support pause, so `--run` is
+unavailable for those). `--run` is rejected up front for any other
+language.
 
 **Limitation:** pausing is cooperative. If the debuggee is blocked inside a single
 blocking external call or syscall, the pause can't land until that call returns --
@@ -1339,6 +1544,48 @@ blocking external call or syscall, the pause can't land until that call returns
 **Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--server`,
 `--headless`, `--mcp`, `--terminal`.
 
+### Eval Mode (`-e`/`--eval`)
+
+Eval mode automates a common debugging loop--set a breakpoint, run to it,
+evaluate an expression in the Evaluate console, continue--without
+opening the TUI. `-e` takes two arguments, a location and an expression:
+
+```bash
+tdb --eval examples/digits_of_pi.py:25 "print(f'{nr=}')" examples/digits_of_pi.py
+```
+
+sets a breakpoint at line 25, runs the program, and each time that line is
+reached evaluates `print(f'{nr=}')` in the stopped frame, then continues.
+Program output and evaluation output both stream to the terminal; when the
+program exits, `tdb` exits with the same code (and with `1` if the session
+ends without one--as with a crash or killed adapter--so a scripted `tdb -e ...
+&& next` can trust the exit status). `Ctrl-C` stops the program and exits
+`130`. Under `multiprocessing`, an eval point placed in child code is
+evaluated in each child process that reaches it.
+
+- The location is `FILE:LINE`, or a bare `LINE` of the program being debugged,
+  and is snapped to the start of a logical statement just like `-k`.
+- `-e` may be repeated to plant several eval points in one run.
+- The expression is evaluated through the debug adapter (DAP `evaluate`,
+  context `repl`), just like the Evaluate console: side effects are real
+  and persist in the running program, for example 
+  `-e my_program.py:25 "limit = 10"` changes `limit` from line 25 onward.
+- A bare expression's result is printed to stdout; statement-style
+  expressions (`print(...)`, assignments) print nothing beyond their own
+  output. An expression error is reported on stderr and the run continues --
+  a typo isn't fatal, matching the Evaluate console.
+- Saved breakpoints are ignored, and any other stop (e.g. an
+  uncaught-exception stop) is continued untouched, so the program runs to
+  completion unattended.
+- For non-Python debuggees the expression must be in the debug adapter's
+  own syntax, for example gdb's `print x` / `set var x=3` for C/C++, and not
+  necessarily the debuggee's language. The adapter may bind the breakpoint
+  to the next executable line (gdb moves one off a declaration or brace);
+  the eval point matches that bound line, so the expression still runs.
+
+**Incompatible flags:** `--run`, `-r`, `-a`, `-k`/`-t`, `--record`,
+`--replay`, `--server`, `--headless`, `--mcp`, `--terminal`.
+
 ### Keybinding Schemes
 
 ```bash
@@ -1634,6 +1881,10 @@ found; it's Python code, not an external executable), so
 `{"adapters": {"perl": "/path/to/perl"}}`. Use this when the `perl` on
 `PATH` is too old (< 5.18) or you need a specific `perlbrew`/`plenv` version.
 
+**PowerShell** follows the same pattern with two keys: `adapters.pwsh` names
+the interpreter and `adapters.pses` names the PowerShell Editor Services
+module directory (see [PowerShell](#powershell)).
+
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent. Breakpoints set with
 `-t`/`--to-line` are the exception: they behave like `-k` breakpoints during