fix(images): require trusted base image overrides

[HOYALIM]

Summary

Refresh #6884 onto current main after the trusted base-image override implementation and its regression coverage landed independently.
The effective delta keeps the existing command reference source aligned with the writing guide and makes its JSONL redaction fixture safe for gitleaks to scan during merge commits.

Related Issue

Refs #5896.

Changes

• merge current main and preserve its base-image provenance implementation and coverage
• remove seven duplicate provenance tests after automated review confirmed equivalent cases already exist on main
• keep the trusted remote and local override documentation at one sentence per source line without changing rendered meaning
• use a low-entropy, pattern-matching test token so gitleaks can scan merge commits without weakening JSONL redaction 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: current main already documents the trusted override behavior; the effective docs diff only applies sentence-per-line formatting and does not change rendered meaning.
• 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: @prekshivyas approved the provenance changes; latest approval. GitHub continued to report APPROVED after the synchronized head was pushed.
• 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: docs-updated
• Evidence: The effective diff contains only docs/reference/commands.mdx sentence-per-line formatting and a JSONL test-fixture correction. The command reference accurately documents trusted remote digests and current-operation local build proof. Terminology, structure, voice, and code presentation comply with repository guidance. npm run docs completed with 0 errors and 2 known warnings.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

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 — 8 base-image/rebuild files: 135 passed on the synchronized implementation; final retained src/lib/sandbox-base-image-resolution.test.ts suite: 22 passed; src/lib/onboard/machine/jsonl-events.test.ts: 22 passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — not applicable because the effective diff contains regression tests, a test fixture, and command-reference prose; targeted tests and npm run check:diff 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) — completed with 0 errors and 2 known warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new pages.

---

Signed-off-by: Ho Lim subhoya@gmail.com

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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

Sandbox base-image builds now record provenance, while override resolution validates trusted remote references, immutable digests, and image-ID-bound local images. Rebuild flows carry trusted local proofs, tests cover acceptance and rejection paths, and command documentation records per-agent requirements.

Changes

Sandbox base-image provenance and override validation

