Ubuntu DEB upgrades must preserve a zero-configuration working install

[KesleyDavid]

Summary

This issue tracks upgrade-path findings discovered while validating the merged Ubuntu Desktop work from #29 on a real Ubuntu installation.

The validation upgraded an existing OpenMausBot 0.1.7 DEB installation to a locally built and fully verified 0.1.27 package on Ubuntu 24.04 x86_64 with GNOME/X11. Clean-package verification passed, but the real in-place upgrade exposed behavior that extraction-only checks cannot detect.

This is an accumulating validation issue. We will keep adding confirmed findings here and implement them after the verification pass is complete.

Product contract

An Ubuntu user should be able to:

1. Download OpenMausBot.
2. Install or upgrade it through the normal desktop/package flow.
3. Open it and use the supported features without a terminal, manual chmod, path configuration, or separate CUA Driver installation.

Only consent that must belong to the user should remain interactive: administrator authorization, OS screen/control permission, OAuth login, and credentials for optional paid services.

Confirmed findings

1. A DEB upgrade can retain unsafe legacy directory modes

• Make an in-place DEB upgrade repair the exact app-owned executable path automatically.

The new 0.1.27 DEB contains these directories as root:root 0755, but upgrading over the existing 0.1.7 installation retained legacy 0775 modes for:

/opt/OpenMausBot
/opt/OpenMausBot/resources

The bundled CUA Driver correctly refuses a group-writable parent path, so local computer control remained unavailable after an otherwise successful upgrade. Applying 0755 to those two directories and rerunning the installed-package smoke made the real bundled CUA runtime pass.

The permanent fix should be an idempotent DEB install/upgrade hook that repairs and verifies only the exact app-owned directories. Users must never be asked to run chmod themselves, and the runtime validator must not be weakened.

2. CI does not currently prove the real in-place upgrade path

• Add a DEB upgrade regression lane, not only clean extraction/install checks.

The package verifier correctly validated the modes stored in the newly built archive, but that could not reveal modes preserved from an older installed package.

The regression lane should:

1. Install the oldest supported Ubuntu DEB fixture.
2. Upgrade it with the newly built DEB.
3. Assert root:root 0755 on every parent of the bundled driver.
4. Launch /opt/OpenMausBot/openmausbot with CUA_DRIVER_PATH unset.
5. Prove the bundled driver is selected and ready after the explicit in-app opt-in.
6. Prove normal quit and hard-death cleanup leave no daemon, socket, PID file, stale descriptor, or private AppImage stage.
7. Prove bots, messages, configuration, and encrypted credentials survive the upgrade.

3. Optional managed-service latency can delay desktop readiness

• Ensure an unavailable or slow managed Composio service cannot prevent the desktop window from becoming usable.

The first packaged smoke timed out while startup waited for the managed Composio installation request in a restricted-network environment. The complete Linux smoke passed once the optional broker dependency was made deterministic, and the normal online launch also succeeded.

This is cross-platform startup behavior discovered during Ubuntu validation. The product contract should be explicit: chat and local engines must open promptly when an optional hosted integration is offline, slow, or blocked. CI should not depend on the public broker for desktop-readiness assertions.

4. Managed Connected Apps inventory endpoint is out of sync

• Restore the complete Connected Apps inventory contract or split this into a dedicated broker issue once ownership is confirmed.

On the installed app:

• managed Composio registration succeeded;
• /api/connectors/catalog returned the live API catalog;
• /api/connectors?services=gmail,github returned 200 with correct per-service states;
• /api/connectors/connected returned 404 {"error":"not found"} because the hosted broker did not expose the expected /v1/connectors/connected route.

The UI catches that error, but the Connected tab can appear empty even when the rest of managed Composio is healthy. This is not Ubuntu-specific, but it was found in the Ubuntu end-user validation and belongs here until it is assigned to the correct app or broker fix.

Confirmed working in the same validation

