fix(agent): Windows installer host detection works from Git Bash

The one-liner failed from Git Bash with "no cluster host detected": the installer read the host off the live ssh process's command line, which is unreadable when that ssh is Git's MSYS build. Accept it explicitly via $env:PLUG_HOST/PLUG_PORT (the native Windows OpenSSH client is still auto-detected). Also make Die actually stop the script — a piped `powershell -Command -` ignored the old exit, so plug.exe could fail yet the script ran on and copied wintun.dll — and rewrite the README Windows section assuming Git for Windows.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: hhfrancois

README.md

@@ -164,28 +164,41 @@ use its FQDN (`myservice.othernamespace`). See [deploy/README.md](deploy/README.
 
 ## Windows
 
-Native Windows is supported (no WSL2 needed). Install straight from the cluster,
-one line — same model as unix, just piped into PowerShell instead of `sh`:
+Native Windows is supported (no WSL2 needed). You need an `ssh` client; this guide
+**assumes [Git for Windows](https://git-scm.com/download/win) is installed** — it
+ships both `ssh` and Git Bash, which nearly every Windows dev already has. (Windows'
+built-in OpenSSH client works too — see the note below.)
 
-```powershell
+**1. Install — from Git Bash, one line.** Same model as unix, piped into PowerShell
+instead of `sh`. The `ssh` bundled with Git is an MSYS process whose Windows command
+line the installer can't introspect, so **pass the cluster host/port explicitly** on
+the PowerShell side of the pipe — that's what names your profile:
+
+```bash
 # host key regenerated each start (not a secret) — skip the check, as plug does internally:
-ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=NUL get@<cluster-host> install-windows | powershell -NoProfile -Command -
+ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    get@<cluster-host> install-windows \
+  | PLUG_HOST=<cluster-host> PLUG_PORT=2222 powershell -NoProfile -Command -
 ```
 
 This downloads `plug.exe` and `wintun.dll` into `%LOCALAPPDATA%\Programs\plug`,
-adds it to your PATH, and pre-creates a `~/.plug/<host>.conf` profile from your
-`ssh` line. Installing needs **no administrator rights**. Requires the built-in
-Windows OpenSSH client (*Settings → Apps → Optional Features → OpenSSH Client*).
+adds it to your PATH, and pre-creates a `~/.plug/<host>.conf` profile. Installing
+needs **no administrator rights**. Open a new terminal afterwards so the PATH takes
+effect.
 
-**Running — the one caveat.** plug's Windows data path is a WinTUN adapter, and
-creating it plus its routes requires **Administrator**. Unlike Linux (`setcap`) or
-macOS (setuid helper) — where one grant at install lets every later run start
-unprivileged — Windows has no per-binary privilege bit, and the process holding
-the adapter is the same one running your command in the foreground. So **for now,
-start `plug` from an elevated terminal** (*Run as administrator*):
+> **Using Windows' native OpenSSH client instead?** Run the same line from a normal
+> PowerShell (with `UserKnownHostsFile=NUL`) and **drop the `PLUG_HOST=/PLUG_PORT=`
+> prefix** — that client's command line *is* readable, so the host is auto-detected.
+
+**2. Run — the one caveat: an elevated terminal.** plug's Windows data path is a
+WinTUN adapter, and creating it plus its routes requires **Administrator**. Unlike
+Linux (`setcap`) or macOS (setuid helper) — where one grant at install lets every
+later run start unprivileged — Windows has no per-binary privilege bit, and the
+process holding the adapter is the same one running your command in the foreground.
+So **for now, start `plug` from an elevated terminal** (*Run as administrator*):
 
 ```powershell
-plug npm run start:dev
+plug <your command>            # several clusters? plug -p <name> <your command>
 ```
 
 A future release will move the Windows data path into a persistent **SYSTEM

RELEASE_NOTES.md

@@ -2,6 +2,14 @@
 
 ## NEXT RELEASE
 
+- **Windows installer works from Git Bash.** The one-liner used to fail there with
+  `no cluster host detected`: the installer read the host off the live `ssh`
+  process's command line, which is unreadable when that `ssh` is Git's MSYS build.
+  You can now pass it explicitly — `… install-windows | PLUG_HOST=<host> PLUG_PORT=<port>
+  powershell -NoProfile -Command -` — while the native Windows OpenSSH client is
+  still auto-detected with no prefix. Also, a fatal installer error now actually
+  stops the script (a piped `powershell -Command -` ignored the old `exit`), and the
+  README documents the Git-Bash path assuming Git for Windows is present.
 - **Attribution hardened against PID recycling.** The by-process router now stamps
   each hop of the ancestry walk with the process's start time and refuses a
   temporally impossible chain — an "ancestor" that started *after* its child is a

agent/install.ps1

@@ -36,7 +36,9 @@ $PlugExe       = Join-Path $InstallDir 'plug.exe'
 $WintunDll     = Join-Path $InstallDir 'wintun.dll'
 
 function Info($msg) { Write-Host "plug: $msg" }
-function Die($msg)  { Write-Error "plug: $msg"; exit 1 }
+# throw (not Write-Error + exit): under `powershell -Command -` a piped script's
+# `exit` does not reliably stop it, so an error used to print yet the script ran on.
+function Die($msg)  { throw "plug: $msg" }
 
 # --- 1. Discover the cluster host/port from the live ssh invocation ----------
 # You reached the agent with `ssh ... get@<host> install-windows`; the agent can
@@ -48,15 +50,27 @@ function Die($msg)  { Write-Error "plug: $msg"; exit 1 }
 $SshHost = $null
 $SshPort = $DefaultPort
 $profileMsg = $null
-try {
-    $line = Get-CimInstance Win32_Process -Filter "Name='ssh.exe'" |
-            Where-Object { $_.CommandLine -match 'get@' -and $_.CommandLine -match 'install-windows' } |
-            Select-Object -First 1 -ExpandProperty CommandLine
-    if ($line) {
-        if ($line -match 'get@([A-Za-z0-9._-]+)') { $SshHost = $Matches[1] }
-        if ($line -match '-p[ =]*([0-9]+)')       { $SshPort = $Matches[1] }
-    }
-} catch { }
+
+# (a) Explicit override — the robust path from Git Bash / MSYS, where the ssh that
+# streams this script is an MSYS process whose Win32 CommandLine the auto-detect
+# below cannot read. Pass it on the powershell side of the pipe:
+#   ssh ... get@<host> install-windows | PLUG_HOST=<host> PLUG_PORT=<port> powershell -NoProfile -Command -
+if ($env:PLUG_HOST) { $SshHost = $env:PLUG_HOST }
+if ($env:PLUG_PORT) { $SshPort = $env:PLUG_PORT }
+
+# (b) Otherwise auto-detect from the live ssh invocation — works with the native
+# Windows OpenSSH client, whose process CommandLine is readable.
+if (-not $SshHost) {
+    try {
+        $line = Get-CimInstance Win32_Process -Filter "Name='ssh.exe'" |
+                Where-Object { $_.CommandLine -match 'get@' -and $_.CommandLine -match 'install-windows' } |
+                Select-Object -First 1 -ExpandProperty CommandLine
+        if ($line) {
+            if ($line -match 'get@([A-Za-z0-9._-]+)') { $SshHost = $Matches[1] }
+            if ($line -match '-p[ =]*([0-9]+)')       { $SshPort = $Matches[1] }
+        }
+    } catch { }
+}
 
 if ($SshHost) {
     $plugCfgDir = Join-Path $env:USERPROFILE '.plug'
@@ -76,7 +90,7 @@ New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
 
 function Get-AgentBinary($outFile) {
     if (-not $SshHost) {
-        Die 'cannot download plug.exe: no cluster host detected (run from an `ssh ... get@<host> install-windows | powershell -` line)'
+        Die 'no cluster host detected. From Git Bash, pass it on the powershell side of the pipe: | PLUG_HOST=<host> PLUG_PORT=<port> powershell -NoProfile -Command -   (the native Windows OpenSSH client is auto-detected without this)'
     }
     if (-not (Get-Command ssh -ErrorAction SilentlyContinue)) {
         Die 'ssh.exe not found. Install the Windows OpenSSH client (Settings > Apps > Optional Features > OpenSSH Client), then re-run.'