fix(onboard): persist DCode Docker startup limits

[jyaunches]

Summary

Deep Agents Code onboarding on the OpenShell 0.0.85 Docker driver could report success while the managed container retained OPENSHELL_SANDBOX_COMMAND=sleep infinity, leaving no nemoclaw-dcode-entrypoint process after a gateway restart. This change uses the existing restart-safe container recreation for DCode and applies its exact resource-limit contract at Docker container creation time.

Changes

• Persist the DCode nemoclaw-start command for Docker-driver onboarding, matching the existing Hermes restart-safe handoff.
• Preserve inspected Docker ulimits while overriding DCode's required nproc=512:512 and nofile=65536:65536 limits.
• Validate required ulimit names and values before any container mutation.
• Add regression coverage across agent selection, no-GPU orchestration, clone argument rendering, rollback-safe validation, and startup-command recreation.
• Document managed DCode's container-level limits and restart behavior.

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: local nine-category security review passed; required ulimits come from agent-owned constants, names and values fail closed before mutation, Docker arguments remain argv-safe, no dependencies or credentials change, and existing rollback behavior is preserved.
• 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 ...: 72 passed; npm run test:changed: 1,066 passed; npm run typecheck:cli: passed
• Applicable broad gate passed — scoped onboarding/Docker recreation change; affected-test sweep and targeted tests passed, live Docker/Brev validation remains with CI
• 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) — passed with 0 errors; Fern retained 2 existing warnings
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Release-blocking reproduction: https://github.com/NVIDIA/NemoClaw/actions/runs/29619226305

---

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

Summary by CodeRabbit

• New Features
  • Added fail-closed Docker nproc/nofile hard limits for supported sandbox/container recreation flows.
  • Startup-command patching now consistently derives whether limits are persisted and applies required ulimits when applicable.
  • Container cloning preserves existing ulimit settings while overriding to the required nproc/nofile values.
• Documentation
  • Updated security best-practices guidance for operators to set hard ulimit limits when launching containers outside the managed onboarding path.
• Tests
  • Added/updated coverage for --ulimit injection, restart-safe behavior, ulimit preservation/override, and malformed ulimit name rejection.

