Cua Driver 0.13.2 Overnight Stabilization Plan

Status: Draft for review Baseline: Cua Driver 0.13.1 is already released Source baseline: origin/main at 1e77ab5536eb88ca4cb7d3b6cc1fb51eea03f0e4 Target: Merge validated post-0.13.1 work into main Release boundary: Do not create, publish, promote, or merge a 0.13.2 release. Francesco owns the 0.13.2 release tomorrow.

1. Goal

Leave main ready for a 0.13.2 release by:

1. making the default cursor smaller and correcting its session badge;
2. auditing every spatial action so the cursor moves to the action target;
3. landing the hermetic macOS certification work in PR #2660;
4. resolving the highest-impact regressions discovered around 0.13.1;
5. restoring the intended release automation without triggering a release;
6. validating the exact merged main SHA on macOS, Windows, and Linux;
7. updating public docs and post-install guidance for any behavior that changes;
8. preserving reviewable evidence, including videos for GUI behavior.

This is stabilization and correctness work. It is not a release operation.

2. Definition of done

The overnight work is complete only when:

• every accepted product or workflow fix is merged into main through a focused PR;
• the production cursor is smaller on macOS, Windows, Linux X11, and Linux Wayland;
• the session badge fades away after a short reveal, uses the promised session-accent gradient, and has a circular session dot;
• every supported spatial action either moves the agent cursor to its resolved target or documents why the action has no spatial target;
• the spatial-action audit has contract tests and representative E2E evidence;
• PR #2660 is synchronized with current main, reviewed, fully validated, and merged;
• issue #2655 has two consecutive same-SHA macOS certification runs that do not depend on stale worker state;
• canonical Cua Driver installers resolve and install the released 0.13.1 artifacts before any source-built validation begins;
• the final merged main SHA passes the relevant deterministic Linux and Windows CI;
• representative desktop E2E evidence exists for macOS, Windows, Linux X11, and Linux Wayland where the changed behavior applies;
• every GUI success is proven by an external effect, not only ok: true;
• background claims retain focus, z-order, real-cursor, occlusion, and input-isolation evidence;
• public docs, generated references, examples, and post-install instructions match the final behavior;
• PR titles and labels accurately describe release impact and pass release-metadata validation;
• no release, tag, package publication, deployment, or Release Please PR merge occurs;
• the execution journal states the final main SHA, merged PRs, exact test results, artifacts, limitations, and remaining owner.

3. Operating boundaries

• Start every new unit of work from freshly fetched origin/main.
• Preserve the existing dirty worktree. Use clean branches or worktrees for all implementation.
• Keep each independent regression in its own focused PR.
• Merge only after the PR's exact head has the required tests and evidence.
• Do not bypass a required human review or a protected branch rule.
• Do not overlap with independent backlog or contributor-PR review work.
• Preserve external contributor authorship when adapting submitted work.
• Do not introduce a breaking public API, CLI, SDK, protocol, or configuration change without asking first.
• Do not weaken product assertions or relabel a behavior failure as an environment failure.
• Keep public artifacts free of credentials, private infrastructure details, machine-specific paths, and raw session data.
• Use a living execution journal at packages/cua-driver/docs/0.13.2-overnight-execution-journal.md.

4. Priority and landing order

P0. Correct the cursor size, session badge, and spatial action motion

Confirmed product requirements:

1. Make the default cursor visibly smaller while preserving legibility on light and dark backgrounds.
2. Reveal the session-name badge with the pointer, then fade only the badge away after a short readable interval. Cursor visibility and idle behavior remain independent.
3. Match the production badge to the repository web harness:
   • session-accent background gradient;
   • circular session-color dot;
   • centered label;
   • compact spacing and cursor gap;
   • consistent backing-scale behavior.
4. Audit every public action and fix spatial actions that update the semantic icon without moving the agent cursor to their resolved target.

Implementation work:

