fix(onboard): name the advisory identifier in preflight remediation output

[laitingsheng]

Summary

Onboarding preflight printed an advisory title and remediation commands but dropped the advisory identifier, so terminal output could not be matched to the identifier used in the troubleshooting docs. The suggested-fix list now names the identifier after each action title, for example Fix the DOCKER_HOST endpoint (invalid_docker_host).

Related Issue

Fixes #8473

Changes

• src/lib/onboard/remediation.ts: printRemediationActions takes the action identifier and renders - <title> (<id>): <reason>. planHostRemediation already carried the identifier on every action, so no new plumbing was added. The format matches the advisory presenter in src/lib/advisories/presenter.ts.
• src/lib/onboard/preflight-docker-host.test.ts: renders an assessed host with an unsupported DOCKER_HOST through planHostRemediation into captured stderr and asserts the identifier reaches the output.
• docs/reference/troubleshooting.mdx: the invalid Docker host section states that the identifier appears in the Suggested fix list.

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: Maintainer security review PASS: fix(onboard): name the advisory identifier in preflight remediation output #8476 (comment)
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: non-required managed-runtime activation failure classified as unrelated baseline Docker inspection drift; maintainer evidence: fix(onboard): name the advisory identifier in preflight remediation output #8476 (comment)

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/reference/troubleshooting.mdx
• Agent: Codex independent documentation writer

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: npx vitest run --project cli src/lib/onboard/preflight-docker-host.test.ts src/lib/onboard/preflight-messages.test.ts src/lib/onboard/preflight.test.ts (142 passed); npm run typecheck:cli (clean)
• 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)

npm run docs reports 0 errors and the 2 warnings already present on main.

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Documentation

  • Added troubleshooting guidance explaining the advisory identifier shown alongside onboarding remediation titles.
  • Users can match terminal messages, such as invalid_docker_host, with the corresponding troubleshooting section.

• Bug Fixes

  • Improved invalid Docker host guidance by recommending that users unset DOCKER_HOST or use the appropriate Unix socket.
  • Removed unrelated Docker-group and Docker-start remediation suggestions from this scenario, making fixes more accurate.

[coderabbitai]

📝 Walkthrough

Walkthrough

Remediation actions now require identifiers and print them in suggested-fix output. A regression test verifies invalid_docker_host output and remediation selection. Troubleshooting documentation identifies the advisory identifier.

Changes

Docker host advisory output

Layer / File(s)	Summary
Include identifiers in remediation output src/lib/onboard/remediation.ts	Remediation actions require an id field. Suggested-fix output includes the identifier.
Validate invalid Docker host guidance src/lib/onboard/preflight-docker-host.test.ts, docs/reference/troubleshooting.mdx	The regression test checks invalid Docker host guidance, Unix socket output, and exclusion of unrelated remediation identifiers. The troubleshooting guide documents invalid_docker_host.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes add invalid_docker_host to remediation output, preserve actionable commands, and test exclusion of unrelated findings as required by issue #8473.
Out of Scope Changes check	✅ Passed	The code, regression test, and troubleshooting documentation changes directly support the linked issue and stated pull request objectives.
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 clearly and concisely describes the main change: adding advisory identifiers to onboarding preflight remediation output.

✨ 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-remediation-advisory-id

---

