fix(onboard): reserve skipped inference resume route

[sandl99]

Summary

Resume onboarding can skip provider setup after the provider/model are already recorded but before sandbox setup is complete. This change reserves or repairs the sandbox inference route during that resume path so the later sandbox profile step does not fail with sandbox route reservation '<name>' disappeared while onboarding was in progress.

Related Issue

Fixes #6562

Changes

• Reserve the sandbox inference route when nemoclaw onboard --resume skips already-ready inference while sandbox setup is still incomplete.
• Apply the repair to both routed and direct-compatible provider branches while preserving complete-sandbox resume behavior.
• Add regression coverage for the reported cancellation-after-sandbox-name resume path and the already-ready inference resume path.

What each PR/fix does:

• fix(onboard): preserve pending route reservation across resume #6572: protects an existing pendingRouteReservation from being deleted by stale-entry cleanup when no live sandbox exists. It handles "reservation existed, cleanup would remove it."
• fix(onboard): keep pending route reservation through not-ready recreate #6626: protects an existing session-owned pending reservation during a NotReady sandbox recreate. It handles "reservation existed, recreate would remove it."
• This fix: creates/repairs the reservation when resume skips inference before sandbox setup has a complete sandbox. It handles your repro: "reservation was missing because resume skipped the step that normally creates it."

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 public --resume contract is unchanged; this repairs internal route reservation state. A docs review found no documentation updates needed.
• 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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration 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
  • git push -u origin HEAD ran pre-push TypeScript checks and passed.
  • npm run check:diff passed in a temporary clean worktree after npm run build:cli generated the required dist/ artifacts. The main checkout has ignored local worktrees/ directories that otherwise make the source-shape scanner inspect unrelated files.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification:
  • npx vitest run --project cli src/lib/onboard/machine/handlers/provider-inference.test.ts — passed (35 tests)
  • npx vitest run --project cli src/lib/onboard/machine/handlers/provider-inference-recovery-gating.test.ts src/lib/onboard/machine/handlers/provider-inference-route-containment.test.ts src/lib/state/registry-route-reservation.test.ts src/lib/onboard/setup-inference-route-containment.test.ts src/lib/onboard/sandbox-lifecycle.test.ts — passed (38 tests)
  • npm run typecheck:cli — passed
  • npm run build:cli — passed
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved resume reliability during provider inference by correcting which sandbox route is reserved, even when inference is already ready or provider reselection is required.
  • Ensured no sandbox route is reserved when resuming after the sandbox step is already completed.
  • Updated routed-inference reservation behavior to match the expected host-alias endpoint details.
• Tests
  • Added coverage to validate the resumed provider inference reservation flow and updated related router reconciliation expectations.

[coderabbitai]

📝 Walkthrough

Walkthrough

Resume inference handling now derives the sandbox reservation name from resume state, conditionally reserves routes, and updates tests for skipped inference, redone provider selection, and routed-provider reservation parameters.

Changes

Resume inference reservation

Layer / File(s)	Summary
Derive and apply resume reservation names src/lib/onboard/machine/handlers/provider-inference.ts	Resume logic derives the reservation name from authoritative configuration and sandbox-step status, then uses it for routed and non-routed reservations and failure reporting.
Validate resumed route reservations src/lib/onboard/machine/handlers/provider-inference.test.ts	Tests verify prompted sandbox route reservations for skipped inference and redone provider selection, omission after sandbox completion, and routed-provider reservation inputs.

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

Possibly related PRs

• NVIDIA/NemoClaw#4601: Related routed-provider endpoint and resumed inference reservation behavior.
• NVIDIA/NemoClaw#5829: Related resume and fresh inference setup handling.

Suggested labels: bug-fix, area: onboarding, area: inference

Suggested reviewers: cv, ericksoa, prekshivyas, cjagwani, jyaunches

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The implementation and tests address #6562 by preserving or restoring route reservation across --resume when inference is already complete.
Out of Scope Changes check	✅ Passed	The changes stay focused on resume route-reservation logic and regression tests, with no unrelated scope visible.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is clearly related to the main fix: reserving the inference route during resume when inference was skipped.

✨ 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 fix/onboard-resume-reserve-skipped-inference

---

