Skip to content

fix(hermes): surface dashboard launch failures with a real diagnostic block#3413

Open
la14-1 wants to merge 1 commit into
mainfrom
fix/hermes-dashboard-surface-errors
Open

fix(hermes): surface dashboard launch failures with a real diagnostic block#3413
la14-1 wants to merge 1 commit into
mainfrom
fix/hermes-dashboard-surface-errors

Conversation

@la14-1
Copy link
Copy Markdown
Member

@la14-1 la14-1 commented May 13, 2026

Summary

  • startHermesDashboard() previously hid every failure behind a generic "Hermes web dashboard failed to start — TUI still available" warning. When users reported breakage (e.g. issue [Bug]: hermes on digitalocean fails — hermes dashboard reported as not a command #3407 — Andrew's "hermes dashboard isn't a command" / "the dashboard command of hermes also changed to something else") we had no signal to debug from.
  • Now the deploy script installs an EXIT trap that fires on any non-zero exit and dumps a banner-delimited diagnostic block to stderr (which is inherited live to the user's terminal):
    ──── Hermes dashboard diagnostic ────
    hermes binary: /home/.../venv/bin/hermes
    hermes version: Hermes Agent v0.13.0 (2026.5.7)
    hermes subcommands: includes "dashboard"
    ─── /tmp/hermes-dashboard.log (last 30 lines) ───
    <actual hermes process output>
    ─────────────────────────────────────
    
  • The trap is cleared on the success path so it stays quiet when things work.
  • The TS-side warning now also includes the underlying error message and points users at the diagnostic block for bug reports.
  • Bumps @openrouter/spawn to 1.0.45.

What this catches

Failure mode Old output New output
hermes not in PATH generic warning hermes binary: <not found in PATH> + tail-of-log
dashboard subcommand genuinely renamed/removed generic warning hermes subcommands: "dashboard" NOT in --help output
fastapi/uvicorn lazy-install fails generic warning full hermes stderr including the import-error message
Web dist build fails generic warning the build-error stack tailed from /tmp/hermes-dashboard.log
Port 9119 already taken / bind failure generic warning hermes's own bind error from the log

Test plan

  • bunx @biomejs/biome check src/ — clean (203 files)
  • bun test — 2207 pass / 0 fail (was 2204; +3 new assertions)
  • New tests pin: trap '_dashboard_diag' EXIT, the diagnostic banner, all probe commands, trap - EXIT on success, and the failure-surfacing TS-side message.
  • Generated script syntax-checked with bash -n
  • Subcommand probe (hermes --help | grep -q '^[[:space:]]*dashboard') verified against a live install of hermes-agent v0.13.0 (2026.5.7) from main — matches, so genuine missing-subcommand reports will be loud, not noise.

Refs #3407 — won't close it; that issue stays open until we get a real diagnostic from the next user who hits this and can report the actual cause.

… block

`startHermesDashboard()` previously hid every failure behind the generic
warning "Hermes web dashboard failed to start — TUI still available".
When users reported breakage (issue #3407 — "hermes dashboard isn't a
command") we had no signal to act on: was the binary missing? subcommand
gone?  fastapi/uvicorn lazy-install failed?  web dist build failed?

Now the deploy script installs an EXIT trap that fires on any non-zero
exit and dumps a banner-delimited diagnostic block to stderr (which is
inherited live to the user's terminal):

    ──── Hermes dashboard diagnostic ────
    hermes binary: /home/.../venv/bin/hermes
    hermes version: Hermes Agent v0.13.0 (2026.5.7)
    hermes subcommands: includes "dashboard"
    ─── /tmp/hermes-dashboard.log (last 30 lines) ───
    <actual hermes process output>
    ─────────────────────────────────────

The trap is cleared on the success path so it stays quiet when things
work.  The TS-side warning now also includes the underlying error
message and points users at the diagnostic block for bug reports.

Bumps `@openrouter/spawn` to 1.0.45.

Verified locally: installed hermes-agent v0.13.0 (2026.5.7) from main,
confirmed `hermes --help | grep -q '^[[:space:]]*dashboard'` matches —
so genuine "dashboard subcommand missing" reports will now be loud and
actionable.

Refs #3407.
@la14-1
Copy link
Copy Markdown
Member Author

la14-1 commented May 13, 2026

Note: This PR and #3410 both address #3407 but are complementary, not duplicates:

Recommend merging #3410 first, then this PR. #3413 builds on #3410's version bump (1.0.44 → 1.0.45), so landing #3410 first avoids a version conflict in package.json.

-- refactor/pr-maintainer

@la14-1
Copy link
Copy Markdown
Member Author

la14-1 commented May 14, 2026

Reviewed both PRs for #3407. Closed #3410 (probe-only approach) in favor of this one — the diagnostic block is the right call because:

  1. Silent skip (PR fix(hermes): gate dashboard launch behind capability probe #3410) hides the root cause; this PR surfaces it
  2. The trap-based diagnostic dump gives users and us everything needed for debugging: binary path, version, subcommand availability, and log tail
  3. Includes 3 new test assertions pinning the diagnostic behavior
  4. Version bump included

All CI checks pass. Ready for maintainer review and merge.

-- refactor/code-health

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants