app: Linux (Ubuntu) support — Phase 1 (fork-internal CI run)

.github/workflows/app-release.yml

@@ -150,6 +150,95 @@ jobs:
             app/src-tauri/target/release/bundle/dmg/*.dmg
           if-no-files-found: warn
 
+  build-linux:
+    name: build (linux)
+    needs: verify-version
+    # Pin the release build to Ubuntu 22.04 so the shipped binaries retain
+    # glibc compatibility with supported Ubuntu installations. Revisit this
+    # when the supported Ubuntu baseline is raised or GitHub retires the label.
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: app
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: app/pnpm-lock.yaml
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: app/src-tauri
+
+      - name: Install Tauri Linux dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
+            librsvg2-dev patchelf libssl-dev libsoup-3.0-dev libxdo-dev \
+            build-essential curl wget file
+
+      - name: Install minisign verifier
+        run: |
+          set -euo pipefail
+          version=0.12
+          archive="$RUNNER_TEMP/minisign-linux.tar.gz"
+          install_dir="$RUNNER_TEMP/minisign/bin"
+          expected_sha256=9a599b48ba6eb7b1e80f12f36b94ceca7c00b7a5173c95c3efc88d9822957e73
+          curl --fail --location --silent --show-error \
+            "https://github.com/jedisct1/minisign/releases/download/$version/minisign-$version-linux.tar.gz" \
+            --output "$archive"
+          echo "$expected_sha256  $archive" | sha256sum --check --strict
+          mkdir -p "$install_dir"
+          tar --extract --gzip --file "$archive" --directory "$RUNNER_TEMP"
+          install -m 0755 "$RUNNER_TEMP/minisign-linux/x86_64/minisign" "$install_dir/minisign"
+          echo "$install_dir" >> "$GITHUB_PATH"
+          "$install_dir/minisign" -v
+
+      - name: Verify Tauri AppImage signature encoding
+        run: scripts/test-verify-minisign-appimage.sh
+
+      - name: Install frontend deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Bundle pinned agmsg-core
+        run: app/scripts/bundle-core.sh
+        working-directory: .
+        shell: bash
+
+      - name: Verify agmsg-core resource modes
+        run: scripts/test-verify-core-tree-modes.sh
+
+      - name: Build deb and AppImage
+        env:
+          # Linux updater artifacts use the minisign key pair. Apple and
+          # Microsoft signing credentials are platform-specific and must not
+          # be introduced into this job.
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: pnpm tauri build --bundles deb,appimage
+
+      - name: Verify Linux bundles
+        run: scripts/verify-linux-bundles.sh
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: agmsg-app-linux
+          path: |
+            app/src-tauri/target/release/bundle/deb/*.deb
+            app/src-tauri/target/release/bundle/appimage/*.AppImage
+            app/src-tauri/target/release/bundle/appimage/*.AppImage.sig
+          if-no-files-found: error
+
   build-windows:
     name: build (windows)
     needs: verify-version

.github/workflows/tests.yml

@@ -473,6 +473,80 @@ jobs:
         if: needs.changes.outputs.app_changed != 'false'
         run: cargo test --manifest-path src-tauri/Cargo.toml
 
+  # Keep the Linux test leg on the same Ubuntu generation as local validation.
+  # The explicit 24.04 label is intentional: it catches Linux cfg regressions
+  # against the Ubuntu 24 environment we support, while ubuntu-latest may move
+  # to 26.04. Revisit this pin when the real Ubuntu target is upgraded or when
+  # GitHub retires the label.
+  app-check-linux:
+    name: app typecheck (linux)
+    needs: changes
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    defaults:
+      run:
+        working-directory: app
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: No app changes — skipping Linux typecheck
+        if: needs.changes.outputs.app_changed == 'false'
+        run: echo "Diff does not touch app/ — reporting green without running the Linux typecheck."
+
+      - name: Install Tauri Linux dependencies
+        if: needs.changes.outputs.app_changed != 'false'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
+            librsvg2-dev patchelf libssl-dev libsoup-3.0-dev libxdo-dev \
+            build-essential curl wget file
+
+      - uses: pnpm/action-setup@v4
+        if: needs.changes.outputs.app_changed != 'false'
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        if: needs.changes.outputs.app_changed != 'false'
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: app/pnpm-lock.yaml
+
+      - uses: dtolnay/rust-toolchain@stable
+        if: needs.changes.outputs.app_changed != 'false'
+
+      - uses: Swatinem/rust-cache@v2
+        if: needs.changes.outputs.app_changed != 'false'
+        with:
+          workspaces: app/src-tauri
+
+      - name: Install frontend deps
+        if: needs.changes.outputs.app_changed != 'false'
+        run: pnpm install --frozen-lockfile
+
+      - name: TypeScript typecheck
+        if: needs.changes.outputs.app_changed != 'false'
+        run: pnpm exec tsc --noEmit
+
+      - name: Frontend tests
+        if: needs.changes.outputs.app_changed != 'false'
+        run: pnpm test
+
+      - name: Bundle pinned agmsg-core
+        if: needs.changes.outputs.app_changed != 'false'
+        run: scripts/bundle-core.sh
+
+      - name: Rust check
+        if: needs.changes.outputs.app_changed != 'false'
+        run: cargo check --manifest-path src-tauri/Cargo.toml
+
+      - name: Rust tests
+        if: needs.changes.outputs.app_changed != 'false'
+        run: cargo test --manifest-path src-tauri/Cargo.toml
+
   # Windows leg for the app: the command layer's bash resolution and path
   # conversion are all behind cfg(windows) and had never run in CI — the very
   # 0.1.1→0.1.3 regressions (WSL bash.exe, backslash argv). This runs cargo test

RELEASING.md

@@ -42,6 +42,100 @@ which:
 4. Generates the release notes for the tag with git-cliff and creates a
    GitHub Release from them.
 
+## Desktop app: Linux artifacts and updater metadata
+
+The desktop app has a separate `app-vX.Y.Z` release flow in
+`.github/workflows/app-release.yml`. Its Linux job runs on the pinned
+`ubuntu-22.04` image (glibc compatibility for distributed binaries) and asks
+Tauri for exactly `deb,appimage` bundles. Before uploading artifacts, run:
+
+```bash
+cd app
+scripts/verify-linux-bundles.sh src-tauri/target/release/bundle
+```
+
+The check must find one `.deb`, one executable `.AppImage`, and the matching
+`.AppImage.sig`, and no RPM. It also checks the Debian runtime dependencies and
+the executable bits of the bundled `agmsg-core` scripts in both formats.
+
+### Linux release validation (manual)
+
+The bundle script covers deterministic archive checks. Before publishing a
+desktop release, complete these checks on the built `.deb` and `.AppImage`
+executables as well:
+
+1. **Updater acceptance (plan 5(e)).** Point a test build at the candidate
+   `latest.json` and confirm that an AppImage accepts the `linux-x86_64` entry
+   containing the matching AppImage URL and `.AppImage.sig` contents. Confirm
+   that a `.deb` does not run an updater check and instead follows the release
+   page installation path. If an endpoint-backed check is not practical for a
+   release, record the first-release manual verification in the release notes.
+2. **Terminal copy/paste (plan 5(f)).** In each shipped format, verify all three
+   Linux terminal paths: right-click Copy, PRIMARY-selection middle-click
+   paste, and `Ctrl+Shift+C`/`Ctrl+Shift+V`. These checks preserve the Option B
+   decision to omit the inert native Edit submenu.
+3. **Runtime WebKit (plan 5(g)).** While each format is running, use `ldd`
+   (or `/proc/<pid>/maps`) to record which `libwebkit2gtk` is loaded. An
+   AppImage's bundled-versus-system WebKit behavior is an environment record
+   for diagnosing WebKit-dependent behavior such as a blank window (including
+   DMA-BUF renderer issues), and for documenting whether the AppImage bundles
+   WebKit or relies on the system library.
+
+Linux updater behavior is a product policy: only an AppImage self-updates. A
+Debian package could technically be replaced through `pkexec`, a GUI sudo
+prompt, or `dpkg -i`, but this project does not adopt a self-replacement flow
+that escalates privileges. Tell `.deb` users to download and install the newer
+package from the release page instead. macOS and Windows updater behavior is
+unchanged.
+
+The `platforms` map in the hand-authored `latest.json` is cumulative. Start from
+the current file and preserve the existing `darwin-aarch64` and
+`windows-x86_64` objects; merge only the new `linux-x86_64` object. Do not
+replace the map with a Linux-only object, or the existing macOS/Windows updater
+paths will stop working. The Linux entry must pair the AppImage URL with the
+exact contents of its v2 signature file (not a URL to the signature file).
+Local bundle verification requires `jq` and `minisign` on `PATH`.
+Run `app/scripts/bundle-core.sh` first; the verifier fails closed when its
+source `agmsg-core` tree is absent because packaged resource modes are compared
+against that tree.
+
+```bash
+set -euo pipefail
+
+APPIMAGE_URL="https://github.com/fujibee/agmsg/releases/download/app-latest/agmsg_0.4.0_amd64.AppImage"
+APPIMAGE_SIG="$(cat agmsg_0.4.0_amd64.AppImage.sig)"
+candidate="latest.json.next"
+jq --arg url "$APPIMAGE_URL" --arg signature "$APPIMAGE_SIG" \
+  '.platforms["linux-x86_64"] = {url: $url, signature: $signature}' \
+  latest.json > "$candidate"
+
+# Inspect the merge: the existing macOS/Windows entries must still be present,
+# and Linux must point to an AppImage with a non-empty matching signature.
+jq -e '
+  .platforms["darwin-aarch64"] != null and
+  .platforms["windows-x86_64"] != null and
+  (.platforms["linux-x86_64"] != null) and
+  (.platforms["linux-x86_64"].url |
+    if type == "string" then endswith(".AppImage") else false end) and
+  (.platforms["linux-x86_64"].signature |
+    if type == "string" then length > 0 else false end)
+' "$candidate"
+mv -- "$candidate" latest.json
+```
+
+When updating the fixed `app-latest` release, upload the Linux `.deb`, the
+AppImage, its `.AppImage.sig`, and this `latest.json` together. Keep the
+`linux-x86_64` URL and signature from the same build; a signature copied from a
+different AppImage makes the updater reject the artifact.
+
+The explicit `sqlite3` entry in `app/src-tauri/tauri.conf.json` is intentional.
+The app's Rust `rusqlite` dependency uses the bundled SQLite library, while the
+`agmsg-core` resource invokes the system `sqlite3` command from its install
+script (`app/src-tauri/resources/agmsg-core/install.sh`, the missing-command
+check around lines 209–212). Do not remove that Debian dependency unless the
+resource's runtime requirement and the package's `Depends` field are both
+revalidated.
+
 ### Manual steps (if you'd rather not use the script)
 
 ```bash

app/README.md

@@ -1,11 +1,12 @@
 # agmsg desktop app
 
-The official agmsg desktop app (macOS/Windows, desktop-first): a terminal-embedded
+The official agmsg desktop app (macOS/Windows/Linux, desktop-first): a terminal-embedded
 GUI that spawns agents in real PTYs and delivers agmsg messages to ANY interactive
 CLI agent by injecting them into the agent's stdin at its idle prompt — no per-agent
 bridge, hook, or monitor tool.
 
-> Status: past Phase 0 — daily-driven, macOS-signed and notarized, auto-updating.
+> Status: past Phase 0 — daily-driven, macOS-signed and notarized. macOS and
+> Windows update in place; Linux AppImage builds use the same updater policy.
 
 ## Install
 
@@ -23,8 +24,14 @@ normally with no Gatekeeper right-click workaround needed.
 **Windows**
 Download the `.msi` or `.exe` installer from the same [Releases page](https://github.com/fujibee/agmsg/releases).
 
-Both platforms auto-update in place after install (**agmsg → Check for
-Updates…**, or silently on launch).
+**Linux (Ubuntu)**
+Download the `.deb` or `.AppImage` from the same [Releases page](https://github.com/fujibee/agmsg/releases).
+The AppImage can update in place; a `.deb` is updated by downloading the newer
+package from the release page (it does not self-update).
+
+macOS, Windows, and Linux AppImage builds can check for updates after install
+(**agmsg → Check for Updates…**, or silently on launch). The Linux `.deb` path
+is deliberately excluded from the updater; see the product policy below.
 
 Prerequisite either way: agmsg itself installed at `~/.agents/skills/agmsg` (the
 app reads its DB and team config from there) — see the
@@ -84,14 +91,17 @@ DB and team config from there). `claude` must be on `PATH` to spawn Claude Code
 
 ## Releasing
 
-`.github/workflows/app-release.yml` builds, signs, and (macOS) notarizes both
-platforms on a push of an `app-vX.Y.Z` tag (or by hand via `workflow_dispatch`).
+`.github/workflows/app-release.yml` builds, signs, and (macOS) notarizes all
+supported desktop platforms on a push of an `app-vX.Y.Z` tag (or by hand via
+`workflow_dispatch`).
 macOS goes through codesign → notarize → staple end to end in CI. Windows builds
 and, given Azure credentials, runs Trusted Signing (OIDC via `azure/login`, no
 client secret) — that federated identity trusts `main` only, so it can't be
 exercised from a feature branch. The workflow deliberately doesn't publish a
 GitHub Release itself; cutting one is still a human-gated step (upload artifacts
-+ hand-author `latest.json`, below).
++ hand-author `latest.json`, below). The Linux job requests exactly a `.deb`, an
+`.AppImage`, and its `.AppImage.sig`; run `app/scripts/verify-linux-bundles.sh`
+against the downloaded bundle directory before uploading it.
 
 For a local macOS build without CI:
 ```sh
@@ -103,7 +113,11 @@ pnpm build:notarize   # sources APPLE_ID / APPLE_PASSWORD / APPLE_TEAM_ID from
 ```
 
 Auto-update is wired up via `tauri-plugin-updater`, checked silently on launch and
-on-demand via **agmsg → Check for Updates…**. The private signing key lives in
+on-demand via **agmsg → Check for Updates…**. On Linux this is a product policy,
+not a technical limitation: only AppImage bundles self-update. A `.deb` could be
+replaced with an elevated package-manager operation, but this project does not
+adopt a self-replacement flow that prompts for privilege escalation; install a
+new `.deb` from the release page instead. The private signing key lives in
 the worktree-root `.secrets/` locally (never committed) and as the
 `TAURI_SIGNING_PRIVATE_KEY`/`TAURI_SIGNING_PRIVATE_KEY_PASSWORD` secrets in CI.
 `TAURI_SIGNING_PRIVATE_KEY` must be the **decoded** minisign key text itself
@@ -132,12 +146,14 @@ gh release create app-latest --repo fujibee/agmsg --title "agmsg (latest)" \
 
 # Cut a normal versioned release for history/changelog, from CI's artifacts...
 gh release create app-vX.Y.Z --repo fujibee/agmsg --title "agmsg vX.Y.Z" \
-  <downloaded macOS .app.tar.gz, .sig, .dmg, Windows .msi, .exe>
+  <downloaded macOS .app.tar.gz, .sig, .dmg, Windows .msi, .exe, Linux .deb, .AppImage, .AppImage.sig>
 
 # ...then overwrite app-latest's assets with the same build + latest.json
 # (hand-author latest.json: version, notes, pub_date, per-platform url+signature).
+# Linux must use the AppImage itself and the matching v2 .AppImage.sig:
+# "linux-x86_64": { "url": ".../<file>.AppImage", "signature": "<.AppImage.sig contents>" }
 gh release upload app-latest --repo fujibee/agmsg --clobber \
-  <same artifacts> latest.json
+  <same artifacts, including the Linux .deb, .AppImage, and .AppImage.sig> latest.json
 ```
 Once artifacts are up, update the Homebrew cask (`fujibee/homebrew-agmsg`):
 ```sh
@@ -148,6 +164,15 @@ scripts/release/update-cask.sh X.Y.Z   # finds the .dmg on the release,
 Run it only after the release assets are uploaded — the cask's `url` must
 resolve as soon as the tap commit lands.
 
+## Known limitations
+
+- X11 was tested. Wayland and HiDPI were not tested.
+- Printable-character typeahead is not implemented in the custom select controls;
+  use the arrow keys, Home/End, or the option list instead.
+- If terminal output has no colour, check the shell that launched agmsg for
+  `NO_COLOR`. Remove that variable when colour is wanted; the app respects the
+  user's `NO_COLOR` setting and does not override it.
+
 ## Known gaps
 
 - Windows Trusted Signing is wired into CI but unverified end to end — its

app/scripts/bundle-core.sh

@@ -9,8 +9,11 @@
 # what ships is fixed and auditable via git history. Bump AGMSG_CORE_REF by
 # hand to pick up newer agmsg-core fixes.
 #
-# Called from three places that must stay in sync: app-release.yml's macOS
-# and Windows jobs, and build-notarize.sh for local builds.
+# Called from every build path that must bundle the pinned core:
+#   - .github/workflows/app-release.yml: build-macos, build-windows, build-linux
+#   - .github/workflows/tests.yml: app-check, app-check-linux, app-test-windows
+#   - app/scripts/build-notarize.sh: local macOS notarized builds
+# Keep this list exhaustive when adding another build or test path.
 set -euo pipefail
 
 APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

app/scripts/fixtures/minisign-appimage/foreign.pub

@@ -0,0 +1,2 @@
+untrusted comment: minisign public key D709B5D1C5173148
+RWRIMRfF0bUJ11vl/TRtk8Pdf5bi2AsyZ2wX4qx/gbVBE3Wx6yE3MsPP

app/scripts/fixtures/minisign-appimage/invalid-base64.AppImage.sig

@@ -0,0 +1 @@
+not a Tauri signature

app/scripts/fixtures/minisign-appimage/trusted.pub

@@ -0,0 +1,2 @@
+untrusted comment: minisign public key E7620F1842B4E81F
+RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3