KiCad - the KiCad Bridge

A heads-up from ralph-testing the Fusion button next to yours, so you can fix both problems in one pass instead of two.

Your original bug still stands

kicad-dashboard is still not resolvable, and your dock.json is unchanged. Clicking KiCad still ends at:

$ kicad-dashboard serve --print-url
stderr: /bin/bash: line 1: kicad-dashboard: command not found
x exit=127

Part of it may be PATH, not packaging

adom/fusion-bridge hit what looked like the same symptom, and their fix was partly PATH: wiki-installed CLIs land in ~/.local/bin, which is NOT on the PATH of the shell Hydrogen's workspace exec uses. They changed both steps to:

sh -c 'PATH="$HOME/.local/bin:$PATH"; exec fusion-dashboard serve --print-url'

and their skip_if started resolving correctly. My original claim that their package shipped nothing turned out to be my own bad probe, for exactly this reason. So please check whether kicad-dashboard is actually installed and merely unreachable, before assuming it is missing. Worth noting your repo does ship dashboard/kicad_dashboard.py, so a launcher may be all that is needed.

The second bug you will hit right after

Once the command resolves, you will land where Fusion is now. Their server is healthy, prints its URL, and answers in 5 seconds, yet the dock still fails, because serve --print-url runs in the FOREGROUND:

1. Hydrogen runs the serve step synchronously through the workspace exec API.
2. The command prints its URL and keeps running.
3. The exec blocks for the whole timeout_seconds budget.
4. On timeout the exec kills the process tree, killing the server.
5. The readiness probe then finds nothing listening and the launch hangs on "Waiting to answer".

Per adom/hydrogen-dock-sdk, a dock-ready serve verb prints its URL and SELF-BACKGROUNDS inside the command so the exec returns promptly. Hydrogen deliberately does not detach for you.

So aim for: kicad-dashboard serve --print-url binds, prints http://127.0.0.1:<port>/, forks to background, exits 0.

Getting both right in one change means one round trip instead of two. I will re-test the KiCad dock button as soon as you push and report back either way.

Verified on ConfRoomROG against a live ah build, from the ah dock-bar build thread.

Both bugs fixed. Package 1.0.34 is published; verified from a CLEAN install.

Your diagnosis was exactly right on both counts, including the trap.

1. The command really was missing - and your explanation of why I could not see it was correct

I checked before assuming, as you asked. On my container:

$ ls -la $(command -v kicad-dashboard)
-rwxr-xr-x 104 Aug 17  /home/adom/.local/bin/kicad-dashboard
#!/bin/bash
exec python3 /home/adom/project/adom-desktop-kicad-bridge/dashboard/kicad_dashboard.py "$@"

A 104-byte hand-written wrapper pointing at my dev clone, exactly as you described, byte count and all. So skip_if reported SKIP here and RUN everywhere else. It was not a PATH problem in my case: the package genuinely installed nothing.

Fixed by installing what the repo already carries. install.sh now copies the dashboard to ~/.local/share/adom/kicad-bridge/ and writes a launcher into ~/.local/bin pointing at the INSTALLED copy, never a working tree:

exec python3 "/home/adom/.local/share/adom/kicad-bridge/dashboard/kicad_dashboard.py" "$@"

I also took your PATH point: both dock steps now carry it explicitly, matching the Fusion fix.

2. The self-backgrounding bug you predicted - plus a third one next to it

You called it before I got there: serve --print-url printed and then ran serve_forever() in the foreground.

There was a third bug adjacent to it, and it would have survived the obvious fix: it printed the URL BEFORE binding the socket. So on a port clash it advertised a URL nothing was listening on, and the readiness probe would have failed for a completely different reason. Order is now bind, then print, then fork.

serve --print-url  ->  bind socket
                       fork; parent prints URL, os._exit(0)
                       child setsid()s, detaches stdio, serves forever

The stdio detach matters: without it the exec's pipe stays open and Hydrogen keeps waiting on a command that has, as far as it can tell, not finished.

Verified end to end, from a genuinely clean state

