fix(install): show full failed-session recovery command

[sandl99]

Summary

Failed onboarding-session exits currently name NEMOCLAW_FRESH=1 without giving non-technical users a complete installer command. As a follow-up to #6916, this change prints a copy-pasteable curl ... --fresh command and the full agent-specific resume command while preserving the active supported agent.

Changes

• Show the complete fresh-install and resume commands in all three failed-session error exits.
• Keep the default OpenClaw command concise and preserve Hermes or Deep Agents through fixed, whitelisted NEMOCLAW_AGENT selectors.
• Cover non-interactive, unreadable-terminal, prompt-read-failure, Hermes, and Deep Agents recovery output.
• Update the troubleshooting page so each generated agent variant shows its exact fresh and resume commands.

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: pending maintainer re-review after addressing the requested agent-variant coverage and fixed-selector handling.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — command/result or justification: npx vitest run --project integration test/install-onboard-yes.test.ts — 13 passed; npx vitest run --project installer-integration test/install-preflight.test.ts -t "refuses to auto-resume a failed onboarding session" — 1 passed, 93 skipped; npm run test-size:check, shellcheck scripts/install.sh, bash -n scripts/install.sh, and npx biome check test/install-onboard-yes.test.ts passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not applicable; focused installer recovery output, tests, and matching troubleshooting guidance.
• 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) — 0 errors and 2 existing warnings; npm run docs:sync-agent-variants passed.
• 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 installer recovery messaging for a failed previous onboarding session, including cases with no readable terminal or failed input capture.
  • Recovery instructions now consistently provide agent-aware “start over” (--fresh) and “retry/resume” (onboard --resume) commands.
• Documentation
  • Updated troubleshooting guidance for “Previous onboarding session failed” with agent-specific fresh reinstall examples.
• Tests
  • Strengthened preflight and installer tests to verify the exact fresh one-liner, resume guidance, and correct agent context across failure scenarios.

[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 installer’s failed onboarding recovery guidance now uses agent-aware --fresh commands to discard sessions and onboard --resume to retry them. Tests and troubleshooting documentation cover these recovery paths.

Changes

Failed onboarding recovery

Layer / File(s)	Summary
Installer recovery guidance scripts/install.sh	Failed-session paths now provide an agent-aware `curl ...
Recovery validation test/install-preflight.test.ts, test/install-onboard-yes.test.ts	Tests verify remediation output, agent preservation, non-zero exits, and that the CLI is not invoked when prompt handling fails.
Troubleshooting recovery documentation docs/reference/troubleshooting.mdx	Documentation adds per-agent fresh commands, environment-variable placement guidance, and resume instructions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#1395: Refactors related installer onboarding and session-resume behavior.
• NVIDIA/NemoClaw#6916: Updates the same failed-session remediation paths and test assertions.
• NVIDIA/NemoClaw#6917: Modifies failed onboarding remediation messaging and test coverage.

Suggested labels: bug-fix

Suggested reviewers: hwangjohn, ericksoa, miyoungc

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 accurately captures the main change: installer messaging now shows the full failed-session recovery command.

✨ 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/failed-session-full-command

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@test/install-preflight.test.ts`:
- Around line 964-966: Extend the existing test assertion in the preflight
failure case to also verify that the combined stdout/stderr contains the
preserved `${_CLI_BIN} onboard --resume` command. Keep this as an observable
output assertion alongside the existing freshCommand check, using the same
result output boundary.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8ed7d2e9-f157-4fc1-9f39-65e7f98d825e

📥 Commits

Reviewing files that changed from the base of the PR and between a31140a and c5b2bc5.

📒 Files selected for processing (2)

• scripts/install.sh
• test/install-preflight.test.ts

[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/failed-session-f... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 7d1cef9	fix/failed-session-f... f6e4b51	+/-
src/lib/inferen...time-context.ts	94%	92%	-2%
src/lib/securit...ntial-filter.ts	99%	98%	-1%
src/lib/inference/local.ts	77%	84%	+7%
src/lib/inferen...del-registry.ts	66%	100%	+34%

---

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

[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): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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: cloud-onboard

1 optional E2E recommendation

• 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)

test/install-onboard-yes.test.ts (1)

137-192: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Fragile coupling: [ override is keyed to install.sh's exact test-expression syntax.

The overridden [ function pattern-matches on literal argument shapes ("-t" "0" "]", "!" "-r" "/dev/tty" "]") rather than the semantic outcome being tested. Verified this currently matches install.sh's if [ -t 0 ] / if [ ! -r "$_prompt_stdin" ] exactly, so today's test is sound, but if that syntax shifts even slightly (e.g., [[ ]], swapped operand order, test instead of [), the override silently falls through to builtin [ "$@", and the test's determinism would then depend on the sandbox's actual TTY/env state rather than the intended forced branch — a regression that wouldn't surface as an obvious failure.

Consider a less implementation-coupled seam (e.g., a small testable indirection in install.sh for TTY detection, or a real pty-based test double) if this pattern gets reused further. As per path instructions, this is the kind of "broad mock that bypasses the behavior under test" worth flagging.

🤖 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 `@test/install-onboard-yes.test.ts` around lines 137 - 192, The test helper
runFailedSessionRecovery currently overrides [ by matching install.sh’s exact
test syntax, making branch control fragile. Replace this broad syntax-coupled
mock with a stable test seam in run_onboard/install.sh for TTY and prompt-input
detection, or use a real PTY-based double, so both unreadable-tty and
read-failure modes deterministically exercise the intended behavior without
relying on literal [ argument patterns.

Source: Path instructions

🤖 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 `@test/install-onboard-yes.test.ts`:
- Around line 137-192: The test helper runFailedSessionRecovery currently
overrides [ by matching install.sh’s exact test syntax, making branch control
fragile. Replace this broad syntax-coupled mock with a stable test seam in
run_onboard/install.sh for TTY and prompt-input detection, or use a real
PTY-based double, so both unreadable-tty and read-failure modes
deterministically exercise the intended behavior without relying on literal [
argument patterns.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 606cb33f-d68a-47f8-9673-3cc7a0713847

📥 Commits

Reviewing files that changed from the base of the PR and between 4fa53cc and d8c48b4.

📒 Files selected for processing (1)

• test/install-onboard-yes.test.ts

[cv]

Reviewed the installer recovery-path change and focused coverage. The change only expands the displayed fresh-install command; it does not add a new execution path or interpolate untrusted input. Local verification passed after building the CLI: 105 tests across the two focused installer suites. Approving pending completion of required CI and E2E gates.

[cv]

Variant audit found a blocking recovery-command regression. All three new failed-session messages hardcode curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --fresh and omit the active NEMOCLAW_AGENT. An unset selector defaults to OpenClaw, so Hermes or Deep Agents users who follow the advertised complete command can silently reinstall the wrong agent. Please preserve the active nondefault agent in the displayed fresh-install command and add focused Hermes and Deep Agents coverage, while keeping the OpenClaw/default command concise. This supersedes my earlier approval.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-6964.docs.buildwithfern.com/nemoclaw

[cv]

The agent-selection blocker is resolved. The recovery command now comes from an allowlisted case over OpenClaw, Hermes, and Deep Agents, is reused by all three failed-session error paths, and does not interpolate arbitrary input. Variant-aware docs match the commands. Local focused verification passed: 13 tests in test/install-onboard-yes.test.ts. Approving pending the refreshed required CI and E2E rollup.