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

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: dbf5ea92-ac09-45c4-8dc0-9f9fdd930b2a

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

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit bc98436 in the codex/cua-consolidat... branch remains at 96%, unchanged from commit 03fbf5e in the main branch.

[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 · medium confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 11 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:1630: Keep `content-free`; it is established repository terminology and retains its existing meaning.
• established — lifecycle authority at docs/reference/commands.mdx:1641: Keep `lifecycle authority`; it matches the controlled definition and identifies the responsible component.
• justified — operator-owned adapter at docs/reference/commands.mdx:1648: Keep `operator-owned adapter`; the modifier distinguishes authority and credential custody at this trust boundary.
• define — CUA at agents/nemocua/manifest.yaml:27: At the first explanatory use, write `computer-use agent (CUA)` to distinguish this lifecycle surface from the existing CUA driver.

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 — Validate retained task results against current identities

• Location: src/lib/cua/task-lifecycle.ts:296
• Category: correctness
• Problem: `task.result` and `task.status` return a retained terminal result before checking its runtime and target identities against current registry state.
• Impact: After a target reset or runtime identity change, callers can receive a terminal result bound to the prior target or runtime, which misstates the identity associated with the reported task outcome.
• Fix: Before returning a retained result, require the current available runtime and attached target, then apply `taskResultMatches`; return a deterministic stale or incompatible failure when the stored result does not match.
• Verification: Inspect `executeCuaTaskLifecycle` with a persisted `cuaTaskResults` entry after changing `cuaTarget.target.identityDigest` or a runtime component, and confirm it does not return that entry.
• Test coverage: Persist a terminal result, change the recorded target identity and separately a runtime component identity, then verify both `task result` and `task status` reject the retained result without invoking the adapter.
• Simplification (shrink): Remove The early stored-result return that bypasses current identity validation.; use Reuse `taskResultMatches` before returning a retained result.. Net: 5 lines.
• Keep: Retain all current runtime, target, and security-attestation checks; only share the existing identity comparison for the stored-result path.
• Evidence: src/lib/cua/task-lifecycle.ts:292-297 returns a stored result immediately for `task.result` or `task.status`. src/lib/cua/task-lifecycle.ts:342-344 validates only adapter-returned terminal results with `taskResultMatches`. docs/reference/commands.mdx:1801-1803 states that identity drift makes the recorded security state stale and blocks validation and task execution. docs/reference/commands.mdx:1918 states that `cua task result` retrieves and validates the terminal result.

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 corrected consolidation #8170 at f0c1d06 after making src/lib/onboard.ts net-neutral for the growth guardrail. Branch retained.