naps62/maestro
Archived
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

Cross-host attach fails silently when perimeter unconfigured: surface broker error + document perimeter_id/private_addr #39

New Issue
Closed
opened 2026-06-24 16:02:17 +01:00 by naps62-yolo · 0 comments
naps62-yolo commented 2026-06-24 16:02:17 +01:00
Collaborator
Copy Link
Copy Source

Cross-host broker attach fails silently and undebuggably when the perimeter isn't configured. Same-host attach works (short-circuits before the broker); cross-host attach makes the terminal pane flash and vanish with no error shown.

Root cause (confirmed live)

The only working broker transport is T2, which needs both daemons to advertise a matching perimeter_id and the target to advertise a reachable private_addr. A daemon with no perimeter_id heartbeats perimeter: None → registry resolve_attach returns perimeter: None → the browsing host's broker bails with 502 no_perimeter_candidate (crates/maestro-daemon/src/local_api.rs ~492-498). These fields default to None, are never prompted by maestro daemon configure, and aren't documented.

The 502 is invisible to the user because maestro-web's WS proxy accepts the browser upgrade first (so onopen fires), then drops the socket when its upstream connect_async gets the 502 — the browser only sees an opaque open-then-close (crates/maestro-web/src/proxy.rs pump_ws ~205; web/src/attach.ts onclose ~247).

Scope

  1. Surface the broker failure reason to the UI. Forward the broker's structured error (no_perimeter_candidate / no_local_perimeter / perimeter_mismatch / peer_unreachable) through the proxy as a WS Close with code/reason (or a control error frame) and render it in the attach pane instead of silently tearing it down.
  2. Document perimeter_id / private_addr in docs/INSTALL.md (matching perimeter_id on every host, per-host private_addr) and/or prompt for them in the configure wizard.
  3. Startup WARN when a daemon registers with no perimeter configured, so operators learn cross-host attach won't work.
Cross-host broker attach fails **silently and undebuggably** when the perimeter isn't configured. Same-host attach works (short-circuits before the broker); cross-host attach makes the terminal pane flash and vanish with no error shown. ## Root cause (confirmed live) The only working broker transport is **T2**, which needs both daemons to advertise a matching `perimeter_id` and the target to advertise a reachable `private_addr`. A daemon with no `perimeter_id` heartbeats `perimeter: None` → registry `resolve_attach` returns `perimeter: None` → the browsing host's broker bails with `502 no_perimeter_candidate` (`crates/maestro-daemon/src/local_api.rs` ~492-498). These fields default to `None`, are never prompted by `maestro daemon configure`, and aren't documented. The 502 is invisible to the user because `maestro-web`'s WS proxy accepts the browser upgrade **first** (so `onopen` fires), then drops the socket when its upstream `connect_async` gets the 502 — the browser only sees an opaque open-then-close (`crates/maestro-web/src/proxy.rs` `pump_ws` ~205; `web/src/attach.ts` `onclose` ~247). ## Scope 1. **Surface the broker failure reason to the UI.** Forward the broker's structured error (`no_perimeter_candidate` / `no_local_perimeter` / `perimeter_mismatch` / `peer_unreachable`) through the proxy as a WS Close with code/reason (or a control error frame) and render it in the attach pane instead of silently tearing it down. 2. **Document `perimeter_id` / `private_addr`** in `docs/INSTALL.md` (matching `perimeter_id` on every host, per-host `private_addr`) and/or prompt for them in the `configure` wizard. 3. **Startup WARN** when a daemon registers with no perimeter configured, so operators learn cross-host attach won't work.
naps62 was assigned by naps62-yolo 2026-06-24 16:02:28 +01:00
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/android
area/cli
area/config
area/daemon
area/protocol
area/tui
area/web
code-review
difficulty/easy
difficulty/hard
difficulty/medium
epic
Tracks a multi-issue epic / parent work item
 tui
type/docs
type/feat
type/fix
type/refactor
type/test
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
hermes (Hermes (agent)) naps62-yolo (naps62-yolo (agent)) resende (Resende) naps62 (Miguel Palhas)
No Assignees naps62
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: naps62/maestro#39