Skip to content

perf(docker): preserve warm sandbox build cache - #6034

Merged
jyaunches merged 2 commits into
mainfrom
codex/salvage-6019
Jun 30, 2026
Merged

perf(docker): preserve warm sandbox build cache#6034
jyaunches merged 2 commits into
mainfrom
codex/salvage-6019

Conversation

@cv

@cv cv commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator

Summary

Preserve Docker layer reuse for identical warm sandbox builds by leaving NEMOCLAW_BUILD_ID stable in stock OpenClaw and Hermes Dockerfiles. Custom --from Dockerfiles and managed agents that consume the compatibility argument retain the historical sanitized per-run rewrite.

This is a signed, narrowed replacement for #6019. It intentionally drops that PR's late-ENV relocation because an empirical BuildKit control proved that changing any in-scope ARG still invalidates following RUN layers even when the instruction does not mention the argument.

Related Issue

Fixes #4682

Changes

  • Select build-ID policy from explicit provenance: preserve only the known-safe managed OpenClaw/Hermes Dockerfiles; custom --from and other managed agents retain unconditional rewriting.
  • Keep the stock Dockerfile's ARG NEMOCLAW_BUILD_ID=default, with an explicit comment that gateway tokens are generated at container startup and are not baked into image layers.
  • Add focused behavioral coverage for indirect custom consumers, newline sanitization, managed provenance selection, and OpenClaw/Hermes byte identity; move cache coverage out of the large shared patcher test.
  • Require patched stock Dockerfiles to remain byte-identical when only the per-run build ID changes.
  • Preserve the contributor’s cold/warm evidence: OpenClaw 20.9s to 0.1s; Hermes 21.5s to 0.4s, with real rebuilt-versus-CACHED BuildKit excerpts, the measurement boundary, and the ARG-scope caveat recorded in the test fixture.

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 — internal build-context/cache behavior; no user command, configuration, or support contract changes
  • Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
  • Sensitive-path review completed or maintainer-approved waiver recorded — the salvage preserves the existing ARG/ENV and runtime-token boundaries; custom values still pass through sanitizeDockerArg; no credential material is added to layers
  • Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

  • PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
  • Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
  • Targeted tests pass for changed behavior
  • Full npm test passes (broad runtime changes only)
  • 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)

Evidence: 37 focused patch/policy assertions; the normal hook passed 8,330 tests (8,299 passed, 31 skipped) plus source-shape, size, security, lint, DCO, and commitlint gates; CLI pre-push typecheck passed. Real BuildKit controls identified and then cached OpenClaw’s 3.7s plugin + 10.9s layout layers and Hermes’s 9.0s config + 4.8s layout layers. Parent timing record: #3776 (comment). Commits 22c39549bbb6d2aa1796647ecc26973293252545 and c740d4cc3b63d541e7881e3d8206dc31d581501b are GitHub Verified.


Co-authored-by: Angel Mata amata@nvidia.com
Signed-off-by: Angel Mata amata@nvidia.com
Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

  • New Features

    • Improved Docker build handling for onboarded environments, with smarter per-run build ID behavior for managed and custom Dockerfiles.
    • Added support for preserving stable build IDs in selected managed-agent flows to reduce unnecessary rebuilds.
  • Bug Fixes

    • Fixed cases where build ID changes could trigger avoidable cache misses during repeated sandbox image builds.
    • Strengthened build ID sanitization so unexpected input can’t affect generated Dockerfile instructions.

Co-authored-by: Angel Mata <amata@nvidia.com>
Signed-off-by: Angel Mata <amata@nvidia.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
@coderabbitai

coderabbitai Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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: 53c8fbb8-2f5d-4380-a799-49379dc8c9d4

📥 Commits

Reviewing files that changed from the base of the PR and between 22c3954 and c740d4c.

📒 Files selected for processing (5)
  • src/lib/onboard/dockerfile-patch-build-id.test.ts
  • src/lib/onboard/dockerfile-patch.ts
  • src/lib/onboard/sandbox-dockerfile-patch-flow.test.ts
  • src/lib/onboard/sandbox-dockerfile-patch-flow.ts
  • test/fixtures/warm-build-cache-evidence.md
✅ Files skipped from review due to trivial changes (1)
  • test/fixtures/warm-build-cache-evidence.md

📝 Walkthrough

Walkthrough

