feat(start.ps1): expand hermes-agent candidate paths for Windows installers

[Koraji95-coder]

Update notes (2026-05-23, post-initial-filing):

• PR body reformatted to match CONTRIBUTING.md. Initial filing used a generic Summary / What changed / Test plan layout; the maintainer's CONTRIBUTING.md requires the 6-section shape below (Thinking Path / What Changed / Why It Matters / Verification / Risks / Model Used) plus an AI Usage Disclosure. Caught + corrected after human-side review of upstream contributing guidance.
• Copilot review feedback addressed in commit 6f42353. Three of Copilot's six inline comments were real bugs and have been fixed in this PR (Test-Path -PathType Container × 2 sites, conditional candidate-list build to guard ${env:ProgramFiles(x86)} null-on-32-bit, CHANGELOG entry rewritten to be stack-position-independent). Two WSL2-related comments (start.ps1:16 header, README.md:140) are out-of-scope for this PR — the affected lines originated in parent PR feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783, not feat(start.ps1): expand hermes-agent candidate paths for Windows installers #2805 — and have been replied-to on-thread with a deferral note + commitment to file a separate small docs-fix PR per the maintainer's "keep diffs focused" guidance. One comment about the CHANGELOG accuracy was rolled into the rewrite above.

---

Thinking Path

• Hermes WebUI aims for frictionless setup on every supported platform
• PR feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783 added start.ps1 for native Windows, mirroring start.sh's discovery shape
• That discovery list only checked two paths: %USERPROFILE%\.hermes\hermes-agent (user-local install) and ../hermes-agent (dev-checkout layout)
• Users hitting start.ps1 from a fresh checkout where hermes-agent was installed via the official Windows installer (which places it under %LOCALAPPDATA%\hermes\hermes-agent) or via MSI (typically Program Files) currently have to set HERMES_WEBUI_AGENT_DIR manually
• That's exactly the friction PR feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783's start.ps1 was trying to remove
• The maintainer surfaced this in the PR #2783 review thread and explicitly suggested filing as a separate small PR per "keeping diffs focused is good policy here"

What Changed

start.ps1 candidate list expands from 2 → 5 paths, built incrementally with null-guards:

Order	Path	Use case	Guard
1	%USERPROFILE%\.hermes\hermes-agent	User-local install	Always-set on Windows; unguarded
2	%LOCALAPPDATA%\hermes\hermes-agent	Official Windows installer	if ($root)
3	%PROGRAMFILES%\hermes\hermes-agent	MSI to Program Files	if ($root)
4	%PROGRAMFILES(X86)%\hermes\hermes-agent	MSI to x86 path	if ($root) — null on 32-bit Windows
5	../hermes-agent	Dev-checkout layout	Path-derived from $RepoRoot; unguarded

Each candidate is validated as a directory via Test-Path … -PathType Container — a file (not a directory) named hermes_cli at any candidate root no longer passes the check. Applied uniformly at both the env-var-override-validation site (start.ps1:94) and the candidate-loop site (start.ps1:111).

Not-found error now enumerates every searched path via $candidates -join ', ', so when discovery fails the user sees the exact list checked.

