Fixes#71, #72, #73. Supersedes #74.
@TempAccountNull diagnosed all three bugs correctly. This keeps every
fix and the credit, but replaces the patch - it had a defect that would
have broken stepping - and adds one more bug found by backtesting
against a real kernel target.
## The three reported bugs
- **Named pipe / COM sessions always timed out** (#71). `kd` announces a
pipe or serial link with `Kernel Debugger connection established`, not
the KDNET `Connected to target ...`. Only the latter was matched, so
`open_kd_session` sat waiting for a banner that was never coming on a
target that had in fact attached.
- **`g` re-froze the target it had just released** (#72). Go-class
commands hand the CPU back and the debugger stops reading stdin, so the
marker protocol's `.echo` sat unread, the command hit its timeout, and
the cancel-on-timeout CTRL+BREAK halted the machine again.
- **Any command after `g` did the same** (#73), through the same path -
the session had no concept of "the target is running".
## Why #74 is not merged as-is
Its `_GO_COMMANDS` set includes `p`, `t`, `pa`, `ta`. Those are *step*
commands: they execute one instruction or line and come straight back to
the prompt. Treating them as fire-and-forget swallows their output,
returns `"Target resumed."` instead, and leaves the session believing
the target is running - so the next command fires a spurious CTRL+BREAK.
Stepping would have become unusable. The step family keeps the marker
round-trip here, with a test pinning it.
## The fourth bug, found by backtesting
`_resume_target` wrote `g` and returned immediately. Until `kd` reads
it, `kd` is still at its prompt with the resume unread - and a
CTRL+BREAK arriving in that window is answered by the prompt rather than
reaching the target. The break is silently lost and the caller then
waits out a full `wait_for_break` timeout on a machine nothing will
stop.
That is exactly the sequence a tool caller writes, because
`run_kd_command("g")` now returns instantly. Measured on the live KDNET
target:
| gap after `g` | result |
| :--- | :--- |
| 0.00s | **break lost** (every attempt) |
| 0.05s | landed in 0.04s |
| 0.25s / 1s / 2s | landed |
The resume is now probed with a marker the debugger can only answer from
a prompt. Silence means it stopped reading stdin - the target is away
and the resume can no longer swallow a break. An answer means the target
never left, which is a bonus fix: a `gu` that returns in microseconds,
or a breakpoint hit at once, now reports what it printed instead of
falsely claiming the target is running.
## Also in here
- `wait_for_break` - block until a target stops (bugcheck, breakpoint,
manual break) and return what it printed. Asks the debugger rather than
trusting a flag, so it is right about targets this server never resumed.
If the wait expires the target is left **running**.
- Compound forms: `bp nt!X; g` runs the breakpoint first and returns its
result, so a typo'd symbol surfaces as `Couldn't resolve error` rather
than a 300s wait for a break that can never come. A `;` inside a quoted
command string is left alone.
- Qualified forms `~0 g` / `~*g` are recognized.
- One operation at a time per session; closing a session ends a wait
parked on it.
## Verification
Against the real kernel target (Windows 11 26100, KDNET):
- `scenarios/kernel_resume_and_wait.yaml` - new, covers resume, auto
break-in, and the zero-gap break. **Verified to fail without the fix**
with exactly the lost-break symptom, and to pass with it.
- `scenarios/kernel_session.yaml` - still passes.
- Machine confirmed left running afterwards, with no breakpoints behind.
Hermetic and user-mode:
- 89 hermetic tests pass (was 29 on `main`).
- 10 `live` user-mode scenarios pass, including the new
`resume_and_wait.yaml` against a real `cdb.exe`.
- Coverage 91% under CI's conditions, against the 88% gate.
- `mkdocs build --strict` clean; `docs/reference/tools.md` documents the
resume semantics.
**One limitation worth stating:** #71 is the one fix I could not
exercise end to end - this box has a KDNET target, not a pipe one. It is
covered hermetically for both banner wordings, and I did capture `Kernel
Debugger connection established.` verbatim from real `kd` output during
a KDNET reconnect, so the string is genuine. That it appears *instead
of* the KDNET wording on a pipe transport rests on @TempAccountNull's
report and their verified before/after.
---------
Co-authored-by: TempAccountNull <TempAccountNull@users.noreply.github.com>
Closes#62. Closes#47.
Kernel debugging never worked: every remote connection was launched with -remote, which is user-mode only, so a -k target could never connect. Fixing it properly meant kd.exe and a tool surface that can tell the two engines apart.
Breaking: every *_windbg_* tool is renamed, and sessions are addressed by an opaque session_id instead of by dump path or connection string. See CHANGELOG.md.
## Summary
A user-focused pass over the MkDocs guide: close the operational gaps
and tighten every page so
each capability is discoverable as a goal the reader recognizes, and the
limits are stated.
(Supersedes #57, which GitHub auto-closed when its base branch
`test/e2e-framework` was deleted
on the merge of #56. This branch is rebased onto `main` and contains
only the docs changes.)
## New use-case pages
- **Debug from another machine** (`scenarios/http-service.md`) - run the
server over the
streamable-http transport on a Windows host and drive it from your
laptop or a shared
debugging host. Server-side paths, binding/firewall, and a clear
**no-authentication** warning.
- **Redact sensitive data** (`scenarios/redaction.md`) - scrub
secrets/PII from tool output with
a `--filter-script` before it reaches a cloud model. Real script, client
wiring, hook contract.
## Reworked pages
- **Triage** - "Capture crashes automatically" with WER `LocalDumps`
(the registry path behind
the no-directory `list_windbg_dumps` fallback).
- **Crash dump** - use the `dump-triage` prompt for a structured report.
- **Remote target** - attach-by-PID is unsupported (connect to a
`-server`).
- **Tools** - sessions are concurrent. **cli/clients** HTTP no-auth
note. **Index** scope note,
**getting-started** pointers, new **troubleshooting** entries for HTTP
and filter scripts, and
cross-links throughout.
## Verification
- `python -m mkdocs build --strict` - clean; all new links and anchors
resolve.
- `pwsh scripts/Format-Docs.ps1 -Check` - no em/en dashes, no emoji.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
Onboards a MkDocs (Material) documentation site, mirroring the
dap-dbgeng setup, and migrates the GitHub wiki into it (trimmed to the
essentials: getting started, use cases, and a lookup reference).
## What's included
**Site infrastructure**
- `mkdocs.yml` - Material theme, VS Code blue palette, light/dark
toggle, the same markdown extensions and nav structure as dap-dbgeng.
- `requirements-docs.txt` - pinned `mkdocs` / `mkdocs-material` /
`pymdown-extensions`.
- `docs/assets/` - `extra.css` (brand color + mermaid styling) and the
self-contained `mermaid.js` loader.
**Pipeline**
- `.github/workflows/pages.yml` - builds with `mkdocs build --strict`
and deploys to GitHub Pages on pushes to `main` that touch docs.
**Content (migrated + trimmed from the wiki)**
- `index.md`, `getting-started.md`
- Use cases: `scenarios/` - analyze a crash dump, debug a remote target,
triage multiple dumps
- Reference: `reference/` - command-line options, tools, client
configuration
- `troubleshooting.md`
**Agent / authoring setup**
- Migrated `AGENTS.md` -> `CLAUDE.md` (concise, dap-dbgeng style).
- Added `.claude/rules/markdown.md` and
`.claude/rules/documentation.md`, plus `scripts/Format-Docs.ps1` to
enforce the typography rules (plain hyphens, no emojis).
**Housekeeping**
- README documentation links now point at the new site.
- `.gitignore` ignores `/site/`.
## Verification
- `mkdocs build --strict` - clean, all internal links resolve.
- `scripts/Format-Docs.ps1 -Check` - passes repo-wide (also fixed a
stray dash + emoji in CHANGELOG).
## One manual step
GitHub Pages is not enabled on the repo yet. After merge, set **Settings
-> Pages -> Build and deployment -> Source = GitHub Actions** (one time)
so `pages.yml` can publish to `https://svnscha.github.io/mcp-windbg/`.
Happy to enable it via API if you'd prefer.
## Notes / decisions
- Use-case pages chosen to match the product: crash dump, remote target,
triage. The wiki's separate per-client install pages are consolidated
into `reference/clients.md`.
- The wiki repo (`mcp-windbg.wiki`) is left untouched; we can archive or
redirect it once this is live.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sven Scharmentke