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

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. The final fail-closed task lifecycle suite passed 41/41, onboarding compatibility passed 18/18 in isolation, compiled CLI/docs parity passed 3/3, and E2E mock parity passed.
• 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: d3a9d13e-0534-4011-888f-2dd0db4d9171

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 b5f57c3 in the codex/cua-runtime-re... branch remains at 96%, unchanged from commit 3f3eb61 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit b5f57c3 in the codex/cua-runtime-re... branch remains at 81%, unchanged from commit 7475238 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 7475238	codex/cua-runtime-re... b5f57c3	+/-
src/lib/onboard...strap/docker.ts	66%	69%	+3%
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:50 UTC}

[github-actions]

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

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 6 warnings · 0 suggestions

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.

• established — content-free at docs/reference/commands.mdx:1783: Keep content-free for CUA public records and output.
• define — operator-owned adapter at docs/reference/commands.mdx:1648: Keep the term with the ownership and credential-boundary definition in the surrounding documentation.
• define — CUA lifecycle at docs/reference/commands.mdx:1625: Keep CUA lifecycle for the versioned schema and command contract.
• define — security attestation at docs/reference/commands.mdx:1835: Keep security attestation for the schema-defined task-admission record.

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

Blockers

PRA-1 Blocker — Bind security verification to a trusted verifier identity

• Location: src/lib/cua/security-command.ts:22
• Category: security
• Problem: The security verification command constructs a verifier from any caller-supplied absolute path. That executable can return a schema-valid enforced attestation, which the lifecycle persists and task admission accepts.
• Impact: A local caller can forge the security attestation and enable CUA task execution without a verifier that inspected the applied policy, isolation, credential, or artifact boundaries.
• Fix: Require a verifier identity that NemoClaw trusts and validates before execution, such as a registered immutable verifier path with ownership and integrity checks. Do not let an arbitrary CLI argument establish task-admission evidence.
• Verification: Inspect src/lib/cua/security-command.ts and src/lib/adapters/cua-security.ts to confirm that --adapter accepts any absolute executable, then trace the persisted attestation through src/lib/cua/security-lifecycle.ts and src/lib/cua/task-lifecycle.ts.
• Test coverage: Add a task-admission regression test that supplies an unregistered executable emitting a valid enforced attestation and verifies that security verification fails and task start remains blocked.
• Evidence: src/lib/cua/security-command.ts:22 creates ProcessCuaSecurityAdapter from the caller-controlled adapterPath. src/lib/adapters/cua-security.ts:61-76 validates only that the supplied path is absolute, executable, and a regular file. src/lib/cua/security-lifecycle.ts:235-260 persists a schema-valid matching attestation. src/lib/cua/task-lifecycle.ts:292-297 accepts a matching stored attestation before invoking the task adapter.

Workflow run details

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

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[jyaunches]

Closing this draft in favor of a smaller, reviewable CUA stack built from current main. The replacement keeps the lifecycle framework default-off and excludes production agent manifests, binaries, and artifact integration; those remain owned by the NemoClaw image lane.