fix(installer): preserve Hermes GPU fallback selection

[apurvvkumaria]

Summary

Source-checkout installs now retain an absolute executable selected through NEMOCLAW_OPENSHELL_BIN after refreshing user-local OpenShell discovery, while continuing to stage the existing gateway service. This prevents the Hermes GPU fallback test from silently bypassing its fault-injection wrapper and exercising the native route instead.

Related Issue

Related to #7140.
Follow-up to #6333.

Changes

• Preserve the caller-selected absolute OpenShell executable in the source-checkout if-missing path after adding the user-local OpenShell directory to PATH.
• Keep the feat(gateway): manage the default gateway service #7319 gateway-service staging call and the fresh/pinned OpenShell installation path unchanged.
• Add focused E2E-support coverage proving that service staging observes the fallback wrapper, the real gateway component, and the user-local discovery path.
• Reject restoration of a relative executable selection so invalid overrides continue to fall back to the discovered user-local OpenShell binary.

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: This restores the existing documented NEMOCLAW_OPENSHELL_BIN override contract and preserves the already-documented managed gateway-service behavior.
• 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: Exact-head nine-category security review passed with no findings: fix(installer): preserve Hermes GPU fallback selection #7710 (comment)
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: At exact head 03d134564, the review confirmed that docs/reference/commands.mdx already documents the OpenShell executable override and docs/reference/architecture.mdx already documents managed gateway-service staging. Rejecting an absolute directory as a binary does not change a supported user workflow.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• 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
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — hermes-gpu-startup-fallback.test.ts passed 17/17 at exact head; install-preflight.test.ts passed 94/94; CLI type-check and diff-scoped hooks passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable to this two-file source-checkout selection repair; focused tests and diff-scoped hooks cover the changed behavior.
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved installer handling when a custom OpenShell executable is configured.
  • Preserved valid absolute executable selections during managed gateway setup.
  • Added safeguards to fall back to the correct installed OpenShell binary when configured paths are relative or point to directories.
  • Improved reliability of Hermes GPU startup fallback service selection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8d426378-7a1b-4e35-91f1-089c9150c03e

📥 Commits

Reviewing files that changed from the base of the PR and between 2fb69d8 and 03d1345.

📒 Files selected for processing (2)

• scripts/install.sh
• test/e2e/support/hermes-gpu-startup-fallback.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/e2e/support/hermes-gpu-startup-fallback.test.ts
• scripts/install.sh

---

📝 Walkthrough

Walkthrough

The installer preserves a valid explicitly selected OpenShell binary during macOS gateway service staging. End-to-end tests cover fallback-wrapper reporting and normalization of invalid relative or directory selections.

Changes

OpenShell service selection

Layer / File(s)	Summary
Preserve valid OpenShell binary selection scripts/install.sh	The installer captures NEMOCLAW_OPENSHELL_BIN and uses it during the macOS fallback path only when it is an absolute executable.
Validate service staging selection test/e2e/support/hermes-gpu-startup-fallback.test.ts	End-to-end tests verify service-selection output, fallback-wrapper selection, and replacement of relative or directory paths with the absolute temporary openshell binary.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: install

🚥 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 is clear and matches the main installer fix around preserving the Hermes GPU fallback selection.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/hermes-gpu-fallback-events

---

