fix(onboard): persist managed OpenClaw agent identity

[ericksoa]

Summary

Managed OpenClaw sandbox registration now stores agent: "openclaw" when a validated managed-image receipt owns the sandbox. Legacy and custom-image registrations keep agent: null. A mismatch between the receipt and selected agent fails before the registry write.

Related Issue

Fixes #9356

Changes

• buildCreatedSandboxRegistryEntry() now checks the selected agent against the validated managed-image receipt and persists the explicit agent identity. readManagedWorkloadAuthority() consumes this field during rebuild and restore operations.
• sandbox-registration.test.ts covers managed OpenClaw authority, the legacy custom-image convention, and rejection before the registry writer runs.

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: Maintainer Aaron Erickson explicitly accepted the reviewed sensitive-path change for admin merge on 2026-08-17 after CodeRabbit and all other feedback were clear; CodeRabbit reported no actionable comments and the exact-head PR Review Advisor reported zero findings.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: Maintainer Aaron Erickson accepted the CI / Pull Request / checks non-success on 2026-08-17 because shard 6 is the unchanged Launchable authorization-step contract on main (follow-up ci(e2e): add one-off launchable validation #9368/ci(e2e): authorize NVIDIA-owned PR revisions #9369), and accepted Images / Managed Images / PR exact all-agent managed runtime activation because its exact-head-only build hits the unchanged two-argument sandbox-messaging.ts call already fixed on current main by fix(onboard): pass messaging dependencies during reuse #9366. Neither failure overlaps this PR’s changed files or behavior.

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: vitest run --project cli src/lib/onboard/sandbox-registration.test.ts --testTimeout 30000 — 18 tests passed; vitest run --project integration test/onboard-managed-image-buildless-e2e.test.ts --testTimeout 30000 — 1 test 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)

The pre-commit and commit-msg hooks passed for both commits. At base SHA cb018f0224, the pre-push CLI type check was blocked by unchanged errors in sandbox-messaging.ts, sandbox-messaging.test.ts, and portable-uninstall-retirement.test.ts. PR #9366 fixed the shared sandbox-messaging.ts root cause on main; current-base CI at 54cb2a414f passed build-typecheck and installer-integration. CLI shard 6 remains blocked by an unchanged E2E test that references the removed Authorize Launchable image publication workflow step; PRs #9368 and #9369 update that contract, so this branch does not absorb the unrelated E2E change.

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

[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: d433d9f1-93d6-4efa-86a6-66c8c9254af2

📥 Commits

Reviewing files that changed from the base of the PR and between 183c595 and 06cbac0.

📒 Files selected for processing (1)

• test/helpers/managed-image-buildless-e2e.ts

Included review availability: Your plan includes up to 12 reviews per rolling hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

Managed-image sandbox registration now validates receipt agent identity and repository digest before registry mutation. Validated managed agents are persisted in registry entries. Legacy custom-image entries retain agent: null. Tests cover propagation, mismatch rejection, and end-to-end registration assertions.

Changes

Managed sandbox identity

Layer / File(s)	Summary
Validate managed receipt identity src/lib/onboard/sandbox-registration.ts	Managed-image workloads must use a recognized requested agent and matching repository SHA-256 reference. The validated agent is written to the registry entry, and mismatches throw before registry mutation.
Verify identity propagation and rejection src/lib/onboard/sandbox-registration.test.ts, test/helpers/managed-image-buildless-e2e.ts	Added managed receipt fixtures and tests for OpenClaw identity propagation, legacy custom-image behavior, mismatch rejection, and registration identity assertions.

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

Merge Risk: 🟡 Moderate · up to 06cba

The change persists the managed OpenClaw agent identity and rejects receipt mismatches before registry writes. Targeted tests pass, but the required review or waiver for the sensitive onboarding path is not recorded, so the PR should not merge until that gate is completed or explicitly accepted.

Possibly related PRs

• NVIDIA/NemoClaw#9212: Both changes validate managed-image receipt and agent identity consistency before state mutation.
• NVIDIA/NemoClaw#9323: This change extends its managed-image onboarding path with agent identity validation and propagation.

Suggested reviewers: cv, senthilr-nv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the linked issue requirements for managed identity persistence, receipt validation, legacy compatibility, and pre-write rejection.
Out of Scope Changes check	✅ Passed	The changes remain within scope and cover onboarding logic, targeted tests, and the related managed-image E2E assertion.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: persisting the managed OpenClaw agent identity during onboarding.

✨ 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/managed-openclaw-agent-9356

---

_{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 183c595 in the fix/managed-openclaw... branch remains at 96%, unchanged from commit 54cb2a4 in the main branch.

---

_{Updated August 17, 2026 22:46 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 · high 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 terminology decisions differ; normalized E2E selections differ; severity counts match.

3 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• managed workload receipt at src/lib/onboard/sandbox-registration.test.ts:97: selected only by the second-opinion lane as established.
• legacy OpenClaw registry identity at src/lib/onboard/sandbox-registration.test.ts:110: selected only by the second-opinion lane as justified.
• explicit OpenClaw identity at src/lib/onboard/sandbox-registration.test.ts:97: selected only by the second-opinion lane as justified.

2 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• rebuild-hermes: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• rebuild-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

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.

• established — managed workload receipt at src/lib/onboard/sandbox-registration.ts:236: Keep this established term for the managed-image ownership record.
• established — agent identity at src/lib/onboard/sandbox-registration.ts:236: Keep this established term for the selected agent runtime type.

E2E guidance

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

Recommended E2E: managed-image-protected-runtime

Manual-only E2E: managed-image-multiarch-startup, 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

• onboard-managed-image-buildless-e2e

Workflow run details

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