fix(hermes): accept pinned base platform digest

[chengjiew]

Summary

Hermes sandbox onboarding now accepts official pinned base-image resolutions when Docker normalizes the pulled image to an official platform manifest digest. This prevents ensureAgentBaseImage from rejecting the ghcr.io hermes-sandbox-base digest that the pinned resolver path just selected.

Related Issue

Fixes #6313

Changes

• Updated src/lib/agent/base-image.ts so Hermes final-image validation accepts official hermes-sandbox-base@sha256:* refs only when they came from the pinned remote resolver source.
• Kept local Hermes base allowlisting and explicit/moving-candidate digest checks strict.
• Added a regression case in src/lib/agent/base-image-hermes.test.ts for a pinned official digest that differs from the Dockerfile ARG after RepoDigests normalization.

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 Hermes base-image validation behavior only; no docs or command syntax changed.
• 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: targeted sandbox base-image resolver tests, Hermes base-image tests, CLI build/typecheck, and diff-scoped repository checks passed locally; maintainer review requested via this PR.
• 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
• 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: NPM_CONFIG_CACHE=/tmp/nemoclaw-issue-6313-npm-cache npx vitest run --project cli src/lib/agent/base-image-hermes.test.ts passed; NPM_CONFIG_CACHE=/tmp/nemoclaw-issue-6313-npm-cache npx vitest run --project cli src/lib/agent/base-image-hermes.test.ts src/lib/agent/base-image.test.ts src/lib/sandbox-base-image-resolution.test.ts passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: NPM_CONFIG_CACHE=/tmp/nemoclaw-issue-6313-npm-cache npm run build:cli passed; NPM_CONFIG_CACHE=/tmp/nemoclaw-issue-6313-npm-cache npm run typecheck:cli passed; git diff --check 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: Chengjie Wang chengjiew@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Strengthened Hermes base-image acceptance to validate the expected immutable pinned digest format and ensure resolved “pinned” details match.
  • Improved sandbox base-image resolution to better detect pinned digest refs, propagate pinnedRemoteRef, and fail with pinned_ref_mismatch when the pinned remote ref is stale or divergent.
  • Updated compatibility checks to work with either raw image refs or resolved image details.
• Tests
  • Expanded Hermes and sandbox base image resolution tests for pinned refs, platform-digest resolver returns, stale pin rejection, and added a dedicated Hermes resolver integration test.

