archy/docs/HANDOFF-2026-07-23-companion-apk-deploy.md

# HANDOFF — deploy companion APK 0.5.1 (vc21) to nodes

**For: the agent on archi-dev-box.** User-reported failure this evening:
pairing flow on Framework PT — downloaded the companion from the node's
QR, then the pairing scan didn't work. The APK the node serves predates
today's scanner fixes; the pipeline below gets the fixed build into the
user's hands.

## What changed on main today (all merged)

- **Pairing-scanner fix** (`QrScannerOverlay.kt`): ZXing decode attempts are
  frame-gated (~7/s, was every frame — the CPU contention made the preview
  stutter badly enough to never decode) and PreviewView uses TextureView (no
  more black flash on open). This is the likely fix for "doesn't scan".
- Three-finger menu gesture (was two-finger, collided with scroll) + one-time
  teaching overlay ~2 min after login.
- Native wallet QR scanner behind `window.ArchipelagoQr` + WebView file-chooser
  support; web scan modal hands live scanning to it.
- npub-keyed saved servers (pairing contract item 1, PR #106).
- Served APK refreshed: `neode-ui/public/packages/archipelago-companion.apk`
  is now **0.5.3 / versionCode 23**. On top of the 0.5.1 scanner fixes it
  guarantees dual-path peering — the node's LAN endpoint (direct p2p, npub-
  keyed dial hints) AND the Archipelago public anchor (vps2, baked into the
  app so even an old node's QR can't leave the phone LAN-only) — and fixes
  the two field failures from the user's 5G test (screenshots, 21:54):
  - **Mesh VPN no longer kills the phone's internet** — the IPv6-only TUN
    never called `allowFamily(AF_INET)`, so Android blocked all IPv4 while
    the mesh was up. Now allowed (+ `allowBypass`).
  - **Off-LAN connect works** — `connect()` no longer hard-fails when the
    scanned LAN IP doesn't answer; it brings the mesh up and probes the
    node's ULA (`meshIp`) with retries before reporting failure.

## What to do

1. Redeploy the web-ui bundle from current main to the active nodes —
   web root `/opt/archipelago/web-ui/` (NOT a neode-ui/ subfolder), all
   nodes the user pairs against, at minimum the one Framework PT scans.
2. Verify the served artifact really updated:
   `curl -sI http://<node>/packages/archipelago-companion.apk` — size should
   change (~27 MB build of 2026-07-23), or pull it and check
   `aapt dump badging` shows `versionCode='21' versionName='0.5.1'`.
3. The demo stack gets its images from CI (run 100 pushed today with the new
   web bundle) — confirm the Portainer stack re-pulled, or trigger its
   redeploy, so the demo QR also serves vc21.
4. **Node side is half the 5G story**: away-from-home reachability needs the
   NODE connected to the public anchor too. On Framework PT (and any test
   node): deploy current main (node-side npub-first `fips.pair-info`), then
   verify `sudo -n fipsctl show status` reports the anchor connected —
   `fips.reconnect` RPC if not. A phone can dial the anchor perfectly and
   still fail if the node never enrolled with it.
