dbxdebug 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -39,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
@@ -65,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: ${{ 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"
 

{dbxdebug-0.4.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.4.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.4.0 → dbxdebug-0.5.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dbxdebug
-Version: 0.4.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,7 +70,7 @@ For working on dbxdebug itself, `uv sync`.
 ## Quick start
 
 ```python
-from dbxdebug.session import DosboxSession
+from dbxdebug import DosboxSession
 
 # Headless by default: no window, no keyboard focus, no audio device.
 # Pass headless=False when you want to watch the guest.
@@ -231,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
 
@@ -270,17 +296,22 @@ 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
@@ -394,10 +425,13 @@ 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:                 # owns its own client
     lines = video.screen_dump()
@@ -433,9 +467,12 @@ 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;
+  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;

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

@@ -48,7 +48,7 @@ For working on dbxdebug itself, `uv sync`.
 ## Quick start
 
 ```python
-from dbxdebug.session import DosboxSession
+from dbxdebug import DosboxSession
 
 # Headless by default: no window, no keyboard focus, no audio device.
 # Pass headless=False when you want to watch the guest.
@@ -209,10 +209,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
 
@@ -248,17 +274,22 @@ 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
@@ -372,10 +403,13 @@ 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:                 # owns its own client
     lines = video.screen_dump()
@@ -411,9 +445,12 @@ 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;
+  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;

{dbxdebug-0.4.0 → dbxdebug-0.5.0}/docs/migration.md

@@ -63,36 +63,42 @@ Then delete the vendored copy. Nothing in the consumer should still import
 
 | What you had | Where it lives now |
 |---|---|
-| The launcher class (`Popen`, ports, cleanup) | `from dbxdebug.session import DosboxSession` |
+| The launcher class (`Popen`, ports, cleanup) | `from dbxdebug import DosboxSession` |
 | `dosbox_debug.GDBClient` | `from dbxdebug import GDBClient` |
 | `dosbox_debug.QMPClient`, `QMPError` | `from dbxdebug import QMPClient, QMPError` |
 | `dosbox_debug.GDBError` | No equivalent: see section 3 |
-| The launcher's `bp_addr` | `from dbxdebug.addressing import linear` (and see section 2.2) |
+| The launcher's `bp_addr` | `from dbxdebug import linear` (and see section 2.2) |
 | Screen decoding on the GDB client | `DosboxSession.screen_lines()`, or `from dbxdebug import DOSVideoTools` |
-| Frame walking, if you had it | `from dbxdebug.frames import walk_frames, steps_out` |
-| Finding the emulator binary | `from dbxdebug.paths import find_dosbox_x`, or `$DBXDEBUG_DOSBOX` |
+| Frame walking, if you had it | `from dbxdebug import walk_frames, steps_out` |
+| Finding the emulator binary | `from dbxdebug import find_dosbox_x`, or `$DBXDEBUG_DOSBOX` |
 | Nothing: this is new | `from dbxdebug.registry import list_sessions`; the `dbxdebug session` and `dbxdebug doctor` CLI |
 
-### The surface is not tidy, and this is worth knowing before you write imports
+### Where to import from
 
-`dbxdebug/__init__.py` exports the original client surface only. The newer
-modules -- the session, the registry, the addressing helpers, the frame
-walker -- are importable from their own modules and nowhere else. So the
-package's primary entry point is the one thing you cannot import from the
-package root:
+Everything a debugging script needs comes from the package root:
 
 ```python
->>> from dbxdebug import GDBClient, QMPClient, DOSVideoTools   # fine
->>> from dbxdebug import DosboxSession
-ImportError: cannot import name 'DosboxSession' from 'dbxdebug'
->>> from dbxdebug.session import DosboxSession                 # this is the way
+from dbxdebug import DosboxSession, GDBClient, QMPClient, DOSVideoTools, linear
 ```
 
-This is self-consistent (no newer module is exported, so there is no
-arbitrary line) but it is an odd shape, and it is an open question, not a
-settled convention: lokkju/dbxdebug#7. Import from the modules for now. If
-the re-exports land, module-level imports keep working, so nothing written
-today has to be rewritten.
+The rule is that every module declares its surface in `__all__` and the root
+re-exports the union of the library modules' `__all__`. The exceptions are
+`dbxdebug.cli`, `dbxdebug.registry` and `dbxdebug.doctor`, the `dbxdebug`
+command's own machinery, whose names say nothing unqualified:
+
+```python
+from dbxdebug.registry import list_sessions, reap
+from dbxdebug import doctor
+```
+
+Module-path imports work for everything, root or not, and the examples
+further down use them where naming the module makes the call clearer
+(`addressing.bp_addr`, `frames.steps_out`). Nothing you write either way
+has to be rewritten later.
+
+If `from dbxdebug import DosboxSession` raises `ImportError`, you are on a
+build from before lokkju/dbxdebug#7 landed; `from dbxdebug.session import
+DosboxSession` works there.
 
 ### The launcher itself
 
@@ -105,7 +111,7 @@ so only a SIGKILL of the owner can leave a stray emulator behind (which is
 what `dbxdebug session reap` is for).
 
 ```python
-from dbxdebug.session import DosboxSession
+from dbxdebug import DosboxSession
 
 with DosboxSession(mounts={"c": "/path/to/host/dir"}, autoexec=["c:"]) as session:
     session.qmp.type_text("PROG\r")
@@ -347,7 +353,8 @@ were two loops was the first item of lokkju/dbxdebug#7.
 | `key_down(key) -> dict` / `key_up(key) -> dict` | `key_down(key) -> None` / `key_up(key) -> None` | Same `input-send-event` payload |
 | `key_press(key, hold_time=0.1) -> dict` | `key_press(key, hold_time=0.05) -> None` | **Default hold time halved** |
 | `type_text(text, delay=0.1)` | `type_text(text, delay=0.05)` | **Default delay halved.** Unmapped characters are logged and skipped rather than silently skipped; `\r`, `\n`, `\t`, space and shifted punctuation map the same |
-| `input_send_event(events) -> dict` | -- | No raw passthrough. Use `key_down`/`key_up` |
+| `input_send_event(events) -> dict` | -- | No raw passthrough. Use `key_down`/`key_up`, or the mouse methods below |
+| -- | `mouse_move(dx, dy)`, `mouse_button(button, down)`, `mouse_click(button='left', hold_time=0.05)` | New. Relative motion only (the server ignores `abs`), and only `left`/`right`/`middle` -- `MOUSE_BUTTONS` lists them, and anything else raises `ValueError` rather than being accepted and dropped. **Motion has no effect headless**; buttons do. See `mouse_move`'s docstring |
 | `query_commands() -> list` | `query_commands() -> list[str]` | Same |
 | `query_status() -> dict` | `query_status() -> dict` | **Returns the `return` payload, not the envelope**: `resp["return"]["running"]` becomes `status["running"]` |
 | `stop()`, `cont()`, `debug_break_on_exec(enabled)` | Same names | Same unwrapping change as `query_status` |
@@ -449,22 +456,38 @@ gdb.take_pending_stops()          # [b'S05'] -- the stop, delivered once
 Note that a `Z0` breakpoint armed while free-running is inert and never was a
 trigger -- activation only happens on continue.
 
-**The queue is filled by the client's framing layer while it reads, not by the
-socket receiving anything.** Until you issue some GDB request, an unsolicited
-`S05` sits unread in the kernel buffer and `take_pending_stops()` returns
-empty. A poller written as "loop calling `take_pending_stops()` until it is
-non-empty" therefore spins forever on a stop that has genuinely happened:
+**The queue services itself** (was
+[#18](https://github.com/lokkju/dbxdebug/issues/18), fixed). Reading
+`pending_stops` or calling `take_pending_stops()` reads the socket first,
+without blocking, so asking the question also answers it:
 
 ```python
-gdb.take_pending_stops()          # () -- nothing has read the socket yet
-gdb.read_memory(0x400, 4)         # any request; the framing layer sees the S05
+qmp.debug_break_on_exec(True)
+# ... the break fires; no GDB request is issued at all ...
 gdb.take_pending_stops()          # (b'S05',)
 ```
 
-Give your poll loop a cheap read -- a few bytes of the BDA will do -- before
-taking the queue. `qmp.query_status()` on the separate QMP socket has no such
-ordering requirement and is the simpler signal when you are not otherwise
-talking GDB.
+Before that fix the queue filled only as a side effect of some OTHER request
+passing through the framing layer, so a poller written as "loop calling
+`take_pending_stops()` until it is non-empty" spun forever on a stop that had
+genuinely happened, and its caller concluded the breakpoint had never fired.
+A read interposed in the loop was the workaround; it is no longer needed.
+
+Better still, do not write the loop:
+
+```python
+stop = gdb.wait_for_stop(timeout=30.0)   # the payload, or None on timeout
+```
+
+`wait_for_stop` owns the poll and returns the oldest queued stop, removed
+from the queue. It does **not** resume anything -- it is for stops nobody
+asked for. It raises `GDBDesyncError` rather than spinning if the stub still
+owes a reply to a request already on the wire, because the socket cannot be
+polled in that state without stealing that request's own bytes; finish or
+abandon that exchange first (the next request drains an abandoned one).
+
+`qmp.query_status()` on the separate QMP socket is still a valid signal, and
+is the one to use when you are not otherwise talking GDB.
 
 **Trigger 2 -- a timed-out request.** The abandoned reply used to stay in the
 stream and be handed to the next request:
@@ -493,9 +516,10 @@ What a consumer should still do:
 * Do **not** add a read-retry loop. Two identical consecutive requests mask a
   one-packet lag perfectly, so retrying looks like it works whether or not the
   stream has shifted.
-* If you arm `debug_break_on_exec`, drain `gdb.take_pending_stops()` to learn
-  the CPU stopped -- after a read, per the ordering note above. Polling `qmp.query_status()` on the separate QMP socket
-  still works and is still the way to wait for it.
+* If you arm `debug_break_on_exec`, learn that the CPU stopped from
+  `gdb.wait_for_stop()`, or from `gdb.take_pending_stops()` in a loop of your
+  own -- both read the socket themselves now. Polling `qmp.query_status()` on
+  the separate QMP socket still works too.
 
 ### 5.3 One GDB client at a time (lokkju/dbxdebug#8, open)
 

{dbxdebug-0.4.0 → dbxdebug-0.5.0}/pyproject.toml

@@ -32,8 +32,13 @@ dbxdebug = "dbxdebug.cli:main"
 dev = [
     "pytest>=7.4.0",
     "pytest-cov>=4.1.0",
-    "ruff>=0.8.0",
-    "pyright>=1.1.0",
+    # These two floors match the `rev:` pins in .pre-commit-config.yaml on
+    # purpose, and are bumped with them. Each tool runs twice against this
+    # repo -- once as a commit hook, once as the resolved dev environment CI
+    # uses -- and a floor low enough to resolve behind the hook lets the two
+    # disagree about the same file (lokkju/dbxdebug#17).
+    "ruff>=0.14.9",
+    "pyright>=1.1.411",
     "pre-commit>=3.5.0",
 ]
 
@@ -66,7 +71,16 @@ target-version = "py311"
 # `ruff check .` from the root lints other branches' in-progress code and
 # reports their errors as this tree's. pyright already scopes itself via
 # `include`; ruff needs telling.
-extend-exclude = [".claude"]
+extend-exclude = [
+    ".claude",
+    # ruff formats Python inside Markdown code blocks, and it wants to
+    # restretch the aligned trailing comments in our docs samples. CI runs
+    # `ruff format --check src/ tests/` and the pre-commit hook is scoped to
+    # `types_or: [python, pyi]`, so neither ever saw this -- only a bare
+    # `ruff format --check .` did, which made the repo look broken to anyone
+    # running the obvious command. Excluded so all three agree.
+    "*.md",
+]
 
 [tool.ruff.lint]
 select = [

{dbxdebug-0.4.0 → dbxdebug-0.5.0}/skills/debug-dos-programs/SKILL.md

@@ -56,7 +56,7 @@ Point it at a specific build with `DBXDEBUG_DOSBOX=/path/to/dosbox-x`.
 Always as a context manager. Never hand-roll a `subprocess.Popen`.
 
 ```python
-from dbxdebug.session import DosboxSession   # NOT `from dbxdebug import ...`
+from dbxdebug import DosboxSession   # or dbxdebug.session; both work
 
 with DosboxSession(mounts={"c": host_dir}) as session:
     ...
@@ -244,11 +244,13 @@ So, verified behaviour:
 
 - The GDB connection **survives** the break. The read that follows is still
   answered with its own bytes.
-- Learn that the CPU stopped from **`gdb.take_pending_stops()`** — it returns
-  the queued stop replies and empties the queue — or by polling
-  **`qmp.query_status()["running"]`** on the separate QMP socket. Either
-  works; the QMP poll is what you want when you are waiting rather than
-  reacting.
+- Learn that the CPU stopped from **`gdb.wait_for_stop(timeout=...)`** — it
+  polls for you and returns the stop reply, or None if none arrives — or from
+  **`gdb.take_pending_stops()`**, which returns the queued stop replies and
+  empties the queue. Both read the socket themselves, so neither needs any
+  other GDB request to shake a stop loose (lokkju/dbxdebug#18, fixed).
+  Polling **`qmp.query_status()["running"]`** on the separate QMP socket works
+  too, and is what you want when you are not otherwise talking GDB.
 - A plain `Z0` breakpoint armed while free-running is **inert** and is not a
   trigger — activation only happens on continue. This is why the ordinary
   breakpoint recipe (`halt` → `set_breakpoint` → `continue_execution`) is