patchStagedDockerfile gains a buildIdPolicy option ("preserve" or "rewrite") that conditionally skips ARG NEMOCLAW_BUILD_ID replacement. prepareSandboxDockerfilePatch computes the policy using a new STABLE_MANAGED_BUILD_ID_AGENTS allowlist. The Dockerfile comment is updated to reflect compatibility semantics, tests cover all policy branches, and a fixture documents the warm-cache measurement procedure.

Changes

Conditional NEMOCLAW_BUILD_ID patching for warm build cache

Layer / File(s) Summary
buildIdPolicy type and conditional ARG replacement
src/lib/onboard/dockerfile-patch.ts, Dockerfile
Exports DockerfileBuildIdPolicy and PatchStagedDockerfileOptions; adds options parameter to patchStagedDockerfile; makes ARG NEMOCLAW_BUILD_ID rewriting conditional on buildIdPolicy !== "preserve". Dockerfile comment updated from cache-busting guidance to compatibility-arg documentation.
Policy computation in sandbox-dockerfile-patch-flow
src/lib/onboard/sandbox-dockerfile-patch-flow.ts
Adds STABLE_MANAGED_BUILD_ID_AGENTS allowlist ("openclaw", "hermes"), derives managedAgentName, computes buildIdPolicy, and passes it into patchStagedDockerfile.
Unit tests for policy behavior and flow wiring
src/lib/onboard/dockerfile-patch-build-id.test.ts, src/lib/onboard/sandbox-dockerfile-patch-flow.test.ts
New test file covers custom Dockerfile rewrite, preserve policy byte-identity for stock agent Dockerfiles, and injection sanitization. Existing flow tests add patchStagedDockerfile mock and assert buildIdPolicy at argument index 11 for both "preserve" and "rewrite" cases.
Warm build cache evidence fixture
test/fixtures/warm-build-cache-evidence.md
Manual benchmark fixture with cold/warm measurement procedure, observed timing table, representative BuildKit trace, and explanatory notes on ARG invalidation behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

integration: openclaw, area: onboarding

Suggested reviewers

  • 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 Clear, specific, and matches the main change: preserving warm sandbox Docker build cache.
Linked Issues check ✅ Passed The changes target #4682 by reducing avoidable warm-build invalidation, preserving runtime token behavior, and adding OpenClaw/Hermes coverage.
Out of Scope Changes check ✅ Passed All code and docs changes support warm-build cache preservation; no unrelated functionality stands out.
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 codex/salvage-6019

Comment @coderabbitai help to get the list of available commands.

@github-code-quality

github-code-quality Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the codex/salvage-6019 branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main codex/salvage-6019 c740d4c +/-
nemoclaw/src/se...cret-scanner.ts 100%
nemoclaw/src/commands/slash.ts 100%
nemoclaw/src/li...bprocess-env.ts 100%
nemoclaw/src/bl...eprint/state.ts 98%
nemoclaw/src/onboard/config.ts 98%
nemoclaw/src/bl...int/snapshot.ts 97%
nemoclaw/src/bl...print/runner.ts 95%
nemoclaw/src/co...ration-state.ts 94%
nemoclaw/src/bl...ate-networks.ts 94%
nemoclaw/src/index.ts 94%

TypeScript / code-coverage/cli

The overall coverage in the codex/salvage-6019 branch is 67%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.
File main codex/salvage-6019 c740d4c +/-
src/lib/actions...all/run-plan.ts 80%
src/lib/state/o...oard-session.ts 79%
src/lib/actions...dbox/rebuild.ts 74%
src/lib/state/sandbox.ts 72%
src/lib/onboard/preflight.ts 69%
src/lib/actions...licy-channel.ts 60%
src/lib/onboard...er-gpu-patch.ts 59%
src/lib/policy/index.ts 52%
src/lib/shields/index.ts 51%
src/lib/onboard.ts 20%

Updated June 30, 2026 07:54 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.

@github-actions

github-actions Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: cloud-onboard, hermes-e2e, rebuild-openclaw
Optional E2E: sandbox-rebuild, rebuild-hermes, security-posture

Dispatch hint: cloud-onboard,hermes-e2e,rebuild-openclaw

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • cloud-onboard: Runs the full hosted OpenClaw onboarding path through the public installer, Docker/OpenShell sandbox creation, inference.local, and security checks. This is required because the PR changes the stock Dockerfile build args and staged Dockerfile patching used by real onboarding.
  • hermes-e2e: Validates the managed Hermes onboard/runtime flow. The new build-id preservation allowlist includes Hermes, so a real Hermes assistant sandbox should be built and started.
  • rebuild-openclaw: Exercises the real OpenClaw rebuild lifecycle, including Docker/OpenShell rebuild behavior, state preservation, and gateway token rotation. The PR changes the build-id input that historically affected rebuild cache invalidation and token-layer assumptions.

