fix(advisories): keep the headless remote hint platform-neutral

[Dongni-Yang]

Outcome

The headless_remote_hint advisory no longer tells macOS users about "Headless Linux hosts". Its prose is platform-neutral, matching its predicate, and its remediation now recommends SSH port forwarding first while reserving CHAT_UI_URL for an HTTPS external origin.

Reason

reviewHeadlessUiSettings reads no platform term — its predicate is !DISPLAY && !WAYLAND_DISPLAY && !TERM_PROGRAM plus !hasNvidiaGpu. On macOS that collapses to "TERM_PROGRAM is unset", which is true over SSH, under launchd, under cron, and in CI, so a failed preflight on a Mac printed Linux-only prose. #10670's reported transcript showed exactly this.

#10734 left the remedy open as a product call: gate the check to Linux/WSL, or reword. This PR takes the reword, for three reasons:

• The remediation is platform-neutral. SSH port forwarding works across host platforms. When the dashboard genuinely needs an external origin, CHAT_UI_URL provides the same override on every OS.
• Gating would regress macOS coverage to fix a wording defect. The repository treats isHeadlessLikely as a valid macOS signal: the Docker Desktop credential-store advisory uses it on its non-WSL branch (src/lib/advisories/checks/host/docker.ts), and Docker Desktop on macOS is the common case.
• The repository pattern is "predicate matches prose." Every other host advisory that names an OS carries a matching platform predicate — the WSL-integration advisory gates on isWsl, while the docker-group advisory returns null unless platform === "linux". headless_remote_hint was the only outlier. Rewording restores the pattern by removing the OS claim rather than adding a gate.

Related issues

Closes #10734
Refs #10670

Changes

• src/lib/advisories/checks/host/toolchain.ts — removes the Linux-only wording and recommends SSH port forwarding for remote browser access. It directs users to set CHAT_UI_URL only when the dashboard needs an HTTPS external origin.
• src/lib/advisories/checks/host/toolchain.test.ts — adds a macOS regression test that verifies the advisory still fires and pins the platform-neutral reason and remote-access command.

No new mechanism is added. This is advisory copy plus its protecting test.

Verification

• npx vitest run --project cli src/lib/advisories/checks/host/toolchain.test.ts — 3 passed
• npm run typecheck:cli — passed
• npm run validate:pr — passed
• Fresh PR Review Advisor on final commit d76ff23 — completed successfully; all actionable findings resolved
• Fresh E2E on final commit d76ff23 — completed successfully
• Fresh CI on final commit d76ff23 — completed successfully
• CodeRabbit final review — no actionable comments
• Diff contains no secrets, API keys, or credentials

---

Signed-off-by: Dongni Yang dongniy@nvidia.com

[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: 9a1551ee-a79d-4829-adbc-8bdffd4adf0c

📥 Commits

Reviewing files that changed from the base of the PR and between 0e6b8a9 and d76ff23.

📒 Files selected for processing (2)

• src/lib/advisories/checks/host/toolchain.test.ts
• src/lib/advisories/checks/host/toolchain.ts

Included review availability: Your plan provides up to 12 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The headless host advisory now uses platform-neutral wording. It recommends SSH port forwarding and conditional CHAT_UI_URL configuration. The macOS Docker Desktop test verifies the updated advisory output.

Changes

Headless advisory

Layer / File(s)	Summary
Advisory wording and macOS coverage src/lib/advisories/checks/host/toolchain.ts, src/lib/advisories/checks/host/toolchain.test.ts	The advisory removes the Linux-specific qualifier and adds SSH port-forwarding and CHAT_UI_URL guidance. The macOS test verifies the updated reason and command.

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

Merge Risk: ⚪ Minimal · up to d76ff

This change only makes the headless remote hint platform-neutral while preserving its existing behavior and adds a focused regression test; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: apurvvkumaria, brandonpelfrey, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #10734 by removing Linux-specific wording from headless_remote_hint while preserving the advisory behavior and remediation. The added macOS test verifies the platform-neutr…
Out of Scope Changes check	✅ Passed	The source and test changes are directly related to the linked issue. No unrelated code changes are present in the provided summary.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: making the headless remote advisory platform-neutral.

Full details: Linked Issues check

Explanation

The changes satisfy issue #10734 by removing Linux-specific wording from headless_remote_hint while preserving the advisory behavior and remediation. The added macOS test verifies the platform-neutral message and SSH port-forwarding guidance.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files.

✨ 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/10734-headless-hint-platform-neutral

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit d76ff23 in the fix/10734-headless-h... branch remains at 96%, unchanged from commit d5d24b9 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit d76ff23 in the fix/10734-headless-h... branch remains at 84%, unchanged from commit 2b7ae7f in the main branch.

Show a line coverage summary of the most impacted files.

File	main 2b7ae7f	fix/10734-headless-h... d76ff23	+/-
src/lib/onboard...press-resume.ts	78%	76%	-2%
src/lib/onboard...tup-nim-flow.ts	93%	92%	-1%
src/lib/onboard...tup-nim-vllm.ts	90%	90%	0%
src/lib/sandbox...rce-identity.ts	82%	82%	0%
src/lib/state/s...le-key-merge.ts	100%	100%	0%
src/lib/onboard...uild-context.ts	74%	75%	+1%
src/lib/inferen.../vllm-models.ts	93%	95%	+2%
src/lib/inferen...verification.ts	0%	97%	+97%

---

_{Updated September 01, 2026 20:05 UTC}

[github-actions]

PR Review Advisor finished for commit d76ff23. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

All previous runs

[prekshivyas]

Verified the final diff and exact-SHA checks. The macOS advisory is platform-neutral, its remote-access guidance matches the documented SSH and HTTPS paths, and focused tests, CI, E2E, CodeRabbit, and the Advisor are clear.