Diff: start.ps1 | 14 +++++++-----, CHANGELOG.md | 1 + (entry under existing [Unreleased] / ### Added).

Why It Matters

The official Windows installer for hermes-agent ships it to %LOCALAPPDATA%\hermes\hermes-agent. Without this PR, every user of that installer who clones hermes-webui and runs start.ps1 has to either:

• Read the not-found error, figure out which env var to set, set HERMES_WEBUI_AGENT_DIR, re-run
• OR move/symlink the agent install into %USERPROFILE%\.hermes\hermes-agent

Adding the three system-wide candidate paths means installer-deployed agents auto-discover; restructuring the error message means when discovery fails on a machine with no agent installed, the user sees all paths that were checked. The conditional-build hardening means the launcher degrades gracefully on 32-bit Windows where ${env:ProgramFiles(x86)} is null and Join-Path would otherwise throw. The -PathType Container validation means a stray file named hermes_cli can't pass the discovery check and lead to a confusing import error later.

Verification

• start.ps1 parses clean via [System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$null, [ref]$errs) — zero errors
• Anchor-based edits (no line-number drift if surrounding code shifts later); all three anchors match exactly once in the source — no false-positive replacements
• CHANGELOG.md entry under [Unreleased] / ### Added, immediately above the existing PR feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783 entry, preserves chronological ordering
• Wording of CHANGELOG entry is stack-position-independent — reads correctly both when viewed in this PR's stacked diff (where start.ps1 is "newly added") AND post-feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783-merge (where start.ps1 is "extended")
• Needs Windows test machine: smoke test on a fresh checkout, hermes-agent installed at %LOCALAPPDATA%\hermes\hermes-agent, no HERMES_WEBUI_AGENT_DIR set — expected: discovery finds the agent and start.ps1 launches server.py. Happy to coordinate with anyone who has the installer-deployed agent layout available; can run on a fresh foundry-side checkout if useful — let me know if you'd like before/after screenshots in a follow-up comment.
• Needs Windows test machine: smoke test on a fresh checkout, hermes-agent NOT installed anywhere — expected: error message lists all 5 candidate paths (or 3-4 on 32-bit / restricted-env Windows where some system-wide roots are null).
• Needs 32-bit Windows or constrained env: confirm conditional if ($root) correctly skips the missing ${env:ProgramFiles(x86)} without Join-Path throwing. Same coordination offer.

Repo doesn't have PowerShell-specific tests (test suite is pytest-based for the Python side), so the PowerShell-only changes here can't be CI-tested in the existing tests/ layout. If you'd like a Pester test added alongside this PR (or a follow-up), say the word.

Risks / Follow-ups

• No breaking changes. User-local and dev-checkout candidate positions are preserved (slots 1 and 5). New candidates slot in between them. The -PathType Container tightening only narrows what passes — anyone whose hermes_cli was previously a file (impossible by design but theoretically possible) would now be caught earlier instead of later.
• No new dependencies, no build-step changes, no new infrastructure. Pure addition to an existing PowerShell launcher.
• Stacking on feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783. start.ps1 doesn't exist on master yet; this PR depends on feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783 landing first. Once feat: native Windows community-guide link + start.ps1 launcher (#1952) #2783 merges, rebase is clean (additive changes only).
• Follow-up PR coming for the WSL2-once-then-native claim in start.ps1:16 header and README.md:140 — Copilot flagged it as misleading (a WSL2-created venv is Linux-only, not portable to Windows Python). Out of this PR's scope; will file a separate small docs-fix PR.
• No security-sensitive surface touched. The discovery list just controls which directories Test-Path is called against; no auth, path-handling, uploads, or streaming behavior changes.

Model Used

• Provider: Anthropic
• Exact model: Claude 4.7 (Sonnet, 1M context)
• Mode: Used to author the candidate-paths expansion (anchor-based PowerShell edits), the CHANGELOG entry, Copilot-fix follow-up commit, and this PR description. Anchor-based edits were verified via [regex]::Escape($anchor) match-once-or-fail before applying. Final human review (catching the initial PR-body format mismatch with CONTRIBUTING.md) before push.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds native Windows support guidance and a PowerShell launcher to run Hermes WebUI without bootstrap.py on Windows, plus documentation updates describing the community-supported path.

Changes:

• Added start.ps1 PowerShell launcher that loads .env, discovers Python + hermes-agent, sets env defaults, and runs server.py.
• Updated README with links to a community-maintained native Windows setup guide and notes/limitations.
• Updated changelog entries describing the new launcher and Windows discovery paths.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
start.ps1	Introduces a Windows-native launcher with env loading, Python/agent discovery, and direct server.py execution.
README.md	Adds native Windows community guide links and notes about native vs WSL2 usage.
CHANGELOG.md	Documents the addition of start.ps1 and Windows agent discovery behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Koraji95-coder]

