feat: add Tailscale bootstrap helpers for remote TCP setup

Author: Dimillian

README.md

@@ -13,6 +13,7 @@ CodexMonitor is a Tauri app for orchestrating multiple Codex agents across local
 - Worktree and clone agents for isolated work; worktrees live under the app data directory (legacy `.codex-worktrees` supported).
 - Thread management: pin/rename/archive/copy, per-thread drafts, and stop/interrupt in-flight turns.
 - Optional remote backend (daemon) mode for running Codex on another machine.
+- Remote setup helpers for self-hosted connectivity (Orbit actions + Tailscale detection/host bootstrap for TCP mode).
 
 ### Composer & Agent Controls
 

docs/mobile-ios-cloudflare-blueprint.md

@@ -1,11 +1,12 @@
-# CodexMonitor iOS + Orbit Cloudflare Blueprint
+# CodexMonitor iOS Remote Blueprint (Orbit + Tailscale Bootstrap)
 
-This document is the canonical implementation plan for shipping CodexMonitor on iOS using Orbit on Cloudflare as the relay/control plane to a macOS runner.
+This document is the canonical implementation plan for shipping CodexMonitor on iOS with a Tailscale-first bootstrap path and Orbit on Cloudflare as the production relay/control plane to a macOS runner.
 
 ## Scope
 
 - Build and ship a real iOS app (Tauri mobile target).
 - Keep macOS as the execution host (Codex binary, repos, git, terminals, files).
+- Provide a low-friction self-host bootstrap path via Tailscale + TCP daemon for early end-to-end mobile testing.
 - Use Orbit on Cloudflare as secure relay/realtime bridge between iOS and macOS.
 - Make macOS setup manageable from CodexMonitor Settings: authenticate, pair device, launch/stop runner, inspect status/logs.
 - Keep one backend logic path (shared core + daemon). Do not duplicate backend behavior in iOS UI.
@@ -53,6 +54,10 @@ This document is the canonical implementation plan for shipping CodexMonitor on
   - `terminal-exit`
 - Mobile UI scope is the existing app layout in mobile form-factor (no separate mobile-only feature surface).
 - Shared-core parity refactor is in place for prompts, local usage, codex utility helpers, git/github UI helpers, and workspace actions.
+- Tailscale setup helper is implemented for TCP remote mode:
+  - Desktop command: `tailscale_status`
+  - Desktop command: `tailscale_daemon_command_preview`
+  - Settings UI helpers: detect Tailscale, use suggested tailnet host, show daemon launch command template
 - Daemon RPC parity for the current mobile scope is complete.
 - `terminal_*` and `dictation_*` command parity are intentionally out of scope for this mobile phase.
 
@@ -70,14 +75,20 @@ This document is the canonical implementation plan for shipping CodexMonitor on
 - Maintains outbound connection to Orbit.
 - Receives JSON-RPC from Orbit and returns results/events.
 
-3. Orbit Cloud Services
+3. Tailscale Tailnet (Bootstrap Path)
+- iOS and macOS join the same user-managed tailnet.
+- iOS connects directly to daemon TCP endpoint over tailnet (`remoteBackendProvider=tcp`).
+- No hosted CodexMonitor service required.
+
+4. Orbit Cloud Services
 - Auth service (passkey + JWT/session).
 - Orbit relay (Worker + Durable Object routing + event persistence endpoint).
 - User-owned self-host deployment path only.
 
 ## Canonical Protocol Choice
 
 - Use Orbit JSON-RPC relay model plus Orbit control messages (`orbit.subscribe`, `orbit.unsubscribe`, `orbit.list-anchors`, keepalive ping/pong).
+- For Tailscale bootstrap mode, continue using existing TCP JSON-RPC over tailnet (`remoteBackendProvider=tcp`) with token auth.
 - Do not introduce a second custom transport protocol for this phase.
 - Reconnection/resync should use Orbit thread event history endpoint and thread resume flows.
 
