refactor(onboard): extract core flow composition

[cv]

Summary

Extract core onboarding flow composition from src/lib/onboard.ts into the machine layer. Runtime behavior stays unchanged, while the architecture guardrails ratchet toward lower fan-out and fewer root-level onboarding files.

Related Issue

Refs #7695

Changes

• Add a core flow composition module that injects provider recovery and stale dashboard cleanup into the existing phase factory.
• Move the provider recovery shim next to its machine-layer consumer and re-export the existing core flow API through the composition module.
• Add a focused composition test and ratchet the onboarding fan-out budget from 225 to 223 and the root-file budget from 310 to 309.

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: This change only moves internal composition and ratchets architecture budgets. It does not change commands, configuration, output, workflows, defaults, errors, or supported behavior.
• 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: Pending before the draft is marked ready for review.
• 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: Internal onboarding composition refactor only; no public API, CLI behavior, configuration, output, workflow, default, supported behavior, agent variant, or documentation file differs from current main. Independent documentation writer review passed on f41ddb9.
• Agent: Pi CLI

DGX Station Hardware Evidence

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

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 — npx vitest run --project cli src/lib/onboard/checkpoint-record.test.ts src/lib/onboard/machine/core-flow-composition.test.ts (10 tests passed); npm run typecheck:cli passed; normal pre-commit, commit-msg, and pre-push hooks passed on f41ddb901.
• 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved onboarding flow composition and provider-resume recovery.
  • Fixed sandbox messaging refreshes to read the messaging plan only once.
  • Preserved stale dashboard cleanup during onboarding flows.
  • Improved reliability when onboarding resumes or combines provider and sandbox steps.

• Tests

  • Added coverage for onboarding phase composition, dependency wiring, recovery behavior, cleanup handling, and sandbox refreshes.

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

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: b9f7bb46-3870-4474-bf9c-d823acbb5c38

📥 Commits

Reviewing files that changed from the base of the PR and between db629a2 and f41ddb9.

📒 Files selected for processing (3)

• src/lib/onboard.ts
• src/lib/onboard/machine/core-flow-composition.test.ts
• src/lib/onboard/machine/resume-provider-shim.ts

💤 Files with no reviewable changes (2)

• src/lib/onboard/machine/resume-provider-shim.ts
• src/lib/onboard.ts

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

• src/lib/onboard/machine/core-flow-composition.test.ts

---

📝 Walkthrough

Walkthrough

The change centralizes provider-inference and sandbox phase construction in createCoreOnboardFlowPhases. The onboarding entry point uses the composed phases, while tests cover dependency injection, cleanup forwarding, resume-provider wiring, and messaging-plan reads.

Changes

Core onboarding flow

Layer / File(s)	Summary
Phase composition contract and factory src/lib/onboard/machine/core-flow-composition.ts, src/lib/onboard/machine/resume-provider-shim.ts, src/lib/onboard/machine/core-flow-composition.test.ts	Added createCoreOnboardFlowPhases and its input types. The factory injects resume-provider recovery and stale dashboard cleanup dependencies into the provider-inference and sandbox phases.
Onboarding flow integration and regression checks src/lib/onboard.ts, src/lib/onboard/machine/handlers/sandbox.test.ts, src/lib/onboard/machine/resume-provider-shim.test.ts, ci/source-architecture-budget.json	Updated onboarding to use the composed phases. Removed stale listener cleanup wiring. Added regression assertions and reduced architecture budgets.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OnboardFlow
  participant createCoreOnboardFlowPhases
  participant ProviderInferencePhase
  participant SandboxPhase
  OnboardFlow->>createCoreOnboardFlowPhases: compose core phases
  createCoreOnboardFlowPhases->>ProviderInferencePhase: inject provider and resume-provider dependencies
  createCoreOnboardFlowPhases->>SandboxPhase: inject sandbox and cleanup dependencies
  createCoreOnboardFlowPhases-->>OnboardFlow: return composed phases
  OnboardFlow->>ProviderInferencePhase: execute provider phase
  OnboardFlow->>SandboxPhase: execute sandbox phase

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8261: Both changes modify onboarding flow orchestration in src/lib/onboard.ts.

🚥 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 main change: extracting core onboarding flow composition.
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/7695-core-composition

---

_{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 f41ddb9 in the codex/7695-core-comp... branch remains at 96%, unchanged from commit 9b6b8df in the main branch.

---

_{Updated August 05, 2026 06:53 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): Failed

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

2 semantic terminology decisions

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

• established — provider recovery at src/lib/onboard/machine/core-flow-composition.test.ts:40: Keep `provider recovery`; repository code and documentation already use this term with the same meaning.
• justified — stale dashboard listener cleanup at src/lib/onboard/machine/core-flow-composition.test.ts:40: Keep `stale dashboard listener cleanup`; `stale` identifies the cleanup target and avoids conflating it with ordinary dashboard operations.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, onboard-repair, onboard-resume

1 optional E2E recommendation

• double-onboard

Workflow run details

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

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