Skip to content

Latest commit

 

History

History
325 lines (259 loc) · 34 KB

BACKEND-RUNTIME.md

File metadata and controls

325 lines (259 loc) · 34 KB

Backend runtimes and releases

Omarchy plugin-owned backend

Omarchy's Plugin Marketplace owns the checkout and its UI. Omamail keeps exactly one executable at ${XDG_DATA_HOME:-~/.local/share}/omamail/bin/omamail. Keeping the mutable runtime outside the recursively watched plugin tree prevents an installation or CLI operation from reloading the interface. The root backend-version file requires an exact version, independent of PATH and system packages. Service starts one persistent omamail serve process over stdin/stdout and checks its exact binary version, protocol and API revision before dispatching migrated calls. The plugin-local backend-api.json describes its required API; it is not fetched from main or from a latest-release endpoint.

On a missing or mismatched runtime, the UI explains what is needed. Installation is explicit; simply loading the plugin never starts a download. From the plugin directory, scripts/install-backend.sh requests the same installation and python3 scripts/backend-runtime.py status reports local state without network access. Linux x86_64 and aarch64 are supported. Installation downloads only from the pinned release in huacnlee/omamail, verifies SHA256SUMS and the strict archive layout, checks the candidate executable's version and atomically replaces the old executable. A failed installation preserves the working runtime. Checksums protect integrity, not against a compromised publisher.

python3 scripts/backend-runtime.py enable-cli explicitly creates ~/.local/bin/omamail as a symlink to that same private executable; it refuses an unrelated file or link. An owned link into a previous Omamail plugin checkout's runtime is repointed without modifying that watched directory. Nothing edits PATH. Run disable-cli before removing the plugin, since Omarchy has no verified uninstall hook for that external link. scripts/uninstall-backend.sh removes the runtime only. Neither operation deletes accounts, drafts, caches or keyring entries. Marketplace checkouts contain no symlinks; the optional CLI link is outside the checkout.

For development, ./dev backend builds the binary and ./dev run builds then prints environment and launch instructions. It does not open or restart the shell. OMAMAIL_BIN is an explicit development path; the installer must never replace that file. Environment changes in your terminal do not change an already running shell: follow the printed instructions to make the override available when the shell constructs the plugin, restarting the shell with that environment when needed. This is not a second Quickshell application. Rust mail migration remains incomplete; see BACKEND.md.

Forcing a clean reconnect

The running omamail serve process holds its Secret Service session, its account hosts and their sign-in state for the life of the Quickshell process that started it — a credential store that was locked at startup, an API a Cloud project only just enabled, or an OAuth grant that changed underneath it are not re-checked on their own. omarchy plugin disable omamail followed by omarchy plugin enable omamail reloads the plugin's QML context and opens a fresh backend connection without restarting the shell itself, which is enough to pick up a state change made outside the plugin's own knowledge. This is the fastest way to confirm whether a failure is a stale connection or a real one: if disable/enable clears it, it was the former.

Standalone bundled backend

The standalone Qt host under app/ uses the same ui/ composition and Rust business modules through small Quickshell compatibility adapters. A production archive places one exact-version omamail backend beside omamail-app, together with the QML, manifest, Qt libraries, and platform plugin. Production resource lookup accepts that bundled backend only; it does not search PATH, resolve latest, or use OMAMAIL_BIN. The environment override and source-resource lookup are enabled only when OMAMAIL_DEVELOPMENT_RESOURCES=1, which is what make app-run sets for a checkout build.

The host starts one persistent bundled omamail serve process and performs the protocol, version, and API handshake before mail or calendar calls. Normal shutdown asks the service to quit, drains bounded output, and then terminates the process tree on deadline. omamail-app --check-resources verifies the packaged entry points, platform plugin, manifest version, backend architecture, and backend version without opening the UI. omamail-app --smoke-test READY_FILE additionally starts the bundled backend, completes the handshake, requests shutdown, and writes readiness metadata only after a clean exit.

