Skip to content

fix(service): put nvm's Node ahead of /usr/bin in the service PATH - #32108

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
bkarson:fix/nvm-service-path
Nov 9, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
bkarson:fix/nvm-service-path

Conversation

@bkarson

@bkarson bkarson commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A gateway installed with kirocrew service install runs MCP servers on the same nvm Node the installing shell used, not an older system Node.

On a host where Node 20+ comes from nvm and /usr/bin/node is older (Amazon Linux 2023 ships v18), the service gateway launches every #!/usr/bin/env node MCP server on the system Node. slack-mcp then refuses to start (Node version 18 detected, but version 20 or higher is required), and anything that depends on it fails quietly.

Why it matters

Every nvm user who installs the service on a host with an older system Node is hit, and nothing reports it: the gateway starts, and only the Node-20+ servers silently fail. The reporter's Slack sync sat dormant for 16 days before it was noticed.

Not a goal

  • Following a later nvm install without re-running service install. The baked PATH stays a snapshot, as it is today for every other dir.
  • Other Node managers (fnm, volta, asdf), and the macOS launchd PATH, which is unchanged.

What changed (motivation → approach → change)

Symptom: the service runs Node 18 although node -v in the installing shell printed v22. Root cause: service_path() puts /usr/local/bin:/usr/bin:/bin ahead of the installer's $PATH, and only mise's shims dir is moved in front of them. nvm has no shims, so its versioned bin dir landed behind /usr/bin.

Change: on Linux, nvm's versioned bin dirs found on the installer's $PATH (<root>/versions/node/<version>/bin) sit right after the mise shims, ahead of the system dirs. <root> must be one nvm installs to: ~/.nvm, the $XDG_CONFIG_HOME/nvm default, or the installer's $NVM_DIR, so no other dir is promoted. The dirs come from $PATH rather than $NVM_BIN, because nvm exports that variable only in shells that source nvm.sh and sudo usually drops it.

Backwards compatibility

Compatible: a PATH with no nvm entry produces exactly the same service PATH as before; with one, the only difference is the order of a dir that was already present.

Removes nothing: the change only reorders an existing entry.

Tests

Five tests in test/test_service_environment.py lock in the order: an nvm bin dir behind /usr/bin moves ahead of /usr/local/bin; it follows the mise shims; an $XDG_CONFIG_HOME/nvm root and a custom $NVM_DIR root are both promoted; and five look-alikes (a version dir, ~/.nvm/bin, a non-nvm node/<v>/bin, the nvm layout under a non-nvm root, a relative path) are not. Determinism: 20 sequential repeats green, plus -n 4 --dist load and a reversed node-id order.

Proof: PROVEN test/test_service_environment.py::TestServicePathMiseShims::test_installer_nvm_bin_behind_usr_bin_moves_ahead_of_it, test/test_service_environment.py::TestServicePathMiseShims::test_nvm_bin_follows_the_mise_shims, test/test_service_environment.py::TestServicePathMiseShims::test_xdg_nvm_root_is_promoted, test/test_service_environment.py::TestServicePathMiseShims::test_custom_nvm_dir_is_promoted (head b79026d)

Manual verification

On AL2023 with nvm Node 22.22.2 and system Node 18, the patched service_path() places ~/.nvm/versions/node/v22.22.2/bin before /usr/bin; unpatched main places it after. The reporter's workaround (the same order set by hand in /etc/kirocrew/kirocrew.env) restored slack-mcp.

Related Issues

Closes #32078

Sibling sweep

Swept: git grep -nE '/usr/local/bin|"PATH"' -- 'src/kiro_crew/service/*.py'
Sibling: src/kiro_crew/service/live_target.py:460 -- not affected -- prepends the target venv to the inherited PATH and adds no system dirs
Sibling: src/kiro_crew/service/macos.py -- not affected -- launchd PATH is deliberately left unchanged

Pattern harvest

Not generalizable: the defect is one hard-coded precedence list in a single function, already the only place the service PATH is built.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bkarson
bkarson requested review from a team and KiroCrewCaptain as code owners November 7, 2026 05:00
@bkarson
bkarson requested a review from tim-finnigan November 7, 2026 05:00
@bkarson

bkarson commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Local pre-push review: Opus lane (claude-opus-5.5) found no issues on b79026d. The GPT lane ran on gpt-5.6-sol, because gpt-6.1-sol and its gpt-6.x fallback were unavailable on my backend, so that local check is weaker than the server lane. Its first pass flagged nvm roots under $XDG_CONFIG_HOME/nvm and a custom $NVM_DIR. Both are now matched and covered by tests, and the second pass on b79026d found no issues.

@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 7, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving on b79026d. Tier T1, from #32078's tier:T1 label.

