fix(images): normalize managed runtime bundle metadata

[sandl99]

Summary

Normalize the owner and mode of reviewed runtime bundles while Docker copies them into scratch stages, so source file modes cannot make final-image runtime files writable. Add bounded assertion diagnostics that identify the failed contract and path when image assembly rejects runtime metadata.

Related Issue

Fixes #8665

Changes

• Copy the reviewed MCP discovery and managed-startup bundles as root:root with mode 0444 in the OpenClaw, Hermes, and Deep Agents Code image stages.
• Report the exact managed-runtime assertion and bounded file metadata when discovery, ownership, mode, or runtime-directory validation fails.
• Make the real PR managed-image builds start from mode-0664 reviewed bundle files before final contract and managed-startup validation.
• Extend image contract tests to protect the normalized copy metadata, diagnostic behavior, and producer-equivalent workflow coverage.

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 changes internal image-build metadata normalization, CI coverage, and diagnostics, not a public command, configuration, default, workflow, or supported behavior.
• 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 CLI reviewed all security-rubric categories. The change adds no dependency, secret, credential, authorization, input, or cryptographic surface; reviewed artifacts remain root-owned and read-only, and diagnostics expose only fixed runtime paths and numeric metadata.
• 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: Internal managed-image build metadata, CI coverage, and assertion diagnostics only; no public documentation claim changes.
• Agent: Codex CLI

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 — 69 CLI tests, 166 targeted integration tests, and 8 focused image-contract tests 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)

Additional validation:

• npm run source-shape:check
• npm run checks:repository
• hadolint Dockerfile agents/hermes/Dockerfile agents/langchain-deepagents-code/Dockerfile
• A bounded Docker reproduction with mode-0664 input failed the existing discovery-tree contract before this change and passed with output mode 0444 after it.

---

Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Security & Reliability

  • Runtime bundles and startup artifacts are now root-owned and read-only in final images.
  • Image validation checks artifact types, permissions, ownership, symlinks, runtime directories, and discovery behavior.
  • Failures provide specific diagnostics for runtime or discovery issues.
  • Build workflows fail fast when reviewed runtime inputs are invalid or unexpectedly writable.

• Tests

  • Updated image layout and contract checks for strengthened runtime permissions and validation.
  • Added coverage for writable discovery-tree artifacts, runtime bundle requirements, and symlinked runtime directories.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The Dockerfiles now copy managed runtime artifacts as root-owned, read-only files. Final-image checks report individual failures for discovery, artifact metadata, permissions, and runtime-directory creation. Workflow and contract tests validate build preparation and Dockerfile instructions.

Changes

Managed runtime image contract

Layer / File(s)	Summary
Prepare and assemble runtime artifacts .github/workflows/managed-images.yaml, test/mcp-tool-discovery-image-contract.test.ts, Dockerfile, agents/hermes/Dockerfile, agents/langchain-deepagents-code/Dockerfile	The workflow validates reviewed files and sets mode 0664 before builds. Dockerfiles copy runtime artifacts as root-owned files with mode 0444.
Make final-image validation explicit Dockerfile, agents/hermes/Dockerfile, agents/langchain-deepagents-code/Dockerfile, test/support/managed-bootstrap-image-contract.ts, .github/workflows/managed-images.yaml	Managed runtime checks report discovery, contract, tree, artifact, ownership, mode, and runtime-directory failures through managed_runtime_assertion_failed. The workflow adds a symlink rejection probe.
Update image layout and workflow contracts test/hermes-final-image-layout.test.ts, test/langchain-deepagents-code-image.test.ts, test/openclaw-final-image-layout.test.ts, test/managed-image-publication-workflow.test.ts, ci/source-shape-test-budget.json	Tests match standalone commands, explicit failure assertions, root-owned read-only runtime copies, workflow probe ordering, and the security source-shape exception.

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

Sequence Diagram(s)