@@ -249,6 +260,10 @@ Update `src/features/settings/components/SettingsView.tsx` to add an Orbit secti
 Required controls:
 
 - Provider selector (`TCP daemon` / `Orbit`)
+- TCP + Tailscale helpers:
+  - `Detect Tailscale`
+  - `Use suggested host`
+  - daemon launch command template
 - Orbit WS URL input
 - Orbit Auth URL input
 - Runner name input
@@ -265,6 +280,7 @@ Current implementation status:
 
 - Implemented now:
   - Provider selector
+  - TCP Tailscale helper controls (`Detect Tailscale`, suggested host, daemon command template)
   - Orbit WS/Auth URL inputs
   - Runner name input
   - Access toggle + client id/secret ref fields
@@ -299,6 +315,24 @@ UX behavior:
 
 ## User Setup Flows
 
+## Tailscale Bootstrap (Implemented)
+
+Desktop setup:
+
+1. Install Tailscale and sign into the same tailnet on desktop and iPhone.
+2. In CodexMonitor Settings, set `Backend Mode = Remote`, `Provider = TCP`.
+3. Click `Detect Tailscale` and then `Use suggested host`.
+4. Set a `Remote backend token`.
+5. Copy the generated daemon command template and run it on desktop.
+6. Use the same host/token in mobile app remote settings.
+
+Mobile setup:
+
+1. Install and sign into Tailscale on iOS.
+2. Open CodexMonitor iOS app.
+3. Set remote provider to TCP and enter tailnet host + token from desktop setup.
+4. Connect and validate thread list + messaging.
+
 ## Self-Hosted Orbit
 
 Desktop setup:

memory/decisions.md

@@ -267,3 +267,10 @@ Type: decision
 Event: Product direction is now self-hosted Orbit only; app should not present hosted Orbit mode or imply CodexMonitor-hosted relay/auth services.
 Action: Removed `orbitDeploymentMode` from frontend/backend settings models and defaults, removed deployment mode selector from Settings UI, and updated mobile Orbit blueprint/setup language to self-host-only.
 Rule: Keep Orbit setup/docs/UI self-host-only unless user explicitly requests reintroducing hosted mode.
+
+## 2026-02-07 20:48
+Context: Tailscale bootstrap path for mobile remote onboarding
+Type: decision
+Event: Added end-to-end Tailscale setup support so users can self-host remote TCP access before iOS Orbit UX is finalized.
+Action: Implemented desktop `tailscale_status` and `tailscale_daemon_command_preview` commands, wired Settings helpers (detect, suggested host, daemon command), and updated blueprint docs to include the Tailscale bootstrap flow.
+Rule: Keep Tailscale as the first-run self-host bootstrap path for TCP remote setup while Orbit remains the production relay path.

memory/mistakes.md

@@ -81,3 +81,33 @@ Rule: Any settings update that changes remote transport config must invalidate t
 Root cause: Remote client cache lifecycle was only tied to disconnect/errors, not to transport settings mutations.
 Fix applied: Updated `src-tauri/src/settings/mod.rs` to compare previous vs updated transport settings and reset cached remote backend when they differ; added predicate unit tests.
 Prevention rule: Treat transport-config settings as cache keys and invalidate on change at the backend boundary, not only from UI handlers.