Optional E2E

  • sandbox-rebuild: Useful adjacent coverage for the normal nemoclaw <sandbox> rebuild --yes path after a current hosted onboard, including registry refresh and backup hygiene.
  • rebuild-hermes: Additional confidence for Hermes-specific rebuild behavior after the PR changed managed Hermes build-id preservation.
  • security-posture: Extra confidence that preserving the managed build-id does not regress sandbox credential leak boundaries beyond the checks already covered by cloud-onboard.

New E2E recommendations

  • warm-build-cache (medium): Existing live E2E can prove onboarding/rebuild correctness, but there is no dedicated live regression that performs two stable-input OpenClaw and Hermes builds and asserts the second build reuses cached layers or that the managed staged contexts remain stable in the real Docker/OpenShell path.
    • Suggested test: warm-build-cache-openclaw-hermes
  • custom-dockerfile-build-id-compatibility (low): The PR preserves build IDs only for known managed Dockerfiles and keeps rewriting for custom --from Dockerfiles, including indirect consumers. Unit coverage exists, but a live custom-Dockerfile onboard/rebuild E2E would catch regressions at the real CLI and Docker boundary.
    • Suggested test: custom-dockerfile-build-id-onboard

Dispatch hint

  • Workflow: .github/workflows/e2e.yaml
  • jobs input: cloud-onboard,hermes-e2e,rebuild-openclaw

@github-actions

github-actions Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

E2E Target Recommendation

Required E2E targets: ubuntu-repo-cloud-openclaw, ubuntu-repo-cloud-langchain-deepagents-code
Optional E2E targets: None

Dispatch required E2E targets:

  • gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-openclaw
  • gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-langchain-deepagents-code

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

  • ubuntu-repo-cloud-openclaw: The PR changes the managed OpenClaw Dockerfile build-id handling and the shared staged-Dockerfile patch flow used during default OpenClaw onboarding. This live-supported target is the smallest registry target that builds and validates the stock OpenClaw sandbox path.
    • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-openclaw
  • ubuntu-repo-cloud-langchain-deepagents-code: The new build-id policy explicitly keeps per-run rewrites for managed agents outside the stable OpenClaw/Hermes set. This live-supported target exercises the affected managed-agent rewrite path.
    • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-langchain-deepagents-code

Optional E2E targets

  • None.

Relevant changed files

  • Dockerfile
  • src/lib/onboard/dockerfile-patch.ts
  • src/lib/onboard/sandbox-dockerfile-patch-flow.ts

@github-actions

github-actions Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 3 test follow-ups
Since last review: 5 prior items resolved · 0 still apply · 0 new items found

