KiCad - the KiCad Bridge

Fixes the loader shipped in 0.9.166/0.9.167. It guarded against double-starting with an environment variable, and Windows child processes INHERIT the parent environment: once any KiCad process had run the loader, every KiCad it spawned imported the file, compiled a .pyc and then started nothing, which looked exactly like the loader never running. The guard is now a module attribute on sys (per-process, cannot leak to children), the loader calls adom_bridge.start() directly instead of re-importing usercustomize (immune to module-cache subtleties), and it writes a log trail to %TEMP%/adom-kicad-plugin-loader.log so the next diagnosis takes minutes instead of hours.

Follow-up to 0.9.166: the plugin installer's already-current short-circuit compared only the payload and the .pth, so on a box that already had those it returned early and never wrote the new scripting/plugins loader - the whole point of that release. The check now includes every artifact the installer deploys.

Issue #31, the KiCad 10.0.5 plugin-bind regression, gets the loader that actually fires. Chain of evidence: usercustomize.py stopped running in 10.0.5 GUI processes (a 10.0.3 kicad.exe wrote its discovery breadcrumb, the 10.0.5 one never did); a .pth in the user-site did not help either; but a probe planted in KiCad's own scripting/plugins directory DID fire inside kicad.exe on 10.0.5, and reported site.USER_SITE already pointing at the bridge's deploy directory. So KiCad still imports its plugin directory at startup even though it no longer runs the usercustomize step. kicad_install_plugin now writes adom_bridge_plugin.py into %APPDATA%/kicad//scripting/plugins for every installed version; it simply imports the existing loader, so the payload and the discovery protocol are unchanged, and an env guard keeps it from starting twice.

Hotfix for a regression I introduced in 0.9.155-0.9.164 and John hit live: the bridge stopped answering entirely on his laptop. Root cause: the boot path ran ownership-ledger revival, off-screen healing, usability healing, session sanitising and the parking sweep BEFORE binding the server port. Those touch other processes' windows, and SetWindowLongPtr sends WM_STYLECHANGING/WM_STYLECHANGED cross-process - against a hung KiCad that SendMessage never returns, so the bridge deadlocked before it ever listened and every verb timed out (three orphaned bridge processes, no port bound). Two fixes: all desktop-window maintenance now runs on a daemon thread that starts after the server is listening, so the bridge always comes up no matter what state the desktop is in; and style changes first probe the target window with a 150ms SendMessageTimeout, skipping any window whose thread is not pumping messages.

John: 'why is it that when i try to click to see one of your kicad windows it doesn't work? is this cuz you position during launch and then forget to fix the window position afterwards?' Right on the mechanism, and there was a subtler gap than 0.9.160 closed. Suppression (WS_EX_NOACTIVATE, which also hides the taskbar button) is cleared by walking a set held in the bridge PROCESS. Any window suppressed by an earlier bridge - or by one that was killed mid-verb, which happens on every upgrade - is absent from that set in the new process, so nothing ever clears it and the window stays unclickable and taskbar-less no matter how many fixes ship afterwards. The bridge now heals by INSPECTION rather than memory: it reads the style off every KiCad window at boot and every 20 seconds while idle, clearing stale suppression, restoring the taskbar button, re-stamping the icon and pulling any window that is off-screen back to a reachable position. Windows genuinely mid-verb are left alone.

Two things. (1) Plugin bind, continued from 0.9.162: asking KiCad 10.0.5's own interpreter reveals ENABLE_USER_SITE is true but site.USER_SITE is the INTERPRETER DEFAULT (%APPDATA%/Python/Python311/site-packages), not the Documents path KiCad's bundled sitecustomize is supposed to install - so on 10.0.5 every file deployed to the Documents user-site was simply invisible to Python. The payload and the .pth loader now deploy to both locations; a guard keeps the loader inert in any non-KiCad interpreter. (2) The dashboard gains the per-part surface ladder from ab's web-control demo: one real wiki part with eight buttons (symbol, footprint, 3D chip, library, schematic, 2D board, 3D board, project) plus show-every-window. Each button fetches the part's files from its wiki page, installs them into the user's real KiCad, opens just that surface in the background and renders it back into the card. Progress streams over the live channel per card AND paints on the KiCad taskbar button's progress bar, so a long job is legible without watching the page.

