Merge pull request #427 from Codename-11/dev

chore(release): Android 1.13.0, Plugin 1.10.0, and CLI beta.5

.github/workflows/release-cli.yml

@@ -117,6 +117,9 @@ jobs:
       - name: Build Linux x64
         run: npm run build:bin:linux
 
+      - name: Build Linux arm64
+        run: npm run build:bin:linux-arm
+
       - name: Build macOS x64
         run: npm run build:bin:mac-x64
 
@@ -138,19 +141,27 @@ jobs:
 
       - name: Smoke-test Linux binary
         run: |
-          set -e
+          set -euo pipefail
           chmod +x dist/bin/hermes-relay-linux-x64
           for cmd in --version --help doctor; do
-            out=$(./dist/bin/hermes-relay-linux-x64 "$cmd" 2>&1 || true)
+            set +e
+            out=$(./dist/bin/hermes-relay-linux-x64 "$cmd" 2>&1)
             exit_code=$?
-            if [ -z "$out" ] || [ ${#out} -lt 10 ]; then
-              echo "SMOKE FAIL: './hermes-relay-linux-x64 $cmd' produced no output (exit=$exit_code)"
+            set -e
+            if [ "$exit_code" -ne 0 ] || [ -z "$out" ] || [ ${#out} -lt 10 ]; then
+              echo "SMOKE FAIL: './hermes-relay-linux-x64 $cmd' failed or produced no output (exit=$exit_code)"
               echo "Raw output was: [$out]"
               exit 1
             fi
             echo "  smoke OK: $cmd -> $(echo "$out" | head -1)"
           done
 
+      - name: Verify Linux arm64 artifact architecture
+        run: |
+          set -euo pipefail
+          file dist/bin/hermes-relay-linux-arm64 | tee /tmp/hermes-relay-linux-arm64.file
+          grep -Eq 'ELF 64-bit.*(ARM aarch64|ARM64)' /tmp/hermes-relay-linux-arm64.file
+
       - name: Upload CLI release assets
         uses: actions/upload-artifact@v4
         with:
@@ -158,6 +169,7 @@ jobs:
           path: |
             desktop/dist/bin/hermes-relay-win-x64.exe
             desktop/dist/bin/hermes-relay-linux-x64
+            desktop/dist/bin/hermes-relay-linux-arm64
             desktop/dist/bin/hermes-relay-darwin-x64
             desktop/dist/bin/hermes-relay-darwin-arm64
           retention-days: 7
@@ -196,6 +208,60 @@ jobs:
             throw "Windows CLI smoke left $(@($leftovers).Count) process(es) behind"
           }
 
+  smoke-macos-cli-release-asset:
+    name: Smoke exact macOS CLI release asset
+    runs-on: macos-latest
+    needs:
+      - validate-release
+      - build-cli-binaries
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: cli-binaries
+          path: release-assets
+
+      - name: Launch native release asset and inspect both architectures
+        env:
+          EXPECTED_DESKTOP_VERSION: ${{ needs.validate-release.outputs.version }}
+        run: |
+          set -euo pipefail
+          case "$(uname -m)" in
+            x86_64) native_asset=hermes-relay-darwin-x64 ;;
+            arm64) native_asset=hermes-relay-darwin-arm64 ;;
+            *) echo "Unsupported macOS runner architecture: $(uname -m)" >&2; exit 1 ;;
+          esac
+          chmod +x "release-assets/$native_asset"
+          version_output=$("release-assets/$native_asset" --version)
+          test "$version_output" = "hermes-relay $EXPECTED_DESKTOP_VERSION"
+          "release-assets/$native_asset" --help | grep -Fq 'Usage:'
+          file release-assets/hermes-relay-darwin-x64 | grep -Fq 'x86_64'
+          file release-assets/hermes-relay-darwin-arm64 | grep -Eq '(arm64|arm64e)'
+
+  smoke-linux-arm64-cli-release-asset:
+    name: Smoke exact Linux arm64 CLI release asset
+    runs-on: ubuntu-24.04-arm
+    needs:
+      - validate-release
+      - build-cli-binaries
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: cli-binaries
+          path: release-assets
+
+      - name: Launch native arm64 release asset
+        env:
+          EXPECTED_DESKTOP_VERSION: ${{ needs.validate-release.outputs.version }}
+        run: |
+          set -euo pipefail
+          asset=release-assets/hermes-relay-linux-arm64
+          test "$(uname -m)" = "aarch64"
+          chmod +x "$asset"
+          version_output=$("$asset" --version)
+          test "$version_output" = "hermes-relay $EXPECTED_DESKTOP_VERSION"
+          "$asset" --help | grep -Fq 'Usage:'
+          file "$asset" | grep -Eq 'ELF 64-bit.*(ARM aarch64|ARM64)'
+
   build-windows-tray-installer:
     name: Build Windows tray installer
     runs-on: windows-latest
@@ -419,6 +485,8 @@ jobs:
     needs:
       - build-cli-binaries
       - smoke-windows-cli-release-asset
+      - smoke-macos-cli-release-asset
+      - smoke-linux-arm64-cli-release-asset
       - build-windows-tray-installer
     steps:
       # Needed so CLI_RELEASE_NOTES.md is available to render into the release body
@@ -466,6 +534,7 @@ jobs:
           files: |
             release-assets/cli-binaries/hermes-relay-win-x64.exe
             release-assets/cli-binaries/hermes-relay-linux-x64
+            release-assets/cli-binaries/hermes-relay-linux-arm64
             release-assets/cli-binaries/hermes-relay-darwin-x64
             release-assets/cli-binaries/hermes-relay-darwin-arm64
             release-assets/cli-windows-installer/hermes-relay-windows-x64-setup.exe

.gitignore

@@ -95,3 +95,4 @@ keystore.properties
 desktop/tray/ui/vendor/
 # Generated from assets/screenshots/02_chat.png before docs dev/build.
 /user-docs/public/chat-demo.png
+/user-docs/public/product/desktop-ui/

CHANGELOG.md

@@ -6,19 +6,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [Android 1.13.0] - 2026-08-25
+
 ### Added
 
+- **Provider usage and limits are available from top-level Settings.** Codex credential pools, Nous balances, and OpenCode Go account windows share one provider-neutral screen with Summary, Expanded, and Hidden presentation modes. Provider credentials remain on the Hermes host.
 - **Android Bot Mode provides one messenger-style workspace across saved Hermes gateways.** Bots and read-only group rooms aggregate without changing the foreground connection, Bot Chats retain exact gateway/profile ownership, and unavailable gateways keep clearly marked last-known roster entries.
 - **Android Assistant screen context.** Compatible unlocked assistant-button invocations can open Hermes, begin listening, and include bounded visible text plus an available screenshot in the first Standard voice turn. Ordinary wake and keyguard invocations remain screen-context free.
 
 ### Changed
 
-- **Release and candidate names use one public product hierarchy.** Future releases use `Hermes-Relay Android`, `Hermes-Relay Plugin`, or `Hermes-Relay CLI+UI` display names, while isolated Android review and release-candidate installs use `HR Candidate`, without changing immutable tags, package identities, updater contracts, or artifact filenames.
-- **Review candidates are an explicit PR opt-in with one trusted handoff comment.** Maintainers can apply `review-candidate` for exact-head Android and Relay bundles; a separate reporter updates the PR with the artifact, expiry, source SHA, and bounded review instructions without executing fork code with write permission.
-- **Unlabeled PR updates no longer receive false candidate-failure comments.** The trusted reporter ignores skipped review-bundle workflow shells before reading artifacts or writing to a PR.
+- **Android releases and review candidates use clear public product names.** Stable builds use `Hermes-Relay Android`, while isolated review installs use `HR Candidate` without changing package identities or update contracts.
+- **Review candidates are explicit and source-pinned.** Maintainers can opt a PR into a matched Android and Relay bundle with checksums, expiry, source SHA, and bounded review instructions.
 
 ### Fixed
 