_{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 remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/onboard-resume-r... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 3de1de6	fix/onboard-resume-r... 0729488	+/-
src/lib/core/pr...mpt-activity.ts	92%	67%	-25%
src/lib/security/redact.ts	99%	95%	-4%
src/lib/onboard...er-inference.ts	94%	94%	0%
src/lib/securit...ntial-filter.ts	98%	99%	+1%
src/lib/state/gateway.ts	88%	90%	+2%
src/lib/runner.ts	72%	75%	+3%
src/lib/state/m...-acquisition.ts	77%	80%	+3%
src/lib/name-validation.ts	94%	100%	+6%
src/lib/actions...ge-preflight.ts	74%	89%	+15%

---

_{Updated July 13, 2026 12:24 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

E2E Advisor Recommendation

Required E2E: cloud-onboard, inference-routing, network-policy, onboard-repair, onboard-resume
Optional E2E: model-router-provider-routed-inference

Dispatch hint: cloud-onboard,inference-routing,network-policy,onboard-repair,onboard-resume,model-router-provider-routed-inference

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard: Required deterministic floor: validate the modified onboarding flow on a clean hosted environment with a usable assistant.
• inference-routing: Required deterministic floor: validate real host-to-sandbox inference routing, endpoint reachability, and inference.local behavior.
• network-policy: Required deterministic floor: validate that the intended inference route is allowed at the sandbox network boundary without unintended egress.
• onboard-repair: Required deterministic floor and onboarding-resume rule: validate persisted onboarding state repair and convergence after partial failure.
• onboard-resume: Required deterministic floor and onboarding-resume rule: validate interrupted onboarding resume behavior across live sandbox and gateway state.

Optional E2E

• model-router-provider-routed-inference: Adjacent confidence for the changed nvidia-router branch: it validates provider-routed onboarding, host router health, and sandbox inference.local completion.

New E2E recommendations

• onboarding-resume-state (high): Current live resume and repair coverage exercises resumability, but this regression specifically requires an interrupted provider-ready onboarding run to reserve the selected sandbox route before sandbox creation, including the nvidia-router path, and then prove inference.local succeeds after completion.
  • Suggested test: Extend an existing live onboarding-resume or repair target with a provider-ready, sandbox-incomplete resume scenario that verifies the gateway reservation and a successful sandbox inference.local request for both a compatible provider and nvidia-router.

Dispatch hint

• Workflow: .github/workflows/e2e.yaml
• jobs input: cloud-onboard,inference-routing,network-policy,onboard-repair,onboard-resume,model-router-provider-routed-inference

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Review the warnings below.
Findings: 0 required · 1 warning · 0 optional suggestions
Since last review: 0 prior items resolved · 0 still apply · 1 new item found

1 warning · 0 optional suggestions

Warnings

These merit maintainer attention but do not block by themselves.

PRA-1 Warning — Cover failed reservation on the new incomplete-sandbox resume path

• Location: src/lib/onboard/machine/handlers/provider-inference.test.ts:496
• Category: tests
• Problem: The new tests cover successful reservation for an incomplete sandbox and non-reservation after sandbox completion, but none makes `reserveSandboxInferenceRoute` return false in the newly broadened resume path. The handler has a distinct failure branch that must exit before recording inference as skipped or complete.
• Impact: A future ordering regression could advance the persisted onboarding session after the route reservation fails, recreating a resume state that claims inference completed without the required route dependency.
• Recommendation: Add a focused mocked handler test for a provider-selection-complete, sandbox-incomplete resume where `calls.reserveRoute` returns false; assert non-zero exit and that neither `recordStateSkipped("inference", ...)` nor `recordStepComplete("inference", ...)` is called.
• Verification: In `provider-inference.test.ts`, search for `reserveRoute` configured to return `false` or assertions that skipped/complete recording is absent after a reservation failure; no such test exists in the changed suite.
• Test coverage: A Vitest handler test with `isInferenceRouteReady` true and `reserveRoute` returning false for an incomplete sandbox session, asserting exit 1 and no inference skipped/completed session writes.
• Evidence: `provider-inference.ts:699-723` reserves on the new incomplete-sandbox path and exits when the result is false before the skip/completion writes. `provider-inference.test.ts:496-588` asserts success for incomplete sandbox, no reservation for completed sandbox, and success after selection replay, but has no reservation-failure case. The nearby test-file search found no `reserveRoute` false or failed-reservation test.

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[github-actions]

E2E Target Results — ✅ All requested tests passed

Run: 29260752181
Workflow ref: fix/onboard-resume-reserve-skipped-inference
Requested targets: (default — all supported)
Requested test IDs: model-router-provider-routed-inference
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped, 0 unknown

Test	Result
model-router-provider-routed-inference	✅ success

[github-actions]

E2E Target Results — ✅ All selected tests passed

Run: 29261685137
Workflow ref: fix/onboard-resume-reserve-skipped-inference
Requested targets: cloud-onboard,inference-routing,network-policy,onboard-repair,onboard-resume
Requested test IDs: (default — all default-enabled tests; explicit-only tests openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 5 passed, 0 failed, 0 cancelled, 0 skipped, 0 unknown

Test	Result
cloud-onboard	✅ success
inference-routing	✅ success
network-policy	✅ success
onboard-repair	✅ success
onboard-resume	✅ success

[prekshivyas]

Reviewed current head. Required CI, both PR advisors, CodeRabbit, and required/optional E2E coverage are clean. LGTM.