fix(install): keep the managed checkout clean after dependency install

[laitingsheng]

Summary

The installer's own npm install normalizes the committed lockfile while it builds the tree, so the checkout at ~/.nemoclaw/source was dirty by the time the reuse check ran. Before this change every installer re-run failed that check and took the destructive branch, removing the checkout and cloning and rebuilding it again; after it, a re-run at the installed revision reuses the checkout as intended.

Related Issue

Fixes #8305

Changes

• scripts/install.sh: add restore_managed_source_lockfile and call it after the managed branch finishes its npm steps, so the checkout the installer owns stays at the installed revision. The source-checkout branch is untouched, because that tree belongs to the contributor.
• test/install-managed-cli-reuse.test.ts: the git stub answered diff with an unconditional exit 0, so the reuse check passed in tests while it could never pass on a real install. The stub now reports a dirty tree from state the npm stub writes during install and the checkout case clears, and the build stubs write the artifacts the reuse check inspects.
• test/install-managed-cli-reuse.test.ts: add a case covering a later installer run, which reuses the checkout instead of cloning again.

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: no user-facing surface changes. docs/reference/commands.mdx already documents --fresh as the clean re-clone escape hatch for a broken-but-current install, which describes the behavior this change restores.
• 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:
• 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: no documentation paths changed. The change restores the reuse behavior that docs/reference/commands.mdx already describes through the --fresh re-clone escape hatch, so no page needs an edit.
• Agent: Claude Code

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: npx vitest run --project installer-integration test/install-managed-cli-reuse.test.ts — 4 passed. With the new restore_managed_source_lockfile call removed, the added case fails and the three existing cases still pass.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Managed source installations now restore the project lockfile after building and linking the CLI.
  • If lockfile restoration fails, installation continues with a warning instead of stopping unexpectedly.
  • Reusing an existing managed checkout now avoids unnecessary setup, dependency installation, and linking operations.
  • Managed installations remain reusable after a separate dependency-installation run, providing a more reliable installation experience.

[coderabbitai]

📝 Walkthrough

Walkthrough

The installer restores package-lock.json for managed Git checkouts after installation. The reuse tests simulate dirty lockfiles, separate runs, and restoration failures.

Changes

Managed checkout reuse

Layer / File(s)	Summary
Restore managed lockfile scripts/install.sh	Adds restore_managed_source_lockfile and invokes it for managed GitHub installations after dependency installation, builds, and CLI linking.
Validate repeated installation test/install-managed-cli-reuse.test.ts	Extends fake Git and npm behavior, supports separate installer runs, and verifies checkout reuse and warning-based continuation when restoration fails.

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

🚥 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 installer fix that keeps the managed checkout clean for reuse.
Linked Issues check	✅ Passed	The changes restore the managed lockfile and add tests for clean checkout reuse, meeting issue #8305 objectives.
Out of Scope Changes check	✅ Passed	The changes are limited to lockfile restoration and installer reuse test coverage described by issue #8305.

✨ 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 fix/installer-checkout-reuse

---

_{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 c4a2d38 in the fix/installer-checko... branch remains at 96%, unchanged from commit 28fdd78 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit c4a2d38 in the fix/installer-checko... branch remains at 81%, unchanged from commit 28fdd78 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 28fdd78	fix/installer-checko... c4a2d38	+/-
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated August 05, 2026 10:38 UTC}

