fix(onboard): print portable recovery instead of --resume

[rluo8]

Summary

When --experimental-profile portable onboarding fails, recovery text previously suggested nemoclaw onboard --resume. Portable onboarding always starts fresh and rejects --resume, so that guidance was a dead end. After this change, those failure paths print nemoclaw onboard --experimental-profile portable instead.

Related Issue

Fixes #8873

Changes

• Add onboardRecoveryCommand() and make printOnboardResumeHint() profile-aware.
• Capture the portable flag when registering the incomplete-exit handler so the catch-all hint stays correct after env restore.
• Route sandbox-create and gateway-start recovery strings through the same helper.
• Soften portable-only secondary lines that still implied resume reuse.
• Add unit coverage for the portable recovery command, exit-handler capture, and Podman daemon recovery branch.

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:
• 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 | no-docs-needed | blocked
• Evidence:
• Agent:

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 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 — command/result or justification:
• 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: Rui Luo ruluo@nvidia.com

Summary by CodeRabbit

• New Features
  • Added profile-aware recovery guidance for portable experimental setups.
  • Portable onboarding now provides the appropriate fresh-start command and avoids misleading resume instructions.
  • Sandbox and onboarding failures display portable-specific recovery steps, including no-GPU options where applicable.
  • Gateway startup failures now provide rootless Podman guidance for portable setups while preserving standard Docker recovery instructions.
• Bug Fixes
  • Corrected recovery messaging to match the active onboarding profile and failure context.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 10a5524e-9cc3-42cc-b26b-f110c6510308

📥 Commits

Reviewing files that changed from the base of the PR and between ac6adac and d0d4e19.

📒 Files selected for processing (8)

• src/lib/build-context.test.ts
• src/lib/build-context.ts
• src/lib/onboard/exit-step-failure.test.ts
• src/lib/onboard/exit-step-failure.ts
• src/lib/onboard/gateway-start-failure-integration.test.ts
• src/lib/onboard/gateway-start-failure.ts
• src/lib/onboard/resume-hint.test.ts
• src/lib/onboard/resume-hint.ts

---

📝 Walkthrough

Walkthrough

Portable-profile recovery guidance now uses fresh portable onboarding commands instead of incompatible resume commands. Sandbox, gateway, and incomplete-exit failure paths pass profile-aware recovery state and include targeted tests.

Changes

Portable recovery guidance

Layer / File(s)	Summary
Profile-aware recovery command selection src/lib/onboard/resume-hint.ts, src/lib/onboard/resume-hint.test.ts	onboardRecoveryCommand selects portable fresh onboarding or standard resume recovery. Recovery hints and tests now reflect both profiles.
Sandbox and gateway recovery integration src/lib/build-context.ts, src/lib/build-context.test.ts, src/lib/onboard/gateway-start-failure.ts, src/lib/onboard/gateway-start-failure-integration.test.ts	Sandbox and gateway failures use profile-specific commands. Portable gateway failures report rootless Podman guidance and omit Docker-specific instructions.
Incomplete-exit recovery propagation src/lib/onboard/exit-step-failure.ts, src/lib/onboard/exit-step-failure.test.ts	The exit handler passes portable-profile state to recovery hints and verifies portable output without --resume guidance.

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

Sequence Diagram(s)

sequenceDiagram
  participant OnboardingFailure
  participant RecoveryHint
  participant RecoveryCommand
  participant CLI
  OnboardingFailure->>RecoveryHint: pass portable profile state
  RecoveryHint->>RecoveryCommand: select recovery command
  RecoveryCommand-->>RecoveryHint: return portable fresh-onboarding command
  RecoveryHint-->>CLI: print profile-specific recovery guidance

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8732: Both changes modify portable-profile onboarding recovery and gateway-failure messaging.

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

Suggested reviewers: cv, laitingsheng

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the onboarding fix: portable recovery guidance replaces the incompatible --resume command.
Linked Issues check	✅ Passed	The changes satisfy issue #8873 by preserving portable recovery guidance across sandbox, gateway, and incomplete-exit failure paths.
Out of Scope Changes check	✅ Passed	The changes remain within scope and add only profile-aware recovery logic plus focused tests for issue #8873.

✨ 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 fix/8873-portable-resume-hint

