Continued WireGuard troubleshooting

Docs/Codex/WireGuard_Troubleshooting.md

@@ -0,0 +1,106 @@
+# Borealis WireGuard Troubleshooting Handoff
+
+This file is a self-contained handoff prompt + context for a new Codex agent to resume WireGuard tunnel troubleshooting.
+
+## Prompt to Use in a New Codex Session
+
+Copy/paste the prompt below into a new Codex chat:
+
+"""
+You are a new Codex agent working in d:\Github\Borealis. Please do the following:
+
+1) Read AGENTS.md, Docs/Codex/BOREALIS_AGENT.md, Docs/Codex/BOREALIS_ENGINE.md, Docs/Codex/REVERSE_TUNNELS.md, then Docs/Codex/WireGuard_Troubleshooting.md.
+2) Investigate why the WireGuard tunnel does not come up (remote shell timeouts) even though the Engine emits vpn_tunnel_start.
+3) Focus on the WireGuard client lifecycle in Data/Agent/Roles/role_WireGuardTunnel.py and the bootstrap logic in Borealis.ps1 (WireGuard adapter provisioning).
+4) Use Data/Agent for edits (runtime under Agent/ is ephemeral). Keep the adapter name "Borealis" and ensure idempotent behavior. Do not rely on the PIA adapter.
+5) Provide concrete fixes + verification steps. Be careful with Windows services and avoid GUI popup dialogs when possible.
+"""
+
+## Environment / Scope
+
+- Workspace: d:\Github\Borealis
+- Host OS: Windows 10/11 (build 26200). Current tests run on the Windows 11 machine that also runs Engine + Agent.
+- Agent/Engine launch: via Borealis.ps1, always elevated as admin.
+- Network: Engine + Agent run on the same host during testing (Engine endpoint is "localhost:30000").
+- WireGuard version: wireguard.exe 0.5.3, wg.exe 1.0.20210914.
+- PIA (Private Internet Access) is installed and supplies a wintun driver (pia-wintun.sys). Do NOT treat the PIA adapter as the Borealis adapter.
+
+## Desired Behavior
+
+- Agent has a dedicated WireGuard adapter named "Borealis" (Description shows "WireGuard Tunnel").
+- Adapter provisioning is idempotent: if "Borealis" exists, do not recreate it.
+- WireGuard config should be stored under Agent\Borealis\Settings\WireGuard\Borealis.conf (preferred) and not only in Program Files.
+- Agent should bring up the WireGuard tunnel on vpn_tunnel_start, then remote shell / RDP / VNC / SSH should flow through it.
+- On stop/idle, the tunnel should be torn down and firewall rules removed.
+
+## Recent Changes (Current Repo State)
+
+- Data/Agent/Roles/role_WireGuardTunnel.py
+  - Service name fix: WireGuard tunnel service is "WireGuardTunnel$Borealis".
+  - Config path preference: Agent\Borealis\Settings\WireGuard.
+  - Uses registry ImagePath to locate the actual service config when needed.
+  - Adds a session lock to prevent concurrent start/stop.
+- Borealis.ps1
+  - WireGuard config search order includes Agent\Borealis\Settings\WireGuard.
+  - Adapter provisioning reads the service ImagePath to write config when service exists.
+  - Avoids /installtunnelservice if service still present to prevent GUI error dialogs.
+  - Adapter name is "Borealis".
+
+Note: Data/Agent changes only apply to runtime after Borealis.ps1 re-stages the agent under Agent/.
+
+## Symptoms from Fresh Logs (2026-01-12 19:29)
+
+Agent (Agent/Logs/VPN_Tunnel/tunnel.log):
+- "WireGuard tunnel service already installed; skipping install."
+- "WireGuard tunnel service still missing after install attempt."
+
+Engine (Engine/Logs/VPN_Tunnel/tunnel.log):
+- vpn_tunnel_session_create for agent LAB-OPERATOR-01_..._SYSTEM
+- WireGuard listener installed (service=borealis-wg)
+- vpn_api_status_response status=up
+
+Engine (Engine/Logs/VPN_Tunnel/remote_shell.log):
+- repeated vpn_shell_connect_attempt to 10.255.0.2:47002
+- timeouts
+
+Agent (Agent/Logs/VPN_Tunnel/remote_shell.log):
+- VPN shell server listening on 0.0.0.0:47002
+
+Net effect: engine believes tunnel is "up", but remote shell cannot reach 10.255.0.2. This implies the WireGuard client tunnel is not actually up on the agent.
+
+## Key Paths
+
+- Agent WireGuard role: Data/Agent/Roles/role_WireGuardTunnel.py
+- Agent VPN shell role: Data/Agent/Roles/role_VpnShell.py
+- Engine WireGuard manager: Data/Engine/services/VPN/wireguard_server.py
+- Engine tunnel service: Data/Engine/services/VPN/vpn_tunnel_service.py
+- Agent tunnel logs: Agent/Logs/VPN_Tunnel/tunnel.log
+- Agent shell logs: Agent/Logs/VPN_Tunnel/remote_shell.log
+- Engine tunnel logs: Engine/Logs/VPN_Tunnel/tunnel.log
+- Engine shell logs: Engine/Logs/VPN_Tunnel/remote_shell.log
+- Agent WireGuard config: Agent/Borealis/Settings/WireGuard/Borealis.conf
+
+## Known WireGuard Services / Names
+
+- Engine listener service name: "borealis-wg"
+- Agent tunnel service name: "WireGuardTunnel$Borealis"
+- Adapter name in Control Panel: "Borealis"
+
+## Suggested Verification Commands
+
+- Check agent service:
+  - Get-Service -Name "WireGuardTunnel$Borealis"
+  - Get-ItemProperty "HKLM:\\SYSTEM\\CurrentControlSet\\Services\\WireGuardTunnel$Borealis" | Select-Object ImagePath
+- Confirm adapter exists:
+  - Get-NetAdapter -IncludeHidden | Where-Object { $_.InterfaceDescription -like "*WireGuard*" } | Select-Object Name, Status, InterfaceDescription, ifIndex
+- Check WireGuard state:
+  - "C:\\Program Files\\WireGuard\\wg.exe" show
+
+## Troubleshooting Focus Areas
+
+- Ensure runtime is up-to-date (Borealis.ps1 re-staging Data/Agent -> Agent/).
+- Validate service detection vs. WireGuard install output (sc.exe vs registry).
+- Confirm the config file used by the service matches Agent/Borealis/Settings/WireGuard/Borealis.conf.
+- Confirm /installtunnelservice is not invoked when service already exists (avoid WireGuard GUI errors).
+- Confirm the WireGuard tunnel actually connects (wg.exe show handshake) before attempting remote shell.
+