fix(maestro): surface cross-host attach failures instead of silent close
ci / rust (push) Failing after 2m11s

Cross-host (T2-brokered) attach fails when no shared perimeter is
configured: the daemon rejects the upgrade with a structured 502
(no_perimeter_candidate / no_local_perimeter / perimeter_mismatch /
peer_unreachable), but maestro-web's WS proxy had already upgraded the
browser socket and merely dropped it on the upstream failure — the
attach pane flashed and vanished with no reason shown.

- maestro-web proxy: on a failed upstream handshake, relay the daemon's
  error message to the browser as an application close frame (4502 +
  reason) instead of a bare drop; parse the structured JSON error body.
- web attach.ts: on a 4000+ close with a reason, show it in the pane
  header and terminal body and keep the pane up, rather than auto-closing.
- daemon: WARN at startup when no perimeter_id/private_addr is configured,
  since cross-host attach is then unavailable.
- docs/INSTALL.md: document the required matching perimeter_id + per-host
  private_addr for cross-host attach.

Closes #39

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-24 15:08:03 +00:00
co-authored by Claude Opus 4.8
parent b67591695e
commit 70c592e884
5 changed files with 151 additions and 3 deletions
+27
View File
@@ -190,6 +190,33 @@ Pick `/tmp` if the daemon must outlive your login session and you can't run
tmux sockets with it). The env var `MAESTRO_DAEMON_TMUX_TMPDIR` takes
precedence over the file.
## Cross-host attach (perimeter setup)
Attaching to a session that lives on **another** host is brokered over the "T2"
transport, which only works when both daemons advertise a **matching
`perimeter_id`** and the session's owner advertises a **reachable
`private_addr`**. These default to unset, and without them every cross-host
attach fails — the registry resolves the session but returns no perimeter
candidate, so the attaching daemon rejects it (`no_perimeter_candidate`) and the
browser pane shows the reason and closes. Same-host attach is unaffected.
Set both on **every** host in `~/.config/maestro/config.toml`:
```toml
[daemon]
# Identical on every daemon that should reach each other — name it after your
# VPN/LAN segment. Two daemons broker to each other only when these match.
perimeter_id = "wg-home"
# THIS host's address as its peers reach it on that perimeter (host:port of the
# daemon's bind_addr). Per-host — never the same value on two daemons.
private_addr = "10.0.0.7:7070"
```
It's both-or-neither: setting only one is ignored with a startup warning. A
daemon started with no perimeter configured logs a `WARN` saying cross-host
attach is unavailable. (T1 direct-WSS was dropped — NAP-235 — and T3 relay isn't
implemented — NAP-238 — so T2 is currently the only cross-host path.)
## Peer attach trust model
There is no per-peer allow-list. The operator's network perimeter (VPN/firewall)