From 8af501877619382d701bc89831b695e8e8c8a6c4 Mon Sep 17 00:00:00 2001
From: codex <codex@local>
Date: Mon, 24 Aug 2026 22:30:36 +0200
Subject: [PATCH] docs(recovery): record proposed tunnels.yaml changes for
 CUST-WP-0067-T02

The bridge config lives outside any repo and could not be edited from the
session. Captures the two health-check defects and the reverse-relay
retirement, with the sequencing constraint that remote agents must be
repointed before the relay entries are removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...nels-yaml-proposed-changes-CUST-WP-0067.md | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/recovery/tunnels-yaml-proposed-changes-CUST-WP-0067.md

diff --git a/docs/recovery/tunnels-yaml-proposed-changes-CUST-WP-0067.md b/docs/recovery/tunnels-yaml-proposed-changes-CUST-WP-0067.md
new file mode 100644
index 0000000..b7b3049
--- /dev/null
+++ b/docs/recovery/tunnels-yaml-proposed-changes-CUST-WP-0067.md
@@ -0,0 +1,58 @@
+# Proposed `~/.config/bridge/tunnels.yaml` changes — CUST-WP-0067-T02
+
+Claude could not edit this file (outside any repo; blocked by the permission
+classifier). Apply manually or grant the write. **Back up first:**
+
+```bash
+cp ~/.config/bridge/tunnels.yaml ~/.config/bridge/tunnels.yaml.bak-$(date +%Y%m%d%H%M%S)
+```
+
+## 1. `state-hub-primary` — health check probes the wrong thing
+
+Its `local_port: 8000` is already correct and needs no change. The health check
+does:
+
+```yaml
+    health_check:
+-     url: http://127.0.0.1:8000/state/health
++     url: http://127.0.0.1:8000/state/health   # correct only now that no local hub binds 8000
+```
+
+No edit required today, but note *why* it read healthy for seven weeks: it
+probed the local cache, not the tunnel it opened on `[::1]:8000`. A tunnel
+health check that can be satisfied by a different process is not a health check.
+Prefer probing through the tunnel's own bind address once instance identity
+lands (T03).
+
+## 2. `state-hub-mcp-railiance01` — probes the wrong port
+
+Forwards `:8001`, probes `:8000`:
+
+```yaml
+  state-hub-mcp-railiance01:
+    health_check:
+-     url: http://127.0.0.1:8000/state/health
++     url: http://127.0.0.1:8001/state/health
+```
+
+## 3. Reverse relay tunnels — retire
+
+```yaml
+-  state-hub-railiance01:      # -R 18000 -> workstation:8000
+-  state-hub-mcp-railiance01:  # -R 18001 -> workstation:8001
+```
+
+Both make a remote box dial back into this workstation to reach a hub. That was
+correct when the workstation *was* the hub. It is not: the primary runs on
+railiance01, so an agent there currently routes
+`localhost:18000 -> workstation:8000 -> jump host -> 10.43.68.154:8000` to reach
+a service on its own machine.
+
+**Before removing**, repoint remote agents. On railiance01 the primary is
+reachable in-cluster with no tunnel at all — this is where "abandon tunneling"
+genuinely applies. The global agent instructions' remote port map
+(`State Hub API http://127.0.0.1:18000`) must be updated in the same change, or
+remote sessions will silently lose the hub.
+
+Sequencing: repoint remote agents and update the port map first, then remove
+these two entries. Removing them first breaks every remote session.