fix(installer): resolve the CLI through the user-local shim

[cv]

Summary

Fixes installer verification when npm prefix changes leave NemoClaw available only through the user-local shim. The installer now probes the shim after the npm-prefix checks and records whether the calling shell needs a PATH refresh.

This replacement preserves Dongni Yang's original commit from #8440 and adds the missing regression coverage.

Related Issue

Closes #8311

Changes

• Probe the user-local shim when the active npm prefix does not expose the CLI.
• Re-check command resolution before recording readiness so a rejected binary that shadows the shim keeps the PATH-refresh guidance.
• Cover stale-prefix, shadowing, shim-on-PATH, npm-uninstall, and missing-shim behavior.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: docs/reference/troubleshooting.mdx already explains how to source the shell profile and add ~/.local/bin to PATH. The removed installer failure was not documented.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: An independent review passed all nine security categories for PR commit d2b1ea5139076b45bf366dcec04a3a75dd8cf49e against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711. The existing shim trust boundary does not change.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: No waiver is recorded.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Reviewed scripts/install.sh, test/install-npm-resolution.test.ts, and the existing user-local shim recovery in docs/reference/troubleshooting.mdx for PR commit d2b1ea5139076b45bf366dcec04a3a75dd8cf49e against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711. The change removes an undocumented failure and retains the documented recovery action. The review covered repository terminology, test titles, comments, security wording, and documentation ownership; no documentation or code sample changed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh does not change.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub — both contributor commits and the current-main refresh commit are GitHub Verified.
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable — normal hooks passed for the contributor fix, remediation, and current-main refresh.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — GitHub Actions is authoritative; no standalone local test suite ran for the reviewed replacement commit.
• Applicable broad gate passed — GitHub Actions has not completed for the replacement PR.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — not applicable; no documentation changes.
• Doc pages follow the style guide (doc changes only) — not applicable; no documentation changes.
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new page.

---

Signed-off-by: Dongni Yang dongniy@nvidia.com
Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved CLI detection when the active npm installation path does not contain the command.
  • Added support for valid user-local CLI shims.
  • Provides clearer onboarding guidance when PATH needs refreshing.
  • Correctly resolves valid shims and removes conflicting invalid command entries.
  • Reports a clear failure when no usable CLI installation is found.

• Tests

  • Added coverage for local shim discovery, PATH handling, conflicting binaries, and missing installations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The installer now checks the user-local nemoclaw shim when the active npm prefix lacks the CLI. It validates the shim, handles PATH readiness and refresh messaging, and continues onboarding through its absolute path. Tests cover fallback, shadowing binaries, recovery, and failure.

Changes

CLI shim verification

Layer / File(s)	Summary
User-local shim fallback scripts/install.sh	verify_nemoclaw validates the user-local shim, records its path, determines readiness from PATH, and supports onboarding through the shim.
Shim resolution test coverage test/install-npm-resolution.test.ts	Tests simulate stale npm-prefix environments and cover shim fallback, PATH refresh hints, shadowing-binary removal, successful resolution, and missing-CLI failure.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#8440: Implements the same user-local shim fallback and overlapping installer-resolution tests.

Suggested labels: area: install, bug-fix

Suggested reviewers: brandonpelfrey, dnandakumar-nv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: resolving the CLI through the user-local shim during installation.
Linked Issues check	✅ Passed	The installer independently checks the user-local shim and handles PATH refresh and shadowing cases required by issue #8311.
Out of Scope Changes check	✅ Passed	The changes are limited to shim resolution in the installer and regression tests for the linked issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/salvage-8440-user-shim-ready

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit d2b1ea5 in the codex/salvage-8440-u... branch remains at 96%, unchanged from commit 2f29784 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit d2b1ea5 in the codex/salvage-8440-u... branch remains at 82%, unchanged from commit 2f29784 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 2f29784	codex/salvage-8440-u... d2b1ea5	+/-
src/lib/onboard...shboard-port.ts	96%	90%	-6%
src/lib/inferen...y-production.ts	48%	48%	0%
src/lib/core/immutable.ts	97%	97%	0%
src/lib/messagi...flow-planner.ts	93%	93%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/actions...air-approval.ts	89%	90%	+1%
src/lib/inferen...er-discovery.ts	87%	88%	+1%

---

_{Updated August 06, 2026 07:19 UTC}

[coderabbitai]

🧹 Nitpick comments (1)

test/install-npm-resolution.test.ts (1)

429-429: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use the repository POSIX PATH separator.

Replace path.delimiter with ":" in these test PATH values. These tests run on POSIX environments in CI. This keeps the new cases consistent with the established test convention.

Based on learnings: “prefer the established POSIX PATH separator : when constructing process.env.PATH in tests” and “Do not replace it with path.delimiter.”

Also applies to: 444-444, 467-467

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/install-npm-resolution.test.ts` at line 429, Update the PATH
constructions in the affected test cases to use the POSIX separator ":" instead
of path.delimiter, including the entries around tree.fakeBin, tree.shimPath, and
TEST_SYSTEM_PATH. Keep the existing PATH component order and test behavior
unchanged.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/install-npm-resolution.test.ts`:
- Line 429: Update the PATH constructions in the affected test cases to use the
POSIX separator ":" instead of path.delimiter, including the entries around
tree.fakeBin, tree.shimPath, and TEST_SYSTEM_PATH. Keep the existing PATH
component order and test behavior unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ae68882d-a3e8-4868-ab15-200550484679

📥 Commits

Reviewing files that changed from the base of the PR and between 2f29784 and d2b1ea5.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-npm-resolution.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• bootstrap-install-smoke: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• spark-install: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• double-onboard: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — user-local shim at scripts/install.sh:2245: Keep `user-local shim`; existing installer, contributor, and test text uses the same meaning.
• justified — active npm prefix at scripts/install.sh:2244: Keep `active npm prefix`; the modifier identifies the stale-prefix case that controls fallback behavior.
• established — PATH-refresh at test/install-npm-resolution.test.ts:419: Keep `PATH-refresh`; it uses the established PATH-refresh concept for the emitted guidance.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, managed-image-multiarch-startup

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.