fix(sandbox): preserve Shields parent ownership on restart

[jyaunches]

Summary

OpenShell 0.0.99 began preparing its default /sandbox workspace when Docker supplies OPENSHELL_OCI_IMAGE_USER; after a Shields up restart, that preparation changes the protected parent from root:sandbox to sandbox:sandbox before the workload starts and leaves the container restarting. This change preserves the protected parent by omitting only that marker at NemoClaw's exact reviewed Docker recreation boundary while keeping the explicit sandbox:sandbox workload policy and /sandbox runtime contract.

Related Issue

Follow-up to #8662. Complementary to #8765, which covers supervisor recovery after transient process exits rather than the pre-workload workspace ownership change.

Changes

• Add the Docker recreation compatibility correction required by the OpenClaw and Hermes Shields lifecycle consumers. OpenShell 0.0.101 has no supported switch for preserving the existing default-workspace owner, so the exact root-supervisor, Docker working-directory, supervisor-argument, label, startup-command, and identity-metadata contract is validated before omitting OPENSHELL_OCI_IMAGE_USER; malformed or partial metadata fails before cutover. Focused clone and managed-bootstrap environment-delta tests protect this boundary.
• Require every shipped managed policy to retain explicit sandbox:sandbox process identity, and verify the replacement still preserves empty driver UID/GID markers plus every unrelated environment entry.
• Extend the OpenClaw and Hermes Shields live targets with redacted Docker logs on startup failure and post-restart assertions for workload user, group, home, and working directory. The OpenClaw lane also proves /sandbox remains 1775 root:sandbox after a Shields up restart.
• Correct the later failed-startup E2E proof to stop and continue PID 1 through the Docker daemon, verify the stopped state before terminating the startup child, and retain exit 137 as a hard failure.
• Record the escaped workspace-ownership finding and correction in the OpenShell 0.0.99 and 0.0.101 migration reviews.
• Scope: this repairs fresh Docker recreation used by the failing lanes. Existing affected containers still require recreation, and native-GPU composition remains a separate live-evidence gap.

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:
• 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: independent Codex Desktop nine-category security review found no blocking findings after verifying the exact OpenShell producer contract, fail-closed metadata validation, replacement delta, and diagnostic redaction.
• 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: docs-updated
• Evidence: docs/security/openshell-0.0.99-migration-review.md; docs/security/openshell-0.0.101-migration-review.md
• Agent: Codex Desktop

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 — npm exec -- vitest run src/lib/onboard/docker-gpu-patch-clone.test.ts src/lib/onboard/managed-bootstrap/docker.test.ts test/openshell-0.0.99-migration-review.test.ts test/openshell-0.0.101-migration-review.test.ts --maxWorkers=2 (67 passed); source-shape review tests (35 passed); npm run typecheck:cli; npm run checks:repository; and npm run test:e2e-phases:check passed; npm exec -- vitest run --project e2e-support test/e2e/support/shields-failed-startup.test.ts passed 10 focused tests.
• 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)

npm run docs completed with zero errors and two existing Fern warnings.

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Docker workspace migration compatibility for managed environments.
  • Preserved /sandbox ownership, permissions, and runtime identity during container replacement.
  • Rejected malformed or unauthorized identity metadata.
  • Prevented failed replacements from stopping the existing workload.

• Diagnostics

  • Enhanced startup recovery with Docker logs and clearer failure details.
  • Added checks for runtime identity, working directory, home directory, and workspace permissions.

• Documentation

  • Updated migration and security reviews with compatibility requirements and acceptance criteria.
  • Documented managed policy identity requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds an OpenShell/NemoClaw Docker compatibility correction. It omits OPENSHELL_OCI_IMAGE_USER at the reviewed workspace boundary, validates metadata and policy identities, and strengthens Shields restart evidence.

Changes

OpenShell workspace compatibility

