Adom Bridge

@@ -0,0 +1,91 @@+# Adom Bridge on Linux++Adom Bridge for Linux is the same app as on Windows, built from the same code and shipped in the same release. It signs in to the same Adom account, joins the same mesh, runs the same bridges, and answers the same verbs from the relay, the mesh and the local API (`127.0.0.1:24680`). It is packaged as one AppImage that runs on any recent x86_64 distribution (tested on Ubuntu 24.04, Fedora 44 and Debian 13; GNOME, Cinnamon; Wayland and X11).++Linux builds are on the **insiders** tier for now: the AppImage is an asset of each Adom Bridge release on this page, and the insiders manifest's `linux` entry is what Linux machines update from.++## Install++Download `adom-bridge_<version>_linux_x86_64.AppImage` from this page's release, then:++```bash+chmod +x adom-bridge_*_linux_x86_64.AppImage+./adom-bridge_*_linux_x86_64.AppImage --install+```++`--install` needs no sudo and writes only under your home folder:++| Path | What it is |+|---|---|+| `~/.local/share/adom-bridge-app/adom-bridge_<version>_linux_x86_64.AppImage` | the app |+| `~/.local/share/adom-bridge-app/adom-bridge-app.AppImage` | a stable link to it; self-update repoints it |+| `~/.local/share/adom-bridge-app/run.sh` | the launcher: starts one copy and exits quietly if one is running |+| `~/.local/share/applications/inc.adom.bridge.desktop` | the app menu entry |+| `~/.config/autostart/inc.adom.bridge.desktop` | start at login (Settings > Launch on boot turns it off and on) |++It then starts Adom Bridge. Running `--install` again from a newer AppImage upgrades in place. `--install --no-launch` installs without starting it. FUSE is not needed.++**Always start it through `run.sh`** (the menu entry and autostart do). Two copies of Adom Bridge on one machine share one identity and keep knocking each other off the relay; `run.sh` takes a lock and checks for a running copy first.++To remove it: quit Adom Bridge, then delete the paths above plus `~/.local/share/icons/hicolor/256x256/apps/adom-bridge.png`. Your settings and sign-in live in `~/.adom/`.++## With Hydrogen++On a machine that runs Hydrogen, Adom Bridge runs embedded, as on Windows:++- **One sign-in.** If Adom Bridge is signed out, it uses Hydrogen's Adom session; you are not asked to sign in twice. If you sign out of Adom Bridge yourself, it stays signed out until you sign in again.+- **It joins your mesh.** If nobody has chosen a mesh mode on this machine, Adom Bridge switches the mesh on in relay mode (nothing listens on your network). Your other machines then show a card asking you to let the new machine in. A mode you chose, including off, is never changed.+- **Approvals show in Hydrogen** as well as in Adom Bridge and in the desktop notification.++## Bridges and runtimes++Bridges with a Linux build (python, node, or a native `spawn.entrypoints.linux`) install and run as on Windows.++- **Node:** Adom Bridge uses your Node if it is version 18 or newer and has npm (it looks on PATH and in the usual places: nvm, volta, fnm, `/usr/local`, snap). Otherwise it downloads the official Node build for your CPU from nodejs.org into `~/.adom/adom-runtimes/` and checks its SHA-256 against the value built into the app before using it. No sudo, nothing installed system-wide.+- **Python:** your distribution's `python3`. If it is missing, the error says how to install it.++`adom-bridge runtimes` shows what each bridge will run with.++## Screenshots and windows++| | X11 | Wayland |+|---|---|---|+| `desktop_screenshot_screen` | read from the X server, no tools needed | through the desktop's screenshot service (xdg-desktop-portal) |+| `desktop_screenshot_window` | the window's area of the screen | the window itself, for windows running under XWayland (KiCad, for one): no prompt, and right even when another window covers it |+| `desktop_list_windows` | every window | windows running under XWayland only (on a stock GNOME desktop most apps are native Wayland, so the list is often empty and the reply says why) |++**Allowing screenshots on Wayland.** The first whole-screen screenshot on a Wayland desktop asks the person at the screen once: *Allow Adom Bridge to take screenshots?* Choose **Allow** and later screenshots are silent. GNOME asks this itself only while Adom Bridge's window is the focused window. When it is not (always the case when Adom Bridge runs inside Hydrogen), Adom Bridge asks in a desktop notification with **Allow** and **Not now** buttons; Allow stores the same answer GNOME would. Not now stores nothing, and the next screenshot asks again. To allow it ahead of time, or after choosing Deny:++```bash+flatpak permission-set screenshot screenshot inc.adom.bridge yes+```++(The `flatpak` command manages the desktop's permission store; Adom Bridge itself is not a Flatpak.) The screenshot service saves each capture to a file, which Adom Bridge reads and deletes at once.++## When memory runs out++Each bridge Adom Bridge starts, and each app it opens for your AI, runs in a systemd scope of its own. If the system kills one of them for memory (a KiCad with a very large board, say), Adom Bridge and the other bridges keep running. `systemctl --user list-units 'adom-bridge-child-*'` lists them.++## Notifications and approvals++Permission prompts appear as desktop notifications with their buttons (**Approve 1 hr**, **Deny**, and so on). Choosing one in the notification decides the request, exactly like the same button in Adom Bridge's window or in Hydrogen. A decision made anywhere else closes the notification. If the desktop's notification service cannot show buttons, the notification says so and the decision is made in Adom Bridge's window.++## Updates++Adom Bridge updates itself from the insiders manifest's `linux` entry: it downloads the new AppImage, checks its SHA-256, puts it beside the old one, repoints `adom-bridge-app.AppImage`, keeps the previous version for a rollback, and starts one new copy through `run.sh` after the old one has exited. `update_mode` works as on Windows (`prompt` by default; `auto` for an unattended machine).++## What does not work on Linux yet++| Feature | Status |+|---|---|+| Input verbs (`desktop_click`, `desktop_type`, ...) | not yet; planned: X11 first, then Wayland through the desktop's remote-control service |+| UI Automation (`desktop_ui_*`) | Windows only |+| Screen and window recording (`desktop_record_*`) | Windows only |+| Windows-only bridges (an `.exe` with no Linux entry, such as Fusion 360) | listed, never started; their verbs answer `unsupported_on_this_os` |++## Troubleshooting++- **It does not start / no window:** run `~/.local/share/adom-bridge-app/run.sh` and read `~/.local/share/adom-bridge-app/app.log`.+- **"Could not create default EGL display":** the AppImage carries its own Mesa EGL and uses it when the machine has none. `ADOM_BRIDGE_EGL=bundled` or `=system` forces one or the other.+- **A node bridge does not start:** `adom-bridge runtimes` shows whether Node was found or downloaded, and why a system Node was skipped.+- **Screenshots fail on Wayland:** the error says whether the screenshot service is missing, waiting for the person to answer, or was refused, and what to do.

