[Bug]: Installing Hermes Desktop broke iTerm disk access and nvm usage

[johnnyshankman]

Bug Description

After installing Hermes Agent, my iTerm no longer had read access to any files on disk. After fixing that, my nvm CLI no longer worked anymore, causing me get stuck on node v22 indefinitely no matter what.

Steps to Reproduce

1. Be iTerm user who uses nvm to manage their node versions / environment
2. Install hermes agent using hermes desktop.

Expected Behavior

My iTerm session still has disk access. nvm still works as expected.

Actual Behavior

iTerm immediately loses disk access. Only solution is to toggle it in Privacy settings.

nvm no longer works. hermes symlinks are overriding its configuration and causing v22 to always be used.

Got to the bottom of this using Claude

Root cause in one line: your ~/.zshrc prepends ~/.local/bin to PATH after nvm loads, and ~/.local/bin/node|npm|npx are symlinks to the Claude/Hermes bundled Node v22 — so they shadow nvm's v24. The repo's .npmrc has engine-strict=true + engines.node >=24, so npm i running under the shadowed v22 hard-fails.

Affected Component

Setup / Installation

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

Report       https://paste.rs/2QMUB
  agent.log    https://paste.rs/O7Gaw
  gui.log      https://paste.rs/Yxxja
  desktop.log  https://paste.rs/3qCeN

Operating System

macOS 14.8.3

Python Version

3.11.15

Hermes Version

0.18.0

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

Symlinking complications.

My personal fix:

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR

[GottZ]

This was generated by AI during triage.

Summary

Five PRs address or reference this issue complex, but only #58099 directly removes the reported user-scoped PATH shadowing; #63623 mitigates collisions and GUI PATH misdetection without eliminating managed links, while #52913, #53232, and #61351 concern recovery of broken or missing managed Node tools. None of the diffs establishes or fixes the reported macOS iTerm/TCC disk-access change.

Related pull requests

• fix(hermes): fall back to system npm when managed node tree is broken #52913 [merged] unrelated — (+368/-5) — unrelated: This merged reference implementation validates and heals a broken Hermes-managed Node tree for Hermes-owned subprocesses, but it does not change the user-scoped node/npm/npx links that shadow nvm.
• fix(hermes): heal managed Node when a sibling tool (npm/npx) is missing, not only broken #53232 [closed] unrelated — (+44/-1) — unrelated: This closed PR extends managed-tree healing to a missing npm/npx sibling rather than preventing Hermes links from overriding the user's version manager; it remains relevant as the direct predecessor superseded by fix(hermes): heal managed Node when npm/npx sibling is missing #61351.
• fix(install): keep managed Node private for user installs #58099 best fix — (+303/-95) — best partial fix: It directly removes legacy Hermes-owned node/npm/npx links from user-scoped command directories, keeps future managed Node tools private, preserves root-FHS exposure, and leaves unrelated user links intact. The contributor keep_open review requested behavioral tests instead of source-text assertions, and the latest discussion reports that commit 779265f replaced them with installer/bootstrap behavioral coverage; the separate iTerm/TCC claim remains unaddressed for lack of evidence.
• fix(hermes): heal managed Node when npm/npx sibling is missing #61351 unrelated — (+94/-1) — unrelated to [Bug]: Installing Hermes Desktop broke iTerm disk access and nvm usage #57997: It salvages fix(hermes): heal managed Node when a sibling tool (npm/npx) is missing, not only broken #53232 by healing an absent managed npm/npx sibling, including the POSIX shell predicate and direct predicate coverage, but does not prevent PATH shadowing. Despite its keep_open review, it should remain independently tracked as managed-tree recovery rather than be treated as the fix for this issue; the review's production-path objection is addressed by the shown shell-predicate change.
• fix(installer): preserve user-managed Node commands #63623 [closed] partial — (+201/-15) — partial alternative: This closed PR detects modern Node in common locations under a GUI-minimal PATH and preserves an existing non-Hermes command collision, but it still creates Hermes node/npm/npx links in the user command directory when no destination exists, so it does not eliminate the reported shadowing class. Despite the keep_open review on fix(installer): preserve user-managed Node commands #63623, its diff retains the user-PATH symlink design and the cited install.sh behavioral-test gap remains visible, whereas fix(install): keep managed Node private for user installs #58099 removes that exposure and reports behavioral coverage.

Duplicates

#53232 and #61351 implement substantially the same missing-managed-sibling healing change, with #61351 adding the required POSIX predicate fix. #58099 and #63623 overlap on installer ownership of node/npm/npx, but they are not exact duplicates: #58099 makes managed Node private, while #63623 retains collision-safe user-PATH links and adds GUI-path discovery.

Suggested consolidation

Merge #58099 as the verified best fix for the evidenced nvm/PATH root cause, after confirming the reported behavioral-test replacement is present on the current head. Keep #63623 closed as superseded for #57997; its GUI Node discovery can be ported separately if still desired, but its retained user-PATH links should not replace #58099. Keep #53232 closed as superseded by #61351, and track #61351 separately rather than closing it as a duplicate of the installer-shadowing fix; #52913 is already merged infrastructure and is not a competing fix. Do not claim the iTerm/TCC disk-access symptom fixed without additional evidence.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I57997(["issue #57997 (open)"])
    I63612(["issue #63612 (open)"])
    P58099["PR #58099 (open)"]
    P63623["PR #63623 (closed)"]
    subgraph Dup53232 ["PRs duplicating each other"]
        P53232["PR #53232 (closed)"]
        P61351["PR #61351 (open)"]
    end
    P58099 -->|best fix| I57997
    P63623 -.->|partial| I57997
    P58099 -.->|partial| I63612
    P63623 -->|best fix| I63612
    class I57997 open
    class I63612 open
    class I57997 target
    class P53232 closed
    class P58099 open
    class P61351 open
    class P63623 closed
    class P58099 best
    class P63623 best
    click I57997 "https://github.com/NousResearch/hermes-agent/issues/57997"
    click I63612 "https://github.com/NousResearch/hermes-agent/issues/63612"
    click P53232 "https://github.com/NousResearch/hermes-agent/pull/53232"
    click P58099 "https://github.com/NousResearch/hermes-agent/pull/58099"
    click P61351 "https://github.com/NousResearch/hermes-agent/pull/61351"
    click P63623 "https://github.com/NousResearch/hermes-agent/pull/63623"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 5 pull requests and 2 issues in this complex. Each diff was read against this issue; Assessment working set: 59 kB of PR diffs, 18 kB of issue/PR text, 8 kB of discussion (14 comments), 13 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.