From 6822cbbbb5cd1d8e609b9090f88ec56bc6ffbf61 Mon Sep 17 00:00:00 2001
From: Dustin <204417361+Koraji95-coder@users.noreply.github.com>
Date: Sat, 23 May 2026 15:36:21 -0500
Subject: [PATCH] feat(start.ps1): expand hermes-agent candidate paths for
 Windows installers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Maintainer follow-up on PR #2783: the auto-discovery list only checked
`%USERPROFILE%\.hermes\hermes-agent` and `../hermes-agent`, but the
official Windows installer puts hermes-agent under
`%LOCALAPPDATA%\hermes\hermes-agent`, and MSI installs commonly land in
`Program Files`. Users hitting `start.ps1` from a fresh clone of an
installer-deployed agent currently have to set `HERMES_WEBUI_AGENT_DIR`
manually — which is the exact friction the PR was trying to remove.

Adds three new candidate paths to the discovery list:

- `%LOCALAPPDATA%\hermes\hermes-agent`   (official Windows installer)
- `%PROGRAMFILES%\hermes\hermes-agent`   (MSI to Program Files)
- `%PROGRAMFILES(X86)%\hermes\hermes-agent`  (MSI to x86 path)

Order matters: existing `%USERPROFILE%\.hermes\hermes-agent` stays
first (user-local installs win), then the three new system-wide paths,
then the sibling-of-RepoRoot `../hermes-agent` developer-checkout case
stays last. Same `Test-Path (Join-Path \$c 'hermes_cli')` validation
applies to every candidate.

Also restructures the not-found error message to enumerate every
searched path via `\$candidates -join ', '` — when discovery fails the
user now sees the exact list checked, so it's obvious where to drop
the agent or which `HERMES_WEBUI_AGENT_DIR` value to set.

Stacked on top of #2783. Once #2783 lands, this rebases cleanly onto
master.
---
 CHANGELOG.md | 1 +
 start.ps1    | 8 +++++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 803a379a..a3e8924d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 
 ### Added
 
+- **`start.ps1`: native Windows launcher candidate-path expansion** — extends `start.ps1`'s hermes-agent auto-discovery to also check `%LOCALAPPDATA%\hermes\hermes-agent`, `%PROGRAMFILES%\hermes\hermes-agent`, and `%PROGRAMFILES(X86)%\hermes\hermes-agent` in addition to the existing `%USERPROFILE%\.hermes\hermes-agent` and `../hermes-agent` candidates. Closes the installer-user-path friction the maintainer flagged in #2783 — users who install hermes-agent via the official Windows installer (which places it under `%LOCALAPPDATA%\hermes\hermes-agent`) or an MSI to `Program Files` no longer need to set `HERMES_WEBUI_AGENT_DIR` explicitly. The not-found error message also restructured to enumerate every searched path, so when discovery fails the user sees exactly where to look. Same `Test-Path (Join-Path $c 'hermes_cli')` validation applies uniformly to all candidates.
 - **`start.ps1`: native Windows launcher** — PowerShell equivalent of `start.sh` that bypasses `bootstrap.py`'s `ensure_supported_platform()` refusal and invokes `server.py` directly on native Windows. Mirrors `start.sh`'s discovery (load optional `.env` with the same readonly-var filter for `UID`/`GID`/`EUID`/`EGID`/`PPID`, find Python via `HERMES_WEBUI_PYTHON` env → `python3` → `python` → `py`, locate the hermes-agent dir at `%USERPROFILE%\.hermes\hermes-agent` or `../hermes-agent`, prefer the agent's `venv\Scripts\python.exe` if present, set `HERMES_WEBUI_HOST` / `HERMES_WEBUI_PORT` / `HERMES_WEBUI_STATE_DIR` / `HERMES_HOME` defaults). Closes the launcher half of #1952; complements the README community-guide link below. Assumes Python + agent venv are already set up — for first-time setup, use WSL2 once to create the venv, then `start.ps1` works natively.
 
 ### Documentation
diff --git a/start.ps1 b/start.ps1
index 191db6c1..6631e81d 100644
--- a/start.ps1
+++ b/start.ps1
@@ -98,6 +98,9 @@ if ($AgentDir -and -not (Test-Path (Join-Path $AgentDir 'hermes_cli'))) {
 if (-not $AgentDir) {
     $candidates = @(
         (Join-Path $env:USERPROFILE '.hermes\hermes-agent'),
+        (Join-Path $env:LOCALAPPDATA 'hermes\hermes-agent'),
+        (Join-Path ${env:ProgramFiles} 'hermes\hermes-agent'),
+        (Join-Path ${env:ProgramFiles(x86)} 'hermes\hermes-agent'),
         (Join-Path (Split-Path -Parent $RepoRoot) 'hermes-agent')
     )
     foreach ($c in $candidates) {
@@ -105,9 +108,8 @@ if (-not $AgentDir) {
     }
 }
 if (-not $AgentDir) {
-    $expectedPrimary = Join-Path $env:USERPROFILE '.hermes\hermes-agent'
-    $expectedSibling = Join-Path (Split-Path -Parent $RepoRoot) 'hermes-agent'
-    Write-Error "hermes-agent not found at $expectedPrimary or $expectedSibling. Set HERMES_WEBUI_AGENT_DIR explicitly."
+    $searched = $candidates -join ', '
+    Write-Error "hermes-agent not found. Searched: $searched. Set HERMES_WEBUI_AGENT_DIR explicitly to override."
     exit 1
 }