@@ -2,21 +2,31 @@ name: adom-bridge-linux
 description: >-
   For Adom Bridge running on a Linux machine (the AppImage), not the adom-bridge CLI in a
-  container: install one copy, self-update, what is still Windows-only, Grok Bot computers
-  (wake with grok_wake). Use when installing, updating or debugging ab on Linux, or a Linux
-  mesh peer is unreachable.
+  container: --install, one copy, self-update, Wayland screenshots, what is still Windows-only,
+  Grok Bot computers. Use when installing, updating or debugging ab on Linux, or a Linux mesh
+  peer is unreachable.
 ---
 
 # Adom Bridge on Linux
 
-The Linux build is the same app as on Windows, packaged as an AppImage
-(`adom-bridge_<version>_linux_x86_64.AppImage`). It signs in to the same Adom
-account, joins the same mesh, and answers the same verbs from the relay, the mesh
-and the local API (`127.0.0.1:24680`). It is a **private preview**: the AppImage
-lives on the insiders tier, not the public page.
+The Linux build is the same app as on Windows, built from the same code and shipped
+in the same release, packaged as an AppImage
+(`adom-bridge_<version>_linux_x86_64.AppImage`, an asset of the release on
+adom/adom-bridge). It signs in to the same Adom account, joins the same mesh, and
+answers the same verbs from the relay, the mesh and the local API
+(`127.0.0.1:24680`). Linux is on the **insiders** tier: only the insiders
+manifest has a `linux` entry until a human promotes it.
 
 ## Install and launch: one copy, always
 