Layer / File(s)	Summary
Build provenance labeling src/lib/sandbox-base-image/*, src/lib/adapters/docker/image.ts, src/lib/agent/base-image.ts	Local builds derive provenance from source revisions and inputs, attach it as Docker labels, and validate the labeling behavior.
Trusted override resolution src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image-resolution.test.ts	Local overrides are checked against image IDs and provenance; remote overrides are restricted, refreshed, and required to resolve to immutable digests.
Trusted override operation pinning src/lib/agent/*, src/lib/actions/sandbox/*	Rebuild preflight propagates trusted local override proof and leases it for the recreation operation before cleanup restores the pin.
Validation support and per-agent requirements test/helpers/*, test/rebuild-credential-preflight.test.ts, test/repro-2201.test.ts, docs/reference/commands.mdx	Fixtures and mocks expose provenance metadata, source revision coverage is extended, and per-agent override requirements are documented.

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

Possibly related PRs

• NVIDIA/NemoClaw#4082: Both changes modify the sandbox base-image override resolution flow.

Suggested labels: area: sandbox, feature

Suggested reviewers: cv, ericksoa, sandl99

Sequence Diagram(s)

sequenceDiagram
  participant RebuildPreflight
  participant AgentBaseImage
  participant resolveSandboxBaseImage
  participant Docker
  RebuildPreflight->>AgentBaseImage: resolve base image
  AgentBaseImage->>resolveSandboxBaseImage: pass trusted local proof or override
  resolveSandboxBaseImage->>Docker: inspect local image or refresh remote reference
  Docker-->>resolveSandboxBaseImage: image ID, provenance, or immutable digest
  resolveSandboxBaseImage-->>AgentBaseImage: validated image result
  AgentBaseImage-->>RebuildPreflight: image reference and trusted override

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.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 clearly matches the main change: tightening sandbox/base-image overrides to require trusted provenance.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[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 · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections match; 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: cloud-onboard

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

🧹 Nitpick comments (1)

src/lib/sandbox-base-image-resolution.test.ts (1)

193-280: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider extracting a small helper for the repeated override-options spread.

All four tests repeat { ...options, envVar: "NEMOCLAW_SANDBOX_BASE_IMAGE_REF", env: { ...options.env, NEMOCLAW_SANDBOX_BASE_IMAGE_REF: <ref> } }. A tiny withOverride(ref) helper would reduce duplication as more override scenarios are added.

♻️ Example helper

function withOverride(options: ReturnType<typeof resolutionOptions>, ref: string) {
  return {
    ...options,
    envVar: "NEMOCLAW_SANDBOX_BASE_IMAGE_REF",
    env: { ...options.env, NEMOCLAW_SANDBOX_BASE_IMAGE_REF: ref },
  };
}

🤖 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 `@src/lib/sandbox-base-image-resolution.test.ts` around lines 193 - 280,
Extract a small helper near the test setup, such as withOverride, that accepts
the result of resolutionOptions and an override reference, then returns the
shared options/env structure for NEMOCLAW_SANDBOX_BASE_IMAGE_REF. Replace the
repeated inline spreads in all four resolveSandboxBaseImage tests with this
helper while preserving each test’s reference value and assertions.

🤖 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 `@docs/reference/commands.mdx`:
- Line 3436: In the documentation text near the remote override requirements,
place each sentence on its own source line: keep the remote NVIDIA sandbox-base
repository and immutable digest requirement together, then put the
repository-built local override tag requirement on the following line. Preserve
the wording and rendering.

In `@src/lib/sandbox-base-image.ts`:
- Around line 389-403: Update the override resolution flow in the surrounding
base-image resolver so floating remote tag overrides refresh or pull the image
before `resolvePulledCandidate` trusts `RepoDigests`. Preserve
`resolveContentAddressedLocalOverride` for immutable local overrides, but ensure
tag-based overrides cannot use stale locally cached digest metadata and must
resolve a fresh trusted registry digest.

---

Nitpick comments:
In `@src/lib/sandbox-base-image-resolution.test.ts`:
- Around line 193-280: Extract a small helper near the test setup, such as
withOverride, that accepts the result of resolutionOptions and an override
reference, then returns the shared options/env structure for
NEMOCLAW_SANDBOX_BASE_IMAGE_REF. Replace the repeated inline spreads in all four
resolveSandboxBaseImage tests with this helper while preserving each test’s
reference value and assertions.

🪄 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: e1a2ffaa-c1df-4fea-b10e-4d357d5d67b4

📥 Commits

Reviewing files that changed from the base of the PR and between ea143b8 and d72e53c.

📒 Files selected for processing (3)

• docs/reference/commands.mdx
• src/lib/sandbox-base-image-resolution.test.ts
• src/lib/sandbox-base-image.ts

[wscurran]

✨ Thanks for the fix. Hardening sandbox base-image trust boundaries to fail closed on untrusted overrides improves deployment security. Ready for maintainer review.

---

Related open issues:

• #5896 Post-tag hardening: close OpenClaw 2026.6.9 trust, live-proof, and compatibility-debt gaps

---

Related open issues:

• #5896 Post-tag hardening: close OpenClaw 2026.6.9 trust, live-proof, and compatibility-debt gaps

[prekshivyas]

Reviewed the remote repository restriction, digest refresh/pinning, content-addressed local override validation, ABI/runtime checks, and regression coverage. No blocking findings.

[prekshivyas]

Re-reviewed the current head after syncing main. The integration fixture now uses the immutable official-repository digest required by the new provenance contract; the resolver suite passes 19/19 and affected onboarding suites pass 12/12.

[prekshivyas]

Re-reviewed at c4f33ec: content-addressed local overrides now require a full-source-revision and current-input fingerprint stamped by NemoClaw local builds. Arbitrary matching-ID retags fail closed; focused resolver, source-identity, Docker adapter tests and CLI build/typecheck pass.

[coderabbitai]

Actionable comments posted: 4

🤖 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/adapters/docker/image.ts`:
- Around line 36-38: Update the label sorting comparator in the
Object.entries(...).sort chain to use direct code-unit ordering with -1, 1, or 0
based on left and right comparisons, replacing localeCompare so argv generation
remains deterministic across locales.

In `@src/lib/agent/base-image.test.ts`:
- Around line 176-182: Update the test around the provenance label assertion to
use deterministic source inputs and verify the exact expected derived provenance
key rather than only matching a 64-character hexadecimal format. Alternatively,
vary a provenance source value and assert that the emitted label changes, while
preserving the existing container execution options.

In `@src/lib/sandbox-base-image/resolution-key.ts`:
- Around line 51-60: Strengthen local base-image provenance so
createSandboxBaseImageBuildProvenanceKey is not the sole trust mechanism. Update
resolveContentAddressedLocalOverride to accept an image only when its provenance
is backed by an external attestation/signature or a repository-owned mapping,
rather than trusting the image’s own label; preserve the existing override
behavior only after that verification succeeds.

In `@src/lib/sandbox-base-image/source-identity.test.ts`:
- Around line 170-176: Update the test around getSourceRevisionIds to stub the
git subprocess so it returns a failed result without launching the real command,
then restore the stub after the assertion. Keep the invalid repository path and
ensure the assertion depends solely on GITHUB_SHA.

🪄 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: ac1f9286-5595-4224-b2be-44492c4c418c

📥 Commits

Reviewing files that changed from the base of the PR and between a3e610c and c4f33ec.

📒 Files selected for processing (10)

• src/lib/adapters/docker/image.ts
• src/lib/adapters/docker/index.test.ts
• src/lib/agent/base-image.test.ts
• src/lib/agent/base-image.ts
• src/lib/sandbox-base-image-resolution.test.ts
• src/lib/sandbox-base-image.ts
• src/lib/sandbox-base-image/resolution-key.ts
• src/lib/sandbox-base-image/source-identity.test.ts
• src/lib/sandbox-base-image/source-identity.ts
• src/lib/sandbox-base-image/types.ts

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

• src/lib/sandbox-base-image.ts

[prekshivyas]

Re-reviewed at 13b0db1: local override trust is now a per-build capability with a fresh nonce, not a self-asserted image label. Matching-ID images with copied provenance are rejected without the current operation proof. Deterministic argv, exact provenance wiring, isolated source identity, resolver and agent regressions all pass.

[coderabbitai]

🧹 Nitpick comments (1)

test/helpers/base-image-test-harness.ts (1)

92-135: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Expose dockerInfoFormatMock from withMockedDocker
The harness already patches and restores this mock, so returning it with the other deps keeps the helper symmetrical and lets tests override host-platform reporting when needed.

🤖 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/helpers/base-image-test-harness.ts` around lines 92 - 135, Update
withMockedDocker to include dockerInfoFormatMock in its returned dependencies
alongside the other Docker mocks. Keep the existing patching and restoration
behavior unchanged so callers can override host-platform reporting through the
exposed mock.

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

Nitpick comments:
In `@test/helpers/base-image-test-harness.ts`:
- Around line 92-135: Update withMockedDocker to include dockerInfoFormatMock in
its returned dependencies alongside the other Docker mocks. Keep the existing
patching and restoration behavior unchanged so callers can override
host-platform reporting through the exposed mock.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 04820c81-515c-42dd-bfaa-cb25d97eedb9

📥 Commits

Reviewing files that changed from the base of the PR and between c4f33ec and 13b0db1.

📒 Files selected for processing (10)

• docs/reference/commands.mdx
• src/lib/adapters/docker/image.ts
• src/lib/agent/base-image.test.ts
• src/lib/agent/base-image.ts
• src/lib/sandbox-base-image-resolution.test.ts
• src/lib/sandbox-base-image.ts
• src/lib/sandbox-base-image/resolution-key.ts
• src/lib/sandbox-base-image/source-identity.ts
• src/lib/sandbox-base-image/types.ts
• test/helpers/base-image-test-harness.ts

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

• src/lib/adapters/docker/image.ts
• src/lib/agent/base-image.ts
• docs/reference/commands.mdx
• src/lib/sandbox-base-image.ts

[prekshivyas]

@cv Exact-head E2E authorization is the only remaining gate for acf926de990376c130a52cefce406e99c072ff6b. Normal CI is green, the PR advisor reports 0 blockers / 0 warnings / 0 suggestions, CodeRabbit is green, and all review threads are resolved. This fork PR selected credential-bearing E2E jobs, so no secrets were exposed and the jobs were intentionally not run. Please approve the approve-credentialed-e2e-skip-for-fork-pr deployment on controller run https://github.com/NVIDIA/NemoClaw/actions/runs/29468870548 to record the exact-head skip.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.