fix(remote): handle TLS endpoint verification timeout gracefully in remote:beginPairing

[sambitcreate]

Description

When initiating remote pairing with remote:beginPairing, if the Tailscale HTTPS endpoint or local TLS port is unreachable or outdated (e.g. pointing to a port from a prior session), the TLS probe times out after 5 seconds:

Error occurred in handler for 'remote:beginPairing': Error: Aiden Remote TLS endpoint timed out.
    at Timeout._onTimeout (file:///home/sambit/projects/aiden-agent/build/main/index.js:55636:22)
    at listOnTimeout (node:internal/timers:605:17)
    at process.processTimers (node:internal/timers:541:7)

Steps to Reproduce

1. Start Aiden when Tailscale Serve route points to an inactive port or when the TLS endpoint cannot be reached.
2. In the UI or via client call, trigger remote:beginPairing.
3. Wait 5 seconds.
4. An unhandled exception is logged by the remote:beginPairing IPC handler.

Expected Behavior

The timeout in fetchTlsServerSpkiSha256 should be handled cleanly, returning a structured error outcome to the renderer (e.g. indicating the endpoint is unreachable or timed out) rather than bubbling as an unhandled rejection in the IPC handler.

[pullfrog]

Plan: handle TLS endpoint verification failures gracefully in remote:beginPairing (issue #87 — this is actionable; no implementation done yet)

Root cause

Verified call chain: remote:beginPairing (main/handlers/aiden-remote.ts:132) → AidenRemoteService.beginPairing (main/services/aiden-remote-service.ts:918) → for Tailscale transport, fetchTlsServerSpkiSha256(status.dnsName, 443) (main/services/aiden-remote-service.ts:978, default when the resolveTlsEndpointPin test seam is absent; implementation at main/services/aiden-remote-tls-identity.ts:85). Three facts shape the fix:

1. The probe is the first end-to-end liveness check. The route assessment that precedes it (assessRoute/inspectRoute) verifies Tailscale's configured ownership of the Serve route, not that the tailnet HTTPS proxy can actually reach a live local listener. A route proxying to a dead/outdated port or an unreachable endpoint therefore passes every pre-check and fails only here, after the 5 s timer.
2. Failure surfaces are raw. The timer destroys the socket with a bare Error("Aiden Remote TLS endpoint timed out.") (aiden-remote-tls-identity.ts:104-106); socket-level failures (ECONNREFUSED, ENOTFOUND, TLS handshake/certificate errors) bubble through the error listener (:119-122) with OS text.
3. Every rejected ipcMain.handle promise makes Electron log Error occurred in handler for 'remote:beginPairing': … — the exact line in the issue — even though the renderer already catches it. The toast the user sees is Electron's wrapped text (Error invoking remote method 'remote:beginPairing': Error: …), which explains nothing. State is otherwise clean: the probe runs before this.pairing.begin(...), so no pairing session or secret is created on failure.

Recommended design

A narrow, repo-consistent contract: probe failures become a classified error with a stable code, and the IPC handler resolves a structured error outcome for that expected class instead of rejecting (the only way to silence Electron's handler-error log for this condition). Unexpected/defensive failures keep the existing reject path.

Milestone 1 — classify failures in fetchTlsServerSpkiSha256 (main/services/aiden-remote-tls-identity.ts)

• Introduce an exported error type (e.g. AidenRemoteTlsEndpointError) carrying a stable code plus a human sentence, and classify: timer timeout → timed_out; connect/DNS/network errors → unreachable; certificate/verification failures (including the existing no-certificate branch) → untrusted; bad hostname/port → invalid_endpoint.
• Security invariant: unchanged. Keep rejectUnauthorized: true, servername, and the raw-certificate pin derivation exactly as they are; verification still fails closed — only the failure reporting becomes structured.

Milestone 2 — normalize at the service boundary (main/services/aiden-remote-service.ts)

• Wrap the pin-fetch call in the beginPairing Tailscale branch so any rejection (real fetchTlsServerSpkiSha256 or an injected alternative) becomes the classified error; raw rejects map to unreachable. This keeps the service-level contract (still throws; existing assert.rejects tests keep their shape) and makes the behavior testable through the existing resolveTlsEndpointPin fixture seam (aiden-remote-service.test.ts:275), which currently only ever succeeds.
• Assert the failure happens before pairing.begin — no session and no one-time secret may be created (add a regression assertion).

Milestone 3 — structured IPC outcome (main/handlers/aiden-remote.ts)

• Catch only the classified probe-failure class in the remote:beginPairing handler and return a resolved outcome { errorCode, message }; rethrow everything else. Electron then logs nothing for the expected case, and the renderer gets clean, typed data. (Note: the sibling remote:tailscaleConnect issue fix(remote): handle tailscale_permission_denied gracefully in remote:tailscaleConnect IPC handler #86 has the same shape; keeping the code set/error type in the service layer lets fix(remote): handle tailscale_permission_denied gracefully in remote:tailscaleConnect IPC handler #86 reuse it later without touching this handler.)

Milestone 4 — renderer types and UI (renderer/shared/aiden-remote.ts, renderer/lib/ipc.ts, renderer/components/settings/remote-access-settings.tsx)

• Add a result union (AidenRemotePairingBootstrapView | { errorCode: …; message: string }) in shared types; widen aidenRemoteApi.beginPairing's return type.
• In beginPairing (remote-access-settings.tsx:381), branch on the outcome before treating the result as a pairing session, and show actionable copy per code, e.g.:
  • timed_out/unreachable: the mobile route is not answering — disconnect and reconnect the mobile route (or confirm HTTPS is enabled and the local service is running), then retry.
  • untrusted: verification failed — confirm the system clock and that this is the expected Tailscale name (no trust relaxation).
• Fall back to a fixed friendly sentence (not Electron's wrapped error.message) for any remaining reject, and keep the existing busy-state/finally reset and pairingRequestGeneration guards intact. LAN transport is untouched (its pin comes from the local CA — no probe).

Milestone 5 — tests and verification

• main/services/aiden-remote-service.test.ts: fixture option that makes the pin seam reject; assert beginPairing("tailscale") rejects with each code and that no pairing session/secret was created.
• main/services/aiden-remote-tls-identity.test.ts: unit coverage for the classifier (pure failure classification; no new live-network dependence).
• Update the source-contract tests (main/handlers/aiden-remote.test.ts, renderer/components/settings/remote-access-settings.test.tsx) for the new outcome branch and copy.
• Run npm run test:aiden-remote plus the repo's typecheck/lint scripts. No native-client impact: this is desktop IPC plus a renderer shared type — no wire/protocol change reaches ios//android/.
• Record implementation friction in .papercuts/troubleshooting.md and update .memory/ per repo conventions.

Out of scope (noted, not done)

• Converting the precondition guard throws in beginPairing (e.g. "The Tailscale route is not privately connected…") to resolved outcomes — the UI already disables pairing when those hold false, so they are defensive and can keep rejecting.
• The 5 s probe timeout itself, and issue fix(remote): handle tailscale_permission_denied gracefully in remote:tailscaleConnect IPC handler #86's remote:tailscaleConnect path.

Task list (2/3 completed)

• Analyze issue fix(remote): handle TLS endpoint verification timeout gracefully in remote:beginPairing #87 and gather codebase context (root cause chain)
• Draft structured plan with milestones
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Flash ｜ 𝕏}