feat(cua): add first-class lifecycle runtime

[jyaunches]

Summary

Consolidate the first-class CUA contract, target/task/security lifecycle, GPU qualification consumer, and the smallest NemoCUA runtime/onboarding slice into one PR on current main. NemoClaw now exposes a public host lifecycle through operator-owned adapters and invokes NemoCUA directly inside the existing OpenShell sandbox, without creating a nested NemoCUA sandbox.

The checked-in release tuple remains fail closed as awaiting-live-qualification. This draft does not claim that a live image-backed CUA has passed qualification; the exact external completion gate is recorded below.

Related Issue

Fixes #7750
Fixes #7751
Fixes #7752
Fixes #7754
Relates to #7753
Relates to #7755
Relates to #6015
Supersedes #8169

Product scope decision: #7750 (comment)

Changes

• Define the versioned, secret-free CUA lifecycle contract and schemas for runtime readiness, target attachment, security admission, task control/results, evidence indexes, and bounded failures.
• Expose public target, security, and task commands through absolute, operator-owned host adapters that run without a shell and do not leak credentials, private task input, target authority, or raw diagnostics into public state.
• Add the nemocua agent manifest, pinned runtime artifact manifest, digest-pinned base-image handoff, deny-default policy additions, and nemocua-runtime interactive|headless|version|smoke wrapper.
• Map NemoCUA onboarding and resumed setup into the existing sandbox lifecycle, validate the runtime files/version/managed inference route, and record qualified runtime readiness through the normal registry boundary.
• Reject mutable or mismatched NemoCUA runtime-image references and reject lifecycle use until the exact pinned artifact tuple reports qualified.
• Add the bounded GPU qualification environment/receipt consumer while keeping image construction, target provisioning, live scenario execution, and receipt production outside the NemoClaw repository.
• Document the exact public CLI grammar, artifact inputs, adapter boundary, fail-closed qualification state, and prohibition on nemocua sandbox create inside NemoClaw.

Public lifecycle mapping

NEMOCLAW_NEMOCUA_RUNTIME_IMAGE_REF='<repository>@sha256:c1a577fc8f69071642b97706130df26abd8a89b8bd429a9ef37abf0ccd634e0b' \
  nemoclaw onboard --agent nemocua --name my-cua

nemoclaw my-cua cua target attach --adapter /absolute/path/to/target-adapter \
  --target-manifest ./target-manifest.json --json
nemoclaw my-cua cua target status --json
nemoclaw my-cua cua security verify --adapter /absolute/path/to/security-verifier --json
nemoclaw my-cua cua security status --json
nemoclaw my-cua cua task start --adapter /absolute/path/to/task-adapter \
  --task-id task-1 --mode headless --input-file ./task.txt --json
nemoclaw my-cua cua task status --adapter /absolute/path/to/task-adapter \
  --task-id task-1 --json
nemoclaw my-cua cua task result --adapter /absolute/path/to/task-adapter \
  --task-id task-1 --json

Inside the existing sandbox, the image invokes /app/run.py or /app/run_with_harness.py through nemocua-runtime; it never invokes nemocua sandbox create.

Pinned image inputs

Input	Exact identity
NemoCUA CLI	0.0.20-dev-v3; nemocua_linux_amd64.tar.gz; size 12322325; SHA-256 702d93c4fc01ba4aafdd23daaf17fd25cea8f7deab3f1caa1c91ef047f4778aa
NVLumina runtime image	v0.0.5; linux/amd64; digest sha256:c1a577fc8f69071642b97706130df26abd8a89b8bd429a9ef37abf0ccd634e0b
NemoCUA target services	0.0.66-dev-v29; nemocua-services-linux-x86_64-v0.0.66-dev-v29.tar.gz; size 183706364; SHA-256 6d731e02226b364daa61d3521e5903b86f1e4260e41d330b1a7daed5c3ae3b01

Remaining qualification gate

