refactor(onboard): centralize scoped sandbox creation

[cjagwani]

Summary

This refactor removes all three line-budget evasions attributable to #8863: its two formatter-suppressed sandbox-creation calls and its awaited dashboard-recovery addition to a block suppressed by #7788. The duplicated creation calls move into one typed composition helper in the existing dashboard-port owner, while the recovery branch is expanded normally.

It preserves dashboard-port reservation scope, compute-plan evaluation before scope creation, base-image context creation inside the scope, temporary-runtime selection, nullable arguments, forwarded sandbox arguments, Promise rejection for synchronous setup failures, accepted-target completion, awaited dashboard restoration, and return order. src/lib/onboard.ts is net two lines smaller.

Changes

• Add one dashboard-port-scoped factory for the standard and temporary managed-runtime sandbox creation entry points.
• Replace the duplicated positional calls in src/lib/onboard.ts and remove their two growth-guardrail formatter suppressions.
• Expand the accepted-recreate recovery branch that fix(onboard): reserve dashboard port during build #8863 extended under an inherited suppression, removing that third exemption.
• Preserve the original async entry-point contract when compute-plan or setup dependencies fail synchronously.
• Add focused contract tests for evaluation order, fresh scopes, per-call compute plans, nullable arguments, runtime-mode selection, argument forwarding, and Promise rejection from both entry points.

The current consumer is the standard and temporary managed-runtime creation paths in src/lib/onboard.ts.
A direct readable expansion would grow the line-budgeted monolith, while the existing dashboard-port.ts module already owns reservation scope creation and cleanup.
The new dashboard-port tests protect this composition contract, and the existing reservation-failure test protects cleanup.

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 reorganizes internal composition, restores the original Promise-rejection boundary, and expands an identical control-flow block. Commands, defaults, configuration, output, errors, and reservation behavior do not change.
• 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 completed the full nine-category review and exact-head follow-up reviews with PASS in every category and no findings. Full review: refactor(onboard): centralize scoped sandbox creation #8902 (comment). Final Promise-rejection delta: refactor(onboard): centralize scoped sandbox creation #8902 (comment).
• 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 docs paths changed. Existing quickstart, command-reference, and troubleshooting pages already describe the preserved reservation, conflict, and recovery behavior; the final follow-up restores an internal Promise-rejection boundary only.
• 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 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 — the final two exact entry-point success/rejection tests passed; npm run typecheck:cli, source architecture, source shape, test-size, normal commit hooks, and pre-push CLI typecheck passed. Earlier full-PR validation passed 31 dashboard-port tests and 21 onboarding dashboard/rollback integrations.
• 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 to this focused internal refactor.
• 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: Charan Jagwani cjagwani@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: e15d60c2-cf52-484b-b85c-d9cacb6e2775

📥 Commits

Reviewing files that changed from the base of the PR and between 5e7e03b and bd3746d.

📒 Files selected for processing (2)

• src/lib/onboard/dashboard-port.test.ts
• src/lib/onboard/dashboard-port.ts

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

• src/lib/onboard/dashboard-port.test.ts

---

📝 Walkthrough

Walkthrough

The change extracts dashboard-port reservation and sandbox setup into a shared factory. Onboarding uses the factory for standard and temporary managed-runtime sandbox creation. Tests verify contexts, compute plans, reservation scopes, flags, names, invocation counts, ordering, and error propagation.

Changes

Sandbox entry-point reservation

Layer / File(s)	Summary
Reservation-scoped entry-point factory src/lib/onboard/dashboard-port.ts, src/lib/onboard/dashboard-port.test.ts	The dashboard-port module adds a dependency contract and factory for standard and temporary managed-runtime sandbox entry points. The factory resolves compute plans, opens reservation scopes, creates base-image contexts, and forwards sandbox arguments. Tests cover both flows and synchronous setup failures.
Onboarding integration src/lib/onboard.ts	Onboarding replaces local sandbox wrappers with factory-generated entry points. It supplies base-image, sandbox creation, and compute-plan dependencies. Recreate-target completion and dashboard restoration remain unchanged.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant DashboardPortFactory
  participant ReservationScope
  participant SandboxCreator
  Onboarding->>DashboardPortFactory: create sandbox entry points
  DashboardPortFactory->>ReservationScope: open dashboard-port reservation
  DashboardPortFactory->>SandboxCreator: create sandbox with scope and runtime flag
  SandboxCreator-->>Onboarding: return sandbox

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8577: This PR also modifies dashboard-port reservation and sandbox creation scopes.
• NVIDIA/NemoClaw#8863: This PR refactors dashboard-port-scoped sandbox entry points introduced by that PR.

Suggested reviewers: cv, laitingsheng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the centralization of scoped sandbox creation, which is the main change in the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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/audit-8863-onboard-growth

---