---

_{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 a100a27 in the fix/8873-portable-re... branch remains at 96%, unchanged from commit a44610a in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a100a27 in the fix/8873-portable-re... branch remains at 82%, unchanged from commit c49c0a2 in the main branch.

Show a code coverage summary of the most impacted files.

File	main c49c0a2	fix/8873-portable-re... a100a27	+/-
src/lib/policy/...ne-exclusion.ts	92%	87%	-5%
src/lib/policy/index.ts	68%	68%	0%
src/lib/adapters/http/probe.ts	91%	92%	+1%
src/lib/state/registry.ts	87%	89%	+2%
src/lib/adapter...tp/curl-args.ts	97%	99%	+2%
src/lib/securit...ate-endpoint.ts	94%	97%	+3%
src/lib/messagi.../token-paste.ts	92%	96%	+4%
src/lib/onboard...age/contract.ts	89%	93%	+4%
src/lib/messagi...annel-config.ts	92%	99%	+7%
src/lib/state/registry/lock.ts	39%	48%	+9%

---

_{Updated August 13, 2026 03:00 UTC}

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported 1 fewer blocker, the same number of warnings, the same number of suggestions.

4 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• rootless Podman at src/lib/onboard/gateway-start-failure.ts:53: selected only by the second-opinion lane as justified.
• experimental profile at src/lib/onboard/resume-hint.ts:9: selected only by the second-opinion lane as established.
• portable experimental profile at src/lib/onboard/resume-hint.ts:28: selected only by the second-opinion lane as established.
• portable onboarding at src/lib/onboard/resume-hint.ts:39: selected only by the second-opinion lane as established.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

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

• established — portable profile at src/lib/build-context.test.ts:260: Keep the established term for the profile-specific recovery behavior.
• established — rootless Podman API service at src/lib/onboard/gateway-start-failure.ts:53: Keep the established term for the portable runtime service.
• established — recovery command at src/lib/onboard/resume-hint.ts:27: Keep the established term and select its command through the shared helper.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Blockers

PRA-1 Blocker — Use the profile-aware recovery command after local inference failure

• Location: src/lib/onboard/local-inference-route.ts:69
• Category: correctness
• Problem: The non-interactive local inference-route failure message still directs every onboarding run to `nemoclaw onboard --resume`. This path runs while portable onboarding has set its profile environment. The command resolver rejects `--resume` with the portable profile, so this remaining failure path gives portable users an unusable recovery command.
• Impact: Portable non-interactive onboarding can exit after a failed local inference-route apply with recovery guidance that the CLI rejects.
• Fix: Replace the literal command with `onboardRecoveryCommand()` in the local inference-route failure message.
• Verification: Inspect `createLocalInferenceRouteApplier` with a portable environment and confirm its non-interactive exit message selects the shared helper output.
• Test coverage: Extend `src/lib/onboard/local-inference-route.test.ts` with a non-interactive portable-profile failure case that expects `onboard --experimental-profile portable` and excludes `onboard --resume`.
• Evidence: src/lib/onboard/local-inference-route.ts:66-71 prints the literal resume command on the exit-only non-interactive failure path. src/lib/onboard/command.ts:339-347 rejects `--resume` with `--experimental-profile portable`. src/lib/onboard/command.ts:544-570 applies the portable environment while `runOnboard` executes. src/lib/onboard/resume-hint.ts:6-10 defines the shared profile-aware recovery command.

Workflow run details

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

[apurvvkumaria]

CI disposition after the single safe reruns:

• The required CLI shard-8 timeout passed on rerun. The original timeout matched the unrelated rebuild-credential-preflight transient seen on other PRs.
• The isolated advisor lane passed on rerun; the published advisor and primary lane were already successful.
• The managed activation rerun stopped before executing the PR because the rerun job had no downloaded managed-image contract directory and therefore could not assemble the three-agent catalog. The three direct managed-startup jobs from the original run passed. This is workflow artifact plumbing on a failed-job rerun, not a failure in the PR's onboarding changes.

The one permitted rerun has been used, so I will not retry it again. The remaining failed managed-activation check is an external repository-workflow blocker that requires a fresh repository event or maintainer acceptance. All other required gates and human review must still pass.