Standalone credentials use the native store through typed backend RPC: Keychain on macOS, Secret Service on Linux, and Credential Manager on Windows. Account metadata, cache, state, runtime endpoints, and downloads use the platform directories selected by src/platform/dirs.rs; private files and outbox IPC are protected by the platform implementations under src/platform/. The host never places a secret in its process arguments. The standalone capability object disables AI, the tray, and operating-system mailto: registration while retaining native notifications.

For source development, make app-build builds the backend with --no-default-features --features standalone and then builds the Qt host. make app-run performs that build and launches the host from source resources. These targets require Rust, CMake 3.21 or newer, and Qt 6.5 or newer; the Linux host also needs Qt DBus.

Stable API and old plugins

backend-version belongs to the installed plugin revision. A plugin that has not been updated continues using that exact private binary, even after main and newer plugins move on. Neither the app nor Install CLI selects a global or latest backend. Install CLI only links to the plugin's own executable. Old release tags, binaries, checksums and API contract assets must remain available and immutable: an old plugin must also be able to reinstall its pinned version years later. This preserves the plugin/backend pairing; it cannot guarantee that external mail providers will never change their services.

There are three independent versions: the plugin manifest version, the exact backend binary release in backend-version, and the integer API revision in backend-api.json. JSON-RPC framing has its own protocolVersion. Internal Rust fixes or optimizations can merge without changing the binary pin or API revision; users receive those fixes when a later backend release is explicitly pinned. QML presentation changes can likewise reuse the existing backend.

The contract records the public method inventory and representative request/response fixtures. Changes to methods, accepted parameters, returned fields, errors or their meaning require contract review, updated fixtures and a higher API revision. system.info.apiVersion states the API revision. The initial published binary 0.9.0 predates this field; only that exact version is recognized as legacy API 1. Missing revision information from any other version is refused.

Native AI conversations (API 6)

Settings → AI follows the Omarchy system default or selects Claude, Codex or OpenCode V2, with an optional model override. agent.providerStatus resolves the supported provider without starting an agent or creating a job. An unsupported default leaves the AI action visible but disabled; Settings explains the supported choices. Availability checks require API 6 and are repeated while following the system default. Explicit choices bypass the system-default lookup. CLI installation and authentication are still checked when a request starts. Standalone Linux/macOS builds default to OpenCode; Windows does not advertise AI.

Until the published pin advances from API 5, the plugin retains its existing Claude chat with System default and no model override. The old backend checks Omarchy's default when a job starts; it cannot preflight availability. Reader and composer requests, plain-text insertion and follow-ups remain available. Legacy follow-ups use their original context snapshot; start a new chat to include draft edits. Agent/model selection, current-context updates, proposal cards and paged history remain gated on API 6. The release workflow publishes the new backend before advancing the exact pin.

make test-agent-published PUBLISHED_BACKEND=/path/to/verified/omamail exercises that API-5 user flow with production Service/App/AgentRunner components and the actual published binary: reader/composer entry, four jobs, two continuations and insertion. Only the Claude CLI and mail-context loading are synthetic; it asserts no send occurs. Use a checksum-verified download matching backend-version, not a source build.

Each conversation retains one native provider session, serializes follow-ups and leaves compaction to that provider. Durable jobs retain per-turn public transcripts and proposal records; API-6 history pages and a rebuildable head index keep polling bounded. Interrupted turns preserve their session and mail context when safe to continue; crashed or unconfirmed workers require a fresh chat. Agent/model changes start new chats, preserve unsent input and retain prior chats as read-only history.

The isolated provider launch preserves model/authentication configuration while excluding unrelated tools, plugins and hooks. The only mail-writing tool records a content-only draft proposal: account, recipients, threading and attachment ownership come from app-owned snapshots. Applying or sending a proposal requires a human action and uses the normal composer/outbox path. Delivery labels follow outbox receipts; the standard send toast provides Undo. Codex advertises the proposal namespace directly even for code-mode-only models, without general tool discovery.