Action checklist

  • PRA-T1 Add or justify test follow-up: Runtime validation
  • PRA-T2 Add or justify test follow-up: Runtime validation
  • PRA-T3 Add or justify test follow-up: Runtime validation
Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

  • PRA-T1 Runtime validation — Identify a local OpenClaw cold/warm onboard run where only `NEMOCLAW_BUILD_ID` changes and the stock staged Dockerfile remains byte-identical while BuildKit reports the plugin/layout layers as `CACHED`.. The unit coverage is well targeted, but Dockerfile/onboard cache behavior is infrastructure-sensitive and benefits from runtime validation against real Docker/BuildKit behavior.
  • PRA-T2 Runtime validation — Identify a local Hermes cold/warm onboard run where only `NEMOCLAW_BUILD_ID` changes and the stock staged Dockerfile remains byte-identical while BuildKit reports the doctor/layout layers as `CACHED`.. The unit coverage is well targeted, but Dockerfile/onboard cache behavior is infrastructure-sensitive and benefits from runtime validation against real Docker/BuildKit behavior.
  • PRA-T3 Runtime validation — Identify a custom `--from` Dockerfile probe with `ARG NEMOCLAW_BUILD_ID=default` followed by a non-textual `RUN` consumer and confirm the staged Dockerfile still rewrites the ARG to a sanitized per-run value.. The unit coverage is well targeted, but Dockerfile/onboard cache behavior is infrastructure-sensitive and benefits from runtime validation against real Docker/BuildKit behavior.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@src/lib/onboard/dockerfile-patch.ts`:
- Around line 80-89: The dockerfileConsumesBuildId helper is still over-matching
plain NEMOCLAW_BUILD_ID text, so update the detection logic to recognize only
real build-id expansions in the dockerfile-patch flow rather than any literal
token. Adjust dockerfileConsumesBuildId to key off expansion syntax used by
Dockerfile directives and shell interpolation, and keep it from treating
LABEL/text/escaped mentions as consumers; then add a regression test covering a
literal-only NEMOCLAW_BUILD_ID mention so the rewrite path in dockerfile
patching stays skipped for that case.
🪄 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: f39c59a0-90b7-4d00-a635-eb9854a28a44

📥 Commits

Reviewing files that changed from the base of the PR and between 09bef70 and 22c3954.

📒 Files selected for processing (4)
  • Dockerfile
  • src/lib/onboard/dockerfile-patch.test.ts
  • src/lib/onboard/dockerfile-patch.ts
  • test/fixtures/warm-build-cache-evidence.md

Comment thread src/lib/onboard/dockerfile-patch.ts Outdated
@github-actions

github-actions Bot commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor (Nemotron Ultra) — Changes requested

Merge posture: Do not merge yet
Primary next action: Resolve or justify PRA-1: Test reads Hermes Dockerfile from repo root — fragile if file moves.
Open items: 0 required · 1 warning · 0 suggestions · 0 test follow-ups
Since last review: 1 prior item resolved · 1 still applies · 0 new items found

Action checklist

  • PRA-1 Resolve or justify: Test reads Hermes Dockerfile from repo root — fragile if file moves in src/lib/onboard/dockerfile-patch-build-id.test.ts:33

Findings index

ID Severity Category Location Required action
PRA-1 Resolve/justify correctness src/lib/onboard/dockerfile-patch-build-id.test.ts:33 Wrap the file read in a try/catch with a descriptive error message, or copy the Dockerfile content into a test fixture. Since this test validates a critical cache-stability property for both agents, it should fail loudly with a clear message if the source file is missing.
Review findings by urgency: 0 required fixes, 1 item to resolve/justify, 0 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

PRA-1 Resolve/justify — Test reads Hermes Dockerfile from repo root — fragile if file moves

  • Location: src/lib/onboard/dockerfile-patch-build-id.test.ts:33
  • Category: correctness
  • Problem: The byte-identity test for stock Dockerfiles uses `path.join(REPO_ROOT, "agents", "hermes", "Dockerfile")` to read the actual Hermes Dockerfile. If the file moves or is renamed, the test fails with ENOENT rather than a clear assertion message, reducing maintainability of a critical cache-stability regression test.
  • Impact: Test failure with cryptic error if Hermes Dockerfile is moved/renamed, delaying detection of actual regressions in build-context stability.
  • Recommended action: Wrap the file read in a try/catch with a descriptive error message, or copy the Dockerfile content into a test fixture. Since this test validates a critical cache-stability property for both agents, it should fail loudly with a clear message if the source file is missing.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Read dockerfile-patch-build-id.test.ts:33-34 and verify the file read has error handling or uses a fixture.
  • Missing regression test: Add a test setup check that both Dockerfiles exist before running the byte-identity assertion, or embed fixture content.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Read dockerfile-patch-build-id.test.ts:33-34 and verify the file read has error handling or uses a fixture.
  • Evidence: dockerfile-patch-build-id.test.ts lines 33-34: `path.join(REPO_ROOT, "agents", "hermes", "Dockerfile")`

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

  • None.
Since last review details

Current findings, using the urgency labels above:

PRA-1 Resolve/justify — Test reads Hermes Dockerfile from repo root — fragile if file moves

  • Location: src/lib/onboard/dockerfile-patch-build-id.test.ts:33
  • Category: correctness
  • Problem: The byte-identity test for stock Dockerfiles uses `path.join(REPO_ROOT, "agents", "hermes", "Dockerfile")` to read the actual Hermes Dockerfile. If the file moves or is renamed, the test fails with ENOENT rather than a clear assertion message, reducing maintainability of a critical cache-stability regression test.
  • Impact: Test failure with cryptic error if Hermes Dockerfile is moved/renamed, delaying detection of actual regressions in build-context stability.
  • Recommended action: Wrap the file read in a try/catch with a descriptive error message, or copy the Dockerfile content into a test fixture. Since this test validates a critical cache-stability property for both agents, it should fail loudly with a clear message if the source file is missing.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Read dockerfile-patch-build-id.test.ts:33-34 and verify the file read has error handling or uses a fixture.
  • Missing regression test: Add a test setup check that both Dockerfiles exist before running the byte-identity assertion, or embed fixture content.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Read dockerfile-patch-build-id.test.ts:33-34 and verify the file read has error handling or uses a fixture.
  • Evidence: dockerfile-patch-build-id.test.ts lines 33-34: `path.join(REPO_ROOT, "agents", "hermes", "Dockerfile")`

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

Signed-off-by: Carlos Villela <cvillela@nvidia.com>
@cv
cv requested a review from prekshivyas June 30, 2026 07:50
@github-actions

Copy link
Copy Markdown
Contributor

Vitest E2E Target Results — ❌ Some jobs failed

Run: 28428908792
Workflow ref: codex/salvage-6019
Requested targets: (selector rejected by workflow validation)
Requested jobs: (selector rejected by workflow validation)
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped

Job Result
generate-matrix ❌ failure

Failed jobs: generate-matrix. Check run artifacts for logs.

@github-actions

Copy link
Copy Markdown
Contributor

Vitest E2E Target Results — ✅ All selected jobs passed

Run: 28429086924
Workflow ref: codex/salvage-6019
Requested targets: ubuntu-repo-cloud-openclaw
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs such as jetson-nvmap-gpu and sandbox-rlimits-connect are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job Result
live ✅ success

@cv

cv commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator Author

Maintainer resolution for exact head c740d4c: Nemotron PRA-1 is already satisfied by the code it reviewed. Before readFileSync, the parameterized test executes expect(fs.existsSync(stockDockerfile), missing managed ${agentName} Dockerfile).toBe(true). A moved or missing OpenClaw/Hermes Dockerfile therefore fails with the requested descriptive agent-specific assertion rather than an ENOENT. Reading the real checked-in Dockerfiles is intentional: copying them into fixtures would decouple this cache invariant from the production inputs and allow drift. GPT-5.5 is exact-head merge_as_is, standard CI is green, and the exact-head ubuntu-repo-cloud-openclaw E2E passed. The required cloud-onboard and sandbox-rebuild jobs are still running; no merge will occur until they pass and an external human approves.

@cv cv added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: packaging Packages, images, registries, installers, or distribution v0.0.71 labels Jun 30, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Vitest E2E Target Results — ✅ All requested jobs passed

Run: 28429091895
Workflow ref: codex/salvage-6019
Requested targets: (default — all supported)
Requested jobs: cloud-onboard,sandbox-rebuild
Summary: 2 passed, 0 failed, 0 cancelled, 0 skipped

Job Result
cloud-onboard ✅ success
sandbox-rebuild ✅ success

@cv cv left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exact-head maintainer review for c740d4c:

GPT-5.5 recommends merge_as_is. Nemotron's remaining items are maintenance warnings, not a correctness blocker:

  • The test already performs an explicit existence assertion with missing managed <agent> Dockerfile before readFileSync. Reading the checked-in Dockerfiles is deliberate source-of-truth coverage; a copied fixture would mask drift.
  • The stable-agent allowlist is compatibility-safe: only stock OpenClaw/Hermes preserve an ID proven unused. Custom --from, LangChain, and every unlisted/future agent retain the historical rewrite. Missing a future entry costs cache performance only.
  • Exact-head E2E is green (28429086924 and 28429091895), and real BuildKit evidence shows the expected warm-layer reuse for both managed agents.
  • Any overlapping PR that lands first requires rebase/re-review; no overlap is being silently accepted.

All commits are Verified/DCO and ordinary CI/CodeRabbit are green. This is a rationale/evidence review, not independent approval; required human approval and a clean advisor gate still apply.

@jyaunches
jyaunches merged commit 37a8094 into main Jun 30, 2026
278 of 279 checks passed
@jyaunches
jyaunches deleted the codex/salvage-6019 branch June 30, 2026 18:30
@jyaunches jyaunches mentioned this pull request Jun 30, 2026
21 tasks
jyaunches added a commit that referenced this pull request Jun 30, 2026
<!-- markdownlint-disable MD041 -->
## Summary
Refreshes the public documentation for NemoClaw v0.0.71 after scanning
commits since v0.0.70. Adds release notes and fills the remaining doc
gaps for Windows bootstrap diagnostics, OpenClaw agent auto-relock
warnings, auto-pair cadence tuning, and plugin-install recovery hints.

## Changes
- `docs/about/release-notes.mdx`: adds the v0.0.71 release-note section,
grouped by gateway recovery, OpenShell auth, policy provenance, day-two
maintenance, messaging/inference, and Windows setup.
- `docs/get-started/windows-preparation.mdx`: documents sanitized WSL
install output and reboot gating in the Windows bootstrap.
- `docs/reference/commands.mdx`: documents the host `agent` wrapper's
shields auto-relock warning and OpenClaw auto-pair watcher tuning
variables.
- `docs/reference/troubleshooting.mdx`: adds plugin-install network
failure recovery guidance and updates Windows WSL troubleshooting for
sanitized install logs and reboot-required handling.

Source summary:
- #6065 -> `docs/about/release-notes.mdx`: Notes explicit model override
preservation and gateway-log guard-chain recovery diagnostics.
- #5874 -> `docs/about/release-notes.mdx`: Summarizes host-mediated
`recover` and `gateway restart`, linking to lifecycle, command,
troubleshooting, and trusted-boundary docs already added by the source
PR.
- #5596 -> `docs/about/release-notes.mdx`: Summarizes OpenShell 0.0.71
gateway auth, loopback binding, and compatibility-container docs already
added by the source PR.
- #5797 and #5798 -> `docs/about/release-notes.mdx`: Summarizes
`policy-list` provenance, Restricted tier suppression, and Balanced tier
weather behavior already reflected in policy docs.
- #5784 -> `docs/about/release-notes.mdx`: Summarizes
`--destroy-user-data` and the safe `--yes` uninstall behavior already
documented in lifecycle and command docs.
- #6034 -> `docs/about/release-notes.mdx`: Summarizes custom Dockerfile
warm-build cache behavior already documented in the command reference.
- #5951 -> `docs/reference/commands.mdx`: Documents the stderr-only host
`agent` wrapper warning after recent shields auto-relock.
- #5387 -> `docs/reference/commands.mdx`: Documents OpenClaw auto-pair
watcher cadence and fast-reentry tuning variables.
- #5835 -> `docs/reference/troubleshooting.mdx`: Adds recovery guidance
for OpenClaw plugin-install network failures.
- #5995 and #5956 -> `docs/about/release-notes.mdx`: Summarizes
Microsoft Teams final-message delivery and runtime mention hints already
covered by messaging docs.
- #5716 -> `docs/about/release-notes.mdx`: Summarizes non-interactive
Ollama loopback safety already covered by local inference docs.
- #5505, #5527, and #5528 -> `docs/about/release-notes.mdx`: Summarizes
compatible local endpoint, model task-fit, and model capability audit
docs.
- #6009 -> `docs/get-started/windows-preparation.mdx`,
`docs/reference/troubleshooting.mdx`: Documents sanitized Windows
bootstrap WSL output and reboot-required gating.
- #6055 -> no additional source doc page change needed beyond the
already-merged quickstart update; release notes did not duplicate
routine quickstart cleanup.

No matching v0.0.71 GitHub announcement discussion was found in the
latest 20 discussions, so this refresh is based on the commit scan and
existing source PR docs.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [x] Doc only (includes code sample changes)

## Quality Gates
<!-- Check all that apply. For any "covered by existing tests", "not
applicable", or waiver entry, add a brief justification on the same line
or in the Changes section. -->
- [ ] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [x] Tests not applicable — justification: docs-only refresh with no
runtime behavior changes.
- [x] Docs updated for user-facing behavior changes
- [ ] Docs not applicable — justification:
- [ ] 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:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification
<!-- Check each item you ran and confirmed. Leave unchecked items you
skipped. Doc-only changes do not require npm test unless you ran it. -->
- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Git hooks passed during commit and push, or `npx prek run
--from-ref main --to-ref HEAD` passes
- [ ] Targeted tests pass for changed behavior
- [ ] Full `npm test` passes (broad runtime changes only)
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) — ran
`npm run docs`; Fern reported 0 errors and 2 existing warnings.
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
<!-- DCO sign-off is required in this PR description, and every commit
must appear as Verified in GitHub. Run: git config user.name && git
config user.email -->
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added a new release-notes entry covering gateway recovery,
authentication, network policy/provenance output, uninstall safety,
Windows bootstrap diagnostics, messaging defaults, and inference setup
guidance.
* Clarified Windows preparation steps around reboot behavior and
redacting troubleshooting transcripts.
* Expanded command reference details for OpenClaw wrapper behavior and
new auto-pair tuning options.
* Improved troubleshooting guidance for plugin installation issues, WSL
repair/reboot cases, and install timing problems.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Co-authored-by: Prekshi Vyas <34834085+prekshivyas@users.noreply.github.com>
Hadar301 pushed a commit to Hadar301/NemoClaw-OpenShift that referenced this pull request Jul 12, 2026
<!-- markdownlint-disable MD041 -->
## Summary

Preserve Docker layer reuse for identical warm sandbox builds by leaving
`NEMOCLAW_BUILD_ID` stable in stock OpenClaw and Hermes Dockerfiles.
Custom `--from` Dockerfiles and managed agents that consume the
compatibility argument retain the historical sanitized per-run rewrite.

This is a signed, narrowed replacement for NVIDIA#6019. It intentionally drops
that PR's late-`ENV` relocation because an empirical BuildKit control
proved that changing any in-scope `ARG` still invalidates following
`RUN` layers even when the instruction does not mention the argument.

## Related Issue

Fixes NVIDIA#4682

## Changes

- Select build-ID policy from explicit provenance: preserve only the
known-safe managed OpenClaw/Hermes Dockerfiles; custom `--from` and
other managed agents retain unconditional rewriting.
- Keep the stock Dockerfile's `ARG NEMOCLAW_BUILD_ID=default`, with an
explicit comment that gateway tokens are generated at container startup
and are not baked into image layers.
- Add focused behavioral coverage for indirect custom consumers, newline
sanitization, managed provenance selection, and OpenClaw/Hermes byte
identity; move cache coverage out of the large shared patcher test.
- Require patched stock Dockerfiles to remain byte-identical when only
the per-run build ID changes.
- Preserve the contributor’s cold/warm evidence: OpenClaw `20.9s` to
`0.1s`; Hermes `21.5s` to `0.4s`, with real rebuilt-versus-`CACHED`
BuildKit excerpts, the measurement boundary, and the ARG-scope caveat
recorded in the test fixture.

## Type of Change

- [x] 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

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [ ] Docs updated for user-facing behavior changes
- [x] Docs not applicable — internal build-context/cache behavior; no
user command, configuration, or support contract changes
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — the salvage preserves the existing ARG/ENV and runtime-token
boundaries; custom values still pass through `sanitizeDockerArg`; no
credential material is added to layers
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification

- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Git hooks passed during commit and push, or `npx prek run
--from-ref main --to-ref HEAD` passes
- [x] Targeted tests pass for changed behavior
- [ ] Full `npm test` passes (broad runtime changes only)
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

Evidence: 37 focused patch/policy assertions; the normal hook passed
8,330 tests (8,299 passed, 31 skipped) plus source-shape, size,
security, lint, DCO, and commitlint gates; CLI pre-push typecheck
passed. Real BuildKit controls identified and then cached OpenClaw’s
3.7s plugin + 10.9s layout layers and Hermes’s 9.0s config + 4.8s layout
layers. Parent timing record:
NVIDIA#3776 (comment).
Commits `22c39549bbb6d2aa1796647ecc26973293252545` and
`c740d4cc3b63d541e7881e3d8206dc31d581501b` are GitHub Verified.

---
Co-authored-by: Angel Mata <amata@nvidia.com>
Signed-off-by: Angel Mata <amata@nvidia.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Improved Docker build handling for onboarded environments, with
smarter per-run build ID behavior for managed and custom Dockerfiles.
* Added support for preserving stable build IDs in selected
managed-agent flows to reduce unnecessary rebuilds.

* **Bug Fixes**
* Fixed cases where build ID changes could trigger avoidable cache
misses during repeated sandbox image builds.
* Strengthened build ID sanitization so unexpected input can’t affect
generated Dockerfile instructions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Angel Mata <amata@nvidia.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Co-authored-by: Angel Mata <amata@nvidia.com>
Hadar301 pushed a commit to Hadar301/NemoClaw-OpenShift that referenced this pull request Jul 12, 2026
<!-- markdownlint-disable MD041 -->
## Summary
Refreshes the public documentation for NemoClaw v0.0.71 after scanning
commits since v0.0.70. Adds release notes and fills the remaining doc
gaps for Windows bootstrap diagnostics, OpenClaw agent auto-relock
warnings, auto-pair cadence tuning, and plugin-install recovery hints.

## Changes
- `docs/about/release-notes.mdx`: adds the v0.0.71 release-note section,
grouped by gateway recovery, OpenShell auth, policy provenance, day-two
maintenance, messaging/inference, and Windows setup.
- `docs/get-started/windows-preparation.mdx`: documents sanitized WSL
install output and reboot gating in the Windows bootstrap.
- `docs/reference/commands.mdx`: documents the host `agent` wrapper's
shields auto-relock warning and OpenClaw auto-pair watcher tuning
variables.
- `docs/reference/troubleshooting.mdx`: adds plugin-install network
failure recovery guidance and updates Windows WSL troubleshooting for
sanitized install logs and reboot-required handling.

Source summary:
- NVIDIA#6065 -> `docs/about/release-notes.mdx`: Notes explicit model override
preservation and gateway-log guard-chain recovery diagnostics.
- NVIDIA#5874 -> `docs/about/release-notes.mdx`: Summarizes host-mediated
`recover` and `gateway restart`, linking to lifecycle, command,
troubleshooting, and trusted-boundary docs already added by the source
PR.
- NVIDIA#5596 -> `docs/about/release-notes.mdx`: Summarizes OpenShell 0.0.71
gateway auth, loopback binding, and compatibility-container docs already
added by the source PR.
- NVIDIA#5797 and NVIDIA#5798 -> `docs/about/release-notes.mdx`: Summarizes
`policy-list` provenance, Restricted tier suppression, and Balanced tier
weather behavior already reflected in policy docs.
- NVIDIA#5784 -> `docs/about/release-notes.mdx`: Summarizes
`--destroy-user-data` and the safe `--yes` uninstall behavior already
documented in lifecycle and command docs.
- NVIDIA#6034 -> `docs/about/release-notes.mdx`: Summarizes custom Dockerfile
warm-build cache behavior already documented in the command reference.
- NVIDIA#5951 -> `docs/reference/commands.mdx`: Documents the stderr-only host
`agent` wrapper warning after recent shields auto-relock.
- NVIDIA#5387 -> `docs/reference/commands.mdx`: Documents OpenClaw auto-pair
watcher cadence and fast-reentry tuning variables.
- NVIDIA#5835 -> `docs/reference/troubleshooting.mdx`: Adds recovery guidance
for OpenClaw plugin-install network failures.
- NVIDIA#5995 and NVIDIA#5956 -> `docs/about/release-notes.mdx`: Summarizes
Microsoft Teams final-message delivery and runtime mention hints already
covered by messaging docs.
- NVIDIA#5716 -> `docs/about/release-notes.mdx`: Summarizes non-interactive
Ollama loopback safety already covered by local inference docs.
- NVIDIA#5505, NVIDIA#5527, and NVIDIA#5528 -> `docs/about/release-notes.mdx`: Summarizes
compatible local endpoint, model task-fit, and model capability audit
docs.
- NVIDIA#6009 -> `docs/get-started/windows-preparation.mdx`,
`docs/reference/troubleshooting.mdx`: Documents sanitized Windows
bootstrap WSL output and reboot-required gating.
- NVIDIA#6055 -> no additional source doc page change needed beyond the
already-merged quickstart update; release notes did not duplicate
routine quickstart cleanup.

No matching v0.0.71 GitHub announcement discussion was found in the
latest 20 discussions, so this refresh is based on the commit scan and
existing source PR docs.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [x] Doc only (includes code sample changes)

## Quality Gates
<!-- Check all that apply. For any "covered by existing tests", "not
applicable", or waiver entry, add a brief justification on the same line
or in the Changes section. -->
- [ ] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [x] Tests not applicable — justification: docs-only refresh with no
runtime behavior changes.
- [x] Docs updated for user-facing behavior changes
- [ ] Docs not applicable — justification:
- [ ] 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:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification
<!-- Check each item you ran and confirmed. Leave unchecked items you
skipped. Doc-only changes do not require npm test unless you ran it. -->
- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Git hooks passed during commit and push, or `npx prek run
--from-ref main --to-ref HEAD` passes
- [ ] Targeted tests pass for changed behavior
- [ ] Full `npm test` passes (broad runtime changes only)
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) — ran
`npm run docs`; Fern reported 0 errors and 2 existing warnings.
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
<!-- DCO sign-off is required in this PR description, and every commit
must appear as Verified in GitHub. Run: git config user.name && git
config user.email -->
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added a new release-notes entry covering gateway recovery,
authentication, network policy/provenance output, uninstall safety,
Windows bootstrap diagnostics, messaging defaults, and inference setup
guidance.
* Clarified Windows preparation steps around reboot behavior and
redacting troubleshooting transcripts.
* Expanded command reference details for OpenClaw wrapper behavior and
new auto-pair tuning options.
* Improved troubleshooting guidance for plugin installation issues, WSL
repair/reboot cases, and install timing problems.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Co-authored-by: Prekshi Vyas <34834085+prekshivyas@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: packaging Packages, images, registries, installers, or distribution

Projects

None yet

Development

Successfully merging this pull request may close these issues.

perf(onboard): reduce Dockerfile cache misses in warm sandbox builds

3 participants