+**The AppImage installs itself:** `./adom-bridge_<ver>_linux_x86_64.AppImage --install`
+(no sudo, no FUSE). It copies itself to `~/.local/share/adom-bridge-app/`, points
+`adom-bridge-app.AppImage` at it, writes the locked `run.sh` below, a menu entry
+(`~/.local/share/applications/inc.adom.bridge.desktop`) and, while Launch on boot is on,
+`~/.config/autostart/inc.adom.bridge.desktop` (both run `run.sh`), then starts it.
+`--no-launch` skips the start. Running it again from a newer AppImage upgrades in place.
+What it sets up, and why:
+
 - Keep the AppImage in a folder of its own, for example
   `~/.local/share/adom-bridge-app/`, with a stable symlink
   `adom-bridge-app.AppImage -> adom-bridge_<version>_linux_x86_64.AppImage`.
@@ -25,14 +35,20 @@ lives on the insiders tier, not the public page.   checks for a running copy first**. Linux has no single-instance lock without a
   D-Bus session bus, and two copies share one identity: they knock each other off
   the relay every few seconds. A running copy is any process whose executable is
-  `*appimage_extracted*/usr/bin/adom-bridge` (or the AppImage file itself while it
-  extracts). `pgrep -f usr/bin/adom-bridge` does NOT match: the command line is just
+  `*appimage_extracted*/usr/bin/adom-bridge` (or `/tmp/.mount_*/usr/bin/adom-bridge`). `pgrep -f usr/bin/adom-bridge` does NOT match: the command line is just
   `adom-bridge`. Read `/proc/<pid>/exe` instead.
 - In a container or sandbox without FUSE, run it with `--appimage-extract-and-run`.
 - Set `DISPLAY` to the X display it should use.
 - `adom-bridge-app --version` prints the version and exits; it never starts a copy.
 
