Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
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.mdnew file mode 100644index 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.