fix(install): bootstrap OpenShell on git-clone source installs

[laitingsheng]

Summary

On a fresh host, git clone NemoClaw && bash install.sh lands in the source-checkout branch of install_nemoclaw, which intentionally skipped the OpenShell CLI install — the assumption being that a developer running ./scripts/install.sh manages their own openshell. End users following the documented install flow still ended up at the [3/3] Onboarding step with the circular hint "Run the NemoClaw installer or scripts/install-openshell.sh", telling them to re-run the installer they were already inside.

Related Issue

Fixes #3989

Changes

• scripts/install.sh: in the source-checkout branch, invoke scripts/install-openshell.sh when command_exists openshell is false. The bootstrap respects NEMOCLAW_DEFER_OPENSHELL_INSTALL=1, matching the existing GitHub-clone branch contract. A developer who already has openshell on PATH keeps autonomy: any version skips the install.
• test/install-preflight.test.ts: two new tests covering the source-checkout bootstrap (invoke when missing, skip when present). Existing source-checkout tests opt in to NEMOCLAW_DEFER_OPENSHELL_INSTALL=1 so they don't fetch openshell over the network.

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)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features

  • Installer now consistently ensures the OpenShell CLI is available during setup for both persistent source checkouts and cloned installs.
  • Added a configurable defer option and smarter install modes to control whether/install when OpenShell is installed.

• Tests

  • Expanded installer tests to verify OpenShell install behavior and added source-checkout scenarios; tests pass the defer flag in preflight runs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a shared helper to conditionally install OpenShell during install.sh and updates installer paths to call it; tests add NEMOCLAW_DEFER_OPENSHELL_INSTALL to spawned installer envs and include source-checkout cases that assert install vs skip behavior.

Changes

OpenShell Auto-Install Bootstrap

Layer / File(s)	Summary
Shared helper and install.sh call sites scripts/install.sh	Adds maybe_install_openshell_during_install(mode) and updates the source-checkout and GitHub-clone branches of install_nemoclaw to call it (if-missing and force).
Test updates and new source-checkout tests test/install-preflight.test.ts	Adds NEMOCLAW_DEFER_OPENSHELL_INSTALL=1 to spawned installer envs across tests and introduces two source-checkout tests verifying that the installer invokes scripts/install-openshell.sh when openshell is missing and skips it when present.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

bug, Platform: Windows/WSL

Suggested reviewers

• ericksoa

Poem

🐰 A rabbit hops through install scripts with cheer,
Adds a helper so OpenShell can appear.
Tests sit politely with their env set aside,
Now onboarding won't loop — it can proceed with pride. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing the install script to bootstrap OpenShell during git-clone source installs, which directly addresses the problem in issue #3989.
Linked Issues check	✅ Passed	The code changes comprehensively implement the primary objective from #3989: install.sh now auto-installs OpenShell during source-checkout installs, making the bootstrap flow self-sufficient on fresh machines while respecting the defer environment variable.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the stated objective: extracting OpenShell bootstrap logic, adding it to the source-checkout branch, and adding comprehensive tests for the new behavior; no unrelated modifications detected.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 fix/install-source-openshell-3989

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: onboard-resume-e2e, cloud-onboard-e2e
Optional E2E: openshell-gateway-upgrade-e2e, launchable-smoke-e2e

Dispatch hint: onboard-resume-e2e,cloud-onboard-e2e

Auto-dispatched E2E: onboard-resume-e2e, cloud-onboard-e2e via nightly-e2e.yaml at 8367546d08da824d9a427a40612a84e893a20c0e — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• onboard-resume-e2e (high): Runs bash install.sh from a checked-out PR before exercising onboarding resume. This is the closest existing E2E to the changed source-checkout installer path and should prove that a CI host without openshell gets OpenShell bootstrapped and can continue into real onboarding.
• cloud-onboard-e2e (high): Exercises the public/curl installer path, validates the GitHub-clone branch still installs OpenShell, puts nemoclaw and openshell on PATH, and completes real OpenClaw cloud onboarding plus sandbox/security checks.

Optional E2E

