fix(onboard): preserve Spark managed-vLLM Express intent on onboard --resume (#7231)

[yanyunl1991]

Summary

On DGX Spark, a failed non-interactive managed-vLLM onboard now resumes the same Express flow instead of losing its provider, sandbox, and model intent and dropping into the interactive provider menu. An unpinned resume also isolates inherited model overrides so the Spark default is selected consistently.

Related Issue

Closes #7231

Changes

• Persist a strict, secret-free kind: "spark" resume intent for non-interactive NEMOCLAW_PROVIDER=install-vllm runs detected on DGX Spark.
• Restore the managed-vLLM provider, non-interactive mode, sandbox name, and an explicitly pinned Spark model during resume without enabling DGX Station receipt or policy state.
• Temporarily clear inherited NEMOCLAW_VLLM_MODEL and NEMOCLAW_MODEL values for an unpinned Spark resume, then restore the caller environment afterward.
• Clear Spark resume intent after provider selection completes; keep the existing DGX Station binding and receipt lifecycle unchanged.
• Cover capture, strict parsing, tamper rejection, platform gating, environment isolation/restoration, session normalization, and completion cleanup.

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: Existing resume and DGX Spark Express documentation already specifies the provider/model/sandbox retention and unpinned-model behavior; this fix makes the implementation conform to that contract.
• 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: Codex Desktop maintainer security review found no findings; strict persisted-state parsing, platform/model/name validation, Station isolation, and temporary environment restoration were reviewed.
• 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: no-docs-needed
• Evidence: Existing resume, DGX Spark, DGX Station, and managed-vLLM docs already describe the provider/model/sandbox contract and platform separation; this head only isolates inherited Station settings during Spark resume. Focused tests passed 128/128 and npm run check:diff passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 — npx vitest run --project cli src/lib/onboard/station-express-resume.test.ts src/lib/state/onboard-session.test.ts (2 files, 128 tests 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)

Additional validation:

• npm run test-size:check passed.
• npm run build:cli passed.
• npm --prefix nemoclaw run build passed.
• Live DGX Spark validation from the contributor reproduced a managed-vLLM failure at provider configuration, resumed with nemoclaw onboard --resume without --name, completed with provider=vllm-local, cleared the intent, and left the sandbox Ready.

---

Signed-off-by: Yanyun Liao yanyunl@nvidia.com

[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

Adds DGX Spark managed-vLLM Express resume intent capture, strict parsing, environment restoration, and session cleanup after provider selection.

Changes

Spark Express resume

Layer / File(s)	Summary
Spark intent contract and detection src/lib/onboard/station-express-resume.ts, src/lib/onboard/station-express-resume.test.ts	Adds Spark intent validation, Spark model resolution, provider-based intent detection, and capture/filtering tests.
Spark resume environment restoration src/lib/onboard/station-express-resume.ts, src/lib/onboard/station-express-resume.test.ts, src/lib/state/onboard-session.ts	Restores managed-vLLM provider settings and optionally pinned Spark model variables without Station markers, while validating incomplete Spark sessions.
Spark session lifecycle completion src/lib/state/onboard-session.ts, src/lib/state/onboard-session.test.ts	Skips Station provider binding and clears the Spark Express resume intent after provider selection completes, without generating Station receipt retirement state.

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

Sequence Diagram(s)

sequenceDiagram
  participant FailedExpress
  participant ResumeSession
  participant Environment
  participant ProviderSelection
  FailedExpress->>ResumeSession: persist Spark Express intent
  ResumeSession->>Environment: restore install-vllm and non-interactive settings
  ResumeSession->>ProviderSelection: resume provider selection
  ProviderSelection->>ResumeSession: complete provider selection
  ResumeSession->>ResumeSession: clear Spark Express intent

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% 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	The changes preserve Spark managed-vLLM resume state, avoid the interactive provider menu, and keep Station behavior intact as requested by #7231.
Out of Scope Changes check	✅ Passed	Only Spark resume onboarding logic and its tests were changed; no unrelated scope appears introduced.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: preserving Spark managed-vLLM Express intent during onboard resume.

✨ 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/7231-spark-express-resume

---

_{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 0fd3064 in the fix/7231-spark-expre... branch remains at 96%, unchanged from commit 70a8b6b in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 0fd3064 in the fix/7231-spark-expre... branch remains at 80%, unchanged from commit f764692 in the main branch.

Show a code coverage summary of the most impacted files.

File	main f764692	fix/7231-spark-expre... 0fd3064	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/state/m...-acquisition.ts	89%	84%	-5%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/state/m...ock-identity.ts	95%	95%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/state/o...oard-session.ts	90%	91%	+1%
src/lib/onboard...press-resume.ts	75%	78%	+3%
src/lib/inferen...er-lifecycle.ts	65%	71%	+6%
src/lib/inferen...lama/process.ts	50%	100%	+50%

---

_{Updated July 24, 2026 03:12 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 5 warnings · 2 suggestions

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

E2E guidance

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

Recommended E2E: onboard-repair, onboard-resume, cloud-onboard

2 optional E2E recommendations

• spark-install
• onboard-negative-paths

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/station-express-resume.ts (1)

19-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a discriminated union for Station vs. Spark intent shapes.

Making model optional on the shared interface loosens the type for the Station branch too, even though Station intents always carry model at runtime (see parseStationExpressResumeIntent's station branch and getStationExpressResumeIntent, which both require a resolved model). A discriminated union ({ kind?: undefined; model: string; ... } | { kind: "spark"; model?: string; ... }) would let the compiler continue to enforce "Station intents always have a model" instead of relying purely on runtime checks scattered across expectedEnvironment, parseStationExpressResumeIntent, and callers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/station-express-resume.ts` around lines 19 - 32, Replace the
shared StationExpressResumeIntent shape with a discriminated union: keep the
Station branch identified by an absent or undefined kind and require model plus
its Station-only fields, while defining the Spark branch with kind "spark",
optional model, and no Station-only receipt/served/checkpoint fields. Update
parseStationExpressResumeIntent and getStationExpressResumeIntent as needed to
construct and narrow the correct branch.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/station-express-resume.ts`:
- Around line 19-32: Replace the shared StationExpressResumeIntent shape with a
discriminated union: keep the Station branch identified by an absent or
undefined kind and require model plus its Station-only fields, while defining
the Spark branch with kind "spark", optional model, and no Station-only
receipt/served/checkpoint fields. Update parseStationExpressResumeIntent and
getStationExpressResumeIntent as needed to construct and narrow the correct
branch.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: efb367cc-0f01-4c53-8f11-d79dbf45a54a

📥 Commits

Reviewing files that changed from the base of the PR and between 3c4ea5a and 6a37eee.

📒 Files selected for processing (4)

• src/lib/onboard/station-express-resume.test.ts
• src/lib/onboard/station-express-resume.ts
• src/lib/state/onboard-session.test.ts
• src/lib/state/onboard-session.ts

[wscurran]

✨
Related open issues:

• #7231 [DGX Spark][Onboard] onboard --resume after an Express (managed vLLM) failure drops into the interactive provider menu, losing the non-interactive Express intent
• #7048 Station Express context is lost after managed vLLM onboarding failure

---

Related open PRs:

• #7059 fix(onboard): preserve Station Express choices on resume

---

Related open issues:

• #7231 [DGX Spark][Onboard] onboard --resume after an Express (managed vLLM) failure drops into the interactive provider menu, losing the non-interactive Express intent
• #7048 Station Express context is lost after managed vLLM onboarding failure

[prekshivyas]

All required checks are green. The unpinned Spark resume model-environment blocker is fixed with regression coverage, both selected live E2E targets passed, and no unresolved actionable automated-review or security findings remain.

[prekshivyas]

Re-reviewed exact head e8051ec. Spark resume now clears inherited Station/policy variables for the child run and restores the caller environment; the regression test exercises both boundaries. Focused tests (128/128), build/typecheck, security review, receipt, and check:diff pass. Independent maintainer review remains requested because I pushed the fix.