fix(connect): stop at once when a live probe cannot identify the session

Merged
KH
3d ago
+229-8

Customer symptom. A guest on macOS (no app installed, so the standalone-probe path) got Timed out waiting for the Agent Relay probe after 60000 ms. Afterwards there was no pointer and no probe process, and headless.log was empty.

Root cause.

  • The installer's readiness check polls GET /setup/status and accepts only ok:true.
  • The probe answers every route, /setup/status included, with 403 not_a_relay_session when it cannot tie the calling process to a live Claude Code or Codex session (relay-desktop outbound.rs setup_route → identify).
  • So a probe that started fine looked dead. The installer waited the full 60 s, killed the probe, removed the pointer and printed only a timeout.
  • headless.log is empty on a successful start too, so the empty log meant nothing.

Reproduced with the published v2026.10.31 macOS arm64 probe tarball and a fresh HOME. It was ready in 2 s and wrote its pointer, and /setup/status answered not_a_relay_session.

Fix.

  • A probe that answers not_a_relay_session or session_file_unreadable now counts as live, in both findLiveSocket and waitForLiveSocket. Its version can't be read in that state.
  • The join, send, status or leave request then gets the same answer, and the CLI prints it inline in about a second.
  • No second probe is installed. A freshly installed probe is kept, not rolled back.
  • The not_a_relay_session message now says the probe is running and that the command must run from the agent's own shell tool.
  • session_file_unreadable passes the probe's own explanation through. It was previously "Relay Connect request failed (session_file_unreadable)".
  • A readiness timeout now names the probe's last answer, or says it never answered and points at headless.log.
  • connect install run from a plain terminal no longer times out against a live probe.

Unchanged.

  • The Linux 2026.10.4 update hint still applies when /setup/status answers ok:true with that version.
  • Old-version detection is the same.

Tests (54 pass). Six are new, and all six fail on main:

  • waitForLiveSocket returns on the first not_a_relay_session answer, with no sleep.
  • A timeout names the last answer, or "never answered".
  • findLiveSocket returns a caller-rejecting probe as live instead of null.
  • Fresh-HOME reproduction, end to end: a fake probe answers every route 403 not_a_relay_session. connect join exits 6 with the inline message in under 5 s, and only GET /setup/status and POST /connect/join are requested. On main, the old code instead waits through recovery and starts an install.
  • session_file_unreadable prints the probe's message.
  • A fresh Linux install whose probe rejects the caller is kept. On main this hits the 60 s timeout and rolls back.

This is a separate fix from the Node-relay design (#1966). We still need to learn why Julian's session was not identified; questions are out to him.

🤖 Generated with Claude Code

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

[!NOTE]
Low Risk
Scoped to connect CLI probe readiness and error messaging; no auth or cloud API changes.

Overview
Fixes a case where @agent-relay/connect join (and install) could sit for 60 seconds, tear down a healthy probe, and only report a generic timeout when the probe was up but returned not_a_relay_session or session_file_unreadable on /setup/status.

Probe discovery now treats those responses as proof the socket is live: findLiveSocket and waitForLiveSocket return immediately with sessionRejected instead of polling until timeout or rolling back a fresh Linux install. Readiness timeouts include the probe’s last answer (or a pointer to headless.log).

CLI behavior surfaces the real session errors in ~1s—clearer copy for not_a_relay_session, probe text for session_file_unreadable, and connect install uses requireVerifiedProbe so a running but unverifiable probe is not reported “ready” from an outside terminal.

Docs and changelog describe running connect from the agent’s shell; six new tests cover the fast-fail and install-keep paths.

Reviewed by Cursor Bugbot for commit 60dc36a83fc37c3e85a69800234dd842989c65df. Bugbot is set up for automated code reviews on this repo. Configure here.

Agent Relay sessions

  • claude session 290d4dce · opened via gh pr create · last active 2026-10-12
  • claude session e402462f · contributor · ran gh pr commands · last active 2026-10-12