_{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 03d1345 in the codex/hermes-gpu-fal... branch remains at 96%, unchanged from commit c3ab052 in the main branch.

Show a code coverage summary of the most impacted files.

File	main c3ab052	codex/hermes-gpu-fal... 03d1345	+/-
nemoclaw/src/plugin-config.ts	100%	0%	-100%
nemoclaw/src/index.ts	94%	94%	0%

TypeScript / code-coverage/cli

The overall coverage in commit 03d1345 in the codex/hermes-gpu-fal... branch is 80%. The coverage in commit c3ab052 in the main branch is 81%.

Show a code coverage summary of the most impacted files.

File	main c3ab052	codex/hermes-gpu-fal... 03d1345	+/-
src/lib/onboard...rovider-shim.ts	67%	33%	-34%
src/lib/onboard...andbox-reuse.ts	86%	61%	-25%
src/lib/state/registry.ts	93%	85%	-8%
src/lib/state/o...d-checkpoint.ts	90%	87%	-3%
src/lib/onboard.ts	31%	31%	0%
src/lib/onboard...lers/sandbox.ts	96%	97%	+1%
src/lib/onboard...itial-policy.ts	94%	95%	+1%
src/lib/actions...ard-recovery.ts	93%	95%	+2%
src/lib/state/r...ry-messaging.ts	48%	79%	+31%
src/lib/policy/context.ts	0%	91%	+91%

---

_{Updated July 28, 2026 16:45 UTC}

[apurvvkumaria]

Security review — exact head 2fb69d8d1150d03118d3144ae7432975a67a6f17

Verdict

PASS — safe to merge from a security perspective, subject to required CI and maintainer review.

The change restores the existing, documented NEMOCLAW_OPENSHELL_BIN selection only when it is an absolute path to an executable file. It does not broaden the executable trust boundary, change privilege handling, or alter the fresh/pinned OpenShell installation path. The existing managed gateway-service staging remains in place and continues to resolve the real gateway sibling.

Findings

Severity	Finding
—	No security findings

Detailed analysis

1. Secrets and credentials — PASS. No secrets, tokens, credential values, or secret-bearing output were added. Diff-scoped gitleaks passed.
2. Input validation — PASS. Restoration requires both an absolute path (/*) and an executable file (-x). Regression coverage confirms a relative executable selection is rejected in favor of normal user-local discovery.
3. Authentication and authorization — PASS / not applicable. No endpoint, identity, authorization, or permission behavior changed.
4. Dependencies and supply chain — PASS. No dependency, lockfile, image, action, or downloaded artifact changed.
5. Error handling and logging — PASS. Production logging is unchanged. Tests expose only controlled temporary fixture paths and do not serialize command arguments or credentials.
6. Cryptography and data protection — PASS / not applicable. No cryptographic or persisted-data behavior changed.
7. Configuration and service integrity — PASS. The existing gateway-service staging call is retained. Tests verify it receives the preserved wrapper selection, the real sibling gateway binary, and the user-local-first discovery path.
8. Security testing — PASS. Focused tests cover accepted absolute selection, rejected relative selection, service staging, real gateway resolution, and PATH behavior. Existing fallback tests continue to assert that secret markers and credential-shaped values are absent from artifacts.
9. System security — PASS. The forced/fresh install route is unchanged, no new privilege boundary is introduced, and the change remains inside the existing caller-controlled executable override contract.

Files reviewed

• scripts/install.sh
• test/e2e/support/hermes-gpu-startup-fallback.test.ts

Reviewed range: 8a0f36f612cd8c58e53c22fd6e52d10193ee593d...2fb69d8d1150d03118d3144ae7432975a67a6f17.

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@scripts/install.sh`:
- Around line 1540-1541: Reject absolute directory paths in the OpenShell
override validation by requiring both a regular file and executable permissions
in the install script condition around explicit_openshell_bin. Add an
absolute-directory test case to hermes-gpu-startup-fallback.test.ts that
verifies the fallback resolves to ${realDir}/openshell.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 60c5bc1f-f80c-4343-a38b-94590761dc08

📥 Commits

Reviewing files that changed from the base of the PR and between 8a0f36f and 2fb69d8.

📒 Files selected for processing (2)

• scripts/install.sh
• test/e2e/support/hermes-gpu-startup-fallback.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 · high 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 E2E selections match; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, security-posture

1 optional E2E recommendation

• hermes-gpu-startup

Workflow run details

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

[apurvvkumaria]

Security review — exact head 03d134564d14eccbd3a8a7b0f4e78181fa1e939d

Verdict

PASS — safe to merge from a security perspective, subject to required CI and maintainer review.

The change restores the existing, documented NEMOCLAW_OPENSHELL_BIN selection only when it is an absolute path to an executable regular file. It does not broaden the executable trust boundary, change privilege handling, or alter the fresh/pinned OpenShell installation path. The existing managed gateway-service staging remains in place and continues to resolve the real gateway sibling.

Findings

Severity	Finding
—	No security findings

Detailed analysis

1. Secrets and credentials — PASS. No secrets, tokens, credential values, or secret-bearing output were added. Diff-scoped gitleaks passed.
2. Input validation — PASS. Restoration requires an absolute path (/*) to a regular file (-f) with executable permissions (-x). Regression coverage confirms both relative executable selections and absolute directories are rejected in favor of normal user-local discovery.
3. Authentication and authorization — PASS / not applicable. No endpoint, identity, authorization, or permission behavior changed.
4. Dependencies and supply chain — PASS. No dependency, lockfile, image, action, or downloaded artifact changed.
5. Error handling and logging — PASS. Production logging is unchanged. Tests expose only controlled temporary fixture paths and do not serialize command arguments or credentials.
6. Cryptography and data protection — PASS / not applicable. No cryptographic or persisted-data behavior changed.
7. Configuration and service integrity — PASS. The existing gateway-service staging call is retained. Tests verify it receives the preserved wrapper selection, the real sibling gateway binary, and the user-local-first discovery path.
8. Security testing — PASS. Focused tests cover accepted absolute-file selection, rejected relative selection, rejected absolute-directory selection, service staging, real gateway resolution, and PATH behavior. Existing fallback tests continue to assert that secret markers and credential-shaped values are absent from artifacts.
9. System security — PASS. The forced/fresh install route is unchanged, no new privilege boundary is introduced, and the change remains inside the existing caller-controlled executable override contract.

Files reviewed

• scripts/install.sh
• test/e2e/support/hermes-gpu-startup-fallback.test.ts

Reviewed range: 8a0f36f612cd8c58e53c22fd6e52d10193ee593d...03d134564d14eccbd3a8a7b0f4e78181fa1e939d.