fix(ipc): find KiCad's Windows endpoint in the pipe namespace

[mixelpixx]

Summary

NNG maps ipc:// to a named pipe on Windows, and a named pipe has no filesystem presence. Discovery probed the candidate path as a file, so is_adoptable answered "no" for every Windows install and detect_ipc_address could never succeed there.

The consequence was not a missing convenience. A Konnect launched by an MCP client — the shipped PCM package registered with a client, carrying no ipc_address and no KICAD_API_SOCKET — reported the transport unreachable with KiCad running and the API server enabled, so every hybrid tool took its direct-file fallback while KiCad held the board open. That is the one outcome attempt_ipc_write's gate exists to prevent, reached because discovery could not see a transport that was in fact reachable. Live-only tools refused outright.

Closes #529

Approach

The module already said what the fix was — "Inspecting the pipe … is the real answer and is left for a change that can be tested on Windows" — so this is that change, made on a Windows machine with KiCad 10.0.5.

• Look where the endpoint is. Windows resolves the candidate against the pipe namespace instead of the filesystem. FindFirstFileW over \\.\pipe lists bound names without opening any of them, so the metadata-only rule IPC socket auto-detection wedges KiCad's API server on Linux (no reply to any client until restart) #498 made non-negotiable still holds. std::fs::metadata would not have done: on Windows it opens a handle, and against KiCad's endpoint that consumes a server instance.
• No new candidates and no new dependencies. file_name() returns the bound name verbatim — drive letter and backslashes intact — which is exactly the candidate path, so the existing candidate list and the format_address output are unchanged. std::fs::read_dir does the enumeration; no windows-sys/winapi is added.
• Case-insensitive matching, because Windows paths are and the bound name is KiCad's spelling of the temp directory rather than ours.
• Unix is untouched, and a third arm keeps any other target compiling and adopting nothing.

The limit, stated rather than implied

The pipe namespace is machine-global and any local account may bind a name in it, so a squatter could be adopted. Unix answers that with an ownership check; the Windows equivalent needs the pipe's security descriptor, which means opening it. An explicitly configured ipc_address has always carried the same exposure, so the doc comment records this as the state of the art on the platform rather than implying a check that is not there. Happy to split it out as a follow-up if you want it pursued.

Branch and dependencies

Base branch: main at f0f5ad0.
Depends on: nothing. Overlap: none — crates/konnect-ipc/src/socket.rs plus three docs; no open PR touches them.
Series order: none — single PR, one commit.
Next PR to promote after this one: none in this chain.

Compatibility and safety

• Behaviour change, Windows only: tools that reported source: "file" with fallback_reason.kind: transport_unreachable now report source: "ipc" when KiCad is running with the API server enabled, and their edits go through KiCad instead of to the saved file. Live-only tools start working. get_installation_info reports the discovered endpoint instead of a null one. Recorded in docs/API_MIGRATIONS.md.
• No response field, argument, or tool changed shape. Nothing changes on Linux or macOS, or for any caller that set the address explicitly.
• Discovery still runs only at startup, so a server launched before KiCad stays unresolved for its lifetime — unchanged, and docs/TROUBLESHOOTING.md still says so.
• No tool added or removed; cargo xtask fix-doc-counts --check unchanged. Rollback: revert the one commit.

Validation

Run on commit f67fe06 (Windows 11, KiCad 10.0.5), exit codes captured directly:

cargo fmt --all -- --check                                        exit 0
cargo clippy --workspace --locked --all-targets -- -D warnings    exit 0
cargo test --workspace --locked --lib --tests                     exit 0 (1784 passed, 0 failed)
cargo test --workspace --locked --doc                             exit 0
cargo xtask fix-doc-counts --check                                unchanged
cargo test -p konnect-ipc --lib socket                            8 passed, 1 ignored (5 new)

• cargo fmt --all -- --check
• cargo test --workspace --locked --lib --tests
• cargo test --workspace --locked --doc
• cargo clippy --workspace --locked --all-targets -- -D warnings
• Real-KiCad check: the #[ignore] live test and the end-to-end run below, both against KiCad 10.0.5 on this machine. The Unix branch is unchanged and CI covers its matrix; the new code is #[cfg(windows)], so the Windows leg of CI is what exercises it there.

Reproduced first, with the released v0.11.1 PCM binary, no config file and no KICAD_* variables, pcbnew open on a board:

get_installation_info -> ipc: { configured: false, endpoint: null }
run_drc               -> OK        (kicad-cli resolves fine)
open_project          -> ipc_available: false, kicad_ui_running: false, open_board_count: 0

And the mechanism, measured directly with pcbnew running:

socket FILE  %TEMP%\kicad\api.sock                      exists: False
named PIPE   \\.\pipe\%TEMP%\kicad\api.sock             exists: True

Negative controls (each neutered, then restored):