An artifact owner must stage and test the exact CLI, NVLumina image, and target-services tuple together in an image-backed live CUA scenario, produce the checked-in environment and scenario receipt shapes, and publish an immutable runtime image reference ending in the declared digest. After that evidence passes, agents/nemocua/runtime-artifacts.json can change from awaiting-live-qualification to qualified; until then onboarding and all public CUA lifecycle commands deliberately return unavailable.

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:
• 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: The cumulative focused review from feat(cua): enforce security boundaries #7783 covers the adapter, credential, policy, task-admission, identity-binding, lifecycle-invalidation, and private-material boundaries. The consolidation adds fail-closed pinned-runtime onboarding and regression coverage without widening adapter authority.
• 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: docs/reference/commands.mdx, src/lib/cua/contract.md, and test/e2e/README.md; independent review verified the public CUA grammar, exact artifact identities, fail-closed qualification state, direct in-sandbox runtime invocation, and absence of nested NemoCUA sandbox creation. npm run docs, CLI type-check, repository checks, and focused tests passed.
• Agent: Codex Desktop — NemoCUA onboarding, public CUA lifecycle, artifact handoff, and qualification boundary

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
• Targeted behavior tests pass for the current change set — 175 assertions passed in the 21-file focused run; the sole load-sensitive CLI lifecycle case exceeded the combined 60-second timeout, then its file passed 4/4 alone with a 120-second timeout. The affected onboarding group passed 28/28, including both new NemoCUA regressions.
• Applicable broad gate passed — GitHub CI supplies the broad test and coverage lanes for this cumulative runtime/test-harness 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) — the build passed with 0 errors and 5 existing Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

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

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f81d1ede-e58b-4727-8d00-b6f753c7e36d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{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 7a72c05 in the codex/cua-first-clas... branch remains at 96%, unchanged from commit 7475238 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 7a72c05 in the codex/cua-first-clas... branch is 80%. The coverage in commit d756d15 in the main branch is 81%.

Show a code coverage summary of the most impacted files.

File	main d756d15	codex/cua-first-clas... 7a72c05	+/-
src/lib/onboard...strap/docker.ts	60%	66%	+6%
src/lib/cua/run...me-readiness.ts	0%	55%	+55%
src/lib/cua/schema.ts	0%	75%	+75%
src/lib/adapters/cua-target.ts	0%	76%	+76%
src/lib/adapters/cua-task.ts	0%	76%	+76%
src/lib/adapter...cua-security.ts	0%	80%	+80%
src/lib/cua/tar...et-lifecycle.ts	0%	82%	+82%
src/lib/cua/sec...ty-lifecycle.ts	0%	82%	+82%
src/lib/cua/task-lifecycle.ts	0%	89%	+89%
src/lib/cua/contract.ts	0%	91%	+91%

---

_{Updated August 03, 2026 22:15 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8170.docs.buildwithfern.com/nemoclaw

[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 · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 2 warnings · 1 suggestion

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

4 semantic terminology decisions

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

• define — operator-owned adapter at docs/reference/commands.mdx:1625: Define this term at first use as a host-side adapter controlled by the operator, with authority retained outside NemoClaw.
• established — content-free at src/lib/cua/contract.md:174: Keep using content-free consistently for records that exclude private content and authority.
• define — CUA lifecycle at docs/reference/commands.mdx:1625: Define CUA lifecycle at first use as the versioned target, security, and task contract.
• define — live qualification at docs/reference/commands.mdx:1582: Define live qualification at first use as qualification of the exact pinned runtime tuple that enables runtime availability.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-inference, cloud-onboard, security-posture, full-e2e, hermes-e2e, onboard-repair, onboard-resume, rebuild-openclaw, state-backup-restore, ubuntu-repo-docker-post-reboot-recovery

Workflow run details

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

[jyaunches]

Superseded by the final single-commit consolidation in #8174 at b5f57c3. The replacement is based directly on current main 7475238 and preserves the validated cumulative CUA diff.