refactor(onboard): centralize messaging plan authority

[cv]

Summary

This PR centralizes messaging plan selection in one internal authority. The registry plan controls an existing sandbox. For a new or pending target, a staged plan takes precedence over a matching session plan. Provider-effect recovery receipts also own the exact credential bindings they created, so resume validates the complete live binding set before reuse and removes replaced keys without changing another effect group.

Related Issue

Refs #7701

Changes

• Add one messaging plan selection authority that accepts logical bindings but not credential values.
• Distinguish a registered sandbox from a pending route reservation.
• Apply registry authority to resume, reuse, and disabled-channel selection.
• Reject registry, staged, or session plans that target another sandbox before mutation.
• Clear plans recorded for a previous sandbox before resolving an explicit new target.
• Record exact web-search and messaging provider bindings by effect group.
• Reject malformed, missing, duplicate, or conflicting recovery receipts before replay.
• Preflight every required credential-provider binding before changing providers or session receipts, including recovery with only some credentials present.
• Revalidate persisted and live provider bindings before reuse, then replace only bindings owned by the replayed effect group.
• Document messaging selection, provider registration order, and the recovery binding contract.

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:
• 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 exact-head nine-category security review PASS at 424abbc0c7f3bbb707cdd208230191720df581ad against base 271c4d16f1e1f183371654fb6ab6a8a2a2914ca2; no findings. The complete 34-file effective patch remains stable at patch ID a0e2721475d310a3fe9b2f1fc7b019fee3a08184. Registry authority is resolved before staged or saved intent for known targets. Checkpoint receipts store only provider names, provider types, and credential keys. Malformed, duplicate, cross-owned, or mismatched bindings fail before mutation, and live bindings are revalidated under the gateway lock before sandbox reuse or creation. Refreshed-main model-selection, state-directory, and Windows installer changes do not alter these credential, authorization, checkpoint, or messaging boundaries. No injection, dependency, endpoint-authentication, cryptography, permission, logging, secret-handling, network, or resource-control regression was introduced. All nine security categories pass.
• 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: Reviewed every changed code, test, and documentation file at exact head 424abbc0c7f3bbb707cdd208230191720df581ad against base 271c4d16f1e1f183371654fb6ab6a8a2a2914ca2. The 34-file effective patch remains identical to prior reviewed head ca358bdaffaebcba390585f1129765a3096e9a8e, with stable patch ID a0e2721475d310a3fe9b2f1fc7b019fee3a08184. Verified docs/security/credential-storage.mdx and src/lib/onboard/lifecycle-contracts.md against the sandbox handler, messaging-plan authority, checkpoint recording and replay, credential-provider registration, and regression tests. Current-main Ollama/NIM changes do not affect these claims. The updated credential-order text renders only in the OpenClaw guide variant, as intended. Changed comments, diagnostics, and test titles follow the repository writing rules. git diff --check passed; npm run test:changed passed with no affected test files.
• Agent: Codex Desktop

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 — the effective patch at exact head 424abbc0c7f3bbb707cdd208230191720df581ad is identical to the prior validated patch, with stable patch ID a0e2721475d310a3fe9b2f1fc7b019fee3a08184. All 17 changed test files previously passed (299/299); current git diff --check passed; npm run test:changed passed with no affected test files; and the normal pre-push CLI TypeScript check passed.
• Applicable broad gate passed — not run locally; the complete effective patch previously passed npm run validate:pr, and GitHub CI is the current exact-head broad validation authority. No non-success check is accepted or waived.
• 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) — exact-head docs validation passed with 0 errors and 2 existing warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — Not applicable; no new page was added.

---

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

Summary by CodeRabbit

• New Features

  • Improved sandbox onboarding and resume flows for messaging and web-search provider setup.
  • Messaging plans are selected consistently across registered, staged, and resumed sandboxes.
  • Checkpoint replay detects provider changes and restores only verified configurations.
  • Provider configurations validate credentials, preserve unrelated settings, and safely replace outdated bindings.
  • Registration now follows a consistent messaging and web-search setup sequence.

• Security

  • Session metadata records provider details without storing raw credential values.

• Documentation

  • Updated lifecycle and credential-storage guidance.

