fix(onboard): preserve structured mounts during recreation

[jyaunches]

Summary

Deep Agents Code startup-command recreation preserved legacy Docker binds but silently dropped OpenShell structured mounts, causing the exact-main MCP bridge proof to lose its tmpfs immediately after onboarding. Preserve the structured mount contract across recreation and reject unsupported inspect shapes before mutating the original container.

Changes

• Render OpenShell tmpfs mounts with their read-only flag, arbitrary options, byte size, and octal mode when recreating a Docker sandbox.
• Render supported named-volume mounts with their read-only, no-copy, and subpath options; fail closed on unsupported mount types and option shapes.
• Extend the clone inspect fixture with the exact noexec, 16 MiB, mode 1777 tmpfs that failed in live E2E, and prove unsupported mounts are rejected before stop, rename, or clone.
• Record the QA escape: the DCode recreation path added in fix(onboard): persist DCode Docker startup limits #7128 exercised HostConfig.Mounts, while its source tests modeled only HostConfig.Binds; the corrected fixture now protects that boundary.

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: this restores the existing internal Docker-driver recreation contract without changing commands, configuration, defaults, schemas, migrations, or documented behavior; the required documentation review found no inaccurate user-facing guidance.
• 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: fail-closed review confirmed that only the tmpfs and named-volume shapes emitted by supported OpenShell are reconstructed, delimiter-bearing or malformed values are rejected, and unsupported mount types fail before the original container is stopped or renamed.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project cli src/lib/onboard/docker-gpu-patch-clone.test.ts src/lib/onboard/docker-gpu-patch-validation.test.ts (27 passed); npx vitest run --project cli src/lib/onboard/docker-gpu-patch-recreate.test.ts (2 passed); npm run typecheck:cli 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: Julie Yaunches jyaunches@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Docker GPU sandbox clones now preserve supported tmpfs and volume mount settings, including read-only, no-copy, subpath, size, and mode options.
  • Unsupported mount types are rejected before modifying the original container.
  • Improved validation prevents invalid structured mount configurations from being recreated.