• 0.1.27 DEB installed over 0.1.7 without losing the two existing bots or their messages.
• Credential migration created credentials.bin with mode 0600.
• The real installed Electron window rendered with native Ubuntu window chrome.
• The embedded server answered /api/health with the expected app identity and static UI enabled.
• The bundled CUA Driver 0.19.3 passed the installed-package smoke after repairing the inherited directory modes.
• A real Codex turn returned the expected response; the temporary validation bot was deleted afterward.
• Grok, Claude, Codex, Antigravity, and OpenCode Go were detected as available on the host.
• The updater correctly reported 0.1.27 as current.
• Unit, type, packaged-server, Linux package, AppImage, X11, guarded Wayland, lifecycle, and hard-death smoke suites passed.

Final acceptance criteria

• A supported old Ubuntu DEB upgrades to the current version through the normal package flow with no terminal steps.
• Clean install and upgrade produce the same secure runtime modes and ownership.
• The first launch works online, offline, and with a slow optional broker.
• Supported local engines and ordinary chat remain usable without Box or self-hosted Composio credentials.
• Local computer control needs only the explicit in-app consent required by the security model; driver installation and filesystem repair are automatic.
• GNOME/X11 and GNOME/Wayland show truthful capability states and never ask users to configure implementation details.
• Existing bots, messages, settings, and encrypted credentials survive the upgrade.
• CI installs and runs the actual upgraded DEB payload, rather than validating only an extracted archive.

Related umbrella: #29

[KesleyDavid]

Additional confirmed finding: first Linux local-control opt-in can become non-recoverable in the UI

Real installed-app validation on Ubuntu 24.04 x86_64, GNOME/Xorg, OpenMausBot 0.1.27:

1. The user opened a supported bot's Computer panel and clicked Enable local control (Beta).
2. The card changed to Needs attention / Starting the private Cua Driver runtime….
3. Both Try again and Disable local control remained disabled. The user reported that the rest of the app could not be clicked and had to close the window.
4. The preference timestamp and clean-quit descriptor show that the first-enable state lasted about 66 seconds before the app was closed.

Post-close evidence:

• the opt-in was persisted as enabled;
• the app and server exited cleanly;
• no cua-driver process was orphaned;
• the descriptor was safely downgraded to status: stopped, reasonCode: app-stopped.

The driver installation and desktop prerequisites are healthy:

• cua-driver --version: success in less than 0.01s;
• cua-driver manifest: success in less than 0.01s;
• cua-driver doctor --json: success in 0.02s, with X11, six visible windows, and AT-SPI all reported healthy;
• the exact production createLinuxCuaRuntime path started the bundled daemon, reached ready, and shut down cleanly in 0.013s in the same real desktop session;
• reopening the installed app with the persisted opt-in transitioned directly to ready and started the supervised bundled daemon successfully.

This currently looks like an intermittent first-opt-in/UI-IPC state problem rather than a driver installation failure. Regardless of the underlying race, a user must never be trapped behind a pending setup action.

Required work

• Put a bounded end-to-end deadline on the first-enable UI operation and always settle the renderer promise.
• Keep a working Cancel or Disable local control action available while the runtime is checking/starting.
• Never block unrelated chat/navigation controls while local control starts.
• Let capability broadcasts recover the card to ready or error even if the original enable IPC response is delayed or lost.
• Preserve and surface a bounded, sanitized daemon-start diagnostic instead of discarding all child stderr.
• Record phase timings (inspection, spawn, handshake) so a future stall identifies its exact boundary.
• Add tests for first opt-in, a stalled inspection, a stalled handshake, cancellation during startup, close during startup, and restart recovery.

Additional UX finding: This computer setup is difficult to discover

The tester initially could not find how to enable This computer. The opt-in is inside each bot's Computer panel, while App Settings exposes a separate section named Local VM. Those are different products, but their placement/naming makes the setup path easy to misunderstand.