The change is small and in the right place: service_path() is the only function that builds the service PATH. The match is strict: an absolute path shaped like <root>/versions/node/<v>/bin, with <root> named .nvm or nvm, or equal to $NVM_DIR. Only an entry that is already on the installer's PATH moves, so nothing new is added. A PATH with no nvm entry gives the same result as before. I traced parts[-4:-2] and parents[3] for the default, XDG and custom roots, and the five look-alike cases are rejected. One commit, no merge commits.

test/test_service_environment.py passes locally on this head (43 passed).

The fork CI and AI review lanes have not run yet. They are waiting for maintainer approval of the workflow runs. Merge waits for those to go green.

AI-assisted, sent by CommunityCrew

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision e5a95cf7d9f30b408841d789f545c77b6c1aea8e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of e5a95cf7d9f30b408841d789f545c77b6c1aea8e via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this is a narrow, reversible reorder of a directory that was already on the PATH, and it fixes the root cause in the one function that builds the service PATH.

Notes

  • Under sudo, secure_path usually replaces $PATH as well as dropping $NVM_BIN, so a system-level install run through sudo may get no nvm entry at all and the fix won't apply. A one-line warning when /usr/bin/node is older than the installer's resolved Node would make that case visible instead of silent.

[DESIGN-REVIEWED] e5a95cf

Description read

[DESCRIPTION-READ] dc2b92f827df14c12245ca4de9d51c9f62588416d083c6a539eda28a7d2a58ad

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of e5a95cf7d9f30b408841d789f545c77b6c1aea8e via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

The fix itself is sound. One premise is wider than described: the root test accepts any dir named nvm or .nvm, not only the roots nvm installs to, and it re-encodes knowledge env.py already owns.

