refactor(onboard): let the runner enter preflight

[cv]

Summary

This cumulative stack change makes the strict FSM runner the transition authority at exact init, preflight, and provider_selection entries. It removes the entrypoint-owned init -> preflight transition, separates provider/inference and sandbox phase construction by effect boundary, and preserves compatibility replay for saved sessions already downstream of the applicable exact entry. Commands, output, configuration, persisted contracts, and supported onboarding behavior are unchanged.

Stack layers 4–6 of 6. Base: codex/onboard-fsm-final-recovery.

Related Issue

Refs #6224

Changes

• Remove recordInitialPreflightTransition and its pre-slice call from runOnboard.
• Let the synthetic init phase and strict runner own init -> preflight for fresh and resumed sessions.
• Split the combined core-phase factory into provider/inference and sandbox factories with phase-specific dependencies.
• Share endpoint-provenance inputs explicitly across the two core phases.
• Remove provider_selection from the resume compatibility state set.
• Apply provider-selection, inference, sandbox, and branch transitions through the strict runner at exact entry.
• Preserve compatibility repair for downstream saved sessions and explicit invalidation of stale transition results.
• Update the lifecycle ownership map and strengthen phase, runtime-boundary, exit-handler, and live-slice tests.

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 internal lifecycle ownership map is updated; commands, output, configuration, persisted contracts, and supported onboarding behavior are unchanged.
• 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: Independent Codex review of the exact six-commit stack found no actionable findings and verified strict entry, compatibility bounds, state durability, recovery, rollback, and fail-closed behavior.
• 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: src/lib/onboard/lifecycle-contracts.md now assigns init to the synthetic phase applied by the strict initial-flow runner. The cumulative implementation also separates provider/inference and sandbox construction and gives the strict runner exact provider_selection entry. Downstream resume compatibility and user-facing onboarding contracts remain unchanged.
• Agent: Codex Desktop documentation-writer subagent

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 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 — exact stack-head FSM selection: PASS (9 files, 112 tests); focused CLI Vitest: PASS (18 tests); focused integration Vitest: PASS (12 tests); CLI type-check: PASS.
• Applicable broad gate passed — exact-head GitHub CLI, platform, security, and selected live E2E gates passed; cloud-onboard, onboard-repair, and onboard-resume all succeeded.
• 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

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

📝 Walkthrough

Walkthrough

Onboarding core phases now use separate provider-inference and sandbox builders with keyed execution. Strict initial-flow handling owns init and preflight, while runtime-boundary recording of the initial preflight transition is removed and resume tests are updated.

Changes

Onboarding flow refactor

Layer / File(s)	Summary
Core phase contracts and factories src/lib/onboard/machine/core-flow-phases.ts	Phase-specific options, endpoint provenance, named phase containers, separate factories, and updated core-slice compatibility handling are introduced.
Core phase wiring and runner validation src/lib/onboard.ts, src/lib/onboard/machine/core-flow-phases.test.ts	Onboarding constructs provider and sandbox phases separately, passes keyed phases to the runner, and updates provenance and runner assertions.
Strict initial-flow ownership and resume behavior src/lib/onboard/machine/initial-flow-phases.ts, src/lib/onboard/machine/initial-flow-phases.test.ts, test/onboard-fsm-live-slices.test.ts	The strict runner owns init and preflight; resume compatibility begins at gateway, with updated state and live-slice expectations.
Runtime-boundary transition removal src/lib/onboard/runtime-boundary.ts, src/lib/onboard/runtime-boundary.test.ts, src/lib/onboard/lifecycle-contracts.md, test/onboard-exit-handler.test.ts	Initial preflight transition recording is removed and related contracts and fixtures are updated.

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

Sequence Diagram(s)

sequenceDiagram
  participant runInitialOnboardFlowSlice
  participant flowSlices
  participant runCoreOnboardFlowSlice
  participant providerInference
  participant sandbox
  runInitialOnboardFlowSlice->>flowSlices: execute init or preflight entry state
  flowSlices->>runCoreOnboardFlowSlice: continue with keyed core phases
  runCoreOnboardFlowSlice->>providerInference: run provider inference
  providerInference-->>runCoreOnboardFlowSlice: phase result
  runCoreOnboardFlowSlice->>sandbox: run sandbox
  sandbox-->>runCoreOnboardFlowSlice: phase result

Loading

Suggested reviewers: jyaunches, ericksoa, laitingsheng

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: shifting the preflight entry transition to the runner.

✨ 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/onboard-fsm-initial-entry

---

_{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 d91b20e in the codex/onboard-fsm-in... branch remains at 96%, unchanged from commit 2540869 in the codex/onboard-fsm-fi... branch.

TypeScript / code-coverage/cli

The overall coverage in commit d91b20e in the codex/onboard-fsm-in... branch is 80%. The coverage in commit 6c43fe2 in the codex/onboard-fsm-fi... branch is 81%.

Show a code coverage summary of the most impacted files.

File	codex/onboard-fsm-fi... 6c43fe2	codex/onboard-fsm-in... d91b20e	+/-
src/lib/actions...-add-restart.ts	19%	10%	-9%
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/actions...lution-probe.ts	95%	88%	-7%
src/lib/policy/...ne-exclusion.ts	97%	91%	-6%
src/lib/actions...x/mcp-bridge.ts	41%	35%	-6%
src/lib/onboard...-flow-phases.ts	100%	96%	-4%
src/lib/actions...e-validation.ts	84%	81%	-3%
src/lib/actions...dbox/destroy.ts	95%	93%	-2%
src/lib/onboard...eway-service.ts	82%	81%	-1%
src/lib/onboard.ts	31%	31%	0%

---

_{Updated July 28, 2026 02:39 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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, 1 more suggestion.

Nemotron output stays in workflow artifacts and does not change the assessment above.

Since last review: 0 prior items resolved · 0 still apply · 0 new items found

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.

[cv]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.