feat(cua): add disposable target lifecycle

[jyaunches]

Summary

Add the public, host-agnostic lifecycle for attaching one disposable CUA desktop target to one NemoClaw sandbox. The implementation keeps provisioning credentials and transport authority in an operator-owned host adapter while NemoClaw validates and persists only the checked-in, secret-free identity and health contract from #7776.

This PR is stacked on #7776 and should be reviewed against codex/cua-contract-7750.

Related Issue

Fixes #7751

Accepted product and architecture direction: #7750 (comment)

Changes

• Add attach, status, health, reset, detach, and destroy CUA target commands with deterministic exit codes and JSON records.
• Add one explicit process adapter boundary that runs without a shell, receives bounded requests on standard input, sanitizes inherited environment variables, and never copies adapter diagnostics into public output.
• Validate immutable target, image, service-bundle, and browser/computer/terminal protocol identities before recording an attachment.
• Persist only schema-validated runtime-readiness and target-attachment projections; expose the bounded recorded state through status and doctor.
• Reject a second target and reject reset, detach, or destroy while a task is active.
• Add unit, integration, package-contract, negative, drift, replacement, reset, recovery, credential-boundary, and manifest file-boundary tests with a synthetic host adapter.
• Document the adapter trust boundary, runtime-readiness prerequisite, lifecycle commands, recovery behavior, recorded-versus-live health semantics, and manifest file boundary.

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: Maintainer review remains required before merge; the accepted product/security boundary is recorded in Define the CUA architecture and trust boundaries #7750.
• 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: At 5fedd4660f6493fa256714e3be2ae2a3710e1576, the documentation writer reviewed the complete 27-file diff, verified that the regular-file, 64 KiB, and no-symlink wording matches the descriptor-bound implementation, and confirmed the lifecycle reference remains accurate and public-safe. npm run docs passed with 0 errors and 2 existing Fern warnings; git diff --check and normal commit hooks passed.
• Agent: Codex Desktop — CUA disposable target lifecycle, target-manifest security boundary, adapter protocol, status/doctor projections, and recovery documentation

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 — target lifecycle tests (14), target CLI test (1), the existing lifecycle suites, and CLI type-check passed.
• Applicable broad gate passed — GitHub CI supplies the full test and coverage lanes for this stacked change.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without errors (doc changes only) — exited 0 with 0 errors and 2 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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: 8c2957ef-65de-4755-975b-4f7194b249e9

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 5fedd46 in the codex/cua-target-lif... branch remains at 96%, unchanged from commit 125ca30 in the codex/cua-contract-7... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 5fedd46 in the codex/cua-target-lif... branch is 80%. The coverage in commit cf34b72 in the codex/cua-contract-7... branch is 81%.

Show a code coverage summary of the most impacted files.

File	codex/cua-contract-7... cf34b72	codex/cua-target-lif... 5fedd46	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/actions...ndbox/doctor.ts	88%	86%	-2%
src/lib/state/registry.ts	93%	92%	-1%
src/lib/platform.ts	84%	89%	+5%
src/lib/adapters/cua-target.ts	0%	76%	+76%
src/lib/cua/schema.ts	0%	79%	+79%
src/lib/cua/tar...et-lifecycle.ts	0%	83%	+83%
src/lib/cua/contract.ts	0%	90%	+90%

---

_{Updated July 29, 2026 06:03 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, 1 more suggestion.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, security-posture, onboard-repair, onboard-resume, state-backup-restore, upgrade-stale-sandbox

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover active-task rejection for detach and destroy

• Location: src/lib/cua/target-lifecycle.ts:264
• Category: tests
• Problem: The lifecycle test covers active-task rejection only for reset. Detach and destroy use the same active-task guard but have no checked-in regression coverage.
• Impact: A future change can invoke the adapter or clear an attached target while its task is active, violating the one-active-task lifecycle constraint.
• Recommendation: Add parameterized tests for target.detach and target.destroy with an active task. Assert task_conflict, exit code 3, unchanged attachment state, and no adapter invocation.
• Verification: Inspect src/lib/cua/target-lifecycle.test.ts for active-task cases, or run its focused Vitest test after adding detach and destroy cases.
• Test coverage: Parameterize target.detach and target.destroy with an attached target that has activeTask set; assert a task_conflict failure, exit code 3, unchanged registry state, and zero adapter calls.
• Evidence: src/lib/cua/target-lifecycle.ts:264-270 rejects reset, detach, and destroy when current.activeTask is set. src/lib/cua/target-lifecycle.test.ts tests active-task rejection only for target.reset.

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]

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.

[jyaunches]

Superseded by the one-commit consolidation in #8169 at bc98436. Closing this obsolete stack layer; its branch is retained.