Proposal cards show their saved From, To and optional Cc, Bcc and Reply-To. If routing in the corresponding open composer changes, direct card sending is disabled and rechecked at dispatch. Use this version applies subject/body without replacing the edited recipients; the normal composer Send then reviews and sends the current routing.

API 7 sender name for IMAP and Outlook

An IMAP or Outlook account entry may carry a top-level senderName. mail.send uses it, trimmed, as the display name of the mailbox's own address in the From header; aliases keep their own names. An empty or missing value sends the bare address, as before. Starting at API 7 the UI offers the name as "Your name" in Settings → Mailboxes and on the IMAP and Outlook setup pages, and the composer names the From address with it. On an older backend the fields are hidden and the composer leaves the stored value unused, so composer and agent sends both carry the bare address rather than disagreeing.

API 6 account-wide IMAP search

IMAP and Outlook text searches, and IMAP address searches, resolve to search:<criteria>. IMAP All mail resolves to search:ALL; folder queries remain folder-scoped. The IMAP UI keeps Archive on API 5 and exposes All mail starting at API 6.

imap.list and imap.listContinue return an empty page plus an opaque work continuation until the scan and page assembly have finished. Continue with the same account, query, request token and original pageToken, including when a later page needs a new scan. Partial scans are not a globally newest-first page. Expired or mismatched work continuations return imap_search_expired; refresh starts a new search.

A completed page's opaque nextPageToken is a self-contained cursor bound to the account's IMAP endpoint, username, query and versioned scope/ordering semantics. It records the last result's INTERNALDATE, folder, UID and UIDVALIDITY, plus an optional-cache reference. Results sort by INTERNALDATE descending, folder name ascending and UID descending; the next page starts strictly after that position without looking up the previous message. The cursor contains no credentials or credential hashes, and token refresh does not invalidate its binding. Invalid cursor encodings/versions return invalid_params; account/query mismatches and detected UIDVALIDITY changes return imap_search_expired.

Completed results are cached for five minutes after scan completion, subject to eviction. Available cached results avoid another inventory/search/metadata scan; an absent cache transparently triggers a new scan and applies the same cursor boundary. The CLI and UI use the same path, including across independent CLI invocations and backend restarts. Cached pages verify candidate UIDs and their folders' UIDVALIDITY before returning IDs, skipping expunged candidates and filling from subsequent results. This is live-result pagination with short-lived cache reuse, not a frozen historical snapshot: new messages before the boundary appear on refresh, and moves between physical folders may reappear under a new identity. A message can still disappear after IDs are returned and before a separate message read.

Each call advances at most four scan or page-verification folders, with at most four concurrent workers per account and a 12-second worker deadline inside the existing 22-second request deadline. The scanner captures UIDNEXT, streams a compact UID inventory through individually framed FETCH responses, and issues SEARCH and metadata FETCH operations in windows of at most 4096 existing UIDs. This bounds SEARCH response lines below the 64 KiB transport limit even for ten-digit UIDs, without walking empty numeric UID gaps. Scans are limited to 2048 folders, one million inventoried UIDs and 250,000 matching folder/UID identities; the existing 32 MiB per-command response ceiling also applies. Oversized responses fail explicitly instead of presenting incomplete results as complete. Inventory storage is released after scanning; at most 16 snapshots with a combined budget of two million inventory/result entries are retained. In-progress scans expire after five idle minutes; completed-cache reads do not extend their lifetime. No search state is written to disk.

