Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(rfc): accept Cua Driver lifecycle sessions

Francesco Bonacci824fea78d2da
diff --git a/rfcs/3007-cua-driver-lifecycle-sessions.md b/rfcs/3007-cua-driver-lifecycle-sessions.md
new file mode 100644
index 0000000000..ec93bdeb16
--- /dev/null
+++ b/rfcs/3007-cua-driver-lifecycle-sessions.md
@@ -0,0 +1,751 @@
+---
+rfc: 3007
+title: 'Cua Driver: Lifecycle Sessions and Per-Call Capture'
+authors:
+ - Cua maintainers
+created: 2026-08-09
+last_updated: 2026-08-09
+status: accepted
+discussion: https://github.com/trycua/cua/issues/3007
+rfc_pr: https://github.com/trycua/cua/pull/3008
+implementation:
+supersedes:
+superseded_by:
+---
+
+# RFC 3007: Cua Driver: Lifecycle Sessions and Per-Call Capture
+
+## Summary
+
+Cua Driver will treat a session as lifecycle state for one agent run. A session
+owns cursor presentation, recording, per-run configuration, cleanup, and
+telemetry. It does not carry permission authority or a persistent capture mode.
+
+The runtime creates an implicit session when a caller makes its first
+session-requiring call without naming one. Calls from the same authenticated
+transport lease reuse that session. Explicit session names remain available for
+coordination and supported reconnection flows.
+
+The public API becomes `start_session`, `get_session`, `list_sessions`, and
+`end_session`. `get_session_state` remains a compatibility alias.
+`escalate_session` and session-level `capture_scope` are deprecated and later
+removed. Each action selects window or desktop capture when it runs, and the
+normal authorization stack evaluates that action independently of session
+lifecycle.
+
+## Motivation
+
+The current API asks an agent to manage two unrelated concerns through one
+session object:
+
+- lifecycle state such as cursor identity, recording, configuration, and
+ cleanup; and
+- a permanent window-to-desktop capture transition.
+
+This produces avoidable failures. An agent can omit `start_session`, so the
+colored cursor may never initialize and later actions may attach to a different
+session. An `auto` session that calls `escalate_session` permanently loses
+window-scoped tools and must end before the caller can recover window behavior.
+Adding a reverse transition would make this state machine larger while leaving
+capture and lifecycle coupled.
+
+The current capture gate also runs only when it can resolve a session. A call
+without a public session can bypass capture-scope state even though it still
+passes hard invariants, managed policy, user policy, the selected permission
+profile, and resource adapters. Session capture state is therefore unsuitable
+as an authorization boundary.
+
+Sessions should give callers stable run identity and reliable cleanup. Capture
+modality belongs to the action being performed, and authority belongs to the
+trusted runtime or authenticated connection that admits the action.
+
+## Goals
+
+- Give ordinary callers stable cursor and lifecycle behavior without requiring
+ `start_session`.
+- Keep explicit session naming and ending available for callers that need them.
+- Bind an implicit session to a trusted ownership namespace and authenticated
+ transport lease.
+- Keep public session strings usable as labels without making them credentials.
+- Make `move_cursor` initialize and wake the colored overlay on a fresh or idle
+ session.
+- Select window or desktop capture for each action instead of permanently
+ changing the session.
+- Provide scoped session inspection through `get_session` and `list_sessions`.
+- Preserve a staged compatibility path for current contracts and generated
+ SDKs.
+- Match the lifecycle contract on macOS, Windows, X11, and supported Wayland
+ environments, or return a concrete platform limitation.
+
+## Non-goals
+
+- Change Cua Driver permission profiles or capability manifests. That work is
+ tracked in [#2996](https://github.com/trycua/cua/issues/2996).
+- Expand the cursor revival bug in
+ [#2976](https://github.com/trycua/cua/issues/2976) into a session redesign.
+- Treat the colored cursor as a protected authorization indicator.
+- Treat an operating-system account, public session name, or model-supplied
+ value as proof of ownership.
+- Preserve a permanent escalation or de-escalation state under another name.
+- Make arbitrary same-user processes a security boundary.
+- Define new macOS TCC, Windows session, or Linux compositor policy.
+
+## Terminology
+
+**Lifecycle session**
+: Runtime state for one agent run. It owns cursor identity and presentation,
+ recording, per-run configuration, cleanup, telemetry, and idle expiration.
+
+**Trusted ownership namespace**
+: The runtime generation or host lease inside which session identities are
+ unique and may be resolved. A same-user operating-system account is too broad
+ to serve as this namespace.
+
+**Authenticated transport lease**
+: A host-attested connection lifetime that receives one default implicit
+ session. It may match one socket or stdio process, or it may survive a socket
+ reconnect when a trusted host authenticates and maintains the lease.
+
+**Implicit session**
+: The lifecycle session generated by the runtime for a transport lease when a
+ session-requiring call omits a public session name.
+
+**Explicit session**
+: A lifecycle session with a caller-supplied public name. Its public name is a
+ map key and label within one trusted ownership namespace.
+
+**Authorization context**
+: The immutable permission profile, policy bindings, grants, and other trusted
+ inputs used to authorize an action. It is supplied by the current runtime or
+ authenticated action connection. A lifecycle session does not select it.
+
+**Capture modality**
+: The window-targeted or desktop-targeted adapter and coordinate space selected
+ for one observation or action.
+
+**Session-requiring call**
+: A call that uses cursor presentation, recording, mutable per-run
+ configuration, or another session-owned resource. Pure administrative or
+ content-free health reads need not create a session.
+
+## Current state
+
+The public session contract currently exposes four tools:
+
+| Tool | Current behavior |
+| --- | --- |
+| `start_session` | Requires a public ID and stores `capture_scope=auto|window|desktop`. |
+| `escalate_session` | Permanently moves an `auto` session to desktop scope. |
+| `get_session_state` | Returns capture policy and effective capture scope for one ID. |
+| `end_session` | Ends the session and invokes cleanup. |
+
+The contract describes escalation as permanent and tells callers to end the
+session and start a new ID to recover window scope. The implementation is in
+[`session_tools.rs`](../libs/cua-driver/rust/crates/cua-driver-core/src/session_tools.rs),
+with public definitions in
+[`session.rs`](../libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs)
+and capture gating in
+[`capture_scope.rs`](../libs/cua-driver/rust/crates/cua-driver-core/src/capture_scope.rs).
+
+RFC 2549 already establishes runtime generations, trusted host leases,
+authenticated action connections, and the rule that a public session ID cannot
+select authority. This RFC defines how user-visible lifecycle sessions fit that
+architecture.
+
+### Prior decisions and related pull requests
+
+This proposal consolidates several decisions that previously landed in pull
+requests without a focused lifecycle-session RFC:
+
+- [PR #1798](https://github.com/trycua/cua/pull/1798) introduced
+ caller-declared session identity, `start_session`, `end_session`, and idle-TTL
+ cleanup. Its design states that session identity is orthogonal to transport
+ and target windows. It also made the cursor require an explicit session. The
+ PR references a local `drafts/session-identity-redesign-2026-05-31.md`, but
+ that file was not included among the merged changes. This RFC retains the
+ lifecycle identity and reverses the explicit-setup requirement.
+- [PR #2329](https://github.com/trycua/cua/pull/2329) moved capture scope from a
+ persistent global setting into immutable per-session policy and introduced
+ one-way escalation. [PR #2857](https://github.com/trycua/cua/pull/2857)
+ later documented that callers must end the session and use a new ID to
+ recover window scope. This RFC deliberately replaces that persistent policy
+ with per-call capture modality.
+- [PR #2550](https://github.com/trycua/cua/pull/2550) added RFC 2549. It defines
+ runtime authorization ceilings, trusted host leases, authenticated action
+ connections, compatibility sessions, and the rule that public session IDs
+ cannot select authority. This RFC carries those trust boundaries forward and
+ applies them to implicit lifecycle ownership and reconnection.
+- [PR #2616](https://github.com/trycua/cua/pull/2616) simplified permission
+ profiles and added sanitized public session-name badges. It did not define
+ automatic implicit sessions, `get_session`, `list_sessions`, reconnection
+ proof, or lifecycle API deprecation.
+- [PR #2677](https://github.com/trycua/cua/pull/2677) moved cursor context into
+ independently fading session badges. Its rendering work remains compatible
+ with this proposal because cursor presentation stays session-owned.
+
+No existing pull request or repository RFC found in the review defines the
+complete target contract proposed here. In particular, none combines
+transport-bound implicit creation, disposable one-shot CLI sessions,
+host-proven named reconnection, scoped enumeration, and retirement of permanent
+capture escalation.
+
+## Proposal
+
+### 1. Separate lifecycle selection from authorization
+
+Every admitted action resolves two independent inputs:
+
+```text
+authenticated action connection -> authorization context
+call or transport default -> lifecycle session
+```
+
+The runtime then evaluates the action through the canonical authorization
+stack. Selecting, naming, reconnecting, omitting, listing, or ending a
+lifecycle session cannot change the authorization context.
+
+An implementation may store a content-free reference to authorization
+provenance for diagnostics. It must never recover grants, approval state,
+permission profiles, or capability manifests by looking up a public session
+name.
+
+### 2. Use host and transport leases as the ownership model
+
+Implicit session ownership has two layers:
+
+```text
+trusted runtime generation or host lease
+└── authenticated transport lease
+ └── implicit lifecycle session
+```
+
+The trusted runtime generation or host lease defines the namespace. The
+authenticated transport lease defines which implicit session ordinary calls
+reuse.
+
+- For MCP over stdio, the lease normally lasts for the MCP process or stdio
+ connection.
+- For a direct SDK, the lease lasts for the trusted session or connection
+ object exposed by the host.
+- For a daemon or reconnectable HTTP service, a trusted host may keep the lease
+ alive across socket reconnects after authenticating the returning caller.
+- A raw socket disconnect ends the session only when that socket is the lease
+ owner. A lower-level reconnect must not accidentally create a new agent run
+ when the trusted lease remains live.
+
+The runtime ends the implicit session when its lease closes, expires, is
+revoked, or receives an explicit end request. Runtime-generation teardown ends
+every session in that generation.
+
+### 3. Create and reuse an implicit session automatically
+
+On the first session-requiring call without a public session name, the runtime:
+
+1. resolves the authenticated transport lease;
+2. creates an opaque internal session identity inside its trusted namespace;
+3. initializes all session-owned subsystems required by the call;
+4. dispatches the call with the authorization context already bound to the
+ connection; and
+5. reuses that identity for later calls on the same lease.
+
+Concurrent first calls on one lease must converge on exactly one implicit
+session. Creation and cleanup must be idempotent.
+
+A cursor idle-hide timeout changes visibility only. It does not create a new
+session, end a session, or change its identity. Later cursor-bearing activity
+wakes the same overlay and cursor identity.
+
+### 4. Make one-shot CLI sessions disposable
+
+A one-shot CLI command has no durable authenticated transport lease. Each
+session-requiring command without an explicit session therefore gets one
+disposable implicit session:
+
+1. create the session before dispatch;
+2. execute the command;
+3. run normal session cleanup synchronously after completion; and
+4. retain idle-TTL reclamation as a crash fallback.
+
+The daemon must not share a short-lived compatibility session across unrelated
+one-shot invocations. Such sharing could combine state from different shells,
+scripts, or agents running as the same operating-system user.
+
+Callers that need cursor, recording, or configuration continuity across CLI
+commands use an explicit session and a supported host-held reconnection flow.
+During migration, a `--no-session` compatibility option may preserve anonymous,
+cursor-free behavior for scripts that rely on it.
+
+### 5. Keep a small public session API
+
+| Tool | Target contract |
+| --- | --- |
+| `start_session` | Optionally declare a named lifecycle session and idempotently return the live session. Ordinary calls do not require it. |
+| `get_session` | Return lifecycle, cursor, recording, configuration, and non-sensitive status for one visible session. |
+| `list_sessions` | Return content-free summaries of sessions visible to the caller's trusted scope. |
+| `end_session` | End one visible session and run all cleanup hooks exactly once. |
+
+`get_session_state` becomes a deprecated alias for `get_session`. Its response
+must not claim that the cursor rendered when a platform overlay rejected or
+dropped the command.
+
+`escalate_session` is absent from the target API. No `deescalate_session` tool
+is added.
+
+### 6. Constrain named-session reconnection
+
+An explicit public name can select existing lifecycle state only inside the
+same trusted ownership namespace. Public names never provide proof of
+ownership.
+
+When a session is attached from a new transport lease, the host must validate:
+
+- the authenticated caller belongs to the original trusted ownership
+ namespace;
+- the session remains live and reconnectable;
+- the host holds an opaque, unguessable resume credential or equivalent
+ host-private proof; and
+- the prior attachment has ended or an explicit coordination policy permits
+ multiple attachments.
+
+The resume credential is host-held. It is never accepted through model-visible
+tool arguments or treated as a permission token.
+
+Successful reconnection restores lifecycle state such as cursor identity,
+recording ownership, and cleanup responsibility. The new connection supplies a
+fresh authorization context. Reconnection does not inherit permission modes,
+grants, approvals, managed or user policy snapshots, or capability manifests
+from the old connection.
+
+A public name cannot reconnect across runtime generations, host leases,
+authenticated principals, or remote tenant boundaries. Being the same
+operating-system user is insufficient proof.
+
+Explicitly restarting an ended public name through `start_session` creates a
+new lifecycle episode. It may preserve the user-facing color derived from the
+name, but it must revive core state, cursor registry state, recording,
+configuration, and the platform overlay together. Issue #2976 covers the
+existing cross-platform overlay tombstone defect required for that behavior.
+
+### 7. Scope `list_sessions` by caller role
+
+Visibility follows trusted ownership rather than string knowledge:
+
+| Caller | Visible sessions |
+| --- | --- |
+| Ordinary agent transport | Sessions currently attached to its authenticated transport lease. |
+| Trusted host or orchestrator | Sessions in its runtime generation or host-lease namespace. |
+| Local operator interface | All live sessions in the local daemon it administers. |
+
+An ordinary summary may include:
+
+- a sanitized public label when one exists;
+- whether the session was implicit or explicitly named;
+- closed-enum client kind;
+- lifecycle state;
+- cursor-visible and recording-active booleans; and
+- coarse idle and expiry status.
+
+A trusted operator view may additionally expose an opaque owner short ID,
+transport kind, start time, and structured end reason. It must not expose:
+
+- runtime keys or resume credentials;
+- caller-supplied free text;
+- recording paths or contents;
+- permission grants, capability-manifest contents, or policy details;
+- precise action history; or
+- captured or typed content.
+
+Pagination, stable ordering, and redaction happen before serialization. Session
+names supplied by one caller never become enumerable by another ordinary
+caller.
+
+### 8. Select capture modality per call
+
+The target contract removes `capture_scope=auto|window|desktop` from lifecycle
+session identity.
+
+1. A window-targeted observation or action uses the window adapter and an exact
+ window identity.
+2. A desktop-targeted observation or action uses the desktop adapter and an
+ explicit display scope.
+3. Hard invariants, managed policy, user policy, the selected permission
+ profile, an optional capability manifest, and live resource checks decide
+ whether the call is allowed.
+4. The lifecycle session records the selected modality for content-free
+ telemetry and resource cleanup.
+
+Action-specific generated contracts may express modality through typed target
+variants or a common per-call field. They must reject ambiguous coordinate
+spaces before platform dispatch.
+
+A product-level preference for window-first behavior belongs in planner
+guidance or one-call fallback logic. A fallback must run through authorization
+for the actual target it chooses and must not mutate session state.
+
+### 9. Unify cursor initialization and cleanup
+
+The first cursor-bearing action creates or resolves the lifecycle session and
+initializes the platform overlay before reporting success. `move_cursor` must
+initialize and display the overlay as reliably as a coordinate click.
+
+All termination paths call one idempotent cleanup operation:
+
+- explicit `end_session`;
+- authenticated transport-lease close;
+- idle expiration;
+- revocation; and
+- runtime-generation shutdown.
+
+Cleanup runs every registered session-owned hook exactly once. Partial cleanup
+is reported as a structured error and remains eligible for bounded retry. State
+inspection reports acknowledged platform state, rather than only accepted
+commands or registry intent.
+
+## Alternatives considered
+
+### Keep explicit session setup mandatory
+
+This preserves the current contract but leaves ordinary agent behavior
+dependent on remembering a setup call. Cursor initialization and cleanup should
+be runtime guarantees for session-requiring actions.
+
+### Give every one-shot CLI invocation a shared daemon session
+
+This provides continuity without an explicit name, but the daemon cannot
+reliably distinguish unrelated shells and agents that share an operating-system
+user. Disposable sessions keep ownership clear.
+
+### Reconnect by public name inside one operating-system account
+
+This makes names act like bearer tokens and lets unrelated same-user processes
+claim lifecycle state. Trusted namespaces and host-private resume proof provide
+the required boundary.
+
+### Add `deescalate_session`
+
+A reverse transition preserves the capture state machine and adds more paths
+for callers to reason about. Per-call modality gives each operation the scope
+it needs without a persistent transition.
+
+### Keep a temporary session-lifetime desktop authorization shim
+
+An intermediate shim that authorizes desktop capture for the remainder of a
+session recreates the coupling this RFC removes. It also makes lifecycle calls
+capable of changing effective action authority. The migration keeps legacy
+capture behavior only for clients that explicitly use the deprecated contract;
+new behavior uses per-call modality.
+
+### Expose every daemon session to every local caller
+
+This is convenient for debugging but leaks caller-chosen names and activity
+metadata. Broad enumeration belongs to a trusted operator interface.
+
+## Compatibility and migration
+
+Migration occurs in two stages.
+
+### Additive release
+
+Release N will:
+
+- create implicit sessions for session-requiring calls;
+- add `get_session` and `list_sessions`;
+- make `get_session_state` a deprecated alias;
+- add per-call capture modality;
+- mark `escalate_session` and session-level `capture_scope` deprecated in Rust
+ contracts, generated SDKs, MCP descriptions, CLI help, and documentation;
+- preserve legacy capture behavior when a caller explicitly uses the deprecated
+ fields or tool; and
+- emit structured migration guidance without placing caller content in logs or
+ telemetry.
+
+The additive release must retain current wire compatibility. New SDKs should
+prefer the lifecycle API and typed per-call targets.
+
+### Declared breaking release
+
+After at least two minor releases and at least 90 days, a declared breaking
+release may:
+
+- remove `escalate_session` from advertised MCP and generated SDK surfaces;
+- remove session-level `capture_scope` from `start_session` and session status;
+ and
+- stop creating legacy capture-state sessions.
+
+The dispatcher retains a structured `tool_removed` tombstone for
+`escalate_session` during the supported compatibility period. It identifies the
+replacement per-call contract and does not perform an action.
+
+Because `get_session_state` is a low-risk read-only alias, it remains available
+through this breaking release and may be retained longer. Its earliest removal
+requires separate release notes and SDK usage evidence.
+
+Rollback during the additive stage disables implicit creation and new
+per-call surfaces while leaving legacy calls intact. Once the breaking release
+ships, rollback follows the normal component-version path and does not require
+session data migration because sessions are ephemeral runtime state.
+
+## Security, privacy, and telemetry
+
+The core invariant is:
+
+```text
+trusted namespace proves lifecycle ownership
+public session identity selects lifecycle state within that namespace
+current authenticated connection supplies all authority
+```
+
+No session lifecycle operation or omitted session argument can widen hard
+invariants, managed policy, user policy, permission-profile behavior, a
+capability manifest, or live resource checks.
+
+The runtime must reject cross-namespace lookup, attachment, listing, and end
+operations before returning whether a named session exists. Errors should avoid
+creating a session-name enumeration oracle.
+
+Telemetry may include generated episode IDs, closed-enum client kind, start and
+end reason, coarse duration, aggregate action counts, and selected capture
+modalities. It must not include public session names, resume credentials,
+free-form caller text, captured content, typed input, recording paths, or
+authorization secrets.
+
+The colored cursor communicates agent activity to the user. It is not proof
+that an action was authorized, delivered, or performed by a particular remote
+principal.
+
+## Implementation plan
+
+### Single implementation pull request
+
+After this RFC lands, one pull request will deliver the additive migration. It
+will include the cross-platform cursor revival fix from #2976, the new
+lifecycle model, public contract changes, compatibility adapters, generated
+SDKs, documentation, and exact-candidate platform evidence.
+
+The pull request does not include capability-manifest work from #2996. It also
+does not delete deprecated session tools or fields before their announced
+support window ends. A later mechanical cleanup pull request will remove those
+surfaces after at least two minor releases and 90 days. That cleanup does not
+block completion of the additive migration.
+
+The pull request should use the release-bearing title:
+
+```text
+feat(cua-driver): add implicit lifecycle sessions
+```
+
+The implementation pull request starts as a draft and links to this accepted
+RFC. It becomes ready only after every gate below passes at its final candidate
+SHA.
+
+### Fixed implementation choices
+
+The implementation uses these choices so work can begin without another design
+round:
+
+- Long-lived transport leases use a 30-minute default session idle TTL. Trusted
+ hosts may configure a shorter or longer value within documented bounds.
+ Transport close and revocation still clean up immediately. Cursor idle-hide
+ remains a separate setting.
+- `start_session` accepts an optional public name. With no name, it creates or
+ returns the transport's implicit session. `get_session` and `end_session`
+ likewise default to the caller's attached implicit session when no visible
+ session reference is supplied.
+- Per-call targets use a generated tagged union:
+
+ ```text
+ target = window { application identity, window_id }
+ | desktop { display_id }
+ ```
+
+ Legacy flat target fields remain accepted by the compatibility decoder and
+ normalize into this union before authorization.
+- Resume credentials are random, host-held, single-use values bound to the
+ runtime generation, host lease, principal, and lifecycle episode. A
+ successful attach rotates the value. The runtime never persists it across a
+ restart and never accepts it through an agent tool argument.
+- Agent-facing `list_sessions` is transport scoped. Trusted SDK hosts receive a
+ host-scope listing method. Local administrators use
+ `cua-driver sessions list --json`; the operator view is not registered as an
+ agent tool.
+- Supplying deprecated `capture_scope` marks an explicit session as legacy for
+ the compatibility window. Lifecycle-only implicit sessions and new typed
+ per-call targets carry no capture state. Compatibility fixtures from the
+ previous supported SDK release must pass before this rule ships.
+
+### Commit and review sequence
+
+The pull request remains one review and one final squash commit. Its working
+commits follow the dependency order below so each layer can be reviewed and
+tested before the next lands.
+
+| Commit | Work | Required focused proof |
+| --- | --- | --- |
+| 1. Contract and fixtures | Link this RFC, freeze 0.19.2 compatibility fixtures, and add failing target schemas and lifecycle cases. | Contract fixtures fail only for the intended missing behavior. |
+| 2. Ownership foundation | Add runtime namespace, transport lease, lifecycle key, and one dispatch context containing separate authorization and lifecycle references. | Unit tests reject cross-lease, cross-host, cross-generation, and concurrent-first-call substitution. |
+| 3. Lifecycle and cleanup | Add implicit creation, 30-minute idle expiry, disposable CLI sessions, attachment, revival, and one idempotent cleanup coordinator. | Lifecycle tests cover every start, reuse, end, expiry, revocation, disconnect, and shutdown path. |
+| 4. Cursor correctness | Finish #2976 across macOS, Windows, X11, and supported Wayland paths; make move initialize the overlay and make render acknowledgement observable. | Platform overlay tests prove remove, late-command rejection, explicit revival, lazy recreation, and truthful state. |
+| 5. Public session API | Add `get_session`, scoped `list_sessions`, optional-name behavior, trusted host listing, operator CLI listing, redaction, pagination, and the `get_session_state` alias. | Contract and privacy tests prove each caller sees only its permitted summaries. |
+| 6. Per-call capture | Add the tagged target union, normalization, canonical authorization, and legacy session-capture adapter. Deprecate `escalate_session` and `capture_scope`. | Old-client fixtures retain behavior; new calls have no persistent capture transition; authorization monotonicity passes. |
+| 7. Generated surfaces and docs | Regenerate MCP, Rust, Python, TypeScript, Swift, and other current bindings. Update CLI help, health/status, telemetry, examples, migration notes, and reference docs. | Generation drift, package signature snapshots, docs links, and docs hygiene pass. |
+| 8. Candidate certification | Run focused suites, ordinary PR CI, then the canonical desktop matrix once at the stable SHA. Fix findings and recertify affected rows after executable changes. | All required checks and exact-SHA platform evidence are green. |
+
+### Core implementation shape
+
+The core owns one lifecycle registry. Adapters do not create private fallback
+sessions or clean up session-owned resources independently.
+
+```text
+trusted runtime generation
+└── host lease namespace
+ ├── authorization bindings by authenticated action connection
+ ├── implicit session index by transport lease
+ └── lifecycle sessions
+ ├── attachments
+ ├── cursor and overlay state
+ ├── recording and per-run configuration
+ ├── idle and absolute deadlines
+ └── cleanup state: live -> ending -> ended
+```
+
+At the canonical dispatch boundary, the runtime performs this order:
+
+1. authenticate the action connection and resolve its immutable authorization
+ context;
+2. resolve or create the lifecycle session inside the connection's trusted
+ namespace;
+3. normalize the typed or legacy action target;
+4. authorize the exact tool and attested target through the existing policy
+ stack;
+5. initialize required session-owned resources and dispatch once;
+6. commit lifecycle activity and telemetry only for the admitted call; and
+7. report platform-acknowledged state.
+
+Failure before dispatch must not refresh a lease, create an externally visible
+cursor, or widen authorization. Failure after partial platform delivery must
+report the known or unknown effect and leave cleanup recoverable.
+
+### Pull-request gates
+
+The pull request cannot become ready until all of these conditions hold:
+
+- The final diff contains only the lifecycle-session implementation and its
+ generated contracts, tests, and documentation. Capability-manifest changes
+ remain outside it.
+- The implementation links to this accepted RFC and its decision summary.
+- The previous supported SDK and raw MCP compatibility fixtures pass against
+ the candidate.
+- Generated contracts and every checked-in SDK surface match the Rust source.
+- The lifecycle-selection property test proves that changing only the session
+ cannot turn `Deny` or `RequireGrant` into `Allow`.
+- Cleanup is exactly once under concurrent end, expiry, revocation,
+ disconnect, and runtime shutdown.
+- macOS, Windows, Linux X11, and supported Wayland cursor revival and first-move
+ behavior have focused coverage.
+- Ordinary pull-request CI is green.
+- The complete canonical Windows, Linux X11, and macOS desktop E2E matrix is
+ green at the final candidate SHA. Wayland passes its supported lane or
+ returns a documented platform limitation.
+- The final pull-request title is release-bearing, the release metadata check
+ passes, review conversations are resolved, and no requested changes remain.
+
+### Merge and release follow-through
+
+After merge, run a short main-branch lifecycle smoke and verify the component
+release path resolves the expected Cua Driver version and artifacts. Repeat the
+full desktop matrix only if the merge result differs materially from the
+certified candidate or the smoke exposes a regression.
+
+Record the earliest permitted legacy-removal date and release number in the
+RFC discussion and migration documentation. The later removal pull request is
+mechanical: delete the compatibility decoder and advertised tombstones, update
+generated surfaces, and remove migration text. It must not redesign lifecycle
+or authorization.
+
+## Test and acceptance plan
+
+### Lifecycle and cursor
+
+- A caller can perform its first cursor-bearing action without calling
+ `start_session`; the runtime creates one implicit session.
+- Later actions on the same authenticated transport lease reuse that session.
+- Concurrent first actions create exactly one implicit session.
+- `move_cursor` initializes and displays the colored overlay on a fresh
+ implicit or explicit session.
+- Cursor idle fade does not change session identity; later activity wakes the
+ same cursor.
+- Connection or lease close, idle TTL, revocation, runtime shutdown, and
+ explicit end invoke the same cleanup hooks exactly once.
+- A one-shot CLI command uses one disposable session and cannot observe state
+ from an unrelated one-shot invocation.
+- Reusing an ended public ID revives core, cursor, recording, configuration,
+ and platform overlay state together.
+- Inspection never reports a cursor as rendered when the platform rejected or
+ dropped its command.
+
+### Ownership and privacy
+
+- Public session names cannot attach, list, end, or probe sessions outside the
+ caller's trusted namespace.
+- Replayed, expired, revoked, cross-generation, cross-principal, and
+ cross-host-lease resume proofs fail closed.
+- Reconnection restores lifecycle state while using only the new connection's
+ authorization context.
+- Ordinary `list_sessions` returns only sessions attached to the caller's
+ transport lease.
+- Trusted host and operator listings follow their documented scopes and redact
+ sensitive fields before serialization.
+
+### Authorization and capture
+
+- Starting, ending, omitting, reconnecting, or renaming a session cannot change
+ the authorization result for the same connection and action.
+- A window-targeted call uses exact window identity and window coordinates.
+- A desktop-targeted call uses an explicit display target and desktop
+ coordinates.
+- Per-call fallback reauthorizes the actual target and leaves lifecycle state
+ unchanged.
+- Legacy capture fields preserve documented behavior only during the migration
+ window.
+
+Add a property test for the primary security invariant:
+
+```text
+Given the same authenticated connection and action,
+changing only lifecycle-session selection cannot change
+Deny or RequireGrant into Allow.
+```
+
+### Contract and platform parity
+
+- Generated MCP schemas and every supported SDK expose matching lifecycle and
+ per-call capture contracts.
+- CLI help, environment variables, status output, deprecation warnings, and
+ documentation agree with the generated contract.
+- Focused unit, contract, and platform smoke tests pass during implementation.
+- The complete canonical Windows, Linux X11, and macOS desktop E2E matrix passes
+ at the exact stable candidate SHA.
+- Supported Wayland behavior matches the contract or reports a concrete
+ compositor or portal limitation.
+- A short main-branch and release-path smoke passes after merge.
+
+## Unresolved questions
+
+No design question blocks implementation. Review may change a fixed choice only
+when it identifies a concrete compatibility, security, or platform failure and
+records the replacement in the decision record.
+
+## Decision record
+
+This draft incorporates an adversarial architecture review using Claude Code
+Fable. The review supported transport-bound implicit sessions, narrow session
+enumeration, disposable one-shot CLI sessions, and staged deprecation. The
+proposal rejects a suggested intermediate session-lifetime desktop
+authorization shim because it would allow lifecycle state to affect effective
+action authority.
+
+The maintainer decision in the discussion issue accepts this RFC. The shortened
+review period reflects the prior shipped decisions, repository-wide issue and
+pull-request audit, and two-round adversarial architecture review. The separate
+implementation pull request remains subject to every compatibility, privacy,
+CI, and exact-candidate platform gate in this document.