Skip to content

Improve launcher stability, align runtime pins, expose portable git - #23

Open
LeonardoCiaccio wants to merge 6 commits into
techjarves:devfrom
LeonardoCiaccio:fix/stability-and-runtime-pin-alignment
Open

Improve launcher stability, align runtime pins, expose portable git#23
LeonardoCiaccio wants to merge 6 commits into
techjarves:devfrom
LeonardoCiaccio:fix/stability-and-runtime-pin-alignment

Conversation

@LeonardoCiaccio

@LeonardoCiaccio LeonardoCiaccio commented Jun 23, 2026

Copy link
Copy Markdown

Summary

Audited the portable launcher scripts and fixed a few stability, portability and consistency issues. All changes are isolated to the orchestration scripts (no Hermes Agent source changes).

  • launcher stability (launch.sh): interactive menu no longer dies when hermes exits non-zero (Ctrl+C / command error); the temporary venv rebuild surfaces real failures instead of masking them with silent || true.
  • runtime pin alignment (setup-unix.sh): Unix pins diverged from Windows (different snapshot dates for Python/Node/uv/ripgrep) with no platform reason — aligned them to the same unified snapshots already used on Windows. Includes a fix for a latent Linux ARM64 bug (ripgrep musl archive 404s on aarch64; uses the gnu flavour) and drop of a hard-coded 14.1.1 glob in the extraction fallback.
  • portable git (launch.bat): MinGit is downloaded during setup but was never on PATH — now exposed so hermes update / git-based tools work on hosts without system git.
  • filesystem guidance (setup-windows.ps1 + README): non-blocking warning on non-NTFS drives (exFAT/FAT32 force copy-mode installs, no hardlinks) + a Troubleshooting FAQ explaining NTFS/exFAT/FAT32 trade-offs.
  • docs: fix ollama pull qwen3.6 → qwen3.

All changes verified with bash -n and the PowerShell AST parser; all runtime download URLs validated HTTP 200.

Test plan

  • Windows first-run setup on an NTFS drive (no warning expected)
  • Windows first-run setup on an exFAT drive (warning printed, setup completes)
  • Linux x86_64 first-run setup (ripgrep installs from musl archive)
  • Linux ARM64 first-run setup (ripgrep installs from gnu archive — previously failing silently)
  • launch.bat then hermes update works without system git
  • ./launch.sh → Ctrl+C in chat returns to menu instead of killing launcher

@LeonardoCiaccio
fix(launch.sh): harden launcher against non-zero exits and venv rebui…
08600d1 
…ld failures

The interactive launcher ran with 'set -e' for its whole lifetime, so a
non-zero exit from the hermes TUI (Ctrl+C, /exit with error, command error)
terminated the launcher instead of returning to the menu.

- Switch to 'set +e' right before launching Hermes; setup/venv bootstrap
  above still run under 'errexit' for safety.
- Propagate the hermes exit code when invoked with explicit arguments
  (./launch.sh hermes setup) instead of always returning 0.
- In the temporary-venv rebuild path, stop masking pip install failures
  with silent '|| true'. A genuinely failed rebuild now prints a clear
  [ERROR] and exits 1, instead of silently claiming success and crashing
  later with an opaque 'no module named hermes_cli' error.
@LeonardoCiaccio
fix(setup-unix): align runtime pins with Windows and fix ripgrep on L…
c430f15 
…inux ARM64

The Unix setup script was pinned to older runtime snapshots than the Windows
one (Python 20260510 vs 20260602, Node 22.14.0 vs 22.22.3, uv 0.7.8 vs
0.11.19, ripgrep 14.1.1 vs 15.1.0). python-build-standalone tags publish
builds for ALL platforms in a single unified release snapshot, so there is
no platform reason for the divergence — it was pure drift from independent
commits. Align the Unix pins to the same snapshot already used on Windows.

Side fix for a latent Linux ARM64 bug: ripgrep 15.1.0 only ships a 'musl'
flavour for x86_64, but the script requested '-musl' for every arch. On
aarch64 the archive 404s, so setup silently fell back to plain grep. Use the
'gnu' flavour for aarch64 instead. Also drop the hard-coded '14.1.1' glob in
the extraction fallback so it tracks the pinned version automatically.
@LeonardoCiaccio
feat(launch.bat): expose portable MinGit in PATH for hermes update/gi…
3d3c354 
…t tools

setup-windows.ps1 downloads MinGit into .cache/runtimes/windows-x64/git/, but
launch.bat never added it to PATH. As a result 'hermes update' and any
git-based feature failed on hosts without a system git.

Add git/cmd and git/mingw64/bin to PATH (conditionally, only when the
portable git was installed) and set GIT_EXEC_PATH so git sub-commands and
helpers resolve. GIT_CONFIG_NOSYSTEM=1 keeps the 'no host pollution' design
contract by ignoring the host's system-level gitconfig.
@LeonardoCiaccio
feat(setup-windows): warn when portable drive is not NTFS
515bc64 
exFAT/FAT32 USB drives work but force copy-mode installs (slower setup,
larger disk footprint) and lack hardlinks/ACLs. There was no signal to the
user that reformatting as NTFS would improve reliability and performance.

Add a non-blocking pre-check (Get-Volume) right before the first download:
on non-NTFS/ReFS filesystems it prints a yellow informational warning, then
continues setup unchanged. Network/UNC paths where the filesystem can't be
determined are skipped silently.
@LeonardoCiaccio
docs: fix ollama model name and add FAQ on USB drive filesystem format
fa6c5a2 
- 'ollama pull qwen3.6' referenced a non-existent model; use qwen3.
- Add a Troubleshooting FAQ entry explaining the trade-offs between NTFS,
  exFAT and FAT32 for the portable drive, recommending NTFS/APFS/ext4 and
  noting the informational warning now printed by setup on non-NTFS drives
  and the 4 GB per-file limit that makes FAT32 unsuitable.
@LeonardoCiaccio
fix(launcher): don't spawn local llama-server for remote custom endpo…
d5fd7e0 
…ints

ensure_llama_server() unconditionally treated provider 'custom' as a local
endpoint (Ollama / llama.cpp) and tried to start a GGUF llama-server, even
when the custom provider pointed to a remote HTTP API like OpenCode Go at
https://opencode.ai/zen/go/v1.

This had two harmful effects on any remote custom provider:
  - crash with 'No GGUF model file configured or found' since no GGUF exists
    for a cloud model, aborting the chat launch;
  - silent rewrite of config.yaml (11434 -> 39600) on every run, corrupting
    the user's provider configuration.

Guard the whole block: only enter the local llama-server path when the
configured base_url points at 127.0.0.1 / localhost. Remote custom
endpoints skip it entirely. Applied to both launch.bat (Windows) and
launch.sh (macOS/Linux).
@LeonardoCiaccio

LeonardoCiaccio commented Jun 23, 2026

Copy link
Copy Markdown
Author

Update: added one more commit d5fd7e0 fix(launcher): don't spawn local llama-server for remote custom endpoints.

While testing a remote OpenAI-compatible custom provider (OpenCode Go, base_url https://opencode.ai/zen/go/v1), ensure_llama_server() unconditionally tried to start a local GGUF llama-server because the provider was custom, crashing with No GGUF model file configured or found and silently rewriting config.yaml (11434 → 39600) on every run. The block now only runs when the configured base_url points at 127.0.0.1/localhost. Cleanup follows the existing audit work — not changing scope, just hardening the new local-LLM feature for remote custom providers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@LeonardoCiaccio