fix(connect): update macOS 2026.10.4 before joining

[miyaontherelay]

Summary

• Require a live 2026.10.5 core on macOS. connect install and connect join now use the existing verified app update path when an installed 2026.10.4 core is responsive, and wait for the new core before reporting readiness.
• Keep a live Linux 2026.10.4 probe usable. If join or status gets not_a_relay_session from that version, print one actionable update line instead of telling the user only to run from a live session.
• Update the Connect README with the platform version requirements.

Why

On finn-mini, the published npx -y @agent-relay/connect install reported “Agent Relay probe ready” with an installed 2026.10.4 macOS app. A daemon-backed Codex user would then still receive 403 from session routes because shared app-server identification landed in the released 2026.10.5 desktop core. The published 2026.10.5 DMG fixes the issue, but the hand-over command did not trigger that update.

Verification

• 41 Connect tests passed locally on macOS, including a responsive 2026.10.4 macOS probe triggering update, Linux 2026.10.4 reuse, update guidance, and waiting through a stale 2026.10.4 core after app launch.
• A local Linux-platform CLI simulation confirmed join, send, status, and leave return the one-line guidance in text mode and retain parseable not_a_relay_session JSON with the guidance in its message under --json.
• On finn-mini with the published signed 2026.10.4 app installed, the real launchd core reported 2026.10.4. A daemon-backed Codex thread ran this branch's built CLI join once; it updated the app to the published 2026.10.5 release and joined the live Connect as macprobe-upgrade-proof-2. The app relaunched at 19:57:16.905Z, and the first 2026.10.5 core status was measured 12.326 seconds later at 19:57:29.232Z. The final installed app and launchd core both report 2026.10.5.
• Connect bundle build passed; Prettier check passed.
• The CLI error output test for Linux runs on Linux CI; the version and message decision is also covered by platform-injected tests on macOS.

🤖 Generated with Claude Code

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: dc330ad9-55a8-480d-b2e7-e5687ae53719

📥 Commits

Reviewing files that changed from the base of the PR and between 5dafdfe and 813c4c9.

📒 Files selected for processing (4)

• packages/connect/README.md
• packages/connect/src/cli.js
• packages/connect/src/install.js
• packages/connect/tests/connect.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

The connect package now applies different minimum probe versions on macOS and Linux. Join, send, status, and leave commands provide Linux update guidance for qualifying probe versions and session errors.

Changes

Probe Version Policy

Layer / File(s)	Summary
Platform minimums and probe reuse packages/connect/src/install.js, packages/connect/tests/connect.test.ts, packages/connect/README.md	Probe checks and live-socket waits use minimums of 2026.10.5 on macOS and 2026.10.4 on Linux. Tests and README guidance reflect these minimums.
Linux session error guidance packages/connect/src/install.js, packages/connect/src/cli.js, packages/connect/tests/connect.test.ts, packages/connect/README.md	For qualifying Linux probes, join, send, status, and leave responses with not_a_relay_session produce update guidance. Tests cover the hint conditions and plain-text and JSON output.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 813c4

No actionable issue remains before merge beyond normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 813c4

The change tightens macOS compatibility while preserving installation verification and session rejection behavior. Risk is low, with remaining uncertainty around desktop-process cleanup and recovery after interrupted replacement.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The changed replacement decision affects the caller's local macOS installation, using existing filesystem permissions. The destination can be the shared /Applications app or the per-user fallback, so the replacement footprint is not necessarily confined to one user's app copy. No new elevation mechanism appears in this path.

Trust Boundaries and Controls

• observed — The normal probe-discovery path rejects non-regular, foreign-owned, or group/world-writable socket pointers and foreign-owned sockets before requesting status. The newly selected macOS replacement path retains checksum verification and staged-app verification against the configured publisher signing requirement.

Resilience and Maintainability Implications

• inferred — Caught failures have explicit rollback handling, but complete recovery cannot be established from this installer alone: macOS retains the socket pointer, and probe cleanup is delegated to desktop-process shutdown. Desktop-owned pointer invalidation and recovery after abrupt interruption remain unverified. These are inherited coverage limits, not established vulnerabilities introduced by this PR.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description includes a detailed summary and verification results, but it omits the required RelayFlow Proof section and does not use the required Test Plan structure with checkboxes.	Add the Test Plan section with the required test checkboxes. Add the RelayFlow Proof section with exactly one valid change type and one case under tests/relayflows/cases//. Add the Screenshots section if applicable.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the primary change: updating macOS 2026.10.4 before joining.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the probe at dawn
Mac needs a newer version on
Linux gets a helpful note
When session names fail to float
Four commands now pass it through
Then hops away beneath the moon}

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 2 potential issues.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[miyaontherelay]

CI follow-up: the original Flows v2 shard 0 failure in this PR was a transient external Relaycast registration error (error sending request for url (https://cast.agentrelay.com/v1/agents)) in scenario-broker-agents-broker-process-integration, not a reproducible regression in this change. The same shard passed on main, and the PR rerun passed with all checks green. The main comparison run had a separate shard 13 failure; it did not reproduce this broker-process failure.