-A minimal `run.sh`:
+The `run.sh` that `--install` writes is equivalent to this minimal one (it also
+matches a FUSE-mounted `/tmp/.mount_*` copy, starts the app in its own systemd scope
+`app-adom-inc.adom.bridge-<pid>.scope` so desktop portals know which app is asking,
+with `OOMPolicy=continue` on systemd 253 and later so a child killed for memory does not
+stop Adom Bridge's scope,
+takes the session's display variables from `systemctl --user show-environment` when it
+has none, and passes its arguments through). Count only the app binary as a running
+copy: the AppImage runtime keeps the AppImage file as its own exe after the app exits.
 
 ```bash
 #!/bin/bash
@@ -41,7 +57,7 @@ exec 9>"$D/.launch.lock" flock -w 30 9 || exit 0
 for p in /proc/[0-9]*; do
   case "$(readlink $p/exe 2>/dev/null)" in
-    *appimage_extracted*/usr/bin/adom-bridge|*adom-bridge_*_linux_x86_64.AppImage) exit 0;;
+    *appimage_extracted*/usr/bin/adom-bridge) exit 0;;
   esac
 done
 export DISPLAY=:0
@@ -85,9 +101,40 @@ overrides). No `libs/` folder or extra packages are needed. | Works | Not yet (Windows only) |
 |---|---|
 | shell_execute, run_script, files (send_files, pull_file, read/write) | input verbs (desktop_click, desktop_type, ...) |
-| desktop_screenshot_screen, desktop_screenshot_window, desktop_list_windows (X11, 2.1.181+, no tools needed) | UI Automation (desktop_ui_*) |
-| bridges with a Linux build (python, node, or `spawn.entrypoints.linux`) | Windows-only bridges (a `.exe` with no Linux entry): listed, never started, verbs answer `unsupported_on_this_os` |
-| self-update, mesh, relay, notifications (notify-send) | recording |
+| desktop_screenshot_screen, desktop_screenshot_window, desktop_list_windows on X11 (no tools needed) and Wayland (see below) | UI Automation (desktop_ui_*) |
+| bridges with a Linux build (python, node, or `spawn.entrypoints.linux`); Node is the system one if 18+ with npm, else a verified nodejs.org download | Windows-only bridges (a `.exe` with no Linux entry): listed, never started, verbs answer `unsupported_on_this_os` |
+| self-update, mesh, relay, notifications with buttons (approve from the notification) | recording |
+
+## Wayland
+
+On a Wayland desktop (Ubuntu and Fedora GNOME) ab's own window is a native Wayland window
+(app id `inc.adom.bridge`), and X11 can neither read the screen nor see native windows.
+
+- `desktop_screenshot_screen` uses the xdg-desktop-portal Screenshot service. The first
+  capture on a machine shows the person a one-time *Allow Adom Bridge to Take Screenshots?*
+  prompt. GNOME shows its own prompt only while Adom Bridge's window is focused, which an
+  Adom Bridge embedded in Hydrogen never is; then Adom Bridge asks itself, in a desktop
+  notification *Allow Adom Bridge to take screenshots?* with **Allow** / **Not now**. Allow
+  stores the same answer GNOME's prompt would (`inc.adom.bridge: yes` in the permission
+  store) and the capture goes ahead; Not now stores nothing and the verb says so. Only the
+  person can answer it: never click it for them. While either prompt is up the verb waits
+  up to 45 s. After Allow, captures are silent. If it was refused:
+  `flatpak permission-set screenshot screenshot inc.adom.bridge yes` (the permission store, not a Flatpak
+  install). Check the stored answer with
+  `flatpak permission-show screenshot` or `gdbus call --session --dest org.freedesktop.impl.portal.PermissionStore --object-path /org/freedesktop/impl/portal/PermissionStore --method org.freedesktop.impl.portal.PermissionStore.Lookup screenshot screenshot`.
+- `desktop_screenshot_window` works for XWayland windows: it reads the window's own pixels
+  (no prompt, right even when covered), falling back to the portal capture, cropped.
+  A native Wayland window (most GNOME apps, Firefox, Hydrogen) has no readable position:
+  capture the screen.
+- `desktop_list_windows` lists XWayland windows only (stock GNOME refuses its full list to apps),
+  so it is often empty there; the reply's `_hint` says so.
+
+## With Hydrogen
+
+- Signed out + embedded: ab takes Hydrogen's session (`GET /auth-token` on Hydrogen's
+  loopback API); no second sign-in. A Sign out in ab's window is remembered.
+- Embedded, mesh off, and nobody ever chose a mode (no `~/.adom/mesh/mode-choice.json`):
+  ab switches the mesh to `relay` and records that; the other boxes show the join card.
 
 Commands a bridge or script runs get the machine's own environment, not the
 AppImage's private library paths, so `python3` and `curl` work normally.
@@ -145,3 +192,15 @@ Other things to know on a Grok computer:   KiCad bridge works only with a Linux build of that bridge.
 - **Checking what the box shows:** `desktop_screenshot_screen` and
   `desktop_list_windows` work (2.1.181+).
+
+## Memory kills and child processes
+
+Each long-lived process Adom Bridge starts (a bridge, an app from `app_launch` or
+`process_start`) is moved into a systemd user scope of its own,
+`adom-bridge-child-<name>-<pid>.scope`, with `OOMPolicy=continue`. When the kernel or
+systemd-oomd kills something for memory (a large board in a KiCad that a bridge
+opened, say), only that child's scope is affected; Adom Bridge and the other bridges
+keep running. `systemctl --user list-units 'adom-bridge-child-*'` shows them. With no
+user systemd (or when Adom Bridge was started from an ssh session, whose processes the
+user manager cannot move) the child stays in Adom Bridge's own group, and the log says
+so (`[scope] ... stays in Adom Bridge's scope`).