Smoke-tested on a Windows 11 Pro machine with hermes-agent installed at %LOCALAPPDATA%\hermes\hermes-agent

Fresh gh repo clone of this PR branch, two tests + a real WOW64 edge case found.

Test 1 — discovery via the new %LOCALAPPDATA% candidate (with HERMES_WEBUI_AGENT_DIR unset)

Pre-test state:
  HERMES_WEBUI_AGENT_DIR: (unset, as expected for Test 1)
  %USERPROFILE%\.hermes\hermes-agent\hermes_cli  exists-as-dir? False
  %LOCALAPPDATA%\hermes\hermes-agent\hermes_cli  exists-as-dir? True

Candidate list (5 entries, post-WOW64 fix):
  [1] C:\Users\koraj\.hermes\hermes-agent              -PathType Container hit: False
  [2] C:\Users\koraj\AppData\Local\hermes\hermes-agent -PathType Container hit: True  ← discovers here
  [3] C:\Program Files\hermes\hermes-agent             -PathType Container hit: False
  [4] C:\Program Files (x86)\hermes\hermes-agent       -PathType Container hit: False
  [5] C:\Users\koraj\AppData\Local\Temp\hermes-agent   -PathType Container hit: False

RESULT: DISCOVERY SUCCESS
  AgentDir resolved to: C:\Users\koraj\AppData\Local\hermes\hermes-agent

Test 2 — -PathType Container guard with HERMES_WEBUI_AGENT_DIR set to a missing path

HERMES_WEBUI_AGENT_DIR = C:\does-not-exist-smoke-test-only
Test-Path -PathType Container: False

Captured stderr (process exited with code 1):
  Write-Error: ...\start.ps1:95
  HERMES_WEBUI_AGENT_DIR is set to 'C:\does-not-exist-smoke-test-only' but no hermes_cli/ folder exists there.
  Unset the variable to fall back to auto-discovery, or fix the path.

✓ Both new behaviors land correctly: -PathType Container validation fires immediately on a missing path; the override path stays a hard exit 1 with the actionable error message.

---

Real bug surfaced by the smoke test → fixed in commit dbebbed

The smoke test was running under PowerShell 7.5.4 in WOW64 mode (32-bit process on 64-bit OS — happens through certain shell chains, like Git Bash → pwsh). In that mode, Windows redirects $env:ProgramFiles to C:\Program Files (x86), which meant the original candidate list produced two identical C:\Program Files (x86)\hermes\hermes-agent entries and silently missed the real C:\Program Files\hermes\hermes-agent where MSI-installed hermes-agent actually lives.

Initial candidate list (pre-fix, on WOW64):

  [3] C:\Program Files (x86)\hermes\hermes-agent   ← ${env:ProgramFiles} redirected!
  [4] C:\Program Files (x86)\hermes\hermes-agent   ← ${env:ProgramFiles(x86)} same path

Fix in dbebbed:

1. Added ${env:ProgramW6432} to the candidate loop — Windows guarantees this points at the 64-bit C:\Program Files regardless of process bitness.
2. Added $candidates = $candidates | Select-Object -Unique after the list is built — collapses any same-path collisions defensively (handles future env-var weirdness too).

Post-fix candidate list on the same WOW64 shell — now distinct, 5 entries, includes the real C:\Program Files\hermes\hermes-agent.

---

This is the "Windows test machine, no HERMES_WEBUI_AGENT_DIR set, hermes-agent installed at %LOCALAPPDATA%" verification checkbox from the PR body. Calling that one ✓ and adding the WOW64 fix to the verification list.

If you'd like before/after Lighthouse-style screenshots in addition to this transcript, happy to capture them via Chrome MCP and post.

[nesquena-hermes]

Summary

Read the discovery block at the PR's HEAD (commit dbebbed) and walked through the smoke-test transcript above. The WOW64 finding is a real bug that would have shipped silently; the ProgramW6432 + Select-Object -Unique fix is the right shape. Worth flagging this as the highest-value piece of the whole stack: the surface change looks small but it prevents a class of "agent installed but not found" reports from MSI-deployed-to-Program-Files users running PowerShell from inside Git Bash, VS Code's integrated terminal under certain configs, or anything else that ends up in a WOW64 process.