sequenceDiagram
  participant Workflow
  participant DockerBuild
  participant DiscoveryRuntime
  participant RuntimeContract
  participant AssertionReporter
  Workflow->>Workflow: Validate and prepare reviewed files
  Workflow->>DockerBuild: Start managed-image build
  DockerBuild->>DiscoveryRuntime: Execute discovery contract
  DiscoveryRuntime->>RuntimeContract: Return contract output
  DockerBuild->>RuntimeContract: Validate artifact and directory metadata
  RuntimeContract->>AssertionReporter: Report failed sub-check
  AssertionReporter-->>DockerBuild: Fail image build

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8642: Adds the managed-startup ownership and mode assertions extended by this change.
• NVIDIA/NemoClaw#8673: Adds related managed-runtime assertion diagnostics in the same validation workflow.
• NVIDIA/NemoClaw#8651: Modifies reviewed runtime bundle staging and image integration checks.

Suggested labels: area: packaging, bug-fix, area: security

Suggested reviewers: apurvvkumaria, jyaunches, prekshivyas, cv

🚥 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 primary change: normalizing managed runtime bundle metadata during image assembly.
Linked Issues check	✅ Passed	The changes address issue #8665 by normalizing runtime metadata, adding fail-closed diagnostics, preserving security checks, and expanding producer-equivalent regression coverage.
Out of Scope Changes check	✅ Passed	The Dockerfile, workflow, test, and source-shape changes directly support the linked issue objectives and contain no unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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/deep-code-runtime-contract

---

