# re-winedbg — headless Windows-binary debugging from a Linux/macOS host

`re-winedbg` is the 10th MCP server in the RE-AI plugin. It drives
the `winedbg` debugger shim (a `gdbserver`-compatible debugger that
ships with Wine) plus a GDB client subprocess, so a Linux or macOS
host can attach to a Windows `.exe` and step through it under the
control of an AI agent. The server exposes 19 vendor-neutral tools
covering the full debug lifecycle: launch, attach, breakpoints
(symbol / RVA / absolute address), single-step, register and memory
read/write, module / thread / backtrace enumeration, and a
server-side trace-breakpoint helper that the v2.4 `re-vm-reverse`
skill uses for dynamic dispatcher sampling.

The server reuses the persistent GDB subprocess plumbing from the
`re-gdb` server (`re_gdb.gdb_mi.GDBSession`) for the gdb-client
side, then layers Wine-specific launch, WINEPREFIX lifecycle, and
gdbserver orchestration on top. Each session gets its own
`WINEPREFIX` under `~/.cache/re-ai-wine/<session-id>/`; the global
`~/.wine` is **never** touched.

## Tools

| Tool | Description |
|---|---|
| `check_winedbg` | Confirm `wine` + `winedbg` + `gdb` are installed (degraded-mode: returns WARN if missing). |
| `launch_under_wine` | Run a `.exe` under Wine (no debugger); returns the host-side PID. |
| `start_winedbg_gdbserver` | Spawn `winedbg --gdb <port> <exe>`; the binary is paused at entry. |
| `attach_winedbg_gdbserver` | Open a GDB client subprocess and `target remote` the gdbserver. |
| `set_breakpoint` | By symbol, `*<addr>`, or `<module>+0x<RVA>` (RVA resolved via the per-module base cache). |
| `remove_breakpoint` | By breakpoint id. |
| `continue_execution` | Resume; return the next stopped event. |
| `step_into` / `step_over` / `step_out` | Single-step primitives. |
| `read_registers` / `write_register` | GDB `info registers` / `set $reg = <val>`. |
| `read_memory` / `write_memory` | `x/...` / `set {<type>}<addr>`. |
| `info_modules` | `info sharedlibrary` parsed (drives the RVA cache). |
| `info_threads` | `info threads`. |
| `backtrace` | `bt <n>`. |
| `gef_trace_breakpoint` | Server-side `commands N; silent; printf ...; continue; end` with a hit counter. |
| `end_session` | Close GDB client, stop the gdbserver, `wineserver -k` the per-session prefix, kill the Wine process tree. |

## Environment variables

| Variable | Default | Used for |
|---|---|---|
| `WINEDBG_PATH` | `winedbg` | Path to the `winedbg` binary. |
| `WINE_PATH` | `wine` | Path to the `wine` binary. |
| `WINESERVER_PATH` | `wineserver` | Path to the `wineserver` binary. |
| `GDB_PATH` | `gdb` | Path to the `gdb` binary (read from `re_gdb.gdb_mi.get_gdb_path`). |
| `GEF_PATH` | `~/.gdb/gef.py` | GDB enhancement script (read from `re_gdb.gdb_mi.get_gdb_path`). |
| `RE_AI_SKIP_WINE` | unset | If `1`, `install.sh` skips the Wine install. |

## Install

`install.sh` (POSIX) installs `wine` + `winedbg` via `apt` / `dnf` /
`brew` on a best-effort basis. Set `RE_AI_SKIP_WINE=1` to opt out.
On Windows, `re-winedbg` is not useful (the user has the native
Windows debuggers; `winedbg` is a Linux/macOS compatibility shim)
and the `check_winedbg` tool returns a structured
`{status: "ERROR", error: "host_not_supported"}`.

```bash
# Linux (Debian / Ubuntu)
sudo apt-get install -y wine wine64 winedbg

# Linux (Fedora / RHEL)
sudo dnf install -y wine winedbg

# macOS
brew install --cask wine-stable
```

## Per-session WINEPREFIX

Every `start_winedbg_gdbserver` / `launch_under_wine` call creates a
fresh random `WINEPREFIX` under `~/.cache/re-ai-wine/<session-id>/`
(overridable via the `wine_prefix` arg). The global `~/.wine` is
*never* touched, and `end_session` will refuse to `wineserver -k`
any prefix that does not start with `~/.cache/re-ai-wine/`. This
guarantees we don't kill another Wine session the user has running.