Layer / File(s)	Summary
OCI metadata resolution src/lib/onboard/docker-gpu-patch-clone.ts, src/lib/onboard/docker-gpu-patch-clone.test.ts	The clone path detects the reviewed NemoClaw boundary, validates identity metadata, omits only OPENSHELL_OCI_IMAGE_USER when required, and preserves metadata outside that boundary.
Docker replacement validation src/lib/onboard/managed-bootstrap/docker.ts, src/lib/onboard/managed-bootstrap/docker-test-fixture.ts, src/lib/onboard/managed-bootstrap/docker.test.ts	Replacement preparation propagates the omission decision through environment and launch-spec validation. Tests cover accepted omission, rejected reintroduction, and preservation of the original workload.
Runtime restart evidence test/e2e/live/hermes-shields-config.test.ts, test/e2e/live/shields-config.test.ts, test/e2e/fixtures/shields-failed-startup.ts, test/e2e/support/shields-failed-startup.test.ts	Recovery tests collect redacted Docker logs, control supervisor signals, and verify runtime identity, paths, and /sandbox permissions after restart.
Migration contract evidence test/openshell-0.0.99-migration-review.test.ts, ci/source-shape-test-budget.json, docs/security/*openshell*migration-review.md	Migration tests require explicit sandbox policy identities. Security reviews document the ownership regression, compatibility boundary, and acceptance checks.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DockerInspection
  participant CompatibilityResolver
  participant DockerReplacement
  participant ShieldsRecovery
  DockerInspection->>CompatibilityResolver: inspect metadata and intended workload
  CompatibilityResolver-->>DockerReplacement: omit OCI-user marker when boundary matches
  DockerReplacement->>ShieldsRecovery: recreate and restart workload
  ShieldsRecovery-->>DockerReplacement: runtime identity and /sandbox evidence

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8660: Modifies related OpenShell 0.0.99/0.0.101 compatibility and migration behavior.
• NVIDIA/NemoClaw#8761: Modifies the same OpenShell 0.0.99 migration review and its qualification gates.

Suggested labels: area: sandbox, platform: container, area: security, bug-fix, v0.0.106

Suggested reviewers: cv

🚥 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
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 change: preserving Shields parent ownership during sandbox restarts.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-shields-config-restart

---

_{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 618d243 in the codex/fix-shields-co... branch remains at 96%, unchanged from commit 4298c03 in the main branch.

---

_{Updated August 11, 2026 01:07 UTC}

[github-actions]

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

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/docker-gpu-patch-clone.ts (1)

358-401: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reduce complexity in shouldOmitOpenShellOciImageUser.

This resolver combines boundary detection, metadata extraction, legacy handling, and metadata validation. Extract the boundary check and identity-metadata validation into focused helpers. Keep this compatibility decision easy to audit.

As per coding guidelines, “Keep function complexity low; tracked existing complexity hotspots do not justify increasing complexity elsewhere.”

🤖 Prompt for 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.

In `@src/lib/onboard/docker-gpu-patch-clone.ts` around lines 358 - 401, Refactor
shouldOmitOpenShellOciImageUser by extracting the exactNemoClawBoundary
detection into a focused helper and the OCI/sandbox identity metadata
validation, including legacy handling, into another helper. Keep
shouldOmitOpenShellOciImageUser as a concise coordinator that reuses these
helpers and preserves the current return and error behavior.

Source: Coding guidelines

🤖 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.

Nitpick comments:
In `@src/lib/onboard/docker-gpu-patch-clone.ts`:
- Around line 358-401: Refactor shouldOmitOpenShellOciImageUser by extracting
the exactNemoClawBoundary detection into a focused helper and the OCI/sandbox
identity metadata validation, including legacy handling, into another helper.
Keep shouldOmitOpenShellOciImageUser as a concise coordinator that reuses these
helpers and preserves the current return and error behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 465daef0-cc7d-44c5-96a8-a24a24215f7b

📥 Commits

Reviewing files that changed from the base of the PR and between b8232eb and 7c13d79.

📒 Files selected for processing (11)

• ci/source-shape-test-budget.json
• docs/security/openshell-0.0.101-migration-review.md
• docs/security/openshell-0.0.99-migration-review.md
• src/lib/onboard/docker-gpu-patch-clone.test.ts
• src/lib/onboard/docker-gpu-patch-clone.ts
• src/lib/onboard/managed-bootstrap/docker-test-fixture.ts
• src/lib/onboard/managed-bootstrap/docker.test.ts
• src/lib/onboard/managed-bootstrap/docker.ts
• test/e2e/live/hermes-shields-config.test.ts
• test/e2e/live/shields-config.test.ts
• test/openshell-0.0.99-migration-review.test.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 · 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.

4 terminology differences from the second opinion

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

• exact NemoClaw startup boundary at docs/security/openshell-0.0.101-migration-review.md:210: selected only by the second-opinion lane as define.
• escaped compatibility regression at docs/security/openshell-0.0.101-migration-review.md:23: selected only by the second-opinion lane as define.
• OCI workspace preparation at test/openshell-0.0.99-migration-review.test.ts:153: selected only by the second-opinion lane as define.
• Shields parent ownership at src/lib/onboard/docker-gpu-patch-clone.ts:398: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — OCI image-user metadata at docs/security/openshell-0.0.99-migration-review.md:20: Keep this term. The concrete contrast makes the modifier necessary.
• define — workspace identity metadata at src/lib/onboard/docker-gpu-patch-clone.ts:389: Define this term near the validator or replace it with "OpenShell OCI identity metadata".
• justified — NemoClaw startup boundary at docs/security/openshell-0.0.101-migration-review.md:210: Keep this term. The documented contract provides the necessary concrete contrast.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, managed-image-protected-runtime, security-posture, hermes-shields-config, onboard-repair, onboard-resume, shields-config

1 optional E2E recommendation

• e2e-all

Workflow run details

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