Adom Bridge

Summary

The container-side Linux adom-desktop CLI does not forward the reason field that the released 1.9.168 desktop now requires on shell_execute (and every Tier-2 shell verb). Net effect: every shell operation from a Linux container is dead — reason_required, unrecoverably — which takes out shell_execute / run_script / wsl_exec and everything built on them (KiCad + Fusion bridge shell ops, and Adom Nucleus's file browser, which is how this was found).

Environment

• Container CLI + relay: adom-desktop 1.9.168 (8d79bc3-dirty, built 2026-07-23T16:55:04Z)
  • Path: adom_modules/adom/adom-desktop/dist/linux/adom-desktop (synced into the adom/adom-desktop package's dist/linux/; PATH symlink retargeted 2026-07-23 17:35).
  • Note it is a -dirty build (uncommitted changes).
• Desktop: BARRETTLAND, Adom Desktop 1.9.168 (installed from the published Adom.Desktop_1.9.168_windows_x64-setup.exe).
• Both sides report 1.9.168, so this is not a major version gap — it's the dirty container CLI being out of sync with the released desktop's shell protocol.

What fails

shell_execute is refused with errorCode: reason_required even when both conditions the error asks for are satisfied:

1. Shell approval is active — request_shell_approval returns alreadyApproved: true (user clicked Approve on the in-app dialog).
2. A reason is included in the args JSON.

$ adom-desktop shell_execute '{"command":"cmd /c echo %USERPROFILE%","reason":"list home for file browser"}'
{ "errorCode": "reason_required",
  "error": "'shell_execute' needs human permission, so it REQUIRES a `reason`. Retry the SAME call with reason:\"...\"." }

Same result for run_script and with the reason passed via a --reason flag, a global pre-verb flag, and a JSON file (no shell-quoting involved).

Root cause (isolated)

• The refusal is desktop-side, not the CLI: the full gate text (needs human permission, Retry the SAME call, appliesTo) is absent from the container binary's strings, and the reason_required round-trip (13 ms) matches a real desktop round-trip (desktop_list_files = 16 ms).
• The container CLI's shell_execute arg schema has no reason — adom-desktop help shell_execute lists only allowPopupRisk, command, cwd, timeoutSeconds. So the CLI drops the reason field before forwarding, the desktop never receives it, and it demands one forever.

So: the released desktop made reason mandatory on shell verbs; the synced-in dirty Linux CLI build doesn't declare/forward reason. They no longer agree.

Impact

Container-wide. Any Linux-container flow that uses a Tier-2 shell verb is blocked with no workaround from the container side (no reason value can be delivered). Confirmed broken: Adom Nucleus "Browse files" (folder listing), and it will hit KiCad/Fusion bridge shell operations the same way.

Suggested fix

Re-sync the container dist/linux/adom-desktop from a clean 1.9.168 build whose shell_execute (and the other Tier-2 verbs) declares + forwards reason, matching the released desktop. (There is no published Linux release asset to fall back to — the container Linux CLI only ever comes from this package's dist/, so it has to be rebuilt/re-synced.)

Notes

• desktop_list_files / structured filesystem verbs are unaffected (they don't go through the shell gate) — good, but they only list files, not directories, so they can't substitute for the browser's dir walk.
• Filed from Barrett's container. Reproducible on demand.