feat(cua): expose task and result lifecycle

[jyaunches]

Summary

Expose the runtime-neutral public lifecycle for starting, observing, controlling, and inspecting CUA tasks. The implementation drives one explicit operator-owned task adapter, validates every response against the checked-in CUA contract, retains only bounded secret-free terminal metadata, and keeps task input and detailed evidence private.

This PR is stacked on #7779 and should be reviewed against codex/cua-target-lifecycle-7751-v2.

Related Issue

Fixes #7752

Accepted product and architecture direction: #7750 (comment)

Changes

• Add public task start, status, result, events, logs, plans, pause, cancel, guide, and respond commands with deterministic JSON records and exit codes.
• Add one explicit process adapter boundary that runs without a shell, accepts bounded private UTF-8 input on standard input, sanitizes inherited environment variables, bounds output and execution time, and never copies adapter diagnostics into public output.
• Open private input once without following symbolic links, require a direct regular file, and enforce non-empty and 64 KiB limits before and after the descriptor-bound read.
• Enforce one active task per target, explicit stable task IDs, optional-operation capability checks, input-required state, terminal cancellation, and fail-closed handling for every contract failure family.
• Require task.pause to return an explicitly paused attachment; a still-running response fails validation without changing recorded task state.
• Bind terminal results to the exact runtime, sandbox image, target image, service bundle, policy, task protocol, inference route, capability protocols, and target identity.
• Add bounded, content-addressed private evidence indexes and retain the most recent 16 schema-validated terminal results for reconnect inspection without retaining task input or runtime-private files.
• Add unit, integration, package-contract, negative, identity-drift, reconnect, invalid-input, symlink-input, and per-modality verification-receipt tests using a synthetic task adapter.
• Document every task command under its exact public heading with command/flag parity.

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 39abce8890276b927d8d976405282f68a083d08b, the documentation writer reviewed the complete 33-file diff, verified the private-input documentation matches the descriptor-bound regular-file, non-empty UTF-8, 64 KiB, and no-symlink implementation and regression test, and confirmed the complete task/result reference remains accurate and public-safe. npm run docs passed with 0 errors and 2 existing Fern warnings; git diff --check, CLI type-check, build, focused tests, and normal hooks passed.
• Agent: Codex Desktop — CUA private task input boundary, task/result lifecycle, evidence indexes, adapter protocol, and reconnect persistence 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 — 41 focused task CLI and lifecycle tests passed; npm run typecheck:cli, npm run build:cli, and Biome 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: 5328ebce-e347-4d86-8b3f-b642877bc190

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 39abce8 in the codex/cua-task-resul... branch remains at 96%, unchanged from commit 125ca30 in the codex/cua-target-lif... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 39abce8 in the codex/cua-task-resul... branch is 80%. The coverage in commit cf34b72 in the codex/cua-target-lif... branch is 81%.

Show a code coverage summary of the most impacted files.

File	codex/cua-target-lif... cf34b72	codex/cua-task-resul... 39abce8	+/-
src/lib/onboard...etson-groups.ts	100%	96%	-4%
src/lib/state/registry.ts	93%	90%	-3%
src/lib/actions...ndbox/doctor.ts	88%	86%	-2%
src/lib/actions...or-messaging.ts	46%	48%	+2%
src/lib/adapters/cua-target.ts	0%	76%	+76%
src/lib/adapters/cua-task.ts	0%	76%	+76%
src/lib/cua/schema.ts	0%	81%	+81%
src/lib/cua/tar...et-lifecycle.ts	0%	83%	+83%
src/lib/cua/task-lifecycle.ts	0%	88%	+88%
src/lib/cua/contract.ts	0%	91%	+91%

---

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

[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): Completed · high confidence · 0 blockers · 4 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 4 more warnings, 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: onboard-repair, onboard-resume

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.