fix(onboard): add Jetson render device group

[jyaunches]

Summary

Jetson GPU onboarding now carries the eligible host group ID for real DRI render devices into the recreated Docker container. This gives the non-root sandbox user the additional device-group access required for CUDA initialization on the reported IGX Orin setup while preserving the existing Tegra device allowlist.

Related Issue

Fixes #7610

Changes

• Discover only real /dev/dri/renderD* character devices and reject symlinks.
• Add a device owner GID only when its group permission grants read or write access that other users do not already have.
• Preserve the established 0440 root:video /dev/nvmap behavior from [Jetson Orin][CLI&UX] nemoclaw status shows "Sandbox GPU: enabled" but CUDA is unusable inside sandbox — misleading status #4231.
• Pass the resulting numeric GIDs through the existing Jetson --group-add recreation path.
• Document the selected Tegra nodes and bounded DRI render-device discovery.

The root-cause hypothesis is that the reporter already receives the video/Tegra groups but not the distinct render-device owner GID. NVIDIA's Jetson container guidance identifies both video and render group membership as required for non-root CUDA initialization. The implementation intentionally does not scan DRI card nodes, arbitrary Tegra subtrees, or symlink targets.

No matching Jetson/IGX runner is currently available, so physical IGX Orin validation remains pending. The sandbox CUDA proof remains fail-closed and will reject the recreation if this best-guess fix is insufficient.

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:
• 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 Desktop security review passed after narrowing discovery to real DRI render character devices, rejecting symlinks, checking effective group permission, and adding the 0440 /dev/nvmap regression case.
• 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: docs-updated
• Evidence: docs/reference/commands.mdx, docs/reference/troubleshooting.mdx, and the related CLI text, code comments, and test titles. The first review found inaccurate group-name and wildcard-scan wording; the final implementation review passed after the text was aligned with the bounded numeric-GID implementation. Follow-up reviews passed at e8dcfdb1e after the CI-driven spy cleanup and helper JSDoc update, at bf46f3e13 after aligning the live Jetson E2E assertion with the current stable group-propagation log prefix, and at 75a954256 after merging current main, retaining its 30-second E2E-support timeout, and confirming npm run docs with 0 Fern errors.
• 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: 333 Docker/sandbox GPU onboarding tests across 32 files pass; the focused Jetson tests pass 9/9; npm run typecheck:cli passes. The live-E2E assertion repair passed Biome and hook checks; the hardware-mutating Jetson E2E remains delegated to the repository's self-hosted gate. After merging current main, the E2E report boundary tests pass 33/33 with the upstream 30-second test-local timeout, and npm run docs passes with 0 Fern errors.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; the change is isolated to Jetson device-group discovery and propagation.
• 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)

npm run docs passes with 0 errors and the two existing Fern warnings.

---

Signed-off-by: J. Yaunches jmyaunch@gmail.com

[coderabbitai]

📝 Walkthrough

Walkthrough

Jetson GPU group detection now scans Tegra and DRI render devices, validates character-device access and GIDs, and propagates all eligible groups during sandbox recreation. Tests, end-to-end assertions, logging, and documentation cover the expanded device-node handling.

Changes

Jetson GPU group propagation

Layer / File(s)	Summary
Device discovery and access filtering src/lib/onboard/docker-gpu-jetson-groups.ts, src/lib/onboard/docker-gpu-jetson-groups.test.ts	Detection discovers Tegra and real DRI render devices, filters invalid entries and permissions, and returns safe eligible GIDs with expanded test coverage.
Sandbox recreation group propagation src/lib/onboard/docker-gpu-patch-jetson.test.ts, src/lib/onboard/docker-gpu-patch-recreate.ts, src/lib/onboard/docker-gpu-patch-types.ts	Jetson recreation passes all detected GIDs through --group-add, with updated tests, comments, imports, and logging.
GPU device-group documentation and E2E validation docs/reference/*.mdx, test/e2e/live/jetson-nvmap-gpu.test.ts, test/e2e/support/e2e-report-to-pr-workflow-boundary.test.ts	Documentation and test expectations describe the expanded device-node set, updated group-propagation message, and explicit integration-test timeout.

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

Sequence Diagram(s)

sequenceDiagram
  participant JetsonHost
  participant detectTegraDeviceGroupGids
  participant dockerRunDetached
  participant SandboxUser
  JetsonHost->>detectTegraDeviceGroupGids: enumerate GPU device paths
  detectTegraDeviceGroupGids->>JetsonHost: inspect GID and permission mode
  detectTegraDeviceGroupGids-->>dockerRunDetached: eligible group IDs
  dockerRunDetached->>SandboxUser: apply --group-add entries
  SandboxUser-->>dockerRunDetached: initialize CUDA as non-root

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7759: Both changes adjust explicit timeout settings for the E2E report workflow-boundary test.

Suggested labels: provider: nvidia, area: e2e, bug-fix, platform: container

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	A separate end-to-end test timeout change touches unrelated workflow-boundary coverage and appears outside the Jetson GPU passthrough scope.	Move the timeout tweak to a separate PR unless it is required for the Jetson GPU onboarding fix.
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 (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds render-device GID discovery and passes those groups into Jetson onboarding, matching the non-root CUDA proof fix for #7610.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding Jetson render-device group handling during onboarding.

✨ 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/7610-jetson-nonroot-cuda

---

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

[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 `@src/lib/onboard/docker-gpu-jetson-groups.test.ts`:
- Around line 58-60: Update the filesystem spy-backed assertions in the affected
test cases to use try/finally, calling mockRestore() for each locally created fs
spy in the finally block. Apply this to the lstatSync spy and the additional spy
setups covering the indicated assertion ranges, ensuring cleanup occurs even
when an assertion fails.

🪄 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: 211e7ddb-d7f8-449a-bbd7-9c39df2002d9

📥 Commits

Reviewing files that changed from the base of the PR and between 71a7856 and 00a3b9e.

📒 Files selected for processing (7)

• docs/reference/commands.mdx
• docs/reference/troubleshooting.mdx
• src/lib/onboard/docker-gpu-jetson-groups.test.ts
• src/lib/onboard/docker-gpu-jetson-groups.ts
• src/lib/onboard/docker-gpu-patch-jetson.test.ts
• src/lib/onboard/docker-gpu-patch-recreate.ts
• src/lib/onboard/docker-gpu-patch-types.ts

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7762.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 75a9542 in the codex/7610-jetson-no... branch remains at 96%, unchanged from commit c4c020c in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 75a9542 in the codex/7610-jetson-no... branch remains at 81%, unchanged from commit c4c020c in the main branch.

Show a code coverage summary of the most impacted files.

File	main c4c020c	codex/7610-jetson-no... 75a9542	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/onboard...etson-groups.ts	100%	96%	-4%
src/lib/sandbox...rce-identity.ts	88%	88%	0%

---

_{Updated July 28, 2026 22:01 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 · medium 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 match; 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-inference, cloud-onboard, security-posture, jetson-nvmap-gpu, onboard-repair, onboard-resume

Workflow run details

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