[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

Hermes base-image resolution now carries pinned remote ref metadata through sandbox resolution, validates stale pinned hints, and accepts the tracked official pinned digest when Hermes final-image checks receive matching resolved provenance.

Changes

Hermes pinned base-image resolution

Layer / File(s)	Summary
Pinned ref metadata propagation src/lib/sandbox-base-image/types.ts, src/lib/sandbox-base-image/resolution-metadata.ts, src/lib/sandbox-base-image.ts	Adds pinnedRemoteRef to resolution types and metadata, validates pinned metadata against the requested pin, and threads the value through candidate resolution and reuse.
Pinned resolution test coverage src/lib/sandbox-base-image-resolution.test.ts	Updates pinned-resolution assertions to include pinnedRemoteRef, adds a pinned platform-digest case, and rejects stale pinned hints with cache_stale tracing.
Hermes pinned digest acceptance src/lib/agent/base-image.ts, src/lib/agent/base-image-hermes.test.ts	Extends Hermes base-image checks to accept resolved pinned images that match the tracked official digest and updates tests for accepted and rejected Hermes base-image refs.
Hermes resolver integration src/lib/agent/base-image-hermes-resolution.test.ts	Adds an integration test for createAgentSandbox that verifies the staged Hermes Dockerfile, resolution metadata, and Docker inspect calls for the pinned platform digest flow.

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

Suggested labels: bug-fix

Suggested reviewers: cjagwani, jyaunches, brandonpelfrey

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the Hermes base-image fix and mentions the key behavior change: accepting the pinned platform digest.
Linked Issues check	✅ Passed	The PR implements the reported fix by accepting the official pinned Hermes digest only from the pinned resolver path and adds regression coverage.
Out of Scope Changes check	✅ Passed	The extra sandbox-base-image type and metadata changes support the Hermes fix and test coverage, so no unrelated scope is evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/6313_hermes_base_digest_validation

---

_{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 the fix/6313_hermes_base... 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	fix/6313_hermes_base... 63aabf9	+/-
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 fix/6313_hermes_base... branch is 73%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	fix/6313_hermes_base... 63aabf9	+/-
src/lib/shields...nsition-lock.ts	—	87%	—
src/lib/onboard/preflight.ts	—	83%	—
src/lib/actions...all/run-plan.ts	—	81%	—
src/lib/state/o...oard-session.ts	—	81%	—
src/lib/state/sandbox.ts	—	71%	—
src/lib/onboard...er-gpu-patch.ts	—	69%	—
src/lib/shields/index.ts	—	68%	—
src/lib/policy/index.ts	—	66%	—
src/lib/actions...licy-channel.ts	—	63%	—
src/lib/onboard.ts	—	24%	—

---

_{Updated July 06, 2026 18:48 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Fix PRA-5: Regression guard: explicit platform digest override without provenance rejected; then add or justify PRA-T1.
Open items: 1 required · 1 warning · 3 suggestions · 3 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Action checklist

• PRA-5 Fix: Regression guard: explicit platform digest override without provenance rejected in src/lib/agent/base-image-hermes-resolution.test.ts:95
• PRA-3 Resolve or justify: Metadata ref may not match local RepoDigests when fallback used in src/lib/sandbox-base-image.ts:78
• 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
• PRA-1 In-scope improvement: getRepoDigest trace event coverage incomplete for fallback paths in src/lib/sandbox-base-image.ts:78
• PRA-2 In-scope improvement: HERMES_OFFICIAL_BASE_DIGEST_REF regex is namespace/format guard only in src/lib/agent/base-image.ts:85
• PRA-4 In-scope improvement: Docker mock setup duplicated across three test files in src/lib/agent/base-image-hermes-resolution.test.ts:1

Findings index

ID	Severity	Category	Location	Required action
PRA-1	Improvement	security	src/lib/sandbox-base-image.ts:78	Add trace events for the other fallback paths (empty inspectOutput, no matching repoDigest) to improve observability of when the fallback is used
PRA-2	Improvement	security	src/lib/agent/base-image.ts:85	Add a comment clarifying this is a namespace/format guard only; actual existence is validated by dockerImageInspect/pull in the resolver
PRA-3	Resolve/justify	correctness	src/lib/sandbox-base-image.ts:78	Document this intentional design: metadata records the requested pinned ref, not the normalized platform digest, when local proof is unavailable. Ensure callers understand metadata.ref may not match local RepoDigests
PRA-4	Improvement	architecture	src/lib/agent/base-image-hermes-resolution.test.ts:1	Extract shared docker mock helpers to test/helpers/docker-mocks.ts to reduce duplication across the three test files
PRA-5	Required	acceptance	src/lib/agent/base-image-hermes-resolution.test.ts:95	Keep this test as a regression guard. The test passes and correctly validates the security boundary

🚨 Required before merge

Address these before merging unless a maintainer explicitly overrides the advisor with rationale.

PRA-5 Required — Regression guard: explicit platform digest override without provenance rejected

• Location: src/lib/agent/base-image-hermes-resolution.test.ts:95
• Category: acceptance
• Problem: Test 'rejects an explicit platform digest override without pinned provenance' verifies that env var override with platform digest is rejected. This is a critical security boundary: explicit overrides must not bypass the Dockerfile pin
• Impact: If this test regresses, explicit overrides could bypass the Dockerfile pin, allowing untrusted base images
• Required action: Keep this test as a regression guard. The test passes and correctly validates the security boundary
• Expected follow-up: Fix before merge or get explicit maintainer override.
• Verification: Run the test: it sets NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF to platformRef and expects createAgentSandbox to throw
• Missing regression test: Already covered by this test - ensure it remains in the test suite
• Done when: The required change is committed and verification passes: Run the test: it sets NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF to platformRef and expects createAgentSandbox to throw.
• Evidence: base-image-hermes-resolution.test.ts:95-101 sets env var and expects throw with 'does not accept base image ref'

Review findings by urgency: 1 required fix, 1 item to resolve/justify, 3 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-3 Resolve/justify — Metadata ref may not match local RepoDigests when fallback used

• Location: src/lib/sandbox-base-image.ts:78
• Category: correctness
• Problem: getRepoDigest returns the caller's pinned digest when RepoDigests is empty/missing, but the returned ref uses the caller's exact imageRef which may be a manifest-list digest, while the local image actually has a platform digest. This creates a mismatch between resolution metadata (ref=manifest-list) and local image reality (RepoDigests=platform)
• Impact: Metadata ref field records requested pinned ref, not normalized platform digest, when local proof is unavailable. Callers must understand metadata.ref may not match local RepoDigests
• Recommended action: Document this intentional design: metadata records the requested pinned ref, not the normalized platform digest, when local proof is unavailable. Ensure callers understand metadata.ref may not match local RepoDigests
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Trace through resolvePulledCandidate -> getRepoDigest -> finish -> createSandboxBaseImageResolutionMetadata when inspectOutput is empty
• Missing regression test: Test that metadata.ref equals pinnedRemoteRef when RepoDigests unavailable, and metadata validation still passes because local image Id/Os/Architecture match
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Trace through resolvePulledCandidate -> getRepoDigest -> finish -> createSandboxBaseImageResolutionMetadata when inspectOutput is empty.
• Evidence: sandbox-base-image.ts:97-103 returns pinnedDigest with caller's ref; resolution-metadata.ts validates via imageId/Os/Architecture not ref

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

PRA-1 Improvement — getRepoDigest trace event coverage incomplete for fallback paths

• Location: src/lib/sandbox-base-image.ts:78
• Category: security
• Problem: getRepoDigest falls back to caller's pinned digest when RepoDigests parse fails or is missing, but trace event only fires on JSON parse failure, not on empty inspectOutput or no matching repoDigest entry
• Impact: Observability gap: operators cannot distinguish between successful platform digest extraction vs fallback to manifest-list digest via traces alone
• Suggested action: Add trace events for the other fallback paths (empty inspectOutput, no matching repoDigest) to improve observability of when the fallback is used
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Check getRepoDigest function lines 78-105 for trace event coverage; add test asserting trace fires when dockerImageInspectFormat returns empty string or no matching repoDigest entry
• Missing regression test: Test that trace event fires when dockerImageInspectFormat returns empty string or no matching repoDigest entry
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: sandbox-base-image.ts:95 only adds trace event in JSON.parse catch block; lines 97-103 return pinnedDigest without tracing

PRA-2 Improvement — HERMES_OFFICIAL_BASE_DIGEST_REF regex is namespace/format guard only

• Location: src/lib/agent/base-image.ts:85
• Category: security
• Problem: HERMES_OFFICIAL_BASE_DIGEST_REF regex accepts any sha256 digest under the official namespace, but does not validate the digest corresponds to an actual published image (could accept a digest that was never published)
• Impact: Low: fabricated but well-formed digest under official namespace would pass format check but fail later in resolver (dockerImageInspect/pull)
• Suggested action: Add a comment clarifying this is a namespace/format guard only; actual existence is validated by dockerImageInspect/pull in the resolver
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Review HERMES_OFFICIAL_BASE_DIGEST_REF constant and hermesFinalDockerfileAcceptsBase logic; verify resolver rejects non-existent digest
• Missing regression test: Test that a fabricated but well-formed digest under the official namespace is rejected by resolver (dockerImageInspect fails)
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: base-image.ts:85 regex only validates format; resolver validation occurs in resolvePulledCandidate via dockerImageInspect

PRA-4 Improvement — Docker mock setup duplicated across three test files

• Location: src/lib/agent/base-image-hermes-resolution.test.ts:1
• Category: architecture
• Problem: New test file duplicates docker mock setup patterns from base-image-hermes.test.ts and sandbox-base-image-platform-digest.test.ts
• Impact: Maintenance burden: changes to mock patterns require updates in multiple files
• Suggested action: Extract shared docker mock helpers to test/helpers/docker-mocks.ts to reduce duplication across the three test files
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Compare mock setup in base-image-hermes-resolution.test.ts, base-image-hermes.test.ts, and sandbox-base-image-platform-digest.test.ts
• Missing regression test: N/A - code organization improvement
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: All three files use vi.hoisted dockerMocks with similar dockerImageInspect, dockerImageInspectFormat, dockerPull mocks

Simplification opportunities: 1 possible cut, net -80 lines possible

These are safe simplification checks only. Do not remove validation, security controls, data-loss prevention, or required tests.

• PRA-4 delete (src/lib/agent/base-image-hermes-resolution.test.ts:1): Duplicate docker mock boilerplate in base-image-hermes-resolution.test.ts, base-image-hermes.test.ts, sandbox-base-image-platform-digest.test.ts
  • Replacement: Shared test/helpers/docker-mocks.ts with createDockerMocks() factory
  • Net: -80 lines
  • Safety boundary: Mock behavior must remain identical; only deduplicate setup code

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 — Add trace event coverage for getRepoDigest fallback paths (empty inspectOutput, no matching repoDigest). Runtime/sandbox/infrastructure paths need behavioral runtime validation: src/lib/agent/base-image.ts, src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image/resolution-metadata.ts, src/lib/sandbox-base-image/types.ts.
• PRA-T2 Runtime validation — Verify metadata.ref vs local RepoDigests mismatch handling when fallback used. Runtime/sandbox/infrastructure paths need behavioral runtime validation: src/lib/agent/base-image.ts, src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image/resolution-metadata.ts, src/lib/sandbox-base-image/types.ts.
• PRA-T3 Runtime validation — Extract shared docker mock helpers to test/helpers to reduce duplication. Runtime/sandbox/infrastructure paths need behavioral runtime validation: src/lib/agent/base-image.ts, src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image/resolution-metadata.ts, src/lib/sandbox-base-image/types.ts.

Since last review details

Current findings, using the urgency labels above:

PRA-1 Improvement — getRepoDigest trace event coverage incomplete for fallback paths

• Location: src/lib/sandbox-base-image.ts:78
• Category: security
• Problem: getRepoDigest falls back to caller's pinned digest when RepoDigests parse fails or is missing, but trace event only fires on JSON parse failure, not on empty inspectOutput or no matching repoDigest entry
• Impact: Observability gap: operators cannot distinguish between successful platform digest extraction vs fallback to manifest-list digest via traces alone
• Suggested action: Add trace events for the other fallback paths (empty inspectOutput, no matching repoDigest) to improve observability of when the fallback is used
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Check getRepoDigest function lines 78-105 for trace event coverage; add test asserting trace fires when dockerImageInspectFormat returns empty string or no matching repoDigest entry
• Missing regression test: Test that trace event fires when dockerImageInspectFormat returns empty string or no matching repoDigest entry
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: sandbox-base-image.ts:95 only adds trace event in JSON.parse catch block; lines 97-103 return pinnedDigest without tracing

PRA-2 Improvement — HERMES_OFFICIAL_BASE_DIGEST_REF regex is namespace/format guard only

• Location: src/lib/agent/base-image.ts:85
• Category: security
• Problem: HERMES_OFFICIAL_BASE_DIGEST_REF regex accepts any sha256 digest under the official namespace, but does not validate the digest corresponds to an actual published image (could accept a digest that was never published)
• Impact: Low: fabricated but well-formed digest under official namespace would pass format check but fail later in resolver (dockerImageInspect/pull)
• Suggested action: Add a comment clarifying this is a namespace/format guard only; actual existence is validated by dockerImageInspect/pull in the resolver
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Review HERMES_OFFICIAL_BASE_DIGEST_REF constant and hermesFinalDockerfileAcceptsBase logic; verify resolver rejects non-existent digest
• Missing regression test: Test that a fabricated but well-formed digest under the official namespace is rejected by resolver (dockerImageInspect fails)
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: base-image.ts:85 regex only validates format; resolver validation occurs in resolvePulledCandidate via dockerImageInspect

PRA-3 Resolve/justify — Metadata ref may not match local RepoDigests when fallback used

• Location: src/lib/sandbox-base-image.ts:78
• Category: correctness
• Problem: getRepoDigest returns the caller's pinned digest when RepoDigests is empty/missing, but the returned ref uses the caller's exact imageRef which may be a manifest-list digest, while the local image actually has a platform digest. This creates a mismatch between resolution metadata (ref=manifest-list) and local image reality (RepoDigests=platform)
• Impact: Metadata ref field records requested pinned ref, not normalized platform digest, when local proof is unavailable. Callers must understand metadata.ref may not match local RepoDigests
• Recommended action: Document this intentional design: metadata records the requested pinned ref, not the normalized platform digest, when local proof is unavailable. Ensure callers understand metadata.ref may not match local RepoDigests
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Trace through resolvePulledCandidate -> getRepoDigest -> finish -> createSandboxBaseImageResolutionMetadata when inspectOutput is empty
• Missing regression test: Test that metadata.ref equals pinnedRemoteRef when RepoDigests unavailable, and metadata validation still passes because local image Id/Os/Architecture match
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Trace through resolvePulledCandidate -> getRepoDigest -> finish -> createSandboxBaseImageResolutionMetadata when inspectOutput is empty.
• Evidence: sandbox-base-image.ts:97-103 returns pinnedDigest with caller's ref; resolution-metadata.ts validates via imageId/Os/Architecture not ref

PRA-4 Improvement — Docker mock setup duplicated across three test files

• Location: src/lib/agent/base-image-hermes-resolution.test.ts:1
• Category: architecture
• Problem: New test file duplicates docker mock setup patterns from base-image-hermes.test.ts and sandbox-base-image-platform-digest.test.ts
• Impact: Maintenance burden: changes to mock patterns require updates in multiple files
• Suggested action: Extract shared docker mock helpers to test/helpers/docker-mocks.ts to reduce duplication across the three test files
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Compare mock setup in base-image-hermes-resolution.test.ts, base-image-hermes.test.ts, and sandbox-base-image-platform-digest.test.ts
• Missing regression test: N/A - code organization improvement
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: All three files use vi.hoisted dockerMocks with similar dockerImageInspect, dockerImageInspectFormat, dockerPull mocks

PRA-5 Required — Regression guard: explicit platform digest override without provenance rejected

• Location: src/lib/agent/base-image-hermes-resolution.test.ts:95
• Category: acceptance
• Problem: Test 'rejects an explicit platform digest override without pinned provenance' verifies that env var override with platform digest is rejected. This is a critical security boundary: explicit overrides must not bypass the Dockerfile pin
• Impact: If this test regresses, explicit overrides could bypass the Dockerfile pin, allowing untrusted base images
• Required action: Keep this test as a regression guard. The test passes and correctly validates the security boundary
• Expected follow-up: Fix before merge or get explicit maintainer override.
• Verification: Run the test: it sets NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF to platformRef and expects createAgentSandbox to throw
• Missing regression test: Already covered by this test - ensure it remains in the test suite
• Done when: The required change is committed and verification passes: Run the test: it sets NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF to platformRef and expects createAgentSandbox to throw.
• Evidence: base-image-hermes-resolution.test.ts:95-101 sets env var and expects throw with 'does not accept base image ref'

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.

[github-actions]

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 · 7 test follow-ups

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: Acceptance clause
• PRA-T4 Add or justify test follow-up: Acceptance clause
• PRA-T5 Add or justify test follow-up: Acceptance clause
• PRA-T6 Add or justify test follow-up: Acceptance clause
• PRA-T7 Add or justify test follow-up: Acceptance clause

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 — On an aarch64 Docker host with the tracked Hermes Dockerfile pin available, `createAgentSandbox(makeAgent())` stages `ARG BASE_IMAGE=ghcr.io/nvidia/nemoclaw/hermes-sandbox-base@<platform-digest>` from Docker `RepoDigests` and does not throw.. The changed unit and mocked integration tests cover the resolver and Hermes trust-boundary behavior well, but the affected path is sandbox/runtime infrastructure where real Docker platform-manifest normalization can differ from mocks.
• PRA-T2 Runtime validation — With a real local Docker image whose `RepoDigests` include the platform digest for the tracked Hermes manifest-list pin, a non-interactive Hermes onboard reaches sandbox creation without `Hermes final image does not accept base image ref`.. The changed unit and mocked integration tests cover the resolver and Hermes trust-boundary behavior well, but the affected path is sandbox/runtime infrastructure where real Docker platform-manifest normalization can differ from mocks.
• PRA-T3 Acceptance clause — Steps to Reproduce: 1. NemoClaw v0.0.74 installed, gateway healthy (`NEMOCLAW_GATEWAY_PORT=18080`). — add test evidence or identify existing coverage. The PR does not alter gateway health handling; this environmental setup clause is outside the changed base-image validation code.
• PRA-T4 Acceptance clause — Steps to Reproduce: 2. Run a non-interactive hermes onboard with a valid NVIDIA API key: `NEMOCLAW_GATEWAY_PORT=18080 nemoclaw onboard --agent hermes --non-interactive --yes --yes-i-accept-third-party-software --name t811143-hermes --no-sandbox-gpu`. — add test evidence or identify existing coverage. The changed code covers the Hermes base-image validation invoked during onboard, and tests use `createAgentSandbox(makeAgent())`; the full non-interactive onboard command is a runtime flow not executed in the static review.
• PRA-T5 Acceptance clause — Steps to Reproduce: 3. Wait for step `[6/8] Creating sandbox`. — add test evidence or identify existing coverage. `createAgentSandbox()` is the changed sandbox-creation surface and is covered by the new Hermes resolver test; the complete onboard state-machine step is not run by the diff-local tests shown.
• PRA-T6 Acceptance clause — Expected Result: The official `hermes-sandbox-base` digest resolved by NemoClaw itself passes validation; the hermes sandbox is created and reaches Ready. — add test evidence or identify existing coverage. The official resolver-produced platform digest passes the changed validation in unit/integration-style mocked tests. Full sandbox Ready state requires runtime validation beyond static review and is captured as a test-depth follow-up.
• PRA-T7 Acceptance clause — No sandbox is registered afterwards. — add test evidence or identify existing coverage. Registry side effects are outside this diff; the changed code prevents the base-image validation throw before sandbox creation but does not directly modify registry registration.

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.

[github-actions]

E2E Advisor Recommendation

Required E2E: cloud-onboard, hermes-e2e, rebuild-hermes-stale-base, sandbox-rebuild
Optional E2E: rebuild-hermes, runtime-overrides

Dispatch hint: cloud-onboard,hermes-e2e,rebuild-hermes-stale-base,sandbox-rebuild

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard (high): Required because shared sandbox base-image resolution can affect full hosted OpenClaw onboarding and sandbox creation with the production CLI.
• hermes-e2e (high): Required because Hermes base-image acceptance and staged Dockerfile rewriting changed; this proves install.sh onboards Hermes and the real hosted assistant runtime still works.
• rebuild-hermes-stale-base (high): Required direct coverage for Hermes stale base cache refresh and rebuild metadata behavior, which is the closest live E2E to the new pinned platform digest/provenance handling.
• sandbox-rebuild (high): Required because the shared base-image resolver affects non-Hermes sandbox lifecycle; this verifies rebuild preserves state and refreshes registry metadata through real OpenShell sandbox operations.

Optional E2E

• rebuild-hermes (high): Useful adjacent confidence for the regular old-Hermes-sandbox rebuild path, distinct from the stale-base cache variant.
• runtime-overrides (medium): Useful deployment-image confidence after base image resolver changes, especially to catch production sandbox image runtime/entrypoint regressions.

New E2E recommendations

• sandbox base image platform digest resolution (high): Existing live jobs exercise onboarding/rebuild outcomes but do not explicitly prove, against real Docker/GHCR metadata on amd64 and arm64, that a Dockerfile-pinned manifest-list digest resolves to a platform RepoDigest while retaining pinnedRemoteRef provenance.
  • Suggested test: Add a selective live E2E target that pulls the pinned sandbox and Hermes base refs, validates the platform RepoDigest/provenance metadata, and verifies staged Dockerfiles use the trusted platform digest on both amd64 and arm64 runners.

Dispatch hint

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

[github-actions]

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 shared sandbox base-image resolution, digest metadata, and resolution typing used by normal OpenClaw Docker onboarding. This live-supported typed target is the smallest baseline OpenClaw path that exercises that surface.
  • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-openclaw
• ubuntu-repo-cloud-langchain-deepagents-code: The PR changes agent/base-image integration and shared resolution metadata. This live-supported typed target exercises a non-Hermes agent sandbox path that uses agent base-image resolution during onboarding/lifecycle coverage.
  • 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

• src/lib/agent/base-image.ts
• src/lib/sandbox-base-image.ts
• src/lib/sandbox-base-image/resolution-metadata.ts
• src/lib/sandbox-base-image/types.ts

[coderabbitai]

🧹 Nitpick comments (2)

src/lib/agent/base-image-hermes.test.ts (1)

69-80: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Consider adding boundary negative-case coverage.

To pin down the acceptance boundary introduced in hermesFinalDockerfileAcceptsBase, consider adding two negative cases alongside this one: (1) source: "pinned" with a ref that doesn't match the official Hermes digest pattern (e.g., wrong image name), and (2) a matching official digest pattern with a non-"pinned" source (e.g., "latest"). Both should still be rejected, and asserting this would guard against future regressions widening the trust boundary.

🤖 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/agent/base-image-hermes.test.ts` around lines 69 - 80, The current
base-image acceptance test only covers the happy path for
hermesFinalDockerfileAcceptsBase, so add two negative assertions in
base-image-related tests around ensureAgentBaseImage and
resolveSandboxBaseImageMock: one where source is "pinned" but the ref does not
match the official Hermes digest pattern, and another where the ref matches the
Hermes digest pattern but source is not "pinned" (for example "latest"). Both
cases should assert rejection to keep the trust boundary enforced.

src/lib/agent/base-image.ts (1)

32-34: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reuse the new constant to avoid duplicating the digest regex.

getHermesPinnedRemoteBaseRef (line 101, unchanged) hardcodes an identical inline regex literal for the same official-digest pattern now captured in HERMES_OFFICIAL_BASE_DIGEST_REF. Since this PR introduces the shared constant, consolidating avoids future drift between the two patterns.

♻️ Proposed fix to reuse the shared constant

   if (
     !pinnedRef ||
-    !/^ghcr\.io\/nvidia\/nemoclaw\/hermes-sandbox-base@sha256:[0-9a-f]{64}$/.test(pinnedRef)
+    !HERMES_OFFICIAL_BASE_DIGEST_REF.test(pinnedRef)
   ) {

🤖 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/agent/base-image.ts` around lines 32 - 34, Reuse the shared digest
pattern constant instead of duplicating the inline regex in
getHermesPinnedRemoteBaseRef. Update the Hermes base-image logic in
src/lib/agent/base-image.ts so the official digest check uses
HERMES_OFFICIAL_BASE_DIGEST_REF rather than a separate regex literal, keeping
the pinned-ref validation aligned with the constant already defined alongside
HERMES_MCP_RUNTIME_PROBE_OK.

🤖 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 `@src/lib/agent/base-image-hermes.test.ts`:
- Around line 69-80: The current base-image acceptance test only covers the
happy path for hermesFinalDockerfileAcceptsBase, so add two negative assertions
in base-image-related tests around ensureAgentBaseImage and
resolveSandboxBaseImageMock: one where source is "pinned" but the ref does not
match the official Hermes digest pattern, and another where the ref matches the
Hermes digest pattern but source is not "pinned" (for example "latest"). Both
cases should assert rejection to keep the trust boundary enforced.

In `@src/lib/agent/base-image.ts`:
- Around line 32-34: Reuse the shared digest pattern constant instead of
duplicating the inline regex in getHermesPinnedRemoteBaseRef. Update the Hermes
base-image logic in src/lib/agent/base-image.ts so the official digest check
uses HERMES_OFFICIAL_BASE_DIGEST_REF rather than a separate regex literal,
keeping the pinned-ref validation aligned with the constant already defined
alongside HERMES_MCP_RUNTIME_PROBE_OK.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e43a32e2-ad0e-4c5d-a763-5ea7fdd8b2d8

📥 Commits

Reviewing files that changed from the base of the PR and between f0d2549 and e0aac4b.

📒 Files selected for processing (2)

• src/lib/agent/base-image-hermes.test.ts
• src/lib/agent/base-image.ts

[cv]

Maintainer follow-up for the current Advisor evidence request:

• 822414e makes the resolver integration fixture exercise the reported Linux/aarch64 path (linux/aarch64), verifies Docker-normalized Architecture: arm64, and asserts baseImageResolutionMetadata.architecture is arm64. The focused base-image suites pass 24/24.
• A base-image validation failure cannot publish a fresh registry row: ensureAgentBaseImage runs before build-context staging in createAgentSandbox; onboarding then creates the sandbox and waits for readiness before registerSandbox; the machine handler likewise waits for createSandbox to resolve before updateSandboxRegistry.

This is test/evidence closure only; no production behavior change or registry-risk waiver is needed.

[cv]

Maintainer accepted-scope decision for current-head PRA-1 (63aabf9):

The defect and changed crash boundary are narrow. resolveSandboxBaseImage() starts from the immutable Hermes Dockerfile manifest-list pin and can return the locally proven Docker RepoDigests platform digest. On v0.0.74, ensureAgentBaseImage() then passed only that normalized ref to hermesFinalDockerfileAcceptsBase() and rejected it before createAgentSandbox() could stage the sandbox build context. This PR carries the resolver source and pinnedRemoteRef provenance into that acceptance check. It does not change dashboard-port assignment, OpenShell sandbox-create launch, Ready polling, or registry persistence.

Changed-boundary evidence is now explicit:

• src/lib/agent/base-image-hermes-resolution.test.ts executes the resolver → ensureAgentBaseImage() → createAgentSandbox() staging seam with Docker modeled as linux/aarch64, the exact reporter platform digest, Architecture: arm64, matching pinned provenance, and the normalized digest written into the staged Hermes Dockerfile. It also proves an explicit platform-digest override without pinned provenance is rejected.
• src/lib/agent/base-image-hermes.test.ts covers the trust-boundary negatives for wrong namespace, wrong source, stale pinned provenance, and an untrusted digest.
• test/e2e/live/hermes-e2e.test.ts is the existing full-flow contract for fresh non-interactive Hermes install/onboard. It proceeds through nemoclaw list and status, Hermes health, configuration state, and live inference. This RC fix deliberately does not duplicate that opt-in runtime contract inside a resolver unit harness.

The Ready/create/registry ordering is unchanged and excludes a fresh-row leak from this failure:

1. createAgentSandbox() calls ensureAgentBaseImage() before creating its temporary build context.
2. createSandboxWithBaseImageResolution() stages that context before streamSandboxCreate() is called.
3. The same function waits for waitForCreatedSandboxReadyWithTrace() to report Ready before calling sandboxRegistration.registerCreatedSandbox().
4. SandboxStateFlow.createAndRecordSandbox() likewise awaits createSandbox() before calling updateSandboxRegistry().

Therefore a base-image validation exception occurs before OpenShell create and before every fresh registry writer. The issue report also describes clean failure/no registry pollution as observed v0.0.74 reproduction context, not behavior introduced or altered by this patch.

For the v0.0.75 RC, I explicitly accept the focused aarch64 resolver/staging regression coverage as sufficient for the changed boundary. The broader onboard→Ready contract and registry ordering are unchanged and already have their canonical full-flow/runtime coverage. No additional full-onboard harness is required in this PR, and PRA-1 is accepted as resolved on that basis.