fix(sandbox): preserve persisted agent through registry recovery

[laitingsheng]

Summary

Registry recovery silently rewrote a sandbox's persisted agent field to null whenever it had no source of truth for that field (the live OpenShell gateway does not expose the NemoClaw agent type, and the session-seeded path never read session.agent). A NemoHermes sandbox would therefore end up registered as agent: null after the first command that triggered recovery, which downstream agent-aware paths interpret as OpenClaw — nemohermes list showed agent: openclaw, status drifted to "Provisioning", and rebuild aborted in pre-rebuild backup because state paths under /sandbox/.hermes-data were probed against the OpenClaw manifest.

Related Issue

Fixes #5327

Changes

• src/lib/registry-recovery-action.ts — buildRecoveredSandboxEntry now omits agent from the returned entry unless metadata.agent is explicitly provided, so the Object.assign in updateSandbox can no longer clobber a persisted agent: "hermes" with null. The session-seed path also threads session.agent through, so a confirmed onboard session keeps the correct agent across recovery.
• src/lib/registry-recovery-action.test.ts — adds two regression tests: (a) a persisted Hermes agent is preserved when the session re-seeds with agent: "hermes"; (b) a persisted agent is still preserved when an older session format omits the agent field entirely.

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
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Improved recovery mechanism to better preserve agent settings. The system now correctly maintains existing agent information during recovery operations and restores agent data when available from the session.

[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: d89df5bc-a996-4f0d-8e15-a6b370f342ba

📥 Commits

Reviewing files that changed from the base of the PR and between b4ba8ec and 064a505.

📒 Files selected for processing (2)

• src/lib/registry-recovery-action.test.ts
• src/lib/registry-recovery-action.ts

---

📝 Walkthrough

Walkthrough

This PR fixes a registry recovery bug where Hermes agent type information was being overwritten with null during sandbox recovery operations. The core logic now conditionally preserves the agent field, and session recovery includes agent information when available. Two test cases validate the fix covers both agent preservation scenarios.

Changes

Hermes Agent State Preservation in Recovery

Layer / File(s)	Summary
Conditional agent field assignment in recovery src/lib/registry-recovery-action.ts	buildRecoveredSandboxEntry assigns entry.agent only when recovery metadata contains an explicit non-null value, preventing persisted agents from being overwritten. seedRecoveryMetadata passes agent: session.agent || null to enable agent restoration when session provides it.
Test coverage for agent preservation during recovery src/lib/registry-recovery-action.test.ts	Two new tests validate that Hermes agent and agentVersion are preserved when recovery re-seeds from session data, and that persisted agent is not clobbered when session metadata omits the agent field.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

area: sandbox, bug-fix, integration: hermes

Suggested reviewers

• cv
• prekshivyas
• sandl99

Poem

A Hermes agent, once proud and free,
Was lost to null in recovery—
No more! We guard with conditional care,
And test to prove the agent's still there. 🐰✨

🚥 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%.	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 accurately summarizes the main code change: fixing registry recovery to preserve the persisted agent field through the recovery process.
Linked Issues check	✅ Passed	The code changes directly address issue #5327 by preserving agent metadata through recovery, enabling correct agent identification and preventing backup failures.
Out of Scope Changes check	✅ Passed	All changes are scoped to registry recovery logic and corresponding tests; no unrelated modifications are present outside the recovery objectives.

_{✏️ 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/recovery-preserves-hermes-agent

---

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

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: PR review advisor unavailable

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• PR review advisor unavailable: The automated advisor could not complete: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt
  • Recommendation: Re-run the PR Review Advisor or perform a manual review.
  • Evidence: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — Add or identify targeted runtime/integration validation for the changed behavior; do not report external E2E job pass/fail here.. Runtime/sandbox/infrastructure paths need behavioral runtime validation: src/lib/registry-recovery-action.ts.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[github-actions]

E2E Advisor Recommendation

Required E2E: hermes-e2e-vitest, sandbox-rebuild-vitest
Optional E2E: double-onboard-vitest, sandbox-survival-vitest

Dispatch hint: hermes-e2e-vitest,sandbox-rebuild-vitest

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• hermes-e2e-vitest (high): Runs the real Hermes install/onboard/runtime path and asserts Hermes session/registry agent metadata plus live Hermes health/inference, making it the closest existing guard for the agent metadata boundary changed here.
• sandbox-rebuild-vitest (high): Exercises real sandbox rebuild with registry metadata mutation and state preservation. The changed recovery code is on the sandbox lifecycle path and the PR rationale explicitly mentions rebuild-time agent resolution risk.

Optional E2E

• double-onboard-vitest (high): Useful adjacent coverage for stale registry recovery/list/status/connect/rebuild behavior across multiple sandboxes, but it is less directly tied to Hermes agent preservation than the required lanes.
• sandbox-survival-vitest (high): Covers registry/list/status behavior and live sandbox survival through gateway restart, providing confidence that registry recovery remains compatible with runtime recovery paths.

New E2E recommendations

• Hermes registry recovery before rebuild (high): No existing E2E appears to reproduce the exact regression: a persisted Hermes registry entry plus older/stale onboard-session metadata that omits agent, followed by registry recovery and a rebuild/connect path that must keep agent: "hermes" and use Hermes state paths.
  • Suggested test: Add a focused live Vitest scenario that onboards Hermes, snapshots/edits sandboxes.json and onboard-session.json to omit session.agent, triggers nemoclaw list or nemoclaw <sandbox> rebuild --yes, and asserts the registry still has agent: "hermes" and the rebuilt runtime uses /sandbox/.hermes-data rather than /sandbox/.openclaw-data.

Dispatch hint

• Workflow: .github/workflows/e2e-vitest-scenarios.yaml
• jobs input: hermes-e2e-vitest,sandbox-rebuild-vitest

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: None
Optional Vitest E2E scenarios: sandbox-rebuild-vitest

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required Vitest E2E scenarios

• None.

Optional Vitest E2E scenarios

• sandbox-rebuild-vitest: Adjacent registry/rebuild metadata coverage: this job mutates stale registry metadata and verifies rebuild refresh/preservation behavior. It is OpenClaw-focused, so it is optional rather than the primary Hermes-agent target.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=sandbox-rebuild-vitest

Relevant changed files

• src/lib/registry-recovery-action.ts
• src/lib/registry-recovery-action.test.ts