KiCad - the KiCad Bridge

Correcting my own report: the premise was wrong, and it now passes

Two things in the original are wrong, and one investigation step of mine was wrong too. Recording all of it because the wrong details are the kind that send someone down the same dead end.

1. "eeschema never launches" is not a symptom. On KiCad 10 the Symbol Editor is hosted INSIDE kicad.exe, not in a separate eeschema.exe. Proven by posting the menu command by hand and watching the process list:

posted WM_COMMAND 20011 to the project manager
after: 0 eeschema
  kicad pid=47928 title=[no symbol loaded] - Symbol Editor

Same process, new frame. So "no eeschema appeared" says nothing at all, and I built the report's headline on it.

2. The menu path is fine. Dumping the project manager's menu shows id=20011 "Symbol Editor" state=0 - the exact id the bridge sends, enabled, not greyed. And posting it by hand opens the editor. So neither the id nor the command is the problem.

3. My "the bridge is blind to KiCad windows" step was a PARSING ERROR of mine, and I nearly published it as the root cause. I read kicad_state's window list from a kicadState key that does not exist, got an empty list, and concluded the bridge could not see any window. Read correctly, the bridge sees all five:

hwnd 531874 | 'Adom:CR0603-FX-5601ELF — Symbol Editor'
hwnd 7738018 | 'Adom:nRF52840-CKAA — Footprint Editor'
... plus PCB Editor, 3D Viewer, project manager

4. It passes now. With an editor open:

kicad_show_symbol {AdomDemo_R, Adom} -> success, 9.6s
window: Adom:AdomDemo_R — Symbol Editor, canvasRendered: true

What is actually established: a symbol_editor_not_open failure happens when no Symbol Editor frame exists at that moment, and the 30s Phase-1 wait did not produce one. What I have NOT established is why the bridge's WM_COMMAND did not bring one up when a hand-posted identical command did. That is the open question, and it is narrower than the title of this issue.

Confound worth naming: the box I was testing on is the maintainer's daily laptop and he was USING KiCad in it while I probed - the Symbol Editor's hwnd changed three times (925862, 725748, 531874) and its loaded part changed to one I never opened. Some of my "no editor" observations were probably his editor being closed and reopened underneath me. That makes this a poor test bed for a race, and I should have noticed sooner.

Kept from the original, because it is real and fixed (0.9.204): the failure originally reported as library_cache_stale - "the symbol exists on disk but your editor's index predates it" - was a confident false diagnosis with no editor open at all. The check only asked whether the symbol was on disk. It now requires a live editor with a readable title before saying anything about that editor's index.

Retitling in spirit: the bug is "cold open sometimes does not produce a Symbol Editor frame within 30s", not anything about eeschema. Next step is instrumenting the Phase-1 post itself (which hwnd, whether the post returned true, what the manager's title was at that instant) on a box nobody is using.

Not reproducible on an idle machine. Closing, with the real cause named.

I reproduced the exact failing state on a box nobody was touching, and it passes every time.

Test 1 - fully cold, no KiCad process at all:

kicad_show_symbol {IN-S42ATR, Adom} -> success, 63.0s
window: Adom:IN-S42ATR — Symbol Editor, canvasRendered: true

Test 2 - the precise state this issue was filed about: project manager running, Symbol Editor closed by WM_CLOSE, nothing else touched:

kicad_show_symbol {IN-S42ATR, Adom} -> success, 56.7s
window: Adom:IN-S42ATR — Symbol Editor

So the cold open is not broken, and neither is the reopen after a close.

What was actually happening. Every failure I recorded was on a laptop whose owner was USING KiCad while I probed it. The evidence was in front of me the whole time and I read past it: the Symbol Editor's hwnd changed three times during my session (925862 -> 725748 -> 531874), and its loaded part became Adom:CR0603-FX-5601ELF, a symbol I never opened. That was a human working, not a race in the bridge.

KiCad is single-instance. While a person is driving it, it does not service our menu command promptly, so a 30s wait expires and the bridge reports a window that never appeared. Correct observation, wrong conclusion - the machine was busy, not broken.

Shipped anyway, 0.9.206, because the old message is what sent me down this path. A bare "Symbol Editor did not appear within 30s" implies a defect. It now checks how recently a human touched the machine and says so:

errorCode: symbol_editor_did_not_open
"KiCad accepted the Symbol Editor command but no editor window appeared within 30s.
 A human was active on this machine 12s ago, which is the most likely reason: KiCad is
 single-instance, and while someone is driving it, it does not service our menu command
 promptly."
userIdleSeconds: 12.0
hint: "...succeeds on a machine nobody is touching (measured: 63s cold, 57s with the
 project manager already running). If it repeats on an IDLE box, that is a real bug."

That turns an opaque timeout into a testable claim, and it gives the next person the two numbers to compare against.

Also worth stating as a general rule, since it cost me an afternoon: a machine someone is actively using is not a test bed. Concurrent human use of a single-instance app produces symptoms indistinguishable from a race, and I burned real time chasing one. Automated verification belongs on an idle box; the user's daily machine is for showing them the result.

Kept from this issue and genuinely fixed (0.9.204): the false library_cache_stale diagnosis, which claimed a stale library index for an editor that did not exist. That check now requires a live editor with a readable title before it says anything about that editor's index.

Reopening is one line of evidence away: a symbol_editor_did_not_open with a high userIdleSeconds means nobody was touching the box, and that is a real bug.