@@ -181,6 +181,8 @@ Genesis supports a VSCode Remote-SSH-like workflow: a lightweight headless daemo
 
 **Design constraint — multiple remote connections:** Each SSH target gets a **unique per-target node name** (`genesis_remote_<id>@127.0.0.1`, derived from the target's slugified `id`) and a per-target systemd unit (`genesis-remote-<id>`) / launchd plist label (`com.genesis.remote.<id>`). This enables **multiple simultaneous remote connections** — each target connects to a distinct BEAM node name, so `Node.connect` can address multiple hosts. The SSH tunnel uses a dynamically-assigned local port (via `find_free_port/0`) that forwards to the remote daemon's fixed port 9000. The custom `EvoGit.EpmdDist` module maps each per-target node name to its tunnel's local port via `:persistent_term` so the VM's `port_please/2` callback resolves it correctly without an external EPMD process. The remote daemon's `RELEASE_NODE` is set per-target at launch time via `--setenv=RELEASE_NODE` (systemd-run) or an `EnvironmentVariables` dict (launchd plist), and `rel/genesis_remote/env.sh.eex` respects an existing `RELEASE_NODE` env var (`export RELEASE_NODE="${RELEASE_NODE:-...}"`).
 
+**SSH tunnel readiness (connect-path invariant)**: `RemoteConnection.do_connect_distributed/1` polls the local forwarded port for readiness (`wait_for_tunnel/4`, 100 ms interval, 10 s budget) BEFORE calling `Node.connect/1` — `ssh -L` can take >1.5 s to start listening (a fixed 500 ms settle sleep used to race it → instant `:econnrefused` → `{:error, {:node_connect_failed, ...}}` on fast-connecting hosts). The poll fails fast when the ssh Port dies, draining its output into the error; timeout/death → `{:error, {:tunnel_not_ready, reason}}`. `connect/1`'s GenServer call timeout is `@connect_call_timeout_ms` (wait budget + 15 s) so callers can't get a raw 5 s `:timeout`. Diagnostics: no remote-daemon log entry for a connect attempt ⇒ tunnel/port race (not a daemon problem); a `"Invalid challenge reply"` error ⇒ cookie mismatch. See `apps/evo_git/CONTEXT.md` for details.
+
 **Remote asset download**: `EvoGit.RemoteBootstrap.download_url/1` is deterministic and network-free, always returning the direct `https://genesis.evox.group/dl/genesis_remote_<platform>.tar.xz` URL — a Cloudflare worker "smart download" endpoint that auto-detects whether the user is in mainland China and proxies the GitHub release asset through the Cloudflare network when needed (`curl -fL`/`wget` follow redirects). **glibc is the default and ONLY published Linux variant — asset names are NEVER suffixed** (the musl build is disabled for now, so the `_glibc` suffix, the libc-probe machinery, and `effective_libc`/`detect_libc`/`probe_libc` were all removed from `EvoGit.RemoteBootstrap` / `EvoGit.RemoteConnection`; if musl is ever revived, the suffix logic must be reintroduced deliberately). The `version` in `{:ok, url, version}` is always `"latest"` (keys the local download cache). CI uploads unversioned names (`genesis_remote_<os>_<arch>.tar.xz` — build-desktop.yml; Linux tarballs come from the dedicated `build-linux-remote` job on ubuntu-22.04, darwin/windows from their platform jobs), so no asset matching is needed. **Do NOT reintroduce asset listing/matching or any suffix check** — the desktop (`genesis_desktop_*_*.tar.gz`) and remote (`genesis_remote_*_*.tar.xz`) tarballs share the `_<os>_<arch>` suffix shape, so a bare suffix match would select the wrong asset, and the API call is unnecessary. **Format**: the remote asset is `.tar.xz` (`genesis_remote_<platform>.tar.xz`, created with `tar -cJf` in CI, downloaded/extracted with `tar -xJf` on the remote host); the desktop portable archive is `.tar.gz`. All runner OSes and remote hosts (Linux/macOS) have xz-capable tar, so no fallback exists — xz failure fails loudly.
 
 ### Desktop App Build Pipeline
 
@@ -73,6 +73,10 @@ The SSH remote-bootstrap release asset is a **`.tar.xz`** archive: `genesis_remo
 
 **Linux asset variants:** glibc is the default and only published Linux variant — remote tarball names are NEVER suffixed (`genesis_remote_linux_x64.tar.xz`, `genesis_remote_linux_arm64.tar.xz`). The musl build is disabled for now. The previous libc-variant machinery was removed: `detect_libc/1` (ldd parser), `probe_libc/1` (SSH `ldd --version` probe), the private `effective_libc/2` normalization, the `_glibc` suffix in asset names/URLs/cache paths, and the `libc` params threaded through `resolve_platform` → `download_tarball` → `download_url`/`cache_path` (`resolve_platform/2` now returns `{:ok, daemon_os, platform}`). Downloads always resolve the default unsuffixed glibc asset. On NixOS hosts the glibc-only Linux asset runs via on-the-fly patchelf patching during bootstrap (`EvoGit.RemoteBootstrap.nixos_patch_script/1` + the `:patching_binaries` stage) — no new asset variants; glibc stays the only published Linux variant.
 
+### SSH Tunnel Readiness (connect-path invariant)
+
+`EvoGit.RemoteConnection.do_connect_distributed/1` must NOT call `Node.connect/1` before the SSH tunnel's local forwarded port actually accepts TCP connections. An `ssh -L <local_port>:127.0.0.1:<dist_port> -N <target>` forward can take well over a second to start listening on the local port (measured ~1.5s), and a too-early `Node.connect` fails instantly with econnrefused → `{:error, {:node_connect_failed, ...}}` with NO remote-side log entry (the dist handshake never reaches the daemon — do not hunt for cookie/EpmdDist causes when the remote log shows nothing). The connect path therefore polls local-port TCP readiness via `wait_for_tunnel/4` (`@tunnel_poll_interval_ms` 100ms, `@tunnel_wait_timeout_ms` 10s budget), fails fast when the ssh Port dies (draining its output into the error for diagnosability), and returns `{:error, {:tunnel_not_ready, reason}, state}` on timeout/death. `connect/1`'s GenServer call timeout is `@connect_call_timeout_ms` (wait budget + 15s) so callers can't exit with a raw `:timeout` while the handler is legitimately waiting. `wait_for_tunnel/4` is `@doc false` public solely so tests can drive it with tiny timeouts/poll intervals (see `test/evo_git/remote_connection_test.exs`). Remote-side rejection ("Invalid challenge reply" in the daemon journal) means a COOKIE mismatch — a different failure mode with a visible remote log entry.
+
 ## Custom Agents & Model Selection
 
 User-defined agents and per-agent model selection live in ONE file: `<config_dir>/agents.toml` (same dir as config.toml, next to `remote_connections.toml`). Per-node semantics: agents.toml is read from the config dir of the node executing the agent — local node for local tasks, remote host for tasks on an SSH remote node (the RPC edits the file on the node whose config is being edited). The scheduler has NO cached copy; `Dispatch.register_agent/7` calls `EvoGit.CustomAgents`/`EvoGit.CustomAgents.ModelSelector` directly per spawn (both are stat-validated-cache backed, so per-spawn cost is one `File.stat` + one `:persistent_term.get`).
 
@@ -82,7 +82,17 @@ defmodule EvoGit.RemoteConnection do
   @supervisor EvoGit.RemoteConnection.Supervisor
   @pubsub_topic "remote_connections"
   @heartbeat_interval_ms 10_000
-  @tunnel_settle_ms 500
+  # Wait budget for the SSH tunnel to start forwarding the local port before
+  # Node.connect. Measured need is ~1.5s (an `ssh -L` forward can take that
+  # long to start listening on the local port); a fixed 500ms sleep made
+  # Node.connect fail instantly with econnrefused on slower tunnels.
+  @tunnel_wait_timeout_ms 10_000
+  @tunnel_poll_interval_ms 100
+  # The :connect handler can legitimately block for up to @tunnel_wait_timeout_ms
+  # while the tunnel becomes ready, so the GenServer.call in connect/1 must
+  # allow that budget plus headroom (a default 5s call timeout would exit with
+  # :timeout while the handler is still waiting for the tunnel).
+  @connect_call_timeout_ms @tunnel_wait_timeout_ms + 15_000
   @launch_receive_timeout_ms 5_000
   # 900s — bootstrap now stages the release either by uploading a local tarball
   # (scp) OR by probing the remote platform and downloading the release tarball
@@ -192,7 +202,7 @@ defmodule EvoGit.RemoteConnection do
   def connect(target_id) do
     with {:ok, target} <- fetch_target(target_id),
          {:ok, pid} <- ensure_started(target) do
-      GenServer.call(pid, :connect)
+      GenServer.call(pid, :connect, @connect_call_timeout_ms)
     end
   end
 
@@ -423,42 +433,54 @@ defmodule EvoGit.RemoteConnection do
         cmd = build_tunnel_command(target, local_port, remote_port)
         port = Port.open({:spawn, cmd}, [:binary, :exit_status, :stream])
 
-        # Give the SSH tunnel time to establish.
-        Process.sleep(@tunnel_settle_ms)
-
-        # Register the SSH tunnel's local port with our EPMD-less module so
-        # that when Node.connect asks port_please for this node name, EpmdDist
-        # returns local_port (which the SSH tunnel forwards to remote_port 9000).
-        node_name = remote_node_name(target)
-        EvoGit.EpmdDist.register_target(node_name, local_port)
-
-        # The node name is just name@host — NO port suffix. The port is
-        # resolved by EpmdDist.port_please/2 via the registration above.
-        remote_node = String.to_atom(node_name)
-
-        case Node.connect(remote_node) do
-          true ->
-            ref = schedule_heartbeat()
-
-            new_state = %__MODULE__{
-              connecting
-              | phase: :connected,
-                ssh_tunnel_port: port,
-                tunnel_local_port: local_port,
-                node: Atom.to_string(remote_node),
-                heartbeat_ref: ref,
-                last_error: nil
-            }
-
-            broadcast_status(state.target, new_state)
-            {:ok, new_state}
-
-          result when result in [false, :ignored] ->
-            EvoGit.EpmdDist.unregister_target(node_name)
+        # Give the SSH tunnel time to establish: poll the local forwarded port
+        # for TCP readiness (bounded) instead of a fixed sleep — `ssh -L` can
+        # take well over a second to start listening, and a too-early
+        # Node.connect fails instantly with econnrefused.
+        case wait_for_tunnel(port, local_port, @tunnel_wait_timeout_ms,
+               poll_interval: @tunnel_poll_interval_ms
+             ) do
+          :ok ->
+            # Register the SSH tunnel's local port with our EPMD-less module so
+            # that when Node.connect asks port_please for this node name, EpmdDist
+            # returns local_port (which the SSH tunnel forwards to remote_port 9000).
+            node_name = remote_node_name(target)
+            EvoGit.EpmdDist.register_target(node_name, local_port)
+
+            # The node name is just name@host — NO port suffix. The port is
+            # resolved by EpmdDist.port_please/2 via the registration above.
+            remote_node = String.to_atom(node_name)
+
+            case Node.connect(remote_node) do
+              true ->
+                ref = schedule_heartbeat()
+
+                new_state = %__MODULE__{
+                  connecting
+                  | phase: :connected,
+                    ssh_tunnel_port: port,
+                    tunnel_local_port: local_port,
+                    node: Atom.to_string(remote_node),
+                    heartbeat_ref: ref,
+                    last_error: nil
+                }
+
+                broadcast_status(state.target, new_state)
+                {:ok, new_state}
+
+              result when result in [false, :ignored] ->
+                EvoGit.EpmdDist.unregister_target(node_name)
+                close_port(port)
+                reason = {:node_connect_failed, inspect(remote_node)}
+                new_state = %{connecting | phase: :error, last_error: format_error(reason)}
+                {:error, reason, new_state}
+            end
+
+          {:error, reason} ->
             close_port(port)
-            reason = {:node_connect_failed, inspect(remote_node)}
-            new_state = %{connecting | phase: :error, last_error: format_error(reason)}
-            {:error, reason, new_state}
+            error = {:tunnel_not_ready, reason}
+            new_state = %{connecting | phase: :error, last_error: format_error(error)}
+            {:error, error, new_state}
         end
 
       {:error, reason} ->
@@ -1348,6 +1370,80 @@ defmodule EvoGit.RemoteConnection do
     end
   end
 
+  # Waits (bounded) for the SSH tunnel's local forwarded port to accept TCP
+  # connections, so Node.connect doesn't race the `ssh -L` startup.
+  #
+  # Polls `local_port` every `poll_interval` ms (opts, default 100) until a
+  # TCP connect succeeds — the probe socket is closed immediately, which the
+  # `ssh -N` forward handles gracefully. Fails fast when the tunnel Port
+  # dies: `Port.info/1` returning nil (works regardless of the caller's
+  # trap_exit flag), a received `{:exit_status, status}`, or a received
+  # `{:EXIT, port, reason}` (only delivered to trap_exit processes). Port
+  # output (`{port, {:data, data}}`) is drained into the error reason so ssh
+  # stderr is available for diagnosability.
+  #
+  # Returns `:ok` | `{:error, reason}`:
+  #
+  #   * `{:ssh_exited, status_or_reason, ssh_output}` — tunnel port died early
+  #   * `{:timeout, ssh_output}` — budget exhausted, port still alive
+  #
+  # `@doc false`: public only so tests can drive it directly with tiny
+  # timeouts; it is an implementation detail of `do_connect_distributed/1`.
+  @doc false
+  @spec wait_for_tunnel(port(), :inet.port_number(), non_neg_integer(), keyword()) ::
+          :ok | {:error, term()}
+  def wait_for_tunnel(port, local_port, timeout_ms, opts \\ []) do
+    poll_interval = Keyword.get(opts, :poll_interval, 100)
+    wait_for_tunnel(port, local_port, timeout_ms, poll_interval, "")
+  end
+
+  defp wait_for_tunnel(port, local_port, remaining_ms, poll_interval, ssh_output) do
+    if Port.info(port) == nil do
+      {:error, {:ssh_exited, :port_info_nil, ssh_output}}
+    else
+      case tcp_ready?(local_port) do
+        :ok ->
+          :ok
+
+        :not_ready ->
+          wait = min(poll_interval, remaining_ms)
+
+          receive do
+            {^port, {:data, data}} ->
+              wait_for_tunnel(port, local_port, remaining_ms, poll_interval, ssh_output <> data)
+
+            {^port, {:exit_status, status}} ->
+              {:error, {:ssh_exited, status, ssh_output}}
+
+            {:EXIT, ^port, reason} ->
+              {:error, {:ssh_exited, reason, ssh_output}}
+          after
+            wait ->
+              remaining = remaining_ms - wait
+
+              if remaining <= 0 do
+                {:error, {:timeout, ssh_output}}
+              else
+                wait_for_tunnel(port, local_port, remaining, poll_interval, ssh_output)
+              end
+          end
+      end
+    end
+  end
+
+  defp tcp_ready?(local_port) do
+    case :gen_tcp.connect({127, 0, 0, 1}, local_port, [:inet, :binary, {:active, false}], 250) do
+      {:ok, socket} ->
+        # Readiness probe — close immediately, we only need to know the
+        # forwarded port is accepting connections.
+        :gen_tcp.close(socket)
+        :ok
+
+      {:error, _reason} ->
+        :not_ready
+    end
+  end
+
   # ── Helpers ────────────────────────────────────────────────────────
 
   defp remote_node_name(target) do