fix(onboard): restore portable and legacy launch recovery

[senthilr-nv]

Summary

Prevent portable onboarding from reporting a healthy rootless Podman runtime as unreachable when the OpenShell network is not yet inspectable. Restore the qualified-launch contract for legacy OpenClaw registry entries and print an actionable resume command when onboarding failed before recording a sandbox name.

Related Issue

Related to #9006.
Follow-up to #9023.

Changes

• Probe the Docker-compatible runtime with JSON output and validate both Docker and native Podman daemon schemas with the shared parser.
• Keep rejected runtime-info stdout and stderr outside the rendered failure diagnostic while reporting bounded status, signal, timeout, or version-observation outcomes.
• Pass the launch-readiness decision's trusted agent identity into session completion so a legacy agent: null OpenClaw entry does not repeat the complete pairing path.
• Preserve complete session setup for non-OpenClaw agents and missing sandbox state.
• Add --name <sandbox> to the incomplete-onboarding resume hint when no sandbox name was checkpointed.

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: Existing command, troubleshooting, recovery, portable-profile, and gateway-authentication docs already describe these contracts; this PR restores their implementation.
• 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: Exact launch-readiness qualification remains authoritative; only accepted OpenClaw state skips approval, while non-OpenClaw and missing-sandbox states retain complete setup. The runtime probe requires exit-zero, valid Docker or Podman daemon JSON, rejects malformed, empty, or unreachable results, and never renders captured runtime-info output.
• 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: no-docs-needed
• Evidence: Existing docs already own the unchanged --resume/--name, portable runtime, and lease-qualified OpenClaw pairing contracts. The review covered the complete 10-file diff, including the bounded user-visible runtime diagnostic and its credential-bearing regression.
• Agent: Codex Desktop

Brev Exact-Head Validation

• Candidate: 5fc6746bf34c38d4c93ef72489a07d5de62f83ba; causal control: cc89a7d6fe701845b00f379902c0cfa2888c9fc9.
• Environment: Brev nc-1l40sgpu-aug13, Node 22.23.2, OpenShell 0.0.101, portable rootless Podman through unix:///run/user/1000/podman/podman.sock, and the preserved my-assistant registry entry with agent: null.
• Candidate launch-to-first exact gateway connected | idle: 5.228s, 5.265s, 5.428s, and 5.324s; mean 5.311s and median 5.295s. The complete pairing fallback was absent in all four runs.
• Control launch time: 11.364s, 9.788s, and 9.755s; mean 10.302s. The complete pairing fallback ran in all three controls and averaged 4.391s.
• Observed end-to-end mean improvement: 4.991s (48.4%). Probe-only exact-head status was 0 in 1.127s.
• Registry and readiness-receipt hashes remained unchanged. The exact test processes were removed after capture; older pre-existing sessions were preserved.

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 — npx vitest run --project cli on the five affected test files: 108 passed
• Applicable broad gate passed — not required for this narrow change; an informational npm run test:fast attempt produced 19,730 passes and 16 unrelated host-sensitive failures on macOS temporary-path, filesystem, GNU utility, and timing assumptions
• 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: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Improvements

  • Improved sandbox session setup for qualified OpenClaw launches while preserving support for legacy and other supported agent configurations.
  • Enhanced Docker and Podman reachability checks with clearer diagnostics for unavailable, incomplete, timed-out, or unsuccessful probes.
  • Resume guidance now includes the relevant sandbox name and a recovery command when needed.

• Tests

  • Added coverage for qualified launches, legacy sandbox records, reachability outcomes, and onboarding recovery hints.