• When This computer is unavailable because opt-in is off, provide an inline Enable local control action beside that choice.
• Keep This computer and Local VM explanations visibly distinct: the former is the user's active Ubuntu desktop; the latter is an isolated container desktop.
• After successful enablement, automatically return focus to the pending This computer selection or clearly show the next action.
• Keep the zero-configuration contract: users should not need documentation to find the normal setup path.

[KesleyDavid]

Severity correction: blocker — starting Linux local control captures the real X11 seat

The earlier first-opt-in comment treated this primarily as a stuck UI/IPC state. A second real-user reproduction shows that diagnosis was incomplete and the impact is critical.

Reproduction

Environment: installed OpenMausBot 0.1.27, Ubuntu 24.04 x86_64, GNOME/Xorg, bundled Cua Driver 0.19.3.

1. On the first opt-in, the card remained at Starting the private Cua Driver runtime… and the user lost the ability to click or type on the desktop until OpenMausBot was closed.
2. The opt-in had been persisted before readiness.
3. On the next ordinary launch, OpenMausBot automatically started the driver from that preference. Global mouse/keyboard input was captured immediately, before the app window became usable. The user again had to close OpenMausBot to recover the seat.
4. Closing the app terminated the owned driver and immediately restored input. No orphan remained.
5. The preference has now been repaired out of band to linuxLocalControlEnabled: false with mode 0600; no OpenMausBot or Cua process is active.

This is reproducible across the first enable and the following persisted-enabled launch. The direct runtime diagnostic reaching ready does not prove safety because it checked handshake/lifecycle but did not assert that a human could still use the real seat. The Xvfb smoke also cannot detect a physical-session input grab.

Release safety requirement

Linux This computer control must fail closed until this is understood and fixed. A daemon becoming healthy must never seize the user's pointer or keyboard merely by starting; only an approved, bounded action may synthesize input.

• Do not auto-start Linux local control on app launch from a previously persisted opt-in while this bug is unresolved.
• Do not persist the durable enabled preference before startup and the seat-safety check complete successfully.
• If first enable is interrupted, crashes, or times out, the next launch must open safely with local control off.
• Keep the rest of OpenMausBot and the operating system interactive during inspection, daemon startup, handshake, retry, disable, and shutdown.
• Provide an in-app safe recovery path that never requires a terminal or editing JSON.
• Preserve standard-mode approval boundaries: starting the daemon grants no mouse/keyboard action and cannot create a global input grab.
• Add a real GNOME/Xorg acceptance test proving an unrelated application remains clickable and typeable before any tool call, after denial, after approval, and after daemon shutdown.
• Test restart with a persisted enabled preference and prove the window renders and remains controllable before any driver work.
• Add equivalent real-seat GNOME/Wayland evidence before claiming that session safe; Xvfb/simulated Wayland is insufficient for this boundary.
• Consider temporarily disabling the Linux Enable local control control in release builds until the real-seat test passes.

User recovery performed

The application was closed, no app/driver process remained, and the private preference was changed back to disabled. The installed app should now open without starting Cua. We will not re-enable the driver on this host during validation until a safe fix is available.

[KesleyDavid]

Safe Ubuntu validation round — installed DEB and AppImage

I completed the remaining tests that do not require starting Cua again. Linux local control remained explicitly disabled throughout this round.

Environment: Ubuntu 24.04 x86_64, GNOME/Xorg, OpenMausBot 0.1.27.

Passed

