dbxdebug 0.3.0__tar.gz → 0.5.0__tar.gz

{dbxdebug-0.3.0 → dbxdebug-0.5.0}/.github/workflows/release.yml

@@ -9,6 +9,18 @@ name: Release
 on:
   push:
     branches: [main]
+  # Recovery path. A tag/release created with GITHUB_TOKEN does not trigger a
+  # workflow, so a publish that fails for an environmental reason (a bad
+  # publisher/metadata pairing, a PyPI outage) cannot be retried by re-running
+  # the original run -- a re-run replays the workflow file from that commit,
+  # including whatever was broken. Dispatch this against the existing tag
+  # instead. It rebuilds from that tag and republishes; it never creates a tag.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to build and publish, e.g. v0.3.0"
+        required: true
+        type: string
 
 permissions: {}
 
@@ -18,6 +30,7 @@ concurrency:
 
 jobs:
   release-please:
+    if: ${{ github.event_name == 'push' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write # create the release + tag
@@ -26,7 +39,7 @@ jobs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
     steps:
-      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
         id: release
         with:
           config-file: release-please-config.json
@@ -36,14 +49,14 @@ jobs:
   # If anything here fails, the publish job below is skipped and nothing ships.
   ci:
     needs: release-please
-    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    if: ${{ !cancelled() && (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch') }}
     permissions:
       contents: read
     uses: ./.github/workflows/test.yml
 
   publish:
     needs: [release-please, ci]
-    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    if: ${{ !cancelled() && needs.ci.result == 'success' && (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch') }}
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -52,13 +65,13 @@ jobs:
       id-token: write # OIDC for PyPI Trusted Publishing
       contents: write # upload built artifacts to the GitHub Release
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ needs.release-please.outputs.tag_name }}
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
           fetch-depth: 0 # Full history + tags for hatch-vcs version
 
       - name: Install uv and set up Python
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
 
@@ -66,9 +79,9 @@ jobs:
         run: uv build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
 
       - name: Attach artifacts to the GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release upload "${{ needs.release-please.outputs.tag_name }}" dist/* --clobber
+        run: gh release upload "${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}" dist/* --clobber

{dbxdebug-0.3.0 → dbxdebug-0.5.0}/.github/workflows/test.yml

@@ -18,10 +18,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set up Python
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
 
@@ -47,10 +47,10 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12"]
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set up Python ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -64,12 +64,12 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0 # Full history for hatch-vcs
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Build (packaging smoke test)
         run: uv build

{dbxdebug-0.3.0 → dbxdebug-0.5.0}/.pre-commit-config.yaml

@@ -27,19 +27,32 @@ repos:
     hooks:
       - id: gitleaks
 
-  # Ruff for linting and formatting
+  # Ruff for linting and formatting.
+  #
+  # This rev and the `ruff` floor in pyproject.toml are ONE version, pinned in
+  # two places, and they must be bumped together. Two ruffs run against this
+  # repo -- this hook on every commit, and the resolved dev environment in CI
+  # -- and when they drifted six minor versions apart they disagreed about
+  # formatting: 0.8.4 rewrote a multi-line `assert ..., "message"` into a shape
+  # 0.14.9's `--check` then rejected, so a commit blessed here was refused by
+  # CI and each tool undid the other (lokkju/dbxdebug#17). Neither reports its
+  # version in the diff it produces, which is what made that confusing.
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+    rev: v0.14.9
     hooks:
-      - id: ruff
+      # `ruff-check`, not `ruff`: the latter is a legacy alias in 0.14.x and
+      # says so on every run.
+      - id: ruff-check
         types_or: [python, pyi]
         args: [--fix]
       - id: ruff-format
         types_or: [python, pyi]
 
-  # Pyright for type checking
+  # Pyright for type checking. Same rule as ruff above: this rev and the
+  # `pyright` floor in pyproject.toml are one version in two places. A pyright
+  # that is stale here accepts code CI's newer one rejects.
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.390
+    rev: v1.1.411
     hooks:
       - id: pyright
         additional_dependencies:
@@ -68,8 +81,10 @@ repos:
     hooks:
       - id: actionlint
 
-  # UV for dependency management - ensures uv.lock is synced
+  # UV for dependency management - ensures uv.lock is synced. Matched to the
+  # uv that resolved the current lockfile: this hook REWRITES uv.lock, so an
+  # older uv here can churn the file the developer's own uv just wrote.
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.13
+    rev: 0.9.21
     hooks:
       - id: uv-lock

dbxdebug-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{dbxdebug-0.3.0 → dbxdebug-0.5.0}/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.5.0](https://github.com/lokkju/dbxdebug/compare/v0.4.0...v0.5.0) (2026-09-06)
+
+
+### Features
+
+* **api:** derive the package root's exports from the modules' __all__ ([f4fbb2d](https://github.com/lokkju/dbxdebug/commit/f4fbb2d18a7a4b7c329c7593a26e39e99930b1c6)), closes [#7](https://github.com/lokkju/dbxdebug/issues/7)
+* **qmp:** add mouse input to QMPClient ([a25a356](https://github.com/lokkju/dbxdebug/commit/a25a356c19115d5ea12189aca3c221413602dc9f)), closes [#2](https://github.com/lokkju/dbxdebug/issues/2)
+
+
+### Bug Fixes
+
+* **frames:** end steps_out at the return address, and wrap segment reads ([40e2817](https://github.com/lokkju/dbxdebug/commit/40e28174473ada9997f650b84051cf296f72d0dd)), closes [#6](https://github.com/lokkju/dbxdebug/issues/6)
+* **gdb:** make the pending-stop queue service itself ([908eae0](https://github.com/lokkju/dbxdebug/commit/908eae0ea621ea460c4627a4f7d4320eaaace81a)), closes [#18](https://github.com/lokkju/dbxdebug/issues/18)
+
+## [0.4.0](https://github.com/lokkju/dbxdebug/compare/v0.3.0...v0.4.0) (2026-09-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **session:** DosboxSession now runs the emulator headless by default. A caller that relied on seeing the window -- to watch the guest while debugging, or to drive it by hand -- must now pass headless=False explicitly. Everything else is unaffected: the debug surface is identical headless, and screen capture was verified byte-identical between the two modes. Note also that `headless` sits mid-dataclass, so positional construction past `connect=` shifts.
+
+### Features
+
+* **session:** add DosboxSession(headless=True), on by default ([8af1f56](https://github.com/lokkju/dbxdebug/commit/8af1f56528977c2dbc4a2ddec442f4aa6f76933d)), closes [#3](https://github.com/lokkju/dbxdebug/issues/3)
+* **session:** add read_bulk, a one-call bulk memory read ([f8e228b](https://github.com/lokkju/dbxdebug/commit/f8e228b101b14e682e3b4ec98b434f1fd7e5e7c7)), closes [#9](https://github.com/lokkju/dbxdebug/issues/9)
+
+
+### Bug Fixes
+
+* **ci:** unblock publishing and add a recovery path for a failed one ([9c69a87](https://github.com/lokkju/dbxdebug/commit/9c69a87c73f30b0a249e1bd5ec3c4cc4f2af0736))
+* **gdb:** bound reads and resynchronise the packet stream ([5940242](https://github.com/lokkju/dbxdebug/commit/5940242035181668c4d35e61db56d5b2342aa620))
+* **session:** record that headless is now the default ([d649d70](https://github.com/lokkju/dbxdebug/commit/d649d705bb46261d38c30a23fc9c39bd390f7c87))
+* **video,cli:** let a GDB client be borrowed instead of reopened ([bb9d351](https://github.com/lokkju/dbxdebug/commit/bb9d35170283407f9c7fbd64f4cfd4f1d75f1d64))
+
+
+### Performance Improvements
+
+* **clients:** set TCP_NODELAY, and correct what read_bulk is now worth ([c535e3b](https://github.com/lokkju/dbxdebug/commit/c535e3bafe2799e708714e4f771046fd35a55d81))
+
+
+### Documentation
+
+* correct the hazard write-ups now that the GDB stream is fixed ([a1821aa](https://github.com/lokkju/dbxdebug/commit/a1821aa8904987afd73ad1ba97d022fee5e30213)), closes [#4](https://github.com/lokkju/dbxdebug/issues/4) [#5](https://github.com/lokkju/dbxdebug/issues/5)
+* **migration:** fix the gaps a real migration hit ([96ffaa7](https://github.com/lokkju/dbxdebug/commit/96ffaa7a901a35529e14a81828f8a36d550664d9))
+
 ## [0.3.0](https://github.com/lokkju/dbxdebug/compare/v0.2.1...v0.3.0) (2026-09-05)
 
 

{dbxdebug-0.3.0 → dbxdebug-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dbxdebug
-Version: 0.3.0
+Version: 0.5.0
 Summary: Client library and CLI for DOSBox-X remote debug protocols (GDB and QMP)
 Author: lokkju
 License-Expression: LicenseRef-Polyform-Shield-1.0.0
@@ -70,12 +70,11 @@ For working on dbxdebug itself, `uv sync`.
 ## Quick start
 
 ```python
-from dbxdebug.session import DosboxSession
+from dbxdebug import DosboxSession
 
-# Without these DOSBox-X opens a real window and takes your keyboard focus.
-HEADLESS = {"SDL_VIDEODRIVER": "dummy", "SDL_AUDIODRIVER": "dummy"}
-
-with DosboxSession(env=HEADLESS) as session:
+# Headless by default: no window, no keyboard focus, no audio device.
+# Pass headless=False when you want to watch the guest.
+with DosboxSession() as session:
     print(f"pid={session.pid} gdb={session.gdb_port} qmp={session.qmp_port}")
 
     gdb = session.gdb
@@ -103,15 +102,56 @@ Leaving the `with` block kills the emulator's whole process group, deletes the
 scratch workdir, and removes the registry entry. `atexit` and SIGINT/SIGTERM
 handlers repeat that teardown for a process that leaves by some other door.
 
+### Headless is the default
+
+A session runs with SDL's `dummy` video and audio drivers, so it opens **no
+window**, takes no keyboard focus, and claims no audio device. Starting one
+does not take over the display of whoever is at the machine, which is what
+makes a test suite -- or several sessions at once -- usable on a workstation.
+
+What you give up is real: you cannot watch the guest. `headless=False` gives
+you a normal window, and that window will take the focus of whoever is at the
+keyboard, so it is for looking at one session, not for a suite.
+
+The debug surface is unaffected. `screen_lines()` reads guest video memory
+over GDB and `qmp.screendump()` renders through DOSBox-X's own capture path;
+`dummy` removes the window, not the rendering. Compared live, a headless
+session and a windowed session showing the same screen returned
+**byte-identical** 720x400 PNGs and identical text lines.
+
+`env=` still works and takes precedence over the headless variables, so
+`DosboxSession(headless=True, env={"SDL_VIDEODRIVER": "x11"})` keeps the dummy
+audio driver and gets an x11 window. Precedence, lowest to highest: inherited
+`os.environ`, then the headless variables, then `env`.
+
 Useful `DosboxSession` arguments: `mounts={"c": path}`, `program=` and
 `files=` to stage host files onto the first mounted drive, `autoexec=`,
-`conf=` for your own conf template, `cycles=`, `connect=False` for the handle
-without clients, `boot_settle=` (default 2.5s -- the debug ports accept long
-before the guest reaches a prompt), and `label=` to name the scratch workdir.
-Conveniences on the handle: `screen_lines()`, `wait_for_text()`,
+`conf=` for your own conf template, `cycles=`, `headless=False` for a visible
+window, `connect=False` for the handle without clients, `boot_settle=`
+(default 2.5s -- the debug ports accept long before the guest reaches a
+prompt), and `label=` to name the scratch workdir.
+Conveniences on the handle: `screen_lines()`, `read_bulk()`, `wait_for_text()`,
 `assert_screen_readable()`, `running`, `set_breakpoint()`,
 `remove_breakpoint()`.
 
+### Reading a region: `session.read_bulk(address, length)`
+
+One QMP `memdump` reply instead of thousands of GDB `m` round-trips.
+Measured on this build, one 64 KB segment: **2.8 ms** through `read_bulk` against **33.5 ms** for the same bytes through 64 one-kilobyte `gdb.read_memory` calls -- 12x against a running guest, and 2.6x (2.1 ms against 5.5 ms) when the CPU is already halted, where the loop has no emulation competing with it. Both paths return
+identical bytes; the live suite asserts it.
+
+```python
+data = session.read_bulk(0xF0000, 0x10000)   # -> 65536 bytes
+```
+
+It exists because the raw sequence has two traps. `memdump` is refused
+while the CPU runs, and the obvious way to stop it -- `qmp.stop()` --
+parks the emulation thread that services the GDB stub, so the dump
+succeeds and every later GDB request goes unanswered. `read_bulk` halts
+through GDB, dumps, and resumes. If the CPU was ALREADY stopped (a
+breakpoint, the interactive debugger, or a QMP stop) it takes the dump
+and leaves it stopped: it resumes only what it halted itself.
+
 ## Addressing -- read this once
 
 This is the most consequential behaviour in the package, and the thing most
@@ -182,7 +222,7 @@ old build fails at `start()` rather than at the first breakpoint.
 |---|---|
 | `dbxdebug.session` | `DosboxSession` -- launch, connect, tear down. Also `DEFAULT_CONF`, `render_conf`, `DosboxLaunchError` |
 | `dbxdebug.gdb` | `GDBClient`, `IncompatibleStubError`, `REGISTER_NAMES` |
-| `dbxdebug.qmp` | `QMPClient`, `QMPError` -- keys, `memdump`, `screendump`, save/load state, `stop`/`cont`, `debug_break_on_exec` |
+| `dbxdebug.qmp` | `QMPClient`, `QMPError`, `CpuNotStoppedError` -- keys, `memdump`, `screendump`, save/load state, `stop`/`cont`, `debug_break_on_exec` |
 | `dbxdebug.addressing` | `linear`, `linear_pc`, `parse_address`, `bp_addr`, `PackedAddressError` |
 | `dbxdebug.frames` | `walk_frames`, `steps_out`, `Frame`, `FrameWalkError` |
 | `dbxdebug.registry` | `list_sessions`, `reap`, `format_table`, `free_port`, `kill_group` |
@@ -191,10 +231,36 @@ old build fails at `start()` rather than at the first breakpoint.
 | `dbxdebug.video` / `.html` / `.capture_io` | `DOSVideoTools`, HTML rendering, `ScreenRecorder`, `load_capture` |
 | `dbxdebug.keyboard` / `.dbx_kbd` | key-chord helpers and constants (`CTRL_C`, `ctrl_key`, `DBX_KEY`, ...) |
 
-`dbxdebug/__init__.py` re-exports the clients, the video tools, and the
-keyboard helpers. It does **not** yet re-export `DosboxSession`, `addressing`,
-`frames`, `registry`, `paths` or `doctor` -- import those from their modules,
-as every example here does ([#7](https://github.com/lokkju/dbxdebug/issues/7)).
+### The export rule
+
+Every module declares its supported surface in `__all__`, and
+`dbxdebug/__init__.py` re-exports the union of the **library** modules'
+`__all__`. So everything in the table above except the last three rows'
+worth of command machinery is importable straight from `dbxdebug`:
+
+```python
+from dbxdebug import DosboxSession, GDBClient, QMPClient, linear, walk_frames
+```
+
+The exceptions are `dbxdebug.cli`, `dbxdebug.registry` and `dbxdebug.doctor`
+-- the `dbxdebug` command's own machinery. They act on the host's whole set
+of sessions rather than on the one you launched, and their names mean
+nothing unqualified: a package root should not own `run`, `reap`,
+`list_sessions` or `free_port`. Import those from their modules:
+
+```python
+from dbxdebug.registry import list_sessions, reap
+from dbxdebug import doctor
+
+report = doctor.run()
+```
+
+Leaving `cli` out is also what keeps `import dbxdebug` free of `click`.
+
+Module-path imports keep working everywhere, and the examples below use
+whichever form reads better in context -- `addressing.bp_addr` says more
+about `bp_addr` than a bare name does. `tests/test_exports.py` holds the
+root to the union so the two cannot drift.
 
 ### Locating the emulator
 
@@ -230,22 +296,29 @@ steps_out(gdb)                            # single-step until the current frame
 BP, a saved BP that is not strictly above the current one (which is also what
 terminates a cyclic chain), a short or failed read, or `max_depth`.
 
-`steps_out` is **a heuristic over SP**, with bounds worth knowing before you
-rely on it. It records the entry BP and steps until `SP & 0xFFFF` is strictly
-greater than `BP + 2` -- past the return-address slot, which only the `ret`
-itself reaches, not the `pop bp` or `leave` before it. Consequences:
+`steps_out` reads the frame's own return address once, then steps until the
+CPU is **at that address with the return slot popped**: `IP` equal to
+`[BP+2]`, and either `CS` unchanged with `SP >= BP+4` (a near return) or `CS`
+equal to `[BP+4]` with `SP >= BP+6` (a far one). Both halves matter -- SP
+alone stops early on a callee that raises SP without returning
+(`pop ax / add sp,N / jmp ax`), and the return address alone would accept a
+callee merely branching through the caller's code. Nothing is decoded; every
+value compared already arrives with each step's register read. Consequences:
 
 * it raises `FrameWalkError` if `SP > BP` on entry (no frame pointer
-  established, or a stale BP) rather than returning after a single step;
-* a callee that pops BP and jumps to a shared epilogue popping further
-  registers raises SP past `BP+2` while still inside the callee, and this
-  stops there, early. Telling that apart from a real return needs instruction
-  decoding, which this does not do;
+  established, or a stale BP) rather than returning after a single step, and
+  likewise for a `BP` so near the top of SS that no return SP would fit in 16
+  bits;
+* a return address that never arrives -- a guest that rewrites its own return
+  slot -- runs to `timeout`/`max_steps` and **raises**, naming the address it
+  was waiting for. It does not stop somewhere plausible;
 * called at a procedure's first instruction, before the prologue has run, BP
   still belongs to the caller and this measures the caller's frame;
 * **clear every breakpoint first.** A breakpoint hit during one of these steps
-  makes the stub emit an unsolicited stop reply, which permanently desyncs the
-  GDB connection -- see Known hazards.
+  makes the stub emit an unsolicited stop reply. The connection no longer
+  desyncs on one -- it is queued on `gdb.pending_stops` -- but the stop you
+  get is still not the step you asked for, so the walk ends up measuring a
+  frame you did not mean to be in. See Known hazards.
 
 ## CLI
 
@@ -352,56 +425,99 @@ with GDBClient() as gdb:                       # localhost:2159
     gdb.set_breakpoint("1000:0020")            # the same address, seg:off form
     gdb.step()
     gdb.continue_execution()
+    gdb.wait_for_stop(timeout=30.0)            # a stop NOBODY asked for
 
 with QMPClient() as qmp:                       # localhost:4444
     qmp.send_key(CTRL_C)
     qmp.type_text("Hello World!")
+    qmp.mouse_click("left")                    # buttons reach the guest
+    qmp.mouse_move(50, -20)                    # motion does NOT, headless
 
-with DOSVideoTools() as video:
+with DOSVideoTools() as video:                 # owns its own client
     lines = video.screen_dump()
     lines, ticks = video.screen_dump_with_ticks()
+
+with DOSVideoTools(gdb=session.gdb) as video:  # borrows a session's client
+    lines = video.screen_dump()                # and never closes it
 ```
 
 ## Known hazards
 
-Three open defects. All three are reproduced, all have tests pinning today's
-behaviour, and none is fixed. Plan around them.
+One open defect, and two that are fixed but still shape how you should write
+against this library.
+
+**Unanswered GDB packets: bounded, not silent** (was
+[#4](https://github.com/lokkju/dbxdebug/issues/4), fixed). `GDBClient` arms a
+30 s read timeout on every read, not just the connect, and raises
+`GDBTimeoutError` naming the packet that went unanswered. Override it per
+client with `GDBClient(timeout=...)`, or pass `timeout=None` for the old
+unbounded blocking. The underlying interaction is unchanged and still worth
+knowing: while the emulator is QMP-stopped the GDB stub is not serviced at
+all, so `qmp.stop()` followed by any GDB request cannot be answered. It now
+fails in 30 s with a message instead of deadlocking. To read memory, reach
+for `session.read_bulk()`, which halts over GDB for you; otherwise halt
+with `gdb.halt()` rather than stopping over QMP. A `memdump` refused for
+this reason now raises `CpuNotStoppedError` (a `QMPError`) naming the fix,
+rather than surfacing the stub's refusal alone.
+
+**Stream desync: resynchronised, or refused** (was
+[#5](https://github.com/lokkju/dbxdebug/issues/5), fixed). Both triggers were
+reproduced against a live build -- an unsolicited `$S05` stop reply (QMP
+break-on-exec fires one nobody asked for) and a timed-out request leaving its
+reply in the stream -- and both are handled at the framing layer:
+
+* an unrequested stop reply is diverted to `gdb.pending_stops` instead of
+  being read as an answer. Drain it with `gdb.take_pending_stops()`, or wait
+  on it with `gdb.wait_for_stop(timeout=...)`; both read the socket
+  themselves, so no other request is needed to shake a stop loose
+  ([#18](https://github.com/lokkju/dbxdebug/issues/18), fixed). The queue
+  keeps the most recent 64. This is how you learn the CPU stopped without
+  polling QMP;
+* an abandoned exchange is drained before the next packet is sent, so the
+  request after a `GDBTimeoutError` gets its own reply rather than the
+  previous one's;
+* if that drain cannot complete, the client marks itself **permanently
+  unusable** and every later call raises `GDBDesyncError`. That is
+  deliberate: a loud failure beats a plausible wrong answer. Open a new
+  `GDBClient`.
+
+Still true, and still worth doing: keep GDB traffic serialised on one thread,
+and never add a read-retry loop. Two identical consecutive requests mask a
+one-packet lag perfectly, so retrying would look like it worked whether or
+not the stream had shifted.
+
+**One GDB client at a time**
+([#8](https://github.com/lokkju/dbxdebug/issues/8)). The stub serves a single
+GDB client. A second one completes the TCP connect and then never gets its
+`qSupported` reply -- no refusal, and nothing on the wire. Two things changed
+independently: it now fails after the read timeout instead of hanging forever
+([#5](https://github.com/lokkju/dbxdebug/issues/5)), and nothing in this
+package opens a competing connection behind your back any more
+([#11](https://github.com/lokkju/dbxdebug/issues/11)). The stub limitation
+itself is still open ([#8](https://github.com/lokkju/dbxdebug/issues/8)).
 
-**No read timeout** ([#4](https://github.com/lokkju/dbxdebug/issues/4)).
-`GDBClient` never calls `settimeout`, so any packet the stub does not answer
-hangs the caller forever with no diagnostic. This is easy to reach by
-accident, because the two protocols interact: while the emulator is
-QMP-stopped the GDB stub does not answer at all, so `qmp.stop()` followed by
-any GDB request is a deadlock. Arm the socket yourself right after `start()`:
+Lend the session's client out instead of opening a second one:
 
 ```python
-if session.gdb is not None and session.gdb.sock is not None:
-    session.gdb.sock.settimeout(30.0)
-```
+from dbxdebug.cli import GDB_CLIENT_KEY, main
+from dbxdebug.video import DOSVideoTools
 
-**Desync after a timeout or an unsolicited stop reply**
-([#5](https://github.com/lokkju/dbxdebug/issues/5) -- confirmed and
-reproduced). `GDBClient` assumes strict request/response and never
-resynchronises. Once a reply is left unread, every later request returns the
-*previous* request's payload, silently and permanently. Both triggers are
-confirmed against a live build: an unsolicited `$S05` stop reply (QMP
-break-on-exec fires one nobody asked for), and a timed-out request leaving its
-reply in the stream -- so the `settimeout` above converts a hang into a
-`TimeoutError` that lands you here instead. Keep GDB traffic serialised on one
-thread, treat `TimeoutError` as fatal to the connection rather than retryable,
-and check the length of every `read_memory` result against what you asked for:
-it is the one cheap symptom visible from outside. Do not add a read-retry
-loop -- two identical consecutive requests mask a one-packet lag perfectly, so
-it would look like it worked whether or not the stream had shifted.
+with DosboxSession(...) as session:
+    with DOSVideoTools(gdb=session.gdb) as video:   # borrowed, not reopened
+        lines = video.screen_dump()
 
-**One GDB client at a time**
-([#8](https://github.com/lokkju/dbxdebug/issues/8)). The stub serves a single
-GDB client. A second one completes the TCP connect and then blocks forever in
-the `qSupported` handshake -- no refusal, no error, just a hang. In particular,
-pointing a `dbxdebug mem` / `cpu` / `screen` command at a session that already
-holds its own GDB client hangs that command. Use
-`DosboxSession(connect=False)` if you want the CLI to be the one client, or
-drive the session's own `session.gdb` from Python.
+    # the CLI, driven in-process, borrows the same client
+    main(["screen", "show"], obj={GDB_CLIENT_KEY: session.gdb}, standalone_mode=False)
+```
+
+A borrowed client is never closed by the borrower -- the session stays its
+owner. `DOSVideoTools()` with no `gdb=` still builds and closes its own, which
+is the right thing when it is the only client, and so does a `dbxdebug` command
+run as a separate process. Running the CLI as a separate process against a
+session that holds its own client is still a second connection however it is
+spelled, so it now fails on the timeout rather than working: use
+`DosboxSession(connect=False)` there, or drive the session's `session.gdb`
+from Python.
 
 QMP is a separate socket and is undisturbed by any of this, which is why
 `qmp.query_status()` is the way to learn that the CPU stopped.
@@ -425,11 +541,20 @@ prove the library actually drives one: the vendor GDB capabilities, `eip` as an
 offset rather than a linear address, a breakpoint above 64 KB firing, `memdump`
 agreeing with GDB reads and refusing while the CPU runs, `frames.steps_out`
 stopping after a real 16-bit `ret`, and what the GDB client does when the
-stream is disturbed -- which today is desync, pinned by tests that fail the
-moment it is fixed. The binary is located with `dbxdebug.paths.find_dosbox_x`
+stream is disturbed -- an unrequested stop reply queued rather than read as an
+answer, an abandoned reply drained rather than handed to the next request, and
+a request the stub will never answer bounded rather than deadlocked. The
+framing paths a live emulator will not produce on demand are covered against a
+fake socket in `tests/test_gdb_framing.py`.
+The binary is located with `dbxdebug.paths.find_dosbox_x`
 -- set `DBXDEBUG_DOSBOX` to choose a specific build -- and the tests skip when
 none is found.
 
+One test in `tests/integration/test_headless.py` is skipped even under the
+`integration` marker: the one that compares a headless screen capture against
+a windowed one has to launch a real window, which takes the keyboard focus of
+whoever is at the machine. Set `DBXDEBUG_ALLOW_WINDOWED=1` to run it.
+
 The other gates:
 
 ```bash