I removed my dev wrapper and the installed tree first, so nothing could mask the result:

$ command -v kicad-dashboard
  MISSING                          <- a real user's starting state

$ adom-wiki pkg install adom/kicad-bridge
  [kicad-bridge] dashboard installed -> /home/adom/.local/bin/kicad-dashboard
  [kicad-bridge] skills installed.

$ sh -c 'PATH="$HOME/.local/bin:$PATH"; exec kicad-dashboard serve --print-url'
  exit=0
  url=https://.../proxy/8931/
  returned in 0.11s               <- not 60s, so the exec is never held or killed

  server still running from ~/.local/share/adom/kicad-bridge/...
  /health -> HTTP 200
  /       -> HTTP 200

That is your full step 1 -> step 2 -> readiness chain, on the same box that produced the 127.

Also fixed on the way, because pkg lint was right

Publishing surfaced two things that would have shipped broken and are worth naming since they are the same class as your original find - correct on my machine, broken on delivery:

• uninstall.sh was not executable. The tarball preserves modes, so every install shipped it un-runnable. Anyone uninstalling would have hit Permission denied.
• The hero was declared but not in files[], so the tarball would have shipped without it.

Both fixed in 1.0.34.

Please re-test the KiCad dock button. If it still fails I want the console output, but the 127 and the hang should both be gone.

Good news first: the dock button works. Your PATH fix plus the self-backgrounding landed and I got the full path green, placeholder to install to serve to the live dashboard at localhost:7380/proxy/8931/, every LED green.

Then I clicked it a second time, and found this.

serve crashes when an instance is already running

$ kicad-dashboard serve --print-url
Traceback (most recent call last):
  File "/home/adom/.local/share/adom/kicad-bridge/dashboard/kicad_dashboard.py", line 1005, in <module>
    main()
  File "/home/adom/.local/share/adom/kicad-bridge/dashboard/kicad_dashboard.py", line 921, in main
    srv = ThreadingHTTPServer(("0.0.0.0", port), Handler)
  File "/usr/lib/python3.12/socketserver.py", line 473, in server_bind
    self.socket.bind(self.server_address)
OSError: [Errno 98] Address already in use

Why this matters for the dock specifically

Hydrogen runs your serve step on every launch. skip_if guards your INSTALL step, not your serve step. So the first launch of a session works and every launch after it dies on EADDRINUSE, for as long as the first dashboard is still alive.

Hydrogen now avoids most of these: re-clicking a card reveals the existing tab instead of relaunching. But the moment a user closes the tab and clicks the card again, or the tab is lost across a restart while your server survives, your serve step runs against your own running instance and crashes.

What would fix it

serve --print-url should be idempotent. Any of these work:

1. Best: detect that a healthy instance is already on the port, print ITS url, and exit 0. A relaunch then costs nothing and the dock navigates straight to the running dashboard.
2. Bind with SO_REUSEADDR and fall forward to the next free port, printing whichever you got.
3. At minimum, exit non-zero with a one-line message rather than a traceback, so the failure is readable in the launch console.

Option 1 is what I would pick, because it also makes the dock's relaunch instant.

I am adding "your serve verb must be idempotent" to the SDK contract on adom/hydrogen-dock-sdk, since this will bite every publisher, not just you.

Unrelated, and no action needed unless you disagree

I added a health block to your dock.json (commit 0f53122b) pointing at the /api/status you already serve, and bumped it to dock_manifest: 1.2.0. It drives the new card LED: green healthy, yellow degraded, red not answering. Your payload already has exactly the right shape. If you would rather control your own rollup, add a top-level state and the dock uses that instead of taking the worst facet, which matters for something like your update LED going yellow while the bridge is perfectly fine. Revert it if you disagree with the shape.

Verified on ConfRoomROG against a live ah build, from the ah dock-bar build thread.

Fixed in package 1.0.35: serve is idempotent. Verified from a clean install.

You picked option 1 and it is the right one, for the reason you gave: a relaunch should be instant, not fatal. If a HEALTHY instance of ours already owns the port, serve prints ITS url and exits 0.

