Add Ubuntu screen preview and guarded local control betas

.github/workflows/ci.yml

@@ -63,7 +63,7 @@ jobs:
           sudo chmod 4755 release/linux-unpacked/chrome-sandbox
           test "$(stat -c '%U:%G %a' release/linux-unpacked/chrome-sandbox)" = "root:root 4755"
       - name: Launch packaged app and verify lifecycle
-        run: dbus-run-session -- xvfb-run -a node scripts/smoke-linux-package.mjs
+        run: pnpm smoke:linux-package
       - uses: actions/upload-artifact@v4
         if: always()
         with:

CONTRIBUTING.md

@@ -101,8 +101,13 @@ The SPI in [`server/contracts.ts`](server/contracts.ts) is deliberately small. A
 - Renderer code must consume the desktop capability contract rather than infer support from Electron,
   the user agent, or the presence of a preload bridge. Screen preview, dictation, and local control are
   independent capabilities.
-- Test Ubuntu platform claims on a real GNOME session. Xvfb proves packaging and lifecycle, not Wayland
-  portal behavior or local computer control.
+- Test Ubuntu platform claims on a real GNOME session. Xvfb proves packaging and fake-driver orchestration, not
+  Wayland portal behavior or real CUA inspection/input delivery.
+- Linux local control must remain explicit: global opt-in plus per-bot **This computer**. Linux Auto, provider
+  full-auto/bypass modes, remembered grants, and cloud approvals must never authorize the user's desktop.
+- Keep user-installed CUA discovery shell-free and pin accepted manifest/driver contracts. Do not add a bundled
+  binary, automatic installer/update, or default-daemon ownership to the Linux beta. GNOME/Wayland readiness must
+  require its exact compositor/helper/portal health contract; never infer it from `WAYLAND_DISPLAY` or XWayland.
 - **Never build command strings for a shell.** No `shell: true`, no spawning through `cmd.exe` with
   quoted strings — model names, personas, and MCP config JSON travel through argv, and cmd.exe
   metacharacter expansion is a real injection class. On Windows, resolve `.cmd` shims to their JS

README.md

@@ -50,8 +50,8 @@ already have:
   — your existing logins and subscriptions, no new accounts, no proxy in the middle.
 - **Local first.** One small harness server on `127.0.0.1` owns every agent process. Transcripts, keys, and
   events live in `~/.openmausbot`, not a cloud.
-- **Agents with hands.** Each bot can get a real computer — a cloud Linux desktop it drives while you watch
-  live, or your own Mac — plus 500+ apps through Composio Connect.
+- **Agents with hands.** Each bot can use a cloud Linux desktop, an isolated Local VM, or your own computer,
+  plus 500+ apps through Composio Connect. Host control is available on macOS and as an explicit Ubuntu GNOME beta.
 
 ## Features
 
@@ -172,7 +172,7 @@ flowchart LR
 | API | `server/index.ts` | Bots, turns, approvals, model catalog, computer lifecycle, connectors, config — HTTP + SSE. |
 | Voice | `server/tts/` | ElevenLabs, bring your own key. Runs on the harness so the key never reaches the UI; markdown is rewritten into something worth hearing before it is spoken. |
 | App | `src/` | The chat shell. Server-backed store, one reducer, zero client-side transports. |
-| Desktop | `electron/` | macOS, Windows, and Ubuntu shells with an embedded harness and explicit platform capabilities; Apple speech, local screen capture, and the current CUA bridge remain macOS-only. |
+| Desktop | `electron/` | macOS, Windows, and Ubuntu shells with an embedded harness and platform capabilities; Apple speech stays macOS-only, while user-installed CUA can enable guarded Ubuntu GNOME local control. |
 
 ## Quick start
 
@@ -216,12 +216,17 @@ pnpm package:linux    # Ubuntu x64: .deb + AppImage; no Swift required
 |---|---|---|---|
 | Packaged app, embedded harness, local agent CLIs | Supported | Beta | Beta |
 | Composio and Box/cloud computers | Supported | Beta | Beta |
-| Local screen preview and computer control | Supported | Planned | Planned after compositor validation |
+| Explicit preview-only local screen capture | Supported | Beta | Beta |
+| Bot control of this computer | Supported | Beta: opt-in, Cua 0.19.3 | Beta: GNOME only, opt-in, Cua 0.19.3 + WinRects v8 |
 | Native on-device dictation | Supported | Planned | Planned |
 
