fix(e2e): pin Deep Agents Code base qualification

[cv]

Summary

Deep Agents Code qualification now consumes the immutable base-image contract from the selected trusted publication run instead of resolving the mutable :latest alias. The gate binds publication provenance, proves both required Python imports, passes the exact digest to onboarding, and records candidate/base provenance in uploaded E2E evidence.

Related Issue

Fixes #9049

Changes

• Export the trusted base-image publication run identity and download its exact Deep Agents Code contract.
• Validate the contract image, digest, platforms, source revision, run identity, and both deepagents and deepagents_code imports before live E2E runs.
• Pass only the validated image@sha256 reference to Deep Agents Code onboarding and upload the base contract with the target evidence.
• Retain immutable base contracts for 90 days so later qualification can consume the selected publication receipt.
• Add focused contract, workflow-boundary, negative, ordering, evidence, and retention tests.

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 modifications)

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: This changes internal E2E qualification and artifact evidence only; it does not change a user command, configuration, default, error, or supported runtime behavior.
• 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: Codex Desktop reviewed exact commit deaaa94f394b7f5c367f607f531a56b2317f161d against all nine repository security categories. The workflow keeps actions: read and contents: read; consumes only the canonical repository's pinned artifact action and exact publication run; strictly validates every contract field and digest; runs the import proof without network, capabilities, writable root filesystem, or privilege escalation; propagates failures; emits no credentials; and records only public image provenance. No new dependency, authentication, authorization, cryptographic, network-policy, credential, logging, or privilege risk was found. Negative tests reject mutable references, wrong source/run provenance, malformed fields, missing imports, workflow drift, missing evidence, and unsafe ordering.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Internal Actions qualification, immutable base-image contract validation, 90-day receipt retention, and E2E support tests do not change a user-facing command, configuration, default, error, or supported runtime behavior.
• Agent: Codex Desktop documentation writer

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project e2e-support test/e2e/support/base-image-publication.test.ts test/e2e/support/base-image-publication-workflow-boundary.test.ts test/e2e/support/dcode-base-image-contract.test.ts test/e2e/support/dcode-profile-import-gate-workflow-boundary.test.ts (92 tests); the current trusted publication contract also passed both imports from its immutable arm64 image on this host.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• New Features

  • Added validation for immutable Deep Agents Code base-image contracts, including image digests, publication metadata, platform references, and required runtime imports.
  • E2E runs now use validated base-image references and record per-target image evidence.
  • Publication outputs now include verified run metadata.

• Bug Fixes

  • Improved safeguards against mutable, mismatched, incomplete, or unauthorized base-image contracts.

• Chores

  • Base-image contract artifacts are now retained for 90 days.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

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: 020977c4-c6ed-4907-a910-ffff2d203a21

📥 Commits

Reviewing files that changed from the base of the PR and between 8566aa6 and deaaa94.

📒 Files selected for processing (9)

• .github/actions/publish-base-image-manifest/action.yaml
• .github/workflows/e2e.yaml
• ci/source-shape-test-budget.json
• test/e2e/support/base-image-publication-workflow-boundary.test.ts
• test/e2e/support/base-image-publication.test.ts
• test/e2e/support/dcode-base-image-contract.test.ts
• tools/e2e/base-image-publication.mts
• tools/e2e/dcode-base-image-contract.mts
• tools/e2e/operations-workflow-boundary.mts

---

📝 Walkthrough

Walkthrough

The E2E workflow now validates an immutable Deep Agents Code base-image contract, propagates its digest-pinned reference, records evidence, and requires publication for trusted controller runs. Publication outputs and contract validation tests cover run identity, metadata, image digests, and required imports.

Changes

Deep Agents Code base-image qualification

Layer / File(s)	Summary
Publication identity and contract artifact .github/actions/publish-base-image-manifest/action.yaml, tools/e2e/base-image-publication.mts, test/e2e/support/base-image-publication.test.ts, test/e2e/support/base-image-publication-workflow-boundary.test.ts, ci/source-shape-test-budget.json	Publication now writes verified run ID, attempt, and commit outputs. The contract artifact retention period is 90 days. Boundary tests verify pinned upload behavior and required artifact settings.
Base-image contract validation tools/e2e/dcode-base-image-contract.mts, test/e2e/support/dcode-base-image-contract.test.ts	The validator checks contract fields, immutable image and platform digests, source revision, publication metadata, and required imports. Docker import checks use restricted execution settings.
Workflow propagation and evidence .github/workflows/e2e.yaml, tools/e2e/operations-workflow-boundary.mts, test/e2e/support/base-image-publication-workflow-boundary.test.ts	Trusted controller runs require publication. The workflow validates and propagates the contract and digest-pinned reference, injects the reference into live E2E jobs, records evidence, and uploads it. Drift tests cover the workflow boundary.
Estimated code review effort: 4 (Complex)	~45 minutes

Mergeability Score: ⚪ Minimal · up to deaaa

The PR pins internal E2E qualification to validated immutable base-image provenance and records the associated evidence. No actionable merge-blocking risk remains at the current head.

Sequence Diagram(s)

sequenceDiagram
  participant BasePublication as base-image-publication
  participant E2EWorkflow as e2e.yaml
  participant ContractValidator as dcode-base-image-contract
  participant LiveE2E as live E2E jobs
  BasePublication->>E2EWorkflow: publish run metadata and contract outputs
  E2EWorkflow->>ContractValidator: download and validate immutable contract
  ContractValidator-->>E2EWorkflow: validated contract and digest-pinned reference
  E2EWorkflow->>LiveE2E: inject base reference and record contract evidence
  LiveE2E-->>E2EWorkflow: upload dcode-base-image.json with E2E artifacts

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8632 — Both changes modify base-image publication and E2E workflow validation.
• NVIDIA/NemoClaw#8950 — Both changes cover Deep Agents Code base-image validation and contract tests.

Suggested labels: area: e2e, area: security, bug-fix

Suggested reviewers: prekshivyas, brandonpelfrey

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: pinning the Deep Agents Code base image for E2E qualification.
Linked Issues check	✅ Passed	The changes address immutable digest pinning, contract validation, import checks, provenance evidence, and workflow propagation required by issue [#9049].
Out of Scope Changes check	✅ Passed	All changes support immutable Deep Agents Code base-image qualification, validation, workflow enforcement, evidence, retention, or related tests.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-9049

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit deaaa94 in the codex/fix-9049 branch remains at 96%, unchanged from commit 8566aa6 in the main branch.

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

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 terminology decisions differ; normalized E2E selections differ; severity counts match.

3 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• DCode at .github/workflows/e2e.yaml:107: selected only by the second-opinion lane as established.
• publication run at test/e2e/support/dcode-base-image-contract.test.ts:51: selected only by the second-opinion lane as established.
• immutable base contract at ci/source-shape-test-budget.json:106: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — immutable base contract at test/e2e/support/base-image-publication-workflow-boundary.test.ts:96: Use immutable base contract when the digest-bound retention property distinguishes it from a mutable base contract reference.
• established — base contract at .github/workflows/e2e.yaml:159: Keep base contract for the established managed base-image contract concept. Name Deep Agents Code where the consumer matters.
• established — publication identity at test/e2e/support/base-image-publication.test.ts:541: Keep publication identity for the selected run attributes and use image reference for the digest-bound image location.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: cloud-onboard, security-posture, cloud-inference
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

1 optional E2E recommendation

• ubuntu-repo-cloud-langchain-deepagents-code

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.