fix(onboard): remove stale Hermes volumes on recreation

[prekshivyas]

Summary

Remove a recreated sandbox's stale Hermes state volume when the replacement target does not use managed Hermes state. Previously, the lifecycle wrapper was truthy even when volume preparation returned no lifecycle, so recreation incorrectly retained the old volume for OpenClaw, custom-Dockerfile, and non-Docker targets.

Changes

• Return null from the managed Hermes state lifecycle wrapper when no managed volume is prepared.
• Keep the existing managed-Hermes volume only when the replacement target actually prepares that lifecycle.
• Add transition tests proving stale-volume removal for non-Hermes targets and preservation for a managed Docker Hermes target.

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:
• 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: Reviewed recreation cleanup and failure behavior; deletion still occurs only after confirmed sandbox absence and continues to use the existing exact NemoClaw volume-ownership gate. Failed removal still preserves the registry entry.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — command/result or justification: npx vitest run --project cli src/lib/onboard/sandbox-create/orchestration.test.ts src/lib/onboard/managed-workload/onboard-orchestration.test.ts src/lib/onboard/managed-workload/hermes-state-volume.test.ts (54 passed)
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Prekshi Vyas prekshiv@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved managed Hermes state-volume onboarding when preparation is unavailable, preventing incomplete setup operations.
  • Added safer handling for state-volume recreation scenarios.

• Tests

  • Expanded coverage for recreating workloads with OpenClaw, custom Dockerfiles, and non-Docker configurations.
  • Verified appropriate source-volume cleanup and preservation for managed Docker Hermes workloads.
  • Confirmed source registry entries are removed consistently.

• Documentation

  • Updated integration test coverage documentation for managed Hermes state-volume behavior.

[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: 6ab28d25-13e9-4b1e-9488-aafdebc0cde6

📥 Commits

Reviewing files that changed from the base of the PR and between ba12fc0 and f546035.

📒 Files selected for processing (3)

• src/lib/onboard/managed-workload/hermes-state-volume.ts
• src/lib/onboard/managed-workload/onboard-orchestration.ts
• src/lib/onboard/sandbox-create/orchestration.test.ts

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

---

📝 Walkthrough

Walkthrough

Managed Hermes state-volume onboarding now returns null when preparation is unavailable. Recreation tests cover source-volume cleanup and source registry removal across workload configurations.

Changes

Hermes state-volume lifecycle

Layer / File(s)	Summary
Require a prepared state-volume scope src/lib/onboard/managed-workload/onboard-orchestration.ts, src/lib/onboard/managed-workload/hermes-state-volume.ts	The lifecycle return contract allows null when preparation fails. Prepared scopes require mount injection and commit execution. Integration-test documentation includes sandbox recreation coverage.
Validate recreation cleanup src/lib/onboard/sandbox-create/orchestration.test.ts	Parameterized tests verify source-volume removal or preservation across OpenClaw, custom Dockerfile, non-Docker, and managed Docker Hermes recreations. Tests also verify source registry removal.

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

Merge Risk: ⚪ Minimal · up to f5460

This change removes stale Hermes state for replacements that do not use managed Hermes while preserving it for managed targets; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: ericksoa, laitingsheng

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: removing stale Hermes state volumes during sandbox recreation.
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hermes-recreate-volume-cleanup

---

_{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 f546035 in the fix/hermes-recreate-... branch remains at 96%, unchanged from commit ba12fc0 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit f546035 in the fix/hermes-recreate-... branch remains at 84%, unchanged from commit ea1927d in the main branch.

Show a line coverage summary of the most impacted files.

File	main ea1927d	fix/hermes-recreate-... f546035	+/-
src/lib/actions...ary-recovery.ts	97%	92%	-5%
src/lib/actions...eway-restart.ts	98%	97%	-1%
src/lib/onboard...ind-contract.ts	94%	93%	-1%
src/lib/adapter...observer-cli.ts	100%	99%	-1%
src/lib/onboard...uild-context.ts	74%	74%	0%
src/lib/actions...ateway-state.ts	80%	80%	0%
src/lib/onboard...rchestration.ts	63%	63%	0%
src/lib/gateway...ntime-action.ts	94%	95%	+1%
src/lib/onboard...rchestration.ts	30%	32%	+2%
src/lib/actions...sor-relaunch.ts	91%	98%	+7%

---

_{Updated August 27, 2026 04:10 UTC}

[prekshivyas]

Superseded by #10450. The consolidated PR now includes the managed Hermes recreation ownership fix, failed-create compensation, lifecycle documentation, and owned/reused/foreign-volume regression coverage.