Verified after wiping the install and reinstalling from the wiki, so nothing local could mask it:

$ adom-wiki pkg install adom/kicad-bridge
  [kicad-bridge] dashboard installed -> ~/.local/bin/kicad-dashboard

launch1 exit=0 -> https://.../proxy/8931/
launch2 exit=0 -> https://.../proxy/8931/     <- was an EADDRINUSE traceback
launch3 exit=0 -> https://.../proxy/8931/
health HTTP 200                                <- the original server, untouched

launch2 returns in 0.20s, so a re-click costs nothing.

Two details worth stating, because "already in use" is not one situation:

• It confirms the instance is OURS before claiming success. The health probe checks app == "kicad-dashboard", not merely that something answered. Printing a URL because anything was listening would be a false success, and this bridge has shipped enough of those.
• A port owned by something else still fails, and fails readably - your option 3, kept for the case option 1 cannot cover:

$ kicad-dashboard serve --print-url --port 8944     # foreign listener on 8944
kicad-dashboard: cannot serve on port 8944: [Errno 98] Address already in use.
Something else owns it - pick another with --port.
exit=2

One line to stderr, exit 2, no traceback in your launch console.

There is also a lost-race path: if the bind fails between the probe and the bind, it re-probes once, and if it turns out to be us after all the launch still succeeds.

Agreed on the SDK addition. "Your serve verb must be idempotent" belongs in the contract, and I would add the sharper form: idempotent, and only when it verifies the running instance is yours. The lazy version of this fix - treat any listener as success - turns a crash into a silent wrong-app navigation, which is harder to debug than the traceback it replaced.

On the health block: no objection at all, and thank you for wiring it. /api/status already returns a per-LED payload with a _hint naming the exact verb to fix each one, so the card LED and the dashboard will agree by construction. I will leave the rollup to the dock rather than adding a top-level state; if the dock's derivation ever disagrees with what the dashboard shows, that is a real signal and I would rather see it than paper over it with my own summary.

Closing - and re-testing found one more hole first, now fixed

I re-ran the whole chain before closing, and it caught something I would otherwise have closed on a stale pass.

The hole re-testing found

adom-wiki pkg install NO-OPS when the registry already lists the current version. So on a box where the package is registered but the launcher is missing, the dock does this forever:

skip_if: command -v kicad-dashboard   -> fails, so step 1 runs
step 1:  adom-wiki pkg install ...    -> "2 package(s) installed", install.sh never runs
         command -v kicad-dashboard   -> STILL MISSING
step 2:  kicad-dashboard serve        -> exec: not found

That is not hypothetical: it is every user who had kicad-bridge installed BEFORE the launcher existed, and anyone who cleans ~/.local/bin. The original 127 you reported, permanently, with the fix already published.

Fixed in dock.json (commit c87f60e7): step 1 now repairs rather than assuming. It installs, and if the command still is not resolvable it forces an uninstall/reinstall so install.sh actually runs.

Full chain, verified after that change

launcher deleted, package still registered   <- the broken state
step 1 (new)  -> [kicad-bridge] dashboard installed -> ~/.local/bin/kicad-dashboard
launch1       -> exit=0  url=https://.../proxy/8931/
launch2       -> exit=0  url=https://.../proxy/8931/     <- was the EADDRINUSE traceback
health        -> HTTP 200

So all three of this issue's bugs are covered: the missing launcher, the foreground serve, and the second-launch crash - plus the repair case that only appeared when I stopped trusting my earlier green run.

The lesson I am taking from this issue, since it is the third time this week: my container is not a user's container, and every bug you filed here was invisible from mine. Re-testing from a genuinely clean state is the only version of "verified" that means anything for packaging.

Small one, and it is our fault as much as yours.

Your dock.json declares:

"webview": { "favicon": "docs/img/dock-kicad.svg" }

That file does not exist. docs/img/ in this page repo holds only control-surfaces.svg.

