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"}.

# 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.