fix(installer): warn with skipped-setup detail on an unrecognized Jetson release

[laitingsheng]

Summary

On a Jetson whose L4T release the installer does not recognize, scripts/setup-jetson.sh printed one line and continued, so the user had no signal that host setup was skipped. It now names the skipped host configuration, states that sandbox pods lose ClusterIP routing to CoreDNS without br_netfilter, lists the recognized L4T releases, and says that installation continues in an untested configuration. Release lines the script cannot parse take the same path and carry the same detail.

Related Issue

Fixes #7612

Changes

• scripts/setup-jetson.sh: add warnings that name the skipped work, its consequence, the recognized releases, and that installation continues untested.
• scripts/setup-jetson.sh: keep every warning on stderr so the parsed version written to stdout is unchanged.
• scripts/setup-jetson.sh: bind production detection to the canonical root-owned /etc/nv_tegra_release path.
• test/setup-jetson.test.ts: use a child-process PATH stub for head instead of a production path override, and prove that an inherited NEMOCLAW_TEST_NV_TEGRA_RELEASE_PATH cannot redirect release detection.
• test/helpers/vitest-watch-triggers.ts and test/vitest-watch-triggers.test.ts: register scripts/setup-jetson.sh as an opaque input so watch mode and npm run test:changed select its behavior tests.

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: docs/reference/troubleshooting.mdx already documents the recognized L4T releases, the host setup applied for each, and the skipped-setup continuation path.
• 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 exact-head security review PASS across all nine categories with no findings; diff fingerprint f0825aa085c1a1e05c871b4d1155e121cbf153f551561eb68e1a3c0e3137105d.
• 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. docs/reference/troubleshooting.mdx already documents the recognized L4T releases, the host setup applied for each, the ClusterIP/CoreDNS consequence, and continuation when release metadata is not recognized. An incomplete REVISION now follows that same documented fail-safe path.
• 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 or justification: npx vitest run --project integration test/setup-jetson.test.ts test/vitest-watch-triggers.test.ts test/platform-vitest-main-workflow.test.ts (3 files, 19 tests passed); bash -n scripts/setup-jetson.sh 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

[coderabbitai]

📝 Walkthrough

Walkthrough

Jetson setup now emits detailed stderr warnings when host setup is skipped for unparsable or unrecognized releases. Tests cover these paths, recognized releases, non-Jetson silence, and Vitest watch-trigger integration.

Changes

Jetson host setup

Layer / File(s)	Summary
Release detection and warning behavior scripts/setup-jetson.sh	Adds stderr warning helpers and routes unparsable and unrecognized L4T releases through expanded skipped-host-setup warnings.
Behavior validation and watch integration test/setup-jetson.test.ts, test/helpers/vitest-watch-triggers.ts, test/vitest-watch-triggers.test.ts	Adds an isolated setup-script harness and tests for release variants, while mapping scripts/setup-jetson.sh changes to the setup test suite.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds actionable warnings, supported release details, and continuation guidance for unsupported Jetson L4T versions as requested by #7612.
Out of Scope Changes check	✅ Passed	The test and watch-trigger updates directly support the Jetson warning change and do not introduce unrelated behavior.
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: adding a detailed warning for skipped Jetson host setup on unrecognized releases.

✨ 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/unsupported-jetpack-warning

---

_{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 87cd97e in the fix/unsupported-jetp... branch remains at 96%, unchanged from commit 2540869 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 87cd97e in the fix/unsupported-jetp... branch remains at 81%, unchanged from commit 6c43fe2 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 6c43fe2	fix/unsupported-jetp... 87cd97e	+/-
src/lib/policy/...ne-exclusion.ts	97%	91%	-6%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/readiness/host.ts	0%	100%	+100%

---

_{Updated July 28, 2026 01:03 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 E2E selections differ; severity counts match.

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

Workflow run details

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

scripts/setup-jetson.sh (1)

72-78: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Treat a missing revision as a parse failure.

The code validates release but not revision. For a line such as # R36 (release) without a parseable REVISION, l4t_version becomes 36., which matches 36.* and incorrectly enables JetPack 6 host setup instead of emitting the skipped-setup warning. Validate both components before constructing l4t_version, and add a regression test in test/setup-jetson.test.ts.

Suggested fix

   release="$(printf '%s\n' "$release_line" | sed -n 's/^# R\([0-9][0-9]*\) (release).*/\1/p')"
   revision="$(printf '%s\n' "$release_line" | sed -n 's/^.*REVISION: \([0-9][0-9]*\)\..*$/\1/p')"
-  l4t_version="${release}.${revision}"

-  if [[ -z "$release" ]]; then
+  if [[ -z "$release" || -z "$revision" ]]; then
     warn "Jetson detected but the L4T release could not be parsed from /etc/nv_tegra_release."
     warn_host_setup_skipped
     return 0
   fi
+
+  l4t_version="${release}.${revision}"

🤖 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 `@scripts/setup-jetson.sh` around lines 72 - 78, Update the Jetson version
parsing flow around release and revision extraction to treat either missing
component as a parse failure before constructing l4t_version. Preserve the
existing warn_host_setup_skipped behavior for invalid metadata, and add a
regression case in the setup-jetson tests covering a release line without a
parseable REVISION.

🤖 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.

Outside diff comments:
In `@scripts/setup-jetson.sh`:
- Around line 72-78: Update the Jetson version parsing flow around release and
revision extraction to treat either missing component as a parse failure before
constructing l4t_version. Preserve the existing warn_host_setup_skipped behavior
for invalid metadata, and add a regression case in the setup-jetson tests
covering a release line without a parseable REVISION.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1a269c7c-c168-425c-87d8-03e407b465aa

📥 Commits

Reviewing files that changed from the base of the PR and between 4009d01 and d4919f7.

📒 Files selected for processing (2)

• scripts/setup-jetson.sh
• test/setup-jetson.test.ts

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

• test/setup-jetson.test.ts

[apurvvkumaria]

Exact-head maintainer review: required checks pass, Advisor recommends merge_as_is, CodeRabbit has no unresolved actionable findings, risky installer behavior has focused regression coverage, and DCO/GitHub verification are current. Approved at 87cd97e.