1. Treat the native Skia renderer as the production source of truth and the web harness as a visual contract and review surface.
2. Add a renderer-owned badge reveal clock with explicit hold and fade durations. Reset it when the session label is first set and whenever a new session becomes visibly active.
3. Keep the fade deterministic, independent per session, and disabled only when the badge itself is absent.
4. Render the badge accent with the session fill and bounded light and dark variants. Do not accept an agent-controlled arbitrary badge color.
5. Render the dot through a circular path, not a square rectangle.
6. Reduce the one canonical production display size and update all tests, docs, gallery exports, and platform bounds that depend on it.
7. Create a complete action-motion inventory with:
   • public tool;
   • semantic action;
   • target source;
   • expected movement;
   • platform implementation;
   • external E2E oracle.
8. For actions with resolved coordinates or element bounds, move the agent cursor before dispatch while preserving the real pointer for background delivery.
9. For actions without a spatial target, keep the cursor at its current location and animate the semantic state there.
10. At minimum, audit and test:
    • click, double click, right click;
    • drag;
    • scroll;
    • type text and set value;
    • press key and hotkey;
    • browser click, drag, scroll, type, fill, press key, and hotkey;
    • navigation, app, transfer, record, system, and observe actions.
11. Assert that semantic begin and end events are emitted for every classified public tool with an explicit session.
12. Add platform-focused tests that prove spatial actions send the correct keyed move command before action dispatch.
13. Run the repository cursor gallery and record the complete action and modifier sequence.
14. Run real Cua Driver action sequences on macOS, Windows, Linux X11, and Linux Wayland. Verify application effects independently and record videos.
15. Update cursor personalization, action catalog, session, and post-install documentation.

P0. Make macOS certification hermetic

Tracking:

• Issue #2655
• PR #2660

Work:

1. Rebase or merge the latest origin/main into the PR branch without losing its existing evidence.
2. Re-run shell syntax, ShellCheck, focused script tests, Rust formatting, and all changed-path CI.
3. Preflight the macOS Lume host and guest:
   • adequate host and guest disk space;
   • logged-in GUI session;
   • exact source SHA installed;
   • correct TCC identity and grants;
   • no stale daemon, socket, fixture, Cargo target, or build-cache ownership;
   • sufficient evidence output space.
4. Run the canonical full macOS certification matrix twice consecutively at the same exact PR SHA.
5. Require each run to:
   • create a fresh run-owned build namespace;
   • own daemon startup, permission mode, socket, watchdog, shutdown, and restoration;
   • execute every declared row;
   • preserve the initial attempt and any allowed exact-cell retry;
   • record row-level screenshots, logs, videos, and external oracles;
   • restore the normal daemon after success or failure.
6. If a run fails, classify it before changing anything:
   • product failure: fix product behavior and restart exact-head validation;
   • harness failure: fix the harness without weakening assertions;
   • environment failure: prove it through preflight or independent system evidence and retry in a repaired representative environment.
7. Update the PR body with the final exact SHA and both consecutive run links.
8. Confirm the test(cua-driver) title and no-release label remain accurate.
9. Merge after required review and checks pass.
10. Verify issue #2655 is closed by the merged PR.

P0. Verify the shipped installer baseline

Tracking:

• Issue #2654

Work:

1. Verify the canonical Unix and Windows installers resolve the released 0.13.1 component tag.
2. Verify the expected macOS, Linux, and Windows assets exist under that exact component release.
3. Exercise a clean install and an upgrade from the prior supported version on each platform.
4. Verify:
   • installed executable path;
   • cua-driver --version;
   • source or release provenance;
   • daemon start and stop;
   • one representative MCP smoke test.
5. If the 0.13.1 release already resolves the reported 0.13.0 404, record the evidence and close #2654 as resolved.
6. If any canonical path still fails, fix it in a focused PR and rerun all installer-contract tests before merging.

P0. Restore safe automatic publication for future releases

Tracking:

• Issue #2662

Work:

1. Restore the intended normal release path after an approved Release Please PR merge:
   • immutable component tag;
   • required build and verification dependencies;
   • GitHub release publication;
   • version-locked PyPI and npm SDK publication.