Search includes aggregate All Mail destinations and excludes Trash/Junk membership from aggregate results. Cross-folder copies are collapsed using server-provided EMAILID/X-GM-MSGID. A generic server that advertises \All but no server identity is searched through its \All mailbox alone, because RFC 6154 defines it as every message in the store; scanning physical folders as well would only add copies that cannot be matched without reading them. Its Message-ID header and RFC822.SIZE nominate possible overlaps between All and Trash/Junk, then SHA-256 of complete message bytes verifies those candidates before excluding any aggregate result. Verification reads at most 64 candidates and 8 MiB per folder step with BODY.PEEK[] and retains only digests; a candidate larger than 8 MiB is not read and stays in the results. A server with neither \All nor a server identity preserves folder/UID copies, so overlapping folders may produce duplicate rows. A sender-written Message-ID, headers or size alone never suppress a result. Copies within one physical folder remain distinct. mail.list follows search continuations for at most 120 seconds; other IMAP listings still accept one continuation.

Released and unreleased: one step ahead of the pin

Backends ship in batches, not per merge, so main may implement an API the pinned binary does not have yet. The contract names that difference and nothing more:

  • releasedApiVersion is the API the pinned, published binary speaks; the runtime handshake accepts exactly that. apiVersion is what this checkout's Rust implements, equal to it or one step ahead — a second step is refused by check-api until the first is released, which is what makes releases batches.
  • unreleased.methods and unreleased.cases name what the step adds: methods only the step has, and contract cases only a binary from this checkout passes. A case on an unreleased method is itself unreleased. With apiVersion equal to releasedApiVersion both lists are empty.
  • CI runs two gates on every revision, and the required check needs both. The Released backend gate downloads the pinned release and checks that its contract equals the checkout's released view (check-api --published), then runs the released view of the fixtures against that binary (test_backend_api.py --released). The Unreleased API gate builds the backend from the revision and runs the whole contract and the native agent bridge against it. A merge into main can therefore carry an unreleased step and still leave every fresh install working. A failed gate leaves a note, and ci-report.yml — run after CI, with the one write permission the CI run of a fork cannot have — posts it on the PR as a comment saying which gate failed and what to do, updating the same comment on every push.
  • The plugin's runtime status reports latestApiVersion and unreleasedMethods beside the required revision. Backend exposes needsUpdate when the connected binary lacks the step, and refuses a call to an unreleased method on it with backend_needs_update (code -32012) — so a feature that forgot to look before asking fails the way it already handles, never as a request the old binary would misread. Service.backendNeedsUpdate is an overall update indicator, not a per-feature gate. A feature checks the connected backend against the fixed API revision that introduced it: event suggestions use Service.backendCanSuggestEvents, true only for a ready backend with API 2 or newer. That requirement remains correct before release, after the pin advances, and when a later unrelated API is introduced.
  • tests/test_source.sh permits calls only to declared backend methods. QML regression tests exercise fixed feature requirements across connected API versions and changing release metadata; a release must not require deleting compatibility checks from QML.
  • The pin commit made by a release folds the step: releasedApiVersion becomes apiVersion, both unreleased lists empty. Published contracts from before the split are read as all released.

Release before pin

Run make publish VERSION=MAJOR.MINOR.PATCH on a clean main synchronized with origin. Without VERSION, it prepares the next patch version. The command creates release/X.Y.Z, prepares Cargo.toml, the omamail Cargo.lock record and manifest.json, and opens one PR targeting main. It pushes only that release branch, then follows its exact Release run. It never pushes main or a tag. backend-version and the released API contract stay unchanged during preparation.

