refactor(onboard): complete FSM ownership and lifecycle recovery
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Ownership
@cv owns this roadmap and all linked sub-issues.
Do not start, assign, or submit this work unless @cv transfers ownership in the applicable issue.
## Problem
Onboarding now uses strict FSM routing at several exact entry states. Compatibility paths still own recovery, machine mutation, and lifecycle decisions elsewhere.
These split authorities make resumed execution harder to review. They also permit session, registry, gateway, and sandbox state to diverge after an interrupted effect.
## Desired result
Complete the internal FSM migration before changing lifecycle behavior.
Then, use the FSM boundary to consolidate desired state and recovery contracts.
The work must keep these properties:
- Preserve CLI commands, output, configuration, and supported behavior unless a sub-issue states a tested change.
- Keep credentials and secret-bearing URLs out of checkpoints and machine events.
- Validate intent before an external or destructive effect.
- Revalidate a persisted receipt before the runner skips an effect.
- Use one owner for each transition and persisted decision.
- Keep each PR narrow and independently reviewable.
## Work streams
1. Make initial and core recovery explicit. Make checkpoint reads authoritative. Give strict entry ownership to the sandbox flow.
2. Make `OnboardRuntime` the sole machine-state authority.
3. Reduce `src/lib/onboard.ts` to setup, context construction, dependency wiring, and machine invocation.
4. Consolidate desired-state authorities for messaging, target selection, conflicts, and policy persistence.
5. Add durable receipts and compensation across lifecycle effect groups.
6. Design health-before-delete replacement and an atomic swap contract.
Streams 1 through 5 can use stacked PRs. Stream 6 requires a separate design decision before implementation.
## Sequence
Each stream starts after the previous stream establishes its contract.
Do not mix atomic replacement with the FSM or authority refactors.
## Validation
Each sub-issue must define:
- the authority that changes;
- the compatibility path that remains or is removed;
- the failure and resume behavior;
- the smallest stable test boundary;
- documentation impact;
- security and secret-handling impact.
## Non-goals
- A public NemoClaw plugin SDK.
- A new supported integration or solution recipe.
- New configuration or compatibility layers without a current consumer.
- Same-name atomic replacement before stream 6 has an accepted design.
## Completion
The roadmap is complete when all sub-issues are closed or have an explicit maintainer deferral.
Implementation in the first delivery series covers streams 1 through 5.
Contributor guide
Assessment
This issue has not been assessed yet.