fix(onboard): persist OpenClaw startup command

[jyaunches]

Summary

An OpenShell Docker-driver sandbox can restart when its OpenShell gateway restarts. OpenClaw onboarding previously left the persisted container command as sleep infinity, so the container returned without nemoclaw-start or the OpenClaw gateway. OpenClaw now uses the existing restart-safe startup-command path already used by Hermes and Deep Agents Code.

Changes

• Recognize OpenClaw's canonical null agent representation when selecting Docker startup-command persistence.
• Persist the existing OpenClaw nemoclaw-start command during Docker-driver onboarding.
• Keep the existing transactional recovery path for legacy sleep infinity sandboxes unchanged.
• Exercise explicit recovery in sandbox-survival and capture credential-safe container, process, service, health, and startup diagnostics around the gateway restart.
• Verify registry identity, writable state, sandbox execution, inference, and OpenClaw gateway health after restart.

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 gateway lifecycle and recovery docs already describe the OpenShell PID 1 topology and restart-safe recovery; no command, flag, or supported workflow changed.
• 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 change reuses the existing sanitized Docker startup-command persistence path. E2E diagnostics redact API key values and classify the startup command without printing command text or process argv.
• 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: Reviewed exact head 8bf80331200fb7819a7c03404191ea97dc62bc4b. The merge from main did not alter the five PR files. Existing docs already cover OpenShell PID 1 launching nonroot nemoclaw-start and legacy transactional recovery. The canonical null agent fix and its controlled Docker test fixture add no command, flag, configuration, default, workflow, or support claim.
• Agent: Codex CLI

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 published commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed for the exact head
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Focused regression passed 11 tests; the onboarding regression cluster passed 47 tests; shared subprocess fixture consumers passed 54 tests; npm run test:changed passed 44 tests; CLI typecheck, Biome, and git diff --check passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Exact-head trusted sandbox-survival E2E is pending.
• 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: Julie Yaunches jyaunches@nvidia.com
Signed-off-by: Prekshi Vyas prekshiv@nvidia.com
Signed-off-by: San Dang sdang@nvidia.com

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The OpenShell readiness probe now retries qualifying follow-up failures after a retryable sandbox re-registration state. Unit tests cover blank and opaque retries plus terminal blanks, while sandbox survival coverage validates OpenClaw gateway health after restart.

Changes

OpenShell readiness recovery

Layer / File(s)	Summary
Retryable blank follow-up handling src/lib/actions/sandbox/process-recovery.ts, src/lib/actions/sandbox/process-recovery.test.ts	The probe tracks retryable re-registration states and treats qualifying blank or opaque follow-ups as inconclusive; tests cover repeated retries, eventual success, and isolated terminal failure.
Post-restart gateway health validation test/e2e/live/sandbox-survival.test.ts	The survival contract, post-restart state validation, and completion artifact assert restored OpenClaw gateway health.

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

Suggested labels: area: sandbox, area: e2e, bug-fix

Suggested reviewers: brandonpelfrey, cv, ericksoa

Sequence Diagram(s)

sequenceDiagram
  participant ReadinessLoop
  participant OpenShell
  participant SleepTimer
  ReadinessLoop->>OpenShell: Probe recreated sandbox
  OpenShell-->>ReadinessLoop: Retryable re-registration state
  ReadinessLoop->>OpenShell: Probe follow-up result
  ReadinessLoop->>SleepTimer: Wait 3 seconds
  SleepTimer-->>ReadinessLoop: Advance retry time
  OpenShell-->>ReadinessLoop: Success or terminal blank failure

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title describes persisting an OpenClaw startup command, but the changes update sandbox recovery retries and gateway health validation.	Use a title that identifies the sandbox recovery retry behavior and the added OpenClaw gateway health validation after restart.

✅ Passed checks (4 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.

✨ 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-sandbox-survival-status

---

_{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 01d1b41 in the codex/fix-sandbox-su... branch remains at 96%, unchanged from commit 91fc63e in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 01d1b41 in the codex/fix-sandbox-su... branch remains at 81%, unchanged from commit 91fc63e in the main branch.

Show a code coverage summary of the most impacted files.

File	main 91fc63e	codex/fix-sandbox-su... 01d1b41	+/-
src/lib/onboard...ommand-agent.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated July 31, 2026 04:47 UTC}

[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/actions/sandbox/process-recovery.test.ts`:
- Around line 138-164: Update the test around
waitForRecreatedSandboxOpenShellReady to inject a controllable nowImpl clock,
advance that clock by each recorded sleep duration in sleepImpl, and increase
timeoutSeconds to 7. Preserve the three-probe sequence and assertions so the
test exercises the retry path with enough time for the final ready probe.

🪄 Autofix (Beta)

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: 87e0abbe-65c8-49f6-a406-36bffe96eede

📥 Commits

Reviewing files that changed from the base of the PR and between d52d459 and db52f20.

📒 Files selected for processing (2)

• src/lib/actions/sandbox/process-recovery.test.ts
• src/lib/actions/sandbox/process-recovery.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 · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-inference, cloud-onboard, security-posture, onboard-repair, onboard-resume, sandbox-survival, 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.

[github-actions]

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

[cv]

Post-merge verification against main E2E run 30594584034 and exact PR head 01d1b41:

Both available main-run attempts failed at the same restart boundary. sandbox-survival and ubuntu-repo-docker-post-reboot-recovery left the sandbox present, but recovery could not restart the managed agent gateway.

The final diff makes canonical OpenClaw use the existing restart-safe Docker startup-command path. It replaces persisted sleep infinity with the generated nemoclaw-start command. Unit and integration tests bind that selection and the recreated Docker command.

Exact-head trusted E2E run 30605105778 passed sandbox-survival. Its evidence showed the persisted command ending in nemoclaw-start, healthy Docker state, a running OpenClaw gateway, an HTTP 200 probe, and preserved state and inference.

This change directly addresses both reported failures through their shared Docker restart mechanism. The exact-head risk plan did not separately select ubuntu-repo-docker-post-reboot-recovery; that target conclusion relies on the shared mechanism and the exact sandbox-survival restart evidence.

[cv]

Follow-up after direct target validation: my earlier shared-mechanism inference was too broad for ubuntu-repo-docker-post-reboot-recovery. A later exact-head run containing #7856 executed that named target and failed after the lifecycle boundary: the managed Docker container remained stopped, OpenShell reported Error, Docker health was unhealthy, and nemoclaw status classified sandbox_container_stopped. The exact sandbox-survival pass still validates #7856 for that breakage, but it does not establish a complete fix for the Docker post-reboot target. Treat docker-post-reboot-recovery as still unresolved pending a direct passing run and a fix for the stopped-container path.

Direct target evidence: https://github.com/NVIDIA/NemoClaw/actions/runs/30606139059/job/91078772350