fix(installer): reuse current CLI during reinstall

[senthilr-nv]

Summary

Re-running the maintained installer at the already installed revision rebuilt the NemoClaw CLI twice when sandboxes required a pre-upgrade backup. The installer now reuses a healthy installer-managed CLI at the selected revision and prepares any changed or explicitly repaired CLI only once per installer run.

Related Issue

Fixes #7898

Changes

• Reuse ~/.nemoclaw/source only when its commit matches the selected installer payload, its tracked state is clean, required dependency and build outputs exist, build identity matches, and the active CLI resolves inside that managed source with the expected version.
• Record CLI preparation within one installer process so the pre-upgrade backup phase and the normal install phase do not clone, build, or link the same selected source twice. Any failed reuse check retains the existing reinstall path.
• Preserve nemoclaw update --fresh as an explicit clean re-clone by passing an installer-internal repair request and consuming it before onboarding.
• Add external-command-stubbed installer orchestration tests for same-revision reuse, changed-revision installation, and explicit repair, plus the required installer-test project registrations.

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: The change only avoids redundant installer clone/build/link work. Existing commands and documented update --fresh repair behavior are unchanged.
• 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: Nine-category review passed at a824390d5 with no findings. Reuse remains bound to the selected payload commit, a user-owned clean managed checkout, required build and dependency markers, matching build identity, and a CLI path contained by that checkout; any failed check retains the existing reinstall path. No credential, authorization, dependency, cryptography, network, or privilege contract changed.
• 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: Reviewed the completed installer change, explanatory text, and all test titles at a824390d5. No findings remain. The delta from the previous review only corrects the CLI lifecycle term from rebuilds to reinstalls. Focused validation passed 44/44 tests, Vitest project membership was exact across 2,058 candidates, and the final diff passes git diff --check.
• 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 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 — test/install-managed-cli-reuse.test.ts passed 3/3; src/lib/actions/update.test.ts passed 18/18; test/test-boundary-guards.test.ts passed 41/41. CLI and plugin typechecks, repository checks, ShellCheck, test-size, source-shape, and Vitest project-membership checks passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• New Features

  • Repeated managed CLI installations now reuse an existing healthy checkout when the revision matches, avoiding unnecessary rebuilds.
  • Installations automatically rebuild when the source revision changes.
  • Fresh reinstalls now reliably force CLI reinstallation while preserving existing setup options.

• Bug Fixes

  • Improved validation prevents reuse of incomplete, modified, or incompatible managed installations.