Notes

  • Item 3 — undeclared, duplicate of src/kiro_crew/env.py:264 (_NVM_ROOTS / nvm_dirs()): the description says "<root> must be one nvm installs to: ~/.nvm, the $XDG_CONFIG_HOME/nvm default … so no other dir is promoted", but the hunk tests root.name in (".nvm", "nvm"), which also promotes /opt/nvm/versions/node/*/bin. Subtraction: replace the name test with membership in kiro_crew.env.nvm_dirs() (plus $NVM_DIR), the one list that file says "every nvm lookup derives from".
  • Item 1 — symptom-level point patch: the cause is the hard-coded system dirs placed ahead of the installer's PATH. That is now special-cased twice (mise, nvm), while 5 sibling manager layouts in env.py _NODE_MANAGER_GLOBS/_NODE_MANAGER_DIRS (asdf, 4 fnm globs) plus volta still land behind /usr/bin. ## Not a goal defers them, so this is accepted.

What this change ships

Inventory (3 items) — 1 justified

Intent: a gateway installed as a service runs MCP servers on the installer's nvm Node, not an older system Node. FIX.

  1. On Linux, nvm version bin dirs from the installer's PATH now come before /usr/local/bin:/usr/bin:/bin in the service PATH — symptom-level (mise and nvm special-cased; asdf, fnm and volta siblings deferred)
  2. A custom $NVM_DIR root is also recognised — justified
  3. Any root dir named nvm or .nvm, anywhere on disk, is treated as an nvm root — undeclared, duplicate of env.py _NVM_ROOTS

[FIRST-PRINCIPLES-REVIEWED] e5a95cf

Description read

[DESCRIPTION-READ] ac1be364cb95ca911d53e1599b3f27660ef119ec92ad2cd26cea4132abd7fa10

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed e5a95cf7d9f30b408841d789f545c77b6c1aea8e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e5a95cf

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed e5a95cf7d9f30b408841d789f545c77b6c1aea8e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e5a95cf

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes on b79026d. CI ran on this head, and one red comes from this PR:

  • Backend Lint & Type Check (3.12), black check: test/test_service_environment.py is not black-formatted. Fix: black --target-version py310 test/test_service_environment.py, then push.

Coverage Gate is red only because that lint job failed, so the test shards never ran. It should clear once lint passes. The code change itself still looks right to me.

AI-assisted, sent by CommunityCrew

service_path() put /usr/local/bin:/usr/bin:/bin ahead of the installer's
PATH and promoted only mise's shims, so on a host whose system Node is
older than nvm's (AL2023 ships v18), every #!/usr/bin/env node MCP server
the service gateway starts ran on the system Node. nvm's versioned bin
dirs on the installer's PATH, under ~/.nvm, $XDG_CONFIG_HOME/nvm or
$NVM_DIR, now follow the mise shims ahead of the system dirs.

Closes kirodotdev#32078
@bkarson
bkarson force-pushed the fix/nvm-service-path branch from b79026d to e5a95cf Compare November 8, 2026 22:20
@bkarson

bkarson commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Thanks! Fixed in e5a95cf: I ran black --target-version py310 test/test_service_environment.py. The change is formatting only, with no logic change and still one commit. scripts/check_black_formatting.py passes, and the 43 service-environment tests, flake8 and isort are green. I left src/kiro_crew/service/common.py alone because it is on .github/black-baseline.txt, and reformatting it would touch lines outside this fix. Ready for another look whenever you have a moment.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 9, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving e5a95cf. The range-diff against b79026d is black formatting only in test/test_service_environment.py, and Backend Lint & Type Check passes now. GPT 6.1 and Opus 5.5 have no blocking findings. Thanks @bkarson.

Security Scope Review still shows "scope never resolved" from a run that hit GitHub's API rate limit (tracked in #33604). That isn't a finding on this change, and we're fixing the lane.

AI-assisted, sent by CommunityCrew

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 9, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving on e5a95cf. All 94 checks are green, and I read the whole diff.

On Linux, service_path now puts nvm's versioned Node bin dirs from the installer's $PATH right after the mise shims and ahead of /usr/local/bin and /usr/bin. A service then runs the Node the installing shell resolved, not an older system one. nvm has no shims, so the PATH entry is the only signal.

_nvm_bin_dirs promotes an entry only when it is an absolute <root>/versions/node/<version>/bin whose root is named .nvm or nvm, or is the installer's absolute $NVM_DIR. It uses PurePosixPath parts, so an unrelated dir is never moved ahead of the system dirs. The tests cover the default, XDG and custom roots, the order after the shims, and five entries that must not be promoted. launchd's PATH is unchanged.

No regex, no new restrictions.

@bolichen97
bolichen97 merged commit 94c62ba into kirodotdev:main Nov 9, 2026
100 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 9, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Post-merge note from a review that finished after this merged (head e5a95cf).

This change and #33125 (on main before it) combine into a regression. With both, src/kiro_crew/service/common.py:368 (required += _nvm_bin_dirs(env_path)) makes the promoted nvm dir an anchor in env.augmented_path, so the data home's glibc-2.17 Node (env_node_pins.data_home_tree_dirs) now lands behind nvm.

Trigger: an Amazon Linux 2 host where nvm's default Node is v16, or a v18+ build that does not load, install.sh has installed <data-home>/node-glibc217, and the operator runs kirocrew service install from a shell with nvm on PATH. Outcome: every npx or #!/usr/bin/env node MCP server resolves the nvm Node and fails to start, where before the merge it resolved the glibc-2.17 Node. With a fake home holding both trees and an installer PATH of <nvm v16>:/usr/bin:/bin, shutil.which("node", path=env.mcp_search_path("")) returned node-glibc217/bin/node before and .nvm/versions/node/v16.20.2/bin/node after. No current test covers the case.

Smallest fix: skip the nvm promotion when data_home_tree_dirs(...) finds a tree, or place that tree ahead of the promoted nvm dirs in service_path, plus one test that combines an nvm dir on the service PATH with a present glibc-2.17 tree.

bolichen97 pushed a commit that referenced this pull request Nov 9, 2026
…32108)

service_path() put /usr/local/bin:/usr/bin:/bin ahead of the installer's
PATH and promoted only mise's shims, so on a host whose system Node is
older than nvm's (AL2023 ships v18), every #!/usr/bin/env node MCP server
the service gateway starts ran on the system Node. nvm's versioned bin
dirs on the installer's PATH, under ~/.nvm, $XDG_CONFIG_HOME/nvm or
$NVM_DIR, now follow the mise shims ahead of the system dirs.

Closes #32078

Co-authored-by: Barrett Karson <barkar@amazon.com>

Backport note: docstring-only conflict in service_path: release's
paragraph on the mise shims dir is kept and main's nvm paragraph
follows it. The code hunks apply as on main.

(cherry picked from commit 94c62ba)
bolichen97 pushed a commit that referenced this pull request Nov 9, 2026
…32108)

service_path() put /usr/local/bin:/usr/bin:/bin ahead of the installer's
PATH and promoted only mise's shims, so on a host whose system Node is
older than nvm's (AL2023 ships v18), every #!/usr/bin/env node MCP server
the service gateway starts ran on the system Node. nvm's versioned bin
dirs on the installer's PATH, under ~/.nvm, $XDG_CONFIG_HOME/nvm or
$NVM_DIR, now follow the mise shims ahead of the system dirs.

Closes #32078

Co-authored-by: Barrett Karson <barkar@amazon.com>

Backport note: docstring-only conflict in service_path: release's
paragraph on the mise shims dir is kept and main's nvm paragraph
follows it. The code hunks apply as on main.

(cherry picked from commit 94c62ba)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kirocrew service install pins the gateway to system Node 18 when Node comes from nvm

3 participants