fix(installer): reject OpenShell gateway version skew

[prekshivyas]

Summary

The installer now stops before onboarding when an existing Linux OpenShell user service would start a different gateway version from NemoClaw's pinned user-local gateway. Previously, the mixed versions reached inference setup and failed with an unsupported-operation error.

Related Issue

Fixes #8051

Changes

• Compare the pinned user-local OpenShell gateway version with the gateway version supplied by an existing upstream systemd user service.
• Reject a mismatch before provider or sandbox mutation and report both versions, binary paths, and apt remediation.
• Preserve the existing upstream-service path when both gateway versions match.
• Require the NemoClaw-selected gateway binary to use an existing trusted install path before executing its version command.
• Add regression coverage for matching 0.0.85 versions and the reproduced 0.0.85 CLI with 0.0.91 gateway mismatch.
• Document the mismatch, package-removal risk, remediation, and verification result in the shared troubleshooting guide.

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:
• 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: Codex Desktop completed the nine-category security review for commit 973ca20e70d6f7c90914cc51eae009d48ebcd283 against base b7249323aa08aff8ced7a309f6823e84ac1ded0d; PASS with no findings. The NemoClaw-selected gateway remains restricted to trusted install paths, the effective upstream systemd command must resolve to one absolute executable openshell-gateway, and missing, malformed, ambiguous, or version-mismatched evidence fails before service, provider, or sandbox mutation.
• 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: docs-updated
• Evidence: docs/reference/troubleshooting.mdx; reviewed the gateway-version mismatch, package-removal warning, recovery command, and acceptance criterion against scripts/install.sh and test/install-openshell-gateway-service.test.ts at the current commit. The merge-only renewal leaves the effective three-file PR change unchanged.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: GitHub CI passed installer-integration, all CLI test shards, aggregate checks, macOS, WSL, and E2E / PR Gate for commit 973ca20e70d6f7c90914cc51eae009d48ebcd283. The focused installer test previously passed 11/11 at bb2a1faa105295745f94262a5c845ce198112419; the only later commit merges main and leaves the effective three-file PR change unchanged.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not run because the change is limited to one installer compatibility boundary with focused integration coverage.
• 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: Prekshi Vyas prekshiv@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Linux installation checks for conflicts between existing system OpenShell gateways and the NemoClaw gateway.
  • Installation now stops before onboarding when gateway binaries are missing, unreadable, untrusted, or version-mismatched.
  • Error messages identify detected gateway versions and locations, preventing incompatible service setup.
  • Gateway detection now uses the service’s configured executable path for more accurate validation.

• Documentation

  • Added troubleshooting guidance for resolving gateway version conflicts, including package removal steps and instructions for rerunning the installer.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The installer validates an existing upstream OpenShell gateway before onboarding. It compares binary paths and versions, stops on unsafe or mismatched binaries, and provides remediation guidance. Tests cover matching versions, mismatches, and systemd-configured paths.

Changes

Gateway compatibility handling

Layer / File(s)	Summary
Validate upstream gateway compatibility scripts/install.sh	The installer resolves the gateway path from systemd, validates binary trust and executability, compares versions, and stops before staging an incompatible upstream service.
Cover mismatch handling and remediation test/install-openshell-gateway-service.test.ts, docs/reference/troubleshooting.mdx	Tests cover matching and mismatched versions and systemd path resolution. Troubleshooting guidance documents diagnostics, resource warnings, APT removal, and installer rerun steps.

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

Sequence Diagram(s)

sequenceDiagram
  participant Installer
  participant Systemd
  participant GatewayBinaries
  Installer->>Systemd: Resolve effective ExecStart path
  Systemd-->>Installer: Upstream gateway binary path
  Installer->>GatewayBinaries: Read NemoClaw and upstream versions
  GatewayBinaries-->>Installer: Version and path data
  Installer->>Installer: Stop on mismatch before onboarding

Loading

Possibly related issues

• NVIDIA/NemoClaw issue 8110: Both changes affect upstream gateway service installation, but this PR validates version compatibility while issue 8110 addresses service reload and restart behavior.

Possibly related PRs

• NVIDIA/NemoClaw#8098: Both PRs validate the systemd-selected upstream gateway binary, but this PR applies validation during installation and PR 8098 applies it during onboarding.

Suggested labels: platform: ubuntu, area: onboarding, bug-fix, area: docs

Suggested reviewers: apurvvkumaria

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The installer compares gateway versions, reports paths and remediation, preserves matching services, and stops before onboarding on mismatch.
Out of Scope Changes check	✅ Passed	The code, tests, and troubleshooting documentation directly support the linked issue and contain no unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the installer change that rejects OpenShell gateway version mismatches.

✨ 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 agent/reject-openshell-version-skew

---

