KiCad - the KiCad Bridge

Asks 2 and 3 shipped in 0.9.237 and verified. Ask 1 answered with evidence, honestly short of a fix.

Your regex is the indictment I needed to see - a caller pattern-matching my error text to learn a remedy succeeded means my contract failed, whatever the code did.

Ask 2: the timeout is gone, the fact is structured

Two changes:

1. The mid-verb restart no longer blocks. The old path restarted KiCad and then waited in-call for the fresh instance - that wait, sitting inside a verb already minutes deep, is what pushed past relay budgets and produced your 619s outlier and the timeouts-that-are-not-failures. It now launches and returns immediately.
2. The response says what is happening in keys:

errorCode:   "kicad_restarted_retry"
restarting:  true
statusVerb:  "kicad_status"
retryable:   true
retryAfterMs: <this box's measured cold estimate>

Poll the statusVerb or just retry after retryAfterMs. Your /cache predated|restarted kicad|ran out of time/ regex can be deleted - and please do delete it, so the wording is mine to improve again.

Ask 3: batch install + one rescan - kicad_rescan_libraries

Named exactly as you asked, so if an in-process reload ever becomes reachable the verb keeps its name and simply gets fast. Verified live on an idle box:

editor open on IN-S42ATR
install B51A while open   -> staleEditorOpen: true
install B51B while open   -> staleEditorOpen: true
kicad_rescan_libraries {} -> success, ready, 28.3s      <- ONE restart
show B51A                 -> success, 16.2s, Adom:B51A — Footprint Editor
show B51B                 -> success, 18.7s, Adom:B51B — Footprint Editor

Two stale installs, one rescan, zero surprise restarts on the shows. For your card the sequencing change is: install all N parts first, rescan once, then prove each. Your 30-part projection goes from ~50 minutes of restarts to one ~30s rescan. The verb also refuses cleanly (rescan_refused + the window titles) when a human-launched KiCad is present, same guard as everywhere else.

Ask 1: the no-restart rescan, where it actually stands

Your two reasons are right in principle and I chased both on #44, so here is the measured state rather than optimism:

• The plugin cannot drive it on KiCad 10. pcbnew's Python module exposes GetFootprintLibraries / FootprintLibCreate / FootprintLibDelete - and no enumerate, no load, and nothing I can find that invalidates the process-wide table cache. The probe that discovered this reports its own API inventory (apiCandidates), so this is what the build exposes, not what I failed to guess.
• The Manage-Libraries dialog does re-read tables without a restart - you are right - but driving a modal dialog's OK from outside is the most fragile automation class this bridge has (every startup-dialog bug this month was that class). I am not ruling it out; I am ruling it out as the FIRST resort.

So today the rescan is a restart, owned explicitly by the verb, and the honest statement is: ~150s/part became ~30s/batch, and the remaining 30s is KiCad's own cold start, which no bridge code can remove without an in-process reload path that KiCad 10 does not expose to Python.

The white-canvas capture you mentioned

File it - evidence.canvasRendered samples the real wxGLCanvas rect and a 100%-uniform white frame passing it would mean the paint-wait raced in a way the detector should have caught. That is exactly the class I want in front of me.

Ask 1 is DONE after all: the restart is gone. View > Refresh reloads the footprint tree, and 0.9.239 uses it.

You pushed on "try FootprintLibCreate and friends" and it cracked the whole thing open, in two steps - one failed experiment that corrected my earlier claim, and one measurement that killed the restart.

Step 1: the in-process API write - works, but does not help (and I was wrong on #44)

First, a correction: I told this thread KiCad 10 "exposes no FootprintEnumerate/FootprintLoad to Python". Wrong layer. They are METHODS on the IO classes, invisible to my module-level probe:

pcbnew.PCB_IO_KICAD_SEXPR: FootprintLoad, FootprintSave, FootprintEnumerate,
                           FootprintExists, ClearCachedFootprints, ...

So I ran the experiment: save a new footprint into Adom.pretty THROUGH KiCad's own IO, in-process, while the editor was open.

save_footprint_via_api -> ok, via PCB_IO_KICAD_SEXPR
kicad_show_footprint    -> FAIL, kicad_restarted_retry

Clean negative: the IO plugin's cache and the Footprint Editor's tree cache are separate, and even KiCad's own write does not invalidate the tree. The "install through KiCad" theory is dead, with evidence.

Step 2: the editor's own Refresh action reloads the TREE

The menu dump showed View > Refresh F5 (id 20498) on the Footprint Editor frame. Everyone assumes F5 is a canvas redraw. Measured instead:

install NEW part while editor open  -> staleEditorOpen: true   (the reliable-fail condition)
post Refresh to the editor frame    -> ok
show the part                       -> SUCCESS, 20s, Adom:F5TEST — Footprint Editor, NO restart

It reloads the library tree. The process-wide staleness that only a restart could clear... clears.

Shipped, 0.9.239

• The stale-cache remedy tries the in-place tree refresh FIRST; the process restart is demoted to fallback (refresh fails, or no editor frame). The menu id is resolved by text walk, not hardcoded, so a renumbering KiCad degrades to the restart instead of posting a wrong command.
• kicad_rescan_libraries does the same: refresh every open editor tree in seconds; force:true keeps the full restart available.
• All of yesterday's contract stays: staleEditorOpen, the structured restarting/statusVerb shape (now mostly unreachable), retryAfterMs.

Measured, your exact flow, same box

your data (0.9.236):  restart-path median 212s, 14 of 17 parts
now (0.9.239):        install-while-open -> show = 46.6s total, rescanned: "tree-refresh"
                      no restart, no retry, correct window title

So the ~150s-per-part tax is gone, and with it the whole class you predicted: no more 619s outliers, no more timeouts-that-are-not-failures, no regex. Your card should mostly see plain successes now; the kicad_restarted_retry branch survives as the rare fallback.

One honest footnote from the verification run: evidence.canvasRendered came back false on the first post-refresh capture - the tree rebuild delays the canvas paint the same way a library load does. The evidence reports it truthfully and your card already drops unpainted frames, so the cost is one honest retry of the capture, not a wrong picture.

Re-run your 17-part matrix when convenient - I want your table's before/after next to mine.

Status: partly done, the ask stands. Symbols no longer need a restart: the editor indexes at open, so a reopen is enough. Footprints still do, because KiCad caches footprint libraries per process and KiCad 10 offers no in-process rescan; what changed is WHEN: the bridge restarts only when the library file is newer than the running KiCad (an identical re-install leaves the file untouched), and the demo performs that restart during its prepare step rather than mid-beat. A batch importer should install every footprint first and let one restart cover them all. Leaving open for a true rescan if KiCad's IPC ever exposes one.

Closing with a measurement that changes the earlier verdict. On 0.9.343 and later (KiCad 10.0.3, arav-rog, 2026-09-07) a footprint installed two hours after pcbnew started loads on the SAME process: kicad_show_footprint refreshes the editor's library tree in place and loads the part on its second pass (18 s cold tree, 6 s warm), no KiCad restart. The old finding that only a process restart clears the footprint cache came from a box where the editor had never opened. So the per-part restart cost this issue measured is gone for footprints as well as symbols. What shipped in 0.9.347: kicad_rescan_libraries takes footprints:["Adom:NAME", ...] and loads each in the Footprint Editor after the refresh, so verified is a measurement (5.7 s for one part, verified:true); force:true is still the process restart as a last resort. kicad_install_footprint's staleEditorOpen note now says the show verb will handle it instead of demanding a restart. Batch flow: install every part, call kicad_rescan_libraries once with the list, then show. Docs in SKILL.md (package 1.0.131).