refactor(onboard): move policy setup into policy-selection

[cv]

Summary

Moves onboarding policy setup from src/lib/onboard.ts into src/lib/onboard/policy-selection.ts.
This keeps onboard.ts responsible for sequencing and reduces its fan-out budget from 219 to 212 without changing onboarding behavior.

Related Issue

Part of #7695

Changes

• Add createOnboardPolicyApplication to group the policy setup dependencies used by src/lib/onboard.ts.
• Run baseline policy selection, tier validation, preset selection, messaging policy setup, and policy application through policy-selection.ts.
• Preserve the existing exports and error propagation.
• Add a regression test that verifies policy setup runs under the sandbox mutation lock.
• Reduce the src/lib/onboard.ts fan-out budget from 219 to 212.

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 refactor moves internal policy setup. It does not change a user-visible API, CLI, configuration, workflow, default, output, or error.
• 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: An independent nine-category review found no findings for PR commit a2a4354e6e6622ddbd5ca6c5581a0cba4477e8e5 against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: No waiver is recorded.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Reviewed ci/source-architecture-budget.json, src/lib/onboard.ts, src/lib/onboard/policy-selection.ts, and src/lib/onboard/policy-selection-application.test.ts for PR commit a2a4354e6e6622ddbd5ca6c5581a0cba4477e8e5 against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711. The current PR commit preserves the Personal policy tier added on main while moving existing policy application wiring and adding a regression test for the sandbox mutation lock. It does not change a user-visible API, CLI, configuration, workflow, default, output, or error. The review covered terminology, structure, voice, test-title wording, and code-sample presentation; no documentation or code sample changed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh does not change.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub — all 13 commits appear as Verified.
• 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 — normal hooks passed for the contributor-authored commits. GitHub automation created the current conflict-resolution merge commit; its commit-lint, build-and-typecheck, and static checks passed.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — GitHub Actions cli-test-shards 1–8 and cli-tests passed for PR commit a2a4354e6e6622ddbd5ca6c5581a0cba4477e8e5. No standalone local test suite ran after the merge.
• Applicable broad gate passed — source checks passed, but E2E / PR Gate has not produced a result for the current PR commit.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed — the independent security review passed all nine categories.
• npm run docs builds without warnings (doc changes only) — not applicable; no documentation changes.
• Doc pages follow the style guide (doc changes only) — not applicable; no documentation changes.
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new page.

Sensitive-Path Security Review

Independent review found no security finding for PR commit a2a4354e6e6622ddbd5ca6c5581a0cba4477e8e5 against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711.

1. Secrets and credentials: PASS. No credential values or credential handling changed.
2. Input validation and data sanitization: PASS. No parser or user-controlled input boundary changed.
3. Authentication and authorization: PASS. No identity or access decision changed.
4. Dependencies and third-party libraries: PASS. No dependency changes.
5. Error handling and logging: PASS. Policy errors retain their existing propagation and output paths.
6. Cryptography and data protection: PASS. No cryptographic or protected-data handling changed.
7. Configuration and security headers: PASS. No runtime policy, container, endpoint, or security-header configuration changed.
8. Security testing: PASS. The regression test verifies that the complete policy operation executes while the sandbox mutation lock is held.
9. System security: PASS. The asynchronous policy operation remains inside the lock, including synchronization and policy-context seeding.

Independent maintainer approval remains a separate merge requirement.

GitHub Actions

GitHub Actions is authoritative for PR commit a2a4354e6e6622ddbd5ca6c5581a0cba4477e8e5 against base SHA 2f297843b8fddad80b046eaf34f2987bdd922711.
Source CI passed. E2E / PR Gate has not produced a result for the current PR commit.
No check waiver is recorded.

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Improvements
  • Onboarding policy selection, preset filtering, resume handling, tier validation, and setup flows now follow a more consistent process.
  • Improved handling for policy suggestions, messaging settings, environment checks, and sandbox changes during onboarding.
• Tests
  • Added coverage for policy setup, including synchronization, context setup, and safe lock release.
• Chores
  • Updated architecture budget limits to reflect the streamlined onboarding flow.