• openshell-gateway-upgrade-e2e (high): Useful adjacent confidence because the refactor preserves NEMOCLAW_DEFER_OPENSHELL_INSTALL semantics for the pre-upgrade backup flow before installing/upgrading OpenShell.
• launchable-smoke-e2e (medium): Optional broader install confidence: verifies a community/bootstrap install path leaves both nemoclaw and openshell available and can onboard a sandbox, though it is less directly tied to scripts/install.sh source-checkout behavior.

New E2E recommendations

• source-checkout installer OpenShell bootstrap (medium): Existing scenario-based repo-current setup links the CLI directly and does not run scripts/install.sh, so scenario coverage may miss regressions where a fresh git clone runs the installer with openshell absent from PATH.
  • Suggested test: Add a scenario or nightly job that starts from a clean Ubuntu runner/source checkout, runs scripts/install.sh or install.sh with openshell absent, asserts install-openshell.sh ran, then verifies openshell and nemoclaw are on PATH before onboarding.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: onboard-resume-e2e,cloud-onboard-e2e

[github-actions]

PR Review Advisor

Recommendation: blocked
Confidence: high
Analyzed HEAD: 8367546d08da824d9a427a40612a84e893a20c0e
Findings: 2 blocker(s), 1 warning(s), 1 suggestion(s)

This is an automated advisory review. A human maintainer must make the final merge decision.

Limitations: Review used trusted deterministic context plus read-only file/diff inspection; no tests, scripts, package-manager commands, installers, or PR-provided instructions were executed.; The provided diff is truncated, but the changed hunks for scripts/install.sh and test/install-preflight.test.ts relevant to this review were available.; No passing required E2E result for onboard-resume-e2e or cloud-onboard-e2e at 8367546 was included in the trusted context.; A selective E2E success comment exists for an older SHA and was not counted for this head.; Review-thread state was reported as unavailable/unknown despite GraphQL returning an empty reviewThreads.nodes array.; Linked issue #3989 has no comments in the trusted context, so acceptance extraction is based on the issue body only.

Workflow run

Full advisor summary

PR Review Advisor

Base: origin/main
Head: HEAD
Analyzed SHA: 8367546d08da824d9a427a40612a84e893a20c0e
Recommendation: blocked
Confidence: high

The installer fix is small and well-targeted, with unit coverage for the new source-checkout OpenShell bootstrap, but the PR is blocked by GitHub merge state and missing required E2E results for the current head SHA.

Gate status

• CI: pass — 5 required status context(s) completed with no failures for 8367546: checks, commit-lint, dco-check, check-hash, changes. Non-required contexts still pending: 3; failed: 0.
• Mergeability: fail — mergeStateStatus=BLOCKED for PR fix(install): bootstrap OpenShell on git-clone source installs #4060 at head 8367546; GraphQL also reports reviewDecision=REVIEW_REQUIRED.
• Review threads: unknown — No review thread state was available in the trusted gate context. GraphQL reviewThreads.nodes is empty, but unresolved-thread state was not independently confirmed.
• Risky code tested: warning — Risky areas detected: installer/bootstrap shell and onboarding/host glue. test/install-preflight.test.ts adds source-checkout OpenShell bootstrap tests, but trusted testDepth says scripts/install.sh requires E2E coverage.

🔴 Blockers

• PR merge state is blocked: The PR cannot be treated as merge-ready while GitHub reports mergeStateStatus=BLOCKED and reviewDecision=REVIEW_REQUIRED for the current head SHA, even though required status contexts are green.
  • Recommendation: Resolve the repository merge gate and required review state, then re-check mergeability for head SHA 8367546.
  • Evidence: Trusted context: mergeStateStatus=BLOCKED; graphQl.pullRequest.reviewDecision=REVIEW_REQUIRED; headRefOid=8367546d08da824d9a427a40612a84e893a20c0e.
