perf(openclaw): collapse final image payload layers

[apurvvkumaria]

Summary

Current-main full-e2e completed functionally but spent 108.1 seconds exporting the final OpenClaw image, pushing the sandbox phase to 200.2 seconds against its 171-second budget. This change collapses repository-owned final-image payloads from 39 COPY layers to four materialization layers while preserving the three intentional direct-copy boundaries, reducing the final repository layer count from 42 to seven.

Related Issue

Related to #6660

Changes

• Group dependency, plugin/blueprint, OpenClaw patch, and runtime payloads in four trusted scratch stages, then materialize each group at its existing cache boundary. Direct final-stage COPY instructions are insufficient here because every instruction produces another exported image layer even when the functional build work is already complete.
• Keep the Node refresh, production package manifests, and final node-tar filesystem scanner as separate COPY boundaries so Node replacement, dependency installation, and the completed-image security scan retain their existing cache and review semantics.
• Preserve existing parent-directory metadata with fail-closed GNU tar extraction and verify representative payload files retain their exact owner and mode in the completed image.
• Add an OpenClaw final-image layout contract and teach the node-tar contract to find its remediation input in the grouped dependency payload.

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: Internal BuildKit layer construction changes; CLI behavior, configuration, runtime paths, permissions, and documented onboarding behavior 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: Independent exact-head nine-category Docker/security review found no blocking findings at 85bef6d9e; the signed merge tree is exact and the six-file feature patch is unchanged. Fresh exact-head x86/arm64 image builds and protected E2E remain required before merge.
• 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 OpenClaw image assembly and contract-test changes only; repository payload contents, permissions, runtime behavior, and user workflows remain unchanged, so no user-facing documentation changes are required.
• 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 integration test/openclaw-final-image-layout.test.ts test/node-tar-dockerfile-contract.test.ts test/sandbox-provisioning-helper-permissions.test.ts test/messaging-runtime-preload-packaging.test.ts test/runner.test.ts test/openclaw-dependency-review.test.ts test/openclaw-version-parser.test.ts test/sandbox-build-context.test.ts (98/98 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Docker image assembly to preserve file ownership and permissions during payload extraction, with stricter validation of expected runtime metadata.
  • Expanded the allowlist of accepted canonical dashboard RUN instructions.

• Tests

  • Added coverage for final image layout, payload-layer cache boundaries, ordering, and required metadata checks.
  • Updated Dockerfile contract tests to support alternative patch-payload stage configurations.
  • Added a lifecycle test to prevent checked-in remote dashboard output from being overridden.

• Chores / Compatibility

  • Updated source-shape test budget exceptions to retain intended payload-layer caching behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Dockerfile now uses scratch payload stages and BuildKit tar extraction for OpenClaw artifacts, with directory and file metadata checks. Tests enforce payload-stage structure, ordering, metadata, patch-stage discovery, and remote-dashboard Dockerfile lifecycle rules.

Changes

OpenClaw payload materialization

Layer / File(s)	Summary
Payload stages and runtime materialization Dockerfile	OpenClaw dependency, plugin, patch, and runtime files are collected into scratch stages and extracted into the runtime image with parent-directory metadata checks.
Final image metadata validation Dockerfile	The post-build tar-image scan validates owner, group, and mode for selected shipped runtime files.
Dockerfile layout contract tests test/openclaw-final-image-layout.test.ts, test/node-tar-dockerfile-contract.test.ts, ci/source-shape-test-budget.json	Tests enforce payload stage contents, extraction commands, ordering, metadata assertions, patch-stage selection, and source-shape accounting.

Remote dashboard Dockerfile contract

Layer / File(s)	Summary
Dashboard contract and lifecycle validation src/lib/onboard/dockerfile-remote-dashboard-bind-contract.ts, test/dashboard-remote-bind-lifecycle.test.ts	The accepted canonical instruction digest set is extended, and lifecycle coverage rejects appended configuration rewrites.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: integration: openclaw

Sequence Diagram(s)

sequenceDiagram
  participant PayloadStages
  participant BuildKit
  participant RuntimeImage
  PayloadStages->>BuildKit: provide dependency, plugin, patch, and runtime payload files
  BuildKit->>RuntimeImage: mount payload filesystem and extract tar archive
  RuntimeImage->>RuntimeImage: compare parent-directory ownership and mode

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: collapsing OpenClaw final image payload layers for performance.

✨ 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/6660-openclaw-layer-collapse

---

_{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 85bef6d in the codex/6660-openclaw-... branch remains at 96%, unchanged from commit fac91e6 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 85bef6d in the codex/6660-openclaw-... branch remains at 80%, unchanged from commit 361ceac in the main branch.

Show a code coverage summary of the most impacted files.

File	main 361ceac	codex/6660-openclaw-... 85bef6d	+/-
src/lib/onboard/dashboard.ts	72%	72%	0%
src/lib/inferen...pter-forward.ts	88%	88%	0%
src/lib/onboard...ure-contract.ts	87%	87%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/shields...nsition-lock.ts	89%	89%	0%
src/lib/actions...eway-restart.ts	93%	95%	+2%
src/lib/onboard...shboard-port.ts	90%	93%	+3%
src/lib/onboard...orward-start.ts	89%	98%	+9%
src/lib/onboard...ixed-forward.ts	38%	77%	+39%

---

_{Updated July 24, 2026 20:15 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 5 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 5 more warnings, 1 more suggestion.

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-onboard, full-e2e, onboard-repair, onboard-resume

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: 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 924-944: The runtime-payload metadata invariant omits pre-existing
directories written by the payload. In Dockerfile lines 924-944, update both
stat invocations in the runtime payload extraction to include /usr/local/share,
/usr/local/share/nemoclaw, and /scripts; update
test/openclaw-final-image-layout.test.ts lines 18-39 so the
openclaw-runtime-payload metadata expectation includes the same paths.

🪄 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: e84b1bc9-6c66-4ee8-b6d6-f1f99a9ead81

📥 Commits

Reviewing files that changed from the base of the PR and between 5faed2c and bd33f2d.

📒 Files selected for processing (4)

• Dockerfile
• ci/source-shape-test-budget.json
• test/node-tar-dockerfile-contract.test.ts
• test/openclaw-final-image-layout.test.ts

[ericksoa]

Maintainer follow-up: #7497 is now open to make repository-root Dockerfile changes select the cold full-e2e job. The current trusted risk policy selected cloud-onboard for this PR but left full-e2e skipped, so we did not yet have the exact cold-build/first-turn evidence this optimization needs.

No branch churn is requested here while that prerequisite is under review. Once #7497 lands, I plan to sync this branch normally to current main and run the resulting exact-head E2E selection; that will let us judge this PR on the path it is intended to improve rather than on indirect build evidence alone.

[ericksoa]

Maintainer validation update for exact head f9a2556ff9576983e379d60f96ae6a591cc1e2eb:

• the signed author merge commit reproduces the clean merge tree exactly;
• the focused Docker/layout/runtime contract suite passes 98/98;
• npm run check:diff passes after generating the normal CLI artifacts;
• independent documentation review returned no-docs-needed and the exact-head nine-category security review returned GO with no actionable finding;
• hosted x86 and arm64 production-image builds, downstream sandbox checks, gateway isolation, non-root smoke, and port overrides are green.

Ordinary CI has no failure; one CLI coverage shard and the protected E2E coordination check remain in progress. main advanced after this head via #7464, limited to trusted E2E swap/workflow support. I am checking the controller ancestry contract before any exact-head fallback dispatch so the eventual full-E2E evidence is bound to a valid candidate/base/workflow tuple.

[ericksoa]

Exact-head performance evidence is now available from child run 30121533570, full-e2e job 89575236211, artifact e2e-full-e2e (8607721655), bound to candidate f9a2556ff9576983e379d60f96ae6a591cc1e2eb, base cef1fd03776520bbb6c9151b3430f9960c459bca, workflow 50ae554de37f27b4bed8826565ed60d827358959, and plan 32f24d61e4e5841f4758e878d7ecd5057c8155f62d19803068099c474ceb7972.

Cold-path result:

• full-e2e: SUCCESS
• final image exporting layers: 49.8s (PR baseline: 108.1s)
• sandbox phase: 140,956 ms / 171,000 ms budget (PR baseline: 200.2s)
• root start to first-turn completion: 193,736 ms / 228,000 ms budget
• max silence: 33s / 60s budget
• performance violations: none
• BuildKit prebuild: used; fallback: false
• authoritative local-base allowance: not used

cloud-onboard and onboard-repair are also green. onboard-resume remains the sole selected job in progress, so the overall protected gate is not yet terminal.

[ericksoa]

Current-main integration checkpoint: exact head 85bef6d9e33185b808e0e9a73d239a676621645b is a signed merge of prior validated head f9a2556ff with main fac91e60f (including merged gateway-restart fix #7489).

• merge-tree recomputation matches the committed tree exactly;
• the six-file perf(openclaw): collapse final image payload layers #7486 feature diff is byte-for-byte unchanged;
• focused suite passes 98/98 on the integrated head;
• npm run check:diff passes;
• final documentation receipt is no-docs-needed at 85bef6d9e;
• final nine-category security composition review is GO with no finding.

Fresh ordinary CI, x86/arm64 image builds, and the protected four-job E2E plan are now running for this exact head/base. No waiver or skipped gate is being requested.

[ericksoa]

Terminal exact-head receipt for 85bef6d9e33185b808e0e9a73d239a676621645b on base fac91e60f468206f59ee23f7e70bb4cc4b08d1eb:

• ordinary CI recovered its isolated 5-second CDI-test timeout on failed-job rerun attempt 2; all required checks are now green;
• x86 and arm64 image builds plus sandbox, gateway-isolation, non-root, and port-override checks passed;
• protected plan ec3152981c8d3724f6a8d12cf7e52c4f95d1bb1a37c62181ea802d64727e28d7 passed all four selected jobs with no skips: cloud-onboard, full-e2e, onboard-repair, onboard-resume;
• child run: https://github.com/NVIDIA/NemoClaw/actions/runs/30123420956
• coordination: https://github.com/NVIDIA/NemoClaw/runs/89581138649
• full-e2e artifact e2e-full-e2e (8608415808) reports final layer export 50.7s, sandbox phase 146,089/171,000 ms, root-start-to-first-turn 204,378/228,000 ms, max silence 37/60s, zero violations, no fallback, and no local-base allowance.

Current main advanced two unrelated commits after dispatch (#7491 and #7370). Their ten paths are disjoint from this PR; none enters the Dockerfile explicit payload allowlists; the synthetic merge is clean and the combined tree passes build/typecheck/source-shape/test-size plus 139 relevant tests. That drift does not invalidate review approval.

[ericksoa]

Approved at exact head 85bef6d9e33185b808e0e9a73d239a676621645b. The signed current-main merge is exact, the reviewed six-file feature patch is unchanged, local 98/98 plus check:diff passed, independent docs/security reviews are current, x86/arm64 and downstream image checks passed, and protected plan ec315298… passed all four selected jobs with objective cold-path budgets green. The two post-dispatch main commits were separately proven clean and non-interacting with the explicit OpenClaw payload allowlists.