• Installed DEB launched with the existing user profile; /api/health returned { app: "openmausbot", static: true } and one native application window was present.
• While OpenMausBot was running, an unrelated Zenity window remained interactive. Automated typing entered the exact expected phrase and submitted it successfully, proving the real mouse/keyboard seat remained available with local control disabled.
• A temporary bot completed a real Codex turn and returned the exact requested sentence. The temporary bot was removed afterward and the original bot count was preserved.
• A validated main-process termination cleaned up the Electron app and embedded server immediately. All health ports closed and no Cua process or descriptor remained active. This validates the signal-driven cleanup path; it does not claim that a synthetic X11 window-close event is equivalent to clicking the native close button.
• The installed desktop entry passes desktop-file-validate and has the expected executable, icon, StartupWMClass, and categories.
• The release AppImage launched against a disposable profile in 3.569 s, exposed healthy static content, created one window, kept Cua disabled, exited cleanly, and left no process or temporary profile behind.

Confirmed startup finding

With a disposable first-launch profile and a managed Composio broker that accepted the TCP connection but never replied, the application window and health endpoint did not become ready until 17.826 s. After the broker timeout, the app rendered and cleaned up correctly. Optional integration discovery therefore remains on the critical startup path and should be moved behind first paint or given a much shorter non-blocking deadline.

The same AppImage reached a usable window in 3.569 s when the configured broker endpoint failed immediately, which further isolates the delay to the slow optional-broker path rather than Electron packaging.

Excluded/inconclusive evidence

Launching the desktop entry through gtk-launch from the automation shell was killed with the tool-owned process scope before application readiness. Since this does not reproduce a normal click from GNOME Activities, it is not classified as an application failure.

Final safe state

• No OpenMausBot or Cua process is running.
• Ports 8799, 18799, and 28799 are closed.
• cua-local-control.json still has linuxLocalControlEnabled: false and mode 0600.
• No disposable test profile remains.

No additional blocker was found in this safe round. The previously reported X11 seat-capture defect remains a release blocker, and Linux This computer must not be enabled on this host until that boundary is fixed and validated on a real seat.

[KesleyDavid]

Implementation started in #346

The first corrective PR is now open with four reviewable commits and remains linked with Addresses #345 so this issue will not close prematurely.

Implemented in the PR:

• Linux local control now fails closed behind a source-level release safety hold. The app does not inspect, stage, or start Cua, clears a legacy durable opt-in, ignores ambient/override driver paths, and presents an honest Temporarily unavailable state.
• The local-control card keeps Disable available during a normal pending startup state, so the recovery action is no longer tied to the same broad busy flag.
• The DEB has an idempotent after-install hook that repairs and verifies only the exact package-owned CUA directory/executable chain as root:root 0755.
• Linux CI now creates and installs a minimal 0.1.7 legacy DEB, proves the inherited 0775 modes, upgrades with the new artifact, validates ownership/modes, and runs the installed payload smoke before always purging the fixture.
• Managed Composio registration now starts after the server and first window are usable. A private Electron parent-port message updates the embedded server without exposing the credential to the renderer or requiring a restart.
• Packaged smoke tests hold a deterministic broker request open and prove first paint is not delayed.
• Connected Apps no longer converts an inventory failure into a false No connected apps state; it displays the error and a direct Try again action.
• Ubuntu and contributor docs now describe the temporary safety hold and explicitly reject manual driver/chmod workarounds.

Local validation completed:

• 148 test files; 1,524 passed and 8 pre-existing skips
• typecheck, Electron syntax checks, and contrast check
• documentation build: 111 static pages
• offline AppImage + DEB build and artifact verifier
• unpacked, AppImage, and simulated GNOME/Wayland package smokes
• no CUA or embedded-server process left behind

Still intentionally open:

1. The GitHub Actions run must execute the privileged installed-DEB upgrade lane on an ephemeral runner. This is not safe to run over the tester's real installed package.
2. The hosted Connected Apps worker still needs its current source deployed so the existing connected-inventory route reaches production.
3. The underlying Cua real-seat input-capture defect is not declared fixed. Linux This computer remains disabled until the real GNOME/Xorg and GNOME/Wayland seat-safety matrix passes.

PR: #346

[KesleyDavid]

#346 validation complete and ready for review