• Required E2E results are missing for the current installer bootstrap change (scripts/install.sh:1397): The PR changes installer/bootstrap shell that affects fresh-host OpenShell installation and onboarding. E2E Advisor requires onboard-resume-e2e and cloud-onboard-e2e for this head SHA, and states they were auto-dispatched, but no passing result for those required jobs at 8367546 was provided. A selective E2E success comment exists only for the older SHA 7f4dcf9 and cannot satisfy this head.
  • Recommendation: Wait for onboard-resume-e2e and cloud-onboard-e2e to complete successfully for 8367546, or provide trusted status evidence tied to exactly that SHA.
  • Evidence: E2E Advisor comment: Required E2E: onboard-resume-e2e, cloud-onboard-e2e; Auto-dispatched via nightly-e2e.yaml at 8367546. No matching pass result is present in the provided context.

🟡 Warnings

• Unit tests stub install-openshell.sh and cannot prove real install/onboard behavior (test/install-preflight.test.ts:628): The added tests verify the intended invocation semantics when OpenShell is missing or present, but they replace scripts/install-openshell.sh and openshell with local stubs. This is appropriate unit coverage, but it does not validate real download/checksum behavior, PATH refresh, user-local OpenShell preference, architecture handling, or successful onboarding after bootstrap.
  • Recommendation: Keep the unit tests, and rely on required E2E for the real source-checkout installer path with OpenShell initially absent.
  • Evidence: New tests write a fake scripts/install-openshell.sh that appends 'install-openshell.sh invoked' and exits 0; trusted testDepth verdict is e2e_required for scripts/install.sh.

🔵 Suggestions

• Concurrent PRs overlap the same installer files (scripts/install.sh:1397): The patch applies to active files that still exist, but open PRs feat(hermes): request network access through policy local #3750 and fix(installer): preserve npm lockfiles during install #4029 also touch scripts/install.sh and test/install-preflight.test.ts. This increases conflict or behavior-drift risk in the installer path.
  • Recommendation: Before final merge, compare the final diff against overlapping installer PRs and ensure the OpenShell bootstrap helper and tests are not overwritten or contradicted.
  • Evidence: Trusted openPrOverlaps: PR feat(hermes): request network access through policy local #3750 and PR fix(installer): preserve npm lockfiles during install #4029 list sameFiles: scripts/install.sh and test/install-preflight.test.ts. Drift evidence shows both files have recent active history.

Acceptance coverage