[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 terminology decisions differ; normalized E2E selections match; severity counts match.

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.

• justified — managed checkout at test/install-managed-cli-reuse.test.ts:250: Keep “managed checkout” where lifecycle ownership distinguishes this checkout from a contributor source checkout.

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.

[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 2062-2066: Update restore_managed_source_lockfile to return the
git checkout failure instead of suppressing it with || true, and ensure its
caller at the managed installation flow around line 2150 propagates the failure
and stops installation. Add a regression test covering a failed
package-lock.json restoration and verify the installation does not continue or
remove and reclone the checkout.

🪄 Autofix

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: e9cb02a0-310c-45a4-9909-5ce7a29a1130

📥 Commits

Reviewing files that changed from the base of the PR and between 3a39ff3 and bac9688.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-managed-cli-reuse.test.ts

[coderabbitai]

🧹 Nitpick comments (3)

test/install-managed-cli-reuse.test.ts (3)

246-258: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert the fallback warning.

The test checks Could not restore package-lock.json, the absence of the reuse message, and a second git init. It does not check that the warning identifies the removal-and-reclone fallback.

Add an assertion for a stable fallback-specific warning substring. This prevents the test from passing when the user receives no recovery guidance.

Based on the PR objective, the warning must identify the removal-and-reclone fallback.

🤖 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-managed-cli-reuse.test.ts` around lines 246 - 258, The test case
run by runManagedCliInstallTwice should also assert that result.stdout contains
the stable warning substring identifying the removal-and-reclone fallback,
alongside the existing lockfile, reuse-message, and git-init assertions.

---

136-149: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Reject unsupported build commands in the fake npm.

The case "$*" patterns match any command containing build. The run branch has no failure path for unknown commands. A mistyped build script can return success and create artifacts, so the test can miss a broken installer command.

Match the exact run build:cli and run build commands. Exit with a failure for unsupported npm run commands.

As per path instructions, do not let a broad mock bypass the behavior under test.

🤖 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-managed-cli-reuse.test.ts` around lines 136 - 149, Update the
fake npm command handling around the run-command case so it matches only the
exact supported commands “run build:cli” and “run build”, rather than any
argument containing “build”. Add a failure path for unsupported npm run
commands, ensuring mistyped build scripts exit nonzero without creating
artifacts.

Source: Path instructions

---

103-109: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Make the lockfile fixture verify the managed file.

The fake npm install only creates .fixture-lockfile-dirty at Line 135. The fake Git path clears that marker for any checkout command at Lines 103 and 107-109. It does not validate package-lock.json or restore its contents.

The pre-existing writeManagedSource fixture also has no lockfile. The test can therefore pass with a wrong checkout target or without verifying restored content. Create a baseline package-lock.json, mutate it during fake installation, require checkout -- package-lock.json, and assert the baseline content before cleanup.

As per path instructions, review this test through observable lockfile behavior instead of a private dirty marker.

Also applies to: 135-135

🤖 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-managed-cli-reuse.test.ts` around lines 103 - 109, Update the
lockfile fixture and fake Git/npm flows around writeManagedSource and the
checkout handling so a baseline package-lock.json is created, fake installation
mutates its contents, and only checkout -- package-lock.json restores the
baseline. Remove reliance on the private .fixture-lockfile-dirty marker, and
assert the restored package-lock.json content before cleanup to verify
observable lockfile behavior.

Source: Path instructions

🤖 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-managed-cli-reuse.test.ts`:
- Around line 246-258: The test case run by runManagedCliInstallTwice should
also assert that result.stdout contains the stable warning substring identifying
the removal-and-reclone fallback, alongside the existing lockfile,
reuse-message, and git-init assertions.
- Around line 136-149: Update the fake npm command handling around the
run-command case so it matches only the exact supported commands “run build:cli”
and “run build”, rather than any argument containing “build”. Add a failure path
for unsupported npm run commands, ensuring mistyped build scripts exit nonzero
without creating artifacts.
- Around line 103-109: Update the lockfile fixture and fake Git/npm flows around
writeManagedSource and the checkout handling so a baseline package-lock.json is
created, fake installation mutates its contents, and only checkout --
package-lock.json restores the baseline. Remove reliance on the private
.fixture-lockfile-dirty marker, and assert the restored package-lock.json
content before cleanup to verify observable lockfile behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2d817c9f-3b9e-4666-ac24-c21ee88e3375

📥 Commits

Reviewing files that changed from the base of the PR and between bac9688 and a79a511.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-managed-cli-reuse.test.ts

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

• scripts/install.sh

[coderabbitai]

🧹 Nitpick comments (1)

test/install-managed-cli-reuse.test.ts (1)

251-262: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the no-rebuild outcome.

The test proves one initialization, one install, and one link operation. It does not prove that npm run --if-present build:cli or npm run build runs only during the first installer run. A regression that rebuilds the reused checkout can still pass this test.

Add a build sentinel or an assertion that each build command occurs once across both runs.

As per path instructions, make the test prove the no-rebuild behavior instead of only checking the current command sequence.

🤖 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-managed-cli-reuse.test.ts` around lines 251 - 262, Add coverage
in the managed CLI reuse test around runManagedCliInstallTwice to verify
build:cli and build commands each execute exactly once across both installer
runs. Use the existing command log or a build sentinel, while preserving the
current initialization, install, link, lockfile, and reuse assertions.

Source: Path instructions

🤖 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-managed-cli-reuse.test.ts`:
- Around line 251-262: Add coverage in the managed CLI reuse test around
runManagedCliInstallTwice to verify build:cli and build commands each execute
exactly once across both installer runs. Use the existing command log or a build
sentinel, while preserving the current initialization, install, link, lockfile,
and reuse assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6e37349f-2f2e-4c0d-81d1-7b4f85c3c3f6

📥 Commits

Reviewing files that changed from the base of the PR and between a79a511 and c4a2d38.

📒 Files selected for processing (1)

• test/install-managed-cli-reuse.test.ts

[apurvvkumaria]

The current branch has 43 passing checks, no pending or failed checks, and no unresolved review threads. The addressed review finding now also has a written disposition in its thread. The remaining merge blocker is independent approval.