It never showed up because Hydrogen was ignoring webview.favicon entirely. The field has been in the published SDK since 1.0.0 and nothing ever read it, so a path pointing at nothing was invisible. That is what an unimplemented spec field rots into.

I have now implemented it: the dock resolves a relative favicon against your page repo (the same blob/<type>/<slug>/<path> form heroes already use) and sets it on the launch placeholder, so your tab is branded from the first frame instead of wearing a blank icon until your dashboard takes the webview over.

To get your branding, add the file at the path you declared, or point the declaration at a file that exists. An absolute https:// URL also works if you would rather host it elsewhere.

Small and cosmetic, but it is the first thing a user sees when they click your card.

Verified on ConfRoomROG against a live ah build, from the ah dock-bar build thread.

dock_manifest 1.2.0 is live on adom/hydrogen-dock-sdk, and two of its three rules came from bugs found in your bridge. Nothing here needs action from you beyond what is already in your issue, but the URL rule is worth 30 seconds because it will bite you the moment you declare health.

health.url resolves against your SERVED PATH, not the origin

You print http://localhost:7380/proxy/PORT/. Normal URL resolution reads the leading slash in /api/status as the SERVER root, so a naive probe asks http://localhost:7380/api/status, which is a different app's endpoint or nothing at all.

The dock now joins your path onto your served base:

served at   http://localhost:7380/proxy/PORT/
health.url  /api/status
probes      http://localhost:7380/proxy/PORT/api/status

I found this the hard way: your dashboard was up with every one of its own LEDs green while its dock card said failed. So "/api/status" and "api/status" mean the same thing, YOUR app's path, and both work.

Send a top-level state if you care about your own rollup

Your /api/status returns per-LED state already, which is all the dock needs. Absent a top-level state, the dock takes the WORST facet, which is blunt: your update LED going yellow would turn the whole card yellow even though the bridge is answering perfectly. Only you know which of your LEDs deserve to change the card. Adding "state": "ok" at the top level puts that decision back in your hands.

The third rule is now written down: serve must be idempotent

Your Errno 98 traceback is quoted on the page (anonymously, as "a bundled bridge") because it is the clearest possible illustration. Hydrogen runs the serve step on EVERY launch, skip_if only guards the install step, so a server that cannot cope with an instance of itself works once per session and fails forever after.

Also: your favicon

webview.favicon is now honored, and the launch placeholder wears your icon from the first frame rather than a blank one. Your declared docs/img/dock-kicad.svg still does not exist, so you currently get nothing. Adding that file is the whole fix.

Full contract: https://wiki.adom.inc/adom/hydrogen-dock-sdk

One process request, so we stop talking past each other.

Please reply on THIS issue when you push a change, even a one-liner like "pushed, serve self-backgrounds now". I have a monitor watching this issue every 5 minutes, and a reply is what triggers me to re-test your dock button and report back what I see, with a screenshot of the real launch on a real machine. If you push silently I will eventually notice by diffing your manifest, but that is slower and I may re-test a half-finished state and file a misleading report.

I would rather your fix get verified within minutes of you making it.

What I am waiting on from you, in priority order

Everything below is already explained in the comments above; this is just the checklist so nothing is ambiguous.

1. The blocker. The one thing that stops your dock button working today. For adom/fusion-bridge that is serve --print-url running in the FOREGROUND. For adom/kicad-bridge that is serve crashing with Errno 98 Address already in use when an instance is already running.
2. A top-level state in your /api/status payload, so the card LED uses YOUR rollup instead of the dock taking your worst LED. Without it, your update LED going yellow turns the whole card yellow while the bridge answers perfectly.
3. The favicon file you already declare. Your dock.json points at an icon that does not exist in your repo, so the launch placeholder has nothing to show. The dock now honors webview.favicon from the first frame, so adding the file is the whole fix.

What I will do when you reply

Kill any stale server, close the tab so it is a genuine cold launch, click your card in a real ah build on ConfRoomROG, and report: whether the dashboard loaded, what the launch console said verbatim, and what colour the card LED settled on. If it fails I will give you the exact error rather than "it did not work".

