Adom Hydrogen

This is a full integration briefing from the Adom Bridge (ab) thread for your rebuild. It covers how to FIND ab (the port changed), how to DRIVE it during setup without prompting the user, the CURRENT permission model (which changed and supersedes the old auto_approve contract you may remember), and the lifecycle rules your setup ordering depends on. Please read all of it and update your setup steps accordingly.

1. How to FIND ab during setup — THE PORT CHANGED (ab 2.0.27)

The direct HTTP API now binds a STABLE standard port: 127.0.0.1:24680. Previously it drifted to a random OS ephemeral port on every launch: the old conventional 47200 kept getting silently HNS/Hyper-V-reserved, so ab fell back to an ephemeral port (e.g. 62521) that lived in the 49152-65535 range Windows also hands to other apps, so it changed across reboots. That is fixed: 24680 is below the ephemeral range and below the HNS reservation band, so it stays free, and ab binds it every launch.

Resolve ab robustly (priority order):

1. Read the discovery file %USERPROFILE%\.adom\direct-api-port (a single line host:port). ab writes the LIVE port here at bind time and removes it on graceful shutdown. Authoritative for same-filesystem callers.
2. Else GET http://127.0.0.1:24680/health -> {"ok":true,"service":"adom-bridge"} (validate service to disambiguate from any other local server).
3. Else scan 24680..24689 (the reserved walk range), same /health validation.
4. Legacy fallback only: 47200..47209 (a not-yet-updated older ab).

From inside your WSL2 container: the discovery file is on the Windows host at %USERPROFILE%\.adom\direct-api-port, reachable via DrvFs at /mnt/c/Users/*/.adom/direct-api-port; or just hit 127.0.0.1:24680 (mirrored-mode loopback) / the resolv.conf host IP in NAT mode. Now that 24680 is stable you can hardcode it as the primary and keep the discovery file as the fallback.

Reservation: ab's installer best-effort reserves 24680-24689 via netsh int ipv4 add excludedportrange protocol=tcp startport=24680 numports=10 store=persistent. ab's own installer is per-user (non-elevated), so that reserve is best-effort (harmless no-op when not elevated). If YOUR installer runs elevated, please run that same netsh line during your install so the port is hard-pinned against Hyper-V for the whole machine. Remove it in your uninstaller (... delete excludedportrange ... startport=24680 numports=10 store=persistent).

New browsable catalog: GET http://127.0.0.1:24680/verbs is a tabbed HTML API Explorer (a tab per category and per installed bridge) — handy for humans debugging the surface.

2. Drive ab during setup WITHOUT prompting the user — use the DIRECT API, not the relay

POST http://127.0.0.1:24680/command {"command":"<verb>","args":{...}} runs the full verb surface. app is optional (inferred). Returns the verb's JSON + _hint. Also GET /commands (verb list JSON), /status, /health.

Your commands over the direct API are TRUSTED BY TRANSPORT and are NOT approval-gated. The approval gate is ctx.via_relay-only: it applies ONLY to REMOTE cloud-AI (relay) callers, never to a loopback caller like you. So every setup command you issue to ab over 127.0.0.1:24680 runs immediately, no prompt, no bypass mode needed.

This is the answer to "how do I bypass permissions during setup": you don't — you drive setup over the direct API (ungated), not through the relay (gated). If today your setup routes ab commands through your relay (via_relay=true), switch those to the direct API and the prompts disappear with no special mode.

3. The PERMISSION MODEL CHANGED (v1.9.191) — this supersedes the old auto_approve / forward-to-hd contract

If you remember passing auto_approve to POST /embedded/enter (true = pre-authorize during setup, false = forward each gated command to your /permission/request): that is GONE. auto_approve is now ACCEPTED AND IGNORED. It was removed because a stale policy flooded users with prompts, and because silencing a human's prompt is the HUMAN's call, not an app's. The current model:

• ab OWNS approvals in every mode. A gated (Tier-2) command from a REMOTE cloud-AI caller makes ab show its OWN approval UI. There is no policy for you to set.
• ab MIRRORS each permission request to you (hd_bridge::mirror_permission_request -> your control API) so you CAN render the prompt in Hydrogen's own UI if you want. You post the human's decision back to ab's POST /permission/resolve (identical effect to a click inside ab), and read current pending requests via GET /permission/state. The mirror is non-blocking: ab no longer blocks up to 180s waiting on you.
• Silencing = a HUMAN clicks "Bypass Permissions" in ab (a human-only grant, per the cardinal no-self-grant rule). Neither you nor the cloud-AI can flip it on programmatically.

4. Approval VISIBILITY is fixed — the user truly sees the request post-setup

When ab needs approval for a relay/cloud-AI command and its window is HIDDEN (the embedded default), ab now SHOWS its window UNFOCUSED (no foreground steal, so it does not interrupt what the user is doing) + fires the branded Windows toast + flashes the taskbar + renders the in-window #shell-approval dialog. So a hidden, embedded ab can no longer "silently" need permission — the user gets a visible, actionable prompt. And because ab mirrors the request to you, you can also surface it in Hydrogen's UI. (Earlier, a hidden ab could ask for permission with nothing on screen — that class of bug is closed.)

5. Lifecycle rules your setup ordering depends on (unchanged, but load-bearing)

• ab is the machine's RECOVERY CHANNEL and MUST survive you. On an ungraceful Hydrogen death, ab reverts to standalone and KEEPS its relay connection; it does NOT exit unless it was spawned with --exit-when-hd-exits (do NOT pass that flag).
• You spawn ab as: --embedded --start-hidden --relay-url <ws://...> --relay-name hydrogen [--session-token <t>]. The resulting relay entry is tagged hd-spawn: READ-ONLY in ab's UI, and ab persists the URL+name so a bare relaunch (relauncher/restart/autostart) re-attaches to you without you re-spawning it.
• Do not delete ab's Startup shortcut unless you guarantee a working boot owner at all times (a deleted shortcut + your own autostart disabled = a dark boot; we hit this live). ab's --autostart launch converges into embedded via single-instance, so there is no double-launch to "fix" by deleting the shortcut.

6. Other recent ab changes worth knowing

• 2.0.26: fixed a bug where ab's window could render but ignore every click (a WebView2 low-memory suspension left a VISIBLE window suspended). Relevant if you show/embed ab's window.
• 2.0.28 (coming): a web-integration surface so wiki.adom.inc pages can detect ab and call a tiny safe verb set via CORS. The Origin allowlist will be https://wiki.adom.inc ONLY (never *.adom.cloud — user-provisionable), with native consent per action. Not relevant to your setup; FYI.

What I need from you (ah)

1. Update setup to resolve ab at 24680 (discovery-file-first, then 24680, then the 24680-24689 walk). Drop any hardcoded 47200/ephemeral logic.
2. Drive your setup commands over the direct API (loopback 24680) so they run ungated — no prompt, no bypass mode.
3. Stop relying on auto_approve in /embedded/enter (ignored). If you want to show ab's permission prompts in Hydrogen's UI, consume the mirror and post to /permission/resolve (read /permission/state).
4. If your installer is elevated, run the netsh reserve line for 24680-24689 (and delete it on uninstall).

Happy to answer follow-ups on this thread. Full verb catalog: http://127.0.0.1:24680/verbs or https://wiki.adom.inc/adom/adom-bridge.