[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: 2cf5883f-c80a-4319-be13-32939850c861

📥 Commits

Reviewing files that changed from the base of the PR and between 757e5e2 and 391378a.

📒 Files selected for processing (5)

• src/lib/onboard/__test-helpers__/docker-gpu-patch-fixtures.ts
• src/lib/onboard/docker-gpu-patch-clone.test.ts
• src/lib/onboard/docker-gpu-patch-clone.ts
• src/lib/onboard/docker-gpu-patch-types.ts
• src/lib/onboard/docker-gpu-patch-validation.test.ts

---

📝 Walkthrough

Walkthrough

Structured Docker mount inspection types, fixture data, clone argument reconstruction, and validation tests were added. Supported tmpfs and volume mounts are preserved during GPU container cloning, while unsupported mount types are rejected before modifying the original container.

Changes

Docker structured mount preservation

Layer / File(s)	Summary
Mount inspection contracts and fixtures src/lib/onboard/docker-gpu-patch-types.ts, src/lib/onboard/__test-helpers__/docker-gpu-patch-fixtures.ts	HostConfig.Mounts now has explicit structured mount types, and the inspection fixture includes the configured tmpfs mount.
Structured mount argument reconstruction src/lib/onboard/docker-gpu-patch-clone.ts	Supported tmpfs and volume mounts are validated and serialized into --tmpfs or --mount clone arguments.
Mount preservation and rejection tests src/lib/onboard/docker-gpu-patch-clone.test.ts, src/lib/onboard/docker-gpu-patch-validation.test.ts	Tests cover tmpfs and volume option preservation and verify unsupported bind mounts are rejected before container operations.

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

Sequence Diagram(s)

sequenceDiagram
  participant DockerInspect
  participant MountSerializer
  participant CloneArgsBuilder
  DockerInspect->>MountSerializer: provide HostConfig.Mounts
  MountSerializer->>MountSerializer: validate structured mount options
  MountSerializer->>CloneArgsBuilder: return --tmpfs and --mount arguments
  CloneArgsBuilder->>CloneArgsBuilder: append mount arguments to clone command

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7128: Extends the same clone argument builder to preserve Docker ulimits.

Suggested labels: bug-fix, area: sandbox

Suggested reviewers: ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: preserving structured mounts when recreating onboarding sandboxes.
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.

✨ 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-dcode-structured-mounts

---

_{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 remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the codex/fix-dcode-stru... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 757e5e2	codex/fix-dcode-stru... 391378a	+/-
src/lib/onboard...-patch-clone.ts	99%	95%	-4%
src/lib/state/registry.ts	86%	83%	-3%
src/lib/adapter...hell/resolve.ts	100%	100%	0%
src/lib/agent/s...store-reader.ts	90%	90%	0%
src/lib/sandbox...rce-identity.ts	91%	91%	0%
src/lib/securit...p-url-target.ts	100%	100%	0%
src/lib/state/config-io.ts	93%	93%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/credentials/store.ts	59%	64%	+5%
src/lib/core/pr...mpt-activity.ts	67%	92%	+25%

---

_{Updated July 18, 2026 01:43 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 fewer blocker, the same number of warnings, the same number of suggestions.

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: onboard-repair, onboard-resume, cloud-onboard

1 optional E2E recommendation

• gpu-e2e

Blockers

PRA-1 Blocker — Read structured mounts from Docker inspect's top-level mount list

• Location: src/lib/onboard/docker-gpu-patch-clone.ts:215
• Category: correctness
• Problem: The clone builder iterates `HostConfig.Mounts` and serializes `Target`, but raw `docker inspect` mount records are not normalized before the parsed response is cast to `DockerContainerInspect`. Consequently, the normal raw-inspect mount list takes the absent-list path and the recreated sandbox omits its structured tmpfs and volume mounts.
• Impact: A GPU recreation can replace a sandbox with one missing required mounts. Because clone arguments are assembled before lifecycle mutation but the ordinary raw-inspect representation is silently ignored rather than rejected, the original can be stopped and renamed before the mount-loss becomes apparent.
• Fix: Model the actual raw `docker inspect` mount records at their returned location (including their destination field), serialize that source, and keep unsupported mount forms fail-closed before container mutation.
• Verification: Inspect a real or documented raw `docker inspect` JSON response containing a tmpfs or named volume and trace it through `parseDockerInspectJson` into `buildDockerGpuCloneRunArgs`; confirm that the current `HostConfig.Mounts` loop receives no records.
• Test coverage: Add clone and recreation regression tests using raw-inspect-shaped top-level tmpfs and volume records (with Docker's destination field), asserting their run flags are emitted and that unsupported records fail before stop/rename.
• Evidence: `dockerStructuredMountArgs` iterates only `inspect.HostConfig?.Mounts ?? []` at `src/lib/onboard/docker-gpu-patch-clone.ts:215`. The new type places `Mounts` under `HostConfig` and calls its target `Target` (`src/lib/onboard/docker-gpu-patch-types.ts:191-210`). `parseDockerInspectJson` returns the raw parsed inspect object by type cast, with no mount-location or destination-field normalization (`src/lib/onboard/docker-gpu-patch-clone.ts`). Clone arguments are built before `dockerStop` and `dockerRename` in `src/lib/onboard/docker-gpu-patch-recreate.ts:252`. The added fixture/tests populate the same `HostConfig.Mounts`/`Target` assumed shape, so they do not exercise a raw inspect mount response.

Workflow run details

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

[jyaunches]

Reviewed PRA-1 against the actual Docker Engine inspect contract and pinned OpenShell driver. No code change is needed: Docker container InspectResponse includes HostConfig, and HostConfig includes the original structured Mounts array. The top-level Mounts array is a separate runtime MountPoint summary; it uses Destination but drops the structured TmpfsOptions and VolumeOptions needed for exact recreation. OpenShell creates these mounts through HostConfig.mounts, and parseDockerInspectJson retains that raw field. The existing fixture intentionally models that create-time inspect field, while the live E2E uses top-level .Mounts only to verify the resulting runtime mount. Switching reconstruction to top-level Mounts would lose noexec, tmpfs size/mode, and volume options.

[cv]

lgtm when ready