refactor(onboard): extract flow handoff context

[cv]

Summary

Stack 3 of 5; depends on #7716.

Move initial-to-core and core-to-final context validation into flow-handoff.ts. The entrypoint retains dependency wiring instead of constructing handoff context.

Related Issue

Refs #7706

Changes

• Validate preflight GPU output before core execution.
• Preserve sandbox-name precedence and reserved-name reporting.
• Validate sandbox identity and inference output before final execution.
• Document the extracted handoff owner.

Type of Change

• Code change with doc updates

Quality Gates

• Tests added or updated for changed behavior
• Documentation not applicable — No supported command, configuration, default, workflow, or user-visible behavior changes. The internal ownership README was updated.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed — Independent nine-category review passed for commit SHA 74d024849fb23fca25c339f567220a937298d6c0 against base SHA 7c83651249b7a53a847a317736aa59e46ded8101: refactor(onboard): extract flow handoff context #7717 (comment)

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Independent Codex Desktop documentation writer review passed for commit SHA 74d024849fb23fca25c339f567220a937298d6c0 against base SHA 7c83651249b7a53a847a317736aa59e46ded8101. Reviewed all five changed files against WRITING.md, the NemoClaw Controlled Word List, the shared documentation-writing contract, and the documentation contributor guidance. src/lib/onboard/machine/README.md accurately states that flow-handoff.ts validates required data and constructs context at the initial-to-core and core-to-final boundaries. The entrypoint continues to supply process-bound dependencies and reserved-name output. Changed errors and behavior-oriented test titles accurately describe preflight GPU validation, sandbox-name precedence, required final context, and preservation of runner results and sessions. Issue refactor(onboard): reduce entrypoint to setup and wiring #7706 defines this internal refactor scope and prohibits a new public API or speculative extension point. The change does not modify a supported command, output, configuration, workflow, default, or other user-visible behavior, so no user-facing docs/ source change is required.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Result: Not applicable; this PR does not change scripts/prepare-dgx-station-host.sh.

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 — CI / Pull Request test jobs passed for commit SHA 74d024849fb23fca25c339f567220a937298d6c0.
• Applicable broad gate passed — Required check E2E / PR Gate passed for commit SHA 74d024849fb23fca25c339f567220a937298d6c0.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (documentation changes only) — Not applicable; no published documentation source changed.
• Doc pages follow the style guide (doc changes only)

---

Signed-off-by: Carlos Villela cvillela@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.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 74d0248 in the codex/onboard-fsm-th... branch remains at 96%, unchanged from commit 8c542b2 in the codex/onboard-fsm-ru... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 74d0248 in the codex/onboard-fsm-th... branch remains at 81%, unchanged from commit 8c542b2 in the codex/onboard-fsm-ru... branch.

Show a code coverage summary of the most impacted files.

File	codex/onboard-fsm-ru... 8c542b2	codex/onboard-fsm-th... 74d0248	+/-
src/lib/state/o...d-step-state.ts	100%	67%	-33%
src/lib/onboard...esult-events.ts	100%	67%	-33%
src/lib/state/o...oard-session.ts	91%	89%	-2%
src/lib/onboard...hine/runtime.ts	95%	93%	-2%
src/lib/inferen...ompatibility.ts	95%	94%	-1%
src/lib/onboard.ts	31%	31%	0%
src/lib/onboard...ime-boundary.ts	84%	86%	+2%
src/lib/onboard...shboard-port.ts	90%	96%	+6%
src/lib/onboard...flow-handoff.ts	0%	100%	+100%
src/lib/onboard...-slice-error.ts	0%	100%	+100%

---

