# Android: coming back to the app restores the connection ## What this item changed Android app only. - `data/transport/ConnectionRecovery.kt` (new): `ForegroundAction` and the one pure `foregroundAction(state, confirmedAlive)` policy — `Idle` → leave alone (a deliberate Disconnect is the only way the client reaches Idle), `Connected` with a confirmed-alive socket → leave alone, `Connected` unconfirmed → reconnect, `Connecting`/`Disconnected` → reconnect. - `data/ForegroundReconnector.kt` (new): the one lifecycle-aware owner. It is created once with the Application and observes `ProcessLifecycleOwner`, never the Activity or the ViewModel (both recreated). On `ON_START` it applies the policy: a non-Connected state reconnects at once, and the reconnect cancels the client's pending backoff delay, so the operator never waits it out; a state that still claims `Connected` is first confirmed with the existing `ping`, bounded to 3 s, and the state is re-read afterwards (the socket's own failure callback can land while the check is in flight). - `PipelinesApplication.kt`: wires the owner to the process lifecycle; `confirmAlive` is `repository.ping()`, `reconnect` is `ServerUrl.validate(...) + repository.recover(...)`. Recovery shares the client's state lock with Disconnect, so a Disconnect after the probe has made its decision but before its reconnect effect runs stays authoritative. Manual Connect/Reconnect continue to use `repository.connect(...)`; the client's bounded backoff stays the only reconnect mechanism and the policy lives in the one pure place. - `data/transport/PipelinesClient.kt`: `open()` now closes the socket it supersedes, and every `WebSocketListener` callback ignores a socket that is no longer the current one (`isCurrent`). A failure the replaced socket reports late — the common case when the process was frozen while it died — can then neither clear the new connection nor schedule a reconnect that would undo the recovery. - `app/build.gradle.kts` and `gradle/libs.versions.toml`: `androidx.lifecycle:lifecycle-process` 2.8.7 (already in the offline cache, with its `androidx.startup`/`androidx.tracing` transitives). - Tests: `data/transport/ConnectionRecoveryTest.kt` (5 cases) and `data/ForegroundReconnectorTest.kt` (8 cases). ## Shared documents this change makes stale `android/README.md`. - The Configuration section (`android/README.md:99-101`) — "Tap **Connect** to open the single shared WebSocket (probed with `ping`, showing the server build). Reconnect uses bounded exponential backoff; **Disconnect** stops it." — should record that coming back to the app restores the connection on its own: the process coming to the front reconnects immediately, cancelling the pending backoff delay, and when the last state still claims Connected it first confirms the socket with `ping` before trusting it. An explicit Disconnect stays authoritative and is never reconnected over; the manual Reconnect control stays, but normal recovery never needs it. - The Architecture block (`android/README.md:310-323`) lists `data/transport` and `data`. It should name the two new files — `data/transport/ConnectionRecovery.kt` (the pure return-to-foreground policy) and `data/ForegroundReconnector.kt` (the process-lifecycle owner) — and the new `androidx.lifecycle:lifecycle-process` dependency behind the owner. ## Not stale - `android/AGENTS.md` names neither the presence nor the absence of a lifecycle observer; its "Where things are" summary stays correct (it could optionally add the new owner beside `data/PipelinesRepository.kt`). - `docs/app-integration-verification.md` — its connection mentions are about restoring the stub URL, which this item does not change. - No packaged OpenCode skill reference (`internal/author/skill/references/`) documents the app's connection lifecycle, so nothing there is stale. ## Verified on the device, and what was not Built and captured on the operator's Pixel 9 Pro XL (`47241FDAS00DLK`) from `51a2ba4` + this change; after merging main the same tree (now `b93eee2`) was rebuilt and the full unit suite re-run (691 tests, 0 failures). The operator's `ws://10.0.0.75:8080/connect` and `/Users/alan/repos/pipelines` were used throughout and were not changed. The phone was left on main's build. Captured, all with `android/scripts/capture_png.sh` (every image validated): - a **live** socket on return: the server log shows a `ping`/`pong` on the same connection at the second of the return and no reconnect — the positive check runs and a healthy connection is left alone; - a **dead** socket on return: the reconnect and re-subscribe land in the same second as the return, with no interaction (the process was frozen, so the client's own backoff had not run); - **no network** on return: the banner reads "Disconnected: Failed to connect to …:8080 · retrying with backoff" — never a false Connected — and recovery follows on its own once the network returns; - an explicit **Disconnect**: still "Not connected. Enter the server URL in Settings, then connect." after returning, with no reconnect in the server log. **Not verified live:** the stale-Connected probe branch. In every capture the frozen socket's own failure was delivered to the client before the lifecycle owner ran, so the client already read `Disconnected` and no probe was attempted (confirmed by the client's request-id sequence never skipping a value in the server log). That branch — `Connected` still claimed, probe fails, reconnect — is covered by unit tests only.