fix(onboard): release stdin event-loop ref so the wizard exits after its final prompt

[laitingsheng]

Summary

nemoclaw onboard on Linux interactive TTY hangs after the post-onboard summary box — the wizard finishes, prints the dashboard URL, and then sits there with no shell prompt until the user reaches for Ctrl+C. The cause is readline.createInterface({ input: process.stdin }) resuming stdin internally and leaving the underlying TTY handle ref'd to the event loop after rl.close(); once the wizard's last prompt resolves Node has no other refs but still cannot exit. CI and other non-TTY callers did not hit this because the previous cleanup pause+unref'd stdin only when !process.stdin.isTTY.

This switches the shared prompt() cleanup to always pause+unref and adds a matching process.stdin.ref() at every prompt entry — the readline branch, the secret branch, promptSecret() itself, and the four raw-mode TUI selectors in onboard.ts — so a sticky unref() from a prior prompt cannot strand a follow-up read on a detached handle. The same TTY-guarded cleanup pattern in policies.ts and the missing pause/unref in sandbox-config.ts:confirmYesNo are aligned to the same shape.

Related Issues

Fixes #2518

Changes

• src/lib/credentials.ts: drop the if (!process.stdin.isTTY) guard from prompt() cleanup so pause+unref runs on every code path; hoist process.stdin.ref() above the secret-vs-readline branch so both paths re-attach stdin before the next read; make promptSecret() self-contained — ref() at the top of the body and pause+unref in its own cleanup so a direct caller (or two sequential direct calls) is safe regardless of prior stdin state.
• src/lib/onboard.ts: add process.stdin.ref() before the setRawMode(true) + resume() block in the messaging-channels selector and in the three identical arrow-key picker patterns (sandbox-prompt, model-prompt, policy-preset-prompt) so a sticky unref() from earlier prompt() cleanup does not leave the raw-mode read attached to a detached handle; add unref() to each cleanup so wizards that end on a TUI selector also exit naturally.
• src/lib/policies.ts: drop the if (!process.stdin.isTTY) guards in both preset-selection callbacks (lines 446 and 770) and add ref() at the top of each prompt block.
• src/lib/sandbox-config.ts: add the matching ref() + pause/unref pair to confirmYesNo(), which previously only ran rl.close() and would have leaked the same stdin ref had it ever been the wizard's last prompt.
• test/credentials.test.ts: source-text assertions for the new contract — TTY guard is gone from prompt() cleanup, ref() precedes the silent/secret branch in prompt(), promptSecret() is self-contained, and the secret-path cleanup pauses+unrefs.
• test/policies.test.ts: source-text assertions for the same contract on the two preset-selection prompts — TTY guard removed and a ref() precedes each createInterface.
• test/onboard.test.ts: source-text assertion that all four raw-mode TUI sites (one input.ref() alias + three process.stdin.ref() calls) ref before setRawMode(true) and unref after setRawMode(false), so any one of them stays safe to be the wizard's last prompt.

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)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make 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)

AI Disclosure

• AI-assisted — tool: Claude Code, Codex

---

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

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability of sequential interactive prompts (credentials, onboarding, policies, and configuration flows) so prompts no longer hang and the process exits cleanly after the final prompt.

• Tests

  • Added and extended tests to validate interactive prompt lifecycle and ensure multiple sequential prompts complete without leaving lingering handles or blocking subsequent prompts.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR ensures interactive prompts explicitly manage stdin event-loop references: each prompt re-attaches stdin with ref() before reads and pauses+unref() after cleanup across credentials, onboard, policies, and sandbox-config modules so the process can exit after the final prompt.

Changes

Cohort / File(s)	Summary
Stdin lifecycle (core prompt code) src/lib/credentials.ts, src/lib/onboard.ts, src/lib/policies.ts, src/lib/sandbox-config.ts	Add explicit process.stdin.ref() / input.ref() before interactive/readline/raw-mode prompts and perform symmetric process.stdin.pause() + process.stdin.unref() (when available) after closing/cleanup so prompts don't leave stdin in a detached state that blocks process exit or later prompts.
Tests (source-inspection & assertions) test/credentials.test.ts, test/onboard.test.ts, test/policies.test.ts	Add static/source-text assertions verifying prompts call ref() before entering raw-mode/readline and call pause()/unref() during cleanup; extend tests to catch regressions where a prior sticky unref() would block subsequent prompts or prevent process termination.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 In the terminal burrow where bytes like to hop,
I nudged stdin gently — "please don't just stop."
ref() before dancing, unref() when we're done,
No more stuck shells — now exit and run! 🎋

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.33% 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
Title check	✅ Passed	The title directly addresses the root cause of the issue: releasing stdin's event-loop reference so the wizard exits cleanly after the final prompt on Linux.
Linked Issues check	✅ Passed	Changes comprehensively implement stdin ref/unref lifecycle management across all interactive prompt paths (credentials, onboard, policies, sandbox-config) with matching test assertions to prevent the hang described in #2518.
Out of Scope Changes check	✅ Passed	All changes focus exclusively on managing stdin event-loop references in interactive prompts and their tests; no unrelated modifications are present.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/2518-onboard-stdin-cleanup

---

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