Wave 9 #122.d.iii — Phase 6 Tailscale self-test (Gate E 'tunnel works both ways')

connections/remote-access/connection.yml

@@ -444,6 +444,51 @@ wizard:
       setup_notes: |
         Skip remote access entirely — your van stays reachable only on home Wi-Fi.
 
+    # Connectivity self-test (Wave 9 #122.d.iii — Gate E "tunnel works
+    # both ways" check). This entry is separate from the four remote-
+    # access paths above (A/B/C/D); it doesn't pick a path, it verifies
+    # that the chosen path is honestly working two-way. The operator
+    # types their tunnel URL once, taps Run now, and the package runs
+    # an outbound probe (Hub → tunnel URL via magicdns) + an inbound
+    # probe (simulated phone callback carrying a one-time nonce back
+    # through the tunnel) and reports the round-trip result in plain
+    # English. Tier-b recipe over the HA core `tailscale` integration
+    # + two shell_command probes with 10-second timeouts.
+    - id: self_test
+      label: "Tailscale tunnel self-test (one-tap two-way check — recommended after setup)"
+      connection_kind: recipe
+      tier: b
+      recipe_over: "HA core `tailscale` integration (since 2022.x — exposes the upstream `binary_sensor.tailscale_*` entities + `device_tracker.tailscale_*` entities) + two `shell_command` probes (10s timeouts) with file-based nonce round-trip verification"
+      estimated_time: "~1 min"
+      requires_reboot: false
+      requires_inputs:
+        - "Tailscale tunnel URL (e.g. https://my-van.ts.net)"
+      side_effects:
+        - registers_tailscale_self_test_tunnel_url_input_text_password_mode
+        - registers_tailscale_self_test_running_input_boolean
+        - registers_tailscale_run_self_test_input_button
+        - registers_tailscale_self_test_last_run_input_datetime
+        - registers_tailscale_self_test_outbound_probe_shell_command_10s_timeout
+        - registers_tailscale_self_test_inbound_probe_shell_command_10s_timeout
+        - registers_tailscale_self_test_outbound_ok_binary_sensor
+        - registers_tailscale_self_test_inbound_ok_binary_sensor
+        - registers_tailscale_self_test_ok_binary_sensor
+        - registers_tailscale_self_test_recovery_binary_sensor
+        - registers_tailscale_self_test_status_sensor_plain_english
+        - registers_tailscale_self_test_run_automation_button_event_stage
+        - registers_tailscale_self_test_recovery_automation_60s_timeout
+        - registers_tailscale_self_test_wizard_advance_automation_on_round_trip_success
+        - surfaces_persistent_notification_on_recovery_with_run_wizard_from_inside_van_guidance
+        - surfaces_persistent_notification_on_wizard_advance_with_van_reachable_from_anywhere
+      setup_notes: |
+        One-tap check that proves your tunnel works in both directions —
+        not just that the dashboard loads (a stale tunnel can still serve
+        a cached page). Type your tunnel address once, tap Run now, and
+        the dashboard tells you honestly whether your van is really
+        reachable from anywhere. Recovery is automatic — if the check
+        times out, the dashboard shows plain-English guidance instead
+        of dropping you into a manual recovery.
+
 install:
   ha_integration_domain: tailscale
   config_flow: true

docs/setup/tailscale-self-test.md

