dbxdebug 0.3.0__tar.gz → 0.4.0__tar.gz

{dbxdebug-0.3.0 → dbxdebug-0.4.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
@@ -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
@@ -54,7 +67,7 @@ jobs:
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.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
@@ -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.4.0/.release-please-manifest.json

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

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

@@ -1,5 +1,36 @@
 # Changelog
 
+## [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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dbxdebug
-Version: 0.3.0
+Version: 0.4.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
@@ -72,10 +72,9 @@ For working on dbxdebug itself, `uv sync`.
 ```python
 from dbxdebug.session 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` |
@@ -244,8 +284,10 @@ itself reaches, not the `pop bp` or `leave` before it. Consequences:
 * 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
 
@@ -357,51 +399,88 @@ with QMPClient() as qmp:                       # localhost:4444
     qmp.send_key(CTRL_C)
     qmp.type_text("Hello World!")
 
-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()`; 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 +504,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

{dbxdebug-0.3.0 → dbxdebug-0.4.0}/README.md

@@ -50,10 +50,9 @@ For working on dbxdebug itself, `uv sync`.
 ```python
 from dbxdebug.session 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
@@ -81,15 +80,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
@@ -160,7 +200,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` |
@@ -222,8 +262,10 @@ itself reaches, not the `pop bp` or `leave` before it. Consequences:
 * 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
 
@@ -335,51 +377,88 @@ with QMPClient() as qmp:                       # localhost:4444
     qmp.send_key(CTRL_C)
     qmp.type_text("Hello World!")
 
-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()`; 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.
@@ -403,11 +482,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