The repository CI exposed one more end-user upgrade defect after the first implementation pass: the configured DEB left /opt/OpenMausBot/chrome-sandbox without the required root:root 4755 state, so Electron aborted before opening the installed application.

This is now fixed in the package-owned post-install hook. The hook validates the exact regular file, refuses symlinks, applies root:root 4755, verifies the result, and remains idempotent. A dedicated regression test covers the mode repair and symlink refusal, and the privileged upgrade lane asserts the installed sandbox before launching the application.

Final evidence from GitHub Actions:

• the minimal 0.1.7 fixture installed with the reproduced legacy 0775 directories;
• apt upgraded it to the new 0.1.27 DEB and configured declared dependencies;
• the post-install hook repaired the CUA path and Chromium sandbox automatically;
• /opt/OpenMausBot/openmausbot launched successfully with the sandbox enabled;
• slow optional-broker startup, first paint, fail-closed Linux CUA behavior, normal exit, and cleanup all passed;
• Ubuntu, Windows, macOS, Swift/iOS, and Linux packaging jobs are green.

PR #346 now contains six focused commits, is synchronized with the current main, and is ready for maintainer review. This issue intentionally remains open: deploying the current Connected Apps worker and proving the underlying Cua real-seat safety on GNOME/Xorg and GNOME/Wayland are still pending.

[KesleyDavid]

Final #346 validation after rebase — 2026-08-21

PR #346 is rebased onto current main and now fixes both the zero-configuration upgrade path and the Xorg seat-safety regression found during real use.

Completed and verified:

• legacy 0.1.7 DEB directories upgrade to root-owned 0755 runtime paths;
• chrome-sandbox is installed as root:root 4755 through an idempotent package hook;
• Ubuntu 24.04 GNOME/Xorg local control requires explicit schema-2 opt-in and runs Cua with --no-overlay;
• the user's physical pointer and keyboard remain usable while bot click/type actions use a private logical cursor;
• GNOME/Wayland remains fail-closed;
• normal close, SIGINT/SIGTERM, crash/retry, and stale AppImage-stage cleanup are covered;
• managed Composio URLs are HTTPS/loopback validated, redirects and inherited unvalidated broker variables are rejected, and Connected Apps refresh races are fixed;
• real Grok 4.6 + LibreOffice Writer E2E saved and independently verified an ODT through computer tools.

Final head 2628702a passed Ubuntu, macOS, Windows, Swift/iOS, and the Ubuntu package+smoke job. The package job installed a 0.1.7 fixture, upgraded it to 0.1.27, verified package modes, launched the installed DEB, and completed bundled-CUA lifecycle cleanup.

This issue remains open only because deployment of the current hosted Connected Apps worker is external to this repository change. The code and Ubuntu artifact work in #346 is ready for maintainer review.

[OWConnoi]

Real-user confirmation of finding 4's exact user-visible shape (0.1.32, macOS, managed broker mode): bots kept using previously linked apps through the MCP path while the Connected tab rendered "No connected apps yet", because /api/connectors/connected failing is swallowed client-side and renders as empty rather than as an error. Opened #414 to make that failure state honest and to avoid registering a fresh installation over an unreadable credential store.

One more observation worth a decision while this issue is open — mode precedence: connectionMode returns managed whenever a broker token exists (server/composio.ts), so a user's own project key sits dormant while a managed installation is registered, and clearing the key in Settings doesn't change the mode either. That makes "paste your own key to use your own project" a no-op for packaged users until the broker identity disappears, which is surprising given the Settings copy implies the key is what's being used. If self-hosted-is-explicit is the intended semantics, a line in the key row ("managed mode is active; this key will be used if the managed service is unavailable") would remove the trap.

[tall27]

• Still reproduces on Windows v0.1.32 today, so not Ubuntu-specific
• The 401-vs-404 probe proving it’s an unrouted path, not auth
• That the 404 body text distinguishes an upstream 404 from a local one, useful for future triage