[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: 9a033905-84ba-48c1-b62b-89e7cd2d5c49

📥 Commits

Reviewing files that changed from the base of the PR and between 453b5df and a824390.

📒 Files selected for processing (8)

• scripts/checks/no-test-dist-imports.mts
• scripts/checks/vitest-project-overlap.mts
• scripts/install.sh
• src/lib/actions/update.test.ts
• src/lib/actions/update.ts
• test/install-managed-cli-reuse.test.ts
• test/test-boundary-guards.test.ts
• vitest.config.ts

---

📝 Walkthrough

Walkthrough

The installer now validates and reuses matching managed CLI checkouts. It rebuilds invalid or changed checkouts, supports forced reinstall through NEMOCLAW_REINSTALL_CLI, and adds integration coverage for reuse and reinstall behavior.

Changes

Managed CLI reuse

Layer / File(s)	Summary
Installer reuse and finalization scripts/install.sh	The installer tracks preparation state and installation mode. It validates revisions, repository cleanliness, artifacts, CLI identity, and versions before reusing managed installations.
Forced reinstall environment src/lib/actions/update.ts, src/lib/actions/update.test.ts	Fresh updates clear inherited reinstall state and set NEMOCLAW_REINSTALL_CLI=1. Tests verify the environment and inherited standard I/O.
Installer integration coverage and project wiring test/install-managed-cli-reuse.test.ts, test/test-boundary-guards.test.ts, vitest.config.ts, scripts/checks/no-test-dist-imports.mts, scripts/checks/vitest-project-overlap.mts	Integration tests cover exact reuse, changed revisions, and forced reinstall. Test boundary and Vitest configuration classify the new test correctly.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UpdateAction
  participant Installer
  participant ManagedCheckout
  participant GitNpm
  UpdateAction->>Installer: set NEMOCLAW_REINSTALL_CLI for fresh update
  Installer->>ManagedCheckout: validate revision and installation state
  ManagedCheckout->>GitNpm: inspect checkout and build artifacts
  alt matching healthy checkout without force flag
    Installer->>ManagedCheckout: reuse CLI
  else changed or forced installation
    Installer->>GitNpm: clone, install dependencies, build, and link
  end
  Installer-->>UpdateAction: complete installation finalization

Loading

Suggested labels: area: cli, bug-fix

Suggested reviewers: apurvvkumaria, cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main installer change: reusing the existing CLI during reinstall.
Linked Issues check	✅ Passed	The changes address issue #7898 by reusing healthy managed CLI installations and testing same-revision reuse, changed revisions, and forced reinstall.
Out of Scope Changes check	✅ Passed	All changes support installer reuse, forced reinstall behavior, or related test configuration and coverage.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-express-same-version-install

---

_{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 a824390 in the codex/fix-express-sa... branch remains at 96%, unchanged from commit 643a4ab in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a824390 in the codex/fix-express-sa... branch remains at 81%, unchanged from commit a556201 in the main branch.

Show a code coverage summary of the most impacted files.

File	main a556201	codex/fix-express-sa... a824390	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/policy/...ne-exclusion.ts	96%	92%	-4%
src/lib/private-networks.ts	93%	90%	-3%
src/lib/shields/index.ts	70%	70%	0%
src/lib/actions...all/run-plan.ts	83%	84%	+1%
src/lib/inferen...ving/catalog.ts	91%	93%	+2%
src/lib/onboard...eway-process.ts	95%	97%	+2%
src/lib/state/g...way-registry.ts	94%	97%	+3%
src/lib/onboard...eway-cleanup.ts	59%	66%	+7%
src/lib/actions...ateway-ports.ts	0%	93%	+93%

---

_{Updated August 04, 2026 06:15 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

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

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

1 semantic terminology decision

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

• define — managed source at test/install-managed-cli-reuse.test.ts:172: Define this term if it is used outside test-local context; the test title is unambiguous.

E2E guidance

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

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

1 optional E2E recommendation

• bootstrap-install-smoke

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Test rejection of an external CLI during managed-source reuse

• Location: test/install-managed-cli-reuse.test.ts:172
• Category: tests
• Problem: The reuse tests cover a CLI symlink that resolves inside the managed source, but do not cover an expected-version CLI outside that source. The new containment check could be removed or inverted without these cases detecting the trust-boundary regression.
• Impact: A future change that weakens canonical CLI containment can reuse a managed installation while executing a CLI outside the validated source tree.
• Recommendation: Add an installer-integration case that places a version-valid CLI outside the managed source on PATH or in npm's bin directory, then assert the installer performs one clone, dependency install, build, and link sequence.
• Verification: Inspect the new fixture's CLI path and assert its canonical path is outside sourceRoot while the npm and git logs show one rebuild sequence.
• Test coverage: An installer integration test with an external expected-version CLI must assert that managed-source reuse is rejected and exactly one rebuild sequence occurs.
• Evidence: test/install-managed-cli-reuse.test.ts:81 creates fakeBin/nemoclaw as a symlink to sourceRoot/bin/nemoclaw.js. scripts/install.sh:1964-1983 permits reuse only when the resolved CLI path canonicalizes within source_root. test/install-managed-cli-reuse.test.ts:172-214 has no fixture case with a version-valid external CLI path.

Workflow run details

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