[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

📝 Walkthrough

Walkthrough

Changes

Onboarding policy operations now use a centralized application factory. The onboarding flow removes duplicated policy helpers and direct imports. Tests verify mutation locking and setup sequencing. The architecture budget lowers the allowed fan-out from 219 to 212.

Changes

Onboarding policy application

Layer / File(s)	Summary
Policy application contract and factory src/lib/onboard/policy-selection.ts	Adds OnboardPolicyApplicationDeps and createOnboardPolicyApplication. The factory exposes centralized policy, preset, resume, baseline, validation, messaging, and setup operations.
Onboarding policy flow integration src/lib/onboard.ts	Removes local policy helpers and direct policy imports. Onboarding uses the centralized application for policy setup, baseline resolution, environment validation, resume selection, and preset filtering.
Policy application validation and architecture budget src/lib/onboard/policy-selection-application.test.ts, ci/source-architecture-budget.json	Adds coverage for mutation-locked policy setup, synchronization, context seeding, and lock release order. Reduces the onboarding fan-out limit from 219 to 212.

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

Possibly related PRs

• NVIDIA/NemoClaw#8263: Extracts onboarding orchestration into dedicated composition and factory modules.
• NVIDIA/NemoClaw#8264: Extracts onboarding flow and policy composition into dedicated modules.
• NVIDIA/NemoClaw#8431: Modifies onboarding policy-selection logic, including tier validation and preset filtering.

Suggested labels: refactor, area: onboarding, area: architecture, v0.0.103

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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 and concisely describes moving onboarding policy setup into the policy-selection module.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7695-policy-application

---

_{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 3aa52ce in the codex/7695-policy-ap... branch remains at 96%, unchanged from commit b5ac557 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 3aa52ce in the codex/7695-policy-ap... branch remains at 81%, unchanged from commit b5ac557 in the main branch.

Show a code coverage summary of the most impacted files.

File	main b5ac557	codex/7695-policy-ap... 3aa52ce	+/-
src/lib/onboard...flight-ports.ts	67%	33%	-34%
src/lib/platform.ts	89%	84%	-5%
src/lib/onboard.ts	31%	31%	0%
src/lib/messagi...flow-planner.ts	91%	91%	0%
src/lib/onboard...cy-selection.ts	97%	97%	0%
src/lib/core/immutable.ts	97%	97%	0%
src/lib/messagi...etup-applier.ts	68%	68%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/onboard...licy-presets.ts	94%	100%	+6%
src/lib/onboard...icy-tier-env.ts	45%	82%	+37%

---

_{Updated August 07, 2026 09:21 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

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

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

1 semantic terminology decision

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

• established — policy application at src/lib/onboard/policy-selection-application.test.ts:29: Keep the established term.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: managed-image-multiarch-startup, managed-image-protected-runtime, onboard-repair, onboard-resume, cloud-onboard

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Add production policy-application wiring coverage

• Location: src/lib/onboard.ts:3741
• Category: tests
• Problem: The new test constructs createOnboardPolicyApplication with direct mocks, but no test verifies the production onboarding factory supplies the registry tier callbacks, readiness checks, and sandbox mutation lock to the extracted application.
• Impact: A missing or incorrectly mapped production callback can change resume-tier selection or bypass readiness and lock guarantees while the new unit test still passes.
• Recommendation: Add a focused onboarding composition test that invokes the production factory wiring and asserts a resume policy application reads the registry tier, checks readiness before and after synchronization, and runs synchronization under withSandboxMutationLock.
• Verification: Inspect the createOnboardPolicyApplication call in src/lib/onboard.ts and compare its exercised callbacks with policy-selection-application.test.ts.
• Test coverage: A source test for the onboarding composition path that exercises a resume policy application through createOnboardPolicyApplication and asserts registry-tier, readiness, synchronization, and mutation-lock callback wiring.
• Evidence: src/lib/onboard/policy-selection-application.test.ts:44-64 supplies direct mocks for all factory dependencies. src/lib/onboard.ts:3741-3762 constructs the production createOnboardPolicyApplication dependency object. src/lib/onboard/policy-selection-recorded-tier.test.ts:68-109 covers callee tier/readiness behavior but not the production factory wiring.

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 `@src/lib/onboard/policy-selection-application.test.ts`:
- Around line 12-14: Update the withSandboxMutationLock mock in the test to
accept the production callback signature and execute the supplied callback
instead of returning lockResult directly. Remove the unknown cast around the
mock, then assert the callback’s setup result or another observable policy
effect while retaining the sandbox-name assertion as a secondary check.

🪄 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: 4228f56e-2601-4f48-bc64-930d7f691c14

📥 Commits

Reviewing files that changed from the base of the PR and between b6c3b7c and 55eb691.

📒 Files selected for processing (1)

• src/lib/onboard/policy-selection-application.test.ts

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

[cv]

Decision: request changes. GitHub does not permit this account to submit CHANGES_REQUESTED on its own PR, so this comment review records the same decision without claiming approval. Refresh the branch onto current main; fix the failing exact all-agent activation check and obtain passing commit-lint and docs-review-receipt results; then obtain a current independent security and automated review for the refreshed head. The available advisor and security evidence cover older commits.