#1966 docs(connect): plan — @agent-relay/connect becomes the local relay (no native probe on guests)

Design-only PR for review before implementation. No code changes.

Problem. npx -y @agent-relay/connect join <link> downloads and detached-launches the native probe, then waits 60 s blind. On a managed Mac the first launch can be blocked, and the guest sees only Timed out waiting for the Agent Relay probe after 60000 ms.

Proposal (docs/connect-node-local-relay.md). The npm package runs its own per-user relay daemon under the Node that npx already started. It holds the Connect credential, polls Relaycast deliveries, injects into the calling Claude Code or Codex session, and acks. It does this with the probe's ledger rules and the same local /connect/* contract. A live, eligible desktop probe is still preferred. join no longer downloads a native binary, and startup failures print inline through an IPC handshake.

The doc covers:

• what we port, with references to the probe source;
• lifecycle (an on-demand detached daemon, not a service, and not foreground);
• exactly-once and ack semantics;
• coexistence with the desktop probe;
• what we deliberately do not port;
• phases and tests.

It also records findings on the related items:

• (a) the five causes of connect_unreachable, which are not logged;
• (b) confirmed: leave is local-only, and Cloud has no room leave operation (left_at is never set).

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

[!NOTE]
Low Risk
Documentation-only proposal with no code, config, or behavior changes in this PR.

Overview
Design-only: adds docs/connect-node-local-relay.md as a pre-implementation proposal—no runtime changes in this PR.

The doc proposes replacing join's native probe download and 60s blind wait with a per-user Node relay daemon (process.execPath, detached, IPC handshake) that keeps the existing local /connect/* socket contract, polls Relaycast, injects into the calling Claude Code or Codex session, and uses the probe's delivery ledger rules under ~/.agentworkforce/connect/.

It specifies backend selection (Node relay when no eligible desktop probe; join stops auto-downloading the probe), session targeting via env/ancestry instead of SO_PEERCRED, lifecycle (runtime copy, single instance, idle exit, revival from persisted state), deliberate non-ports, phased rollout and test plan, and follow-up items (splitting connect_unreachable causes and fixing leave presence via Relaycast/Cloud).

^{Reviewed by Cursor Bugbot for commit 7e7c975a27644c17df195072672c7f4d69c4054b. 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