fix(install): report installed version from the requested tag

[laitingsheng]

Summary

The curl | bash installer stamped the installed version from git describe on a shallow clone. When a release tag is lightweight and the checkout is not exactly on the tagged commit, describe resolves to a different nearby tag, so nemoclaw --version reported an older release than the one requested. The installer now pins the checkout to the requested ref and records the version from that ref, so the reported version matches the tag that was installed.

Related Issue

Fixes #7474

Changes

• clone_nemoclaw_ref: fetch the requested ref into an explicit local ref and check that out, pinning HEAD to the exact object the ref names instead of relying on FETCH_HEAD.
• Add resolve_stamped_version: map an immutable version tag to its semver and record it in .version. Mutable refs (lkg, latest) and non-version refs return empty and keep the previous git describe fallback, whose only current consumers are development clones and CI, which have no .version file.
• resolve_installer_version: read the stamped .version before git describe, since .version records the exact requested tag while describe on a shallow clone can resolve a different nearby tag.
• Extend installer integration coverage for lightweight-tag checkout, stamped-version precedence in both entrypoints, and the exact private refspec used by the piped bootstrap installer.

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: internal installer version-reporting fix; no user-facing documentation surface.
• 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: maintainer security review found no credential, policy, injection, or ref-integrity regression; the fix pins both installer entrypoints to the exact fetched ref.
• 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: The change makes a requested version tag check out and report that exact release. docs/get-started/quickstart.mdx already tells users to select a versioned release with NEMOCLAW_INSTALL_TAG=vX.Y.Z and clear the higher-priority NEMOCLAW_INSTALL_REF; docs/reference/commands.mdx already defines --version as the installed CLI version and documents both selector variables and precedence. The PR changes no command, flag, environment variable, install procedure, or documented output contract, so no docs page needs a change. The current-main topper leaves the effective four-file product diff byte-identical to the independently reviewed diff (SHA-256 950459d8c82d4364060853cafe9f27e82820994f8f787b5ff453f47409139872).
• 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 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 — command/result: installer-integration test/install-preflight.test.ts → 94 passed; combined test/install-preflight.test.ts and test/install-clone-ref.test.ts → 98 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved installer version detection for GitHub-based installations.
  • Ensured installations from immutable tags check out the exact requested version.
  • Added reliable fallback behavior when stamped version information is unavailable.
  • Improved handling of mutable references such as latest and lkg.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 53025a7 in the codex/7474-installer... branch remains at 96%, unchanged from commit 9171d79 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 53025a7 in the codex/7474-installer... branch remains at 80%, unchanged from commit 9171d79 in the main branch.

---

_{Updated July 25, 2026 05:17 UTC}

[coderabbitai]

📝 Walkthrough

Walkthrough

The installer now fetches requested refs into a deterministic local ref, checks out the exact target commit, and stamps .version from immutable semantic-version tags when available. Version resolution prioritizes stamped metadata, with tests covering checkout, fallback, and unavailable-ref behavior.

Changes

Installer versioning

Layer / File(s)	Summary
Deterministic ref checkout and version stamping scripts/install.sh, install.sh	Requested refs are shallow-fetched into refs/nemoclaw-install/target; immutable tag refs provide the stamped version, while other refs fall back to git describe. Stamped .version metadata takes precedence during version resolution.
Checkout and version resolution validation test/install-clone-ref.test.ts, test/install-preflight.test.ts	Tests verify lightweight-tag checkout, immutable versus mutable ref handling, .version precedence and fallback, and the updated refspec recorded for unavailable refs.

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

Sequence Diagram(s)

sequenceDiagram
  participant Installer
  participant Git
  participant VersionFile
  Installer->>Git: Fetch requested ref into target ref
  Installer->>Git: Checkout target ref
  Installer->>VersionFile: Write resolved version
  VersionFile-->>Installer: Provide stamped version

Loading

Suggested reviewers: cv, sandl99, chengjiew

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The ref checkout and .version stamping changes address #7474’s exact commit, version reporting, and git describe issues.
Out of Scope Changes check	✅ Passed	The changes stay within installer ref handling and version-reporting tests, with no clear unrelated additions.
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 matches the main change: installer version reporting is fixed to use the requested tag.

✨ 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/7474-installer-lightweight-tag-version

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 more blocker, the same number of warnings, the same number of suggestions.

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-onboard

1 optional E2E recommendation

• bootstrap-install-smoke

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

🧹 Nitpick comments (1)

test/install-clone-ref.test.ts (1)

132-179: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Consider covering both installer entrypoints for parity with tests 1 & 2.

This test only runs resolve_installer_version against CURL_PIPE_INSTALLER (line 159); tests 1 and 2 loop over both INSTALLER_PAYLOAD and CURL_PIPE_INSTALLER. Since CURL_PIPE_INSTALLER resolves to a different file than the one under review in scripts/install.sh, extending this test to also exercise INSTALLER_PAYLOAD would confirm the .version-precedence fix is verified on the source-checkout entrypoint as well, not just the curl-pipe one.

♻️ Suggested parity fix