2. Keep PR comment and checkbox controls unable to bump or publish packages.
3. Preserve manual recovery dispatch without making it the normal path.
4. Add deterministic workflow tests for:
   • valid component tag push;
   • required build failure;
   • tag and SHA mismatch;
   • disabled PR comment or checkbox path;
   • explicit recovery dispatch.
5. Validate the workflow without creating a tag, release, or package publication.
6. Merge the focused workflow PR only after release-metadata and workflow tests pass.

P0. Fix silent Linux process-control success

Tracking:

• Issue #2661

Work:

1. Reproduce kill_app reporting success while the process survives.
2. Reproduce launch_app.launch_path leaving a shell child hung without executing.
3. Trace process identity, signal delivery, child state, pipes, process groups, wait behavior, and timeout handling.
4. Change the contract so:
   • kill_app verifies the target exited or returns a structured failure;
   • PID reuse cannot produce a false success;
   • launch_path drains or redirects child pipes safely;
   • launch completion has a bounded, observable condition;
   • abandoned children are reaped;
   • unsupported sandbox behavior fails explicitly.
5. Add deterministic unit and integration coverage.
6. Run representative Linux X11 and Wayland E2E.
7. Run a gVisor-equivalent proof when an existing authorized environment is available. Otherwise, state that gVisor remains unproven and do not claim the reported platform fixed.
8. Merge only when the product cannot silently report a process-control success with no effect.

P1. Stop Cua Driver from launching a screen reader on COSMIC

Tracking:

• Issue #2630

Work:

1. Confirm the current default behavior from source and a representative Linux session.
2. Prefer the safe default for unknown desktops: enable generic AT-SPI inspection without claiming that a screen reader is active.
3. Preserve an explicit override for environments that genuinely require full advertisement.
4. Add regression tests for GNOME, COSMIC, known non-GNOME desktops, mixed desktop identifiers, and unknown desktops.
5. Verify on Linux Wayland that:
   • Orca and Speech Dispatcher do not start;
   • accessibility inspection still works;
   • a representative action still completes.
6. Update Linux troubleshooting and accessibility documentation if the override or default behavior changes.
7. Merge the focused fix after exact-head Linux validation.

P1. Improve drag cursor animation

Tracking:

• Issue #2625

Work:

1. Animate drag as a continuous point-to-point gesture rather than a standard cursor movement.
2. Keep the production cursor compact, session-colored, legible on light and dark backgrounds, and consistent across platforms.
3. Preserve the existing semantic action and delivery modifiers.
4. Add deterministic rendering or timeline tests for:
   • drag start;
   • continuous travel;
   • destination arrival;
   • release;
   • cancellation or refusal.
5. Validate at least one foreground and one supported background drag path per representative platform.
6. Record short macOS, Windows, Linux X11, and Linux Wayland videos where supported.
7. Update cursor personalization documentation and the repository cursor preview harness.
8. Keep this change separate from correctness and release-workflow fixes.

5. Cross-platform validation matrix

Platform	Environment	Minimum proof
macOS	Logged-in Lume macOS VM with exact source SHA and TCC grants	Two consecutive full certification runs for #2660, installer smoke, affected product rows, screenshots, logs, and videos
Windows	GitHub Actions for deterministic coverage, interactive Azure VM when desktop behavior changes	Install or upgrade, daemon and MCP smoke, affected GUI rows, external oracles, and video
Linux X11	GitHub Actions when representative, otherwise interactive Azure VM	Install or upgrade, daemon and MCP smoke, affected action rows, focus and input guards, and video
Linux Wayland	Representative GNOME or supported compositor session in Actions or Azure	Portal and accessibility preflight, affected action rows, external oracles, and video
Linux COSMIC	Representative session if available	No Orca launch, AT-SPI remains usable, one successful action
Linux gVisor	Existing authorized sandbox environment if available	Process exit and launch effects independently verified, with no silent success

Hosted CI proves deterministic build and unit contracts. It does not substitute for a real interactive desktop when the claim depends on focus, z-order, TCC, compositor routing, or visible cursor behavior.

6. Documentation and examples audit

After the product PRs are stable:

