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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.4
+Version: 0.2.6
 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:
@@ -142,6 +142,8 @@ as open source.
 - OpenAI, for providing access to Codex through the
 [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
 
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/) debugger.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -303,8 +305,9 @@ process inspectors and wait graph, the evaluate console's trailing-`?` help,
 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.
+for C/C++, Bash, or Tcsh. `--terminal` works for every launch-mode
+language — Python, Perl, Bash, Tcsh, and C/C++ via `--adapter lldb-dap` —
+see [External Terminal Support](#external-terminal-support).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature envelope than Python/Perl:
@@ -366,6 +369,9 @@ 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.
 
 ### Perl
 
@@ -379,6 +385,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 +509,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 +539,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
@@ -1007,22 +1018,82 @@ 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, and C/C++ via `--adapter lldb-dap`.
+The default C/C++ adapter, `gdb -i dap`, has no terminal integration --
+`tdb` rejects `--terminal` up front with an error pointing at
+`--adapter lldb-dap` instead. `--terminal` also only applies when `tdb`
+launches the program itself; it is rejected for remote-attach (`-r`), since
+there's no program for `tdb` to spawn a terminal around.
+
+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`)
+
+For inspecting a program that appears hung: run it headless, at full speed, with no
+breakpoints installed and no stop-on-entry, then drop into the full TUI the moment you
+actually need it -- without paying for either up front.
+
+```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, and C/C++ (both `gdb` and `lldb-dap`).
+`--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

{textual_debugger-0.2.4/src/tdb → textual_debugger-0.2.6}/README.md

@@ -74,6 +74,8 @@ as open source.
 - OpenAI, for providing access to Codex through the
 [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
 
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/) debugger.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -235,8 +237,9 @@ process inspectors and wait graph, the evaluate console's trailing-`?` help,
 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.
+for C/C++, Bash, or Tcsh. `--terminal` works for every launch-mode
+language — Python, Perl, Bash, Tcsh, and C/C++ via `--adapter lldb-dap` —
+see [External Terminal Support](#external-terminal-support).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature envelope than Python/Perl:
@@ -298,6 +301,9 @@ 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.
 
 ### Perl
 
@@ -311,6 +317,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
@@ -432,7 +441,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
@@ -461,7 +471,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
@@ -939,22 +950,82 @@ 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, and C/C++ via `--adapter lldb-dap`.
+The default C/C++ adapter, `gdb -i dap`, has no terminal integration --
+`tdb` rejects `--terminal` up front with an error pointing at
+`--adapter lldb-dap` instead. `--terminal` also only applies when `tdb`
+launches the program itself; it is rejected for remote-attach (`-r`), since
+there's no program for `tdb` to spawn a terminal around.
+
+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`)
+
+For inspecting a program that appears hung: run it headless, at full speed, with no
+breakpoints installed and no stop-on-entry, then drop into the full TUI the moment you
+actually need it -- without paying for either up front.
+
+```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, and C/C++ (both `gdb` and `lldb-dap`).
+`--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

{textual_debugger-0.2.4 → textual_debugger-0.2.6/src/tdb}/README.md

@@ -74,6 +74,8 @@ as open source.
 - OpenAI, for providing access to Codex through the
 [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
 
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/) debugger.
+
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -235,8 +237,9 @@ process inspectors and wait graph, the evaluate console's trailing-`?` help,
 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.