_{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 91a19e1 in the codex/audit-8863-onb... branch remains at 96%, unchanged from commit 24eaba1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 91a19e1 in the codex/audit-8863-onb... branch remains at 82%, unchanged from commit 6160df1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 6160df1	codex/audit-8863-onb... 91a19e1	+/-
src/lib/cua/bounded-file.ts	94%	84%	-10%
src/lib/cua/run...ime-manifest.ts	91%	84%	-7%
src/lib/cua/contract.ts	87%	80%	-7%
src/lib/messagi.../ilink-login.ts	96%	89%	-7%
src/lib/trace.ts	94%	90%	-4%
src/lib/state/o...d-checkpoint.ts	90%	87%	-3%
src/lib/onboard.ts	32%	32%	0%
src/lib/onboard...press-resume.ts	78%	82%	+4%
src/lib/securit...ntial-filter.ts	89%	95%	+6%
src/lib/onboard...der/snapshot.ts	75%	83%	+8%

---

_{Updated August 13, 2026 07:20 UTC}

[cjagwani]

Verdict

PASS. The review found no security findings. The refactor preserves the existing dashboard-port reservation lifecycle and exact sandbox-creation arguments without widening a trust boundary or changing a security control.

Findings Table

The review found no findings.

Detailed Analysis

1. Secrets and Credentials: PASS. The changed code does not read, store, forward, log, or remove credentials.
2. Input Validation and Data Sanitization: PASS. The factory does not parse or transform input. It forwards the existing typed argument tuple unchanged.
3. Authentication and Authorization: PASS. The diff changes no identity, permission, provider, gateway, or sandbox authorization check.
4. Dependencies and Third-Party Libraries: PASS. The diff adds no dependency, artifact, registry, install hook, or lockfile change.
5. Error Handling and Logging: PASS. withDashboardPortReservationScope still owns finally cleanup. Both entry points call that owner directly, so failures still release the current reservation and propagate.
6. Cryptography and Data Protection: PASS. The diff changes no cryptographic or protected-data path.
7. Configuration and Security Headers: PASS. Dashboard bind address, port selection, defaults, forward timing, sandbox options, and policy configuration remain unchanged.
8. Security Testing: PASS. The focused test proves fresh scopes, per-call compute plans, both nullable arguments, runtime-mode selection, and argument forwarding. The existing failure test proves reservation release, and 21 onboarding integration tests cover dashboard and rollback behavior.
9. System Security: PASS. Each call still receives a fresh reservation scope. The standard path passes false, the temporary path passes true, and both preserve the two null arguments before forwarding the original tuple. The existing sandbox workflow still releases the reservation immediately before forwarding.

Files Reviewed

• src/lib/onboard.ts
• src/lib/onboard/dashboard-port.ts
• src/lib/onboard/dashboard-port.test.ts

Reviewed commit: d843add1b9aa727aeb92ee386bafd29e60eb794c.

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Partial review preserved 0 canonical finding(s) and 2 terminology decision(s) before the advisor stopped.

Model lanes

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

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

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

• established — recovery authority at src/lib/shields/index.ts:4739: Keep `recovery authority`; repository documentation and Shields code use the term with this meaning.
• define — nemoclaw2 contract at .github/workflows/managed-images.yaml:114: Name the enforced package artifact and revision requirement, for example: `libssh2 nemoclaw1 cannot satisfy the candidate requirement for libssh2 nemoclaw2.`

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: managed-image-protected-runtime

Manual-only E2E: cloud-inference, managed-image-multiarch-startup, security-posture, onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

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

[cjagwani]

Follow-up sensitive-path review for exact head 2e9f31e: PASS with no findings. The delta restores the original compute-plan/base-image-context evaluation order and adds an event-order assertion. Rechecked all nine categories: no input boundary, credential, network/SSRF, command execution, permission, sandbox-isolation, injection, dependency, or data-exposure behavior changes. The original full nine-category review remains applicable to the complete PR diff.

[cjagwani]

Sensitive-path security review (exact head 796ea2c): PASS with no findings. The complete diff was rechecked across all nine required categories. The new delta only expands an existing accepted-recreate branch: it preserves the same condition, optional transaction completion, awaited dashboard restoration, and return order while removing an inherited formatter suppression. It changes no input or trust boundary, credential or secret handling, network or SSRF behavior, command execution, privilege model, sandbox isolation, injection sink, dependency, persisted data, or logging. The original factory extraction still preserves fresh per-call reservation scopes, compute-plan-before-scope ordering, base-image context creation, fixed nullable arguments, and standard versus temporary runtime selection.

[cjagwani]

Exact-head sensitive-path review

Verdict: PASS for signed head bd3746d3aca0ed368ebd179a92d7fd174487e68e against first parent 472f966867a7335259cbc1bfbb406e3ffe3b123d. No security findings.

The final delta addresses PR Review Advisor finding PRA-1 by restoring the original rejected-Promise contract when resolveComputePlan() throws synchronously. The exact error is propagated as a rejection; setup ordering remains compute-plan first; and no reservation or sandbox side effect exists at that failure point. Successful execution, reservation cleanup, argument forwarding, and standard/temporary runtime selection are unchanged.

All nine categories passed: secrets/credentials, input validation, authentication/authorization, dependencies, error handling/logging, cryptography/data protection, configuration, security testing, and system security.

Verification:

• Good ED25519 Git signature.
• Both public entry points are covered by the synchronous-failure rejection test.
• Focused regression test passed.
• CLI type-check, diff hygiene, normal commit hooks, and pre-push checks passed.

The earlier full-PR nine-category review remains applicable to the complete refactor.

[prekshivyas]

Reviewed the current head, compute-plan factory semantics, required CI, and exact-head advisor/security feedback. Required checks are green; ordering, per-call scope, and rejection behavior are preserved. Auxiliary base-image/rerun-artifact failures remain for maintainer disposition.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.