Merge pull request #333 from Codename-11/dev

release(server): server-v1.6.3
fix(android): complete upstream feature translations
2026-08-11 22:00:43 -04:00 · 2026-08-11 21:46:45 -04:00 · 2026-08-11 21:37:54 -04:00 · 2026-08-11 21:35:40 -04:00 · 2026-08-11 21:35:05 -04:00 · 2026-08-11 20:50:36 -04:00
567 changed files with 73316 additions and 6707 deletions
@@ -89,7 +89,7 @@ jobs:
          VERSION: ${{ steps.metadata.outputs.version }}
        run: |
          gh workflow run release-android.yml \
-            --ref="android-v${VERSION}" \
+            --ref=main \
            -f version="$VERSION"

      - name: Approval summary
@@ -97,4 +97,4 @@ jobs:
          echo "## Android release approved" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "Created \`android-v${{ steps.metadata.outputs.version }}\` from main at \`$GITHUB_SHA\`." >> "$GITHUB_STEP_SUMMARY"
-          echo "The release workflow was dispatched at that tag. It will submit the preflighted Play draft before creating the public GitHub Release." >> "$GITHUB_STEP_SUMMARY"
+          echo "The current release workflow was dispatched from main and will check out that immutable tag. It will submit the preflighted Play draft before creating the public GitHub Release." >> "$GITHUB_STEP_SUMMARY"
@@ -63,7 +63,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}

@@ -95,7 +95,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}

@@ -139,7 +139,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}

@@ -203,7 +203,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}

@@ -100,13 +100,15 @@ jobs:
        with:
          node-version: '22'
          cache: npm
-          cache-dependency-path: desktop/package-lock.json
+          cache-dependency-path: |
+            desktop/package-lock.json
+            desktop/tray/package-lock.json

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install deps
-        run: npm ci
+        run: npm ci && npm --prefix tray ci

      - name: Check tray formatting
        run: npm run tray:fmt
@@ -1,65 +0,0 @@
-name: Issue Triage
-
-on:
-  issues:
-    types: [opened]
-  workflow_dispatch:
-    inputs:
-      issue_number:
-        description: "Issue number to label again"
-        required: true
-        type: string
-
-concurrency:
-  group: issue-triage-${{ github.event.issue.number || github.event.inputs.issue_number }}
-  cancel-in-progress: false
-
-permissions:
-  contents: read
-  issues: write
-
-jobs:
-  auto-label:
-    if: >
-      github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'issues' && github.event.issue.user.type != 'Bot')
-    runs-on: ubuntu-latest
-    steps:
-      - name: Label from title prefix and issue area
-        uses: actions/github-script@v8
-        env:
-          ISSUE_NUMBER: ${{ github.event.issue.number || github.event.inputs.issue_number }}
-        with:
-          script: |
-            const issue_number = Number(process.env.ISSUE_NUMBER);
-            const { data: issue } = await github.rest.issues.get({
-              owner: context.repo.owner, repo: context.repo.repo, issue_number,
-            });
-            const title = (issue.title || '').toLowerCase();
-            const body = (issue.body || '').toLowerCase();
-            const haystack = `${title}\n${body}`;
-            const labels = [];
-
-            if (title.startsWith('[bug]')) labels.push('bug');
-            else if (title.startsWith('[feature]') || title.startsWith('[feat]')) labels.push('enhancement');
-            else if (title.startsWith('[docs]')) labels.push('documentation');
-
-            if (/\b(cli|desktop|terminal|daemon|pty|hermes-relay (install|binary|tray))\b/.test(haystack)) labels.push('area:cli');
-            else if (/\b(dashboard|plugin ui|react)\b/.test(haystack)) labels.push('area:dashboard');
-            else if (/\b(relay|plugin|aiohttp|python|pairing|voice (transcribe|synthesize)|bridge (endpoint|route))\b/.test(haystack)) labels.push('area:plugin');
-            else if (/\b(readme|user-?docs|documentation)\b/.test(haystack)) labels.push('area:docs');
-            else if (/\b(android|app|compose|apk|phone|samsung|gradle|chat|voice|notification|sphere|keystore)\b/.test(haystack)) labels.push('area:android');
-
-            if (!labels.length) {
-              core.info('No deterministic label matched; leaving the issue for maintainer triage.');
-              return;
-            }
-
-            try {
-              await github.rest.issues.addLabels({
-                owner: context.repo.owner, repo: context.repo.repo, issue_number, labels,
-              });
-              core.info(`Applied labels: ${labels.join(', ')}`);
-            } catch (error) {
-              core.warning(`Could not apply ${labels.join(', ')}: ${error.message}`);
-            }
@@ -76,7 +76,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: false

@@ -74,7 +74,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: false

@@ -12,8 +12,9 @@ on:
    tags:
      - "android-v*"
  # Approve Android Release creates its tag with GITHUB_TOKEN, whose tag event
-  # does not recursively start workflows. It explicitly dispatches this file
-  # at that tag instead. Manual tag pushes continue to use the push trigger.
+  # does not recursively start workflows. It dispatches the current workflow
+  # definition from main, while every job checks out the immutable tag. Manual
+  # tag pushes continue to use the push trigger.
  workflow_dispatch:
    inputs:
      version:
@@ -37,19 +38,22 @@ jobs:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Extract version from tag
        id: version
        env:
          DISPATCHED_VERSION: ${{ inputs.version }}
        run: |
-          REF_VERSION="${GITHUB_REF#refs/tags/android-v}"
-          if [ "$GITHUB_REF" = "$REF_VERSION" ]; then
+          if [ -n "$DISPATCHED_VERSION" ]; then
            REF_VERSION="$DISPATCHED_VERSION"
-          fi
-          if [ -n "$DISPATCHED_VERSION" ] && [ "$DISPATCHED_VERSION" != "$REF_VERSION" ]; then
-            echo "::error::Dispatched version $DISPATCHED_VERSION does not match ref version $REF_VERSION"
-            exit 1
+            TAG_COMMIT=$(git rev-list -n 1 "android-v${REF_VERSION}")
+            if [ -z "$TAG_COMMIT" ] || [ "$TAG_COMMIT" != "$(git rev-parse HEAD)" ]; then
+              echo "::error::Checked-out commit does not match immutable tag android-v${REF_VERSION}"
+              exit 1
+            fi
+          else
+            REF_VERSION="${GITHUB_REF#refs/tags/android-v}"
          fi
          VERSION_CODE=$(grep -oP 'appVersionCode\s*=\s*"\K[^"]+' gradle/libs.versions.toml)
          echo "version=$REF_VERSION" >> "$GITHUB_OUTPUT"
@@ -67,8 +71,8 @@ jobs:
            echo "::error::Tag version ($TAG_VERSION) does not match appVersionName ($TOML_VERSION) in gradle/libs.versions.toml"
            exit 1
          fi
-          if ! grep -Fq "## [$TAG_VERSION]" CHANGELOG.md; then
-            echo "::error::CHANGELOG.md has no release heading for $TAG_VERSION"
+          if ! grep -Eq "^## \\[(Android )?${TAG_VERSION}\\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no Android release heading for $TAG_VERSION"
            exit 1
          fi

@@ -111,6 +115,8 @@ jobs:
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Set up JDK 17
        uses: actions/setup-java@v5
@@ -119,7 +125,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: false

@@ -147,6 +153,8 @@ jobs:
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Set up JDK 17
        uses: actions/setup-java@v5
@@ -155,7 +163,7 @@ jobs:
          java-version: 17

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v6
+        uses: gradle/actions/setup-gradle@v6.3.0
        with:
          cache-read-only: false

@@ -183,6 +191,19 @@ jobs:
        #   app/build/outputs/bundle/sideloadRelease/hermes-relay-<version>-sideload-release.aab
        run: ./gradlew bundleRelease assembleRelease

+      # The Play AAB carries its mapping for Play Console deobfuscation, but
+      # sideload issue reports need the exact mapping from this immutable build.
+      # Keep both variants as a workflow artifact (not a public release asset).
+      - name: Retain R8 mappings for retrace
+        uses: actions/upload-artifact@v7
+        with:
+          name: android-r8-mappings-${{ needs.validate.outputs.version }}-${{ github.sha }}
+          path: |
+            app/build/outputs/mapping/googlePlayRelease/mapping.txt
+            app/build/outputs/mapping/sideloadRelease/mapping.txt
+          if-no-files-found: error
+          retention-days: 90
+
      - name: Scan release DEX for unsupported collection APIs
        run: |
          python3 scripts/check-android-collection-apis.py \
@@ -168,7 +168,9 @@ jobs:
        with:
          node-version: '22'
          cache: npm
-          cache-dependency-path: desktop/package-lock.json
+          cache-dependency-path: |
+            desktop/package-lock.json
+            desktop/tray/package-lock.json

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
@@ -179,7 +181,7 @@ jobs:
        uses: dtolnay/rust-toolchain@stable

      - name: Install deps
-        run: npm ci
+        run: npm ci && npm --prefix tray ci

      - name: Type-check
        run: npm run type-check
@@ -213,12 +215,153 @@ jobs:
          $proc = Start-Process -FilePath tray/target/release/hermes-relay-tray.exe -WindowStyle Hidden -PassThru
          Start-Sleep -Seconds 5
          if ($proc.HasExited) { throw "tray app exited early with code $($proc.ExitCode)" }
-          $proc.Refresh()
-          if ($proc.MainWindowHandle -ne 0) { throw 'menu-only systray created an application window' }
          $traySize = (Get-Item tray/target/release/hermes-relay-tray.exe).Length
-          if ($traySize -gt 5242880) { throw "tray executable exceeds 5 MiB: $traySize bytes" }
+          if ($traySize -le 0) { throw 'tray executable is empty' }
          Stop-Process -Id $proc.Id -Force
-          Write-Host "menu-only tray launch smoke OK pid=$($proc.Id) bytes=$traySize"
+          Write-Host "management tray launch smoke OK pid=$($proc.Id) bytes=$traySize"
+
+      - name: Smoke-test packaged installer lifecycle
+        shell: pwsh
+        env:
+          EXPECTED_DESKTOP_VERSION: ${{ needs.validate-release.outputs.version }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          function Normalize-UserPath([string]$Value) {
+            return (@($Value -split ';' | Where-Object { $_ }) -join ';')
+          }
+
+          function Get-RawUserPath {
+            $environmentKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment')
+            if ($null -eq $environmentKey) { return '' }
+            try {
+              return [string]$environmentKey.GetValue(
+                'Path',
+                '',
+                [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames
+              )
+            } finally {
+              $environmentKey.Dispose()
+            }
+          }
+
+          $setup = (Resolve-Path 'dist/tray/hermes-relay-windows-x64-setup.exe').Path
+          $smokeRoot = Join-Path $env:RUNNER_TEMP 'hermes-installer-lifecycle-smoke'
+          $smokeProfile = Join-Path $smokeRoot 'profile'
+          $installDir = Join-Path $smokeRoot 'installed files'
+          $sessionDir = Join-Path $smokeProfile '.hermes'
+          $sessionSentinel = Join-Path $sessionDir 'remote-sessions.json'
+          $uninstaller = Join-Path $installDir 'uninstall-hermes-relay.exe'
+          $uninstallKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\HermesRelay'
+          $productKey = 'HKCU:\Software\HermesRelay'
+          $startupKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Run'
+          $startMenuDir = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Hermes-Relay CLI'
+          $oldUserProfile = $env:USERPROFILE
+          $oldHomeEnv = $env:HOME
+          $environmentKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+          $hadUserPath = $environmentKey.GetValueNames() -contains 'Path'
+          $originalUserPath = Get-RawUserPath
+          $originalUserPathKind = if ($hadUserPath) { $environmentKey.GetValueKind('Path') } else { $null }
+          $userPathBefore = 'C:\Windows\System32'
+          $environmentKey.Dispose()
+          $startupBefore = (Get-ItemProperty -Path $startupKey -Name HermesRelayTray -ErrorAction SilentlyContinue).HermesRelayTray
+
+          if (Test-Path $uninstallKey) { throw 'installer smoke requires a clean HermesRelay uninstall registry key' }
+          if (Test-Path $productKey) { throw 'installer smoke requires a clean HermesRelay product registry key' }
+          if (Test-Path $smokeRoot) { Remove-Item -LiteralPath $smokeRoot -Recurse -Force }
+          New-Item -ItemType Directory -Force -Path $sessionDir | Out-Null
+          Set-Content -LiteralPath $sessionSentinel -Value '{"sentinel":"preserve-me"}' -Encoding UTF8
+
+          $env:USERPROFILE = $smokeProfile
+          $env:HOME = $smokeProfile
+          try {
+            $environmentKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+            $environmentKey.SetValue('Path', $userPathBefore, [Microsoft.Win32.RegistryValueKind]::String)
+            $environmentKey.Dispose()
+
+            $installProcess = Start-Process -FilePath $setup -ArgumentList @('/S', "/D=$installDir") -Wait -PassThru
+            if ($installProcess.ExitCode -ne 0) { throw "installer exited with code $($installProcess.ExitCode)" }
+
+            $expectedFiles = @(
+              'hermes-relay.exe',
+              'hermes-relay-tray.exe',
+              'hermes-relay-ui.cmd',
+              'hermes-relay-path.ps1',
+              'uninstall-hermes-relay.exe'
+            )
+            foreach ($name in $expectedFiles) {
+              $path = Join-Path $installDir $name
+              if (-not (Test-Path -LiteralPath $path -PathType Leaf)) {
+                throw "packaged installer did not create $path"
+              }
+            }
+
+            $cli = Join-Path $installDir 'hermes-relay.exe'
+            $versionOutput = (& $cli --version | Out-String).Trim()
+            if ($LASTEXITCODE -ne 0) { throw "installed CLI --version exited with code $LASTEXITCODE" }
+            if ($versionOutput -ne "hermes-relay $env:EXPECTED_DESKTOP_VERSION") {
+              throw "installed CLI version mismatch: expected $env:EXPECTED_DESKTOP_VERSION, got '$versionOutput'"
+            }
+            $helpOutput = (& $cli --help | Out-String)
+            if ($LASTEXITCODE -ne 0 -or $helpOutput -notmatch 'Usage:') {
+              throw 'installed CLI --help smoke failed'
+            }
+            if (-not (Test-Path -LiteralPath $sessionSentinel -PathType Leaf)) {
+              throw 'installer removed profile session data'
+            }
+
+            $uninstallProcess = Start-Process -FilePath $uninstaller -ArgumentList '/S' -Wait -PassThru
+            if ($uninstallProcess.ExitCode -ne 0) { throw "uninstaller exited with code $($uninstallProcess.ExitCode)" }
+
+            $deadline = [DateTime]::UtcNow.AddSeconds(20)
+            while ((Test-Path -LiteralPath $uninstaller) -and [DateTime]::UtcNow -lt $deadline) {
+              Start-Sleep -Milliseconds 250
+            }
+            foreach ($name in $expectedFiles) {
+              $path = Join-Path $installDir $name
+              if (Test-Path -LiteralPath $path) { throw "uninstaller left owned artifact $path" }
+            }
+            if (Test-Path $uninstallKey) { throw 'uninstaller left the Installed Apps registry key' }
+            if (Test-Path $productKey) { throw 'uninstaller left the HermesRelay product registry key' }
+            if (Test-Path -LiteralPath $startMenuDir) { throw "uninstaller left Start-menu artifacts at $startMenuDir" }
+            if (-not (Test-Path -LiteralPath $sessionSentinel -PathType Leaf)) {
+              throw 'uninstaller removed preserved profile session data'
+            }
+            if ((Get-Content -LiteralPath $sessionSentinel -Raw) -notmatch 'preserve-me') {
+              throw 'installer lifecycle modified preserved profile session data'
+            }
+
+            # Compare the raw registry value so expandable entries such as
+            # %USERPROFILE% are not resolved against the isolated smoke profile.
+            $userPathAfter = Normalize-UserPath (Get-RawUserPath)
+            if ($userPathAfter -ne $userPathBefore) {
+              throw "uninstaller did not restore user PATH (before='$userPathBefore', after='$userPathAfter')"
+            }
+            $startupAfter = (Get-ItemProperty -Path $startupKey -Name HermesRelayTray -ErrorAction SilentlyContinue).HermesRelayTray
+            if ($startupAfter -ne $startupBefore) {
+              throw "installer lifecycle changed the pre-existing tray startup preference"
+            }
+
+            Write-Host "packaged installer lifecycle smoke OK version=$versionOutput install=$installDir"
+          } finally {
+            Get-Process -Name 'hermes-relay-tray' -ErrorAction SilentlyContinue |
+              Stop-Process -Force -ErrorAction SilentlyContinue
+            if (Test-Path -LiteralPath $uninstaller) {
+              Start-Process -FilePath $uninstaller -ArgumentList '/S' -Wait | Out-Null
+            }
+            $env:USERPROFILE = $oldUserProfile
+            $env:HOME = $oldHomeEnv
+            $environmentKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+            if ($hadUserPath) {
+              $environmentKey.SetValue('Path', $originalUserPath, $originalUserPathKind)
+            } else {
+              $environmentKey.DeleteValue('Path', $false)
+            }
+            $environmentKey.Dispose()
+            if (Test-Path -LiteralPath $smokeRoot) {
+              Remove-Item -LiteralPath $smokeRoot -Recurse -Force -ErrorAction SilentlyContinue
+            }
+          }

      - name: Upload Windows tray release asset
        uses: actions/upload-artifact@v4
@@ -8,8 +8,216 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this

 ### Fixed

+- **Android keeps profile management and retained automation truthful.** Custom Endpoint list and mutation routes now follow the selected Hermes profile, while completed one-shot cron jobs show their retained outcome and expose only valid Runs/Delete actions.
+- **Android and Relay recover more generated media reliably.** Android accepts upstream-valid wrapped, punctuated, adjacent, spaced, and Windows `MEDIA:` markers without consuming fenced examples, and Relay translates Docker-visible workspace, home, cache, and configured-mount paths before applying its existing credential, sandbox, and size checks.
+
+## [1.6.3] - 2026-08-11
+
+### Fixed
+
+- **Relay diagnostics distinguish a prior clean stop from a crash.** Doctor and `/relay/info` expose only bounded clean, unclean, or unknown gateway-exit state with an optional suspected out-of-memory hint, without returning raw log evidence.
+- **Relay reconnects spread out after shared gateway restarts.** Ordinary exponential reconnect delays use full jitter while explicit reconnects and server-directed retry timing retain their exact behavior.
+
+## [0.4.0-alpha.7] - 2026-08-11
+
+### Fixed
+
+- **Installer lifecycle validation uses an isolated Windows PATH fixture.** Release smoke tests now verify add/remove cleanup against a fixed registry value and restore the runner's original value afterward, independently of the temporary profile used for session-preservation checks.
+
+## [0.4.0-alpha.6] - 2026-08-11
+
+### Fixed
+
+- **Installer cleanup validation compares the unexpanded Windows PATH.** Release smoke tests now read the raw user registry value, ensuring `%USERPROFILE%` entries are verified without temporary-profile expansion changing their apparent value.
+
+## [0.4.0-alpha.5] - 2026-08-11
+
+### Fixed
+
+- **Installer cleanup validation handles expandable Windows PATH entries.** Release smoke tests restore the original profile environment before comparing user PATH, avoiding false failures when unchanged `%USERPROFILE%` entries are expanded inside an isolated test profile.
+
+## [0.4.0-alpha.4] - 2026-08-11
+
+### Fixed
+
+- **Windows release validation waits for installer processes.** The packaged install/uninstall lifecycle smoke now captures GUI-subsystem process exit codes reliably before validating installed files, preserved sessions, registry state, and cleanup.
+
+## [0.4.0-alpha.3] - 2026-08-11
+
+### Added
+
+- **Windows tray provides focused remote-access management.** The compact host-aware popup covers connection state, per-host Ask/Trusted/Full Access, pending grant dialogs, authorized-client revocation, activity, daemon controls, and settings without adding chat, terminal, plugin, voice, or session surfaces.
+- **Desktop access policy is isolated per Hermes host.** `hermes-relay hosts` lists and selects local pairings and stores fail-closed access modes independently for each canonical relay URL.
+- **Windows CLI installations can add or open the management UI directly.** `hermes-relay ui install|open|status` and the installed UI shim provide a supported lifecycle for optional UI setup, discovery, and activation.
+
+### Changed
+
+- **Daemon connectivity no longer requires a tool grant.** Ask mode can keep an authenticated daemon connected with zero desktop tools attached; Trusted enables command/file tools with task-scoped screen/input grants, while Full Access removes those task prompts only for the selected host.
+- **Windows bundle updates preserve the desktop lifecycle.** The CLI and tray coordinate one verified installer launch, restore the daemon and UI after setup, and permit same-version UI add or repair without silently downgrading a newer CLI.
+
+### Fixed
+
+- **Background daemon start reports real readiness.** Detached startup now waits for the spawned process to authenticate and connect, and returns actionable log evidence for configuration, authentication, early-exit, and timeout failures.
+- **Local and release tray builds embed the packaged UI.** Development installs use Tauri's production protocol instead of attempting to load a missing localhost development server, and release CI exercises a silent install/uninstall lifecycle.
 - **Windows-trusted certificates work in the desktop CLI.** The packaged Windows binary and newer Node runtimes add the Windows certificate store without dropping bundled or operator-supplied roots, while TLS verification and Relay certificate pinning remain enforced.

+## [1.6.2] - 2026-08-11
+
+### Fixed
+
+- **Paired sessions use recognizable device identities.** Relay sessions preserve a client-provided hostname as the primary name, retain model and platform details, and enrich valid reconnects without requiring users to pair again.
+- **Long-lived session expiry is readable.** The Dashboard presents paired-session lifetime in days or weeks with the exact local deadline available in the detail view instead of accumulating hundreds of hours.
+
+## [Android 1.8.1] - 2026-08-09
+
+### Fixed
+
+- **Android preserves complete long-session transcripts.** API-server and profile-scoped Dashboard history reads now use explicit bounded pagination, retain compatibility with older unpaginated responses, and keep edit, retry, sharing, and recovery anchors stable beyond Hermes' latest-500 default window.
+- **Android follows authoritative Gateway turn contracts.** Submit rejections retain the server's message without silently falling through to SSE, event envelopes reconcile consistently, and edit-and-regenerate requests send the required truncation confirmation.
+
+## [Android 1.8.0] - 2026-08-09
+
+### Added
+
+- **Android chat keeps work in context and makes live turns easier to read.** Draft text, edits, quotes, and attachments stay with their connection, profile, and session; conversation search and prompt-turn navigation jump by stable message identity; message actions reveal smoothly on tap; quoted replies use linked previews without placing markup in the composer; assistant replies retain their compact high-contrast bubbles; and pending attachments support preview, removal, and accessible reordering.
+- **Android reasoning and tool activity use a quieter transcript.** Live thinking opens as an inline disclosure and settles to a collapsed Thought row, while consecutive routine reads, searches, commands, browser actions, and device actions share one live activity ticker or concise completed summary. Approvals, failures, generated media, file changes, output risks, and delegated work keep their own visible lifecycle surfaces even when ordinary tool progress is hidden.
+- **Android Profile Shelf makes agent switching immediate without mixing conversations.** The Chat header expands a compact, accessible shelf with ordered profile avatars, a subtle Server-default home badge on the resolved identity, last-session restoration, display hiding, lock controls, and one full switcher shared with Agent Passport.
+- **Android accepts shared text as a new Chat draft.** Hermes Relay now appears in the system sharesheet for text, opens the active profile in a fresh conversation, and fills the composer for review without sending automatically.
+
+### Changed
+
+- **Android appearance controls are more expressive and easier to preview.** Theme presets, accent and shape customization, imported Sphere skins, and custom pet creation share one live-preview workflow while preserving separate agent, background, and companion identities.
+
+### Fixed
+
+- **Android restores complete Gateway activity and makes settled replies speakable.** Successful Gateway turns reconcile structured persisted tool calls even when an upstream server omits live tool lifecycle events, and a configured voice can read a completed assistant reply from its message actions without requiring Voice Mode. While that narration is active, the same message actions expose Stop without cancelling an unrelated chat turn.
+- **Android chat matches standard keyboard, scrolling, and photo behavior.** Sentence capitalization is enabled, physical Enter can send or insert a newline according to a device-level setting, Ctrl/Command+Enter always submits, directional keys stay with the text caret, expanded thinking and tool content retains bottom-follow until the user scrolls away, and portrait attachments honor their EXIF orientation in previews and message viewers.
+- **Android distinguishes live-turn corrections from queued follow-ups.** The composer names its current action with visible text and accessible state, successful gateway redirects show a correction lifecycle marker, and attachment-bearing follow-ups always enter the session-owned queue because the upstream redirect operation is text-only.
+- **Android visibly explains quiet startup work without an empty chat bubble.** The full-size thinking animation now sits directly in the conversation lane with a stable reviewable status until the first answer text arrives, while recovery keeps its explicit reconnecting state.
+- **Android keeps pets and screen chrome inside safe interaction bounds.** Floating companions avoid agent identity rows and controls during scrolling, remain touchable for their menu, and settings headers respect edge-to-edge system insets.
+
+## [Android 1.7.1] - 2026-08-08
+
+### Fixed
+
+- **Android chat follows a growing live reply.** Bottom-owned conversations now observe each replacement of the streaming message list, keeping newly added lines visible while preserving the reader's position after a manual scroll away.
+- **Hosted Hermes onboarding completes through the official Dashboard sign-in path.** Android recognizes hosted account addresses, uses the system-browser native PKCE flow, and resumes the verified Dashboard session after its loopback callback.
+- **Live Android tool cards remain expandable while a run is active.** Streaming Gateway updates preserve stable card identity and merge tool arguments and result previews into the existing row, so details can be opened before the session finishes.
+- **Completed Android replies format Markdown immediately.** Live assistant text keeps its stable plain renderer only while incomplete, then the same owned row transitions to rich code blocks, lists, emphasis, and links without leaving or reopening the session.
+- **Android approval cards require an explicit labeled decision.** Reading or scrolling a guarded command, navigating away, backgrounding, recomposition, later turn activity, and card dismissal cannot submit or locally resolve it; pending requests remain bound to their owning profile and session until an explicit response or authoritative upstream expiry.
+- **Android Agent Passport controls are readable and easy to dismiss.** Safety and speed choices use full-width accessible targets with plain-language selected-state explanations, while a persistent close action and boundary-aware downward swipe make the sheet reliably dismissible without stealing nested content scrolling.
+- **Android queued messages stay with their originating chat.** Follow-ups now retain their exact connection, profile, session, run, route, attachments, and voice context across concurrent Gateway session switches instead of following whichever session is visible when a run finishes.
+- **Android model pickers reject duplicate catalog identities before rendering.** Repeated provider/model rows from cached or refreshed inventories are merged at the provider boundary, while identical model IDs under different providers remain distinct choices with provider-aware reasoning capabilities.
+- **Android session pins and archives survive app restarts.** The session drawer now reads and updates the owning Hermes profile's durable session metadata, rolls failed changes back, and makes unpinned stars clearly distinct in light theme.
+
+## [1.6.1] - 2026-08-08
+
+### Fixed
+
+- **The Dashboard plugin hands hosted Hermes connections to Android reliably.** Mobile setup exposes the canonical Dashboard address and keeps dialog focus handling contained, so system-browser authentication can return to the correct connection without disrupting the Dashboard.
+
+## [Android 1.7.0] - 2026-08-06
+
+### Added
+
+- **Android exposes provider-aware reasoning controls.** The effort drawer consumes exact upstream or optional Relay capability metadata for each provider/model identity, while unmodified or older Hermes installations retain a fail-soft standard fallback including `max` and `ultra`.
+- **Android support information is local, redacted, and reviewable.** Fatal crashes and handled failures share a bounded on-device record, Diagnostics can copy or share the exact reviewed text, and nothing is uploaded automatically.
+
+### Fixed
+
+- **Android chat chrome follows its active interaction state.** Opening the session drawer dismisses the composer keyboard, refreshed sessions keep their newest row visible, and floating pets wait for measured chat terrain, sit flush on supported rails, and treat the complete scroll-to-bottom control as forbidden space.
+- **Android pets and optional model discovery initialize quietly.** Floating companions wait for a measured overlay before taking their home position, and background API model-inventory failures retain actionable local diagnostics without interrupting chat with a generic notice.
+- **Android chat and Voice stay precisely bottom-pinned through replies, restores, and layout changes.** The active tail keeps its stable live renderer until another row takes ownership, restored sessions follow late composer and message measurement without overriding a reader, and bottom-owned transcripts settle to the exact list boundary after replies and keyboard animations instead of leaving a small hidden remainder.
+- **Android Focus voice controls remain responsive.** The modal click-through guard now sits behind the voice UI instead of consuming pointer events from the mic, close, expansion, and panel controls.
+- **Android diagnostics explain what failed and what to try next.** Relay, route, WebSocket, and API checks distinguish the saved route from the redacted request they actually attempted, name the operation, and provide targeted guidance for connection, DNS, timeout, TLS, authentication, rate-limit, and server failures.
+- **Android chat and Voice keep one render identity through recovery.** Checkpoint restore, streamed callbacks, server-ID adoption, and replay now resolve the same owned transcript row before publication, preventing recurring Compose duplicate-key crashes.
+- **Android crash reports retain actionable release context.** Reports identify the Android surface, avoid exposing hosts and credentials, migrate earlier local crash records, and release automation retains exact Play and sideload R8 mappings for retrace.
+
+## [1.6.0] - 2026-08-06
+
+### Added
+
+- **Relay supplies exact provider/model reasoning capabilities when providers expose them.** The bounded, profile-aware overlay resolves dynamic catalogs for OpenAI Codex, Copilot, LM Studio, and Ollama Cloud, keeps provider credentials on the host, and leaves unknown or unavailable catalogs on the advisory fallback.
+
+## [Android 1.6.1] - 2026-08-03
+
+### Fixed
+
+- **Voice capture waits for the microphone to be released.** Manual recording no longer races barge-in teardown, and AudioRecord startup failures now explain how to free or permit the microphone before retrying.
+- **Android text selection stays stable as streamed replies finish.** Chat resets an active selection when live text becomes rich Markdown, preventing selection-handle drags from retaining removed text nodes.
+- **Android session history follows the upstream page-size contract.** The drawer keeps its 200-session window through bounded 100-row requests, avoiding HTTP 422 errors from current dashboard servers while preserving active-profile isolation.
+- **Android no longer mistakes optional-surface auth failures for expired Relay pairing.** Background session refreshes stay out of the global snackbar, Dashboard and API authorization errors name their owning credential, and Relay-only surfaces use consistent Optional, Ready, Reconnecting, Unavailable, and Needs re-pair states. Foreground recovery retries ordinary Relay backoff immediately while preserving server rate limits, and recovery prioritizes Dashboard or host session management while retained credentials are labeled as stored details instead of active pairing.
+- **Voice controls no longer collide with new-chat coaching.** The clean-view hint yields while Voice owns the composer so it cannot cover the expanding Voice drawer.
+
+## [1.5.1] - 2026-08-03
+
+### Fixed
+
+- **Re-pairing repairs one device instead of accumulating duplicate sessions.** An explicit host-approved pair replaces older sessions and refresh credentials for the same device, while the Dashboard and `/relay revoke <token-prefix>` remain available for operator cleanup.
+
+## [Android 1.6.0] - 2026-08-02
+
+### Added
+
+- **Hermes can be selected as Android’s default Digital Assistant.** The opt-in system role supports background and locked-screen invocation, while the separate experimental “Hey Hermes” listener keeps pre-activation audio on the phone and exposes an ongoing Stop control.
+- **Installed Hermes plugins can contribute native Android pages.** Android renders a bounded declarative schema instead of plugin code, keeps write access off until the user grants it, and supports approval-gated agent-created previews through Relay 1.5.0.
+- **Pets can stay with you across the Android app without replacing the agent.** Petdex and imported companions live in an app-level overlay, can be held and dragged, and optionally roam across live-measured chat and settings surfaces without reserving message space. (#267)
+- **Petdex browsing and one-tap installation are built into Appearance.** Search results use lightweight previews, full atlases download only after Install, creator attribution remains visible, and installed pets stay available offline. (#267)
+- **Android can be used in Russian.** Both product flavors include an AI-assisted Russian catalog, language picker support, localized plurals, and refreshed translations for the 1.6 feature set.
+
+### Changed
+
+- **Assistant and floating Voice surfaces use compact, expandable controls.** Opening full Voice continues the same turn and microphone owner instead of restarting the session.
+- **Voice interruption covers generation and playback.** Barge-in follows upstream RMS calibration and timing, exact stop phrases can end an active voice chat, and interrupted spoken context remains private to the next Standard turn.
+- **Profile identity, the Sphere, and pets are separate appearance choices.** Agent avatars identify messages, background visualization controls ambient art, and Floating pet controls the companion independently. (#267)
+- **The Agent Passport exposes more profile state and safer controls.** Profile configuration, skills, routing, reasoning, and scoped API access remain visibly distinct from the active session identity.
+
+### Fixed
+
+- **Voice output recovers when a streaming renderer produces no audio.** Android falls back to basic synthesis after a bounded first-audio timeout, and long Standard Voice uploads no longer retain duplicate encoded audio buffers.
+- **Relay route failover avoids competing reconnect loops.** Route changes settle through one generation-aware reconnect owner instead of rapidly switching between LAN and remote candidates.
+- **Live chat rows keep stable UI identity while upstream state reconciles.** Streamed messages and process rows no longer collide or restart merely because a server identity arrives later.
+- **Floating pets recover from invalid or scrolling terrain.** Roaming uses measured bubble edges, avoids the jump-to-latest control and text overlap, resumes after drag or scrolling, and preserves locomotion, held, drop, and fallback animation states.
+- **Hermes appears and activates in OEM Android assistant pickers.** Required Assist, Voice, recognition-service, and single-microphone lifecycle metadata now agree.
+- **Experimental wake detection handles completed sherpa results and empty speech cleanly.** Tests use the real local microphone/model path, and no-speech activation returns to ready state instead of surfacing a fatal server error.
+
+## [Android 1.5.3] - 2026-07-31
+
+### Fixed
+
+- **Voice transcripts retain stable rows after chat-history reconciliation.** Focus mode uses the same stable Compose identity as the main conversation, preventing duplicate-key crashes when live rows adopt persisted server IDs.
+
+## [1.5.0] - 2026-08-02
+
+### Added
+
+- **Realtime Agent sessions can speak only settled answers.** Clients may enable an optional per-session `final_answer_only` policy that suppresses routine acknowledgements, progress narration, and intermediate commentary while preserving spoken approvals, confirmation questions, blocking failures, and the final Hermes answer.
+- **Agents can draft native Android plugin pages through Relay.** New tools store bounded declarative JSON pages under the authenticated Relay plugin namespace, while Android retains control of enablement, publication, write grants, and persistent removal. Generated pages cannot include executable code, arbitrary network calls, Android intents, or backend action requests.
+## [Android 1.5.2] - 2026-07-28
+
+### Fixed
+
+- **Dashboard sign-in completes across supported providers and network routes.** Self-hosted OIDC stays on the dashboard cookie flow, while Nous Portal opens in the system browser and completes standards-compatible PKCE through HTTPS, private-LAN, or Tailscale dashboard routes.
+- **Replayed chat updates no longer destabilize the conversation list.** Duplicate upstream message identifiers are coalesced before Compose renders them.
+
+## [Android 1.5.1] - 2026-07-26
+
+### Added
+
+- **Voice supports focused and conversational layouts.** Focus keeps spoken turns, Markdown, tools, media, and actions in a compact voice surface, while Conversation opens the full Chat renderer without leaving the active voice session.
+- **Voice can speak only settled answers.** A global Voice setting keeps tool progress, service updates, and intermediate commentary visual while supported voice paths wait to speak the final Hermes answer.
+
+### Changed
+
+- **Chat answers are easier to read in every theme.** Primary assistant text now uses the theme's full-contrast foreground, and chat prose uses a 15sp size with 21sp line height.
+- **Google Play builds target Android 16.** The app now targets API level 36 while retaining its existing minimum-device support.
+
+### Fixed
+
+- **Completed streamed answers render their formatting without losing the reading position.** Markdown headings, lists, emphasis, and code blocks replace the live text renderer only after completion, then the measured trailing edge remains anchored at the bottom.
+- **Standard Voice speaks completed assistant replies again.** Session and message fences no longer suppress a valid final answer during the handoff from generation to narration.
+- **Realtime background work no longer blocks the active voice controls.** A promoted task releases the foreground spinner and microphone while its progress, tools, cancellation, and final result remain available in the owning chat.
+
 ## [Server 1.4.3] - 2026-07-22

 ### Added
@@ -1,35 +1,38 @@
-# Hermes-Relay-CLI v__VERSION__
+# Hermes-Relay CLI v__VERSION__

-**Release Date:** 2026-07-13
+**Release Date:** 2026-08-11

-This alpha makes the desktop direction explicit: Hermes-Relay is a real CLI/TUI with an optional Windows right-click systray—not a second desktop application. The old Tauri/WebView dashboard and its embedded windows are gone. The installed CLI remains the single source of behavior for pairing, TUI, daemon management, grants, audit, diagnostics, chat, voice, and tools.
+This alpha replaces the right-click-only Windows tray with the compact **Hermes-Relay CLI UI** popup while keeping Hermes-Relay's desktop boundary narrow. Chat, the remote TUI, plugins, voice, and agent sessions remain CLI or upstream desktop concerns.

-**Experimental phase.** Assets are 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 optional native systray is Windows-only.
+**Experimental 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 tray is Windows-only.

 ## What's changed

 ### Added

- **Persistent desktop-use control.** `hermes-relay computer-use status|enable|disable|cancel` stores one local preference, reports daemon privilege and active/pending grants, and can end an active task-scoped grant without relying on a GUI.
- **Headless grant review.** `hermes-relay grants` lists pending local computer-use requests and supports interactive review plus explicit `approve`, `reject`, and JSON forms for scripts.
- **Typed Relay chat option.** `chat --relay-chat` sends `chat.send` over WSS and renders typed `stream.event` v1 assistant, tool, artifact, memory, skill, and error lifecycles while preserving the existing gateway path as the default.
- **Release-parity verification.** One version contract now keeps the npm package, compiled CLI, Rust tray, lockfile, and installer metadata aligned. The Windows verification target covers TypeScript, compiled-binary smoke tests, Rust formatting/lint/check/tests, and installer packaging.
+- **Compact Windows management tray.** The popup provides connection status, host selection, per-host access, pending approval dialogs, recent activity, daemon controls, startup settings, and authorized-client revocation.
+- **Host-aware desktop access.** `hermes-relay hosts` lists and selects paired Hermes instances and stores independent Ask, Trusted, or Full Access policy for each canonical relay URL.
+- **In-window grant decisions.** New computer-use requests bring the tray forward and show the requesting host, scope, reason, and duration with explicit Approve and Reject actions.
+- **Supported UI lifecycle from the CLI.** `hermes-relay ui install|open|status` lets a CLI-only Windows installation add, reveal, or inspect the optional management UI without rerunning setup by hand.

 ### Changed

- **Menu-only Windows systray.** The optional tray is a small native Rust process with no application window, WebView, overlay, embedded terminal, chat view, voice view, or settings dashboard. Interactive actions open the installed CLI in a normal terminal.
- **State- and privilege-aware daemon control.** The menu reports PID-backed daemon state and User/Administrator privilege, disables invalid lifecycle actions, and requests UAC only when **Start/Restart daemon as Administrator…** is explicitly chosen. The tray itself remains unprivileged.
- **Visible desktop-use safety.** The tray shows enablement, active grant mode and expiry, warns when an Administrator control grant is active, raises a native alert for pending approvals, opens CLI grant review, and provides immediate cancellation and emergency stop.
- **Per-user Windows installation.** The default PowerShell installer downloads the checksum-verified NSIS package, installs the CLI and optional tray under `~/.hermes/bin`, adds Start-menu shortcuts and user PATH, and can start the tray at sign-in. CLI-only installation remains available with `HERMES_RELAY_INSTALL_SURFACE=cli`.
+- **Daemon startup is connectivity-first.** Ask mode can keep an authenticated daemon connected with zero desktop tools attached, so starting the daemon does not itself grant authority.
+- **Full Access is explicit and host-scoped.** Trusted hosts may use command and file tools while screen/input remains task-granted. Full Access also removes task prompts for screen, input, and file patches for that host, while authentication, audit, revocation, emergency stop, and UAC boundaries remain enforced.
+- **Host changes apply immediately.** Selecting a different host or changing its access mode restarts an already-running daemon and the UI verifies that the daemon URL matches the selected host before showing it as connected.
+- **PowerShell remains first-class.** Agents should prefer the dedicated `desktop_powershell` RPC for native Windows work; `desktop_terminal` remains cmd-compatible for existing callers.
+- **CLI and UI updates share one verified installer.** Bundle updates coordinate shutdown and restart, allow same-version UI repair, and refuse accidental downgrade unless explicitly forced.

 ### Fixed

- **Installed-binary diagnostics.** `hermes-relay doctor` reports the physical Bun-compiled executable instead of a virtual embedded-module path, so PATH and install-directory checks describe the binary that actually launched.
- **Release guardrails.** CLI tag automation rejects version drift, tags not contained in `main`, oversized tray binaries, or a tray process that creates an application window.
+- **Detached daemon start reports real readiness.** `daemon start` waits for the spawned PID to authenticate and connect, and reports configuration, authentication, early-exit, and timeout diagnostics instead of returning a false success.
+- **Normal tray operation no longer requires opening a CLI for grants.** Pending requests are resolved directly in the focused management dialog.
+- **Release checks match the management tray.** CI builds the React assets, validates Tauri metadata, and smoke-tests the packaged tray without obsolete menu-only size or window assertions.
+- **Installed tray builds no longer depend on a localhost development server.** Local and packaged builds embed their UI assets, eliminating the `127.0.0.1 refused to connect` failure.

 ## Install

-**Windows CLI + optional systray (PowerShell):**
+**Windows CLI + management tray (PowerShell):**

 ```powershell
 irm https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.ps1 | iex
@@ -53,11 +56,11 @@ Pin this release with `HERMES_RELAY_VERSION=__TAG__`.

 ```text
 hermes-relay --version
-hermes-relay pair --remote ws://<host>:8767 --grant-tools
+hermes-relay hosts list --json
 hermes-relay daemon start
-hermes-relay daemon status
+hermes-relay daemon status --json
 ```

-On Windows, open **Hermes Relay Systray** from the Start menu and right-click its notification-area icon. No separate desktop window is installed.
+On Windows, click the Hermes-Relay CLI UI notification-area icon to open the management popup directly above it.

-See the [CLI and systray guide](https://hermes-relay.dev/docs/desktop/) for installation, commands, desktop-use safety, and troubleshooting.
+See the [CLI and tray guide](https://hermes-relay.dev/docs/desktop/) for installation, access modes, grants, and troubleshooting.
@@ -17,17 +17,41 @@ That's it — no extra setup or credentials required for a debug build.
 Helper scripts for common development tasks:

 ```bash
-scripts/dev.bat build      # Build debug APK
+scripts/dev.bat build      # Build the sideload debug APK
+scripts/dev.bat compile    # Compile sideload Kotlin only
+scripts/dev.bat test-one "com.hermesandroid.relay.SomeTest"  # Run one test class
+scripts/dev.bat install-fast  # Build arm64 only + install + launch
 scripts/dev.bat release    # Build signed release APK
 scripts/dev.bat bundle     # Build release AAB for Google Play
-scripts/dev.bat run        # Build + install + launch + logcat
-scripts/dev.bat test       # Run unit tests
+scripts/dev.bat run        # Build sideload + install + launch + logcat
+scripts/dev.bat test       # Run sideload debug unit tests
 scripts/dev.bat version    # Show current version
 scripts/dev.bat relay      # Start relay server (dev, no TLS)
 ```

 Linux/macOS equivalent lives at `scripts/dev.sh`.

+### Fast Android iteration
+
+Gradle's daemon, local build cache, configuration cache, and parallel task
+execution are enabled for repeat local builds. Keep the same Gradle JVM
+configuration between invocations and do not add `--no-daemon` to normal dev
+commands; a different heap or Java home starts a separate daemon and discards
+the warm-process benefit.
+
+Use the narrowest command that proves the change:
+
+1. `scripts/dev.bat compile` for a Kotlin compile check.
+2. `scripts/dev.bat test-one "<fully-qualified-class-or-pattern>"` for a focused regression.
+3. `scripts/dev.bat install-fast` when the result must run on the connected
+   arm64 phone. This passes `-Phermes.devAbi=arm64-v8a`, avoiding the x86,
+   x86_64, and armeabi-v7a native libraries in the local APK.
+4. `scripts/dev.bat prepush` before pushing Android work.
+
+`install-fast` is intentionally phone-specific. Use `install` for a universal
+sideload debug APK or when the target ABI is not arm64. Release builds remain
+universal and are unaffected unless `-Phermes.devAbi` is explicitly supplied.
+
 ## Repository Structure

 ```
@@ -51,12 +75,12 @@ The legacy `relay_server/` directory is a thin compatibility shim around `plugin

 | Component | Stack |
 |-----------|-------|
-| **Android App** | Kotlin 2.0, Jetpack Compose, Material 3, OkHttp |
+| **Android App** | Kotlin 2.4, Jetpack Compose, Material 3, OkHttp |
 | **Relay Server** | Python 3.11+, aiohttp |
 | **Serialization** | kotlinx.serialization |
-| **Build** | AGP 9, Gradle 8.13, JVM toolchain 17 |
+| **Build** | AGP 9.3.1, Gradle 9.6.1, JVM toolchain 17 |
 | **CI/CD** | GitHub Actions (lint, build, test, signed APK artifacts) |
-| **Min SDK** | 26 (Android 8.0) / Target SDK 35 |
+| **Min SDK** | 26 (Android 8.0) / Target SDK 36 |

 ## Running the Relay Locally

@@ -174,7 +198,8 @@ Release notes (`RELEASE_NOTES.md`, `app/src/main/assets/whats_new.txt`, `docs/pl
  CI in one cached Gradle invocation. Run it before pushing Android PR updates
  to catch common hosted failures without waiting for another full Actions
  cycle; hosted CI remains the exhaustive all-variant gate.
- **Android unit tests:** `scripts/dev.bat test` (runs JUnit + MockK + Compose testing)
+- **Focused Android unit test:** `scripts/dev.bat test-one "<fully-qualified-class-or-pattern>"`
+- **Android unit tests:** `scripts/dev.bat test` (runs the sideload debug JUnit + MockK + Compose suite)
 - **Python tests:** `python -m unittest plugin.tests.test_<name>` from the repo root with the hermes-agent venv active. `pytest` works too but the pre-existing `conftest.py` imports a module that isn't always installed — `unittest` avoids that entirely.

 CI is split into path-filtered workflows: `.github/workflows/ci-android.yml` (lint + build + test on app/Gradle changes), `.github/workflows/ci-server.yml` (syntax check + focused server tests on plugin/Python changes), and `.github/workflows/ci-desktop.yml` (desktop type/build/smoke checks). They run on pushes to `main` and `dev` and on PRs targeting either when their paths are touched.
@@ -1,5 +1,573 @@
 # Hermes-Relay — Dev Log

+## 2026-08-09 — Gateway activity recovery and chat speech
+
+Successful Android Gateway turns now reconcile against their profile-owned,
+structured session history. This recovers persisted tool calls when an upstream
+Gateway completes a turn without emitting live tool lifecycle events; assistant
+prose is never inspected for inferred activity, and the recovered calls continue
+through the existing Off, Compact, and Detailed display policy.
+
+The Speak message action now follows configured voice readiness and idle output
+state instead of active Voice Mode or presentation style. A settled assistant
+reply can therefore be read aloud directly from chat, while live or provider
+playback still prevents overlapping output. One-shot message narration owns its
+completion state outside Voice Mode and replaces Speak with Stop while active;
+stopping drains only that narration pipeline and does not cancel a chat turn
+started while the response was playing.
+
+## 2026-08-09 — Quiet reasoning and grouped tool activity
+
+Android Chat now treats reasoning and routine tools as transcript scaffolding.
+Visible live reasoning opens automatically without a tinted card, then collapses
+to a quiet Thought disclosure when it settles unless the reader has explicitly
+chosen its state. Empty reasoning remains absent and the existing first-token
+status continues to own the waiting state.
+
+Top-level routine calls retain their source order but render as consecutive
+activity runs. A live run keeps one summary and one latest-activity ticker in a
+stable footprint; a settled run becomes one collapsed summary that can disclose
+the original identity-preserving tool rows. File edits, approval/question tools,
+generated media, failures, output-risk findings, and delegated work split runs
+and retain independent surfaces. Off hides only ordinary activity runs, Compact
+uses compact disclosed rows, and Detailed preserves the full per-tool detail
+surface on demand. Expansion still yields bottom-follow ownership, and each run
+registers its measured bounds as Chat pet terrain.
+
+## 2026-08-09 — Android chat experience and attachment polish
+
+The Android composer now declares sentence capitalization and a Send IME
+action. A device-level setting chooses whether unmodified physical Enter sends
+or inserts a newline; Shift+Enter remains a newline and Ctrl/Command+Enter
+always submits. Every submit route converges on the existing live-turn owner,
+so the current gateway state still decides whether content steers the active
+turn or queues behind it. Directional focus traversal is cancelled while the
+editor owns focus so hardware arrow keys continue to move the caret and
+selection.
+
+Conversation bottom-follow now remains owned when thinking or tool details
+expand. Only an actual drag ending above the bottom yields that ownership, and
+a chat first measured while the IME is already visible now captures the same
+resize-follow state as a keyboard opened after composition.
+
+Bitmap-backed attachment surfaces now apply EXIF rotation and reflection before
+display. Attachment reads and Base64 conversion also leave the UI thread, so
+selecting a larger photo no longer performs the full ingestion path inside the
+activity-result callback.
+
+Composer drafts now belong to the stable connection, profile, and session
+identity. Text, edit context, and pending attachments restore when returning to
+a chat without persisting attachment bytes. Pending attachments expose bounded,
+orientation-aware previews plus explicit remove and reorder controls.
+
+Conversation overflow now opens transcript search with previous/next matches
+and a prompt-turn rail, both keyed to the same stable UI identity as the message
+list. Assistant prose retains the compact bubble and subtle edge treatment that
+keeps it legible above the animated chat background. Tapping a message reveals
+the existing copy, quote, speak, and edit actions with reduced-motion-aware
+expansion and accessible targets.
+
+Quotes are composer-owned structured references instead of raw blockquote text.
+The composer and sent message render a linked, highlighted author preview; the
+transport remains ordinary Markdown so unmodified Desktop and TUI clients show
+a readable quoted reply. Thinking and top-level tools continue to use their
+independent compact thought bubbles and configured compact or full tool cards,
+without an aggregate completion card. The composer also names Correction and
+Queue states with visible labels. Gateway redirects remain text-only:
+follow-ups with attachments are forced through the existing destination-owned
+queue so files cannot be left behind by a correction request.
+
+## 2026-08-08 — Standalone Android thinking status
+
+Blank streaming assistant rows now present the full-size working animation
+directly in the conversation lane above the visible `Still working…` label,
+without painting an empty assistant bubble around the status. The first answer
+token replaces that standalone state with the normal response bubble, while
+recovery retains the distinct `Reconnecting to your answer…` wording. The
+status owns one stable TalkBack description and suppresses animated child
+nodes, avoiding repeated announcements without claiming measurable progress.
+
+## 2026-08-08 — Android text-share draft handoff
+
+The shared Android manifest now advertises a `text/*` `ACTION_SEND` target for
+both app flavors. `MainActivity` accepts only non-blank single-item text shares
+and places them in a process-local, identity-fenced handoff that survives cold
+Compose initialization. Once the configured chat context settles, the app root
+navigates to Chat and delegates draft creation and composer prefill to
+`ChatViewModel`.
+
+The ViewModel reuses the existing new-chat lifecycle, preserving Gateway
+background-turn reconciliation and the active connection/profile/transport
+namespace. Composer prefills use a one-consumer conflated channel so an intent
+received before Chat composition is delivered once. Shared text is never
+routed through message sending; the user must review and submit it explicitly.
+
+## 2026-08-08 — Android Profile Shelf and profile-context identity
+
+Chat profile selection now lives in a collapsible shelf directly below the top
+app bar. The header toggles the shelf, the active capsule opens Agent Passport,
+inactive 48 dp avatars switch context, and a pinned overflow opens the same full
+switcher used by Passport. Saved ordering and hidden state drive both surfaces;
+the selected hidden profile remains disclosed, while a one-identity shelf stays
+out of the layout. Long-press actions expose inspection, Passport, profile lock,
+and hiding without adding activity or presence claims.
+
+The shelf uses the chat surface instead of a second elevated toolbar. A neutral
+active capsule, 36 dp avatar artwork inside 48 dp targets, compact spacing, and
+a contained overflow affordance keep the row visually subordinate to Chat. When
+Server default resolves to a concrete profile, that profile's avatar remains
+the identity and a small home badge discloses its default routing role.
+Local avatar lookup remains keyed to the Server-default presentation identity,
+so an image customized while that row is selected appears consistently in both
+the Chat header and shelf rather than being re-keyed to whichever explicit
+profile is currently active.
+
+The Server-default sentinel is now distinct from a profile literally named
+`default`. Profile selection restores the last compatible connection/profile/
+transport session, otherwise leaves a fresh draft. Gateway turns detach and
+reconcile in their original session, live SSE turns keep switching disabled,
+and every profile transition clears session-scoped model, provider, personality,
+reasoning, approval, Fast, and YOLO state before the destination session seeds
+its own values. Server sticky-default state is never written.
+
+## 2026-08-08 — Streaming reply tail follow
+
+Android's conversation-bottom follower now reads the current immutable message
+list from Compose state inside its long-lived layout observer. Each streamed
+replacement can therefore advance the viewport as the active bubble gains
+lines, while dragging or scrolling away still releases bottom ownership.
+
+## 2026-08-08 — Settled live replies transition to Markdown
+
+Android now releases the live plain-text renderer immediately after an
+assistant row settles. The transition retains the row's stable UI identity,
+commits the final live frame before replacing its selectable text topology,
+and anchors the same bottom-owned row during the Markdown remeasure. Readers
+who scrolled away retain their viewport, while completed code fences, lists,
+emphasis, links, and interrupted partial replies no longer require session
+navigation before rich rendering appears.
+
+## 2026-08-08 — Explicit-consent ownership for Android approvals
+
+Android no longer treats unrelated Gateway activity or a terminal display event
+as proof that an approval was resolved. Approval cards remain pending through
+scrolling, recomposition, navigation, and background restoration, and retain
+their exact connection, profile, and session ownership. Only a labeled action
+that successfully reaches `approval.respond`, an authoritative upstream expiry,
+or an explicit interrupt can retire the local request; the interrupt path stays
+visibly denied because upstream force-denies it.
+
+## 2026-08-08 — Agent Passport control and dismissal accessibility
+
+The Android Agent Passport keeps its title and explicit close action outside
+the nested content scroller. Material bottom-sheet gestures are enabled again,
+so a downward gesture scrolls long content toward its top boundary before the
+sheet receives the gesture and dismisses; backdrop and Back dismissal retain
+the same callback.
+
+Safety and speed choices now sit below their labels instead of competing for a
+narrow horizontal column. Every segment provides at least a 48 dp target,
+allows two-line labels, exposes radio-selection semantics, and states the
+meaning of the current approval, chat override, or processing-tier choice in
+plain language. The layout remains scrollable on compact heights and at larger
+font scales without moving the close action off-screen.
+
+## 2026-08-08 — Session-owned Android send queues
+
+Android follow-up queues now capture the composing connection/profile context,
+stored session, configured transport, originating run, attachments, and voice
+context as one immutable destination. Queue presentation is filtered to the
+visible session, while completion eligibility is tied to the exact run and live
+Gateway generation that owned the queue. A completion from another session or
+an older live generation cannot dispatch through the current composer route.
+
+In-flight checkpoints retain bounded queued text across process restoration.
+Attachment bytes are not copied into Preferences DataStore; an attachment queue
+that cannot be restored is rejected with a visible review-and-resend notice.
+Connection replacement and session deletion cancel their owned queues, while
+switching among concurrent Gateway sessions preserves each session's queue.
+
+## 2026-08-07 — Provider-owned model inventory identity
+
+Android now normalizes Gateway and API model inventories before publishing
+them to picker consumers. Repeated provider rows merge by canonical provider
+slug, repeated exact model IDs collapse within that provider, and capability
+metadata follows the same provider/model identity. Models intentionally offered
+by different providers remain distinct choices, even when their display labels
+and model IDs match.
+
+The searchable picker groups and keys rows by provider slug plus exact model ID
+instead of provider display text. Cached loads, dynamic refreshes, API aliases,
+and Manage inventory use the same idempotent identity rule, preventing duplicate
+catalog data from reaching keyed Compose lists without hiding valid routes.
+
+## 2026-08-05 — Restored chat bottom ownership and effort fallback clarity
+
+Opening an existing Android session now retains exact bottom ownership through
+late, non-streaming layout changes. Composer capability controls, status rows,
+and restored message content can finish measuring after history first reaches
+the footer; a session-scoped geometry observer corrects those changes without
+using a fixed delay. New-message following remains governed by the smooth
+auto-scroll setting, while a real drag, IME ownership, and the Voice dock keep
+their existing anchors.
+
+The advisory effort drawer now states that Hermes does not advertise exact
+levels for the selected model before explaining why standard options are shown.
+The wording is consistent across all shipped Android locales.
+
+## 2026-08-05 — Provider-aware reasoning effort discovery
+
+The optional Relay plugin now exposes a bearer-protected, profile-aware model
+capability overlay without requiring changes to upstream Hermes. Android merges
+that overlay with the standard `model.options` inventory using exact provider
+and model identities, while older or unpaired Relay installations continue with
+the canonical advisory fallback.
+
+Dynamic LM Studio, Ollama Cloud, and Copilot discovery is bounded by a shared
+network limiter, cached by profile, endpoint, model, and credential fingerprint,
+and fenced across refresh generations. Neither credentials nor internal cache
+scope are returned to clients. Composer controls, Agent Passport, session
+creation, and asynchronous server reconciliation share the same capability
+resolver so a displayed effort cannot silently differ from the value sent.
+
+## 2026-08-05 — Chat drawer and companion terrain ownership
+
+The Chat screen now clears composer focus when the session drawer commits to
+opening, dismissing the IME without continuously clearing focus from drawer
+search or rename fields. Drawer refreshes override keyed list anchoring only
+when the leading session identity changes, keeping the newest row visible after
+activity-based reordering.
+
+Floating companions wait for Chat's measured composer rail before publishing
+their first roaming position. Their collision footprint contains both the
+pointer target and rendered sprite, and the complete scroll-to-bottom control
+envelope is an obstacle rather than a landing perch. Supported rails add no
+visual lift, and the floating-only renderer aligns each frame's opaque bottom
+edge to its canvas baseline so transparent atlas padding cannot make pets hover;
+centered previews and message avatars remain unchanged.
+
+## 2026-08-05 — Measured pet placement and passive model sync
+
+The floating pet now remains unpublished until the app-level overlay has a
+positive measured viewport. Its initial home coordinate is therefore derived
+from the real safe bounds instead of the zero-size pre-measure bounds that
+collapsed to the top-left corner.
+
+API provider inventory remains an optional background catalog on Gateway-led
+connections. A timeout, refusal, or unavailable optional route no longer emits
+a global chat notice during initialization, reconnection, or connection-sheet
+refresh. The failure is retained as a contextual warning in local Diagnostics,
+including the operation, endpoint role, redacted stack trace, preserved network
+cause, and targeted troubleshooting guidance. Cached and Gateway-owned model
+options remain unchanged.
+
+## 2026-08-05 — Stable chat-tail completion
+
+Chat and Voice now treat the active streamed reply as the owner of its live
+renderer until a different row becomes the conversation tail. Stream
+completion retains the existing Compose subtree and list anchor; the full
+Markdown renderer is deferred until the row is no longer active or the session
+is revisited.
+
+The last-in-group timestamp occupies its final geometry from the first
+streaming frame and is only revealed at completion. Measured positive growth
+during an active stream continues to follow the bottom without replacing the
+logical anchor. Once completion layout stabilizes, a bottom-owned transcript
+settles to the exact LazyColumn boundary; proximity slop is reserved for
+retaining follow intent during motion and cannot define the final position. The
+visible footer supplies the exact remaining distance so rounding or adjacent
+layout changes cannot leave a residual forward range.
+
+IME expansion participates in that same viewport owner. A transcript already
+at the bottom advances by the measured viewport-height loss throughout the
+keyboard animation, then settles exactly after inset updates stop on both open
+and close. A transcript being read above the bottom preserves its existing
+anchor, and a real drag cancels keyboard follow immediately. Host-side coverage
+verifies renderer ownership, unchanged bubble height, exact footer settling,
+keyboard arming, viewport loss, completion/IME settlement ownership, and
+history-reading behavior.
+
+## 2026-08-05 — Focus voice input boundary repair
+
+The Focus voice presentation remains modal without installing a consuming
+pointer handler on the full overlay ancestor. Its click-through guard is now a
+behind-content sibling: empty-space gestures cannot reach the chat or drawer,
+while the mic, close, expand/collapse, and panel controls receive their full
+pointer sequence.
+
+Host-side Compose coverage injects real touch events instead of invoking
+semantic click actions. It verifies both child callback delivery and the modal
+background boundary so the two requirements cannot regress independently.
+
+## 2026-08-05 — Actionable Android connection diagnostics
+
+Android diagnostic entries now separate the configured route from the exact
+request operation and path used to test it. Relay health checks identify the
+HTTP `/health` probe that precedes a WebSocket connection, route selection
+records its Dashboard, API, or Relay probe, and WebSocket and API checks name
+their handshake or authentication stage.
+
+Known network and HTTP failure classes attach a bounded next step for refused
+listeners, DNS, routing, timeouts, TLS, credentials, rate limits, missing
+routes, and server failures. The activity list, status timeline, detail dialog,
+copy text, and GitHub issue prefill all carry the same context. Public issue
+text preserves protocol and request paths while redacting hosts, credentials,
+queries, and user information.
+
+## 2026-08-04 — Android transcript identity ownership
+
+ChatHandler now owns one render identity for every published transcript row.
+Checkpoint recovery and all streamed message mutations resolve both the mutable
+server/domain ID and the stable UI identity, so history adoption cannot leave a
+stale client reference that appends a second row. The publication boundary also
+coalesces repeated render identities before Chat or Voice can observe them,
+while keeping the first transcript position and latest state.
+
+Focused coverage composes history reconciliation with checkpoint restore,
+exercises stale post-adoption callbacks, and runs deterministic transition
+sequences across restore, replay, deltas, thinking, and usage updates. Voice's
+temporary transcript row now occupies an auxiliary key namespace disjoint from
+real message rows.
+
+## 2026-08-04 — Android reliability and support foundation
+
+Android fatal capture and centrally classified handled failures now converge on
+a versioned, allowlisted reliability record. Reports are redacted before local
+persistence, capped at 20 records with 14-day retention, written atomically,
+and correlated only with random app/report identifiers. Expected cancellation
+and permission denial remain non-reportable. The pre-existing one-file crash
+format migrates locally on first launch.
+
+Crash recovery leads with the recovery outcome and no-upload guarantee, then
+requires an explicit review before copy, share, or GitHub actions. Diagnostics
+adds an offline support-information review using the same exact redacted text.
+Android issue prefills now request the Android area while repository-wide issue
+ownership remains maintainer-reviewed, and the release workflow retains both
+variant R8 mappings for deterministic retrace.
+
+The architecture audit defers an ANR watchdog, richer allowlisted breadcrumbs,
+hashed product correlation, and OOM emergency writing until their lifecycle,
+privacy, and false-positive behavior can be validated on devices.
+
+## 2026-08-02 — Android Russian localization
+
+Android now ships complete Russian catalogs for the main and sideload builds.
+The in-app language picker, Android locale configuration, chat and voice labels,
+tool and status presentation, diagnostics, onboarding, and plural resources are
+registered against the canonical English catalog. Existing non-English catalogs
+were refreshed to retain exact resource and format-argument parity.
+
+The integration preserves PR #276 as the source contribution while excluding
+unrelated recovery, routing, and test-stability changes from the localization
+scope. The localization registry records Android coverage only; Russian public
+documentation and marketing pages continue to use the canonical English
+fallback until those surfaces are translated separately.
+
+## 2026-07-31 — Upstream-compatible voice interruption semantics
+
+Android full-turn barge-in now follows upstream Hermes' RMS behavior: roughly
+450 ms of quiet-room calibration, a 90th-percentile floor, 3× default
+multiplier, separate generation/playback minimums, a bounded ceiling, 500 ms
+playback grace, and an 80%-majority decision window. Calibration remains frozen
+against speaker output and cannot itself trigger. Renderer-driven phase tracking
+returns to generation thresholds in quiet output gaps and rearms playback grace
+only after a gap of at least one second. Opt-in Logcat diagnostics expose the
+inputs used for device tuning. Barge-in is enabled by default while retaining its master,
+Silero sensitivity, RMS multiplier, playback grace, and resume controls.
+
+Voice stop phrases now use an editable exact-match list that defaults to
+`stop`; clearing the list disables the behavior. A match ends the active voice
+chat in generation or playback, but the same word outside voice chat and longer
+requests continue through normal Hermes input. Continuous-mode pause/resume and
+explicit background-task cancellation retain their narrower state gates.
+
+Interrupting spoken playback arms the upstream one-shot interruption note for
+the next Standard model-bound message. The latch expires after 120 seconds and
+travels only in API-local voice interface context, never in visible or
+persisted user text. Generation and pre-audio synthesis interruption do not mark
+an unspoken reply, Realtime keeps its provider-session context, and silencing remains independent
+from cancellation of promoted background work.
+
+## 2026-07-30 — Expandable Android assistant surface
+
+Android Digital Assistant sessions now open as a compact bottom bar over the
+current app, expand in place for transcript and response detail, and collapse
+without changing the active turn. Open full voice disables only the
+system-owned session UI and reveals the existing app Voice surface, preserving
+the same session, response stream, and microphone owner.
+
+Connection, chat, and voice state machines now have one main-process,
+application-lifetime owner. Assistant activation can initialize and run a cold
+voice turn without constructing or foregrounding `MainActivity`; opening full
+Voice binds the Activity to those same ViewModels and audio resources.
+
+The optional `SYSTEM_ALERT_WINDOW` Voice surface now follows the same
+wide-bar-to-expanded-sheet progression while retaining its minimized bubble.
+It remains a separately user-invoked control for turns that began in the app;
+the Assistant-role session does not require display-over-other-apps permission.
+
+The assistant window is transparent outside the bar or sheet, leaves the
+underlying app unresized, and restricts touch interception to the measured
+surface. Back collapses an expanded surface first; Back from compact, Stop, and
+ordinary dismissal remain terminal. A hidden full-Voice handoff instead follows
+the app-owned turn through its final Closed state.
+Package-scoped lifecycle reconciliation also clears assistant state if Android
+reclaims the separately processed UI while full Voice remains active.
+
+Assistant activation is ID-aware and single-flight. Duplicate delivery cannot
+re-arm capture, Retry replaces a pending readiness attempt, and Stop invalidates
+the attempt before chat, Voice, or microphone mutations. Scoped voice settings
+must hydrate from DataStore before route readiness, and process extraction
+preserves connection-catalog isolation plus the existing gateway route-flip
+settle window.
+
+Physical-device validation on a Samsung SM-S938U confirmed cold invocation over
+a non-Hermes foreground app, compact and expanded presentation without
+foregrounding `MainActivity`, and one main-process microphone owner. Locked
+invocation reached a shown system assistant session without runtime or recorder
+errors; Samsung's secure lock screen prevented screenshot-based visual review.
+
+## 2026-07-30 — Foreground wake-word diagnostics and recovery
+
+The Android-local sherpa listener now treats each non-empty keyword result as a
+completed KWS event, resets the stream immediately, and maps the stored
+confirmation setting to sherpa's native trailing-blank confirmation instead of
+requiring an already-completed result to recur across application frames. Voice
+settings can arm a ten-second test against the same foreground service,
+microphone owner, installed model, and current tuning; it displays live input
+level and reports detection without opening voice or transmitting audio.
+
+Expected empty-transcript responses after activation now record a no-speech
+diagnostic and return voice to its ready state with a retry hint rather than
+surfacing the provider's HTTP error. Other transcription failures retain the
+existing error path. Foreground-service behavior is documented explicitly:
+background detections remain pending behind the notification until Hermes is
+visible; Android default-assistant integration is a separate mode. Opening the
+visible Voice settings screen also reconciles an enabled listener after package
+replacement or process death without adding boot/background auto-start.
+
+Focused wake preferences/core and no-speech classification tests pass.
+Sideload lint, sideload debug packaging, and Google Play debug Kotlin
+compilation pass. This batch adds no model, native library, ABI, permission, or
+network dependency; the existing approximately 6 MB downloaded model and
+packaged sherpa ABI footprint are unchanged.
+
+## 2026-07-30 — Voice transcript identity alignment
+
+Android voice Focus mode now keys transcript rows with the same stable UI
+identity as the main Chat list. A live row may adopt its persisted server
+message ID during history reconciliation while retaining its original Compose
+identity; using the mutable domain ID in the voice overlay could otherwise
+collide during that transition and close the app.
+
+Focused JVM coverage recreates two visible rows with a shared reconciled server
+ID and verifies distinct stable transcript keys. Sideload production and
+Android-test Kotlin compilation pass. The existing full-overlay instrumentation
+fixture remains blocked by its continuously animating surface never reaching
+Compose idleness.
+
+## 2026-07-30 — Opt-in Android Digital Assistant mode
+
+Android now declares an explicit `VoiceInteractionService` and separately
+processed `VoiceInteractionSessionService`. Only Android's user-confirmed
+Assistant role activates the integration. Optional background “Hey Hermes”
+detection reuses the local sherpa model and tuning, releases its recorder before
+the system session opens the existing voice flow, and resumes after session
+exit. Package-scoped lifecycle messages reconcile prompt/listen state,
+transcript/response presentation, cancellation, errors, and process recreation.
+
+The Digital Assistant listener and the existing experimental microphone
+foreground service are separate, mutually exclusive opt-ins. Both retain local
+pre-activation privacy and the shared one-microphone contract. Standard voice
+continues through the upstream Dashboard audio surface. Voice settings include
+role status, setup, removal, runtime status, and the limitation that third-party
+assistants do not receive Google's low-power hotword hardware.
+
+## 2026-07-29 — Full-turn voice interruption and local wake-word preview
+
+Android barge-in now owns one microphone/VAD listener from response generation
+through playback drain for both Standard and Realtime voice. Quiet-room RMS
+calibration freezes before output begins, playback receives a grace interval,
+and model-confirmed majority filtering separates actual interruption from raw
+ducking hints. Turn epochs, stream cancellation, late-delta suppression, and
+an awaited microphone handoff keep an interrupted response from speaking again
+or racing the replacement recording. Exact stop/pause intent is phase-aware,
+while explicit background-task cancellation remains separate from silencing.
+
+An opt-in Android-local “Hey Hermes” preview uses sherpa-onnx in a user-started
+microphone foreground service. Its approximately 6 MB English model is
+downloaded and hash-verified on first enable rather than bundled. The service
+keeps pre-activation audio local, exposes an ongoing Stop notification, pauses
+for active voice, and shares a process-wide single-microphone ownership
+contract with voice recording, barge-in, and realtime diagnostics. The stored
+configuration includes strictness, confirmation frames, new-session behavior,
+and a deliberately inactive future profile-routing shape.
+
+Focused JVM coverage exercises calibration, grace, listener teardown,
+Thinking-to-Speaking ownership, generation/playback interruption, command
+gating, wake preferences, activation, and microphone exclusion. Android
+compilation for both distribution flavors, sideload lint, and sideload APK
+packaging pass with all four supported ABIs. On-device acoustic, foreground
+service, and lifecycle checks remain the corresponding validation gates.
+## 2026-07-28 — Android 1.5.2 production release
+
+Android 1.5.2 shipped from the approved `dev` to `main` release tree as
+versionCode 35. The release adds provider-aware Dashboard sign-in: Nous uses
+the advertised native PKCE system-browser flow, while compatible self-hosted
+providers retain cookie-backed full-page Dashboard authentication. Callback
+origin discovery remains server-driven, private-network HTTP compatibility is
+preserved, and arbitrary public HTTP redirects remain rejected.
+
+The private Play preflight validated the exact application tree before release
+PR #265 merged. The immutable `android-v1.5.2` tag resolves to the resulting
+`main` tip, the production workflow promoted versionCode 35 to the completed
+Google Play production track, and the public GitHub release contains the
+signed AAB, sideload APK, and SHA-256 manifest. The published sideload APK
+checksum was independently verified; replacing the debug-signed phone build
+with the release-signed artifact requires an uninstall because Android
+correctly rejects cross-signature in-place updates.
+
+## 2026-07-27 — Android replayed-message identity reconciliation
+
+Android history reconciliation now collapses reconnect/rejoin replays of the
+same persisted message ID before publishing the transcript to Compose. The
+latest repeated snapshot replaces the value at the message's first transcript
+position, preserving stable ordering, distinct messages, and the LazyColumn
+identity contract without index- or random-key fallbacks.
+
+Focused coverage reproduces the duplicate UUID condition and verifies that the
+authoritative final content wins while every rendered message keeps a unique
+stable UI key.
+
+## 2026-07-26 — Android 1.5.1 patch reconciliation
+
+Android 1.5.1 reconciles the post-1.5.0 voice and chat fixes into versionCode
+34. Voice now offers compact Focus and full Conversation presentation,
+Standard narration preserves valid completed replies, and promoted Realtime
+tasks release foreground voice controls while retaining progress and results.
+
+Completed streamed answers promote from the stable live text node to full
+Markdown only after completion. The measured Markdown row is then positioned
+by its trailing edge until deferred code and attachment measurement settles,
+preventing the LazyColumn from restoring the start of a tall response.
+
+The release also targets Android API level 36. Release notes, in-app What's
+New assets, localized Play notes, and the Play listing reference were updated
+for Android 1.5.1.
+
+## 2026-07-25 — Immutable Android release dispatch repair
+
+Android approval now dispatches the current release workflow definition from
+`main`, while every release job explicitly checks out the immutable
+`android-v*` tag. Validation confirms the dispatched version resolves to that
+checked-out commit and accepts the repository's surface-qualified
+`[Android x.y.z]` changelog heading. Existing tags remain unchanged, and a
+workflow-only correction can resume a failed publication without rebuilding
+from a different application tree.
+
+Audited `.github/workflows/approve-release-android.yml`,
+`.github/workflows/release-android.yml`, `RELEASE.md`, and `DEVLOG.md`.
+
 ## 2026-07-25 — Android 1.5.0 final release reconciliation

 The final Android 1.5.0 release tree reconciles the accumulated Dashboard-first
@@ -6685,3 +7253,16 @@ After:  Phone (HTTP/SSE) → API Server (:8642)          [chat — direct]
 - Deploy docs site (GitHub Pages or similar)
 - Phase 2: Terminal channel (xterm.js in WebView, tmux integration)
 - Phase 3: Bridge channel migration
+
+# 2026-07-30 — Wake-word strictness tuning
+
+- Lowered the unset Android wake-word strictness default from `0.6` to `0.3` after physical-device testing showed reliable activation only at the lower slider positions.
+- Added the live numeric strictness value to Voice settings so tuning is observable.
+- Preserved saved user values and the existing three-frame confirmation default; this adjustment does not migrate working installations or broaden the detector acceptance window beyond the selected threshold.
+
+# 2026-07-30 — OEM assistant-picker compatibility
+
+- Added the standard `android.intent.action.ASSIST` activity filter because some OEM assistant pickers enumerate Assist activities even when a valid `VoiceInteractionService` is present.
+- Routed activity-based Assist invocations through the existing system-assistant activation protocol so both Android entry points share microphone ownership and session lifecycle behavior.
+- Added the required `recognitionService` metadata and a bounded recognition component after device validation showed Samsung could grant the package role while leaving the active voice-interaction service empty. The component does not open the microphone; Hermes assistant sessions continue to use the established transcription pipeline.
+- Declared `CATEGORY_VOICE` on the Assist activity and retained `ACTION_ASSIST` on the explicit activation intent. `VoiceInteractionSession.startVoiceActivity()` adds the voice category, and Android rejects the launch as `START_NOT_VOICE_COMPATIBLE` unless the target filter matches both.
@@ -1,22 +1,17 @@
-# Hermes-Relay-Plugin v__VERSION__
+# Hermes-Relay-Server v__VERSION__

-**Release Date:** July 22, 2026
+**Release Date:** August 11, 2026

-This patch hardens Relay authorization, adds upstream-aware diagnostics, and keeps plugin bootstrap work off the Gateway event loop.
+This patch improves gateway recovery diagnostics and prevents clients from reconnecting in lockstep after a shared restart.

-It can accompany Hermes-Relay-Android v1.5.0 for optional Relay diagnostics and power features. Standard chat and Vanilla Hermes voice remain upstream-owned and do not require this plugin.
+Standard chat, session history, and Vanilla Hermes voice remain upstream-owned and do not require this plugin.

 ## What's changed

-### Added
-
- **Upstream-aware Gateway diagnostics.** Doctor and `/relay/info` expose optional health, configuration-route, and capability signals so clients can explain compatibility gaps without treating an older upstream install as a broken Relay.
-
 ### Fixed

- **Privileged Relay paths enforce host authorization and active grants.** Pairing, Android bridge, terminal, session policy, remote profile configuration, and voice provider origins retain their intended trust boundaries.
- **Plugin bootstrap remains responsive.** Database initialization and compatibility inspection run outside the Gateway event loop while preserving compatibility with older upstream bootstrap contracts.
- **Windows Gateway detection is non-signalling.** Starting Relay and periodic profile rescans no longer risk terminating an existing Gateway process.
+- **Bounded prior-exit diagnostics.** Relay Doctor and `/relay/info` distinguish a clean stop, an unclean exit, and unknown history, with an optional suspected out-of-memory hint. Raw logs are never returned through the API.
+- **Desynchronized recovery.** Ordinary exponential reconnect delays use full jitter so multiple Relay clients do not retry in lockstep after the gateway restarts. Explicit reconnects and server-directed retry timing remain unchanged.

 ## Install / update

@@ -24,7 +19,7 @@ It can accompany Hermes-Relay-Android v1.5.0 for optional Relay diagnostics and
    hermes plugins install Codename-11/hermes-relay/plugin --enable

    # Classic install / update on a systemd host:
-    curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash
+    curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/server-v__VERSION__/install.sh | bash
    # or, if already installed:
    hermes-relay-update

@@ -34,10 +34,10 @@

 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, and the full Hermes dashboard (models, keys, skills, profiles), rebuilt native. On sideload builds, the agent can read your screen and act on 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.

-A vanilla [hermes-agent](https://github.com/NousResearch/hermes-agent) install is enough — chat, management, and voice need **no plugin**. Add the optional relay only when you want terminal, phone control, 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 — 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.**

 <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">
@@ -99,7 +99,7 @@ the whole Vanilla Hermes setup.

 ### 4 · Optional: install Relay for power tools

-Install the Relay plugin on the server only when you want Terminal, Bridge phone control, relay sessions, media routes, or the realtime voice engine:
+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:

 ```bash
 hermes plugins install Codename-11/hermes-relay/plugin --enable
@@ -115,8 +115,11 @@ shell shims, and the full clone/update workflow:
 curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash
 ```

-The plugin-manager install owns the plugin code, dashboard tab, CLI commands,
-and agent tools. `hermes relay compat status/install/remove` manages only the
+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
@@ -135,7 +138,7 @@ Full server setup, TLS, and systemd details: [docs/relay-server.md](docs/relay-s

 <table>
  <tr>
-    <td align="center" width="25%"><img src="assets/screenshots/01_startup.png" alt="Cold start" width="100%"><br><sub><b>Cold start</b></sub></td>
+    <td align="center" width="25%"><img src="assets/screenshots/01_voice_conversation.png" alt="Voice controls in chat" width="100%"><br><sub><b>Voice in chat</b></sub></td>
    <td align="center" width="25%"><img src="assets/screenshots/02_chat.png" alt="Streaming chat" width="100%"><br><sub><b>Streaming chat</b></sub></td>
    <td align="center" width="25%"><img src="assets/screenshots/03_voice.png" alt="Hands-free voice" width="100%"><br><sub><b>Hands-free voice</b></sub></td>
    <td align="center" width="25%"><img src="assets/screenshots/04_sessions.png" alt="Session history" width="100%"><br><sub><b>Session history</b></sub></td>
@@ -159,7 +162,7 @@ Full server setup, TLS, and systemd details: [docs/relay-server.md](docs/relay-s
 </table>

 The Android app ships complete AI-assisted catalogs for **Deutsch**, **Español**,
-**日本語**, **Português (Brasil)**, and **简体中文**. Choose a language from
+**日本語**, **Português (Brasil)**, **Русский**, and **简体中文**. Choose a language from
 **Settings → Appearance → Language**; translation status and fluent review are
 tracked independently so community corrections remain easy to contribute.

@@ -183,7 +186,7 @@ tracked independently so community corrections remain easy to contribute.

 ## Hands on any machine — the Hermes-Relay CLI&nbsp;<sub>(alpha)</sub>

-> **Alpha.** Self-contained CLI binaries ship for Windows x64, Linux x64, and macOS x64/arm64 — no Node required. Windows also has an optional native, menu-only systray. Assets are unsigned during the experimental phase, so SmartScreen / Gatekeeper warnings are expected.
+> **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.

 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.

@@ -199,7 +202,7 @@ hermes-relay update                            # self-update via GitHub Releases

 It pairs against the **same relay and credential store** as the Android app — pair once from either, both work. Tagged on the `desktop-v*` [release track](https://github.com/Codename-11/hermes-relay/releases?q=desktop), with historical releases still visible under `cli-v*`.

-On Windows, the default installer adds the optional right-click-only systray: no dashboard or app window, just TUI launch, User/Administrator-aware daemon controls, pairing, local grant review, audit, diagnostics, logs, desktop-use status/cancellation, sign-in startup, and emergency stop.
+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.

 - **Docs:** [CLI guide](https://hermes-relay.dev/docs/desktop/) · [`desktop/README.md`](desktop/README.md)
 - **AI-agent setup recipe:** `/hermes-relay-desktop-setup`
@@ -264,11 +267,14 @@ Already installed? The same recipe is auto-loaded as a Hermes skill — invoke `

 ```bash
 # Android: open the repo root in Android Studio, wait for Gradle sync, Run (Shift+F10).
-scripts/dev.bat build      # Build debug APK
+scripts/dev.bat build      # Build sideload debug APK
+scripts/dev.bat compile    # Compile sideload Kotlin only
+scripts/dev.bat test-one "com.hermesandroid.relay.SomeTest"  # Focused unit test
+scripts/dev.bat install-fast  # arm64 phone build + install + launch
 scripts/dev.bat release    # Build signed release APK
 scripts/dev.bat bundle     # Build release AAB for Google Play
-scripts/dev.bat run        # Build + install + launch + logcat
-scripts/dev.bat test       # Run unit tests
+scripts/dev.bat run        # Build sideload + install + launch + logcat
+scripts/dev.bat test       # Run sideload debug unit tests
 scripts/dev.bat version    # Show current version
 scripts/dev.bat relay      # Start the relay server (dev, no TLS)
 ```
@@ -277,13 +283,13 @@ scripts/dev.bat relay      # Start the relay server (dev, no TLS)

 | Component | Stack |
 |-----------|-------|
-| **Android app** | Kotlin 2.0, Jetpack Compose, Material 3, OkHttp |
+| **Android app** | Kotlin 2.4, Jetpack Compose, Material 3, OkHttp |
 | **Hermes-Relay CLI** | TypeScript, Bun-compiled native binary, Node ≥21 (source/dev), zero runtime deps |
 | **Server / plugin** | Python 3.11+, aiohttp |
 | **Serialization** | kotlinx.serialization (Android) |
-| **Build** | AGP 9, Gradle 8.13, JVM toolchain 17 (Android); `tsc` + `bun build --compile` (CLI) |
+| **Build** | AGP 9.3.1, Gradle 9.6.1, JVM toolchain 17 (Android); `tsc` + `bun build --compile` (CLI) |
 | **CI/CD** | GitHub Actions — lint, build, test, APK artifact, CLI binaries per platform |
-| **Min SDK** | 26 (Android 8.0) · Target SDK 35 |
+| **Min SDK** | 26 (Android 8.0) · Target SDK 36 |

 <details>
 <summary><b>Repository structure</b></summary>
@@ -18,9 +18,9 @@

 ## 功能简介

- **Android 应用**：流式聊天、会话历史、文件附件、Hermes 管理、语音模式、多连接和配置文件。
+- **Android 应用**：流式聊天、会话历史、文件附件、Hermes 管理、语音模式、原生插件页面、Petdex 悬浮宠物、多连接和配置文件；也可将 Hermes 设为 Android 助手。
 - **无需插件的标准路径**：聊天、管理和标准语音可直接连接未修改的上游 Hermes Agent。
- **可选 Relay 插件**：增加终端、手机控制、媒体传输、通知助手、Relay 语音和电脑工具。
+- **可选 Relay 插件**：增加终端、手机控制、媒体传输、通知助手、Relay 语音、电脑工具，以及需确认的代理创建插件页面草稿。
 - **安全连接**：二维码配对、Android Keystore、证书固定、按通道授权和可配置会话有效期。
 - **远程使用**：可配置 Tailscale 或 HTTPS 地址，在家庭局域网和远程路由之间自动切换。
 - **两种 Android 发行渠道**：Google Play 版本适合日常使用；sideload 版本包含完整手机控制能力。
@@ -67,7 +67,7 @@ hermes gateway

 ### 4. 可选：安装 Relay

-仅在需要终端、手机控制、媒体路由、Relay 会话、实时语音或电脑工具时安装：
+仅在需要终端、手机控制、媒体路由、Relay 会话、实时语音、电脑工具或代理创建插件页面草稿时安装：

 ```bash
 hermes plugins install Codename-11/hermes-relay/plugin --enable
@@ -76,6 +76,8 @@ hermes relay start --no-ssl
 hermes pair
 ```

+已安装的 Hermes 插件可通过已认证的 Dashboard 向 Android 提供由应用安全渲染的原生页面，无需在手机上运行插件代码。Relay 1.5.0 另支持需用户确认的代理创建页面草稿。
+
 完整说明请阅读[中文快速开始](https://hermes-relay.dev/docs/zh-CN/guide/quick-start)；远程访问、协议和高级配置暂时链接到英文参考文档。

 ## 中文界面
@@ -119,9 +119,9 @@ artifacts.
 ### CLI / tray versioning

 `desktop/package.json` is the Desktop/CLI release track's source of truth. Its version
-must match the generated CLI and native Windows systray metadata. The systray is
-a menu-only controller for the installed CLI; it has no application window,
-WebView, embedded terminal, or separate desktop product surface. The public
+must match the generated CLI and Windows tray metadata. The tray is a compact
+management popup over the installed CLI and shared state; it has no chat,
+embedded terminal, plugins, voice, or separate desktop product surface. The public
 release remains one `Hermes-Relay-Desktop` track containing CLI binaries plus the
 optional Windows installer.

@@ -132,6 +132,9 @@ optional Windows installer.
 | `desktop/src/version.ts` | compiled CLI runtime version |
 | `desktop/tray/Cargo.toml` | native systray package version |
 | `desktop/tray/Cargo.lock` | locked systray package version |
+| `desktop/tray/tauri.conf.json` | tray application and bundle version |
+| `desktop/tray/package.json` | tray UI package version |
+| `desktop/tray/package-lock.json` | locked tray UI package version |

 Prepare a new CLI version on `dev` without creating a tag or npm-generated
 commit:
@@ -494,6 +497,14 @@ the new app version and a higher `appVersionCode`.
  in `app/build.gradle.kts`. Never rename the sideload APK — the
  in-app update checker matches assets by `.apk` + `sideload` in the
  name, and user-docs verify steps cite the filename.
+  The release workflow also retains
+  `app/build/outputs/mapping/{googlePlayRelease,sideloadRelease}/mapping.txt`
+  for 90 days in the `android-r8-mappings-<version>-<sha>` workflow
+  artifact. It is intentionally not a GitHub Release asset. To symbolicate an
+  in-app or sideload report, download the artifact for the exact version/SHA and
+  run Android's retrace tool with the matching flavor mapping:
+  `retrace <mapping.txt> <obfuscated-trace.txt>`. Play reports can additionally
+  use the mapping bundled into the uploaded AAB through Play Console.
 - `app/src/main/assets/whats_new.txt` — in-app "What's New" content
  shown in the settings/about screen. Update with the version number
  and a brief feature summary. Gets stale silently if forgotten
@@ -509,7 +520,11 @@ the new app version and a higher `appVersionCode`.
  the version reference and the "Release Notes" section that gets
  pasted into the Play Console "What's new" field. Keep the Play
  "What's new" within **500 characters** and framed around the
-  release's themes, not a feature dump.
+  release's themes, not a feature dump. Compare its **Foreground service
+  permissions** section with the merged `googlePlayRelease` manifest and
+  complete Play Console declarations for every declared service type before
+  approval; the Publisher API can upload a draft and still reject promotion
+  when an App content declaration is missing.

 #### Scrub for public distribution

@@ -610,8 +625,12 @@ git push origin dev
 Then open **Actions → Approve Android Release**, choose **Run workflow**, select
 `main`, and enter the version. Starting the workflow is the release approval. It
 verifies that `main` has the exact preflighted tree and creates the
-`android-v<version>` tag. Manual stable tags are still guarded by the same
-preflight proof in the tag workflow.
+`android-v<version>` tag. Because tags created with `GITHUB_TOKEN` do not trigger
+another workflow, approval dispatches the current release workflow definition
+from `main`; every release job explicitly checks out and verifies the immutable
+`android-v<version>` tag. This lets release-workflow fixes apply without moving
+an existing tag or changing its artifact tree. Manual stable tags are still
+guarded by the same preflight proof in the tag workflow.

 The tag-triggered `.github/workflows/release-android.yml` rebuilds and scans the
 artifacts, changes the existing Play Production draft to `completed` (submitting
@@ -1,10 +1,10 @@
-# Hermes-Relay-Android v1.5.0
+# Hermes-Relay-Android v1.8.1

-**Release Date:** July 25, 2026
+**Release Date:** August 9, 2026

 ## Download

-> Installing on your phone? Download `hermes-relay-1.5.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).
+> Installing on your phone? Download `hermes-relay-1.8.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).

 The `.aab` file is a Play Console upload bundle and cannot be installed by tapping it on a phone.

@@ -12,28 +12,23 @@ Verify the download against `SHA256SUMS.txt`. See the [sideload guide](https://h

 ## Summary

-This release makes the Hermes Dashboard and Gateway the clear standard connection, keeps active work reachable across the app and Android backgrounding, and gives profiles, voice, attachments, image generation, and approvals a more coherent native interface.
-
-## Added
-
- The Agent Passport drawer combines live route and session context with explicit profile switching, personality, model, reasoning, approval-policy, chat-override, and processing-tier controls.
- Secure browser-based Dashboard sign-in is scoped to the selected host. Chat, sessions, Manage, and Standard Voice share the same authenticated Gateway route while the API server remains an automatic fallback.
- Standard and Realtime voice settings use focused provider, model, and voice cards with upstream-aware discovery, descriptions, inline previews, waveforms, and a browsable catalog. Standard replies can begin speaking completed segments before generation finishes.
- User-started turns stay protected until every concurrent session settles. Privacy-safe notifications reopen the correct chat for approvals, questions, elevated permissions, or secure responses.
- Onboarding finishes with a layered permission review: notifications are recommended deliberately, optional capabilities remain separate, and users can continue without granting phone access.
- Chat surfaces one-turn model choices, approval modes, advisor progress, queued recovery, project labels, collapsible attachments, persisted images, interim Gateway events, and image-generation activity.
+This patch keeps long Hermes conversations complete and aligns Android's
+Gateway behavior with current upstream turn contracts.

 ## Fixed

- Gateway reconnects reactivate the original live session without resubmitting acknowledged prompts or duplicating session rows.
- Tailscale, QR, and other remote routes move Dashboard, Gateway, sessions, Manage, Standard Voice, API fallback, and optional Relay together.
- Dashboard authentication, model routing, recovery, and profile state stay scoped to the selected connection and session, including during cold start and rapid switching.
- Promoted voice and background tasks keep their owning Chat row until the work settles.
- User-installed certificate authorities work for self-hosted HTTPS/WSS while normal chain, hostname, and Relay-pin verification remain enforced.
- Malformed syntax-highlighting ranges no longer crash Markdown rendering.
- Developer Options no longer exposes the obsolete Relay feature flag; version-tap unlock, relock, backup, import, and reset actions now persist and report accurately.
+- Complete transcript reads page explicitly across both API-server and
+  profile-scoped Dashboard routes, so sessions beyond Hermes' latest-500
+  default retain stable history, sharing, retry, edit, and recovery anchors.
+- Gateway submit rejections preserve the authoritative server message without
+  silently falling through to SSE.
+- Gateway event envelopes reconcile consistently, and edit-and-regenerate
+  requests send the required truncation confirmation.

 ## Install / Verify

- App version: **1.5.0** (versionCode **33**).
- Standard Chat and Vanilla Hermes voice continue to work against unmodified upstream Hermes.
+- App version: **1.8.1** (versionCode **42**).
+- Standard Chat, sessions, Manage, and Vanilla Hermes voice continue to work
+  against unmodified upstream Hermes.
+- The optional Relay plugin is not required for standard Android chat or hosted
+  Dashboard authentication.
@@ -6,6 +6,63 @@ For shipped work, see `DEVLOG.md`. For architectural decisions, see `docs/decisi

 ---

+## Structured desktop hardware capabilities
+
+Desktop command, PowerShell, process, and job tools currently execute with the
+desktop daemon's OS-user authority. Add typed hardware operations for reliable
+schemas, audit detail, and task-scoped approval, but do not present hardware
+toggles as isolation while an enabled general shell can reach the same device.
+
+- Define per-host capabilities for commands, files, processes, clipboard,
+  screen, input, connected devices, microphone, and camera. Disabled must win,
+  hardware-sensitive capabilities must default off, and unavailable backends
+  must appear unavailable rather than as inert toggles.
+- Add a **Structured only** access profile that withholds shell/process escape
+  hatches so individual capability toggles become enforceable boundaries.
+- Implement connected-device support first with typed, serial-bound ADB
+  operations (`list`, `shell`, `push`, `pull`, `install`, and bounded logcat)
+  instead of a generic device-exec wrapper.
+- Add microphone and camera only with backend readiness detection, bounded local
+  grants, active-use indicators, audit events, and immediate cancellation.
+- Reconcile legacy `desktop_screenshot` with the task-granted computer screenshot
+  path so screen capture follows one policy.
+
+---
+
+## Android Plugin Studio protocol follow-ups
+
+The first live declarative Plugin lane is host-local: Relay tools create bounded
+draft JSON, Android previews it through the authenticated Dashboard namespace,
+and exact-digest Keep/Remove actions require an Android user tap. Complete the
+multi-session protocol before treating `lifecycle=session` as an isolation claim:
+
+- Derive draft ownership from trusted Hermes task context and store only an HMAC
+  of that identifier; never accept a model-supplied session owner.
+- Filter draft discovery by the Android app's active Hermes session while keeping
+  profile and connection publications separate with explicit precedence.
+- Replace foreground five-second catalog polling with authenticated catalog
+  invalidation events plus ETag polling fallback.
+- Expire abandoned drafts and pending approvals, and add revision-bound profile
+  versus connection promotion targets.
+
+---
+
+## Split fast Android unit tests from resource and screenshot tests
+
+The quick-loop commands now narrow execution to the sideload debug variant and
+support one-class filtering, but all `:app` unit tests still share one Android
+test variant. That variant includes merged Android resources, gives every test
+worker a 2 GiB heap, runs on JDK 21, and enables Roborazzi recording because a
+small subset of Robolectric/screenshot tests requires those settings.
+
+Create a separate resource/screenshot test lane so pure state, parser, routing,
+and formatting tests can run as ordinary JVM tests without Android resource
+packaging. Keep golden-image recording explicit rather than applying it to all
+unit tests, preserve a CI task that runs both lanes, and benchmark cold plus
+warm focused-test latency before adopting the split.
+
+---
+
 ## Verify Android native dashboard sign-in on device

 Android now selects Custom Tab + PKCE for HTTPS gateways that advertise
@@ -717,9 +774,10 @@ Deferred:

 A 5-agent audit compared the chat surface to Discord/Telegram/Messenger/iMessage/
 GitHub-mobile. **Shipped this pass (pending on-device verification):** a chat-tuned
-`markdownTypography()` ramp (headings were falling through to M3 display roles —
-h1=`displayLarge` 57sp in this app's scale — so a `#` was a billboard; now h1≈20sp
-scaling down, list/paragraph unified to 14sp, inline+fenced code 13sp, `textLink`
+  `markdownTypography()` ramp (headings were falling through to M3 display roles —
+  h1=`displayLarge` 57sp in this app's scale — so a `#` was a billboard; now h1≈20sp
+  scaling down, list/paragraph unified to 15sp/21sp, primary assistant prose moved
+  to the theme's full-contrast `onSurface`, inline+fenced code 13sp, `textLink`
 accent+underline) in `MarkdownContent.kt`; timestamp gated to `isLastInGroup` (was on
 every bubble) + grouping breaks on a >5min gap (`GROUP_GAP_MS`) so a resumed
 conversation gets its own beat; long-press haptic on the action menu; streaming dots
@@ -731,10 +789,6 @@ gated to pre-first-token. Deferred:
  parses one full CommonMark document so global link references, indentation, and
  nested containers remain correct; the viewport now anchors that same remeasure.
  Verify lists, tables, quotes, HTML, nested fences, and reference links on-device.
- **Bubble body 14sp → 15sp/21.** 14sp is the smallest body of the five reference
-  apps. Bump markdown paragraph/text/list + the two plain `Text` sites
-  (`MessageBubble.kt` user/system) together; keep ~1.4 leading so the ~272dp measure
-  stays ~36–38 chars/line. Debatable/broad — left out of the certain heading win.
 - **Tail-corner on last-in-group only (design decision).** The audit flagged the
  per-bubble bottom tail as "half-implemented," but it's a deliberate aesthetic
  (every bubble tails). Switching to iMessage-style "tail on the last bubble only"
@@ -1045,12 +1099,14 @@ to tool state, safety prompts, or the current task.
  playback-synchronized amplitude through `shouldMarkRealtimeOutputActive`,
  matching the basic-TTS path. Confirm visually on-device with the 1.4.1 batch.

- **Voice command layer — initial 1.4.1 subset code-complete; live verify and
-  navigation residuals remain.** Exact final transcripts can stop speech,
+- **Voice command layer — upstream stop phrases and phase-aware pause are
+  code-complete; live verify and navigation residuals remain.** Exact final transcripts can end the active voice chat,
  explicitly cancel the active background task, pause/resume Continuous mode,
-  repeat a settled background answer, and start a new Standard chat. Bare `stop`
-  and `cancel`, partial transcripts, and command-like ordinary prompts stay on the
-  normal Hermes route. Realtime `new chat` remains gated on a clean websocket
+  repeat a settled background answer, and start a new Standard chat. Bare
+  `stop` is configurable and exact-only while voice chat is active; bare
+  `pause` remains phase-gated to Continuous mode. `cancel`, partial transcripts,
+  and command-like ordinary prompts stay on the normal Hermes route. Realtime
+  `new chat` remains gated on a clean websocket
  session-rebind boundary; `open overlay` and `return to Hermes` remain future
  navigation commands. Verify barge-in Stop, pause during a background run, local
  command Chat cleanup, and Continuous rearm on device.
@@ -1085,11 +1141,34 @@ and whether the agent is waiting on the user.
  experimental barge-in choice. Relay update is server-first; local Voice/barge-in
  values share one DataStore transaction, with relay rollback on local failure.

- **Barge-in hardening** — keep barge-in experimental until echo/self-recording
+- **Barge-in hardening — code complete; on-device matrix remains.** Full-turn
+  listener ownership, AEC/noise suppression, upstream-compatible RMS
+  calibration and thresholds, configurable playback grace, duck/cut behavior,
+  late-delta fencing, next-turn interruption context, and single-microphone
+  handoff are implemented. Phone testing still needs to cover speakerphone/headphones, quiet/noisy rooms, Standard/Realtime
+  generation and playback, stop/pause, and resume-after-interruption.

-is solved. The target path is proper AEC, playback-ducking, and a rule that
+- **Experimental wake word — on-device validation.** Verify first-enable model
+  installation and integrity failure recovery, all supported ABIs, Android
+  notification/microphone permission variants, background-start restrictions,
+  task recreation from the detection notification, acoustic false-positive and
+  false-negative rates, battery impact, stop action, and wake→voice→wake
+  microphone handoff. Voice settings now provide a bounded real-microphone/model
+  test with an input meter; use it to distinguish audio capture from KWS tuning
+  before testing the full activation flow. The first release remains fixed to
+  “Hey Hermes”; do not
+  expose profile-specific phrases until routing and acoustic behavior are
+  implemented and validated.

-output audio can never become a user turn.
+- **Android Digital Assistant — on-device validation.** On a physical device,
+  select and remove Hermes through the system Assistant role; verify gesture,
+  power-button, screen-off, credential-lock, and unlocked “Hey Hermes”
+  invocation; confirm the system session appears without overlay/full-screen
+  permissions; exercise compact, expanded, collapsed, and full-Voice handoff
+  states, background tap-through, rotation and insets, cancel/back, microphone
+  denial, network failure, process kill/recreation, and wake→voice→wake
+  resumption. Measure idle battery drain because third-party assistants do not
+  receive Google's dedicated low-power hotword hardware.

 - **Audio quality guardrails** — normalize output volume across realtime and

@@ -1218,14 +1297,11 @@ Follow-ups:
  profile/skill-aware empty-state chips and the ~40-flow recomposition hotspot at
  the top of `ChatScreen`.
 - **Pet hot-load + in-app add/remove (shipped 2026-06-20).** Pets now live-refresh: an `avatarsRefreshTick` keys the avatar `produceState` in `RelayApp`, and Appearance re-scans `pets/` on open and after in-app import/delete — no app restart. Appearance gained "Add a pet" (SAF `.zip` import via `PetImporter`, zip-slip/zip-bomb guarded + validated through `toAvatar`) and an "Installed pets" list with per-pet remove (`PetLoader.deletePet`, confirm dialog, Sphere fallback). Remaining:
-  - **Sphere-skin parity.** Skins are still process-scoped + `adb push` only — the live tick and the importer cover pets, not skins. Extend the tick to `loadUserSkins` and add a `.json` skin import if hot-loading/adding skins in-app is wanted.
+  - **Sphere-skin parity (shipped 2026-08-09).** Appearance now imports a bounded, validated declarative `.json` skin through the system picker, hot-refreshes the shared sphere registry, and selects the imported skin without an app restart.
  - `**adb push` into `Android/data` hangs on Samsung scoped storage.** Confirmed: pushing a pet pack to `/sdcard/Android/data/<pkg>/files/pets/` stalls (no bytes written) although `adb shell ls` of the dir works. In-app `.zip` import is the supported path; `/sdcard/Download` pushes fine. Consider softening `docs/pet-spec.md` + user-docs to lead with in-app import over adb.
  - **On-device import/delete smoke.** Import `/sdcard/Download/lucy.zip` via Add a pet → confirm Lucy appears, selects, and animates all states; then remove it and confirm the avatar falls back to the Sphere.
- **Pet state-change re-decode can flash one blank frame.** When the agent state switches clips, the first frame of the new clip may briefly be blank during decode; prewarm/hold-last-frame to smooth it. Root cause is the same as the next item: `PetAvatar.Render` re-decodes from disk on every clip change.
- **Pet frame-sequence memory: no cap or downsample (audit 2026-06-19).** `decodeClip` decodes every frame of the selected clip into `List<ImageBitmap>` at full resolution with no `inSampleSize` downscale to the display size and no frame-count/dimension ceiling — a long sequence of large PNGs can use a lot of RAM and a single very large image can OOM `BitmapFactory`. Add `inSampleSize` downsampling to the avatar's draw size and/or a documented hard cap. Spec now warns authors (prefer sprite sheets), but the renderer doesn't enforce it.
- **Pet decoded-clip cache (audit 2026-06-19).** `PetAvatar.Render` keys `produceState` on `clip`, so idle→thinking→speaking→idle within one turn re-runs `BitmapFactory.decodeFile` from disk each transition (repeated I/O + GC churn, and the blank-frame flash above). Add a small per-avatar `Map<SphereState, PetFrames>` decode cache.
 - **Pet behavior model — richer state association (spec'd 2026-06-19, `docs/pet-spec.md` "Agent states &amp; pet behavior").** Shipped: the honesty clamp (declared reactivity ∩ `PET_RENDERER_CAPABILITIES`), the friendly `writing` alias, the `**working`/tool-use overlay** (pet-local sub-state from `toolCallBurst`; opt-in `working` clip drives both the swap and the Tools badge), the **one-shot reaction layer** (`greet`/`wake` on appear, `done`/`celebrate` on turn-finish — opt-in, play-once-then-revert, transition-derived; `ONE_SHOT_MAX_MS` backstop), and `**intensity` modulation** (opt-in `reactive.intensity` → live playback speedup ≤1.6× via `rememberUpdatedState`; un-clamps the Activity badge). Voice · Tools · Activity reactivity is now complete. Remaining:
  - `**attention` one-shot (only deferred behavior).** A reaction on notification arrival — needs a host event the avatar doesn't yet receive (unlike `greet`/`done`, which ride state transitions). Would plumb a notification edge into `AvatarRenderState` (or a side channel) + a `PetOneShot.Attention`. Low priority: the avatar is rarely on-screen when notifications land (backgrounded) — see the value analysis; revisit only if the avatar becomes an always-on surface (persistent overlay / Quest port).
-  - **On-device verification (working + one-shots + intensity).** Best seen in clean mode (`AgentTextFlow` feeds `toolCallBurst` + `streamingIntensity` + state transitions). Confirm: a `working` clip swaps in during a tool run and releases ~600ms after (`WORKING_BURST_THRESHOLD` 0.5); a `done` clip plays once on reply completion then returns to idle; a `greet` clip plays once when the avatar appears; with `intensity:true`, a writing/working loop visibly quickens while streaming. Watch for the known clip re-decode flash on each swap (separate TODO — decoded-clip cache).
+  - **On-device verification (working + one-shots + intensity).** Best seen in clean mode (`AgentTextFlow` feeds `toolCallBurst` + `streamingIntensity` + state transitions). Confirm: a `working` clip swaps in during a tool run and releases ~600ms after (`WORKING_BURST_THRESHOLD` 0.5); a `done` clip plays once on reply completion then returns to idle; a `greet` clip plays once when the avatar appears; with `intensity:true`, a writing/working loop visibly quickens while streaming. Confirm each decoded clip swap holds the previous complete visual until the new state is ready.
 - **Undecodable-but-present image appears valid (audit 2026-06-19).** A file that exists but isn't a decodable image passes the loader's `isFile` check, so the pet shows in the picker but renders blank. Documented as a caveat; consider a cheap header sniff at load time if false-valid pets become a support issue.

@@ -7,6 +7,15 @@ plugins {
    alias(libs.plugins.play.publisher)
 }

+val supportedHermesDevAbis = setOf("arm64-v8a", "armeabi-v7a", "x86", "x86_64")
+val hermesDevAbi = providers.gradleProperty("hermes.devAbi").orNull
+hermesDevAbi?.let { requestedAbi ->
+    require(requestedAbi in supportedHermesDevAbis) {
+        "Unsupported hermes.devAbi '$requestedAbi'. Expected one of: " +
+            supportedHermesDevAbis.sorted().joinToString()
+    }
+}
+
 // Rename output artifacts to include the app version. AGP respects
 // `archivesName` for both APK (assemble*) and AAB (bundle*) outputs, so
 // this single line produces `hermes-relay-<version>-<flavor>-<buildType>`
@@ -37,12 +46,23 @@ android {
        // exempt from Play's 14-day closed-testing rule. See RELEASE.md.
        applicationId = "com.axiomlabs.hermesrelay"
        minSdk = 26
-        targetSdk = 35
+        targetSdk = 36
        versionCode = libs.versions.appVersionCode.get().toInt()
        versionName = libs.versions.appVersionName.get()

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"

+        // Optional local-only fast path for device iteration. Native voice/VAD
+        // dependencies make the universal sideload APK very large, while a
+        // connected phone needs only its own ABI. Release and normal debug
+        // builds remain universal unless the developer explicitly supplies
+        // -Phermes.devAbi=<abi>.
+        hermesDevAbi?.let { requestedAbi ->
+            ndk {
+                abiFilters += requestedAbi
+            }
+        }
+
        // Feature flags — DEV_MODE enables all experimental features in debug builds
        buildConfigField("boolean", "DEV_MODE", "false")
    }
@@ -125,6 +145,7 @@ android {
        }
        release {
            isMinifyEnabled = true
+            isShrinkResources = true
            ndk {
                debugSymbolLevel = "SYMBOL_TABLE"
            }
@@ -164,6 +185,21 @@ android {
        }
    }

+    packaging {
+        jniLibs {
+            // sherpa-onnx v1.13.4 and the Silero VAD both use ONNX Runtime.
+            // Keep them on sherpa's 1.27.0 baseline and package one shared core.
+            pickFirsts += "**/libonnxruntime.so"
+
+            // The Android app calls only sherpa's JNI facade. These native C/C++
+            // API facades are development surfaces and are not loaded by the app.
+            excludes += setOf(
+                "**/libsherpa-onnx-c-api.so",
+                "**/libsherpa-onnx-cxx-api.so",
+            )
+        }
+    }
+
    // JVM unit tests run against the stubbed Android SDK jar, where every
    // platform API method throws RuntimeException("... not mocked") by
    // default. With returnDefaultValues = true, those stubs instead
@@ -262,6 +298,12 @@ dependencies {
    // Bundled ONNX Silero model (~2.2 MB); pulled from JitPack.
    implementation(libs.android.vad.silero)

+    // Experimental, opt-in local keyword spotting. Models are downloaded only
+    // after the user enables the feature; no model binary is bundled in APKs.
+    // Keep the shared runtime aligned with sherpa-onnx v1.13.4.
+    implementation(libs.onnxruntime.android)
+    implementation(libs.sherpa.onnx)
+
    // Google Play In-App Update — googlePlay flavor ONLY (FLEXIBLE flow).
    // Scoped via the `googlePlayImplementation` configuration so it never
    // ships in the sideload APK, which updates via the GitHub-releases
@@ -278,6 +320,7 @@ dependencies {
    // Coil 3 — async image loading for generated images in chat
    implementation(libs.coil.compose)
    implementation(libs.coil.network.okhttp)
+    implementation(libs.exifinterface)

    // QR Code scanning (ML Kit + CameraX)
    implementation(libs.mlkit.barcode)
@@ -327,8 +370,8 @@ dependencies {
    // [POC] Roborazzi host-side screenshot rendering (src/test, Robolectric).
    // Renders real composables on the JVM at an exact canvas — no device, no
    // status bar, no clipping. See StoreScreenshotTest.
-    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.70.0")
-    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.70.0")
+    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.71.0")
+    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.71.0")
    testImplementation(libs.compose.ui.test.junit4)
    testImplementation(libs.compose.ui.test.manifest)
    testImplementation("androidx.test.ext:junit:1.3.0")
@@ -0,0 +1,70 @@
+package com.hermesandroid.relay.plugins.ui
+
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.ui.test.assertIsDisplayed
+import androidx.compose.ui.test.isToggleable
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performClick
+import com.hermesandroid.relay.plugins.document.PluginDocumentState
+import com.hermesandroid.relay.plugins.document.PluginElement
+import com.hermesandroid.relay.plugins.document.PluginPage
+import com.hermesandroid.relay.plugins.document.PluginText
+import com.hermesandroid.relay.plugins.document.PluginValue
+import org.junit.Assert.assertEquals
+import org.junit.Rule
+import org.junit.Test
+
+class PluginDocumentRendererTest {
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun pageRendersBindingsAndEmitsControlledStateChanges() {
+        var interaction: PluginInteraction? = null
+        val page = PluginPage(
+            id = "home",
+            title = PluginText.Binding("title", "Fallback"),
+            content = PluginElement.Group(
+                id = "root",
+                children = listOf(
+                    PluginElement.Text(
+                        id = "message",
+                        text = PluginText.Binding("message"),
+                    ),
+                    PluginElement.Toggle(
+                        id = "enabled-toggle",
+                        label = PluginText.Literal("Enabled"),
+                        binding = "enabled",
+                    ),
+                ),
+            ),
+        )
+        val state = PluginDocumentState(
+            mapOf(
+                "title" to PluginValue.StringValue("Status plugin"),
+                "message" to PluginValue.StringValue("Everything is healthy"),
+                "enabled" to PluginValue.BooleanValue(false),
+            ),
+        )
+
+        composeTestRule.setContent {
+            MaterialTheme {
+                PluginPageRenderer(page, state, { interaction = it })
+            }
+        }
+
+        composeTestRule.onNodeWithText("Status plugin").assertIsDisplayed()
+        composeTestRule.onNodeWithText("Everything is healthy").assertIsDisplayed()
+        composeTestRule.onNode(isToggleable()).performClick()
+
+        assertEquals(
+            PluginInteraction.ValueChanged(
+                elementId = "enabled-toggle",
+                key = "enabled",
+                value = PluginValue.BooleanValue(true),
+            ),
+            interaction,
+        )
+    }
+}
@@ -0,0 +1,147 @@
+package com.hermesandroid.relay.ui.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.testTag
+import androidx.compose.ui.test.assertDoesNotExist
+import androidx.compose.ui.test.assertExists
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithContentDescription
+import androidx.compose.ui.test.onNodeWithTag
+import androidx.compose.ui.test.onNodeWithText
+import androidx.test.platform.app.InstrumentationRegistry
+import com.hermesandroid.relay.R
+import com.hermesandroid.relay.ui.components.avatar.AgentAvatar
+import com.hermesandroid.relay.ui.components.avatar.AvatarRenderState
+import com.hermesandroid.relay.ui.components.avatar.AvatarSource
+import com.hermesandroid.relay.ui.components.avatar.LocalAgentAvatar
+import com.hermesandroid.relay.ui.components.avatar.LocalBackgroundVisualizationEnabled
+import com.hermesandroid.relay.viewmodel.InteractionMode
+import com.hermesandroid.relay.viewmodel.VoiceState
+import com.hermesandroid.relay.viewmodel.VoiceUiState
+import org.junit.Rule
+import org.junit.Test
+
+class AmbientVisualizationVisibilityTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun cleanMode_backgroundOff_hidesSphereAndKeepsComposer() {
+        composeTestRule.setContent {
+            AmbientTestProviders(enabled = false) {
+                CleanChatMode(
+                    messages = emptyList(),
+                    isStreaming = false,
+                    sphereState = SphereState.Idle,
+                    streamingIntensity = 0f,
+                    toolCallBurst = 0f,
+                    animationEnabled = true,
+                    enabled = true,
+                    onSend = {},
+                    onExit = {},
+                )
+            }
+        }
+
+        composeTestRule.onNodeWithTag(AMBIENT_RENDERER_TAG).assertDoesNotExist()
+        composeTestRule.onNodeWithContentDescription(targetString(R.string.agent_text_send_cd))
+            .assertExists()
+    }
+
+    @Test
+    fun cleanMode_backgroundOn_rendersSphere() {
+        composeTestRule.setContent {
+            AmbientTestProviders(enabled = true) {
+                CleanChatMode(
+                    messages = emptyList(),
+                    isStreaming = false,
+                    sphereState = SphereState.Idle,
+                    streamingIntensity = 0f,
+                    toolCallBurst = 0f,
+                    animationEnabled = false,
+                    enabled = true,
+                    onSend = {},
+                    onExit = {},
+                )
+            }
+        }
+
+        composeTestRule.onNodeWithTag(AMBIENT_RENDERER_TAG).assertExists()
+    }
+
+    @Test
+    fun voiceMode_backgroundOff_hidesSphereAndKeepsVoiceUi() {
+        composeTestRule.setContent {
+            AmbientTestProviders(enabled = false) {
+                TestVoiceOverlay()
+            }
+        }
+
+        composeTestRule.onNodeWithTag(AMBIENT_RENDERER_TAG).assertDoesNotExist()
+        composeTestRule.onNodeWithText(targetString(R.string.voice_overlay_tap_mic)).assertExists()
+    }
+
+    @Test
+    fun voiceMode_backgroundOn_rendersSphere() {
+        composeTestRule.setContent {
+            AmbientTestProviders(enabled = true) {
+                TestVoiceOverlay()
+            }
+        }
+
+        composeTestRule.onNodeWithTag(AMBIENT_RENDERER_TAG).assertExists()
+    }
+
+    @Composable
+    private fun AmbientTestProviders(enabled: Boolean, content: @Composable () -> Unit) {
+        MaterialTheme {
+            CompositionLocalProvider(
+                LocalAgentAvatar provides TaggedAmbientRenderer,
+                LocalBackgroundVisualizationEnabled provides enabled,
+                content = content,
+            )
+        }
+    }
+
+    @Composable
+    private fun TestVoiceOverlay() {
+        VoiceModeOverlay(
+            uiState = VoiceUiState(
+                voiceMode = true,
+                state = VoiceState.Idle,
+                interactionMode = InteractionMode.TapToTalk,
+            ),
+            onMicTap = {},
+            onMicRelease = {},
+            onInterrupt = {},
+            onDismiss = {},
+            onModeChange = {},
+            onClearError = {},
+        )
+    }
+
+    private fun targetString(id: Int): String =
+        InstrumentationRegistry.getInstrumentation().targetContext.getString(id)
+
+    private object TaggedAmbientRenderer : AgentAvatar {
+        override val id = "ambient-test"
+        override val label = "Ambient test"
+        override val description = "Test renderer"
+        override val source = AvatarSource.BUILT_IN
+        override val reactivity = SphereReactivity()
+
+        @Composable
+        override fun Render(state: AvatarRenderState, modifier: Modifier) {
+            Box(modifier = modifier.testTag(AMBIENT_RENDERER_TAG))
+        }
+    }
+
+    private companion object {
+        const val AMBIENT_RENDERER_TAG = "ambientVisualizationRenderer"
+    }
+}
@@ -121,12 +121,15 @@ class OnboardingFlowTest {
    }

    @Test
-    fun connectPage_showsNearbyFirst() {
+    fun connectPage_recommendsGeneralSetupQr() {
        setOnboardingContent()
        navigateToPage(4)

        composeTestRule
-            .onNodeWithText("Enter address instead")
+            .onNodeWithText("Scan Hermes setup QR")
+            .assertIsDisplayed()
+        composeTestRule
+            .onNodeWithText("Recommended")
            .assertIsDisplayed()
    }

@@ -135,7 +138,7 @@ class OnboardingFlowTest {
        setOnboardingContent()
        navigateToPage(4)

-        composeTestRule.onNodeWithText("Enter address instead").performClick()
+        composeTestRule.onNodeWithText("Server or VPS").performClick()
        composeTestRule.waitForIdle()

        composeTestRule
@@ -148,7 +151,7 @@ class OnboardingFlowTest {
        setOnboardingContent()
        navigateToPage(4)

-        composeTestRule.onNodeWithText("Enter address instead").performClick()
+        composeTestRule.onNodeWithText("Server or VPS").performClick()
        composeTestRule.waitForIdle()

        composeTestRule
@@ -156,12 +159,28 @@ class OnboardingFlowTest {
            .assertIsDisplayed()
    }

+    @Test
+    fun cloudSetup_requestsTheHostedDashboardAddress() {
+        setOnboardingContent()
+        navigateToPage(4)
+
+        composeTestRule.onNodeWithText("Nous-hosted Hermes").performClick()
+        composeTestRule.waitForIdle()
+
+        composeTestRule
+            .onNodeWithText("Connect to Nous-hosted Hermes")
+            .assertIsDisplayed()
+        composeTestRule
+            .onNodeWithText("Use the complete HTTPS address shown for your hosted agent.")
+            .assertIsDisplayed()
+    }
+
    @Test
    fun connectPage_keepsPairingOptional() {
        setOnboardingContent()
        navigateToPage(4)

-        composeTestRule.onNodeWithText("Other connection methods").performClick()
+        composeTestRule.onNodeWithText("Advanced").performClick()
        composeTestRule.waitForIdle()

        composeTestRule
@@ -1 +1 @@
-Connect through secure Dashboard sign-in, switch profiles from the new Agent Passport, and keep multiple background chats active with actionable approval and question alerts. Image generation, attachments, model routing, voice, and Gateway recovery are clearer and more reliable. Setup now guides optional notification, camera, microphone, and companion permissions without blocking chat.
+Long sessions now retain complete history beyond Hermes' latest-500 default, keeping edit, retry, sharing, and recovery anchors stable. Gateway submit rejections preserve the server's message without unintended SSE fallback, while event envelopes and edit-and-regenerate requests follow current upstream contracts.
@@ -1 +1 @@
-通过安全的 Dashboard 登录连接，并在新的智能体护照中切换配置文件。多个后台对话可保持运行，审批或提问通知可直接返回正确会话。图像生成、附件、模型路由、语音和 Gateway 恢复更加清晰可靠。设置流程会说明可选的通知、相机、麦克风和通知伴侣权限，且不会阻止聊天。
+新增可在界面中漫游的 Petdex 浮动宠物、由已安装 Hermes 插件提供的安全原生页面，以及支持本地“Hey Hermes”的可选 Android 数字助理。本次更新还新增俄语，并改进语音恢复、路线切换、实时聊天稳定性和宠物移动。
@@ -20,6 +20,7 @@
         for the device-control bridge service; the merger dedups.) -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />

    <uses-feature android:name="android.hardware.camera" android:required="false" />

@@ -47,6 +48,32 @@
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
+            <!-- User-mediated text handoff. The app opens a fresh Chat draft
+                 and fills the composer; it never sends from an external intent. -->
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="text/*" />
+            </intent-filter>
+            <!-- The loopback native-PKCE result page uses this fixed, tokenless
+                 link only to bring the installed flavor back to the foreground.
+                 MainActivity intentionally does not interpret the URI as an auth
+                 callback or navigation command. -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="${applicationId}"
+                    android:host="return" />
+            </intent-filter>
+            <!-- Some Android OEM assistant pickers enumerate ACTION_ASSIST
+                 activities in addition to VoiceInteractionService providers. -->
+            <intent-filter>
+                <action android:name="android.intent.action.ASSIST" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.VOICE" />
+            </intent-filter>
        </activity>

        <!-- AppCompat persists in-app language choices on Android 12 and lower.
@@ -93,8 +120,8 @@
        <!-- Protects user-started active turns automatically; the optional
             "Persistent connection" setting extends the same foreground
             protection to idle/background connectivity (and relay-paired
-             device features). In main so BOTH flavors ship it. specialUse
-             needs a Play Console foreground-service declaration at submission. -->
+             device features). In main so BOTH flavors ship it. Every Play
+             foreground-service type needs its matching App content declaration. -->
        <service
            android:name=".network.upstream.GatewayKeepAliveService"
            android:exported="false"
@@ -104,6 +131,70 @@
                android:value="Keeps user-started Hermes turns connected until they finish or need input, and optionally keeps idle connections responsive when the user enables Persistent connection." />
        </service>

+        <!-- Experimental, explicitly user-started on-device wake-word listener.
+             Audio remains local and the service is never boot/restart started.
+             The Play build's microphone type needs an App content declaration. -->
+        <service
+            android:name=".wake.WakeWordForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="microphone"
+            android:stopWithTask="false" />
+
+        <!-- User-started protection for voice capture from the system overlay.
+             The service does not own AudioRecord; it keeps foreground-only
+             microphone app-ops available while Hermes is behind another app.
+             Include this use case in the Play microphone declaration. -->
+        <service
+            android:name=".voice.VoiceOverlayForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="microphone"
+            android:stopWithTask="false" />
+
+        <!-- Explicitly opt-in Android Digital Assistant integration. Android
+             binds this only after the user selects Hermes for ROLE_ASSISTANT. -->
+        <service
+            android:name=".assistant.HermesVoiceInteractionService"
+            android:exported="true"
+            android:label="@string/assistant_service_label"
+            android:permission="android.permission.BIND_VOICE_INTERACTION">
+            <intent-filter>
+                <action android:name="android.service.voice.VoiceInteractionService" />
+            </intent-filter>
+            <meta-data
+                android:name="android.voice_interaction"
+                android:resource="@xml/voice_interaction_service" />
+        </service>
+
+        <!-- Heavy assistant UI is isolated from the always-running interaction
+             service, matching the platform lifecycle guidance. -->
+        <service
+            android:name=".assistant.HermesVoiceInteractionSessionService"
+            android:exported="true"
+            android:permission="android.permission.BIND_VOICE_INTERACTION"
+            android:process=":assistant_session" />
+
+        <!-- Required companion component for VoiceInteractionService metadata.
+             Hermes session transcription remains owned by the existing voice
+             pipeline; this service does not open a second microphone stream. -->
+        <service
+            android:name=".assistant.HermesRecognitionService"
+            android:exported="true"
+            android:permission="android.permission.BIND_VOICE_INTERACTION">
+            <intent-filter>
+                <action android:name="android.speech.RecognitionService" />
+                <category android:name="android.intent.category.DEFAULT" />
+            </intent-filter>
+        </service>
+
+        <receiver
+            android:name=".assistant.AssistantSessionStateReceiver"
+            android:exported="false"
+            android:process=":assistant_session" />
+
+        <receiver
+            android:name=".assistant.AssistantSessionLifecycleReceiver"
+            android:exported="false" />
+
    </application>

 </manifest>
@@ -1,5 +1,242 @@
 {
 "versions": [
+  {
+   "version": "1.8.1",
+   "title": "Complete, reliable transcripts",
+   "date": "2026-08-09",
+   "sections": [
+    {
+     "header": "Keep long sessions complete",
+     "bullets": [
+      "Android pages explicitly through complete API-server and profile-scoped Dashboard history instead of silently stopping at Hermes' latest-500 default.",
+      "Sharing, retry, edit, and recovery retain stable transcript anchors while bounded safety limits keep unusually large reads controlled."
+     ]
+    },
+    {
+     "header": "Follow Gateway truth",
+     "bullets": [
+      "Authoritative submit rejections preserve the server's message without an unintended SSE fallback.",
+      "Gateway event envelopes and edit-and-regenerate truncation confirmation now follow current upstream contracts."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.8.0",
+   "title": "Conversations with more context",
+   "date": "2026-08-09",
+   "sections": [
+    {
+     "header": "Keep the whole turn together",
+     "bullets": [
+      "Quote, edit, search, and attach or reorder files without losing the active connection, profile, or session.",
+      "Share text from another Android app into a fresh Chat draft for review before sending."
+     ]
+    },
+    {
+     "header": "See the work without the clutter",
+     "bullets": [
+      "Live thinking settles into a compact Thought disclosure, while routine tool activity groups into concise runs.",
+      "Approvals, failures, generated media, file changes, risks, and delegated work remain clearly distinct."
+     ]
+    },
+    {
+     "header": "Switch agents, not identities",
+     "bullets": [
+      "The Profile Shelf switches agents from Chat while restoring each profile's last session.",
+      "Agent Passport model and reasoning controls remain scoped to the active session instead of rewriting server defaults."
+     ]
+    },
+    {
+     "header": "Make it yours",
+     "bullets": [
+      "Preview theme accents and shapes, Sphere skins, and pets in one Appearance workflow.",
+      "Message speech controls, pet touch targets, scrolling terrain, image rotation, and edge-to-edge settings layout are more reliable."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.7.1",
+   "title": "Safer, steadier conversations",
+   "date": "2026-08-08",
+   "sections": [
+    {
+     "header": "Chat stays with you",
+     "bullets": [
+      "Growing streamed replies stay visible while you are at the bottom, and intentional scrollback remains undisturbed.",
+      "Completed replies render Markdown immediately while live tool details remain expandable."
+     ]
+    },
+    {
+     "header": "Sessions keep their ownership",
+     "bullets": [
+      "Queued follow-ups retain their originating connection, profile, session, route, attachments, and voice context.",
+      "Session pins and archives persist across restarts, and duplicate model rows are reconciled before rendering."
+     ]
+    },
+    {
+     "header": "Safer controls and setup",
+     "bullets": [
+      "Approval cards require an explicit labeled decision, and Agent Passport safety controls are easier to read and dismiss.",
+      "Hosted Hermes setup completes through the official Dashboard system-browser sign-in flow."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.7.0",
+   "title": "Smarter controls, steadier sessions",
+   "date": "2026-08-06",
+   "sections": [
+    {
+     "header": "Model controls fit the model",
+     "bullets": [
+      "Reasoning effort choices follow the selected provider and model when an exact supported list is available.",
+      "Unmodified Hermes and setups without the optional Relay capability overlay keep a fail-soft standard choice list."
+     ]
+    },
+    {
+     "header": "Active chats stay easy to follow",
+     "bullets": [
+      "The searchable session drawer shows which conversations are working or waiting for input.",
+      "Restored and completed chats remain bottom-pinned through late layout changes without overriding intentional scrollback.",
+      "Chat and Voice keep stable rows through recovery, and Focus Voice controls receive taps normally."
+     ]
+    },
+    {
+     "header": "Support stays private and useful",
+     "bullets": [
+      "Review locally redacted support information before choosing to copy, share, or open GitHub; nothing uploads automatically.",
+      "Connection diagnostics identify the failed operation and offer targeted guidance without exposing hosts or credentials."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.6.1",
+   "title": "Clearer recovery, steadier chat",
+   "date": "2026-08-03",
+   "sections": [
+    {
+     "header": "Relay stays optional",
+     "bullets": [
+      "Relay-only surfaces now use consistent Optional, Ready, Reconnecting, Unavailable, and Needs re-pair states without nagging from background session refreshes.",
+      "Foreground recovery retries ordinary reconnect backoff immediately and explains whether Relay credentials are merely stored or actually need re-pairing."
+     ]
+    },
+    {
+     "header": "Sessions and chat stay stable",
+     "bullets": [
+      "The session drawer restores its 200-row window through upstream-compatible 100-row pages.",
+      "Selecting streamed text stays stable when a completed response changes to rendered Markdown."
+     ]
+    },
+    {
+     "header": "Voice controls stay reachable",
+     "bullets": [
+      "Manual recording waits for the previous microphone owner to release it and gives a useful recovery message if capture cannot start.",
+      "New-chat coaching yields while Voice owns the composer so it cannot cover the expanding Voice drawer."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.6.0",
+   "title": "Pets, plugins, and voice",
+   "date": "2026-08-02",
+   "sections": [
+    {
+     "header": "A companion with personality",
+     "bullets": [
+      "Browse and install Petdex companions, or import your own pet without replacing the agent avatar or background Sphere.",
+      "Drag a pet anywhere or let it roam across measured chat bubbles, settings cards, controls, and other safe UI ledges."
+     ]
+    },
+    {
+     "header": "Native plugin pages",
+     "bullets": [
+      "Installed Hermes plugins can contribute host-rendered native pages without loading executable plugin code on the phone.",
+      "Scoped writes stay off until granted, while Relay 1.5.0 adds approval-gated agent-created page previews."
+     ]
+    },
+    {
+     "header": "Hermes as your assistant",
+     "bullets": [
+      "Optionally select Hermes as Android’s Digital Assistant and use a local “Hey Hermes” listener for background or locked-screen sessions.",
+      "Compact assistant and floating Voice controls expand for detail and continue the same turn when full Voice opens."
+     ]
+    },
+    {
+     "header": "More reliable everywhere",
+     "bullets": [
+      "Voice output recovery, long recordings, route failover, streamed chat identity, and pet terrain recovery are more resilient.",
+      "Android now includes a complete AI-assisted Russian catalog refreshed for the 1.6 feature set."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.5.3",
+   "title": "Voice stays open",
+   "date": "2026-07-31",
+   "sections": [
+    {
+     "header": "Stable voice transcripts",
+     "bullets": [
+      "Voice Focus keeps stable transcript rows while live messages reconcile with persisted chat history, preventing duplicate-key crashes that could close the app."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.5.2",
+   "title": "Sign in without detours",
+   "date": "2026-07-28",
+   "sections": [
+    {
+     "header": "Provider-compatible sign-in",
+     "bullets": [
+      "Self-hosted OIDC returns through the dashboard callback, while Nous Portal opens securely in the system browser.",
+      "Private-LAN and Tailscale dashboard routes preserve the configured HTTPS callback and keep credentials scoped to the active connection."
+     ]
+    },
+    {
+     "header": "Stable conversation updates",
+     "bullets": [
+      "Replayed upstream chat events are coalesced before rendering so duplicate message identifiers do not destabilize the conversation list."
+     ]
+    }
+   ]
+  },
+  {
+   "version": "1.5.1",
+   "title": "Voice and chat stay in place",
+   "date": "2026-07-26",
+   "sections": [
+    {
+     "header": "Voice at the right depth",
+     "bullets": [
+      "Use Voice Focus for a compact spoken-turn view or Conversation for the complete Chat renderer without leaving the active voice session.",
+      "Keep intermediate work visual while supported voice paths wait to speak the settled final response."
+     ]
+    },
+    {
+     "header": "Reliable narration and background work",
+     "bullets": [
+      "Standard Voice now speaks valid completed replies after generation hands off to narration.",
+      "Realtime background tasks release foreground voice controls while their progress and results remain reachable."
+     ]
+    },
+    {
+     "header": "Formatted answers stay readable",
+     "bullets": [
+      "Completed streams render headings, lists, emphasis, and code blocks without returning to the beginning of the answer.",
+      "Assistant text uses stronger theme contrast and a more comfortable chat reading scale."
+     ]
+    }
+   ]
+  },
  {
   "version": "1.5.0",
   "title": "Hermes, always in reach",
@@ -1,6 +1,6 @@
-v1.5.0 - Hermes, always in reach
+v1.8.1 - Complete, reliable transcripts

-* Connect through secure Dashboard sign-in and switch profiles from the new Agent Passport.
-* Keep multiple background chats active and reopen the right session from approval or question alerts.
-* Follow richer attachments, image generation, model routing, Gateway recovery, and streaming voice.
-* Finish setup with clear, optional permission guidance that never blocks standard chat.
+* Keep complete history in long sessions beyond Hermes' latest-500 default.
+* Preserve stable edit, retry, sharing, and recovery anchors while paging history.
+* Show authoritative Gateway rejection messages without an unintended fallback.
+* Reconcile Gateway events and edit-and-regenerate requests with current upstream contracts.
@@ -1,6 +1,9 @@
 package com.hermesandroid.relay

+import android.app.ActivityManager
 import android.app.Application
+import android.content.Context
+import android.os.Build
 import coil3.ImageLoader
 import coil3.PlatformContext
 import coil3.SingletonImageLoader
@@ -9,11 +12,24 @@ import coil3.request.crossfade
 import com.hermesandroid.relay.bridge.UnattendedAccessManager
 import com.hermesandroid.relay.data.AppAnalytics
 import com.hermesandroid.relay.power.WakeLockManager
+import com.hermesandroid.relay.runtime.HermesProcessRuntime
 import com.hermesandroid.relay.util.AppForegroundTracker
 import com.hermesandroid.relay.util.CrashReporter

 class HermesRelayApp : Application(), SingletonImageLoader.Factory {

+    /**
+     * Shared chat/voice runtime for the main application process. It is lazy so
+     * the always-available assistant session UI process stays lightweight and
+     * cannot accidentally become a second microphone/session owner.
+     */
+    val runtime: HermesProcessRuntime by lazy(LazyThreadSafetyMode.SYNCHRONIZED) {
+        check(isMainApplicationProcess()) {
+            "HermesProcessRuntime may only be created in the main application process"
+        }
+        HermesProcessRuntime(this)
+    }
+
    /**
     * Coil's singleton image loader for the whole app. Registering the OkHttp
     * network fetcher EXPLICITLY guarantees `http(s)` image URLs (e.g. a
@@ -51,6 +67,19 @@ class HermesRelayApp : Application(), SingletonImageLoader.Factory {
        AppForegroundTracker.initialize()
    }

+    private fun isMainApplicationProcess(): Boolean {
+        val processName = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+            getProcessName()
+        } else {
+            val pid = android.os.Process.myPid()
+            val activityManager = getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager
+            activityManager.runningAppProcesses
+                ?.firstOrNull { process -> process.pid == pid }
+                ?.processName
+        }
+        return processName == packageName
+    }
+
    companion object {
        lateinit var instance: HermesRelayApp
            private set
@@ -5,16 +5,18 @@ import android.content.Context
 import android.content.Intent
 import android.media.projection.MediaProjectionManager
 import android.os.Bundle
+import android.os.Build
 import android.util.Log
 import android.view.View
+import android.view.WindowManager
 import android.view.animation.DecelerateInterpolator
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.activity.result.contract.ActivityResultContracts
-import androidx.activity.viewModels
 import androidx.core.animation.doOnEnd
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import androidx.appcompat.app.AppCompatActivity
+import androidx.lifecycle.lifecycleScope
 import com.hermesandroid.relay.accessibility.ScreenCaptureRequester
 import com.hermesandroid.relay.bridge.BridgeForegroundService
 import com.hermesandroid.relay.bridge.UnattendedAccessManager
@@ -23,11 +25,16 @@ import com.hermesandroid.relay.notifications.TurnCompleteNotifier
 import com.hermesandroid.relay.notifications.InteractionRequestNotifier
 import com.hermesandroid.relay.ui.RelayApp
 import com.hermesandroid.relay.util.NavRouteRequest
+import com.hermesandroid.relay.util.SharedTextRequest
+import com.hermesandroid.relay.util.extractSharedText
 import com.hermesandroid.relay.viewmodel.ConnectionViewModel
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.flow.collect

 class MainActivity : AppCompatActivity() {

-    private val connectionViewModel: ConnectionViewModel by viewModels()
+    private val connectionViewModel: ConnectionViewModel
+        get() = (applicationContext as HermesRelayApp).runtime.connectionViewModel

    // === PHASE3-bridge-ui-followup: MediaProjection consent flow ===
    // ActivityResultLauncher for the system screen-capture consent dialog.
@@ -67,6 +74,8 @@ class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        val splashScreen = installSplashScreen()
+        com.hermesandroid.relay.assistant.AssistantSessionProtocol
+            .prepareAssistActivation(intent)

        // Hold splash until DataStore is loaded and onboarding status is known
        splashScreen.setKeepOnScreenCondition {
@@ -88,6 +97,12 @@ class MainActivity : AppCompatActivity() {
        }

        super.onCreate(savedInstanceState)
+        configureAssistantWindow(intent)
+        lifecycleScope.launch {
+            com.hermesandroid.relay.assistant.AssistantAppSessionState.active.collect { active ->
+                if (!active) clearAssistantWindow()
+            }
+        }
        enableEdgeToEdge()

        // === PHASE3-bridge-ui-followup: install MediaProjection requester ===
@@ -114,6 +129,15 @@ class MainActivity : AppCompatActivity() {
        // in RelayApp's NavRouteRequest collector — we just pump the request
        // into the SharedFlow here.
        consumeNavRouteIntent(intent)
+        consumeSharedTextIntent(intent)
+        val consumedAssistantActivation =
+            com.hermesandroid.relay.assistant.AssistantSessionProtocol.consumeActivation(
+                this,
+                intent,
+            )
+        if (!consumedAssistantActivation) {
+            com.hermesandroid.relay.assistant.AssistantSessionProtocol.restoreActivation(this)
+        }
        // === END PHASE3-safety-rails-followup ===
        setContent {
            RelayApp()
@@ -122,6 +146,9 @@ class MainActivity : AppCompatActivity() {

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
+        com.hermesandroid.relay.assistant.AssistantSessionProtocol
+            .prepareAssistActivation(intent)
+        configureAssistantWindow(intent)
        // === PHASE3-safety-rails-followup: deep-link nav route on re-launch ===
        // Same as onCreate but for the singleTask / FLAG_ACTIVITY_CLEAR_TOP
        // path: when the app is already running and the foreground service's
@@ -129,6 +156,8 @@ class MainActivity : AppCompatActivity() {
        // instead of onCreate. RelayApp's collector handles both cases.
        setIntent(intent)
        consumeNavRouteIntent(intent)
+        consumeSharedTextIntent(intent)
+        com.hermesandroid.relay.assistant.AssistantSessionProtocol.consumeActivation(this, intent)
        // === END PHASE3-safety-rails-followup ===
    }

@@ -138,6 +167,49 @@ class MainActivity : AppCompatActivity() {
        NavRouteRequest.tryRequest(route)
    }

+    private fun consumeSharedTextIntent(intent: Intent?) {
+        val sharedText = extractSharedText(
+            action = intent?.action,
+            mimeType = intent?.type,
+            text = intent?.getCharSequenceExtra(Intent.EXTRA_TEXT),
+        ) ?: return
+        SharedTextRequest.tryRequest(sharedText)
+    }
+
+    private fun configureAssistantWindow(intent: Intent?) {
+        if (
+            intent?.getBooleanExtra(
+                com.hermesandroid.relay.assistant.AssistantSessionProtocol.EXTRA_ASSISTANT_SESSION,
+                false,
+            ) == true ||
+            com.hermesandroid.relay.assistant.AssistantSessionPersistence.isActive(this)
+        ) {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1) {
+                setShowWhenLocked(true)
+                setTurnScreenOn(true)
+            } else {
+                @Suppress("DEPRECATION")
+                window.addFlags(
+                    WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+                        WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+                )
+            }
+        }
+    }
+
+    private fun clearAssistantWindow() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1) {
+            setShowWhenLocked(false)
+            setTurnScreenOn(false)
+        } else {
+            @Suppress("DEPRECATION")
+            window.clearFlags(
+                WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+                    WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+            )
+        }
+    }
+
    override fun onResume() {
        super.onResume()
        // Returning to the app clears the one-slot "Hermes finished
@@ -0,0 +1,426 @@
+package com.hermesandroid.relay.assistant
+
+import android.app.role.RoleManager
+import android.content.BroadcastReceiver
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.provider.Settings
+import android.service.voice.VoiceInteractionService
+import androidx.core.content.edit
+import com.hermesandroid.relay.viewmodel.VoiceState
+import com.hermesandroid.relay.viewmodel.VoiceUiState
+import com.hermesandroid.relay.HermesRelayApp
+import com.hermesandroid.relay.wake.WakeWordActivation
+import com.hermesandroid.relay.wake.WakeWordActivationCoordinator
+import com.hermesandroid.relay.wake.WakeWordActivationSource
+import com.hermesandroid.relay.wake.WakeWordProfileRouting
+import java.util.UUID
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+
+enum class AssistantRoleStatus {
+    Unavailable,
+    NotSelected,
+    Selected,
+}
+
+enum class AssistantSessionPhase {
+    Launching,
+    Listening,
+    Transcribing,
+    Thinking,
+    Speaking,
+    Idle,
+    Error,
+    Closed,
+}
+
+data class AssistantSessionSnapshot(
+    val phase: AssistantSessionPhase = AssistantSessionPhase.Launching,
+    val transcript: String? = null,
+    val response: String = "",
+    val error: String? = null,
+)
+
+object AssistantRole {
+    fun status(context: Context): AssistantRoleStatus {
+        val component = ComponentName(context, HermesVoiceInteractionService::class.java)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            val roles = context.getSystemService(RoleManager::class.java)
+                ?: return AssistantRoleStatus.Unavailable
+            if (!roles.isRoleAvailable(RoleManager.ROLE_ASSISTANT)) {
+                return AssistantRoleStatus.Unavailable
+            }
+            return if (roles.isRoleHeld(RoleManager.ROLE_ASSISTANT) &&
+                VoiceInteractionService.isActiveService(context, component)
+            ) {
+                AssistantRoleStatus.Selected
+            } else {
+                AssistantRoleStatus.NotSelected
+            }
+        }
+        return if (VoiceInteractionService.isActiveService(context, component)) {
+            AssistantRoleStatus.Selected
+        } else {
+            AssistantRoleStatus.NotSelected
+        }
+    }
+
+    fun selectionIntent(context: Context): Intent? {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            val roles = context.getSystemService(RoleManager::class.java)
+            if (roles?.isRoleAvailable(RoleManager.ROLE_ASSISTANT) == true) {
+                return roles.createRequestRoleIntent(RoleManager.ROLE_ASSISTANT)
+            }
+        }
+        return Intent(Settings.ACTION_VOICE_INPUT_SETTINGS)
+            .takeIf { it.resolveActivity(context.packageManager) != null }
+    }
+
+    fun managementIntent(context: Context): Intent? =
+        Intent(Settings.ACTION_VOICE_INPUT_SETTINGS)
+            .takeIf { it.resolveActivity(context.packageManager) != null }
+            ?: selectionIntent(context)
+}
+
+/**
+ * Cross-process protocol between the system-owned assistant session process
+ * and the normal app process that owns the established voice pipeline.
+ */
+object AssistantSessionProtocol {
+    const val EXTRA_ASSISTANT_SESSION = "com.hermesandroid.relay.assistant.SESSION"
+    const val EXTRA_ACTIVATION_ID = "com.hermesandroid.relay.assistant.ACTIVATION_ID"
+    const val EXTRA_START_NEW_SESSION =
+        "com.hermesandroid.relay.assistant.START_NEW_SESSION"
+    const val EXTRA_HANDOFF_ONLY = "com.hermesandroid.relay.assistant.HANDOFF_ONLY"
+    private const val ACTION_STATUS = "com.hermesandroid.relay.assistant.STATUS"
+    private const val ACTION_FINISH = "com.hermesandroid.relay.assistant.FINISH"
+    private const val ACTION_START = "com.hermesandroid.relay.assistant.START"
+    private const val ACTION_ACTIVATE = "com.hermesandroid.relay.assistant.ACTIVATE"
+    private const val EXTRA_PHASE = "phase"
+    private const val EXTRA_TRANSCRIPT = "transcript"
+    private const val EXTRA_RESPONSE = "response"
+    private const val EXTRA_ERROR = "error"
+    private const val EXTRA_CANCEL_VOICE = "cancel_voice"
+
+    fun prepareAssistActivation(intent: Intent?) {
+        val assistIntent = intent ?: return
+        if (!isAssistAction(assistIntent.action)) return
+        if (assistIntent.getBooleanExtra(EXTRA_HANDOFF_ONLY, false)) return
+        assistIntent.putExtra(EXTRA_ASSISTANT_SESSION, true)
+    }
+
+    internal fun isAssistAction(action: String?): Boolean = action == Intent.ACTION_ASSIST
+
+    fun activationIntent(
+        context: Context,
+        activationId: String = UUID.randomUUID().toString(),
+        startNewSession: Boolean = true,
+    ) =
+        Intent(context, com.hermesandroid.relay.MainActivity::class.java).apply {
+            action = Intent.ACTION_ASSIST
+            putExtra(EXTRA_ASSISTANT_SESSION, true)
+            putExtra(EXTRA_ACTIVATION_ID, activationId)
+            putExtra(EXTRA_START_NEW_SESSION, startNewSession)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        }
+
+    fun fullVoiceIntent(context: Context) =
+        Intent(context, com.hermesandroid.relay.MainActivity::class.java).apply {
+            action = Intent.ACTION_ASSIST
+            addCategory(Intent.CATEGORY_VOICE)
+            putExtra(EXTRA_HANDOFF_ONLY, true)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        }
+
+    fun activate(
+        context: Context,
+        activationId: String = UUID.randomUUID().toString(),
+        startNewSession: Boolean = true,
+    ) {
+        context.sendBroadcast(
+            Intent(context, AssistantSessionLifecycleReceiver::class.java).apply {
+                action = ACTION_ACTIVATE
+                putExtra(EXTRA_ACTIVATION_ID, activationId)
+                putExtra(EXTRA_START_NEW_SESSION, startNewSession)
+            }
+        )
+    }
+
+    fun consumeActivation(context: Context, intent: Intent?): Boolean {
+        if (intent?.getBooleanExtra(EXTRA_HANDOFF_ONLY, false) == true) {
+            intent.removeExtra(EXTRA_HANDOFF_ONLY)
+            com.hermesandroid.relay.util.NavRouteRequest.tryRequest("chat")
+            return true
+        }
+        if (intent?.getBooleanExtra(EXTRA_ASSISTANT_SESSION, false) != true) return false
+        val id = intent.getStringExtra(EXTRA_ACTIVATION_ID) ?: UUID.randomUUID().toString()
+        val startNewSession = intent.getBooleanExtra(EXTRA_START_NEW_SESSION, true)
+        AssistantSessionPersistence.setActivation(context, id, startNewSession)
+        WakeWordActivationCoordinator.request(
+            WakeWordActivation(
+                id = id,
+                startNewSession = startNewSession,
+                profileRouting = WakeWordProfileRouting(),
+                source = WakeWordActivationSource.SystemAssistant,
+            )
+        )
+        AssistantAppSessionState.setActive(true)
+        intent.removeExtra(EXTRA_ASSISTANT_SESSION)
+        intent.removeExtra(EXTRA_ACTIVATION_ID)
+        intent.removeExtra(EXTRA_START_NEW_SESSION)
+        return true
+    }
+
+    fun restoreActivation(context: Context): Boolean {
+        if (AssistantAppSessionState.active.value) return false
+        val activation = AssistantSessionPersistence.restoreActivation(context) ?: return false
+        AssistantAppSessionState.setActive(true)
+        HermesVoiceInteractionService.setVoiceSessionActive(true)
+        val application = context.applicationContext as HermesRelayApp
+        application.runtime.requestVoiceActivation(
+            activationId = activation.id,
+            startNewSession = activation.startNewSession,
+            onFailure = { failure ->
+                publish(
+                    application,
+                    AssistantSessionSnapshot(
+                        phase = AssistantSessionPhase.Error,
+                        error = failure.message ?: "Hermes voice could not start",
+                    ),
+                )
+            },
+        )
+        return true
+    }
+
+    fun publish(context: Context, snapshot: AssistantSessionSnapshot) {
+        context.sendBroadcast(
+            Intent(context, AssistantSessionStateReceiver::class.java).apply {
+                action = ACTION_STATUS
+                putExtra(EXTRA_PHASE, snapshot.phase.name)
+                putExtra(EXTRA_TRANSCRIPT, snapshot.transcript)
+                putExtra(EXTRA_RESPONSE, snapshot.response)
+                putExtra(EXTRA_ERROR, snapshot.error)
+            }
+        )
+        if (shouldFinishLifecycleOnSnapshot(snapshot)) {
+            // The session UI runs in a separate process. Reconcile the app-owned
+            // lifecycle directly as well so a reclaimed hidden UI process cannot
+            // leave wake listening paused after full Voice closes.
+            finish(context, cancelVoice = false)
+        }
+    }
+
+    fun publish(context: Context, state: VoiceUiState) {
+        publish(context, snapshotFromVoiceState(state))
+    }
+
+    internal fun snapshotFromVoiceState(state: VoiceUiState): AssistantSessionSnapshot {
+        val phase = when {
+            !state.voiceMode -> AssistantSessionPhase.Closed
+            state.state == VoiceState.Listening -> AssistantSessionPhase.Listening
+            state.state == VoiceState.Transcribing -> AssistantSessionPhase.Transcribing
+            state.state == VoiceState.Thinking -> AssistantSessionPhase.Thinking
+            state.state == VoiceState.Speaking -> AssistantSessionPhase.Speaking
+            state.state == VoiceState.Error -> AssistantSessionPhase.Error
+            else -> AssistantSessionPhase.Idle
+        }
+        return AssistantSessionSnapshot(
+            phase = phase,
+            transcript = state.transcribedText?.take(MAX_SESSION_TEXT_CHARS),
+            response = state.responseText.take(MAX_SESSION_TEXT_CHARS),
+            error = state.error?.take(MAX_SESSION_ERROR_CHARS),
+        )
+    }
+
+    internal fun shouldFinishLifecycleOnSnapshot(snapshot: AssistantSessionSnapshot): Boolean =
+        snapshot.phase == AssistantSessionPhase.Closed
+
+    fun finish(context: Context, cancelVoice: Boolean) {
+        context.sendBroadcast(
+            Intent(context, AssistantSessionLifecycleReceiver::class.java).apply {
+                action = ACTION_FINISH
+                putExtra(EXTRA_CANCEL_VOICE, cancelVoice)
+            }
+        )
+    }
+
+    fun started(context: Context) {
+        context.sendBroadcast(
+            Intent(context, AssistantSessionLifecycleReceiver::class.java).setAction(ACTION_START)
+        )
+    }
+
+    internal fun isFinishAction(action: String?): Boolean = action == ACTION_FINISH
+    internal fun isStartAction(action: String?): Boolean = action == ACTION_START
+    internal fun isActivateAction(action: String?): Boolean = action == ACTION_ACTIVATE
+    internal fun shouldCancelVoice(intent: Intent): Boolean =
+        intent.getBooleanExtra(EXTRA_CANCEL_VOICE, false)
+
+    internal fun readSnapshot(intent: Intent): AssistantSessionSnapshot {
+        val phase = runCatching {
+            AssistantSessionPhase.valueOf(
+                intent.getStringExtra(EXTRA_PHASE) ?: AssistantSessionPhase.Launching.name
+            )
+        }.getOrDefault(AssistantSessionPhase.Error)
+        return AssistantSessionSnapshot(
+            phase = phase,
+            transcript = intent.getStringExtra(EXTRA_TRANSCRIPT),
+            response = intent.getStringExtra(EXTRA_RESPONSE).orEmpty(),
+            error = intent.getStringExtra(EXTRA_ERROR),
+        )
+    }
+
+    private const val MAX_SESSION_TEXT_CHARS = 4_000
+    private const val MAX_SESSION_ERROR_CHARS = 1_000
+}
+
+object AssistantSessionState {
+    private val _snapshot = MutableStateFlow(AssistantSessionSnapshot())
+    val snapshot: StateFlow<AssistantSessionSnapshot> = _snapshot.asStateFlow()
+
+    internal fun update(snapshot: AssistantSessionSnapshot) {
+        _snapshot.value = snapshot
+    }
+
+    internal fun reset() {
+        _snapshot.value = AssistantSessionSnapshot()
+    }
+}
+
+class AssistantSessionStateReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        AssistantSessionState.update(AssistantSessionProtocol.readSnapshot(intent))
+    }
+}
+
+class AssistantSessionLifecycleReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (AssistantSessionProtocol.isActivateAction(intent.action)) {
+            val id = intent.getStringExtra(AssistantSessionProtocol.EXTRA_ACTIVATION_ID)
+                ?: UUID.randomUUID().toString()
+            val startNewSession = intent.getBooleanExtra(
+                AssistantSessionProtocol.EXTRA_START_NEW_SESSION,
+                true,
+            )
+            AssistantSessionPersistence.setActive(context, true)
+            AssistantSessionPersistence.setActivation(context, id, startNewSession)
+            AssistantAppSessionState.setActive(true)
+            HermesVoiceInteractionService.setVoiceSessionActive(true)
+            val application = context.applicationContext as HermesRelayApp
+            // Dispatch into the process-owned scope and return from the receiver
+            // immediately. Cold readiness can take longer than a broadcast's
+            // execution budget.
+            application.runtime.requestVoiceActivation(
+                activationId = id,
+                startNewSession = startNewSession,
+                onFailure = { failure ->
+                    AssistantSessionProtocol.publish(
+                        application,
+                        AssistantSessionSnapshot(
+                            phase = AssistantSessionPhase.Error,
+                            error = failure.message ?: "Hermes voice could not start",
+                        ),
+                    )
+                },
+            )
+            return
+        }
+        if (AssistantSessionProtocol.isStartAction(intent.action)) {
+            AssistantSessionPersistence.setActive(context, true)
+            HermesVoiceInteractionService.setVoiceSessionActive(true)
+            return
+        }
+        if (!AssistantSessionProtocol.isFinishAction(intent.action)) return
+        AssistantSessionPersistence.setActive(context, false)
+        if (AssistantSessionProtocol.shouldCancelVoice(intent)) {
+            val application = context.applicationContext as HermesRelayApp
+            application.runtime.cancelVoice()
+        }
+        AssistantAppSessionState.setActive(false)
+        HermesVoiceInteractionService.setVoiceSessionActive(false)
+    }
+}
+
+object AssistantSessionPersistence {
+    private const val STORE = "assistant_session_lifecycle"
+    private const val KEY_ACTIVE_SINCE = "active_since"
+    private const val KEY_ACTIVATION_ID = "activation_id"
+    private const val KEY_START_NEW_SESSION = "start_new_session"
+    private const val STALE_AFTER_MS = 30 * 60 * 1_000L
+
+    fun setActive(context: Context, active: Boolean) {
+        context.getSharedPreferences(STORE, Context.MODE_PRIVATE).edit(commit = true) {
+            putLong(KEY_ACTIVE_SINCE, if (active) System.currentTimeMillis() else 0L)
+            if (!active) {
+                remove(KEY_ACTIVATION_ID)
+            }
+        }
+    }
+
+    fun setActivation(context: Context, id: String, startNewSession: Boolean) {
+        context.getSharedPreferences(STORE, Context.MODE_PRIVATE).edit(commit = true) {
+            putString(KEY_ACTIVATION_ID, id)
+            putBoolean(KEY_START_NEW_SESSION, startNewSession)
+        }
+    }
+
+    fun restoreActivation(context: Context): WakeWordActivation? {
+        if (!isActive(context)) return null
+        val store = context.getSharedPreferences(STORE, Context.MODE_PRIVATE)
+        val id = store.getString(KEY_ACTIVATION_ID, null) ?: return null
+        return WakeWordActivation(
+            id = id,
+            startNewSession = store.getBoolean(KEY_START_NEW_SESSION, true),
+            profileRouting = WakeWordProfileRouting(),
+            source = WakeWordActivationSource.SystemAssistant,
+        )
+    }
+
+    fun isActive(context: Context, nowMs: Long = System.currentTimeMillis()): Boolean {
+        val since = context.getSharedPreferences(STORE, Context.MODE_PRIVATE)
+            .getLong(KEY_ACTIVE_SINCE, 0L)
+        return isFresh(since, nowMs)
+    }
+
+    internal fun isFresh(sinceMs: Long, nowMs: Long): Boolean =
+        sinceMs > 0L && nowMs - sinceMs in 0..STALE_AFTER_MS
+}
+
+object AssistantAppSessionState {
+    private val _active = MutableStateFlow(false)
+    val active: StateFlow<Boolean> = _active.asStateFlow()
+    @Volatile private var voiceStarted = false
+
+    internal fun setActive(active: Boolean) {
+        if (active && !_active.value) voiceStarted = false
+        if (!active) voiceStarted = false
+        _active.value = active
+    }
+
+    fun markVoiceStarted() {
+        voiceStarted = true
+    }
+
+    fun hasVoiceStarted(): Boolean = voiceStarted
+}
+
+object AssistantVoiceCommandCoordinator {
+    private val _cancelRequest = MutableStateFlow<String?>(null)
+    val cancelRequest: StateFlow<String?> = _cancelRequest.asStateFlow()
+
+    fun requestCancel() {
+        _cancelRequest.value = UUID.randomUUID().toString()
+    }
+
+    fun consume(id: String): Boolean {
+        if (_cancelRequest.value != id) return false
+        _cancelRequest.value = null
+        return true
+    }
+}
@@ -0,0 +1,26 @@
+package com.hermesandroid.relay.assistant
+
+import android.content.Intent
+import android.speech.RecognitionService
+import android.speech.SpeechRecognizer
+
+/**
+ * Platform-required recognition component for the Hermes voice interactor.
+ *
+ * Assistant sessions deliberately use the existing Hermes transcription
+ * pipeline so wake detection, session capture, and active voice never compete
+ * for the microphone. Direct SpeechRecognizer clients are therefore rejected
+ * instead of opening a second recorder.
+ */
+class HermesRecognitionService : RecognitionService() {
+    override fun onStartListening(
+        recognizerIntent: Intent,
+        listener: Callback,
+    ) {
+        listener.error(SpeechRecognizer.ERROR_CLIENT)
+    }
+
+    override fun onStopListening(listener: Callback) = Unit
+
+    override fun onCancel(listener: Callback) = Unit
+}
@@ -0,0 +1,299 @@
+package com.hermesandroid.relay.assistant
+
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.pm.PackageManager
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import android.service.voice.VoiceInteractionService
+import android.util.Log
+import androidx.core.content.ContextCompat
+import com.hermesandroid.relay.wake.MicrophoneLease
+import com.hermesandroid.relay.wake.MicrophoneOwner
+import com.hermesandroid.relay.wake.MicrophoneOwnershipCoordinator
+import com.hermesandroid.relay.wake.SherpaWakeWordDetector
+import com.hermesandroid.relay.wake.WakeWordModelInstaller
+import com.hermesandroid.relay.wake.WakeWordPreferences
+import com.hermesandroid.relay.wake.WakeWordPreferencesRepository
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+
+enum class AssistantWakeRuntimeState {
+    Stopped,
+    Starting,
+    Listening,
+    PausedForVoice,
+    AwaitingSession,
+    Error,
+}
+
+/**
+ * Opt-in Android Digital Assistant service. Android keeps the selected service
+ * available in the background; all pre-activation audio is evaluated locally.
+ */
+class HermesVoiceInteractionService : VoiceInteractionService() {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private val stopRequested = AtomicBoolean(false)
+    private val resourceLock = Any()
+    private var preferencesJob: Job? = null
+    private var recognitionJob: Job? = null
+    private var recorder: AudioRecord? = null
+    private var detector: SherpaWakeWordDetector? = null
+    private var microphoneLease: MicrophoneLease? = null
+    @Volatile private var latestPreferences = WakeWordPreferences()
+    @Volatile private var voiceSessionActive = false
+
+    override fun onCreate() {
+        super.onCreate()
+        runningInstance = this
+    }
+
+    override fun onReady() {
+        super.onReady()
+        if (runningInstance !== this) return
+        voiceSessionActive = AssistantSessionPersistence.isActive(this)
+        preferencesJob?.cancel()
+        preferencesJob = scope.launch {
+            WakeWordPreferencesRepository(applicationContext).flow.collectLatest { prefs ->
+                latestPreferences = prefs
+                if (prefs.assistantEnabled && !voiceSessionActive) {
+                    restartRecognition(prefs)
+                } else {
+                    stopRecognition()
+                    setRuntimeState(
+                        if (voiceSessionActive) {
+                            AssistantWakeRuntimeState.PausedForVoice
+                        } else {
+                            AssistantWakeRuntimeState.Stopped
+                        }
+                    )
+                }
+            }
+        }
+    }
+
+    override fun onLaunchVoiceAssistFromKeyguard() {
+        val activationId = java.util.UUID.randomUUID().toString()
+        showAssistantSession(
+            fromKeyguard = true,
+            activationId = activationId,
+        )
+    }
+
+    override fun onShutdown() {
+        stopRecognition()
+        preferencesJob?.cancel()
+        setRuntimeState(AssistantWakeRuntimeState.Stopped)
+        super.onShutdown()
+    }
+
+    override fun onDestroy() {
+        stopRecognition()
+        preferencesJob?.cancel()
+        if (runningInstance === this) runningInstance = null
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    private suspend fun restartRecognition(preferences: WakeWordPreferences) {
+        val previous = recognitionJob
+        stopRecognition()
+        previous?.join()
+        if (!voiceSessionActive && preferences.assistantEnabled) {
+            startRecognition(preferences)
+        }
+    }
+
+    @SuppressLint("MissingPermission")
+    private fun startRecognition(preferences: WakeWordPreferences) {
+        if (voiceSessionActive || recognitionJob?.isActive == true) return
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) !=
+            PackageManager.PERMISSION_GRANTED
+        ) {
+            setRuntimeState(AssistantWakeRuntimeState.Error)
+            return
+        }
+        val files = WakeWordModelInstaller(this).installedFiles()
+        if (files == null) {
+            setRuntimeState(AssistantWakeRuntimeState.Error)
+            return
+        }
+        val lease = MicrophoneOwnershipCoordinator.tryAcquire(MicrophoneOwner.WakeWord)
+        if (lease == null) {
+            setRuntimeState(AssistantWakeRuntimeState.PausedForVoice)
+            scheduleRetry()
+            return
+        }
+        microphoneLease = lease
+        stopRequested.set(false)
+        setRuntimeState(AssistantWakeRuntimeState.Starting)
+        recognitionJob = scope.launch {
+            var detected = false
+            var unattachedDetector: SherpaWakeWordDetector? = null
+            try {
+                val createdDetector = SherpaWakeWordDetector(
+                    files,
+                    preferences.sensitivity,
+                    preferences.confirmationFrames,
+                )
+                unattachedDetector = createdDetector
+                val minBuffer = AudioRecord.getMinBufferSize(
+                    SAMPLE_RATE,
+                    AudioFormat.CHANNEL_IN_MONO,
+                    AudioFormat.ENCODING_PCM_16BIT,
+                ).coerceAtLeast(SAMPLE_RATE / 5 * 2)
+                val createdRecorder = AudioRecord.Builder()
+                    .setAudioSource(MediaRecorder.AudioSource.VOICE_RECOGNITION)
+                    .setAudioFormat(
+                        AudioFormat.Builder()
+                            .setSampleRate(SAMPLE_RATE)
+                            .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+                            .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
+                            .build()
+                    )
+                    .setBufferSizeInBytes(minBuffer * 2)
+                    .build()
+                if (createdRecorder.state != AudioRecord.STATE_INITIALIZED) {
+                    createdRecorder.release()
+                    error("Assistant wake microphone failed to initialize")
+                }
+                synchronized(resourceLock) {
+                    if (stopRequested.get()) {
+                        createdRecorder.release()
+                        return@launch
+                    }
+                    recorder = createdRecorder
+                    detector = createdDetector
+                    unattachedDetector = null
+                }
+                createdRecorder.startRecording()
+                setRuntimeState(AssistantWakeRuntimeState.Listening)
+                val samples = ShortArray(FRAME_SAMPLES)
+                while (!stopRequested.get()) {
+                    val count = createdRecorder.read(samples, 0, samples.size)
+                    if (count < 0) error("Assistant wake microphone read failed: $count")
+                    if (count > 0 && createdDetector.accept(samples, count)) {
+                        detected = true
+                        break
+                    }
+                }
+            } catch (t: Throwable) {
+                if (!stopRequested.get()) {
+                    Log.w(TAG, "Assistant wake listening failed", t)
+                    setRuntimeState(AssistantWakeRuntimeState.Error)
+                }
+            } finally {
+                runCatching { unattachedDetector?.close() }
+                releaseResources()
+                recognitionJob = null
+            }
+            if (detected && !stopRequested.get()) {
+                setRuntimeState(AssistantWakeRuntimeState.AwaitingSession)
+                val keyguard = getSystemService(android.app.KeyguardManager::class.java)
+                mainHandler.post {
+                    showAssistantSession(fromKeyguard = keyguard?.isKeyguardLocked == true)
+                }
+            }
+        }
+    }
+
+    private fun showAssistantSession(fromKeyguard: Boolean, activationId: String? = null) {
+        voiceSessionActive = true
+        stopRecognition()
+        setRuntimeState(AssistantWakeRuntimeState.AwaitingSession)
+        showSession(
+            Bundle().apply {
+                putBoolean(EXTRA_FROM_KEYGUARD, fromKeyguard)
+                activationId?.let { putString(AssistantSessionProtocol.EXTRA_ACTIVATION_ID, it) }
+                putBoolean(
+                    AssistantSessionProtocol.EXTRA_START_NEW_SESSION,
+                    latestPreferences.startNewSession,
+                )
+            },
+            0,
+        )
+    }
+
+    private fun setVoiceSessionActiveInternal(active: Boolean) {
+        voiceSessionActive = active
+        if (active) {
+            stopRecognition()
+            setRuntimeState(AssistantWakeRuntimeState.PausedForVoice)
+        } else if (latestPreferences.assistantEnabled) {
+            scheduleRetry()
+        } else {
+            setRuntimeState(AssistantWakeRuntimeState.Stopped)
+        }
+    }
+
+    private fun scheduleRetry() {
+        if (recognitionJob?.isActive == true || voiceSessionActive) return
+        recognitionJob = scope.launch {
+            delay(RETRY_DELAY_MS)
+            recognitionJob = null
+            if (!voiceSessionActive && latestPreferences.assistantEnabled) {
+                startRecognition(latestPreferences)
+            }
+        }
+    }
+
+    private fun stopRecognition() {
+        stopRequested.set(true)
+        synchronized(resourceLock) {
+            runCatching { recorder?.stop() }
+            runCatching { recorder?.release() }
+            recorder = null
+            microphoneLease?.let(MicrophoneOwnershipCoordinator::release)
+            microphoneLease = null
+        }
+        recognitionJob?.cancel()
+    }
+
+    private fun releaseResources() {
+        synchronized(resourceLock) {
+            runCatching { recorder?.stop() }
+            runCatching { recorder?.release() }
+            recorder = null
+            runCatching { detector?.close() }
+            detector = null
+            microphoneLease?.let(MicrophoneOwnershipCoordinator::release)
+            microphoneLease = null
+        }
+    }
+
+    private fun setRuntimeState(state: AssistantWakeRuntimeState) {
+        _runtimeState.value = state
+    }
+
+    companion object {
+        private const val TAG = "HermesAssistant"
+        private const val SAMPLE_RATE = 16_000
+        private const val FRAME_SAMPLES = 1_600
+        private const val RETRY_DELAY_MS = 500L
+        const val EXTRA_FROM_KEYGUARD = "from_keyguard"
+
+        private val _runtimeState = kotlinx.coroutines.flow.MutableStateFlow(
+            AssistantWakeRuntimeState.Stopped
+        )
+        val runtimeState = _runtimeState.asStateFlow()
+
+        @Volatile private var runningInstance: HermesVoiceInteractionService? = null
+
+        fun setVoiceSessionActive(active: Boolean) {
+            runningInstance?.setVoiceSessionActiveInternal(active)
+        }
+    }
+}
@@ -0,0 +1,629 @@
+package com.hermesandroid.relay.assistant
+
+import android.graphics.drawable.ColorDrawable
+import android.os.Bundle
+import android.service.voice.VoiceInteractionSession
+import android.service.voice.VoiceInteractionSessionService
+import android.view.View
+import android.view.WindowManager
+import androidx.compose.animation.animateContentSize
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+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.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.AutoAwesome
+import androidx.compose.material.icons.filled.ExpandLess
+import androidx.compose.material.icons.filled.ExpandMore
+import androidx.compose.material.icons.filled.GraphicEq
+import androidx.compose.material.icons.filled.Person
+import androidx.compose.material.icons.filled.Stop
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.StrokeCap
+import androidx.compose.ui.layout.boundsInWindow
+import androidx.compose.ui.layout.onGloballyPositioned
+import androidx.compose.ui.platform.ComposeView
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.LifecycleRegistry
+import androidx.lifecycle.ViewModelStore
+import androidx.lifecycle.ViewModelStoreOwner
+import androidx.lifecycle.setViewTreeLifecycleOwner
+import androidx.lifecycle.setViewTreeViewModelStoreOwner
+import androidx.savedstate.SavedStateRegistry
+import androidx.savedstate.SavedStateRegistryController
+import androidx.savedstate.SavedStateRegistryOwner
+import androidx.savedstate.setViewTreeSavedStateRegistryOwner
+import com.hermesandroid.relay.R
+import com.hermesandroid.relay.ui.theme.HermesRelayTheme
+import java.util.UUID
+import kotlin.math.max
+import kotlin.math.roundToInt
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+class HermesVoiceInteractionSessionService : VoiceInteractionSessionService() {
+    override fun onNewSession(args: Bundle?): VoiceInteractionSession =
+        HermesVoiceInteractionSession(this)
+}
+
+internal enum class AssistantSessionPresentation {
+    Inactive,
+    Overlay,
+    FullVoice,
+}
+
+internal fun shouldCancelVoiceWhenSessionUiEnds(
+    presentation: AssistantSessionPresentation,
+): Boolean = presentation == AssistantSessionPresentation.Overlay
+
+private class HermesVoiceInteractionSession(
+    private val service: HermesVoiceInteractionSessionService,
+) : VoiceInteractionSession(service) {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+    private val viewOwner = AssistantSessionViewOwner().also { it.start() }
+    private var presentation = AssistantSessionPresentation.Inactive
+    private val assistantSurfaceBounds = android.graphics.Rect()
+    private var surfaceExpanded by mutableStateOf(false)
+
+    init {
+        scope.launch {
+            AssistantSessionState.snapshot.collect { snapshot ->
+                if (presentation != AssistantSessionPresentation.Inactive &&
+                    snapshot.phase == AssistantSessionPhase.Closed
+                ) {
+                    finishSession(cancelVoice = false)
+                }
+            }
+        }
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        window.window?.apply {
+            setBackgroundDrawable(ColorDrawable(android.graphics.Color.TRANSPARENT))
+            clearFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND)
+            setDimAmount(0f)
+        }
+    }
+
+    override fun onCreateContentView(): View = ComposeView(service).apply {
+        setBackgroundColor(android.graphics.Color.TRANSPARENT)
+        setViewTreeLifecycleOwner(viewOwner)
+        setViewTreeViewModelStoreOwner(viewOwner)
+        setViewTreeSavedStateRegistryOwner(viewOwner)
+        setContent {
+            HermesRelayTheme {
+                AssistantSessionSurface(
+                    expanded = surfaceExpanded,
+                    onExpandedChange = { surfaceExpanded = it },
+                    onCancel = { finishSession(cancelVoice = true) },
+                    onRetry = { launchVoice(startNewSession = true) },
+                    onOpenFullVoice = {
+                        if (presentation == AssistantSessionPresentation.Overlay) {
+                            openFullVoice()
+                        }
+                    },
+                    onSurfaceBoundsChanged = { bounds ->
+                        if (assistantSurfaceBounds != bounds) {
+                            assistantSurfaceBounds.set(bounds)
+                            window.window?.decorView?.requestLayout()
+                        }
+                    },
+                )
+            }
+        }
+    }
+
+    override fun onShow(args: Bundle?, showFlags: Int) {
+        super.onShow(args, showFlags)
+        if (args?.getBoolean(HermesVoiceInteractionService.EXTRA_FROM_KEYGUARD, false) == true) {
+            window.window?.addFlags(
+                WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+                    WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+            )
+        }
+        setUiEnabled(true)
+        val startsNewLifecycle = presentation == AssistantSessionPresentation.Inactive
+        presentation = AssistantSessionPresentation.Overlay
+        if (!startsNewLifecycle) return
+
+        surfaceExpanded = false
+        AssistantSessionState.reset()
+        launchVoice(
+            activationId = args?.getString(AssistantSessionProtocol.EXTRA_ACTIVATION_ID)
+                ?: UUID.randomUUID().toString(),
+            startNewSession = args?.getBoolean(
+                AssistantSessionProtocol.EXTRA_START_NEW_SESSION,
+                true,
+            ) ?: true,
+        )
+    }
+
+    override fun onComputeInsets(outInsets: Insets) {
+        super.onComputeInsets(outInsets)
+        outInsets.touchableInsets = Insets.TOUCHABLE_INSETS_REGION
+        outInsets.touchableRegion.set(assistantSurfaceBounds)
+    }
+
+    override fun onBackPressed() {
+        if (presentation == AssistantSessionPresentation.Overlay && surfaceExpanded) {
+            surfaceExpanded = false
+            return
+        }
+        super.onBackPressed()
+    }
+
+    override fun onHide() {
+        if (shouldCancelVoiceWhenSessionUiEnds(presentation)) {
+            finishSession(cancelVoice = true)
+        }
+        super.onHide()
+    }
+
+    override fun onDestroy() {
+        if (shouldCancelVoiceWhenSessionUiEnds(presentation)) {
+            AssistantSessionProtocol.finish(service, cancelVoice = true)
+        }
+        presentation = AssistantSessionPresentation.Inactive
+        viewOwner.stop()
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    private fun launchVoice(
+        activationId: String = UUID.randomUUID().toString(),
+        startNewSession: Boolean,
+    ) {
+        runCatching {
+            AssistantSessionProtocol.activate(
+                service,
+                activationId = activationId,
+                startNewSession = startNewSession,
+            )
+        }.onFailure {
+            AssistantSessionState.update(
+                AssistantSessionSnapshot(
+                    phase = AssistantSessionPhase.Error,
+                    error = it.message ?: "Hermes could not open the voice session.",
+                )
+            )
+        }
+    }
+
+    private fun openFullVoice() {
+        runCatching {
+            startVoiceActivity(AssistantSessionProtocol.fullVoiceIntent(service))
+            presentation = AssistantSessionPresentation.FullVoice
+            setUiEnabled(false)
+        }.onFailure {
+            AssistantSessionState.update(
+                AssistantSessionSnapshot(
+                    phase = AssistantSessionPhase.Error,
+                    error = it.message ?: "Hermes could not open full voice.",
+                )
+            )
+        }
+    }
+
+    private fun finishSession(cancelVoice: Boolean) {
+        if (presentation == AssistantSessionPresentation.Inactive) return
+        presentation = AssistantSessionPresentation.Inactive
+        AssistantSessionProtocol.finish(service, cancelVoice)
+        finish()
+    }
+}
+
+private class AssistantSessionViewOwner :
+    LifecycleOwner,
+    ViewModelStoreOwner,
+    SavedStateRegistryOwner {
+
+    private val lifecycleRegistry = LifecycleRegistry(this)
+    private val store = ViewModelStore()
+    private val savedStateController = SavedStateRegistryController.create(this)
+
+    override val lifecycle: Lifecycle get() = lifecycleRegistry
+    override val viewModelStore: ViewModelStore get() = store
+    override val savedStateRegistry: SavedStateRegistry
+        get() = savedStateController.savedStateRegistry
+
+    fun start() {
+        savedStateController.performRestore(null)
+        lifecycleRegistry.currentState = Lifecycle.State.CREATED
+        lifecycleRegistry.currentState = Lifecycle.State.RESUMED
+    }
+
+    fun stop() {
+        lifecycleRegistry.currentState = Lifecycle.State.DESTROYED
+        store.clear()
+    }
+}
+
+@Composable
+private fun AssistantSessionSurface(
+    expanded: Boolean,
+    onExpandedChange: (Boolean) -> Unit,
+    onCancel: () -> Unit,
+    onRetry: () -> Unit,
+    onOpenFullVoice: () -> Unit,
+    onSurfaceBoundsChanged: (android.graphics.Rect) -> Unit,
+) {
+    val snapshot by AssistantSessionState.snapshot.collectAsState()
+    val status = assistantStatus(snapshot.phase)
+
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .padding(horizontal = 12.dp, vertical = 12.dp)
+            .navigationBarsPadding(),
+        contentAlignment = Alignment.BottomCenter,
+    ) {
+        Surface(
+            modifier = Modifier
+                .fillMaxWidth()
+                .animateContentSize()
+                .onGloballyPositioned { coordinates ->
+                    val bounds = coordinates.boundsInWindow()
+                    onSurfaceBoundsChanged(
+                        android.graphics.Rect(
+                            bounds.left.roundToInt(),
+                            bounds.top.roundToInt(),
+                            bounds.right.roundToInt(),
+                            bounds.bottom.roundToInt(),
+                        )
+                    )
+                },
+            shape = RoundedCornerShape(if (expanded) 30.dp else 28.dp),
+            color = MaterialTheme.colorScheme.surfaceContainerHigh.copy(alpha = 0.98f),
+            contentColor = MaterialTheme.colorScheme.onSurface,
+            tonalElevation = 10.dp,
+            shadowElevation = 12.dp,
+        ) {
+            if (expanded) {
+                ExpandedAssistantSurface(
+                    snapshot = snapshot,
+                    status = status,
+                    onCollapse = { onExpandedChange(false) },
+                    onCancel = onCancel,
+                    onRetry = onRetry,
+                    onOpenFullVoice = onOpenFullVoice,
+                )
+            } else {
+                CompactAssistantSurface(
+                    snapshot = snapshot,
+                    status = status,
+                    onExpand = { onExpandedChange(true) },
+                    onCancel = onCancel,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun CompactAssistantSurface(
+    snapshot: AssistantSessionSnapshot,
+    status: String,
+    onExpand: () -> Unit,
+    onCancel: () -> Unit,
+) {
+    Row(
+        modifier = Modifier.padding(horizontal = 14.dp, vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        AssistantOrb(snapshot.phase)
+        Column(modifier = Modifier.weight(1f)) {
+            Text(
+                text = status,
+                style = MaterialTheme.typography.labelLarge,
+                color = MaterialTheme.colorScheme.primary,
+                fontWeight = FontWeight.SemiBold,
+            )
+            Text(
+                text = compactAssistantText(snapshot),
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+        }
+        IconButton(
+            onClick = onExpand,
+            modifier = Modifier.size(40.dp),
+        ) {
+            Icon(
+                imageVector = Icons.Filled.ExpandLess,
+                contentDescription = stringResource(R.string.assistant_session_expand),
+            )
+        }
+        AssistantStopButton(onClick = onCancel, compact = true)
+    }
+}
+
+@Composable
+private fun ExpandedAssistantSurface(
+    snapshot: AssistantSessionSnapshot,
+    status: String,
+    onCollapse: () -> Unit,
+    onCancel: () -> Unit,
+    onRetry: () -> Unit,
+    onOpenFullVoice: () -> Unit,
+) {
+    Column(
+        modifier = Modifier.padding(horizontal = 20.dp, vertical = 12.dp),
+        verticalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        Box(
+            modifier = Modifier
+                .width(38.dp)
+                .height(4.dp)
+                .clip(CircleShape)
+                .background(MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.5f))
+                .align(Alignment.CenterHorizontally),
+        )
+        Row(
+            modifier = Modifier.fillMaxWidth(),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(10.dp),
+        ) {
+            AssistantOrb(snapshot.phase, size = 38)
+            Column(modifier = Modifier.weight(1f)) {
+                Text(
+                    text = stringResource(R.string.app_name),
+                    style = MaterialTheme.typography.titleMedium,
+                    fontWeight = FontWeight.SemiBold,
+                )
+                Text(
+                    text = status,
+                    style = MaterialTheme.typography.labelMedium,
+                    color = MaterialTheme.colorScheme.primary,
+                )
+            }
+            IconButton(onClick = onCollapse) {
+                Icon(
+                    imageVector = Icons.Filled.ExpandMore,
+                    contentDescription = stringResource(R.string.assistant_session_collapse),
+                )
+            }
+        }
+
+        AssistantWaveform(snapshot.phase)
+
+        snapshot.transcript?.takeIf { it.isNotBlank() }?.let { transcript ->
+            AssistantTextRow(
+                icon = Icons.Filled.Person,
+                text = transcript,
+                color = MaterialTheme.colorScheme.primary,
+            )
+        }
+        snapshot.response.takeIf { it.isNotBlank() }?.let { response ->
+            AssistantTextRow(
+                icon = Icons.Filled.AutoAwesome,
+                text = response,
+                color = MaterialTheme.colorScheme.onSurface,
+            )
+        }
+        snapshot.error?.let { error ->
+            Text(
+                text = error,
+                color = MaterialTheme.colorScheme.error,
+                style = MaterialTheme.typography.bodyMedium,
+            )
+        }
+        if (snapshot.phase == AssistantSessionPhase.Transcribing ||
+            snapshot.phase == AssistantSessionPhase.Thinking
+        ) {
+            LinearProgressIndicator(modifier = Modifier.fillMaxWidth())
+        }
+
+        Row(
+            modifier = Modifier.fillMaxWidth(),
+            horizontalArrangement = Arrangement.spacedBy(10.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            AssistantStopButton(onClick = onCancel, compact = false)
+            Spacer(Modifier.weight(1f))
+            if (snapshot.phase == AssistantSessionPhase.Error) {
+                TextButton(onClick = onRetry) {
+                    Text(stringResource(R.string.assistant_session_retry))
+                }
+            }
+            OutlinedButton(onClick = onOpenFullVoice) {
+                Text(stringResource(R.string.assistant_session_open_full_voice))
+            }
+        }
+    }
+}
+
+@Composable
+private fun AssistantOrb(
+    phase: AssistantSessionPhase,
+    size: Int = 52,
+) {
+    val active = phase == AssistantSessionPhase.Listening ||
+        phase == AssistantSessionPhase.Transcribing ||
+        phase == AssistantSessionPhase.Thinking ||
+        phase == AssistantSessionPhase.Speaking
+    Box(
+        modifier = Modifier
+            .size(size.dp)
+            .clip(CircleShape)
+            .background(
+                if (active) {
+                    MaterialTheme.colorScheme.primaryContainer
+                } else {
+                    MaterialTheme.colorScheme.surfaceVariant
+                }
+            ),
+        contentAlignment = Alignment.Center,
+    ) {
+        Icon(
+            imageVector = Icons.Filled.GraphicEq,
+            contentDescription = null,
+            tint = if (active) {
+                MaterialTheme.colorScheme.onPrimaryContainer
+            } else {
+                MaterialTheme.colorScheme.onSurfaceVariant
+            },
+            modifier = Modifier.size((size * 0.5f).dp),
+        )
+    }
+}
+
+@Composable
+private fun AssistantWaveform(phase: AssistantSessionPhase) {
+    val active = phase == AssistantSessionPhase.Listening ||
+        phase == AssistantSessionPhase.Speaking
+    val primary = if (active) {
+        MaterialTheme.colorScheme.primary
+    } else {
+        MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.55f)
+    }
+    Canvas(
+        modifier = Modifier
+            .fillMaxWidth()
+            .height(28.dp),
+    ) {
+        val centerY = size.height / 2f
+        val bars = 33
+        val spacing = size.width / bars
+        repeat(bars) { index ->
+            val distance = kotlin.math.abs(index - bars / 2f) / (bars / 2f)
+            val envelope = max(0.18f, 1f - distance)
+            val pattern = 0.45f + ((index * 17) % 11) / 20f
+            val halfHeight = size.height * 0.46f * envelope * pattern
+            val x = spacing * (index + 0.5f)
+            drawLine(
+                color = primary,
+                start = Offset(x, centerY - halfHeight),
+                end = Offset(x, centerY + halfHeight),
+                strokeWidth = max(2f, spacing * 0.28f),
+                cap = StrokeCap.Round,
+            )
+        }
+    }
+}
+
+@Composable
+private fun AssistantTextRow(
+    icon: androidx.compose.ui.graphics.vector.ImageVector,
+    text: String,
+    color: Color,
+) {
+    Row(
+        modifier = Modifier.fillMaxWidth(),
+        horizontalArrangement = Arrangement.spacedBy(12.dp),
+        verticalAlignment = Alignment.Top,
+    ) {
+        Icon(
+            imageVector = icon,
+            contentDescription = null,
+            tint = color,
+            modifier = Modifier.size(20.dp),
+        )
+        Text(
+            text = text,
+            style = MaterialTheme.typography.bodyLarge,
+            color = color,
+            maxLines = 4,
+            overflow = TextOverflow.Ellipsis,
+        )
+    }
+}
+
+@Composable
+private fun AssistantStopButton(
+    onClick: () -> Unit,
+    compact: Boolean,
+) {
+    if (compact) {
+        IconButton(
+            onClick = onClick,
+            modifier = Modifier
+                .size(44.dp)
+                .clip(CircleShape)
+                .background(MaterialTheme.colorScheme.errorContainer),
+        ) {
+            Icon(
+                imageVector = Icons.Filled.Stop,
+                contentDescription = stringResource(R.string.assistant_session_cancel),
+                tint = MaterialTheme.colorScheme.error,
+            )
+        }
+    } else {
+        Button(
+            onClick = onClick,
+            colors = ButtonDefaults.buttonColors(
+                containerColor = MaterialTheme.colorScheme.errorContainer,
+                contentColor = MaterialTheme.colorScheme.error,
+            ),
+        ) {
+            Icon(
+                imageVector = Icons.Filled.Stop,
+                contentDescription = null,
+                modifier = Modifier.size(18.dp),
+            )
+            Spacer(Modifier.width(8.dp))
+            Text(stringResource(R.string.assistant_session_stop))
+        }
+    }
+}
+
+@Composable
+private fun assistantStatus(phase: AssistantSessionPhase): String = when (phase) {
+    AssistantSessionPhase.Launching -> stringResource(R.string.assistant_session_launching)
+    AssistantSessionPhase.Listening -> stringResource(R.string.assistant_session_listening)
+    AssistantSessionPhase.Transcribing -> stringResource(R.string.assistant_session_transcribing)
+    AssistantSessionPhase.Thinking -> stringResource(R.string.assistant_session_thinking)
+    AssistantSessionPhase.Speaking -> stringResource(R.string.assistant_session_speaking)
+    AssistantSessionPhase.Idle -> stringResource(R.string.assistant_session_ready)
+    AssistantSessionPhase.Error -> stringResource(R.string.assistant_session_error)
+    AssistantSessionPhase.Closed -> stringResource(R.string.assistant_session_closing)
+}
+
+@Composable
+private fun compactAssistantText(snapshot: AssistantSessionSnapshot): String =
+    snapshot.transcript?.takeIf { it.isNotBlank() }
+        ?: snapshot.response.takeIf { it.isNotBlank() }
+        ?: snapshot.error?.takeIf { it.isNotBlank() }
+        ?: assistantStatus(snapshot.phase)
@@ -8,11 +8,16 @@ import android.media.MediaRecorder
 import android.media.audiofx.AcousticEchoCanceler
 import android.media.audiofx.NoiseSuppressor
 import android.util.Log
+import com.hermesandroid.relay.wake.MicrophoneLease
+import com.hermesandroid.relay.wake.MicrophoneOwner
+import com.hermesandroid.relay.wake.MicrophoneOwnershipCoordinator
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.NonCancellable
+import kotlinx.coroutines.cancelAndJoin
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -22,23 +27,26 @@ import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
 import kotlinx.coroutines.yield
 import kotlin.math.max

 /**
 * Duplex audio capture for voice barge-in (plan unit B3).
 *
- * While TTS is playing, this listener continuously pulls 32 ms / 512-sample
- * PCM frames off the microphone and feeds them to [VadEngine]. It emits two
- * SharedFlows that B4 will wire into the voice state machine:
+ * During response generation and playback, this listener continuously pulls
+ * 32 ms / 512-sample PCM frames off the microphone and feeds them to
+ * [VadEngine]. One instance owns the full active turn. It emits two
+ * SharedFlows wired into the voice state machine:
 *
 *  - [maybeSpeech] fires on the **first** positive raw-VAD frame — before the
 *    second-layer debouncer latches. B4 uses this to softly [VoicePlayer.duck]
 *    the TTS so the user's voice has acoustic headroom while we decide whether
 *    to cut off.
 *
- *  - [bargeInDetected] fires when [VadEngine] confirms speech post-hysteresis.
- *    B4 uses this to call `interruptSpeaking()` and flip state to Listening.
+ *  - [bargeInDetected] fires when [VadEngine] confirms speech post-hysteresis
+ *    and the calibrated RMS majority gate accepts it. The owner uses this to
+ *    interrupt generation/playback and flip state to Listening.
 *
 * ### Acoustic echo cancellation
 *
@@ -140,8 +148,43 @@ class BargeInListener internal constructor(
    private val frameBuffer: ShortArray = ShortArray(VadEngine.FRAME_SIZE_SAMPLES)

    @Volatile private var readerJob: Job? = null
+    @Volatile private var microphoneLease: MicrophoneLease? = null
    @Volatile private var aec: AcousticEchoCanceler? = null
    @Volatile private var noiseSuppressor: NoiseSuppressor? = null
+    private val rmsGate = RmsBargeInGate()
+    @Volatile private var playbackGraceMs: Long = RmsBargeInGate.DEFAULT_PLAYBACK_GRACE_MS
+    @Volatile private var playbackActiveProvider: (() -> Boolean)? = null
+    @Volatile private var diagnosticsEnabled: Boolean = false
+    private var wasCalibrating: Boolean = false
+
+    /** Apply the user-facing barge-in sensitivity to the quiet-room RMS gate. */
+    fun setThresholdMultiplier(multiplier: Float) {
+        rmsGate.thresholdMultiplier = multiplier
+    }
+
+    fun setDiagnosticsEnabled(enabled: Boolean) {
+        diagnosticsEnabled = enabled
+    }
+
+    /** Supplies the renderer's current playback phase for upstream-style gaps. */
+    fun setPlaybackActiveProvider(provider: () -> Boolean) {
+        playbackActiveProvider = provider
+    }
+
+    /**
+     * Freeze quiet-room calibration and begin the playback-only grace window.
+     * Idempotent so every renderer may call it at its first audible chunk.
+     */
+    fun markPlaybackStarted(
+        nowMs: Long = System.currentTimeMillis(),
+        graceMs: Long = RmsBargeInGate.DEFAULT_PLAYBACK_GRACE_MS,
+    ) {
+        playbackGraceMs = graceMs.coerceAtLeast(0L)
+        rmsGate.markPlaybackStarted(nowMs)
+        if (diagnosticsEnabled) {
+            Log.d(TAG, "voice-vad playback started; grace=${playbackGraceMs}ms")
+        }
+    }

    /**
     * Allocate the audio pipeline and begin reading frames into [vadEngine].
@@ -163,6 +206,12 @@ class BargeInListener internal constructor(
            return
        }

+        val lease = MicrophoneOwnershipCoordinator.tryAcquire(MicrophoneOwner.BargeIn)
+        if (lease == null) {
+            Log.i(TAG, "Barge-in listener inactive — microphone is owned by another voice surface")
+            return
+        }
+        microphoneLease = lease
        if (!audioSource.initialize()) {
            Log.w(
                TAG,
@@ -170,11 +219,16 @@ class BargeInListener internal constructor(
                    "(missing RECORD_AUDIO permission or mic busy) — listener inactive",
            )
            _aecAttached.value = false
+            MicrophoneOwnershipCoordinator.release(lease)
+            microphoneLease = null
            return
        }

        _aecAttached.value = false
+        rmsGate.reset()
+        wasCalibrating = true
        readerJob = scope.launch(readerDispatcher) {
+            var effectsJob: Job? = null
            try {
                try {
                    audioSource.start()
@@ -185,7 +239,10 @@ class BargeInListener internal constructor(
                    return@launch
                }
                Log.i(TAG, "Barge-in AudioRecord reader started")
-                maybeAttachEffects()
+                // Do not block generation-phase listening while waiting for an
+                // AudioTrack session that does not exist until playback. The
+                // effects attach races harmlessly beside the reader.
+                effectsJob = launch { maybeAttachEffects() }

                while (isActive) {
                    val read = try {
@@ -222,10 +279,41 @@ class BargeInListener internal constructor(
                        Log.w(TAG, "VadEngine.analyze failed; stopping reader: ${t.message}")
                        break
                    }
-                    if (result.probability > 0f) {
+                    val gated = rmsGate.observe(
+                        frame = frameBuffer,
+                        rawSpeech = result.probability > 0f,
+                        nowMs = System.currentTimeMillis(),
+                        playbackGraceMs = playbackGraceMs,
+                        confirmedSpeech = result.isSpeech,
+                        playbackActiveOverride = playbackActiveProvider?.invoke(),
+                    )
+                    if (diagnosticsEnabled) {
+                        if (wasCalibrating && !gated.calibrating) {
+                            Log.d(
+                                TAG,
+                                "voice-vad calibrated quiet floor=${gated.floor.toInt()} " +
+                                    "mult=${rmsGate.thresholdMultiplier}",
+                            )
+                        }
+                        wasCalibrating = gated.calibrating
+                        if (
+                            gated.detected || gated.playbackGrace ||
+                            gated.rms >= gated.threshold * 0.5f
+                        ) {
+                            Log.d(
+                                TAG,
+                                "voice-vad rms=${gated.rms.toInt()} floor=${gated.floor.toInt()} " +
+                                    "trigger=${gated.threshold.toInt()} raw=${result.probability > 0f} " +
+                                    "confirmed=${result.isSpeech} detected=${gated.detected} " +
+                                    "grace=${gated.playbackGrace} " +
+                                    "phase=${if (gated.playback) "playback" else "generation"}",
+                            )
+                        }
+                    }
+                    if (gated.maybeSpeech) {
                        _maybeSpeech.tryEmit(Unit)
                    }
-                    if (result.isSpeech) {
+                    if (gated.detected) {
                        _bargeInDetected.tryEmit(Unit)
                    }
                    // Give the dispatcher a chance to observe cancellation
@@ -237,11 +325,19 @@ class BargeInListener internal constructor(
                    yield()
                }
            } finally {
+                // The reader reaches this block with its Job cancelled.
+                // Teardown still has to wait for the sibling AEC poll before
+                // releasing the AudioRecord and microphone lease.
+                withContext(NonCancellable) {
+                    effectsJob?.cancelAndJoin()
+                }
                // Release effects + AudioRecord in the reverse of attach order
                // so the AudioSessionId is still valid when AEC teardown runs.
                releaseEffects()
                runCatching { audioSource.stop() }
                runCatching { audioSource.release() }
+                microphoneLease?.let(MicrophoneOwnershipCoordinator::release)
+                microphoneLease = null
                _aecAttached.value = false
            }
        }
@@ -258,8 +354,16 @@ class BargeInListener internal constructor(
        if (job?.isActive == true) {
            Log.i(TAG, "Stopping barge-in AudioRecord reader")
        }
+        // AudioRecord.read() may be blocked in native code, so stop the source
+        // before cancellation to make the reader observe shutdown promptly.
+        runCatching { audioSource.stop() }
        job?.cancel()
        readerJob = null
+        if (job == null) {
+            runCatching { audioSource.release() }
+            microphoneLease?.let(MicrophoneOwnershipCoordinator::release)
+            microphoneLease = null
+        }
        return job
    }

@@ -4,6 +4,8 @@ import android.annotation.SuppressLint
 import android.media.AudioFormat
 import android.media.AudioRecord
 import android.media.MediaRecorder
+import com.hermesandroid.relay.wake.MicrophoneOwner
+import com.hermesandroid.relay.wake.MicrophoneOwnershipCoordinator
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import java.io.ByteArrayOutputStream
@@ -40,24 +42,37 @@ class RealtimePcmRecorder(
        maxDurationMs: Long = 15_000,
        onLevel: ((Float) -> Unit)? = null,
    ): ByteArray = withContext(Dispatchers.IO) {
-        val minBuffer = AudioRecord.getMinBufferSize(
-            sampleRate,
-            AudioFormat.CHANNEL_IN_MONO,
-            AudioFormat.ENCODING_PCM_16BIT,
-        ).coerceAtLeast(sampleRate / 10 * 2)
+        val microphoneLease =
+            MicrophoneOwnershipCoordinator.tryAcquire(MicrophoneOwner.RealtimeDiagnostics)
+                ?: error("Microphone is in use by another voice feature")
+        val minBuffer = try {
+            AudioRecord.getMinBufferSize(
+                sampleRate,
+                AudioFormat.CHANNEL_IN_MONO,
+                AudioFormat.ENCODING_PCM_16BIT,
+            ).coerceAtLeast(sampleRate / 10 * 2)
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
+            throw t
+        }
        val maxBytes = ((sampleRate * maxDurationMs) / 1000L * 2L).toInt()

-        val recorder = AudioRecord.Builder()
-            .setAudioSource(MediaRecorder.AudioSource.MIC)
-            .setAudioFormat(
-                AudioFormat.Builder()
-                    .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
-                    .setSampleRate(sampleRate)
-                    .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
-                    .build()
-            )
-            .setBufferSizeInBytes(minBuffer)
-            .build()
+        val recorder = try {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(
+                    AudioFormat.Builder()
+                        .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+                        .setSampleRate(sampleRate)
+                        .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
+                        .build()
+                )
+                .setBufferSizeInBytes(minBuffer)
+                .build()
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
+            throw t
+        }

        val out = ByteArrayOutputStream(minBuffer * 4)
        val buffer = ByteArray(minBuffer)
@@ -77,32 +92,46 @@ class RealtimePcmRecorder(
            capturing = false
            try { recorder.stop() } catch (_: Exception) { }
            recorder.release()
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
        }
        out.toByteArray()
    }

    @SuppressLint("MissingPermission")
    suspend fun capture(durationMs: Long = 800): ByteArray = withContext(Dispatchers.IO) {
-        val minBuffer = AudioRecord.getMinBufferSize(
-            sampleRate,
-            AudioFormat.CHANNEL_IN_MONO,
-            AudioFormat.ENCODING_PCM_16BIT,
-        ).coerceAtLeast(sampleRate / 10 * 2)
+        val microphoneLease =
+            MicrophoneOwnershipCoordinator.tryAcquire(MicrophoneOwner.RealtimeDiagnostics)
+                ?: error("Microphone is in use by another voice feature")
+        val minBuffer = try {
+            AudioRecord.getMinBufferSize(
+                sampleRate,
+                AudioFormat.CHANNEL_IN_MONO,
+                AudioFormat.ENCODING_PCM_16BIT,
+            ).coerceAtLeast(sampleRate / 10 * 2)
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
+            throw t
+        }
        val targetBytes = ((sampleRate * durationMs) / 1000L * 2L)
            .toInt()
            .coerceAtLeast(minBuffer)

-        val recorder = AudioRecord.Builder()
-            .setAudioSource(MediaRecorder.AudioSource.MIC)
-            .setAudioFormat(
-                AudioFormat.Builder()
-                    .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
-                    .setSampleRate(sampleRate)
-                    .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
-                    .build()
-            )
-            .setBufferSizeInBytes(minBuffer)
-            .build()
+        val recorder = try {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(
+                    AudioFormat.Builder()
+                        .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+                        .setSampleRate(sampleRate)
+                        .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
+                        .build()
+                )
+                .setBufferSizeInBytes(minBuffer)
+                .build()
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
+            throw t
+        }

        val out = ByteArrayOutputStream(targetBytes)
        val buffer = ByteArray(minBuffer)
@@ -123,6 +152,7 @@ class RealtimePcmRecorder(
        } finally {
            try { recorder.stop() } catch (_: Exception) { }
            recorder.release()
+            MicrophoneOwnershipCoordinator.release(microphoneLease)
        }
        out.toByteArray()
    }
@@ -0,0 +1,216 @@
+package com.hermesandroid.relay.audio
+
+import kotlin.math.ceil
+import kotlin.math.roundToInt
+import kotlin.math.sqrt
+
+/**
+ * Turn-scoped RMS gate layered in front of the model VAD.
+ *
+ * The first quiet frames establish a room floor before playback. That floor is
+ * frozen as soon as playback begins so speaker output can never teach the gate
+ * to ignore the user. Detection uses a majority window rather than requiring
+ * perfectly consecutive frames, which tolerates short consonant/syllable dips.
+ */
+internal class RmsBargeInGate(
+    private val calibrationFrames: Int = DEFAULT_CALIBRATION_FRAMES,
+    private val decisionWindowFrames: Int = DEFAULT_DECISION_WINDOW_FRAMES,
+    private val requiredWindowRatio: Float = DEFAULT_REQUIRED_WINDOW_RATIO,
+) {
+    private val ambient = ArrayDeque<Float>(MAX_AMBIENT_FRAMES)
+    private val decisions = ArrayDeque<Boolean>(decisionWindowFrames)
+
+    private var quietFloor: Float = DEFAULT_QUIET_FLOOR_RMS
+    private var calibrated = false
+    private var playbackActive = false
+    private var playbackStartedAtMs: Long? = null
+    private var playbackStoppedAtMs: Long? = null
+
+    var thresholdMultiplier: Float = DEFAULT_THRESHOLD_MULTIPLIER
+        set(value) {
+            field = value.coerceIn(MIN_THRESHOLD_MULTIPLIER, MAX_THRESHOLD_MULTIPLIER)
+        }
+
+    fun reset() {
+        ambient.clear()
+        decisions.clear()
+        quietFloor = DEFAULT_QUIET_FLOOR_RMS
+        calibrated = false
+        playbackActive = false
+        playbackStartedAtMs = null
+        playbackStoppedAtMs = null
+    }
+
+    fun markPlaybackStarted(nowMs: Long) {
+        updatePlaybackPhase(active = true, nowMs = nowMs)
+    }
+
+    fun observe(
+        frame: ShortArray,
+        rawSpeech: Boolean,
+        nowMs: Long,
+        playbackGraceMs: Long,
+        confirmedSpeech: Boolean = rawSpeech,
+        playbackActiveOverride: Boolean? = null,
+    ): RmsGateResult {
+        val rms = rms(frame)
+        playbackActiveOverride?.let { reportedActive ->
+            // A renderer marks playback just before its first write so speaker
+            // output cannot enter calibration. Do not let a provider that has
+            // not observed the first audible frame yet undo that protection
+            // during the configured grace window.
+            val withinStartupGrace = playbackActive && playbackStartedAtMs?.let {
+                nowMs - it < playbackGraceMs
+            } == true
+            if (reportedActive || !withinStartupGrace) {
+                updatePlaybackPhase(active = reportedActive, nowMs = nowMs)
+            }
+        }
+        val playback = playbackActive
+        var justCalibrated = false
+
+        if (!playback && !calibrated) {
+            addAmbient(rms)
+            if (ambient.size >= calibrationFrames) {
+                freezeCalibration()
+                justCalibrated = true
+            }
+        }
+
+        if (!playback && (!calibrated || justCalibrated)) {
+            return RmsGateResult(
+                maybeSpeech = false,
+                detected = false,
+                rms = rms,
+                floor = quietFloor,
+                threshold = (quietFloor * thresholdMultiplier).coerceIn(
+                    MIN_GENERATION_THRESHOLD_RMS,
+                    MAX_THRESHOLD_RMS,
+                ),
+                calibrating = !calibrated,
+                playbackGrace = false,
+                playback = false,
+            )
+        }
+
+        var threshold = if (playback) {
+            (quietFloor * thresholdMultiplier).coerceIn(
+                MIN_PLAYBACK_THRESHOLD_RMS,
+                MAX_THRESHOLD_RMS,
+            )
+        } else {
+            (quietFloor * thresholdMultiplier).coerceIn(
+                MIN_GENERATION_THRESHOLD_RMS,
+                MAX_THRESHOLD_RMS,
+            )
+        }
+
+        // Match upstream ambient drift: after initial calibration, keep the
+        // 90th-percentile floor current only while the room is quiet and no
+        // playback can contaminate it.
+        if (!playback && calibrated && !justCalibrated && rms < threshold) {
+            addAmbient(rms)
+            quietFloor = robustFloor(ambient)
+            threshold = (quietFloor * thresholdMultiplier).coerceIn(
+                MIN_GENERATION_THRESHOLD_RMS,
+                MAX_THRESHOLD_RMS,
+            )
+        }
+        val inPlaybackGrace = playbackStartedAtMs?.let { nowMs - it < playbackGraceMs } == true
+        val aboveRaw = rawSpeech && rms >= threshold && !inPlaybackGrace
+        val aboveConfirmed = confirmedSpeech && rms >= threshold && !inPlaybackGrace
+
+        decisions.addLast(aboveConfirmed)
+        while (decisions.size > decisionWindowFrames) decisions.removeAt(0)
+        val required = (decisionWindowFrames * requiredWindowRatio).roundToInt().coerceAtLeast(1)
+        val detected = aboveConfirmed && decisions.count { it } >= required
+
+        return RmsGateResult(
+            maybeSpeech = aboveRaw,
+            detected = detected,
+            rms = rms,
+            floor = quietFloor,
+            threshold = threshold,
+            calibrating = !playback && !calibrated,
+            playbackGrace = inPlaybackGrace,
+            playback = playback,
+        )
+    }
+
+    private fun freezeCalibration() {
+        if (!calibrated) {
+            quietFloor = robustFloor(ambient)
+            calibrated = true
+        }
+    }
+
+    private fun updatePlaybackPhase(active: Boolean, nowMs: Long) {
+        if (active == playbackActive) return
+        if (active) {
+            freezeCalibration()
+            val gapMs = playbackStoppedAtMs?.let { nowMs - it }
+            playbackStartedAtMs = if (gapMs == null || gapMs >= PLAYBACK_GRACE_REARM_GAP_MS) {
+                nowMs
+            } else {
+                null
+            }
+            playbackActive = true
+            decisions.clear()
+        } else {
+            playbackActive = false
+            playbackStartedAtMs = null
+            playbackStoppedAtMs = nowMs
+            decisions.clear()
+        }
+    }
+
+    private fun addAmbient(rms: Float) {
+        ambient.addLast(rms)
+        while (ambient.size > MAX_AMBIENT_FRAMES) ambient.removeAt(0)
+    }
+
+    private fun robustFloor(values: Collection<Float>): Float {
+        if (values.isEmpty()) return DEFAULT_QUIET_FLOOR_RMS
+        val sorted = values.sorted()
+        val percentileIndex = (ceil(sorted.size * 0.9).toInt() - 1).coerceIn(sorted.indices)
+        return sorted[percentileIndex].coerceAtLeast(MIN_QUIET_FLOOR_RMS)
+    }
+
+    private fun rms(frame: ShortArray): Float {
+        if (frame.isEmpty()) return 0f
+        var sum = 0.0
+        frame.forEach { sample ->
+            val value = sample.toDouble()
+            sum += value * value
+        }
+        return sqrt(sum / frame.size).toFloat()
+    }
+
+    companion object {
+        const val DEFAULT_THRESHOLD_MULTIPLIER = 3f
+        const val DEFAULT_PLAYBACK_GRACE_MS = 500L
+        internal const val DEFAULT_CALIBRATION_FRAMES = 14
+        internal const val DEFAULT_DECISION_WINDOW_FRAMES = 10
+        internal const val DEFAULT_REQUIRED_WINDOW_RATIO = 0.8f
+        internal const val MIN_PLAYBACK_THRESHOLD_RMS = 1_500f
+        internal const val MAX_THRESHOLD_RMS = 4_000f
+        internal const val MIN_GENERATION_THRESHOLD_RMS = 400f
+        internal const val DEFAULT_QUIET_FLOOR_RMS = 200f
+        internal const val MIN_QUIET_FLOOR_RMS = 200f
+        internal const val MAX_AMBIENT_FRAMES = 100
+        internal const val PLAYBACK_GRACE_REARM_GAP_MS = 1_000L
+        internal const val MIN_THRESHOLD_MULTIPLIER = 1f
+        internal const val MAX_THRESHOLD_MULTIPLIER = 8f
+    }
+}
+
+internal data class RmsGateResult(
+    val maybeSpeech: Boolean,
+    val detected: Boolean,
+    val rms: Float,
+    val floor: Float,
+    val threshold: Float,
+    val calibrating: Boolean,
+    val playbackGrace: Boolean,
+    val playback: Boolean,
+)
@@ -8,6 +8,9 @@ import android.media.MediaRecorder
 import android.media.audiofx.AcousticEchoCanceler
 import android.media.audiofx.NoiseSuppressor
 import android.util.Log
+import com.hermesandroid.relay.wake.MicrophoneLease
+import com.hermesandroid.relay.wake.MicrophoneOwner
+import com.hermesandroid.relay.wake.MicrophoneOwnershipCoordinator
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -57,6 +60,7 @@ class VoiceRecorder(
    private val bufferLock = Any()
    private val stopRequested = AtomicBoolean(false)
    private var audioRecord: AudioRecord? = null
+    private var microphoneLease: MicrophoneLease? = null
    private var echoCanceler: AcousticEchoCanceler? = null
    private var noiseSuppressor: NoiseSuppressor? = null
    private var currentOutputFile: File? = null
@@ -79,12 +83,21 @@ class VoiceRecorder(
                releaseRecorder()
            }
        }
+        val lease = MicrophoneOwnershipCoordinator.tryAcquire(MicrophoneOwner.VoiceCapture)
+            ?: throw IllegalStateException("Microphone is in use by another voice feature")
+        microphoneLease = lease

-        val minBuffer = AudioRecord.getMinBufferSize(
+        val minBuffer = try {
+            AudioRecord.getMinBufferSize(
            SAMPLE_RATE,
            AudioFormat.CHANNEL_IN_MONO,
            AudioFormat.ENCODING_PCM_16BIT,
-        ).coerceAtLeast(SAMPLE_RATE / 10 * BYTES_PER_SAMPLE)
+            ).coerceAtLeast(SAMPLE_RATE / 10 * BYTES_PER_SAMPLE)
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(lease)
+            microphoneLease = null
+            throw t
+        }

        val outFile = File(context.cacheDir, "voice_rec_${System.currentTimeMillis()}.wav")
        currentOutputFile = outFile
@@ -95,21 +108,29 @@ class VoiceRecorder(
        stopRequested.set(false)
        _amplitude.value = 0f

-        val recorder = AudioRecord.Builder()
-            .setAudioSource(MediaRecorder.AudioSource.MIC)
-            .setAudioFormat(
-                AudioFormat.Builder()
-                    .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
-                    .setSampleRate(SAMPLE_RATE)
-                    .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
-                    .build()
-            )
-            .setBufferSizeInBytes(minBuffer * 2)
-            .build()
+        val recorder = try {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(
+                    AudioFormat.Builder()
+                        .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+                        .setSampleRate(SAMPLE_RATE)
+                        .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
+                        .build()
+                )
+                .setBufferSizeInBytes(minBuffer * 2)
+                .build()
+        } catch (t: Throwable) {
+            MicrophoneOwnershipCoordinator.release(lease)
+            microphoneLease = null
+            throw t
+        }

        if (recorder.state != AudioRecord.STATE_INITIALIZED) {
            recorder.release()
            currentOutputFile = null
+            MicrophoneOwnershipCoordinator.release(lease)
+            microphoneLease = null
            throw IllegalStateException("AudioRecord failed to initialize")
        }

@@ -118,6 +139,8 @@ class VoiceRecorder(
        } catch (e: Exception) {
            recorder.release()
            currentOutputFile = null
+            MicrophoneOwnershipCoordinator.release(lease)
+            microphoneLease = null
            throw e
        }

@@ -281,6 +304,8 @@ class VoiceRecorder(
            try { record.release() } catch (_: Exception) { }
        }
        audioRecord = null
+        microphoneLease?.let(MicrophoneOwnershipCoordinator::release)
+        microphoneLease = null
        readThread = null
        readDone = null
    }
@@ -1,6 +1,7 @@
 package com.hermesandroid.relay.auth

 import android.content.Context
+import android.provider.Settings
 import android.util.Log
 import com.hermesandroid.relay.data.Connection
 import com.hermesandroid.relay.data.EndpointCandidate
@@ -19,6 +20,8 @@ import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonObject
@@ -48,6 +51,7 @@ data class ConnectionAuthSecrets(
    val refreshToken: String? = null,
    val deviceId: String? = null,
    val apiKey: String? = null,
+    val profileApiKeys: Map<String, String> = emptyMap(),
    val pairedSessionMetaJson: String? = null,
 )

@@ -114,6 +118,7 @@ class AuthManager(
        private const val KEY_REFRESH_TOKEN = "refresh_token"
        private const val KEY_DEVICE_ID = "device_id"
        private const val KEY_API_KEY = "api_server_key"
+        private const val KEY_PROFILE_API_KEYS = "profile_api_server_keys"
        private const val HINT_API_KEY_PRESENT = "api_key_present"
        private const val KEY_PAIRED_META = "paired_session_meta_json"
        // Marker (in the connection-0 token store) recording that the one-shot
@@ -132,6 +137,29 @@ class AuthManager(
         */
        const val CONNECTION_ID_LEGACY: String = "legacy"

+        internal fun encodeProfileApiKeys(keys: Map<String, String>): String =
+            Json.encodeToString(
+                keys.mapNotNull { (profile, key) ->
+                    val normalizedProfile = profile.trim()
+                    val normalizedKey = key.trim()
+                    if (normalizedProfile.isBlank() || normalizedKey.isBlank()) null
+                    else normalizedProfile to normalizedKey
+                }.toMap(),
+            )
+
+        internal fun decodeProfileApiKeys(raw: String?): Map<String, String> {
+            if (raw.isNullOrBlank()) return emptyMap()
+            return runCatching { Json.decodeFromString<Map<String, String>>(raw) }
+                .getOrDefault(emptyMap())
+                .mapNotNull { (profile, key) ->
+                    val normalizedProfile = profile.trim()
+                    val normalizedKey = key.trim()
+                    if (normalizedProfile.isBlank() || normalizedKey.isBlank()) null
+                    else normalizedProfile to normalizedKey
+                }
+                .toMap()
+        }
+
        internal fun shouldPreservePairedSessionOnAuthFail(
            currentState: AuthState,
            rawReason: String,
@@ -173,6 +201,7 @@ class AuthManager(
                refreshToken = store.getString(KEY_REFRESH_TOKEN),
                deviceId = store.getString(KEY_DEVICE_ID),
                apiKey = store.getString(KEY_API_KEY),
+                profileApiKeys = decodeProfileApiKeys(store.getString(KEY_PROFILE_API_KEYS)),
                pairedSessionMetaJson = store.getString(KEY_PAIRED_META),
            )
        }
@@ -188,6 +217,11 @@ class AuthManager(
                writeOrRemove(store, KEY_REFRESH_TOKEN, secrets.refreshToken)
                writeOrRemove(store, KEY_DEVICE_ID, secrets.deviceId)
                writeOrRemove(store, KEY_API_KEY, secrets.apiKey)
+                writeOrRemove(
+                    store,
+                    KEY_PROFILE_API_KEYS,
+                    secrets.profileApiKeys.takeIf { it.isNotEmpty() }?.let(::encodeProfileApiKeys),
+                )
                writeOrRemove(store, KEY_PAIRED_META, secrets.pairedSessionMetaJson)
            }
        }
@@ -290,6 +324,7 @@ class AuthManager(

    private var _store: SessionTokenStore? = null
    private val storeMutex = Mutex()
+    private val profileApiKeysMutex = Mutex()

    /**
     * The encrypted-store filename for this connection — shared by [store]
@@ -416,6 +451,7 @@ class AuthManager(
            KEY_REFRESH_TOKEN,
            KEY_DEVICE_ID,
            KEY_API_KEY,
+            KEY_PROFILE_API_KEYS,
            KEY_PAIRED_META,
        )
        var migrated = false
@@ -596,7 +632,7 @@ class AuthManager(
        val now = System.currentTimeMillis() / 1000L
        val defaults = PairedSession(
            token = token,
-            deviceName = android.os.Build.MODEL,
+            deviceName = relayDeviceName(),
            expiresAt = null,
            grants = emptyMap(),
            transportHint = null,
@@ -616,7 +652,7 @@ class AuthManager(
            val transportHint = obj["transport_hint"]?.jsonPrimitive?.contentOrNull
            val firstSeen = obj["first_seen"]?.jsonPrimitive?.longOrNull ?: now
            val deviceName = obj["device_name"]?.jsonPrimitive?.contentOrNull
-                ?: android.os.Build.MODEL
+                ?: relayDeviceName()

            PairedSession(
                token = token,
@@ -715,6 +751,26 @@ class AuthManager(
        })
    }

+    private fun JsonObjectBuilder.putRelayDeviceIdentity() {
+        val model = android.os.Build.MODEL.orEmpty().ifBlank { "Android device" }
+        val deviceName = relayDeviceName()
+        put("device_name", deviceName)
+        put("device_hostname", deviceName)
+        put("device_model", model)
+        put("device_platform", "Android ${android.os.Build.VERSION.RELEASE}")
+        put("client_surface", "android")
+        put("device_form_factor", "phone")
+    }
+
+    private fun relayDeviceName(): String {
+        val configured = runCatching {
+            Settings.Global.getString(context.contentResolver, "device_name")
+        }.getOrNull()?.trim().orEmpty()
+        return configured.ifBlank {
+            android.os.Build.MODEL.orEmpty().ifBlank { "Android device" }
+        }
+    }
+
    /**
     * Send auth envelope when connection is established.
     *
@@ -749,7 +805,7 @@ class AuthManager(
                            put("refresh_token", refreshToken)
                        }
                        put("device_id", deviceId)
-                        put("device_name", android.os.Build.MODEL)
+                        putRelayDeviceIdentity()
                        putRelayClientSupports()
                    }
                }
@@ -765,7 +821,7 @@ class AuthManager(
                    buildJsonObject {
                        put("pairing_code", codeToSend)
                        put("device_id", deviceId)
-                        put("device_name", android.os.Build.MODEL)
+                        putRelayDeviceIdentity()
                        putRelayClientSupports()
                        pendingTtlSeconds?.let { put("ttl_seconds", it) }
                        pendingGrants?.let { grants ->
@@ -947,6 +1003,27 @@ class AuthManager(
        recordApiKeyHint(false)
    }

+    suspend fun getProfileApiKey(profileName: String): String? =
+        decodeProfileApiKeys(store().getString(KEY_PROFILE_API_KEYS))[profileName.trim()]
+
+    suspend fun setProfileApiKey(profileName: String, key: String) {
+        val normalizedProfile = profileName.trim()
+        require(normalizedProfile.isNotBlank()) { "Profile name must not be blank" }
+        profileApiKeysMutex.withLock {
+            val tokenStore = store()
+            val keys = decodeProfileApiKeys(tokenStore.getString(KEY_PROFILE_API_KEYS)).toMutableMap()
+            val normalizedKey = key.trim()
+            if (normalizedKey.isBlank()) keys.remove(normalizedProfile)
+            else keys[normalizedProfile] = normalizedKey
+            if (keys.isEmpty()) tokenStore.remove(KEY_PROFILE_API_KEYS)
+            else tokenStore.putString(KEY_PROFILE_API_KEYS, encodeProfileApiKeys(keys))
+        }
+    }
+
+    suspend fun clearProfileApiKey(profileName: String) {
+        setProfileApiKey(profileName, "")
+    }
+
    val isPaired: Boolean
        get() = _authState.value is AuthState.Paired

@@ -1010,7 +1087,7 @@ class AuthManager(

                    val paired = PairedSession(
                        token = token,
-                        deviceName = android.os.Build.MODEL,
+                        deviceName = relayDeviceName(),
                        expiresAt = expiresAt,
                        grants = grantsMap,
                        transportHint = transportHint,
@@ -74,6 +74,14 @@ data class PairedDeviceInfo(
    val deviceName: String = "",
    @SerialName("device_id")
    val deviceId: String = "",
+    @SerialName("device_model")
+    val deviceModel: String = "",
+    @SerialName("device_platform")
+    val devicePlatform: String = "",
+    @SerialName("client_surface")
+    val clientSurface: String = "",
+    @SerialName("device_form_factor")
+    val deviceFormFactor: String = "",
    @SerialName("created_at")
    val createdAt: Double? = null,
    @SerialName("last_seen")
@@ -3,10 +3,10 @@ package com.hermesandroid.relay.data
 /**
 * Shared profile/personality display and request identity helpers.
 *
- * A null profile name is the app's explicit "Server default" state. The
- * relay also advertises the root Hermes config as a synthetic profile named
- * "default"; for request/session identity that row is an alias of server
- * default so it does not split chat, voice, or session scope.
+ * A null profile name is the app's explicit "Server default" state. It is
+ * intentionally distinct from a real profile whose name is literally
+ * `default`: the former follows the server's sticky default, while the latter
+ * explicitly addresses the root profile.
 */
 object AgentDisplay {
    const val SERVER_DEFAULT_PROFILE_KEY: String = "__server_default__"
@@ -16,17 +16,16 @@ object AgentDisplay {
        "hermes agent",
    )

-    // Only an EXPLICIT pick drives request/session identity. The advertised
-    // "default" profile is an alias for server default, so falling back to it
-    // here would split chat, voice, or session scope.
+    // Only an explicit pick drives request identity. Server default is the null
+    // selection; a named `default` profile is an ordinary explicit pick.
    @Suppress("UNUSED_PARAMETER")
    fun effectiveProfile(
        selectedProfile: Profile?,
        profiles: List<Profile>,
    ): Profile? = selectedProfile

-    // Display can use the synthetic default profile's metadata without making
-    // it a request/session override. Verbose SOUL summaries are filtered by
+    // Display can use the root default profile's metadata without making it a
+    // request/session override. Verbose SOUL summaries are filtered by
    // profileDisplayName below, so this is safe for headers/cards.
    fun effectiveDisplayProfile(
        selectedProfile: Profile?,
@@ -39,7 +38,7 @@ object AgentDisplay {
            ?.let { activeName ->
                profiles.firstOrNull { it.name.equals(activeName, ignoreCase = true) }
            }
-            ?: profiles.firstOrNull { isServerDefaultAlias(it.name) }
+            ?: profiles.firstOrNull { it.name.equals("default", ignoreCase = true) }
    }

    // The NAME goes in the name slot. Non-default profiles use their profile
@@ -48,7 +47,7 @@ object AgentDisplay {
    // verbose SOUL summary.
    fun profileDisplayName(profile: Profile?): String? {
        if (profile == null) return null
-        if (isServerDefaultAlias(profile.name)) {
+        if (profile.name.equals("default", ignoreCase = true)) {
            return defaultProfileDisplayName(profile)
        }
        return when {
@@ -135,22 +134,18 @@ object AgentDisplay {
            ?.takeIf { it.isNotEmpty() }
            ?.takeUnless { it.lowercase() in GENERIC_MODEL_ALIASES }

-    fun isServerDefaultAlias(profileName: String?): Boolean =
-        profileName?.trim()?.equals("default", ignoreCase = true) == true
-
-    fun normalizeSelection(profile: Profile?): Profile? =
-        if (isServerDefaultAlias(profile?.name)) null else profile
+    fun normalizeSelection(profile: Profile?): Profile? = profile

    fun profileRequestName(profileName: String?): String? =
        profileName
            ?.trim()
-            ?.takeIf { it.isNotEmpty() && !isServerDefaultAlias(it) }
+            ?.takeIf { it.isNotEmpty() && it != SERVER_DEFAULT_PROFILE_KEY }

    /**
     * The profile name that owns chat sessions for the current UI selection.
     *
-     * [selectedProfileName] is null (or the synthetic `default` alias) for the
-     * "Server default" row. That UI sentinel must remain distinct from the
+     * [selectedProfileName] is null for the "Server default" row. That UI
+     * sentinel must remain distinct from the
     * server's sticky active profile: a dashboard launched under the root home
     * may still report `active=victor`, in which case upstream Gateway and
     * dashboard session calls must explicitly target `victor`. The resolved
@@ -12,6 +12,7 @@ enum class AppLanguage(val languageTag: String) {
    JAPANESE("ja"),
    SIMPLIFIED_CHINESE("zh-Hans"),
    SPANISH("es"),
+    RUSSIAN("ru"),
    ;

    fun toLocaleList(): LocaleListCompat = if (languageTag.isEmpty()) {
@@ -35,6 +36,7 @@ enum class AppLanguage(val languageTag: String) {
                "es" -> SPANISH
                "ja" -> JAPANESE
                "pt" -> BRAZILIAN_PORTUGUESE
+                "ru" -> RUSSIAN
                "zh" -> {
                    val simplified = locale.script.equals("Hans", ignoreCase = true) ||
                        locale.script.isEmpty() ||
@@ -5,6 +5,8 @@ import androidx.datastore.core.DataStore
 import androidx.datastore.preferences.core.Preferences
 import androidx.datastore.preferences.core.booleanPreferencesKey
 import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.floatPreferencesKey
+import androidx.datastore.preferences.core.longPreferencesKey
 import androidx.datastore.preferences.core.stringPreferencesKey
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.distinctUntilChanged
@@ -15,15 +17,14 @@ import kotlinx.coroutines.flow.map
 *
 * Phase V follow-on — owned by the voice-barge-in plan (Wave 1 / unit B1).
 *
- * Barge-in lets the user interrupt TTS playback by speaking. The three knobs
+ * Barge-in lets the user interrupt generation or TTS playback by speaking.
 * here back the Voice Settings "Interruption" section added by B5 and are
 * consumed by [com.hermesandroid.relay.viewmodel.VoiceViewModel] (wired in
 * B4):
 *
 *  - [enabled] — master toggle for the whole barge-in path. When false, the
- *    listener never starts and TTS plays uninterrupted. Default off at launch
- *    on both flavors so existing users aren't surprised by mic activation
- *    during a speaking turn.
+ *    listener never starts and TTS plays uninterrupted. Default on matches
+ *    upstream Hermes full-duplex voice; users can opt out here.
 *
 *  - [sensitivity] — maps to Silero VAD threshold + hysteresis tuning inside
 *    [com.hermesandroid.relay.audio.VadEngine]. [BargeInSensitivity.Off] is
@@ -36,6 +37,12 @@ import kotlinx.coroutines.flow.map
 *    barge-in behaves like a hard cancel, which is more abrupt than most
 *    conversational UX expects.
 *
+ *  - [thresholdMultiplier] / [playbackGraceMs] — upstream-compatible RMS
+ *    tuning. Defaults are 3x over the calibrated quiet floor and 500 ms.
+ *
+ *  - [debugDiagnostics] — opt-in per-block VAD decision logging for logcat,
+ *    equivalent to upstream's HERMES_VOICE_DEBUG switch.
+ *
 * Matches the [BridgePreferences] / [VoicePreferences] / [MediaSettings] style:
 * single shared DataStore (`relayDataStore`), one key per scalar field, enum
 * stored as its `name` (cheap + schema-evolvable via fall-back to default on
@@ -45,6 +52,9 @@ data class BargeInPreferences(
    val enabled: Boolean = DEFAULT_ENABLED,
    val sensitivity: BargeInSensitivity = DEFAULT_SENSITIVITY,
    val resumeAfterInterruption: Boolean = DEFAULT_RESUME_AFTER_INTERRUPTION,
+    val thresholdMultiplier: Float = DEFAULT_THRESHOLD_MULTIPLIER,
+    val playbackGraceMs: Long = DEFAULT_PLAYBACK_GRACE_MS,
+    val debugDiagnostics: Boolean = DEFAULT_DEBUG_DIAGNOSTICS,
 )

 /**
@@ -62,9 +72,12 @@ enum class BargeInSensitivity {
    High,
 }

-const val DEFAULT_ENABLED: Boolean = false
+const val DEFAULT_ENABLED: Boolean = true
 val DEFAULT_SENSITIVITY: BargeInSensitivity = BargeInSensitivity.Default
 const val DEFAULT_RESUME_AFTER_INTERRUPTION: Boolean = true
+const val DEFAULT_THRESHOLD_MULTIPLIER: Float = 3f
+const val DEFAULT_PLAYBACK_GRACE_MS: Long = 500L
+const val DEFAULT_DEBUG_DIAGNOSTICS: Boolean = false

 /**
 * DataStore-backed repository for [BargeInPreferences].
@@ -86,6 +99,10 @@ class BargeInPreferencesRepository(
        internal val KEY_SENSITIVITY = stringPreferencesKey("barge_in_sensitivity")
        internal val KEY_RESUME_AFTER_INTERRUPTION =
            booleanPreferencesKey("barge_in_resume_after_interruption")
+        internal val KEY_THRESHOLD_MULTIPLIER =
+            floatPreferencesKey("barge_in_threshold_multiplier")
+        internal val KEY_PLAYBACK_GRACE_MS = longPreferencesKey("barge_in_playback_grace_ms")
+        internal val KEY_DEBUG_DIAGNOSTICS = booleanPreferencesKey("barge_in_debug_diagnostics")
    }

    val flow: Flow<BargeInPreferences> = dataStore.data
@@ -96,6 +113,14 @@ class BargeInPreferencesRepository(
                    ?: DEFAULT_SENSITIVITY,
                resumeAfterInterruption = prefs[KEY_RESUME_AFTER_INTERRUPTION]
                    ?: DEFAULT_RESUME_AFTER_INTERRUPTION,
+                thresholdMultiplier = prefs[KEY_THRESHOLD_MULTIPLIER]
+                    ?.coerceIn(MIN_THRESHOLD_MULTIPLIER, MAX_THRESHOLD_MULTIPLIER)
+                    ?: DEFAULT_THRESHOLD_MULTIPLIER,
+                playbackGraceMs = prefs[KEY_PLAYBACK_GRACE_MS]
+                    ?.coerceIn(MIN_PLAYBACK_GRACE_MS, MAX_PLAYBACK_GRACE_MS)
+                    ?: DEFAULT_PLAYBACK_GRACE_MS,
+                debugDiagnostics = prefs[KEY_DEBUG_DIAGNOSTICS]
+                    ?: DEFAULT_DEBUG_DIAGNOSTICS,
            )
        }
        .distinctUntilChanged()
@@ -112,6 +137,33 @@ class BargeInPreferencesRepository(
        dataStore.edit { it[KEY_RESUME_AFTER_INTERRUPTION] = value }
    }

+    suspend fun setThresholdMultiplier(value: Float) {
+        dataStore.edit {
+            it[KEY_THRESHOLD_MULTIPLIER] = value.coerceIn(
+                MIN_THRESHOLD_MULTIPLIER,
+                MAX_THRESHOLD_MULTIPLIER,
+            )
+        }
+    }
+
+    suspend fun setPlaybackGraceMs(value: Long) {
+        dataStore.edit {
+            it[KEY_PLAYBACK_GRACE_MS] = value.coerceIn(
+                MIN_PLAYBACK_GRACE_MS,
+                MAX_PLAYBACK_GRACE_MS,
+            )
+        }
+    }
+
+    suspend fun setDebugDiagnostics(value: Boolean) {
+        dataStore.edit { it[KEY_DEBUG_DIAGNOSTICS] = value }
+    }
+
    private fun decodeSensitivity(raw: String): BargeInSensitivity =
        runCatching { BargeInSensitivity.valueOf(raw) }.getOrDefault(DEFAULT_SENSITIVITY)
 }
+
+private const val MIN_THRESHOLD_MULTIPLIER = 1f
+private const val MAX_THRESHOLD_MULTIPLIER = 8f
+private const val MIN_PLAYBACK_GRACE_MS = 0L
+private const val MAX_PLAYBACK_GRACE_MS = 3_000L
@@ -0,0 +1,147 @@
+package com.hermesandroid.relay.data
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+
+/**
+ * Immutable owner of one composer draft.
+ *
+ * Callers must supply stable ids rather than display labels. [sessionId] may be
+ * a server id or a stable client-generated id for a not-yet-created session.
+ * [draftId] separates the primary composer from any future named draft slot.
+ */
+data class ChatComposerDraftKey(
+    val connectionId: String,
+    val profileId: String,
+    val sessionId: String,
+    val draftId: String = PRIMARY_DRAFT_ID,
+) {
+    init {
+        require(connectionId.isNotBlank()) { "connectionId must not be blank" }
+        require(profileId.isNotBlank()) { "profileId must not be blank" }
+        require(sessionId.isNotBlank()) { "sessionId must not be blank" }
+        require(draftId.isNotBlank()) { "draftId must not be blank" }
+    }
+
+    companion object {
+        const val PRIMARY_DRAFT_ID = "primary"
+        const val DEFAULT_PROFILE_ID = "default"
+    }
+}
+
+/** Message references associated with composer content. */
+data class ChatComposerDraftContext(
+    val quotedMessageId: String? = null,
+    val editingMessageId: String? = null,
+) {
+    internal fun normalized(): ChatComposerDraftContext = copy(
+        quotedMessageId = quotedMessageId?.takeIf(String::isNotBlank),
+        editingMessageId = editingMessageId?.takeIf(String::isNotBlank),
+    )
+}
+
+/**
+ * Complete restorable state for one composer.
+ *
+ * Selection offsets use the same start-inclusive/end-exclusive convention as
+ * Compose text fields. The store clamps them whenever the text changes so a
+ * restored selection can never address outside the restored string.
+ */
+data class ChatComposerDraft(
+    val text: String = "",
+    val selectionStart: Int = text.length,
+    val selectionEnd: Int = selectionStart,
+    val context: ChatComposerDraftContext = ChatComposerDraftContext(),
+    val attachments: List<Attachment> = emptyList(),
+) {
+    val isEmpty: Boolean
+        get() = text.isEmpty() &&
+            context.quotedMessageId == null &&
+            context.editingMessageId == null &&
+            attachments.isEmpty()
+
+    internal fun normalized(): ChatComposerDraft {
+        val normalizedStart = selectionStart.coerceIn(0, text.length)
+        val normalizedEnd = selectionEnd.coerceIn(0, text.length)
+        return copy(
+            selectionStart = minOf(normalizedStart, normalizedEnd),
+            selectionEnd = maxOf(normalizedStart, normalizedEnd),
+            context = context.normalized(),
+            attachments = attachments.toList(),
+        )
+    }
+}
+
+/**
+ * Session-owned composer state.
+ *
+ * This store is deliberately memory-only: outbound [Attachment.content] can
+ * contain large Base64 payloads and must not enter Preferences DataStore. Keep
+ * one instance in the chat owner (normally its ViewModel) so drafts survive
+ * navigation and Activity recreation. Process death starts with empty drafts;
+ * a future durable implementation should persist URI grants, not attachment
+ * bytes.
+ */
+interface ChatComposerDraftStore {
+    fun observe(key: ChatComposerDraftKey): Flow<ChatComposerDraft>
+    fun snapshot(key: ChatComposerDraftKey): ChatComposerDraft
+    fun save(key: ChatComposerDraftKey, draft: ChatComposerDraft)
+    fun update(
+        key: ChatComposerDraftKey,
+        transform: (ChatComposerDraft) -> ChatComposerDraft,
+    )
+    fun remove(key: ChatComposerDraftKey)
+    fun removeSession(connectionId: String, profileId: String, sessionId: String)
+    fun clear()
+}
+
+class InMemoryChatComposerDraftStore : ChatComposerDraftStore {
+    private val drafts = MutableStateFlow<Map<ChatComposerDraftKey, ChatComposerDraft>>(emptyMap())
+
+    override fun observe(key: ChatComposerDraftKey): Flow<ChatComposerDraft> =
+        drafts
+            .map { it[key] ?: ChatComposerDraft() }
+            .distinctUntilChanged()
+
+    override fun snapshot(key: ChatComposerDraftKey): ChatComposerDraft =
+        drafts.value[key] ?: ChatComposerDraft()
+
+    @Synchronized
+    override fun save(key: ChatComposerDraftKey, draft: ChatComposerDraft) {
+        val normalized = draft.normalized()
+        drafts.value = if (normalized.isEmpty) {
+            drafts.value - key
+        } else {
+            drafts.value + (key to normalized)
+        }
+    }
+
+    @Synchronized
+    override fun update(
+        key: ChatComposerDraftKey,
+        transform: (ChatComposerDraft) -> ChatComposerDraft,
+    ) {
+        save(key, transform(snapshot(key)))
+    }
+
+    @Synchronized
+    override fun remove(key: ChatComposerDraftKey) {
+        drafts.value = drafts.value - key
+    }
+
+    @Synchronized
+    override fun removeSession(connectionId: String, profileId: String, sessionId: String) {
+        drafts.value = drafts.value.filterKeys { key ->
+            key.connectionId != connectionId ||
+                key.profileId != profileId ||
+                key.sessionId != sessionId
+        }
+    }
+
+    @Synchronized
+    override fun clear() {
+        drafts.value = emptyMap()
+    }
+}
@@ -0,0 +1,48 @@
+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 kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+
+/** Phone-local behavior for a physical keyboard's unmodified Enter key. */
+enum class PhysicalKeyboardEnterBehavior(val storedValue: String) {
+    SendMessage("send_message"),
+    InsertNewline("insert_newline"),
+    ;
+
+    companion object {
+        fun fromStoredValue(value: String?): PhysicalKeyboardEnterBehavior =
+            entries.firstOrNull { it.storedValue == value } ?: SendMessage
+    }
+}
+
+/** Device-level chat input preferences shared by every Hermes profile. */
+class ChatInputPreferencesRepository(
+    private val dataStore: DataStore<Preferences>,
+) {
+    constructor(context: Context) : this(context.relayDataStore)
+
+    companion object {
+        internal val KEY_PHYSICAL_KEYBOARD_ENTER =
+            stringPreferencesKey("physical_keyboard_enter_behavior")
+    }
+
+    val physicalKeyboardEnterBehavior: Flow<PhysicalKeyboardEnterBehavior> = dataStore.data
+        .map { preferences ->
+            PhysicalKeyboardEnterBehavior.fromStoredValue(
+                preferences[KEY_PHYSICAL_KEYBOARD_ENTER],
+            )
+        }
+        .distinctUntilChanged()
+
+    suspend fun setPhysicalKeyboardEnterBehavior(behavior: PhysicalKeyboardEnterBehavior) {
+        dataStore.edit { preferences ->
+            preferences[KEY_PHYSICAL_KEYBOARD_ENTER] = behavior.storedValue
+        }
+    }
+}
@@ -112,12 +112,11 @@ data class ChatMessage(
     */
    val clientOnly: Boolean = false,
    /**
-     * Delivery state for a message the user sends into an agent **Thread** over
-     * the relay proactive channel ([com.hermesandroid.relay.viewmodel.ChatViewModel]
-     * routes `source=phone` sessions here instead of the normal chat send).
-     * `SENDING` until the relay acks (`proactive.reply.ack`) → `DELIVERED`;
-     * `FAILED` on a send error. Null for ordinary chat messages — those render
-     * no status affix.
+     * Delivery state for a user-authored message. Agent **Thread** replies use
+     * `SENDING` until the relay acks (`proactive.reply.ack`) → `DELIVERED`,
+     * with `FAILED` on a send error. Ordinary chat may additionally use
+     * `QUEUED` and `STEERED` to make active-turn routing visible. Null keeps the
+     * legacy behavior of rendering no status affix.
     */
    val deliveryStatus: MessageDeliveryStatus? = null,
    /**
@@ -367,12 +366,20 @@ data class ToolCall(
     * header can render without a separate lane registry.
     */
    val taskLabel: String? = null,
+    /** Live upstream child id used by subagent.steer while this lane runs. */
+    val subagentId: String? = null,
    /** Deterministic non-low output risk reported by upstream for this call. */
    val outputRisk: String? = null,
    /** Human-readable deterministic findings; rendered as untrusted metadata. */
    val outputRiskFindings: List<String> = emptyList(),
    /** Upstream removed sensitive spans before emitting the findings. */
    val outputRiskRedacted: Boolean = false,
+    /**
+     * Stable UI identity retained when a generating placeholder adopts its
+     * gateway tool ID. This keeps per-card interaction state attached to the
+     * logical call across streaming reconciliation and list updates.
+     */
+    val uiKey: String = id ?: "$name:$startedAt",
 )

 enum class MessageRole {
@@ -382,15 +389,17 @@ enum class MessageRole {
 }

 /**
- * Delivery state of a user reply sent into an agent Thread over the relay
- * proactive channel. Only set on Thread replies; ordinary chat messages leave
- * it null and show no status affix.
+ * Delivery state of a user-authored message. Thread replies use the relay ack
+ * lifecycle; ordinary chat can additionally expose queue and steer outcomes.
+ * Null preserves the legacy behavior of rendering no status affix.
 *
 * - [SENDING]   handed to the relay; awaiting the per-reply ack.
+ * - [QUEUED]    held client-side until the active turn completes.
+ * - [STEERED]   accepted as a correction to the active turn.
 * - [DELIVERED] the relay acked (`proactive.reply.ack`) — buffered for the agent.
 * - [FAILED]    the send errored (e.g. relay disconnected).
 */
-enum class MessageDeliveryStatus { SENDING, DELIVERED, FAILED }
+enum class MessageDeliveryStatus { SENDING, QUEUED, STEERED, DELIVERED, FAILED }

 data class ChatSession(
    val sessionId: String,
@@ -409,6 +418,9 @@ data class ChatSession(
    val source: String? = null,
    /** Server reports a persisted session runtime/model binding. */
    val hasModelConfig: Boolean = false,
+    /** Durable upstream session metadata, scoped by the owning connection/profile DB. */
+    val pinned: Boolean = false,
+    val archived: Boolean = false,
 ) {
    val activityTimestamp: Long
        get() = firstPositive(lastActivityAt, updatedAt, startedAt)
@@ -0,0 +1,66 @@
+package com.hermesandroid.relay.data
+
+import java.nio.charset.StandardCharsets
+import java.util.Base64
+
+/** Structured identity and preview for a quoted chat message. */
+data class ChatQuoteReference(
+    val messageId: String,
+    val authorLabel: String,
+    val excerpt: String,
+)
+
+/** Parsed transport envelope: Android renders [reference] separately from [body]. */
+data class ChatQuoteEnvelope(
+    val reference: ChatQuoteReference,
+    val body: String,
+)
+
+/**
+ * Serialize a structured quote as ordinary Markdown for unmodified Hermes clients.
+ * Android parses the same envelope back into a quote chip, while Desktop/TUI see
+ * a readable linked attribution instead of an Android-only marker.
+ */
+fun buildChatQuotedPrompt(body: String, reference: ChatQuoteReference?): String {
+    if (reference == null) return body
+    val encodedId = Base64.getUrlEncoder().withoutPadding().encodeToString(
+        reference.messageId.toByteArray(StandardCharsets.UTF_8),
+    )
+    val author = reference.authorLabel.normalizedQuoteText(MAX_AUTHOR_CHARS)
+    val excerpt = reference.excerpt.normalizedQuoteText(MAX_EXCERPT_CHARS)
+    if (encodedId.isBlank() || author.isBlank() || excerpt.isBlank()) return body
+    return "> **Replying to [@$author](hermes-message://$encodedId):** $excerpt\n\n$body"
+}
+
+/** Parse only the exact bounded envelope emitted by [buildChatQuotedPrompt]. */
+fun parseChatQuotedPrompt(content: String): ChatQuoteEnvelope? {
+    val match = QUOTE_ENVELOPE.matchEntire(content) ?: return null
+    val author = match.groupValues[1]
+    val encodedId = match.groupValues[2]
+    val excerpt = match.groupValues[3]
+    val body = match.groupValues[4]
+    val messageId = runCatching {
+        String(Base64.getUrlDecoder().decode(encodedId), StandardCharsets.UTF_8)
+    }.getOrNull()?.takeIf { it.isNotBlank() && it.length <= MAX_MESSAGE_ID_CHARS } ?: return null
+    return ChatQuoteEnvelope(
+        reference = ChatQuoteReference(messageId, author, excerpt),
+        body = body,
+    )
+}
+
+private fun String.normalizedQuoteText(maxChars: Int): String =
+    replace(Regex("[\\p{Cc}\\s]+"), " ")
+        .replace("\\", "")
+        .replace("]", "")
+        .trim()
+        .take(maxChars)
+
+private val QUOTE_ENVELOPE = Regex(
+    pattern = "^> \\*\\*Replying to \\[@([^]\\r\\n]{1,$MAX_AUTHOR_CHARS})]" +
+        "\\(hermes-message://([A-Za-z0-9_-]{1,512})\\):\\*\\* " +
+        "([^\\r\\n]{1,$MAX_EXCERPT_CHARS})\\n\\n([\\s\\S]*)$",
+)
+
+private const val MAX_AUTHOR_CHARS = 40
+private const val MAX_EXCERPT_CHARS = 240
+private const val MAX_MESSAGE_ID_CHARS = 512
@@ -32,6 +32,7 @@ data class ChatTurnCheckpoint(
    val priorUserMessageCount: Int,
    val baselineAssistantCount: Int,
    val pendingAsk: ChatTurnAskCheckpoint? = null,
+    val queuedMessages: List<ChatQueuedMessageCheckpoint> = emptyList(),
    val startedAt: Long,
    val updatedAt: Long,
 ) {
@@ -41,6 +42,17 @@ data class ChatTurnCheckpoint(
    }
 }

+@Serializable
+data class ChatQueuedMessageCheckpoint(
+    val id: String,
+    val text: String,
+    val transport: String,
+    val ownerRunId: String,
+    val interfaceContextPrompt: String? = null,
+    /** Attachment bytes are intentionally not copied into Preferences DataStore. */
+    val hadAttachments: Boolean = false,
+)
+
@Serializable
 data class ChatTurnUserCheckpoint(
    val id: String,
@@ -134,7 +134,7 @@ data class Connection(
         * than to crash).
         */
        fun extractDefaultLabel(apiServerUrl: String): String =
-            extractHost(apiServerUrl) ?: apiServerUrl
+            extractHost(apiServerUrl)?.let(::defaultLabelFromHost) ?: apiServerUrl

        /** Preserve explicit labels while upgrading an auto-generated IP label to a discovered host name. */
        fun chooseDiscoveredLabel(
@@ -160,7 +160,25 @@ data class Connection(
            val primary = dashboardUrl?.trim()?.takeIf { it.isNotBlank() }
                ?: apiServerUrl.trim().takeIf { it.isNotBlank() }
                ?: relayUrl.trim()
-            return extractHost(primary) ?: primary
+            return extractHost(primary)?.let(::defaultLabelFromHost) ?: primary
+        }
+
+        /**
+         * Nous-hosted agent gateways use the stable
+         * `<slug>.agents.nousresearch.com` origin contract. The public Hermes
+         * status response deliberately carries no tenant/agent display name,
+         * so a URL-only connection uses that exact single-label slug as its
+         * least-surprising default. Portal's human-readable agent name is only
+         * available through its separately authenticated discovery API.
+         *
+         * Match the complete suffix and exactly one leading DNS label. This
+         * avoids shortening lookalike or operator-controlled hostnames.
+         */
+        private fun defaultLabelFromHost(host: String): String {
+            val suffix = ".agents.nousresearch.com"
+            if (!host.endsWith(suffix, ignoreCase = true)) return host
+            val slug = host.dropLast(suffix.length)
+            return slug.takeIf { it.isNotBlank() && '.' !in it } ?: host
        }

        private fun extractHost(url: String): String? = try {
@@ -247,6 +265,7 @@ data class Connection(
            apiServerUrl: String,
            relayUrl: String,
            extraApiUrls: List<Pair<String, String>> = emptyList(),
+            dashboardUrl: String? = null,
        ): List<EndpointCandidate> {
            val routes = buildList {
                endpointCandidateFromApiUrl(
@@ -255,6 +274,7 @@ data class Connection(
                    apiServerUrl = apiServerUrl,
                    relayUrl = relayUrl.takeIf { it.isNotBlank() }
                        ?: deriveDefaultRelayUrl(apiServerUrl).orEmpty(),
+                    dashboardUrl = dashboardUrl,
                )?.let(::add)

                extraApiUrls
@@ -266,6 +286,7 @@ data class Connection(
                            priority = index + 1,
                            apiServerUrl = url,
                            relayUrl = deriveDefaultRelayUrl(url).orEmpty(),
+                            dashboardUrl = dashboardUrl,
                        )?.let(::add)
                    }
            }
@@ -340,6 +361,7 @@ data class Connection(
            priority: Int,
            apiServerUrl: String,
            relayUrl: String,
+            dashboardUrl: String? = null,
        ): EndpointCandidate? {
            val uri = runCatching { URI(apiServerUrl.trim().trimEnd('/')) }.getOrNull()
                ?: return null
@@ -363,12 +385,62 @@ data class Connection(
                role = role.ifBlank { inferRouteRole(apiServerUrl) },
                priority = priority,
                api = ApiEndpoint(host = host, port = port, tls = tls),
-                dashboard = deriveDefaultDashboardUrl(apiServerUrl)
+                dashboard = dashboardUrl
+                    ?.trim()
+                    ?.trimEnd('/')
+                    ?.takeIf { it.isNotBlank() && urlsShareHost(it, apiServerUrl) }
+                    ?.let { DashboardEndpoint(url = it) }
+                    ?: deriveDefaultDashboardUrl(apiServerUrl)
                    ?.let { DashboardEndpoint(url = it) },
                relay = RelayEndpoint(url = resolvedRelayUrl, transportHint = transportHint),
            )
        }

+        /**
+         * Reconcile stored API-derived routes with the Dashboard origin that
+         * was actually verified during setup. Older app versions synthesized
+         * `:9119` for every API route, even when the same host was reached
+         * through an HTTPS reverse proxy on 443. Replace only that conventional
+         * synthesized value (or a missing value); preserve explicit and
+         * different-host LAN/Tailscale routes.
+         */
+        fun reconcileDashboardRoutes(
+            dashboardUrl: String?,
+            candidates: List<EndpointCandidate>,
+        ): List<EndpointCandidate> {
+            val explicitDashboard = dashboardUrl
+                ?.trim()
+                ?.trimEnd('/')
+                ?.takeIf { it.isNotBlank() }
+                ?: return candidates
+            return candidates.map { candidate ->
+                val apiUrl = candidate.api?.url ?: return@map candidate
+                if (!urlsShareHost(explicitDashboard, apiUrl)) return@map candidate
+
+                val currentDashboard = candidate.dashboard?.url
+                val derivedDashboard = deriveDefaultDashboardUrl(apiUrl)
+                val canReplace = currentDashboard.isNullOrBlank() ||
+                    (
+                        derivedDashboard != null &&
+                            currentDashboard.trim().trimEnd('/')
+                                .equals(derivedDashboard, ignoreCase = true)
+                    )
+                if (canReplace) {
+                    candidate.copy(dashboard = DashboardEndpoint(url = explicitDashboard))
+                } else {
+                    candidate
+                }
+            }
+        }
+
+        fun urlsShareHost(leftUrl: String, rightUrl: String): Boolean {
+            val leftHost = runCatching { URI(leftUrl.trim()) }.getOrNull()?.host
+            val rightHost = runCatching { URI(rightUrl.trim()) }.getOrNull()?.host
+            return !leftHost.isNullOrBlank() &&
+                !rightHost.isNullOrBlank() &&
+                leftHost.equals(rightHost, ignoreCase = true)
+        }
+
        /**
         * De-duplication identity for rebuilding stored routes. Prefer the
         * legacy API authority when present so an older API-only candidate and
@@ -543,29 +543,6 @@ class ConnectionStore private constructor(
        }
    }

-    private fun Connection.withDashboardDefaults(): Connection {
-        val derivedDashboardUrl = Connection.deriveDefaultDashboardUrl(apiServerUrl)
-        val normalizedRoutes = routeCandidates.ifEmpty {
-            Connection.buildRouteCandidates(apiServerUrl, relayUrl)
-        }
-        val normalizedPreferredRouteRole = preferredRouteRole?.takeIf { preferred ->
-            normalizedRoutes.any { it.role.equals(preferred, ignoreCase = true) }
-        }
-        return if (
-            (dashboardUrl.isNullOrBlank() && derivedDashboardUrl != null) ||
-            normalizedRoutes != routeCandidates ||
-            normalizedPreferredRouteRole != preferredRouteRole
-        ) {
-            copy(
-                dashboardUrl = dashboardUrl?.takeIf { it.isNotBlank() } ?: derivedDashboardUrl,
-                routeCandidates = normalizedRoutes,
-                preferredRouteRole = normalizedPreferredRouteRole,
-            )
-        } else {
-            this
-        }
-    }
-
    companion object {
        private const val TAG = "ConnectionStore"

@@ -585,3 +562,40 @@ class ConnectionStore private constructor(
        private const val DEFAULT_RELAY_URL = "ws://localhost:8767"
    }
 }
+
+/**
+ * Restore route defaults after loading a serialized connection. This remains
+ * internal so focused persistence tests can exercise the same normalization
+ * path used by [ConnectionStore].
+ */
+internal fun Connection.withDashboardDefaults(): Connection {
+    val derivedDashboardUrl = Connection.deriveDefaultDashboardUrl(apiServerUrl)
+    val effectiveDashboardUrl = dashboardUrl?.takeIf { it.isNotBlank() } ?: derivedDashboardUrl
+    val storedOrDefaultRoutes = routeCandidates.ifEmpty {
+        Connection.buildRouteCandidates(
+            apiServerUrl = apiServerUrl,
+            relayUrl = relayUrl,
+            dashboardUrl = effectiveDashboardUrl,
+        )
+    }
+    val normalizedRoutes = Connection.reconcileDashboardRoutes(
+        dashboardUrl = effectiveDashboardUrl,
+        candidates = storedOrDefaultRoutes,
+    )
+    val normalizedPreferredRouteRole = preferredRouteRole?.takeIf { preferred ->
+        normalizedRoutes.any { it.role.equals(preferred, ignoreCase = true) }
+    }
+    return if (
+        dashboardUrl != effectiveDashboardUrl ||
+        normalizedRoutes != routeCandidates ||
+        normalizedPreferredRouteRole != preferredRouteRole
+    ) {
+        copy(
+            dashboardUrl = effectiveDashboardUrl,
+            routeCandidates = normalizedRoutes,
+            preferredRouteRole = normalizedPreferredRouteRole,
+        )
+    } else {
+        this
+    }
+}
@@ -22,6 +22,7 @@ object FeatureFlags {

    // DataStore keys
    private val KEY_DEV_OPTIONS_UNLOCKED = booleanPreferencesKey("dev_options_unlocked")
+    private val KEY_PET_TERRAIN_OVERLAY = booleanPreferencesKey("pet_terrain_overlay")

    /** Whether the app is running a debug build. */
    val isDevBuild: Boolean get() = BuildConfig.DEV_MODE
@@ -32,6 +33,35 @@ object FeatureFlags {
            prefs[KEY_DEV_OPTIONS_UNLOCKED] ?: isDevBuild
        }

+    /**
+     * Developer-only visualization of the floating pet's measured terrain.
+     *
+     * The persisted request is intentionally weaker than both gates: release
+     * builds can never enable it, and explicitly locking Developer Options
+     * suppresses it immediately.
+     */
+    fun petTerrainOverlayEnabled(context: Context): Flow<Boolean> =
+        context.relayDataStore.data.map { prefs ->
+            petTerrainOverlayEffective(
+                isDevBuild = isDevBuild,
+                devOptionsUnlocked = prefs[KEY_DEV_OPTIONS_UNLOCKED] ?: isDevBuild,
+                requested = prefs[KEY_PET_TERRAIN_OVERLAY] ?: false,
+            )
+        }
+
+    internal fun petTerrainOverlayEffective(
+        isDevBuild: Boolean,
+        devOptionsUnlocked: Boolean,
+        requested: Boolean,
+    ): Boolean = isDevBuild && devOptionsUnlocked && requested
+
+    /** Persist the developer's overlay request. Runtime gates remain authoritative. */
+    suspend fun setPetTerrainOverlayEnabled(context: Context, enabled: Boolean) {
+        context.relayDataStore.edit { prefs ->
+            prefs[KEY_PET_TERRAIN_OVERLAY] = enabled
+        }
+    }
+
    /** Unlock Developer Options. */
    suspend fun unlockDevOptions(context: Context) {
        context.relayDataStore.edit { prefs ->
@@ -43,6 +73,7 @@ object FeatureFlags {
    suspend fun lockDevOptions(context: Context) {
        context.relayDataStore.edit { prefs ->
            prefs[KEY_DEV_OPTIONS_UNLOCKED] = false
+            prefs[KEY_PET_TERRAIN_OVERLAY] = false
        }
    }

@@ -0,0 +1,135 @@
+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.floatPreferencesKey
+import androidx.datastore.preferences.core.intPreferencesKey
+import androidx.datastore.preferences.core.stringPreferencesKey
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+
+/** Exact cadence values consumed by the floating-pet behavior director. */
+data class PetBehaviorPacing(
+    val responseVisitDelayMs: Long,
+    val roamIntervalMs: Long,
+    val idleReactionCadenceMs: Long,
+) {
+    init {
+        require(responseVisitDelayMs > 0L)
+        require(roamIntervalMs > responseVisitDelayMs)
+        require(idleReactionCadenceMs > roamIntervalMs)
+    }
+}
+
+/**
+ * User-facing pet activity presets.
+ *
+ * These values control how often an otherwise-idle pet may act. Existing
+ * animation, reduced-motion, touch-exploration, scrolling, and agent-activity
+ * gates remain authoritative and may always defer an action.
+ */
+enum class PetTemperament(val pacing: PetBehaviorPacing) {
+    Calm(
+        PetBehaviorPacing(
+            responseVisitDelayMs = 2_500L,
+            roamIntervalMs = 12_000L,
+            idleReactionCadenceMs = 28_000L,
+        ),
+    ),
+    Balanced(
+        PetBehaviorPacing(
+            responseVisitDelayMs = 1_500L,
+            roamIntervalMs = 8_000L,
+            idleReactionCadenceMs = 18_000L,
+        ),
+    ),
+    Playful(
+        PetBehaviorPacing(
+            responseVisitDelayMs = 750L,
+            roamIntervalMs = 5_000L,
+            idleReactionCadenceMs = 10_000L,
+        ),
+    ),
+}
+
+val DEFAULT_PET_TEMPERAMENT: PetTemperament = PetTemperament.Balanced
+const val DEFAULT_PET_SIZE_SCALE: Float = 1f
+const val MIN_PET_SIZE_SCALE: Float = 0.6f
+const val MAX_PET_SIZE_SCALE: Float = 1.2f
+private const val LEGACY_PET_SIZE_BASE_SCALE: Float = 1.25f
+private const val CURRENT_PET_SIZE_SCALE_VERSION: Int = 2
+
+internal fun sanitizedPetSizeScale(value: Float?): Float =
+    value?.takeIf(Float::isFinite)?.coerceIn(MIN_PET_SIZE_SCALE, MAX_PET_SIZE_SCALE)
+        ?: DEFAULT_PET_SIZE_SCALE
+
+internal fun decodeStoredPetSizeScale(value: Float?, version: Int?): Float {
+    if (value == null) return DEFAULT_PET_SIZE_SCALE
+    val rebased = if (version == null) value / LEGACY_PET_SIZE_BASE_SCALE else value
+    return sanitizedPetSizeScale(rebased)
+}
+
+data class PetBehaviorPreferences(
+    val temperament: PetTemperament = DEFAULT_PET_TEMPERAMENT,
+    val sizeScale: Float = DEFAULT_PET_SIZE_SCALE,
+) {
+    /**
+     * Runtime seam for the behavior director. A disabled motion gate returns
+     * no pacing rather than weakening the app's accessibility policy.
+     */
+    fun pacingWhenMotionAllowed(motionAllowed: Boolean): PetBehaviorPacing? =
+        temperament.pacing.takeIf { motionAllowed }
+}
+
+/** Additive, phone-local DataStore persistence for pet behavior preferences. */
+class PetBehaviorPreferencesRepository(
+    private val dataStore: DataStore<Preferences>,
+) {
+    constructor(context: Context) : this(context.relayDataStore)
+
+    companion object {
+        internal val KEY_TEMPERAMENT = stringPreferencesKey("pet_temperament")
+        internal val KEY_SIZE_SCALE = floatPreferencesKey("pet_size_scale")
+        internal val KEY_SIZE_SCALE_VERSION = intPreferencesKey("pet_size_scale_version")
+    }
+
+    val flow: Flow<PetBehaviorPreferences> = dataStore.data
+        .map { preferences ->
+            PetBehaviorPreferences(
+                temperament = decodeTemperament(preferences[KEY_TEMPERAMENT]),
+                sizeScale = decodeStoredPetSizeScale(
+                    value = preferences[KEY_SIZE_SCALE],
+                    version = preferences[KEY_SIZE_SCALE_VERSION],
+                ),
+            )
+        }
+        .distinctUntilChanged()
+
+    val temperament: Flow<PetTemperament> = flow
+        .map { preferences -> preferences.temperament }
+        .distinctUntilChanged()
+
+    val sizeScale: Flow<Float> = flow
+        .map { preferences -> preferences.sizeScale }
+        .distinctUntilChanged()
+
+    suspend fun setTemperament(temperament: PetTemperament) {
+        dataStore.edit { preferences ->
+            preferences[KEY_TEMPERAMENT] = temperament.name
+        }
+    }
+
+    suspend fun setSizeScale(sizeScale: Float) {
+        dataStore.edit { preferences ->
+            preferences[KEY_SIZE_SCALE] = sanitizedPetSizeScale(sizeScale)
+            preferences[KEY_SIZE_SCALE_VERSION] = CURRENT_PET_SIZE_SCALE_VERSION
+        }
+    }
+
+    private fun decodeTemperament(raw: String?): PetTemperament =
+        raw?.let { stored -> PetTemperament.entries.firstOrNull { it.name == stored } }
+            ?: DEFAULT_PET_TEMPERAMENT
+}
@@ -47,9 +47,10 @@ import kotlinx.serialization.Serializable
 *
 * **Hermes profile API metadata.** A relay can advertise an isolated
 * profile API server without exposing its secret. When [apiServerUrl] is
- * present, Android routes chat/session traffic to that URL and reuses the
- * active connection's stored API key. Operators that use distinct API keys
- * per profile should pair those profile API servers as separate connections.
+ * present, Android routes chat/session traffic to that URL using the active
+ * connection credential. A positively identified shared multiplex
+ * `/p/<profile>` route instead uses a separately encrypted profile credential;
+ * the root connection key is never reused for that route.
 */
@Serializable
 data class Profile(
@@ -26,7 +26,6 @@ object ProfilePresentationPolicy {
    fun availableKeys(profiles: List<Profile>): List<String> = buildList {
        add(AgentDisplay.SERVER_DEFAULT_PROFILE_KEY)
        profiles.asSequence()
-            .filterNot { AgentDisplay.isServerDefaultAlias(it.name) }
            .map(Profile::name)
            .distinct()
            .forEach(::add)
@@ -49,6 +48,12 @@ object ProfilePresentationPolicy {
    ): List<String> = orderedKeys(profiles, presentation).filter { key ->
        key == selectedKey || key !in presentation.hidden
    }
+
+    fun shouldShowShelf(
+        profiles: List<Profile>,
+        presentation: ProfilePresentation,
+        selectedKey: String,
+    ): Boolean = visibleKeys(profiles, presentation, selectedKey).size > 1
 }

 class ProfilePresentationStore(
@@ -0,0 +1,7 @@
+package com.hermesandroid.relay.data
+
+/** Live activity surfaced beside a session without conflating it with selection. */
+enum class SessionActivityState {
+    Working,
+    NeedsInput,
+}
@@ -13,6 +13,11 @@ import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+val DEFAULT_VOICE_STOP_PHRASES: List<String> = listOf("stop")

 /**
 * User-tunable voice mode preferences.
@@ -36,6 +41,16 @@ data class VoiceSettings(
    val audioRoute: String = VoiceAudioRoute.Auto.storageValue,
    val interactionMode: String = "tap",
    val silenceThresholdMs: Long = 1250L,
+    /** Exact phrases that end an active voice chat; empty disables the command. */
+    val stopPhrases: List<String> = DEFAULT_VOICE_STOP_PHRASES,
+    /**
+     * When true, voice keeps progress visual and waits for the settled Hermes
+     * answer before speaking. Tool status, service updates, and intermediate
+     * assistant commentary are not narrated.
+     */
+    val finalAnswerOnly: Boolean = false,
+    /** Presentation only; changing this never restarts or interrupts voice. */
+    val presentationMode: String = VoicePresentationMode.Focus.storageValue,
    val realtimeTraceDetails: Boolean = false,
    /**
     * When true (default), Realtime Agent keeps one provider session/socket open
@@ -122,6 +137,16 @@ enum class VoiceAudioRoute(val storageValue: String) {
    }
 }

+enum class VoicePresentationMode(val storageValue: String) {
+    Focus("focus"),
+    Conversation("conversation");
+
+    companion object {
+        fun fromStorage(value: String?): VoicePresentationMode =
+            values().firstOrNull { it.storageValue == value } ?: Focus
+    }
+}
+
 /**
 * Active scope for per-profile voice prefs.
 *
@@ -182,6 +207,9 @@ class VoicePreferencesRepository(private val dataStore: DataStore<Preferences>)
        // un-namespaced means switching profiles never churns these.
        private val KEY_INTERACTION_MODE = stringPreferencesKey("voice_interaction_mode")
        private val KEY_SILENCE_THRESHOLD_MS = longPreferencesKey("voice_silence_threshold_ms")
+        private val KEY_STOP_PHRASES = stringPreferencesKey("voice_stop_phrases")
+        private val KEY_FINAL_ANSWER_ONLY = booleanPreferencesKey("voice_final_answer_only")
+        private val KEY_PRESENTATION_MODE = stringPreferencesKey("voice_presentation_mode")
        private val KEY_REALTIME_TRACE_DETAILS = booleanPreferencesKey("voice_realtime_trace_details")
        private val KEY_REALTIME_PERSISTENT_SESSION =
            booleanPreferencesKey("voice_realtime_persistent_session")
@@ -191,8 +219,14 @@ class VoicePreferencesRepository(private val dataStore: DataStore<Preferences>)
        const val DEFAULT_INTERACTION_MODE = "tap"
        // 1250 ms matches hermes-desktop voice_mode `silenceMs` end-of-speech.
        const val DEFAULT_SILENCE_THRESHOLD_MS = 1250L
+        const val DEFAULT_FINAL_ANSWER_ONLY = false
+        const val DEFAULT_PRESENTATION_MODE = "focus"
        const val DEFAULT_REALTIME_TRACE_DETAILS = false
        const val DEFAULT_REALTIME_PERSISTENT_SESSION = true
+        private val stopPhrasesJson = Json {
+            ignoreUnknownKeys = true
+            isLenient = true
+        }

        /**
         * Build the storage name for a per-profile [base] key under [scope].
@@ -258,6 +292,11 @@ class VoicePreferencesRepository(private val dataStore: DataStore<Preferences>)
            // --- global (shared across profiles) ---
            interactionMode = prefs[KEY_INTERACTION_MODE] ?: DEFAULT_INTERACTION_MODE,
            silenceThresholdMs = prefs[KEY_SILENCE_THRESHOLD_MS] ?: DEFAULT_SILENCE_THRESHOLD_MS,
+            stopPhrases = decodeStopPhrases(prefs[KEY_STOP_PHRASES]),
+            finalAnswerOnly = prefs[KEY_FINAL_ANSWER_ONLY] ?: DEFAULT_FINAL_ANSWER_ONLY,
+            presentationMode = VoicePresentationMode.fromStorage(
+                prefs[KEY_PRESENTATION_MODE] ?: DEFAULT_PRESENTATION_MODE,
+            ).storageValue,
            realtimeTraceDetails = prefs[KEY_REALTIME_TRACE_DETAILS]
                ?: DEFAULT_REALTIME_TRACE_DETAILS,
            realtimePersistentSession = prefs[KEY_REALTIME_PERSISTENT_SESSION]
@@ -367,6 +406,23 @@ class VoicePreferencesRepository(private val dataStore: DataStore<Preferences>)
        dataStore.edit { it[KEY_SILENCE_THRESHOLD_MS] = ms.coerceAtLeast(500L) }
    }

+    suspend fun setStopPhrases(phrases: List<String>) {
+        val normalized = phrases.asSequence()
+            .map(String::trim)
+            .filter(String::isNotEmpty)
+            .distinct()
+            .toList()
+        dataStore.edit { it[KEY_STOP_PHRASES] = stopPhrasesJson.encodeToString(normalized) }
+    }
+
+    suspend fun setFinalAnswerOnly(enabled: Boolean) {
+        dataStore.edit { it[KEY_FINAL_ANSWER_ONLY] = enabled }
+    }
+
+    suspend fun setPresentationMode(mode: VoicePresentationMode) {
+        dataStore.edit { it[KEY_PRESENTATION_MODE] = mode.storageValue }
+    }
+
    suspend fun setRealtimeTraceDetails(enabled: Boolean) {
        dataStore.edit { it[KEY_REALTIME_TRACE_DETAILS] = enabled }
    }
@@ -375,6 +431,17 @@ class VoicePreferencesRepository(private val dataStore: DataStore<Preferences>)
        dataStore.edit { it[KEY_REALTIME_PERSISTENT_SESSION] = enabled }
    }

+    private fun decodeStopPhrases(raw: String?): List<String> {
+        if (raw == null) return DEFAULT_VOICE_STOP_PHRASES
+        return runCatching { stopPhrasesJson.decodeFromString<List<String>>(raw) }
+            .getOrDefault(DEFAULT_VOICE_STOP_PHRASES)
+            .asSequence()
+            .map(String::trim)
+            .filter(String::isNotEmpty)
+            .distinct()
+            .toList()
+    }
+
    /**
     * Atomically apply the phone-side portion of [preset]. Only fields owned by
     * the preset are written, so route/provider/model/voice overrides and other
@@ -3,6 +3,8 @@ package com.hermesandroid.relay.diagnostics
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import com.hermesandroid.relay.reliability.ReliabilityCenter
+import com.hermesandroid.relay.reliability.ReliabilityRedactor

 enum class DiagnosticCategory(val label: String) {
    Api("API"),
@@ -25,7 +27,16 @@ data class DiagnosticLogEntry(
    val severity: DiagnosticSeverity,
    val title: String,
    val detail: String? = null,
+    /** Human-readable action that produced this event, not merely its subsystem. */
+    val operation: String? = null,
    val endpointRole: String? = null,
+    /** User/configuration-facing route before protocol/path normalization. */
+    val configuredUrl: String? = null,
+    /** Exact sanitized URL attempted on the wire, including the diagnostic path. */
+    val requestUrl: String? = null,
+    /** Concrete next troubleshooting step for failures with a known interpretation. */
+    val suggestion: String? = null,
+    /** Legacy single-URL field retained for diagnostics that have not needed split context. */
    val url: String? = null,
    val elapsedMs: Long? = null,
    /**
@@ -34,7 +45,11 @@ data class DiagnosticLogEntry(
     * the detail view shows this. Null for non-error / manually-recorded entries.
     */
    val stacktrace: String? = null,
-)
+) {
+    /** Best route for mode inference and compact list rendering. */
+    val primaryUrl: String?
+        get() = configuredUrl ?: requestUrl ?: url
+}

 /**
 * Current health of a single subsystem on the Diagnostics status timeline.
@@ -81,19 +96,29 @@ object DiagnosticsLog {
        severity: DiagnosticSeverity = DiagnosticSeverity.Info,
        title: String,
        detail: String? = null,
+        operation: String? = null,
        endpointRole: String? = null,
+        configuredUrl: String? = null,
+        requestUrl: String? = null,
+        suggestion: String? = null,
        url: String? = null,
        elapsedMs: Long? = null,
        stacktrace: String? = null,
    ) {
+        val safeConfiguredUrl = sanitizeUrl(configuredUrl)
+        val safeRequestUrl = sanitizeUrl(requestUrl)
        val entry = DiagnosticLogEntry(
            timestampMs = System.currentTimeMillis(),
            category = category,
            severity = severity,
            title = clean(title) ?: title.take(MAX_TEXT_LENGTH),
            detail = clean(detail),
+            operation = clean(operation),
            endpointRole = clean(endpointRole),
-            url = sanitizeUrl(url),
+            configuredUrl = safeConfiguredUrl,
+            requestUrl = safeRequestUrl,
+            suggestion = clean(suggestion),
+            url = if (safeConfiguredUrl == null && safeRequestUrl == null) sanitizeUrl(url) else null,
            elapsedMs = elapsedMs,
            stacktrace = redactTrace(stacktrace),
        )
@@ -121,20 +146,40 @@ object DiagnosticsLog {
        title: String,
        detail: String? = null,
        throwable: Throwable? = null,
+        operation: String? = null,
        endpointRole: String? = null,
+        configuredUrl: String? = null,
+        requestUrl: String? = null,
+        suggestion: String? = null,
        url: String? = null,
        elapsedMs: Long? = null,
+        reliabilityContext: String? = null,
    ) {
        record(
            category = category,
            severity = DiagnosticSeverity.Error,
            title = title,
            detail = detail ?: throwable?.message,
+            operation = operation,
            endpointRole = endpointRole,
+            configuredUrl = configuredUrl,
+            requestUrl = requestUrl,
+            suggestion = suggestion,
            url = url,
            elapsedMs = elapsedMs,
            stacktrace = throwable?.let { stackTraceText(it) },
        )
+        if (throwable != null) {
+            runCatching {
+                ReliabilityCenter.recordHandled(
+                    title = title,
+                    detail = detail ?: throwable.message,
+                    throwable = throwable,
+                    context = reliabilityContext,
+                    routeRole = endpointRole,
+                )
+            }
+        }
    }

    private fun stackTraceText(t: Throwable): String =
@@ -167,10 +212,8 @@ object DiagnosticsLog {
            val prefix = noQuery.substring(0, schemeEnd + 3)
            val rest = noQuery.substring(schemeEnd + 3)
            val slash = rest.indexOf('/').let { if (it < 0) rest.length else it }
-            val authority = rest.substring(0, slash)
            val path = rest.substring(slash)
-            val safeAuthority = authority.substringAfterLast('@')
-            prefix + safeAuthority + path
+            prefix + "[host]" + path
        } else {
            noQuery
        }
@@ -197,7 +240,7 @@ object DiagnosticsLog {
     */
    private fun redactTrace(value: String?): String? {
        val trimmed = value?.trim()?.takeIf { it.isNotBlank() } ?: return null
-        val redacted = redact(trimmed)
+        val redacted = ReliabilityRedactor.redact(trimmed, MAX_TRACE_LENGTH)
        return if (redacted.length > MAX_TRACE_LENGTH) {
            redacted.take(MAX_TRACE_LENGTH) + "\n… (truncated)"
        } else {
@@ -205,8 +248,5 @@ object DiagnosticsLog {
        }
    }

-    private fun redact(value: String): String =
-        value.replace(Regex("""(?i)(bearer|token|api[_-]?key|session[_-]?token)\s*[:=]\s*\S+""")) {
-            "${it.groupValues[1]}=[hidden]"
-        }
+    private fun redact(value: String): String = ReliabilityRedactor.redact(value, MAX_TRACE_LENGTH)
 }
@@ -0,0 +1,42 @@
+package com.hermesandroid.relay.diagnostics
+
+import java.net.ConnectException
+import java.net.NoRouteToHostException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+
+/**
+ * Maps network failure classes to narrow, truthful next steps.
+ *
+ * These messages are diagnostic guidance, not recovery behavior: callers still
+ * own retries, routing, and authentication. Walking the cause chain preserves
+ * useful classification when OkHttp or a coroutine boundary wraps the socket
+ * exception in a higher-level failure.
+ */
+object NetworkDiagnosticGuidance {
+    fun forThrowable(throwable: Throwable, target: String): String? {
+        val causes = generateSequence(throwable as Throwable?) { it.cause }.take(12).toList()
+        return when {
+            causes.any { it is ConnectException } ->
+                "Verify $target is running and listening on the configured host and port."
+            causes.any { it is UnknownHostException } ->
+                "Verify the configured hostname resolves from this device."
+            causes.any { it is NoRouteToHostException } ->
+                "Verify the device has a network path to the configured host."
+            causes.any { it is SocketTimeoutException } ->
+                "Check network routing or firewall rules between this device and $target."
+            causes.any { it is SSLException } ->
+                "Verify the TLS scheme, certificate, and trust configuration for $target."
+            else -> null
+        }
+    }
+
+    fun forHttpStatus(statusCode: Int, target: String): String? = when (statusCode) {
+        401, 403 -> "Verify the configured $target credentials or pair the device again."
+        404 -> "Verify this URL points to the expected $target route and version."
+        429 -> "Wait for the server's backoff period before retrying."
+        in 500..599 -> "Check the $target server logs for the failing request."
+        else -> null
+    }
+}
@@ -5,6 +5,7 @@ import android.net.ConnectivityManager
 import android.net.Network
 import android.net.NetworkCapabilities
 import android.net.NetworkRequest
+import android.os.SystemClock
 import android.util.Log
 import com.hermesandroid.relay.R
 import com.hermesandroid.relay.auth.CertPinStore
@@ -14,11 +15,15 @@ import com.hermesandroid.relay.data.PairingPreferences
 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.relay.models.Envelope
 import com.hermesandroid.relay.network.shared.EndpointResolver
+import com.hermesandroid.relay.network.shared.EndpointSurface
+import com.hermesandroid.relay.network.shared.fullJitterDelayMs
 import com.hermesandroid.relay.network.shutdownOffMainThread
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -44,6 +49,20 @@ enum class ConnectionState {
    Reconnecting
 }

+internal fun isRelayRateLimitBackoffActive(untilMs: Long, nowMs: Long): Boolean =
+    untilMs > nowMs
+
+internal fun canOverrideScheduledRelayReconnect(
+    state: ConnectionState,
+    backoffWaiting: Boolean,
+    rateLimitBackoffActive: Boolean,
+): Boolean = !rateLimitBackoffActive && when (state) {
+    ConnectionState.Disconnected -> true
+    ConnectionState.Reconnecting -> backoffWaiting
+    ConnectionState.Connecting,
+    ConnectionState.Connected -> false
+}
+
 /**
 * Build an OkHttp request for a relay socket URL, or `null` if the URL is
 * malformed. OkHttp's [Request.Builder.url] throws [IllegalArgumentException]
@@ -121,6 +140,8 @@ class ConnectionManager(
     * non-null — the manager falls back to the single-URL path.
     */
    private val deviceIdProvider: (suspend () -> String?)? = null,
+    /** Random source for ordinary reconnect full-jitter; exact backoffs never use it. */
+    private val reconnectJitterUnit: () -> Double = { kotlin.random.Random.nextDouble() },
 ) {
    private val supervisorJob = SupervisorJob()
    private val scope = CoroutineScope(supervisorJob + Dispatchers.IO)
@@ -161,7 +182,11 @@ class ConnectionManager(

    @Volatile
    private var serverUrl: String? = null
-    private var reconnectAttempt = 0
+    private val reconnectState = RelayReconnectState()
+    @Volatile
+    private var reconnectJob: Job? = null
+    @Volatile
+    private var reconnectBackoffWaiting = false
    private var shouldReconnect = true
    // Last HTTP status seen during WSS upgrade, captured in onFailure.
    // Used by scheduleReconnect() to pick an appropriate backoff — notably
@@ -169,14 +194,8 @@ class ConnectionManager(
    // we don't re-fill the ban bucket and brick our own auth window.
    @Volatile
    private var lastUpgradeResponseCode: Int? = null
-
-    // Consecutive relay socket failures (response == null) since the last
-    // successful onOpen. One slow Tailscale/DERP cold-start handshake must not
-    // immediately evict the active route from the SHARED resolver cache (chat +
-    // dashboard ride the same resolver), so we only poison the route after a
-    // couple of consecutive transport-level failures.
    @Volatile
-    private var consecutiveSocketFailures = 0
+    private var rateLimitBackoffUntilMs: Long = 0L

    // The relay requires the FIRST frame on a socket to be `system/auth` and
    // rejects the whole connection otherwise ("expected system/auth, got
@@ -206,6 +225,10 @@ class ConnectionManager(
    private val _activeEndpoint = MutableStateFlow<EndpointCandidate?>(null)
    val activeEndpoint: StateFlow<EndpointCandidate?> = _activeEndpoint.asStateFlow()

+    /** Relay-only winner, deliberately separate from the standard route. */
+    @Volatile
+    private var activeRelayEndpoint: EndpointCandidate? = null
+
    /**
     * Manual role override. When non-null, the resolver's output is replaced
     * with whichever candidate in the stored list matches this role (case-
@@ -262,9 +285,9 @@ class ConnectionManager(
        private const val TAG = "ConnectionManager"
        private const val MAX_BACKOFF_MS = 30_000L
        private const val BASE_BACKOFF_MS = 1_000L
-        // How many consecutive relay socket failures before we mark the active
-        // endpoint unreachable in the shared resolver cache. Tolerates a single
-        // cold-start blip on a slow remote (Tailscale DERP) link.
+        // How many consecutive failures on one relay socket URL before we mark
+        // that candidate's Relay surface unreachable. Standard Dashboard/API
+        // reachability is cached independently and remains healthy.
        private const val MARK_UNREACHABLE_AFTER_FAILURES = 2
        // Settle window before re-resolving after a network event. Long
        // enough to coalesce the onAvailable burst of a handoff, short
@@ -325,17 +348,19 @@ class ConnectionManager(
        // behavior for freshly-upgraded installs and for v1/v2 QRs where
        // the synthesized list just collapses to the same URL anyway.
        scope.launch {
-            val resolved = resolveBestEndpointSafe()
-            val resolvedRelayUrl = resolved?.relay?.url?.takeIf { it.isNotBlank() }
+            val resolved = resolveBestEndpointSafe(EndpointSurface.Standard)
+            val relayResolved = resolveBestEndpointSafe(EndpointSurface.Relay)
+            val resolvedRelayUrl = relayResolved?.relay?.url?.takeIf { it.isNotBlank() }
            val targetUrl = resolvedRelayUrl ?: url.takeIf { it.isNotBlank() }
+            activeRelayEndpoint = relayResolved
            if (resolved != null) {
                _activeEndpoint.value = resolved
-                Log.i(TAG, "connect: resolver picked role=${resolved.role} " +
-                    "route=${resolved.primaryRouteUrl()} (relay fallback would have been $url)")
+                Log.i(TAG, "connect: standard resolver picked role=${resolved.role} " +
+                    "route=${resolved.primaryRouteUrl()}")
                DiagnosticsLog.record(
-                    category = DiagnosticCategory.Relay,
+                    category = DiagnosticCategory.Endpoint,
                    severity = DiagnosticSeverity.Info,
-                    title = context?.getString(R.string.conn_diag_route_selected) ?: "Relay route selected",
+                    title = context?.getString(R.string.conn_diag_route_selected) ?: "Route selected",
                    endpointRole = resolved.role,
                    url = resolved.primaryRouteUrl(),
                )
@@ -350,6 +375,13 @@ class ConnectionManager(
                    url = url,
                )
            }
+            relayResolved?.let { relayRoute ->
+                Log.i(
+                    TAG,
+                    "connect: relay resolver picked role=${relayRoute.role} " +
+                        "url=${relayRoute.relay?.url}",
+                )
+            }
            if (targetUrl != null) {
                connectToUrlOnMainPath(targetUrl)
            } else {
@@ -358,6 +390,41 @@ class ConnectionManager(
        }
    }

+    /**
+     * Replace an ordinary scheduled reconnect with an immediate attempt.
+     *
+     * Foregrounding the app or opening Relay status is an explicit signal that
+     * the route may be usable again, so exponential/slow-poll backoff should not
+     * make the user wait. A server-issued 429 is different: retrying early would
+     * extend the server block, so that protected backoff is never overridden.
+     */
+    fun reconnectNowIfAllowed(url: String): Boolean {
+        val rateLimitActive = isRelayRateLimitBackoffActive(
+            rateLimitBackoffUntilMs,
+            SystemClock.elapsedRealtime(),
+        )
+        if (!canOverrideScheduledRelayReconnect(
+                state = _connectionState.value,
+                backoffWaiting = reconnectBackoffWaiting,
+                rateLimitBackoffActive = rateLimitActive,
+            )
+        ) {
+            if (rateLimitActive) {
+                Log.i(TAG, "reconnectNowIfAllowed: preserving rate-limit backoff")
+            }
+            return false
+        }
+        reconnectJob?.cancel()
+        reconnectJob = null
+        reconnectBackoffWaiting = false
+        // connectToUrlOnMainPath suppresses duplicate opens while the manager is
+        // Reconnecting. Move to the honest idle state before starting the fresh
+        // resolver/open path; the ViewModel's grace window prevents UI flicker.
+        _connectionState.value = ConnectionState.Disconnected
+        connect(url)
+        return true
+    }
+
    /**
     * Same as [connect] but bypasses the resolver — used by the network-
     * change callback when we've already picked a winner and just want to
@@ -368,6 +435,7 @@ class ConnectionManager(
    private fun connectToUrlOnMainPath(
        url: String,
        replaceReason: String = "Relay socket replaced",
+        preserveReconnectBackoff: Boolean = false,
    ) {
        val isInsecure = url.startsWith("ws://") && !url.startsWith("wss://")
        if (isInsecure && !_insecureMode.value) {
@@ -377,7 +445,9 @@ class ConnectionManager(
                severity = DiagnosticSeverity.Error,
                title = context?.getString(R.string.conn_diag_socket_blocked) ?: "Relay socket blocked",
                detail = "ws:// is disabled",
-                url = url,
+                operation = "Open Relay WebSocket",
+                configuredUrl = url,
+                suggestion = "Use wss:// or explicitly allow plain ws:// for a trusted LAN or VPN.",
            )
            return
        }
@@ -388,7 +458,9 @@ class ConnectionManager(
                severity = DiagnosticSeverity.Error,
                title = context?.getString(R.string.conn_diag_url_invalid) ?: "Relay socket URL invalid",
                detail = "URL must start with ws:// or wss://",
-                url = url,
+                operation = "Open Relay WebSocket",
+                configuredUrl = url,
+                suggestion = "Edit or re-pair the Relay route with a ws:// or wss:// URL.",
            )
            return
        }
@@ -398,6 +470,14 @@ class ConnectionManager(
        // hits the HTTP root and comes back as 404 Not Found during the
        // upgrade handshake. We still accept an explicit path if present.
        val normalized = normalizeRelayUrl(url)
+        if (isRelayRateLimitBackoffActive(
+                rateLimitBackoffUntilMs,
+                SystemClock.elapsedRealtime(),
+            )
+        ) {
+            Log.i(TAG, "connect: preserving active rate-limit backoff")
+            return
+        }
        val existingState = _connectionState.value
        if (serverUrl == normalized &&
            (existingState == ConnectionState.Connecting ||
@@ -416,20 +496,28 @@ class ConnectionManager(
                category = DiagnosticCategory.Relay,
                severity = DiagnosticSeverity.Warning,
                title = context?.getString(R.string.conn_diag_opening_insecure) ?: "Opening insecure relay socket",
-                url = normalized,
+                operation = "Open Relay WebSocket",
+                configuredUrl = url,
+                requestUrl = normalized,
            )
        } else {
            DiagnosticsLog.record(
                category = DiagnosticCategory.Relay,
                severity = DiagnosticSeverity.Info,
                title = context?.getString(R.string.conn_diag_opening_socket) ?: "Opening relay socket",
-                url = normalized,
+                operation = "Open Relay WebSocket",
+                configuredUrl = url,
+                requestUrl = normalized,
            )
        }

        serverUrl = normalized
        shouldReconnect = true
-        reconnectAttempt = 0
+        if (preserveReconnectBackoff) {
+            reconnectState.beginAutomaticRouteSwap(normalized)
+        } else {
+            reconnectState.beginExplicitConnect(normalized)
+        }
        doConnect(normalized, previousSocket, replaceReason)
    }

@@ -445,9 +533,12 @@ class ConnectionManager(
     * Wraps the DataStore read in a 1-second timeout; if DataStore stalls
     * for any reason we don't block the connect loop forever.
     */
-    suspend fun resolveBestEndpoint(): EndpointCandidate? = resolveBestEndpointSafe()
+    suspend fun resolveBestEndpoint(): EndpointCandidate? =
+        resolveBestEndpointSafe(EndpointSurface.Standard)

-    private suspend fun resolveBestEndpointSafe(): EndpointCandidate? {
+    private suspend fun resolveBestEndpointSafe(
+        surface: EndpointSurface,
+    ): EndpointCandidate? {
        val resolver = endpointResolver ?: return null
        val ctx = context ?: return null

@@ -486,14 +577,14 @@ class ConnectionManager(
            }
            if (preferred != null) {
                // Single-element list still respects the 2s probe gate.
-                val winner = resolver.resolve(listOf(preferred))
+                val winner = resolver.resolve(listOf(preferred), surface)
                if (winner != null) return winner
                Log.i(TAG, "manualRoleOverride=$preferredRole not reachable — " +
                    "falling through to strict-priority resolve")
            }
        }

-        return resolver.resolve(endpoints)
+        return resolver.resolve(endpoints, surface)
    }

    /**
@@ -521,7 +612,8 @@ class ConnectionManager(
    suspend fun probeAndReconnectNow(): EndpointCandidate? {
        endpointResolver?.clearCache()
        val current = serverUrl
-        val resolved = resolveBestEndpointSafe()
+        val resolved = resolveBestEndpointSafe(EndpointSurface.Standard)
+        val relayResolved = resolveBestEndpointSafe(EndpointSurface.Relay)
        if (resolved == null && _connectionState.value == ConnectionState.Connected) {
            // Transient probe miss while the relay socket is demonstrably up
            // — keep the live route published rather than downgrading every
@@ -529,7 +621,8 @@ class ConnectionManager(
            return _activeEndpoint.value
        }
        _activeEndpoint.value = resolved
-        val targetUrl = resolved?.relay?.url ?: current ?: return resolved
+        if (relayResolved != null) activeRelayEndpoint = relayResolved
+        val targetUrl = relayResolved?.relay?.url ?: current ?: return resolved
        val normalizedTarget = normalizeRelayUrl(targetUrl)
        // Reconnect when the winner changed, and also when the socket is
        // stale/disconnected on the same winner. The latter makes the
@@ -566,7 +659,7 @@ class ConnectionManager(
     */
    suspend fun refreshActiveEndpoint(clearProbeCache: Boolean = false): EndpointCandidate? {
        if (clearProbeCache) endpointResolver?.clearCache()
-        val resolved = resolveBestEndpointSafe()
+        val resolved = resolveBestEndpointSafe(EndpointSurface.Standard)
        if (resolved == null && _connectionState.value == ConnectionState.Connected) {
            // Transient probe miss while the relay socket is demonstrably up
            // (slow resume, mid-handoff blip) — keep publishing the live
@@ -590,9 +683,9 @@ class ConnectionManager(

    fun getManualRoleOverride(): String? = _manualRoleOverride.value

-    private fun markActiveEndpointUnreachable(reason: String) {
-        val active = _activeEndpoint.value ?: return
-        endpointResolver?.markUnreachable(active)
+    private fun markActiveRelayEndpointUnreachable(reason: String) {
+        val active = activeRelayEndpoint ?: return
+        endpointResolver?.markUnreachable(active, EndpointSurface.Relay)
        Log.i(TAG, "marked endpoint role=${active.role} unreachable ($reason)")
    }

@@ -615,9 +708,9 @@ class ConnectionManager(
            // Tailscale's tun churns onAvailable repeatedly — coalesces into a
            // single cache wipe + re-probe instead of one per event. onLost
            // manages its own cache (clear + markUnreachable) and passes false.
-            if (wipeCache) endpointResolver?.clearCache()
+            if (wipeCache) endpointResolver.clearCache()
            val current = serverUrl
-            val resolved = resolveBestEndpointSafe()
+            val resolved = resolveBestEndpointSafe(EndpointSurface.Standard)
            if (resolved == null) {
                // Hysteresis for the AUTOMATIC (network-callback) path. A
                // transient cold-route probe miss must NOT null the published
@@ -662,11 +755,34 @@ class ConnectionManager(
            // (connectToUrlOnMainPath force-sets shouldReconnect = true, so
            // the swap path never re-checked it.)
            if (!shouldReconnect) return@launch
-            val relayUrl = resolved.relay?.url?.takeIf { it.isNotBlank() } ?: return@launch
+            val relayResolved = resolveBestEndpointSafe(EndpointSurface.Relay)
+            if (relayResolved != null) activeRelayEndpoint = relayResolved
+            val relayUrl = relayResolved?.relay?.url?.takeIf { it.isNotBlank() }
+                ?: return@launch
+            if (isRelayRateLimitBackoffActive(
+                    rateLimitBackoffUntilMs,
+                    SystemClock.elapsedRealtime(),
+                )
+            ) {
+                // Keep publishing the newly resolved standard/Relay routes, but
+                // leave the protected retry job intact. It will resolve the
+                // latest Relay winner again when the server cooldown expires.
+                Log.i(TAG, "network change: preserving rate-limit retry job")
+                return@launch
+            }
            val normalizedNew = normalizeRelayUrl(relayUrl)
            if (normalizedNew != current) {
                Log.i(TAG, "network change: swapping $current → $normalizedNew")
-                connectToUrlOnMainPath(relayUrl, closeReason)
+                if (reconnectBackoffWaiting) {
+                    reconnectJob?.cancel()
+                    reconnectJob = null
+                    reconnectBackoffWaiting = false
+                }
+                connectToUrlOnMainPath(
+                    relayUrl,
+                    closeReason,
+                    preserveReconnectBackoff = true,
+                )
            } else if (_connectionState.value == ConnectionState.Disconnected &&
                reconnectGate()
            ) {
@@ -708,7 +824,9 @@ class ConnectionManager(
                    Log.i(TAG, "network loss sustained past grace — marking active endpoint unreachable and resolving fallback")
                    sustainedLossDeclared = true
                    endpointResolver?.clearCache()
-                    markActiveEndpointUnreachable("network lost (sustained)")
+                    _activeEndpoint.value?.let { active ->
+                        endpointResolver?.markUnreachable(active, EndpointSurface.Standard)
+                    }
                    // wipeCache=false: we just cleared + poisoned the dead route
                    // above; re-wiping inside the job would drop that negative
                    // entry and let the dead route win the resolve again.
@@ -762,6 +880,11 @@ class ConnectionManager(

    fun disconnect() {
        shouldReconnect = false
+        reconnectJob?.cancel()
+        reconnectJob = null
+        reconnectBackoffWaiting = false
+        rateLimitBackoffUntilMs = 0L
+        lastUpgradeResponseCode = null
        DiagnosticsLog.record(
            category = DiagnosticCategory.Relay,
            severity = DiagnosticSeverity.Info,
@@ -779,6 +902,8 @@ class ConnectionManager(
        // the ViewModel on the next connection load.
        _manualRoleOverride.value = null
        _activeEndpoint.value = null
+        activeRelayEndpoint = null
+        reconnectState.reset()
    }

    fun shutdown() {
@@ -815,19 +940,28 @@ class ConnectionManager(
        url: String,
        previousSocketToClose: WebSocket? = null,
        replaceReason: String = "Relay socket replaced",
+        scheduledReconnect: Boolean = false,
    ) {
+        if (isRelayRateLimitBackoffActive(
+                rateLimitBackoffUntilMs,
+                SystemClock.elapsedRealtime(),
+            )
+        ) {
+            Log.i(TAG, "doConnect: preserving active rate-limit backoff")
+            return
+        }
        val existingState = _connectionState.value
        if (previousSocketToClose == null &&
            serverUrl == url &&
            (existingState == ConnectionState.Connecting ||
                existingState == ConnectionState.Connected ||
-                existingState == ConnectionState.Reconnecting)
+                (existingState == ConnectionState.Reconnecting && !scheduledReconnect))
        ) {
            Log.i(TAG, "doConnect: already ${existingState.name.lowercase()} to $url — skipping duplicate open")
            return
        }

-        _connectionState.value = if (reconnectAttempt > 0) {
+        _connectionState.value = if (reconnectState.reconnectAttempt > 0) {
            ConnectionState.Reconnecting
        } else {
            ConnectionState.Connecting
@@ -863,7 +997,9 @@ class ConnectionManager(
                severity = DiagnosticSeverity.Error,
                title = "Invalid relay URL",
                detail = "The relay address could not be parsed; re-pair to refresh it.",
-                url = url,
+                operation = "Build Relay WebSocket request",
+                configuredUrl = url,
+                suggestion = "Edit or re-pair the Relay route to replace the invalid address.",
            )
            authenticated = false
            _connectionState.value = ConnectionState.Disconnected
@@ -884,16 +1020,20 @@ class ConnectionManager(
                    webSocket.cancel()
                    return
                }
-                reconnectAttempt = 0
+                reconnectState.connected(url)
+                reconnectJob?.cancel()
+                reconnectJob = null
+                reconnectBackoffWaiting = false
+                rateLimitBackoffUntilMs = 0L
                lastUpgradeResponseCode = null
-                consecutiveSocketFailures = 0
                _connectionState.value = ConnectionState.Connected
                Log.i(TAG, "onOpen: WSS handshake complete ($url)")
                DiagnosticsLog.record(
                    category = DiagnosticCategory.Relay,
                    severity = DiagnosticSeverity.Info,
                    title = context?.getString(R.string.conn_diag_connected) ?: "Relay socket connected",
-                    url = url,
+                    operation = "Relay WebSocket handshake",
+                    requestUrl = url,
                )

                // TOFU: record the peer cert fingerprint if we don't have one
@@ -954,7 +1094,9 @@ class ConnectionManager(
                    severity = DiagnosticSeverity.Warning,
                    title = context?.getString(R.string.conn_diag_closed) ?: "Relay socket closed",
                    detail = "code=$code reason=$reason",
-                    url = url,
+                    operation = "Relay WebSocket session",
+                    requestUrl = url,
+                    suggestion = if (code == 1000) null else "Check the Relay server logs for the matching close code and reason.",
                )
                authenticated = false
                _connectionState.value = ConnectionState.Disconnected
@@ -977,20 +1119,24 @@ class ConnectionManager(
                        t.message,
                        code?.let { "HTTP $it" },
                    ).joinToString(": "),
-                    url = url,
+                    operation = "Relay WebSocket handshake",
+                    requestUrl = url,
+                    suggestion = code?.let {
+                        NetworkDiagnosticGuidance.forHttpStatus(it, "Relay")
+                    } ?: NetworkDiagnosticGuidance.forThrowable(t, "Relay"),
                )
                lastUpgradeResponseCode = code
                if (response == null) {
                    // Transport-level failure (no HTTP upgrade response): on a
                    // remote (Tailscale) link the first handshake can fail cold.
-                    // Don't evict the only working route from the shared resolver
-                    // on a single blip — wait for it to repeat. A genuinely
-                    // sustained network loss is handled separately by onLost.
-                    consecutiveSocketFailures++
-                    if (consecutiveSocketFailures >= MARK_UNREACHABLE_AFTER_FAILURES) {
-                        markActiveEndpointUnreachable("socket failure x$consecutiveSocketFailures")
+                    // Don't evict this Relay surface on a single blip — wait
+                    // for the same socket URL to fail again. Standard route
+                    // health is separate and is never poisoned here.
+                    val failureCount = reconnectState.recordSocketFailure(url)
+                    if (failureCount >= MARK_UNREACHABLE_AFTER_FAILURES) {
+                        markActiveRelayEndpointUnreachable("socket failure x$failureCount")
                    } else {
-                        Log.i(TAG, "relay socket failure $consecutiveSocketFailures/$MARK_UNREACHABLE_AFTER_FAILURES — not yet poisoning route")
+                        Log.i(TAG, "relay socket failure $failureCount/$MARK_UNREACHABLE_AFTER_FAILURES — not yet poisoning route")
                    }
                }
                authenticated = false
@@ -1029,7 +1175,12 @@ class ConnectionManager(
        }

        val url = serverUrl ?: return
-        reconnectAttempt++
+        val reconnectAttempt = reconnectState.nextReconnectAttempt()
+        // Keep the socket lifecycle visibly in-flight for the whole backoff
+        // window. Callers such as reconnectIfStale() treat Disconnected as an
+        // invitation to call connect() again; leaving this state Disconnected
+        // let screen entry restart both the route resolve and the retry counter.
+        _connectionState.value = ConnectionState.Reconnecting

        // Server-issued 429 means we're IP-banned — keep retrying at our
        // normal exponential cadence and we'll re-fill the ban bucket on
@@ -1040,6 +1191,7 @@ class ConnectionManager(
            // block window instead of re-filling the ban bucket at our normal
            // cadence.
            lastUpgradeResponseCode == 429 -> {
+                rateLimitBackoffUntilMs = SystemClock.elapsedRealtime() + RATE_LIMIT_BACKOFF_MS
                Log.i(TAG, "scheduleReconnect: rate-limited (429) — backing off ${RATE_LIMIT_BACKOFF_MS}ms")
                DiagnosticsLog.record(
                    category = DiagnosticCategory.Relay,
@@ -1064,8 +1216,9 @@ class ConnectionManager(
                SLOW_POLL_BACKOFF_MS
            }
            else -> {
-                val ms = (BASE_BACKOFF_MS * (1L shl minOf(reconnectAttempt - 1, 4)))
+                val capMs = (BASE_BACKOFF_MS * (1L shl minOf(reconnectAttempt - 1, 4)))
                    .coerceAtMost(MAX_BACKOFF_MS)
+                val ms = fullJitterDelayMs(capMs, reconnectJitterUnit())
                DiagnosticsLog.record(
                    category = DiagnosticCategory.Relay,
                    severity = DiagnosticSeverity.Info,
@@ -1077,13 +1230,16 @@ class ConnectionManager(
            }
        }

-        scope.launch {
+        reconnectJob?.cancel()
+        reconnectBackoffWaiting = true
+        val scheduledJob = scope.launch {
            delay(backoffMs)
+            reconnectBackoffWaiting = false
            // Re-check the gate after the backoff — by the time the delay
            // expires, auth state may have changed (e.g., user hit Revoke
            // during the retry window).
            if (shouldReconnect && reconnectGate()) {
-                val resolved = resolveBestEndpointSafe()
+                val resolved = resolveBestEndpointSafe(EndpointSurface.Relay)
                val targetUrl = resolved?.relay?.url
                if (resolved != null) {
                    // Mirror scheduleNetworkReResolve: clear the sustained-loss
@@ -1092,24 +1248,28 @@ class ConnectionManager(
                    // in onLost's grace job but can be cleared on EITHER success
                    // edge — network-callback or relay-timer.)
                    sustainedLossDeclared = false
-                    _activeEndpoint.value = resolved
-                } else if (sustainedLossDeclared || _activeEndpoint.value == null) {
-                    // Same hysteresis as scheduleNetworkReResolve: a transient
-                    // miss during a relay reconnect must not flip every effective
-                    // URL back to the dead saved host. Keep the last-known route;
-                    // we fall through to doConnect(url) and retry it with backoff.
-                    _activeEndpoint.value = null
+                    activeRelayEndpoint = resolved
                }
                if (targetUrl != null && normalizeRelayUrl(targetUrl) != url) {
                    Log.i(TAG, "scheduleReconnect: switching $url → ${normalizeRelayUrl(targetUrl)}")
-                    connectToUrlOnMainPath(targetUrl)
+                    connectToUrlOnMainPath(
+                        targetUrl,
+                        preserveReconnectBackoff = true,
+                    )
                } else {
-                    doConnect(url)
+                    doConnect(url, scheduledReconnect = true)
                }
            } else if (!reconnectGate()) {
                Log.i(TAG, "scheduleReconnect: gate turned false during backoff — aborting retry")
                _connectionState.value = ConnectionState.Disconnected
            }
        }
+        reconnectJob = scheduledJob
+        scheduledJob.invokeOnCompletion {
+            if (reconnectJob === scheduledJob) {
+                reconnectJob = null
+                reconnectBackoffWaiting = false
+            }
+        }
    }
 }
@@ -7,10 +7,12 @@ import com.hermesandroid.relay.auth.PairedDeviceInfo
 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 kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.contentOrNull
@@ -59,6 +61,10 @@ class RelayHttpClient(

    companion object {
        private const val TAG = "RelayHttpClient"
+        const val MAX_MODEL_CAPABILITY_ROWS = 64
+        private const val MAX_MODEL_CAPABILITY_PROVIDER_CHARS = 128
+        private const val MAX_MODEL_CAPABILITY_MODEL_CHARS = 512
+        private const val MAX_MODEL_CAPABILITY_PROFILE_CHARS = 128
        private val sessionsJson = Json {
            ignoreUnknownKeys = true
            isLenient = true
@@ -710,6 +716,37 @@ class RelayHttpClient(
        @SerialName("age_seconds") val ageSeconds: Int? = null,
    )

+    @Serializable
+    data class ModelCapabilityRequestRow(
+        val provider: String,
+        val model: String,
+    )
+
+    @Serializable
+    data class ModelCapabilitiesRequest(
+        @SerialName("schema_version") val schemaVersion: Int = 1,
+        val profile: String? = null,
+        val refresh: Boolean = false,
+        val models: List<ModelCapabilityRequestRow>,
+    )
+
+    @Serializable
+    data class ModelCapabilityRow(
+        val provider: String,
+        val model: String,
+        val reasoning: Boolean? = null,
+        @SerialName("reasoning_efforts") val reasoningEfforts: List<String> = emptyList(),
+        @SerialName("reasoning_efforts_exact") val reasoningEffortsExact: Boolean = false,
+        val source: String = "",
+    )
+
+    @Serializable
+    data class ModelCapabilitiesResponse(
+        @SerialName("schema_version") val schemaVersion: Int = 1,
+        @SerialName("contract_version") val contractVersion: String = "",
+        val capabilities: List<ModelCapabilityRow> = emptyList(),
+    )
+
    /** Fetch the installed plugin/protocol/profile capability contract. */
    suspend fun fetchRelayInfo(): Result<RelayInfo?> = withContext(Dispatchers.IO) {
        val relayUrl = relayUrlProvider()?.trim().orEmpty()
@@ -743,6 +780,64 @@ class RelayHttpClient(
        }
    }

+    /** Optional provider/model reasoning overlay; 404 and no pairing are fail-soft. */
+    suspend fun fetchModelCapabilities(
+        models: List<ModelCapabilityRequestRow>,
+        profile: String? = null,
+        refresh: Boolean = false,
+    ): Result<ModelCapabilitiesResponse?> = withContext(Dispatchers.IO) {
+        val boundedModels = models
+            .asSequence()
+            .map {
+                ModelCapabilityRequestRow(
+                    it.provider.trim().take(MAX_MODEL_CAPABILITY_PROVIDER_CHARS),
+                    it.model.trim().take(MAX_MODEL_CAPABILITY_MODEL_CHARS),
+                )
+            }
+            .filter { it.provider.isNotEmpty() && it.model.isNotEmpty() }
+            .distinct()
+            .take(MAX_MODEL_CAPABILITY_ROWS)
+            .toList()
+        if (boundedModels.isEmpty()) return@withContext Result.success(null)
+        val relayUrl = relayUrlProvider()?.trim().orEmpty()
+        val token = sessionTokenProvider()
+        if (relayUrl.isEmpty() || token.isNullOrBlank()) return@withContext Result.success(null)
+        val base = relayUrl
+            .replace(Regex("^wss://", RegexOption.IGNORE_CASE), "https://")
+            .replace(Regex("^ws://", RegexOption.IGNORE_CASE), "http://")
+            .trimEnd('/')
+        val url = runCatching { "$base/relay/model-capabilities".toHttpUrl() }.getOrElse {
+            return@withContext Result.success(null)
+        }
+        val payload = ModelCapabilitiesRequest(
+            profile = profile?.trim()?.take(MAX_MODEL_CAPABILITY_PROFILE_CHARS)
+                ?.takeIf { it.isNotEmpty() },
+            refresh = refresh,
+            models = boundedModels,
+        )
+        val request = Request.Builder()
+            .url(url)
+            .post(sessionsJson.encodeToString(payload).toRequestBody("application/json".toMediaType()))
+            .header("Authorization", "Bearer $token")
+            .header("Accept", "application/json")
+            .build()
+        try {
+            okHttpClient.newBuilder().callTimeout(4, java.util.concurrent.TimeUnit.SECONDS).build()
+                .newCall(request).execute().use { response ->
+                    if (response.code == 404) return@withContext Result.success(null)
+                    if (!response.isSuccessful) return@withContext Result.failure(IOException("HTTP ${response.code}"))
+                    val body = response.body?.string().orEmpty()
+                    val parsed = body.takeIf { it.isNotBlank() }?.let {
+                        sessionsJson.decodeFromString(ModelCapabilitiesResponse.serializer(), it)
+                    }
+                    if (parsed?.schemaVersion != 1) Result.success(null) else Result.success(parsed)
+                }
+        } catch (e: Exception) {
+            Log.w(TAG, "fetchModelCapabilities failed: ${e.message}")
+            Result.failure(e)
+        }
+    }
+
    /**
     * Ask the relay whether a newer plugin release is available — it compares its
     * installed version against the latest `plugin-v*` GitHub release (cached an
@@ -1139,6 +1234,7 @@ class RelayHttpClient(
        logSuccess: Boolean = true,
    ): Result<RelayHealth> = withContext(Dispatchers.IO) {
        val trimmed = relayUrl.trim()
+        val operation = "Relay health probe before WebSocket connection"
        if (trimmed.isEmpty()) {
            return@withContext Result.failure(
                IllegalArgumentException("Relay URL is empty")
@@ -1159,7 +1255,9 @@ class RelayHttpClient(
                severity = DiagnosticSeverity.Error,
                title = context?.getString(R.string.http_diag_url_invalid) ?: "Relay URL invalid",
                detail = e.message,
-                url = relayUrl,
+                operation = operation,
+                configuredUrl = relayUrl,
+                suggestion = "Enter a Relay URL beginning with ws:// or wss://.",
            )
            return@withContext Result.failure(
                IOException("Invalid relay URL: ${e.message}")
@@ -1180,6 +1278,7 @@ class RelayHttpClient(
            .get()
            .header("Accept", "application/json")
            .build()
+        val requestUrl = request.url.toString()

        try {
            fastClient.newCall(request).execute().use { response ->
@@ -1189,8 +1288,11 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                        detail = "HTTP ${response.code}",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
+                        suggestion = NetworkDiagnosticGuidance.forHttpStatus(response.code, "Relay"),
                    )
                    return@withContext Result.failure(
                        IOException("Relay responded HTTP ${response.code}")
@@ -1203,8 +1305,11 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                        detail = "Empty response",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
+                        suggestion = "Verify this route points to a Hermes-Relay server and inspect its logs.",
                    )
                    return@withContext Result.failure(
                        IOException("Relay returned an empty response")
@@ -1220,8 +1325,11 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                        detail = "Non-JSON response",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
+                        suggestion = "Verify this route points to a Hermes-Relay server rather than another HTTP service.",
                    )
                    return@withContext Result.failure(
                        IOException("Relay returned non-JSON: ${e.message ?: "parse error"}")
@@ -1234,8 +1342,11 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                        detail = "status=${status ?: "missing"}",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
+                        suggestion = "Check the Relay service health and server logs.",
                    )
                    return@withContext Result.failure(
                        IOException("Relay reports status=${status ?: "missing"} (expected 'ok')")
@@ -1248,8 +1359,11 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                        detail = "Missing version field",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
+                        suggestion = "Verify this route points to a current Hermes-Relay server.",
                    )
                    return@withContext Result.failure(
                        IOException("Response doesn't look like a hermes-relay — missing 'version' field")
@@ -1265,7 +1379,9 @@ class RelayHttpClient(
                        severity = DiagnosticSeverity.Info,
                        title = context?.getString(R.string.http_diag_health_ok) ?: "Relay health ok",
                        detail = "version=$version clients=$clients sessions=$sessions",
-                        url = httpBase,
+                        operation = operation,
+                        configuredUrl = trimmed,
+                        requestUrl = requestUrl,
                        elapsedMs = System.currentTimeMillis() - startedAtMs,
                    )
                }
@@ -1278,8 +1394,11 @@ class RelayHttpClient(
                severity = DiagnosticSeverity.Warning,
                title = context?.getString(R.string.http_diag_health_timeout) ?: "Relay health timeout",
                detail = "No HTTP response in 3s",
-                url = httpBase,
+                operation = operation,
+                configuredUrl = trimmed,
+                requestUrl = requestUrl,
                elapsedMs = System.currentTimeMillis() - startedAtMs,
+                suggestion = NetworkDiagnosticGuidance.forThrowable(e, "Relay"),
            )
            Result.failure(IOException("Relay is not responding (3s timeout)"))
        } catch (e: java.net.ConnectException) {
@@ -1289,8 +1408,11 @@ class RelayHttpClient(
                severity = DiagnosticSeverity.Error,
                title = context?.getString(R.string.http_diag_conn_refused) ?: "Relay connection refused",
                detail = e.message,
-                url = httpBase,
+                operation = operation,
+                configuredUrl = trimmed,
+                requestUrl = requestUrl,
                elapsedMs = System.currentTimeMillis() - startedAtMs,
+                suggestion = NetworkDiagnosticGuidance.forThrowable(e, "Relay"),
            )
            Result.failure(IOException("Connection refused — is the relay running on this URL?"))
        } catch (e: IOException) {
@@ -1300,8 +1422,11 @@ class RelayHttpClient(
                severity = DiagnosticSeverity.Warning,
                title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                detail = e.message ?: "Network error",
-                url = httpBase,
+                operation = operation,
+                configuredUrl = trimmed,
+                requestUrl = requestUrl,
                elapsedMs = System.currentTimeMillis() - startedAtMs,
+                suggestion = NetworkDiagnosticGuidance.forThrowable(e, "Relay"),
            )
            Result.failure(IOException("Network error: ${e.message ?: "unreachable"}"))
        } catch (e: Exception) {
@@ -1311,8 +1436,11 @@ class RelayHttpClient(
                severity = DiagnosticSeverity.Error,
                title = context?.getString(R.string.http_diag_health_failed) ?: "Relay health failed",
                detail = e.message ?: e.javaClass.simpleName,
-                url = httpBase,
+                operation = operation,
+                configuredUrl = trimmed,
+                requestUrl = requestUrl,
                elapsedMs = System.currentTimeMillis() - startedAtMs,
+                suggestion = NetworkDiagnosticGuidance.forThrowable(e, "Relay"),
            )
            Result.failure(e)
        }
@@ -0,0 +1,61 @@
+package com.hermesandroid.relay.network.relay
+
+/**
+ * Route-aware retry state for the Relay WebSocket.
+ *
+ * Automatic LAN/Tailscale fallback keeps the accumulated reconnect attempt so
+ * swapping URLs cannot restart exponential backoff. Socket-failure streaks are
+ * scoped to one URL, so failures on different roles cannot combine and poison
+ * the newly selected route.
+ */
+internal class RelayReconnectState {
+    @Volatile
+    var reconnectAttempt: Int = 0
+        private set
+
+    private var socketFailureRoute: String? = null
+    private var consecutiveSocketFailures: Int = 0
+
+    @Synchronized
+    fun beginExplicitConnect(route: String) {
+        reconnectAttempt = 0
+        resetSocketFailures(route)
+    }
+
+    @Synchronized
+    fun beginAutomaticRouteSwap(route: String) {
+        resetSocketFailures(route)
+    }
+
+    @Synchronized
+    fun nextReconnectAttempt(): Int {
+        reconnectAttempt++
+        return reconnectAttempt
+    }
+
+    @Synchronized
+    fun recordSocketFailure(route: String): Int {
+        if (socketFailureRoute != route) {
+            resetSocketFailures(route)
+        }
+        consecutiveSocketFailures++
+        return consecutiveSocketFailures
+    }
+
+    @Synchronized
+    fun connected(route: String) {
+        reconnectAttempt = 0
+        resetSocketFailures(route)
+    }
+
+    @Synchronized
+    fun reset() {
+        reconnectAttempt = 0
+        resetSocketFailures(null)
+    }
+
+    private fun resetSocketFailures(route: String?) {
+        socketFailureRoute = route
+        consecutiveSocketFailures = 0
+    }
+}
@@ -98,6 +98,7 @@ class RelayVoiceClient(
    private val webSocketFactory: ((Request, WebSocketListener) -> WebSocket)? = null,
    private val realtimeResumeRetryIntervalMs: Long = REALTIME_RESUME_RETRY_INTERVAL_MS,
    private val realtimeResumeRetryWindowMs: Long = REALTIME_RESUME_RETRY_WINDOW_MS,
+    private val voiceOutputFirstAudioTimeoutMs: Long = VOICE_OUTPUT_FIRST_AUDIO_TIMEOUT_MS,
 ) {

    companion object {
@@ -108,6 +109,7 @@ class RelayVoiceClient(
        private val WAV_AUDIO = "audio/wav".toMediaType()
        private val OCTET_STREAM = "application/octet-stream".toMediaType()
        private const val REALTIME_TIMEOUT_MS = 90_000L
+        private const val VOICE_OUTPUT_FIRST_AUDIO_TIMEOUT_MS = 15_000L
        private const val REALTIME_AGENT_IDLE_TIMEOUT_MS = 90_000L
        private const val REALTIME_AGENT_MAX_TURN_MS = 5 * 60_000L
        private const val REALTIME_AGENT_WAIT_SLICE_MS = 1_000L
@@ -867,6 +869,7 @@ class RelayVoiceClient(
        val resumeAttempted = AtomicBoolean(false)
        val routeProbeRequested = AtomicBoolean(false)
        val currentSocket = AtomicReference<WebSocket?>()
+        val firstAudioSeen = AtomicBoolean(false)
        val socketGeneration = AtomicLong(0L)
        val activeSocketGeneration = AtomicLong(0L)
        val lastEventId = AtomicLong(0L)
@@ -980,6 +983,7 @@ class RelayVoiceClient(
                    }
                    onEvent(event)
                    if (event.isAudioDelta) {
+                        firstAudioSeen.set(true)
                        event.audioEventId?.let {
                            lastPlayedAudioEventId.updateAndGet { current -> maxOf(current, it) }
                        }
@@ -1123,6 +1127,15 @@ class RelayVoiceClient(
            onHandoff = onHandoff,
            completeFailure = ::completeFailure,
        )
+        val firstAudioWatchdog = launch {
+            delay(voiceOutputFirstAudioTimeoutMs)
+            if (!completed.get() && !firstAudioSeen.get()) {
+                completeFailure(
+                    "Voice output produced no audio within ${voiceOutputFirstAudioTimeoutMs}ms",
+                )
+                currentSocket.get()?.cancel()
+            }
+        }
        try {
            withTimeout(REALTIME_TIMEOUT_MS) {
                finished.await()
@@ -1132,6 +1145,7 @@ class RelayVoiceClient(
            socket.close(1001, "timeout")
            Result.failure(IOException("Voice output timed out", e))
        } finally {
+            firstAudioWatchdog.cancel()
            routeWatcher?.cancel()
        }
    }
@@ -1278,6 +1292,7 @@ class RelayVoiceClient(
        model: String? = null,
        voice: String? = null,
        sampleRate: Int? = null,
+        finalAnswerOnly: Boolean = false,
        onHandoff: (VoiceHandoffEvent) -> Unit = {},
        turnInputs: kotlinx.coroutines.channels.ReceiveChannel<RealtimeTurnInput>? = null,
        onTurnComplete: (RealtimeVoiceSummary) -> Unit = {},
@@ -1309,6 +1324,7 @@ class RelayVoiceClient(
            model = model,
            voice = voice,
            sampleRate = sampleRate,
+            finalAnswerOnly = finalAnswerOnly,
        )
        if (sessionResult.isFailure) {
            return@withContext Result.failure(sessionResult.exceptionOrNull() ?: IOException("Realtime agent session failed"))
@@ -1822,6 +1838,28 @@ class RelayVoiceClient(
                    if (event.type == "hermes.run.promoted") {
                        longRunningTurn.set(true)
                        Log.i(TAG, "Realtime agent turn marked long-running (run promoted); relaxing idle guard")
+                        if (persistent &&
+                            event.spokenHandoff == false &&
+                            activeTurn.compareAndSet(true, false)
+                        ) {
+                            Log.i(
+                                TAG,
+                                "Realtime agent foreground turn ended at silent background promotion",
+                            )
+                            onTurnComplete(
+                                RealtimeVoiceSummary(
+                                    provider = event.provider ?: session.provider,
+                                    model = event.model ?: session.model,
+                                    voice = event.voice ?: session.voice,
+                                    sampleRate = session.sampleRate,
+                                    audioChunks = audioChunks,
+                                    audioBytes = audioBytes,
+                                    firstAudioMs = event.firstAudioMs,
+                                    responseDoneMs = event.responseDoneMs,
+                                    eventLogPath = event.eventLogPath ?: session.eventLogPath,
+                                )
+                            )
+                        }
                    }
                    if (event.isAudioDelta) {
                        audioChunks += 1
@@ -1847,13 +1885,12 @@ class RelayVoiceClient(
                            responseDoneMs = event.responseDoneMs,
                            eventLogPath = event.eventLogPath ?: session.eventLogPath,
                        )
-                        if (persistent) {
+                        if (persistent && activeTurn.compareAndSet(true, false)) {
                            // Turn boundary, not session boundary: keep the socket
                            // open for the next utterance.
-                            activeTurn.set(false)
                            longRunningTurn.set(false)
                            onTurnComplete(summary)
-                        } else {
+                        } else if (!persistent) {
                            if (claimTerminalSocket(
                                    webSocket,
                                    generation,
@@ -2679,6 +2716,7 @@ class RelayVoiceClient(
        model: String? = null,
        voice: String? = null,
        sampleRate: Int? = null,
+        finalAnswerOnly: Boolean = false,
    ): Result<RealtimeSessionResponse> {
        val body = buildJsonObject {
            putProfile()
@@ -2694,6 +2732,9 @@ class RelayVoiceClient(
            sampleRate?.takeIf { it > 0 }?.let {
                put("sample_rate", JsonPrimitive(it))
            }
+            if (finalAnswerOnly) {
+                put("final_answer_only", JsonPrimitive(true))
+            }
            chatSessionId?.trim()?.takeIf { it.isNotBlank() }?.let {
                put("chat_session_id", JsonPrimitive(it))
            }
@@ -2980,6 +3021,9 @@ class RelayVoiceClient(
                responseDoneMs = (metrics?.get("response_done_ms") as? JsonPrimitive)?.doubleOrNull,
                tier = (obj["tier"] as? JsonPrimitive)?.contentOrNull,
                floor = (obj["floor"] as? JsonPrimitive)?.contentOrNull,
+                spokenHandoff = (obj["spoken_handoff"] as? JsonPrimitive)
+                    ?.contentOrNull
+                    ?.toBooleanStrictOrNull(),
                activeToolName = (obj["active_tool_name"] as? JsonPrimitive)?.contentOrNull,
                completedToolCount = (obj["completed_tool_count"] as? JsonPrimitive)?.intOrNull
                    ?: (obj["tool_count"] as? JsonPrimitive)?.intOrNull,
@@ -3374,6 +3418,7 @@ data class RealtimeVoiceEvent(
    // ADR 33: background-run promotion fields.
    val tier: String? = null,
    val floor: String? = null,
+    val spokenHandoff: Boolean? = null,
    // hermes.run.progress extras — drive the live background-run chip.
    val activeToolName: String? = null,
    val completedToolCount: Int? = null,
@@ -9,6 +9,7 @@ import com.hermesandroid.relay.data.routeAuthority
 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 kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.async
@@ -47,6 +48,16 @@ data class RouteProbeOutcome(
    val atMillis: Long,
 )

+/**
+ * Service whose reachability is being resolved. Standard Hermes surfaces and
+ * Relay are intentionally independent: a healthy Dashboard must not vouch for
+ * a dead Relay listener on the same host.
+ */
+enum class EndpointSurface {
+    Standard,
+    Relay,
+}
+
 /**
 * Picks the highest-priority **reachable** [EndpointCandidate] from a
 * per-device list, driven by ADR 24 "Multi-endpoint pairing + network-aware
@@ -124,9 +135,14 @@ class EndpointResolver(
     */
    val probeOutcomes: StateFlow<Map<String, RouteProbeOutcome>> = _probeOutcomes.asStateFlow()

-    private fun recordOutcome(candidate: EndpointCandidate, reachable: Boolean, detail: String?) {
+    private fun recordOutcome(
+        candidate: EndpointCandidate,
+        surface: EndpointSurface,
+        reachable: Boolean,
+        detail: String?,
+    ) {
        _probeOutcomes.update { outcomes ->
-            outcomes + (cacheKey(candidate) to RouteProbeOutcome(
+            outcomes + (cacheKey(candidate, surface) to RouteProbeOutcome(
                reachable = reachable,
                detail = detail,
                atMillis = clock(),
@@ -167,21 +183,44 @@ class EndpointResolver(
        private const val PROBE_TIMEOUT_DETAIL = "No answer (timed out)"

        /**
-         * Stable cache key for a candidate: `"<role>|<primary host>:<port>"`.
+         * Stable cache key for one candidate surface:
+         * `"<surface>|<role>|<surface host>:<port>"`.
         * Roles are preserved case-verbatim (HMAC canonicalization contract)
         * but hostnames are lowercased — two roles pointing at the same
         * host:port share reachability state.
         */
-        internal fun cacheKey(candidate: EndpointCandidate): String =
-            "${candidate.role}|${candidate.routeAuthority() ?: candidate.primaryRouteUrl().orEmpty().lowercase()}"
+        internal fun cacheKey(
+            candidate: EndpointCandidate,
+            surface: EndpointSurface = EndpointSurface.Standard,
+        ): String {
+            val authority = when (surface) {
+                EndpointSurface.Standard ->
+                    candidate.routeAuthority() ?: candidate.primaryRouteUrl().orEmpty().lowercase()
+                EndpointSurface.Relay ->
+                    routeAuthority(candidate.relay?.url).orEmpty()
+            }
+            return "${surface.name.lowercase()}|${candidate.role}|$authority"
+        }
+
+        private fun routeAuthority(rawUrl: String?): String? {
+            val candidate = rawUrl?.trim()?.takeIf { it.isNotBlank() } ?: return null
+            val httpUrl = when {
+                candidate.startsWith("ws://", ignoreCase = true) ->
+                    "http://${candidate.substringAfter("://")}"
+                candidate.startsWith("wss://", ignoreCase = true) ->
+                    "https://${candidate.substringAfter("://")}"
+                else -> candidate
+            }
+            return httpUrl.toHttpUrlOrNull()?.let { url -> "${url.host}:${url.port}" }
+        }
    }

    /**
     * Run the resolver against [candidates].
     *
     *  1. Group by `priority` ascending.
-     *  2. For each priority group, race a HEAD /health probe against every
-     *     candidate in the group (2 s per candidate). First 2xx wins; ties
+     *  2. For each priority group, race the selected surface's health probe
+     *     against every candidate in the group. First 2xx wins; ties
     *     broken by whichever response lands first.
     *  3. If the entire group is unreachable, fall through to the next
     *     priority group.
@@ -193,37 +232,42 @@ class EndpointResolver(
     * its tier). An empty [candidates] list returns null immediately without
     * touching the network.
     */
-    suspend fun resolve(candidates: List<EndpointCandidate>): EndpointCandidate? {
-        if (candidates.isEmpty()) return null
+    suspend fun resolve(
+        candidates: List<EndpointCandidate>,
+        surface: EndpointSurface = EndpointSurface.Standard,
+    ): EndpointCandidate? {
+        val eligible = candidates.filter { probeTarget(it, surface) != null }
+        if (eligible.isEmpty()) return null

        // Strict priority: sort ascending so priority-0 lands first. Grouping
        // preserves emitted order within a priority class (DNS SRV parity).
-        val groups = candidates.groupBy { it.priority }.toSortedMap()
+        val groups = eligible.groupBy { it.priority }.toSortedMap()

        for ((priority, group) in groups) {
            Log.d(TAG, "probing priority=$priority group (size=${group.size})")
-            val winner = raceGroup(group)
+            val winner = raceGroup(group, surface)
            if (winner != null) {
+                val winnerUrl = probeTarget(winner, surface)?.baseUrl
                Log.i(TAG, "resolve winner: role=${winner.role} " +
-                    "route=${winner.primaryRouteUrl()} priority=$priority")
+                    "surface=$surface route=$winnerUrl priority=$priority")
                DiagnosticsLog.record(
                    category = DiagnosticCategory.Endpoint,
                    severity = DiagnosticSeverity.Info,
                    title = context?.getString(R.string.endpoint_diag_selected) ?: "Endpoint selected",
                    detail = "priority=$priority",
                    endpointRole = winner.role,
-                    url = winner.primaryRouteUrl(),
+                    url = winnerUrl,
                )
                return winner
            }
        }

-        Log.w(TAG, "resolve: no reachable candidate across ${candidates.size} record(s)")
+        Log.w(TAG, "resolve: no reachable $surface candidate across ${eligible.size} record(s)")
        DiagnosticsLog.record(
            category = DiagnosticCategory.Endpoint,
            severity = DiagnosticSeverity.Warning,
            title = context?.getString(R.string.endpoint_diag_no_reachable) ?: "No reachable endpoint",
-            detail = "${candidates.size} configured route(s) failed health probes",
+            detail = "${eligible.size} configured $surface route(s) failed health probes",
        )
        return null
    }
@@ -237,17 +281,20 @@ class EndpointResolver(
     * for "first 2xx wins" so latency matters. The losing probes' results
     * still land in the cache, though, so the next call benefits.
     */
-    private suspend fun raceGroup(group: List<EndpointCandidate>): EndpointCandidate? {
+    private suspend fun raceGroup(
+        group: List<EndpointCandidate>,
+        surface: EndpointSurface,
+    ): EndpointCandidate? {
        if (group.isEmpty()) return null
        if (group.size == 1) {
            val only = group.first()
-            return if (isReachable(only)) only else null
+            return if (isReachable(only, surface)) only else null
        }

        // Fast-path: any cached-reachable candidate wins immediately without
        // touching the network.
        for (candidate in group) {
-            val cached = probeCache[cacheKey(candidate)]
+            val cached = probeCache[cacheKey(candidate, surface)]
            if (cached != null && cached.expiresAt > clock() && cached.reachable) {
                return candidate
            }
@@ -256,7 +303,7 @@ class EndpointResolver(
        return coroutineScope {
            val deferred = group.map { candidate ->
                async(Dispatchers.IO) {
-                    if (isReachable(candidate)) candidate else null
+                    if (isReachable(candidate, surface)) candidate else null
                }
            }
            // Collect results in arrival order: iterate through awaitAll +
@@ -276,8 +323,11 @@ class EndpointResolver(
     * [probeCache] first; on miss or expiry, runs a HEAD /health probe and
     * records the result.
     */
-    private suspend fun isReachable(candidate: EndpointCandidate): Boolean {
-        val key = cacheKey(candidate)
+    private suspend fun isReachable(
+        candidate: EndpointCandidate,
+        surface: EndpointSurface,
+    ): Boolean {
+        val key = cacheKey(candidate, surface)
        val now = clock()
        val cached = probeCache[key]
        if (cached != null && cached.expiresAt > now) {
@@ -285,7 +335,7 @@ class EndpointResolver(
            return cached.reachable
        }

-        val reachable = probe(candidate)
+        val reachable = probe(candidate, surface)
        val ttl = if (reachable) CACHE_TTL_MS else NEGATIVE_CACHE_TTL_MS
        probeCache[key] = CacheEntry(expiresAt = now + ttl, reachable = reachable)
        return reachable
@@ -299,9 +349,16 @@ class EndpointResolver(
     * Returns false on any failure (timeout, I/O, non-2xx, invalid URL).
     * We never raise: a bad record shouldn't crash the connect loop.
     */
-    private suspend fun probe(candidate: EndpointCandidate): Boolean {
+    private suspend fun probe(
+        candidate: EndpointCandidate,
+        surface: EndpointSurface,
+    ): Boolean {
        val startedAtMs = clock()
-        val target = probeTarget(candidate)
+        val operation = when (surface) {
+            EndpointSurface.Standard -> "Dashboard or API route health probe"
+            EndpointSurface.Relay -> "Relay route health probe"
+        }
+        val target = probeTarget(candidate, surface)
        val url = target?.requestUrl?.toHttpUrlOrNull()
            ?: run {
                Log.w(TAG, "probe: invalid url for role=${candidate.role}")
@@ -310,10 +367,12 @@ class EndpointResolver(
                    severity = DiagnosticSeverity.Error,
                    title = context?.getString(R.string.endpoint_diag_probe_invalid) ?: "Endpoint probe invalid",
                    detail = "No valid Dashboard, API, or Relay URL",
+                    operation = operation,
                    endpointRole = candidate.role,
-                    url = candidate.primaryRouteUrl(),
+                    configuredUrl = candidate.primaryRouteUrl(),
+                    suggestion = "Edit or re-pair this route so it contains a valid service URL.",
                )
-                recordOutcome(candidate, reachable = false, detail = "Invalid route URL")
+                recordOutcome(candidate, surface, reachable = false, detail = "Invalid route URL")
                return false
            }
        val fastClient = httpClient.newBuilder()
@@ -345,12 +404,20 @@ class EndpointResolver(
                            severity = if (ok) DiagnosticSeverity.Info else DiagnosticSeverity.Warning,
                            title = probeTitle,
                            detail = if (ok) null else "HTTP ${resp.code}",
+                            operation = operation,
                            endpointRole = candidate.role,
-                            url = target.baseUrl,
+                            configuredUrl = target.baseUrl,
+                            requestUrl = target.requestUrl,
                            elapsedMs = clock() - startedAtMs,
+                            suggestion = if (ok) {
+                                null
+                            } else {
+                                NetworkDiagnosticGuidance.forHttpStatus(resp.code, surface.diagnosticTarget())
+                            },
                        )
                        recordOutcome(
                            candidate,
+                            surface,
                            reachable = ok,
                            detail = if (ok) null else "HTTP ${resp.code} from ${target.path}",
                        )
@@ -362,11 +429,14 @@ class EndpointResolver(
                        severity = DiagnosticSeverity.Warning,
                        title = context?.getString(R.string.endpoint_diag_probe_timeout) ?: "Endpoint probe timeout",
                        detail = "No ${target.path} response in ${PROBE_TIMEOUT_MS}ms",
+                        operation = operation,
                        endpointRole = candidate.role,
-                        url = target.baseUrl,
+                        configuredUrl = target.baseUrl,
+                        requestUrl = target.requestUrl,
                        elapsedMs = clock() - startedAtMs,
+                        suggestion = "Check network routing or firewall rules between this device and ${surface.diagnosticTarget()}.",
                    )
-                    recordOutcome(candidate, reachable = false, detail = PROBE_TIMEOUT_DETAIL)
+                    recordOutcome(candidate, surface, reachable = false, detail = PROBE_TIMEOUT_DETAIL)
                    false
                }
            } catch (_: TimeoutCancellationException) {
@@ -375,11 +445,14 @@ class EndpointResolver(
                    severity = DiagnosticSeverity.Warning,
                    title = context?.getString(R.string.endpoint_diag_probe_timeout) ?: "Endpoint probe timeout",
                    detail = "No ${target.path} response in ${PROBE_TIMEOUT_MS}ms",
+                    operation = operation,
                    endpointRole = candidate.role,
-                    url = target.baseUrl,
+                    configuredUrl = target.baseUrl,
+                    requestUrl = target.requestUrl,
                    elapsedMs = clock() - startedAtMs,
+                    suggestion = "Check network routing or firewall rules between this device and ${surface.diagnosticTarget()}.",
                )
-                recordOutcome(candidate, reachable = false, detail = PROBE_TIMEOUT_DETAIL)
+                recordOutcome(candidate, surface, reachable = false, detail = PROBE_TIMEOUT_DETAIL)
                false
            } catch (e: Exception) {
                Log.d(TAG, "probe failed role=${candidate.role} " +
@@ -388,19 +461,28 @@ class EndpointResolver(
                    category = DiagnosticCategory.Endpoint,
                    severity = DiagnosticSeverity.Warning,
                    title = context?.getString(R.string.endpoint_diag_probe_failed) ?: "Endpoint probe failed",
-                    detail = e.javaClass.simpleName,
+                    detail = humanProbeFailure(e),
+                    operation = operation,
                    endpointRole = candidate.role,
-                    url = target.baseUrl,
+                    configuredUrl = target.baseUrl,
+                    requestUrl = target.requestUrl,
                    elapsedMs = clock() - startedAtMs,
+                    suggestion = NetworkDiagnosticGuidance.forThrowable(e, surface.diagnosticTarget()),
                )
-                recordOutcome(candidate, reachable = false, detail = humanProbeFailure(e))
+                recordOutcome(candidate, surface, reachable = false, detail = humanProbeFailure(e))
                false
            }
        }
    }

    /** Choose the standard Dashboard/Gateway surface first when advertised. */
-    private fun probeTarget(candidate: EndpointCandidate): ProbeTarget? {
+    private fun probeTarget(
+        candidate: EndpointCandidate,
+        surface: EndpointSurface,
+    ): ProbeTarget? {
+        if (surface == EndpointSurface.Relay) {
+            return relayProbeTarget(candidate)
+        }
        candidate.dashboard?.url
            ?.trim()
            ?.trimEnd('/')
@@ -421,6 +503,10 @@ class EndpointResolver(
            )
        }

+        return relayProbeTarget(candidate)
+    }
+
+    private fun relayProbeTarget(candidate: EndpointCandidate): ProbeTarget? {
        candidate.relay?.url
            ?.trim()
            ?.trimEnd('/')
@@ -458,6 +544,11 @@ class EndpointResolver(
        else -> e.javaClass.simpleName
    }

+    private fun EndpointSurface.diagnosticTarget(): String = when (this) {
+        EndpointSurface.Standard -> "Dashboard or API server"
+        EndpointSurface.Relay -> "Relay"
+    }
+
    /**
     * Mark [candidate] unreachable without re-probing. Called from
     * `ConnectionManager`'s `NetworkCallback.onLost` so the next resolve()
@@ -467,13 +558,21 @@ class EndpointResolver(
     * transition can skip the known-dead active route without suppressing a
     * valid fallback for the whole positive cache window.
     */
-    fun markUnreachable(candidate: EndpointCandidate) {
-        val key = cacheKey(candidate)
+    fun markUnreachable(
+        candidate: EndpointCandidate,
+        surface: EndpointSurface = EndpointSurface.Standard,
+    ) {
+        val key = cacheKey(candidate, surface)
        probeCache[key] = CacheEntry(
            expiresAt = clock() + NEGATIVE_CACHE_TTL_MS,
            reachable = false,
        )
-        recordOutcome(candidate, reachable = false, detail = "Network changed — assumed offline")
+        recordOutcome(
+            candidate,
+            surface,
+            reachable = false,
+            detail = "Network changed — assumed offline",
+        )
    }

    /**
@@ -61,7 +61,7 @@ object HermesLanDiscovery {
            .callTimeout(PROBE_TIMEOUT_MS * 2, TimeUnit.MILLISECONDS)
            .build()

-        coroutineScope {
+        val results = coroutineScope {
            val semaphore = Semaphore(MAX_CONCURRENT_PROBES)
            hosts.map { host ->
                async {
@@ -79,6 +79,8 @@ object HermesLanDiscovery {
                        .thenBy { it.host },
                )
        }
+        Log.d(TAG, "scan complete hosts=${hosts.size} matches=${results.size}")
+        results
    }

    private fun probeHost(
@@ -133,8 +135,7 @@ object HermesLanDiscovery {
                val body = response.body.string().take(2_048)
                expectedBody(body, contentType)
            }
-        } catch (e: Exception) {
-            Log.d(TAG, "probe failed url=$url type=${e.javaClass.simpleName}")
+        } catch (_: Exception) {
            false
        }
    }
@@ -65,13 +65,14 @@ object ProfileApiUrlResolver {
        val dedicated = resolveForConnection(profileApiUrl, base)
        if (dedicated != null) return dedicated

-        val profile = selectedProfileName
-            ?.trim()
-            ?.takeIf { it.isNotBlank() && !it.equals("default", ignoreCase = true) }
-            ?: return base
-        val isKnownMultiplexProfile = gatewayMode.equals("multiplex", ignoreCase = true) &&
-            servedProfiles.any { it.equals(profile, ignoreCase = false) }
-        if (!isKnownMultiplexProfile) return base
+        val profile = selectedProfileName?.trim() ?: return base
+        if (!usesMultiplexProfileKey(
+                profileApiUrl = profileApiUrl,
+                selectedProfileName = profile,
+                gatewayMode = gatewayMode,
+                servedProfiles = servedProfiles,
+            )
+        ) return base

        val root = base?.toHttpUrlOrNull() ?: return base
        return root.newBuilder()
@@ -82,6 +83,27 @@ object ProfileApiUrlResolver {
            .trimEnd('/')
    }

+    /**
+     * A profile-specific credential is required only for the positively
+     * identified shared `/p/<profile>` mirror. Dedicated profile APIs retain
+     * the connection credential contract, while default/legacy/unknown routes
+     * stay on the root client.
+     */
+    fun usesMultiplexProfileKey(
+        profileApiUrl: String?,
+        selectedProfileName: String?,
+        gatewayMode: String?,
+        servedProfiles: Collection<String>,
+    ): Boolean {
+        if (normalize(profileApiUrl) != null) return false
+        val profile = selectedProfileName
+            ?.trim()
+            ?.takeIf { it.isNotBlank() && !it.equals("default", ignoreCase = true) }
+            ?: return false
+        return gatewayMode.equals("multiplex", ignoreCase = true) &&
+            servedProfiles.any { it == profile }
+    }
+
    private fun isLocalBindHost(host: String): Boolean {
        return when (host.lowercase().trim('[', ']')) {
            "localhost", "127.0.0.1", "0.0.0.0", "::1", "::" -> true
@@ -0,0 +1,13 @@
+package com.hermesandroid.relay.network.shared
+
+import kotlin.random.Random
+
+/** Full-jitter retry delay in the inclusive range 0..[capMs]. */
+internal fun fullJitterDelayMs(
+    capMs: Long,
+    unit: Double = Random.nextDouble(),
+): Long {
+    if (capMs <= 0L) return 0L
+    val boundedUnit = unit.coerceIn(0.0, Math.nextDown(1.0))
+    return (boundedUnit * (capMs + 1.0)).toLong().coerceAtMost(capMs)
+}
@@ -90,12 +90,9 @@ class ChatHandler {
        // Fallback form (no relay): `MEDIA:/absolute/path` — relay wasn't
        //   reachable when the tool fired, so we render an "unavailable"
        //   placeholder instead of attempting a fetch.
-        private val mediaRelayRegex = Regex("""MEDIA:hermes-relay://([A-Za-z0-9_-]+)""")
-        // `/.+?` (not `/\S+`) so absolute paths containing spaces — e.g.
-        // `MEDIA:/mnt/media/Coralee Adshade/undressher.jpg` — still match. The
-        // trailing `\s*$` trims any trailing whitespace; non-greedy keeps the
-        // capture to the path. OkHttp re-encodes the space for /media/by-path.
-        private val mediaBarePathRegex = Regex("""^\s*MEDIA:(/.+?)\s*$""")
+        private val mediaRelayPayloadRegex = Regex("""^hermes-relay://([A-Za-z0-9_-]+)$""")
+        private val mediaMarkerPrefixRegex = Regex("MEDIA:")
+        private val windowsAbsoluteMediaPathRegex = Regex("""^[A-Za-z]:[\\/].+""")
        // Rich card marker — single line, full JSON object payload.
        //
        // Agents emit:
@@ -188,6 +185,7 @@ class ChatHandler {
     * post-stream finalize reconciliation pass.
     */
    private var mediaLineBuffer = StringBuilder()
+    private var mediaFenceDelimiter: String? = null
    private val dispatchedMediaMarkers = mutableSetOf<String>()

    /**
@@ -218,8 +216,14 @@ class ChatHandler {
     */
    private val activeAnnotationTools = mutableMapOf<String, String>()

-    private val _messages = MutableStateFlow<List<ChatMessage>>(emptyList())
-    val messages: StateFlow<List<ChatMessage>> = _messages.asStateFlow()
+    // All Chat and Voice transcript publications pass through this invariant
+    // boundary. A caller may address a row by its mutable server/domain id or
+    // its retained client uiKey, but Compose must never observe both aliases.
+    private val _messages = RenderedMessageState(emptyList())
+    val messages: StateFlow<List<ChatMessage>> = _messages.flow
+
+    private fun ChatMessage.matchesIdentity(reference: String): Boolean =
+        id == reference || uiKey == reference

    /**
     * Latest gateway `status.update` lifecycle line for the in-flight turn
@@ -320,47 +324,54 @@ class ChatHandler {
        fun boolField(name: String): Boolean? = (payload[name] as? JsonPrimitive)?.booleanOrNull
        val toolName = textField("tool_name", "tool", "name") ?: "unknown"
        val callId = textField("call_id", "tool_call_id") ?: toolName
+        // The caller owns one client placeholder id for the whole Relay stream.
+        // message.started can replace that domain id with the server id while
+        // uiKey deliberately retains the client id. Resolve the current domain
+        // id before every event so the tail keeps mutating the same visible row.
+        val currentMessageId = _messages.value.findLast {
+            it.matchesIdentity(messageId)
+        }?.id ?: messageId

        when (envelope.event) {
            "message.started" -> {
                val msgObj = payload["message"] as? JsonObject
                val serverMsgId = (msgObj?.get("id") as? JsonPrimitive)?.contentOrNull
-                if (!serverMsgId.isNullOrBlank()) replaceMessageId(messageId, serverMsgId)
+                if (!serverMsgId.isNullOrBlank()) replaceMessageId(currentMessageId, serverMsgId)
            }
            "assistant.delta" -> {
-                textField("delta", "content", "text")?.let { onTextDelta(messageId, it) }
+                textField("delta", "content", "text")?.let { onTextDelta(currentMessageId, it) }
            }
            "tool.progress" -> {
                textField("delta", "thinking_delta", "thinking", "text", "message")?.let {
-                    onThinkingDelta(messageId, it)
+                    onThinkingDelta(currentMessageId, it)
                }
            }
-            "tool.pending", "tool.started" -> onToolCallStart(messageId, callId, toolName)
-            "tool.completed" -> onToolCallComplete(messageId, callId, textField("result_preview", "summary", "message"))
-            "tool.failed" -> onToolCallFailed(messageId, callId, textField("error", "message") ?: "Tool failed")
+            "tool.pending", "tool.started" -> onToolCallStart(currentMessageId, callId, toolName)
+            "tool.completed" -> onToolCallComplete(currentMessageId, callId, textField("result_preview", "summary", "message"))
+            "tool.failed" -> onToolCallFailed(currentMessageId, callId, textField("error", "message") ?: "Tool failed")
            "memory.updated", "skill.loaded" -> {
                val label = when (envelope.event) {
                    "memory.updated" -> "Memory"
                    else -> "Skill"
                }
-                addMessageBadges(messageId, listOf(label))
+                addMessageBadges(currentMessageId, listOf(label))
            }
            "artifact.created" -> {
-                addMessageBadges(messageId, listOf("Artifact"))
+                addMessageBadges(currentMessageId, listOf("Artifact"))
                textField("url", "path", "preview", "title")?.takeIf { it.isNotBlank() }?.let {
-                    onThinkingDelta(messageId, "Artifact: $it")
+                    onThinkingDelta(currentMessageId, "Artifact: $it")
                }
            }
            "assistant.completed" -> {
                if (boolField("interrupted") == true) {
                    onStreamError("Response interrupted")
                } else {
-                    onTurnComplete(messageId)
+                    onTurnComplete(currentMessageId)
                }
            }
-            "run.completed", "done" -> onStreamComplete(messageId)
+            "run.completed", "done" -> onStreamComplete(currentMessageId)
            "error" -> {
-                addMessageBadges(messageId, listOf("Error"))
+                addMessageBadges(currentMessageId, listOf("Error"))
                onStreamError(textField("message", "error") ?: "Unknown error")
            }
            "session.created", "run.started" -> Unit
@@ -372,6 +383,7 @@ class ChatHandler {

    fun addUserMessage(message: ChatMessage) {
        _messages.update { list ->
+            if (list.any { it.uiKey == message.uiKey }) return@update list
            (list + message).let { if (it.size > MAX_MESSAGES) it.drop(it.size - MAX_MESSAGES) else it }
        }
    }
@@ -384,7 +396,7 @@ class ChatHandler {
     */
    fun updateDeliveryStatus(messageId: String, status: MessageDeliveryStatus) {
        _messages.update { list ->
-            list.map { if (it.id == messageId) it.copy(deliveryStatus = status) else it }
+            list.map { if (it.matchesIdentity(messageId)) it.copy(deliveryStatus = status) else it }
        }
    }

@@ -392,7 +404,7 @@ class ChatHandler {
    fun setBackgroundTask(messageId: String, task: BackgroundTaskState) {
        _messages.update { list ->
            list.map { message ->
-                if (message.id == messageId) message.copy(backgroundTask = task) else message
+                if (message.matchesIdentity(messageId)) message.copy(backgroundTask = task) else message
            }
        }
    }
@@ -404,7 +416,7 @@ class ChatHandler {
    ) {
        _messages.update { list ->
            list.map { message ->
-                if (message.id == messageId && message.backgroundTask != null) {
+                if (message.matchesIdentity(messageId) && message.backgroundTask != null) {
                    message.copy(backgroundTask = transform(message.backgroundTask))
                } else {
                    message
@@ -485,7 +497,7 @@ class ChatHandler {
     */
    fun appendAskCardMessage(messageId: String, card: HermesCard) {
        _messages.update { list ->
-            if (list.any { it.id == messageId }) return@update list
+            if (list.any { it.matchesIdentity(messageId) }) return@update list
            val msg = ChatMessage(
                id = messageId,
                role = MessageRole.ASSISTANT,
@@ -507,7 +519,7 @@ class ChatHandler {
     */
    fun truncateMessagesFrom(messageId: String) {
        _messages.update { list ->
-            val idx = list.indexOfFirst { it.id == messageId }
+            val idx = list.indexOfFirst { it.matchesIdentity(messageId) }
            if (idx < 0) list else list.take(idx)
        }
    }
@@ -515,7 +527,7 @@ class ChatHandler {
    fun replaceMessageContent(messageId: String, content: String) {
        _messages.update { messages ->
            messages.map { message ->
-                if (message.id == messageId) {
+                if (message.matchesIdentity(messageId)) {
                    message.copy(content = content)
                } else {
                    message
@@ -535,8 +547,9 @@ class ChatHandler {
        content: String,
    ) {
        _messages.update { messages ->
-            val interim = messages.firstOrNull { it.id == interimMessageId } ?: return@update messages
-            val current = messages.firstOrNull { it.id == currentMessageId }
+            val interim = messages.firstOrNull { it.matchesIdentity(interimMessageId) }
+                ?: return@update messages
+            val current = messages.firstOrNull { it.matchesIdentity(currentMessageId) }
            val mergedTools = (interim.toolCalls + current?.toolCalls.orEmpty())
                .distinctBy { it.id ?: "${it.name}:${it.startedAt}" }
            val merged = interim.copy(
@@ -555,14 +568,18 @@ class ChatHandler {
                backgroundTask = current?.backgroundTask ?: interim.backgroundTask,
            )
            messages
-                .filterNot { it.id == currentMessageId && currentMessageId != interimMessageId }
-                .map { if (it.id == interimMessageId) merged else it }
+                .filterNot {
+                    current != null &&
+                        current.uiKey != interim.uiKey &&
+                        it.matchesIdentity(currentMessageId)
+                }
+                .map { if (it.matchesIdentity(interimMessageId)) merged else it }
        }
    }

    /** Remove a provisional client-side message that never became a real turn. */
    fun removeMessage(messageId: String) {
-        _messages.update { messages -> messages.filterNot { it.id == messageId } }
+        _messages.update { messages -> messages.filterNot { it.matchesIdentity(messageId) } }
    }

    /**
@@ -744,7 +761,7 @@ class ChatHandler {
        _messages.update { messages ->
            var changed = false
            val mapped = messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    changed = true
                    // A realtimeTurn trace is attached ONLY for provider-only
                    // (non-Hermes-backed) turns — Hermes-backed ones leave it
@@ -942,6 +959,7 @@ class ChatHandler {
    fun addPlaceholderMessage(message: ChatMessage) {
        _isStreaming.value = true
        _messages.update { list ->
+            if (list.any { it.uiKey == message.uiKey }) return@update list
            (list + message).let { if (it.size > MAX_MESSAGES) it.drop(it.size - MAX_MESSAGES) else it }
        }
    }
@@ -957,11 +975,17 @@ class ChatHandler {
    fun restoreInFlightTurn(
        checkpoint: ChatTurnCheckpoint,
        upstreamAssistantText: String? = null,
+        corrections: List<String> = emptyList(),
    ) {
        val user = checkpoint.user
        val assistant = checkpoint.assistant
        val upstreamText = upstreamAssistantText.orEmpty()
-        val currentAssistant = _messages.value.lastOrNull { it.id == assistant.id }
+        // A history poll may already have adopted the server id while the
+        // checkpoint still names the original client identity. They are one
+        // logical row, resolved through either side of that alias.
+        val currentAssistant = _messages.value.lastOrNull {
+            it.matchesIdentity(assistant.id) && it.role == MessageRole.ASSISTANT
+        }
        val restoredContent = listOf(
            assistant.content,
            upstreamText,
@@ -1043,7 +1067,8 @@ class ChatHandler {
            ?.takeIf { it.isNotEmpty() }
            ?: checkpointMoaReferences
        val restoredAssistant = ChatMessage(
-            id = assistant.id,
+            id = currentAssistant?.id ?: assistant.id,
+            uiKey = currentAssistant?.uiKey ?: assistant.id,
            role = MessageRole.ASSISTANT,
            content = restoredContent,
            timestamp = assistant.timestamp,
@@ -1070,10 +1095,12 @@ class ChatHandler {

        activeAgentName = restoredAssistant.agentName ?: activeAgentName
        _messages.update { current ->
-            val withoutOldAssistant = current.filterNot { it.id == assistant.id }
+            val withoutOldAssistant = current.filterNot {
+                it.matchesIdentity(assistant.id) && it.role == MessageRole.ASSISTANT
+            }
            val users = withoutOldAssistant.filter { it.role == MessageRole.USER }
            val positionalUser = users.getOrNull(checkpoint.priorUserMessageCount)
-            val hasUser = withoutOldAssistant.any { it.id == user.id } ||
+            val hasUser = withoutOldAssistant.any { it.matchesIdentity(user.id) } ||
                positionalUser?.content?.trim() == user.content.trim()
            val withUser = if (hasUser) {
                withoutOldAssistant
@@ -1085,13 +1112,53 @@ class ChatHandler {
                    timestamp = user.timestamp,
                )
            }
-            val insertBeforeAsk = withUser.indexOfFirst {
+            // Newer gateways retain the original prompt in inflight.user and
+            // expose every accepted active-turn redirect separately. Restore
+            // those corrections as ordinary user bubbles before the assistant
+            // row. Consume matching already-present rows first so repeated
+            // resume/checkpoint passes cannot duplicate them.
+            val originalUserIndex = withUser.indexOfFirst { it.matchesIdentity(user.id) }
+                .takeIf { it >= 0 }
+                ?: withUser.indexOfFirst {
+                    it.role == MessageRole.USER && it.content.trim() == user.content.trim()
+                }
+            val existingAfterOriginal = withUser
+                .drop((originalUserIndex + 1).coerceAtLeast(0))
+                .filter { it.role == MessageRole.USER }
+                .map { it.content.trim() }
+                .toMutableList()
+            val restoredCorrections = corrections
+                .map { it.trim() }
+                .filter { it.isNotBlank() }
+                .mapIndexedNotNull { index, correction ->
+                    val existingIndex = existingAfterOriginal.indexOf(correction)
+                    if (existingIndex >= 0) {
+                        existingAfterOriginal.removeAt(existingIndex)
+                        null
+                    } else {
+                        ChatMessage(
+                            id = "${user.id}-correction-${index + 1}",
+                            role = MessageRole.USER,
+                            content = correction,
+                            timestamp = user.timestamp + index + 1L,
+                        )
+                    }
+                }
+            val firstAskIndex = withUser.indexOfFirst {
+                it.clientOnly && it.id.startsWith("ask-")
+            }
+            val withCorrections = if (firstAskIndex >= 0) {
+                withUser.toMutableList().apply { addAll(firstAskIndex, restoredCorrections) }
+            } else {
+                withUser + restoredCorrections
+            }
+            val insertBeforeAsk = withCorrections.indexOfFirst {
                it.clientOnly && it.id.startsWith("ask-")
            }
            val restored = if (insertBeforeAsk >= 0) {
-                withUser.toMutableList().apply { add(insertBeforeAsk, restoredAssistant) }
+                withCorrections.toMutableList().apply { add(insertBeforeAsk, restoredAssistant) }
            } else {
-                withUser + restoredAssistant
+                withCorrections + restoredAssistant
            }
            restored.let { list ->
                if (list.size > MAX_MESSAGES) list.drop(list.size - MAX_MESSAGES) else list
@@ -1107,12 +1174,14 @@ class ChatHandler {
        // Drop any pending line buffers / dedupe state so a fresh session
        // doesn't inherit leftovers from the previous one.
        mediaLineBuffer.clear()
+        mediaFenceDelimiter = null
        dispatchedMediaMarkers.clear()
        annotationLineBuffer.clear()
        activeAnnotationTools.clear()
        cardLineBuffer.clear()
        dispatchedCardMarkers.clear()
        subagentLabels.clear()
+        subagentIds.clear()
    }

    /**
@@ -1163,7 +1232,7 @@ class ChatHandler {
    fun replaceMessageId(oldId: String, newId: String) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == oldId && msg.content.isBlank() && msg.isStreaming) {
+                if (msg.matchesIdentity(oldId) && msg.content.isBlank() && msg.isStreaming) {
                    msg.copy(id = newId)
                } else msg
            }
@@ -1186,7 +1255,7 @@ class ChatHandler {
    fun mutateMessage(messageId: String, transform: (ChatMessage) -> ChatMessage) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId) transform(msg) else msg
+                if (msg.matchesIdentity(messageId)) transform(msg) else msg
            }
        }
    }
@@ -1223,6 +1292,14 @@ class ChatHandler {
        // so we can attach results back to the originating assistant message's ToolCall
        val toolResults = items.filter { it.role == "tool" }
            .associateBy { it.toolCallId }
+        // A reconnect/rejoin history response can repeat a persisted message row.
+        // Chat's LazyColumn renders domain ids as stable keys (via ChatMessage.uiKey),
+        // so allowing both copies through would crash Compose before either copy
+        // could be reconciled. A domain id identifies one persisted message: retain
+        // its first transcript position while adopting the latest repeated snapshot.
+        // Rows without ids remain independent, and tool/hidden rows keep their
+        // separate handling above/below.
+        val renderedItems = coalesceRenderedHistoryItems(items)

        // Accumulator for media markers we find in loaded content — fired AFTER
        // the wholesale `_messages.value = ...` assignment so the ViewModel's
@@ -1240,8 +1317,8 @@ class ChatHandler {
        // silently misses those rows, so a gateway turn's tokens/badges survived
        // only if a content match happened to cover them. See
        // [reconcileLiveIdsToServer].
-        val serverItemIds = items.mapNotNullTo(HashSet()) { it.id }
-        val idRemap = reconcileLiveIdsToServer(items, serverItemIds)
+        val serverItemIds = renderedItems.mapNotNullTo(HashSet()) { it.id }
+        val idRemap = reconcileLiveIdsToServer(renderedItems, serverItemIds)

        // Carry CLIENT-ONLY enrichment forward across the reload, keyed by the
        // RECONCILED message id. The server transcript (MessageItem) rebuilds
@@ -1278,7 +1355,7 @@ class ChatHandler {
        // clientOnly bubbles (same exchange, pre-sync copy).
        val syncedRealtimeTurnContents = mutableSetOf<String>()

-        val loaded = items.mapNotNull { item ->
+        val loaded = renderedItems.mapNotNull { item ->
            val displayKind = item.displayKind?.trim()?.lowercase()
            if (displayKind == "hidden") return@mapNotNull null
            val role = when {
@@ -1540,6 +1617,34 @@ class ChatHandler {
        }
    }

+    /**
+     * Collapse replayed visible history rows by their authoritative message id.
+     *
+     * Replacing the value at its first-seen slot preserves transcript ordering;
+     * the last repeated value wins so a later, more complete snapshot is not lost.
+     * Null ids cannot be proven identical and therefore remain separate rows.
+     */
+    private fun coalesceRenderedHistoryItems(items: List<MessageItem>): List<MessageItem> {
+        val firstSlotById = HashMap<String, Int>()
+        val coalesced = ArrayList<MessageItem>(items.size)
+        for (item in items) {
+            if (renderedRoleOf(item) == null) continue
+            val id = item.id
+            if (id == null) {
+                coalesced += item
+                continue
+            }
+            val existingSlot = firstSlotById[id]
+            if (existingSlot == null) {
+                firstSlotById[id] = coalesced.size
+                coalesced += item
+            } else {
+                coalesced[existingSlot] = item
+            }
+        }
+        return coalesced
+    }
+
    /** One adoptable server row during id reconciliation. `taken` enforces consume-once. */
    private class ReconcileSlot(
        val serverId: String,
@@ -1666,7 +1771,7 @@ class ChatHandler {
        for (line in text.lines()) {
            val t = line.trim()
            if (t.isEmpty()) continue
-            if (mediaRelayRegex.containsMatchIn(t) || mediaBarePathRegex.containsMatchIn(t)) continue
+            if (parseMediaMarkerLine(t).isNotEmpty()) continue
            if (PersistedImageReferenceParser.parse(t).paths.isNotEmpty()) continue
            if (cardMarkerRegex.containsMatchIn(t)) continue
            if (sb.isNotEmpty()) sb.append('\n')
@@ -1683,6 +1788,51 @@ class ChatHandler {
        data class BarePath(val path: String) : MediaMarkerHit
    }

+    /**
+     * Parse one marker-only line using upstream-compatible wrappers and
+     * boundaries. Prose and malformed examples remain ordinary text; a whole
+     * inline-code or emphasis wrapper is accepted, as are adjacent markers,
+     * sentence-final punctuation, POSIX paths, and Windows absolute paths.
+     */
+    private fun parseMediaMarkerLine(line: String): List<MediaMarkerHit> {
+        val trimmed = line.trim()
+        if (trimmed.isEmpty() || trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+            return emptyList()
+        }
+        val starts = mediaMarkerPrefixRegex.findAll(trimmed).map { it.range.first }.toList()
+        if (starts.isEmpty()) return emptyList()
+        val prefix = trimmed.substring(0, starts.first())
+        if (prefix.any { !it.isWhitespace() && it !in "`*_~" }) return emptyList()
+
+        val hits = ArrayList<MediaMarkerHit>(starts.size)
+        for ((index, start) in starts.withIndex()) {
+            val payloadStart = start + "MEDIA:".length
+            val payloadEnd = starts.getOrNull(index + 1) ?: trimmed.length
+            val payload = trimmed.substring(payloadStart, payloadEnd)
+                .trim()
+                .trimEnd { it in "`*_~.,;:)}]" }
+                .trim()
+            if (payload.isEmpty()) return emptyList()
+            val relay = mediaRelayPayloadRegex.matchEntire(payload)
+            when {
+                relay != null -> hits += MediaMarkerHit.RelayToken(relay.groupValues[1])
+                payload.startsWith("/") || windowsAbsoluteMediaPathRegex.matches(payload) ->
+                    hits += MediaMarkerHit.BarePath(payload)
+                else -> return emptyList()
+            }
+        }
+        return hits
+    }
+
+    private fun fenceDelimiter(line: String): String? {
+        val trimmed = line.trimStart()
+        return when {
+            trimmed.startsWith("```") -> "```"
+            trimmed.startsWith("~~~") -> "~~~"
+            else -> null
+        }
+    }
+
    /**
     * Scan loaded (non-streaming) message content line-by-line for media
     * markers, append hits to [out], and return the content with matched
@@ -1695,24 +1845,20 @@ class ChatHandler {
        out: MutableList<Pair<String, MediaMarkerHit>>,
    ): String {
        var cleaned = content
+        var openFence: String? = null
        for (rawLine in content.lines()) {
            val trimmed = rawLine.trim()
            if (trimmed.isEmpty()) continue
-
-            val relayMatch = mediaRelayRegex.find(trimmed)
-            if (relayMatch != null) {
-                out.add(messageId to MediaMarkerHit.RelayToken(relayMatch.groupValues[1]))
-                cleaned = cleaned
-                    .replace("\n$rawLine\n", "\n")
-                    .replace("\n$rawLine", "")
-                    .replace("$rawLine\n", "")
-                    .replace(rawLine, "")
+            val delimiter = fenceDelimiter(rawLine)
+            if (delimiter != null) {
+                openFence = if (openFence == delimiter) null else if (openFence == null) delimiter else openFence
                continue
            }
+            if (openFence != null) continue

-            val bareMatch = mediaBarePathRegex.find(trimmed)
-            if (bareMatch != null) {
-                out.add(messageId to MediaMarkerHit.BarePath(bareMatch.groupValues[1]))
+            val hits = parseMediaMarkerLine(trimmed)
+            if (hits.isNotEmpty()) {
+                hits.forEach { out.add(messageId to it) }
                cleaned = cleaned
                    .replace("\n$rawLine\n", "\n")
                    .replace("\n$rawLine", "")
@@ -1804,6 +1950,37 @@ class ChatHandler {
        }
    }

+    /**
+     * Returns true when structured session history contains tool lifecycle
+     * state that the live transcript did not receive. This is a read-only
+     * preflight for Gateway completion reconciliation: healthy live turns keep
+     * their current StateFlow list and UI identity, while omitted upstream
+     * tool events opt into [loadMessageHistory]. Assistant prose is never
+     * inspected or interpreted here.
+     */
+    fun hasMissingPersistedToolActivity(items: List<MessageItem>): Boolean {
+        val toolResults = items.filter { it.role == "tool" }
+            .associateBy { it.toolCallId }
+        val persistedCalls = coalesceRenderedHistoryItems(items)
+            .asSequence()
+            .filter { it.role == "assistant" }
+            .flatMap { parseToolCallsFromHistory(it.toolCalls, toolResults).asSequence() }
+            .toList()
+        if (persistedCalls.isEmpty()) return false
+
+        val localCalls = _messages.value.flatMap { it.toolCalls }
+        return persistedCalls.any { persisted ->
+            val local = persisted.id?.let { id -> localCalls.firstOrNull { it.id == id } }
+                ?: localCalls.firstOrNull {
+                    it.id == null && it.name == persisted.name && it.args == persisted.args
+                }
+            local == null ||
+                (persisted.isComplete && !local.isComplete) ||
+                (persisted.result != null && persisted.result != local.result) ||
+                (persisted.success != null && persisted.success != local.success)
+        }
+    }
+
    // --- Session management ---

    fun setSessionId(sessionId: String?) {
@@ -1857,6 +2034,8 @@ class ChatHandler {
                // rows (default source). (ADR 12 — Threads surface, slice 1.)
                source = item.source,
                hasModelConfig = item.hasModelConfig,
+                pinned = item.pinned,
+                archived = item.archived,
            )
        }.sortedByDescending { it.activityTimestamp }
        // Preserve the active session's optimistic row when the server list
@@ -1903,6 +2082,26 @@ class ChatHandler {
        }
    }

+    /** Apply an optimistic pin/archive mutation; a failed server write restores the copy. */
+    fun setSessionFlagsLocal(
+        sessionId: String,
+        pinned: Boolean? = null,
+        archived: Boolean? = null,
+    ) {
+        _sessions.update { sessions ->
+            sessions.map { session ->
+                if (session.sessionId == sessionId) {
+                    session.copy(
+                        pinned = pinned ?: session.pinned,
+                        archived = archived ?: session.archived,
+                    )
+                } else {
+                    session
+                }
+            }
+        }
+    }
+
    /**
     * Add a newly created session to the list.
     */
@@ -1938,12 +2137,12 @@ class ChatHandler {

        _messages.update { messages ->
            val existing = messages.findLast {
-                it.id == messageId && it.role == MessageRole.ASSISTANT
+                it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
            }

            if (existing != null) {
                messages.map { msg ->
-                    if (msg.id == messageId) {
+                    if (msg.matchesIdentity(messageId)) {
                        msg.copy(content = msg.content + processedDelta)
                    } else {
                        msg
@@ -2107,6 +2306,18 @@ class ChatHandler {
            val trimmed = line.trim()
            if (trimmed.isEmpty()) continue

+            fenceDelimiter(line)?.let { delimiter ->
+                mediaFenceDelimiter = if (mediaFenceDelimiter == delimiter) {
+                    null
+                } else if (mediaFenceDelimiter == null) {
+                    delimiter
+                } else {
+                    mediaFenceDelimiter
+                }
+                continue
+            }
+            if (mediaFenceDelimiter != null) continue
+
            if (tryDispatchMediaMarker(messageId, trimmed)) {
                stripLineFromContent(messageId, trimmed)
            }
@@ -2176,7 +2387,7 @@ class ChatHandler {

        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    msg.copy(cards = msg.cards + card)
                } else msg
            }
@@ -2202,7 +2413,7 @@ class ChatHandler {

        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id != messageId || msg.role != MessageRole.ASSISTANT) return@map msg
+                if (!msg.matchesIdentity(messageId) || msg.role != MessageRole.ASSISTANT) return@map msg
                var cleaned = msg.content
                var changed = false
                for (rawLine in msg.content.lines()) {
@@ -2236,29 +2447,26 @@ class ChatHandler {
     * Returns true when a marker was matched so the caller can strip the line.
     */
    private fun tryDispatchMediaMarker(messageId: String, line: String): Boolean {
-        val relayMatch = mediaRelayRegex.find(line)
-        if (relayMatch != null) {
-            val token = relayMatch.groupValues[1]
-            val dedupeKey = "$messageId:relay:$token"
-            if (dispatchedMediaMarkers.add(dedupeKey)) {
-                Log.d(TAG, "Media marker (relay): token=$token")
-                onMediaAttachmentRequested(messageId, token)
+        val hits = parseMediaMarkerLine(line)
+        for (hit in hits) {
+            when (hit) {
+                is MediaMarkerHit.RelayToken -> {
+                    val dedupeKey = "$messageId:relay:${hit.token}"
+                    if (dispatchedMediaMarkers.add(dedupeKey)) {
+                        Log.d(TAG, "Media marker (relay): token=${hit.token}")
+                        onMediaAttachmentRequested(messageId, hit.token)
+                    }
+                }
+                is MediaMarkerHit.BarePath -> {
+                    val dedupeKey = "$messageId:bare:${hit.path}"
+                    if (dispatchedMediaMarkers.add(dedupeKey)) {
+                        Log.d(TAG, "Media marker (bare-path): ${hit.path}")
+                        onMediaBarePathRequested(messageId, hit.path)
+                    }
+                }
            }
-            return true
        }
-
-        val bareMatch = mediaBarePathRegex.find(line)
-        if (bareMatch != null) {
-            val path = bareMatch.groupValues[1]
-            val dedupeKey = "$messageId:bare:$path"
-            if (dispatchedMediaMarkers.add(dedupeKey)) {
-                Log.d(TAG, "Media marker (bare-path, unavailable): $path")
-                onMediaBarePathRequested(messageId, path)
-            }
-            return true
-        }
-
-        return false
+        return hits.isNotEmpty()
    }

    /**
@@ -2269,7 +2477,7 @@ class ChatHandler {
    private fun stripLineFromContent(messageId: String, line: String) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    // Remove the line (with surrounding newlines) from content
                    val cleaned = msg.content
                        .replace("\n$line\n", "\n")
@@ -2397,24 +2605,29 @@ class ChatHandler {
        if (mediaLineBuffer.isNotEmpty()) {
            val remaining = mediaLineBuffer.toString().trim()
            mediaLineBuffer.clear()
-            if (remaining.isNotEmpty() && tryDispatchMediaMarker(messageId, remaining)) {
+            if (mediaFenceDelimiter == null && remaining.isNotEmpty() && tryDispatchMediaMarker(messageId, remaining)) {
                stripLineFromContent(messageId, remaining)
            }
        }
+        mediaFenceDelimiter = null

        // Post-stream reconciliation: re-scan the final content for markers
        // that raced with stripLineFromContent during streaming.
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id != messageId || msg.role != MessageRole.ASSISTANT) return@map msg
+                if (!msg.matchesIdentity(messageId) || msg.role != MessageRole.ASSISTANT) return@map msg
                var cleaned = msg.content
                var changed = false
+                var openFence: String? = null
                for (rawLine in msg.content.lines()) {
                    val trimmed = rawLine.trim()
                    if (trimmed.isEmpty()) continue
-                    if (mediaRelayRegex.containsMatchIn(trimmed) ||
-                        mediaBarePathRegex.containsMatchIn(trimmed)
-                    ) {
+                    val delimiter = fenceDelimiter(rawLine)
+                    if (delimiter != null) {
+                        openFence = if (openFence == delimiter) null else if (openFence == null) delimiter else openFence
+                        continue
+                    }
+                    if (openFence == null && parseMediaMarkerLine(trimmed).isNotEmpty()) {
                        tryDispatchMediaMarker(messageId, trimmed)
                        cleaned = cleaned
                            .replace("\n$rawLine\n", "\n")
@@ -2460,7 +2673,7 @@ class ChatHandler {
    private fun finalizeAnnotations(messageId: String) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id != messageId || msg.role != MessageRole.ASSISTANT) return@map msg
+                if (!msg.matchesIdentity(messageId) || msg.role != MessageRole.ASSISTANT) return@map msg

                val existingToolNames = msg.toolCalls.map { it.name }.toSet()
                val newToolCalls = mutableListOf<ToolCall>()
@@ -2543,7 +2756,7 @@ class ChatHandler {
            .take(4)
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    msg.copy(badges = cleaned)
                } else {
                    msg
@@ -2559,7 +2772,7 @@ class ChatHandler {
        if (cleaned.isEmpty()) return
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    msg.copy(badges = (msg.badges + cleaned).distinct().take(4))
                } else {
                    msg
@@ -2593,11 +2806,11 @@ class ChatHandler {
        )
        _messages.update { messages ->
            val target = messages.findLast {
-                it.id == messageId && it.role == MessageRole.ASSISTANT
+                it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
            }
            if (target != null) {
                messages.map { msg ->
-                    if (msg.id == messageId) {
+                    if (msg.matchesIdentity(messageId)) {
                        msg.copy(toolCalls = msg.toolCalls + placeholder)
                    } else {
                        msg
@@ -2621,6 +2834,7 @@ class ChatHandler {
        messageId: String,
        toolCallId: String,
        toolName: String,
+        argsPreview: String? = null,
        runId: String? = null,
        provenance: String? = null,
    ) {
@@ -2628,7 +2842,7 @@ class ChatHandler {

        _messages.update { messages ->
            val target = messages.findLast {
-                it.id == messageId && it.role == MessageRole.ASSISTANT
+                it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
            }
            if (target != null) {
                // Adopt a pending "preparing" placeholder for this name
@@ -2642,12 +2856,13 @@ class ChatHandler {
                        .indexOfFirst { it.isGenerating && !it.isComplete && it.name.isEmpty() }
                        .takeIf { it >= 0 }
                messages.map { msg ->
-                    if (msg.id != messageId) return@map msg
+                    if (!msg.matchesIdentity(messageId)) return@map msg
                    if (genIdx != null) {
                        val calls = msg.toolCalls.toMutableList()
                        calls[genIdx] = calls[genIdx].copy(
                            id = toolCallId,
                            name = toolName,
+                            args = argsPreview ?: calls[genIdx].args,
                            isGenerating = false,
                            // Execution starts now — preparing time isn't runtime.
                            startedAt = System.currentTimeMillis(),
@@ -2660,7 +2875,7 @@ class ChatHandler {
                            toolCalls = msg.toolCalls + ToolCall(
                                id = toolCallId,
                                name = toolName,
-                                args = null,
+                                args = argsPreview,
                                result = null,
                                success = null,
                                isComplete = false,
@@ -2681,7 +2896,7 @@ class ChatHandler {
                        ToolCall(
                            id = toolCallId,
                            name = toolName,
-                            args = null,
+                            args = argsPreview,
                            result = null,
                            success = null,
                            isComplete = false,
@@ -2700,7 +2915,7 @@ class ChatHandler {
    fun onMoaReference(messageId: String, event: GatewayMoaReference) {
        _messages.update { messages ->
            val targetIndex = messages.indexOfLast {
-                it.id == messageId && it.role == MessageRole.ASSISTANT
+                it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
            }
            if (targetIndex < 0) return@update messages
            _isStreaming.value = true
@@ -2743,6 +2958,7 @@ class ChatHandler {
     * [onStreamComplete] / [clearMessages].
     */
    private val subagentLabels = mutableMapOf<Int, String>()
+    private val subagentIds = mutableMapOf<Int, String>()

    /**
     * Apply one gateway `subagent.*` lifecycle event to the streaming
@@ -2758,6 +2974,9 @@ class ChatHandler {
        when (event.phase) {
            GatewaySubagentEvent.Phase.START -> {
                if (label != null) subagentLabels[event.taskIndex] = label
+                event.subagentId?.takeIf(String::isNotBlank)?.let {
+                    subagentIds[event.taskIndex] = it
+                }
            }

            GatewaySubagentEvent.Phase.TOOL -> {
@@ -2772,14 +2991,16 @@ class ChatHandler {
                    isComplete = false,
                    taskIndex = event.taskIndex,
                    taskLabel = laneLabel,
+                    subagentId = event.subagentId?.takeIf(String::isNotBlank)
+                        ?: subagentIds[event.taskIndex],
                )
                _messages.update { messages ->
                    val target = messages.findLast {
-                        it.id == messageId && it.role == MessageRole.ASSISTANT
+                        it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
                    }
                    if (target != null) {
                        messages.map { msg ->
-                            if (msg.id != messageId) return@map msg
+                            if (!msg.matchesIdentity(messageId)) return@map msg
                            val closed = msg.toolCalls.map { call ->
                                if (call.taskIndex == event.taskIndex && !call.isComplete) {
                                    call.copy(
@@ -2811,10 +3032,11 @@ class ChatHandler {
                // "interrupted" lanes never finished — not a success either.
                val failed = event.status == "failed" || event.status == "interrupted"
                val laneLabel = subagentLabels.remove(event.taskIndex) ?: label
+                val subagentId = subagentIds.remove(event.taskIndex) ?: event.subagentId
                val summaryId = "subagent-${event.taskIndex}-${syntheticToolSeq++}"
                _messages.update { messages ->
                    messages.map { msg ->
-                        if (msg.id != messageId || msg.role != MessageRole.ASSISTANT) return@map msg
+                        if (!msg.matchesIdentity(messageId) || msg.role != MessageRole.ASSISTANT) return@map msg
                        val hasLaneCalls = msg.toolCalls.any { it.taskIndex == event.taskIndex }
                        val closed = msg.toolCalls.map { call ->
                            if (call.taskIndex == event.taskIndex && !call.isComplete) {
@@ -2843,6 +3065,7 @@ class ChatHandler {
                                completedAt = System.currentTimeMillis(),
                                taskIndex = event.taskIndex,
                                taskLabel = laneLabel,
+                                subagentId = subagentId,
                            )
                        }
                        msg.copy(toolCalls = withSummary)
@@ -2865,14 +3088,14 @@ class ChatHandler {
        // Snapshot the matching tool call's name BEFORE mutating — we need it
        // to decide whether to emit a phone-action result bubble below.
        val toolName = _messages.value
-            .firstOrNull { it.id == messageId && it.role == MessageRole.ASSISTANT }
+            .firstOrNull { it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT }
            ?.toolCalls
            ?.firstOrNull { it.id == toolCallId }
            ?.name

        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    val updatedCalls = msg.toolCalls.map { call ->
                        if (call.id == toolCallId && !call.isComplete) {
                            call.copy(
@@ -2909,14 +3132,14 @@ class ChatHandler {
        // Snapshot tool name before the update so the phone-action bubble
        // can label the failure correctly.
        val toolName = _messages.value
-            .firstOrNull { it.id == messageId && it.role == MessageRole.ASSISTANT }
+            .firstOrNull { it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT }
            ?.toolCalls
            ?.firstOrNull { it.id == toolCallId }
            ?.name

        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && msg.role == MessageRole.ASSISTANT) {
+                if (msg.matchesIdentity(messageId) && msg.role == MessageRole.ASSISTANT) {
                    val updatedCalls = msg.toolCalls.map { call ->
                        if (call.id == toolCallId && !call.isComplete) {
                            call.copy(
@@ -2949,7 +3172,7 @@ class ChatHandler {
    fun onToolOutputRisk(messageId: String, outputRisk: GatewayToolOutputRisk) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id != messageId || msg.role != MessageRole.ASSISTANT) return@map msg
+                if (!msg.matchesIdentity(messageId) || msg.role != MessageRole.ASSISTANT) return@map msg
                val updatedCalls = msg.toolCalls.map { call ->
                    if (call.id == outputRisk.toolCallId) {
                        call.copy(
@@ -2980,7 +3203,7 @@ class ChatHandler {

        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId) {
+                if (msg.matchesIdentity(messageId)) {
                    msg.copy(isStreaming = false, isThinkingStreaming = false)
                } else {
                    msg
@@ -3009,7 +3232,7 @@ class ChatHandler {
    fun markStopped(messageId: String) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && "Stopped" !in msg.badges) {
+                if (msg.matchesIdentity(messageId) && "Stopped" !in msg.badges) {
                    msg.copy(badges = msg.badges + "Stopped")
                } else {
                    msg
@@ -3036,7 +3259,7 @@ class ChatHandler {
    fun markError(messageId: String) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId && "Error" !in msg.badges) {
+                if (msg.matchesIdentity(messageId) && "Error" !in msg.badges) {
                    msg.copy(badges = msg.badges + "Error", clientOnly = true)
                } else {
                    msg
@@ -3062,7 +3285,7 @@ class ChatHandler {
        _messages.update { messages ->
            messages
                .filterNot { msg ->
-                        msg.id == messageId &&
+                        msg.matchesIdentity(messageId) &&
                        msg.role == MessageRole.ASSISTANT &&
                        msg.toolCalls.isEmpty() &&
                        msg.backgroundTask == null &&
@@ -3070,7 +3293,7 @@ class ChatHandler {
                        (msg.content.isBlank() || isIntentionalSilenceMarker(msg.content))
                }
                .map { msg ->
-                    if (msg.id == messageId || msg.isStreaming) {
+                    if (msg.matchesIdentity(messageId) || msg.isStreaming) {
                        msg.copy(isStreaming = false, isThinkingStreaming = false)
                    } else {
                        msg
@@ -3100,6 +3323,7 @@ class ChatHandler {
            }
        }
        subagentLabels.clear()
+        subagentIds.clear()
    }

    fun onStreamError(message: String) {
@@ -3129,15 +3353,18 @@ class ChatHandler {
            }
        }
        subagentLabels.clear()
+        subagentIds.clear()
    }

    fun onThinkingDelta(messageId: String, delta: String) {
        _isStreaming.value = true
        _messages.update { messages ->
-            val existing = messages.findLast { it.id == messageId && it.role == MessageRole.ASSISTANT }
+            val existing = messages.findLast {
+                it.matchesIdentity(messageId) && it.role == MessageRole.ASSISTANT
+            }
            if (existing != null) {
                messages.map { msg ->
-                    if (msg.id == messageId) {
+                    if (msg.matchesIdentity(messageId)) {
                        msg.copy(
                            thinkingContent = msg.thinkingContent + delta,
                            isThinkingStreaming = true
@@ -3162,7 +3389,7 @@ class ChatHandler {
    fun onUsageReceived(messageId: String, inputTokens: Int?, outputTokens: Int?, totalTokens: Int?, cost: Double?) {
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id == messageId) {
+                if (msg.matchesIdentity(messageId)) {
                    msg.copy(
                        inputTokens = inputTokens,
                        outputTokens = outputTokens,
@@ -3195,7 +3422,7 @@ class ChatHandler {
        )
        _messages.update { messages ->
            messages.map { msg ->
-                if (msg.id != messageId) return@map msg
+                if (!msg.matchesIdentity(messageId)) return@map msg
                val alreadyDispatched = msg.cardDispatches.any {
                    it.cardKey == cardKey && it.actionValue == actionValue
                }
@@ -365,8 +365,10 @@ class DashboardApiClient(
     * `available=false` with an empty list when the server has no API key
     * configured; the API key itself never leaves the server.
     */
-    suspend fun getElevenLabsVoices(): Result<ElevenLabsVoices> = withContext(Dispatchers.IO) {
-        getJson("/api/audio/elevenlabs/voices").mapCatching { parseElevenLabsVoices(it) }
+    suspend fun getElevenLabsVoices(profile: String? = null): Result<ElevenLabsVoices> =
+        withContext(Dispatchers.IO) {
+            getJson("/api/audio/elevenlabs/voices${profileQuery(profile)}")
+                .mapCatching { parseElevenLabsVoices(it) }
    }

    /**
@@ -498,6 +500,7 @@ class DashboardApiClient(
        name: String,
        cloneFromDefault: Boolean = true,
        description: String? = null,
+        mcpServers: List<String> = emptyList(),
    ): Result<JsonObject> =
        postJsonObject(
            path = "/api/profiles",
@@ -505,9 +508,16 @@ class DashboardApiClient(
                put("name", name)
                put("clone_from_default", cloneFromDefault)
                if (!description.isNullOrBlank()) put("description", description)
+                if (mcpServers.isNotEmpty()) {
+                    put("mcp_servers", JsonArray(mcpServers.map(::JsonPrimitive)))
+                }
            },
        )

+    /** Create a host-owned Hermes backup, distinct from Android settings export. */
+    suspend fun createServerBackup(): Result<JsonObject> =
+        postJsonObject("/api/ops/backup")
+
    suspend fun setProfileDescription(name: String, description: String): Result<JsonObject> =
        putJsonObject(
            path = "/api/profiles/${pathSegment(name)}/description",
@@ -603,15 +613,16 @@ class DashboardApiClient(
        )
    }

-    suspend fun getCustomEndpoints(): Result<DashboardCustomEndpoints> =
-        getJsonObject("/api/providers/custom-endpoints")
+    suspend fun getCustomEndpoints(profile: String? = null): Result<DashboardCustomEndpoints> =
+        getJsonObject("/api/providers/custom-endpoints${profileQuery(profile)}")
            .mapCatching(::parseCustomEndpoints)

    suspend fun saveCustomEndpoint(
        draft: DashboardCustomEndpointDraft,
+        profile: String? = null,
    ): Result<DashboardCustomEndpoints> =
        postJsonObject(
-            "/api/providers/custom-endpoints",
+            "/api/providers/custom-endpoints${profileQuery(profile)}",
            customEndpointPayload(draft),
        ).mapCatching(::parseCustomEndpoints)

@@ -632,13 +643,19 @@ class DashboardApiClient(

    suspend fun activateCustomEndpoint(
        id: String,
+        profile: String? = null,
    ): Result<JsonObject> =
-        postJsonObject("/api/providers/custom-endpoints/${pathSegment(id)}/activate")
+        postJsonObject(
+            "/api/providers/custom-endpoints/${pathSegment(id)}/activate${profileQuery(profile)}",
+        )

    suspend fun deleteCustomEndpoint(
        id: String,
+        profile: String? = null,
    ): Result<DashboardCustomEndpoints> =
-        deleteJsonObject("/api/providers/custom-endpoints/${pathSegment(id)}")
+        deleteJsonObject(
+            "/api/providers/custom-endpoints/${pathSegment(id)}${profileQuery(profile)}",
+        )
            .mapCatching(::parseCustomEndpoints)

    suspend fun installMcpCatalogEntry(
@@ -718,27 +735,59 @@ class DashboardApiClient(
     */
    suspend fun listSessions(
        profile: String? = null,
-        limit: Int = 200,
+        limit: Int = SESSION_LIST_WINDOW_LIMIT,
        archived: String? = null,
    ): Result<List<SessionItem>> =
        withContext(Dispatchers.IO) {
-            val query = buildList {
-                add("limit=${limit.coerceIn(1, 200)}")
-                add("order=recent")
-                add("min_messages=1")
-                val name = profile?.trim().orEmpty()
-                if (name.isNotBlank()) add("profile=${pathSegment(name)}")
-                // Upstream `archived` filter: exclude (default) | only | include.
-                // Omitted unless requested so older hosts see an unchanged request.
-                val archivedMode = archived?.trim().orEmpty()
-                if (archivedMode.isNotBlank()) add("archived=${pathSegment(archivedMode)}")
-            }.joinToString(prefix = "?", separator = "&")
-            getJson("/api/sessions$query").mapCatching { root ->
-                val parsed = json.decodeFromJsonElement(SessionListResponse.serializer(), root)
-                parsed.sessions ?: parsed.items ?: parsed.data ?: emptyList()
+            val sessions = linkedMapOf<String, SessionItem>()
+            for (page in sessionListPages(limit)) {
+                val query = buildList {
+                    // Upstream dashboard GET /api/sessions rejects pages over 100.
+                    // Keep Android's 200-row drawer window via two bounded pages.
+                    add("limit=${page.limit}")
+                    add("offset=${page.offset}")
+                    add("order=recent")
+                    add("min_messages=1")
+                    val name = profile?.trim().orEmpty()
+                    if (name.isNotBlank()) add("profile=${pathSegment(name)}")
+                    // Upstream `archived` filter: exclude (default) | only | include.
+                    // Omitted unless requested so older hosts see an unchanged request.
+                    val archivedMode = archived?.trim().orEmpty()
+                    if (archivedMode.isNotBlank()) add("archived=${pathSegment(archivedMode)}")
+                }.joinToString(prefix = "?", separator = "&")
+                val pageResult = getJson("/api/sessions$query").mapCatching { root ->
+                    val parsed = json.decodeFromJsonElement(SessionListResponse.serializer(), root)
+                    parsed.sessions ?: parsed.items ?: parsed.data ?: emptyList()
+                }
+                if (pageResult.isFailure) return@withContext pageResult
+                val pageSessions = pageResult.getOrThrow()
+                pageSessions.forEach { sessions.putIfAbsent(it.id, it) }
+                if (pageSessions.size < page.limit) break
            }
+            Result.success(sessions.values.take(limit.coerceIn(1, SESSION_LIST_WINDOW_LIMIT)))
        }

+    /**
+     * Read the bounded, authoritative session window across every profile.
+     * Every usable row must retain its owning profile; rows without one are
+     * skipped rather than risking a cross-profile transcript or mutation.
+     */
+    suspend fun listAllProfileSessions(
+        limit: Int = SESSION_LIST_WINDOW_LIMIT,
+    ): Result<List<SessionItem>> = withContext(Dispatchers.IO) {
+        val boundedLimit = limit.coerceIn(1, SESSION_LIST_WINDOW_LIMIT)
+        getJson(
+            "/api/profiles/sessions?limit=$boundedLimit&offset=0&order=recent" +
+                "&min_messages=1&archived=include&profile=all",
+        ).mapCatching { root ->
+            val parsed = json.decodeFromJsonElement(SessionListResponse.serializer(), root)
+            (parsed.sessions ?: parsed.items ?: parsed.data ?: emptyList())
+                .filter { it.id.isNotBlank() && !it.profile.isNullOrBlank() }
+                .distinctBy { "${it.profile}:${it.id}" }
+                .take(boundedLimit)
+        }
+    }
+
    /**
     * A session's message history, scoped to its owning profile via the dashboard
     * `GET /api/sessions/{id}/messages?profile=`. Required twin of [listSessions]:
@@ -750,12 +799,24 @@ class DashboardApiClient(
    suspend fun getSessionMessages(
        sessionId: String,
        profile: String? = null,
+        mode: SessionMessageLoadMode = SessionMessageLoadMode.COMPLETE,
    ): Result<List<MessageItem>> = withContext(Dispatchers.IO) {
        val name = profile?.trim().orEmpty()
-        val query = if (name.isNotBlank()) "?profile=${pathSegment(name)}" else ""
-        getJson("/api/sessions/${pathSegment(sessionId)}/messages$query").mapCatching { root ->
-            val parsed = json.decodeFromJsonElement(MessageListResponse.serializer(), root)
-            parsed.messages ?: parsed.data ?: parsed.items ?: emptyList()
+        loadSessionMessages(mode) { page ->
+            val query = buildList {
+                add("limit=${page.limit}")
+                add("offset=${page.offset}")
+                add("order=${page.order}")
+                if (name.isNotBlank()) add("profile=${pathSegment(name)}")
+            }.joinToString(prefix = "?", separator = "&")
+            getJson("/api/sessions/${pathSegment(sessionId)}/messages$query").mapCatching { root ->
+                val parsed = json.decodeFromJsonElement(MessageListResponse.serializer(), root)
+                SessionMessagePage(
+                    messages = parsed.messages ?: parsed.data ?: parsed.items ?: emptyList(),
+                    pagination = parsed.pagination,
+                    payloadChars = root.toString().length,
+                )
+            }
        }
    }

@@ -819,6 +880,20 @@ class DashboardApiClient(
            },
        )

+    /** Persist the upstream keep flag that backs official-client session pins. */
+    suspend fun setSessionPinned(
+        sessionId: String,
+        pinned: Boolean,
+        profile: String? = null,
+    ): Result<JsonObject> =
+        patchJsonObject(
+            "/api/sessions/${pathSegment(sessionId)}${profileQuery(profile)}",
+            buildJsonObject {
+                put("pinned", pinned)
+                profile?.trim()?.takeIf { it.isNotBlank() }?.let { put("profile", it) }
+            },
+        )
+
    /**
     * Dry-run a server-backed bulk session cleanup via the dashboard
     * `POST /api/sessions/prune` (`dry_run: true`). Returns what WOULD be
@@ -1058,7 +1133,12 @@ class DashboardApiClient(
            }
        }

-        fun gatewayWebSocketUrl(baseUrl: String, ticket: String, path: String = "/api/ws"): String? {
+        fun gatewayWebSocketUrl(
+            baseUrl: String,
+            ticket: String,
+            path: String = "/api/ws",
+            profile: String? = null,
+        ): String? {
            val httpUrl = baseUrl.trim().trimEnd('/').toHttpUrlOrNull() ?: return null
            val websocketPrefix = when (httpUrl.scheme) {
                "https" -> "wss://"
@@ -1074,6 +1154,11 @@ class DashboardApiClient(
            val url = httpUrl.newBuilder()
                .encodedPath(encodedPath)
                .addQueryParameter("ticket", ticket)
+                .apply {
+                    profile?.trim()?.takeIf { it.isNotBlank() }?.let {
+                        addQueryParameter("profile", it)
+                    }
+                }
                .build()
                .toString()
            return websocketPrefix + url.substringAfter("://")
@@ -18,10 +18,12 @@ import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeout
+import com.hermesandroid.relay.network.shared.fullJitterDelayMs
 import kotlinx.coroutines.withTimeoutOrNull
 import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonNull
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.booleanOrNull
@@ -31,6 +33,7 @@ import kotlinx.serialization.json.decodeFromJsonElement
 import kotlinx.serialization.json.intOrNull
 import kotlinx.serialization.json.longOrNull
 import kotlinx.serialization.json.put
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.Response
@@ -85,6 +88,8 @@ class GatewayChatClient(
    private val promptSubmitTimeoutMs: Long = PROMPT_SUBMIT_REQUEST_TIMEOUT_MS,
    /** Test seam — idle-progress watchdog base. Production keeps [TURN_TIMEOUT_MS]. */
    private val turnIdleTimeoutMs: Long = TURN_TIMEOUT_MS,
+    /** Random source for ordinary reconnect full-jitter. */
+    private val reconnectJitterUnit: () -> Double = { kotlin.random.Random.nextDouble() },
 ) {
    /** Existing upstream rich-chat vocabulary; do not invent a Relay-only source. */
    private val sessionSource = "webui"
@@ -259,6 +264,9 @@ class GatewayChatClient(
    private val _serverProvider = MutableStateFlow<String?>(null)
    val serverProvider: StateFlow<String?> = _serverProvider.asStateFlow()

+    private val _serverModelIdentity = MutableStateFlow<GatewayModelIdentity?>(null)
+    val serverModelIdentity: StateFlow<GatewayModelIdentity?> = _serverModelIdentity.asStateFlow()
+
    /**
     * Active reasoning EFFORT from `session.info` (string; "" when reasoning is
     * disabled). The reasoning DISPLAY mode is NOT on session.info — it stays a
@@ -268,6 +276,10 @@ class GatewayChatClient(
    private val _serverReasoningEffort = MutableStateFlow<String?>(null)
    val serverReasoningEffort: StateFlow<String?> = _serverReasoningEffort.asStateFlow()

+    private val _serverReasoningIdentity = MutableStateFlow<GatewayReasoningIdentity?>(null)
+    val serverReasoningIdentity: StateFlow<GatewayReasoningIdentity?> =
+        _serverReasoningIdentity.asStateFlow()
+
    /**
     * Server-reported credential warning (upstream `session.info.credential_warning`)
     * — present ONLY when the active provider's key is missing/invalid, absent
@@ -501,6 +513,10 @@ class GatewayChatClient(
     *   into the session's USER messages (counted from the first user
     *   message). The server drops that message and everything after it
     *   before running [text] as a fresh turn.
+     * @param queuedFollowUp true only when Android is draining a prompt the
+     *   user explicitly queued behind an active turn. Newer gateways use the
+     *   additive `queued:true` marker to preserve run-after semantics while
+     *   the previous turn is still settling; older gateways ignore it.
     * @param onPreflightFailure invoked INSTEAD of starting the turn when the
     *   gateway could not be reached / authenticated / the prompt could not
     *   be submitted — i.e. nothing started server-side, so the caller can
@@ -514,6 +530,7 @@ class GatewayChatClient(
        callbacks: GatewayTurnCallbacks,
        attachments: List<GatewayAttachment> = emptyList(),
        truncateBeforeUserOrdinal: Int? = null,
+        queuedFollowUp: Boolean = false,
        onPreflightFailure: (reason: String) -> Unit,
    ): ActiveTurnHandle {
        val turn = GatewayTurn(dispatchOn(callbacks))
@@ -549,7 +566,12 @@ class GatewayChatClient(
                    buildJsonObject {
                        put("session_id", liveSessionId ?: error("no live session"))
                        put("text", text)
-                        truncateBeforeUserOrdinal?.let { put("truncate_before_user_ordinal", it) }
+                        truncateBeforeUserOrdinal?.let { ordinal ->
+                            put("truncate_before_user_ordinal", ordinal)
+                            put("confirm_truncate", true)
+                            if (ordinal == 0) put("confirm_empty_truncate", true)
+                        }
+                        if (queuedFollowUp) put("queued", true)
                    },
                    // Long-running RPC, not a generic 15s ack — see the
                    // constant's doc. The idle watchdog (armed above, reset by
@@ -573,8 +595,22 @@ class GatewayChatClient(
                    }
                    if (activeTurn === turn) activeTurn = null
                    turn.disarmWatchdog()
+                    val submitError = submitted.exceptionOrNull()
+                    if (submitError.isAuthoritativePromptSubmitRejection()) {
+                        // Authoritative policy rejection: the gateway received
+                        // the prompt and deliberately refused to create the
+                        // first turn. Falling back to SSE would bypass the cap
+                        // and duplicate the optimistic user turn on another
+                        // transport. Surface the holder-aware upstream message
+                        // through the normal failed-turn callback instead.
+                        turn.tracer.done("submit-rejected")
+                        turn.callbacks.onError(
+                            submitError?.message ?: "Hermes rejected the new session",
+                        )
+                        return@launch
+                    }
                    throw GatewayPreflightException(
-                        submitted.exceptionOrNull()?.message ?: "prompt.submit failed",
+                        submitError?.message ?: "prompt.submit failed",
                    )
                }
                turn.tracer.mark("submit")
@@ -881,6 +917,16 @@ class GatewayChatClient(
                    user = value.stringField("user").orEmpty(),
                    assistant = value.stringField("assistant").orEmpty(),
                    streaming = value.booleanField("streaming") == true,
+                    corrections = (value["corrections"] as? JsonArray)
+                        ?.mapNotNull { correction ->
+                            (correction as? JsonPrimitive)
+                                ?.contentOrNull
+                                ?.trim()
+                                ?.takeIf { it.isNotBlank() }
+                                ?.take(MAX_RECOVERED_CORRECTION_CHARS)
+                        }
+                        ?.take(MAX_RECOVERED_CORRECTIONS)
+                        .orEmpty(),
                    status = value.stringField("status"),
                    error = value.stringField("error"),
                    recoverable = value.booleanField("recoverable") == true,
@@ -1084,41 +1130,59 @@ class GatewayChatClient(
        )

    /** Answer a [GatewayAsk.Kind.CLARIFY] ask. */
-    suspend fun respondClarify(requestId: String, answer: String): Result<GatewayAskResponse> =
-        rpc(
+    suspend fun respondClarify(requestId: String, answer: String): Result<GatewayAskResponse> {
+        val respondingTurn = activeTurn
+        return rpc(
            "clarify.respond",
            buildJsonObject {
                put("request_id", requestId)
                put("answer", answer)
            },
-        ).map { it.gatewayAskResponse() }
+        ).map {
+            it.gatewayAskResponse().also {
+                respondingTurn?.acknowledgeInteraction(GatewayAskExpiry(GatewayAsk.Kind.CLARIFY, requestId))
+            }
+        }
+    }

    /**
     * Answer a [GatewayAsk.Kind.SUDO] ask. The password must NEVER be logged
     * or persisted — it exists only inside this outbound frame.
     */
-    suspend fun respondSudo(requestId: String, password: String): Result<GatewayAskResponse> =
-        rpc(
+    suspend fun respondSudo(requestId: String, password: String): Result<GatewayAskResponse> {
+        val respondingTurn = activeTurn
+        return rpc(
            "sudo.respond",
            buildJsonObject {
                put("request_id", requestId)
                put("password", password)
            },
-        ).map { it.gatewayAskResponse() }
+        ).map {
+            it.gatewayAskResponse().also {
+                respondingTurn?.acknowledgeInteraction(GatewayAskExpiry(GatewayAsk.Kind.SUDO, requestId))
+            }
+        }
+    }

    /**
     * Answer a [GatewayAsk.Kind.SECRET] ask. Empty [value] = skip (upstream
     * returns `skipped: true` to the tool). The value must NEVER be logged
     * or persisted — it exists only inside this outbound frame.
     */
-    suspend fun respondSecret(requestId: String, value: String): Result<GatewayAskResponse> =
-        rpc(
+    suspend fun respondSecret(requestId: String, value: String): Result<GatewayAskResponse> {
+        val respondingTurn = activeTurn
+        return rpc(
            "secret.respond",
            buildJsonObject {
                put("request_id", requestId)
                put("value", value)
            },
-        ).map { it.gatewayAskResponse() }
+        ).map {
+            it.gatewayAskResponse().also {
+                respondingTurn?.acknowledgeInteraction(GatewayAskExpiry(GatewayAsk.Kind.SECRET, requestId))
+            }
+        }
+    }

    /**
     * Answer a [GatewayAsk.Kind.APPROVAL] ask — correlated by the live
@@ -1126,6 +1190,7 @@ class GatewayChatClient(
     * resolves every pending approval on the session at once.
     */
    suspend fun respondApproval(choice: String, all: Boolean = false): Result<GatewayAskResponse> {
+        val respondingTurn = activeTurn
        val sid = liveSessionId
            ?: return Result.failure(GatewayRpcException("no live session"))
        return rpc(
@@ -1135,7 +1200,11 @@ class GatewayChatClient(
                put("choice", choice)
                put("all", all)
            },
-        ).map { it.gatewayAskResponse() }
+        ).map {
+            it.gatewayAskResponse().also {
+                respondingTurn?.acknowledgeInteraction(GatewayAskExpiry(GatewayAsk.Kind.APPROVAL, null))
+            }
+        }
    }

    /**
@@ -1159,6 +1228,59 @@ class GatewayChatClient(
            .onSuccess { commandsCatalogCache = it }
    }

+    /**
+     * Fetch the upstream gateway's cropped preview for a Petdex pet.
+     *
+     * A missing thumbnail is represented by a successful `null`, matching the
+     * gateway's fail-open `{ "ok": false }` response. RPC errors, including
+     * method-not-found on older upstream gateways, remain failures so callers
+     * can distinguish an unavailable capability from a missing image.
+     */
+    suspend fun petThumbnail(
+        slug: String,
+        spritesheetUrl: String? = null,
+        profile: String? = currentSessionProfile(),
+    ): Result<String?> {
+        val normalizedSlug = slug.trim()
+        if (!PETDEX_SLUG.matches(normalizedSlug)) {
+            return Result.failure(IllegalArgumentException("invalid Petdex slug"))
+        }
+
+        val normalizedUrl = spritesheetUrl?.trim()?.takeIf { it.isNotEmpty() }
+        if (normalizedUrl != null && !isTrustedPetdexAssetUrl(normalizedUrl)) {
+            return Result.failure(IllegalArgumentException("invalid Petdex spritesheet URL"))
+        }
+
+        try {
+            connectMutex.withLock { ensureConnected() }
+        } catch (e: Exception) {
+            return Result.failure(e)
+        }
+
+        return rpc(
+            "pet.thumb",
+            buildJsonObject {
+                put("slug", normalizedSlug)
+                normalizedUrl?.let { put("url", it) }
+                profile?.trim()?.takeIf { it.isNotEmpty() }?.let { put("profile", it) }
+            },
+        ).mapCatching { response ->
+            val ok = (response["ok"] as? JsonPrimitive)?.booleanOrNull
+                ?: throw GatewayRpcException("pet.thumb returned an invalid response")
+            val responseSlug = (response["slug"] as? JsonPrimitive)?.contentOrNull
+            if (responseSlug != normalizedSlug) {
+                throw GatewayRpcException("pet.thumb returned a mismatched slug")
+            }
+            if (!ok) return@mapCatching null
+
+            val dataUri = (response["dataUri"] as? JsonPrimitive)?.contentOrNull
+            if (dataUri == null || !isValidPetThumbnailDataUri(dataUri)) {
+                throw GatewayRpcException("pet.thumb returned an invalid thumbnail")
+            }
+            dataUri
+        }
+    }
+
    /**
     * Fetch the current chat session's running and recently-finished background
     * processes. Callers never provide a session id: this wrapper resolves and
@@ -1270,6 +1392,22 @@ class GatewayChatClient(
            }
    }

+    /**
+     * List personalities through upstream's slash completer. Unlike the
+     * dashboard config schema, this resolves the CLI config that contains both
+     * built-in and profile-defined personalities, matching `/personality` in
+     * the desktop and TUI.
+     */
+    suspend fun personalityOptions(): Result<List<String>> {
+        if (webSocket == null || readySignal?.isCompleted != true) {
+            return Result.failure(GatewayRpcException("not connected"))
+        }
+        return rpc(
+            "complete.slash",
+            buildJsonObject { put("text", "/personality ") },
+        ).map(::parseGatewayPersonalityOptions)
+    }
+
    /**
     * Set the personality the way the desktop + TUI do (`config.set
     * {key:"personality"}`). The gateway persists `display.personality` +
@@ -1319,23 +1457,12 @@ class GatewayChatClient(
            if (refresh) put("refresh", true)
        }
        return rpc("model.options", params).map { result ->
-            val providers = (result["providers"] as? JsonArray).orEmpty().mapNotNull { el ->
-                val obj = el as? JsonObject ?: return@mapNotNull null
-                val slug = obj.stringField("slug") ?: return@mapNotNull null
-                GatewayModelProvider(
-                    name = obj.stringField("name") ?: slug,
-                    slug = slug,
-                    models = (obj["models"] as? JsonArray).orEmpty()
-                        .mapNotNull { (it as? JsonPrimitive)?.contentOrNull },
-                    isCurrent = (obj["is_current"] as? JsonPrimitive)?.booleanOrNull ?: false,
-                    warning = obj.stringField("warning"),
-                    authenticated = (obj["authenticated"] as? JsonPrimitive)?.booleanOrNull ?: true,
-                    unavailableModels = (obj["unavailable_models"] as? JsonArray).orEmpty()
-                        .mapNotNull { (it as? JsonPrimitive)?.contentOrNull },
-                    freeTier = (obj["free_tier"] as? JsonPrimitive)?.booleanOrNull ?: false,
-                    totalModels = (obj["total_models"] as? JsonPrimitive)?.contentOrNull?.toIntOrNull() ?: 0,
-                )
-            }
+            val providers = normalizeGatewayModelProviders(
+                (result["providers"] as? JsonArray).orEmpty().mapNotNull { el ->
+                    val obj = el as? JsonObject ?: return@mapNotNull null
+                    parseGatewayModelProvider(obj)
+                },
+            )
            GatewayModelOptions(
                providers = providers,
                currentModel = result.stringField("model") ?: "",
@@ -1363,6 +1490,43 @@ class GatewayChatClient(
            },
        )

+    /**
+     * React to the newest message for a role without guessing a transcript row
+     * id. This follows the upstream gateway contract, which resolves the row
+     * atomically inside the active session. A null emoji removes the reaction.
+     */
+    suspend fun reactToNewest(role: String, emoji: String?): Result<JsonObject> {
+        require(role == "user" || role == "assistant") { "unsupported reaction role" }
+        val sid = liveSessionId
+            ?: return Result.failure(GatewayRpcException("no live session"))
+        return rpc(
+            "message.react",
+            buildJsonObject {
+                put("session_id", sid)
+                put("newest_role", role)
+                if (emoji == null) put("emoji", JsonNull) else put("emoji", emoji)
+                put("author", "user")
+            },
+        )
+    }
+
+    /** Redirect one running child agent without interrupting the parent turn. */
+    suspend fun steerSubagent(subagentId: String, text: String): Result<JsonObject> {
+        val sessionId = liveSessionId
+            ?: return Result.failure(IllegalStateException("No live gateway session"))
+        if (subagentId.isBlank() || text.isBlank()) {
+            return Result.failure(IllegalArgumentException("Subagent and instruction are required"))
+        }
+        return rpc(
+            "subagent.steer",
+            buildJsonObject {
+                put("session_id", sessionId)
+                put("subagent_id", subagentId)
+                put("text", text.trim())
+            },
+        )
+    }
+
    /** Fetch the session/global reasoning effort and display mode. */
    suspend fun getReasoningSettings(): Result<GatewayReasoningSettings> {
        if (webSocket == null || readySignal?.isCompleted != true) {
@@ -1684,12 +1848,23 @@ class GatewayChatClient(
            _serverPersonality.value =
                (info.stringField("personality") ?: "").ifBlank { "none" }
        }
-        info.stringField("model")?.takeIf { it.isNotBlank() }?.let { _serverModel.value = it }
-        info.stringField("provider")?.takeIf { it.isNotBlank() }?.let { _serverProvider.value = it }
+        val model = info.stringField("model")?.takeIf { it.isNotBlank() }
+        val provider = info.stringField("provider")?.takeIf { it.isNotBlank() }
+        model?.let { _serverModel.value = it }
+        provider?.let { _serverProvider.value = it }
+        if (model != null && provider != null) {
+            _serverModelIdentity.value = GatewayModelIdentity(model = model, provider = provider)
+        }
        // reasoning effort: ignore "" (reasoning disabled) so it can't clobber
        // the chip; display mode is config.get-only, not here.
-        info.stringField("reasoning_effort")?.takeIf { it.isNotBlank() }
-            ?.let { _serverReasoningEffort.value = it }
+        val reasoningEffort = info.stringField("reasoning_effort")?.takeIf { it.isNotBlank() }
+        reasoningEffort?.let { _serverReasoningEffort.value = it }
+        if (model != null && provider != null && reasoningEffort != null) {
+            _serverReasoningIdentity.value = GatewayReasoningIdentity(
+                identity = GatewayModelIdentity(model = model, provider = provider),
+                effort = reasoningEffort,
+            )
+        }
        // credential_warning: present only when the provider key is missing/
        // invalid. ABSENT means healthy — clear to null so it self-resolves.
        _serverCredentialWarning.value =
@@ -1960,6 +2135,42 @@ class GatewayChatClient(
            return
        }

+        // Upstream emits session.reclaimed process-wide, so it is identified
+        // by payload rather than params.session_id. Retire only an exact live
+        // runtime we own; preserve the durable id so the next send resumes it.
+        if (type == "session.reclaimed") {
+            val reclaimedLiveId = payload?.stringField("session_id")
+            val reclaimedStoredId = payload?.stringField("stored_session_id")
+            val reason = payload?.stringField("reason")
+            val supportedReason = reason in setOf("idle_timeout", "lru_evict", "ws_orphan_reap")
+            if (!reclaimedLiveId.isNullOrBlank() && supportedReason) {
+                val background = backgroundTurns.remove(reclaimedLiveId)
+                if (background != null) {
+                    callbackDispatcher {
+                        unmatchedTurnCompleteListener?.invoke(
+                            GatewayBackgroundTurnCompletion(
+                                storedSessionId = reclaimedStoredId?.takeIf(String::isNotBlank)
+                                    ?: background.storedSessionId,
+                                liveSessionId = reclaimedLiveId,
+                                profile = background.profile,
+                                expectedAssistantText = null,
+                            ),
+                        )
+                    }
+                }
+                if (reclaimedLiveId == liveSessionId) {
+                    liveSessionId = null
+                    reclaimedStoredId?.takeIf(String::isNotBlank)?.let { storedSessionId = it }
+                    val turn = activeTurn
+                    if (turn != null && !turn.ended) {
+                        activeTurn = null
+                        turn.failFromTransport("Gateway reclaimed the inactive session")
+                    }
+                }
+            }
+            return
+        }
+
        // read_terminal is a renderer query, not a user decision. Android has
        // no xterm pane on the Gateway chat surface, so mirror upstream
        // desktop's no-live-pane behavior and answer with empty text instead
@@ -2036,13 +2247,14 @@ class GatewayChatClient(
                pendingAsk.kind == expiry.kind &&
                (pendingAsk.kind == GatewayAsk.Kind.APPROVAL ||
                    pendingAsk.requestId == expiry.requestId)
-            val turnResumed = pendingAsk != null &&
-                GatewayEventMapper.isInteractionResumeEvent(type)
-            if (explicitlyExpired || turnResumed) {
+            // Ordinary turn activity is not a decision acknowledgement. It can
+            // be replayed or buffered. Only an authoritative expiry retires a
+            // detached ask; an explicit response is retired by its foreground VM.
+            if (explicitlyExpired) {
                backgroundTurn.pendingAsk = null
                callbackDispatcher {
                    backgroundInteractionListener?.invoke(
-                        GatewayBackgroundInteractionEvent.Resolved(
+                        GatewayBackgroundInteractionEvent.Expired(
                            storedSessionId = backgroundTurn.storedSessionId,
                            profile = backgroundTurn.profile,
                            ask = pendingAsk,
@@ -2058,6 +2270,7 @@ class GatewayChatClient(
                    unmatchedTurnCompleteListener?.invoke(
                        GatewayBackgroundTurnCompletion(
                            storedSessionId = backgroundTurn.storedSessionId,
+                            liveSessionId = eventSessionId,
                            profile = backgroundTurn.profile,
                            expectedAssistantText = expectedText,
                        ),
@@ -2132,6 +2345,7 @@ class GatewayChatClient(
                    unmatchedTurnCompleteListener?.invoke(
                        GatewayBackgroundTurnCompletion(
                            storedSessionId = storedId,
+                            liveSessionId = eventSessionId,
                            profile = liveSessionProfile,
                            expectedAssistantText = expectedText,
                        ),
@@ -2275,7 +2489,7 @@ class GatewayChatClient(
                Log.i(TAG, "Gateway socket rejoined for ${backgroundTurns.size} detached turn(s)")
                return
            }
-            delay(backoffMs)
+            delay(fullJitterDelayMs(backoffMs, reconnectJitterUnit()))
            backoffMs = (backoffMs * 2).coerceAtMost(5_000L)
        }
    }
@@ -2368,7 +2582,7 @@ class GatewayChatClient(
                )
                return
            }
-            delay(backoffMs)
+            delay(fullJitterDelayMs(backoffMs, reconnectJitterUnit()))
            backoffMs = (backoffMs * 2).coerceAtMost(5_000L)
        }
        if (activeTurn === turn) activeTurn = null
@@ -2540,6 +2754,9 @@ class GatewayChatClient(
        fun restoreInteraction(ask: GatewayAsk) {
            mapper.restoreInteraction(ask)
        }
+        fun acknowledgeInteraction(expiry: GatewayAskExpiry) {
+            mapper.acknowledgeInteraction(expiry)
+        }
        private val deferredEventLock = Any()
        private val deferredEvents = mutableListOf<Pair<String, JsonObject?>>()
        private var eventsDeferred = deferEvents
@@ -2869,7 +3086,9 @@ class GatewayChatClient(
            callbackDispatcher { callbacks.onInterimReconciled(text) }
        },
        onThinkingDelta = { v -> callbackDispatcher { callbacks.onThinkingDelta(v) } },
-        onToolCallStart = { a, b -> callbackDispatcher { callbacks.onToolCallStart(a, b) } },
+        onToolCallStart = { id, name, args ->
+            callbackDispatcher { callbacks.onToolCallStart(id, name, args) }
+        },
        onToolCallDone = { a, b -> callbackDispatcher { callbacks.onToolCallDone(a, b) } },
        onToolCallFailed = { a, b -> callbackDispatcher { callbacks.onToolCallFailed(a, b) } },
        onToolOutputRisk = { v -> callbackDispatcher { callbacks.onToolOutputRisk(v) } },
@@ -2883,7 +3102,6 @@ class GatewayChatClient(
        onMoaReference = { v -> callbackDispatcher { callbacks.onMoaReference(v) } },
        onInteractionRequest = { v -> callbackDispatcher { callbacks.onInteractionRequest(v) } },
        onInteractionExpired = { v -> callbackDispatcher { callbacks.onInteractionExpired(v) } },
-        onInteractionResolved = { v -> callbackDispatcher { callbacks.onInteractionResolved(v) } },
        // MUST be wrapped like every other member: GatewayTurnCallbacks gives
        // onStatusUpdate a default no-op, so omitting it here silently swallows
        // EVERY gateway status line — the ❌ terminal-error lifecycle update
@@ -2895,6 +3113,22 @@ class GatewayChatClient(
    )
 }

+internal fun parseGatewayPersonalityOptions(result: JsonObject): List<String> =
+    (result["items"] as? JsonArray)
+        .orEmpty()
+        .mapNotNull { item ->
+            (item as? JsonObject)
+                ?.stringField("text")
+                ?.trim()
+                ?.removePrefix("/personality")
+                ?.trim()
+                ?.takeIf {
+                    it.isNotBlank() &&
+                        it.lowercase() !in setOf("none", "default", "neutral")
+                }
+        }
+        .distinctBy { it.lowercase() }
+
 /** Outcome of an active-turn correction — Rejected and Failed both mean "queue locally instead". */
 enum class SteerResult {
    /** Server accepted the active-turn correction. */
@@ -2931,6 +3165,37 @@ internal class GatewayConnectAttemptException(message: String) : Exception(messa
 internal class GatewayRpcException(message: String, val code: Int? = null) : Exception(message)

 private const val JSONRPC_METHOD_NOT_FOUND = -32601
+private val AUTHORITATIVE_PROMPT_SUBMIT_REJECTIONS = setOf(
+    4028, // first-turn truncate requires explicit empty-history confirmation
+    4029, // every destructive truncate requires explicit confirmation
+    4090, // active-session capacity policy
+    5070, // initial session persistence failed: storage full
+    5071, // other authoritative initial session persistence failure
+)
+private const val MAX_RECOVERED_CORRECTIONS = 32
+private const val MAX_RECOVERED_CORRECTION_CHARS = 32_768
+private const val PET_THUMB_DATA_PREFIX = "data:image/png;base64,"
+private const val MAX_PET_THUMB_BASE64_CHARS = 512 * 1024
+private val PETDEX_SLUG = Regex("[a-z0-9][a-z0-9-]{0,127}")
+private val STANDARD_BASE64 = Regex("[A-Za-z0-9+/]*={0,2}")
+
+private fun isTrustedPetdexAssetUrl(raw: String): Boolean {
+    val url = raw.toHttpUrlOrNull() ?: return false
+    return url.scheme == "https" &&
+        url.host == "assets.petdex.dev" &&
+        url.port == 443 &&
+        url.username.isEmpty() &&
+        url.password.isEmpty()
+}
+
+private fun isValidPetThumbnailDataUri(raw: String): Boolean {
+    if (!raw.startsWith(PET_THUMB_DATA_PREFIX)) return false
+    val payload = raw.substring(PET_THUMB_DATA_PREFIX.length)
+    return payload.isNotEmpty() &&
+        payload.length <= MAX_PET_THUMB_BASE64_CHARS &&
+        payload.length % 4 == 0 &&
+        STANDARD_BASE64.matches(payload)
+}

 data class GatewayCompressResult(
    val status: String,
@@ -2962,6 +3227,9 @@ private fun Throwable?.isMethodNotFound(): Boolean {
        msg.contains("unknown method", ignoreCase = true)
 }

+private fun Throwable?.isAuthoritativePromptSubmitRejection(): Boolean =
+    (this as? GatewayRpcException)?.code in AUTHORITATIVE_PROMPT_SUBMIT_REJECTIONS
+
 private fun Throwable?.isApprovalModeUnsupported(): Boolean {
    val rpcError = this as? GatewayRpcException ?: return false
    val message = rpcError.message.orEmpty()
@@ -40,6 +40,15 @@ class GatewayEventMapper(
        if (!duplicate) callbacks.onInteractionRequest(ask)
    }

+    /** Retire only the ask whose explicit respond RPC reached server truth. */
+    internal fun acknowledgeInteraction(expiry: GatewayAskExpiry) {
+        val pending = pendingInteraction ?: return
+        if (pending.matches(expiry)) {
+            pendingInteraction = null
+            drainDeferredTerminalEvent()
+        }
+    }
+
    private var sawMessageStart = false
    private var previousEventType: String? = null
    private var sawTextDelta = false
@@ -50,6 +59,7 @@ class GatewayEventMapper(
    private var compactionStatusActive = false
    private var moaStatusActive = false
    private var pendingInteraction: GatewayAsk? = null
+    private var deferredTerminalEvent: Pair<String, JsonObject?>? = null

    /**
     * `tool.complete` events match their `tool.start` by `tool_id`; when a
@@ -81,17 +91,17 @@ class GatewayEventMapper(
            }
            callbacks.onInteractionExpired(expiry)
            previousEventType = type
+            if (pendingInteraction == null) drainDeferredTerminalEvent()
            return
        }
-        if (type in INTERACTION_RESUME_EVENTS) {
-            pendingInteraction?.let { ask ->
-                pendingInteraction = null
-                callbacks.onInteractionResolved(
-                    GatewayAskExpiry(kind = ask.kind, requestId = ask.requestId),
-                )
-            }
+        if (pendingInteraction != null && type in TERMINAL_EVENTS) {
+            // A buffered/late terminal frame is not consent. Upstream blocks
+            // the turn on an interaction, so hold the first terminal until an
+            // explicit response acknowledgement or authoritative expiry.
+            if (deferredTerminalEvent == null) deferredTerminalEvent = type to payload
+            previousEventType = type
+            return
        }
-
        when (type) {
            "reasoning.delta" -> {
                val text = payload.string("text")
@@ -197,7 +207,14 @@ class GatewayEventMapper(
                    }
                    else -> syntheticToolId(name)
                }
-                callbacks.onToolCallStart(toolId, name)
+                val argsPreview = payload?.get("args")
+                    ?.takeUnless { it is JsonPrimitive && it.contentOrNull.isNullOrBlank() }
+                    ?.toString()
+                    ?.takeIf { it.isNotBlank() && it != "null" }
+                    ?: payload.string("args_text")
+                    ?.takeIf { it.isNotBlank() }
+                    ?: payload.string("context")?.takeIf { it.isNotBlank() }
+                callbacks.onToolCallStart(toolId, name, argsPreview)
            }

            "tool.complete" -> {
@@ -210,7 +227,10 @@ class GatewayEventMapper(
                if (!error.isNullOrEmpty()) {
                    callbacks.onToolCallFailed(toolId, error)
                } else {
-                    callbacks.onToolCallDone(toolId, payload.string("summary"))
+                    val resultPreview = payload.string("result_text")
+                        ?.takeIf { it.isNotBlank() }
+                        ?: payload.string("summary")?.takeIf { it.isNotBlank() }
+                    callbacks.onToolCallDone(toolId, resultPreview)
                }
            }

@@ -278,6 +298,7 @@ class GatewayEventMapper(
                        // text; thinking/progress carry text only.
                        preview = payload.string("tool_preview") ?: payload.string("text"),
                        durationSeconds = payload.double("duration_seconds"),
+                        subagentId = payload.string("subagent_id"),
                    ),
                )
            }
@@ -371,6 +392,12 @@ class GatewayEventMapper(
        previousEventType = type
    }

+    private fun drainDeferredTerminalEvent() {
+        val deferred = deferredTerminalEvent ?: return
+        deferredTerminalEvent = null
+        onEvent(deferred.first, deferred.second)
+    }
+
    private fun syntheticToolId(name: String): String {
        val id = "gateway-tool-$name-${syntheticToolCounter++}"
        openSyntheticIdsByName.getOrPut(name) { ArrayDeque() }.addLast(id)
@@ -410,20 +437,7 @@ class GatewayEventMapper(
        private const val MAX_MOA_LABEL_CHARS = 120
        private const val MAX_MOA_REFERENCE_CHARS = 16_000
        private val OUTPUT_RISK_LEVELS = setOf("low", "medium", "high", "critical")
-        private val INTERACTION_RESUME_EVENTS = setOf(
-            "reasoning.delta",
-            "thinking.delta",
-            "reasoning.available",
-            "message.delta",
-            "message.interim",
-            "message.start",
-            "tool.generating",
-            "tool.start",
-            "tool.complete",
-            "message.complete",
-            "error",
-        )
-
+        private val TERMINAL_EVENTS = setOf("message.complete", "error")
        internal fun isFailedMoaReference(text: String): Boolean {
            val normalized = text.trimStart().lowercase()
            return normalized.startsWith("[failed:") || normalized.startsWith("[skipped:")
@@ -497,8 +511,6 @@ class GatewayEventMapper(
            else -> null
        }

-        fun isInteractionResumeEvent(type: String): Boolean = type in INTERACTION_RESUME_EVENTS
-
        /**
         * Hermes 2026-07-15 emits these operational wait lines through the
         * legacy `thinking.delta` display callback. Match the deliberately
@@ -1,6 +1,11 @@
 package com.hermesandroid.relay.network.upstream

 import com.hermesandroid.relay.network.upstream.models.UsageInfo
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.contentOrNull

 /**
 * Shared types for the Gateway chat transport — upstream hermes-agent's
@@ -122,6 +127,8 @@ data class GatewayInflightTurn(
    val user: String,
    val assistant: String,
    val streaming: Boolean,
+    /** Accepted active-turn redirects in display order; additive on newer Hermes. */
+    val corrections: List<String> = emptyList(),
    val status: String? = null,
    val error: String? = null,
    val recoverable: Boolean = false,
@@ -166,6 +173,7 @@ data class GatewaySessionRecovery(
 /** A detached sibling turn reached its terminal event on the shared Gateway socket. */
 data class GatewayBackgroundTurnCompletion(
    val storedSessionId: String,
+    val liveSessionId: String,
    val profile: String?,
    val expectedAssistantText: String?,
 )
@@ -182,7 +190,8 @@ sealed interface GatewayBackgroundInteractionEvent {
        override val ask: GatewayAsk,
    ) : GatewayBackgroundInteractionEvent

-    data class Resolved(
+    /** An authoritative upstream `*.expire` event ended this request. */
+    data class Expired(
        override val storedSessionId: String,
        override val profile: String?,
        override val ask: GatewayAsk,
@@ -261,6 +270,7 @@ data class GatewaySubagentEvent(
    val toolName: String? = null,
    val preview: String? = null,
    val durationSeconds: Double? = null,
+    val subagentId: String? = null,
 ) {
    enum class Phase { START, THINKING, TOOL, PROGRESS, COMPLETE }
 }
@@ -345,8 +355,122 @@ data class GatewayModelProvider(
    val unavailableModels: List<String> = emptyList(),
    val freeTier: Boolean = false,
    val totalModels: Int = 0,
+    /** Per-model capability rows keyed by the exact model id. */
+    val capabilities: Map<String, GatewayModelCapabilities> = emptyMap(),
 )

+/** Shared tolerant parser for the gateway RPC and API-server REST twins. */
+internal fun parseGatewayModelProvider(obj: JsonObject): GatewayModelProvider? {
+    val slug = (obj["slug"] as? JsonPrimitive)?.contentOrNull
+        ?.trim()?.takeIf { it.isNotEmpty() } ?: return null
+    val capabilities = (obj["capabilities"] as? JsonObject).orEmpty().mapNotNull { (model, raw) ->
+        val row = raw as? JsonObject ?: return@mapNotNull null
+        val effortsElement = row["reasoning_efforts"]
+        val efforts = if (effortsElement is JsonArray) {
+            effortsElement
+                .mapNotNull { (it as? JsonPrimitive)?.contentOrNull?.trim()?.takeIf(String::isNotEmpty) }
+                .distinct()
+        } else {
+            null
+        }
+        val modelId = model.trim().takeIf { it.isNotEmpty() } ?: return@mapNotNull null
+        modelId to GatewayModelCapabilities(
+            reasoning = (row["reasoning"] as? JsonPrimitive)?.booleanOrNull,
+            reasoningEfforts = efforts,
+            reasoningEffortsExact =
+                (row["reasoning_efforts_exact"] as? JsonPrimitive)?.booleanOrNull,
+        )
+    }.toMap()
+    return GatewayModelProvider(
+        name = (obj["name"] as? JsonPrimitive)?.contentOrNull ?: slug,
+        slug = slug,
+        models = (obj["models"] as? JsonArray).orEmpty()
+            .mapNotNull { (it as? JsonPrimitive)?.contentOrNull?.trim()?.takeIf(String::isNotEmpty) }
+            .distinct(),
+        isCurrent = (obj["is_current"] as? JsonPrimitive)?.booleanOrNull ?: false,
+        warning = (obj["warning"] as? JsonPrimitive)?.contentOrNull,
+        authenticated = (obj["authenticated"] as? JsonPrimitive)?.booleanOrNull ?: true,
+        unavailableModels = (obj["unavailable_models"] as? JsonArray).orEmpty()
+            .mapNotNull { (it as? JsonPrimitive)?.contentOrNull?.trim()?.takeIf(String::isNotEmpty) }
+            .distinct(),
+        freeTier = (obj["free_tier"] as? JsonPrimitive)?.booleanOrNull ?: false,
+        totalModels = (obj["total_models"] as? JsonPrimitive)?.contentOrNull?.toIntOrNull() ?: 0,
+        capabilities = capabilities,
+    )
+}
+
+/**
+ * Publish one coherent row per provider identity.
+ *
+ * Dynamic catalogs and compatibility payloads can repeat a provider row or a
+ * model inside that row. Provider slugs are case-insensitive upstream, while
+ * model ids remain exact request values. Merge only equal provider slugs so a
+ * model intentionally offered by two different providers stays selectable.
+ */
+internal fun normalizeGatewayModelProviders(
+    providers: List<GatewayModelProvider>,
+): List<GatewayModelProvider> {
+    val normalized = linkedMapOf<String, GatewayModelProvider>()
+    providers.forEach { raw ->
+        val slug = raw.slug.trim()
+        if (slug.isEmpty()) return@forEach
+        val models = raw.models.map(String::trim).filter(String::isNotEmpty).distinct()
+        val unavailable = raw.unavailableModels
+            .map(String::trim)
+            .filter(String::isNotEmpty)
+            .distinct()
+        val capabilities = raw.capabilities.mapNotNull { (model, capability) ->
+            model.trim().takeIf(String::isNotEmpty)?.let { it to capability }
+        }.toMap()
+        val row = raw.copy(
+            name = raw.name.trim().ifEmpty { slug },
+            slug = slug,
+            models = models,
+            unavailableModels = unavailable,
+            totalModels = maxOf(raw.totalModels, models.size),
+            capabilities = capabilities,
+        )
+        val identity = slug.lowercase()
+        val existing = normalized[identity]
+        normalized[identity] = if (existing == null) {
+            row
+        } else {
+            val mergedModels = (existing.models + row.models).distinct()
+            existing.copy(
+                models = mergedModels,
+                isCurrent = existing.isCurrent || row.isCurrent,
+                warning = existing.warning ?: row.warning,
+                authenticated = existing.authenticated || row.authenticated,
+                unavailableModels = (existing.unavailableModels + row.unavailableModels).distinct(),
+                freeTier = existing.freeTier || row.freeTier,
+                totalModels = maxOf(existing.totalModels, row.totalModels, mergedModels.size),
+                capabilities = mergeGatewayModelCapabilities(existing.capabilities, row.capabilities),
+            )
+        }
+    }
+    return normalized.values.toList()
+}
+
+private fun mergeGatewayModelCapabilities(
+    existing: Map<String, GatewayModelCapabilities>,
+    incoming: Map<String, GatewayModelCapabilities>,
+): Map<String, GatewayModelCapabilities> {
+    val merged = existing.toMutableMap()
+    incoming.forEach { (model, next) ->
+        val current = merged[model]
+        merged[model] = if (current == null) {
+            next
+        } else {
+            GatewayModelCapabilities(
+                reasoning = next.reasoning ?: current.reasoning,
+                reasoningEfforts = next.reasoningEfforts ?: current.reasoningEfforts,
+                reasoningEffortsExact = next.reasoningEffortsExact ?: current.reasoningEffortsExact,
+            )
+        }
+    }
+    return merged
+}
+
 data class GatewayMoaReference(
    val index: Int?,
    val count: Int?,
@@ -362,6 +486,15 @@ data class GatewayModelOptions(
    val currentProvider: String,
 )

+/** Coherent model identity from a single `session.info` payload. */
+data class GatewayModelIdentity(val model: String, val provider: String)
+
+/** Model identity and effort observed together in one `session.info` payload. */
+data class GatewayReasoningIdentity(
+    val identity: GatewayModelIdentity,
+    val effort: String,
+)
+
 /** Reject provider catalogs that completed after a profile/context switch. */
 internal fun isCurrentModelOptionsResponse(
    requestGeneration: Long,
@@ -371,6 +504,21 @@ internal fun isCurrentModelOptionsResponse(
 ): Boolean =
    requestGeneration == currentGeneration && requestProfileKey == currentProfileKey

+/**
+ * Selects the identity a model-options response may publish into chat UI state.
+ * Catalog-only requests populate picker choices without changing session identity.
+ */
+internal fun modelOptionsIdentityToPublish(
+    catalogOnly: Boolean,
+    hasLiveSession: Boolean,
+    sessionIdentity: GatewayModelIdentity?,
+    options: GatewayModelOptions,
+): GatewayModelIdentity? = when {
+    catalogOnly -> null
+    hasLiveSession && sessionIdentity != null -> sessionIdentity
+    else -> GatewayModelIdentity(options.currentModel, options.currentProvider)
+}
+
 /**
 * The explicit in-chat overrides to bind onto a gateway `session.create` as the
 * new session's PER-SESSION overrides. Matches the upstream desktop client,
@@ -435,7 +583,7 @@ class GatewayTurnCallbacks(
     */
    val onInterimReconciled: (text: String) -> Unit = { _ -> },
    val onThinkingDelta: (String) -> Unit,
-    val onToolCallStart: (toolCallId: String, toolName: String) -> Unit,
+    val onToolCallStart: (toolCallId: String, toolName: String, argsPreview: String?) -> Unit,
    val onToolCallDone: (toolCallId: String, resultPreview: String?) -> Unit,
    val onToolCallFailed: (toolCallId: String, errorMsg: String?) -> Unit,
    /** Attach deterministic output-risk metadata to the matching tool card. */
@@ -468,8 +616,6 @@ class GatewayTurnCallbacks(
    val onInteractionRequest: (GatewayAsk) -> Unit,
    /** Server declared a pending interaction expired; clear only the matching card. */
    val onInteractionExpired: (GatewayAskExpiry) -> Unit,
-    /** The turn resumed after a pending interaction was resolved elsewhere. */
-    val onInteractionResolved: (GatewayAskExpiry) -> Unit = { _ -> },
    /**
     * Gateway `status.update` lifecycle line — model fallback, retries, and
     * errors (often emoji-prefixed: 🔄 fallback, ⏳ retry, ❌ error). Default
@@ -19,6 +19,7 @@ import com.hermesandroid.relay.network.upstream.models.SkillListResponse
 import com.hermesandroid.relay.network.upstream.models.UsageInfo
 import com.hermesandroid.relay.util.TurnLatencyTracer
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.Serializable
@@ -27,6 +28,7 @@ import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.buildJsonObject
 import kotlinx.serialization.json.contentOrNull
 import kotlinx.serialization.json.decodeFromJsonElement
 import kotlinx.serialization.json.put
@@ -213,25 +215,12 @@ internal fun parseApiProviderModelOptionsBody(
    val root = runCatching { json.parseToJsonElement(body) as? JsonObject }.getOrNull()
        ?: return null
    val rows = root["providers"] as? JsonArray ?: return null
-    val providers = rows.mapNotNull { element ->
-        val obj = element as? JsonObject ?: return@mapNotNull null
-        val slug = (obj["slug"] as? JsonPrimitive)?.contentOrNull
-            ?.trim()?.takeIf { it.isNotEmpty() } ?: return@mapNotNull null
-        GatewayModelProvider(
-            name = (obj["name"] as? JsonPrimitive)?.contentOrNull ?: slug,
-            slug = slug,
-            models = (obj["models"] as? JsonArray).orEmpty()
-                .mapNotNull { (it as? JsonPrimitive)?.contentOrNull },
-            isCurrent = (obj["is_current"] as? JsonPrimitive)?.booleanOrNull ?: false,
-            warning = (obj["warning"] as? JsonPrimitive)?.contentOrNull,
-            authenticated = (obj["authenticated"] as? JsonPrimitive)?.booleanOrNull ?: true,
-            unavailableModels = (obj["unavailable_models"] as? JsonArray).orEmpty()
-                .mapNotNull { (it as? JsonPrimitive)?.contentOrNull },
-            freeTier = (obj["free_tier"] as? JsonPrimitive)?.booleanOrNull ?: false,
-            totalModels = (obj["total_models"] as? JsonPrimitive)?.contentOrNull
-                ?.toIntOrNull() ?: 0,
-        )
-    }
+    val providers = normalizeGatewayModelProviders(
+        rows.mapNotNull { element ->
+            val obj = element as? JsonObject ?: return@mapNotNull null
+            parseGatewayModelProvider(obj)
+        },
+    )
    return ApiProviderModelOptions(
        providers = providers,
        currentModel = (root["model"] as? JsonPrimitive)?.contentOrNull.orEmpty(),
@@ -254,7 +243,8 @@ enum class ApiModelRoutingErrorCode {
 class ApiModelRoutingException(
    val code: ApiModelRoutingErrorCode,
    message: String,
-) : IOException(message)
+    cause: Throwable? = null,
+) : IOException(message, cause)

 sealed interface ApiModelSelectionAck {
    data object ServerDefault : ApiModelSelectionAck
@@ -337,7 +327,7 @@ internal fun parseModelOptionsBody(json: Json, body: String): List<ApiModelOptio
            root = (obj["root"] as? JsonPrimitive)?.contentOrNull,
            parent = (obj["parent"] as? JsonPrimitive)?.contentOrNull,
        )
-    }
+    }.distinctBy { it.id }
 }

 private const val STREAM_ERROR_BODY_LIMIT = 16L * 1024L
@@ -596,27 +586,35 @@ class HermesApiClient(

    // --- Session CRUD ---

-    suspend fun listSessionsResult(limit: Int = 200): Result<List<SessionItem>> = withContext(Dispatchers.IO) {
+    suspend fun listSessionsResult(limit: Int = SESSION_LIST_WINDOW_LIMIT): Result<List<SessionItem>> = withContext(Dispatchers.IO) {
        try {
-            val request = authRequest("$baseUrl/api/sessions?limit=$limit").get().build()
-            client.newCall(request).execute().use { response ->
-                if (!response.isSuccessful) {
-                    return@withContext Result.failure(apiFailure(response, "List sessions"))
+            val sessions = linkedMapOf<String, SessionItem>()
+            for (page in sessionListPages(limit)) {
+                val request = authRequest(
+                    "$baseUrl/api/sessions?limit=${page.limit}&offset=${page.offset}",
+                ).get().build()
+                val pageSessions = client.newCall(request).execute().use { response ->
+                    if (!response.isSuccessful) {
+                        return@withContext Result.failure(apiFailure(response, "List sessions"))
+                    }
+                    val body = response.body.string()
+                    if (body.isBlank()) {
+                        return@withContext Result.failure(IOException("List sessions returned an empty response"))
+                    }
+                    val parsed = json.decodeFromString<SessionListResponse>(body)
+                    parsed.data ?: parsed.items ?: parsed.sessions ?: emptyList()
                }
-                val body = response.body.string()
-                if (body.isBlank()) {
-                    return@withContext Result.failure(IOException("List sessions returned an empty response"))
-                }
-                val parsed = json.decodeFromString<SessionListResponse>(body)
-                Result.success(parsed.data ?: parsed.items ?: parsed.sessions ?: emptyList())
+                pageSessions.forEach { sessions.putIfAbsent(it.id, it) }
+                if (pageSessions.size < page.limit) break
            }
+            Result.success(sessions.values.take(limit.coerceIn(1, SESSION_LIST_WINDOW_LIMIT)))
        } catch (e: Exception) {
            Log.w(TAG, "Failed to list sessions: ${e.message}")
            Result.failure(e)
        }
    }

-    suspend fun listSessions(limit: Int = 200): List<SessionItem> =
+    suspend fun listSessions(limit: Int = SESSION_LIST_WINDOW_LIMIT): List<SessionItem> =
        listSessionsResult(limit).getOrElse { emptyList() }

    suspend fun createSessionResult(
@@ -688,19 +686,62 @@ class HermesApiClient(
        }
    }

-    suspend fun getMessages(sessionId: String): List<MessageItem> = withContext(Dispatchers.IO) {
+    suspend fun setSessionPinned(sessionId: String, pinned: Boolean): Boolean =
+        patchSessionFlag(sessionId, "pinned", pinned)
+
+    suspend fun setSessionArchived(sessionId: String, archived: Boolean): Boolean =
+        patchSessionFlag(sessionId, "archived", archived)
+
+    private suspend fun patchSessionFlag(
+        sessionId: String,
+        field: String,
+        value: Boolean,
+    ): Boolean = withContext(Dispatchers.IO) {
        try {
-            val request = authRequest("$baseUrl/api/sessions/$sessionId/messages")
-                .get()
+            val reqBody = buildJsonObject { put(field, value) }.toString()
+            val request = authRequest("$baseUrl/api/sessions/$sessionId")
+                .patch(reqBody.toRequestBody(JSON_MEDIA))
                .build()
            client.newCall(request).execute().use { response ->
-                if (!response.isSuccessful) return@withContext emptyList()
-                val body = response.body?.string() ?: return@withContext emptyList()
-                val parsed = json.decodeFromString<MessageListResponse>(body)
-                parsed.data ?: parsed.items ?: parsed.messages ?: emptyList()
+                if (!response.isSuccessful) {
+                    Log.w(TAG, "Set session $field failed: HTTP ${response.code}")
+                }
+                response.isSuccessful
            }
        } catch (e: Exception) {
-            Log.w(TAG, "Failed to get messages: ${e.message}")
+            Log.w(TAG, "Failed to set session $field: ${e.message}")
+            false
+        }
+    }
+
+    suspend fun getMessages(
+        sessionId: String,
+        mode: SessionMessageLoadMode = SessionMessageLoadMode.COMPLETE,
+    ): List<MessageItem> = withContext(Dispatchers.IO) {
+        loadSessionMessages(mode) { page ->
+            runCatching {
+                val url = "$baseUrl/api/sessions/$sessionId/messages".toHttpUrlOrNull()
+                    ?.newBuilder()
+                    ?.addQueryParameter("limit", page.limit.toString())
+                    ?.addQueryParameter("offset", page.offset.toString())
+                    ?.addQueryParameter("order", page.order)
+                    ?.build()
+                    ?: error("invalid session messages URL")
+                val request = authRequest(url.toString()).get().build()
+                client.newCall(request).execute().use { response ->
+                    if (!response.isSuccessful) error("HTTP ${response.code}")
+                    val body = response.body?.string() ?: error("empty response body")
+                    val parsed = json.decodeFromString<MessageListResponse>(body)
+                    SessionMessagePage(
+                        messages = parsed.data ?: parsed.items ?: parsed.messages ?: emptyList(),
+                        pagination = parsed.pagination,
+                        payloadChars = body.length,
+                    )
+                }
+            }
+        }.getOrElse { error ->
+            if (error is CancellationException) throw error
+            Log.w(TAG, "Failed to get messages: ${error.message}")
            emptyList()
        }
    }
@@ -807,6 +848,7 @@ class HermesApiClient(
                    ApiModelRoutingException(
                        ApiModelRoutingErrorCode.INVENTORY_UNAVAILABLE,
                        "Model inventory could not be loaded.",
+                        e,
                    )
                },
            )
@@ -1000,9 +1042,7 @@ class HermesApiClient(
                // Personalities: config.agent.personalities { name: "system prompt", ... }
                val agent = config["agent"] as? JsonObject
                val personalitiesObj = agent?.get("personalities") as? JsonObject
-                val prompts = personalitiesObj?.entries?.associate { (key, value) ->
-                    key to ((value as? kotlinx.serialization.json.JsonPrimitive)?.content ?: "")
-                } ?: emptyMap()
+                val prompts = parsePersonalityPrompts(personalitiesObj)

                // Default display identity. Upstream Hermes currently uses
                // config.display.personality for the active persona and often
@@ -4,17 +4,28 @@ import android.content.Context
 import com.hermesandroid.relay.auth.SessionTokenStore
 import com.hermesandroid.relay.auth.SecureStoreCache
 import com.hermesandroid.relay.auth.buildRawTokenStore
+import java.io.EOFException
 import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.ConnectException
+import java.net.InetAddress
+import java.net.NoRouteToHostException
+import java.net.SocketException
+import java.net.UnknownHostException
 import java.security.MessageDigest
 import java.security.SecureRandom
+import java.util.Collections
+import java.util.IdentityHashMap
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.TimeUnit
+import javax.net.ssl.SSLException
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.decodeFromString
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 import okhttp3.Authenticator
+import okhttp3.Dns
 import okhttp3.Interceptor
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.OkHttpClient
@@ -28,6 +39,7 @@ import okio.ByteString.Companion.toByteString
 private const val NATIVE_PKCE_FLOW = "native_pkce"
 private const val CALLBACK_PATH = "/callback"
 private const val TOKEN_KEY = "dashboard_native_tokens_json"
+private const val NATIVE_AUTH_DNS_RETRY_BACKOFF_MILLIS = 75L
 private val JSON_MEDIA = "application/json; charset=utf-8".toMediaType()

@Serializable
@@ -91,6 +103,8 @@ class NativeDashboardAuthClient(
    baseUrl: String,
    private val tokenStore: NativeDashboardTokenStore,
    private val client: OkHttpClient = OkHttpClient.Builder()
+        .dns(RetryingNativeAuthDns())
+        .retryOnConnectionFailure(false)
        .connectTimeout(10, TimeUnit.SECONDS)
        .readTimeout(15, TimeUnit.SECONDS)
        .writeTimeout(15, TimeUnit.SECONDS)
@@ -108,13 +122,18 @@ class NativeDashboardAuthClient(
        provider: String? = null,
    ): NativeDashboardAuthorization {
        requireStrictLoopbackRedirect(redirectUri)
-        val verifier = randomBytes(32).base64Url()
+        // RFC 7636 uses unpadded Base64URL. Okio's base64Url() preserves
+        // trailing "=", which makes Hermes' standards-compliant S256
+        // comparison fail even though both sides hashed the same bytes.
+        val verifier = randomBytes(32).base64Url().trimEnd('=')
        val challenge = MessageDigest.getInstance("SHA-256")
            .digest(verifier.toByteArray(Charsets.US_ASCII))
            .toByteString()
            .base64Url()
+            .trimEnd('=')
        val state = randomBytes(24).base64Url()
-        val root = "$baseUrl/auth/native/authorize".toHttpUrlOrNull()
+        val authorizationBaseUrl = resolveAuthorizationBaseUrl(provider)
+        val root = "$authorizationBaseUrl/auth/native/authorize".toHttpUrlOrNull()
            ?: throw IOException("Dashboard URL is not a valid http(s) address")
        val url = root.newBuilder()
            .addQueryParameter("code_challenge", challenge)
@@ -130,6 +149,41 @@ class NativeDashboardAuthClient(
        return NativeDashboardAuthorization(url, verifier, state, generation)
    }

+    /**
+     * A private-route dashboard may be configured with a canonical HTTPS
+     * callback origin for its provider. Starting the browser on the private
+     * origin would scope Hermes' temporary PKCE cookie to the wrong host, so
+     * discover the provider's declared callback and start native auth there.
+     * Token exchange still uses [baseUrl], keeping the resulting bearer bound
+     * to the active connection route.
+     */
+    private fun resolveAuthorizationBaseUrl(provider: String?): String {
+        val configured = baseUrl.toHttpUrlOrNull() ?: return baseUrl
+        if (
+            !provider.equals("nous", ignoreCase = true) ||
+            configured.scheme != "http" ||
+            !isPrivateNetworkLiteral(configured.host)
+        ) {
+            return baseUrl
+        }
+        val loginUrl = configured.newBuilder()
+            .addPathSegments("auth/login")
+            .addQueryParameter("provider", provider)
+            .addQueryParameter("next", "/")
+            .build()
+        val discoveryClient = client.newBuilder()
+            .followRedirects(false)
+            .followSslRedirects(false)
+            .build()
+        val location = discoveryClient.newCall(
+            Request.Builder().url(loginUrl).get().build(),
+        ).execute().use { response ->
+            if (response.code !in 300..399) null else response.header("Location")
+        }
+        return canonicalDashboardBaseFromNousRedirect(location)
+            ?: throw IOException("Dashboard did not advertise a secure Nous callback origin")
+    }
+
    fun exchangeCallback(
        authorization: NativeDashboardAuthorization,
        callbackTarget: String,
@@ -231,12 +285,19 @@ class NativeDashboardAuthClient(
                }
                throw NativeDashboardAuthHttpException(response.code)
            }
-            val body = response.body?.string().orEmpty()
+            val body = response.body.string()
            runCatching { json.decodeFromString<NativeDashboardTokens>(body) }
-                .getOrElse { throw IOException("Dashboard token response was malformed", it) }
+                .getOrElse {
+                    throw NativeDashboardTokenShapeException(
+                        "Dashboard token response was malformed",
+                        it,
+                    )
+                }
                .also {
                    if (it.accessToken.isBlank()) {
-                        throw IOException("Dashboard token response did not include an access token")
+                        throw NativeDashboardTokenShapeException(
+                            "Dashboard token response did not include an access token",
+                        )
                    }
                }
        }
@@ -245,7 +306,7 @@ class NativeDashboardAuthClient(
                NativeTokenRefreshCoordinator.currentGeneration(tokenStore.coordinationKey) !=
                expectedGeneration
            ) {
-                throw IOException("Dashboard sign-in is no longer active")
+                throw NativeDashboardInactiveAuthorizationException()
            }
            tokenStore.save(tokens)
        }
@@ -272,6 +333,42 @@ class NativeDashboardAuthClient(
    }
 }

+/**
+ * Retries only the name lookup that precedes a native-auth request. The HTTP
+ * call itself remains single-shot, so a one-time authorization code is never
+ * replayed after the server may have consumed it.
+ */
+internal class RetryingNativeAuthDns(
+    private val delegate: Dns = Dns.SYSTEM,
+    private val backoffMillis: Long = NATIVE_AUTH_DNS_RETRY_BACKOFF_MILLIS,
+    private val sleeper: (Long) -> Unit = { Thread.sleep(it) },
+) : Dns {
+    override fun lookup(hostname: String): List<InetAddress> {
+        val firstFailure = try {
+            return delegate.lookup(hostname)
+        } catch (error: UnknownHostException) {
+            error
+        }
+
+        if (backoffMillis > 0L) {
+            try {
+                sleeper(backoffMillis)
+            } catch (interrupted: InterruptedException) {
+                Thread.currentThread().interrupt()
+                firstFailure.addSuppressed(interrupted)
+                throw firstFailure
+            }
+        }
+
+        return try {
+            delegate.lookup(hostname)
+        } catch (secondFailure: UnknownHostException) {
+            secondFailure.addSuppressed(firstFailure)
+            throw secondFailure
+        }
+    }
+}
+
 internal class NativeDashboardCallbackException(
    message: String,
    val retryable: Boolean = true,
@@ -280,7 +377,52 @@ internal class NativeDashboardCallbackException(
 internal fun isNativeDashboardTransportEligible(baseUrl: String): Boolean {
    val url = baseUrl.trim().trimEnd('/').toHttpUrlOrNull() ?: return false
    return url.scheme == "https" ||
-        (url.scheme == "http" && url.host == "127.0.0.1")
+        (
+            url.scheme == "http" &&
+                (url.host == "127.0.0.1" || isPrivateNetworkLiteral(url.host))
+            )
+}
+
+/**
+ * Hermes already permits explicitly configured HTTP dashboard sessions on
+ * local routes. The brokered flow is no less protected than that cookie flow,
+ * but remains unavailable to arbitrary cleartext Internet hosts.
+ */
+private fun isPrivateNetworkLiteral(host: String): Boolean {
+    val octets = host.split('.').mapNotNull(String::toIntOrNull)
+    if (octets.size != 4 || octets.any { it !in 0..255 }) return false
+    val first = octets[0]
+    val second = octets[1]
+    return first == 10 ||
+        (first == 172 && second in 16..31) ||
+        (first == 192 && second == 168) ||
+        (first == 100 && second in 64..127)
+}
+
+internal fun canonicalDashboardBaseFromNousRedirect(location: String?): String? {
+    val providerUrl = location?.toHttpUrlOrNull() ?: return null
+    if (
+        providerUrl.scheme != "https" ||
+        !providerUrl.host.equals("portal.nousresearch.com", ignoreCase = true)
+    ) {
+        return null
+    }
+    val callback = providerUrl.queryParameter("redirect_uri")
+        ?.toHttpUrlOrNull()
+        ?: return null
+    if (callback.scheme != "https") return null
+    val callbackSuffix = "/auth/callback"
+    if (!callback.encodedPath.endsWith(callbackSuffix)) return null
+    val basePath = callback.encodedPath
+        .removeSuffix(callbackSuffix)
+        .ifBlank { "/" }
+    return callback.newBuilder()
+        .encodedPath(basePath)
+        .query(null)
+        .fragment(null)
+        .build()
+        .toString()
+        .trimEnd('/')
 }

 /**
@@ -345,10 +487,56 @@ class DashboardBearerAuth(
    }
 }

-private class NativeDashboardAuthHttpException(
+internal class NativeDashboardAuthHttpException(
    val statusCode: Int,
 ) : IOException("Dashboard native authentication failed (HTTP $statusCode)")

+internal class NativeDashboardTokenShapeException(
+    message: String,
+    cause: Throwable? = null,
+) : IOException(message, cause)
+
+internal class NativeDashboardInactiveAuthorizationException :
+    IOException("Dashboard sign-in is no longer active")
+
+internal fun nativeDashboardSignInFailureStage(error: Throwable): String {
+    error.firstCauseOfType<NativeDashboardCallbackException>()?.let { return "callback_error" }
+    error.firstCauseOfType<NativeDashboardAuthHttpException>()?.let {
+        return "token_http_${it.statusCode}"
+    }
+    if (error.firstCauseOfType<NativeDashboardTokenShapeException>() != null) return "token_shape"
+    if (error.firstCauseOfType<NativeDashboardInactiveAuthorizationException>() != null) {
+        return "inactive_generation"
+    }
+    if (error.firstCauseOfType<InterruptedIOException>() != null) return "token_transport_timeout"
+    if (error.firstCauseOfType<UnknownHostException>() != null) return "token_transport_dns"
+    if (error.firstCauseOfType<ConnectException>() != null ||
+        error.firstCauseOfType<NoRouteToHostException>() != null
+    ) {
+        return "token_transport_connect"
+    }
+    if (error.firstCauseOfType<SSLException>() != null) return "token_transport_tls"
+    if (error.firstCauseOfType<SocketException>() != null ||
+        error.firstCauseOfType<EOFException>() != null
+    ) {
+        return "token_transport_socket"
+    }
+    return if (error.firstCauseOfType<IOException>() != null) "token_transport" else "token_store"
+}
+
+internal fun nativeDashboardSignInFailureDiagnostic(error: Throwable): String =
+    "dashboard_native_pkce_failed stage=${nativeDashboardSignInFailureStage(error)}"
+
+private inline fun <reified T : Throwable> Throwable.firstCauseOfType(): T? {
+    val seen = Collections.newSetFromMap(IdentityHashMap<Throwable, Boolean>())
+    var current: Throwable? = this
+    while (current != null && seen.add(current)) {
+        if (current is T) return current
+        current = current.cause
+    }
+    return null
+}
+
 private object NativeTokenRefreshCoordinator {
    private val locks = ConcurrentHashMap<String, Any>()
    private val generations = ConcurrentHashMap<String, Long>()
@@ -1,5 +1,6 @@
 package com.hermesandroid.relay.network.upstream

+import com.hermesandroid.relay.BuildConfig
 import java.io.IOException
 import java.io.InputStream
 import java.net.InetAddress
@@ -7,6 +8,7 @@ import java.net.InetSocketAddress
 import java.net.ServerSocket
 import java.net.Socket
 import java.net.SocketTimeoutException
+import java.security.MessageDigest
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.currentCoroutineContext
@@ -14,12 +16,44 @@ import kotlinx.coroutines.ensureActive
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.withContext
 import kotlinx.coroutines.withTimeout
+import okio.ByteString.Companion.toByteString

 private const val CALLBACK_PATH = "/callback"
 private const val MAX_REQUEST_LINE_BYTES = 8 * 1024
 private const val MAX_HEADER_BYTES = 16 * 1024
 private const val ACCEPT_POLL_MILLIS = 500
 internal const val DEFAULT_NATIVE_SIGN_IN_TIMEOUT_MILLIS = 2 * 60 * 1000L
+internal val NATIVE_SIGN_IN_RETURN_URI = "${BuildConfig.APPLICATION_ID}://return"
+
+private enum class CallbackPage(
+    val modifier: String,
+    val eyebrow: String,
+    val title: String,
+    val message: String,
+    val guidance: String,
+) {
+    Success(
+        modifier = "success",
+        eyebrow = "Secure sign-in",
+        title = "Sign-in complete",
+        message = "Your secure session is ready in Hermes Relay.",
+        guidance = "Return to Hermes Relay to continue.",
+    ),
+    Failure(
+        modifier = "failure",
+        eyebrow = "Secure sign-in",
+        title = "Sign-in needs another try",
+        message = "No session details were saved from this attempt.",
+        guidance = "Return to Hermes Relay and start sign-in again.",
+    ),
+    Rejected(
+        modifier = "rejected",
+        eyebrow = "Protected callback",
+        title = "Callback not accepted",
+        message = "Hermes Relay ignored this request to protect your sign-in.",
+        guidance = "Return to the app and continue the sign-in already in progress.",
+    ),
+}

 internal enum class DashboardRedirectAuthMode {
    NativePkce,
@@ -33,6 +67,24 @@ internal fun dashboardRedirectAuthMode(authFlows: List<String>): DashboardRedire
        DashboardRedirectAuthMode.WebView
    }

+/**
+ * Nous Portal uses Cloudflare Turnstile and does not support embedded Android
+ * WebViews. Keep self-hosted OIDC on the dashboard cookie flow, but use the
+ * gateway's brokered system-browser flow for Nous when it is advertised.
+ */
+internal fun androidDashboardRedirectAuthMode(
+    providerName: String,
+    authFlows: List<String>,
+): DashboardRedirectAuthMode =
+    if (
+        providerName.equals("nous", ignoreCase = true) &&
+        dashboardRedirectAuthMode(authFlows) == DashboardRedirectAuthMode.NativePkce
+    ) {
+        DashboardRedirectAuthMode.NativePkce
+    } else {
+        DashboardRedirectAuthMode.WebView
+    }
+
 /**
 * Owns one native dashboard sign-in attempt.
 *
@@ -101,7 +153,7 @@ class NativeDashboardSignInCoordinator(
                    writeResponse(
                        socket,
                        status = "403 Forbidden",
-                        body = "This sign-in callback was not accepted.",
+                        page = CallbackPage.Rejected,
                    )
                    return@use null
                }
@@ -114,7 +166,7 @@ class NativeDashboardSignInCoordinator(
                    writeResponse(
                        socket,
                        status = "400 Bad Request",
-                        body = "This sign-in callback was not accepted.",
+                        page = CallbackPage.Rejected,
                    )
                    return@use null
                }
@@ -127,7 +179,7 @@ class NativeDashboardSignInCoordinator(
                        writeResponse(
                            socket,
                            status = "200 OK",
-                            body = "Sign-in complete. You can return to Hermes Relay.",
+                            page = CallbackPage.Success,
                        )
                    }
                } catch (error: NativeDashboardCallbackException) {
@@ -135,21 +187,21 @@ class NativeDashboardSignInCoordinator(
                        writeResponse(
                            socket,
                            status = "400 Bad Request",
-                            body = "This sign-in callback was not accepted.",
+                            page = CallbackPage.Rejected,
                        )
                        return@use null
                    }
                    writeResponse(
                        socket,
                        status = "400 Bad Request",
-                        body = "Sign-in could not be completed. Return to Hermes Relay and try again.",
+                        page = CallbackPage.Failure,
                    )
                    throw error
                } catch (error: Exception) {
                    writeResponse(
                        socket,
                        status = "400 Bad Request",
-                        body = "Sign-in could not be completed. Return to Hermes Relay and try again.",
+                        page = CallbackPage.Failure,
                    )
                    throw error
                }
@@ -219,17 +271,20 @@ class NativeDashboardSignInCoordinator(
        throw IOException("Native sign-in callback line was too large")
    }

-    private fun writeResponse(socket: Socket, status: String, body: String) {
-        val html = """
-            <!doctype html>
-            <html><head><meta name="viewport" content="width=device-width,initial-scale=1"></head>
-            <body><p>${escapeHtml(body)}</p></body></html>
-        """.trimIndent().toByteArray(Charsets.UTF_8)
+    private fun writeResponse(socket: Socket, status: String, page: CallbackPage) {
+        val html = callbackPageHtml(page).toByteArray(Charsets.UTF_8)
        val headers = buildString {
            append("HTTP/1.1 ").append(status).append("\r\n")
            append("Content-Type: text/html; charset=utf-8\r\n")
            append("Content-Length: ").append(html.size).append("\r\n")
            append("Cache-Control: no-store\r\n")
+            append("Pragma: no-cache\r\n")
+            append("Expires: 0\r\n")
+            append("Content-Security-Policy: ").append(CALLBACK_CSP).append("\r\n")
+            append("Referrer-Policy: no-referrer\r\n")
+            append("X-Content-Type-Options: nosniff\r\n")
+            append("X-Frame-Options: DENY\r\n")
+            append("Permissions-Policy: camera=(), geolocation=(), microphone=(), payment=(), usb=()\r\n")
            append("Connection: close\r\n\r\n")
        }.toByteArray(Charsets.US_ASCII)
        runCatching {
@@ -241,8 +296,63 @@ class NativeDashboardSignInCoordinator(
        }
    }

-    private fun escapeHtml(value: String): String =
-        value.replace("&", "&amp;")
-            .replace("<", "&lt;")
-            .replace(">", "&gt;")
+    private fun callbackPageHtml(page: CallbackPage): String = """
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+          <meta name="color-scheme" content="dark">
+          <title>${page.title} · Hermes Relay</title>
+          <style>$CALLBACK_STYLE</style>
+        </head>
+        <body>
+          <main class="shell">
+            <section class="card ${page.modifier}" aria-labelledby="page-title" aria-describedby="page-message page-guidance">
+              <div class="status-rail" aria-hidden="true"></div>
+              <p class="brand">Hermes Relay</p>
+              <p class="eyebrow">${page.eyebrow}</p>
+              <h1 id="page-title" tabindex="-1">${page.title}</h1>
+              <p id="page-message" class="message">${page.message}</p>
+              <p id="page-guidance" class="guidance">${page.guidance}</p>
+              <a class="return-link" href="$NATIVE_SIGN_IN_RETURN_URI">Return to Hermes Relay</a>
+            </section>
+          </main>
+        </body>
+        </html>
+    """.trimIndent()
+
+    private companion object {
+        private val CALLBACK_STYLE = """
+            :root{color-scheme:dark;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#08090d;color:#f7f4ff}
+            *{box-sizing:border-box}
+            body{margin:0;min-height:100vh;min-height:100svh;background:#08090d}
+            .shell{min-height:100vh;min-height:100svh;display:grid;place-items:center;padding:max(24px,env(safe-area-inset-top)) max(20px,env(safe-area-inset-right)) max(24px,env(safe-area-inset-bottom)) max(20px,env(safe-area-inset-left))}
+            .card{position:relative;width:min(100%,460px);overflow:hidden;border:1px solid #2d2938;border-radius:18px;background:#111219;padding:32px 28px 28px;box-shadow:0 18px 48px rgba(0,0,0,.34);animation:card-in 220ms ease-out both}
+            .status-rail{position:absolute;inset:0 auto 0 0;width:4px;background:#9b6bf0}
+            .success .status-rail{background:#55d98b}.failure .status-rail{background:#ff7188}
+            .brand{margin:0 0 28px;color:#bba4f5;font-size:.78rem;font-weight:750;letter-spacing:.12em;text-transform:uppercase}
+            .eyebrow{margin:0 0 8px;color:#cac4d8;font-size:.9rem;font-weight:650}
+            h1{margin:0;color:#fff;font-size:clamp(1.8rem,8vw,2.45rem);font-weight:720;letter-spacing:-.035em;line-height:1.08;outline:none}
+            h1:focus-visible{outline:2px solid #9b6bf0;outline-offset:6px;border-radius:3px}
+            .message{margin:18px 0 0;color:#eeeaf7;font-size:1.04rem;line-height:1.6}
+            .guidance{margin:12px 0 0;color:#bdb7c9;font-size:.95rem;line-height:1.55}
+            .return-link{display:block;width:100%;margin-top:26px;border:1px solid #8c5ef0;border-radius:12px;background:#6b35e8;color:#fff;padding:13px 18px;font:inherit;font-weight:700;text-align:center;text-decoration:none;cursor:pointer}
+            .return-link:hover{border-color:#c4a8ff}.return-link:focus-visible{outline:3px solid #c4a8ff;outline-offset:3px}.return-link:active{background:#5d28d3}
+            @keyframes card-in{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:none}}
+            @media (prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;scroll-behavior:auto!important;transition:none!important}}
+            @media (max-width:380px){.card{padding:28px 22px 24px;border-radius:16px}}
+        """.trimIndent()
+
+        private fun cspHash(value: String): String = MessageDigest.getInstance("SHA-256")
+            .digest(value.toByteArray(Charsets.UTF_8))
+            .toByteString()
+            .base64()
+
+        private val CALLBACK_CSP = buildString {
+            append("default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; ")
+            append("img-src 'none'; connect-src 'none'; object-src 'none'; script-src 'none'; ")
+            append("style-src 'sha256-").append(cspHash(CALLBACK_STYLE)).append("'")
+        }
+    }
 }
@@ -0,0 +1,31 @@
+package com.hermesandroid.relay.network.upstream
+
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.contentOrNull
+
+/**
+ * Parse both upstream personality formats: the original prompt string and the
+ * structured form introduced for richer descriptions, tone, and style.
+ */
+internal fun parsePersonalityPrompts(personalities: JsonObject?): Map<String, String> =
+    personalities
+        ?.mapValues { (_, value) -> personalityPrompt(value) }
+        .orEmpty()
+
+private fun personalityPrompt(value: JsonElement): String = when (value) {
+    is JsonPrimitive -> value.contentOrNull.orEmpty()
+    is JsonObject -> listOfNotNull(
+        value.stringValue("system_prompt"),
+        value.stringValue("tone")?.let { "Tone: $it" },
+        value.stringValue("style")?.let { "Style: $it" },
+    ).joinToString("\n")
+    else -> ""
+}
+
+private fun JsonObject.stringValue(key: String): String? =
+    (this[key] as? JsonPrimitive)
+        ?.contentOrNull
+        ?.trim()
+        ?.takeIf { it.isNotBlank() }
@@ -0,0 +1,102 @@
+package com.hermesandroid.relay.network.upstream
+
+/** Canonical reasoning-effort values accepted by upstream Hermes. */
+object ReasoningEfforts {
+    const val DEFAULT = "medium"
+
+    val canonical: List<String> =
+        listOf("none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra")
+
+    fun normalize(value: String?): String {
+        val normalized = value?.trim()?.lowercase().orEmpty()
+        return normalized.takeIf { it in canonical } ?: DEFAULT
+    }
+}
+
+/** Provider/model capability row advertised by upstream `model.options`. */
+data class GatewayModelCapabilities(
+    /** Legacy capability flag. Null means the server did not advertise support either way. */
+    val reasoning: Boolean? = null,
+    /** Exact selectable values on newer servers. Null means use the canonical compatibility list. */
+    val reasoningEfforts: List<String>? = null,
+    /** Explicit false means the advertised list is advisory rather than selectable. */
+    val reasoningEffortsExact: Boolean? = null,
+)
+
+data class ReasoningEffortAvailability(
+    val supported: Boolean?,
+    val choices: List<String>,
+    val exact: Boolean,
+) {
+    fun accepts(effort: String): Boolean = supported != false && (!exact || effort in choices)
+}
+
+/** Exact provider/model identity to which a confirmed effort belongs. */
+data class ReasoningEffortIdentity(val provider: String, val model: String)
+
+/**
+ * Resolve the active provider/model's advertised reasoning contract.
+ *
+ * Older servers expose either no capability entry or only `reasoning: true`;
+ * those receive the full canonical compatibility list. An explicit false
+ * disables the control. A `reasoning_efforts` array is authoritative.
+ */
+fun resolveReasoningEffortAvailability(
+    providers: List<GatewayModelProvider>,
+    provider: String?,
+    model: String?,
+    relayCapabilities: Map<ReasoningEffortIdentity, GatewayModelCapabilities> = emptyMap(),
+): ReasoningEffortAvailability {
+    val normalizedProvider = provider?.trim().orEmpty()
+    val normalizedModel = model?.trim().orEmpty()
+    if (normalizedProvider.isEmpty() || normalizedModel.isEmpty()) {
+        return ReasoningEffortAvailability(
+            supported = null,
+            choices = ReasoningEfforts.canonical,
+            exact = false,
+        )
+    }
+    val providerRow = providers.firstOrNull {
+        it.slug.equals(normalizedProvider, ignoreCase = true)
+    }
+
+    val upstream = providerRow?.capabilities?.get(normalizedModel)
+        ?: providerRow?.capabilities?.entries?.firstOrNull {
+            it.key.equals(normalizedModel, ignoreCase = true)
+        }?.value
+    val identity = ReasoningEffortIdentity(
+        provider = normalizedProvider.lowercase(),
+        model = normalizedModel,
+    )
+    val relay = relayCapabilities[identity]
+
+    fun exactAvailability(capabilities: GatewayModelCapabilities): ReasoningEffortAvailability {
+        val choices = capabilities.reasoningEfforts.orEmpty()
+            .map { it.trim().lowercase() }
+            .filter { it in ReasoningEfforts.canonical }
+            .distinct()
+        return ReasoningEffortAvailability(
+            supported = capabilities.reasoning ?: choices.isNotEmpty(),
+            choices = choices,
+            exact = true,
+        )
+    }
+
+    // Contract precedence: authoritative upstream, authoritative Relay overlay,
+    // explicit upstream suppression, then compatibility fallback.
+    if (upstream?.reasoningEfforts != null && upstream.reasoningEffortsExact == true) {
+        return exactAvailability(upstream)
+    }
+    if (relay?.reasoningEfforts != null && relay.reasoningEffortsExact == true) {
+        return exactAvailability(relay)
+    }
+    if (upstream?.reasoning == false) {
+        return ReasoningEffortAvailability(supported = false, choices = emptyList(), exact = false)
+    }
+
+    return ReasoningEffortAvailability(
+        supported = upstream?.reasoning,
+        choices = ReasoningEfforts.canonical,
+        exact = false,
+    )
+}
@@ -0,0 +1,52 @@
+package com.hermesandroid.relay.network.upstream
+
+import com.hermesandroid.relay.data.ChatMessage
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+
+/**
+ * The publication boundary for Chat and Voice transcript rows.
+ *
+ * [ChatMessage.id] may change when the server adopts a client-created row,
+ * while [ChatMessage.uiKey] is that row's stable render identity. Every value
+ * emitted from this state therefore has exactly one row per render identity.
+ */
+internal class RenderedMessageState(initialValue: List<ChatMessage>) {
+    private val mutable = MutableStateFlow(normalizeRenderedMessages(initialValue))
+    val flow: StateFlow<List<ChatMessage>> = mutable.asStateFlow()
+
+    var value: List<ChatMessage>
+        get() = mutable.value
+        set(value) {
+            mutable.value = normalizeRenderedMessages(value)
+        }
+
+    fun update(transform: (List<ChatMessage>) -> List<ChatMessage>) {
+        mutable.update { current -> normalizeRenderedMessages(transform(current)) }
+    }
+}
+
+/**
+ * Coalesce aliases before they can escape to keyed Compose consumers.
+ *
+ * The first slot owns transcript position and the latest snapshot owns row
+ * state. This is the same ordering contract used for replayed server history.
+ */
+internal fun normalizeRenderedMessages(messages: List<ChatMessage>): List<ChatMessage> {
+    if (messages.size < 2) return messages
+
+    val firstSlotByUiKey = HashMap<String, Int>()
+    val normalized = ArrayList<ChatMessage>(messages.size)
+    for (message in messages) {
+        val existingSlot = firstSlotByUiKey[message.uiKey]
+        if (existingSlot == null) {
+            firstSlotByUiKey[message.uiKey] = normalized.size
+            normalized += message
+        } else {
+            normalized[existingSlot] = message
+        }
+    }
+    return if (normalized.size == messages.size) messages else normalized
+}
@@ -0,0 +1,25 @@
+package com.hermesandroid.relay.network.upstream
+
+internal const val SESSION_LIST_PAGE_LIMIT = 100
+internal const val SESSION_LIST_WINDOW_LIMIT = 200
+
+internal data class SessionListPage(
+    val limit: Int,
+    val offset: Int,
+)
+
+internal fun sessionListPages(requestedLimit: Int): List<SessionListPage> {
+    val window = requestedLimit.coerceIn(1, SESSION_LIST_WINDOW_LIMIT)
+    return buildList {
+        var offset = 0
+        while (offset < window) {
+            add(
+                SessionListPage(
+                    limit = minOf(SESSION_LIST_PAGE_LIMIT, window - offset),
+                    offset = offset,
+                ),
+            )
+            offset += SESSION_LIST_PAGE_LIMIT
+        }
+    }
+}
@@ -0,0 +1,78 @@
+package com.hermesandroid.relay.network.upstream
+
+import com.hermesandroid.relay.network.upstream.models.MessageItem
+import com.hermesandroid.relay.network.upstream.models.MessagePagination
+import kotlinx.coroutines.CancellationException
+
+/** Explicit transcript read intent for Hermes' bounded messages endpoint. */
+enum class SessionMessageLoadMode {
+    /** One bounded newest-first window, returned in chronological order. */
+    LATEST,
+
+    /** Every page, oldest first, subject to Android memory safety bounds. */
+    COMPLETE,
+}
+
+internal const val SESSION_MESSAGE_PAGE_SIZE = 500
+private const val MAX_COMPLETE_TRANSCRIPT_MESSAGES = 50_000
+private const val MAX_COMPLETE_TRANSCRIPT_PAYLOAD_CHARS = 32_000_000
+
+internal data class SessionMessagePageRequest(
+    val limit: Int = SESSION_MESSAGE_PAGE_SIZE,
+    val offset: Int = 0,
+    val order: String,
+)
+
+internal data class SessionMessagePage(
+    val messages: List<MessageItem>,
+    val pagination: MessagePagination?,
+    val payloadChars: Int,
+)
+
+internal class SessionTranscriptTooLargeException(message: String) : IllegalStateException(message)
+
+/** Shared API-server/dashboard pagination contract. Legacy unpaginated envelopes remain valid. */
+internal suspend fun loadSessionMessages(
+    mode: SessionMessageLoadMode,
+    fetchPage: suspend (SessionMessagePageRequest) -> Result<SessionMessagePage>,
+): Result<List<MessageItem>> {
+    return try {
+        val order = if (mode == SessionMessageLoadMode.LATEST) "latest" else "oldest"
+        val collected = ArrayList<MessageItem>()
+        var offset = 0
+        var payloadChars = 0L
+
+        while (true) {
+            val request = SessionMessagePageRequest(offset = offset, order = order)
+            val page = fetchPage(request).getOrThrow()
+            payloadChars += page.payloadChars
+            if (payloadChars > MAX_COMPLETE_TRANSCRIPT_PAYLOAD_CHARS) {
+                throw SessionTranscriptTooLargeException(
+                    "Session transcript exceeds Android's 32 MB safe-load limit",
+                )
+            }
+            if (collected.size + page.messages.size > MAX_COMPLETE_TRANSCRIPT_MESSAGES) {
+                throw SessionTranscriptTooLargeException(
+                    "Session transcript exceeds Android's 50,000-message safe-load limit",
+                )
+            }
+            collected += page.messages
+
+            if (mode == SessionMessageLoadMode.LATEST) break
+            // Older Hermes returned one unpaginated complete envelope. Never issue
+            // a speculative second request against that contract.
+            val pagination = page.pagination ?: break
+            val returned = pagination.returned ?: page.messages.size
+            if (page.messages.isEmpty() || returned < request.limit || page.messages.size < request.limit) break
+
+            val nextOffset = offset + page.messages.size
+            if (nextOffset <= offset) break
+            offset = nextOffset
+        }
+        Result.success(collected)
+    } catch (error: CancellationException) {
+        throw error
+    } catch (error: Throwable) {
+        Result.failure(error)
+    }
+}
@@ -21,16 +21,27 @@ import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.OkHttpClient
 import okhttp3.Request
+import okhttp3.RequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
 import okhttp3.Response
 import okhttp3.WebSocket
 import okhttp3.WebSocketListener
+import okio.BufferedSink
 import okio.ByteString
 import java.io.File
 import java.io.IOException
+import java.io.OutputStream
 import java.util.Base64
 import java.util.concurrent.TimeUnit

+internal fun standardHermesAudioUrl(
+    baseUrl: String,
+    path: String,
+    profile: String?,
+) = "$baseUrl$path".toHttpUrlOrNull()?.newBuilder()?.apply {
+    profile?.trim()?.takeIf { it.isNotBlank() }?.let { addQueryParameter("profile", it) }
+}?.build()
+
 /**
 * Standard (no-plugin) voice client — speaks the upstream **dashboard web
 * server** contract that hermes-desktop's voice mode uses:
@@ -51,11 +62,9 @@ class StandardHermesVoiceClient(
    private val context: Context,
    private val dashboardHttpClientProvider: (String) -> OkHttpClient,
    private val dashboardUrlProvider: () -> String?,
-    // Active chat profile name (null = default/launch). Sent DEFENSIVELY on
-    // /api/audio/speak: upstream `TTSSpeakRequest` is text-only and Pydantic
-    // ignores extra fields, so this is harmless today and forward-compatible if
-    // upstream ever adds profile-aware TTS. Until then, standard voice remains
-    // the host's global TTS (see VoiceViewModel's standard-voice profile notice).
+    // Active chat profile name (null = default/launch). Current upstream audio
+    // routes accept it as a query parameter so TTS, STT, streaming speech, and
+    // provider catalogs resolve through the same Hermes home as chat.
    private val profileProvider: () -> String? = { null },
    private val webSocketFactory: ((Request, WebSocketListener) -> WebSocket)? = null,
    private val json: Json = Json {
@@ -86,17 +95,18 @@ class StandardHermesVoiceClient(
        // malformed dashboard URL (a non-address pasted into that field, #131),
        // and this runs before executeJson()'s try/catch, so the throw would
        // escape withContext(IO) onto the calling coroutine and crash the app.
-        val httpUrl = "$baseUrl/api/audio/transcribe".toHttpUrlOrNull()
+        val httpUrl = dashboardAudioUrl(baseUrl, "/api/audio/transcribe")
            ?: return@withContext Result.failure(IOException("Hermes dashboard URL is not a valid address: $baseUrl"))

-        val dataUrl = buildAudioDataUrl(audioFile)
-        val payload = buildJsonObject {
-            put("data_url", dataUrl)
-            put("mime_type", mediaTypeForAudioFile(audioFile))
-        }
+        val mimeType = mediaTypeForAudioFile(audioFile)
        val request = Request.Builder()
            .url(httpUrl)
-            .post(json.encodeToString(JsonObject.serializer(), payload).toRequestBody(JSON_MEDIA))
+            // Stream the file through Base64 directly into OkHttp's sink. Building
+            // a JsonObject first retained the file bytes, a Base64 String, the JSON
+            // serializer's growing char buffer, and the final request bytes at the
+            // same time. A near-limit recording could therefore exhaust Android's
+            // 256 MB heap before the request reached the network (#271).
+            .post(standardHermesTranscriptionRequestBody(audioFile, mimeType))
            .header("Accept", "application/json")
            .build()

@@ -122,14 +132,11 @@ class StandardHermesVoiceClient(

        // See transcribe(): guard the throwing url(String) so a malformed
        // dashboard URL is a clean Result.failure, never a Main-thread crash.
-        val httpUrl = "$baseUrl/api/audio/speak".toHttpUrlOrNull()
+        val httpUrl = dashboardAudioUrl(baseUrl, "/api/audio/speak")
            ?: return@withContext Result.failure(IOException("Hermes dashboard URL is not a valid address: $baseUrl"))

        val payload = buildJsonObject {
            put("text", cleanText)
-            // Defensive only — upstream /api/audio/speak ignores it (text-only
-            // TTSSpeakRequest). Omitted for the default profile.
-            profileProvider()?.trim()?.takeIf { it.isNotBlank() }?.let { put("profile", it) }
        }
        val request = Request.Builder()
            .url(httpUrl)
@@ -176,6 +183,7 @@ class StandardHermesVoiceClient(
                baseUrl = baseUrl,
                ticket = ticket,
                path = "/api/audio/speak-stream",
+                profile = activeProfile(),
            ) ?: throw IOException("Could not build Hermes speech stream URL")
            val request = Request.Builder().url(websocketUrl).build()
            StandardHermesSpeechStream(
@@ -195,6 +203,12 @@ class StandardHermesVoiceClient(
    private fun dashboardBaseUrl(): String? =
        dashboardUrlProvider()?.trim()?.trimEnd('/')?.takeIf { it.isNotBlank() }

+    private fun activeProfile(): String? =
+        profileProvider()?.trim()?.takeIf { it.isNotBlank() }
+
+    private fun dashboardAudioUrl(baseUrl: String, path: String) =
+        standardHermesAudioUrl(baseUrl, path, activeProfile())
+
    private fun callClient(baseUrl: String): OkHttpClient =
        standardHermesDashboardAudioClient(dashboardHttpClientProvider(baseUrl))

@@ -244,12 +258,6 @@ class StandardHermesVoiceClient(
        return IOException(message)
    }

-    private fun buildAudioDataUrl(audioFile: File): String {
-        val mimeType = mediaTypeForAudioFile(audioFile)
-        val encoded = Base64.getEncoder().encodeToString(audioFile.readBytes())
-        return "data:$mimeType;base64,$encoded"
-    }
-
    private fun mediaTypeForAudioFile(file: File): String =
        when (file.extension.lowercase()) {
            "wav" -> "audio/wav"
@@ -294,6 +302,58 @@ class StandardHermesVoiceClient(
    }
 }

+/**
+ * JSON request body for upstream `/api/audio/transcribe`.
+ *
+ * The endpoint requires a Base64 data URL inside JSON rather than multipart
+ * upload. Encoding into [BufferedSink] keeps peak memory bounded by the copy
+ * buffer instead of materializing several 33+ MB representations at once.
+ */
+internal fun standardHermesTranscriptionRequestBody(
+    audioFile: File,
+    mimeType: String,
+): RequestBody {
+    val prefix = "{\"data_url\":\"data:$mimeType;base64,"
+    val suffix = "\",\"mime_type\":\"$mimeType\"}"
+    val contentType = "application/json".toMediaType()
+    val fileLength = audioFile.length()
+    val encodedLength = ((fileLength + 2L) / 3L) * 4L
+    val bodyLength = prefix.toByteArray(Charsets.UTF_8).size.toLong() +
+        encodedLength +
+        suffix.toByteArray(Charsets.UTF_8).size.toLong()
+
+    return object : RequestBody() {
+        override fun contentType() = contentType
+
+        override fun contentLength(): Long = bodyLength
+
+        override fun writeTo(sink: BufferedSink) {
+            sink.writeUtf8(prefix)
+            Base64.getEncoder().wrap(NonClosingSinkOutputStream(sink)).use { encoded ->
+                audioFile.inputStream().use { input ->
+                    input.copyTo(encoded)
+                }
+            }
+            sink.writeUtf8(suffix)
+        }
+    }
+}
+
+/** Lets the Base64 encoder finish padding without closing OkHttp's request sink. */
+private class NonClosingSinkOutputStream(
+    private val sink: BufferedSink,
+) : OutputStream() {
+    override fun write(value: Int) {
+        sink.writeByte(value)
+    }
+
+    override fun write(bytes: ByteArray, offset: Int, length: Int) {
+        sink.write(bytes, offset, length)
+    }
+
+    override fun close() = Unit
+}
+
 private class StandardHermesSpeechStream(
    private val request: Request,
    private val callbacks: VoiceSpeechStreamCallbacks,
@@ -142,6 +142,8 @@ data class SessionItem(
    val preview: String? = null,
    val model: String? = null,
    val source: String? = null,
+    /** Owning profile on the cross-profile `/api/profiles/sessions` endpoint. */
+    val profile: String? = null,
    @SerialName("started_at")
    @Serializable(with = FlexibleTimestampSerializer::class)
    val startedAt: Double? = null,
@@ -165,6 +167,9 @@ data class SessionItem(
    @SerialName("input_tokens") val inputTokens: Int? = null,
    @SerialName("output_tokens") val outputTokens: Int? = null,
    @SerialName("has_model_config") val hasModelConfig: Boolean = false,
+    /** Durable flags returned by current Dashboard and API-server session resources. */
+    val pinned: Boolean = false,
+    val archived: Boolean = false,
 ) {
    val resolvedLastActivity: Double?
        get() = lastActive ?: lastActivity ?: lastActivityAt ?: updatedAt
@@ -241,7 +246,16 @@ data class MessageListResponse(
    val items: List<MessageItem>? = null,
    val messages: List<MessageItem>? = null, // alternate key
    val data: List<MessageItem>? = null, // upstream /api/sessions/{id}/messages list envelope
-    val total: Int? = null
+    val total: Int? = null,
+    val pagination: MessagePagination? = null,
+)
+
+@Serializable
+data class MessagePagination(
+    val limit: Int? = null,
+    val offset: Int? = null,
+    val order: String? = null,
+    val returned: Int? = null,
 )

@Serializable
@@ -0,0 +1,181 @@
+package com.hermesandroid.relay.petdex
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.jsonPrimitive
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+
+class PetdexCatalogClient internal constructor(
+    private val fetcher: PetdexFetcher,
+    private val nowMs: () -> Long,
+) {
+    constructor() : this(SecurePetdexFetcher(), System::currentTimeMillis)
+
+    @Volatile
+    private var cached: CachedCatalog? = null
+
+    suspend fun fetchCatalog(forceRefresh: Boolean = false): List<PetdexPet> {
+        val now = nowMs()
+        cached?.takeIf { !forceRefresh && now - it.loadedAtMs < CACHE_TTL_MS }?.let { return it.pets }
+
+        val pets = runCatching {
+            val bytes = fetcher.fetch(V2_URL, MAX_V2_BYTES, PetdexRemoteKind.Catalog)
+            PetdexCatalogParser.parseV2(bytes.decodeToString())
+        }.getOrElse { v2Error ->
+            if (v2Error is CancellationException) throw v2Error
+            runCatching {
+                val bytes = fetcher.fetch(V1_URL, MAX_V1_BYTES, PetdexRemoteKind.Catalog)
+                PetdexCatalogParser.parseV1(bytes.decodeToString())
+            }.getOrElse { v1Error ->
+                if (v1Error is CancellationException) throw v1Error
+                throw PetdexException("Couldn't load the Petdex catalog.", v1Error).also {
+                    it.addSuppressed(v2Error)
+                }
+            }
+        }
+        cached = CachedCatalog(nowMs(), pets)
+        return pets
+    }
+
+    fun clearCache() {
+        cached = null
+    }
+
+    private data class CachedCatalog(val loadedAtMs: Long, val pets: List<PetdexPet>)
+
+    private companion object {
+        const val V2_URL = "https://petdex.dev/api/manifest/v2"
+        const val V1_URL = "https://petdex.dev/api/manifest"
+        const val CACHE_TTL_MS = 5 * 60 * 1000L
+        const val MAX_V2_BYTES = 4L * 1024 * 1024
+        const val MAX_V1_BYTES = 8L * 1024 * 1024
+    }
+}
+
+internal object PetdexCatalogParser {
+    private const val MAX_CATALOG_ITEMS = 10_000
+    private const val MAX_MANIFEST_FIELDS = 32
+    private const val MAX_FIELD_NAME_LENGTH = 64
+    private const val MAX_ROW_FIELDS = 32
+    private const val MAX_DISPLAY_NAME_LENGTH = 256
+    private const val MAX_KIND_LENGTH = 64
+    private const val MAX_CREATOR_LENGTH = 256
+    private const val MAX_ASSET_URL_LENGTH = 2_048
+    private val slugPattern = Regex("[a-z0-9][a-z0-9-]{0,127}")
+    private val json = Json { ignoreUnknownKeys = true }
+
+    fun parseV2(raw: String): List<PetdexPet> {
+        val manifest = json.decodeFromString(V2Manifest.serializer(), raw)
+        if (manifest.v != 2) throw PetdexException("Unsupported Petdex catalog version.")
+        if (manifest.pets.size > MAX_CATALOG_ITEMS) throw PetdexException("Petdex catalog has too many entries.")
+        if (manifest.fields.isEmpty() || manifest.fields.size > MAX_MANIFEST_FIELDS ||
+            manifest.fields.any { it.isBlank() || it.length > MAX_FIELD_NAME_LENGTH }
+        ) {
+            throw PetdexException("Petdex catalog has invalid fields.")
+        }
+        val fieldIndex = manifest.fields.withIndex().associate { it.value to it.index }
+        if (!fieldIndex.keys.containsAll(REQUIRED_V2_FIELDS)) {
+            throw PetdexException("Petdex catalog is missing required fields.")
+        }
+        val base = manifest.assetBase.toHttpUrlOrNull()
+            ?.takeIf { PetdexUrlPolicy.isTrusted(it.toString(), PetdexRemoteKind.Asset) }
+            ?: throw PetdexException("Petdex catalog has an untrusted asset base.")
+        return manifest.pets.mapNotNull row@{ row ->
+            if (row.size > MAX_ROW_FIELDS || row.size > manifest.fields.size) return@row null
+            fun value(name: String): String = fieldIndex[name]
+                ?.let(row::getOrNull)
+                ?.jsonPrimitive
+                ?.contentOrNull
+                .orEmpty()
+            buildPet(
+                slug = value("slug"),
+                displayName = value("displayName"),
+                kind = value("kind"),
+                submittedBy = value("submittedBy"),
+                spritesheetUrl = resolveAsset(base.toString(), value("spritesheet")),
+                petJsonUrl = resolveAsset(base.toString(), value("petJson")),
+                zipUrl = value("zip").takeIf(String::isNotBlank)?.let { resolveAsset(base.toString(), it) },
+            )
+        }
+    }
+
+    fun parseV1(raw: String): List<PetdexPet> {
+        val manifest = json.decodeFromString(V1Manifest.serializer(), raw)
+        if (manifest.pets.size > MAX_CATALOG_ITEMS) throw PetdexException("Petdex catalog has too many entries.")
+        return manifest.pets.mapNotNull { entry ->
+            buildPet(
+                slug = entry.slug,
+                displayName = entry.displayName,
+                kind = entry.kind,
+                submittedBy = entry.submittedBy.orEmpty(),
+                spritesheetUrl = entry.spritesheetUrl,
+                petJsonUrl = entry.petJsonUrl,
+                zipUrl = entry.zipUrl?.takeIf(String::isNotBlank),
+            )
+        }
+    }
+
+    private fun buildPet(
+        slug: String,
+        displayName: String,
+        kind: String,
+        submittedBy: String,
+        spritesheetUrl: String,
+        petJsonUrl: String,
+        zipUrl: String?,
+    ): PetdexPet? {
+        if (!slugPattern.matches(slug)) return null
+        if (displayName.length > MAX_DISPLAY_NAME_LENGTH || kind.length > MAX_KIND_LENGTH ||
+            submittedBy.length > MAX_CREATOR_LENGTH || spritesheetUrl.length > MAX_ASSET_URL_LENGTH ||
+            petJsonUrl.length > MAX_ASSET_URL_LENGTH || (zipUrl?.length ?: 0) > MAX_ASSET_URL_LENGTH
+        ) {
+            return null
+        }
+        if (!PetdexUrlPolicy.isTrusted(spritesheetUrl, PetdexRemoteKind.Asset)) return null
+        if (!PetdexUrlPolicy.isTrusted(petJsonUrl, PetdexRemoteKind.Asset)) return null
+        if (zipUrl != null && !PetdexUrlPolicy.isTrusted(zipUrl, PetdexRemoteKind.Asset)) return null
+        return PetdexPet(
+            slug = slug,
+            displayName = displayName.ifBlank { slug },
+            kind = kind.ifBlank { "pet" },
+            submittedBy = submittedBy,
+            spritesheetUrl = spritesheetUrl,
+            petJsonUrl = petJsonUrl,
+            zipUrl = zipUrl,
+        )
+    }
+
+    private fun resolveAsset(base: String, reference: String): String {
+        if (reference.isBlank()) return ""
+        val absolute = reference.toHttpUrlOrNull()
+        if (absolute != null) return absolute.toString()
+        return base.toHttpUrlOrNull()?.resolve(reference)?.toString().orEmpty()
+    }
+
+    private val REQUIRED_V2_FIELDS = setOf("slug", "displayName", "spritesheet", "petJson")
+}
+
+@Serializable
+private data class V2Manifest(
+    val v: Int,
+    val assetBase: String,
+    val fields: List<String>,
+    val pets: List<List<JsonElement>>,
+)
+
+@Serializable
+private data class V1Manifest(val pets: List<V1Pet> = emptyList())
+
+@Serializable
+private data class V1Pet(
+    val slug: String = "",
+    val displayName: String = "",
+    val kind: String = "",
+    val submittedBy: String? = null,
+    val spritesheetUrl: String = "",
+    val petJsonUrl: String = "",
+    val zipUrl: String? = null,
+)
@@ -0,0 +1,106 @@
+package com.hermesandroid.relay.petdex
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import okhttp3.HttpUrl
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import java.io.ByteArrayOutputStream
+import java.io.InputStream
+import java.util.concurrent.TimeUnit
+
+internal enum class PetdexRemoteKind { Catalog, Asset }
+
+internal fun interface PetdexFetcher {
+    suspend fun fetch(url: String, maxBytes: Long, kind: PetdexRemoteKind): ByteArray
+}
+
+internal object PetdexUrlPolicy {
+    private val catalogHosts = setOf("petdex.dev", "assets.petdex.dev")
+    private val assetHosts = setOf("assets.petdex.dev")
+
+    fun isTrusted(url: String, kind: PetdexRemoteKind): Boolean {
+        val parsed = url.toHttpUrlOrNull() ?: return false
+        if (!parsed.isHttps) return false
+        if (parsed.port != 443 || parsed.username.isNotEmpty() || parsed.password.isNotEmpty()) return false
+        val hosts = if (kind == PetdexRemoteKind.Catalog) catalogHosts else assetHosts
+        return parsed.host in hosts
+    }
+}
+
+internal class SecurePetdexFetcher(
+    client: OkHttpClient = OkHttpClient.Builder()
+        .connectTimeout(10, TimeUnit.SECONDS)
+        .readTimeout(60, TimeUnit.SECONDS)
+        .followRedirects(false)
+        .followSslRedirects(false)
+        .build(),
+) : PetdexFetcher {
+    private val http = client.newBuilder()
+        .followRedirects(false)
+        .followSslRedirects(false)
+        .build()
+
+    override suspend fun fetch(url: String, maxBytes: Long, kind: PetdexRemoteKind): ByteArray =
+        withContext(Dispatchers.IO) {
+            var current = trustedUrl(url, kind)
+            repeat(MAX_REDIRECTS + 1) { redirectCount ->
+                val request = Request.Builder()
+                    .url(current)
+                    .header("User-Agent", "Hermes-Relay-Android-Petdex")
+                    .get()
+                    .build()
+                http.newCall(request).execute().use { response ->
+                    if (response.code in 300..399) {
+                        if (redirectCount == MAX_REDIRECTS) throw PetdexException("Too many Petdex redirects.")
+                        current = redirectTarget(response, current, kind)
+                    } else {
+                        if (!response.isSuccessful) throw PetdexException("Petdex request failed (${response.code}).")
+                        return@withContext readBounded(
+                            response.body.byteStream(),
+                            response.body.contentLength(),
+                            maxBytes,
+                        )
+                    }
+                }
+            }
+            throw PetdexException("Too many Petdex redirects.")
+        }
+
+    private fun trustedUrl(raw: String, kind: PetdexRemoteKind): HttpUrl {
+        if (!PetdexUrlPolicy.isTrusted(raw, kind)) throw PetdexException("Untrusted Petdex URL.")
+        return raw.toHttpUrlOrNull() ?: throw PetdexException("Invalid Petdex URL.")
+    }
+
+    private fun redirectTarget(response: Response, current: HttpUrl, kind: PetdexRemoteKind): HttpUrl {
+        val location = response.header("Location") ?: throw PetdexException("Petdex redirect had no destination.")
+        val resolved = current.resolve(location) ?: throw PetdexException("Invalid Petdex redirect.")
+        return trustedUrl(resolved.toString(), kind)
+    }
+
+    private companion object {
+        const val MAX_REDIRECTS = 3
+    }
+}
+
+internal fun readBounded(input: InputStream, declaredLength: Long, maxBytes: Long): ByteArray {
+    if (declaredLength < -1L) throw PetdexException("Petdex response had an invalid length.")
+    if (maxBytes <= 0L || declaredLength > maxBytes) throw PetdexException("Petdex download is too large.")
+    val initial = when {
+        declaredLength in 1..maxBytes -> declaredLength.toInt()
+        else -> minOf(maxBytes, 32L * 1024L).toInt()
+    }
+    val out = ByteArrayOutputStream(initial)
+    val buffer = ByteArray(8 * 1024)
+    var total = 0L
+    while (true) {
+        val read = input.read(buffer)
+        if (read < 0) break
+        total += read
+        if (total > maxBytes) throw PetdexException("Petdex download is too large.")
+        out.write(buffer, 0, read)
+    }
+    return out.toByteArray()
+}
@@ -0,0 +1,256 @@
+package com.hermesandroid.relay.petdex
+
+import android.content.Context
+import android.graphics.BitmapFactory
+import com.hermesandroid.relay.ui.components.avatar.PetClipSpec
+import com.hermesandroid.relay.ui.components.avatar.PetLoader
+import com.hermesandroid.relay.ui.components.avatar.PetReactiveSpec
+import com.hermesandroid.relay.ui.components.avatar.PetSpec
+import com.hermesandroid.relay.ui.components.avatar.toAvatar
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+import java.util.UUID
+
+class PetdexInstaller internal constructor(
+    private val fetcher: PetdexFetcher,
+) {
+    constructor() : this(SecurePetdexFetcher())
+
+    suspend fun install(context: Context, pet: PetdexPet): PetdexInstallResult =
+        installTo(PetLoader.userDir(context), pet)
+
+    internal suspend fun installTo(petsDir: File, pet: PetdexPet): PetdexInstallResult = installMutex.withLock {
+        withContext(Dispatchers.IO) {
+            runCatching {
+                validateCatalogPet(pet)
+                val metadataBytes = fetcher.fetch(pet.petJsonUrl, MAX_METADATA_BYTES, PetdexRemoteKind.Asset)
+                val remoteMetadata = parseMetadata(metadataBytes)
+                val spriteBytes = fetcher.fetch(pet.spritesheetUrl, MAX_SPRITESHEET_BYTES, PetdexRemoteKind.Asset)
+                val image = inspectSpritesheet(spriteBytes)
+                val layout = PetdexAtlasLayout.fromDimensions(image.width, image.height)
+                    ?: throw PetdexException("That Petdex pet uses an unsupported spritesheet layout.")
+                val extension = image.extension
+                val spec = layout.toPetSpec(pet, remoteMetadata, "spritesheet.$extension")
+                installAtomically(petsDir, pet.installedAvatarId, spec, spriteBytes, extension)
+                PetdexInstallResult.Success(spec.id, spec.label)
+            }.getOrElse { error ->
+                if (error is CancellationException) throw error
+                PetdexInstallResult.Failure(error.message ?: "Couldn't install that Petdex pet.")
+            }
+        }
+    }
+
+    private fun validateCatalogPet(pet: PetdexPet) {
+        if (!PETDEX_SLUG.matches(pet.slug)) throw PetdexException("Invalid Petdex pet id.")
+        if (!PetdexUrlPolicy.isTrusted(pet.petJsonUrl, PetdexRemoteKind.Asset) ||
+            !PetdexUrlPolicy.isTrusted(pet.spritesheetUrl, PetdexRemoteKind.Asset)
+        ) {
+            throw PetdexException("Untrusted Petdex asset URL.")
+        }
+    }
+
+    private fun parseMetadata(bytes: ByteArray): PetdexMetadata {
+        val metadata = try {
+            json.decodeFromString(PetdexMetadata.serializer(), bytes.decodeToString())
+        } catch (t: Throwable) {
+            throw PetdexException("Petdex metadata isn't valid JSON.", t)
+        }
+        if (metadata.id.length > MAX_METADATA_ID_LENGTH ||
+            metadata.displayName.length > MAX_METADATA_NAME_LENGTH ||
+            metadata.description.length > MAX_METADATA_DESCRIPTION_LENGTH
+        ) {
+            throw PetdexException("Petdex metadata fields are too large.")
+        }
+        return metadata
+    }
+
+    private fun inspectSpritesheet(bytes: ByteArray): InspectedImage {
+        val extension = when {
+            bytes.hasPrefix(PNG_MAGIC) -> "png"
+            bytes.hasWebpMagic() -> "webp"
+            else -> throw PetdexException("Petdex spritesheet isn't PNG or WebP.")
+        }
+        val options = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)
+        if (options.outWidth <= 0 || options.outHeight <= 0) {
+            throw PetdexException("Petdex spritesheet couldn't be decoded.")
+        }
+        val pixels = options.outWidth.toLong() * options.outHeight.toLong()
+        if (pixels > MAX_SPRITESHEET_PIXELS) throw PetdexException("Petdex spritesheet is too large.")
+        return InspectedImage(options.outWidth, options.outHeight, extension)
+    }
+
+    private fun installAtomically(
+        petsDir: File,
+        avatarId: String,
+        spec: PetSpec,
+        spriteBytes: ByteArray,
+        extension: String,
+    ) {
+        petsDir.mkdirs()
+        val staging = File(petsDir, ".petdex-install-${UUID.randomUUID()}")
+        val backup = File(petsDir, ".petdex-backup-${UUID.randomUUID()}")
+        val target = File(petsDir, avatarId)
+        try {
+            check(staging.mkdir()) { "Couldn't prepare Petdex install." }
+            File(staging, "spritesheet.$extension").writeBytes(spriteBytes)
+            File(staging, "pet.json").writeText(json.encodeToString(spec))
+            spec.toAvatar(staging) // Validate the exact installed representation before swapping it in.
+
+            if (target.exists() && !target.renameTo(backup)) {
+                throw PetdexException("Couldn't replace the existing Petdex pet.")
+            }
+            if (!staging.renameTo(target)) {
+                if (backup.exists()) backup.renameTo(target)
+                throw PetdexException("Couldn't finish the Petdex install.")
+            }
+            backup.deleteRecursively()
+        } finally {
+            staging.deleteRecursively()
+            if (backup.exists() && !target.exists()) backup.renameTo(target)
+            if (backup.exists() && target.exists()) backup.deleteRecursively()
+        }
+    }
+
+    private data class InspectedImage(val width: Int, val height: Int, val extension: String)
+
+    private companion object {
+        val PETDEX_SLUG = Regex("[a-z0-9][a-z0-9-]{0,127}")
+        val PNG_MAGIC = byteArrayOf(0x89.toByte(), 0x50, 0x4E, 0x47)
+        const val MAX_METADATA_BYTES = 256L * 1024
+        const val MAX_METADATA_ID_LENGTH = 128
+        const val MAX_METADATA_NAME_LENGTH = 256
+        const val MAX_METADATA_DESCRIPTION_LENGTH = 4_096
+        const val MAX_SPRITESHEET_BYTES = 32L * 1024 * 1024
+        const val MAX_SPRITESHEET_PIXELS = 16L * 1024 * 1024
+        val installMutex = Mutex()
+        val json = Json {
+            ignoreUnknownKeys = true
+            prettyPrint = true
+        }
+    }
+}
+
+@Serializable
+internal data class PetdexMetadata(
+    val id: String = "",
+    val displayName: String = "",
+    val description: String = "",
+)
+
+internal data class PetdexAtlasLayout(
+    val columns: Int,
+    val rows: Map<String, Int>,
+    val frameCounts: Map<String, Int> = emptyMap(),
+) {
+    fun toPetSpec(pet: PetdexPet, metadata: PetdexMetadata, sheetName: String): PetSpec {
+        fun clip(rowName: String): PetClipSpec? = rows[rowName]?.let { row ->
+            val frameCount = frameCounts[rowName] ?: LEGACY_FRAMES_PER_STATE
+            val loopDurationMs = PETDEX_CURRENT_LOOP_DURATIONS_MS[rowName]
+                ?: LEGACY_LOOP_DURATION_MS
+            PetClipSpec(
+                sheet = sheetName,
+                frameWidth = FRAME_WIDTH,
+                frameHeight = FRAME_HEIGHT,
+                frameCount = minOf(frameCount, columns),
+                startFrame = row * columns,
+                fps = frameCount * 1000f / loopDurationMs,
+            )
+        }
+        requireNotNull(clip("idle"))
+        // Preserve the source atlas taxonomy. PetLoader owns the backwards-
+        // compatible semantic mapping from these upstream names to Android
+        // activity and locomotion, so directional travel rows are not discarded
+        // or confused with the in-place `running` agent-work row.
+        val states = rows.keys.mapNotNull { rowName ->
+            clip(rowName)?.let { rowName to it }
+        }.toMap()
+        return PetSpec(
+            schemaVersion = 1,
+            id = pet.installedAvatarId,
+            label = pet.displayName.ifBlank { metadata.displayName.ifBlank { pet.slug } },
+            description = metadata.description,
+            source = "petdex",
+            sourceUrl = pet.sourceUrl,
+            creator = pet.submittedBy,
+            reactive = PetReactiveSpec(voice = true, tools = true, intensity = false),
+            states = states,
+        )
+    }
+
+    companion object {
+        const val FRAME_WIDTH = 192
+        const val FRAME_HEIGHT = 208
+        private const val LEGACY_FRAMES_PER_STATE = 6
+        private const val LEGACY_LOOP_DURATION_MS = 1100f
+
+        private val CURRENT_ROWS = mapOf(
+            "idle" to 0,
+            "running-right" to 1,
+            "running-left" to 2,
+            "waving" to 3,
+            "jumping" to 4,
+            "failed" to 5,
+            "waiting" to 6,
+            "running" to 7,
+            "review" to 8,
+        )
+        private val LEGACY_ROWS = mapOf(
+            "idle" to 0,
+            "wave" to 1,
+            "run" to 2,
+            "failed" to 3,
+            "review" to 4,
+            "jump" to 5,
+        )
+
+        fun fromDimensions(width: Int, height: Int): PetdexAtlasLayout? = when {
+            width == 8 * FRAME_WIDTH &&
+                (height == 9 * FRAME_HEIGHT || height == 11 * FRAME_HEIGHT) ->
+                PetdexAtlasLayout(8, CURRENT_ROWS, PETDEX_CURRENT_FRAME_COUNTS)
+            width == 9 * FRAME_WIDTH && height == 8 * FRAME_HEIGHT -> PetdexAtlasLayout(9, LEGACY_ROWS)
+            else -> null
+        }
+    }
+}
+
+/** Canonical used cells in the current Codex/Petdex 8-column atlas. */
+internal val PETDEX_CURRENT_FRAME_COUNTS: Map<String, Int> = mapOf(
+    "idle" to 6,
+    "running-right" to 8,
+    "running-left" to 8,
+    "waving" to 4,
+    "jumping" to 5,
+    "failed" to 8,
+    "waiting" to 6,
+    "running" to 6,
+    "review" to 6,
+)
+
+/** Total authored duration of each current row; Android approximates variable frame timing with average fps. */
+internal val PETDEX_CURRENT_LOOP_DURATIONS_MS: Map<String, Float> = mapOf(
+    "idle" to 1100f,
+    "running-right" to 1060f,
+    "running-left" to 1060f,
+    "waving" to 700f,
+    "jumping" to 840f,
+    "failed" to 1220f,
+    "waiting" to 1010f,
+    "running" to 820f,
+    "review" to 1030f,
+)
+
+private fun ByteArray.hasPrefix(prefix: ByteArray): Boolean =
+    size >= prefix.size && prefix.indices.all { this[it] == prefix[it] }
+
+private fun ByteArray.hasWebpMagic(): Boolean =
+    size >= 12 &&
+        copyOfRange(0, 4).contentEquals("RIFF".encodeToByteArray()) &&
+        copyOfRange(8, 12).contentEquals("WEBP".encodeToByteArray())
@@ -0,0 +1,22 @@
+package com.hermesandroid.relay.petdex
+
+/** Public Petdex catalog entry. Installing is always an explicit user action. */
+data class PetdexPet(
+    val slug: String,
+    val displayName: String,
+    val kind: String,
+    val submittedBy: String,
+    val spritesheetUrl: String,
+    val petJsonUrl: String,
+    val zipUrl: String? = null,
+) {
+    val sourceUrl: String get() = "https://petdex.dev/pets/$slug"
+    val installedAvatarId: String get() = "petdex-$slug"
+}
+
+sealed interface PetdexInstallResult {
+    data class Success(val avatarId: String, val label: String) : PetdexInstallResult
+    data class Failure(val reason: String) : PetdexInstallResult
+}
+
+internal class PetdexException(message: String, cause: Throwable? = null) : Exception(message, cause)
@@ -0,0 +1,264 @@
+package com.hermesandroid.relay.plugins.document
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * A declarative Android surface supplied by a Hermes plugin.
+ *
+ * Documents contain no executable code, URLs, Android intents, or gateway calls. The host
+ * renders the bounded element vocabulary and decides how (or whether) to handle actions and
+ * asset references.
+ */
+@Serializable
+data class PluginDocument(
+    val schemaVersion: Int = CURRENT_SCHEMA_VERSION,
+    val pages: List<PluginPage>,
+    val initialState: Map<String, PluginValue> = emptyMap(),
+    /** Host-owned revision for generated pages; ordinary installed plugins may omit it. */
+    @SerialName("host_revision") val hostRevision: Int? = null,
+) {
+    companion object {
+        const val CURRENT_SCHEMA_VERSION = 1
+    }
+}
+
+@Serializable
+data class PluginPage(
+    val id: String,
+    val title: PluginText,
+    val content: PluginElement,
+)
+
+@Serializable
+sealed interface PluginValue {
+    @Serializable
+    @SerialName("string")
+    data class StringValue(val value: String) : PluginValue
+
+    @Serializable
+    @SerialName("boolean")
+    data class BooleanValue(val value: Boolean) : PluginValue
+
+    @Serializable
+    @SerialName("number")
+    data class NumberValue(val value: Double) : PluginValue
+
+    @Serializable
+    @SerialName("null")
+    data object NullValue : PluginValue
+}
+
+@Serializable
+sealed interface PluginText {
+    @Serializable
+    @SerialName("literal")
+    data class Literal(val value: String) : PluginText
+
+    @Serializable
+    @SerialName("binding")
+    data class Binding(
+        val key: String,
+        val fallback: String = "",
+    ) : PluginText
+}
+
+@Serializable
+sealed interface PluginCondition {
+    @Serializable
+    @SerialName("truthy")
+    data class Truthy(val key: String) : PluginCondition
+
+    @Serializable
+    @SerialName("equals")
+    data class Equals(val key: String, val value: PluginValue) : PluginCondition
+
+    @Serializable
+    @SerialName("not")
+    data class Not(val condition: PluginCondition) : PluginCondition
+
+    @Serializable
+    @SerialName("all")
+    data class All(val conditions: List<PluginCondition>) : PluginCondition
+
+    @Serializable
+    @SerialName("any")
+    data class Any(val conditions: List<PluginCondition>) : PluginCondition
+}
+
+@Serializable
+data class PluginAnimation(
+    val enter: PluginAnimationKind = PluginAnimationKind.NONE,
+    val change: PluginAnimationKind = PluginAnimationKind.NONE,
+    val speed: PluginAnimationSpeed = PluginAnimationSpeed.NORMAL,
+)
+
+@Serializable
+enum class PluginAnimationKind {
+    NONE,
+    FADE,
+    SCALE,
+    SLIDE_VERTICAL,
+    HIGHLIGHT,
+}
+
+@Serializable
+enum class PluginAnimationSpeed { FAST, NORMAL, SLOW }
+
+@Serializable
+data class PluginAction(
+    val id: String,
+    val arguments: Map<String, PluginValue> = emptyMap(),
+    val confirmation: PluginText? = null,
+    val request: PluginActionRequest? = null,
+)
+
+@Serializable
+data class PluginActionRequest(
+    val method: String = "POST",
+    val path: String,
+)
+
+@Serializable
+sealed interface PluginElement {
+    val id: String
+    val visibleWhen: PluginCondition?
+    val animation: PluginAnimation
+
+    @Serializable
+    @SerialName("group")
+    data class Group(
+        override val id: String,
+        val direction: PluginDirection = PluginDirection.COLUMN,
+        val children: List<PluginElement>,
+        val spacing: PluginSpacing = PluginSpacing.MEDIUM,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("card")
+    data class Card(
+        override val id: String,
+        val child: PluginElement,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("text")
+    data class Text(
+        override val id: String,
+        val text: PluginText,
+        val style: PluginTextStyle = PluginTextStyle.BODY,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("badge")
+    data class Badge(
+        override val id: String,
+        val text: PluginText,
+        val tone: PluginTone = PluginTone.NEUTRAL,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("button")
+    data class Button(
+        override val id: String,
+        val label: PluginText,
+        val action: PluginAction,
+        val style: PluginButtonStyle = PluginButtonStyle.PRIMARY,
+        val enabledWhen: PluginCondition? = null,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("text_input")
+    data class TextInput(
+        override val id: String,
+        val label: PluginText,
+        val binding: String,
+        val placeholder: PluginText? = null,
+        val maxLength: Int = DEFAULT_INPUT_LIMIT,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("toggle")
+    data class Toggle(
+        override val id: String,
+        val label: PluginText,
+        val binding: String,
+        val enabledWhen: PluginCondition? = null,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("progress")
+    data class Progress(
+        override val id: String,
+        val valueBinding: String? = null,
+        val value: Double? = null,
+        val label: PluginText? = null,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("image")
+    data class Image(
+        override val id: String,
+        val asset: PluginAssetReference,
+        val contentDescription: PluginText,
+        val aspectRatio: Float = 16f / 9f,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("divider")
+    data class Divider(
+        override val id: String,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    @Serializable
+    @SerialName("spacer")
+    data class Spacer(
+        override val id: String,
+        val size: PluginSpacing = PluginSpacing.MEDIUM,
+        override val visibleWhen: PluginCondition? = null,
+        override val animation: PluginAnimation = PluginAnimation(),
+    ) : PluginElement
+
+    companion object {
+        const val DEFAULT_INPUT_LIMIT = 2_000
+    }
+}
+
+/** An opaque, plugin-scoped asset id. The host resolves it; documents cannot supply URLs. */
+@Serializable
+data class PluginAssetReference(val id: String)
+
+@Serializable
+enum class PluginDirection { ROW, COLUMN }
+
+@Serializable
+enum class PluginSpacing { NONE, SMALL, MEDIUM, LARGE }
+
+@Serializable
+enum class PluginTextStyle { BODY, LABEL, TITLE, HEADLINE }
+
+@Serializable
+enum class PluginTone { NEUTRAL, INFO, SUCCESS, WARNING, DANGER }
+
+@Serializable
+enum class PluginButtonStyle { PRIMARY, SECONDARY, TEXT }
@@ -0,0 +1,183 @@
+package com.hermesandroid.relay.plugins.document
+
+data class PluginDocumentState(
+    val values: Map<String, PluginValue> = emptyMap(),
+) {
+    operator fun get(key: String): PluginValue = values[key] ?: PluginValue.NullValue
+
+    fun updated(key: String, value: PluginValue): PluginDocumentState =
+        copy(values = values + (key to value))
+
+    fun resolve(text: PluginText): String = when (text) {
+        is PluginText.Literal -> text.value
+        is PluginText.Binding -> this[text.key].displayString() ?: text.fallback
+    }
+
+    fun matches(condition: PluginCondition?): Boolean = when (condition) {
+        null -> true
+        is PluginCondition.Truthy -> this[condition.key].isTruthy()
+        is PluginCondition.Equals -> this[condition.key] == condition.value
+        is PluginCondition.Not -> !matches(condition.condition)
+        is PluginCondition.All -> condition.conditions.all(::matches)
+        is PluginCondition.Any -> condition.conditions.any(::matches)
+    }
+
+    companion object {
+        fun from(document: PluginDocument): PluginDocumentState =
+            PluginDocumentState(document.initialState)
+    }
+}
+
+fun PluginValue.displayString(): String? = when (this) {
+    is PluginValue.StringValue -> value
+    is PluginValue.BooleanValue -> value.toString()
+    is PluginValue.NumberValue -> value.toString().removeSuffix(".0")
+    PluginValue.NullValue -> null
+}
+
+fun PluginValue.isTruthy(): Boolean = when (this) {
+    is PluginValue.StringValue -> value.isNotBlank()
+    is PluginValue.BooleanValue -> value
+    is PluginValue.NumberValue -> value != 0.0 && !value.isNaN()
+    PluginValue.NullValue -> false
+}
+
+sealed interface PluginDocumentValidation {
+    data object Valid : PluginDocumentValidation
+    data class Invalid(val errors: List<String>) : PluginDocumentValidation
+}
+
+/** Rejects pathological or ambiguous documents before they reach Compose. */
+object PluginDocumentValidator {
+    const val MAX_PAGES = 32
+    const val MAX_ELEMENTS = 500
+    const val MAX_DEPTH = 16
+    const val MAX_CHILDREN = 100
+    const val MAX_TEXT_LENGTH = 16_000
+    const val MAX_STATE_ENTRIES = 250
+
+    private val safeIdentifier = Regex("^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+    fun validate(document: PluginDocument): PluginDocumentValidation {
+        val errors = mutableListOf<String>()
+        if (document.schemaVersion != PluginDocument.CURRENT_SCHEMA_VERSION) {
+            errors += "Unsupported schema version: ${document.schemaVersion}"
+        }
+        if (document.pages.isEmpty() || document.pages.size > MAX_PAGES) {
+            errors += "Document must contain 1..$MAX_PAGES pages"
+        }
+        if (document.initialState.size > MAX_STATE_ENTRIES) {
+            errors += "Initial state exceeds $MAX_STATE_ENTRIES entries"
+        }
+
+        val ids = mutableSetOf<String>()
+        var elements = 0
+        document.initialState.keys.forEach { validateIdentifier("state key", it, errors) }
+        document.pages.forEach { page ->
+            validateIdentifier("page id", page.id, errors)
+            validateText(page.title, errors)
+            walk(page.content, 1) { element, depth ->
+                elements += 1
+                if (depth > MAX_DEPTH) errors += "Element ${element.id} exceeds depth $MAX_DEPTH"
+                validateIdentifier("element id", element.id, errors)
+                if (!ids.add(element.id)) errors += "Duplicate element id: ${element.id}"
+                validateElement(element, errors)
+            }
+        }
+        if (elements > MAX_ELEMENTS) errors += "Document exceeds $MAX_ELEMENTS elements"
+        return if (errors.isEmpty()) PluginDocumentValidation.Valid
+        else PluginDocumentValidation.Invalid(errors.distinct())
+    }
+
+    private fun validateElement(element: PluginElement, errors: MutableList<String>) {
+        validateCondition(element.visibleWhen, errors)
+        when (element) {
+            is PluginElement.Group -> if (element.children.size > MAX_CHILDREN) {
+                errors += "Element ${element.id} exceeds $MAX_CHILDREN children"
+            }
+            is PluginElement.Card -> Unit
+            is PluginElement.Text -> validateText(element.text, errors)
+            is PluginElement.Badge -> validateText(element.text, errors)
+            is PluginElement.Button -> {
+                validateText(element.label, errors)
+                validateIdentifier("action id", element.action.id, errors)
+                element.action.arguments.keys.forEach { validateIdentifier("action argument", it, errors) }
+                element.action.confirmation?.let { validateText(it, errors) }
+                validateCondition(element.enabledWhen, errors)
+            }
+            is PluginElement.TextInput -> {
+                validateText(element.label, errors)
+                element.placeholder?.let { validateText(it, errors) }
+                validateIdentifier("binding", element.binding, errors)
+                if (element.maxLength !in 1..PluginElement.DEFAULT_INPUT_LIMIT) {
+                    errors += "Input ${element.id} has an invalid maxLength"
+                }
+            }
+            is PluginElement.Toggle -> {
+                validateText(element.label, errors)
+                validateIdentifier("binding", element.binding, errors)
+                validateCondition(element.enabledWhen, errors)
+            }
+            is PluginElement.Progress -> {
+                element.valueBinding?.let { validateIdentifier("binding", it, errors) }
+                element.label?.let { validateText(it, errors) }
+                if (element.value == null && element.valueBinding == null) {
+                    errors += "Progress ${element.id} needs a value or binding"
+                }
+                if (element.value != null && (!element.value.isFinite() || element.value !in 0.0..1.0)) {
+                    errors += "Progress ${element.id} value must be between 0 and 1"
+                }
+            }
+            is PluginElement.Image -> {
+                validateIdentifier("asset id", element.asset.id, errors)
+                validateText(element.contentDescription, errors)
+                if (!element.aspectRatio.isFinite() || element.aspectRatio !in 0.25f..4f) {
+                    errors += "Image ${element.id} has an invalid aspect ratio"
+                }
+            }
+            is PluginElement.Divider, is PluginElement.Spacer -> Unit
+        }
+    }
+
+    private fun validateCondition(condition: PluginCondition?, errors: MutableList<String>) {
+        when (condition) {
+            null -> Unit
+            is PluginCondition.Truthy -> validateIdentifier("condition key", condition.key, errors)
+            is PluginCondition.Equals -> validateIdentifier("condition key", condition.key, errors)
+            is PluginCondition.Not -> validateCondition(condition.condition, errors)
+            is PluginCondition.All -> condition.conditions.forEach { validateCondition(it, errors) }
+            is PluginCondition.Any -> condition.conditions.forEach { validateCondition(it, errors) }
+        }
+    }
+
+    private fun validateText(text: PluginText, errors: MutableList<String>) {
+        when (text) {
+            is PluginText.Literal -> if (text.value.length > MAX_TEXT_LENGTH) {
+                errors += "Text exceeds $MAX_TEXT_LENGTH characters"
+            }
+            is PluginText.Binding -> {
+                validateIdentifier("text binding", text.key, errors)
+                if (text.fallback.length > MAX_TEXT_LENGTH) {
+                    errors += "Text fallback exceeds $MAX_TEXT_LENGTH characters"
+                }
+            }
+        }
+    }
+
+    private fun validateIdentifier(label: String, value: String, errors: MutableList<String>) {
+        if (!safeIdentifier.matches(value)) errors += "Invalid $label: $value"
+    }
+
+    private fun walk(
+        element: PluginElement,
+        depth: Int,
+        visit: (PluginElement, Int) -> Unit,
+    ) {
+        visit(element, depth)
+        when (element) {
+            is PluginElement.Group -> element.children.forEach { walk(it, depth + 1, visit) }
+            is PluginElement.Card -> walk(element.child, depth + 1, visit)
+            else -> Unit
+        }
+    }
+}
@@ -0,0 +1,61 @@
+package com.hermesandroid.relay.plugins.runtime
+
+import com.hermesandroid.relay.network.upstream.DashboardApiClient
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.contentOrNull
+
+/**
+ * Discovers opt-in Android plugin surfaces through the vanilla upstream dashboard.
+ *
+ * The dashboard catalog is authoritative for plugin identity and active state. Only
+ * entries advertising a backend API are probed; a missing or malformed mobile manifest
+ * simply means that dashboard plugin has no Android surface.
+ */
+class PluginDiscoveryClient(
+    private val dashboard: DashboardApiClient,
+) {
+    suspend fun discover(): Result<List<DiscoveredAndroidPlugin>> = runCatching {
+        val catalog = dashboard.getJsonElement(CATALOG_PATH).getOrThrow() as? JsonArray
+            ?: error("Dashboard plugin catalog must be a JSON array")
+
+        catalog.mapNotNull(::parseCatalogEntry)
+            .mapNotNull { entry ->
+                val manifest = dashboard
+                    .getJsonObject("/api/plugins/${entry.id}/mobile/manifest")
+                    .getOrNull()
+                    ?: return@mapNotNull null
+                // The authenticated catalog supplies provenance. A backend document cannot
+                // claim another plugin's identity and inherit this plugin's namespace/grants.
+                if (manifest.string("id") != entry.id) return@mapNotNull null
+                DiscoveredAndroidPlugin(catalog = entry, manifest = manifest)
+            }
+    }
+
+    private fun parseCatalogEntry(element: kotlinx.serialization.json.JsonElement): AndroidPluginCatalogEntry? {
+        val root = element as? JsonObject ?: return null
+        val id = root.string("name") ?: return null
+        val exposesApi = root.boolean("has_api") == true || root.string("api") != null
+        if (!PluginIdentifiers.isValid(id) || !exposesApi) return null
+        return AndroidPluginCatalogEntry(
+            id = id,
+            label = root.string("label") ?: id,
+            description = root.string("description").orEmpty(),
+            version = root.string("version").orEmpty(),
+            icon = root.string("icon") ?: "Puzzle",
+            source = root.string("source").orEmpty(),
+        )
+    }
+
+    private fun JsonObject.string(key: String): String? =
+        (this[key] as? JsonPrimitive)?.contentOrNull?.trim()?.takeIf(String::isNotEmpty)
+
+    private fun JsonObject.boolean(key: String): Boolean? =
+        (this[key] as? JsonPrimitive)?.booleanOrNull
+
+    private companion object {
+        const val CATALOG_PATH = "/api/dashboard/plugins"
+    }
+}
@@ -0,0 +1,93 @@
+package com.hermesandroid.relay.plugins.runtime
+
+/** Host-stamped context for plugin UI. It is never accepted from plugin JSON. */
+data class PluginHostContext(
+    val connectionId: String,
+    val profileName: String?,
+    val sessionId: String?,
+) {
+    init {
+        require(connectionId.isNotBlank()) { "connectionId must not be blank" }
+        require(sessionId == null || sessionId.isNotBlank()) { "sessionId must be null or non-blank" }
+    }
+}
+
+enum class PluginLifecycleChange {
+    CONNECTED,
+    DISCONNECTED,
+    CONNECTION_CHANGED,
+    PROFILE_CHANGED,
+    SESSION_CHANGED,
+    UNCHANGED,
+}
+
+data class PluginLifecycleSnapshot(
+    val context: PluginHostContext?,
+    val generation: Long,
+    val changedAtEpochMillis: Long,
+    val lastChange: PluginLifecycleChange,
+)
+
+/**
+ * Tracks provenance changes independently from UI navigation.
+ *
+ * A connection or profile change invalidates catalog/page ownership. A session change is
+ * metadata-only: it updates the context available to the active surface without replacing the
+ * authenticated Dashboard client or discarding the catalog.
+ */
+class PluginLifecycleTracker(
+    private val clock: () -> Long = System::currentTimeMillis,
+) {
+    var snapshot: PluginLifecycleSnapshot = PluginLifecycleSnapshot(
+        context = null,
+        generation = 0,
+        changedAtEpochMillis = clock(),
+        lastChange = PluginLifecycleChange.UNCHANGED,
+    )
+        private set
+
+    fun update(next: PluginHostContext?): PluginLifecycleSnapshot {
+        val previous = snapshot.context
+        val change = when {
+            previous == next -> PluginLifecycleChange.UNCHANGED
+            previous == null && next != null -> PluginLifecycleChange.CONNECTED
+            previous != null && next == null -> PluginLifecycleChange.DISCONNECTED
+            previous?.connectionId != next?.connectionId -> PluginLifecycleChange.CONNECTION_CHANGED
+            previous?.profileName != next?.profileName -> PluginLifecycleChange.PROFILE_CHANGED
+            else -> PluginLifecycleChange.SESSION_CHANGED
+        }
+        if (change != PluginLifecycleChange.UNCHANGED) {
+            snapshot = PluginLifecycleSnapshot(
+                context = next,
+                generation = snapshot.generation + 1,
+                changedAtEpochMillis = clock(),
+                lastChange = change,
+            )
+        }
+        return snapshot
+    }
+}
+
+data class PluginCatalogPreview(
+    val context: PluginHostContext,
+    val pluginCount: Int,
+    val enabledPluginCount: Int,
+    val pageCount: Int,
+    val refreshedAtEpochMillis: Long,
+    val liveRefreshEnabled: Boolean,
+) {
+    init {
+        require(pluginCount >= 0 && enabledPluginCount in 0..pluginCount)
+        require(pageCount >= 0)
+    }
+}
+
+object PluginCatalogRefreshPolicy {
+    const val VISIBLE_REFRESH_INTERVAL_MILLIS: Long = 5_000L
+    const val MIN_PAGE_REFRESH_SECONDS: Int = 5
+    const val MAX_PAGE_REFRESH_SECONDS: Int = 300
+
+    fun pageRefreshIntervalMillis(requestedSeconds: Int?): Long? = requestedSeconds
+        ?.coerceIn(MIN_PAGE_REFRESH_SECONDS, MAX_PAGE_REFRESH_SECONDS)
+        ?.times(1_000L)
+}
@@ -0,0 +1,54 @@
+package com.hermesandroid.relay.plugins.runtime
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class AndroidPluginManifest(
+    @SerialName("schema_version") val schemaVersion: Int = 1,
+    val id: String,
+    @SerialName("display_name") val displayName: String? = null,
+    val description: String? = null,
+    val version: String? = null,
+    @SerialName("min_host_api") val minHostApi: Int = 1,
+    @SerialName("default_enabled") val defaultEnabled: Boolean = false,
+    val contributions: List<AndroidPluginContribution> = emptyList(),
+    @SerialName("requested_capabilities")
+    val requestedCapabilities: List<AndroidPluginCapabilityRequest> = emptyList(),
+    val updates: AndroidPluginUpdateSource? = null,
+)
+
+@Serializable
+data class AndroidPluginContribution(
+    val id: String,
+    val surface: String = "page",
+    val title: String,
+    val document: AndroidPluginDocumentEndpoint,
+    /** Optional host-rendered metadata used by Relay-generated declarative previews. */
+    val status: String? = null,
+    val lifecycle: String? = null,
+    val description: String? = null,
+    val revision: Int? = null,
+    val digest: String? = null,
+)
+
+@Serializable
+data class AndroidPluginDocumentEndpoint(
+    val method: String = "GET",
+    val path: String,
+)
+
+@Serializable
+data class AndroidPluginCapabilityRequest(
+    val id: String,
+    val reason: String,
+    val required: Boolean = false,
+)
+
+@Serializable
+data class AndroidPluginUpdateSource(
+    @SerialName("poll_seconds") val pollSeconds: Int? = null,
+)
+
+const val ANDROID_PLUGIN_HOST_API_VERSION: Int = 1
+const val PLUGIN_API_WRITE_CAPABILITY: String = "plugin.api.write"
@@ -0,0 +1,51 @@
+package com.hermesandroid.relay.plugins.runtime
+
+import kotlinx.serialization.json.JsonObject
+
+/** Upstream dashboard metadata for a plugin whose backend can expose a mobile surface. */
+data class AndroidPluginCatalogEntry(
+    val id: String,
+    val label: String,
+    val description: String,
+    val version: String,
+    val icon: String,
+    val source: String,
+)
+
+/**
+ * A mobile manifest with identity anchored to the authenticated dashboard catalog.
+ *
+ * [manifest] stays as JSON at this transport boundary. The renderer owns the versioned
+ * declarative document contract; the discovery layer must not let a manifest assert a
+ * different plugin identity or widen its API namespace.
+ */
+data class DiscoveredAndroidPlugin(
+    val catalog: AndroidPluginCatalogEntry,
+    val manifest: JsonObject,
+)
+
+/** Local preference scope. A null profile is the server-default profile context. */
+data class PluginScope(
+    val connectionId: String,
+    val profileName: String?,
+    val pluginId: String,
+) {
+    init {
+        require(connectionId.isNotBlank()) { "connectionId must not be blank" }
+        require(PluginIdentifiers.isValid(pluginId)) { "Invalid plugin id: $pluginId" }
+    }
+}
+
+data class PluginPreferenceState(
+    val enabled: Boolean = false,
+    val grants: Set<String> = emptySet(),
+    /** Distinguishes an explicit opt-out from a manifest's default enablement. */
+    val configured: Boolean = false,
+)
+
+/** Conservative identifier grammar shared by discovery, API routing, and persistence. */
+object PluginIdentifiers {
+    private val pattern = Regex("^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$")
+
+    fun isValid(value: String): Boolean = pattern.matches(value)
+}
@@ -0,0 +1,63 @@
+package com.hermesandroid.relay.plugins.runtime
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.booleanPreferencesKey
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringSetPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import com.hermesandroid.relay.data.AgentDisplay
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import java.security.MessageDigest
+
+/** Durable, local-only plugin enablement and permission grants. */
+class PluginPreferenceStore(
+    private val dataStore: DataStore<Preferences>,
+) {
+    constructor(context: Context) : this(context.pluginPreferencesDataStore)
+
+    fun state(scope: PluginScope): Flow<PluginPreferenceState> {
+        val suffix = scope.keySuffix()
+        val enabledKey = booleanPreferencesKey("enabled_$suffix")
+        val grantsKey = stringSetPreferencesKey("grants_$suffix")
+        return dataStore.data.map { preferences ->
+            PluginPreferenceState(
+                enabled = preferences[enabledKey] ?: false,
+                grants = preferences[grantsKey].orEmpty(),
+                configured = enabledKey in preferences,
+            )
+        }
+    }
+
+    suspend fun setEnabled(scope: PluginScope, enabled: Boolean) {
+        val key = booleanPreferencesKey("enabled_${scope.keySuffix()}")
+        dataStore.edit { preferences -> preferences[key] = enabled }
+    }
+
+    suspend fun setGrants(scope: PluginScope, grants: Set<String>) {
+        require(grants.none(String::isBlank)) { "Plugin grants must not be blank" }
+        val key = stringSetPreferencesKey("grants_${scope.keySuffix()}")
+        dataStore.edit { preferences -> preferences[key] = grants.toSortedSet() }
+    }
+
+    suspend fun clear(scope: PluginScope) {
+        val suffix = scope.keySuffix()
+        dataStore.edit { preferences ->
+            preferences.remove(booleanPreferencesKey("enabled_$suffix"))
+            preferences.remove(stringSetPreferencesKey("grants_$suffix"))
+        }
+    }
+
+    private fun PluginScope.keySuffix(): String {
+        val profileKey = AgentDisplay.profileSessionKey(profileName)
+        val material = "$connectionId\u0000$profileKey\u0000$pluginId"
+        return MessageDigest.getInstance("SHA-256")
+            .digest(material.toByteArray(Charsets.UTF_8))
+            .joinToString("") { byte -> "%02x".format(byte) }
+    }
+}
+
+internal val Context.pluginPreferencesDataStore: DataStore<Preferences>
+    by preferencesDataStore(name = "plugin_preferences")
@@ -0,0 +1,96 @@
+package com.hermesandroid.relay.plugins.runtime
+
+import com.hermesandroid.relay.network.upstream.DashboardApiClient
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import java.net.URLEncoder
+
+/**
+ * Namespace-confined access to one authenticated plugin backend.
+ *
+ * Callers provide path segments, never a URL. This rejects traversal and encoded path
+ * tricks before composing with [DashboardApiClient], while query values are encoded.
+ */
+class ScopedPluginApiClient(
+    private val pluginId: String,
+    private val dashboard: DashboardApiClient,
+) {
+    init {
+        require(PluginIdentifiers.isValid(pluginId)) { "Invalid plugin id: $pluginId" }
+    }
+
+    suspend fun get(
+        relativePath: String,
+        query: Map<String, String> = emptyMap(),
+    ): Result<JsonElement> = validateAndBuild(relativePath, query).fold(
+        onSuccess = { dashboard.getJsonElement(it) },
+        onFailure = { Result.failure(it) },
+    )
+
+    suspend fun post(relativePath: String, payload: JsonObject): Result<JsonObject> =
+        objectPath(relativePath).fold(
+            onSuccess = { dashboard.postJsonObject(it, payload) },
+            onFailure = { Result.failure(it) },
+        )
+
+    suspend fun put(relativePath: String, payload: JsonObject): Result<JsonObject> =
+        objectPath(relativePath).fold(
+            onSuccess = { dashboard.putJsonObject(it, payload) },
+            onFailure = { Result.failure(it) },
+        )
+
+    suspend fun patch(relativePath: String, payload: JsonObject): Result<JsonObject> =
+        objectPath(relativePath).fold(
+            onSuccess = { dashboard.patchJsonObject(it, payload) },
+            onFailure = { Result.failure(it) },
+        )
+
+    suspend fun delete(relativePath: String): Result<JsonObject> = objectPath(relativePath).fold(
+        onSuccess = { dashboard.deleteJsonObject(it) },
+        onFailure = { Result.failure(it) },
+    )
+
+    internal fun objectPath(relativePath: String): Result<String> =
+        validateAndBuild(relativePath, emptyMap())
+
+    private fun validateAndBuild(
+        relativePath: String,
+        query: Map<String, String>,
+    ): Result<String> = runCatching {
+        val trimmed = relativePath.trim()
+        require(trimmed.isNotEmpty()) { "Plugin API path must not be empty" }
+        require(!trimmed.startsWith('/') && !trimmed.endsWith('/')) {
+            "Plugin API path must be relative and have no empty segments"
+        }
+        require('?' !in trimmed && '#' !in trimmed && '\\' !in trimmed && '%' !in trimmed) {
+            "Plugin API path must contain only plain path segments"
+        }
+        val segments = trimmed.split('/')
+        require(segments.all(::isSafeSegment)) { "Invalid plugin API path: $relativePath" }
+
+        buildString {
+            append("/api/plugins/")
+            append(pluginId)
+            append('/')
+            append(segments.joinToString("/"))
+            if (query.isNotEmpty()) {
+                append('?')
+                append(
+                    query.entries.sortedBy { it.key }.joinToString("&") { (key, value) ->
+                        "${encode(key)}=${encode(value)}"
+                    },
+                )
+            }
+        }
+    }
+
+    private fun isSafeSegment(segment: String): Boolean =
+        segment.isNotEmpty() && segment != "." && segment != ".." && SEGMENT.matches(segment)
+
+    private fun encode(value: String): String =
+        URLEncoder.encode(value, Charsets.UTF_8.name()).replace("+", "%20")
+
+    private companion object {
+        val SEGMENT = Regex("^[a-zA-Z0-9._~-]+$")
+    }
+}
--- a/Show More
+++ b/Show More