Recover Relay publication after pipe failures

[arul28]

Summary

• keep real Relay pipe and local-listener setup failures fail-closed for the current connection generation until a fresh tunnel reaches ready
• preserve an already-ready Relay route when a secondary attempt fails, and republish account-directory state when the active route blocks or recovers
• report authoritative bridge blockers ahead of stale historical errors in sync diagnostics
• document the recovery contract and prepare v1.2.35 release notes

Validation

• npm --prefix apps/ade-cli run typecheck
• npm --prefix apps/ade-cli run test (96 files, 2,147 tests)
• npm --prefix apps/ade-cli run build
• npm --prefix apps/desktop run typecheck
• node scripts/validate-docs.mjs (200 files)
• focused Relay/loopback/publisher/CLI suite (4 files, 361 tests)
• independent correctness and maintainability review

Compatibility

• the tunnel status field is additive; the Worker wire protocol is unchanged
• no iOS payload, schema, or command contract changed

Summary by CodeRabbit

• New Features
  • Improved relay status reporting with clearer connection and failure details.
  • Automatically refreshes route information when relay health changes.
  • Preserves verified relay endpoints during temporary pipe failures and restores normal publishing after recovery.
• Bug Fixes
  • Retains accurate bridge failure diagnostics until a new tunnel is ready.
  • Prevents stale relay errors from masking current relay health.
  • Preserves historical failure timestamps across relay recovery.

Greptile Summary

This PR improves Relay recovery and status reporting for sync routes. The main changes are:

• Tracks current-generation Relay pipe and local bridge setup failures until a fresh tunnel reaches ready.
• Preserves already-ready Relay routes when secondary attempts fail.
• Republishes account-directory state when the active Relay route becomes blocked or recovers.
• Updates CLI status output to prefer current Relay blockers over stale control errors.
• Adds focused tests and release documentation for the recovery behavior.

Confidence Score: 5/5

Safe to merge with low risk.

The changes are focused on Relay state tracking and diagnostics, with targeted tests covering blocker persistence, recovery, retained healthy routes, publisher behavior, and CLI status formatting. No blocking correctness or security issues were identified.

No files require special attention.

T-Rex Logs

What T-Rex did

• T-Rex produced a proof for a posted P1 finding.
• T-Rex ran the relay/loopback/publisher validation and finished with exit code 0 after 8 seconds, reporting 3 test files passed and a total of 77 tests passed with 3 skipped (80 total).
• T-Rex executed CLI diagnostics after the prior step, which finished with exit code 1 after 20 seconds and reported 1 failed test (1) and 279 passed with 1 skipped (281 total).
• T-Rex included a reproduction script transcript to capture the exact commands used for the executed validation.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
apps/ade-cli/src/services/sync/syncTunnelClientService.ts	Introduces generation-scoped bridge-open failure state and publication callbacks for route block/recovery events.
apps/ade-cli/src/services/sync/syncService.ts	Adjusts route health reasoning to distinguish control errors from bridge-open blockers.
apps/ade-cli/src/bootstrap.ts	Wires the tunnel client publication callback through the renamed publication-state hook.
apps/ade-cli/src/services/sync/syncTunnelClientService.test.ts	Adds detailed tunnel client coverage for bridge-open blockers, publication triggers, recovery, and retained active tunnels.
apps/ade-cli/src/services/account/accountMachinePublisherService.test.ts	Adds publisher coverage for retaining verified Relay endpoints during a blocker and clearing retention after recovery.
apps/ade-cli/src/cli.ts	Updates Relay status formatting to show authoritative skip reasons before reachability and stale control errors.
docs/features/sync-and-multi-device/README.md	Documents the Relay bridge recovery contract and publication blocker semantics.

Sequence Diagram

sequenceDiagram
  participant Worker as Relay Worker
  participant Tunnel as SyncTunnelClientService
  participant Local as Local ADE listener
  participant Publisher as AccountMachinePublisher
  participant Directory as Account Directory

  Worker->>Tunnel: control open request
  Tunnel->>Local: validate loopback listener
  Local-->>Tunnel: ADE marker validated
  Worker->>Tunnel: data pipe open
  Tunnel->>Local: local websocket open
  alt pipe/local setup fails before ready
    Tunnel->>Tunnel: record bridgeOpenFailure for current generation
    Tunnel->>Publisher: onPublicationStateChanged(route-state-changed)
    Publisher->>Directory: publish with retained Relay endpoints hint
  else pipe and local both ready
    Tunnel->>Worker: ready
    Tunnel->>Tunnel: clear bridgeOpenFailure
    Tunnel->>Publisher: onPublicationStateChanged(route-state-changed)
    Publisher->>Directory: publish recovered reachable endpoints
  end

Loading

Comments Outside Diff (1)

1. General comment

   CLI socketless headless login fails to initialize the ADE brain

   • Bug
     • The requested CLI diagnostics test run fails in apps/ade-cli/src/cli.test.ts at ADE CLI > autostarts a machine brain for socketless headless login. The runtime error is Failed to initialize the ADE brain for account login, with details showing it could not attach to /tmp/.../sock/ade.sock because the socket did not exist. This indicates the changed CLI account-login/autostart path is not satisfying the expected socketless headless login behavior covered by the repository's real test.
   • Cause
     • The failure is thrown from the changed runAccountLogin path in apps/ade-cli/src/cli.ts after the attempted ADE brain initialization/attachment cannot find the expected local runtime socket. The test expected the CLI to autostart or otherwise make the machine brain available for socketless headless login, but the changed behavior leaves the attach path pointing at a nonexistent socket.
   • Fix
     • Restore the socketless headless login initialization contract in runAccountLogin: ensure the machine brain autostart path completes and publishes/creates the runtime socket before attempting to attach, or update the attach retry/readiness handling so it waits for the autostarted brain socket rather than failing immediately with ENOENT.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "Simplify relay publication lifecycle" | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
ade	Ignored	Preview	Jul 22, 2026 9:56pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Relay bridge-open failures are tracked by bridge identity, propagated through sync status, and used to trigger route republishing. Tunnel lifecycle, relay recovery, status formatting, and account-machine publication behavior gain regression coverage.

Changes

Relay failure propagation

Layer / File(s)	Summary
Bridge failure tracking and lifecycle apps/ade-cli/src/services/sync/syncTunnelClientService.ts	Tracks bridge-open failures per tunnel bridge key, reports failures once, clears stale state during recovery or identity changes, and exposes matching diagnostics in status.
Status and route publication integration apps/ade-cli/src/services/sync/syncService.ts, apps/ade-cli/src/cli.ts, apps/ade-cli/src/bootstrap.ts	Propagates bridge and control failure reasons into relay status, formats skip reasons and reachability, and requests account-machine publication when route state changes.
Failure recovery and publication validation apps/ade-cli/src/services/sync/*test.ts, apps/ade-cli/src/services/account/*test.ts, apps/ade-cli/src/cli.test.ts	Tests diagnostic persistence, relay recovery, status formatting, and relay endpoint retention during account-machine republishing.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• arul28/ADE#816: Extends relay pipe forwarding and health propagation around bridge validation.
• arul28/ADE#846: Overlaps in route publication wiring and relay skip-reason handling.
• arul28/ADE#864: Adds related relay-readiness and republishing assertions.

Suggested labels: docs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: recovering relay publication after pipe failures.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ade/relay-pipe-recovery-a91af798

---

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

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