hermes - 💡(How to fix) Fix [Bug]: hermes update leaves web/node_modules in broken state — dashboard service crash-loops with lucide-react resolve + missing tsc

Description

After running hermes update, the dashboard service (hermes-agent.service on a native systemd install — not Docker) enters a permanent crash-loop. Every restart attempt prints:

✗ Web UI npm install failed

…then exits with status 1, systemd retries every ~17s, dashboard URL returns 502 through the reverse proxy.

Root Cause

hermes/web/node_modules is left in a Frankenstein state after hermes update. Running the dashboard manually reveals two compounding errors from the same root cause:

sh: line 1: tsc: command not found

> [email protected] build
> tsc -b && vite build

vite v7.3.2 building client environment for production...
✓ 1045 modules transformed.
✗ Build failed in 1.05s
error during build:
Could not resolve "./icons/alarm-clock-check.js" from "node_modules/lucide-react/dist/esm/lucide-react.js"
file: /home/cashc/.hermes/hermes-agent/web/node_modules/lucide-react/dist/esm/lucide-react.js

Two distinct symptoms, single cause:

1. tsc missing from node_modules/.bin/ — the TypeScript devDep is declared but isn't materialised in the bin directory after the in-place update.
2. lucide-react partial install — the package's package.json advertises an icons module path that doesn't exist on disk in the installed copy.

Both are classic symptoms of npm doing a non-atomic install over an existing node_modules tree where dep versions changed across the update (lucide-react upgrade in particular shifts its icons file layout in newer versions).

Repro

1. Native install of Hermes Agent (systemd-managed hermes-agent.service running hermes dashboard --host 100.x.y.z --port 8585 --insecure --no-open as a non-root user).
2. Some prior version where web/node_modules was healthy.
3. Run hermes update. Update completes successfully ("Update complete!").
4. systemctl restart hermes-agent → crash-loop.

Workaround

cd ~/.hermes/hermes-agent/web
rm -rf node_modules package-lock.json
npm install
sudo systemctl restart hermes-agent

Service comes up healthy, curl http://<bind-host>:8585/ returns 200.

Suggested Fix

The pattern is the same one documented in #16773 (which covers ui-tui/'s @hermes/ink file-dep). The general fix would apply here too:

• hermes update's _update_node_dependencies() (in hermes_cli/main.py) should treat web/node_modules (and any other JS subproject) as ephemeral on version-bump updates — rm -rf node_modules && npm ci rather than in-place npm install. The cost is a slower update; the win is updates that never leave the dashboard in a crash-loop.
• Alternatively: detect package.json hash mismatch vs lock and auto-clean on mismatch.
• Or: if performance of full clean is the concern, run npm install --no-package-lock and then npm dedupe, but the cleanest answer is rm + npm ci.

Environment

• Native install on Arch-based Linux (CachyOS), Node v20+
• Hermes Agent installed at ~/.hermes/hermes-agent/
• Dashboard managed via custom systemd unit hermes-agent.service (renamed from hermes-dashboard.service at some point in recent versions)
• Bound to a Tailscale IP, no Docker layer involved

Related

• #16773 — same root-cause pattern for ui-tui/@hermes/ink. This issue extends the surface to web/node_modules and demonstrates the bug is not limited to file-deps.