+
+## 2026-02-07 20:36
+Context: Orbit token sync persistence retry behavior in Settings
+Type: mistake
+Event: `syncRemoteBackendToken` updated `latestSettingsRef` before settings persistence succeeded, so a failed save could make later retries no-op.
+Action: Moved `latestSettingsRef` mutation to after successful `onUpdateAppSettings` completion and added a regression test for retry-after-failure.
+Rule: In async settings flows, only advance local "latest" refs after persistence succeeds.
+Root cause: Optimistically mutating in-memory settings state before awaiting durable save.
+Fix applied: Updated `src/features/settings/components/SettingsView.tsx` token sync ordering and added `retries Orbit token persistence after a failed save` in `src/features/settings/components/SettingsView.test.tsx`.
+Prevention rule: Keep optimistic UI drafts separate from persisted-settings refs and add explicit retry-path tests for async save failures.
+
+## 2026-02-07 21:01
+Context: Tailscale settings helper token preview freshness
+Type: mistake
+Event: Tailscale daemon command preview did not auto-refresh after remote token changes, leaving `tokenConfigured` warning state stale until manual refresh.
+Action: Added `appSettings.remoteBackendToken` as a dependency of the auto-refresh effect in `SettingsView` so preview data is recomputed after token edits.
+Rule: Any derived helper output that depends on settings values must include those values in effect dependencies (or equivalent invalidation paths).
+Root cause: The effect dependency list tracked provider/mode only and omitted token changes used by preview generation.
+Fix applied: Updated `src/features/settings/components/SettingsView.tsx` effect dependencies and revalidated `SettingsView` tests.
+Prevention rule: When adding helper panels, explicitly audit dependency arrays against all backend inputs shown in that panel (especially token/auth state).
+
+## 2026-02-07 21:03
+Context: Tailscale helper auto-preview on mobile
+Type: mistake
+Event: Settings auto-fetched desktop-only Tailscale daemon command preview on mobile, creating immediate unsupported-error noise.
+Action: Added `isMobilePlatform` helper and gated auto preview fetch in `SettingsView` to desktop platforms only.
+Rule: Do not auto-run desktop-only diagnostics on mobile surfaces; gate by platform first.
+Root cause: Auto-refresh effect was scoped by provider/mode only and assumed desktop capabilities.
+Fix applied: Updated `src/features/settings/components/SettingsView.tsx` effect logic and added `src/utils/platformPaths.test.ts` coverage for mobile detection.
+Prevention rule: For any auto-run settings helper, explicitly classify desktop-only vs cross-platform behavior before wiring useEffect refreshes.

memory/todo.md

@@ -4,6 +4,7 @@
 - [ ] 2026-02-07: Implement Orbit-only mobile remote foundation: Orbit transport in `remote_backend`, runner Orbit mode, self-host settings + pairing UX, and iOS keychain-backed auth storage.
 - [ ] 2026-02-07: Harden Orbit WS transport with explicit reconnect/backoff + replay/resync handling for mobile reconnect flows.
 - [ ] 2026-02-07: Complete Orbit production readiness gaps after baseline wiring: secure secret storage (Keychain/keyring), LaunchAgent/background runner management, pairing QR/code UX, and app-side Orbit reconnect/resync handling.
+- [ ] 2026-02-07: Build iOS-side remote onboarding UI that can consume the new Tailscale bootstrap outputs (status hints + daemon command + host/token handoff).
 
 ## Done
 - [x] 2026-02-07: Restored Sentry frontend reporting removed in `83a37da` (`@sentry/react`, `Sentry.init`, captureException callsites, and metrics instrumentation).
@@ -18,3 +19,4 @@
 - [x] 2026-02-07: Implement Cloudflare WebSocket transport internals behind `remoteBackendProvider=cloudflare` (connect/read/write/pending-response flow) while preserving TCP behavior and callsites.
 - [x] 2026-02-07: Migrate remote provider naming/settings from Cloudflare-specific keys to Orbit (`orbit` provider + `orbit*` settings).
 - [x] 2026-02-07: Remove unreleased Cloudflare backward-compat aliases and backport tests to keep Orbit implementation canonical-only.
+- [x] 2026-02-07: Add Tailscale bootstrap support for remote TCP setup (desktop status detection + suggested host + daemon command preview + settings/docs wiring).

src-tauri/src/daemon_binary.rs