[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 424abbc in the codex/onboard-fsm-de... branch remains at 96%, unchanged from commit fdd6828 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 424abbc in the codex/onboard-fsm-de... branch remains at 81%, unchanged from commit 962f1c3 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 962f1c3	codex/onboard-fsm-de... 424abbc	+/-
src/lib/onboard...aging-config.ts	100%	90%	-10%
src/lib/onboard...hannel-setup.ts	89%	83%	-6%
src/lib/messagi...annel-config.ts	96%	92%	-4%
src/lib/shields/index.ts	73%	70%	-3%
src/lib/onboard...point-record.ts	100%	97%	-3%
src/lib/onboard...ox-messaging.ts	91%	89%	-2%
src/lib/onboard...est-fixtures.ts	93%	96%	+3%
src/lib/tunnel/services.ts	76%	80%	+4%
src/lib/onboard...ing-selector.ts	78%	82%	+4%
src/lib/messagi...an-authority.ts	0%	100%	+100%

---

_{Updated August 05, 2026 06:03 UTC}

[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

The PR centralizes messaging-plan authority across registry, staged, and session state. It adds canonical provider-binding validation, effect-group fingerprints, checkpoint replay checks, and sandbox onboarding coverage for provider changes and credential consistency.

Changes

Onboarding authority and provider replay

Layer / File(s)	Summary
Authority contracts and plan selection src/lib/messaging/plan-authority.ts, src/lib/onboard/messaging-channel-setup.ts, src/lib/onboard/channel-state.ts, src/lib/onboard/messaging-config.ts, src/lib/onboard/messaging-reuse.ts, src/lib/onboard/machine/handlers/sandbox-messaging.ts	Messaging selection uses authoritative registry data, matching staged plans, and matching session plans. Pending reservations do not provide authoritative registry plans.
Provider-effect recording and replay src/lib/onboard/checkpoint-record.ts, src/lib/onboard/checkpoint-replay.ts, src/lib/onboard/checkpoint-revalidate.ts, src/lib/onboard/credential-provider-registration.ts	Checkpoint records validate canonical provider bindings, store provider-effect fingerprints, and replay only when live provider identity, type, and credential key match.
Sandbox provider integration src/lib/onboard/machine/handlers/sandbox.ts, src/lib/onboard/machine/handlers/sandbox-provider-effect-replay.test.ts, src/lib/onboard/machine/handlers/sandbox-checkpoint-crash-recovery.test.ts	Sandbox flows derive required bindings, validate checkpoint receipts, register web-search and messaging groups in order, replay provider effects, and reject cross-group or stale bindings before mutation.
Supporting contracts and validation src/lib/onboard/lifecycle-contracts.md, docs/security/credential-storage.mdx, ci/source-architecture-budget.json	The lifecycle contract and security documentation describe messaging-first checkpointing and secret-free binding receipts. The registry fan-in limit changes from 101 to 99.

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

Possibly related PRs

• NVIDIA/NemoClaw#5115: Modifies messaging-plan authority and registry/session state handling.
• NVIDIA/NemoClaw#5809: Modifies sandbox messaging-plan resolution during rebuild and resume.
• NVIDIA/NemoClaw#5913: Extends sandbox messaging orchestration and provider-effect replay.

Suggested labels: area: architecture

Suggested reviewers: apurvvkumaria, cjagwani, ericksoa

🚥 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 clearly and concisely describes the main change: centralizing messaging plan authority during onboarding.

✨ 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/onboard-fsm-desired-state-authority

---

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

[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): Failed after a partial review · low confidence · 0 blockers · 3 warnings · 1 suggestion

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

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

3 semantic terminology decisions

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

• justified — messaging plan authority at src/lib/messaging/plan-authority.test.ts:29: Keep this term for the shared source-selection rule.
• justified — provider-binding receipt at src/lib/onboard/lifecycle-contracts.md:62: Keep this term where the persisted receipt, rather than the binding metadata alone, is meant.
• define — pending target at src/lib/onboard/lifecycle-contracts.md:199: Define "pending target" on first use as a target with a pending route reservation.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, security-posture, channels-add-remove, channels-stop-start, 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]

Coordination note for future Pi onboarding

This is not a scope request for this PR. It records how #7923 / #7927 should consume the authority established here.

Pi v1 currently excludes messaging, but Pi onboarding still needs the same desired-state rules: one authoritative source, logical bindings without credential values, conflict rejection before effects, and exact receipt revalidation before resume skips.

Recommended order:

1. Land this PR and the relevant remaining refactor(onboard): complete FSM ownership and lifecycle recovery #7700 authority/receipt slices.
2. Let Decompose onboarding into phase composition #7695 place the established phase ownership in its final feature modules.
3. Add Pi through the generic FSM and lifecycle contracts in [Pi 3/7] Integrate Pi onboarding, lifecycle, state, and recovery #7927.

Pi work should not modify or bypass plan-authority.ts, checkpoint precedence, provider-effect receipt ownership, or OnboardRuntime. No Pi-specific code should be added to this PR.

outdated