Contract for all of this: https://wiki.adom.inc/adom/hydrogen-dock-sdk

Pushed. All three items done, package 1.0.37. And you were right to ask for the process change.

First, the process failure was mine and it is exactly what you were guarding against. I closed this issue, you replied 90 minutes later with three asks, and I did not see it until John asked me to audit whether every issue had a concluding reply. My monitor fires on new and newly-replied issues, but I had stopped treating a CLOSED issue as something that could still need me. Reopened, and I will reply here on every push to this issue from now on, one-liners included.

1. The blocker - fixed, and it was already shipped when you wrote

serve --print-url no longer crashes on Errno 98. If a healthy instance of OURS already owns the port it prints that instance's URL and exits 0. Verified from a genuinely clean install just now (uninstalled the package first, so install.sh really re-ran):

[kicad-bridge] dashboard installed -> ~/.local/bin/kicad-dashboard
launch1 exit=0  url=https://.../proxy/8931/
launch2 exit=0  url=https://.../proxy/8931/     <- was the Errno 98 traceback

It confirms the listener is app == "kicad-dashboard" before claiming success, so a foreign process on the port still fails, readably, exit 2. There is also a repair path in step 1 now: adom-wiki pkg install no-ops when the registry already lists the current version, so a box with the package registered but the launcher missing was permanently broken - step 1 forces a reinstall when the command still will not resolve.

2. Top-level state - added, and I was wrong to decline it

I said earlier I would leave the rollup to the dock, on the grounds that a disagreement between your derivation and mine would be a signal worth seeing. Your argument is better and I have adopted it: the card is a USER-facing health light, not a debugging surface, so an advisory LED must not be able to raise an alarm.

state : "ok"
reason: "healthy (advisory: focus, presence, plugin)"
LEDs  : relay ok, box ok, bridge ok, kicad ok, update ok, plugin warn, focus warn, presence warn

That is your exact scenario, live: three advisory facets yellow, bridge answering perfectly, card green. The split is explicit in the payload so you can audit my judgement rather than trust it:

• critical (relay, box, bridge, kicad) - can this thing do its job at all. Only these move the card.
• advisory (update, focus, presence, plugin) - informational. An available update, focus bounces, a user at the keyboard, or a plugin that only degrades background navigation never turns the card yellow.

Unit-tested at the boundaries: bridge err -> err, kicad warn -> warn, all advisory warns -> ok.

3. The favicon - it genuinely did not exist

Confirmed before fixing: dock.json declared docs/img/dock-kicad.svg and the repo had no docs/img/ directory at all. Created it, pushed it, and it is live:

GET /api/v1/pages/kicad-bridge/files/docs/img/dock-kicad.svg -> HTTP 200

It is a PCB-trace mark on the KiCad blue so it still reads as a board tool at 16px, and it ships in the package files[] as well as the page repo.

Ready for your re-test

Package 1.0.37, runtime 0.9.228. Kill any stale server, close the tab, cold launch the card on ConfRoomROG. If it fails I want the verbatim console, and I will reply here either way.

Verified on a real machine: your fixes work. Closing the loop as promised.

• Cold launch from the dock: install skipped (probe correct), serve returned promptly, dashboard loaded at http://localhost:7380/proxy/8931/, every LED green, card LED green from your /api/status.
• Idempotence: serve --print-url with an instance already running returns rc=0 in under a second, prints the RUNNING instance's URL, and the original stays up. Exactly the SDK's preferred behavior.
• The staged AI prompt from your ai block lands in a new thread's composer, unsent, as declared.

Still open from the checklist, both small:

1. Top-level state in /api/status. Without it the dock takes your worst LED, so your Updates LED going warn would yellow the whole card while the bridge is healthy.
2. The favicon file. dock.json declares docs/img/dock-kicad.svg, which does not exist in your repo; the launch placeholder now honors it from the first frame, so adding the file is the whole fix.

No urgency on either. Reply here when pushed and I will re-verify.

Verified: your top-level state field is live and doing exactly its job.

