fix(remote): handle tailscale_permission_denied gracefully in remote:tailscaleConnect IPC handler

[sambitcreate]

Description

When attempting to connect or configure Tailscale Remote routes on Linux where the current user has not been granted Tailscale operator permissions (sudo tailscale set --operator=$USER), remote:tailscaleConnect throws an unhandled rejection:

Error occurred in handler for 'remote:tailscaleConnect': Error: tailscale_permission_denied
    at AidenRemoteTailscaleController.applyExactRouteMutation (file:///home/sambit/projects/aiden-agent/build/main/index.js:57408:43)
    at async file:///home/sambit/projects/aiden-agent/build/main/index.js:57425:41
    at async withAidenTailscaleRouteLock (file:///home/sambit/projects/aiden-agent/build/main/index.js:57073:12)
    at async file:///home/sambit/projects/aiden-agent/build/main/index.js:56694:11

Steps to Reproduce

1. Start Aiden on Linux without granting Tailscale operator permissions (sudo tailscale set --operator=$USER).
2. In Settings -> Remote Access, attempt to connect Tailscale.
3. Observe unhandled error logged in Electron process console.

Expected Behavior

remote:tailscaleConnect should handle tailscale_permission_denied gracefully, updating the connection status or returning a structured error outcome so the UI can guide the user to run sudo tailscale set --operator=$USER without throwing an unhandled IPC rejection.

[pullfrog]

Analysis

Issue #86 is actionable. No duplicate/similar issues found (find_similar_issues returned no candidates).

Current behavior on main. The literal string tailscale_permission_denied no longer exists anywhere in the tree — on current main a non-operator connect attempt on Linux dies inside AidenRemoteTailscaleController.applyExactRouteMutation (main/services/aiden-remote-tailscale.ts:653): the tailscale serve mutation error is swallowed into commandFailed = true, the fail-closed read-back confirms the route never changed, and the controller throws the misleading tailscale_route_outcome_unknown. remote:tailscaleConnect (main/handlers/aiden-remote.ts:106) rejects, Electron logs Error occurred in handler for 'remote:tailscaleConnect', and the settings UI toasts "Tailscale reported an uncertain route update…" with no hint that the fix is sudo tailscale set --operator=$USER. There is no operator-permission classification anywhere and no actionable UI copy.

House precedent that fits the requested shape. The issue asks to "update the connection status or return a structured error outcome so the UI can guide the user… without throwing an unhandled IPC rejection". The codebase already does exactly this for startup port collisions: AidenRemoteService latches lastErrorCode = "remote_port_in_use" (aiden-remote-service.ts:623), the IPC call resolves with the status snapshot, and the renderer renders guidance in the Tailscale/technical callout (remote-access-settings.tsx:714). The plan below mirrors that pattern with a permission_denied status code instead of rejecting.

Plan

Milestone 1 — Typed permission-denied detection in the Tailscale controller

main/services/aiden-remote-tailscale.ts

• Add an exported classifier (e.g. aidenTailscaleCommandFailureIsPermissionDenied(error)) that inspects the execFile rejection (error.message, which embeds CLI stderr) for tolerant markers: the literal tailscale_permission_denied, permission denied, access denied, not an operator, and --operator=. Keep the helper exported for unit tests.
• In applyExactRouteMutation, keep the existing fail-closed read-back as the gate: when commandFailed and the post-mutation serveStatus fingerprint proves the route is untouched (the branch that already clears outcomeStore), throw new Error("tailscale_permission_denied") instead of tailscale_route_outcome_unknown when the CLI error classifies as permission-denied; otherwise keep the current codes. Never classify without the read-back proof — unchanged-route verification is what distinguishes "you lack permission" from "outcome genuinely unknown".
• Same typed code from takeOver/disconnect/route-recovery paths is covered automatically because all writes funnel through applyExactRouteMutation.

Milestone 2 — Graceful connect outcome + status latch

main/services/aiden-remote-service.ts

• In connectTailscale(), catch the typed tailscale_permission_denied and record it on a service latch (new tailscaleErrorCode-style member following the lastError/lastErrorCode precedent at lines 387–388/623–626) without rethrowing, so remote:tailscaleConnect resolves with a settings snapshot that carries the structured error. Clear the latch on a successful connect, on disable, and when the connection mode no longer includes Tailscale.
• status() merges the latch into the returned view as tailscaleErrorCode: "permission_denied"; the read-derived route state stays whatever live inspection reports (typically available), so the Connect button remains available for retry after the user grants operator.
• Disconnect/takeover paths keep rejecting with the typed code (nothing changed, so there is no status to update) — consistent with every other typed tailscale_* failure.

Milestone 3 — Shared contract + UI guidance

• Extend the tailscaleErrorCode union with "permission_denied" in renderer/shared/aiden-remote.ts:22 and the matching main-side status type so the desktop IPC contract stays consistent (verify no snapshot normalization or mobile wire projection consumes this union — the status view is desktop-settings-only IPC, but confirm against aiden-remote-protocol.ts and the native clients per AGENTS.md).
• renderer/components/settings/remote-access-settings.tsx: when tailscaleErrorCode === "permission_denied", show an actionable badge/copy in the Tailscale Serve callout (e.g. "Permission needed" + "Run sudo tailscale set --operator=$USER in a terminal, then connect again") using existing Badge/Callout/Text primitives and semantic tokens. Add a friendlyTailscaleError branch for the typed code so the reject-based paths (disconnect/takeover) also render the same remediation.
• The main-process Error occurred in handler… console line disappears for the connect path because the handler no longer rejects for this condition.

Milestone 4 — Tests, docs, verification

• main/services/aiden-remote-tailscale.test.ts: controller tests via the fake runner — permission-denied mutation error → connect() rejects with tailscale_permission_denied, outcomeStore cleared, route untouched; a generic command failure still yields tailscale_route_outcome_unknown (no misclassification); classifier unit cases.
• main/services/aiden-remote-service.test.ts: connectTailscale() resolves (no throw) under a permission-denied tailscale; returned status exposes tailscaleErrorCode: "permission_denied"; latch clears after a subsequent successful connect and on disable.
• renderer/components/settings/remote-access-settings.test.tsx: source-contract assertions for the new copy/permission_denied branch (matches the file's existing source-scan style).
• Run npm run test:aiden-remote (register the file only if a new test file is added); follow the CI learnings: run focused suites via node_modules/.bin/tsx --test, ignore pre-existing pi-session/subagent-run-store noise.
• Per AGENTS.md: check docs/security/aiden-remote-threat-model.md §9 triggers (expected: no new route/capability/credential surface — error handling only), update .memory/, and record friction in .papercuts/troubleshooting.md if any.

Open question / risk

• Detection relies on Tailscale CLI error text markers, which vary across Tailscale versions; the classifier is deliberately tolerant, and the unchanged-route read-back gate prevents false "permission denied" claims. Any error that doesn't match falls back to today's behavior unchanged. Note the issue's stack trace names an older build (current main surfaces tailscale_route_outcome_unknown, not tailscale_permission_denied), so unit-level reproduction via the fake runner is the verification path rather than live Tailscale on Linux.

Task list (4/4 completed)

• Analyze issue fix(remote): handle tailscale_permission_denied gracefully in remote:tailscaleConnect IPC handler #86 and gather context (issue body, related code)
• Check for duplicate/similar issues
• Read AGENTS.md, learnings, and relevant IPC handler code
• Produce structured plan and report progress

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