feat: add local-first gateway routing

docs/BLOCKERS.md

@@ -0,0 +1,9 @@
+# Hermes Mobile Blockers
+
+## Stable gateway identity binding
+
+The documented direct gateway routes currently available to Hermes Mobile (`GET /health` and authenticated `GET /v1/models`) do not expose a verified stable gateway instance identifier.
+
+B2 therefore protects local-first routing by requiring explicit HTTPS URLs, disabling redirects and cleartext traffic, probing `/health` without credentials, and sending a bearer token only for the documented `/v1/models` compatibility check. This confirms TLS reachability and authenticated API compatibility, but it cannot cryptographically prove that separately configured Local and Remote URLs terminate at the same Hermes gateway identity.
+
+Upstream compatibility needed for stronger binding: a documented stable gateway instance ID signed or authenticated consistently across both routes, or an upstream-supported certificate/public-key pin that the Android client can bind to the single logical profile. Until then, Local and Remote pairing remains an explicit user trust decision and diagnostics identify only the active route, not internal URLs.

docs/DIRECT_GATEWAY_ARCHITECTURE.md

@@ -57,9 +57,32 @@ Android contracts may model these needs, but implementation must keep them capab
 - The transport/domain model exposes direct gateway capabilities first. `legacyCompanionAdapter` exists only to identify old adapters during migration.
 - Backend behavior belongs upstream in Hermes Agent. Hermes Mobile may add client adapters and mappers, not server-side replacements.
 
+## Local-first gateway routing
+
+A server profile can contain two URLs for the **same Hermes gateway identity**:
+
+- **Local URL** — preferred when the phone can safely reach the gateway on the home/LAN (for example, `https://hermes.home.arpa`).
+- **Remote URL** — fallback when local reachability is unavailable (for example, a configured public HTTPS hostname).
+
+The client must choose automatically per connection attempt:
+
+1. If a local URL is configured, probe its documented `GET /health` endpoint using a short, bounded timeout.
+2. Use the local URL when the probe succeeds and the gateway identity/auth contract is compatible.
+3. Otherwise immediately use the configured remote URL; never leave chat blocked waiting for LAN discovery.
+4. Re-evaluate on app foreground, explicit reconnect, connectivity changes, and after a failed active request. Do not switch a request mid-stream.
+5. Show the active route (`Local` or `Remote`) in connection diagnostics, but do not expose bearer tokens or internal host details in message content/logs.
+
+Security and reliability rules:
+
+- Local and remote URLs are explicit user configuration, not guessed IP ranges or silently discovered devices in the MVP.
+- Both routes must use HTTPS by default and must be treated as the same intended gateway only after an authenticated compatibility check. The app must not silently send a bearer token to an arbitrary captive portal or unrelated LAN host.
+- Remote is a fallback, not a duplicate profile. User preferences, selected session state, and credentials stay associated with one logical gateway profile.
+- A later milestone may add opt-in mDNS/QR setup, certificate pinning/identity binding, and richer connectivity observation only after direct-gateway basics are verified.
+- The current upstream identity-binding limitation and the stronger contract needed are tracked in `docs/BLOCKERS.md`.
+
 ## Android Contract Milestones
 
-1. Auth and connection: validate URL, store bearer tokens securely, probe `GET /health`, and use `GET /v1/models` as the first authenticated check.
+1. Auth and connection: validate local + remote URLs, store bearer tokens securely, probe `GET /health`, use `GET /v1/models` as the first authenticated check, and make local-first fallback observable/retryable.
 2. Sessions: keep repository interfaces for list/create/select/continue, but mark route mapping provisional until upstream session docs are verified.
-3. Streaming: support final response and token delta reduction now; gate structured tool/artifact/session events behind server capabilities.
+3. Streaming: support final response and token delta reduction now; gate structured tool/artifact/session events behind server capabilities. Keep each stream bound to its selected local or remote route.
 4. Companion removal: after direct gateway chat/session/streaming works end to end, remove legacy companion UI routes and then deprecate install/docs around `apps/companion`.

docs/ROADMAP.md

@@ -6,7 +6,9 @@ Status: in progress. Android foundation work is complete, and the beta path now
 
 Done:
 - Native Kotlin/Compose Android shell replaces the web-first mobile path for the beta surface.
-- Android connection flow stores a gateway URL and bearer token locally, validates URL/auth state, and surfaces offline/unauthorized/retry states in-app.
+- Android connection flow stores one logical gateway profile with optional Local HTTPS, required Remote HTTPS, Android-keystore-protected bearer/no-auth configuration, and active Local/Remote diagnostics.
+- Local-first route selection uses bounded `GET /health` probes, authenticated `GET /v1/models` compatibility checks, deterministic Remote fallback, and foreground/connectivity/request-failure re-evaluation without switching in-flight leases.
+- Android no longer calls undocumented legacy companion `/api/*` routes from the direct-gateway client path.
 - Chat UI supports conversation list/thread navigation, native composer, busy state, selectable replies, error bubbles, and new-chat reset.
 - Direct gateway compatibility contract is documented in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.
 - Legacy companion chat, terminal, and file utilities remain in the repo during migration but are not the target architecture.
@@ -14,9 +16,9 @@ Done:
 - Companion and workspace TypeScript typecheck, build, and lint pass as of 2026-07-24.
 
 Remaining for beta:
-- Android debug build validation passed on 2026-07-24: `GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:assembleDebug` from `apps/mobile/android`.
+- Exercise the connection/settings unhappy paths on a real device or emulator; this sandbox cannot start ADB because local control sockets are prohibited.
 - Exercise a real device or emulator against a running upstream Hermes gateway/API server.
-- Verify direct gateway behavior end to end: bearer auth, `GET /health`, `GET /v1/models`, chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.
+- Verify direct gateway behavior end to end beyond B2: chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.
 - Verify or revise provisional session, streaming, tool-event, artifact, and cancellation route assumptions against official upstream docs.
 - Add or run focused Android UI validation for chat/settings flows on small and large screens.
 - Confirm adaptive accessibility: font scaling, TalkBack labels, contrast, keyboard/IME behavior, and reduced-motion tolerance.