-Unavailable native features fail closed on Ubuntu without blocking chat or cloud features. Linux local computer
-control, Wayland capture/automation, dictation, and ARM64 are tracked in
-[#29](https://github.com/milind-soni/OpenMausBot/issues/29) and are not claimed by the baseline package.
+The Linux preview is user-initiated and never enables local bot control or Auto routing. Linux control requires a
+separately installed Cua Driver 0.19.3, explicit app opt-in, and an explicit per-bot **This computer** selection;
+every local action asks for approval. GNOME/Wayland additionally requires the versioned WinRects v8 helper and a
+passing prompt-free AT-SPI/capture/portal health report. Other Wayland compositors fail closed without blocking
+chat or cloud features. See the [Ubuntu Desktop guide](docs/linux-desktop.md) and
+tracking issues [#29](https://github.com/milind-soni/OpenMausBot/issues/29) and
+[#79](https://github.com/milind-soni/OpenMausBot/issues/79) / [#109](https://github.com/milind-soni/OpenMausBot/issues/109).
 
 These credentials are optional — local chat works without them. Paste a key once in **App Settings** (gear
 in the sidebar footer) when you want to enable its integration:

docs/computer-use-integration.md

@@ -1,16 +1,18 @@
 # Computer use & browser use in OpenMausBot
 
 Decision doc, 2026-08-12. How bots in OpenMausBot get local computer use and
-browser use, out of the box, with no separate installs. Based on a survey of
-OSS chat-app MCP hosts, macOS control servers, browser-automation stacks, and
-the local `cua` / `axstream` code on this machine.
+browser use. macOS targets an out-of-the-box bundled provider; the staged
+Ubuntu beta currently verifies a separately installed, pinned provider. Based
+on a survey of OSS chat-app MCP hosts, macOS control servers,
+browser-automation stacks, and the local `cua` / `axstream` code on this
+machine.
 
 ## TL;DR architecture
 
-```
+```text
 Electron main process
-├── EmbeddedCuaDriverHost  ──spawns──▶  cua-driver (bundled Rust binary, Resources/)
-│     one TCC prompt, named OpenMausBot          │ unix socket (private)
+├── CUA host  ──spawns──▶  cua-driver (bundled on macOS; verified user install on Ubuntu 24.04 GNOME Xorg/Wayland betas)
+│     platform permission boundary               │ unix socket (private)
 ├── WebContentsView pool (embedded browser, persist: partitions per bot)
 │     driven via webContents.debugger (CDP) — zero-install browser use
 └── server/ harness (drivers spawn agent CLIs with --mcp-config)
@@ -21,8 +23,11 @@ Electron main process
 - **Plugins = MCP servers over stdio.** The Plugins panel toggles which MCP
   servers get injected into each bot's `--mcp-config`. Same pattern as Claude
   Desktop / Cherry Studio / LibreChat.
-- **Computer use = bundled `cua-driver`** (Rust, single static Mach-O,
-  23MB arm64 / 48MB universal — from `mywork/cua/libs/cua-driver/rust`).
+- **Local desktop use = `cua-driver`**. macOS packages the Rust Mach-O in app
+  Resources; the Ubuntu 24.04 GNOME/Xorg beta and guarded GNOME/Wayland beta
+  accept only the certified user-installed 0.19.3 Linux binary while bundling
+  is tracked separately. Remote/cloud boxes and the isolated Local VM remain
+  separate providers.
   NOT Swift — the Swift file everyone remembers
   (`examples/embedded-host-macos/ExampleAgentHarness.swift`) is a 165-line
   reference host showing the embedding pattern, not the driver.
@@ -31,18 +36,30 @@ Electron main process
   `webContents.debugger` CDP transport. No Chrome dependency, no 281MB
   Playwright download, and the user watches the bot browse inside the chat.
 
-## Computer use: CUA only — bundle cua-driver, spawn from Electron main
+## Local desktop use: CUA only — Electron owns the driver lifecycle
 
-**Decision (Milind, 2026-08-12): CUA is the ONLY computer-use provider.
+**Decision (Milind, 2026-08-12): CUA is the ONLY local desktop-control provider.
 No cliclick, no robotjs/nut.js, no Python computer-server, no fallbacks.**
-Everything that touches the user's screen/mouse/keyboard goes through the
-bundled `cua-driver` binary. Alternatives evaluated and rejected:
+All local desktop-control and input actions go through the validated
+`cua-driver` binary. Linux screen preview uses the supported Xorg or
+user-initiated XDG portal capture path and is not a control provider. This rule
+does not replace remote/cloud boxes or the isolated Local VM provider. Local
+alternatives evaluated and rejected:
+
+The Ubuntu GNOME beta is an intentional staged exception to the
+zero-install packaging statement: it uses the same official CUA provider but
+requires user-installed Cua Driver 0.19.3 while supply-chain bundling remains
+Phase 5 of [#29](https://github.com/milind-soni/OpenMausBot/issues/29). Electron
+still owns a private embedded daemon/socket, and the harness only receives the
+validated MCP proxy contract. Xorg is tracked in [#79](https://github.com/milind-soni/OpenMausBot/issues/79);
+GNOME/Wayland additionally requires WinRects v8 plus the exact Cua health-report contract tracked in
+[#109](https://github.com/milind-soni/OpenMausBot/issues/109).
 
 | Option | Verdict |
 | --- | --- |
 | cua `computer-server` (Python/FastAPI) | ✗ 200MB+ frozen Python, second TCC prompt under wrong identity |
 | axstream / cliclick / robotjs-class | ✗ rejected — CUA-only policy |
-| **cua-driver binary, embedded mode** | ✓ THE provider: zero deps, 20+ tools, its own stdio MCP proxy + socket daemon + TS SDK (`@trycua/cua-driver`), agent-cursor overlay, permission tooling |
+| **cua-driver binary, embedded mode** | ✓ THE provider: one contract, 20+ tools, its own stdio MCP proxy + socket daemon + TS SDK (`@trycua/cua-driver`), agent-cursor overlay, permission tooling |
 
 ### The rules (from `cua/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md` — read it end to end)
 
@@ -64,7 +81,7 @@ bundled `cua-driver` binary. Alternatives evaluated and rejected:
    grant change, destroy clients → `restart()` → reconnect (macOS caches TCC
    per process).
 
-### Packaging
+### macOS packaging target
 
 - Ship the binary at `OpenMausBot.app/Contents/Resources/cua-driver`,
   **outside the ASAR**, executable bit preserved (electron-builder