_{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 973ca20 in the agent/reject-openshe... branch remains at 96%, unchanged from commit f504948 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 973ca20 in the agent/reject-openshe... branch remains at 81%, unchanged from commit 00c6111 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 00c6111	agent/reject-openshe... 973ca20	+/-
src/lib/actions...ce-preflight.ts	78%	50%	-28%
src/lib/onboard...ization-deps.ts	83%	58%	-25%
src/lib/actions...ess-recovery.ts	84%	82%	-2%
src/lib/actions...licy-channel.ts	81%	80%	-1%
src/lib/policy/index.ts	59%	59%	0%
src/lib/actions...oy-execution.ts	89%	95%	+6%
nemoclaw/src/se...cret-scanner.ts	0%	11%	+11%
nemoclaw/src/index.ts	0%	51%	+51%
nemoclaw/src/banner.ts	0%	87%	+87%
nemoclaw/src/plugin-config.ts	0%	100%	+100%

---

_{Updated August 04, 2026 09:20 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8053.docs.buildwithfern.com/nemoclaw

[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 1316-1329: Update
resolve_upstream_openshell_gateway_bin_for_service to resolve the effective
systemd user-service configuration, including applicable drop-ins, and extract
the gateway binary from its ExecStart rather than inferring it from the
unit-file directory. Return failure when ExecStart is missing or the gateway
binary cannot be identified, and add coverage for a service whose ExecStart
differs from the conventional package path.

🪄 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: 83febefd-d565-4d4a-9e6d-a8bb2016ad05

📥 Commits

Reviewing files that changed from the base of the PR and between 0de2789 and 51c31e1.

📒 Files selected for processing (3)

• docs/reference/troubleshooting.mdx
• scripts/install.sh
• test/install-openshell-gateway-service.test.ts

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 7 warnings · 0 suggestions

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

2 semantic terminology decisions

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

• justified — upstream OpenShell user service at scripts/install.sh:1355: Keep the modifier because it identifies the service ownership and command source.
• define — OpenShell gateway version mismatch at docs/reference/troubleshooting.mdx:531: Keep the term and its adjacent explanation of the compared gateway versions and remediation.

E2E guidance

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

Recommended E2E: cloud-onboard

1 optional E2E recommendation

• openshell-gateway-upgrade

Blockers

PRA-1 Blocker — Do not execute an untrusted upstream service binary

• Location: scripts/install.sh:1358
• Category: security
• Problem: The installer extracts the effective gateway path from the existing upstream systemd user service and runs that executable with `--version` without validating its ownership or write permissions. A user-controlled systemd drop-in can point the service at an attacker-controlled executable named `openshell-gateway`; that executable then runs in the installer environment, which can contain provider credentials.
• Impact: An attacker who can alter the user service command can execute arbitrary code and read installer environment credentials before onboarding starts.
• Fix: Before invoking the upstream gateway, require a trusted root-owned, non-user-writable package path and reject every other path. Add a test that a writable service-selected gateway is rejected and never executed.
• Verification: Inspect `resolve_upstream_openshell_gateway_bin_for_service` and `openshell_binary_version`; confirm that the parsed `path=` value reaches `"$binary" --version` with no trust or ownership validation.
• Test coverage: Add an installer-service test whose effective `ExecStart` selects a user-writable `openshell-gateway`; assert the installer fails before invoking it and before staging or starting a service.
• Evidence: scripts/install.sh:1321-1344 accepts a single absolute executable path ending in `openshell-gateway` from `systemctl --user show` output. scripts/install.sh:1354-1359 passes the resolved upstream path to `openshell_binary_version`, which executes `"$binary" --version`. scripts/install.sh:1349-1352 validates only the NemoClaw-selected binary with `trusted_openshell_gateway_bin_for_service`; no equivalent validation applies to the upstream path. test/install-openshell-gateway-service.test.ts:169-234 covers version match, mismatch, and an overridden command but not rejection without execution of a writable selected binary.

Workflow run details

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

[prekshivyas]

Functional DGX Spark evidence:

• Initial package-skew reproduction used OpenShell 0.0.91-1 with NemoClaw-selected 0.0.85 and stopped before onboarding without service, provider, sandbox, or listener mutation.
• Revalidated exact current PR head ed342847 after merging current main, using a real systemd user unit plus an ExecStart drop-in override.
• systemctl --user show reported the effective overridden gateway (0.0.91) rather than the conventional package path.
• The installer resolved that effective path, compared it with the user-local 0.0.85 binary, exited 1 with both versions and remediation, and left the service inactive with no listener on :8080 or :17670.
• Focused installer suite passed 11/11 and complete local PR validation passed.
• Temporary unit, drop-in, binary, and output files were removed; systemd was reloaded.

Result: PASS.

[prekshivyas]

Addressed the CodeRabbit linked-issue warning by updating #8051’s acceptance criteria to the safe implementation boundary recorded in the issue discussion: preserve matching-version upstream services, but stop before onboarding on version mismatch. Automatic replacement or disabling of the separately managed apt service is intentionally out of scope. The exact-head DGX Spark functional evidence confirms the mismatch path performs no service, provider, or sandbox mutation.

[apurvvkumaria]

Approve — reviewed exact head e2f18f2. The installer resolves the effective systemd user-service ExecStart, requires one executable openshell-gateway path, compares the installed and active semantic versions, and fails before onboarding or service mutation on skew. Tests cover matching versions, mismatch diagnostics, and a drop-in-overridden ExecStart; exact-head DGX Spark evidence and CI pass. I found no blocking correctness, security, compatibility, or regression defect.

[apurvvkumaria]

Approve — reviewed exact head bb2a1fa. The only post-review change replaces Bash mapfile with a portable read loop while preserving exact-one executable resolution. Focused installer coverage passes 11 of 11 tests. I accounted for the existing automated ambiguous-ExecStart coverage warning and am not duplicating it; it is non-blocking. No blocking correctness, security, compatibility, or regression defect found.