• met — On a fresh Windows ARM WSL2 install (no OpenShell present), running bash install.sh from the NemoClaw source tree completes [1/3] Node.js and [2/3] NemoClaw CLI successfully, then aborts at [3/3] Onboarding with:: The PR addresses this failure path by calling maybe_install_openshell_during_install if-missing in the source-checkout branch after npm link and before refresh/verify/onboarding. This should prevent the missing-OpenShell preflight from being the reason onboarding aborts.
• met — This is circular advice: the user is currently running the NemoClaw installer (bash install.sh).: The source-checkout path now runs scripts/install-openshell.sh automatically when command_exists openshell is false, removing the need for the user to re-run the installer or manually discover the script in the targeted path.
• met — Either:: The PR satisfies the either/or by implementing option (a).
• met — - (a) install.sh should run scripts/install-openshell.sh itself as part of step [2/3] or [3/3], OR: scripts/install.sh adds maybe_install_openshell_during_install and invokes it in the source-checkout branch after 'Linking NemoClaw CLI', which is part of the phase [2/3] install flow.
• met — - (b) The error message should explicitly say "Run scripts/install-openshell.sh" and drop the "Run the NemoClaw installer" suggestion (which is the loop the user is already in).: This alternate clause is not directly implemented, but the issue accepted (a) OR (b); option (a) is implemented.
• partial — 1. Fresh WSL2 Ubuntu-24.04 (no NemoClaw, no OpenShell, no nemoclaw artifacts in ~/.local/bin or ~/.nemoclaw).: Unit tests create a fresh temp HOME and fake PATH with no openshell for the missing-OpenShell case, but a real fresh WSL2 Ubuntu-24.04 run has not been confirmed for the current head SHA in the provided E2E results.
• partial — 2. Clone NemoClaw main HEAD:: Tests simulate a source checkout using package.json plus .git/NEMOCLAW_REPO_ROOT. They do not perform a real git clone of the current head in the unit test. E2E Advisor requires onboard-resume-e2e for closest source-checkout coverage.
• partial — 3. Run install.sh:: Tests spawn bash [INSTALLER] with NEMOCLAW_NON_INTERACTIVE=1 and NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1, but real installer execution with actual OpenShell download/onboarding awaits required E2E results for this head SHA.
• met — 4. install.sh completes [1/3] Node.js and [2/3] NemoClaw CLI successfully. At [3/3] Onboarding, observe the error.: The regression path is changed so OpenShell bootstrap occurs during phase [2/3] before onboarding preflight can emit the circular missing-OpenShell error. New tests assert install-openshell.sh is invoked when OpenShell is absent.
• met — Either:: The Expected Result either/or is satisfied by option (a).
• met — - (a) install.sh runs scripts/install-openshell.sh as part of its bootstrap so the user gets OpenShell installed in the same flow, OR: scripts/install.sh calls spin "Installing OpenShell CLI" bash "${NEMOCLAW_SOURCE_ROOT}/scripts/install-openshell.sh" through the helper; the source-checkout call uses if-missing mode.
• met — - (b) install.sh's "OpenShell missing" error says exactly which script to run, without suggesting the installer the user is already running.: Not directly changed, but not required because option (a) is implemented.
• partial — In either case the install.sh flow should be self-sufficient on a fresh box (Node → NemoClaw CLI → OpenShell → onboard). Today it stops one step short and leaves a confusing breadcrumb.: Code order now installs Node/NemoClaw, then invokes OpenShell bootstrap before onboarding. Unit tests cover helper invocation and skip behavior. Full self-sufficient fresh-box behavior still needs onboard-resume-e2e and cloud-onboard-e2e passes for 8367546.
• partial — User experience:: The code targets the UX issue by avoiding manual OpenShell discovery in the source-checkout flow, but runtime UX confirmation is pending required E2E for the current head.
• met — - nemoclaw onboard still fails because OpenShell is genuinely not installed.: The changed source-checkout installer should leave OpenShell installed when it was absent, so subsequent onboarding should no longer fail solely because OpenShell is missing.
• met — - User has to discover separately that the fix is bash ~/NemoClaw-main/scripts/install-openshell.sh, not "re-run install.sh".: The installer now discovers and runs ${NEMOCLAW_SOURCE_ROOT}/scripts/install-openshell.sh automatically when OpenShell is missing.
• partial — Possibly a regression of NVB#6000851 / GH#708 (Closed Fixed 2026-04-16) which described "nemoclaw onboard will automatically install openshell in the PATH ~/.local/bin/openshell" — that bug suggested auto-install was working.: This PR restores auto-install behavior for install.sh source-checkout installs, but it does not directly test the older nemoclaw onboard auto-install contract. Required E2E should validate OpenShell availability and onboarding.
• met — Discovered during ARM64 validation for PR chore: upgrade agent runtime dependencies #3925 QA but is not PR-introduced — reproduces on main HEAD cfa817b.: The PR is a targeted fix to active installer files. Trusted drift evidence confirms scripts/install.sh and test/install-preflight.test.ts still exist and have recent history; no rename drift was reported.
• met — Linked issue comments: Trusted context reports issue [WSL2][Install] install.sh does not auto-install OpenShell, aborts onboard with circular "Run the NemoClaw installer" advice #3989 has comments: 0, so there are no linked issue comments to extract.

Security review

