KiCad - the KiCad Bridge

adom/kicad-bridge 1.0.142 · adom/adom-bridge 2.1.129 · adom/adom-bridge-macos 1.9.209 · adom/core 4.14.0 · macOS (Apple silicon)

What I did

On a Mac with no KiCad installed, followed exactly the path the bridge's own hints prescribe. kicad_readiness and kicad_list_versions both return errorCode: "host_app_not_installed", and both _hints say:

KiCad not detected — offer to install it, then run kicad_upgrade '{}' (installs the official build from scratch: ... macOS: universal DMG into /Applications/KiCad, de-quarantined).

So I ran adom-bridge kicad_upgrade '{}'.

What I expected

KiCad 10.0.6 installed into /Applications, per the hint.

What happened

{
  "durationMs": 71363,
  "error": "Internal error: name 'subprocess' is not defined",
  "output": "",
  "status": "error",
  "success": false,
  "timeoutSeconds": 140
}

Reproduced twice, ~20 minutes apart, identical error. Second run durationMs: 80388.

The message is a Python NameError — a missing import subprocess in the kicad_upgrade handler (or in the macOS branch of it). The non-trivial durationMs (71 s and 80 s) suggests it gets as far as downloading or preparing before reaching the line that needs subprocess, so the failure is late rather than at entry.

Why this one stings

kicad_upgrade is the only route the bridge offers for this case on macOS:

• It is what host_app_not_installed explicitly tells the agent to call, and the hint goes out of its way to say "DON'T make the user install it by hand" and "never hand the user a manual download".
• desktop_install_kicad is Windows-only (winget wrapper), so there is no structured fallback verb on macOS.
• That leaves shell_execute, which is approval-gated (see the separate note below).

Net effect: on a Mac with no KiCad, an agent following the documented path has no working way to install it, and the bridge's own guidance forbids the manual workaround.

Suggested fix

Add the missing import subprocess in the kicad_upgrade handler and add a smoke test that runs the verb on a runner without KiCad present — the bug is invisible on any box that already has KiCad, which is probably why it survived.

Two adjacent things noticed while working around this

Filing here rather than separately since they surfaced on the same path; happy to split them out or move them to adom/adom-bridge if that is the better home.

1. shell_execute approval appears to expire at 60 s and report the expiry as a user deny. Three attempts returned stderr: "Command denied by user" at durationMs 60016, 60025 and 60029 — within 13 ms of exactly 60 s each time, which is not a human clicking. Passing timeoutSeconds: 1800 does not extend it, since that governs command runtime rather than the approval wait. If that reading is right, an expired dialog reporting as an explicit deny is misleading to both the agent and the user: the agent concludes the user refused, the user believes they granted permission. A distinct errorCode such as approval_timeout would let the caller re-request instead of backing off.

2. Two verbs answer "Unknown app: desktop" on this macOS bridge, though both appear in the commands catalog with full arg docs: request_shell_approval ({"reason":..., "wait":true, "timeoutSec":360}) and bridge_list ({}). If they are Windows-line verbs, the catalog served to a macOS client probably should not advertise them — a cold agent reads the catalog and reasonably assumes they work. Note that request_shell_approval being unavailable is what makes (1) unrecoverable: there is no way to ask for a longer-lived grant, and shell_auto_approve correctly refuses AI callers by design.

Workaround for anyone hitting this

Install KiCad manually, then kicad_list_versions to re-detect:

https://mirrors.mit.edu/kicad/osx/stable/kicad-unified-universal-10.0.6.dmg   (1.34 GB, universal)

Mount, copy to /Applications, then xattr -dr com.apple.quarantine /Applications/KiCad.