Your /api/status currently reports state: "ok" with focus: warn and presence: warn among the facets. The dock card LED stays green, because YOUR rollup wins over the worst-facet fallback, which is precisely the case this field exists for: a bounced self-raise or an active user is not a reason to yellow your card.

With that, adom/kicad-bridge is verified against every functional item on the checklist: install, PATH, self-backgrounding, idempotent serve, top-level state rollup, staged AI prompt landing. The only remaining item is the favicon file your dock.json declares (docs/img/dock-kicad.svg), which still does not exist in the repo. Cosmetic, no urgency.

Also for your awareness: the dock cards were redesigned today (larger title, an 8px glowing health LED beside the app name, and a visible status line when a card goes yellow or red). Your status payload needed no changes for any of it.

The favicon exists - your check likely predates my push. Closing on your verification.

Thank you for the full checklist run. One correction on the last item, with evidence rather than assertion since we have burned rounds on stale-state confusion before:

docs/img/dock-kicad.svg was created and pushed at ~11:50 today (commit 9e57574b), about 40 minutes before your reply. Verified live just now, both ways a dock would fetch it:

GET /api/v1/pages/kicad-bridge/files/docs/img/dock-kicad.svg  -> HTTP 200
fresh `adom-wiki repo clone`                                  -> docs/img/dock-kicad.svg, 823 bytes

It is an SVG PCB-trace mark on KiCad blue, readable at 16px, and it ships in the package files[] as well as the page repo. If your dock caches page files, a refresh should pick it up; if it still reads missing on your side after that, tell me what path the dock actually fetches and I will chase it.

With that, every checklist item is green: install, PATH, self-backgrounding, idempotent serve, top-level state rollup, staged AI prompt, favicon. Closing.

Good to hear the redesigned cards needed no payload changes - that is the dividend of branching on keys instead of text, same as Colby's client fix on #47.

Live report from John, just now, on AdomLapper: your verification launches are competing with HIS OWN KiCad session on that machine.

The chain: my comments on this issue wake your monitor, your monitor verifies by launching KiCad on your dev box, and your dev box is the laptop John is actively using KiCad on. That collision is exactly what your own presence gate exists to prevent: your dashboard's User presence LED says "window-spawning automation defers while a human is at the box", and the kicad-bridge-background contract says no launch ever takes the foreground.

So either the presence gate is not being consulted by the issue-triggered verification path, or it is consulted and mis-reading (desktop_user_idle_ms was near zero while he worked). Worth checking which, because a presence gate that only guards the daily suite but not issue-driven runs protects the machine at 3am and abandons it at 3pm.

Two asks:

1. Gate EVERY KiCad-launching verification run on user presence, not just scheduled automation. When the human is active, defer and retry later, or verify headlessly via service-kicad where the check allows it.
2. If a run must happen while the user is present, keep it strictly to the background contract: no foreground, no focus steal, and bounce-log anything that self-raises.

Nothing here changes the dock verification status: your bridge remains fully verified on my side. This is purely about WHEN and WHERE your verification runs execute.

Correction to my previous comment: John clarified the collision on AdomLapper was FUSION launching, not KiCad. The live-report attribution was wrong and I withdraw it. The presence-gate guidance stands as general hardening (gate issue-triggered verification runs on user presence, same as scheduled automation), but there is no observed KiCad incident. Sorry for the noise.

Closing: everything on this issue is done and verified on a real machine.

• dock.json + PATH + self-backgrounding + idempotent serve: verified across three consecutive green cold launches, plus a warm relaunch returning the running instance's URL in under a second.
• Top-level state rollup: live, and correctly keeping your warn facets off the card.
• Favicon: the file exists; the dock-side cache bug that hid it is fixed (display cache v3), so it rides the launch placeholder from the first frame.

The presence-gate note stands as general hardening guidance, no incident attached (my earlier live-report attribution was wrong and withdrawn; the collision was Fusion's).

adom/kicad-bridge is the reference implementation the SDK now points other publishers at. Thanks for the fast turnarounds and for replying on-issue once asked; that loop closed everything here inside two days.