fix(images): report managed runtime assertion failures

[jyaunches]

Summary

PR #8642 restored the managed startup runtime file invariants, but a failed Docker assertion reported only the shell exit code. This change reports the failed invariant and bounded file metadata before preserving the same nonzero build result.

Changes

• Report the invariant name, fixed artifact path, UID, GID, file type, mode, and symlink state for each managed startup runtime assertion in the OpenClaw, Hermes, and LangChain Deep Agents Code images.
• Keep the regular-file, non-symlink, root:root, and 0444 checks fail-closed.
• Extend the shared image contract to require every guarded assertion and execute missing-file and symlink diagnostic paths for all three images.

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 failure output. It does not change a command, configuration, runtime contract, or documented workflow.
• 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 reviewed commit b18ad31e7 against all nine security categories. The applicable error-handling, security-testing, and system-security checks passed. The diagnostic emits only a fixed path and numeric file metadata, and every failed assertion still exits nonzero.
• 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: Commit b18ad31e7 changes only internal managed-image build diagnostics and their tests. It changes no command, configuration, default, runtime behavior, or documented workflow. The review found no terminology, structure, or changed-text findings.
• 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 --project integration test/openclaw-final-image-layout.test.ts test/hermes-final-image-layout.test.ts test/langchain-deepagents-code-image.test.ts passed 36 tests in 3 files. hadolint and npm run source-shape:check also 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

[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: 67814415-9383-4feb-86fc-084f87963c20

📥 Commits

Reviewing files that changed from the base of the PR and between 352680c and b18ad31.

📒 Files selected for processing (4)

• Dockerfile
• agents/hermes/Dockerfile
• agents/langchain-deepagents-code/Dockerfile
• test/support/managed-bootstrap-image-contract.ts

---

📝 Walkthrough

Walkthrough

The managed startup runtime checks now report detailed diagnostics before exiting. The bootstrap image contract tests validate missing-file and symlink failures, metadata checks, and fail-closed output across the native and agent Dockerfiles.

Changes

Managed runtime diagnostics

Layer / File(s)	Summary
Runtime assertion failure handling Dockerfile, agents/hermes/Dockerfile, agents/langchain-deepagents-code/Dockerfile	Each Dockerfile adds a failure handler that reports the assertion, path, ownership, type, mode, and symlink state. Runtime checks route missing-file, symlink, ownership, permission, and metadata failures through the handler while preserving the required runtime metadata.
Diagnostic contract validation test/support/managed-bootstrap-image-contract.ts	The contract test parses the runtime assertion, checks required metadata validations, executes missing-file and symlink fixtures, verifies exact fail-closed diagnostics, and invokes the validation from the native image contract.

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

Possibly related PRs

• NVIDIA/NemoClaw#8642: Modifies the same managed-startup runtime metadata checks.
• NVIDIA/NemoClaw#8658: Shares managed Hermes runtime artifact metadata and permission validation.
• NVIDIA/NemoClaw#8668: Shares managed-startup symlink validation and fail-closed diagnostics.

Suggested labels: area: packaging, bug-fix, v0.0.106

Suggested reviewers: cv, ericksoa, prekshivyas

🚥 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 and concisely describes the main change: reporting managed runtime assertion failures.
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/managed-image-assertion-diagnostics

---

_{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 b18ad31 in the codex/managed-image-... branch remains at 96%, unchanged from commit 352680c in the main branch.

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

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 terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

2 terminology differences from the second opinion

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

• managed image assertion at Dockerfile:1500: primary classified it as justified; the second opinion classified it as define.
• owner-root-root at Dockerfile:1510: selected only by the second-opinion lane as define.

2 additional E2E selections from the second opinion

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

• openclaw-inference-switch: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• openclaw-plugin-runtime-exdev: 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.

1 semantic terminology decision

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

• justified — managed image assertion at Dockerfile:1500: Retain `managed image assertion` for these diagnostic messages.

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

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Test the stat-failure diagnostic fallback

• Location: test/support/managed-bootstrap-image-contract.ts:67
• Category: tests
• Problem: The shared contract executes missing-file and symlink cases, but it does not execute the helper path that handles a failed stat call for an existing artifact.
• Impact: A future edit can suppress or alter the diagnostic for an existing artifact when metadata collection fails, leaving the build failure without the intended bounded context.
• Recommendation: Add a contract case that makes stat fail for an existing regular-file fixture. Assert exit status 1, empty stdout, and the unavailable metadata diagnostic.
• Verification: Inspect the shared contract test for a case that invokes managed_runtime_assertion_failed on an existing non-symlink fixture while stat exits nonzero.
• Test coverage: Run the extracted helper with an existing regular-file fixture and a stat stub that exits nonzero; assert the stderr record contains type=unavailable, mode=unavailable, symlink=no, and exit status 1.
• Evidence: test/support/managed-bootstrap-image-contract.ts:67-91 defines the diagnostic runner and substitutes stat output. test/support/managed-bootstrap-image-contract.ts:94-114 covers only missing and symlink artifacts. Dockerfile:1492-1493, agents/hermes/Dockerfile:354-355, and agents/langchain-deepagents-code/Dockerfile:104-105 map stat failures to unavailable metadata.

Workflow run details

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