_{Updated August 03, 2026 16:18 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 terminology decisions differ; normalized E2E selections differ; severity counts match.

4 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• flow handoff at src/lib/onboard/machine/README.md:22: primary classified it as define; the second opinion classified it as justified.
• handoff at src/lib/onboard/machine/README.md:22: selected only by the second-opinion lane as justified.
• core-to-final at src/lib/onboard/machine/README.md:22: selected only by the second-opinion lane as justified.
• initial-to-core at src/lib/onboard/machine/README.md:22: selected only by the second-opinion lane as justified.

2 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• full-e2e: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• double-onboard: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

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.

• define — flow handoff at src/lib/onboard/machine/README.md:22: Retain the term with the boundary explanation in the README. It names the new module responsibility without conflicting with an established repository term.
• justified — process-bound dependencies at src/lib/onboard/machine/README.md:22: Retain the modifier because it distinguishes entrypoint-owned process operations from handoff-owned context construction.

E2E guidance

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

Recommended E2E: cloud-onboard, 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.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b7595fb9-81a9-433c-bd5e-6ac663b215e5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/onboard-fsm-thin-entrypoint

---

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

[cjagwani]

Draft-stack babysitting status for exact head 01aa8c3 (plain comment; no Changes Requested review): the direct #7716 base matches this PRs recorded base, but #7716 itself is stale behind current #7715, so this transitive stack cannot provide current exact-head evidence. Draft CI is absent, sensitive-path review remains pending, and maintainer edits are disabled. I will review and gate the refreshed quiet stack in dependency order.

[cv]

Sensitive-path security review: PASS

Reviewed PR #7717 at commit SHA 4721b38 against base SHA dfd7278.

Product scope: PASS. Accepted issue #7706 defines this internal onboarding handoff refactor. The change creates no supported surface.

All nine security-review categories pass. No security findings remain.

The delta from the previous review consists only of repository-required Biome formatting in src/lib/onboard/machine/flow-handoff.test.ts. It changes no fixture values, assertions, test titles, control flow, or production behavior. GitHub reports the commit as verified. No unresolved review thread remains.

This receipt applies only to the reviewed commit SHA and base SHA. It does not waive failing or pending repository checks.

[cv]

Sensitive-path security review: PASS

Reviewed PR #7717 at commit SHA 74d024849fb23fca25c339f567220a937298d6c0 against base SHA 7c83651249b7a53a847a317736aa59e46ded8101.

Product scope: PASS. Issue #7706 establishes this internal onboarding handoff refactor. The five-file patch adds no supported integration, configuration, workflow, image, public API, or other product surface.

No findings. All nine review categories pass:

1. Secrets and credentials — PASS. The handoff helpers do not persist credential values or process-bound callbacks.
2. Input validation and data sanitization — PASS. Preflight GPU output, sandbox-name precedence, reserved names, sandbox identity, model, and provider remain validated.
3. Authentication and authorization — PASS. No identity, authentication, authorization, permission, or token behavior changes.
4. Dependencies and third-party libraries — PASS. No dependency or supply-chain changes.
5. Error handling and logging — PASS. Existing error and reserved-name output paths remain unchanged, and failed and paused runner sessions remain preserved.
6. Cryptography and data protection — PASS. No cryptographic or protected-storage behavior changes.
7. Configuration and security headers — PASS. No network policy, sandbox capability, container, port, or production configuration changes.
8. Security testing — PASS. Tests cover missing required data, sandbox-name precedence, validator invocation, incomplete final identity, and resumed, failed, and paused handoffs.
9. System security — PASS. prepareCoreOnboardFlowContext and prepareFinalOnboardFlowContext preserve the existing validation boundaries and carry the runner-returned session across both boundaries.

The effective patch retains stable patch ID a8a30a3f3aae65f6b4d324ad559da4d64c62b134. The PR body contains the contributor DCO declaration, dco-check passed, GitHub reports valid signatures for all 23 PR commits, and no unresolved review thread remains.

At review time, checks for commit SHA 74d024849fb23fca25c339f567220a937298d6c0 had no failures. Build/typecheck, static checks, both CodeQL languages, reviewed npm audit, installer integration, and both advisor lanes passed. Seven CLI test shards and both E2E checks remained in progress.

Required reviews, pending checks, documentation writer review, and merge state remain separate repository gates.

[apurvvkumaria]

Reviewed current head 74d0248. The extracted prepare and final handoffs preserve session handling, sandbox-name precedence, lifecycle guards, and final configuration checks. Focused tests pass 15 of 15 and the GitHub checks are green or intentionally skipped. I found no blocking correctness, security, compatibility, or regression issue.