[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: b365935c-858e-44f3-b26d-4a3dc4397269

📥 Commits

Reviewing files that changed from the base of the PR and between 0cbf006 and 5fc6746.

📒 Files selected for processing (2)

• src/lib/onboard/gateway-sandbox-reachability.test.ts
• src/lib/onboard/gateway-sandbox-reachability.ts

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

• src/lib/onboard/gateway-sandbox-reachability.ts

---

📝 Walkthrough

Walkthrough

The changes update readiness-qualified sandbox setup, portable runtime reachability validation, and onboarding resume hints. Tests cover trusted agent propagation, legacy sandbox entries, structured daemon responses, credential redaction, and nullable sandbox names.

Changes

Sandbox session setup

Layer / File(s)	Summary
Trusted agent propagation and setup src/lib/actions/sandbox/connect.ts, src/lib/actions/sandbox/launch.ts, src/lib/actions/sandbox/connect-qualified-session-setup.test.ts	Readiness-qualified setup receives the trusted agent definition. OpenClaw skips the approval pass while broker setup remains active.
Legacy registry compatibility tests src/lib/actions/sandbox/launch.test.ts	Tests cover null registry agents, OpenClaw setup, legacy pairing behavior, and TUI launch.

Portable runtime reachability

Layer / File(s)	Summary
Structured runtime daemon probing src/lib/onboard/gateway-sandbox-reachability.ts	Runtime probing accepts Docker arguments and a timeout. Portable checks validate formatted JSON and parsed daemon reachability.
Runtime probe classification tests src/lib/onboard/gateway-sandbox-reachability.test.ts	Tests cover Docker and Podman observations, unavailable network inspection, invalid daemon responses, credential redaction, and generic failure details.

Onboarding resume hints

Layer / File(s)	Summary
Sandbox-aware recovery commands src/lib/onboard/resume-hint.ts, src/lib/onboard/exit-step-failure.ts	Resume hints receive the sandbox name and add --name <sandbox> when the name is unavailable.
Resume hint behavior tests src/lib/onboard/resume-hint.test.ts, src/lib/onboard/exit-step-failure.test.ts	Tests cover missing and recorded sandbox names in resume guidance.

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

Merge Risk: ⚪ Minimal · up to 5fc67

The change restores portable runtime detection, legacy launch recovery, and actionable onboarding resumption without any evidenced merge-blocking risk; it is ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant launchSandbox
  participant AgentDefinition
  participant completeReadinessQualifiedInteractiveSessionSetup
  participant BrokerSetup
  launchSandbox->>AgentDefinition: resolve decision.agent
  launchSandbox->>completeReadinessQualifiedInteractiveSessionSetup: pass sandbox and agent
  completeReadinessQualifiedInteractiveSessionSetup->>BrokerSetup: configure broker
  completeReadinessQualifiedInteractiveSessionSetup->>completeReadinessQualifiedInteractiveSessionSetup: skip OpenClaw approval pass

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8951 — Updates the readiness-qualified session setup and launch flow.
• NVIDIA/NemoClaw#8958 — Updates onboarding resume behavior and sandbox-name handling.
• NVIDIA/NemoClaw#9034 — Modifies readiness-qualified OpenClaw setup and pairing approval.

Suggested labels: area: onboarding, area: sandbox, bug-fix, platform: container

Suggested reviewers: apurvvkumaria, prekshivyas, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: restoring portable and legacy launch recovery behavior.

✨ 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-portable-probe-launch-readiness

---

_{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 5fc6746 in the codex/fix-portable-p... branch remains at 96%, unchanged from commit 73a3ce3 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 5fc6746 in the codex/fix-portable-p... branch remains at 82%, unchanged from commit 73a3ce3 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 73a3ce3	codex/fix-portable-p... 5fc6746	+/-
src/lib/onboard...mage-runtime.ts	49%	51%	+2%
src/lib/sandbox...rce-identity.ts	81%	85%	+4%
src/lib/onboard...al-inference.ts	95%	99%	+4%
src/lib/actions...ridge-output.ts	89%	95%	+6%
src/lib/onboard...-environment.ts	91%	98%	+7%
src/lib/onboard...teway-config.ts	90%	97%	+7%
src/lib/onboard...eate-journal.ts	80%	89%	+9%
src/lib/inferen...al-lifecycle.ts	88%	97%	+9%
src/lib/onboard...ne-authority.ts	86%	96%	+10%
src/lib/inferen...ntext-window.ts	32%	50%	+18%

---

_{Updated August 14, 2026 07:07 UTC}

[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 — trusted agent identity at src/lib/actions/sandbox/connect.ts:1227: Keep the term. The modifier identifies the authority used to skip OpenClaw pairing.
• justified — Docker-compatible runtime at src/lib/onboard/gateway-sandbox-reachability.ts:245: Keep the term. The modifier accurately includes Docker and Podman daemon schemas.

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

• ubuntu-repo-docker-post-reboot-recovery

Workflow run details

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