guard neutered	tests that fail
Windows arm back to adopting nothing	detection_finds_a_live_pipe_without_connecting_to_it
candidate probed as a file again (the original defect)	detection_finds_a_live_pipe_without_connecting_to_it

Both neuters are caught by that one test, and deliberately so: it is the only one that goes through the production is_adoptable. The other four state what is bound rather than binding it, so they exercise is_adoptable_among directly and survive either neuter — which is what makes the live-pipe test load-bearing rather than decorative.

Live, on this branch — same binary invocation as the reproduction, still no config and no KICAD_*:

detect_ipc_address()  -> ipc://C:\Users\…\AppData\Local\Temp\kicad\api.sock
get_installation_info -> ipc: { configured: true, endpoint: ipc://…\kicad\api.sock }
open_project          -> ipc_available: true, kicad_ui_running: true, open_board_count: 1

Review checklist

• The diff is focused and contains no generated output, personal data, or unrelated cleanup.
• The branch includes current upstream/main, has no merge conflicts, and CI passed on this exact head.
• The branch was based on latest upstream/main, not a release tag.
• The PR shows only its unique commits and diff; dependencies and series position are explicit.
• Every review conversation is resolved.
• New names follow docs/NAMING_CONVENTIONS.md (PIPE_NAMESPACE, pipe_names, is_adoptable_among); no public renames.
• New behavior and failure paths have regression coverage, including the no-connect property against a real pipe server.
• No file mutations. No IPC mutations — discovery opens nothing.
• No tools added/removed; cargo xtask fix-doc-counts --check unchanged.

Maintainer merge state

• The PR has exactly one current status:* workflow label.
• status:ready-to-merge applies to this exact head SHA.
• All required checks and review conversations satisfy the main ruleset.
• Merge with gh pr merge N --merge after final verification.
• Terminal issue closure: Windows: KiCad IPC auto-detection can never succeed (nng ipc:// is a named pipe, not a file), so a default install has no live IPC #529. Next PR to promote: none.

🤖 Generated with Claude Code

[mixelpixx]

Filed the documented limit as #531, with a measured self-test rather than a theoretical note.

Binding KiCad's default pipe name before KiCad starts does capture Konnect's connection — but the squatter speaks no NNG, so the bounded Ping fails and the session falls back exactly as designed. What protects us is the protocol handshake, not an ownership check. A peer that implemented NNG would get through, and separately KiCad silently loses its API server when the name is already taken.

The cheapest real improvement that came out of it is not a security check at all: Konnect can already distinguish "no pipe bound" from "a pipe answered and was not KiCad", and today both render as the transport being unreachable. That is on #531 as the recommended first step. Nothing in this PR changes the trust model — an explicitly configured address always carried the same exposure — so I do not think it blocks the merge.

[neusse]

One release-classification correction is needed before this can enter the merge queue.

• Change the new docs/API_MIGRATIONS.md heading from minor release to patch release. This PR fixes Windows endpoint discovery and changes no tool, argument, or response shape; GOVERNANCE.md classifies that as a patch.

Everything else on exact head f67fe0666b8f800d7c3901365dd8f39fc1811745 matches #529: it is based on current main, the Windows namespace probe does not connect to the endpoint, the live Windows evidence covers default discovery, all ten required checks pass, and Closes #529 is correct. Please make that focused wording correction and let CI rerun on the new head.

[mixelpixx]

Corrected. The heading now reads (patch release), and that line is the whole diff from f67fe06. New exact head: 709267fc8eb4af4b05ef2d053a88d8bed96b2fd9, still one commit on f0f5ad0, all ten required checks green on it. Local doc guards (doc_tool_counts, asset_references, schema_migrations) and fix-doc-counts --check pass.

[neusse]

The patch-release correction resolves the earlier requested change. Spec and standards review found no remaining implementation defect at exact head 709267fc8eb4af4b05ef2d053a88d8bed96b2fd9.

This approval is for the reviewed diff only; the PR is not merge-ready until current main is incorporated as noted below.

[neusse]

Please rebase this exact head onto current main (39e006131cb7d5ba3f1d3c9f07021a507a9f7370) and rerun CI. No code change is requested: the earlier patch-release correction is accepted, and the focused implementation review passes.

This remains first in the least-resistance train: #530 -> #528 -> #523 -> #535. Once the refreshed head is green, it needs only the final exact-head check before merge.

[mixelpixx]

Rebased onto current main (39e006131cb7d5ba3f1d3c9f07021a507a9f7370). New exact head: 705a30d23a305031007dc278a1cb308aa760fbb4, one commit, no code change: git diff of the commit is byte-identical to 709267f's (verified with cmp on the two patches). The base moved only by #534's two documentation files, which this branch does not touch.

All ten required checks green on 705a30d. Local gate on the same head: fmt, clippy -D warnings, --lib --tests 1784 passed / 0 failed, --doc, fix-doc-counts --check unchanged.

Ready for the final exact-head check.