Code reference

start.ps1:104-122 at HEAD - the post-fix candidate loop:

$candidates = @()
$candidates += (Join-Path $env:USERPROFILE '.hermes\hermes-agent')
foreach ($root in @($env:LOCALAPPDATA, ${env:ProgramW6432}, ${env:ProgramFiles}, ${env:ProgramFiles(x86)})) {
    if ($root) { $candidates += (Join-Path $root 'hermes\hermes-agent') }
}
$candidates += (Join-Path (Split-Path -Parent $RepoRoot) 'hermes-agent')
# De-dup: when running in a WOW64 (32-bit-on-64-bit) PowerShell process,
# $env:ProgramFiles is redirected to C:\Program Files (x86)...
$candidates = $candidates | Select-Object -Unique
foreach ($c in $candidates) {
    if (Test-Path (Join-Path $c 'hermes_cli') -PathType Container) { $AgentDir = $c; break }
}

Diagnosis

WOW64 bug + fix: correct and well-targeted. Windows' filesystem-and-environment redirection layer (WoW64) maps %ProgramFiles% to the x86 path for 32-bit processes on 64-bit OS. The canonical escape hatch is %ProgramW6432%, which always points at the native 64-bit C:\Program Files regardless of process bitness. Without it, a 32-bit PowerShell process (which is more common than people expect - some VS Code terminal configs, Git Bash -> pwsh chains, older shell shortcuts) would have produced exactly the symptom in the transcript: %ProgramFiles% and %ProgramFiles(x86)% resolve to the same path, the real C:\Program Files\hermes\hermes-agent is silently skipped, and a working installer-deployed agent shows up as "not found." The Select-Object -Unique post-pass is also good defensive practice - it collapses any future env-var collisions before they become a "we checked twice but missed once" bug. LGTM.

-PathType Container tightening: also correct. The earlier Test-Path (Join-Path $c 'hermes_cli') would have passed if there was a stray file named hermes_cli at any candidate root. That's a contrived edge case but the tightening costs nothing and produces a clearer failure-point (no agent vs malformed agent) when discovery falls through. Applied uniformly at both the env-var-override-validation site (line ~95) and the candidate-loop site (line ~120). LGTM.

Enumerated not-found error: Write-Error "hermes-agent not found. Searched: $searched. ..." is a meaningful improvement over the previous "expected $primary or $sibling" wording - when discovery fails on a machine where the user thinks they installed the agent, the error names every directory checked, which makes the diagnostic loop one round instead of three.

Smoke-test transcript

The transcript above (Test 1 confirming %LOCALAPPDATA% discovery, Test 2 confirming -PathType Container validation, plus the WOW64 finding) is the right shape of evidence. The two ticked checkboxes from the PR body are satisfied. The remaining "needs 32-bit Windows or constrained env" item could be done virtually via Start-Job -InitializationScript { $env:'ProgramFiles(x86)' = $null } for a unit-style proof, but it's not blocking - the conditional if ($root) is verifiable by inspection.

Stacking note

Stacked on #2783 alongside #2806 and #2807 - this is the most substantive of the three follow-ups (real bug fix surfaced by smoke testing, not just hardening or docs). Worth landing.

Verification

I did not execute the script (cron policy is read-only on PR worktrees). The WOW64 redirect behavior is documented Windows API surface; the fix is verifiable by inspection. The -PathType Container change is mechanically equivalent at the happy-path level but tightens the failure mode. The enumerated error message is structurally observable in the diff.

[nesquena-hermes]

Summary

