fix(onboard): extend dashboard readiness wait

[apurvvkumaria]

Summary

Dashboard-forward startup now gives OpenShell's exact sandbox is not ready handoff up to 1 minute to settle. Actions run 31767577321 showed multiple onboarding lanes exhausting the ordinary three-retry allowance while the new sandbox was still transitioning to forward-ready state.

Authentication, ownership, port-conflict, and ordinary listener failures keep their existing retry and cleanup behavior.

Changes

• Give the exact OpenShell readiness response a separate default of 12 retries with 5-second delays.
• Preserve maxRetries as an explicit override for every retryable outcome.
• Cover recovery after four consecutive readiness responses and the persistent 12-retry bound.
• Update the OpenClaw and Hermes quickstarts with the readiness-specific wait.

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: The repository security checklist covered the complete four-file diff. The longer wait remains limited to one exact OpenShell diagnostic and one minute; authentication, ownership, cleanup, and ordinary listener retry boundaries are unchanged. No security finding was identified.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Updated both quickstarts to describe the exact readiness response, 12 retries, 5-second intervals, and the 1-minute maximum readiness-specific delay. npm run docs, file-scoped hooks, and diff validation passed.
• Agent: Codex documentation writer subagent

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; DGX Station preparation is unchanged.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

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 — focused forward-start suite: 47 passed; affected test selection: 370 passed across 28 files
• Applicable broad gate passed — npm run typecheck:cli, npm run docs, source-shape and test-conditional validation, targeted repository hooks, and diff validation passed
• 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) — result: zero errors; two existing Fern notices
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved sandbox startup handoff reliability by retrying “sandbox is not ready” responses up to 12 times.
  • Added five-second delays between readiness retries, allowing up to one minute for the sandbox to become available.
  • Preserved existing sandbox and selected host-port settings throughout retries.
  • Kept standard retry behavior separate and unchanged.

• Documentation

  • Updated quickstart guides to explain the extended sandbox-readiness retry behavior.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[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: 7f438fc1-e893-4b7b-9e51-11782be1f867

📥 Commits

Reviewing files that changed from the base of the PR and between e3d1fe9 and 6cb3217.

📒 Files selected for processing (1)

• src/lib/onboard/forward-start.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard/forward-start.test.ts

---

📝 Walkthrough

Walkthrough

The forward-start flow now handles exact sandbox is not ready responses with up to 12 five-second retries. Tests cover successful and exhausted retries. Both quickstart documents describe the one-minute maximum delay.

Changes

Sandbox readiness retry handling

Layer / File(s)	Summary
Dedicated readiness retry flow src/lib/onboard/forward-start.ts	Sandbox-readiness failures use a separate 12-retry budget and five-second delay. These retries do not perform cleanup. Ordinary retry behavior remains unchanged.
Retry validation and documentation src/lib/onboard/forward-start.test.ts, docs/get-started/quickstart.mdx, docs/get-started/quickstart-hermes.mdx	Tests cover successful and exhausted readiness retries. Both quickstart documents describe the 12-attempt limit and five-second delay.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 6cb32

The PR extends the wait only for the exact sandbox-not-ready response and documents that behavior; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• NVIDIA/NemoClaw#8931: Both PRs modify src/lib/onboard/forward-start.ts and its tests for the exact sandbox is not ready retry path.
• NVIDIA/NemoClaw#9064: Both PRs modify sandbox-readiness handling and retry exact sandbox is not ready forwarding failures, but in different code paths and functions.

Suggested labels: area: onboarding, bug-fix

Suggested reviewers: cv

🚥 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 change: extending the dashboard readiness wait during onboarding.
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.

✨ 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 codex/fix-dashboard-forward-readiness-31767577321

---

_{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 6cb3217 in the codex/fix-dashboard-... branch remains at 96%, unchanged from commit d0ac205 in the main branch.

---

_{Updated August 14, 2026 05:28 UTC}

[github-actions]

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

[senthilr-nv]

Approved PR 9089

[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 · medium 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.

2 semantic terminology decisions

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

• justified — readiness-specific at docs/get-started/quickstart-hermes.mdx:290: Keep `readiness-specific` for the bounded delay that applies only to the exact readiness diagnostic.
• established — readiness handoff at src/lib/onboard/forward-start.ts:66: Keep the established term for this OpenShell lifecycle transition.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

1 optional E2E recommendation

• double-onboard

Workflow run details

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