docs/archive/computer-use-runtime-hardening.md

# Computer Use Runtime Hardening

This follow-up addresses lifecycle gaps found during review of PR #892.

## Problems

- `clearSession()` did not create a stop tombstone when no session-state record
  existed yet, so a first queued invocation could activate after cleanup.
- Read-only host actions did not acquire a session lease and could continue
  after `user_stopped`.
- Later lifecycle events could overwrite `blocked_url` or `user_stopped`.
- A process-wide executor queue blocked unrelated windows, while a first
  per-session replacement allowed two sessions to interleave
  snapshot/validation/dispatch against the same window.
- The ambiguity gate included ephemeral element IDs even when a stable element
  identity was available.
- `cursor_position` formatting existed without a production backend result.
- Service release reasons did not distinguish a session-only notification from
  a real child-generation release, so `clearSession(A)` could discard retained
  observations and keyboard ownership for unrelated session B.

## Root Cause

The Runtime treated observation and mutation leases as the only operations that
needed lifecycle fencing. Cleanup also mutated only an already-created state
record, while terminal transitions shared the same unrestricted transition
helper as recoverable states.

The executor queue was scoped to the caller rather than the resource being
validated. Ambiguity signatures also mixed stable identity with snapshot-local
IDs, and the cursor result test used only a fake backend.

The backend also inferred generation loss from the release reason. The
no-in-flight `clearSession()` path emits `session_cleared` without stopping the
child, so the reason alone cannot establish that shared executor state changed.

## Fix

- Create the same-turn stop tombstone unconditionally during `clearSession()`.
- Require an observation lease for every host-reading or waiting action.
- Make `blocked_url` and `user_stopped` absorb later lifecycle events.
- Serialize mutations by bound PID/window, with one conservative queue for
  unbound mutations; unrelated bound windows may still progress independently.
- Ignore ephemeral element IDs when a stable element identity is present.
- Read `get_cursor_position` through the pinned cua-driver and return the
  resolved point without moving the pointer.
- Carry `generationReleased` as an explicit service release fact. Session-only
  releases invalidate only their listed sessions; actual child exits sweep all
  retained session observations and keyboard targets.

A new turn still creates a fresh Computer Use session state, preserving the
existing explicit recovery boundary.

## Verification

- `npm --workspace @maka/runtime run typecheck`
- `npm --workspace @maka/runtime test`
- `npm --workspace @maka/computer-use test`
- `git diff --check`