• pass — 1. Secrets and Credentials: No hardcoded secrets, tokens, passwords, PEM/key material, credential JSON, or secret logging were added. Test fixtures use temp paths and local stubs only.
• warning — 2. Input Validation and Data Sanitization: The installer now executes ${NEMOCLAW_SOURCE_ROOT}/scripts/install-openshell.sh from the checkout when OpenShell is missing. This is consistent with the trusted installer source-checkout model and variables are quoted, but it remains high-risk shell execution of checkout-local code in an installer path.
• pass — 3. Authentication and Authorization: Not applicable — no endpoints, authentication flows, authorization decisions, token validation, or privilege-boundary checks are added or modified.
• warning — 4. Dependencies and Third-Party Libraries: No new dependency is added, but the change expands when the existing OpenShell installer runs during source-checkout installs. The PR relies on existing install-openshell.sh supply-chain controls and does not itself alter pinning/checksum verification.
• pass — 5. Error Handling and Logging: No sensitive data is logged. The helper uses existing info/spin behavior and preserves explicit deferral logging when NEMOCLAW_DEFER_OPENSHELL_INSTALL is set.
• pass — 6. Cryptography and Data Protection: Not applicable — this diff introduces no cryptographic operations, key handling, encryption, hashing, or transport-security logic.
• pass — 7. Configuration and Security Headers: No HTTP endpoints, CORS/CSP, Dockerfile, container user, port exposure, or security-header configuration changes are introduced. The existing deferral environment variable remains respected.
• warning — 8. Security Testing: Unit tests cover the positive missing-OpenShell path and the negative already-present path with stubs, and unrelated installer tests opt into deferral to avoid unintended network bootstrap. Because this is installer/bootstrap shell affecting real host onboarding, required E2E remains necessary and has not been observed passed for the current head SHA.
• warning — 9. Holistic Security Posture: The change improves install reliability and reduces a confusing failure loop. No sandbox escape, SSRF bypass, policy bypass, credential leakage, blueprint tampering, or workflow trusted-code-boundary issue was found in the diff. Overall posture still depends on real E2E validation of download/PATH/onboarding behavior.

Test / E2E status

• Test depth: e2e_required — Runtime/sandbox/infrastructure paths need real execution coverage: scripts/install.sh. Unit tests validate invocation semantics but cannot prove real OpenShell download, PATH refresh, architecture handling, or onboarding behavior.
• E2E Advisor: missing
• Required E2E jobs: onboard-resume-e2e, cloud-onboard-e2e
• Missing for analyzed SHA: onboard-resume-e2e, cloud-onboard-e2e

✅ What looks good

• The PR is small and scoped to the linked installer bug: only scripts/install.sh and test/install-preflight.test.ts changed.
• The new helper centralizes OpenShell bootstrap behavior and preserves NEMOCLAW_DEFER_OPENSHELL_INSTALL=1 for pre-upgrade backup flows.
• The source-checkout path uses if-missing mode, preserving developer autonomy when an openshell binary is already on PATH.
• The existing GitHub-clone path is refactored through the same helper in force mode, reducing duplicate installer logic.
• New tests cover both missing-OpenShell invocation and already-present skip behavior.
• Existing source-checkout tests were updated with NEMOCLAW_DEFER_OPENSHELL_INSTALL=1 to avoid accidental network/bootstrap side effects.
• Required CI status contexts are green for the current head SHA.

Review completeness

• Review used trusted deterministic context plus read-only file/diff inspection; no tests, scripts, package-manager commands, installers, or PR-provided instructions were executed.
• The provided diff is truncated, but the changed hunks for scripts/install.sh and test/install-preflight.test.ts relevant to this review were available.
• No passing required E2E result for onboard-resume-e2e or cloud-onboard-e2e at 8367546 was included in the trusted context.
• A selective E2E success comment exists for an older SHA and was not counted for this head.
• Review-thread state was reported as unavailable/unknown despite GraphQL returning an empty reviewThreads.nodes array.
• Linked issue [WSL2][Install] install.sh does not auto-install OpenShell, aborts onboard with circular "Run the NemoClaw installer" advice #3989 has no comments in the trusted context, so acceptance extraction is based on the issue body only.
• Human maintainer review required: yes

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26276434173
Target ref: 7f4dcf9ef29fc199eca9dc3d904c845dfc2a54d2
Workflow ref: main
Requested jobs: cloud-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
cloud-e2e	✅ success

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26277942536
Target ref: 8367546d08da824d9a427a40612a84e893a20c0e
Workflow ref: main
Requested jobs: onboard-resume-e2e,cloud-onboard-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-resume-e2e	✅ success

[ericksoa]

Approved. I reviewed the installer bootstrap change and the independent adversarial pass found no blockers. Local validation also passed: npm run build:cli, full test/install-preflight.test.ts (98/98), and git diff --check. Live PR checks are green on head 8367546.