The KiCad 10.0.5 plugin-bind regression (issue #31, open since 2026-08-16) is root-caused and fixed. The reverse-bridge plugin was loaded by usercustomize.py, which only runs if the interpreter performs site's execusercustomize() step. KiCad 10.0.5's GUI processes stopped doing that: a 10.0.3 kicad.exe wrote its discovery breadcrumb, the 10.0.5 one never did, so adom_bridge.start() was never called and kicad_bridge_status reported zero live instances while KiCad was plainly running. The loader now also ships as adom_bridge_boot.pth, whose import line is executed by site.addsitedir() - the call KiCad's own sitecustomize.py always makes to expose its 3rdparty packages - so the bridge binds regardless of the usercustomize step. It only starts inside real KiCad GUI processes, and re-importing the shared loader is a no-op thanks to Python's module cache. Dashboard fixes in the same release: the Plugin LED read a top-level alive field that has always lived under summary, so it could never turn green; it now also distinguishes KiCad-closed from KiCad-open-but-not-bound and says which is true. The Daily suite LED is maintainer-only and now hidden unless the dashboard runs with --dev.

John: 'it is really weird how you open kicad in the background'. He was right, and this is the mechanism. Parking exists for one job: stop a brand-new window flashing into the user's face during the second or two it takes to be created. But the park baseline (the set of windows considered pre-existing when a verb starts) subtracted every window the bridge had ever created, so a bridge-launched KiCad was permanently classified as 'new' and got yanked off-screen again on EVERY later verb - a status poll, a screenshot, anything - for the rest of its life. That is the flicker, the disappearing window, and the sliver at the bottom of the screen. The baseline now includes every window that already exists when a verb starts, bridge-created or not; only windows that appear mid-verb are parked, and they unpark as soon as the verb settles. The park clock is also stamped inside the park call itself, so the 12-second park watchdog covers every path rather than just the sweep.

John: 'why do i see no windows taskbar icons after you claim you launched'. Root cause, and it is documented Windows behavior the bridge was ignoring: WS_EX_NOACTIVATE - the style the bridge uses to stop KiCad windows stealing focus - also removes the window from the taskbar unless WS_EX_APPWINDOW is set alongside it. Every suppression now pairs the two, so a backgrounded window keeps a normal clickable taskbar button. Background means BEHIND, never INVISIBLE. Three supporting fixes found in the same investigation: (1) a leaked focus guard kept the parking sweep active indefinitely, leaving a launched window parked off-screen and NOACTIVATE'd for five hours - a guard watchdog now resets guards that overrun their own deadline, and a park watchdog releases any window parked longer than 12 seconds regardless of bridge state; (2) window icon probing used blocking SendMessageW, which hangs on a still-loading KiCad and can freeze the sweep and guard threads - now SendMessageTimeoutW with SMTO_ABORTIFHUNG; (3) unparking could restore a window to a position KiCad had never actually chosen (John got a 406x354 sliver under the taskbar), so unpark now verifies the window is genuinely reachable on screen, re-stamps its icon, and re-applies its Adom badge.

Two things. (1) Every verb response now carries bridgeVersion. It previously only reached /health, so no caller - the dashboard included - could ask which bridge code was actually running, and verifying a deploy meant reading a file on the box. (2) kicad-dashboard 2.0: full parity with fusion-dashboard. Live SSE channel (/events) with state, toast and click events; POST /api/action for launch, close, demo with streamed step screenshots, upgrade, install_plugin, overlay-badge setting and a wiki part tour; ui toast and ui click CLI so an AI can narrate over the page and make the page click its own controls; a _hint on every LED naming the verb that fixes it; a multi-box target picker; console read-back; and a dock.json so the dashboard launches from the Hydrogen dock.

The parking sweep now starts at bridge boot instead of arming on the first GUI verb. Found reviewing 0.9.157: the 60-second session-sanitize retry lives in the sweep's idle branch, so on a quiet boot (bridge up, no verbs yet) the scrub of bridge projects from KiCad's restore-on-launch list never ran, and neither did the between-verb parked-window defense.

Session sanitize, closing the last user-collision John found: KiCad restores system.open_projects at every PM launch, and the bridge left ITS demo project there, so each launch of the users own KiCad auto-opened the bridge demo and hit the project lock warning. Project-creating verbs now record their .kicad_pro in the ownership ledger, and the bridge scrubs owned (plus legacy adom-/in--demo) entries from open_projects at boot and from the sweep whenever no KiCad process is running (KiCad rewrites the file at exit, so edits only stick in that window). file_history is left alone.

Geometry-poison prevention, closing the loop John predicted: a window closed while parked off-screen makes KiCad persist the off-screen position, so the next NORMAL launch opens invisibly. Three defenses: the dispatcher unparks everything before any close verb; atexit unparks on bridge shutdown; and boot heals any KiCad window stranded at parking coordinates (left <= -20000) by moving it to a sane on-screen spot without activation, which repairs even crash-poisoned geometry on windows the user relaunched. The kicad-bridge-background dev skill now documents the full ownership contract, the shell-click intent rule, and the taskbar identity lessons.

Emergency ownership fix, caught live when John launched his own KiCad: the focus sentinel bounced his taskbar launches 8 times (a taskbar click leaves the cursor over the shell, not the raised window, so click-on-window intent detection missed it) and 0.9.154's boot pass badged every enumerated window. New contract: ownership is decided by process - every kicad-family pid the bridge spawns (children included, via parent-chain walk) is recorded in a persisted ledger (%USERPROFILE%/.adom/kicad-bridge-owned.json); the sentinel, event hook, parking sweep, badges, and identity stamps act ONLY on bridge-owned windows. A KiCad the user launches is in no spawned tree and is never parked, bounced, badged, or stamped. Taskbar/Start/desktop clicks now count as user intent for any KiCad raise. Two instances coexist: the bridge drives its own projects in its own processes alongside the user's.

Taskbar identity done right, stealing two paid-for lessons. (1) pup/fusion's: in-bridge ITaskbarList3::SetOverlayIcon is in-process-only, so badges now go through AD-core desktop_taskbar (via the fusion-bridge ad_client, ported verbatim) with fusion's exact 32px badge asset, matched size. (2) New one: eeschema.exe and pcbnew.exe buttons showed blank white documents because the shell's per-exe icon cache was poisoned during the pre-0.9.151 parking era; the bridge now stamps those windows with per-exe AUMIDs (desktop_set_window_identity) whose iconPath is a real .ico extracted from the exe, bypassing the poisoned cache without touching Explorer. Applied on window creation, on setting flips, and 5s after boot for windows that survived a bridge restart.

Overlay badge fix: KiCad windows outlive a bridge restart but the bridge's window-tracking set does not, so the Adom taskbar overlay vanished after every upgrade. The bridge now re-stamps ALL live KiCad windows 5s after boot and on every overlayBadges setting flip (enumeration union tracked set). Also: the container-side dashboard/ directory is no longer shipped in the runtime zip.

Adom overlay badges, John's design after pup's: every bridge-created KiCad window's taskbar button gets the Adom favicon stamped as an overlay (ITaskbarList3::SetOverlayIcon), so the user sees at a glance which windows Adom is driving. Gated by the new overlayBadges setting (default on) in kicad_get_settings/kicad_set_settings, which persist per box and apply live (flipping the setting stamps/clears badges on existing windows). These settings verbs are the backend for the upcoming kicad dashboard (fusion-dashboard parity).

Taskbar icon repair: minimize-first parking freezes a window into the taskbar before KiCad assigns its window icon (wx sets it a beat after frame creation), leaving blank document buttons. The parking path now checks WM_GETICON / class icons and, when absent, stamps the window with its own executable's icon (ExtractIconEx, cached per exe) before minimizing.

Bridge-created windows are now parked by MINIMIZING without activation from their first sighting: positional off-screen parking lost a visible-flicker fight against eeschema's load-phase geometry reassertion (and hwnd churn reset any escalation threshold). Minimized windows are invisible instantly, wx never un-minimizes itself, the taskbar button works with restore-to-maximized preserved, and captures restore off-screen just for the shot. Unparking places non-maximized windows at their true coordinates bottom-z; ex-maximized ones stay in the taskbar.

Park-fight escalation: eeschema reasserts its saved geometry every ~120ms during load, turning positional off-screen parking into visible flicker. A window that fights the park 4 times is now minimized WITHOUT activation (wx never un-minimizes itself; the taskbar button keeps working, with restore-to-maximized preserved). The screenshot path restores park-minimized windows off-screen, captures, and leaves the sweep in charge - so kicad_state and stepShot evidence keep working.