test(e2e): distinguish managed image rollback backup

[senthilr-nv]

Summary

The protected managed-image main E2E counted the stopped managed-bootstrap rollback backup as a second active PR-image container. This change qualifies exactly one running replacement while preserving all-container rollback cleanup, and replaces empty startup-probe failures with the exact failed condition.

Changes

• Use running-only Docker discovery when qualifying the active exact-image replacement.
• Continue including stopped containers when proving failed-bootstrap rollback cleanup.
• Model active qualification and post-rollback cleanup as distinct lifecycle states, including rejection of a retained stopped container.
• Report the exact managed-startup predicate that has not passed, including agent-specific health or version checks.
• Exercise the consuming qualification and cleanup paths with an injected command runner and validate every generated agent probe with the system shell parser.

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: This changes protected live E2E qualification and failure evidence only; production and public behavior are unchanged.
• 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: Running-only selection is limited to active qualification. Failed-bootstrap cleanup still lists every stopped and running labeled container and refuses retained state.
• 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: Reviewed both files in the complete PR diff. The change improves protected live E2E qualification, cleanup evidence, and diagnostics without changing production code, a public command, configuration, workflow, or supported behavior.
• Agent: Codex Desktop

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 — command/result or justification: npx vitest run --project integration test/managed-image-protected-runtime-contract.test.ts passed 32/32; npm run typecheck:cli passed; npm run test-conditionals:scan -- --top 25 passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Linux PR CI is the authoritative broad gate for this protected E2E-only change.
• 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)

Failure evidence

• main E2E run 31524967895, duplicate-container assertion
• main E2E run 31532408138, startup-probe timeout without a condition diagnostic

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved managed image validation with clearer, specific startup failure messages.
  • Added checks for executable availability, configuration, filesystem links, ownership and permissions, certificates, and readiness.
  • Strengthened container image matching and rollback cleanup verification.

• Tests

  • Expanded protected runtime coverage for running and stopped containers.
  • Added validation for image, label, and network matching.
  • Added checks for shell probe failures and completion-file permissions.

[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: 5cf88e2f-9bb9-4e85-83e4-e2f05140a2e8

📥 Commits

Reviewing files that changed from the base of the PR and between 92c9b05 and 136ad51.

📒 Files selected for processing (1)

• test/managed-image-protected-runtime-contract.test.ts

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

• test/managed-image-protected-runtime-contract.test.ts

---

📝 Walkthrough

Walkthrough

The managed image E2E harness now uses typed, injectable command runners. It validates exact running-container images, stopped-container cleanup, and explicit startup probe failures for executable, configuration, filesystem, CA, and readiness checks.

Changes

Managed image runtime validation

Layer / File(s)	Summary
Command runner contracts and discovery scripts/checks/run-managed-image-openshell-e2e.ts	Adds structured command results and injectable runners. Image resolution and container listing support running and stopped containers.
Container qualification and rollback cleanup scripts/checks/run-managed-image-openshell-e2e.ts, test/managed-image-protected-runtime-contract.test.ts	Validates exact image, labels, and network matches. Failed bootstrap checks now require removal of matching labeled and stopped containers.
Startup probe diagnostics and contract tests scripts/checks/run-managed-image-openshell-e2e.ts, test/managed-image-protected-runtime-contract.test.ts	Adds labeled startup checks with explicit failure messages and validates shell syntax, agent diagnostics, ownership, group, and mode requirements.

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

Possibly related PRs

• NVIDIA/NemoClaw#8658: Extends the same managed-image E2E and protected runtime contract paths with command injection, cleanup, and startup-probe validation.
• NVIDIA/NemoClaw#8771: Enhances related managed-image lifecycle E2E helpers and validation paths.

Suggested labels: area: e2e, platform: container

Suggested reviewers: cv

🚥 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 describes the main change: distinguishing the managed-image rollback backup in E2E tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/protected-managed-bootstrap-evidence

---

_{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 136ad51 in the codex/protected-mana... branch remains at 96%, unchanged from commit 71e559b in the main branch.

---

_{Updated August 11, 2026 22:23 UTC}

[coderabbitai]

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 `@test/managed-image-protected-runtime-contract.test.ts`:
- Around line 133-177: Update the test case around assertExactSandboxImage and
assertFailedBootstrapContainerCleanup to model a valid lifecycle: return the
running container for the initial ps -q lookup, then return no containers for
post-rollback ps -aq cleanup. Add a separate focused case where ps -aq returns a
stopped, correctly labeled container and assert that
assertFailedBootstrapContainerCleanup throws, covering both cleanup detection
and the no-container false-positive behavior.

🪄 Autofix

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: 835929bf-f46c-4dd0-8f86-d4aab96bbe86

📥 Commits

Reviewing files that changed from the base of the PR and between 0d51022 and 92c9b05.

📒 Files selected for processing (2)

• scripts/checks/run-managed-image-openshell-e2e.ts
• test/managed-image-protected-runtime-contract.test.ts

[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): Skipped

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.

• established — rollback backup at scripts/checks/run-managed-image-openshell-e2e.ts:770: Keep `rollback backup`; repository lifecycle source and documentation use this term with the same meaning.
• justified — running replacement at scripts/checks/run-managed-image-openshell-e2e.ts:771: Keep `running replacement`; the modifier identifies the lifecycle state that determines running-only qualification.
• justified — managed-bootstrap transaction at scripts/checks/run-managed-image-openshell-e2e.ts:770: Keep `managed-bootstrap transaction`; it names the lifecycle interval that explains the distinct qualification and cleanup checks.

E2E guidance

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

Recommended E2E: managed-image-protected-runtime

Manual-only E2E: managed-image-multiarch-startup
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

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