[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: f7295d53-626a-41e0-94e3-3b5ae13882da

📥 Commits

Reviewing files that changed from the base of the PR and between 8cd88af and 035279e.

📒 Files selected for processing (4)

• src/lib/onboard/sandbox-gpu-create-flow.test.ts
• src/lib/onboard/sandbox-gpu-create-run-attempt.ts
• test/onboard-prepared-build-context.test.ts
• test/onboard-terminal-dashboard.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard/sandbox-gpu-create-run-attempt.ts

---

📝 Walkthrough

Walkthrough

The onboarding flow centralizes Docker startup policy, propagates required nproc and nofile limits through sandbox recreation, validates and emits Docker --ulimit arguments, and documents restart-safe enforcement.

Changes

Docker ulimit onboarding

Layer / File(s)	Summary
Startup policy resolution src/lib/onboard/docker-startup-command-agent.ts, src/lib/onboard/sandbox-create-step.ts, src/lib/onboard.ts, docs/security/best-practices.mdx, src/lib/onboard/sandbox-create-step.test.ts	DCode startup persistence and fixed Docker limits are resolved centrally and passed into sandbox creation; tests and security guidance cover the resulting behavior.
Ulimit contract propagation src/lib/onboard/docker-gpu-patch-types.ts, src/lib/onboard/docker-gpu-patch.ts, src/lib/onboard/docker-gpu-sandbox-create.ts, src/lib/onboard/docker-startup-command-patch.ts, src/lib/onboard/docker-startup-command-sandbox-create.ts, src/lib/onboard/docker-gpu-patch-recreate.ts, src/lib/onboard/sandbox-gpu-create-flow.ts, src/lib/onboard/sandbox-gpu-create-run-attempt.ts, src/lib/onboard/*test.ts	requiredUlimits is added to Docker and sandbox contracts and threaded through GPU and startup-command recreation paths.
Clone ulimit validation and emission src/lib/onboard/docker-gpu-patch-clone.ts, src/lib/onboard/docker-gpu-patch-recreate.ts, src/lib/onboard/docker-gpu-patch-clone.test.ts, src/lib/onboard/docker-gpu-patch-validation.test.ts	Required limits are validated, merged with inspected limits, emitted as Docker arguments, and tested for override and early rejection behavior.
Embedded test harness wiring test/onboard-prepared-build-context.test.ts, test/onboard-terminal-dashboard.test.ts	Embedded onboarding scenarios stub GPU sandbox patch creation and retain sandbox-name verification.

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

Sequence Diagram(s)

sequenceDiagram
  participant SandboxCreateStep
  participant StartupPolicy
  participant SandboxRecreation
  participant DockerClone
  SandboxCreateStep->>StartupPolicy: agent and gateway configuration
  StartupPolicy-->>SandboxCreateStep: persistence policy and required ulimits
  SandboxCreateStep->>SandboxRecreation: sandbox patch options
  SandboxRecreation->>DockerClone: validated requiredUlimits
  DockerClone-->>SandboxRecreation: Docker run arguments with --ulimit flags

Loading

Suggested labels: bug-fix, area: onboarding, area: sandbox, area: security, v0.0.74

Suggested reviewers: ericksoa, cv, apurvvkumaria

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% 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 is concise and accurately summarizes the main onboarding change around persisting DCode Docker startup limits.
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 fix/dcode-docker-startup-limits

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

---

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

[coderabbitai]

Actionable comments posted: 2

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

Inline comments:
In `@src/lib/onboard/docker-gpu-patch-clone.test.ts`:
- Line 76: Update the test title in the preserves inspected ulimits test case to
append the required local tracking-reference suffix in the final (`#1234`) format,
using the appropriate issue number. Keep the existing behavior-oriented wording
unchanged.

In `@src/lib/onboard/docker-gpu-patch-validation.test.ts`:
- Around line 189-220: Strengthen the malformed required-ulimits test around
recreateOpenShellDockerSandboxWithGpu by asserting dockerRun is not called
before validation rejects the input. Keep the existing dockerStop and
dockerRunDetached assertions, and retain the malformed ulimit setup and expected
error.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 21e78c2b-032f-43e2-851e-271a4410bf47

📥 Commits

Reviewing files that changed from the base of the PR and between 54b49c8 and a41b721.

📒 Files selected for processing (18)

• docs/security/best-practices.mdx
• src/lib/onboard.ts
• src/lib/onboard/docker-gpu-patch-clone.test.ts
• src/lib/onboard/docker-gpu-patch-clone.ts
• src/lib/onboard/docker-gpu-patch-recreate.ts
• src/lib/onboard/docker-gpu-patch-types.ts
• src/lib/onboard/docker-gpu-patch-validation.test.ts
• src/lib/onboard/docker-gpu-patch.ts
• src/lib/onboard/docker-gpu-sandbox-create.ts
• src/lib/onboard/docker-startup-command-agent.ts
• src/lib/onboard/docker-startup-command-patch.ts
• src/lib/onboard/docker-startup-command-sandbox-create.test.ts
• src/lib/onboard/docker-startup-command-sandbox-create.ts
• src/lib/onboard/sandbox-create-step.test.ts
• src/lib/onboard/sandbox-create-step.ts
• src/lib/onboard/sandbox-gpu-create-flow.test.ts
• src/lib/onboard/sandbox-gpu-create-flow.ts
• src/lib/onboard/sandbox-gpu-create-run-attempt.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 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 the same number of blockers, 1 fewer warning, 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

3 optional E2E recommendations

• sandbox-rlimits-connect
• gpu-e2e
• ubuntu-repo-cloud-langchain-deepagents-code

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover rollback of a limit-bearing startup recreation failure

• Location: src/lib/onboard/docker-startup-command-sandbox-create.test.ts:74
• Category: tests
• Problem: The new startup-command test asserts that required ulimits are included in a successful detached clone, and the existing rollback test uses a mocked startup recreator rather than the new required-ulimit path. There is no checked-in regression that fails the detached Docker run after required limits have been propagated and proves that the original backup is restored.
• Impact: A failure caused by the newly added Docker ulimit flags could leave the managed DCode sandbox stopped, renamed, or accompanied by a stale replacement instead of converging back to the original container.
• Recommendation: Add a recreation-level test with requiredUlimits that makes dockerRunDetached fail, then assert rollback restores and starts the original container under its original name and does not retain the failed replacement.
• Verification: Inspect the startup-command recreation tests and docker-gpu patch rollback tests for a case combining requiredUlimits with a nonzero dockerRunDetached result and assertions on restored name/running state.
• Test coverage: A unit test for required nproc/nofile startup recreation where detached docker run fails and the original container is renamed back and restarted successfully.
• Evidence: src/lib/onboard/docker-startup-command-sandbox-create.test.ts covers successful required-ulimit argument emission at line 74 and mocked supervisor-reconnect rollback later in the file. src/lib/onboard/docker-gpu-sandbox-create.ts forwards requiredUlimits into the recreate mutation path before the clone is stopped/renamed. The tests-stage analysis found no failed-detached-run rollback case that exercises requiredUlimits.

Workflow run details

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