fix(cli): preserve platform base resolution metadata (#9400)

<!-- markdownlint-disable MD041 -->
## Summary

Pass the Deep Agents Code publication contract's validated `linux/amd64`
platform reference into onboarding instead of its multi-platform index
reference. The complete index contract remains the publication evidence,
while the runtime now receives the exact platform digest that its
evidence gate already requires.

## Related Issue

Fixes #9386

## Changes

- Export `platformReferences["linux/amd64"]` as the existing
`dcode_base_ref` workflow output while retaining the complete
multi-platform contract as evidence.
- Run the locked-down import proof against that same exact platform
reference.
- Require the live DCode evidence environment to match the validated
platform reference and add regression coverage that rejects the
publication index.

## 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:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: the publication
contract already validates both immutable platform references. This
change uses its exact `linux/amd64` reference for the existing import
proof and onboarding output, preserves the full contract as evidence,
and makes the live evidence parser reject the index reference.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## 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

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — `vitest run --project e2e-support
test/e2e/support/dcode-base-image-contract.test.ts
test/e2e/support/dcode-base-image-runtime-evidence.test.ts
test/e2e/support/base-image-publication-workflow-boundary.test.ts
test/e2e/support/e2e-operations-workflow-boundary.test.ts` (135 passed)
- [x] Applicable broad gate passed — `npm run test-size:check` (22
passed) and `npm run build:cli` passed
- [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)

---
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>


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

## Summary by CodeRabbit

- **Improvements**
- Onboarding now uses a platform-specific base image reference for
`linux/amd64`.
- Docker validation and runtime evidence checks consistently verify the
selected platform reference.
- Published image contract output now reports the platform-specific base
reference while preserving complete contract details.

- **Tests**
- Added end-to-end coverage for platform reference selection, Docker
invocation, and rejection of generic publication references.

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

---------

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

Author: ericksoa

test/e2e/live/dcode-base-image-runtime-evidence.ts

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import { readSandboxBaseImageResolutionMetadata } from "../../../src/lib/sandbox-base-image/label-codec.ts";
 import type { SandboxBaseImageResolutionMetadata } from "../../../src/lib/sandbox-base-image/types.ts";
 import {
+  DCODE_BASE_IMAGE_ONBOARD_PLATFORM,
   type DcodeBaseImageContract,
   type DcodePlatform,
   parseDcodeBaseImageContract,
@@ -76,9 +77,12 @@ export function parseDcodeBaseImagePublicationEvidence(
     );
   }
   const contract = parseDcodeBaseImageContract(evidence.base);
-  if (requireDcodeBaseImageReference(environment) !== contract.reference) {
+  if (
+    requireDcodeBaseImageReference(environment) !==
+    contract.platformReferences[DCODE_BASE_IMAGE_ONBOARD_PLATFORM]
+  ) {
     throw new Error(
-      "Deep Agents Code onboarding reference does not match the published base contract",
+      `Deep Agents Code onboarding reference does not match the published ${DCODE_BASE_IMAGE_ONBOARD_PLATFORM} base contract`,
     );
   }
   return contract;

test/e2e/support/dcode-base-image-contract.test.ts

@@ -1,9 +1,15 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { describe, expect, it, vi } from "vitest";
 
 import {
+  DCODE_BASE_IMAGE_ONBOARD_PLATFORM,
+  main,
   validateDcodeBaseImageContract,
   validateDcodeBaseImageImports,
 } from "../../../tools/e2e/dcode-base-image-contract.mts";
@@ -57,15 +63,16 @@ describe("Deep Agents Code E2E base contract", () => {
     expect(() => validateDcodeBaseImageContract(contract(override), expected)).toThrow(message);
   });
 
-  it("proves both imports from the exact digest in a locked-down container (#9049)", () => {
+  it("proves both imports from the selected platform digest in a locked-down container (#9386)", () => {
     const runDocker = vi.fn(() => "nemoclaw-dcode-base-imports-ok");
-    validateDcodeBaseImageImports(`${IMAGE}@${DIGEST}`, runDocker);
+    const platformReference = `${IMAGE}@sha256:${"c".repeat(64)}`;
+    validateDcodeBaseImageImports(platformReference, runDocker);
 
     expect(runDocker).toHaveBeenCalledWith([
       "run",
       "--rm",
       "--platform",
-      "linux/amd64",
+      DCODE_BASE_IMAGE_ONBOARD_PLATFORM,
       "--network",
       "none",
       "--cap-drop",
@@ -77,13 +84,45 @@ describe("Deep Agents Code E2E base contract", () => {
       "999:999",
       "--entrypoint",
       "/opt/venv/bin/python3",
-      `${IMAGE}@${DIGEST}`,
+      platformReference,
       "-I",
       "-c",
       'import deepagents; import deepagents_code; print("nemoclaw-dcode-base-imports-ok")',
     ]);
   });
 
+  it("emits the selected platform reference while preserving the full contract (#9386)", () => {
+    const directory = mkdtempSync(join(tmpdir(), "nemoclaw-dcode-base-contract-"));
+    const contractPath = join(directory, "contract.json");
+    const outputPath = join(directory, "github-output");
+    const contractValue = contract();
+    const platformReference = `${IMAGE}@sha256:${"c".repeat(64)}`;
+    const runDocker = vi.fn(() => "nemoclaw-dcode-base-imports-ok");
+    try {
+      writeFileSync(contractPath, JSON.stringify(contractValue), "utf8");
+
+      main(
+        [contractPath],
+        {
+          GITHUB_OUTPUT: outputPath,
+          PUBLICATION_HEAD_SHA: HEAD_SHA,
+          PUBLICATION_RUN_ATTEMPT: String(RUN_ATTEMPT),
+          PUBLICATION_RUN_ID: String(RUN_ID),
+        },
+        runDocker,
+      );
+
+      const [baseReferenceOutput, contractOutput] = readFileSync(outputPath, "utf8")
+        .trim()
+        .split("\n");
+      expect(baseReferenceOutput).toBe(`base_ref=${platformReference}`);
+      expect(JSON.parse(String(contractOutput).slice("contract=".length))).toEqual(contractValue);
+      expect(runDocker).toHaveBeenCalledWith(expect.arrayContaining([platformReference]));
+    } finally {
+      rmSync(directory, { force: true, recursive: true });
+    }
+  });
+
   it("rejects missing or noisy import evidence (#9049)", () => {
     expect(() => validateDcodeBaseImageImports(`${IMAGE}@${DIGEST}`, () => "")).toThrow(
       /did not prove both required imports/u,

test/e2e/support/dcode-base-image-runtime-evidence.test.ts

@@ -23,7 +23,7 @@ const PUBLICATION_REVISION = "e".repeat(40);
 
 function publicationEnvironment(overrides: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
   return {
-    [DCODE_BASE_IMAGE_ENV]: INDEX_REFERENCE,
+    [DCODE_BASE_IMAGE_ENV]: AMD64_REFERENCE,
     ...overrides,
   };
 }
@@ -99,15 +99,15 @@ describe("Deep Agents Code published base runtime evidence", () => {
     });
   });
 
-  it("rejects a valid official reference that differs from the publication contract", () => {
+  it("rejects the publication index instead of the validated platform reference (#9386)", () => {
     expect(() =>
       parseDcodeBaseImagePublicationEvidence(
         publicationEvidence(),
         publicationEnvironment({
-          [DCODE_BASE_IMAGE_ENV]: `${DCODE_BASE_IMAGE}@sha256:${"f".repeat(64)}`,
+          [DCODE_BASE_IMAGE_ENV]: INDEX_REFERENCE,
         }),
       ),
-    ).toThrow(/does not match the published base contract/);
+    ).toThrow(/does not match the published linux\/amd64 base contract/);
   });
 
   it("prefers the selected manual candidate over the trusted workflow SHA", () => {
@@ -192,7 +192,7 @@ describe("Deep Agents Code published base runtime evidence", () => {
       loadDcodeBaseImagePublicationEvidence(
         DCODE_BASE_IMAGE_TARGET_ID,
         `/missing-dcode-base-evidence-${process.pid}.json`,
-        { [DCODE_BASE_IMAGE_ENV]: INDEX_REFERENCE },
+        { [DCODE_BASE_IMAGE_ENV]: AMD64_REFERENCE },
       ),
     ).toBeUndefined();
   });
@@ -204,7 +204,7 @@ describe("Deep Agents Code published base runtime evidence", () => {
         `/missing-dcode-base-evidence-${process.pid}.json`,
         {
           GITHUB_ACTIONS: "true",
-          [DCODE_BASE_IMAGE_ENV]: INDEX_REFERENCE,
+          [DCODE_BASE_IMAGE_ENV]: AMD64_REFERENCE,
         },
       ),
     ).toThrow(/GitHub Actions run is missing published base evidence/);

tools/e2e/dcode-base-image-contract.mts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 const AGENT = "langchain-deepagents-code";
 const IMAGE = "ghcr.io/nvidia/nemoclaw/langchain-deepagents-code-sandbox-base";
 const PLATFORMS = ["linux/amd64", "linux/arm64"] as const;
+export const DCODE_BASE_IMAGE_ONBOARD_PLATFORM = "linux/amd64" as const;
 const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const SHA_PATTERN = /^[0-9a-f]{40}$/u;
 const IMPORT_MARKER = "nemoclaw-dcode-base-imports-ok";
@@ -120,10 +121,7 @@ export function validateDcodeBaseImageContract(
   if (contract.sourceRevision !== expected.headSha) {
     throw new Error("base contract source revision does not match the selected publication");
   }
-  if (
-    contract.run.id !== expected.runId ||
-    contract.run.attempt !== expected.runAttempt
-  ) {
+  if (contract.run.id !== expected.runId || contract.run.attempt !== expected.runAttempt) {
     throw new Error("base contract run does not match the selected publication");
   }
   return contract;
@@ -172,7 +170,11 @@ function requiredInteger(value: string | undefined, label: string): number {
   return positiveInteger(Number(value), label);
 }
 
-export function main(argv = process.argv.slice(2), env = process.env): void {
+export function main(
+  argv = process.argv.slice(2),
+  env = process.env,
+  runDocker?: (args: string[]) => string,
+): void {
   if (argv.length !== 1) throw new Error("expected one managed base contract path");
   const outputPath = env.GITHUB_OUTPUT ?? "";
   if (!outputPath || outputPath.includes("\r") || outputPath.includes("\n")) {
@@ -186,10 +188,11 @@ export function main(argv = process.argv.slice(2), env = process.env): void {
       headSha: env.PUBLICATION_HEAD_SHA ?? "",
     },
   );
-  validateDcodeBaseImageImports(contract.reference);
+  const baseReference = contract.platformReferences[DCODE_BASE_IMAGE_ONBOARD_PLATFORM];
+  validateDcodeBaseImageImports(baseReference, runDocker);
   appendFileSync(
     outputPath,
-    `base_ref=${contract.reference}\ncontract=${JSON.stringify(contract)}\n`,
+    `base_ref=${baseReference}\ncontract=${JSON.stringify(contract)}\n`,
     "utf8",
   );
 }