A push to release/** starts the authoritative Release workflow. Only the exact release/X.Y.Z branch matching Cargo's version is accepted; dispatching on main, a feature branch or a tag is refused. The workflow builds both plugin backends and all three standalone archives, creates vX.Y.Z, publishes the complete asset set and installers, verifies the public downloads, then commits backend-version and the folded API contract on the same release branch. The pin commit changes only those two files, both excluded from the publication push trigger, so it starts PR checks without another publication.

The required Published backend merge gate refuses a release PR until its pin equals the prepared version, then verifies the actual released binaries and contract as usual. Once the pin commit and required checks pass, review and merge that PR once: main receives the version metadata and working backend dependency together. The command does not merge automatically. Features wait until the connected backend meets their fixed minimum API revision, independently of whether that revision is currently labelled released or unreleased.

The repository's active main ruleset requires a PR and the Published backend merge gate and prohibits deletion and force pushes. Administrators currently have a pull-request-only bypass: direct pushes remain blocked, but an administrator can explicitly bypass checks when merging a PR. Never enable an always-on bypass or use the PR bypass for routine releases; neither a local push nor CI should advance main directly.

The workflow tests and builds locked native musl binaries on Linux x86_64 and aarch64, executes each version probe, rejects dynamic ELF dependencies, and packages omamail-linux-x86_64.tar.gz and omamail-linux-aarch64.tar.gz. Each contains exactly one regular executable named omamail. A combined SHA256SUMS and backend-build.json plus backend-api.json are published with both assets only after both build jobs pass. The release checks the new contract against the pinned release: a changed contract requires a higher API revision. Each native binary must also pass the contract runner before packaging. Both native build jobs produce identical source fingerprints before publication. The new draft release is completed, made public, downloaded again and verified before a follow-up commit updates backend-version and folds backend-api.json on the release branch.

The same workflow builds omamail-app-macos-aarch64.tar.gz on macOS 15, omamail-app-linux-x86_64.tar.gz on Ubuntu 22.04 (the glibc 2.35 floor), and omamail-app-windows-x86_64.zip on Windows Server 2022. Each native job runs the standalone Rust suite, its platform credential contract, the Qt C++ tests, the standalone QML suite, the backend API contract, package validation, installer rollback tests, resource checks, and a live bundled-backend smoke test before uploading its archive. publish-and-pin depends on all five build jobs, creates one combined SHA256SUMS, publishes install.sh and install.ps1 with the archives, downloads every public asset again, and only then advances the plugin backend pin.

The Linux standalone release is tar.gz only; no AppImage is built or published. Standalone archives are currently unsigned. The macOS app is not notarized, so install.sh clears com.apple.quarantine recursively from the exact verified staging bundle before the transactional replacement; an xattr failure aborts without replacing an existing install. The Windows binaries are not code signed, so its platform publisher warning remains a release limitation rather than a property the validation jobs can clear.

Publication is serialized. Existing releases and tags are never overwritten; remote lookup errors fail closed. The branch must still equal the dispatch revision before publication and before the pin commit. A normal fast-forward push rejects concurrent movement; there is no force push or branch-protection bypass. If publication succeeds but the branch moves or rejects the pin push, the release remains published and the pin stays unchanged. Inspect that failure and verify the already-published assets before preparing a reviewed pin-only change on the same release PR; rerunning publication refuses the existing version. If the branch push succeeded but PR creation failed, open the PR for that existing branch instead of invoking publish again. If tag creation succeeded but publication failed, inspect the retained tag and any draft; never delete or reuse a published version. Prepare a new release version when the existing attempt cannot be safely completed.

Repository setup must provide RELEASE_TOKEN, an appropriately scoped GitHub App token or fine-grained token with contents write permission for this repo, permitted to push release branches and create tags and releases. Local gh needs permission to push the branch and open its PR. The default GITHUB_TOKEN cannot be used for the pin push because it suppresses subsequent workflow triggers. See GitHub's workflow triggering rules. Release runs only on versioned release branches, by push or explicit dispatch; restrict who can push these trusted branches and tags. PR CI has read-only permissions and never receives that secret. Require Published backend merge gate in branch protection. That check reads the plugin's exact pin independently of Cargo's current development version, verifies both published native archives, compares the published API contract with the PR's contract, and runs tests/test_backend_api.py against each actual published binary using the PR's production QML Wire/Chunks codecs. It also checks that Rust's public method inventory matches the contract. A PR cannot satisfy this check merely by building a newer local executable.

Source fingerprints in backend-build.json remain release provenance. They bind both release builds to the same Rust sources, resources and build inputs; they do not require future PRs to contain identical Rust source. Cargo and Cargo.lock must still agree for builds, but their development version need not equal the pinned published binary.

For a combined QML/Rust PR requiring an API change: raise apiVersion one step past releasedApiVersion, name the new methods and cases under unreleased, and let the feature wait until the connected backend reaches that feature's fixed minimum API revision. Both gates run on the PR and it merges into main without a release; the next release from main publishes the binary and its pin commit folds the step. Runtime handshake still requires the exact plugin-local binary pin, even when a newer release reports the same API; at that version it accepts the released API or the one unreleased step, so a local build of the checkout (make install) runs the step in the desktop while the published binary of the same version keeps working without it.

The contract runner exercises the contract's cases and checks the advertised inventory — the released view against the pinned binary, everything against a binary built from the checkout. It covers representative mail processing and cached reader behavior, not every provider operation or every possible QML argument. API reviewers must extend fixtures for newly used behavior; passing these tests is not a proof of complete semantic compatibility. Contract fixtures, API revisions, workflows and repository policy changes require trusted review. These scripts do not change repository settings.

Bootstrap status: v0.9.0 contains the optimized x86_64 and aarch64 static backends. The published packages were checked against the successful native CI artifacts from f38c2ac; its source fingerprint was added and downloaded again before advancing the pin. v0.8.2 remains unchanged. The first CI publication attempt failed because RELEASE_TOKEN lacked permission to create a release; the release was completed separately. Future automated publication still requires a contents-write token as described above.

Standalone security gates

A standalone release needs a separate security verdict for macOS arm64, Linux x86_64, and Windows x64. The verdict is PASS only when the release commit has completed its native job and every boundary below was exercised on that runtime. A shared test on another operating system, successful compilation, or source inspection alone leaves that platform NOT VERIFIED. A failing boundary is BLOCK and prevents publication.

Boundary Evidence required on each native runtime
Credentials Native Keychain, Secret Service, or Credential Manager success, missing-item, denial, validation, and bounded-prompt cases; secrets absent from argv, settings, and diagnostics.
Untrusted mail and URLs Plain-text metadata, HTML/resource sanitization, public-address DNS pinning, HTTPS/TLS, redirect, proxy, deadline, and response-size cases using controlled targets.
Process argv and stdin Hostile arguments preserved as one argument, exact stdin bytes including NUL, bounded stdout/stderr, timeout, cancellation, and descendant termination.
Private files and outbox IPC Platform directory resolution, unsafe ancestor/link/reparse refusal, ownership and ACL checks, atomic replacement/rollback, locks, peer identity, and oversized IPC frames.
Archive installation SHA-256 verification before extraction, strict single-root layout and architecture/version checks, traversal/link/special-file and size refusal, transactional upgrade rollback, and uninstall preserving user data.
Notifications Plain-text or escaped markup handling, NUL refusal, bounded private activation routes, stale/forged route refusal, cold and warm activation, and no secret or route token in process arguments.
Network requests Every mail/calendar request keeps credentials on the configured origin or validated public target, validates bytes before process start, applies TLS/protocol/redirect/proxy policy, and has a deadline and response bound.

The native standalone job runs this platform gate before its archive can become an artifact. It must run cargo test --locked --no-default-features --features standalone, the ignored native credential contract, CTest, the standalone QML tests, package and installer tests, --check-resources, --smoke-test, and the packaged backend API contract. The release's publish-and-pin job depends on all three platform jobs; missing or failed native evidence cannot be replaced by manually uploading an archive.

Current integrated-checkout audit on 2026-09-14: macOS arm64, Linux x86_64, and Windows x64 are NOT VERIFIED until the corresponding release/** native jobs complete for this exact commit. Local macOS results may establish part of the boundary evidence, but they do not exercise Linux Secret Service/DBus, Windows Credential Manager/named pipes/ACLs, or clean hosted-runner install and notification activation on those systems. Do not treat this documentation commit or the presence of workflow definitions as a hosted-runner result.

Local verification

For the standalone host, run make app-build to build and make app-run to launch from source resources. Linux and macOS builds include the native AI feature; Windows continues to omit its runtime capability. make test-app-qml builds the host and runs its composition test. A fuller local native check is:

cargo test --locked --no-default-features --features standalone
cmake -S app -B build/app -DOMAMAIL_BACKEND="$PWD/target/debug/omamail"
cmake --build build/app --parallel
ctest --test-dir build/app --output-on-failure
QT_QPA_PLATFORM=offscreen qmltestrunner -input app/tests/qml/tst_host_contract.qml -import app/qml/imports -import ui

These commands establish evidence only for the operating system that ran them. Package and installer acceptance must use the archive produced on its native release runner; macOS and Linux use app/scripts/package-release.sh, while Windows uses app/scripts/package-release.ps1.

make install-plugin removes the old private backend and its local-build marker, then links and reloads only the plugin. It does not compile or download a backend. Accounts, drafts and caches are preserved. Use it to test a fresh backend setup:

make install-plugin

Then open Omamail and choose Install backend. Any optional CLI symlink still points to the same private binary location and works again after installation. Ensure the shell has no OMAMAIL_BIN development override, which would otherwise select that binary instead of testing the missing-runtime screen.

To try the latest checkout in the desktop, run make install. It first builds with cargo build --locked --release into this checkout's target/ directory, regardless of CARGO_TARGET_DIR, then stages and verifies that binary before atomically replacing ${XDG_DATA_HOME:-~/.local/share}/omamail/bin/omamail. When its version is ahead of the release pin, it must match the Git checkout's Cargo package version. The explicit local installation records a private ${XDG_DATA_HOME:-~/.local/share}/omamail/local-build.json marker binding that version, the current release pin and the installed binary's SHA-256. Status and CLI activation accept this local version only while the checkout, Cargo version, pin and binary bytes still match. No tracked pin is changed. Only after that succeeds does it link the plugin and restart the shell. It does not need published backend assets. Failed builds or version checks preserve the old runtime.

make install-backend-local performs only the build and local runtime replacement. Restart the shell afterwards to replace an already running backend process. Unset OMAMAIL_BIN in the shell's startup environment to use the private runtime. The separate scripts/install-backend.sh command remains the release downloader: it always uses backend-version, ignores the local override when selecting a release, and clears the marker after verification as part of installation. Uninstall also removes the marker. Local version overrides require Python 3.11 or newer for Cargo TOML parsing; normal pinned installations do not.

Run make test-local on a machine with Rust, Qt 6 test tooling and Quickshell. It runs the existing Rust, JavaScript, transport/security and offscreen QML suites, then make test-backend-process builds the development executable and tests the production QML bridge against it using real Quickshell pipes. The integration test uses temporary HOME/XDG directories and synthetic account settings. It checks version/protocol handshake, concurrent request correlation, error responses, credential-free account summaries, a binary message larger than 1 MiB through upload and response chunks, and confirmed process shutdown. It does not open the desktop plugin or contact mail providers.

make test-backend-process can also be run on its own. These local checks do not verify live mailbox compatibility, graphical plugin installation, or release availability. make qml-check additionally needs the installed Omarchy shell's QML imports; inspect its diagnostics even when qmllint returns success.

Local synthetic tests cover archive shape, checksum corruption, version drift, preparation without pin advancement, pin-only commits and moved-branch refusal. Historical pre-release checks: a native aarch64 Debian Bookworm container with Rust 1.100.0-nightly (2026-09-03) passed locked musl tests and a release build; its version probe returned 0.8.2 and ELF inspection found no interpreter or dynamic section. The local x86_64 musl test process crashed under Docker emulation. Subsequent v0.9.0 native Actions builds and published-asset verification supersede that architecture gap, as recorded above. Future releases still require their own hosted checks; passing local tests alone is not release availability.