test(images): harden legacy Docker copy contracts

[apurvvkumaria]

Summary

Hardens the Docker Engine compatibility regression tests added in #7622. The tests now reject BuildKit-only RUN --mount instructions across case, whitespace, line-continuation, and preceding RUN-flag variants, and pin every approved scratch-payload COPY source and destination for both OpenClaw and Hermes.

Related Issue

Follow-up to #7622.
Relates to #7611.

Changes

• Parse logical Dockerfile instructions before checking for forbidden BuildKit mount syntax.
• Detect --mount when it follows valid preceding RUN flags such as --network or --security.
• Assert the exact approved COPY boundaries for every OpenClaw scratch payload stage.
• Assert the exact approved COPY boundaries for every Hermes scratch payload stage.

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: Test-only hardening; Dockerfiles, runtime behavior, configuration, and supported platforms are unchanged.
• 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 exact-head security review PASS across all nine categories with no findings at candidate 354e7de; diff fingerprint fcc6d7ec877ec1402b4397e2100cc80d647e883bdc621cb0b14ca647e3795606. The diff changes only regression tests and does not change runtime or final-image bytes.
• 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: the exact candidate 354e7de changes only the OpenClaw and Hermes final-image regression tests. It strengthens detection of forbidden BuildKit RUN --mount syntax after preceding RUN flags and pins approved scratch-payload COPY boundaries. Existing Docker Engine compatibility documentation remains accurate; production Dockerfiles, runtime behavior, configuration, supported platforms, and final-image contents do not change.
• Agent: Codex Desktop documentation writer subagent

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 — command/result or justification: npx vitest run --project integration test/hermes-final-image-layout.test.ts test/openclaw-final-image-layout.test.ts — 15/15 passed at exact head 354e7de4.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable to this narrow test-only contract hardening; repository checks, source-shape budget, test-size budget, Biome, secret scan, CLI typecheck, and CLI build passed.
• 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Tests
  • Strengthened validation of final Docker image layouts.
  • Added detection to prevent unsupported BuildKit RUN --mount usage, including handling line continuations.
  • Improved verification of payload stages by asserting the exact COPY instruction lines and their order (not just counts).

[coderabbitai]

📝 Walkthrough

Walkthrough

The Hermes and OpenClaw final-image layout tests now detect Dockerfile RUN --mount usage and verify exact ordered COPY contents for named scratch payload stages.

Changes

Final image layout validation

Layer / File(s)	Summary
BuildKit mount detection test/hermes-final-image-layout.test.ts, test/openclaw-final-image-layout.test.ts	Adds Dockerfile continuation normalization, RUN option-prefix mount detection, and parameterized coverage for recognized and non-matching forms.
Payload-stage layout assertions test/hermes-final-image-layout.test.ts, test/openclaw-final-image-layout.test.ts	Rejects BuildKit mounts and replaces per-stage COPY count checks with exact ordered instruction comparisons for scratch payload stages.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: integration: hermes, area: packaging, platform: container

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the test-only change hardening Docker copy contracts and BuildKit checks.

✨ 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/7611-docker-engine-contracts

---

_{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 354e7de in the codex/7611-docker-en... branch remains at 96%, unchanged from commit c3ab052 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 354e7de in the codex/7611-docker-en... branch remains at 81%, unchanged from commit c3ab052 in the main branch.

Show a code coverage summary of the most impacted files.

File	main c3ab052	codex/7611-docker-en... 354e7de	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/sandbox...rce-identity.ts	88%	88%	0%

---

_{Updated July 28, 2026 16:50 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 `@test/hermes-final-image-layout.test.ts`:
- Around line 106-110: The hasBuildKitRunMount helper in
test/hermes-final-image-layout.test.ts (lines 106-110) and its counterpart in
test/openclaw-final-image-layout.test.ts (lines 17-21) must detect --mount
anywhere in the RUN option prefix, including after flags such as --network=none;
update the matching logic to parse or accept preceding RUN flags, and add
regression coverage for this layout in both test files.

🪄 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: aec4e65a-451a-478b-9978-aba1d8e6f567

📥 Commits

Reviewing files that changed from the base of the PR and between a47ddd8 and 6017803.

📒 Files selected for processing (2)

• test/hermes-final-image-layout.test.ts
• test/openclaw-final-image-layout.test.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 · 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: None

Workflow run details

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

[prekshivyas]

Blocking review at exact head 6017803eee1341edbe29890d79432e078a14abca:

hasBuildKitRunMount only recognizes --mount when it is the first option after RUN. Docker permits other RUN options first, so RUN --network=none --mount=type=cache ... and a continued RUN --security=sandbox \ --mount=type=secret ... both return false. That lets the legacy-Docker compatibility contract pass while BuildKit-only syntax is present. Update the helper in both test/hermes-final-image-layout.test.ts:106 and test/openclaw-final-image-layout.test.ts:17 to parse the RUN option prefix (or otherwise detect --mount after preceding RUN flags), and add regression coverage for same-line and line-continuation forms with a preceding flag.

The existing targeted suite passes 22/22, but it does not exercise these forms; I reproduced both false negatives directly. Contributor compliance passes (DCO present; commit Verified), E2E evidence is green, and no runtime/security surface changed. The branch is also behind current main and must be refreshed before approval. The Terra advisor failure is an incomplete automated analysis with zero published findings, not a product-test failure.

[prekshivyas]

Re-review at exact head 354e7de457f249cf82a2ff6a1317420b07b64fae:

The prior code blocker is resolved. hasBuildKitRunMount now scans the full RUN option prefix, catches --mount after preceding flags on same-line and continued instructions, and does not treat a shell-command argument as a BuildKit option. The exact ordered COPY assertions also match the reviewed scratch payload stages. I found no remaining code findings.

Security review: PASS across all nine categories (secrets, input validation, authentication/authorization, dependencies, error handling/logging, cryptography, configuration, security testing, and system security). This is test-only hardening; it adds no dependency, runtime, credential, policy, or image-byte change.

Verification:

• focused integration tests: 2 files, 15/15 tests passed
• source-shape contract check: passed with zero invalid exceptions
• git diff --check: passed
• current required CI and exact-head E2E: green; the cancelled E2E run was superseded by the successful current run
• DCO is present and all eight commits are GitHub Verified

One repository-process blocker remains: the PR body records the documentation-writer review and hidden docs-review-head-sha at cad0523c3, but the current head is 354e7de4. AGENTS.md requires rerunning the documentation-writer review and refreshing its evidence/hidden head SHA after any commit changes the PR head. Please refresh that exact-head receipt. The PR body's sensitive-path receipt is also stale, but this review supplies the current exact-head nine-category security PASS.

Once the documentation-writer receipt is refreshed, this is approval-ready; no code changes are requested.

[prekshivyas]

Approved at exact head 354e7de457f249cf82a2ff6a1317420b07b64fae.

The prior RUN --mount detection blocker is resolved, the thread-aware review check shows no unresolved threads, and the exact-head documentation-writer receipt is now refreshed and passing. Focused integration tests pass 15/15, the source-shape and diff checks pass, all current required CI/E2E checks are green, DCO and commit verification are complete, and the exact-head nine-category security review is PASS with no findings.