+- **Unlabeled PR updates no longer receive false candidate-failure comments.** The trusted reporter ignores skipped review-bundle workflow shells before reading artifacts or writing to a PR.
+- **Android chats no longer retain a stale busy composer.** A completed Gateway bubble settles automatically when its exact session has no live or detached turn, new-chat navigation clears stale visible ownership, and Stop remains an immediate escape hatch. (#416, #418)
+- **README and Google Play onboarding now match the Dashboard-first product path.** Public setup copy names the two separate Dashboard QR actions, treats the API server as an advanced fallback, explains the encouraged Hermes-Relay extension without implying Play includes Device Control, and ships one current deterministic Android screenshot set.
+- **The Android Sphere remains gently animated while visibly idle.** New chats and the ambient Sphere behind messages now use a low-cost layer breath, while hidden/backgrounded and motion-disabled surfaces stay still and active agent/voice states retain their full procedural animation.
+- **Android retries Windows-hosted `MEDIA:` attachments through Relay's by-path route.** A document deferred on cellular no longer treats `C:\...` as an opaque media token and reports it as expired.
+
+## [Plugin 1.10.0] - 2026-08-25
+
+### Added
+
+- **Relay provides normalized provider usage without exposing credentials.** The authenticated Dashboard route resolves the active Codex pool entry, structured Nous balances, and OpenCode Go windows on the Hermes host; explicitly enabled paired clients receive the same provider-neutral schema.
+
+### Changed
+
+- **Plugin releases use the `Hermes-Relay Plugin` public name.** The display name is aligned with Android and CLI+UI while the `server-v*` compatibility tag remains unchanged.
+
+### Fixed
+
+- **Relay profile discovery follows `HERMES_HOME` by default.** Custom Hermes installations surface their real default profile and persist Relay sessions beside the active config while retaining the explicit `RELAY_HERMES_CONFIG` override.
+
+## [0.4.0-beta.5] - 2026-08-25
+
+### Added
+
+- **Desktop releases now include a Linux ARM64 CLI artifact.** The one-line installer, updater, checksums, release publication, architecture validation, and platform documentation all recognize the same `linux-arm64` binary.
+- **The public site now shows the real Windows CLI UI and guides each surface through first use.** Deterministic public-safe screenshots cover connection, host access, activity, computer control, and updates.
+
+### Changed
+
+- **Desktop releases use the `Hermes-Relay CLI+UI` public name.** The beta keeps its existing `desktop-v*` tag and updater contract.
+
+### Fixed
+
+- **Desktop install and update discovery remains reliable in a multi-surface release repository.** Every resolver paginates GitHub releases before choosing the SemVer maximum, Windows cooperative updates clean their released backup, unsigned preview installers retain the normal SmartScreen warning, and release smoke tests preserve real exit codes.
 - **Desktop daemon connections recover instead of exiting after an interrupted Relay socket.** Healthy daemons retry through Relay restarts and repeated failed reconnect attempts, oversized desktop-tool results fail within a bounded response instead of closing the shared WebSocket, and terminal failures leave an accurate stopped status for the tray.
 - **Desktop computer control follows Hermes' current CUA Driver contract.** CUA Driver 0.20 and newer are accepted when their manifest, daemon/MCP arguments, required tools, and canonical path remain compatible, and Windows sessions use the manifest-declared direct standard-mode runtime instead of a potentially stale machine-wide daemon. Current 0.21 installations no longer fall back solely because of an obsolete upper version pin or daemon contract.
 
@@ -74,7 +110,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - **Android screen-on idle no longer continuously redraws the ASCII sphere.** Idle holds a stable frame while thinking, streaming, and voice states retain full-rate motion; inactive voice waveforms and closed session drawers also stop their frame loops.
 - **Android capture and audio effects release power-sensitive resources at their actual lifecycle boundaries.** Screen capture attaches its MediaProjection surface only for a requested frame, unattended Bridge wake locks release when the command finishes, and barge-in AEC/noise suppression attach to the microphone capture session instead of playback.
 - **Experimental wake-word listening reuses its PCM normalization buffer.** Continuous opt-in listening no longer allocates a new float frame for every inference call.
-
 ## [1.10.0] - 2026-08-18
 
 ### Added

CLI_RELEASE_NOTES.md

@@ -1,17 +1,33 @@
 # Hermes-Relay CLI+UI v__VERSION__
 
-**Release Date:** 2026-08-15
+**Release Date:** 2026-08-25
 
-This patch keeps the Windows management UI usable when the Relay daemon is stopped or its status cannot be read.
+This beta makes the Desktop connector resilient through Relay interruptions,
+aligns Windows computer control with current CUA Driver releases, adds a native
+Linux ARM64 build, and hardens installation and update discovery.
 
-**Beta phase.** Assets remain unsigned, so Windows SmartScreen and macOS Gatekeeper may warn on first launch. Standalone CLI binaries ship for Windows x64, Linux x64, and macOS x64/arm64; the management UI is Windows-only.
+**Beta phase.** Assets remain unsigned, so Windows SmartScreen and macOS Gatekeeper may warn on first launch. Standalone CLI binaries ship for Windows x64, Linux x64/arm64, and macOS x64/arm64; the management UI is Windows-only.
 
 ## What's changed
 
+### Added
+
+- **Linux ARM64 is a first-class release target.** The one-line installer,
+  updater, checksums, and release artifacts now cover both Linux x64 and arm64.
+- **The public site shows the real Windows CLI UI.** Deterministic screenshots
+  cover connections, host access, activity, computer control, and updates.
+
+### Changed
+
+- **Public naming is aligned.** Releases use `Hermes-Relay CLI+UI` while the
+  beta keeps its existing `desktop-v*` tag and updater contract.
+
 ### Fixed
 
-- **Stopped daemons no longer block the management UI.** Missing, stale, malformed, or temporarily unavailable daemon status falls back to an explicit stopped state while hosts, settings, activity, CLI details, diagnostics, and daemon controls continue loading normally.
-- **Starting the daemon restores live status without reopening the UI.** A valid running status continues through the same bounded, single-flight snapshot path introduced in beta.3.
+- **The daemon reconnects instead of exiting after an interrupted Relay socket.** Relay restarts and repeated transient replacement failures stay on bounded automatic backoff, and terminal failures persist an accurate stopped reason for the UI.
+- **Oversized desktop-tool output no longer closes the shared connection.** PowerShell output and every serialized desktop response stay inside the Relay WebSocket budget.
+- **Current CUA Driver releases remain compatible by contract.** Driver 0.20 and newer are accepted when their manifest and required tools match Hermes, and Windows uses the manifest-declared direct standard-mode runtime instead of a stale machine-wide daemon.
+- **Install and update discovery paginates the multi-surface release history.** Desktop releases remain discoverable after more Android and Server releases, Windows cooperative updates clean their released backup, and unsigned installers retain the normal SmartScreen warning.
 
 ## Install
 
@@ -42,6 +58,7 @@ hermes-relay --version
 hermes-relay hosts list --json
 hermes-relay daemon start
 hermes-relay daemon status --json
+hermes-relay computer-use status --json
 ```
 
 On Windows, click the Hermes-Relay CLI UI notification-area icon to open the management popup directly above it.

DEVLOG.md

@@ -62,6 +62,18 @@ automotive device verified foreground preservation, AssistStructure and screensh
 delivery, immediate listening, contextual response, and one-shot consumption;
 broader firmware certification remains tracked in `TODO.md`.
 
+## 2026-08-23 — Windows attachment retry and Hermes-home resolution
+
+Android now recognizes Windows absolute paths during manual inbound-media retry.
+Cellular-deferred `MEDIA:C:\...` documents use Relay's authenticated
+`/media/by-path` route instead of being sent to the opaque-token route and
+misreported as expired. A Robolectric/MockWebServer regression covers a spaced
+Markdown filename and asserts the exact route and decoded path query.
+
+Relay configuration now derives its default `config.yaml` and session-persistence
+paths from `HERMES_HOME` when present. `RELAY_HERMES_CONFIG` remains the explicit
+override. Focused Python tests cover both resolution paths.
+
 ## 2026-08-23 — GitHub Discussions community surface
 
 GitHub Discussions is enabled as the repository's lightweight community surface.

PLUGIN_RELEASE_NOTES.md

@@ -1,21 +1,26 @@
 # Hermes-Relay Plugin v__VERSION__
 
-**Release Date:** August 21, 2026
+**Release Date:** August 25, 2026
 
 ## Summary
 
-This release makes delayed phone delivery and active Bridge access easier to understand. Relay now identifies messages flushed after reconnect, emits one completion signal for the backlog, and reports permanent, timed, and unlimited phone capabilities through status surfaces.
+This release adds a provider-neutral account-usage surface for Android and Dashboard clients. Relay resolves Codex credential pools, structured Nous balances, and OpenCode Go windows on the Hermes host without returning provider credentials.
 
 Standard chat, session history, and Vanilla Hermes voice remain upstream-owned and do not require this plugin.
 
 ## Added
 
-- **Reconnect backlog context.** Messages flushed from the bounded offline queue carry an explicit delayed-delivery marker, followed by one ordered completion event with the delivered count.
-- **Granular phone capability status.** Relay status and `android_phone_status` report permanent, timed, and unlimited Bridge capabilities alongside existing Android permissions and safety state.
+- **Provider-neutral usage snapshots.** Authenticated Dashboard clients can resolve the exact active Codex pool entry, Nous balances, and OpenCode Go account windows through one normalized schema.
+- **Bounded paired-client fallback.** Operators may explicitly enable the Relay usage route for paired standalone clients while credentials remain host-side.
 
 ## Changed
 
-- **Phone surfacing semantics are explicit.** Default delivery persists to Threads and notifies, Inbox delivery remains silent, and Session delivery targets an available active conversation before falling back to a notification.
+- **Usage capabilities are explicit.** Responses identify Relay-enhanced credential pools, structured balances, and provider adapters instead of implying unsupported upstream data.
+- **Public product naming is aligned.** Releases use `Hermes-Relay Plugin` while retaining the `server-v*` tag and installation contract.
+
+## Fixed
+
+- **Custom Hermes homes resolve correctly.** Relay profile discovery and session persistence follow `HERMES_HOME` by default while preserving the explicit `RELAY_HERMES_CONFIG` override.
 
 ## Install / update
 

README.md

@@ -17,7 +17,7 @@
   <a href="https://developer.android.com/about/versions/oreo"><img src="https://img.shields.io/badge/Android-8.0%2B-3DDC84.svg?logo=android&logoColor=white" alt="Android 8.0+"></a>
   <a href="https://github.com/Codename-11/hermes-relay/actions/workflows/ci-android.yml"><img src="https://github.com/Codename-11/hermes-relay/actions/workflows/ci-android.yml/badge.svg" alt="Android CI"></a>
   <a href="https://github.com/Codename-11/hermes-relay/releases"><img src="https://img.shields.io/github/v/release/Codename-11/hermes-relay?filter=android-v*&label=release&color=8B5CF6" alt="Latest release"></a>
-  <a href="https://github.com/Codename-11/hermes-relay/tree/main/desktop"><img src="https://img.shields.io/badge/CLI-alpha-orange.svg" alt="CLI (alpha)"></a>
+  <a href="https://github.com/Codename-11/hermes-relay/tree/main/desktop"><img src="https://img.shields.io/badge/CLI-beta-756cff.svg" alt="CLI (beta)"></a>
 </p>
 
 <p align="center">
@@ -36,12 +36,12 @@
 Hermes-Relay puts your [Hermes agent](https://github.com/NousResearch/hermes-agent) on the devices you actually carry. The brain stays on your own machine — Hermes-Relay is how you reach it.
 
 - **📱 Android app** — streaming chat, hands-free voice, native plugin pages, and the full Hermes dashboard (models, keys, skills, profiles), rebuilt native. Add a floating Petdex companion or optionally make Hermes your Android assistant; sideload builds can also let the agent read and act on your screen.
-- **⌨️ Hermes-Relay CLI** *(alpha)* — a single binary that gives the agent **hands on any machine you pair**: files, terminal, search, screenshots — consent-gated.
+- **⌨️ Hermes-Relay CLI** *(beta)* — a single binary that gives the agent **hands on any machine you pair**: files, terminal, search, screenshots — consent-gated.
 
-A vanilla [hermes-agent](https://github.com/NousResearch/hermes-agent) install is enough — chat, management, voice, Petdex, and ordinary installed-plugin pages need **no Relay plugin**. Add the optional Relay only when you want terminal, phone control, agent-created page drafts, or the CLI's tools. **Pair once from either surface; both work.**
+A vanilla [hermes-agent](https://github.com/NousResearch/hermes-agent) install is enough for the upstream standard path: chat, management, voice, Petdex, and ordinary installed-plugin pages. The Hermes-Relay plugin is optional for that base but encouraged for the complete current experience: Terminal/TUI, notifications, media, desktop tools, enhanced voice, Relay sessions, page drafts, and optional Device Control. Hermes-Relay prefers compatible upstream surfaces as they become available instead of keeping duplicate extension paths. **Connect Hermes first, then grant Hermes-Relay separately; the same one-time invite contract pairs Android or the Desktop CLI.**
 
 <p align="center">
-  <img src="docs/diagrams/architecture-homepage.png" alt="How Hermes-Relay connects — Vanilla Hermes (Chat, Manage, Voice) runs with no plugin; the optional Relay plugin adds Terminal, Bridge, relay voice and desktop tools to the app and CLI; Device Control needs the sideload build." width="900">
+  <img src="docs/diagrams/architecture-homepage.png" alt="How Hermes-Relay connects — upstream Hermes owns Chat, Manage, and standard Voice; the encouraged Relay extension fills current gaps for Terminal, notifications, media, enhanced voice, sessions, desktop tools, and optional Device Control." width="900">
 </p>
 
 ## Quick Start (Android)
@@ -50,7 +50,7 @@ Install → connect → talk, in about two minutes.
 
 ### 1 · Install the app
 
-- **Google Play** *(easiest — auto-updates)* — [**install from Google Play**](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay). Chat, voice, Manage, terminal/TUI, media, notifications, and relay sessions.
+- **Google Play** *(easiest — auto-updates)* — [**install from Google Play**](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay). Chat, voice, sessions, and Manage work with standard Hermes; pairing the Hermes-Relay plugin adds Terminal/TUI, media, notifications, and Relay sessions.
 - **APK** *(full phone-control feature set)* — download the file ending in **`-sideload-release.apk`** from the newest `android-v*` release on [GitHub Releases](https://github.com/Codename-11/hermes-relay/releases) and open it (allow your browser to install unknown apps the first time). Integrity verification, signing fingerprint, and per-build details are in the [Sideload guide](https://hermes-relay.dev/docs/guide/getting-started.html#sideload-apk).
 
 Sideload builds check GitHub for updates and show a one-tap banner when you're behind; Play builds update through the Store. See [Release tracks](https://hermes-relay.dev/docs/guide/release-tracks) for the capability matrix.
@@ -71,27 +71,21 @@ an HTTPS reverse proxy. The [full walkthrough](https://hermes-relay.dev/docs/gui
 covers Windows, remote access, and dashboard authentication. You do not need to
 enable the separate API server or invent an API key for the standard path.
 
-For plugin-enabled setups, optional **Hermes Secure Link** presents Relay, API,
-and Dashboard routes through one pairing-pinned TLS origin. It protects traffic
-to the paired endpoint while each service keeps its own authentication; it does
-not provide reachability or independently identify the physical host. You still
-use LAN routing, Tailscale or another VPN, or an operator-managed public route
-to reach the listener. Secure Link is off by default and requires a fresh QR
-pairing after it is enabled. See the
-[remote-access guide](https://hermes-relay.dev/docs/guide/remote-access/).
-
-**Hermes Reach** is an experimental, advanced outbound-broker route. It remains
-available for development and self-hosted evaluation, but it is disabled by
-default, ordered after supported routes, and not recommended for normal remote
-access. Use Tailscale for the easiest supported remote setup, or a public TLS
-domain / Direct Secure Link when you want to own the complete network path.
+Start on a trusted LAN. For away-from-home access, Tailscale is the recommended
+path. Secure Link, public TLS, and experimental routing options are covered in
+the [remote-access guide](https://hermes-relay.dev/docs/guide/remote-access/).
 
 ### 3 · Connect and talk
 
-Open the app, choose **Connect to Hermes**, and enter or discover the dashboard
-address (conventionally `http://<host>:9119`). Sign in through the dashboard's
-configured provider when prompted. The app probes the available upstream
-capabilities and finishes with a connection summary.
+For a plugin-enabled host, open the Web Dashboard's **Relay** page, click
+**Connect mobile app**, and scan that tokenless QR from Android **Connect → Scan
+Hermes setup QR**. It contains only the Dashboard address and configures the
+upstream Chat, sessions, Manage, sign-in, and standard voice connection.
+
+Without the Dashboard plugin, use **Find Hermes on LAN** or enter the Dashboard
+address manually (conventionally `http://<host>:9119`). Sign in through the
+Dashboard's configured provider when prompted. The app probes the available
+upstream capabilities and finishes with a connection summary.
 
 The separate API server can be discovered automatically or added later under
 **Advanced** as a chat fallback or for a headless compatibility setup. Its API
@@ -106,49 +100,47 @@ The wizard probes everything and finishes with a capability card:
 | **Manage** | Models, keys, skills, and profiles are available from the phone |
 | **Voice** | Speech ready via your server (or one Manage sign-in away) |
 | **API fallback** | Optional API route available/unavailable |
-| **Relay** | Optional extensions — fine to leave unpaired |
+| **Relay** | Recommended extensions paired/unpaired; never blocks the upstream path |
 
 One dashboard sign-in unlocks Chat, Manage, sessions, and standard voice. That's
 the whole Vanilla Hermes setup.
 
 > **Going places?** Add the Dashboard's Tailscale address — for example `http://100.x.y.z:9119` or a separately published `https://host.ts.net` URL — under **Settings → Connections → Routes**. Android tests it as a Dashboard route; no API server or API key is required. The app uses LAN at home and switches routes automatically when you leave. See [Remote access](https://hermes-relay.dev/docs/guide/remote-access).
 
-### 4 · Optional: install Relay for power tools
+### 4 · Recommended: pair Relay for the complete experience
 
-Install the Relay plugin on the server only when you want Terminal, Bridge phone control, relay sessions, media routes, the realtime voice engine, or approval-gated agent-created plugin-page drafts:
+Install Relay for Terminal/TUI, notifications, media handoff, desktop tools,
+enhanced voice, Relay sessions, approval-gated page drafts, and optional Device
+Control:
 
 ```bash
 hermes plugins install Codename-11/hermes-relay/plugin --enable
 hermes relay doctor
 hermes relay start --no-ssl
-hermes pair
 ```
 
-Use the legacy installer instead if you also want the systemd user service,
-shell shims, and the full clone/update workflow:
+Use `--no-ssl` only on a trusted LAN or VPN. Use the
+[remote-access guide](https://hermes-relay.dev/docs/guide/remote-access/) before
+exposing any Hermes surface beyond that network.
+
+Refresh or restart the Dashboard/Gateway, open **Relay → Pair new device**, and
+scan the one-time QR from Android **Settings → Connections → Pair Hermes Relay**.
+Leave mode on **Auto** for the recommended route discovery. The same dialog
+shows a copyable invite for Desktop CLI clients:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash
+hermes-relay pair --pair-qr "hermes-relay://pair?payload=…" --grant-tools
 ```
 
-Installed Hermes plugins can expose bounded, host-rendered pages to Android
-through the authenticated Dashboard without running plugin code on the phone.
-Relay 1.5.0 additionally supports approval-gated agent-created page drafts. The
-plugin-manager install owns the plugin code, dashboard tab, CLI commands, and
-agent tools. `hermes relay compat status/install/remove` manages only the
-optional legacy API compatibility hook when an older Hermes build needs it. Scan
-the QR from the phone's Connections screen — or use
-`hermes pair --register-code ABCD12` with the manual code from Android
-**Settings → Connections → Advanced**.
+As alternatives, `hermes pair` renders the same Android QR and pasteable invite
+in a terminal, while URL + six-character code and `--register-code` remain
+manual fallbacks when QR or clipboard transfer is unavailable.
 
-- **Plugin-manager uninstall:** `hermes relay compat remove --all` if you installed the optional hook, then `hermes plugins remove hermes-relay`.
-- **Legacy installer update:** `hermes-relay-update` (idempotent) — or re-run the install one-liner.
-- **Legacy installer uninstall:** `bash ~/.hermes/hermes-relay/uninstall.sh` — removes the service, shims, clone, external skill path, editable package, and compat hook. It never touches shared Hermes state. Flags: `--dry-run`, `--keep-clone`, `--remove-secret`.
-- **Dashboard plugin:** installs with the same symlink — restart the gateway and a **Relay** tab (paired devices, bridge activity, media tokens) appears in the web UI.
+**Next:** [Android + Hermes-Relay Quick Start](https://hermes-relay.dev/docs/guide/quick-start) ·
+[Desktop CLI pairing](https://hermes-relay.dev/docs/desktop/pairing) ·
+[server, TLS, legacy install, and uninstall reference](https://hermes-relay.dev/docs/reference/relay-server)
 
-Full server setup, TLS, and systemd details: [docs/relay-server.md](docs/relay-server.md).
-
-**Requirements:** Android 8.0+ (SDK 26) · current upstream [hermes-agent](https://github.com/NousResearch/hermes-agent) with the Dashboard/Gateway enabled · Python 3.11+ on the server. The API server and Relay are optional.
+**Requirements:** Android 8.0+ (SDK 26) · current upstream [hermes-agent](https://github.com/NousResearch/hermes-agent) with the Dashboard/Gateway enabled · Python 3.11+ when installing the Hermes-Relay plugin. The API fallback is optional; the Hermes-Relay plugin is encouraged for the complete experience.
 
 ## Screenshots
 
@@ -193,16 +185,16 @@ tracked independently so community corrections remain easy to contribute.
 - **Hands-free voice** — talk on a vanilla install: speech rides your server's configured providers, unlocked by the same Manage sign-in. Relay-paired setups add per-profile voice and an opt-in provider-native Realtime Agent with background task handoff.
 - **Works away from home** — add a Tailscale or public URL and the app roams automatically (LAN at home, fallback elsewhere). An unreachable server gets a diagnosis, not just a red dot.
 - **Multi-Connection + profiles** — pair multiple Hermes servers (home + work, dev + prod) and switch in one tap; overlay a profile's model + `SOUL.md` per chat.
-- **Phone control (bridge)** — with Relay paired, the agent reads the screen and acts: tap, type, swipe, scroll, screenshots, clipboard, media keys, batched macros. Guarded by per-app blocklist (banking/2FA blocked by default), destructive-verb confirmation, idle auto-disable, and a full activity log.
+- **Device Control (Sideload + Hermes-Relay required)** — the agent can read the screen and act: tap, type, swipe, scroll, screenshots, clipboard, media keys, and batched macros. This is not included in the Google Play build. It is guarded by a per-app blocklist (banking/2FA blocked by default), destructive-verb confirmation, idle auto-disable, and a full activity log.
 - **Notification companion** — opt-in access so the agent can triage, summarize, and route incoming notifications.
 - **Security & pairing** — QR pairing, Android Keystore session storage (StrongBox-preferred), TOFU cert pinning, per-channel time-bound grants, user-chosen session TTL.
 - **Stats for Nerds** — local-only analytics: TTFT, token usage, stream health, peak-time charts.
 
 > Sideload builds add direct SMS, contact search, one-tap dialing, and location awareness — handy for fully hands-free intents like *"text Sam I'll be 10 minutes late."* See [Release tracks](https://hermes-relay.dev/docs/guide/release-tracks).
 
-## Hands on any machine — the Hermes-Relay CLI&nbsp;<sub>(alpha)</sub>
+## Hands on any machine — the Hermes-Relay CLI&nbsp;<sub>(beta)</sub>
 
-> **Alpha.** Self-contained CLI binaries ship for Windows x64, Linux x64, and macOS x64/arm64 — no Node required. Windows also has an optional compact management tray. Assets are unsigned during the experimental phase, so SmartScreen / Gatekeeper warnings are expected.
+> **Beta.** Self-contained CLI binaries ship for Windows x64, Linux x64/arm64, and macOS x64/arm64 — no Node required. Windows also has an optional compact management tray. Assets are unsigned during the experimental phase, so SmartScreen / Gatekeeper warnings are expected.
 
 The agent's brain stays on the host; the CLI lets it call tools **on your machine** over the same WSS relay — `read_file`, `write_file`, `terminal`, `search_files`, `screenshot`, `clipboard`, `open_in_editor`, and more — behind a one-time consent gate, interactive diff approval for patches, and a `--no-tools` kill-switch.
 
@@ -220,6 +212,14 @@ It pairs against the **same relay and credential store** as the Android app —
 
 On Windows, the default installer adds the optional compact **Hermes-Relay CLI UI** tray popup for host selection and pairing, connection and daemon state, per-host Ask/Trusted/Full Access, local grant dialogs, authorized-client revocation, activity, settings, and emergency stop. It is a management surface only—chat, TUI, plugins, voice, and agent sessions remain CLI/upstream concerns.
 
+<table>
+  <tr>
+    <td align="center" width="33%"><img src="assets/screenshots/desktop-ui/overview.png" alt="Hermes-Relay CLI UI connected overview" width="100%"><br><sub><b>Connection &amp; activity</b></sub></td>
+    <td align="center" width="33%"><img src="assets/screenshots/desktop-ui/host-access.png" alt="Hermes-Relay CLI UI host access presets" width="100%"><br><sub><b>Per-host access</b></sub></td>
+    <td align="center" width="33%"><img src="assets/screenshots/desktop-ui/settings.png" alt="Hermes-Relay CLI UI computer control and updates" width="100%"><br><sub><b>Control &amp; maintenance</b></sub></td>
+  </tr>
+</table>
+
 Structured Windows computer control prefers a compatible local CUA Driver
 runtime for window-targeted background actions and virtual per-session agent
 cursors. It remains behind Hermes host policy, grants, targeting, audit, and
@@ -348,7 +348,7 @@ hermes-relay/
 
 <br>
 
-End users should install via the [one-liner](#4--optional-install-relay-for-power-tools) above. For local development:
+End users should follow the [recommended Hermes-Relay setup](#4--recommended-pair-relay-for-the-complete-experience) above. For local development:
 
 ```bash
 hermes relay start --no-ssl          # if you installed the plugin

RELEASE_NOTES.md

@@ -1,10 +1,10 @@
-# Hermes-Relay Android v1.12.1
+# Hermes-Relay Android v1.13.0
 
-**Release Date:** August 22, 2026
+**Release Date:** August 25, 2026
 
 ## Download
 
-> Installing on your phone? Download `hermes-relay-1.12.1-sideload-release.apk` and tap it for the full feature set, or install the conservative build from [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay).
+> Installing on your phone? Download `hermes-relay-1.13.0-sideload-release.apk` and tap it for the full feature set, or install the conservative build from [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay).
 
 The `.aab` file is a Play Console upload bundle and cannot be installed by tapping it on a phone.
 
@@ -12,18 +12,28 @@ Verify the download against `SHA256SUMS.txt`. See the [sideload guide](https://h
 
 ## Summary
 
-This patch makes Android sharing and recovery dependable. Shared links, text, images, and files open as complete reviewable drafts; connection renewal no longer stalls; offline and history failures are visible; and secure-storage recovery appears in Diagnostics.
+This feature release adds Bot Mode across saved Hermes gateways, provider usage and limits, and bounded Assistant screen context. It also settles stale Gateway composer state, improves onboarding, and keeps idle Sphere motion efficient.
+
+## Added
+
+- Use Bot Mode as one messenger-style workspace across saved Hermes gateways, with exact gateway/profile ownership and read-only group rooms.
+- Review Codex credential pools, Nous balances, and OpenCode Go windows from one provider-neutral Usage & limits screen.
+- Start a compatible unlocked Assistant invocation with bounded visible text and an available screenshot in the first Standard voice turn.
+
+## Changed
+
+- Follow the Dashboard-first setup path with current screenshots and clearer separation between standard Hermes and optional Relay extensions.
+- Use clear `Hermes-Relay Android` and isolated `HR Candidate` product names without changing package identities or update behavior.
 
 ## Fixed
 
-- Open shared links, text, images, files, and mixed or multi-item shares as a fresh reviewable draft without sending automatically.
-- Keep Add and Renew connection setup on the correct connection-scoped authentication store, with bounded Retry or Cancel recovery instead of an indefinite preparation screen.
-- Surface unavailable chat routes and profile-history failures clearly instead of silently dropping Send or presenting missing history as an empty conversation.
-- Report Android Keystore fallback, encrypted-store recovery, and temporary credential storage in Diagnostics without exposing credentials.
+- Settle orphaned Gateway busy state automatically while preserving active or detached turns owned by another session.
+- Keep the visible idle Sphere gently animated without running hidden, backgrounded, or motion-disabled loops.
+- Retry Windows-hosted `MEDIA:` attachments through the Relay by-path route instead of treating drive-letter paths as expired tokens.
 
 ## Install / Verify
 
-- App version: **1.12.1** (versionCode **48**).
+- App version: **1.13.0** (versionCode **49**).
 - Standard Chat, sessions, Manage, sharing, profile switching, and Vanilla Hermes voice continue to work against unmodified upstream Hermes.
 - Granular Device Control remains sideload-only; the Google Play build continues to ship Hermes Bridge Core without AccessibilityService Device Control.
-- The optional Relay plugin is not required for standard Android chat, sharing, session continuity, or Gateway recovery.
+- The optional Relay plugin enhances provider usage, media retry, and device surfaces but remains unnecessary for standard Android chat, sessions, Manage, and Vanilla Hermes voice.

app/src/googlePlay/play/listings/en-US/full-description.txt

@@ -1,62 +1,59 @@
-Hermes-Relay is the native Android client for the Hermes agent platform. Point it at your own Hermes instance and chat with your agent, talk to it hands-free, and manage models, keys, skills, and profiles from anywhere.
+Hermes-Relay is the native Android companion for the Hermes agent you run. Chat, talk hands-free, continue sessions, and manage models, keys, skills, profiles, and automations from your phone.
 
-It is not a hosted AI service. It is a companion app for the Hermes agent you run, and it talks only to the instances you configure.
+It is not a hosted AI service. Your Hermes agent stays on infrastructure you control, and the app talks only to instances you configure.
 
 QUICK START
 
-1. Run hermes-agent with its API server and dashboard enabled on your computer or home server.
-2. Install Hermes-Relay and enter your server address, for example http://192.168.1.100:8642.
-3. The setup wizard checks what your server supports and shows a readiness card, then you are ready to chat.
+1. Start the Hermes Dashboard/Gateway on your computer or home server with hermes dashboard.
+2. Install Hermes-Relay from Google Play.
+3. For the recommended full setup, install the Hermes-Relay plugin on the host and refresh the Web Dashboard. A Relay page will appear.
+4. Scan Connect mobile app from Android Connect. Then scan Pair new device from Android Settings > Connections.
 
-A plain Hermes install is enough. Chat, management, and voice work with no plugin or extra service.
+The QR codes are separate on purpose. Connect mobile app adds the standard Dashboard/Gateway connection. Pair new device grants a time-limited Hermes-Relay session for the additional capabilities you approve.
+
+Standard Hermes without the plugin is supported. Choose Find Hermes on LAN or enter the Dashboard address you open in a browser, normally http://<host>:9119. Pair the Hermes-Relay plugin later when you want the full experience.
 
 HOW IT WORKS
 
-Chat streams directly from your Hermes API Server or dashboard gateway in real time. Manage and voice use your Hermes dashboard with one sign-in. Run the optional relay service and the app can pair by QR code to add power tools: remote terminal, notification companion, media handoff, relay-session management, and additional voice engines.
+Chat, sessions, Manage, sign-in, and standard voice use the unmodified Hermes Dashboard/Gateway. The separate Hermes API server is an optional fallback for advanced or headless setups; it is not required for the normal Android connection.
 
-GOOGLE PLAY BUILD
+The encouraged Hermes-Relay plugin adds Terminal/TUI, notifications, media handoff, enhanced voice, Relay sessions, desktop-tool handoff, and time-limited per-feature grants. When upstream Hermes provides a compatible capability, Hermes-Relay prefers it instead of duplicating it.
 
-The Google Play build ships Hermes Bridge Core only. It has no AccessibilityService Device Control: it cannot read your screen, tap, type, swipe, screenshot, send SMS, place calls, or access contacts or location. Device Control is reserved for sideload builds distributed outside Google Play.
+GOOGLE PLAY AND SIDELOAD
+
+The Google Play build includes Chat, voice, sessions, Manage, profiles, notifications, media, and Terminal/TUI when the Hermes-Relay plugin is paired.
+
+Google Play does not include Android Device Control. It cannot read the phone screen, tap, type, swipe, take device screenshots, send SMS, place calls, or access contacts or location.
+
+Device Control is available only in the signed Sideload build on this project's GitHub Releases. It requires the Sideload app, a paired Hermes-Relay plugin, explicit Android accessibility permission, and the app's safety controls.
 
 FEATURES
 
-- Streaming Chat: real-time responses with reasoning, markdown, tool-call visibility, attachments, mid-turn steering, edit-and-resend, and a searchable command palette.
-
-- Manage Your Agent: use your Hermes dashboard from your phone to switch models, manage provider keys, edit profiles, and browse, install, and update skills.
-
-- Voice Mode: talk hands-free using your server's speech providers. Relay-paired setups add per-profile voices and an experimental realtime engine.
-
-- Works Away From Home: add LAN, Tailscale, or public routes and the app chooses the best available path on connect.
-
-- Sessions: create, switch, rename, and delete chats. Message history loads on demand.
-
-- Multiple Servers and Profiles: connect to more than one server and switch in a tap; overlay an agent profile or personality per conversation.
-
-- Relay Power Tools: optional QR pairing for remote terminal, relay-session management, media handoff, and per-feature grants.
-
-- Notification Companion: optionally forward notification metadata to your paired relay so your assistant can summarize it. Toggle it anytime in system settings.
-
-- Stats for Nerds: local-only counters for response timing, token usage, cost, and stream health.
-
-- Material You: Material 3 dynamic color, light/dark/system themes, and haptics.
+- Streaming Chat with reasoning, markdown, tool progress, attachments, mid-turn steering, edit-and-resend, and searchable commands.
+- Manage models and provider keys, edit profiles, and browse, install, or update skills through the Hermes Dashboard.
+- Hands-free voice through your server's speech providers. Hermes-Relay pairing adds per-profile voices and an experimental realtime engine.
+- Create, switch, search, rename, pin, archive, and continue sessions.
+- Connect multiple Hermes servers and switch in one tap; add LAN, Tailscale, or public routes.
+- Pair the Hermes-Relay plugin for Terminal/TUI, notifications, media, enhanced voice, Relay sessions, and per-feature grants.
+- Inspect connection readiness, routes, response timing, token usage, and stream health without exposing credentials.
 
 SECURITY AND PRIVACY
 
-- API keys and relay tokens are stored in encrypted Android storage.
-- HTTPS is enforced for remote connections; cleartext is limited to localhost or LAN setups.
+- Dashboard sessions and Hermes-Relay tokens use encrypted Android storage.
+- Cleartext is limited to trusted local-network setups. Use a VPN or HTTPS remotely.
 - No telemetry, ads, tracking, or third-party analytics SDKs.
-- Notification access and the microphone are optional and user-controlled.
-- All app traffic goes only to servers you configure.
+- Notification and microphone access are optional and user-controlled.
+- App traffic goes only to servers you configure.
 
 REQUIREMENTS
 
 - Android 8.0 or later.
-- A running Hermes agent for chat, management, and voice.
-- Optional Hermes relay service for power tools such as terminal, notifications, and media.
-- Network access to your server by local network, VPN, or internet.
+- A reachable Hermes Dashboard/Gateway.
+- The Hermes-Relay plugin is encouraged for the complete experience but never blocks standard Hermes.
+- Network access through a local network, VPN, or operator-managed internet route.
 
 OPEN SOURCE
 
-Hermes-Relay is MIT licensed. Source, docs, and issue tracking are on GitHub.
+Hermes-Relay is MIT licensed. Source, setup guides, downloads, and issue tracking are on GitHub.
 
-This app is a community project and is not affiliated with or endorsed by NousResearch.
+This community project is not affiliated with or endorsed by NousResearch.

app/src/googlePlay/play/listings/en-US/short-description.txt

@@ -1 +1 @@
-Your Hermes AI agent, in your pocket - chat, voice, and control.
+Your Hermes agent on Android — chat, voice, sessions, and Manage.

app/src/googlePlay/play/release-notes/en-US/default.txt

@@ -1 +1 @@
-Shared links, text, images, and files now open as complete reviewable drafts without sending automatically. Add and Renew connection setup no longer stalls. Offline chat and profile-history failures surface clear recovery guidance instead of doing nothing or showing empty history. Diagnostics now reports secure-storage fallback and recovery without exposing credentials.
+Bot Mode now brings bots from saved Hermes gateways into one messenger-style workspace. Settings adds provider-neutral Codex, Nous, and OpenCode Go usage. Compatible Assistant launches can include bounded visible text and an available screenshot. Gateway chats now settle stale busy state automatically, onboarding is clearer, and idle Sphere motion uses less power.

app/src/googlePlay/play/release-notes/zh-CN/default.txt

@@ -1 +1 @@
-共享链接、文本、图片和文件现在会作为完整、可检查的草稿打开，不会自动发送。添加或续订连接时不再卡在准备阶段。离线聊天和配置文件历史记录失败会显示明确的恢复提示，而不是无响应或显示空历史记录。诊断现在会报告安全存储降级与恢复，且不会暴露凭据。
+Bot 模式现在可将已保存 Hermes 网关中的机器人汇集到一个消息式工作区。设置新增统一的 Codex、Nous 和 OpenCode Go 用量视图。兼容的助手启动可在首个语音回合中包含受限的可见文本和可用截图。Gateway 聊天会自动清除过期的忙碌状态，引导更清晰，空闲 Sphere 动画也更省电。

app/src/main/assets/changelog.json

@@ -1,5 +1,33 @@
 {
  "versions": [
+  {
+   "version": "1.13.0",
+   "title": "Bots, usage, and reliable chat",
+   "date": "2026-08-25",
+   "sections": [
+    {
+     "header": "Talk across saved gateways",
+     "bullets": [
+      "Use Bot Mode as one messenger-style workspace for bots and read-only groups across saved Hermes gateways.",
+      "Keep every Bot Chat bound to its exact gateway and profile without changing the foreground connection."
+     ]
+    },
+    {
+     "header": "Understand account limits",
+     "bullets": [
+      "Review Codex credential pools, Nous balances, and OpenCode Go windows from one provider-neutral Usage and limits screen.",
+      "Choose Summary, Expanded, or Hidden presentation while provider credentials remain on the Hermes host."
+     ]
+    },
+    {
+     "header": "Keep chat and voice in context",
+     "bullets": [
+      "Settle orphaned Gateway busy state automatically while preserving another session's active or detached turn.",
+      "Include bounded visible text and an available screenshot in the first compatible Assistant voice turn."
+     ]
+    }
+   ]
+  },
   {
    "version": "1.12.1",
    "title": "Sharing and recovery that work",

app/src/main/assets/whats_new.txt

@@ -1,6 +1,6 @@
-v1.12.1 - Sharing and recovery that work
+v1.13.0 - Bots, usage, and reliable chat
 
-* Open shared links, text, images, and files as a reviewable draft without auto-sending.
-* Add or renew a connection without getting stuck during secure setup.
-* See clear recovery guidance when chat or profile history is unavailable.
-* Find secret-free secure-storage fallback and recovery evidence in Diagnostics.
+* Use Bot Mode across saved Hermes gateways without changing the foreground connection.
+* Review Codex, Nous, and OpenCode Go usage from one provider-neutral screen.
+* Include bounded visible text and an available screenshot in compatible Assistant turns.
+* Keep the composer accurate when Gateway completion frames and visible bubbles settle separately.

app/src/main/kotlin/com/hermesandroid/relay/data/ProviderUsagePreferences.kt

@@ -0,0 +1,63 @@
+package com.hermesandroid.relay.data
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.core.stringSetPreferencesKey
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+
+enum class ProviderUsageLandingMode(val storedValue: String) {
+    Summary("summary"),
+    Expanded("expanded"),
+    Hidden("hidden"),
+    ;
+
+    companion object {
+        fun fromStoredValue(value: String?): ProviderUsageLandingMode =
+            entries.firstOrNull { it.storedValue == value } ?: Summary
+    }
+}
+
+data class ProviderUsagePreferences(
+    val landingMode: ProviderUsageLandingMode = ProviderUsageLandingMode.Summary,
+    val visibleProviders: Set<String> = DEFAULT_VISIBLE_PROVIDERS,
+) {
+    companion object {
+        val DEFAULT_VISIBLE_PROVIDERS = setOf("openai-codex", "nous", "opencode-go")
+    }
+}
+
+class ProviderUsagePreferencesRepository(private val dataStore: DataStore<Preferences>) {
+    constructor(context: Context) : this(context.relayDataStore)
+
+    companion object {
+        internal val KEY_LANDING_MODE = stringPreferencesKey("provider_usage_landing_mode")
+        internal val KEY_VISIBLE_PROVIDERS = stringSetPreferencesKey("provider_usage_visible_providers")
+    }
+
+    val preferences: Flow<ProviderUsagePreferences> = dataStore.data
+        .map { prefs ->
+            ProviderUsagePreferences(
+                landingMode = ProviderUsageLandingMode.fromStoredValue(prefs[KEY_LANDING_MODE]),
+                visibleProviders = prefs[KEY_VISIBLE_PROVIDERS]
+                    ?: ProviderUsagePreferences.DEFAULT_VISIBLE_PROVIDERS,
+            )
+        }
+        .distinctUntilChanged()
+
+    suspend fun setLandingMode(mode: ProviderUsageLandingMode) {
+        dataStore.edit { it[KEY_LANDING_MODE] = mode.storedValue }
+    }
+
+    suspend fun setProviderVisible(providerId: String, visible: Boolean) {
+        dataStore.edit { prefs ->
+            val current = prefs[KEY_VISIBLE_PROVIDERS]
+                ?: ProviderUsagePreferences.DEFAULT_VISIBLE_PROVIDERS
+            prefs[KEY_VISIBLE_PROVIDERS] = if (visible) current + providerId else current - providerId
+        }
+    }
+}

app/src/main/kotlin/com/hermesandroid/relay/network/relay/RelayHttpClient.kt

@@ -9,6 +9,7 @@ import com.hermesandroid.relay.diagnostics.DiagnosticCategory
 import com.hermesandroid.relay.diagnostics.DiagnosticSeverity
 import com.hermesandroid.relay.diagnostics.DiagnosticsLog
 import com.hermesandroid.relay.diagnostics.NetworkDiagnosticGuidance
+import com.hermesandroid.relay.network.usage.ProviderUsageResponse
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.SerialName
@@ -1444,4 +1445,86 @@ class RelayHttpClient(
         val value = header?.trim()?.lowercase() ?: return false
         return value == "1" || value == "true"
     }
+
+    /** Provider-neutral compatibility fetch for gateways without `account.usage`. */
+    suspend fun fetchProviderUsage(
+        profile: String? = null,
+        sessionId: String? = null,
+    ): Result<ProviderUsageResponse?> =
+        withContext(Dispatchers.IO) {
+            val relayUrl = relayUrlProvider()?.trim().orEmpty()
+            if (relayUrl.isEmpty()) {
+                return@withContext Result.success(null)
+            }
+            val sessionToken = sessionTokenProvider()
+            if (sessionToken.isNullOrBlank()) {
+                return@withContext Result.success(null)
+            }
+
+            val httpBase = relayUrl
+                .replace(Regex("^wss://", RegexOption.IGNORE_CASE), "https://")
+                .replace(Regex("^ws://", RegexOption.IGNORE_CASE), "http://")
+                .trimEnd('/')
+
+            val url = "$httpBase/usage/providers".toHttpUrlOrNull()
+                ?.newBuilder()
+                ?.apply {
+                    profile?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                        addQueryParameter("profile", it)
+                    }
+                    sessionId?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                        addQueryParameter("session_id", it)
+                    }
+                }
+                ?.build()
+                ?: return@withContext Result.failure(
+                    IllegalArgumentException("Invalid relay URL: $httpBase")
+                )
+
+            val request = Request.Builder()
+                .url(url)
+                .get()
+                .header("Authorization", "Bearer $sessionToken")
+                .header("Accept", "application/json")
+                .build()
+
+            try {
+                okHttpClient.newCall(request).execute().use { response ->
+                    if (response.code == 404) {
+                        // Older or operator-disabled hosts simply do not expose
+                        // account usage. This is capability absence, not an error.
+                        return@withContext Result.success(null)
+                    }
+                    if (!response.isSuccessful) {
+                        val reason = when (response.code) {
+                            401, 403 -> "Unauthorized — re-pair with the relay"
+                            502 -> "Provider usage upstream error (HTTP ${response.code})"
+                            in 500..599 -> "Relay error (HTTP ${response.code})"
+                            else -> "HTTP ${response.code}: ${response.message.ifBlank { "request failed" }}"
+                        }
+                        return@withContext Result.failure(IOException(reason))
+                    }
+                    val body = response.body?.string().orEmpty()
+                    if (body.isBlank()) {
+                        return@withContext Result.failure(IOException("Empty response body"))
+                    }
+                    val parsed = runCatching {
+                        sessionsJson.decodeFromString(
+                            ProviderUsageResponse.serializer(),
+                            body,
+                        )
+                    }.getOrElse {
+                        Log.w(TAG, "fetchProviderUsage parse error: ${it.message}")
+                        return@withContext Result.failure(IOException("Unrecognized usage payload"))
+                    }
+                    Result.success(parsed)
+                }
+            } catch (e: IOException) {
+                Log.w(TAG, "fetchProviderUsage failed: ${e.message}")
+                Result.failure(IOException("Relay unreachable: ${e.message ?: "IO error"}"))
+            } catch (e: Exception) {
+                Log.w(TAG, "fetchProviderUsage unexpected error: ${e.message}")
+                Result.failure(e)
+            }
+        }
 }

app/src/main/kotlin/com/hermesandroid/relay/network/upstream/DashboardApiClient.kt

@@ -3,6 +3,7 @@ package com.hermesandroid.relay.network.upstream
 import android.content.Context
 import com.hermesandroid.relay.data.Profile
 import com.hermesandroid.relay.network.shutdownOffMainThread
+import com.hermesandroid.relay.network.usage.ProviderUsageResponse
 import com.hermesandroid.relay.network.upstream.models.MessageItem
 import com.hermesandroid.relay.network.upstream.models.MessageListResponse
 import com.hermesandroid.relay.network.upstream.models.SessionItem
@@ -448,6 +449,25 @@ class DashboardApiClient(
      */
     suspend fun getConfig(): Result<JsonObject> = getJsonObject("/api/config")
 
+    suspend fun getProviderUsage(
+        profile: String? = null,
+        sessionId: String? = null,
+    ): Result<ProviderUsageResponse?> {
+        val query = buildList {
+            profile?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                add("profile=${queryValue(it)}")
+            }
+            sessionId?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                add("session_id=${queryValue(it)}")
+            }
+        }
+        val suffix = query.joinToString(prefix = if (query.isEmpty()) "" else "?", separator = "&")
+        return getJsonObject("/api/plugins/hermes-relay/provider-usage$suffix")
+            .mapCatching { root ->
+                json.decodeFromJsonElement(ProviderUsageResponse.serializer(), root)
+            }
+    }
+
     /**
      * The config SCHEMA: `{fields: {<dot.path>: {type, description, category,
      * options?}}, category_order: [...]}`. Describes how to render each field;

app/src/main/kotlin/com/hermesandroid/relay/network/upstream/GatewayChatClient.kt

@@ -797,6 +797,11 @@ class GatewayChatClient(
      */
     fun hasActiveTurn(): Boolean = activeTurn?.ended == false || backgroundTurns.isNotEmpty()
 
+    /** True only when [storedId] still owns a foreground or deliberately detached turn. */
+    fun hasActiveTurnForSession(storedId: String): Boolean =
+        (activeTurn?.ended == false && storedSessionId == storedId) ||
+            backgroundTurns.values.any { it.storedSessionId == storedId }
+
     /** Live id to persist beside a durable stored id while a turn is active. */
     fun currentLiveSessionId(storedId: String): String? =
         liveSessionId?.takeIf { storedSessionId == storedId }
@@ -1426,6 +1431,21 @@ class GatewayChatClient(
             .onSuccess { commandsCatalogCache = it }
     }
 
+    /**
+     * Provider-neutral account limits owned by upstream Hermes. Current hosts
+     * may not expose this additive method yet; callers should treat JSON-RPC
+     * method-not-found as capability absence and use the optional Relay
+     * compatibility surface when paired.
+     */
+    suspend fun providerUsage(): Result<JsonObject> {
+        try {
+            connectMutex.withLock { ensureConnected() }
+        } catch (e: Exception) {
+            return Result.failure(e)
+        }
+        return rpc("account.usage", JsonObject(emptyMap()))
+    }
+
     /**
      * Create a schedule through upstream's authenticated `cron.manage` RPC.
      * No Relay scheduler or compatibility endpoint is involved.

app/src/main/kotlin/com/hermesandroid/relay/network/usage/ProviderUsageModels.kt

@@ -0,0 +1,89 @@
+package com.hermesandroid.relay.network.usage
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ProviderUsageResponse(
+    @SerialName("schema_version") val schemaVersion: Int = 1,
+    @SerialName("fetched_at") val fetchedAt: String? = null,
+    val capabilities: Set<String> = emptySet(),
+    val providers: List<ProviderUsageProvider> = emptyList(),
+) {
+    val relayEnhanced: Boolean
+        get() = capabilities.containsAll(RELAY_ENHANCED_CAPABILITIES)
+
+    companion object {
+        val RELAY_ENHANCED_CAPABILITIES = setOf(
+            "credential_pools",
+            "structured_balances",
+            "opencode_go",
+        )
+    }
+}
+
+@Serializable
+data class ProviderUsageProvider(
+    val id: String,
+    @SerialName("display_name") val displayName: String,
+    val status: String,
+    val source: String? = null,
+    @SerialName("fetched_at") val fetchedAt: String? = null,
+    val plan: String? = null,
+    val windows: List<ProviderUsageWindow> = emptyList(),
+    val details: List<String> = emptyList(),
+    val balances: List<ProviderUsageBalance> = emptyList(),
+    @SerialName("renews_at") val renewsAt: String? = null,
+    @SerialName("action_url") val actionUrl: String? = null,
+    val credentials: List<ProviderUsageCredential> = emptyList(),
+    @SerialName("active_credential_id") val activeCredentialId: String? = null,
+    @SerialName("active_credential_state") val activeCredentialState: String = "unknown",
+    @SerialName("active_observed_at") val activeObservedAt: String? = null,
+    val message: String? = null,
+) {
+    val available: Boolean get() = status == STATUS_AVAILABLE
+
+    companion object {
+        const val STATUS_AVAILABLE = "available"
+        const val STATUS_NOT_CONFIGURED = "not_configured"
+        const val STATUS_UNAVAILABLE = "unavailable"
+    }
+}
+
+@Serializable
+data class ProviderUsageBalance(
+    val id: String,
+    val label: String,
+    val amount: Double,
+    val currency: String = "USD",
+)
+
+@Serializable
+data class ProviderUsageCredential(
+    val id: String,
+    val label: String,
+    val active: Boolean = false,
+    val status: String,
+    @SerialName("pool_status") val poolStatus: String? = null,
+    @SerialName("last_status_at") val lastStatusAt: String? = null,
+    @SerialName("reset_at") val resetAt: String? = null,
+    val plan: String? = null,
+    val windows: List<ProviderUsageWindow> = emptyList(),
+    val details: List<String> = emptyList(),
+    val message: String? = null,
+) {
+    companion object {
+        const val STATUS_AVAILABLE = "available"
+        const val STATUS_AT_LIMIT = "at_limit"
+        const val STATUS_UNAVAILABLE = "unavailable"
+    }
+}
+
+@Serializable
+data class ProviderUsageWindow(
+    val id: String,
+    val label: String,
+    @SerialName("used_percent") val usedPercent: Double? = null,
+    @SerialName("reset_at") val resetAt: String? = null,
+    val detail: String? = null,
+)

app/src/main/kotlin/com/hermesandroid/relay/network/usage/ProviderUsageRepository.kt

@@ -0,0 +1,46 @@
+package com.hermesandroid.relay.network.usage
+
+import com.hermesandroid.relay.network.relay.RelayHttpClient
+import com.hermesandroid.relay.network.upstream.GatewayChatClient
+import com.hermesandroid.relay.network.upstream.DashboardApiClient
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.decodeFromJsonElement
+
+/** Relay-enhanced usage with an upstream fallback for hosts without Relay support. */
+class ProviderUsageRepository(
+    private val gatewayClientProvider: () -> GatewayChatClient?,
+    private val dashboardClientProvider: () -> DashboardApiClient? = { null },
+    private val relayHttpClient: RelayHttpClient,
+    private val profileProvider: () -> String? = { null },
+    private val sessionProvider: () -> String? = { null },
+) {
+    private val json = Json {
+        ignoreUnknownKeys = true
+        coerceInputValues = true
+        explicitNulls = false
+    }
+
+    suspend fun fetch(): Result<ProviderUsageResponse?> {
+        val profile = profileProvider()
+        val session = sessionProvider()
+        val dashboard = dashboardClientProvider()
+        if (dashboard != null) {
+            val enhanced = dashboard.getProviderUsage(profile, session)
+            if (enhanced.isSuccess && enhanced.getOrNull() != null) return enhanced
+        }
+
+        val relay = relayHttpClient.fetchProviderUsage(
+            profile = profile,
+            sessionId = session,
+        )
+        if (relay.isSuccess && relay.getOrNull() != null) return relay
+
+        val gateway = gatewayClientProvider()
+        if (gateway != null) {
+            val upstream = gateway.providerUsage()
+                .mapCatching { json.decodeFromJsonElement<ProviderUsageResponse>(it) }
+            if (upstream.isSuccess) return upstream
+        }
+        return relay
+    }
+}

app/src/main/kotlin/com/hermesandroid/relay/ui/RelayApp.kt

@@ -170,6 +170,7 @@ import com.hermesandroid.relay.ui.screens.PermissionsStatusScreen
 import com.hermesandroid.relay.ui.screens.ProfileInspectorScreen
 import com.hermesandroid.relay.ui.screens.RealtimeVoiceTestScreen
 import com.hermesandroid.relay.ui.screens.SettingsScreen
+import com.hermesandroid.relay.ui.screens.UsageLimitsScreen
 import com.hermesandroid.relay.ui.screens.PluginsScreen
 import com.hermesandroid.relay.ui.screens.PluginPageScreen
 import com.hermesandroid.relay.ui.screens.TerminalScreen
@@ -530,6 +531,7 @@ sealed class Screen(
     // the plural `ConnectionsSettings` subpage. See `ConnectionsSettings`
     // above for the surviving route.)
     data object ChatSettings : Screen("settings/chat", "Chat", Icons.Filled.Settings)
+    data object ProviderUsage : Screen("settings/usage", "Usage & limits", Icons.Filled.Settings)
     data object MediaSettings : Screen("settings/media", "Media", Icons.Filled.Settings)
     data object AppearanceSettings : Screen("settings/appearance", "Appearance", Icons.Filled.Settings)
     data object CustomTheme : Screen("settings/appearance/custom-theme", "Custom", Icons.Filled.Settings)
@@ -2387,6 +2389,9 @@ fun RelayApp() {
                         onNavigateToManage = {
                             navController.navigate(Screen.Manage.route)
                         },
+                        onNavigateToProviderUsage = {
+                            navController.navigate(Screen.ProviderUsage.route)
+                        },
                         onNavigateToPlugins = {
                             navController.navigate(Screen.Plugins.route)
                         },
@@ -2445,6 +2450,13 @@ fun RelayApp() {
                         },
                     )
                 }
+                composable(Screen.ProviderUsage.route) {
+                    UsageLimitsScreen(
+                        connectionViewModel = connectionViewModel,
+                        chatViewModel = chatViewModel,
+                        onBack = { navController.popBackStack() },
+                    )
+                }
                 composable(Screen.Plugins.route) {
                     PluginsScreen(
                         viewModel = pluginsViewModel,

app/src/main/kotlin/com/hermesandroid/relay/ui/components/MorphingSphere.kt

@@ -14,6 +14,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableFloatStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.withFrameNanos
+import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clipToBounds
 import androidx.compose.ui.geometry.Offset
@@ -25,6 +26,8 @@ import androidx.compose.ui.text.rememberTextMeasurer
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 import com.hermesandroid.relay.ui.theme.LocalBrand
+import kotlinx.coroutines.delay
+import kotlin.math.sin
 
 /**
  * ASCII morphing sphere — the visual embodiment of the AI agent.
@@ -53,6 +56,32 @@ import com.hermesandroid.relay.ui.theme.LocalBrand
 private const val SPHERE_TIME_UNITS_PER_SEC = 1f
 private const val SPHERE_TWO_PI = 6.2832f
 private const val SPHERE_COLOR_RADIANS_PER_SEC = 0.7854f
+private const val SPHERE_IDLE_BREATH_RADIANS_PER_SEC = 0.72f
+private const val SPHERE_IDLE_BREATH_SCALE = 0.012f
+private const val SPHERE_IDLE_LAYER_FRAME_INTERVAL_MS = 184L
+
+internal enum class SphereMotionMode {
+    Still,
+    AmbientLayer,
+    Procedural,
+}
+
+internal fun sphereMotionMode(
+    state: SphereState,
+    voiceMode: Boolean,
+    motionVisible: Boolean,
+    fixedTime: Float?,
+    fixedColorPhase: Float?,
+): SphereMotionMode {
+    if (!motionVisible || fixedTime != null || fixedColorPhase != null) {
+        return SphereMotionMode.Still
+    }
+    return if (state == SphereState.Idle && !voiceMode) {
+        SphereMotionMode.AmbientLayer
+    } else {
+        SphereMotionMode.Procedural
+    }
+}
 
 @Composable
 fun MorphingSphere(
@@ -64,7 +93,8 @@ fun MorphingSphere(
     voiceMode: Boolean = false,
     skin: SphereSkin = LocalSphereSkin.current,
     fixedTime: Float? = null,
-    fixedColorPhase: Float? = null
+    fixedColorPhase: Float? = null,
+    motionVisible: Boolean = true,
 ) {
     val brand = LocalBrand.current
     // Gate reactive inputs on what the skin declares it honors — this is the
@@ -104,16 +134,21 @@ fun MorphingSphere(
     val cg2 by animateFloatAsState(targetC.g2, spec, label = "cg2")
     val cb2 by animateFloatAsState(targetC.b2, spec, label = "cb2")
 
-    // Continuous motion runs only for active agent/voice states. Idle is a
-    // stable frame: the 58x34 text grid is expensive enough that even a
-    // throttled cosmetic drift dominated measured screen-on CPU. Active states
-    // retain full display-rate motion and dt-based timing.
+    // Active states retain the full procedural animation. Visible Idle uses a
+    // lightweight graphics-layer breath: redrawing the 58x34 glyph grid just
+    // for ambient drift was the measured screen-on hotspot, while transforming
+    // its cached layer preserves the intended living Sphere at far lower cost.
     val animatedTime = remember { mutableFloatStateOf(0f) }
     val animatedColorPhase = remember { mutableFloatStateOf(0f) }
-    val fullFrameRate = state != SphereState.Idle || effVoiceMode
-    val driveAnimation = (fixedTime == null || fixedColorPhase == null) && fullFrameRate
-    if (driveAnimation) {
-        LaunchedEffect(fullFrameRate) {
+    val motionMode = sphereMotionMode(
+        state = state,
+        voiceMode = effVoiceMode,
+        motionVisible = motionVisible,
+        fixedTime = fixedTime,
+        fixedColorPhase = fixedColorPhase,
+    )
+    if (motionMode == SphereMotionMode.Procedural) {
+        LaunchedEffect(motionMode) {
             var lastNanos = withFrameNanos { it }
             while (true) {
                 val now = withFrameNanos { it }
@@ -127,6 +162,25 @@ fun MorphingSphere(
             }
         }
     }
+    val idleBreathPhase = remember { mutableFloatStateOf(0f) }
+    LaunchedEffect(motionMode) {
+        if (motionMode != SphereMotionMode.AmbientLayer) {
+            idleBreathPhase.floatValue = 0f
+            return@LaunchedEffect
+        }
+        var lastNanos = withFrameNanos { it }
+        while (true) {
+            val now = withFrameNanos { it }
+            val dtSec = (now - lastNanos).coerceAtLeast(0L) / 1_000_000_000f
+            lastNanos = now
+            idleBreathPhase.floatValue =
+                (idleBreathPhase.floatValue + dtSec * SPHERE_IDLE_BREATH_RADIANS_PER_SEC) %
+                SPHERE_TWO_PI
+            // The frame wait plus this delay caps the gentle layer-only pulse
+            // near 5fps while active procedural states retain display-rate motion.
+            delay(SPHERE_IDLE_LAYER_FRAME_INTERVAL_MS)
+        }
+    }
 
     val time = fixedTime ?: animatedTime.floatValue
     val colorPhase = fixedColorPhase ?: animatedColorPhase.floatValue
@@ -138,7 +192,18 @@ fun MorphingSphere(
     val textMeasurer = rememberTextMeasurer(cacheSize = 64)
     val glyphStrings = remember { HashMap<Char, String>(32) }
 
-    Canvas(modifier = modifier.fillMaxSize().clipToBounds()) {
+    Canvas(
+        modifier = modifier
+            .fillMaxSize()
+            .graphicsLayer {
+                if (motionMode == SphereMotionMode.AmbientLayer) {
+                    val scale = 1f + sin(idleBreathPhase.floatValue) * SPHERE_IDLE_BREATH_SCALE
+                    scaleX = scale
+                    scaleY = scale
+                }
+            }
+            .clipToBounds(),
+    ) {
         val canvasW = size.width
         val canvasH = size.height
         val cellW = canvasW / cols

app/src/main/kotlin/com/hermesandroid/relay/ui/components/avatar/SphereAvatar.kt

@@ -1,9 +1,12 @@
 package com.hermesandroid.relay.ui.components.avatar
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
 import androidx.compose.ui.Modifier
 import com.hermesandroid.relay.ui.components.MorphingSphere
 import com.hermesandroid.relay.ui.components.SphereReactivity
+import com.hermesandroid.relay.util.AppForegroundTracker
 
 /**
  * Default ambient visualization — the ASCII [MorphingSphere].
@@ -34,6 +37,7 @@ object SphereAvatar : AgentAvatar {
 
     @Composable
     override fun Render(state: AvatarRenderState, modifier: Modifier) {
+        val appForeground by AppForegroundTracker.isForeground.collectAsState()
         MorphingSphere(
             modifier = modifier,
             state = state.state,
@@ -46,6 +50,7 @@ object SphereAvatar : AgentAvatar {
             // call did with fixedTime/fixedColorPhase = 0f.
             fixedTime = if (state.paused) 0f else null,
             fixedColorPhase = if (state.paused) 0f else null,
+            motionVisible = appForeground,
         )
     }
 }

app/src/main/kotlin/com/hermesandroid/relay/ui/screens/ConnectionsSettingsScreen.kt

@@ -116,7 +116,10 @@ fun ConnectionsSettingsScreen(
         val configured by connectionViewModel.relayConfigured.collectAsState()
         configured
     } else {
-        false
+        // Preview/screenshot hosts do not construct a ConnectionViewModel.
+        // Fall back to the persisted pairing metadata so their active card is
+        // honest instead of showing a connected Relay as "Optional".
+        connections.firstOrNull { it.id == activeConnectionId }?.hasConfiguredRelay() == true
     }
     val startupConnectionId: String? = if (connectionViewModel != null) {
         val startupId by connectionViewModel.startupConnectionId.collectAsState()
@@ -566,7 +569,7 @@ private fun ConnectionSurfaceSummary(
     val dashboardSignInRequired =
         dashboardStatus?.authRequired == true && dashboardStatus.authenticated != true
 
-    val chatRuntimeStatus: ChatRuntimeStatus? = if (isActive) {
+    val chatRuntimeStatus: ChatRuntimeStatus? = if (isActive && activeConnectionViewModel != null) {
         resolveChatRuntimeStatus(
             gateway = when (gatewayAvailability) {
                 GatewayAvailability.Ready -> ChatTransportReadiness.Ready

app/src/main/kotlin/com/hermesandroid/relay/ui/screens/SettingsScreen.kt

@@ -49,6 +49,7 @@ import androidx.compose.material.icons.filled.Lock
 import androidx.compose.material.icons.filled.NewReleases
 import androidx.compose.material.icons.filled.Palette
 import androidx.compose.material.icons.filled.PhoneAndroid
+import androidx.compose.material.icons.filled.Refresh
 import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.Card
 import androidx.compose.material3.CardDefaults
@@ -70,6 +71,7 @@ import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.runtime.snapshotFlow
@@ -96,11 +98,17 @@ import com.hermesandroid.relay.data.AgentDisplay
 import com.hermesandroid.relay.data.BuildFlavor
 import com.hermesandroid.relay.data.FeatureFlags
 import com.hermesandroid.relay.data.Profile
+import com.hermesandroid.relay.data.ProviderUsageLandingMode
+import com.hermesandroid.relay.data.ProviderUsagePreferences
+import com.hermesandroid.relay.data.ProviderUsagePreferencesRepository
+import com.hermesandroid.relay.network.usage.ProviderUsageRepository
+import com.hermesandroid.relay.network.usage.ProviderUsageResponse
 import com.hermesandroid.relay.network.upstream.GatewayAvailability
 import com.hermesandroid.relay.ui.components.AgentAvatarFace
 import com.hermesandroid.relay.ui.components.AgentInfoSheet
 import com.hermesandroid.relay.ui.components.LocalAgentIconPath
 import com.hermesandroid.relay.ui.components.ProfileInspectorCard
+import com.hermesandroid.relay.ui.components.RelaySkeletonLine
 import com.hermesandroid.relay.ui.components.pet.LocalPetCompanionCoordinator
 import com.hermesandroid.relay.ui.components.pet.petObstacleSurface
 import com.hermesandroid.relay.ui.components.pet.petPerchSurface
@@ -114,6 +122,7 @@ import com.hermesandroid.relay.viewmodel.ConnectionViewModel
 import com.hermesandroid.relay.viewmodel.RelayUiState
 import com.hermesandroid.relay.viewmodel.resolveChatRuntimeStatus
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.delay
 
 private const val SETTINGS_PET_SURFACE_ROUTE = "settings"
 private val SETTINGS_PET_SURFACE_ROUTES = setOf(SETTINGS_PET_SURFACE_ROUTE)
@@ -170,6 +179,7 @@ fun SettingsScreen(
     // expandable sections, so there's nothing left to link to twice.
     onNavigateToConnections: () -> Unit,
     onNavigateToManage: () -> Unit,
+    onNavigateToProviderUsage: () -> Unit,
     onNavigateToPlugins: () -> Unit,
     onNavigateToChatSettings: () -> Unit,
     onNavigateToTerminal: () -> Unit,
@@ -200,9 +210,57 @@ fun SettingsScreen(
     val isDarkTheme = LocalBrand.current.isDark
 
     val activeConnection by connectionViewModel.activeConnection.collectAsState()
+    val selectedProfile by connectionViewModel.selectedProfile.collectAsState()
+    val currentSessionId by chatViewModel.currentSessionId.collectAsState()
+    val providerUsagePreferencesRepository = remember(context) {
+        ProviderUsagePreferencesRepository(context)
+    }
+    val providerUsagePreferences by providerUsagePreferencesRepository.preferences.collectAsState(
+        initial = ProviderUsagePreferences(),
+    )
+    val providerUsageRepository = remember(connectionViewModel) {
+        ProviderUsageRepository(
+            gatewayClientProvider = connectionViewModel::activeGatewayChatClient,
+            dashboardClientProvider = {
+                connectionViewModel.activeDashboardUrl()?.let(
+                    connectionViewModel::dashboardClientForActive,
+                )
+            },
+            relayHttpClient = connectionViewModel.relayHttpClient,
+            profileProvider = { connectionViewModel.selectedProfile.value?.name },
+            sessionProvider = { chatViewModel.currentSessionId.value },
+        )
+    }
+    var providerUsageResponse by remember { mutableStateOf<ProviderUsageResponse?>(null) }
+    var providerUsageLoaded by remember { mutableStateOf(false) }
+    var providerUsageRefreshing by remember { mutableStateOf(false) }
+    var providerUsageRefreshKey by remember { mutableIntStateOf(0) }
+    LaunchedEffect(
+        activeConnection?.id,
+        selectedProfile?.name,
+        currentSessionId,
+        providerUsagePreferences.landingMode,
+        providerUsageRefreshKey,
+    ) {
+        if (providerUsagePreferences.landingMode == ProviderUsageLandingMode.Hidden) {
+            providerUsageResponse = null
+            providerUsageLoaded = true
+        } else {
+            if (providerUsageResponse == null) providerUsageLoaded = false
+            providerUsageRefreshing = providerUsageResponse != null
+            providerUsageRepository.fetch().getOrNull()?.let { providerUsageResponse = it }
+            providerUsageLoaded = true
+            providerUsageRefreshing = false
+        }
+    }
+    LaunchedEffect(providerUsagePreferences.landingMode) {
+        while (providerUsagePreferences.landingMode != ProviderUsageLandingMode.Hidden) {
+            delay(300_000)
+            providerUsageRefreshKey++
+        }
+    }
     // Active Agent card inputs — personality + profile drive the title,
     // ring-accent, and subtitle.
-    val selectedProfile by connectionViewModel.selectedProfile.collectAsState()
     val agentProfiles by connectionViewModel.agentProfiles.collectAsState()
     val effectiveProfile by connectionViewModel.effectiveDisplayProfile.collectAsState()
     val profileDisplayAlias by connectionViewModel.profileDisplayAlias.collectAsState()
@@ -477,6 +535,16 @@ fun SettingsScreen(
                 isDarkTheme = isDarkTheme,
             )
 
+            ProviderUsageLandingCard(
+                response = providerUsageResponse,
+                loaded = providerUsageLoaded,
+                refreshing = providerUsageRefreshing,
+                preferences = providerUsagePreferences,
+                onDisplay = onNavigateToProviderUsage,
+                onRefresh = { providerUsageRefreshKey++ },
+                isDarkTheme = isDarkTheme,
+            )
+
             SettingsSectionHeader(stringResource(R.string.settings_hermes))
 
             SettingsCategoryRow(
@@ -1257,6 +1325,135 @@ private fun SettingsStatusPill(pill: SettingsStatusPillModel) {
     }
 }
 
+@Composable
+private fun ProviderUsageLandingCard(
+    response: ProviderUsageResponse?,
+    loaded: Boolean,
+    refreshing: Boolean,
+    preferences: ProviderUsagePreferences,
+    onDisplay: () -> Unit,
+    onRefresh: () -> Unit,
+    isDarkTheme: Boolean,
+) {
+    val providers = response?.providers
+        ?.filter { it.available && it.id in preferences.visibleProviders }
+        .orEmpty()
+    Card(
+        modifier = Modifier
+            .settingsPetSurface("settings-card:provider-usage")
+            .fillMaxWidth()
+            .gradientBorder(
+                shape = appearanceRoundedCornerShape(12.dp),
+                isDarkTheme = isDarkTheme,
+            ),
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceVariant,
+        ),
+    ) {
+        Column {
+            Row(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(start = 16.dp, end = 8.dp, top = 12.dp, bottom = 12.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Icon(
+                    imageVector = Icons.Filled.Analytics,
+                    contentDescription = null,
+                    tint = MaterialTheme.colorScheme.primary,
+                    modifier = Modifier.size(22.dp),
+                )
+                Spacer(modifier = Modifier.width(16.dp))
+                Column(
+                    modifier = Modifier.weight(1f),
+                    verticalArrangement = Arrangement.spacedBy(4.dp),
+                ) {
+                    Text(
+                        text = stringResource(R.string.provider_usage_title),
+                        style = MaterialTheme.typography.bodyLarge,
+                    )
+                    Text(
+                        text = stringResource(
+                            when (response?.relayEnhanced) {
+                                true -> R.string.provider_usage_settings_desc_relay
+                                false -> R.string.provider_usage_settings_desc_basic
+                                null -> R.string.provider_usage_settings_desc
+                            },
+                        ),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                IconButton(onClick = onRefresh, enabled = !refreshing) {
+                    Icon(
+                        imageVector = Icons.Filled.Refresh,
+                        contentDescription = stringResource(R.string.provider_usage_refresh),
+                        tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                TextButton(onClick = onDisplay) {
+                    Text(stringResource(R.string.provider_usage_customize))
+                }
+            }
+
+            HorizontalDivider(
+                modifier = Modifier.padding(horizontal = 16.dp),
+                color = MaterialTheme.colorScheme.outlineVariant,
+            )
+
+            when {
+                preferences.landingMode == ProviderUsageLandingMode.Hidden -> {
+                    Text(
+                        text = stringResource(R.string.provider_usage_hidden_hint),
+                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 14.dp),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                !loaded -> {
+                    ProviderUsageSkeleton(
+                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 14.dp),
+                    )
+                }
+                providers.isEmpty() -> {
+                    Text(
+                        text = stringResource(R.string.provider_usage_not_available_compact),
+                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 14.dp),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                else -> providers.forEachIndexed { index, provider ->
+                    if (index > 0) {
+                        HorizontalDivider(
+                            modifier = Modifier.padding(horizontal = 16.dp),
+                            color = MaterialTheme.colorScheme.outlineVariant,
+                        )
+                    }
+                    ProviderUsageContent(
+                        provider = provider,
+                        detailed = preferences.landingMode == ProviderUsageLandingMode.Expanded,
+                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 14.dp),
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageSkeleton(modifier: Modifier = Modifier) {
+    Column(modifier = modifier, verticalArrangement = Arrangement.spacedBy(10.dp)) {
+        RelaySkeletonLine(width = 112.dp, height = 16.dp)
+        Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+            RelaySkeletonLine(width = 86.dp)
+            RelaySkeletonLine(width = 58.dp)
+        }
+        RelaySkeletonLine(width = 260.dp, height = 6.dp)
+        RelaySkeletonLine(width = 92.dp, height = 10.dp)
+    }
+}
+
 @Composable
 private fun SettingsSectionHeader(
     label: String,

app/src/main/kotlin/com/hermesandroid/relay/ui/screens/UsageLimitsScreen.kt

@@ -0,0 +1,700 @@
+package com.hermesandroid.relay.ui.screens
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.filled.Refresh
+import androidx.compose.material.icons.filled.Info
+import androidx.compose.material3.Card
+import androidx.compose.material3.CardDefaults
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.SegmentedButton
+import androidx.compose.material3.SegmentedButtonDefaults
+import androidx.compose.material3.SingleChoiceSegmentedButtonRow
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.TopAppBarDefaults
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.platform.LocalUriHandler
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import com.hermesandroid.relay.R
+import com.hermesandroid.relay.data.ProviderUsageLandingMode
+import com.hermesandroid.relay.data.ProviderUsagePreferences
+import com.hermesandroid.relay.data.ProviderUsagePreferencesRepository
+import com.hermesandroid.relay.network.usage.ProviderUsageProvider
+import com.hermesandroid.relay.network.usage.ProviderUsageCredential
+import com.hermesandroid.relay.network.usage.ProviderUsageBalance
+import com.hermesandroid.relay.network.usage.ProviderUsageRepository
+import com.hermesandroid.relay.network.usage.ProviderUsageResponse
+import com.hermesandroid.relay.network.usage.ProviderUsageWindow
+import com.hermesandroid.relay.viewmodel.ConnectionViewModel
+import com.hermesandroid.relay.viewmodel.ChatViewModel
+import com.hermesandroid.relay.ui.components.RelaySkeletonLine
+import java.time.Duration
+import java.time.Instant
+import java.time.ZoneId
+import java.time.format.DateTimeFormatter
+import java.time.format.FormatStyle
+import java.text.NumberFormat
+import java.util.Currency
+import java.util.Locale
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+
+private sealed interface UsageLoadState {
+    data object Loading : UsageLoadState
+    data object Unsupported : UsageLoadState
+    data class Loaded(val response: ProviderUsageResponse) : UsageLoadState
+    data object Error : UsageLoadState
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun UsageLimitsScreen(
+    connectionViewModel: ConnectionViewModel,
+    chatViewModel: ChatViewModel,
+    onBack: () -> Unit,
+) {
+    val context = androidx.compose.ui.platform.LocalContext.current
+    val activeConnection by connectionViewModel.activeConnection.collectAsState()
+    val selectedProfile by connectionViewModel.selectedProfile.collectAsState()
+    val currentSessionId by chatViewModel.currentSessionId.collectAsState()
+    val preferencesRepository = remember(context) { ProviderUsagePreferencesRepository(context) }
+    val preferences by preferencesRepository.preferences.collectAsState(
+        initial = ProviderUsagePreferences(),
+    )
+    val repository = remember(connectionViewModel) {
+        ProviderUsageRepository(
+            gatewayClientProvider = connectionViewModel::activeGatewayChatClient,
+            dashboardClientProvider = {
+                connectionViewModel.activeDashboardUrl()?.let(
+                    connectionViewModel::dashboardClientForActive,
+                )
+            },
+            relayHttpClient = connectionViewModel.relayHttpClient,
+            profileProvider = { connectionViewModel.selectedProfile.value?.name },
+            sessionProvider = { chatViewModel.currentSessionId.value },
+        )
+    }
+    var refreshKey by remember { mutableIntStateOf(0) }
+    var state by remember { mutableStateOf<UsageLoadState>(UsageLoadState.Loading) }
+    var refreshing by remember { mutableStateOf(false) }
+    val scope = rememberCoroutineScope()
+
+    LaunchedEffect(activeConnection?.id, selectedProfile?.name, currentSessionId, refreshKey) {
+        val hadContent = state is UsageLoadState.Loaded
+        if (!hadContent) state = UsageLoadState.Loading else refreshing = true
+        val next = repository.fetch().fold(
+            onSuccess = { result ->
+                result?.let(UsageLoadState::Loaded) ?: UsageLoadState.Unsupported
+            },
+            onFailure = { UsageLoadState.Error },
+        )
+        if (!hadContent || next is UsageLoadState.Loaded) state = next
+        refreshing = false
+    }
+    LaunchedEffect(Unit) {
+        while (true) {
+            delay(300_000)
+            refreshKey++
+        }
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text(stringResource(R.string.provider_usage_title)) },
+                navigationIcon = {
+                    IconButton(onClick = onBack) {
+                        Icon(
+                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
+                            contentDescription = stringResource(R.string.provider_usage_back),
+                            tint = MaterialTheme.colorScheme.primary,
+                        )
+                    }
+                },
+                actions = {
+                    IconButton(onClick = { refreshKey++ }, enabled = !refreshing) {
+                        Icon(
+                            imageVector = Icons.Filled.Refresh,
+                            contentDescription = stringResource(R.string.provider_usage_refresh),
+                            tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.surface,
+                ),
+            )
+        },
+    ) { innerPadding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(innerPadding)
+                .verticalScroll(rememberScrollState())
+                .padding(horizontal = 16.dp, vertical = 16.dp),
+            verticalArrangement = Arrangement.spacedBy(16.dp),
+        ) {
+            Column(verticalArrangement = Arrangement.spacedBy(3.dp)) {
+                Text(
+                    text = activeConnection?.label ?: stringResource(R.string.settings_no_connection),
+                    style = MaterialTheme.typography.titleMedium,
+                    fontWeight = FontWeight.SemiBold,
+                    color = MaterialTheme.colorScheme.primary,
+                )
+                Text(
+                    text = stringResource(R.string.provider_usage_intro),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+
+            when (val current = state) {
+                UsageLoadState.Loading -> ProviderUsageLoading()
+                UsageLoadState.Unsupported -> ProviderUsageMessage(
+                    text = stringResource(R.string.provider_usage_not_available),
+                )
+                UsageLoadState.Error -> ProviderUsageError(onRetry = { refreshKey++ })
+                is UsageLoadState.Loaded -> {
+                    ProviderUsageCapabilityNotice(relayEnhanced = current.response.relayEnhanced)
+                    val providers = current.response.providers
+                    if (providers.none { it.available }) {
+                        ProviderUsageMessage(
+                            text = stringResource(R.string.provider_usage_none_configured),
+                        )
+                    }
+                    providers.forEach { provider ->
+                        ProviderUsageCard(
+                            provider = provider,
+                            detailed = true,
+                        )
+                    }
+                }
+            }
+
+            ProviderUsageDisplaySettings(
+                preferences = preferences,
+                providers = (state as? UsageLoadState.Loaded)?.response?.providers.orEmpty(),
+                onModeChanged = { mode ->
+                    scope.launch { preferencesRepository.setLandingMode(mode) }
+                },
+                onProviderVisibilityChanged = { providerId, visible ->
+                    scope.launch {
+                        preferencesRepository.setProviderVisible(providerId, visible)
+                    }
+                },
+            )
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageCapabilityNotice(relayEnhanced: Boolean) {
+    Card(
+        modifier = Modifier.fillMaxWidth(),
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.primaryContainer,
+            contentColor = MaterialTheme.colorScheme.onPrimaryContainer,
+        ),
+    ) {
+        Row(
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+            verticalAlignment = Alignment.Top,
+        ) {
+            Icon(
+                imageVector = Icons.Filled.Info,
+                contentDescription = null,
+                modifier = Modifier.size(20.dp),
+            )
+            Column(verticalArrangement = Arrangement.spacedBy(3.dp)) {
+                Text(
+                    text = stringResource(
+                        if (relayEnhanced) R.string.provider_usage_capability_relay_title
+                        else R.string.provider_usage_capability_basic_title,
+                    ),
+                    style = MaterialTheme.typography.labelLarge,
+                    fontWeight = FontWeight.SemiBold,
+                )
+                Text(
+                    text = stringResource(
+                        if (relayEnhanced) R.string.provider_usage_capability_relay_body
+                        else R.string.provider_usage_capability_basic_body,
+                    ),
+                    style = MaterialTheme.typography.bodySmall,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageLoading() {
+    Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
+        repeat(2) {
+            Card(
+                modifier = Modifier.fillMaxWidth(),
+                colors = CardDefaults.cardColors(
+                    containerColor = MaterialTheme.colorScheme.surfaceVariant,
+                ),
+            ) {
+                Column(
+                    modifier = Modifier.padding(16.dp),
+                    verticalArrangement = Arrangement.spacedBy(10.dp),
+                ) {
+                    RelaySkeletonLine(width = 112.dp, height = 18.dp)
+                    Row(
+                        modifier = Modifier.fillMaxWidth(),
+                        horizontalArrangement = Arrangement.SpaceBetween,
+                    ) {
+                        RelaySkeletonLine(width = 92.dp)
+                        RelaySkeletonLine(width = 62.dp)
+                    }
+                    RelaySkeletonLine(width = 280.dp, height = 6.dp)
+                    RelaySkeletonLine(width = 98.dp, height = 10.dp)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageMessage(text: String) {
+    Card(
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceVariant,
+        ),
+    ) {
+        Text(
+            text = text,
+            modifier = Modifier.padding(16.dp),
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+}
+
+@Composable
+private fun ProviderUsageError(onRetry: () -> Unit) {
+    Card(
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceVariant,
+        ),
+    ) {
+        Column(modifier = Modifier.padding(16.dp)) {
+            Text(
+                text = stringResource(R.string.provider_usage_error),
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            TextButton(onClick = onRetry) {
+                Text(stringResource(R.string.provider_usage_retry))
+            }
+        }
+    }
+}
+
+@Composable
+fun ProviderUsageCard(
+    provider: ProviderUsageProvider,
+    detailed: Boolean,
+    modifier: Modifier = Modifier,
+) {
+    Card(
+        modifier = modifier.fillMaxWidth(),
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceVariant,
+        ),
+    ) {
+        ProviderUsageContent(
+            provider = provider,
+            detailed = detailed,
+            modifier = Modifier.padding(16.dp),
+        )
+    }
+}
+
+@Composable
+fun ProviderUsageContent(
+    provider: ProviderUsageProvider,
+    detailed: Boolean,
+    modifier: Modifier = Modifier,
+) {
+    Column(
+        modifier = modifier,
+        verticalArrangement = Arrangement.spacedBy(10.dp),
+    ) {
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.SpaceBetween,
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Text(
+                    text = provider.displayName,
+                    style = MaterialTheme.typography.titleMedium,
+                    fontWeight = FontWeight.SemiBold,
+                )
+                provider.plan?.let {
+                    Text(
+                        text = it,
+                        style = MaterialTheme.typography.labelMedium,
+                        color = MaterialTheme.colorScheme.primary,
+                    )
+                }
+            }
+            if (!provider.available) {
+                Text(
+                    text = providerUnavailableText(provider),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                return@Column
+            }
+            if (provider.balances.isNotEmpty()) {
+                ProviderBalanceUsage(provider, detailed)
+            } else if (provider.credentials.isNotEmpty()) {
+                val shownCredentials = if (detailed) {
+                    provider.credentials
+                } else {
+                    provider.credentials.filter { it.active }.take(1)
+                }
+                if (shownCredentials.isEmpty()) {
+                    Text(
+                        text = stringResource(R.string.provider_usage_active_unknown),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                } else {
+                    shownCredentials.forEach { credential ->
+                        ProviderCredentialUsage(credential, detailed)
+                    }
+                }
+            } else {
+                val windows = if (detailed) provider.windows else provider.windows.take(1)
+                windows.forEach { ProviderUsageWindowRow(it) }
+            }
+            if (detailed && provider.credentials.isEmpty() && provider.balances.isEmpty()) {
+                provider.details.forEach { detail ->
+                    Text(
+                        text = detail,
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+    }
+}
+
+@Composable
+private fun ProviderBalanceUsage(
+    provider: ProviderUsageProvider,
+    detailed: Boolean,
+) {
+    val uriHandler = LocalUriHandler.current
+    val total = provider.balances.firstOrNull { it.id == "total" }
+        ?: provider.balances.first()
+    val supporting = provider.balances.filterNot { it.id == total.id }
+    Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+        Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Text(
+                text = formatBalance(total),
+                style = MaterialTheme.typography.headlineSmall,
+                fontWeight = FontWeight.SemiBold,
+                color = MaterialTheme.colorScheme.primary,
+            )
+            Text(
+                text = total.label,
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        if (detailed) {
+            supporting.forEach { balance ->
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Text(
+                        text = balance.label,
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    Text(
+                        text = formatBalance(balance),
+                        style = MaterialTheme.typography.bodyMedium,
+                        fontWeight = FontWeight.Medium,
+                    )
+                }
+            }
+        }
+        formatRenewal(provider.renewsAt)?.let { renewal ->
+            Text(
+                text = stringResource(R.string.provider_usage_renews_on, renewal),
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        if (detailed && !provider.actionUrl.isNullOrBlank()) {
+            TextButton(onClick = { uriHandler.openUri(provider.actionUrl) }) {
+                Text(stringResource(R.string.provider_usage_manage_credits))
+            }
+        }
+        if (detailed) {
+            provider.details.forEach { detail ->
+                Text(
+                    text = detail,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.error,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun ProviderCredentialUsage(
+    credential: ProviderUsageCredential,
+    detailed: Boolean,
+) {
+    Column(verticalArrangement = Arrangement.spacedBy(7.dp)) {
+        Row(
+            modifier = Modifier.fillMaxWidth(),
+            horizontalArrangement = Arrangement.SpaceBetween,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Text(
+                text = credential.label,
+                style = MaterialTheme.typography.labelLarge,
+                fontWeight = if (credential.active) FontWeight.SemiBold else FontWeight.Normal,
+            )
+            Text(
+                text = when {
+                    credential.active && credential.status == ProviderUsageCredential.STATUS_AVAILABLE ->
+                        stringResource(R.string.provider_usage_active_available)
+                    credential.active && credential.status == ProviderUsageCredential.STATUS_AT_LIMIT ->
+                        stringResource(R.string.provider_usage_active_at_limit)
+                    credential.active -> stringResource(R.string.provider_usage_active)
+                    credential.status == ProviderUsageCredential.STATUS_AVAILABLE ->
+                        stringResource(R.string.provider_usage_available)
+                    credential.status == ProviderUsageCredential.STATUS_AT_LIMIT ->
+                        stringResource(R.string.provider_usage_at_limit)
+                    else -> stringResource(R.string.provider_usage_unavailable_status)
+                },
+                style = MaterialTheme.typography.labelSmall,
+                color = when (credential.status) {
+                    ProviderUsageCredential.STATUS_AT_LIMIT -> MaterialTheme.colorScheme.error
+                    ProviderUsageCredential.STATUS_AVAILABLE -> MaterialTheme.colorScheme.primary
+                    else -> MaterialTheme.colorScheme.onSurfaceVariant
+                },
+            )
+        }
+        val windows = if (detailed) credential.windows else credential.windows.take(1)
+        windows.forEach { ProviderUsageWindowRow(it) }
+        if (detailed) {
+            credential.details.forEach { detail ->
+                Text(
+                    text = detail,
+                    style = MaterialTheme.typography.labelSmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageWindowRow(window: ProviderUsageWindow) {
+    var now by remember { mutableStateOf(Instant.now()) }
+    LaunchedEffect(window.resetAt) {
+        while (window.resetAt != null) {
+            delay(60_000)
+            now = Instant.now()
+        }
+    }
+    val percent = window.usedPercent?.coerceIn(0.0, 100.0)
+    Column(verticalArrangement = Arrangement.spacedBy(5.dp)) {
+        Row(
+            modifier = Modifier.fillMaxWidth(),
+            horizontalArrangement = Arrangement.SpaceBetween,
+        ) {
+            Text(window.label, style = MaterialTheme.typography.labelLarge)
+            Text(
+                text = percent?.let { stringResource(R.string.provider_usage_percent, it.toInt()) }
+                    ?: window.detail.orEmpty(),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        if (percent != null) {
+            LinearProgressIndicator(
+                progress = { (percent / 100.0).toFloat() },
+                modifier = Modifier.fillMaxWidth().height(6.dp),
+                color = when {
+                    percent >= 90 -> MaterialTheme.colorScheme.error
+                    percent >= 75 -> MaterialTheme.colorScheme.tertiary
+                    else -> MaterialTheme.colorScheme.primary
+                },
+                trackColor = MaterialTheme.colorScheme.surfaceContainerHighest,
+            )
+        }
+        formatReset(window.resetAt, now)?.let { reset ->
+            Text(
+                text = stringResource(R.string.provider_usage_resets, reset),
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        if (percent != null && !window.detail.isNullOrBlank()) {
+            Text(
+                text = window.detail,
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+    }
+}
+
+@Composable
+private fun ProviderUsageDisplaySettings(
+    preferences: ProviderUsagePreferences,
+    providers: List<ProviderUsageProvider>,
+    onModeChanged: (ProviderUsageLandingMode) -> Unit,
+    onProviderVisibilityChanged: (String, Boolean) -> Unit,
+) {
+    Text(
+        text = stringResource(R.string.provider_usage_display_title),
+        style = MaterialTheme.typography.titleMedium,
+        fontWeight = FontWeight.SemiBold,
+        color = MaterialTheme.colorScheme.primary,
+    )
+    Card(
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceVariant,
+        ),
+    ) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(14.dp),
+        ) {
+            Text(
+                text = stringResource(R.string.provider_usage_display_desc),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            val modes = ProviderUsageLandingMode.entries
+            SingleChoiceSegmentedButtonRow(modifier = Modifier.fillMaxWidth()) {
+                modes.forEachIndexed { index, mode ->
+                    SegmentedButton(
+                        selected = preferences.landingMode == mode,
+                        onClick = { onModeChanged(mode) },
+                        shape = SegmentedButtonDefaults.itemShape(index, modes.size),
+                    ) {
+                        Text(
+                            when (mode) {
+                                ProviderUsageLandingMode.Summary -> stringResource(R.string.provider_usage_mode_summary)
+                                ProviderUsageLandingMode.Expanded -> stringResource(R.string.provider_usage_mode_expanded)
+                                ProviderUsageLandingMode.Hidden -> stringResource(R.string.provider_usage_mode_hidden)
+                            }
+                        )
+                    }
+                }
+            }
+            Text(
+                text = stringResource(R.string.provider_usage_providers_title),
+                style = MaterialTheme.typography.labelLarge,
+            )
+            Text(
+                text = stringResource(R.string.provider_usage_providers_desc),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            val rows = if (providers.isEmpty()) {
+                listOf(
+                    "openai-codex" to "Codex",
+                    "nous" to "Nous",
+                    "opencode-go" to "OpenCode Go",
+                )
+            } else {
+                providers.map { it.id to it.displayName }
+            }
+            rows.forEach { (id, label) ->
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Text(label, style = MaterialTheme.typography.bodyLarge)
+                    Switch(
+                        checked = id in preferences.visibleProviders,
+                        onCheckedChange = { onProviderVisibilityChanged(id, it) },
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun providerUnavailableText(provider: ProviderUsageProvider): String =
+    if (provider.status == ProviderUsageProvider.STATUS_NOT_CONFIGURED) {
+        stringResource(R.string.provider_usage_provider_not_configured)
+    } else {
+        stringResource(R.string.provider_usage_provider_unavailable)
+    }
+
+private fun formatReset(raw: String?, now: Instant): String? = runCatching {
+    val reset = Instant.parse(raw ?: return null)
+    val duration = Duration.between(now, reset)
+    if (duration.isNegative || duration.isZero) return "now"
+    val days = duration.toDays()
+    val hours = duration.toHours() % 24
+    val minutes = duration.toMinutes() % 60
+    when {
+        days > 0 -> "${days}d ${hours}h"
+        hours > 0 -> "${hours}h ${minutes}m"
+        else -> "${minutes}m"
+    }
+}.getOrNull()
+
+private fun formatBalance(balance: ProviderUsageBalance): String = runCatching {
+    NumberFormat.getCurrencyInstance().apply {
+        currency = Currency.getInstance(balance.currency)
+    }.format(balance.amount)
+}.getOrElse { "${balance.amount} ${balance.currency}" }
+
+private fun formatRenewal(raw: String?): String? = runCatching {
+    val instant = Instant.parse(raw ?: return null)
+    DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM)
+        .withLocale(Locale.getDefault())
+        .withZone(ZoneId.systemDefault())
+        .format(instant)
+}.getOrNull()

app/src/main/kotlin/com/hermesandroid/relay/viewmodel/ChatViewModel.kt

@@ -396,6 +396,7 @@ class ChatViewModel : ViewModel() {
 
     private var firstTokenNotified = false
     private var toolHistoryJob: Job? = null
+    private var gatewayComposerSettlementJob: Job? = null
     private var backgroundProcessSessionJob: Job? = null
     private var connectionSwitchJob: Job? = null
     private var sessionRefreshJob: Job? = null
@@ -444,6 +445,7 @@ class ChatViewModel : ViewModel() {
         // === END PHASE3-status ===
         const val MEDIA_TAP_TO_DOWNLOAD = "Tap to download"
         private const val MEDIA_FETCH_TIMEOUT_MS = 120_000L
+        private val WINDOWS_ABSOLUTE_MEDIA_PATH_REGEX = Regex("""^[A-Za-z]:[\\/].+""")
 
         /** Upper bound on the rolling tool-call history flow. */
         const val TOOL_CALL_HISTORY_LIMIT = 10
@@ -3402,6 +3404,8 @@ class ChatViewModel : ViewModel() {
         if (this.chatHandler !== chatHandler) {
             checkpointStatusJob?.cancel()
             checkpointStatusJob = null
+            gatewayComposerSettlementJob?.cancel()
+            gatewayComposerSettlementJob = null
         }
         this.chatHandler = chatHandler
         ensureCheckpointObservers()
@@ -3453,6 +3457,26 @@ class ChatViewModel : ViewModel() {
                 scheduleCheckpointWrite()
             }
         }
+        gatewayComposerSettlementJob?.cancel()
+        gatewayComposerSettlementJob = viewModelScope.launch {
+            chatHandler.messages.collect { messages ->
+                val storedSessionId = chatHandler.currentSessionId.value ?: return@collect
+                val client = gatewayClient ?: return@collect
+                if (
+                    streamingEndpoint == "gateway" &&
+                    chatHandler.isStreaming.value &&
+                    messages.none { it.isStreaming || it.isThinkingStreaming } &&
+                    !client.hasActiveTurnForSession(storedSessionId)
+                ) {
+                    // A terminal bubble with no matching live or detached
+                    // Gateway owner is an orphaned handler-wide busy bit. Clear
+                    // it without disturbing a different session's active turn.
+                    chatHandler.clearStreamingStatus()
+                    _steerableTurn.value = false
+                    _steerNotice.value = null
+                }
+            }
+        }
     }
 
     /**
@@ -5958,6 +5982,13 @@ class ChatViewModel : ViewModel() {
         activeStream?.cancel()
         activeStream = null
         activeStreamIsGateway = false
+        // Navigation owns the visible composer even when the live handle has
+        // already ended or could not be detached. Do not wait for a late
+        // cancel callback to clear a handler-wide busy bit after the new
+        // transcript has replaced its streaming bubble.
+        handler.clearStreamingStatus()
+        _steerableTurn.value = false
+        _steerNotice.value = null
     }
 
     /** Last-chance synchronous flush before the ViewModel scope is cancelled. */
@@ -8804,6 +8835,11 @@ class ChatViewModel : ViewModel() {
             if (streamingMsg != null) {
                 handler.markStopped(streamingMsg.id)
                 handler.onStreamComplete(streamingMsg.id)
+            } else {
+                // The terminal bubble can settle before the handler-wide busy
+                // flag (or navigation can already have cleared the transcript).
+                // Stop must still be an unconditional escape hatch.
+                handler.clearStreamingStatus()
             }
         }
     }
@@ -8890,11 +8926,10 @@ class ChatViewModel : ViewModel() {
      * Re-run the fetch for an attachment that's in the "Tap to download"
      * deferred state. Used by the inbound-media card's CTA on cellular.
      *
-     * Works for both flavors of inbound attachment: if the stored key starts
-     * with `/` it's an absolute path (bare-media form, use
-     * [RelayHttpClient.fetchMediaByPath]); otherwise it's a relay token
-     * (use [RelayHttpClient.fetchMedia]). `secrets.token_urlsafe` never
-     * produces `/` so the prefix check is unambiguous.
+     * Works for both flavors of inbound attachment: POSIX paths start with `/`
+     * and Windows paths match `C:\...`; both use
+     * [RelayHttpClient.fetchMediaByPath]. Everything else is an opaque relay
+     * token and uses [RelayHttpClient.fetchMedia].
      */
     fun manualFetchAttachment(messageId: String, attachmentIndex: Int) {
         val handler = chatHandler ?: return
@@ -8927,7 +8962,10 @@ class ChatViewModel : ViewModel() {
                 settings,
                 expectedRole = expectedRole,
             ) {
-                if (fetchKey.startsWith("/")) {
+                if (
+                    fetchKey.startsWith("/") ||
+                    WINDOWS_ABSOLUTE_MEDIA_PATH_REGEX.matches(fetchKey)
+                ) {
                     relay.fetchMediaByPath(fetchKey)
                 } else {
                     relay.fetchMedia(fetchKey)
@@ -9022,9 +9060,9 @@ class ChatViewModel : ViewModel() {
             },
             content = "",
             state = AttachmentState.LOADING,
-            // Reuse relayToken as a generic inbound-fetch key. Paths always
-            // start with `/`, real tokens never do — downstream helpers
-            // that need to distinguish can check the prefix.
+            // Reuse relayToken as a generic inbound-fetch key. Downstream
+            // helpers distinguish POSIX or Windows absolute paths from opaque
+            // relay tokens.
             relayToken = originalPath,
             fileName = originalPath.substringAfterLast('/').substringAfterLast('\\').ifBlank { null }
         )

app/src/main/res/values-b+pt+BR/strings.xml

@@ -3881,7 +3881,7 @@
     <string name="appearance_preview_voice">Voz</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 tokens  ·  137,2 mil</string>
     <string name="appearance_preview_message_placeholder">Mensagem…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / perfil: padrão</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / perfil: padrão</string>
     <string name="appearance_preview_live_note">Esta prévia é atualizada imediatamente com a predefinição, o modo, a fonte e a aparência da Sphere.</string>
     <string name="appearance_customize_theme">Personalizar %1$s</string>
     <string name="appearance_accent_preset">Cor de destaque predefinida</string>
@@ -4136,6 +4136,45 @@
     <string name="bridge_timed_unlimited_warning">Sem limite de inatividade. O acesso continua após inatividade e reconexão até ser encerrado, a chave mestra ser desligada ou a política mudar. Ideal para um dispositivo dedicado.</string>
     <string name="bss_screen_access_off_desc">O acesso à tela está desligado. Novo acesso finito usa %1$d minutos ocioso por padrão.</string>
     <string name="bss_screen_access_unlimited_desc">Pelo menos um recurso de tela permanece ativo até ser desligado explicitamente.</string>
+    <string name="provider_usage_title">Uso e limites</string>
+    <string name="provider_usage_back">Voltar</string>
+    <string name="provider_usage_refresh">Atualizar uso</string>
+    <string name="provider_usage_intro">Limites de conta dos provedores configurados nesta conexão do Hermes.</string>
+    <string name="provider_usage_not_available">Esta conexão Hermes não expõe o uso dos provedores. Atualize o Hermes ou instale/atualize o plugin Relay.</string>
+    <string name="provider_usage_none_configured">Nenhum provedor visível tem dados de uso da conta disponíveis.</string>
+    <string name="provider_usage_loading">Carregando uso dos provedores…</string>
+    <string name="provider_usage_error">Não foi possível carregar o uso dos provedores.</string>
+    <string name="provider_usage_retry">Tentar novamente</string>
+    <string name="provider_usage_percent">%1$d%% usado</string>
+    <string name="provider_usage_resets">Redefine em %1$s</string>
+    <string name="provider_usage_display_title">Exibição nas Configurações</string>
+    <string name="provider_usage_display_desc">Escolha como o uso da conta aparece na tela principal de Configurações.</string>
+    <string name="provider_usage_mode_summary">Resumo</string>
+    <string name="provider_usage_mode_expanded">Expandido</string>
+    <string name="provider_usage_mode_hidden">Oculto</string>
+    <string name="provider_usage_providers_title">Mostrar nas Configurações principais</string>
+    <string name="provider_usage_providers_desc">Escolha quais cartões de provedores aparecem nas Configurações principais. Todos continuam visíveis aqui.</string>
+    <string name="provider_usage_settings_desc">Uso da conta e limites dos provedores</string>
+    <string name="provider_usage_settings_desc_relay">Uso e limites ampliados pelo plugin Relay</string>
+    <string name="provider_usage_settings_desc_basic">Uso básico do Hermes · Relay adiciona pools e mais</string>
+    <string name="provider_usage_customize">Exibição</string>
+    <string name="provider_usage_hidden_hint">Os cartões de uso estão ocultos nas Configurações.</string>
+    <string name="provider_usage_not_available_compact">O uso dos provedores está indisponível. Atualize o Hermes ou o plugin Relay.</string>
+    <string name="provider_usage_provider_not_configured">Não configurado neste host</string>
+    <string name="provider_usage_provider_unavailable">Uso temporariamente indisponível</string>
+    <string name="provider_usage_active_unknown">Esta sessão ainda não tem uma credencial ativa.</string>
+    <string name="provider_usage_active_available">Ativa · Disponível</string>
+    <string name="provider_usage_active_at_limit">Ativa · Limite atingido</string>
+    <string name="provider_usage_active">Ativa</string>
+    <string name="provider_usage_available">Disponível</string>
+    <string name="provider_usage_at_limit">Limite atingido</string>
+    <string name="provider_usage_unavailable_status">Indisponível</string>
+    <string name="provider_usage_renews_on">Renova em %1$s</string>
+    <string name="provider_usage_manage_credits">Gerenciar créditos</string>
+    <string name="provider_usage_capability_relay_title">Ampliado pelo plugin Relay</string>
+    <string name="provider_usage_capability_relay_body">Pools de credenciais, saldos estruturados da Nous e OpenCode Go são fornecidos pelo plugin Relay.</string>
+    <string name="provider_usage_capability_basic_title">Uso básico do Hermes</string>
+    <string name="provider_usage_capability_basic_body">Instale ou atualize o plugin Relay para pools de credenciais, saldos estruturados da Nous e OpenCode Go.</string>
     <string name="custom_theme_title">Personalizado</string>
     <string name="custom_theme_entry_summary">Crie e salve seus próprios temas</string>
     <string name="custom_theme_your_presets">Seus temas</string>

app/src/main/res/values-b+zh+Hans/strings.xml

@@ -3969,7 +3969,7 @@
     <string name="appearance_preview_voice">语音</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 个 token  ·  137.2K</string>
     <string name="appearance_preview_message_placeholder">消息…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / 配置文件：默认</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / 配置文件：默认</string>
     <string name="appearance_preview_live_note">更改预设、模式、字体或 Sphere 皮肤后，此预览会立即更新。</string>
     <string name="appearance_customize_theme">自定义 %1$s</string>
     <string name="appearance_accent_preset">预设强调色</string>
@@ -4221,6 +4221,45 @@
     <string name="bridge_timed_unlimited_warning">无空闲超时。屏幕访问在空闲和重新连接后仍保持，直到结束访问、关闭主开关或更改策略。适合专用设备。</string>
     <string name="bss_screen_access_off_desc">屏幕访问已关闭。新的有限访问默认使用 %1$d 分钟空闲限制。</string>
     <string name="bss_screen_access_unlimited_desc">至少一项屏幕功能会保持有效，直到明确关闭。</string>
+    <string name="provider_usage_title">用量和限额</string>
+    <string name="provider_usage_back">返回</string>
+    <string name="provider_usage_refresh">刷新用量</string>
+    <string name="provider_usage_intro">此 Hermes 连接中已配置提供商的账户限额。</string>
+    <string name="provider_usage_not_available">此 Hermes 连接未提供服务商用量。请更新 Hermes，或安装／更新 Relay 插件。</string>
+    <string name="provider_usage_none_configured">当前显示的提供商均无可用账户用量。</string>
+    <string name="provider_usage_loading">正在加载提供商用量…</string>
+    <string name="provider_usage_error">无法加载提供商用量。</string>
+    <string name="provider_usage_retry">重试</string>
+    <string name="provider_usage_percent">已使用 %1$d%%</string>
+    <string name="provider_usage_resets">%1$s后重置</string>
+    <string name="provider_usage_display_title">设置页显示</string>
+    <string name="provider_usage_display_desc">选择账户用量在主设置屏幕中的显示方式。</string>
+    <string name="provider_usage_mode_summary">摘要</string>
+    <string name="provider_usage_mode_expanded">展开</string>
+    <string name="provider_usage_mode_hidden">隐藏</string>
+    <string name="provider_usage_providers_title">在主设置页显示</string>
+    <string name="provider_usage_providers_desc">选择要在主设置页显示的提供商卡片。此处仍会显示所有提供商。</string>
+    <string name="provider_usage_settings_desc">账户用量和提供商限额</string>
+    <string name="provider_usage_settings_desc_relay">由 Relay 插件增强的用量和限额</string>
+    <string name="provider_usage_settings_desc_basic">Hermes 基础用量 · Relay 可增加凭据池等功能</string>
+    <string name="provider_usage_customize">显示</string>
+    <string name="provider_usage_hidden_hint">设置页已隐藏用量卡片。</string>
+    <string name="provider_usage_not_available_compact">服务商用量不可用。请更新 Hermes 或 Relay 插件。</string>
+    <string name="provider_usage_provider_not_configured">此主机未配置</string>
+    <string name="provider_usage_provider_unavailable">用量暂时不可用</string>
+    <string name="provider_usage_active_unknown">此会话尚无当前凭据。</string>
+    <string name="provider_usage_active_available">当前 · 可用</string>
+    <string name="provider_usage_active_at_limit">当前 · 已达上限</string>
+    <string name="provider_usage_active">当前</string>
+    <string name="provider_usage_available">可用</string>
+    <string name="provider_usage_at_limit">已达上限</string>
+    <string name="provider_usage_unavailable_status">不可用</string>
+    <string name="provider_usage_renews_on">续期日期：%1$s</string>
+    <string name="provider_usage_manage_credits">管理额度</string>
+    <string name="provider_usage_capability_relay_title">已由 Relay 插件增强</string>
+    <string name="provider_usage_capability_relay_body">凭据池、结构化 Nous 余额和 OpenCode Go 由 Relay 插件提供。</string>
+    <string name="provider_usage_capability_basic_title">Hermes 基础用量</string>
+    <string name="provider_usage_capability_basic_body">安装或更新 Relay 插件即可使用凭据池、结构化 Nous 余额和 OpenCode Go。</string>
     <string name="custom_theme_title">自定义</string>
     <string name="custom_theme_entry_summary">创建并保存自己的主题</string>
     <string name="custom_theme_your_presets">你的预设</string>

app/src/main/res/values-de/strings.xml

@@ -4041,7 +4041,7 @@
     <string name="appearance_preview_voice">Sprache</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 Token  ·  137,2K</string>
     <string name="appearance_preview_message_placeholder">Nachricht…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / Profil: Standard</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / Profil: Standard</string>
     <string name="appearance_preview_live_note">Diese Vorschau wird sofort mit Vorlage, Modus, Schrift und Sphere-Skin aktualisiert.</string>
     <string name="appearance_customize_theme">%1$s anpassen</string>
     <string name="appearance_accent_preset">Voreingestellte Akzentfarbe</string>
@@ -4296,6 +4296,45 @@
     <string name="bridge_timed_unlimited_warning">Kein Leerlaufzeitlimit. Bildschirmzugriff bleibt bei Inaktivität und Wiederverbindung aktiv, bis er beendet, der Hauptschalter deaktiviert oder die Richtlinie geändert wird. Für ein dediziertes Gerät.</string>
     <string name="bss_screen_access_off_desc">Bildschirmzugriff ist aus. Neuer begrenzter Zugriff verwendet standardmäßig %1$d Minuten Leerlauf.</string>
     <string name="bss_screen_access_unlimited_desc">Mindestens eine Bildschirmfunktion bleibt bis zum ausdrücklichen Ausschalten aktiv.</string>
+    <string name="provider_usage_title">Nutzung &amp; Limits</string>
+    <string name="provider_usage_back">Zurück</string>
+    <string name="provider_usage_refresh">Nutzung aktualisieren</string>
+    <string name="provider_usage_intro">Kontolimits der Anbieter, die für diese Hermes-Verbindung konfiguriert sind.</string>
+    <string name="provider_usage_not_available">Diese Hermes-Verbindung stellt keine Anbieternutzung bereit. Aktualisieren Sie Hermes oder installieren/aktualisieren Sie das Relay-Plugin.</string>
+    <string name="provider_usage_none_configured">Für keinen sichtbaren Anbieter sind Kontonutzungsdaten verfügbar.</string>
+    <string name="provider_usage_loading">Anbieternutzung wird geladen…</string>
+    <string name="provider_usage_error">Anbieternutzung konnte nicht geladen werden.</string>
+    <string name="provider_usage_retry">Erneut versuchen</string>
+    <string name="provider_usage_percent">%1$d%% verwendet</string>
+    <string name="provider_usage_resets">Zurücksetzung in %1$s</string>
+    <string name="provider_usage_display_title">Anzeige in Einstellungen</string>
+    <string name="provider_usage_display_desc">Wählen Sie, wie die Kontonutzung in den Haupteinstellungen erscheint.</string>
+    <string name="provider_usage_mode_summary">Übersicht</string>
+    <string name="provider_usage_mode_expanded">Erweitert</string>
+    <string name="provider_usage_mode_hidden">Ausgeblendet</string>
+    <string name="provider_usage_providers_title">In den Haupteinstellungen anzeigen</string>
+    <string name="provider_usage_providers_desc">Wählen Sie, welche Anbieterkarten in den Haupteinstellungen erscheinen. Hier bleiben alle Anbieter sichtbar.</string>
+    <string name="provider_usage_settings_desc">Kontonutzung und Anbieterlimits</string>
+    <string name="provider_usage_settings_desc_relay">Durch Relay-Plugin erweiterte Nutzung und Limits</string>
+    <string name="provider_usage_settings_desc_basic">Hermes-Basisnutzung · Relay-Plugin ergänzt Pools und mehr</string>
+    <string name="provider_usage_customize">Anzeige</string>
+    <string name="provider_usage_hidden_hint">Nutzungskarten sind in den Einstellungen ausgeblendet.</string>
+    <string name="provider_usage_not_available_compact">Anbieternutzung ist nicht verfügbar. Aktualisieren Sie Hermes oder das Relay-Plugin.</string>
+    <string name="provider_usage_provider_not_configured">Auf diesem Host nicht konfiguriert</string>
+    <string name="provider_usage_provider_unavailable">Nutzung ist vorübergehend nicht verfügbar</string>
+    <string name="provider_usage_active_unknown">Für diese Sitzung gibt es noch keine aktiven Anmeldedaten.</string>
+    <string name="provider_usage_active_available">Aktiv · Verfügbar</string>
+    <string name="provider_usage_active_at_limit">Aktiv · Limit erreicht</string>
+    <string name="provider_usage_active">Aktiv</string>
+    <string name="provider_usage_available">Verfügbar</string>
+    <string name="provider_usage_at_limit">Limit erreicht</string>
+    <string name="provider_usage_unavailable_status">Nicht verfügbar</string>
+    <string name="provider_usage_renews_on">Verlängert sich am %1$s</string>
+    <string name="provider_usage_manage_credits">Guthaben verwalten</string>
+    <string name="provider_usage_capability_relay_title">Durch Relay-Plugin erweitert</string>
+    <string name="provider_usage_capability_relay_body">Anmeldedaten-Pools, strukturierte Nous-Guthaben und OpenCode Go werden vom Relay-Plugin bereitgestellt.</string>
+    <string name="provider_usage_capability_basic_title">Basisnutzung von Hermes</string>
+    <string name="provider_usage_capability_basic_body">Installieren oder aktualisieren Sie das Relay-Plugin für Anmeldedaten-Pools, strukturierte Nous-Guthaben und OpenCode Go.</string>
     <string name="custom_theme_title">Benutzerdefiniert</string>
     <string name="custom_theme_entry_summary">Eigene Themes erstellen und speichern</string>
     <string name="custom_theme_your_presets">Deine Presets</string>

app/src/main/res/values-es/strings.xml

@@ -3726,7 +3726,7 @@
     <string name="appearance_preview_voice">Voz</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 tokens  ·  137,2K</string>
     <string name="appearance_preview_message_placeholder">Mensaje…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / perfil: predeterminado</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / perfil: predeterminado</string>
     <string name="appearance_preview_live_note">Esta vista previa se actualiza al instante con el ajuste, modo, fuente y aspecto de Sphere.</string>
     <string name="appearance_customize_theme">Personalizar %1$s</string>
     <string name="appearance_accent_preset">Color de acento predefinido</string>
@@ -3981,6 +3981,45 @@
     <string name="bridge_timed_unlimited_warning">Sin límite de inactividad. El acceso continúa tras inactividad y reconexión hasta finalizarlo, desactivar el interruptor maestro o cambiar la política. Ideal para un dispositivo dedicado.</string>
     <string name="bss_screen_access_off_desc">El acceso a pantalla está desactivado. El acceso finito nuevo usa %1$d minutos de inactividad por defecto.</string>
     <string name="bss_screen_access_unlimited_desc">Al menos una capacidad de pantalla permanece activa hasta desactivarla explícitamente.</string>
+    <string name="provider_usage_title">Uso y límites</string>
+    <string name="provider_usage_back">Atrás</string>
+    <string name="provider_usage_refresh">Actualizar uso</string>
+    <string name="provider_usage_intro">Límites de cuenta de los proveedores configurados en esta conexión de Hermes.</string>
+    <string name="provider_usage_not_available">Esta conexión de Hermes no expone el uso de proveedores. Actualiza Hermes o instala/actualiza el complemento Relay.</string>
+    <string name="provider_usage_none_configured">Ningún proveedor visible tiene datos de uso de cuenta disponibles.</string>
+    <string name="provider_usage_loading">Cargando uso de proveedores…</string>
+    <string name="provider_usage_error">No se pudo cargar el uso de proveedores.</string>
+    <string name="provider_usage_retry">Reintentar</string>
+    <string name="provider_usage_percent">%1$d%% usado</string>
+    <string name="provider_usage_resets">Se restablece en %1$s</string>
+    <string name="provider_usage_display_title">Visualización en Ajustes</string>
+    <string name="provider_usage_display_desc">Elige cómo aparece el uso de cuenta en la pantalla principal de Ajustes.</string>
+    <string name="provider_usage_mode_summary">Resumen</string>
+    <string name="provider_usage_mode_expanded">Ampliado</string>
+    <string name="provider_usage_mode_hidden">Oculto</string>
+    <string name="provider_usage_providers_title">Mostrar en Ajustes principales</string>
+    <string name="provider_usage_providers_desc">Elige qué tarjetas de proveedores aparecen en Ajustes principales. Aquí siempre se muestran todos.</string>
+    <string name="provider_usage_settings_desc">Uso de cuenta y límites de proveedores</string>
+    <string name="provider_usage_settings_desc_relay">Uso y límites ampliados por el complemento Relay</string>
+    <string name="provider_usage_settings_desc_basic">Uso básico de Hermes · Relay añade grupos y más</string>
+    <string name="provider_usage_customize">Visualización</string>
+    <string name="provider_usage_hidden_hint">Las tarjetas de uso están ocultas en Ajustes.</string>
+    <string name="provider_usage_not_available_compact">El uso de proveedores no está disponible. Actualiza Hermes o el complemento Relay.</string>
+    <string name="provider_usage_provider_not_configured">No configurado en este host</string>
+    <string name="provider_usage_provider_unavailable">El uso no está disponible temporalmente</string>
+    <string name="provider_usage_active_unknown">Esta sesión aún no tiene una credencial activa.</string>
+    <string name="provider_usage_active_available">Activa · Disponible</string>
+    <string name="provider_usage_active_at_limit">Activa · Límite alcanzado</string>
+    <string name="provider_usage_active">Activa</string>
+    <string name="provider_usage_available">Disponible</string>
+    <string name="provider_usage_at_limit">Límite alcanzado</string>
+    <string name="provider_usage_unavailable_status">No disponible</string>
+    <string name="provider_usage_renews_on">Se renueva el %1$s</string>
+    <string name="provider_usage_manage_credits">Gestionar créditos</string>
+    <string name="provider_usage_capability_relay_title">Ampliado por el complemento Relay</string>
+    <string name="provider_usage_capability_relay_body">Los grupos de credenciales, los saldos estructurados de Nous y OpenCode Go los proporciona el complemento Relay.</string>
+    <string name="provider_usage_capability_basic_title">Uso básico de Hermes</string>
+    <string name="provider_usage_capability_basic_body">Instala o actualiza el complemento Relay para obtener grupos de credenciales, saldos estructurados de Nous y OpenCode Go.</string>
     <string name="custom_theme_title">Personalizado</string>
     <string name="custom_theme_entry_summary">Crea y guarda tus propios temas</string>
     <string name="custom_theme_your_presets">Tus preajustes</string>

app/src/main/res/values-ja/strings.xml

@@ -4040,7 +4040,7 @@
     <string name="appearance_preview_voice">音声</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206トークン  ·  137.2K</string>
     <string name="appearance_preview_message_placeholder">メッセージ…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / プロファイル: デフォルト</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / プロファイル: デフォルト</string>
     <string name="appearance_preview_live_note">このプレビューには、プリセット、モード、フォント、Sphereスキンの変更がすぐに反映されます。</string>
     <string name="appearance_customize_theme">%1$sをカスタマイズ</string>
     <string name="appearance_accent_preset">プリセットのアクセント</string>
@@ -4294,6 +4294,45 @@
     <string name="bridge_timed_unlimited_warning">アイドルタイムアウトはありません。終了、マスター無効化、またはポリシー変更まで、非操作時や再接続後も画面アクセスが続きます。専用端末向けです。</string>
     <string name="bss_screen_access_off_desc">画面アクセスはオフです。新しい有限アクセスの既定アイドル制限は %1$d 分です。</string>
     <string name="bss_screen_access_unlimited_desc">少なくとも 1 つの画面機能が明示的にオフにするまで有効です。</string>
+    <string name="provider_usage_title">使用量と上限</string>
+    <string name="provider_usage_back">戻る</string>
+    <string name="provider_usage_refresh">使用量を更新</string>
+    <string name="provider_usage_intro">この Hermes 接続に設定されたプロバイダーのアカウント上限です。</string>
+    <string name="provider_usage_not_available">この Hermes 接続はプロバイダー使用量を公開していません。Hermes を更新するか、Relay プラグインをインストール／更新してください。</string>
+    <string name="provider_usage_none_configured">表示中のプロバイダーに利用可能なアカウント使用量がありません。</string>
+    <string name="provider_usage_loading">プロバイダー使用量を読み込み中…</string>
+    <string name="provider_usage_error">プロバイダー使用量を読み込めませんでした。</string>
+    <string name="provider_usage_retry">再試行</string>
+    <string name="provider_usage_percent">%1$d%% 使用済み</string>
+    <string name="provider_usage_resets">%1$s後にリセット</string>
+    <string name="provider_usage_display_title">設定での表示</string>
+    <string name="provider_usage_display_desc">メインの設定画面にアカウント使用量を表示する方法を選びます。</string>
+    <string name="provider_usage_mode_summary">概要</string>
+    <string name="provider_usage_mode_expanded">展開</string>
+    <string name="provider_usage_mode_hidden">非表示</string>
+    <string name="provider_usage_providers_title">メイン設定に表示</string>
+    <string name="provider_usage_providers_desc">メイン設定に表示するプロバイダーカードを選びます。ここではすべて表示されます。</string>
+    <string name="provider_usage_settings_desc">アカウント使用量とプロバイダー上限</string>
+    <string name="provider_usage_settings_desc_relay">Relay プラグインで拡張された使用量と上限</string>
+    <string name="provider_usage_settings_desc_basic">Hermes の基本使用量 · Relay でプールなどを追加</string>
+    <string name="provider_usage_customize">表示</string>
+    <string name="provider_usage_hidden_hint">設定では使用量カードが非表示です。</string>
+    <string name="provider_usage_not_available_compact">プロバイダー使用量を利用できません。Hermes または Relay プラグインを更新してください。</string>
+    <string name="provider_usage_provider_not_configured">このホストでは未設定です</string>
+    <string name="provider_usage_provider_unavailable">使用量は一時的に利用できません</string>
+    <string name="provider_usage_active_unknown">このセッションにはまだ使用中の認証情報がありません。</string>
+    <string name="provider_usage_active_available">使用中 · 利用可能</string>
+    <string name="provider_usage_active_at_limit">使用中 · 上限到達</string>
+    <string name="provider_usage_active">使用中</string>
+    <string name="provider_usage_available">利用可能</string>
+    <string name="provider_usage_at_limit">上限到達</string>
+    <string name="provider_usage_unavailable_status">利用不可</string>
+    <string name="provider_usage_renews_on">%1$s に更新</string>
+    <string name="provider_usage_manage_credits">クレジットを管理</string>
+    <string name="provider_usage_capability_relay_title">Relay プラグインで拡張</string>
+    <string name="provider_usage_capability_relay_body">認証情報プール、構造化された Nous 残高、OpenCode Go は Relay プラグインによって提供されます。</string>
+    <string name="provider_usage_capability_basic_title">Hermes の基本使用量</string>
+    <string name="provider_usage_capability_basic_body">認証情報プール、構造化された Nous 残高、OpenCode Go を利用するには Relay プラグインをインストールまたは更新してください。</string>
     <string name="custom_theme_title">カスタム</string>
     <string name="custom_theme_entry_summary">独自のテーマを作成して保存します</string>
     <string name="custom_theme_your_presets">保存したテーマ</string>

app/src/main/res/values-ru/strings.xml

@@ -3762,7 +3762,7 @@
     <string name="appearance_preview_voice">Голос</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 токенов  ·  137,2 тыс.</string>
     <string name="appearance_preview_message_placeholder">Сообщение…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / профиль: по умолчанию</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / профиль: по умолчанию</string>
     <string name="appearance_preview_live_note">Предпросмотр сразу обновляется при изменении шаблона, режима, шрифта и оформления Sphere.</string>
     <string name="appearance_customize_theme">Настроить %1$s</string>
     <string name="appearance_accent_preset">Предустановленный акцент</string>
@@ -4023,6 +4023,45 @@
     <string name="bridge_timed_unlimited_warning">Без тайм-аута. Доступ сохраняется при бездействии и переподключении, пока не завершен, не выключен главный переключатель или не изменена политика. Для выделенного устройства.</string>
     <string name="bss_screen_access_off_desc">Доступ к экрану выключен. Новый ограниченный доступ по умолчанию использует %1$d минут бездействия.</string>
     <string name="bss_screen_access_unlimited_desc">Хотя бы одна экранная возможность активна до явного отключения.</string>
+    <string name="provider_usage_title">Использование и лимиты</string>
+    <string name="provider_usage_back">Назад</string>
+    <string name="provider_usage_refresh">Обновить использование</string>
+    <string name="provider_usage_intro">Лимиты учётных записей поставщиков, настроенных для этого подключения Hermes.</string>
+    <string name="provider_usage_not_available">Это подключение Hermes не предоставляет данные поставщиков. Обновите Hermes или установите/обновите плагин Relay.</string>
+    <string name="provider_usage_none_configured">Ни у одного видимого поставщика нет доступных данных об использовании.</string>
+    <string name="provider_usage_loading">Загрузка данных поставщиков…</string>
+    <string name="provider_usage_error">Не удалось загрузить данные поставщиков.</string>
+    <string name="provider_usage_retry">Повторить</string>
+    <string name="provider_usage_percent">Использовано %1$d%%</string>
+    <string name="provider_usage_resets">Сброс через %1$s</string>
+    <string name="provider_usage_display_title">Отображение в настройках</string>
+    <string name="provider_usage_display_desc">Выберите, как использование учётной записи отображается на главном экране настроек.</string>
+    <string name="provider_usage_mode_summary">Сводка</string>
+    <string name="provider_usage_mode_expanded">Развёрнуто</string>
+    <string name="provider_usage_mode_hidden">Скрыто</string>
+    <string name="provider_usage_providers_title">Показывать в основных настройках</string>
+    <string name="provider_usage_providers_desc">Выберите карточки поставщиков для главного экрана настроек. Здесь всегда видны все поставщики.</string>
+    <string name="provider_usage_settings_desc">Использование учётной записи и лимиты поставщиков</string>
+    <string name="provider_usage_settings_desc_relay">Расширенные данные и лимиты от плагина Relay</string>
+    <string name="provider_usage_settings_desc_basic">Базовые данные Hermes · Relay добавляет пулы и другое</string>
+    <string name="provider_usage_customize">Отображение</string>
+    <string name="provider_usage_hidden_hint">Карточки использования скрыты в настройках.</string>
+    <string name="provider_usage_not_available_compact">Данные поставщиков недоступны. Обновите Hermes или плагин Relay.</string>
+    <string name="provider_usage_provider_not_configured">Не настроено на этом хосте</string>
+    <string name="provider_usage_provider_unavailable">Данные временно недоступны</string>
+    <string name="provider_usage_active_unknown">Для этого сеанса ещё нет активных учётных данных.</string>
+    <string name="provider_usage_active_available">Активно · Доступно</string>
+    <string name="provider_usage_active_at_limit">Активно · Лимит исчерпан</string>
+    <string name="provider_usage_active">Активно</string>
+    <string name="provider_usage_available">Доступно</string>
+    <string name="provider_usage_at_limit">Лимит исчерпан</string>
+    <string name="provider_usage_unavailable_status">Недоступно</string>
+    <string name="provider_usage_renews_on">Продление: %1$s</string>
+    <string name="provider_usage_manage_credits">Управление кредитами</string>
+    <string name="provider_usage_capability_relay_title">Расширено плагином Relay</string>
+    <string name="provider_usage_capability_relay_body">Пулы учётных данных, структурированные балансы Nous и OpenCode Go предоставляются плагином Relay.</string>
+    <string name="provider_usage_capability_basic_title">Базовые данные Hermes</string>
+    <string name="provider_usage_capability_basic_body">Установите или обновите плагин Relay для пулов учётных данных, структурированных балансов Nous и OpenCode Go.</string>
     <string name="custom_theme_title">Своя тема</string>
     <string name="custom_theme_entry_summary">Создавайте и сохраняйте собственные темы</string>
     <string name="custom_theme_your_presets">Ваши темы</string>

app/src/main/res/values/strings.xml

@@ -1306,7 +1306,7 @@
     <string name="appearance_preview_voice">Voice</string>
     <string name="appearance_preview_tool_meta">tool_executor  ·  206 tokens  ·  137.2K</string>
     <string name="appearance_preview_message_placeholder">Message…</string>
-    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.5 / profile: default</string>
+    <string name="appearance_preview_gateway">Gateway   ·   LAN   ·   gpt-5.6-sol / profile: default</string>
     <string name="appearance_preview_live_note">This preview updates immediately with your preset, mode, font, and sphere skin.</string>
     <string name="appearance_back">Back</string>
     <string name="appearance_remove_pet_title">Remove pet?</string>
@@ -4339,4 +4339,43 @@
     <string name="bridge_timed_allow">Allow access</string>
     <string name="bridge_timed_end_now">End now</string>
     <string name="bridge_timed_ended_snackbar">Screen access ended. Permanent grants are still available.</string>
+    <string name="provider_usage_title">Usage &amp; limits</string>
+    <string name="provider_usage_back">Back</string>
+    <string name="provider_usage_refresh">Refresh usage</string>
+    <string name="provider_usage_intro">Account limits from providers configured on this Hermes connection.</string>
+    <string name="provider_usage_not_available">This Hermes connection does not expose provider usage. Update Hermes or install/update the Relay plugin to enable it.</string>
+    <string name="provider_usage_none_configured">No visible provider has account usage available.</string>
+    <string name="provider_usage_loading">Loading provider usage…</string>
+    <string name="provider_usage_error">Couldn\'t load provider usage.</string>
+    <string name="provider_usage_retry">Retry</string>
+    <string name="provider_usage_percent">%1$d%% used</string>
+    <string name="provider_usage_resets">Resets in %1$s</string>
+    <string name="provider_usage_display_title">Settings display</string>
+    <string name="provider_usage_display_desc">Choose how account usage appears on the main Settings screen.</string>
+    <string name="provider_usage_mode_summary">Summary</string>
+    <string name="provider_usage_mode_expanded">Expanded</string>
+    <string name="provider_usage_mode_hidden">Hidden</string>
+    <string name="provider_usage_providers_title">Show on main Settings</string>
+    <string name="provider_usage_providers_desc">Choose which provider cards appear on the main Settings page. All providers remain visible here.</string>
+    <string name="provider_usage_settings_desc">Account usage and provider limits</string>
+    <string name="provider_usage_settings_desc_relay">Relay plugin enhanced usage and limits</string>
+    <string name="provider_usage_settings_desc_basic">Basic Hermes usage · Relay plugin adds pools and more</string>
+    <string name="provider_usage_customize">Display</string>
+    <string name="provider_usage_hidden_hint">Usage cards are hidden on Settings.</string>
+    <string name="provider_usage_not_available_compact">Provider usage is unavailable. Update Hermes or install/update the Relay plugin.</string>
+    <string name="provider_usage_provider_not_configured">Not configured on this host</string>
+    <string name="provider_usage_provider_unavailable">Usage is temporarily unavailable</string>
+    <string name="provider_usage_active_unknown">No active credential yet for this session.</string>
+    <string name="provider_usage_active_available">Active · Available</string>
+    <string name="provider_usage_active_at_limit">Active · At limit</string>
+    <string name="provider_usage_active">Active</string>
+    <string name="provider_usage_available">Available</string>
+    <string name="provider_usage_at_limit">At limit</string>
+    <string name="provider_usage_unavailable_status">Unavailable</string>
+    <string name="provider_usage_renews_on">Renews %1$s</string>
+    <string name="provider_usage_manage_credits">Manage credits</string>
+    <string name="provider_usage_capability_relay_title">Relay plugin enhanced</string>
+    <string name="provider_usage_capability_relay_body">Credential pools, structured Nous balances, and OpenCode Go are provided by the Relay plugin.</string>
+    <string name="provider_usage_capability_basic_title">Basic usage from Hermes</string>
+    <string name="provider_usage_capability_basic_body">Install or update the Relay plugin for credential pools, structured Nous balances, and OpenCode Go.</string>
 </resources>

app/src/test/kotlin/com/hermesandroid/relay/data/ProviderUsagePreferencesTest.kt

@@ -0,0 +1,69 @@
+package com.hermesandroid.relay.data
+
+import androidx.datastore.preferences.core.PreferenceDataStoreFactory
+import java.io.File
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.test.runTest
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+
+class ProviderUsagePreferencesTest {
+    @get:Rule
+    val tempFolder = TemporaryFolder()
+
+    private lateinit var file: File
+    private lateinit var scope: CoroutineScope
+    private lateinit var repository: ProviderUsagePreferencesRepository
+
+    @Before
+    fun setUp() {
+        file = tempFolder.newFile("provider_usage.preferences_pb").also { it.delete() }
+        scope = CoroutineScope(Dispatchers.IO + Job())
+        repository = ProviderUsagePreferencesRepository(
+            PreferenceDataStoreFactory.create(scope = scope, produceFile = { file }),
+        )
+    }
+
+    @After
+    fun tearDown() {
+        scope.cancel()
+    }
+
+    @Test
+    fun defaultsToSummaryWithSupportedProvidersVisible() = runTest {
+        val preferences = repository.preferences.first()
+        assertEquals(ProviderUsageLandingMode.Summary, preferences.landingMode)
+        assertEquals(
+            setOf("openai-codex", "nous", "opencode-go"),
+            preferences.visibleProviders,
+        )
+    }
+
+    @Test
+    fun persistsDisplayMode() = runTest {
+        repository.setLandingMode(ProviderUsageLandingMode.Expanded)
+
+        val preferences = repository.preferences.first()
+        assertEquals(ProviderUsageLandingMode.Expanded, preferences.landingMode)
+    }
+
+    @Test
+    fun persistsIndependentProviderVisibility() = runTest {
+        repository.setProviderVisible("nous", false)
+
+        val preferences = repository.preferences.first()
+        assertFalse("nous" in preferences.visibleProviders)
+        assertTrue("openai-codex" in preferences.visibleProviders)
+        assertTrue("opencode-go" in preferences.visibleProviders)
+    }
+}

app/src/test/kotlin/com/hermesandroid/relay/network/relay/RelayHttpClientProviderUsageTest.kt

@@ -0,0 +1,99 @@
+package com.hermesandroid.relay.network.relay
+
+import kotlinx.coroutines.test.runTest
+import okhttp3.OkHttpClient
+import okhttp3.mockwebserver.MockResponse
+import okhttp3.mockwebserver.MockWebServer
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+
+class RelayHttpClientProviderUsageTest {
+    private lateinit var server: MockWebServer
+
+    @Before
+    fun setUp() {
+        server = MockWebServer()
+        server.start()
+    }
+
+    @After
+    fun tearDown() {
+        server.shutdown()
+    }
+
+    @Test
+    fun parsesProviderNeutralPayloadAndAuthenticates() = runTest {
+        server.enqueue(
+            MockResponse().setResponseCode(200).setBody(
+                """
+                {
+                  "schema_version": 2,
+                  "capabilities": ["credential_pools", "structured_balances", "opencode_go"],
+                  "providers": [
+                    {
+                      "id": "openai-codex",
+                      "display_name": "Codex",
+                      "status": "available",
+                      "plan": "Plus",
+                      "active_credential_id": "abc123",
+                      "active_credential_state": "known",
+                      "credentials": [{
+                        "id": "abc123",
+                        "label": "Work",
+                        "active": true,
+                        "status": "available",
+                        "windows": []
+                      }],
+                      "windows": [{
+                        "id": "session",
+                        "label": "Session",
+                        "used_percent": 42.5,
+                        "reset_at": "2026-08-22T00:00:00Z"
+                      }]
+                    }
+                  ]
+                }
+                """.trimIndent(),
+            ),
+        )
+
+        val response = client(token = "paired-token")
+            .fetchProviderUsage(profile = "victor", sessionId = "session-42")
+            .getOrThrow()!!
+        val request = server.takeRequest()
+
+        assertEquals("/usage/providers?profile=victor&session_id=session-42", request.path)
+        assertEquals("Bearer paired-token", request.getHeader("Authorization"))
+        assertEquals("Codex", response.providers.single().displayName)
+        assertEquals(42.5, response.providers.single().windows.single().usedPercent!!, 0.001)
+        assertEquals("Work", response.providers.single().credentials.single().label)
+        assertTrue(response.providers.single().credentials.single().active)
+        assertTrue(response.relayEnhanced)
+    }
+
+    @Test
+    fun unsupportedHostIsNullSuccess() = runTest {
+        server.enqueue(MockResponse().setResponseCode(404))
+        val response = client(token = "paired-token").fetchProviderUsage()
+        assertTrue(response.isSuccess)
+        assertNull(response.getOrNull())
+    }
+
+    @Test
+    fun unpairedIsUnsupportedAndDoesNotHitServer() = runTest {
+        val response = client(token = null).fetchProviderUsage()
+        assertTrue(response.isSuccess)
+        assertNull(response.getOrNull())
+        assertEquals(0, server.requestCount)
+    }
+
+    private fun client(token: String?) = RelayHttpClient(
+        okHttpClient = OkHttpClient(),
+        relayUrlProvider = { server.url("/").toString() },
+        sessionTokenProvider = { token },
+    )
+}

app/src/test/kotlin/com/hermesandroid/relay/network/upstream/DashboardApiClientTest.kt

@@ -126,6 +126,44 @@ class DashboardApiClientTest {
         assertEquals(listOf("default", "worker"), status.gateways.single().servedProfiles)
     }
 
+    @Test
+    fun getProviderUsage_carriesSessionAndParsesCredentialPool() = runTest {
+        server.enqueue(
+            MockResponse().setHeader("Content-Type", "application/json").setBody(
+                """
+                {
+                  "schema_version": 2,
+                  "capabilities": ["credential_pools", "structured_balances", "opencode_go"],
+                  "providers": [{
+                    "id": "openai-codex",
+                    "display_name": "Codex",
+                    "status": "available",
+                    "active_credential_state": "known",
+                    "credentials": [{
+                      "id": "abc123",
+                      "label": "bailey",
+                      "active": true,
+                      "status": "available"
+                    }]
+                  }]
+                }
+                """.trimIndent(),
+            ),
+        )
+
+        val usage = DashboardApiClient(baseUrl = server.url("/").toString())
+            .getProviderUsage(profile = "victor", sessionId = "session/42")
+            .getOrThrow()!!
+        val request = server.takeRequest().requestUrl!!
+
+        assertEquals("/api/plugins/hermes-relay/provider-usage", request.encodedPath)
+        assertEquals("victor", request.queryParameter("profile"))
+        assertEquals("session/42", request.queryParameter("session_id"))
+        assertEquals("bailey", usage.providers.single().credentials.single().label)
+        assertTrue(usage.providers.single().credentials.single().active)
+        assertTrue(usage.relayEnhanced)
+    }
+
     @Test
     fun getModelOptions_alwaysRequestsUnconfiguredProviders() = runTest {
         // HRUI-022: newer upstream hides unconfigured provider skeleton rows

app/src/test/kotlin/com/hermesandroid/relay/network/usage/ProviderUsageModelsTest.kt

@@ -0,0 +1,26 @@
+package com.hermesandroid.relay.network.usage
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ProviderUsageModelsTest {
+    @Test
+    fun completeRelayCapabilitySetIsEnhanced() {
+        assertTrue(
+            ProviderUsageResponse(
+                capabilities = ProviderUsageResponse.RELAY_ENHANCED_CAPABILITIES,
+            ).relayEnhanced,
+        )
+    }
+
+    @Test
+    fun missingOrPartialCapabilitiesRemainBasic() {
+        assertFalse(ProviderUsageResponse().relayEnhanced)
+        assertFalse(
+            ProviderUsageResponse(
+                capabilities = setOf("credential_pools", "structured_balances"),
+            ).relayEnhanced,
+        )
+    }
+}

app/src/test/kotlin/com/hermesandroid/relay/screenshots/StoreScreenshotTest.kt

@@ -67,6 +67,7 @@ import com.hermesandroid.relay.ui.components.ChatInputPickerControl
 import com.hermesandroid.relay.ui.components.ChatInputTrailing
 import com.hermesandroid.relay.ui.components.ContextMeterBar
 import com.hermesandroid.relay.ui.components.ConversationVoiceDock
+import com.hermesandroid.relay.ui.components.ConnectionStatusBadge
 import com.hermesandroid.relay.ui.components.MessageBubble
 import com.hermesandroid.relay.ui.components.MorphingSphere
 import com.hermesandroid.relay.ui.components.RelayChromeIconButton
@@ -183,6 +184,10 @@ class StoreScreenshotTest {
     }
     @Test fun s11_voice_conversation() {
         compose.mainClock.autoAdvance = false
+        // RelayRefresh is a process-wide compatibility façade. Seed it before
+        // the first composition so this animation-pinned scene cannot inherit
+        // the palette left by a light-theme gallery test that ran earlier.
+        RelayRefresh.activePalette = AppThemes.byId("hermes-relay").paletteFor(dark = true)
         compose.setContent {
             HermesRelayTheme(appThemeId = "hermes-relay", themePreference = "dark") {
                 CompositionLocalProvider(LocalSphereSkin provides SphereRegistry.Adaptive) {
@@ -280,7 +285,9 @@ class StoreScreenshotTest {
         // The earlier frame scrolled past the pet controls and showed only the
         // sphere-skin grid. Frame the independently selected floating companion,
         // its real PetAvatar preview, Petdex/import actions, and tuning controls.
-        compose.onNodeWithText("Browse Petdex").performScrollTo()
+        compose.onNodeWithText(
+            "Scales the pet art, touch target, and safe routing footprint together. Larger pets may skip narrow perches.",
+        ).performScrollTo()
         compose.onRoot().captureRoboImage("build/store-shots/08_appearance.png")
     }
 
@@ -361,8 +368,7 @@ private fun BlendChatScene() = StoreCockpit(contextUsage = 0.06f) {
 }
 
 @Composable
-private fun BlendThread() {
-    val thread = MockChat.blendThread
+private fun BlendThread(thread: List<ChatMessage> = MockChat.blendThread) {
     Column(
         Modifier.fillMaxSize().padding(start = 18.dp, top = 14.dp, end = 18.dp),
         verticalArrangement = Arrangement.spacedBy(4.dp, Alignment.Bottom)
@@ -405,18 +411,40 @@ private fun StoreCockpit(
                 }
             },
             title = {
-                Row(verticalAlignment = Alignment.CenterVertically) {
-                    Surface(Modifier.size(34.dp), shape = CircleShape, color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.6f)) {
-                        Image(painterResource(R.drawable.splash_icon), contentDescription = null, modifier = Modifier.padding(3.dp))
+                Row(
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    // Keep the Hermes logo as the public default agent identity,
+                    // while matching ChatScreen's current live-status treatment.
+                    Box(Modifier.size(40.dp)) {
+                        Surface(
+                            modifier = Modifier.size(40.dp),
+                            shape = CircleShape,
+                            color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.6f),
+                        ) {
+                            Image(
+                                painter = painterResource(R.drawable.splash_icon),
+                                contentDescription = null,
+                                modifier = Modifier.padding(3.dp),
+                            )
+                        }
+                        ConnectionStatusBadge(
+                            isConnected = true,
+                            isConnecting = false,
+                            modifier = Modifier.size(10.dp).align(Alignment.BottomEnd),
+                            size = 10.dp,
+                        )
                     }
-                    Column(Modifier.padding(start = 10.dp)) {
+                    Column {
                         Text("Hermes", style = MaterialTheme.typography.titleMedium, fontWeight = FontWeight.Bold, maxLines = 1, overflow = TextOverflow.Ellipsis)
                         Text("gpt-5.6-sol", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant, maxLines = 1)
                     }
                 }
             },
             actions = {
-                RelayChromeIconButton(Icons.Filled.Bolt, "Approvals off", onClick = {}, tint = RelayRefresh.Amber, borderColor = RelayRefresh.Amber.copy(alpha = 0.5f), modifier = Modifier.padding(end = 4.dp))
+                // The production bolt appears only when approval bypass is
+                // active. The public marketing fixture uses the safe default.
                 RelayChromeIconButton(Icons.Filled.Code, "Terminal", onClick = {}, modifier = Modifier.padding(end = 4.dp))
                 RelayChromeIconButton(Icons.Filled.Tune, "Settings", onClick = {}, modifier = Modifier.padding(end = 4.dp))
                 RelayChromeIconButton(Icons.Filled.MoreVert, "More", onClick = {}, modifier = Modifier.padding(end = 4.dp))
@@ -534,7 +562,10 @@ private fun VoiceConversationScene() = StoreCockpit(
     contextUsage = 0.05f,
     conversationVoiceState = marketingVoiceUiState,
 ) {
-    BlendThread()
+    // The voice dock occupies more vertical space than the standard composer.
+    // Use its shorter one-line lead-in so the frame starts near the context
+    // meter while the final user reply remains fully visible.
+    BlendThread(MockChat.voiceBlendThread)
 }
 
 /** The real sphere renderer pinned to one frame for pixel-identical marketing output. */
@@ -687,9 +718,18 @@ private object MockChat {
         ),
     )
 
-    // A grouped thread for the "Blend" capture: user → two-message assistant
-    // group (avatar once, code block in the first) → user follow-up.
+    // A grouped thread for the "Blend" capture. The short opening exchange
+    // intentionally fills the production conversation viewport so the first
+    // turn begins directly below the context meter instead of leaving a large,
+    // misleading empty band in the canonical marketing frame.
     val blendThread = listOf(
+        ChatMessage(
+            id = "ba0",
+            role = MessageRole.ASSISTANT,
+            content = "I’ll keep cancellation and offline behavior intact. Show me the retry path.",
+            timestamp = 0L,
+            agentName = "Hermes",
+        ),
         ChatMessage(
             id = "bu1",
             role = MessageRole.USER,
@@ -728,6 +768,15 @@ private object MockChat {
             timestamp = 0L,
         ),
     )
+
+    val voiceBlendThread = listOf(
+        ChatMessage(
+            id = "voice-lead",
+            role = MessageRole.USER,
+            content = "Can you review this?",
+            timestamp = 0L,
+        ),
+    ) + blendThread.drop(1)
 }
 
 // ════════════════════════════════════════════════════════════════════════════

app/src/test/kotlin/com/hermesandroid/relay/ui/components/MorphingSphereMotionPolicyTest.kt

@@ -0,0 +1,44 @@
+package com.hermesandroid.relay.ui.components
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class MorphingSphereMotionPolicyTest {
+    @Test
+    fun `visible idle sphere uses lightweight ambient motion`() {
+        assertEquals(
+            SphereMotionMode.AmbientLayer,
+            sphereMotionMode(
+                state = SphereState.Idle,
+                voiceMode = false,
+                motionVisible = true,
+                fixedTime = null,
+                fixedColorPhase = null,
+            ),
+        )
+    }
+
+    @Test
+    fun `hidden or paused idle sphere is still`() {
+        assertEquals(
+            SphereMotionMode.Still,
+            sphereMotionMode(SphereState.Idle, false, false, null, null),
+        )
+        assertEquals(
+            SphereMotionMode.Still,
+            sphereMotionMode(SphereState.Idle, false, true, 0f, 0f),
+        )
+    }
+
+    @Test
+    fun `visible active and voice states keep procedural motion`() {
+        assertEquals(
+            SphereMotionMode.Procedural,
+            sphereMotionMode(SphereState.Thinking, false, true, null, null),
+        )
+        assertEquals(
+            SphereMotionMode.Procedural,
+            sphereMotionMode(SphereState.Idle, true, true, null, null),
+        )
+    }
+}

app/src/test/kotlin/com/hermesandroid/relay/viewmodel/ChatViewModelGatewayInboundTurnTest.kt

@@ -1003,6 +1003,72 @@ class ChatViewModelGatewayInboundTurnTest {
         assertTrue(handler.messages.value.any { "Stopped" in it.badges })
     }
 
+    @Test
+    fun stopClearsStaleBusyStateAfterTerminalBubbleAlreadySettled() {
+        // Exercise Stop's route-independent fallback without the Gateway
+        // orphan-state observer settling this synthetic state first.
+        viewModel.streamingEndpoint = "sessions"
+        handler.onTextDelta("stale-answer", "Finished answer")
+        handler.onTurnComplete("stale-answer")
+        assertFalse(handler.messages.value.single().isStreaming)
+        assertTrue(handler.isStreaming.value)
+
+        viewModel.cancelStream()
+
+        assertFalse(handler.isStreaming.value)
+        assertNull(handler.turnStatus.value)
+    }
+
+    @Test
+    fun completedGatewayBubbleAutomaticallySettlesComposerWithoutInput() {
+        handler.onTextDelta("completed-answer", "Finished answer")
+        handler.onTurnComplete("completed-answer")
+
+        awaitCondition { !handler.isStreaming.value }
+
+        assertFalse(handler.messages.value.single().isStreaming)
+        assertFalse(gatewayClient.hasActiveTurnForSession(STORED_SESSION_ID))
+        assertTrue(gatewayHarness.rpcLog.none { it.first == "prompt.submit" })
+        assertTrue(gatewayHarness.rpcLog.none { it.first == "session.interrupt" })
+    }
+
+    @Test
+    fun completedBubbleKeepsComposerBusyWhileGatewaySessionStillOwnsTheRun() {
+        viewModel.sendMessage("Continue through another assistant turn")
+        gatewayHarness.awaitRpc("prompt.submit")
+        awaitCondition { gatewayClient.hasActiveTurnForSession(STORED_SESSION_ID) }
+        val assistantId = handler.messages.value.single { it.role == MessageRole.ASSISTANT }.id
+
+        handler.onTextDelta(assistantId, "First assistant message")
+        handler.onTurnComplete(assistantId)
+        shadowOf(Looper.getMainLooper()).idle()
+
+        assertTrue(handler.isStreaming.value)
+        assertTrue(gatewayClient.hasActiveTurnForSession(STORED_SESSION_ID))
+
+        serverWs.send(
+            gatewayHarness.eventFrame(
+                "message.complete",
+                buildJsonObject { put("text", "Final assistant message") },
+                "live-resumed",
+            ),
+        )
+        awaitCondition { !handler.isStreaming.value }
+    }
+
+    @Test
+    fun newChatClearsStaleBusyStateWhenNoLiveGatewayTurnRemains() {
+        handler.onTextDelta("stale-answer", "Finished answer")
+        assertTrue(handler.isStreaming.value)
+        assertFalse(gatewayClient.hasActiveTurn())
+
+        viewModel.createNewChat()
+
+        assertFalse(handler.isStreaming.value)
+        assertTrue(handler.messages.value.isEmpty())
+        assertNull(handler.currentSessionId.value)
+    }
+
     @Test
     fun reopenedChatRestoresRichStateAndReattachesLiveGatewayTurn() {
         val now = System.currentTimeMillis()

app/src/test/kotlin/com/hermesandroid/relay/viewmodel/ChatViewModelMediaStateTest.kt

@@ -103,6 +103,54 @@ class ChatViewModelMediaStateTest {
         assertEquals("content://com.axiomlabs.hermesrelay.fileprovider/hermes-media/photo.jpg", loaded.cachedUri)
     }
 
+    @Test
+    fun assistantWindowsPathCellularRetryUsesByPathEndpoint() {
+        val windowsPath =
+            "C:\\Users\\Example\\AppData\\Local\\Temp\\Sovereign Intelligence copy.md"
+        handler.loadMessageHistory(
+            listOf(
+                MessageItem(
+                    id = "assistant-file-1",
+                    role = "assistant",
+                    content = JsonPrimitive("MEDIA:$windowsPath"),
+                )
+            )
+        )
+
+        val deferred = awaitMessage {
+            it.attachments.singleOrNull()?.errorMessage == "Tap to download"
+        }
+        assertEquals(AttachmentState.FAILED, deferred.attachments.single().state)
+
+        server.enqueue(
+            MockResponse()
+                .setResponseCode(200)
+                .setHeader("Content-Type", "text/markdown")
+                .setHeader(
+                    "Content-Disposition",
+                    "inline; filename=\"Sovereign Intelligence copy.md\"",
+                )
+                .setBody("# copy")
+        )
+        viewModel.cellularNetworkOverride = false
+        viewModel.manualFetchAttachment("assistant-file-1", 0)
+
+        val loaded = awaitMessage {
+            it.attachments.singleOrNull()?.state == AttachmentState.LOADED
+        }.attachments.single()
+        assertEquals("text/markdown", loaded.contentType)
+        assertEquals("Sovereign Intelligence copy.md", loaded.fileName)
+
+        val request = server.takeRequest()
+        assertEquals("/media/by-path", request.requestUrl?.encodedPath)
+        assertEquals(
+            "path=C%3A%5CUsers%5CExample%5CAppData%5CLocal%5CTemp%5C" +
+                "Sovereign%20Intelligence%20copy.md",
+            request.requestUrl?.encodedQuery,
+        )
+        assertEquals(windowsPath, request.requestUrl?.queryParameter("path"))
+    }
+
     private fun awaitMessage(predicate: (ChatMessage) -> Boolean): ChatMessage {
         val deadline = System.nanoTime() + 5_000_000_000L
         while (System.nanoTime() < deadline) {

desktop/README.md

@@ -120,6 +120,9 @@ $env:HERMES_RELAY_INSTALL_SURFACE='cli'; irm https://raw.githubusercontent.com/C
 curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.sh | sh
 ```
 
+Prebuilt Linux CLI assets support both x64 and arm64; the installer selects the
+matching binary from the machine architecture.
+
 Windows downloads and verifies `hermes-relay-windows-x64-setup.exe`. The installer
 places the CLI and management UI together, adds `~/.hermes/bin` to the user PATH, and
 lets the UI start at sign-in. CLI-only installs download the same prebuilt

desktop/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@hermes-relay/cli",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@hermes-relay/cli",
-      "version": "0.4.0-beta.4",
+      "version": "0.4.0-beta.5",
       "license": "MIT",
       "bin": {
         "hermes-relay": "bin/hermes-relay.js"

desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermes-relay/cli",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "description": "Thin-client CLI for Hermes-Relay — talk to a remote Hermes agent over WSS with pairing auth, stream-renders tool calls and responses to plain stdout.",
   "type": "module",
   "bin": {
@@ -28,9 +28,10 @@
     "version": "npm run sync:version",
     "build": "npm run gen:version && tsc -p tsconfig.build.json",
     "build:watch": "tsc -p tsconfig.build.json --watch",
-    "build:bin": "npm run build:bin:win && npm run build:bin:linux && npm run build:bin:mac-x64 && npm run build:bin:mac-arm",
+    "build:bin": "npm run build:bin:win && npm run build:bin:linux && npm run build:bin:linux-arm && npm run build:bin:mac-x64 && npm run build:bin:mac-arm",
     "build:bin:win": "npm run gen:version && bun build --compile --minify --sourcemap --target=bun-windows-x64 src/bunWindowsEntry.ts --outfile dist/bin/hermes-relay-win-x64",
     "build:bin:linux": "npm run gen:version && bun build --compile --minify --sourcemap --target=bun-linux-x64 src/cli.ts --outfile dist/bin/hermes-relay-linux-x64",
+    "build:bin:linux-arm": "npm run gen:version && bun build --compile --minify --sourcemap --target=bun-linux-arm64 src/cli.ts --outfile dist/bin/hermes-relay-linux-arm64",
     "build:bin:mac-x64": "npm run gen:version && bun build --compile --minify --sourcemap --target=bun-darwin-x64 src/cli.ts --outfile dist/bin/hermes-relay-darwin-x64",
     "build:bin:mac-arm": "npm run gen:version && bun build --compile --minify --sourcemap --target=bun-darwin-arm64 src/cli.ts --outfile dist/bin/hermes-relay-darwin-arm64",
     "build:sums": "cd dist/bin && sha256sum hermes-relay-* > SHA256SUMS.txt",

desktop/scripts/install.ps1

@@ -120,7 +120,13 @@ $resolvedVersion = $version
 if ($version -eq 'latest') {
   Say "-> resolving latest desktop-v* release..."
   try {
-    $releases = Invoke-RestMethod -UseBasicParsing "https://api.github.com/repos/$repo/releases"
+    $releases = @()
+    $page = 1
+    do {
+      $releasePage = @(Invoke-RestMethod -UseBasicParsing "https://api.github.com/repos/$repo/releases?per_page=100&page=$page")
+      $releases += $releasePage
+      $page += 1
+    } while ($releasePage.Count -eq 100)
     # Don't trust the API's first-element ordering — GitHub orders by the
     # release row's created_at which shifts when the row is touched (re-tag,
     # edit). Sort by parsed version components explicitly so a touched
@@ -209,10 +215,6 @@ if ($surface -eq 'tray') {
     if ($expected -ne $actual) { Die "checksum mismatch (expected $expected, got $actual) - refusing to install" }
     Say '   ok'
 
-    if (Get-Command Unblock-File -ErrorAction SilentlyContinue) {
-      Unblock-File $installer -ErrorAction SilentlyContinue
-    }
-
     $installerArgs = @()
     if ($env:HERMES_RELAY_TRAY_SILENT -eq '1') {
       $installerArgs += '/S'
@@ -220,7 +222,8 @@ if ($surface -eq 'tray') {
     # NSIS requires /D to be the final argument. Keeping the existing registered
     # install directory avoids splitting an upgrade across two PATH locations.
     $installerArgs += "/D=$dir"
-    Say '-> launching installer...'
+    Say '-> launching unsigned preview installer...'
+    Say '   Windows may show a SmartScreen publisher warning; review it before continuing.'
     $proc = Start-Process -FilePath $installer -ArgumentList $installerArgs -Wait -PassThru
     if ($proc.ExitCode -ne 0) {
       Die "tray installer exited with code $($proc.ExitCode)"

desktop/scripts/install.sh

@@ -90,9 +90,10 @@ os="$(uname -s | tr '[:upper:]' '[:lower:]')"
 arch="$(uname -m)"
 case "$os-$arch" in
   linux-x86_64)  asset="hermes-relay-linux-x64" ;;
+  linux-aarch64|linux-arm64) asset="hermes-relay-linux-arm64" ;;
   darwin-x86_64) asset="hermes-relay-darwin-x64" ;;
   darwin-arm64)  asset="hermes-relay-darwin-arm64" ;;
-  *) die "unsupported platform: $os/$arch (published binaries: linux-x64, darwin-x64/arm64; Windows uses install.ps1)" ;;
+  *) die "unsupported platform: $os/$arch (published binaries: linux-x64/arm64, darwin-x64/arm64; Windows uses install.ps1)" ;;
 esac
 
 # Resolve "latest" to a concrete tag. GitHub's /releases/latest/download/ URL
@@ -103,16 +104,24 @@ esac
 resolved_version="$VERSION"
 if [ "$VERSION" = "latest" ]; then
   say "-> resolving latest desktop-v* release..."
-  api_body=$(curl -fsSL "https://api.github.com/repos/$REPO/releases" 2>/dev/null) \
-    || die "could not query GitHub Releases API"
+  release_tags=""
+  page=1
+  while :; do
+    api_body=$(curl -fsSL "https://api.github.com/repos/$REPO/releases?per_page=100&page=$page" 2>/dev/null) \
+      || die "could not query GitHub Releases API page $page"
+    page_tags=$(printf '%s\n' "$api_body" \
+      | grep -oE '"tag_name"[[:space:]]*:[[:space:]]*"[^"]+"' \
+      | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)"/\1/' || true)
+    page_count=$(printf '%s\n' "$page_tags" | awk 'NF { count++ } END { print count + 0 }')
+    release_tags=$(printf '%s\n%s\n' "$release_tags" "$page_tags")
+    [ "$page_count" -eq 100 ] || break
+    page=$((page + 1))
+  done
   # Extract every CLI-track tag_name and pick the SemVer-max. Don't trust the
   # API's first-element ordering — GitHub orders by the release row's created_at
-  # which shifts when the row is edited or re-tagged. Each "tag_name": entry is
-  # on its own line in GitHub's JSON output, so line-oriented tooling is
-  # sufficient and avoids a jq dependency.
-  release_tags=$(printf '%s\n' "$api_body" \
-    | grep -E '"tag_name": *"(cli-v|desktop-v)' \
-    | sed -E 's/.*"tag_name": *"([^"]+)".*/\1/' || true)
+  # which shifts when the row is edited or re-tagged. Extract only tag_name
+  # fields from each page so this stays independent of JSON formatting and
+  # avoids a jq dependency.
   resolved_version=$(printf '%s\n' "$release_tags" \
     | awk '/^desktop-v/ { v=$0; sub(/^desktop-v/, "", v); print v "\t" $0 }' \
     | sort -V \

desktop/src/updater.ts

@@ -29,8 +29,8 @@ import { pipeline } from 'node:stream/promises'
 import { VERSION } from './version.js'
 
 const DEFAULT_REPO = 'Codename-11/hermes-relay'
-const RELEASES_API = (repo: string): string =>
-  `https://api.github.com/repos/${repo}/releases`
+const RELEASES_API = (repo: string, page: number): string =>
+  `https://api.github.com/repos/${repo}/releases?per_page=100&page=${page}`
 
 export interface UpdateInfo {
   current: string
@@ -176,21 +176,24 @@ interface GhRelease {
 }
 
 async function fetchReleases(repo: string): Promise<GhRelease[]> {
-  const url = RELEASES_API(repo)
-  const res = await fetch(url, {
-    headers: {
-      Accept: 'application/vnd.github+json',
-      'User-Agent': `hermes-relay-cli/${VERSION}`
+  const releases: GhRelease[] = []
+  for (let page = 1; ; page += 1) {
+    const res = await fetch(RELEASES_API(repo, page), {
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': `hermes-relay-cli/${VERSION}`
+      }
+    })
+    if (!res.ok) {
+      throw new Error(`GitHub Releases API ${res.status} ${res.statusText}`)
     }
-  })
-  if (!res.ok) {
-    throw new Error(`GitHub Releases API ${res.status} ${res.statusText}`)
+    const data = (await res.json()) as GhRelease[]
+    if (!Array.isArray(data)) {
+      throw new Error('unexpected Releases API response (not an array)')
+    }
+    releases.push(...data)
+    if (data.length < 100) return releases
   }
-  const data = (await res.json()) as GhRelease[]
-  if (!Array.isArray(data)) {
-    throw new Error('unexpected Releases API response (not an array)')
-  }
-  return data
 }
 
 export async function checkForUpdate(opts: { repo?: string; assetName?: string } = {}): Promise<UpdateInfo | null> {
@@ -396,10 +399,19 @@ export async function finalizePendingUpdate(): Promise<void> {
     // binary, nothing to swap.
     return
   }
+  await finalizePendingUpdateAt(target)
+}
+
+/** Path-level implementation used by the Windows startup hook and tests. */
+export async function finalizePendingUpdateAt(target: string): Promise<void> {
   const base = target.slice(0, -'.exe'.length)
   const newPath = `${base}.new.exe`
   const oldPath = `${base}.old.exe`
 
+  // Reap a backup from the prior cooperative swap even when no new update is
+  // staged. The prior process can keep the renamed image locked until exit.
+  try { await unlink(oldPath) } catch { /* absent or still locked */ }
+
   try {
     await stat(newPath)
   } catch {
@@ -407,10 +419,6 @@ export async function finalizePendingUpdate(): Promise<void> {
   }
 
   try {
-    // Reap any leftover .old.exe from a previous swap. Windows lets us delete
-    // it once the file handle from the prior run is released.
-    try { await unlink(oldPath) } catch { /* either absent or still locked */ }
-
     // Move running binary → .old.exe. This is allowed on Windows even for
     // the actively-executing image (the OS keeps the handle; the file just
     // gets a new name).

desktop/src/version.ts

@@ -1,2 +1,2 @@
 // Regenerated from package.json by gen:version script. Do not edit by hand.
-export const VERSION = "0.4.0-beta.4" as const
+export const VERSION = "0.4.0-beta.5" as const

desktop/tests/uiInstall.test.ts

@@ -118,8 +118,32 @@ test('tray update helper preserves the current install directory and cleans its
 
 test('POSIX installer only advertises artifacts produced by the release workflow', async () => {
   const script = await readFile(new URL('../scripts/install.sh', import.meta.url), 'utf8')
-  assert.doesNotMatch(script, /hermes-relay-linux-arm64/)
+  const packageJson = await readFile(new URL('../package.json', import.meta.url), 'utf8')
+  const workflow = await readFile(new URL('../../.github/workflows/release-cli.yml', import.meta.url), 'utf8')
+  assert.match(script, /linux-aarch64\|linux-arm64\) asset="hermes-relay-linux-arm64"/)
   assert.match(script, /hermes-relay-linux-x64/)
+  assert.match(packageJson, /--target=bun-linux-arm64[^\n]+hermes-relay-linux-arm64/)
+  assert.match(workflow, /npm run build:bin:linux-arm/)
+  assert.match(workflow, /release-assets\/cli-binaries\/hermes-relay-linux-arm64/)
+  assert.doesNotMatch(workflow, /hermes-relay-linux-x64 "\$cmd" 2>&1 \|\| true/)
+  assert.match(workflow, /if \[ "\$exit_code" -ne 0 \]/)
+  assert.match(workflow, /Smoke exact macOS CLI release asset/)
+  assert.match(workflow, /release-assets\/\$native_asset" --version/)
+})
+
+test('bootstrap installers paginate release discovery beyond the first API page', async () => {
+  const posix = await readFile(new URL('../scripts/install.sh', import.meta.url), 'utf8')
+  const powershell = await readFile(new URL('../scripts/install.ps1', import.meta.url), 'utf8')
+  assert.match(posix, /releases\?per_page=100&page=\$page/)
+  assert.match(posix, /page=\$\(\(page \+ 1\)\)/)
+  assert.match(powershell, /releases\?per_page=100&page=\$page/)
+  assert.match(powershell, /while \(\$releasePage\.Count -eq 100\)/)
+})
+
+test('PowerShell tray bootstrap keeps unsigned publisher warnings visible', async () => {
+  const script = await readFile(new URL('../scripts/install.ps1', import.meta.url), 'utf8')
+  assert.doesNotMatch(script, /Unblock-File \$installer/)
+  assert.match(script, /Windows may show a SmartScreen publisher warning/)
 })
 
 test('PowerShell uninstaller delegates bundle cleanup to the NSIS uninstaller', async () => {

desktop/tests/updaterInstaller.test.ts

@@ -1,12 +1,17 @@
 import assert from 'node:assert/strict'
 import { createHash } from 'node:crypto'
-import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import test from 'node:test'
 
 import { updateCommand } from '../src/commands/update.js'
-import { checkForUpdate, downloadAndInstall } from '../src/updater.js'
+import {
+  assetNameForPlatform,
+  checkForUpdate,
+  downloadAndInstall,
+  finalizePendingUpdateAt
+} from '../src/updater.js'
 import { VERSION } from '../src/version.js'
 
 async function captureStdout(run: () => Promise<number>): Promise<{ code: number; output: string }> {
@@ -33,7 +38,7 @@ test('desktop installer selection downloads the requested asset to an exact veri
 
   globalThis.fetch = async (input) => {
     const url = String(input)
-    if (url.endsWith('/releases')) {
+    if (url.includes('/releases?')) {
       return new Response(JSON.stringify([{
         tag_name: 'desktop-v9.0.0',
         prerelease: false,
@@ -65,6 +70,65 @@ test('desktop installer selection downloads the requested asset to an exact veri
   }
 })
 
+test('release discovery paginates past mixed-surface releases', async () => {
+  const originalFetch = globalThis.fetch
+  const requested: string[] = []
+  const nonDesktopRelease = (index: number) => ({
+    tag_name: index % 2 === 0 ? `android-v1.${index}.0` : `server-v1.${index}.0`,
+    prerelease: false,
+    published_at: '2026-08-11T00:00:00Z',
+    assets: []
+  })
+  globalThis.fetch = async (input) => {
+    const url = String(input)
+    requested.push(url)
+    if (url.endsWith('page=1')) {
+      return new Response(JSON.stringify(Array.from({ length: 100 }, (_, index) => nonDesktopRelease(index))), { status: 200 })
+    }
+    if (url.endsWith('page=2')) {
+      return new Response(JSON.stringify([{
+        tag_name: 'desktop-v9.1.0',
+        prerelease: false,
+        published_at: '2026-08-12T00:00:00Z',
+        assets: []
+      }]), { status: 200 })
+    }
+    return new Response('not found', { status: 404 })
+  }
+
+  try {
+    const info = await checkForUpdate({ repo: 'example/hermes-relay', assetName: 'hermes-relay-linux-arm64' })
+    assert.ok(info)
+    assert.equal(info.latest_tag, 'desktop-v9.1.0')
+    assert.equal(info.asset_name, 'hermes-relay-linux-arm64')
+    assert.deepEqual(requested, [
+      'https://api.github.com/repos/example/hermes-relay/releases?per_page=100&page=1',
+      'https://api.github.com/repos/example/hermes-relay/releases?per_page=100&page=2'
+    ])
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('Linux arm64 maps to the published Bun asset', () => {
+  assert.equal(assetNameForPlatform('linux', 'arm64'), 'hermes-relay-linux-arm64')
+})
+
+test('cooperative updater removes a released Windows backup without another staged update', async () => {
+  const scratch = await mkdtemp(join(tmpdir(), 'hermes-updater-old-cleanup-'))
+  const target = join(scratch, 'hermes-relay.exe')
+  const oldPath = join(scratch, 'hermes-relay.old.exe')
+  try {
+    await writeFile(target, 'current')
+    await writeFile(oldPath, 'previous')
+    await finalizePendingUpdateAt(target)
+    await assert.rejects(stat(oldPath), { code: 'ENOENT' })
+    assert.equal(await readFile(target, 'utf8'), 'current')
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+})
+
 test('installer check reports a newer local preview without treating it as an error', async () => {
   const originalFetch = globalThis.fetch
   globalThis.fetch = async () => new Response(JSON.stringify([{

desktop/tray/Cargo.lock

@@ -1232,7 +1232,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "hermes-relay-tray"
-version = "0.4.0-beta.4"
+version = "0.4.0-beta.5"
 dependencies = [
  "base64 0.22.1",
  "serde",

desktop/tray/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hermes-relay-tray"
-version = "0.4.0-beta.4"
+version = "0.4.0-beta.5"
 description = "Compact Windows management UI for Hermes-Relay CLI"
 authors = ["Axiom Labs"]
 edition = "2021"

desktop/tray/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@hermes-relay/tray-ui",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@hermes-relay/tray-ui",
-      "version": "0.4.0-beta.4",
+      "version": "0.4.0-beta.5",
       "dependencies": {
         "@tauri-apps/api": "^2.8.0",
         "lucide-react": "^0.468.0",

desktop/tray/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hermes-relay/tray-ui",
   "private": true,
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "type": "module",
   "scripts": {
     "dev": "vite --host 127.0.0.1",

desktop/tray/scripts/capture-desktop-ui.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process'
+import { createConnection } from 'node:net'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { computeDesktopUiSourceFingerprint } from './desktop-ui-source-fingerprint.mjs'
+
+const trayRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const repositoryRoot = resolve(trayRoot, '..', '..')
+const outputDir = resolve(repositoryRoot, 'assets', 'screenshots', 'desktop-ui')
+const manifestPath = resolve(repositoryRoot, 'docs', 'media', 'desktop-ui-screenshots.json')
+const session = `hermes-relay-desktop-screenshots-${process.pid}`
+const baseUrl = 'http://127.0.0.1:1421/'
+const playwrightCliVersion = '0.1.18'
+const bundledNpx = resolve(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npx-cli.js')
+const viteEntry = resolve(trayRoot, 'node_modules', 'vite', 'bin', 'vite.js')
+const requireFromWebsite = createRequire(resolve(repositoryRoot, 'website', 'package.json'))
+const sharp = requireFromWebsite('sharp')
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: trayRoot,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+    ...options
+  })
+  if (result.status !== 0 || result.error) {
+    throw new Error([result.error?.message, result.stdout, result.stderr].filter(Boolean).join('\n'))
+  }
+  return `${result.stdout ?? ''}${result.stderr ?? ''}`
+}
+
+function cli(...args) {
+  if (!existsSync(bundledNpx)) throw new Error(`npm/npx runtime not found at ${bundledNpx}`)
+  return run(process.execPath, [bundledNpx, '--yes', '--package', `@playwright/cli@${playwrightCliVersion}`, 'playwright-cli', `-s=${session}`, ...args], {
+    env: { ...process.env, TZ: 'UTC' }
+  })
+}
+
+async function waitForServer() {
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    const ready = await new Promise(resolveReady => {
+      const socket = createConnection({ host: '127.0.0.1', port: 1421 })
+      socket.once('connect', () => { socket.destroy(); resolveReady(true) })
+      socket.once('error', () => resolveReady(false))
+    })
+    if (ready) return
+    await new Promise(resolveWait => setTimeout(resolveWait, 100))
+  }
+  throw new Error(`screenshot Vite server did not start at ${baseUrl}`)
+}
+
+async function capture(filename) {
+  const destination = resolve(outputDir, filename)
+  const rawCapture = `${destination}.capture.png`
+  cli('screenshot', '--filename', rawCapture)
+  const normalized = await sharp(rawCapture)
+    .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+    .toBuffer()
+  let preserveExisting = false
+  try {
+    const previous = await readFile(destination)
+    const [before, after] = await Promise.all([
+      sharp(previous).raw().toBuffer({ resolveWithObject: true }),
+      sharp(normalized).raw().toBuffer({ resolveWithObject: true })
+    ])
+    if (before.info.width === after.info.width && before.info.height === after.info.height && before.info.channels === after.info.channels) {
+      let differingChannels = 0
+      let maximumDelta = 0
+      for (let index = 0; index < before.data.length; index += 1) {
+        const delta = Math.abs(before.data[index] - after.data[index])
+        if (delta > 0) differingChannels += 1
+        if (delta > maximumDelta) maximumDelta = delta
+      }
+      preserveExisting = maximumDelta <= 1 && differingChannels / before.data.length <= 0.001
+    }
+  } catch { /* A missing or unreadable canonical image is replaced. */ }
+  if (!preserveExisting) await writeFile(destination, normalized)
+  await rm(rawCapture, { force: true })
+  console.log(`${preserveExisting ? 'retained' : 'captured'} ${destination}`)
+}
+
+await mkdir(outputDir, { recursive: true })
+
+const vite = spawn(
+  process.execPath,
+  [viteEntry, '--config', 'scripts/vite.screenshots.config.mjs'],
+  { cwd: trayRoot, stdio: ['ignore', 'pipe', 'pipe'] }
+)
+let viteOutput = ''
+vite.stdout.on('data', chunk => { viteOutput += chunk })
+vite.stderr.on('data', chunk => { viteOutput += chunk })
+
+try {
+  await waitForServer()
+  cli('open', 'about:blank', '--browser', 'chrome')
+  cli('resize', '493', '785')
+  cli('run-code', "async page => { await page.context().addInitScript(() => { const fixed = Date.parse('2026-08-01T16:00:00Z'); Date.now = () => fixed }) }")
+  cli('goto', baseUrl)
+  cli('run-code', "async page => { await page.waitForSelector('.app-shell.window-visible'); await page.addStyleTag({ content: '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}' }); await page.evaluate(() => document.fonts.ready) }")
+
+  await capture('overview.png')
+
+  cli('run-code', "async page => { await page.getByRole('button', { name: 'Desktop access' }).click(); await page.waitForSelector('h1:text-is(\"Host access\")') }")
+  await capture('host-access.png')
+
+  cli('run-code', "async page => { await page.getByRole('button', { name: 'Overview', exact: true }).click(); await page.getByRole('button', { name: /PowerShell command/ }).click(); await page.waitForSelector('h1:text-is(\"PowerShell command\")') }")
+  await capture('activity-detail.png')
+
+  cli('run-code', "async page => { await page.getByRole('button', { name: 'Settings', exact: true }).click(); await page.waitForSelector('h1:text-is(\"Settings\")'); await page.waitForFunction(() => document.body.innerText.includes('CUA Driver 0.21.0')); await page.evaluate(() => { const content = document.querySelector('.content'); const control = [...document.querySelectorAll('.settings-group')].find(node => node.querySelector('h2')?.textContent === 'Computer control'); if (content && control) content.scrollTop = control.offsetTop - 10 }) }")
+  await capture('settings.png')
+
+  cli('run-code', "async page => { await page.evaluate(() => { const content = document.querySelector('.content'); const updates = [...document.querySelectorAll('.settings-group')].find(node => node.querySelector('h2')?.textContent === 'Updates'); if (content && updates) content.scrollTop = updates.offsetTop - 10 }) }")
+  await capture('settings-update.png')
+
+  const consoleOutput = cli('console', 'warning')
+  if (/\b(TypeError|ReferenceError|Uncaught)\b/i.test(consoleOutput)) {
+    throw new Error(`browser console reported a failure:\n${consoleOutput}`)
+  }
+
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  manifest.sourceFingerprint = await computeDesktopUiSourceFingerprint(repositoryRoot)
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  console.log(`updated ${manifestPath} source fingerprint`)
+} catch (error) {
+  if (vite.exitCode !== null) console.error(viteOutput)
+  throw error
+} finally {
+  try { cli('close') } catch { /* Best effort session cleanup. */ }
+  if (vite.exitCode === null) vite.kill()
+  await rm(resolve(trayRoot, '.playwright-cli'), { recursive: true, force: true })
+}

desktop/tray/scripts/desktop-ui-source-fingerprint.mjs

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { dirname, extname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const defaultRepositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
+
+export const desktopUiScreenshotSourceFiles = Object.freeze([
+  'desktop/tray/ui/App.tsx',
+  'desktop/tray/ui/main.tsx',
+  'desktop/tray/ui/styles.css',
+  'desktop/tray/ui/types.ts',
+  'desktop/tray/index.html',
+  'desktop/tray/icons/icon-256.png',
+  'desktop/tray/package-lock.json',
+  'desktop/src/endpoint.ts',
+  'desktop/src/transportSecurity.ts',
+  'desktop/tray/scripts/vite.screenshots.config.mjs',
+  'desktop/tray/scripts/capture-desktop-ui.mjs',
+  'desktop/tray/scripts/desktop-ui-source-fingerprint.mjs'
+])
+
+const binaryExtensions = new Set(['.png'])
+
+export async function computeDesktopUiSourceFingerprint(repositoryRoot = defaultRepositoryRoot) {
+  const hash = createHash('sha256')
+  for (const relativePath of desktopUiScreenshotSourceFiles) {
+    const bytes = await readFile(resolve(repositoryRoot, relativePath))
+    const normalized = binaryExtensions.has(extname(relativePath))
+      ? bytes
+      : Buffer.from(bytes.toString('utf8').replace(/\r\n?/g, '\n'), 'utf8')
+    hash.update(relativePath)
+    hash.update('\0')
+    hash.update(normalized)
+    hash.update('\0')
+  }
+  return {
+    algorithm: 'sha256',
+    normalization: 'text-lf-v1',
+    digest: hash.digest('hex'),
+    files: [...desktopUiScreenshotSourceFiles]
+  }
+}

desktop/tray/scripts/vite.screenshots.config.mjs

@@ -0,0 +1,50 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+const replacements = new Map([
+  ["server_version: '1.6.3'", "server_version: '1.9.0'"],
+  ["ui_version: '0.4.0-alpha.7'", "ui_version: '0.4.0-beta.4'"],
+  ["cli_version: '0.4.0-alpha.4'", "cli_version: '0.4.0-beta.4'"],
+  ["void getCurrentWindow().isVisible().then(visible => { if (visible) start() })", "start()"],
+  [
+    "selected: 'legacy', effective: 'legacy', available: false, state: 'not_installed',\n    foreground_escalation_enabled: false, message: 'CUA Driver is not installed. Legacy input remains active.'",
+    "selected: 'cua', effective: 'cua', available: true, state: 'ready', version: '0.21.0', cursor_enabled: true, active_sessions: 0, active_backend: 'idle',\n    foreground_escalation_enabled: false, message: 'CUA Driver 0.21.0 is compatible and healthy.'"
+  ],
+  [
+    "return { current: '0.4.0-alpha.3', up_to_date: true, ahead_of_latest: true, latest_version: '0.4.0-alpha.2', installed: false, needs_restart: false } as T",
+    "return { current: '0.4.0-beta.4', up_to_date: true, ahead_of_latest: false, latest_version: '0.4.0-beta.4', installed: false, needs_restart: false } as T"
+  ],
+  [
+    "return { installed: false, stale_path_shim: false, compatible: false, compatibility_reason: 'CUA Driver is not installed', supported_range: { minimum: '0.20.0', maximum_exclusive: null } } as T",
+    "return { installed: true, stale_path_shim: false, current_version: '0.21.0', compatible: true, compatibility_reason: 'Compatible with Hermes-Relay CLI UI', supported_range: { minimum: '0.20.0', maximum_exclusive: null }, update: { latest_version: '0.21.0', update_available: false, compatible: true } } as T"
+  ],
+  [
+    "return { state: 'degraded', checkedAt: new Date().toISOString(), overall: 'degraded', reason: 'UI Automation desktop enumeration exceeded 2000ms.', temporaryWindowsCompatibility: true } as T",
+    "return { state: 'healthy', checkedAt: new Date().toISOString(), overall: 'healthy', reason: 'Accessibility and window discovery checks passed.', temporaryWindowsCompatibility: true } as T"
+  ]
+])
+
+function publicScreenshotFixtures() {
+  return {
+    name: 'public-screenshot-fixtures',
+    enforce: 'pre',
+    transform(source, id) {
+      if (!id.endsWith('/ui/App.tsx') && !id.endsWith('\\ui\\App.tsx')) return null
+      let transformed = source
+      for (const [from, to] of replacements) transformed = transformed.replaceAll(from, to)
+      transformed = transformed.replace(
+        /selected: 'legacy', effective: 'legacy', available: false, state: 'not_installed',\s+foreground_escalation_enabled: false, message: 'CUA Driver is not installed\. Legacy input remains active\.'/,
+        "selected: 'cua', effective: 'cua', available: true, state: 'ready', version: '0.21.0', cursor_enabled: true, active_sessions: 0, active_backend: 'idle',\n    foreground_escalation_enabled: false, message: 'CUA Driver 0.21.0 is compatible and healthy.'"
+      )
+      return { code: transformed, map: null }
+    }
+  }
+}
+
+export default defineConfig({
+  plugins: [publicScreenshotFixtures(), react()],
+  clearScreen: false,
+  server: { host: '127.0.0.1', port: 1421, strictPort: true },
+  envPrefix: ['VITE_', 'TAURI_'],
+  build: { target: ['es2021', 'chrome100', 'safari13'] }
+})

desktop/tray/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Hermes-Relay CLI UI",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "identifier": "com.axiomlabs.hermes-relay-tray",
   "build": {
     "beforeDevCommand": "npm run dev",

desktop/tray/ui/App.tsx

@@ -25,9 +25,9 @@ const isNoticeWindow = windowLabel === 'notice'
 const isEvidenceWindow = windowLabel === 'evidence'
 
 const demo: Snapshot = {
-  hosts: [{ url: 'wss://home-hermes.local:8767', name: 'Docker-Server', server_version: '1.6.3', endpoint_role: 'tailscale', paired_at: 1786458000, is_active: true, access_mode: 'full-access', capabilities: { commands: 'allow', files: 'allow', screen_input: 'allow', usb: 'allow', microphone: 'allow', camera: 'allow' } }],
-  active_url: 'wss://home-hermes.local:8767',
-  daemon: { state: 'connected', running: true, url: 'wss://home-hermes.local:8767', privilege: 'user', username: 'Local user' },
+  hosts: [{ url: 'wss://relay.example.test:8767', name: 'Hermes Home', server_version: '1.6.3', endpoint_role: 'tailscale', paired_at: 1786458000, is_active: true, access_mode: 'full-access', capabilities: { commands: 'allow', files: 'allow', screen_input: 'allow', usb: 'allow', microphone: 'allow', camera: 'allow' } }],
+  active_url: 'wss://relay.example.test:8767',
+  daemon: { state: 'connected', running: true, url: 'wss://relay.example.test:8767', privilege: 'user', username: 'Local user' },
   startup_enabled: true,
   daemon_autostart_enabled: true,
   ui_version: '0.4.0-alpha.7',
@@ -57,7 +57,7 @@ async function call<T>(command: string, args?: Record<string, unknown>): Promise
     ] as T
     if (command === 'check_desktop_update') return { current: '0.4.0-alpha.3', up_to_date: true, ahead_of_latest: true, latest_version: '0.4.0-alpha.2', installed: false, needs_restart: false } as T
     if (command === 'install_desktop_update') return { current: '0.4.0-alpha.3', up_to_date: true, ahead_of_latest: false, installed: true, needs_restart: true } as T
-    if (command === 'test_host_route') return { best: { label: 'LAN', url: 'ws://172.16.24.250:8767', reachable: true, elapsed_ms: 36, encrypted: false, security: 'Unencrypted relay connection' }, routes: [] } as T
+    if (command === 'test_host_route') return { best: { label: 'Secure Link', url: 'wss://relay.example.test:8767', reachable: true, elapsed_ms: 36, encrypted: true, security: 'Encrypted relay connection' }, routes: [] } as T
     if (command === 'computer_cua_status') return { installed: false, stale_path_shim: false, compatible: false, compatibility_reason: 'CUA Driver is not installed', supported_range: { minimum: '0.20.0', maximum_exclusive: null } } as T
     if (command === 'computer_cua_health') return { state: 'degraded', checkedAt: new Date().toISOString(), overall: 'degraded', reason: 'UI Automation desktop enumeration exceeded 2000ms.', temporaryWindowsCompatibility: true } as T
     return undefined as T

docs/decisions.md

@@ -777,7 +777,13 @@ Four sub-decisions captured together:
    contains no tokens, secrets, config contents, or filesystem paths;
    `/bridge/activity` and `/media/inspect` remain loopback-only.
 
-4. **Dashboard backend is a thin proxy; relay is source of truth.** `plugin_api.py` exposes five routes at `/api/plugins/hermes-relay/{overview,sessions,bridge-activity,media,push}` and forwards to the relay over `httpx.AsyncClient` with a 5-second timeout. No business logic — the plugin never maintains its own state, never caches, never retries. Relay connect-error / timeout / 5xx translate to `HTTPException(502, detail=…)` carrying the relay address, so the UI can render a "relay unreachable at 127.0.0.1:8767" banner; 4xx passes through verbatim. The one exception is `/push` — since FCM isn't wired, this route is a static stub returning `{configured: false, reason: "FCM not yet wired; …"}` with no network call. Keeps the four-tab nav layout correct for when FCM lands; swapping in real data only touches `PushConsole.jsx` + `plugin_api.py::get_push`.
+4. **Dashboard backend is a thin proxy; relay is source of truth.** `plugin_api.py` exposes five routes at `/api/plugins/hermes-relay/{overview,sessions,bridge-activity,media,push}` and forwards to the relay over `httpx.AsyncClient` with a 5-second timeout. It does not cache or retry. Relay connect-error / timeout / 5xx translate to `HTTPException(502, detail=…)` carrying the relay address, so the UI can render a "relay unreachable at 127.0.0.1:8767" banner; 4xx passes through verbatim. The `/push` route is a static stub until FCM is wired.
+
+   **2026-08-21 amendment:** the authenticated `/provider-usage` route is a
+   deliberate process-local exception. The Dashboard process owns the live
+   Gateway session, so this Relay-plugin route resolves its active credential
+   on demand and feeds the same provider-neutral Relay adapter without waiting
+   for another turn. It stores no provider secret or additional Dashboard state.
 
 **Consequences:**
 
@@ -3737,3 +3743,53 @@ the active connection, and a group cannot gain a competing mobile writer.
 Route-scoped Relay media, voice, background delivery notifications, autonomous
 peer delivery, and writable room control remain separate capabilities rather
 than implicit authority gained from appearing in the union roster.
+
+---
+
+## ADR 67 — Provider account usage is Relay-enhanced, normalized, and user-presented at top level
+
+**Context.** Android had no account-limit surface even though current Hermes
+already models Codex and Nous usage. A proposed OpenCode Go-only Settings card
+introduced a Relay proxy, fixed provider windows, and inferred dollar spend
+from rounded percentages. That shape could not represent multiple providers,
+made changing plans look authoritative, and placed a provider-specific card on
+the Settings landing page for hosts where it did not apply.
+
+**Decision.** Android owns one top-level **Usage & limits** Settings destination,
+parallel to Hermes Management rather than nested inside it. The device-level
+landing presentation is Summary by default, with opt-in Expanded and Hidden
+modes plus per-provider visibility. The full destination remains reachable in
+all three modes.
+
+When Dashboard auth is available, the client first calls the Relay-owned
+Dashboard-plugin usage route so the live session's active credential can be
+resolved directly. Paired standalone clients fall back to Relay
+`GET /usage/providers`, which requires the operator to set
+`RELAY_PROVIDER_USAGE_ENABLED=1`; additive upstream Gateway `account.usage`
+remains the bounded single-account fallback. Relay reuses Hermes's existing
+account model for Codex and Nous and supplies the missing OpenCode Go adapter. OpenCode Go
+renders only the percentage and reset values returned by the provider; Android
+does not infer dollars or embed plan caps. Provider keys stay host-side.
+The active profile is carried on the compatibility request and validated before
+Hermes's task-local home override scopes every account lookup, so concurrent
+profiles never collapse onto the root account.
+
+For Codex pools, Android also carries its current Gateway session id. The
+authenticated Relay Dashboard-plugin route runs in the process that owns the
+live agent, reads its authoritative stable pool-entry id on demand, and returns
+the provider-neutral usage response without waiting for another turn. Relay
+fetches each pool entry's usage host-side, returns safe labels and hashed opaque
+ids, and marks the exact active entry. Turn hooks retain a secret-free
+profile-local snapshot only for standalone Relay clients without Dashboard
+access. Missing live-agent/session evidence is rendered as active unknown; it
+is never inferred from the first credential or from the legacy singleton.
+
+xAI and other providers remain absent until their account-level source and
+credential scope can be represented honestly. Per-request or session spend is
+not labeled as an account quota.
+
+**Consequences.** Relay can evolve richer provider adapters without requiring
+an upstream Hermes change, while vanilla/current Hermes retains a bounded
+single-account fallback. Merely configuring a provider credential does not
+expose tokens to paired devices. The Android UI can add providers without
+adding provider-specific screens or silently treating missing data as zero usage.

docs/dev-loop.md

@@ -68,6 +68,25 @@ Rule of thumb: where a surface is CI-gateable, write the **failing test first**
 is the deliberate exception — CI only covers lint + unit there, so on-device
 verification stays a manual maintainer step and a fix is never "done" from CI alone.
 
+### Emulator UI evidence
+
+Hermes Android is dark-mode-first. Before emulator screenshots, animation
+review, or renderer performance measurements, explicitly enable Android dark
+mode and restart the app so evidence is not captured in the emulator's light
+default:
+
+```bash
+adb -s <emulator-serial> shell cmd uimode night yes
+adb -s <emulator-serial> shell am force-stop com.axiomlabs.hermesrelay.sideload
+adb -s <emulator-serial> shell am start -n \
+  com.axiomlabs.hermesrelay.sideload/com.hermesandroid.relay.MainActivity
+adb -s <emulator-serial> shell cmd uimode night
+```
+
+Confirm the final command reports `Night mode: yes` before capturing evidence.
+Use host GPU acceleration where available; software rendering is useful for
+compatibility but is not representative performance evidence.
+
 ## Local bridge: `scripts/start-issue.sh`
 
 ```bash

docs/localization-status.json

@@ -13,7 +13,7 @@
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -24,13 +24,13 @@
       },
       "docs_locale": "de",
       "docs_source_sha256": {
-        "index.md": "bbaa33578cd9d8963150ed861e7a0bd489d3938b7c6c2d572beea725f319e136",
-        "guide/quick-start.md": "1a5c4c89a992bd57c1e93702b270a466675c7f65fb8ebe20968febc621877049",
-        "guide/getting-started.md": "d1d348b2ff7c05d639cddf33d14c1a2e4cac26e072fcd2b2988e37ea694d4bbd",
-        "guide/release-tracks.md": "390982de1e1430bed0b8a0e854431c97e3368cf04e477197eb5cb893db225f51",
+        "index.md": "101ef2e9394b76e822d0c828e2100bf18a9d3f450224f5f0ae3ea01cb02fab0d",
+        "guide/quick-start.md": "486fa0b9ea0f08c19be9407d8c30b2c2363182151c31d71ecd81dee996c19632",
+        "guide/getting-started.md": "1c2d5a9d04b86dc784802c1e0d9c5818de13f0b4792f6e000bf12f003f352b8d",
+        "guide/release-tracks.md": "1e793410f433b12f503ac1649afec8820a712aff74b38202693aa9a0d6ad0a26",
         "guide/troubleshooting.md": "43677454b94dd7810adc9b685266598353b851b549b151de31cfa053cf74f6c1"
       },
-      "website_source_sha256": "d4eeb605a56856e1f5002783268049870646bcea4dbccc907467cc0c2e011122"
+      "website_source_sha256": "2de54aed7fd3c4e02ecbf57a4e9069ce64a3fd8d2874dc41b63732924fb354e1"
     },
     "en": {
       "native_name": "English",
@@ -48,7 +48,7 @@
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -59,20 +59,20 @@
       },
       "docs_locale": "es",
       "docs_source_sha256": {
-        "index.md": "bbaa33578cd9d8963150ed861e7a0bd489d3938b7c6c2d572beea725f319e136",
-        "guide/quick-start.md": "1a5c4c89a992bd57c1e93702b270a466675c7f65fb8ebe20968febc621877049",
-        "guide/getting-started.md": "d1d348b2ff7c05d639cddf33d14c1a2e4cac26e072fcd2b2988e37ea694d4bbd",
-        "guide/release-tracks.md": "390982de1e1430bed0b8a0e854431c97e3368cf04e477197eb5cb893db225f51",
+        "index.md": "101ef2e9394b76e822d0c828e2100bf18a9d3f450224f5f0ae3ea01cb02fab0d",
+        "guide/quick-start.md": "486fa0b9ea0f08c19be9407d8c30b2c2363182151c31d71ecd81dee996c19632",
+        "guide/getting-started.md": "1c2d5a9d04b86dc784802c1e0d9c5818de13f0b4792f6e000bf12f003f352b8d",
+        "guide/release-tracks.md": "1e793410f433b12f503ac1649afec8820a712aff74b38202693aa9a0d6ad0a26",
         "guide/troubleshooting.md": "43677454b94dd7810adc9b685266598353b851b549b151de31cfa053cf74f6c1"
       },
-      "website_source_sha256": "d4eeb605a56856e1f5002783268049870646bcea4dbccc907467cc0c2e011122"
+      "website_source_sha256": "2de54aed7fd3c4e02ecbf57a4e9069ce64a3fd8d2874dc41b63732924fb354e1"
     },
     "ja": {
       "native_name": "日本語",
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -83,20 +83,20 @@
       },
       "docs_locale": "ja",
       "docs_source_sha256": {
-        "index.md": "bbaa33578cd9d8963150ed861e7a0bd489d3938b7c6c2d572beea725f319e136",
-        "guide/quick-start.md": "1a5c4c89a992bd57c1e93702b270a466675c7f65fb8ebe20968febc621877049",
-        "guide/getting-started.md": "d1d348b2ff7c05d639cddf33d14c1a2e4cac26e072fcd2b2988e37ea694d4bbd",
-        "guide/release-tracks.md": "390982de1e1430bed0b8a0e854431c97e3368cf04e477197eb5cb893db225f51",
+        "index.md": "101ef2e9394b76e822d0c828e2100bf18a9d3f450224f5f0ae3ea01cb02fab0d",
+        "guide/quick-start.md": "486fa0b9ea0f08c19be9407d8c30b2c2363182151c31d71ecd81dee996c19632",
+        "guide/getting-started.md": "1c2d5a9d04b86dc784802c1e0d9c5818de13f0b4792f6e000bf12f003f352b8d",
+        "guide/release-tracks.md": "1e793410f433b12f503ac1649afec8820a712aff74b38202693aa9a0d6ad0a26",
         "guide/troubleshooting.md": "43677454b94dd7810adc9b685266598353b851b549b151de31cfa053cf74f6c1"
       },
-      "website_source_sha256": "d4eeb605a56856e1f5002783268049870646bcea4dbccc907467cc0c2e011122"
+      "website_source_sha256": "2de54aed7fd3c4e02ecbf57a4e9069ce64a3fd8d2874dc41b63732924fb354e1"
     },
     "pt-BR": {
       "native_name": "Português (Brasil)",
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -107,20 +107,20 @@
       },
       "docs_locale": "pt-BR",
       "docs_source_sha256": {
-        "index.md": "bbaa33578cd9d8963150ed861e7a0bd489d3938b7c6c2d572beea725f319e136",
-        "guide/quick-start.md": "1a5c4c89a992bd57c1e93702b270a466675c7f65fb8ebe20968febc621877049",
-        "guide/getting-started.md": "d1d348b2ff7c05d639cddf33d14c1a2e4cac26e072fcd2b2988e37ea694d4bbd",
-        "guide/release-tracks.md": "390982de1e1430bed0b8a0e854431c97e3368cf04e477197eb5cb893db225f51",
+        "index.md": "101ef2e9394b76e822d0c828e2100bf18a9d3f450224f5f0ae3ea01cb02fab0d",
+        "guide/quick-start.md": "486fa0b9ea0f08c19be9407d8c30b2c2363182151c31d71ecd81dee996c19632",
+        "guide/getting-started.md": "1c2d5a9d04b86dc784802c1e0d9c5818de13f0b4792f6e000bf12f003f352b8d",
+        "guide/release-tracks.md": "1e793410f433b12f503ac1649afec8820a712aff74b38202693aa9a0d6ad0a26",
         "guide/troubleshooting.md": "43677454b94dd7810adc9b685266598353b851b549b151de31cfa053cf74f6c1"
       },
-      "website_source_sha256": "d4eeb605a56856e1f5002783268049870646bcea4dbccc907467cc0c2e011122"
+      "website_source_sha256": "2de54aed7fd3c4e02ecbf57a4e9069ce64a3fd8d2874dc41b63732924fb354e1"
     },
     "ru": {
       "native_name": "Русский",
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -135,7 +135,7 @@
       "verification": "ai-translated",
       "review_refs": [],
       "source_sha256": {
-        "main": "fa94ad2e674f670dfe96f4c75de6f92e0db518b66594fa44aadbae8317ed022e",
+        "main": "0abcf7f4fb8accb1b9ee174243e369173591ee5abd105aac0d3b414e78916a6d",
         "sideload": "4abff4f1069091ec2de735c3037a7ec7d77699cb4321e8511a622437bceaf7c2"
       },
       "surfaces": {
@@ -146,13 +146,13 @@
       },
       "docs_locale": "zh-CN",
       "docs_source_sha256": {
-        "index.md": "bbaa33578cd9d8963150ed861e7a0bd489d3938b7c6c2d572beea725f319e136",
-        "guide/quick-start.md": "1a5c4c89a992bd57c1e93702b270a466675c7f65fb8ebe20968febc621877049",
-        "guide/getting-started.md": "d1d348b2ff7c05d639cddf33d14c1a2e4cac26e072fcd2b2988e37ea694d4bbd",
-        "guide/release-tracks.md": "390982de1e1430bed0b8a0e854431c97e3368cf04e477197eb5cb893db225f51",
+        "index.md": "101ef2e9394b76e822d0c828e2100bf18a9d3f450224f5f0ae3ea01cb02fab0d",
+        "guide/quick-start.md": "486fa0b9ea0f08c19be9407d8c30b2c2363182151c31d71ecd81dee996c19632",
+        "guide/getting-started.md": "1c2d5a9d04b86dc784802c1e0d9c5818de13f0b4792f6e000bf12f003f352b8d",
+        "guide/release-tracks.md": "1e793410f433b12f503ac1649afec8820a712aff74b38202693aa9a0d6ad0a26",
         "guide/troubleshooting.md": "43677454b94dd7810adc9b685266598353b851b549b151de31cfa053cf74f6c1"
       },
-      "website_source_sha256": "d4eeb605a56856e1f5002783268049870646bcea4dbccc907467cc0c2e011122"
+      "website_source_sha256": "2de54aed7fd3c4e02ecbf57a4e9069ce64a3fd8d2874dc41b63732924fb354e1"
     }
   }
 }

docs/media/desktop-ui-screenshots.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "description": "Deterministic, public-safe Windows CLI UI screenshots captured from the production React surface.",
+  "capture": {
+    "command": "node desktop/tray/scripts/capture-desktop-ui.mjs",
+    "viewport": {
+      "width": 493,
+      "height": 785
+    },
+    "fixture": "Browser fallback with fixed UTC time and public example host data",
+    "websiteSync": "node website/scripts/desktop-ui-assets.mjs sync",
+    "websiteCheck": "node website/scripts/desktop-ui-assets.mjs check"
+  },
+  "scenes": [
+    {
+      "id": "overview",
+      "title": "Connected desktop overview",
+      "source": "assets/screenshots/desktop-ui/overview.png",
+      "website": "website/public/product/desktop-ui/overview.png",
+      "captureNote": "Connected public example host, transport, access policy, and local activity."
+    },
+    {
+      "id": "host-access",
+      "title": "Host access presets",
+      "source": "assets/screenshots/desktop-ui/host-access.png",
+      "website": "website/public/product/desktop-ui/host-access.png",
+      "captureNote": "Production host access screen with the four consent presets."
+    },
+    {
+      "id": "activity-detail",
+      "title": "Local activity detail",
+      "source": "assets/screenshots/desktop-ui/activity-detail.png",
+      "website": "website/public/product/desktop-ui/activity-detail.png",
+      "captureNote": "Sanitized PowerShell request timeline and locally retained result detail."
+    },
+    {
+      "id": "settings",
+      "title": "Computer control and updates",
+      "source": "assets/screenshots/desktop-ui/settings.png",
+      "website": "website/public/product/desktop-ui/settings.png",
+      "captureNote": "CUA Driver readiness, safety controls, maintenance status, and diagnostics."
+    },
+    {
+      "id": "settings-update",
+      "title": "Desktop bundle updates",
+      "source": "assets/screenshots/desktop-ui/settings-update.png",
+      "website": "website/public/product/desktop-ui/settings-update.png",
+      "captureNote": "Current CLI UI bundle version, update state, and local activity controls."
+    }
+  ],
+  "sourceFingerprint": {
+    "algorithm": "sha256",
+    "normalization": "text-lf-v1",
+    "digest": "8cf00c04da9e80621b439563145be49ede9539ac95ab903b1903763004e370bc",
+    "files": [
+      "desktop/tray/ui/App.tsx",
+      "desktop/tray/ui/main.tsx",
+      "desktop/tray/ui/styles.css",
+      "desktop/tray/ui/types.ts",
+      "desktop/tray/index.html",
+      "desktop/tray/icons/icon-256.png",
+      "desktop/tray/package-lock.json",
+      "desktop/src/endpoint.ts",
+      "desktop/src/transportSecurity.ts",
+      "desktop/tray/scripts/vite.screenshots.config.mjs",
+      "desktop/tray/scripts/capture-desktop-ui.mjs",
+      "desktop/tray/scripts/desktop-ui-source-fingerprint.mjs"
+    ]
+  }
+}

docs/play-store-listing.md

@@ -91,9 +91,9 @@ This app is a community project and is not affiliated with or endorsed by NousRe
 Paste into Play Console → **What's new** (≤500 characters):
 
 ```
-v1.12.1 - Sharing and recovery that work
+v1.13.0 - Bots, usage, and reliable chat
 
-Shared links, text, images, and files now open as complete reviewable drafts without sending automatically. Add and Renew connection setup no longer stalls. Offline chat and profile-history failures surface clear recovery guidance instead of doing nothing or showing empty history. Diagnostics now reports secure-storage fallback and recovery without exposing credentials.
+Bot Mode now brings bots from saved Hermes gateways into one messenger-style workspace. Settings adds provider-neutral Codex, Nous, and OpenCode Go usage. Compatible Assistant launches can include bounded visible text and an available screenshot. Gateway chats now settle stale busy state automatically, onboarding is clearer, and idle Sphere motion uses less power.
 ```
 ## Category
 

docs/spec.md

@@ -681,6 +681,8 @@ MEDIA:hermes-relay://<url-safe-16-byte-token>
 
 **Server:** media routes on `plugin/relay/server.py`:
 - `POST /media/register` — **loopback-only**. Body `{"path", "content_type", "file_name"}`. Validates path is absolute, resolves (`os.path.realpath`) under an allowed root, exists, is a regular file, fits under `RELAY_MEDIA_MAX_SIZE_MB`. Generates `secrets.token_urlsafe(16)` (128 bits entropy), stores the token → entry mapping in an in-memory `OrderedDict` LRU (capped at `RELAY_MEDIA_LRU_CAP`, TTL `RELAY_MEDIA_TTL_SECONDS`). Returns `{ok, token, expires_at}`. Used when a host-local tool explicitly wants to publish a file.
+- `GET /api/plugins/hermes-relay/provider-usage?profile=<id>&session_id=<id>` — authenticated Dashboard-plugin surface that resolves the active Codex pool entry directly from the live Gateway session, without requiring another turn. Android prefers this route when Dashboard auth is available.
+- `GET /usage/providers?profile=<id>&session_id=<id>` — bearer-authenticated standalone Relay surface for Android provider account limits. Disabled unless `RELAY_PROVIDER_USAGE_ENABLED=1`. The validated profile ID scopes every credential/account lookup through Hermes's context-local home override. It reuses Hermes account snapshots for Codex and Nous, adds OpenCode Go percentage/reset windows, and returns no provider secrets. For Codex it reports every bounded pool entry with a safe label, hashed opaque id, effective status, and usage windows; the optional Gateway session id correlates the active entry from a secret-free profile-local hook snapshot. If that exact evidence is absent, active state is explicitly unknown. Android falls back to this route, then additive upstream Gateway `account.usage` as a single-account fallback.
 - `GET /media/{token}` — requires `Authorization: Bearer <session_token>` against the existing `SessionManager` (same token WSS uses). Streams the file via `web.FileResponse` with the registered content type plus `Content-Disposition: inline; filename="..."` if the entry has a file name. 401 on missing/invalid bearer, 404 on unknown/expired token.
 - `GET /media/by-path?path=<abs>&content_type=<optional>` — requires bearer auth. Shares the same sandbox validation as `/media/register` via a common `validate_media_path()` helper: absolute path, `realpath`-resolves under an allowed root, exists, is a regular file, fits under the size cap. Content-Type is the phone's hint if provided, otherwise guessed via `mimetypes.guess_type()`. This route exists specifically for **LLM-emitted bare-path markers** — upstream `agent/prompt_builder.py` instructs the model to include `MEDIA:/absolute/path/to/file` in its response text, so the bare-path form is the agent's native output, not just a fallback. 401 auth, 403 sandbox, 404 missing file.
 - `POST /media/upload` — bearer-auth'd small upload route for phone-originated media. Accepts base64 content, writes a temp file, and registers it into the same media registry.

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
-appVersionName = "1.12.1"
-appVersionCode = "48"
+appVersionName = "1.13.0"
+appVersionCode = "49"
 agp = "9.3.2"
 kotlin = "2.4.10"
 compose-bom = "2026.08.00"

plugin/dashboard/manifest.json

@@ -3,7 +3,7 @@
   "label": "Relay",
   "description": "Paired devices, bridge activity, media inspection, and remote access for hermes-relay",
   "icon": "Activity",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "tab": {
     "path": "/relay",
     "position": "after:skills"

plugin/dashboard/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hermes-relay-dashboard",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hermes-relay-dashboard",
-      "version": "1.9.0",
+      "version": "1.10.0",
       "devDependencies": {
         "esbuild": "^0.25.12",
         "qrcode": "^1.5.4"

plugin/dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-relay-dashboard",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "private": true,
   "description": "Hermes-Relay dashboard plugin frontend (IIFE bundle). Loaded verbatim by the hermes-agent dashboard via the Plugin SDK global.",
   "scripts": {

plugin/dashboard/plugin_api.py

@@ -2,9 +2,10 @@
 
 Loopback-only; mounted by hermes-agent at ``/api/plugins/hermes-relay/*``.
 
-Each route is a thin pass-through to the already-running relay HTTP server
-on ``127.0.0.1:{HERMES_RELAY_PORT}``. No business logic lives here — the
-relay stays the source of truth.
+Most routes are thin pass-throughs to the already-running relay HTTP server
+on ``127.0.0.1:{HERMES_RELAY_PORT}``. Provider usage is the deliberate
+exception: the Dashboard process owns the live Gateway session and can resolve
+its active credential without waiting for another turn.
 
 Route map
 ---------
@@ -13,6 +14,7 @@ Route map
 - ``GET /bridge-activity``  → relay ``GET /bridge/activity`` (forwards ``limit``)
 - ``GET /media``            → relay ``GET /media/inspect`` (forwards ``include_expired``)
 - ``GET /agent-context``    → relay ``GET /context/injected`` + local env settings
+- ``GET /provider-usage``   → live-session-aware provider usage from this plugin
 - ``GET /push``             → static stub (no network call) until FCM is wired
 
 Error translation
@@ -236,6 +238,44 @@ async def get_agent_context() -> dict[str, Any]:
     }
 
 
+@router.get("/provider-usage")
+async def get_provider_usage(
+    profile: Optional[str] = Query(default=None),
+    session_id: Optional[str] = Query(default=None),
+) -> dict[str, Any]:
+    """Return provider usage with the live session's active pool entry.
+
+    This route runs inside the Dashboard process that owns ``tui_gateway``.
+    Unlike the standalone Relay server, it can read the already-instantiated
+    agent directly and therefore does not need a new turn to learn which
+    credential is active.
+    """
+    provider_usage = _plugin_module("relay.provider_usage")
+    hooks = _plugin_module("hooks")
+    try:
+        profile_home = provider_usage.resolve_profile_home(
+            str(_hermes_home() / "config.yaml"),
+            profile,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    active_credential_id = None
+    live = hooks.resolve_live_active_credential(session_id or "")
+    if (
+        isinstance(live, dict)
+        and live.get("provider_id") == "openai-codex"
+        and FsPath(live.get("profile_home")).resolve() == profile_home
+    ):
+        active_credential_id = str(live.get("credential_id") or "") or None
+
+    return await provider_usage.collect_provider_usage(
+        profile_home=profile_home,
+        session_id=session_id,
+        active_credential_id=active_credential_id,
+    )
+
+
 @router.get("/phone/config")
 async def get_phone_config() -> dict[str, Any]:
     """Phone-platform home-channel config for the Management tab.

plugin/dashboard/src/components/MobileConnectDialog.jsx

@@ -76,7 +76,7 @@ export default function MobileConnectDialog({ open, onClose }) {
               Connect mobile app
             </h2>
             <p id="hr-mobile-connect-description" className="text-sm text-muted-foreground mt-1">
-              Scan this from Hermes Relay to add this Dashboard.
+              Scan with Hermes-Relay Android to add this Dashboard.
             </p>
           </div>
           <Button

plugin/dashboard/src/components/PairDialog.jsx

@@ -235,7 +235,7 @@ export default function PairDialog({ open, onClose }) {
           <div>
             <h2 id="hr-pair-dialog-title" className="hr-modal-title">Pair new device</h2>
             <p className="text-sm text-muted-foreground mt-1">
-              Scan from the Hermes-Relay Android app to pair.
+              Scan with Hermes-Relay Android, or copy the invite for Desktop CLI.
             </p>
           </div>
           <Button variant="ghost" size="sm" className="hr-modal-close" onClick={onClose}>

plugin/dashboard/src/index.jsx

@@ -75,7 +75,7 @@ function RelayPluginRoot() {
         <div>
           <h1 className="text-2xl font-semibold">Relay</h1>
           <p className="text-sm text-muted-foreground">
-            Paired devices, bridge activity, media, and remote access for hermes-relay.
+            Connect clients and manage Relay sessions, activity, media, and remote access.
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-3">

plugin/dashboard/test_plugin_api.py

@@ -7,8 +7,10 @@ Uses FastAPI's ``TestClient`` + ``httpx.MockTransport`` patched over
 from __future__ import annotations
 
 import unittest
+from pathlib import Path
+from types import SimpleNamespace
 from typing import Callable, Optional
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
 
 import httpx
 from fastapi import FastAPI
@@ -96,6 +98,41 @@ class SessionsTests(PluginApiTestCase):
         self.assertEqual(resp.json(), payload)
 
 
+class ProviderUsageTests(PluginApiTestCase):
+    def test_reads_active_credential_from_live_dashboard_session(self) -> None:
+        profile_home = Path("/profiles/victor").resolve()
+        provider_usage = SimpleNamespace(
+            resolve_profile_home=lambda _config, _profile: profile_home,
+            collect_provider_usage=AsyncMock(
+                return_value={"schema_version": 2, "providers": []}
+            ),
+        )
+        hooks = SimpleNamespace(
+            resolve_live_active_credential=lambda _session: {
+                "profile_home": profile_home,
+                "provider_id": "openai-codex",
+                "credential_id": "entry-2",
+            }
+        )
+
+        with patch.object(
+            plugin_api,
+            "_plugin_module",
+            side_effect=lambda name: hooks if name == "hooks" else provider_usage,
+        ):
+            response = self.client.get(
+                "/provider-usage",
+                params={"profile": "victor", "session_id": "session-2"},
+            )
+
+        self.assertEqual(response.status_code, 200)
+        provider_usage.collect_provider_usage.assert_awaited_once_with(
+            profile_home=profile_home,
+            session_id="session-2",
+            active_credential_id="entry-2",
+        )
+
+
 class BridgeActivityTests(PluginApiTestCase):
     def test_limit_param_is_forwarded(self) -> None:
         def handler(request: httpx.Request) -> httpx.Response:

plugin/hooks.py

@@ -1,8 +1,9 @@
 """Lifecycle hooks for the hermes-relay plugin.
 
-Registered via ``ctx.register_hook(...)``. There is exactly one hook here:
-``on_session_start``, which performs a single fast, fully-guarded loopback
-probe of the relay's ``/health`` endpoint and caches the result.
+Registered via ``ctx.register_hook(...)``. Session-start performs a single
+fast, fully-guarded loopback health probe. Turn-boundary hooks also persist the
+stable credential-pool entry selected by the live Gateway session so Relay can
+report the correct account without ever receiving its token.
 
 IMPORTANT — runs in the gateway process
 ---------------------------------------
@@ -30,6 +31,7 @@ import logging
 import time
 import urllib.error
 import urllib.request
+from pathlib import Path
 from typing import Any, Dict, Optional
 
 logger = logging.getLogger(__name__)
@@ -113,6 +115,94 @@ def on_session_start(**kwargs: Any) -> None:
     return None
 
 
+def resolve_live_active_credential(session_id: str) -> dict[str, Any] | None:
+    """Resolve a live Gateway session's active credential without exposing it."""
+    session_id = str(session_id or "").strip()
+    if not session_id:
+        return None
+    try:
+        from tui_gateway import server as gateway_server
+
+        sessions = getattr(gateway_server, "_sessions", {})
+
+        def resolve_record():
+            direct = sessions.get(session_id)
+            if isinstance(direct, dict):
+                return session_id, direct
+            for gateway_id, candidate in sessions.items():
+                if not isinstance(candidate, dict):
+                    continue
+                agent = candidate.get("agent")
+                aliases = {
+                    str(candidate.get("session_key") or ""),
+                    str(getattr(agent, "session_id", "") or ""),
+                }
+                if session_id in aliases:
+                    return str(gateway_id), candidate
+            return None, None
+
+        lock = getattr(gateway_server, "_sessions_lock", None)
+        if lock is None:
+            gateway_id, record = resolve_record()
+        else:
+            with lock:
+                gateway_id, record = resolve_record()
+        if not isinstance(record, dict):
+            return None
+        agent = record.get("agent")
+        credential_id = str(getattr(agent, "_credential_pool_entry_id", "") or "").strip()
+        pool = getattr(agent, "_credential_pool", None)
+        provider_id = str(getattr(pool, "provider", "") or "").strip()
+        if not credential_id or not provider_id:
+            return None
+
+        raw_home = record.get("profile_home")
+        if raw_home:
+            profile_home = Path(raw_home).expanduser().resolve()
+        else:
+            from hermes_constants import get_hermes_home
+
+            profile_home = Path(get_hermes_home()).expanduser().resolve()
+        aliases = {
+            value
+            for value in (
+                session_id,
+                str(gateway_id or ""),
+                str(record.get("session_key") or ""),
+                str(getattr(agent, "session_id", "") or ""),
+            )
+            if value
+        }
+        return {
+            "profile_home": profile_home,
+            "provider_id": provider_id,
+            "credential_id": credential_id,
+            "session_ids": aliases,
+        }
+    except Exception as exc:  # noqa: BLE001 -- live lookup must fail open
+        logger.debug("active credential lookup skipped: %s", exc)
+        return None
+
+
+def capture_active_credential(**kwargs: Any) -> None:
+    """Persist the current live session's stable credential id, if available."""
+    try:
+        resolved = resolve_live_active_credential(str(kwargs.get("session_id") or ""))
+        if resolved is None:
+            return None
+        from .relay.active_credentials import record_active_credential_aliases
+
+        record_active_credential_aliases(
+            resolved["profile_home"],
+            session_ids=resolved["session_ids"],
+            provider_id=resolved["provider_id"],
+            credential_id=resolved["credential_id"],
+        )
+    except Exception as exc:  # noqa: BLE001 -- this hook must always fail open
+        logger.debug("active credential capture skipped: %s", exc)
+    return None
+
+
 def register_hooks(ctx) -> None:
     """Register the ``on_session_start`` hook with the plugin host.
 
@@ -121,5 +211,11 @@ def register_hooks(ctx) -> None:
     """
     try:
         ctx.register_hook("on_session_start", on_session_start)
-    except (AttributeError, TypeError) as exc:
+    except (AttributeError, TypeError, ValueError) as exc:
         logger.debug("register_hook unavailable; skipping on_session_start: %s", exc)
+        return
+    for hook_name in ("pre_llm_call", "post_llm_call"):
+        try:
+            ctx.register_hook(hook_name, capture_active_credential)
+        except (AttributeError, TypeError, ValueError) as exc:
+            logger.debug("register_hook unavailable; skipping %s: %s", hook_name, exc)

plugin/plugin.yaml

@@ -1,6 +1,6 @@
 name: hermes-relay
 manifest_version: 1
-version: 1.9.0
+version: 1.10.0
 description: "Hermes-Relay plugin for QR pairing, relay sessions, dashboard management, remote desktop/phone tooling, and optional legacy compatibility diagnostics. Standard chat, Manage, and dashboard voice remain vanilla upstream Hermes surfaces."
 author: Axiom Labs
 # All three are OPTIONAL — only needed if you use the relay's extra /

plugin/relay/__init__.py

@@ -19,7 +19,7 @@ See ``plugin/relay/server.py`` for the aiohttp server,
 # CLI+UI releases use desktop/package.json and desktop-v* tags. The /health endpoint
 # reports this plugin version, and stale values make live diagnosis harder than
 # it should be.
-__version__ = "1.9.0"
+__version__ = "1.10.0"
 
 from .server import create_app, main  # noqa: E402 — must come after __version__
 

plugin/relay/active_credentials.py

@@ -0,0 +1,144 @@
+"""Secret-free active credential snapshots shared by Gateway hooks and Relay.
+
+The Gateway and Relay server commonly run in separate processes.  Hooks record
+only the stable pool-entry id selected by a live session; provider tokens never
+leave the owning Gateway process.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from pathlib import Path
+from collections.abc import Iterable
+from typing import Any
+
+_STATE_FILE = "hermes-relay-active-credentials.json"
+_MAX_SESSIONS = 64
+_MAX_AGE_SECONDS = 7 * 24 * 60 * 60
+_LOCK = threading.Lock()
+
+
+def state_path(profile_home: Path) -> Path:
+    return profile_home / _STATE_FILE
+
+
+def _read(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError, TypeError):
+        return {"schema_version": 1, "sessions": {}}
+    sessions = payload.get("sessions") if isinstance(payload, dict) else None
+    return {
+        "schema_version": 1,
+        "sessions": sessions if isinstance(sessions, dict) else {},
+    }
+
+
+def record_active_credential(
+    profile_home: Path,
+    *,
+    session_id: str,
+    provider_id: str,
+    credential_id: str,
+) -> None:
+    """Atomically record a bounded, secret-free active credential mapping."""
+    record_active_credential_aliases(
+        profile_home,
+        session_ids=(session_id,),
+        provider_id=provider_id,
+        credential_id=credential_id,
+    )
+
+
+def record_active_credential_aliases(
+    profile_home: Path,
+    *,
+    session_ids: Iterable[str],
+    provider_id: str,
+    credential_id: str,
+) -> None:
+    """Atomically map every authoritative Gateway/session alias to one entry."""
+    aliases = {
+        str(session_id or "").strip()[:160]
+        for session_id in session_ids
+        if str(session_id or "").strip()
+    }
+    provider = str(provider_id or "").strip()[:80]
+    credential = str(credential_id or "").strip()[:160]
+    if not aliases or not provider or not credential:
+        return
+
+    path = state_path(profile_home)
+    now = time.time()
+    with _LOCK:
+        payload = _read(path)
+        sessions = payload["sessions"]
+        for session in aliases:
+            sessions[session] = {
+                "provider_id": provider,
+                "credential_id": credential,
+                "observed_at": now,
+            }
+        retained = sorted(
+            (
+                (key, row)
+                for key, row in sessions.items()
+                if isinstance(row, dict)
+                and isinstance(row.get("observed_at"), (int, float))
+                and now - float(row["observed_at"]) <= _MAX_AGE_SECONDS
+            ),
+            key=lambda item: float(item[1]["observed_at"]),
+            reverse=True,
+        )[:_MAX_SESSIONS]
+        payload["sessions"] = dict(retained)
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, raw_tmp = tempfile.mkstemp(prefix=f".{_STATE_FILE}.", dir=str(path.parent))
+        tmp = Path(raw_tmp)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(payload, handle, separators=(",", ":"), sort_keys=True)
+                handle.flush()
+                os.fsync(handle.fileno())
+            try:
+                os.chmod(tmp, 0o600)
+            except OSError:
+                pass
+            os.replace(tmp, path)
+            try:
+                os.chmod(path, 0o600)
+            except OSError:
+                pass
+        finally:
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def read_active_credential(
+    profile_home: Path,
+    *,
+    session_id: str | None,
+    provider_id: str,
+) -> dict[str, Any] | None:
+    """Return the exact session mapping, or ``None`` when it is not proven."""
+    session = str(session_id or "").strip()
+    if not session:
+        return None
+    row = _read(state_path(profile_home))["sessions"].get(session)
+    if not isinstance(row, dict) or row.get("provider_id") != provider_id:
+        return None
+    observed_at = row.get("observed_at")
+    if not isinstance(observed_at, (int, float)):
+        return None
+    if time.time() - float(observed_at) > _MAX_AGE_SECONDS:
+        return None
+    credential_id = str(row.get("credential_id") or "").strip()
+    if not credential_id:
+        return None
+    return {"credential_id": credential_id, "observed_at": float(observed_at)}

plugin/relay/config.py

@@ -102,6 +102,11 @@ class RelayConfig:
     trust_proxy_headers: bool = False
     allow_insecure_api_bearer: bool = False
 
+    # Provider-account usage can expose billing and quota metadata to paired
+    # devices. Provider credentials alone are not consent to that disclosure;
+    # operators must explicitly enable the read-only mobile surface.
+    provider_usage_enabled: bool = False
+
     # Provider-neutral voice output broker. This is the default assistant
     # speech renderer: final Hermes text goes in, streamed provider PCM comes
     # out. Realtime providers remain available separately as agent-mode tests.
@@ -160,6 +165,12 @@ class RelayConfig:
     @classmethod
     def from_env(cls) -> RelayConfig:
         """Build config from environment variables, falling back to defaults."""
+        hermes_home = (os.getenv("HERMES_HOME") or "").strip()
+        default_hermes_config = (
+            str(Path(hermes_home).expanduser() / "config.yaml")
+            if hermes_home
+            else cls.hermes_config_path
+        )
         config = cls(
             host=os.getenv("RELAY_HOST", cls.host),
             port=int(os.getenv("RELAY_PORT", str(cls.port))),
@@ -167,7 +178,7 @@ class RelayConfig:
             ssl_key=os.getenv("RELAY_SSL_KEY"),
             webapi_url=os.getenv("RELAY_WEBAPI_URL", cls.webapi_url),
             hermes_config_path=os.getenv(
-                "RELAY_HERMES_CONFIG", cls.hermes_config_path
+                "RELAY_HERMES_CONFIG", default_hermes_config
             ),
             log_level=os.getenv("RELAY_LOG_LEVEL", cls.log_level),
             terminal_shell=os.getenv("RELAY_TERMINAL_SHELL") or None,
@@ -283,6 +294,12 @@ class RelayConfig:
         if insecure_api_bearer in ("1", "true", "yes", "on"):
             config.allow_insecure_api_bearer = True
 
+        provider_usage = os.getenv(
+            "RELAY_PROVIDER_USAGE_ENABLED", ""
+        ).strip().lower()
+        if provider_usage in ("1", "true", "yes", "on"):
+            config.provider_usage_enabled = True
+
         apply_voice_output_config_file(config)
         apply_realtime_voice_config_file(config)
 

plugin/relay/provider_usage.py

@@ -0,0 +1,531 @@
+"""Provider-neutral account usage snapshots for paired mobile clients.
+
+Hermes already owns provider credentials and the canonical account-usage model.
+Relay reuses that model, adds credential-pool and balance structure for Android,
+and supplies the missing OpenCode Go adapter. Provider keys remain host-side
+and are never serialized into the response.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import math
+import re
+from urllib.parse import urlparse
+from pathlib import Path
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable
+
+import aiohttp
+
+SCHEMA_VERSION = 2
+RELAY_CAPABILITIES = (
+    "credential_pools",
+    "structured_balances",
+    "opencode_go",
+)
+_OPENCODE_GO_DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1"
+_OPENCODE_GO_USER_AGENT = "curl/8.4.0"
+_MAX_DETAIL_LENGTH = 240
+_PROFILE_ID = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+
+def resolve_profile_home(config_path: str, requested_profile: str | None) -> Path:
+    """Resolve an exact Hermes profile home without mutating process globals."""
+    root = Path(config_path).expanduser().resolve().parent
+    profile = str(requested_profile or "").strip().lower()
+    if profile in {"", "default"}:
+        try:
+            active = (root / "active_profile").read_text(encoding="utf-8").strip().lower()
+        except (OSError, UnicodeError):
+            active = ""
+        if _PROFILE_ID.fullmatch(active):
+            candidate = (root / "profiles" / active).resolve()
+            if candidate.parent == (root / "profiles").resolve() and (candidate / "config.yaml").is_file():
+                return candidate
+        return root
+    if not _PROFILE_ID.fullmatch(profile):
+        raise ValueError("invalid profile")
+    candidate = (root / "profiles" / profile).resolve()
+    if candidate.parent != (root / "profiles").resolve() or not (candidate / "config.yaml").is_file():
+        raise ValueError("unknown profile")
+    return candidate
+
+
+def _set_home(profile_home: Path | None):
+    if profile_home is None:
+        return None
+    from hermes_constants import set_hermes_home_override
+
+    return set_hermes_home_override(profile_home)
+
+
+def _reset_home(token) -> None:
+    if token is None:
+        return
+    from hermes_constants import reset_hermes_home_override
+
+    reset_hermes_home_override(token)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _bounded_text(value: Any, limit: int = _MAX_DETAIL_LENGTH) -> str | None:
+    text = str(value or "").strip()
+    return text[:limit] if text else None
+
+
+def _iso(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        dt = value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+        return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    return _bounded_text(value, 80)
+
+
+def _iso_epoch(value: Any) -> str | None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        try:
+            return _iso(datetime.fromtimestamp(float(value), timezone.utc))
+        except (OverflowError, OSError, ValueError):
+            return None
+    return _iso(value)
+
+
+def unavailable_provider(
+    provider_id: str,
+    display_name: str,
+    *,
+    status: str = "not_configured",
+    message: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "id": provider_id,
+        "display_name": display_name,
+        "status": status,
+        "source": None,
+        "fetched_at": None,
+        "plan": None,
+        "windows": [],
+        "details": [],
+        "balances": [],
+        "renews_at": None,
+        "action_url": None,
+        "credentials": [],
+        "active_credential_id": None,
+        "active_credential_state": "unknown",
+        "message": _bounded_text(message),
+    }
+
+
+def serialize_account_snapshot(
+    snapshot: Any,
+    *,
+    provider_id: str,
+    display_name: str,
+) -> dict[str, Any]:
+    """Serialize upstream ``AccountUsageSnapshot`` without provider secrets."""
+    if snapshot is None or not bool(getattr(snapshot, "available", False)):
+        return unavailable_provider(provider_id, display_name)
+
+    windows: list[dict[str, Any]] = []
+    for index, window in enumerate(tuple(getattr(snapshot, "windows", ()) or ())[:8]):
+        raw_percent = getattr(window, "used_percent", None)
+        percent: float | None = None
+        if isinstance(raw_percent, (int, float)) and not isinstance(raw_percent, bool):
+            if math.isfinite(float(raw_percent)):
+                percent = max(0.0, min(100.0, float(raw_percent)))
+        label = _bounded_text(getattr(window, "label", None), 60) or f"Window {index + 1}"
+        windows.append(
+            {
+                "id": label.lower().replace(" ", "_")[:40],
+                "label": label,
+                "used_percent": percent,
+                "reset_at": _iso(getattr(window, "reset_at", None)),
+                "detail": _bounded_text(getattr(window, "detail", None)),
+            }
+        )
+
+    details = [
+        text
+        for item in tuple(getattr(snapshot, "details", ()) or ())[:8]
+        if (text := _bounded_text(item)) is not None
+    ]
+    return {
+        "id": provider_id,
+        "display_name": display_name,
+        "status": "available",
+        "source": _bounded_text(getattr(snapshot, "source", None), 60),
+        "fetched_at": _iso(getattr(snapshot, "fetched_at", None)) or _now_iso(),
+        "plan": _bounded_text(getattr(snapshot, "plan", None), 80),
+        "windows": windows,
+        "details": details,
+        "balances": [],
+        "renews_at": None,
+        "action_url": None,
+        "credentials": [],
+        "active_credential_id": None,
+        "active_credential_state": "unknown",
+        "message": None,
+    }
+
+
+def _public_credential_id(credential_id: str) -> str:
+    return hashlib.sha256(credential_id.encode("utf-8")).hexdigest()[:12]
+
+
+def _effective_credential_status(entry: Any, snapshot: Any) -> str:
+    pool_status = str(getattr(entry, "last_status", "") or "").lower()
+    if pool_status in {"dead", "invalid"}:
+        return "unavailable"
+    if pool_status in {"exhausted", "rate_limited", "cooldown"}:
+        return "at_limit"
+    windows = tuple(getattr(snapshot, "windows", ()) or ()) if snapshot is not None else ()
+    if any(float(getattr(window, "used_percent", 0) or 0) >= 100 for window in windows):
+        return "at_limit"
+    return "available" if bool(getattr(snapshot, "available", False)) else "unavailable"
+
+
+async def fetch_codex_usage(
+    profile_home: Path | None = None,
+    *,
+    session_id: str | None = None,
+    active_credential_id: str | None = None,
+    snapshot_fetcher: Callable[..., Any] | None = None,
+    pool_loader: Callable[[str], Any] | None = None,
+) -> dict[str, Any]:
+    token = _set_home(profile_home)
+    try:
+        if pool_loader is None:
+            from agent.credential_pool import load_pool
+
+            pool_loader = load_pool
+
+        entries = pool_loader("openai-codex").entries()[:8]
+    except Exception:
+        return unavailable_provider(
+            "openai-codex",
+            "Codex",
+            status="unavailable",
+            message="Could not load Codex usage",
+        )
+    finally:
+        _reset_home(token)
+
+    if not entries:
+        return unavailable_provider("openai-codex", "Codex")
+    if snapshot_fetcher is None:
+        from agent.account_usage import _fetch_codex_account_usage
+
+        snapshot_fetcher = _fetch_codex_account_usage
+
+    def fetch_entry_snapshot(entry: Any) -> Any:
+        entry_token = _set_home(profile_home)
+        try:
+            return snapshot_fetcher(
+                base_url=getattr(entry, "runtime_base_url", None),
+                api_key=entry.runtime_api_key,
+            )
+        finally:
+            _reset_home(entry_token)
+
+    async def fetch_entry(entry: Any) -> tuple[Any, Any]:
+        try:
+            snapshot = await asyncio.to_thread(fetch_entry_snapshot, entry)
+            return entry, snapshot
+        except Exception:
+            return entry, None
+
+    fetched = await asyncio.gather(*(fetch_entry(entry) for entry in entries))
+    active_mapping = None
+    if active_credential_id:
+        active_raw_id = str(active_credential_id).strip()
+    elif profile_home is not None:
+        from .active_credentials import read_active_credential
+
+        active_mapping = read_active_credential(
+            profile_home,
+            session_id=session_id,
+            provider_id="openai-codex",
+        )
+        active_raw_id = active_mapping["credential_id"] if active_mapping else None
+    else:
+        active_raw_id = None
+    if active_raw_id not in {str(getattr(entry, "id", "")) for entry, _ in fetched}:
+        active_raw_id = None
+
+    active_state = "known" if active_raw_id else "unknown"
+    if len(fetched) == 1 and active_raw_id is None:
+        active_raw_id = str(getattr(fetched[0][0], "id", ""))
+        active_state = "single_credential"
+
+    credentials: list[dict[str, Any]] = []
+    active_provider: dict[str, Any] | None = None
+    for index, (entry, snapshot) in enumerate(fetched):
+        raw_id = str(getattr(entry, "id", ""))
+        public_id = _public_credential_id(raw_id)
+        serialized = serialize_account_snapshot(
+            snapshot,
+            provider_id="openai-codex",
+            display_name="Codex",
+        )
+        status = _effective_credential_status(entry, snapshot)
+        credential = {
+            "id": public_id,
+            "label": _bounded_text(getattr(entry, "label", None), 80) or f"Credential {index + 1}",
+            "active": raw_id == active_raw_id,
+            "status": status,
+            "pool_status": _bounded_text(getattr(entry, "last_status", None), 40),
+            "last_status_at": _iso_epoch(getattr(entry, "last_status_at", None)),
+            "reset_at": _iso_epoch(getattr(entry, "last_error_reset_at", None)),
+            "plan": serialized["plan"],
+            "windows": serialized["windows"],
+            "details": serialized["details"],
+            "message": serialized["message"],
+        }
+        credentials.append(credential)
+        if credential["active"]:
+            active_provider = serialized
+
+    available_count = sum(row["status"] == "available" for row in credentials)
+    limited_count = sum(row["status"] == "at_limit" for row in credentials)
+    summary = active_provider or {
+        "source": "credential_pool",
+        "fetched_at": _now_iso(),
+        "plan": None,
+        "windows": [],
+        "details": [],
+    }
+    return {
+        "id": "openai-codex",
+        "display_name": "Codex",
+        "status": "available",
+        "source": summary.get("source") or "credential_pool",
+        "fetched_at": summary.get("fetched_at") or _now_iso(),
+        "plan": summary.get("plan"),
+        "windows": summary.get("windows", []),
+        "details": [
+            f"{available_count} available · {limited_count} at limit · {len(credentials)} total"
+        ],
+        "credentials": credentials,
+        "active_credential_id": (
+            _public_credential_id(active_raw_id) if active_raw_id else None
+        ),
+        "active_credential_state": active_state,
+        "active_observed_at": (
+            _iso(datetime.fromtimestamp(active_mapping["observed_at"], timezone.utc))
+            if active_mapping and active_state == "known"
+            else None
+        ),
+        "message": None,
+    }
+
+
+async def fetch_nous_usage(
+    profile_home: Path | None = None,
+    *,
+    account_fetcher: Callable[..., Any] | None = None,
+) -> dict[str, Any]:
+    token = _set_home(profile_home)
+    try:
+        from agent.account_usage import build_nous_credits_snapshot
+        from hermes_cli.nous_account import get_nous_portal_account_info, nous_portal_topup_url
+
+        if account_fetcher is None:
+            account_fetcher = get_nous_portal_account_info
+
+        account = await asyncio.to_thread(account_fetcher, force_fresh=True)
+        snapshot = build_nous_credits_snapshot(account)
+        result = serialize_account_snapshot(
+            snapshot,
+            provider_id="nous",
+            display_name="Nous",
+        )
+        if not result["status"] == "available":
+            return result
+
+        def balance(balance_id: str, label: str, value: Any) -> dict[str, Any] | None:
+            if not isinstance(value, (int, float)) or isinstance(value, bool):
+                return None
+            amount = float(value)
+            if not math.isfinite(amount):
+                return None
+            return {"id": balance_id, "label": label, "amount": amount, "currency": "USD"}
+
+        access = getattr(account, "paid_service_access_info", None)
+        subscription = getattr(account, "subscription", None)
+        result["balances"] = [
+            item
+            for item in (
+                balance("total", "Total usable", getattr(access, "total_usable_credits", None)),
+                balance(
+                    "subscription",
+                    "Subscription",
+                    getattr(access, "subscription_credits_remaining", None),
+                ),
+                balance(
+                    "top_up",
+                    "Top-up",
+                    getattr(access, "purchased_credits_remaining", None),
+                ),
+                balance("rollover", "Rollover", getattr(subscription, "rollover_credits", None)),
+            )
+            if item is not None
+        ]
+        result["renews_at"] = _iso(getattr(subscription, "current_period_end", None))
+        action_url = _bounded_text(nous_portal_topup_url(account), 500)
+        parsed_action = urlparse(action_url or "")
+        result["action_url"] = (
+            action_url if parsed_action.scheme in {"http", "https"} and parsed_action.netloc else None
+        )
+        # Structured fields own mobile presentation. Preserve only genuinely
+        # additional status lines; never render raw URLs or ISO timestamps.
+        result["details"] = [
+            detail for detail in result["details"] if detail.startswith("Status:")
+        ]
+        return result
+    except Exception:
+        return unavailable_provider(
+            "nous",
+            "Nous",
+            status="unavailable",
+            message="Could not load Nous usage",
+        )
+    finally:
+        _reset_home(token)
+
+
+async def fetch_opencode_go_usage(
+    *,
+    profile_home: Path | None = None,
+    session_factory: Callable[[], Any] = aiohttp.ClientSession,
+    credential_resolver: Callable[[str], dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    token = _set_home(profile_home)
+    try:
+        if credential_resolver is None:
+            from hermes_cli.auth import resolve_api_key_provider_credentials
+
+            credential_resolver = resolve_api_key_provider_credentials
+
+        credentials = await asyncio.to_thread(
+            credential_resolver,
+            "opencode-go",
+        )
+    except Exception:
+        credentials = {}
+    finally:
+        _reset_home(token)
+    api_key = str(credentials.get("api_key") or "").strip()
+    if not api_key:
+        return unavailable_provider("opencode-go", "OpenCode Go")
+
+    base_url = str(credentials.get("base_url") or _OPENCODE_GO_DEFAULT_BASE_URL).rstrip("/")
+    try:
+        async with session_factory() as session:
+            async with session.get(
+                f"{base_url}/usage",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "User-Agent": _OPENCODE_GO_USER_AGENT,
+                },
+                timeout=aiohttp.ClientTimeout(total=15),
+            ) as response:
+                if response.status != 200:
+                    return unavailable_provider(
+                        "opencode-go",
+                        "OpenCode Go",
+                        status="unavailable",
+                        message=f"Provider returned HTTP {response.status}",
+                    )
+                payload = await response.json()
+    except (aiohttp.ClientError, asyncio.TimeoutError, ValueError, TypeError):
+        return unavailable_provider(
+            "opencode-go",
+            "OpenCode Go",
+            status="unavailable",
+            message="Could not load OpenCode Go usage",
+        )
+
+    usage = payload.get("usage") if isinstance(payload, dict) else None
+    if not isinstance(usage, dict):
+        return unavailable_provider(
+            "opencode-go",
+            "OpenCode Go",
+            status="unavailable",
+            message="Provider returned an unsupported usage payload",
+        )
+
+    windows: list[dict[str, Any]] = []
+    for key, label in (
+        ("rolling", "Session · 5h"),
+        ("weekly", "Weekly"),
+        ("monthly", "Monthly"),
+    ):
+        raw = usage.get(key)
+        if not isinstance(raw, dict):
+            continue
+        raw_percent = raw.get("percent")
+        if not isinstance(raw_percent, (int, float)) or isinstance(raw_percent, bool):
+            continue
+        percent = float(raw_percent)
+        if not math.isfinite(percent):
+            continue
+        windows.append(
+            {
+                "id": key,
+                "label": label,
+                "used_percent": max(0.0, min(100.0, percent)),
+                "reset_at": _iso(raw.get("resetsAt")),
+                "detail": None,
+            }
+        )
+
+    if not windows:
+        return unavailable_provider(
+            "opencode-go",
+            "OpenCode Go",
+            status="unavailable",
+            message="Provider returned no usage windows",
+        )
+    return {
+        "id": "opencode-go",
+        "display_name": "OpenCode Go",
+        "status": "available",
+        "source": "provider_api",
+        "fetched_at": _now_iso(),
+        "plan": None,
+        "windows": windows,
+        "details": [],
+        "message": None,
+    }
+
+
+async def collect_provider_usage(
+    *,
+    profile_home: Path | None = None,
+    session_id: str | None = None,
+    active_credential_id: str | None = None,
+    codex_fetcher: Callable[..., Awaitable[dict[str, Any]]] = fetch_codex_usage,
+    nous_fetcher: Callable[[Path | None], Awaitable[dict[str, Any]]] = fetch_nous_usage,
+    opencode_fetcher: Callable[..., Awaitable[dict[str, Any]]] = fetch_opencode_go_usage,
+) -> dict[str, Any]:
+    providers = await asyncio.gather(
+        codex_fetcher(
+            profile_home,
+            session_id=session_id,
+            active_credential_id=active_credential_id,
+        ),
+        nous_fetcher(profile_home),
+        opencode_fetcher(profile_home=profile_home),
+    )
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "fetched_at": _now_iso(),
+        "capabilities": list(RELAY_CAPABILITIES),
+        "providers": providers,
+    }

plugin/relay/server.py

@@ -93,6 +93,7 @@ from .model_capabilities import (
     ModelCapabilityResolver,
     SCHEMA_VERSION as MODEL_CAPABILITIES_SCHEMA_VERSION,
 )
+from .provider_usage import collect_provider_usage, resolve_profile_home
 from .session_store import read_phone_threads
 from .voice import VoiceHandler
 from .voice_output import VoiceOutputHandler
@@ -1172,6 +1173,27 @@ async def handle_sessions_extend(request: web.Request) -> web.Response:
     )
 
 
+async def handle_provider_usage(request: web.Request) -> web.Response:
+    """Return provider-neutral account usage to an authenticated paired device."""
+    _require_bearer_session(request)
+    server: RelayServer = request.app["server"]
+    if not server.config.provider_usage_enabled:
+        raise web.HTTPNotFound(text="provider usage is not enabled on this host")
+    try:
+        profile_home = resolve_profile_home(
+            server.config.hermes_config_path,
+            request.query.get("profile"),
+        )
+    except ValueError as exc:
+        raise web.HTTPBadRequest(text="invalid or unknown profile") from exc
+    return web.json_response(
+        await collect_provider_usage(
+            profile_home=profile_home,
+            session_id=request.query.get("session_id"),
+        )
+    )
+
+
 # ── Desktop tool dispatch (loopback HTTP shim for desktop_tool.py) ──────────
 
 
@@ -4682,6 +4704,7 @@ def create_app(config: RelayConfig) -> web.Application:
     app.router.add_get("/sessions", handle_sessions_list)
     app.router.add_delete("/sessions/{token_prefix}", handle_sessions_revoke)
     app.router.add_patch("/sessions/{token_prefix}", handle_sessions_extend)
+    app.router.add_get("/usage/providers", handle_provider_usage)
     app.router.add_get("/chat/image-activity", handle_image_activity)
     # Desktop tool dispatch — HTTP shim called by `plugin/tools/desktop_tool.py`
     # running inside hermes-gateway. Both endpoints loopback-only.