1. Audit public Cua Driver tutorials, how-to guides, reference pages, generated tool schemas, examples, and post-install output.
2. Verify that:
   • 0.13.1 is described as the installed baseline until 0.13.2 is released;
   • no page claims 0.13.2 is available;
   • installer instructions use canonical component resolution;
   • permission and session examples match the shipped contract;
   • cursor customization documents required states and the drag timeline;
   • Linux accessibility guidance explains the safe advertisement default and override;
   • process-control errors and timeouts are documented where user action is possible.
3. Regenerate checked-in references with repository-owned generators.
4. Run link, formatting, generated-output, and sensitive-information scans.
5. Keep internal execution notes out of public-facing pages.

7. PR and merge discipline

Use one focused PR for each independent unit:

1. cursor size, badge, and action-motion correctness
2. #2660 macOS certification harness
3. #2662 release automation
4. #2661 Linux process control
5. #2630 COSMIC accessibility advertisement
6. #2625 drag cursor animation, unless the confirmed cursor PR fully supersedes it
7. any documentation-only reconciliation that cannot live accurately with its product PR

For every PR:

• synchronize with the latest origin/main immediately before final validation;
• inspect the final changed files and live PR title;
• preserve contributor credit;
• run the exact relevant unit, integration, generated-output, and platform checks;
• attach exact-SHA evidence;
• address review feedback;
• wait for required checks;
• merge only after the completion bar is satisfied;
• verify main contains the merge before starting dependent validation.

Do not combine unrelated fixes merely to reduce PR count.

8. Final merged-main certification

After all accepted PRs merge:

1. Fetch the final origin/main and record its exact SHA.
2. Run deterministic Rust, script, installer-contract, release-metadata, docs, Python SDK, and TypeScript SDK checks affected by the work.
3. Run the representative macOS, Windows, Linux X11, and Linux Wayland E2E cells affected by the merged changes.
4. Verify canonical 0.13.1 installation still works. Source-built tests must report their source SHA and must not be confused with the released binary.
5. Verify no tag, GitHub release, PyPI version, npm version, or installer baked version was changed to 0.13.2.
6. Publish a final internal readiness report containing:
   • merged PRs and issues;
   • final main SHA;
   • per-platform results;
   • videos and run links;
   • supported, refused, unavailable, and unproven cells;
   • exact remaining work owned by Francesco for tomorrow's 0.13.2 release.

9. Stop and escalation conditions

Continue autonomously through ordinary implementation choices, test failures, flaky infrastructure repair, documentation changes, and PR feedback.

Stop and ask only if:

• a public contract requires a breaking change;
• a required representative environment needs new paid infrastructure or credentials;
• a security vulnerability is discovered;
• a destructive or irreversible external action is required;
• a release, tag, deployment, or package publication would occur;
• a protected branch or required human review prevents an otherwise ready merge.

An isolated failed run, a VM crash, a full disk, a CI timeout, or a different recoverable defect is not a reason to stop. Preserve evidence, repair the environment or implementation, and retry.

10. Explicit exclusions

• Creating or publishing 0.13.2
• Merging a 0.13.2 Release Please PR
• General backlog cleanup
• Reviewing unrelated contributor PRs
• Refactoring the daemonless architecture without a regression requiring it
• Expanding permission policy beyond what a reproduced issue requires
• Changing public contracts without explicit approval

11. Additional GitHub work after confirmed scope

After all confirmed P0 and P1 work passes and merges:

1. Refresh open Cua Driver issues and PRs from current GitHub state.
2. Exclude work already owned by another active task or contributor review.
3. Rank candidates by:
   • silent false success or data-loss risk;
   • regression affecting released 0.13.1 behavior;
   • installer or release blocker for 0.13.2;
   • cross-platform user impact;
   • bounded implementation and representative testability.
4. Prefer superseding a stale PR only when:
   • its useful behavior is still needed;
   • direct landing is no longer practical;
   • authorship can be preserved through cherry-pick or coauthor credit;
   • parity is proven before closing the source PR.
5. Take only work that can be implemented, tested, reviewed, and merged without weakening the final merged-main certification.