_{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 1b7b987 in the fix/deep-code-runtim... branch remains at 96%, unchanged from commit 286d3a1 in the main branch.

---

_{Updated August 10, 2026 18:22 UTC}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@Dockerfile`:
- Around line 1535-1536: Reject symlinked /run/nemoclaw paths by updating the
runtime-directory setup in Dockerfile, agents/hermes/Dockerfile, and
agents/langchain-deepagents-code/Dockerfile: after install -d, require it to be
a directory, not a symlink, and have exact 0:0:755 ownership and permissions,
invoking managed_runtime_assertion_failed on any mismatch. Update the
corresponding contract/layout tests in
test/support/managed-bootstrap-image-contract.ts,
test/langchain-deepagents-code-image.test.ts,
test/openclaw-final-image-layout.test.ts, and
test/hermes-final-image-layout.test.ts to assert these checks and add a symlink
negative-path case.

🪄 Autofix

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: d14b2d4c-a378-43ef-93b8-b3c58ead57bc

📥 Commits

Reviewing files that changed from the base of the PR and between 04e28aa and 863f8d2.

📒 Files selected for processing (8)

• Dockerfile
• agents/hermes/Dockerfile
• agents/langchain-deepagents-code/Dockerfile
• test/hermes-final-image-layout.test.ts
• test/langchain-deepagents-code-image.test.ts
• test/mcp-tool-discovery-image-contract.test.ts
• test/openclaw-final-image-layout.test.ts
• test/support/managed-bootstrap-image-contract.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 · medium 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.

6 terminology differences from the second opinion

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

• runtime directory at Dockerfile:1534: selected only by the second-opinion lane as justified.
• runtime-directory-create at Dockerfile:1534: selected only by the second-opinion lane as justified.
• managed-bootstrap-regular-file at Dockerfile:1528: selected only by the second-opinion lane as justified.
• runtime-directory-metadata at Dockerfile:1537: selected only by the second-opinion lane as justified.
• managed-bootstrap-metadata at Dockerfile:1530: selected only by the second-opinion lane as justified.
• runtime-directory-non-symlink at Dockerfile:1536: selected only by the second-opinion lane as justified.

1 additional E2E selection from the second opinion

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

• staging-brev-launchable: 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 — reviewed runtime bundle at .github/workflows/managed-images.yaml:97: Keep the established term for the reviewed image-build inputs.
• established — exact PR image at ci/source-shape-test-budget.json:291: Keep the established term for the commit-bound candidate image.

E2E guidance

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

Recommended E2E: cloud-onboard, full-e2e, hermes-e2e, hermes-inference-switch, managed-image-multiarch-startup, security-posture, ubuntu-repo-cloud-langchain-deepagents-code

Workflow run details

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

[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 @.github/workflows/managed-images.yaml:
- Around line 97-105: Update the “Make reviewed runtime bundle files
group-writable” step to validate every listed artifact path with `[[ -f "$path"
&& ! -L "$path" ]]` before invoking `chmod 0664`. Reject the workflow when any
path is missing, non-regular, or symlinked, while preserving the existing mode
change for valid runtime bundle files.

In `@test/mcp-tool-discovery-image-contract.test.ts`:
- Around line 123-126: Strengthen the assertions in the test around the
workflow’s intended job and run block so they inspect the complete chmod command
rather than independent text occurrences. Bind each reviewedRuntimeBundleFiles
path to the chmod 0664 invocation, and assert the exact command operands so
comments, echo statements, or unrelated commands cannot satisfy the test.

🪄 Autofix

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: cdc05730-cc01-485a-8eea-93ad94789ddb

📥 Commits

Reviewing files that changed from the base of the PR and between 863f8d2 and dd3d98c.

📒 Files selected for processing (6)

• .github/workflows/managed-images.yaml
• Dockerfile
• agents/hermes/Dockerfile
• agents/langchain-deepagents-code/Dockerfile
• ci/source-shape-test-budget.json
• test/mcp-tool-discovery-image-contract.test.ts

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

• agents/hermes/Dockerfile
• Dockerfile
• agents/langchain-deepagents-code/Dockerfile

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@test/support/managed-bootstrap-image-contract.ts`:
- Around line 70-73: Add an image-contract test alongside the existing
runtime-directory checks that builds the image with invalid /run/nemoclaw state,
such as a symlink or incorrect ownership/mode, and asserts the build fails with
the corresponding managed_runtime_assertion_failed diagnostic. Keep source-text
checks only as supplemental coverage, and do not rely solely on the direct
runDiagnostic() formatter test.

🪄 Autofix

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: 032db256-89f4-4003-82e0-bd64ce0cf45c

📥 Commits

Reviewing files that changed from the base of the PR and between dd3d98c and 6e4d1ec.

📒 Files selected for processing (9)

• .github/workflows/managed-images.yaml
• Dockerfile
• agents/hermes/Dockerfile
• agents/langchain-deepagents-code/Dockerfile
• test/hermes-final-image-layout.test.ts
• test/langchain-deepagents-code-image.test.ts
• test/mcp-tool-discovery-image-contract.test.ts
• test/openclaw-final-image-layout.test.ts
• test/support/managed-bootstrap-image-contract.ts

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

• .github/workflows/managed-images.yaml
• test/hermes-final-image-layout.test.ts
• test/openclaw-final-image-layout.test.ts
• Dockerfile
• agents/hermes/Dockerfile
• agents/langchain-deepagents-code/Dockerfile
• test/langchain-deepagents-code-image.test.ts

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/mcp-tool-discovery-image-contract.test.ts (1)

183-207: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Exercise each reviewed bundle file through the workflow.

Line 184 locks the full shell text to expectedRun. Lines 204-207 only replace reviewedRuntimeBundleFiles[3].

Iterate every reviewedRuntimeBundleFiles entry for each invalid preparer. Assert that the executed workflow step fails and reports the affected path. Keep the valid execution assertion for all files. This removes the source-text dependency and detects a regression that skips validation for any earlier bundle file.

As per path instructions, “Prefer observable outcomes through the public boundary over source-text ... assertions.”

🤖 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 `@test/mcp-tool-discovery-image-contract.test.ts` around lines 183 - 207,
Update the test around the metadataStep workflow to stop depending on the exact
shell source in expectedRun and instead validate observable execution outcomes.
For each invalidReviewedBundlePreparers entry, iterate every
reviewedRuntimeBundleFiles path, remove and corrupt that file as needed, execute
metadataStepRun, and assert failure with stderr identifying the affected path;
retain successful execution and permission assertions for all files in the valid
fixture.

Source: Path instructions

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

Outside diff comments:
In `@test/mcp-tool-discovery-image-contract.test.ts`:
- Around line 183-207: Update the test around the metadataStep workflow to stop
depending on the exact shell source in expectedRun and instead validate
observable execution outcomes. For each invalidReviewedBundlePreparers entry,
iterate every reviewedRuntimeBundleFiles path, remove and corrupt that file as
needed, execute metadataStepRun, and assert failure with stderr identifying the
affected path; retain successful execution and permission assertions for all
files in the valid fixture.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 12cc012f-24ac-4566-8f5a-93f1206dc21e

📥 Commits

Reviewing files that changed from the base of the PR and between 6e4d1ec and bdf2902.

📒 Files selected for processing (1)

• test/mcp-tool-discovery-image-contract.test.ts

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.