+for C/C++, Bash, or Tcsh. `--terminal` works for every launch-mode
+language — Python, Perl, Bash, Tcsh, and C/C++ via `--adapter lldb-dap` —
+see [External Terminal Support](#external-terminal-support).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature envelope than Python/Perl:
@@ -298,6 +301,9 @@ 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.
 
 ### Perl
 
@@ -311,6 +317,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
@@ -432,7 +441,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
@@ -461,7 +471,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
@@ -939,22 +950,82 @@ 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, and C/C++ via `--adapter lldb-dap`.
+The default C/C++ adapter, `gdb -i dap`, has no terminal integration --
+`tdb` rejects `--terminal` up front with an error pointing at
+`--adapter lldb-dap` instead. `--terminal` also only applies when `tdb`
+launches the program itself; it is rejected for remote-attach (`-r`), since
+there's no program for `tdb` to spawn a terminal around.
+
+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`)
+
+For inspecting a program that appears hung: run it headless, at full speed, with no
+breakpoints installed and no stop-on-entry, then drop into the full TUI the moment you
+actually need it -- without paying for either up front.
+
+```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, and C/C++ (both `gdb` and `lldb-dap`).
+`--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

{textual_debugger-0.2.4 → textual_debugger-0.2.6}/src/tdb/__init__.py

@@ -1,6 +1,6 @@
 from tdb.breakpoint_hook import breakpoint
 from tdb.post_mortem import exception_hook
 
-__version__ = "0.2.4"  # trailing digit odd == dev version
+__version__ = "0.2.6"  # trailing digit odd == dev version
 
 __all__ = ["breakpoint", "exception_hook"]

{textual_debugger-0.2.4 → textual_debugger-0.2.6}/src/tdb/adapters/bash/server.py

@@ -15,6 +15,7 @@ from typing import Any, Awaitable, Callable
 
 from tdb.dap.messages import Event, Request, Response, parse_message
 from tdb.dap.protocol import encode_message, read_message
+from tdb.dap.reverse import ReverseRequester
 
 from .declares import BashVar
 from .session import BashProtocolError, BashSession
@@ -47,6 +48,14 @@ class BashDapServer:
         self._refs: dict[int, tuple] = {}
         self._next_ref = 1
         self._stack_cache: list[dict] | None = None
+        self._reverse = ReverseRequester(self._write, self._next_seq)
+        self._client_supports_run_in_terminal = False
+        # Strong ref: asyncio only holds a weak reference to a bare
+        # ensure_future() task, so it can be garbage-collected mid-flight
+        # if nothing else keeps it alive. An externalTerminal launch runs
+        # in the background so run()'s read loop can service the
+        # runInTerminal reverse-request reply (see _on_launch).
+        self._launch_task: asyncio.Future | None = None
         self.handlers: dict[str, Callable[[Request], Awaitable[None]]] = {}
         for name in dir(self):
             if name.startswith("_on_"):
@@ -92,6 +101,9 @@ class BashDapServer:
             except (ConnectionError, asyncio.IncompleteReadError, EOFError):
                 break
             msg = parse_message(raw)
+            if self._reverse.route(msg):
+                await self._writer.drain()
+                continue
             if not isinstance(msg, Request):
                 continue
             handler = self.handlers.get(msg.command)
@@ -131,15 +143,90 @@ class BashDapServer:
 
     # ---- lifecycle ----
     async def _on_initialize(self, request: Request) -> None:
+        self._client_supports_run_in_terminal = bool(
+            request.arguments.get("supportsRunInTerminalRequest")
+        )
         self.send_response(request, CAPABILITIES)
 
+    async def _cancel_launch_task(self) -> None:
+        """Cancel and await an in-flight externalTerminal `_finish_launch`
+        background task before disconnect/terminate tear down the session.
+
+        Without this, a still-running launch continuation can assign
+        `self.session = BashSession(...)` (the first thing `_finish_launch`
+        does, synchronously, before any await) AFTER disconnect/terminate's
+        own `if self.session is not None` check already ran and found
+        nothing to stop -- leaking a live (or about-to-be-live) debuggee
+        with nothing left to ever call session.stop() on it. Cancelling and
+        awaiting first makes the eventual `self.session is not None` check
+        below see any session the task managed to create before it was
+        cancelled, so it still gets torn down.
+        """
+        task, self._launch_task = self._launch_task, None
+        if task is None or task.done():
+            return
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            log.exception("launch task raised during cancellation")
+
     async def _on_launch(self, request: Request) -> None:
         args = request.arguments
         program = args.get("program", "")
         if not os.path.isfile(program):
             self.send_error(request, f"program not found: {program}")
             return
+        run_in_terminal = None
+        if args.get("console") == "externalTerminal":
+            if not self._client_supports_run_in_terminal:
+                self.send_error(
+                    request,
+                    "externalTerminal launch requires a client that "
+                    "supports the runInTerminal reverse request",
+                )
+                return
+
+            async def run_in_terminal(cmd, cwd, env):
+                await self._reverse.request(
+                    "runInTerminal",
+                    {
+                        "kind": "external",
+                        "title": "tdb bash debuggee",
+                        "cwd": cwd,
+                        "args": cmd,
+                        "env": env,
+                    },
+                )
+
         self._stop_on_entry = bool(args.get("stopOnEntry", True))
+        if run_in_terminal is not None:
+            # session.launch() awaits self._reverse.request("runInTerminal",
+            # ...), whose reply can only be read/routed by THIS coroutine's
+            # own run() loop -- but run() is what's calling _on_launch, and
+            # it awaits handler(msg) synchronously before reading the next
+            # message. Awaiting inline here would deadlock: the reply can
+            # never arrive because nothing is reading stdin anymore. Run
+            # the rest of launch as a background task (strong ref, per the
+            # repo's task-GC pitfall) so _on_launch returns immediately,
+            # letting run() go back to reading -- including the eventual
+            # runInTerminal response, which self._reverse.route(msg)
+            # handles directly in run() without going through a handler.
+            self._launch_task = asyncio.ensure_future(
+                self._finish_launch(request, program, args, run_in_terminal)
+            )
+            return
+        await self._finish_launch(request, program, args, run_in_terminal)
+
+    async def _finish_launch(
+        self,
+        request: Request,
+        program: str,
+        args: dict,
+        run_in_terminal,
+    ) -> None:
         self.session = BashSession(
             self._forward_output, self._on_session_stop, self._on_session_exit
         )
@@ -150,15 +237,39 @@ class BashDapServer:
                 cwd=args.get("cwd") or os.getcwd(),
                 env=args.get("env"),
                 bash=args.get("bash") or "bash",
+                run_in_terminal=run_in_terminal,
             )
-        except BashProtocolError as e:
-            await self.session.stop()
+        except Exception as e:
+            # Deliberately broad (mirrors run()'s own blanket `except
+            # Exception` net around handler dispatch): BashProtocolError
+            # and ReverseRequestError are the expected failures, but
+            # session.launch() can also raise e.g. bare
+            # asyncio.TimeoutError (ReverseRequester.request()'s own
+            # wait_for) or OSError. In the terminal-mode (background-task)
+            # case this coroutine is NOT awaited inline by run() -- there
+            # is no other except-Exception net standing behind this one --
+            # so anything narrower here would leave the client's launch
+            # request unanswered forever and silently strand the exception
+            # on self._launch_task.
+            #
+            # asyncio.CancelledError deliberately propagates past this
+            # (BaseException, not Exception, on py>=3.8): that's
+            # _on_disconnect/_on_terminate cancelling an in-flight launch,
+            # not a launch failure, and they do their own cleanup.
+            try:
+                await self.session.stop()
+            except Exception:
+                log.exception("session.stop() failed while tearing down failed launch")
             self.session = None
+            if not isinstance(e, BashProtocolError):
+                log.exception("launch failed unexpectedly")
             self.send_error(request, str(e))
+            await self._writer.drain()
             return
         self._launched = True
         self._start_request = request
         self.send_event("initialized")
+        await self._writer.drain()
         # response is sent by _on_configurationDone (DAP ordering)
 
     async def _on_configurationDone(self, request: Request) -> None:
@@ -171,6 +282,7 @@ class BashDapServer:
         self.session.resume("step" if self._stop_on_entry else "continue")
 
     async def _on_disconnect(self, request: Request) -> None:
+        await self._cancel_launch_task()
         if self.session is not None:
             await self.session.stop()
             self.session = None