Read the discovery block at the PR's HEAD (commit dbebbed) and walked through the smoke-test transcript above. The WOW64 finding is a real bug that would have shipped silently; the ProgramW6432 + Select-Object -Unique fix is the right shape. Worth flagging this as the highest-value piece of the whole stack: the surface change looks small but it prevents a class of "agent installed but not found" reports from MSI-deployed-to-Program-Files users running PowerShell from inside Git Bash, VS Code's integrated terminal under certain configs, or anything else that ends up in a WOW64 process.

Code reference

start.ps1:104-122 at HEAD - the post-fix candidate loop:

$candidates = @()
$candidates += (Join-Path $env:USERPROFILE '.hermes\hermes-agent')
foreach ($root in @($env:LOCALAPPDATA, ${env:ProgramW6432}, ${env:ProgramFiles}, ${env:ProgramFiles(x86)})) {
    if ($root) { $candidates += (Join-Path $root 'hermes\hermes-agent') }
}
$candidates += (Join-Path (Split-Path -Parent $RepoRoot) 'hermes-agent')
# De-dup: when running in a WOW64 (32-bit-on-64-bit) PowerShell process,
# $env:ProgramFiles is redirected to C:\Program Files (x86)...
$candidates = $candidates | Select-Object -Unique
foreach ($c in $candidates) {
    if (Test-Path (Join-Path $c 'hermes_cli') -PathType Container) { $AgentDir = $c; break }
}

Diagnosis

WOW64 bug + fix: correct and well-targeted. Windows' filesystem-and-environment redirection layer (WoW64) maps %ProgramFiles% to the x86 path for 32-bit processes on 64-bit OS. The canonical escape hatch is %ProgramW6432%, which always points at the native 64-bit C:\Program Files regardless of process bitness. Without it, a 32-bit PowerShell process (which is more common than people expect - some VS Code terminal configs, Git Bash -> pwsh chains, older shell shortcuts) would have produced exactly the symptom in the transcript: %ProgramFiles% and %ProgramFiles(x86)% resolve to the same path, the real C:\Program Files\hermes\hermes-agent is silently skipped, and a working installer-deployed agent shows up as "not found." The Select-Object -Unique post-pass is also good defensive practice - it collapses any future env-var collisions before they become a "we checked twice but missed once" bug. LGTM.

-PathType Container tightening: also correct. The earlier Test-Path (Join-Path $c 'hermes_cli') would have passed if there was a stray file named hermes_cli at any candidate root. That's a contrived edge case but the tightening costs nothing and produces a clearer failure-point (no agent vs malformed agent) when discovery falls through. Applied uniformly at both the env-var-override-validation site (line ~95) and the candidate-loop site (line ~120). LGTM.

Enumerated not-found error: Write-Error "hermes-agent not found. Searched: $searched. ..." is a meaningful improvement over the previous "expected $primary or $sibling" wording - when discovery fails on a machine where the user thinks they installed the agent, the error names every directory checked, which makes the diagnostic loop one round instead of three.

Smoke-test transcript

The transcript above (Test 1 confirming %LOCALAPPDATA% discovery, Test 2 confirming -PathType Container validation, plus the WOW64 finding) is the right shape of evidence. The two ticked checkboxes from the PR body are satisfied. The remaining "needs 32-bit Windows or constrained env" item could be done virtually via Start-Job -InitializationScript { $env:'ProgramFiles(x86)' = $null } for a unit-style proof, but it's not blocking - the conditional if ($root) is verifiable by inspection.

Stacking note

Stacked on #2783 alongside #2806 and #2807 - this is the most substantive of the three follow-ups (real bug fix surfaced by smoke testing, not just hardening or docs). Worth landing.

Verification

I did not execute the script (cron policy is read-only on PR worktrees). The WOW64 redirect behavior is documented Windows API surface; the fix is verifiable by inspection. The -PathType Container change is mechanically equivalent at the happy-path level but tightens the failure mode. The enumerated error message is structurally observable in the diff.

[nesquena-hermes]

Shipped in v0.51.124 via release/stage-batch6 (#2817). The expanded candidate-list discovery + WOW64 dedupe + PathType Container guard are in. Rebased onto current master (since this was branched off the now-shipped #2783); authorship preserved. Thanks!