-      const resolve = () =>
+      const resolve = (installer: string) =>
         spawnSync(
           "bash",
           [
             "-c",
             'source "$INSTALLER_UNDER_TEST"\nprintf START\nresolve_installer_version\nprintf STOP',
           ],
           {
             encoding: "utf8",
             env: {
               ...process.env,
-              INSTALLER_UNDER_TEST: CURL_PIPE_INSTALLER,
+              INSTALLER_UNDER_TEST: installer,
               NEMOCLAW_REPO_ROOT: tmp,
               NEMOCLAW_INSTALL_REF: "",
               NEMOCLAW_INSTALL_TAG: "",
             },
           },
         );
-
-      fs.writeFileSync(path.join(tmp, ".version"), "0.0.93");
-      const withStamp = resolve();
-      expect(withStamp.status, withStamp.stderr).toBe(0);
-      expect(extract(withStamp.stdout)).toBe("0.0.93");
-
-      fs.rmSync(path.join(tmp, ".version"));
-      const withoutStamp = resolve();
-      expect(withoutStamp.status, withoutStamp.stderr).toBe(0);
-      expect(extract(withoutStamp.stdout)).toBe("0.0.38");
+
+      for (const installer of [INSTALLER_PAYLOAD, CURL_PIPE_INSTALLER]) {
+        fs.writeFileSync(path.join(tmp, ".version"), "0.0.93");
+        const withStamp = resolve(installer);
+        expect(withStamp.status, withStamp.stderr).toBe(0);
+        expect(extract(withStamp.stdout)).toBe("0.0.93");
+
+        fs.rmSync(path.join(tmp, ".version"));
+        const withoutStamp = resolve(installer);
+        expect(withoutStamp.status, withoutStamp.stderr).toBe(0);
+        expect(extract(withoutStamp.stdout)).toBe("0.0.38");
+      }

🤖 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-clone-ref.test.ts` around lines 132 - 179, Update the test
around the resolve helper in “reports the stamped .version over a mismatched git
describe (`#7474`)” to exercise both installer entrypoints, INSTALLER_PAYLOAD and
CURL_PIPE_INSTALLER, rather than only CURL_PIPE_INSTALLER. Run the existing
stamped and unstamped assertions for each entrypoint while preserving the
current expected versions and cleanup behavior.

🤖 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 173-182: Update the top-level install.sh fetch and checkout flow
to match clone_nemoclaw_ref: fetch the requested ref into
refs/nemoclaw-install/target instead of relying on FETCH_HEAD, then check out
that exact target with detached-head advice disabled. Preserve the existing ref
validation and error handling.

---

Nitpick comments:
In `@test/install-clone-ref.test.ts`:
- Around line 132-179: Update the test around the resolve helper in “reports the
stamped .version over a mismatched git describe (`#7474`)” to exercise both
installer entrypoints, INSTALLER_PAYLOAD and CURL_PIPE_INSTALLER, rather than
only CURL_PIPE_INSTALLER. Run the existing stamped and unstamped assertions for
each entrypoint while preserving the current expected versions and cleanup
behavior.

🪄 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: 83ae291f-6995-4f40-b9fc-d7c891dcd1da

📥 Commits

Reviewing files that changed from the base of the PR and between 46ecb86 and d70942f.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-clone-ref.test.ts

[apurvvkumaria]

Fix-forward after infrastructure loss: the exact-head cloud-onboard run was classified as confirmed hosted-runner loss, but the controller’s one linked retry could not start because its stale workflow ancestry check rejected current main. I dispatched the documented run-control-plane fallback for current exact head 74681a9b608fe724be15815a931b023574f5e2bf and base 46ecb867773c6fd745e3d250a5fa9b09e0214002: https://github.com/NVIDIA/NemoClaw/actions/runs/30139735244. No code regression was identified; this rerun supplies the remaining exact-head cloud-onboard evidence.

[apurvvkumaria]

Fix-forward update: the manual run-control-plane fallback correctly declined because this diff selects non-credentialed cloud-onboard only; it is not an authorization-required plan. I have rerun the successful exact-head CI / Pull Request run so the normal workflow-run controller is recreated from current main, avoiding the stale workflow-ancestry failure without changing the PR. Merge readiness remains gated on the resulting exact-head E2E verdict.

[apurvvkumaria]

Reviewed exact head 732dbc0 after the signed sync with current main.\n\nEvidence:\n- installer-integration validation passed: 98/98\n- exact-head ordinary CI passed\n- exact-head cloud-onboard E2E passed\n- canonical PR Review Advisor ledger reports 0 blockers, 0 warnings, 0 suggestions and no follow-up needed\n- no unresolved review threads\n- signed sync commit is GitHub Verified and preserves the contributor's original commits\n\nThe standalone Nemotron lane ended with an analysis-execution failure; the canonical primary Terra assessment completed successfully and classifies the PR as informational with no actionable findings.

[apurvvkumaria]

Advisor PRA-1 is a false positive on exact head 53025a7. The root bootstrap intentionally sources scripts/install.sh when the versioned payload marker is present, so both tested entry points expose resolve_stamped_version and resolve_installer_version. Exact-head verification passes: test/install-clone-ref.test.ts is 4/4, and sourcing install.sh directly exposes resolve_stamped_version and maps refs/tags/v1.2.3 to 1.2.3. No code change is needed; duplicating the payload helper in the thin bootstrap would create a second implementation and future drift.