5. Re-test the user's exact flows with **vc24** (updates any older install in
   place): (a) pair ON the LAN, then switch the phone to 5G — the UI must
   come up via the mesh ULA; (b) pair while ALREADY on 5G (never on the
   node's LAN) — scan, VPN consent, and the connect must succeed through
   the anchor.

## Live diagnosis update (22:30–22:50, phone on adb — Mac agent)

vc23 on-device testing found and fixed the phone-side blocker, and narrowed
what remains to the node side. State as of vc24:

- **Fixed: TUN reader died at startup.** Android hands the VpnService fd over
  non-blocking; the fips fork's blocking reader thread treats EAGAIN as fatal
  ("TUN read error … Try again (os error 11)") — so mesh sessions came up but
  NO packet ever entered the tunnel. archy-fips-core now forces the fd
  blocking before `start_with_tun_fd`. Verified on-device: reader survives,
  and the 30s anchor-link flap disappeared with it (stable 8+ min on 5G).
- **Fixed: VPN marked not-metered** (`setMetered(false)`) — Android 10+
  defaults VPNs to metered, putting the phone into data-restricted behaviour
  while the mesh is up. Note the user's phone also has system **always-on
  VPN** enabled for the app (`always_on_vpn_app`), a Settings-side toggle.
- **Verified good on-device**: peer store has node (LAN udp/tcp hints) + vps2
  anchor; saved server is npub-keyed with ULA; anchor session establishes
  from 5G in ~6s; VPN is bypassable, VALIDATED, only fd00::/8 routed.
- **REMAINING BLOCKER (node side)**: from the phone (app uid), ping6 and
  HTTP to the node's ULA `fd79:1aa:b9e9:4c9f:1f80:5376:9385:1824` get no
  reply — packets enter the mesh, nothing returns. Phone↔anchor works, so
  suspect phone-fork ↔ node-daemon session/routing mismatch (FIPS wire
  format is not stable across revs; phone pins fips-native fork 46494a74).
  From Framework PT please capture:
    - `fipsctl show status` (daemon version + anchor state)
    - `fipsctl show sessions` and `show bloom` while the phone pings
    - `ping6 <phone ULA fd68:496d:fe34:a06d:cf1:6e4:b6a4:3586>` from the
      node (tests the reverse path)
    - `ip addr show fips0` + confirm the web server listens on `[::]:80`
  Report whether the node ever sees a session attempt from
  `npub132c5whrsa6ccs0eylcpzaejq9uxul5ldvczz0axq78dh7fxkqj9st4uvzu`.

## Node-side diagnosis complete (23:00–23:30, archi-dev-box agent)

Chain of findings, each verified live:

1. **FIXED: nginx had no IPv6 listener anywhere** — every shipped config
   listened on 0.0.0.0 only, so `http://[<ULA>]` could NEVER connect on any
   node, ever. Live-fixed on framework-pt + .116, canonical conf + bootstrap
   self-heal shipped (`1e89362e`), heal binary deployed. ULA HTTP verified
   answering on both nodes (local + over-mesh).
2. Firewall clean, fd00::/8 routes correct both ends, wire compat proven
   (node + vps2 anchor both run fips 0.4.1 rev 15db6471db — the latest
   upstream stable; nothing newer exists).
3. **THE REMAINING PROBLEM IS MESH SESSION PATH QUALITY.** From the vps2
   anchor — a DIRECT connected peer — `GET /health` on the node's ULA takes
   **15–17 s per request and intermittently fails outright** (nginx logs
   show 499 client-gave-up then 200; TCP SYN-retransmit backoff signature).
   Session MMP is wildly asymmetric: node→vps2 srtt 204 ms, **vps2→node
   srtt 4270 ms** — on a direct link whose raw RTT is 4 ms. Session traffic
   is not riding the direct link; it appears to route through the ~1271-node
   public tree (node's tree root is the public 00001a8c, depth 8; the node's
   log also shows chronic "Discovery lookup timed out" for other targets).
4. The phone's npub never appears in the node's sessions — consistent with
   discovery/handshake dying on the same degraded tree path, and the app's
   ~8 s probe window being far smaller than the observed 15 s+ first-request
   latency even on the GOOD path.

### Recommendations

- **App side (Mac agent):** widen the ULA probe/connect window to ≥30 s
  with retransmit-friendly pacing, and PRE-WARM the mesh session (start
  pinging the node ULA as soon as the VPN is up, decoupled from the UI
  probe) so the WebView hits a warm session.
- **Infra decision (user):** consider detaching the fleet from the public
  v0l mesh — private tree rooted at the vps2 anchor (drop the legacy
  185.18.221.160 seed anchor fleet-wide AND vps2's public peering). A
  2-hop private tree would make session paths ride the direct links and
  should collapse latency to ms. Trade-off: no reachability to/from the
  broader public mesh.
- **Upstream:** report the direct-peer session-path asymmetry to
  jmcorgan/fips (0.4.1).

## App-side recommendations implemented (23:30–23:50, Mac agent — 0.5.5/vc25)

- Connect probe: mesh ULA now probed inside a **60s budget** with 15s
  per-phase timeouts (rides out TCP retransmit backoff), replacing the old
  ~8s window.
- **Session pre-warm**: the VPN service starts probing every saved node ULA
  the moment the tunnel is up (5s cadence for the first minute, then a 60s
  keep-warm tick) — discovery/handshake cost is paid in the background, and
  the session never idles out while the mesh is connected.
- Extra evidence for the infra decision: from the phone on 5G, a 25-packet
  ping burst to the node's ULA (25s continuous traffic, post-nginx-fix)
  still got **zero replies** — discovery through the public tree isn't just
  slow, it's failing outright. The private-tree option (detach fleet from
  the public v0l mesh, root at vps2) looks like the real fix; app-side
  patience only helps once discovery succeeds at all.