1 files changed, 23 insertions, 2 deletions

diff --git a/src/btftunnel.h b/src/btftunnel.h
index 24a7509..3cc87cd 100644
--- a/src/btftunnel.h
+++ b/src/btftunnel.h
@@ -36,12 +36,33 @@ namespace btf
 // Initialize (sockets + libsodium). Idempotent.
 bool TunnelInit();
 
+// Which stage of BtfClientTunnel failed. INVALID_SOCKET alone says only "no
+// tunnel"; a caller that then guesses at causes in its log line sends whoever
+// reads it to the wrong component (issue #17: "relay unreachable or pool not
+// listening" blamed two healthy parts). The stage is what this side actually
+// knows -- report that.
+enum TunnelFail
+{
+    TUNNEL_FAIL_NONE = 0,
+    TUNNEL_FAIL_INIT,      // local socket/crypto init failed
+    TUNNEL_FAIL_DIAL,      // TCP connect to the meeting node failed
+    TUNNEL_FAIL_REFUSED,   // relay reachable, but no service registered under the pubkey
+    TUNNEL_FAIL_PAIR,      // relay connection died before pairing completed
+    TUNNEL_FAIL_HANDSHAKE, // end-to-end channel handshake failed
+    TUNNEL_FAIL_LOCAL,     // local pump plumbing (socket pair / threads) failed
+};
+
+// Short description of a TunnelFail for log lines.
+const char* TunnelFailText(TunnelFail f);
+
 // Client: dial the service registered under `target_pubkey` at the meeting node
 // (host:port), box to its static x25519 `service_enc_pub`, and return a local
-// plaintext SOCKET tunneled end-to-end to the service. INVALID_SOCKET on error.
+// plaintext SOCKET tunneled end-to-end to the service. INVALID_SOCKET on error
+// -- with `pFail`, if given, naming the stage that failed.
 btf_socket_t BtfClientTunnel(const char* meeting_host, unsigned short port,
                              const unsigned char target_pubkey[32],
-                             const unsigned char service_enc_pub[32]);
+                             const unsigned char service_enc_pub[32],
+                             TunnelFail* pFail = 0);
 
 // Service: wrap an already-paired rendezvous socket (RvServiceRegister followed
 // by RvServiceWaitPaired -- the pairing byte MUST already be consumed) with