@@ -0,0 +1,74 @@
+# Checking that your Tailscale tunnel works both ways
+
+If you've already set up Tailscale so you can reach your van from anywhere, this guide shows you how to confirm — in one tap — that the tunnel is really working two ways (not just that the dashboard loads).
+
+## 1. What this is
+
+Tailscale is what lets you open your RoamCore dashboard from your phone when you're far away — coffee shops, trailheads, your house. Once it's set up, you should be able to open the dashboard from anywhere and see the same screen you'd see sitting inside the van. This page is a one-tap check that proves the tunnel really works in both directions: from your van out to your phone, and from your phone back to your van. A tunnel that's only working one way can still serve a cached dashboard page, which is why "the page loads" isn't the same thing as "I can reach my van." The check runs two probes — one going out from the van, one simulating your phone coming back — and tells you honestly whether both directions work.
+
+## 2. What you see
+
+When you open the **Tunnel self-test** card on your dashboard, you'll see one of these messages:
+
+- **"Type your tunnel address to run a check."** — You haven't entered your tunnel address yet. Type it once below (it looks like `https://my-van.ts.net`).
+- **"Ready to check your tunnel — tap Run now."** — Your tunnel address is entered, but the check hasn't run yet. Tap **Run now** to start it.
+- **"Checking your tunnel — one moment..."** — The check is running. It takes about 30 seconds.
+- **"Round-trip succeeded — your tunnel is two-way."** — Both directions work. You're good to reach your van from anywhere.
+- **"Hub can't reach itself through the tunnel — check your Tailscale ACL."** — The van couldn't reach itself going out through the tunnel. Your Tailscale ACL rules may be blocking the address.
+- **"Phone-side callback didn't arrive — check the tunnel URL."** — The van reached itself, but the simulated "phone-side" callback didn't make it back. The tunnel address you typed may be wrong.
+
+You'll also see a **Run now** button and a box to type your tunnel address (it hides what you type so no one looking over your shoulder can see it). You can re-tap **Run now** any time to re-check — your tunnel address stays in the box.
+
+## 3. What you do
+
+Follow these three steps, in order. Stop when you're done.
+
+1. **Find your tunnel address.** Sign in to Tailscale on any device — your tailnet hostname is listed at the top of the page. It usually looks like `my-van.ts.net`. The full address you type is `https://` followed by that hostname.
+2. **Type your tunnel address into the box on the Tunnel self-test card.** The box hides what you type so no one looking over your shoulder can see it. Make sure you include `https://` at the start and the `.ts.net` at the end.
+3. **Tap Run now.** Wait about 30 seconds. The message at the top of the card will change from "Checking your tunnel..." to one of the four end-state messages. If it says "Round-trip succeeded", you're good — open your phone's browser and try typing your tunnel address to see your dashboard.
+
+You can re-tap **Run now** any time to re-check. Your tunnel address stays in the box, so you don't need to re-type it.
+
+## 4. What to do if it goes wrong
+
+Three things can go sideways, and each one has a plain-English fix.
+
+- **"Hub can't reach itself through the tunnel — check your Tailscale ACL."** This means the van couldn't reach itself going out through the tunnel. The most common cause is a Tailscale ACL rule that blocks MagicDNS or your tailnet hostname. Open your Tailscale admin console, check the ACL page, and make sure the rule for your tailnet allows MagicDNS. If you're not sure what to change, leave the rule alone and try again in a few minutes — Tailscale sometimes takes a moment to apply changes.
+
+- **"Phone-side callback didn't arrive — check the tunnel URL."** This means the van reached itself, but the simulated "phone-side" callback didn't make it back through the tunnel. The most common cause is a typo in the tunnel address you typed. Re-check the address: it should start with `https://` and end with `.ts.net`, with no extra path or trailing slash. If you've typed it right and it still fails, your tunnel may be partially down — restart the Tailscale add-on from the Home Assistant **Settings → Add-ons** page.
+
+- **The check stays on "Checking your tunnel..." for more than a minute.** The dashboard will surface a notification saying "Your Tailscale tunnel can't be reached both ways." That's the dashboard telling you the check timed out. Tap **Run now** to try again — the dashboard will retry on its own with the same tunnel address.
+
+If none of those fix it, the easiest reset is to restart the Tailscale add-on (open Home Assistant on your phone or laptop, go to **Settings → Add-ons**, find Tailscale, and tap **Restart**). Then tap **Run now** on the Tunnel self-test card to re-check. Your tunnel address stays in the box, so you don't need to re-type it.
+
+## 5. Useful links
+
+- [Checking your van from anywhere (Tailscale setup)](./guided-remote-access.md) — how to set up Tailscale for the first time, if you haven't yet.
+- [Reaching your van from your phone on the same WiFi](./local-access-fallback.md) — what to do if your tunnel is down and you're near the van.
+- [Tailscale admin console](https://login.tailscale.com/admin) — where you find your tailnet hostname and check ACL rules.
+- [RoamCore Home Assistant setup](../setup.md) — the main setup walkthrough.
+
+You can come back to the Tunnel self-test card any time to re-check your tunnel or to see whether your tunnel address is still set correctly.
+
+---
+
+## What you might hear us call it (operator → vanlifer)
+
+Sometimes we use technical words. Here's what they mean in plain English.
+
+| Operator calls it | You might call it |
+| --- | --- |
+| Self-test | A check that runs on its own to confirm something is working. |
+| Round-trip | Going out and coming back. A round-trip means both directions work. |
+| Outbound probe | A check that goes from your van out to your phone. |
+| Inbound probe | A check that comes from your phone back to your van. |
+| MagicDNS | The friendly hostname Tailscale gives your van (it ends in `.ts.net`). |
+| ACL rules | The list of who's allowed to talk to whom on your tailnet. |
+| Tunnel | The private connection between your van and your phone. |
+| Tailscale | The piece of software that makes the tunnel work. |
+| Two-way | Both directions — from your van to your phone, and from your phone to your van. |
+| Persistent notification | A message that stays at the top of the dashboard until you dismiss it. |
+| `input_button` | A button on your dashboard. |
+| `input_text` | A text field on your dashboard. |
+| Template sensor | A status reading that updates on its own. |
+| Automation | A rule that runs on its own when something happens. |

homeassistant/packages/roamcore_setup_wizard.yaml

@@ -249,3 +249,22 @@ automation:
         data:
           title: "Remote access done"
           message: "Remote access is set up — moving on to the next setup step."
+
+  # Mount the Tailscale self-test trigger (Wave 9 #122.d.iii — Phase 6
+  # Gate E "tunnel works both ways" check). When the Remote Access Setup
+  # wizard reaches `tailscale_done` (operator has finished setting up
+  # Tailscale), this automation fires the `rc_run_tailscale_self_test`
+  # event so the self-test package runs its outbound + inbound probes.
+  # The self-test then advances `rc_setup_stage` past `networking` via
+  # §8.T.3 if the round-trip succeeds. Idempotent: re-firing the event
+  # does NOT reset the tunnel URL or the operator's wizard progress.
+  - id: rc_setup_trigger_tailscale_self_test_after_done
+    alias: "RC: Setup — Trigger Tailscale self-test after wizard done"
+    mode: single
+    trigger:
+      - platform: state
+        entity_id: input_select.rc_remote_access_setup_stage
+        to: tailscale_done
+    action:
+      - event: rc_run_tailscale_self_test
+        event_data: {}