fix(install): name NEMOCLAW_FRESH=1 in failed-session remediation

[laitingsheng]

Summary

The installer's failed onboarding-session error told users to Re-run with --fresh, but --fresh cannot be passed through a piped curl … | bash install — the only actionable lever there is the NEMOCLAW_FRESH=1 environment variable, which the installer already documents and honours. The three run_onboard failed-session branches now name NEMOCLAW_FRESH=1, so the remediation is actionable for the non-interactive and no-TTY paths that emit it.

Related Issue

Fixes #6912

Changes

• scripts/install.sh: the non-interactive, no-TTY, and TTY-unreadable failed-session branches now advise NEMOCLAW_FRESH=1 in place of the un-pipeable --fresh flag; the onboard --resume alternative is unchanged.
• test/install-preflight.test.ts: the non-interactive failed-session test now asserts the emitted error names NEMOCLAW_FRESH=1, guarding the corrected remediation.

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: NEMOCLAW_FRESH=1 is already documented in the installer help and environment list; only an existing error-message string changed.
• 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: wording-only change to an existing onboarding error message; no change to control flow, onboarding logic, or security posture — deferring to maintainer review.
• 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:
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: n/a — string-only installer change, no broad runtime/harness or coverage change.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Updated installer guidance for recovering from failed onboarding sessions.
  • Clarified how to start a fresh onboarding attempt or resume an existing session in interactive and non-interactive modes.
  • Corrected the fresh-start option to use the NEMOCLAW_FRESH=1 environment setting.

[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: 01091f63-7491-49ae-8c85-6d1a014580ac

📥 Commits

Reviewing files that changed from the base of the PR and between 55fdc3f and df98f7f.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

The installer’s failed-onboarding messages now recommend NEMOCLAW_FRESH=1 instead of --fresh, while retaining the onboard --resume option. The related non-interactive test assertion was updated accordingly.

Changes

Failed onboarding guidance

Layer / File(s)	Summary
Installer guidance and validation scripts/install.sh, test/install-preflight.test.ts	Failed-session guidance uses NEMOCLAW_FRESH=1 for non-interactive and interactive error paths, and the test verifies the updated text.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested labels: bug-fix

Suggested reviewers: cv, sandl99, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main installer remediation change and matches the PR scope.
Linked Issues check	✅ Passed	The PR updates all failed-session installer messages to name NEMOCLAW_FRESH=1 and keeps the resume path, matching #6912.
Out of Scope Changes check	✅ Passed	The changes stay within installer messaging and the related test update, with no unrelated scope added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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/6912-onboard-fresh-env-remediation

---

_{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/6912-onboard-fre... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 55fdc3f	fix/6912-onboard-fre... df98f7f	+/-
src/lib/shields/audit.ts	97%	92%	-5%

---

_{Updated July 15, 2026 10:40 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: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of 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: cloud-onboard

1 optional E2E recommendation

• onboard-negative-paths

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover the changed no-TTY failed-session remediation branches

• Location: scripts/install.sh:2412
• Category: tests
• Problem: The patch changes the no-TTY and unreadable-TTY failed-session messages to recommend NEMOCLAW_FRESH=1, but the updated installer harness asserts that wording only for the non-interactive branch. Neither remaining changed error path has checked-in coverage for the actionable remediation text.
• Impact: A later edit can silently restore the unusable --fresh-only advice for piped or unavailable-TTY installs while the current regression test remains green.
• Recommendation: Add focused installer-harness cases that force the no-TTY and TTY-read-failure branches and assert NEMOCLAW_FRESH=1 appears, the installer fails, and onboard is not invoked.
• Verification: Read test/install-preflight.test.ts around the failed-session tests: its only NEMOCLAW_FRESH=1 assertion is in the non-interactive case, while scripts/install.sh:2412 and :2419 contain the other changed branches.
• Test coverage: Two installer-harness regressions: one with a failed session and no readable TTY, and one where reading the selected TTY fails; each should assert nonzero status, NEMOCLAW_FRESH=1 in output, and no onboard log.
• Evidence: scripts/install.sh:2412 changes the no-readable-TTY error to NEMOCLAW_FRESH=1. scripts/install.sh:2419 changes the TTY-read-failure error to NEMOCLAW_FRESH=1. test/install-preflight.test.ts:966 is the only checked-in assertion for NEMOCLAW_FRESH=1 and belongs to the non-interactive failed-session test.

Workflow run details

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

[prekshivyas]

Reviewed the installer remediation and surrounding failed-session paths. The change matches the documented curl-pipe recovery flow, the exact head is mergeable with all required checks and E2E green, and the full installer integration suite passes locally (94/94).