_{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 e3d9cd9 in the fix/onboard-remediat... branch remains at 96%, unchanged from commit 0d33997 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit e3d9cd9 in the fix/onboard-remediat... branch remains at 81%, unchanged from commit e323de1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main e323de1	fix/onboard-remediat... e3d9cd9	+/-
src/lib/actions...eway-restart.ts	94%	92%	-2%
src/lib/actions...air-approval.ts	90%	89%	-1%
src/lib/inferen...ompatibility.ts	94%	94%	0%
src/lib/inferen...y-production.ts	48%	48%	0%
src/lib/agent/runtime.ts	86%	86%	0%
src/lib/inferen...er-discovery.ts	87%	88%	+1%
src/lib/onboard/remediation.ts	76%	82%	+6%
src/lib/inferen...a/model-size.ts	83%	96%	+13%
src/lib/onboard...box-prebuild.ts	77%	91%	+14%
src/lib/onboard...flight-ports.ts	33%	67%	+34%

---

_{Updated August 06, 2026 14:41 UTC}

[github-actions]

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

[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 `@src/lib/onboard/preflight-docker-host.test.ts`:
- Around line 19-36: Extend the test case around
printRemediationActions(planHostRemediation(assessment)) to assert the
invalid-host output includes an actionable absolute unix:// socket remediation
and does not contain the start_docker finding. Preserve the existing assertions
for the advisory identifier, unset DOCKER_HOST, and exclusion of
docker_group_permission.

🪄 Autofix

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: 3a5190de-e25e-49b3-99f7-12220a95ac8d

📥 Commits

Reviewing files that changed from the base of the PR and between e323de1 and a8561a8.

📒 Files selected for processing (3)

• docs/reference/troubleshooting.mdx
• src/lib/onboard/preflight-docker-host.test.ts
• src/lib/onboard/remediation.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

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 · 0 warnings · 0 suggestions

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

1 semantic terminology decision

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

• justified — advisory identifier at docs/reference/troubleshooting.mdx:141: Keep “advisory identifier” when distinguishing the stable identifier from the remediation title.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

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

Workflow run details

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

[apurvvkumaria]

Maintainer security review for current branch revision b3dfbd189: PASS.

Reviewed all changed files against the nine-category checklist:

1. Secrets and credentials — PASS; no secret material or credential handling changed.
2. Input validation and sanitization — PASS; a static internal advisory ID is added to terminal output, with no new parsing or execution path.
3. Authentication and authorization — PASS; no auth or privilege boundary changed.
4. Dependencies — PASS; no dependency changes.
5. Error handling and logging — PASS; output adds the stable advisory identifier and does not expose sensitive data.
6. Cryptography and data protection — PASS; not applicable, no cryptographic operation changed.
7. Configuration and security headers — PASS; no configuration, container, or HTTP boundary changed.
8. Security testing — PASS; regression coverage exercises the invalid-host remediation and verifies unrelated Docker findings remain absent.
9. Holistic posture — PASS; the change improves diagnostic traceability without widening command, filesystem, network, or privilege authority.

Independent documentation-writer review: docs updated accurately; the test-only feedback fix needs no further docs. npm run docs passed with 0 errors and 2 warnings already present on the base branch. Targeted onboarding tests: 142 passed. CLI type-checking and repository source/test structure checks passed.

[apurvvkumaria]

CI classification for the current branch revision: the managed images build successfully and their direct startup harnesses pass. The remaining failure is external GHCR publication infrastructure.

• The original Hermes publication was rejected with GitHub’s secondary-rate-limit response.
• A failed-job retry cleared that publication, but the dependent catalog job could not reconstruct all three same-attempt contracts from a partial rerun.
• A complete retry rebuilt all lanes, then the Deep Agents publication received the same secondary-rate-limit response.

This does not exercise or implicate the remediation-output change in this PR. I am not starting another immediate retry because the same registry limit has repeated across three attempts. The lane should be retried after the GitHub/GHCR rate-limit window clears; all review fixes, local validation, DCO, documentation review, and security review remain complete.

Withdrawing this review because a non-Advisor E2E check is failing; this PR does not meet the requested green-CI screen.

[apurvvkumaria]

Current-branch readiness receipt for revision e3d9cd90f:

• The three contributor-owned files are byte-identical to the previously reviewed versions; the latest commit only synchronized main.
• Correctness/security review: PASS, no actionable findings. The change only prints the existing stable advisory identifier and does not alter remediation selection, commands, severity, blocking, input handling, or exit behavior. No raw DOCKER_HOST or other sensitive value is newly logged.
• Validation passes: 154 focused CLI tests, CLI build and typecheck, Biome, test-title style, diff checks, and documentation validation with 0 errors, 2 existing warnings, and all 67 guarded routes.
• The PR description now carries current documentation receipt metadata. All four commits are GitHub Verified and the DCO check is green.
• The primary Advisor published merge_as_is with no findings; the secondary model lane failed after a partial review and is advisory.

The failed all-agent managed-runtime activation is unrelated to this three-file presentation change: onboarding reached sandbox creation and then rejected external managed-bootstrap runtime normalization drift in Docker inspect fields. All required aggregate PR checks passed. I will retry that non-required live qualification only after the active GitHub Actions outage recovers. Independent approval remains required before merge.

[apurvvkumaria]

Maintainer follow-up: the later complete retry progressed past the earlier GHCR throttling, so the final failed managed-runtime lane has a different classification. It reached OpenClaw onboarding and then rejected baseline Docker inspection drift in AttachStderr, AttachStdout, and PortBindings. The same external managed-runtime drift was independently observed and documented on #8425. This PR changes only the remediation label, its focused test, and the matching troubleshooting text; it does not touch managed image activation or Docker replacement normalization. All five protected contexts, direct managed startup lanes, focused onboarding tests, documentation review, security review, DCO, and commit verification pass. I accept this non-required failure as unrelated baseline drift; no PR code change or immediate rerun during the GitHub Actions incident is indicated.

[apurvvkumaria]

Reviewed the current branch revision. The remediation output now carries the stable advisory identifier, the regression test covers the actionable Unix-socket guidance and excludes unrelated findings, and the troubleshooting text matches the behavior. Focused tests, type checking, documentation review, security review, DCO, commit verification, all protected contexts, and the review advisor pass. The remaining optional managed-runtime failure is documented as unrelated baseline drift.