@@ -0,0 +1,40 @@
+use std::path::PathBuf;
+
+pub(crate) fn daemon_binary_candidates() -> &'static [&'static str] {
+    if cfg!(windows) {
+        &["codex_monitor_daemon.exe", "codex-monitor-daemon.exe"]
+    } else {
+        &["codex_monitor_daemon", "codex-monitor-daemon"]
+    }
+}
+
+pub(crate) fn resolve_daemon_binary_path() -> Result<PathBuf, String> {
+    let current_exe = std::env::current_exe().map_err(|err| err.to_string())?;
+    let parent = current_exe
+        .parent()
+        .ok_or_else(|| "Unable to resolve executable directory".to_string())?;
+    let candidate_names = daemon_binary_candidates();
+
+    for name in candidate_names {
+        let candidate = parent.join(name);
+        if candidate.is_file() {
+            return Ok(candidate);
+        }
+    }
+
+    Err(format!(
+        "Unable to locate daemon binary in {} (tried: {})",
+        parent.display(),
+        candidate_names.join(", ")
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::daemon_binary_candidates;
+
+    #[test]
+    fn daemon_binary_candidates_prioritize_underscored_name() {
+        assert!(daemon_binary_candidates()[0].starts_with("codex_monitor_daemon"));
+    }
+}

src-tauri/src/lib.rs

@@ -4,6 +4,7 @@ use tauri::{RunEvent, WindowEvent};
 
 mod backend;
 mod codex;
+mod daemon_binary;
 mod dictation;
 mod event_sink;
 mod files;
@@ -20,6 +21,7 @@ mod settings;
 mod shared;
 mod state;
 mod storage;
+mod tailscale;
 mod terminal;
 mod types;
 mod utils;
@@ -174,7 +176,9 @@ pub fn run() {
             orbit::orbit_sign_out,
             orbit::orbit_runner_start,
             orbit::orbit_runner_stop,
-            orbit::orbit_runner_status
+            orbit::orbit_runner_status,
+            tailscale::tailscale_status,
+            tailscale::tailscale_daemon_command_preview
         ])
         .build(tauri::generate_context!())
         .expect("error while running tauri application");

src-tauri/src/orbit/mod.rs

@@ -1,9 +1,9 @@
-use std::path::PathBuf;
 use std::process::Stdio;
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use tauri::State;
 
+use crate::daemon_binary::resolve_daemon_binary_path;
 use crate::shared::orbit_core;
 use crate::shared::process_core::{kill_child_process_tree, tokio_command};
 use crate::shared::settings_core;
@@ -20,45 +20,6 @@ fn now_unix_ms() -> i64 {
         .unwrap_or(0)
 }
 
-fn daemon_binary_candidates() -> &'static [&'static str] {
-    if cfg!(windows) {
-        &["codex_monitor_daemon.exe", "codex-monitor-daemon.exe"]
-    } else {
-        &["codex_monitor_daemon", "codex-monitor-daemon"]
-    }
-}
-
-fn resolve_daemon_binary_path() -> Result<PathBuf, String> {
-    let current_exe = std::env::current_exe().map_err(|err| err.to_string())?;
-    let parent = current_exe
-        .parent()
-        .ok_or_else(|| "Unable to resolve executable directory".to_string())?;
-    let candidate_names = daemon_binary_candidates();
-
-    for name in candidate_names {
-        let candidate = parent.join(name);
-        if candidate.is_file() {
-            return Ok(candidate);
-        }
-    }
-
-    Err(format!(
-        "Unable to locate daemon binary in {} (tried: {})",
-        parent.display(),
-        candidate_names.join(", ")
-    ))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::daemon_binary_candidates;
-
-    #[test]
-    fn daemon_binary_candidates_prioritize_underscored_name() {
-        assert!(daemon_binary_candidates()[0].starts_with("codex_monitor_daemon"));
-    }
-}
-
 async fn refresh_runner_runtime(runtime: &mut OrbitRunnerRuntime) {
     let Some(child) = runtime.child.as_mut() else {
         runtime.status.state = OrbitRunnerState::Stopped;