fix(onboard): reject stale Deep Agents base inventories

[sandl99]

Summary

Deep Agents Code onboarding now rejects a release base image that has the expected distribution version but an obsolete security package inventory. The resolver detects the incompatibility before completed-image construction and retains its existing release-refresh and local-build fallback behavior.

Related Issue

Fixes #7809

Changes

• Require Deep Agents Code base images to match both the manifest distribution version and the immutable security package inventory.
• Move the existing inventory probe to a shared base-image module because OpenClaw and Deep Agents Code must enforce one inventory definition. A second direct probe would let the two compatibility gates drift; deep-agents-code-base-image.test.ts protects the shared DCode consumer.
• Add regression coverage that rejects the stale v0.0.96 inventory even when deepagents-code==0.1.34.
• Preserve the existing resolver contract that refreshes the selected release once, builds the current base locally when required, and does not substitute mutable latest.

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: The command, configuration, recovery, and resolver fallback contracts do not change. Existing docs already describe incompatible-image rejection and compatible local builds.
• 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: Codex Desktop completed the repository's nine-category security review on exact PR SHA 4fafec7ef; all categories passed with no findings. The probe uses constant shell input and runs without network access, Linux capabilities, writable filesystem access, or privilege escalation.
• 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: no-docs-needed
• Evidence: Existing Deep Agents and base-image documentation already covers incompatible-image rejection, compatible local builds, exact override validation, and fail-closed behavior. No command, flag, configuration, schema, workflow, or recovery action changes.
• 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 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/agent/deep-agents-code-base-image.test.ts src/lib/agent/base-image.test.ts src/lib/onboard/base-image.test.ts passed 31 tests; npx vitest run --project integration test/dcode-base-image-workflow.test.ts passed 4 tests; npm run test:changed passed 289 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — Not run; focused CLI, integration, changed-test, type-check, and normal hook evidence cover this scoped compatibility validation.
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Strengthened base-image validation to require an up-to-date immutable security package inventory.
  • Prevented otherwise compatible images from being accepted when their security inventory is outdated or invalid.
  • Improved validation details to clearly indicate both version and security-inventory requirements.

• Tests

  • Added regression coverage for rejecting images with stale security inventories.
  • Expanded workflow and compatibility tests for the enhanced validation checks.

[coderabbitai]

📝 Walkthrough

Walkthrough

Deep Agents Code base-image validation now requires both the expected package version and immutable security package inventory. The inventory probe is shared with OpenClaw, and tests cover stale inventory rejection and updated validation descriptions.

Changes

Base image security inventory validation

Layer / File(s)	Summary
Shared inventory probe and OpenClaw wiring src/lib/sandbox-base-image/security-inventory.ts, src/lib/onboard/base-image.ts	A locked-down Docker probe validates the inventory file’s ownership, permissions, symlink status, and contents; OpenClaw re-exports the shared validator.
Deep Agents Code validation and regression coverage src/lib/agent/deep-agents-code-base-image.ts, src/lib/agent/*test.ts, test/dcode-base-image-workflow.test.ts	Deep Agents Code validation requires the expected version and inventory marker, with tests covering stale inventories and updated descriptions.

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

Possibly related PRs

• NVIDIA/NemoClaw#7667: Updates security package contents that the immutable inventory validation checks.
• NVIDIA/NemoClaw#7679: Changes the underlying security inventory used by the shared validation probe.

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

Suggested reviewers: cv, prekshivyas

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds the required inventory check, shares the inventory probe, and adds regression coverage for the stale base.
Out of Scope Changes check	✅ Passed	The changed files all support the inventory-validation fix and regression coverage; no unrelated scope stands out.
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 summarizes the main change: rejecting stale Deep Agents base inventories during onboarding validation.

✨ 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/7809-dcode-base-security-inventory

---

_{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 4fafec7 in the fix/7809-dcode-base-... branch remains at 96%, unchanged from commit 125ca30 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 4fafec7 in the fix/7809-dcode-base-... branch remains at 81%, unchanged from commit cf34b72 in the main branch.

Show a code coverage summary of the most impacted files.

File	main cf34b72	fix/7809-dcode-base-... 4fafec7	+/-
src/lib/onboard/base-image.ts	86%	80%	-6%
src/lib/onboard...etson-groups.ts	100%	96%	-4%
src/lib/agent/d...e-base-image.ts	86%	86%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/sandbox...ty-inventory.ts	0%	100%	+100%

---

_{Updated July 29, 2026 09:31 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 E2E selections differ; severity counts match.

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: cloud-inference, security-posture, full-e2e, hermes-e2e, onboard-repair, onboard-resume, cloud-onboard

Workflow run details

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