feat(computer-use): internal ExecutionRevision contract (RFC #112734 Phase 0B)

[kvnloo]

Status — draft; redesign against merged Bot Screen lease/fence

Fresh audit against upstream main at d0288be5b3330d2442e3907185b8e9d0958297bb (September 25, 2026).

The original premise that #108914 was unmerged is now obsolete: #108914 merged on September 23 and current computer_use already carries a real lease epoch fence around capture/input publication. The broader ExecutionRevision idea may still be useful for backend/display/snapshot invalidation, but it should now be re-derived from those native seams rather than layering the old abstraction unchanged.

Historical execution below belongs to the old head/environment and is retained as provenance, not current-main acceptance evidence.

Status — draft; redesign against merged Bot Screen lease/fence

Fresh audit against upstream main at d0288be5b3330d2442e3907185b8e9d0958297bb (September 25, 2026).

The original premise that #108914 was unmerged is now obsolete: #108914 merged on September 23 and current computer_use already carries a real lease epoch fence around capture/input publication. The broader ExecutionRevision idea may still be useful for backend/display/snapshot invalidation, but it should now be re-derived from those native seams rather than layering the old abstraction unchanged.

Historical execution in the body below belongs to the old head/environment and is retained as provenance, not current-main acceptance evidence.

What does this PR do?

Implements Phase 0B of #112734: the internal ExecutionRevision contract for computer_use. It extracts the admit at epoch N → do work → validate epoch N → publish / commit pattern from the Bot Screen lease-epoch mechanics (#108914) into one internal record, so stale work is invalidated before publication instead of via scattered special-case checks.

The design question in #112734 asked whether the first PR should extract #108914's proven revision/fence semantics behind one internal contract. #108914 is still open and unmerged, so this PR builds the contract on main using only facts the runtime can prove today — the lease-epoch half plugs in when #108914 lands, with no API change.

Related Issue

Related to #112734 (Phase 0B — revisioned execution)
Related to #112639 (parent RFC: computer-use speedup)

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• tools/computer_use/execution_revision.py (new): frozen ExecutionRevision dataclass with independent typed fields (profile_key, display_identity, backend_generation, control_epoch, app, pid, window_id, snapshot_id — all but profile_key optional); ExecutionState with admit() / validate(); explicit invalidation reasons (control_epoch_changed, display_changed, backend_replaced, target_changed, snapshot_stale); per-operation dependency sets (CAPTURE_DEPS, INPUT_DEPS); the sticky-target substring rule as target_mismatch().
• tools/computer_use/tool.py: per-session backend generation counter bumped in _install_backend; per-profile ExecutionState registry keyed by scoped sid; _guarded_capture() admits before backend.capture() and validates before the result reaches any sink (persist/spill/aux-vision/model) — a stale revision fails closed with revision_invalidated; the _dispatch input guard now admits a revision and runs the target check against it (identical rule and error JSON as before).
• tests/computer_use/test_execution_revision.py (new, 14 tests): the Phase 0B exit-gate cases — stale revision rejected at the publish boundary, takeover/hand-back epoch mismatch fails closed, display rebind invalidates capture, backend rebind invalidates input, target/snapshot changes invalidate, unprovable facts never invent staleness, plus wiring tests for the capture fence and the unchanged input guard.

Deliberately deferred (blocked on #108914, still open): populating control_epoch from the Bot Screen lease epochs and snapshot_id from driver snapshot tokens — both stay None and validate open until then. Complements #112778 (phase spans), #113225 (critical-path report), and #113252 (shadow semantic state) without duplicating any of them.

How to Test

1. scripts/run_tests.sh tests/computer_use/test_execution_revision.py — 14 passed
2. scripts/run_tests.sh tests/computer_use/ tests/tools/test_computer_use_input_target_guard.py — 77 passed, 0 failed, 1 skipped
3. Behavior check: the existing test_computer_use_input_target_guard.py suite passes unchanged — the input guard's rule and error JSON are identical through the revision path.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate (only hit is feat(computer-use): shadow GuiStateV0 + semantic deltas (Phase 1A of #112734) #113252, which defers this phase)
• My PR contains only changes related to this fix/feature
• I've run the focused suites via scripts/run_tests.sh and all tests pass
• I've added tests for my changes
• I've tested on my platform: Linux (this sandbox)

Documentation & Housekeeping

• I've updated relevant documentation — N/A (internal contract; docstrings carry the design)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact — display identity is only populated on Linux (X11 DISPLAY); elsewhere it validates open
• I've updated tool descriptions/schemas if I changed tool behavior — N/A (no schema change, no model-facing change)

---

This PR was authored with AI assistance (Muse, Meta's Muse Spark) under the contributor's direction, including implementation and tests.

[alt-glitch]

This was generated by AI during triage.

Competing implementation of #112734 Phase 0B alongside #113295 (JoaoMarcos44). This PR uses a per-profile ExecutionState registry plus a _guarded_capture fence; #113295 threads a ContextVar revision through _dispatch/_capture_response. Different mechanisms for the same slice; a maintainer should pick one. Note this branch also carries changes already on main (contextvars propagation in agent/account_usage.py, gateway/run_agent_cache.py, the desktop spawn-priority fix from #113269) and needs a rebase so the diff shows only the computer-use files.

[kyssta-exe]

Summary
Introduces the internal ExecutionRevision admit/validate contract for computer-use (Phase 0B of #112734): capture fences on display/backend/target, input additionally on control-epoch/snapshot, with unprovable facts validating open until #108914 lands. The design itself is sound — independent typed fields per dependency, fail-closed stale rejection at the publish boundary, no model-facing change. But the branch as pushed contains ~30 files far beyond the 3 the description claims (agent/*, apps/desktop/*, gateway/*, hermes_cli/update_*, unrelated test files), so it cannot be evaluated or merged as-is.

What changed (claimed)

• tools/computer_use/execution_revision.py (new): frozen ExecutionRevision/RevisionVerdict, ExecutionState.admit()/validate(), CAPTURE_DEPS/INPUT_DEPS, target_mismatch()
• tools/computer_use/tool.py: backend-generation counter, per-profile ExecutionState registry, capture/input guards
• tests/computer_use/test_execution_revision.py (new, 14 tests)

Strengths

• "Never invent staleness" (None validates open) is the correct conservative choice for a contract whose producers haven't landed yet
• Per-dependency invalidation reasons give operators a debuggable signal instead of a bare boolean
• Existing test_computer_use_input_target_guard.py passing unchanged shows the input-guard rule survived the refactor intact

Findings

• gh pr diff shows 30 files changed including agent/account_usage.py, gateway/run_agent_cache.py, hermes_cli/update_receipt.py, desktop TS sources, etc. — the branch needs a rebase onto current main and to drop unrelated commits before review can be meaningful. No CI checks are reported on this branch, consistent with it being unrebasable/unmergable in this state.
• tools/computer_use/execution_revision.py::ExecutionState.validate iterates requires (a frozenset), so when multiple deps are stale the reported reason is nondeterministic. Iterating in a fixed order (e.g. CONTROL, DISPLAY, BACKEND, TARGET, SNAPSHOT) would make failures reproducible.
• typing.AbstractSet/Dict/FrozenSet are deprecated aliases; collections.abc.Set / builtin generics are the current spelling (ruff UP035 may flag on newer configs).

Verdict
Needs changes — rebase to contain only the three claimed paths, then re-request review.

Reviewed using Hermes-Agent

[kvnloo]

Closing my competing Phase 0B carrier. #113295 already covers the same old RFC slice with a different mechanism, and more importantly #108914 has since merged the real lease/epoch publication fence that both designs treated as future work.

The remaining backend/display/snapshot invalidation questions should now be derived from current native seams, not by asking maintainers to choose between two September 16 abstraction layers. Thanks @JoaoMarcos44 for carrying the parallel investigation; I’m removing my duplicate review burden rather than competing for ownership.