tutti/docs/conventions/troubleshooting/mobile.md

# Mobile Troubleshooting

## Android stays on “Syncing the latest data” after pairing

- **Symptom:** Device pairing and the direct DeviceLink handshake succeed, but
  the mobile App remains on **Syncing the latest data**. The native log repeats
  `Agent live stream rejected`, often once per retry interval.
- **Quick checks:** Correlate the pairing ID and workspace across the phone and
  computer logs. If DeviceLink reaches its connected stage and the Agent live
  rejection reports `protocol_revision_mismatch`, compare the safe
  `expectedRevision` and `receivedRevision` hashes. This is a protocol
  compatibility failure, not a local-network or pairing failure.
- **Root cause:** The computer rejects an Agent live subscription whose protocol
  revision does not match its own. If the native rejection is collapsed into a
  generic disconnect, the live lane treats a deterministic incompatibility as
  transient and retries forever. Repeated disconnect callbacks can also keep
  replacing the connection-ready deadline, so the App never reaches a visible
  failed state.
- **Fix:** Preserve the typed rejection reason and revision hashes through the
  native bridge. Classify `protocol_revision_mismatch` as terminal for the
  current connection attempt, close the rejected subscription without
  scheduling another live retry, and keep the original synchronization
  deadline for retryable transport failures. Present an explicit incompatible
  version message with a mobile update action; do not automatically restart a
  terminal attempt after foreground resume.
- **Validation:** Verify an ordinary stream close still retries and rebuilds
  DeviceLink after the recovery grace period. Inject a protocol-revision
  rejection and assert that the connection enters the failed state once, emits
  a `device_connection.phase_changed` diagnostic with stable
  `protocol_revision_mismatch`, preserves both revision hashes, schedules no
  additional subscription, and stays terminal across background and foreground
  transitions. Confirm the failure UI offers **Check for updates** instead of
  **Reconnect**.
- **References:** `apps/mobile/src/native/agentLiveNativeBridge.ts`,
  `apps/mobile/src/services/workspaceAgentLiveLane.ts`,
  `apps/mobile/src/services/mobileApplicationService.ts`,
  `apps/mobile/src/components/MobileConnectionRecoveryOverlay.tsx`

## Android QR scan closes without advancing pairing

- **Symptom:** The pairing scanner opens, reads a valid Desktop QR code, and
  returns to the device page, but the App neither shows an error nor advances
  to waiting or confirmed state.
- **Quick checks:** Confirm Android launches and finishes the ZXing
  `CaptureActivity`, then inspect events from `TuttiAppLifecycle`. A background
  event during the in-process Activity handoff identifies a lifecycle-adapter
  regression rather than a camera or QR parsing failure.
- **Root cause:** Android presents the scanner as a child Activity. Pausing the
  React Activity therefore looks like ordinary App backgrounding. If the
  service invalidates every pairing generation on that transition, the native
  scan promise can resolve successfully while its QR payload is silently
  discarded as stale.
- **Fix:** Own application visibility at the native platform boundary. Android
  publishes `ProcessLifecycleOwner` state, so switching between Activities in
  the same process remains foreground; iOS publishes `UIApplication`
  foreground/background notifications. The TypeScript lifecycle port consumes
  this one semantic signal, while pairing remains unaware of Activities and
  scanners. A genuine process background suspends remote pairing operations
  and starts the DeviceLink grace period. A claim already sent is reconciled
  from challenge state after foreground recovery instead of being submitted
  twice.
- **Validation:** Verify the lifecycle adapter publishes its initial state,
  deduplicates transitions, and disposes subscriptions. Verify the application
  service applies background policy only after a real process background event.
  Verify scanner cancellation, duplicate taps, permission failures, and
  claim/poll reconciliation in the device service. Finally scan on Android and
  confirm no background event is emitted during the
  `MainActivity -> CaptureActivity -> MainActivity` sequence.
- **References:**
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/AppLifecycleModule.kt`,
  `apps/mobile/ios/TuttiMobile/AppLifecycleModule.swift`,
  `apps/mobile/src/native/appLifecyclePort.ts`

## Android release bundling cannot resolve the JSX transform

- **Symptom:** `app:assembleRelease` reaches Metro bundling and fails
  `app:createBundleReleaseJsAndAssets` with `Cannot find module
'@babel/plugin-transform-react-jsx'`, while TypeScript, Jest, and debug
  development may still pass.
- **Quick checks:** Resolve `@babel/plugin-transform-react-jsx` from the
  `apps/mobile` package, then run a production Android Metro bundle. If
  resolution fails from the app but the plugin exists only below the React
  Native preset in pnpm's store, the app has been relying on transitive layout.
- **Root cause:** `react-native-css-interop` asks Babel to load the JSX
  transform by package name but does not declare that package. pnpm's strict
  dependency isolation therefore does not expose the preset's private copy to
  the app-level Babel configuration.
- **Fix:** Keep `@babel/plugin-transform-react-jsx` as an explicit
  `apps/mobile` development dependency aligned with the locked Babel cohort.
  Do not solve this by changing pnpm hoisting.
- **Validation:** Resolve the plugin from `apps/mobile`, produce a
  `--dev false` Android Metro bundle, and run the `Android Internal Build`
  workflow through APK assembly.
- **References:** `apps/mobile/package.json`, `apps/mobile/babel.config.js`

## Android update stays on MainActivity without opening the installer

- **Symptom:** The Android App remains in the update progress overlay or never
  opens `PackageInstaller` / `.InstallStart`. A successful feed request does
  not prove that Android downloaded, verified, and handed off the APK.
- **Quick checks:** Filter the device logcat by the native update tag:

  ```sh
  adb -s <serial> logcat -v threadtime TuttiMobileSecurity:I '*:S'
  ```

  The UI phase narrows the boundary: **Preparing** means validation/storage,
  **Downloading** or **Paused** is Android `DownloadManager`, **Verifying** is
  exact-size plus SHA-256 verification, **Allow update installation** is the
  per-app unknown-source permission handoff, and **Install the downloaded
  update** is the Android package-installer handoff. Inspect the system-owned
  job with:

  ```sh
  adb -s <serial> shell dumpsys download
  ```

  `DownloadManager` owns network reconnection and background continuation. The
  App persists its download id and release metadata so reopening the App and
  choosing the same release reconnects to the job or reuses a verified cached
  APK. After verification it also records the target `versionCode`: a confirmed
  install deletes the APK immediately, while a process replacement during
  upgrade is handled on the next launch once the installed version reaches the
  target. Installer cancellation or failure retains the APK for retry. The
  in-App download cancel action removes the system job and cached artifact.

- **Relevant error codes:** `UPDATE_URL_INVALID`, `UPDATE_VERSION_INVALID`,
  `UPDATE_SIZE_INVALID`, `UPDATE_SIZE_MISMATCH`,
  `UPDATE_STORAGE_INSUFFICIENT`, `UPDATE_DOWNLOAD_FILE_FAILED`,
  `UPDATE_DOWNLOAD_SERVER_FAILED`, `UPDATE_DOWNLOAD_MANAGER_FAILED`,
  `UPDATE_DOWNLOAD_QUERY_FAILED`, `UPDATE_CHECKSUM_INVALID`,
  `UPDATE_CHECKSUM_FAILED`, `UPDATE_CACHE_FAILED`, `UPDATE_CACHE_REPLACE_FAILED`,
  `UPDATE_INSTALL_DEFERRED`, `UPDATE_INSTALL_STORAGE_INSUFFICIENT`,
  `UPDATE_INSTALL_INCOMPATIBLE`, `UPDATE_INSTALL_CONFLICT`,
  `UPDATE_INSTALL_BLOCKED`, `UPDATE_INSTALL_PACKAGE_INVALID`,
  `UPDATE_INSTALL_FAILED`, `UPDATE_URI_FAILED`, and
  `UPDATE_INSTALLER_LAUNCH_FAILED`. If Android's
  per-app unknown-source permission is missing, `UPDATE_INSTALL_PERMISSION_REQUIRED`
  means the user returned without granting it rather than an APK failure;
  `UPDATE_PERMISSION_SETTINGS_FAILED` means the system settings page itself
  could not be opened. The `EXTRA_RETURN_RESULT` flow reports the package
  manager result through `android.intent.extra.INSTALL_RESULT`; project that
  legacy result to the public `PackageInstaller` status before choosing the
  in-App error. A cancelled activity without an install result is user
  cancellation; an aborted or rejected result remains a failure.
- **Root cause:** The release feed, Android system download, artifact
  verification, FileProvider, and PackageInstaller are separate trust
  boundaries. A stale or malformed `sizeBytes`, a reused version URL with
  different bytes, insufficient storage, a paused system job, or missing
  unknown-source permission can stop the chain at different phases.
- **Fix:** Keep release URLs credential-free HTTPS and publish immutable APK
  paths under `<tag>/<sha256>/`. Preflight both the APK and checksum before
  uploading either object, then update `latest.json` last. Treat `latest.json`
  `sizeBytes` and `sha256` as mandatory: both must match before PackageInstaller
  opens. If the permission settings page opens, enable **Allow from this
  source** and return to the App; the verified cached APK continues to the
  installer automatically. Returning without granting permission produces a
  localized recovery prompt and keeps the package for an explicit retry. Keep
  the target version with that pending artifact, delete it on confirmed
  success, and repeat cleanup on the first launch whose installed
  `versionCode` reaches the target. For paused downloads, restore an allowed
  network or cancel and retry rather than deleting app data.
- **Validation:** Run `pnpm --filter @tutti-os/mobile check`,
  `./gradlew app:testDebugUnitTest`, and
  `./gradlew app:compileDebugKotlin` from `apps/mobile/android`. On a physical
  device, reproduce from Settings and verify determinate progress, cancel,
  background/reopen continuation, offline pause/resume, exact-size/SHA failure,
  and the installer handoff. Confirm that a late progress callback after cancel
  cannot reopen the overlay. For permission recovery, revoke Tutti's
  unknown-source permission, finish the download, grant the permission in
  Android settings, return to the App, and confirm the installer opens without
  another download action. Also deny the permission once and confirm the App
  explains how to recover. Exercise an installer rejection and confirm it is
  reported with the mapped failure rather than cancellation. Cancel once and
  confirm the verified APK remains reusable; complete an update and confirm
  the pending APK is gone either from the success callback or after the updated
  App starts. For release recovery, simulate an APK-only upload, rerun the same
  version with a different APK digest, and confirm the missing objects are
  published before `latest.json` moves.
- **References:**
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileSecurityModule.kt`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileUpdateArtifact.kt`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileUpdateCoordinator.kt`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileUpdateInstallResult.kt`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileUpdatePendingInstallStore.kt`,
  `apps/mobile/src/services/mobileUpdateService.ts`,
  `tools/scripts/build-mobile-release-latest.mjs`

## Mobile quick prompts are missing from the plus menu

- **Symptom:** The connected Mobile composer does not show Quick prompts under
  `+`, or the list is empty despite prompts saved on Desktop.
- **Quick checks:** Inspect the DeviceLink `agent_http` response for
  `GET /v1/agent-quick-prompts`. A 403 response with `route_not_allowed`
  identifies an allowlist gap.
- **Root cause:** Mobile loads prompt content only from the canonical device
  list, so neither the UI nor workspace activity state invents a local
  fallback.
- **Fix:** Keep the exact quick-prompt GET route in the DeviceLink allowlist
  and keep all preference writes, quick-prompt mutations, and per-prompt
  routes blocked. Refresh the authenticated-device quick-prompt service when
  the `+` menu opens.
- **Validation:** Confirm the canonical prompt order is visible, search
  matches title and content, and selecting a prompt adds text at the current
  input position without replacing the existing draft or sending it.
- **References:** `services/tuttid/service/mobileremote/remote_protocol.go`,
  `apps/mobile/src/services/mobileQuickPromptLibraryService.ts`,
  `apps/mobile/src/components/MobileComposerDock.tsx`

## Mobile composer model and permission controls are missing

- **Symptom:** A remotely connected Android or iOS App can open an Agent
  conversation and send prompts, but the model and permission controls above
  the composer are absent.
- **Quick checks:** Query the host with
  `tutti --json agent composer-options --agent-id <agent-target-id>` and confirm
  that model and permission options are present. Then inspect the DeviceLink
  `agent_http` response for the matching
  `POST /v1/agent-providers/{provider}/composer-options` request. A 403 response
  with `route_not_allowed` identifies a transport allowlist gap rather than an
  AgentGUI capability or mobile layout problem.
- **Locale check:** Confirm the request body includes the phone's normalized
  `locale` (`en` or `zh-CN`). If it is absent, tuttid falls back to the desktop
  preference and the phone may show model, reasoning, or permission labels in
  the desktop language.
- **Root cause:** Mobile loads authoritative composer options through the
  DeviceLink HTTP bridge. If the exact read-side composer-options route is
  absent from the bridge allowlist, the request is rejected before it reaches
  tuttid's handler. The mobile UI fails closed and hides controls for options it
  cannot verify.
- **Fix:** Add only the exact `POST
/v1/agent-providers/{provider}/composer-options` shape to the DeviceLink
  `agent_http` allowlist, and include the mobile device locale in the request.
  Keep unrelated provider routes and other HTTP methods blocked; do not
  hardcode model or permission catalogs in the App.
- **Validation:** Run the focused `mobileremote` tests, confirm a composer-options
  request round-trips through DeviceLink while GET and extra-path variants
  remain forbidden, then use different phone and desktop languages to verify
  that option labels follow the phone language and that model, reasoning, and
  permission changes update the chips and persist in the selected Session.
- **References:** `services/tuttid/service/mobileremote/remote_protocol.go`,
  `apps/mobile/src/services/workspaceActivityCommandAdapter.ts`,
  `apps/mobile/src/components/MobileComposerSettingsSheet.tsx`

## Mobile composer option sheets do not respond

- **Symptom:** Model, reasoning, speed, and permission chips are visible and
  accessible above the composer, but tapping them does not show their option
  sheet; or rapidly alternating between a chip and the `+` button leaves two
  overlapping menus, with the lower menu visible but unable to receive taps.
- **Quick checks:** Tap a chip on a real Android or iOS renderer and inspect the
  JavaScript log. Repeated `BottomSheetModal::handlePortalRender` entries,
  followed by a maximum-update-depth error, identify the legacy overlay path.
  Without that error, inspect the native window hierarchy: two simultaneous
  composer `Modal` windows identify competing local overlay state rather than
  a slow or missing press handler. A missing composer-options response is a
  different problem covered above.
- **Root causes:** `@gorhom/bottom-sheet` delegates `BottomSheetModal` rendering
  through `@gorhom/portal`; its portal update path is incompatible with the
  current React 19 Native renderer and recursively republishes the modal node
  instead of presenting it. Separately, sibling composer controls must not own
  independent window-level overlay state: queued taps can open both windows,
  and the top window then intercepts input intended for the visible lower one.
- **Fix:** Keep the shared compact `NativeSheet` on React Native's window-level
  `Modal`, with UI System scrim and panel tokens. Require a caller-localized
  close label, expose backdrop dismissal as an accessibility button, handle the
  iOS accessibility escape gesture, and represent an optional fixed height as
  one value rather than silently accepting multiple snap points. Reserve
  `@gorhom/bottom-sheet` for app-owned complex sheets that genuinely need its
  gesture, keyboard, or multi-snap-point behavior. At composition boundaries
  that offer multiple overlay entry points, keep one discriminated overlay
  state in their nearest common owner and make child controls submit typed menu
  intents.
- **Validation:** Open and dismiss the model, speed, and permission sheets more
  than once, select the already active option without changing Session state,
  and rapidly alternate between a settings chip and `+`; assert that no more
  than one native modal is visible. Confirm there is no maximum-update-depth
  error. Also verify touch backdrop, Android system-back, VoiceOver escape, and
  screen-reader close button dismissal without hiding the sheet's interactive
  descendants.
- **References:** `packages/ui/system/src/native/sheet.tsx`,
  `apps/mobile/src/components/MobileComposerDock.tsx`,
  `apps/mobile/src/components/MobileComposerSettingsSheet.tsx`

## Browser login completes but leaves the browser in front

- **Symptom:** Mobile completes provider login, but the browser stays in front.
  Switching back to Tutti manually reveals that the account session is already
  available or allows the login flow to finish.
- **Quick checks:** Confirm the localhost callback received a transfer code and
  that transfer-code redemption succeeds. If the hosted result page's manual
  “open App” action works, the account flow is healthy and only the browser-to-App
  return path failed.
- **Root cause:** Opening a raw external browser makes the hosted result page
  responsible for returning to `tutti://auth/login`. Mobile browsers can reject
  a custom-scheme navigation started by delayed JavaScript because it no longer
  carries a direct user gesture, even though the localhost bridge already
  completed the account transfer.
- **Fix:** Keep the shared hosted login page, localhost bridge, and one-time
  transfer-code redemption. Present that flow with `ASWebAuthenticationSession`
  on iOS and AndroidX Auth Tab when the Android browser provider supports it, so
  the operating system owns callback matching and foreground return. Android
  falls back to the external system browser when Auth Tab is unavailable; the
  hosted manual return action remains the recovery path for that fallback.
- **Validation:** On physical iOS and Android devices, complete a real provider
  login and confirm the browser dismisses and Tutti becomes foreground without
  a manual app switch. Also cancel once, exercise an Android browser without Auth
  Tab support, and verify the transfer code is redeemed no more than once.
- **References:** `apps/mobile/ios/TuttiMobile/MobileWebAuthenticationSession.swift`,
  `apps/mobile/ios/TuttiMobile/MobileBrowserAuthBridge.swift`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MainActivity.kt`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileBrowserAuthBridge.kt`

## Browser login returns to the App but remains signed out

- **Symptom:** Android opens the Tutti Web login page, completes the provider
  login, and returns to the App, but the login screen shows a generic failure.
- **Quick checks:** Confirm the localhost auth bridge has stopped listening after
  the callback. In read-only account-service access logs, compare the transfer
  code redemption with the immediately following `user/v1/user_info` request. A
  successful redemption followed by `SESSION_ID_MISSING` identifies this case.
- **Root cause:** Mobile API requests already authenticate from the encrypted
  session using one explicit `Cookie` header. Leaving React Native's native
  cookie jar enabled creates a second credential source; a stale native
  `session_id` can be appended to or override the explicit session after browser
  login.
- **Fix:** Keep the account session in encrypted native storage, set
  `credentials: "omit"` on account and control-plane fetches, and attach exactly
  one validated `session_id` header per API request. The system browser login
  bridge returns only a short-lived transfer code; do not copy provider or
  browser cookies into the App, and do not make API login depend on a WebView
  cookie store. During migration, clear the legacy native `session_id` cookie
  at startup and sign-out, but keep cookie installation outside the application
  port contract.
- **Validation:** Complete a real browser login, verify the App reaches the
  device page, restart the App, and verify the same account session still
  authorizes device-list requests.
- **References:** `apps/mobile/src/services/accountClient.ts`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/MobileSecurityModule.kt`

## Android DeviceLink opens a session and then repeatedly restarts

- **Symptom:** Pairing and the secure link succeed, and the App may briefly load
  a workspace or session before returning to the launcher. Android process exit
  history reports `EXIT_SELF` with status `2`; logcat contains
  `fatal error: bulkBarrierPreWrite: unaligned arguments` instead of a Java or
  React Native exception.
- **Quick checks:** Run `adb shell dumpsys activity exit-info
sh.tutti.mobile` and inspect a narrow logcat window for the Go fatal message.
  This distinguishes a Go runtime abort from an Android lifecycle transition or
  a React Native development reload.
- **Root cause:** A gomobile-exported Go method returned a pointer-bearing value,
  first `([]byte, error)` and later `(string, error)` from Agent Live's
  `Subscriber.Apply`. Generated cgo code moves pointer-bearing parameters and
  return values through a packed structure whose address is not guaranteed to
  satisfy the Go runtime write barrier's pointer alignment before Go 1.26. The
  first successful response-body or Agent Live frame therefore exposes the
  upstream cgo alignment defect. Returning final stream data together with
  `io.EOF` also cannot be represented by the generated Java API, which chooses
  either a byte array or an exception.
- **Fix:** Build every Android AAR and iOS XCFramework gomobile artifact with
  Go 1.26.0 or newer, which includes the
  [cmd/cgo alignment fix](https://github.com/golang/go/commit/d5b950399de01a0e28eeb48d2c8474db4aad0e8a).
  Keep bulk stream data in a Java-owned byte array passed into Go and return only
  a scalar byte count so final bytes plus `io.EOF` remain representable. The
  Mobile and DeviceLink Makefiles pin the fixed toolchain; do not bypass that pin
  when rebuilding native artifacts.
- **Validation:** Generate the Java binding and confirm the stream method is
  `readInto(byte[])` with a scalar return, build the AAR and confirm every
  `libgojni.so` reports the pinned Go toolchain, then install the AAR consumer,
  connect on an ARM64 Android device, receive Agent Live frames, and observe
  beyond the previous crash window with no new Go fatal message.
- **References:** `packages/device-link/mobile/link.go`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/DeviceLinkModule.kt`

## Mobile direct DeviceLink consistently takes about ten seconds

- **Symptom:** A paired computer is online and often on the same LAN, but the
  direct path regularly needs roughly ten seconds before it becomes usable.
  Relay may appear much faster even though P2P eventually succeeds.
- **Quick checks:** Inspect sanitized `device_link.stage` events for
  `direct_credentials_ready`, `direct_attempt_created`,
  `direct_first_candidate_published`, `direct_attempt_ready`,
  `direct_remote_candidate_received`, and `direct_connected`. If credentials
  or attempt creation appear only after a five-second boundary, inspect the
  native prepare bridge for a blocking full ICE description. If ready is early
  but connected is late, isolate candidate exchange from authenticated
  ICE/QUIC instead of changing Relay delay.
- **Root cause:** The caller previously waited for a complete host-only ICE
  description, created the attempt to discover server STUN endpoints, replaced
  the Participant, and then waited for a second complete description. The
  Desktop owner also waited for its full description before publishing. Two
  configured five-second gathering windows therefore sat on the critical path,
  while TSH's lower-level implementation already published credentials and
  trickled candidates during `Connect`.
- **Fix:** Use `candidateexchange.Start` and publish valid ICE credentials
  immediately, allowing an empty candidate list. Run `PublishLocal` and
  `FeedRemote` beside `Participant.Connect`; keep signed attempt reads/writes,
  push hints, account authorization, and pairing state in the product adapter.
  Mobile must drain the gomobile `ActionPump` next/resolve protocol rather than
  use the legacy blocking `LocalDescription` bridge or own a second TypeScript
  retry/poll scheduler. Resolve a publication successfully only after the
  returned authoritative attempt contains its candidate snapshot. Android must
  keep enough native operation workers for `Connect`, candidate actions, and
  Relay work to progress concurrently.
- **Validation:** Cover an initial zero-candidate snapshot, a later local
  candidate update, a ready peer with zero candidates, a later authoritative
  remote snapshot, missed-push polling fallback, exact-snapshot publish retry,
  and a successful stream probe. Compare stage deltas on LAN and external NAT;
  do not log candidates, addresses, ICE credentials, fingerprints, tokens, or
  payloads.
- **References:** `packages/device-link/candidateexchange`,
  `packages/device-link/mobile/link.go`,
  `apps/mobile/src/services/deviceLinkCandidateExchange.ts`,
  `services/tuttid/service/mobileremote/candidate_exchange.go`

## Mobile shows output from a completed Session after foreground resume

- **Symptom:** After the App enters the background and is reopened, transcript
  output from the previously selected Session continues streaming even though
  that Session already ended on the host.
- **Quick checks:** Compare App lifecycle events with Native `TuttiDeviceLink`
  Agent Live logs. Capture the subscription generation on the last delivery
  before background and the first delivery after foreground. If a delivery from
  the closed generation reaches the replacement JavaScript listener, the fault
  is lifecycle fencing rather than canonical Session state or server replay.
- **Root cause:** DeviceLink intentionally stays open for a short background
  grace period, but Agent Live used to share that lifetime. A suspended
  JavaScript runtime could therefore miss or delay its stop call while Native
  continued reading the old stream. React Native could queue those deliveries
  and publish them to the newly attached listener after foreground resume. The
  Native envelope carried workspace identity but no local subscription
  generation, so the replacement listener could not distinguish queued old
  output from its new stream.
- **Fix:** Stop Agent Live immediately at the Android and iOS background
  boundary while preserving the underlying DeviceLink grace interval. Give
  every bridge subscription a caller-owned generation, include it in every
  Native delivery, and reject mismatched generations in both the bridge parser
  and workspace live lane. Queue canonical workspace and selected-Session
  reconciliation before opening the replacement stream.
- **Validation:** Background and foreground a connected workspace, invoke a
  captured old listener after the replacement subscription exists, and verify
  it cannot mark transport connected or change projected activity. Verify
  matching-generation ready and event deliveries still apply, missing or stale
  generations fail closed, and Android/iOS Native binding checks pass.
- **References:**
  `apps/mobile/src/native/createMobileServicePorts.ts`,
  `apps/mobile/src/services/workspaceAgentLiveLane.ts`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/DeviceLinkModule.kt`,
  `apps/mobile/ios/TuttiMobile/DeviceLinkModule.mm`

## Mobile stays connected after a long lock-screen interval but sends fail

- **Symptom:** After Mobile remains locked or backgrounded for at least the
  DeviceLink grace interval, the previous conversation is still visible but the
  next command fails. Returning to the computer list and connecting again
  restores service.
- **Quick checks:** Compare `application.lifecycle_changed` and
  `device_connection.phase_changed` diagnostics with Native `TuttiDeviceLink`
  logs. If Native closed the link after its grace deadline while JavaScript
  never published its own delayed disconnect, verify whether the foreground
  transition used elapsed background time. Confirm the workspace runtime is
  blocked until a replacement live lane reports ready.
- **Root cause:** Native lifecycle handlers continue running while React Native
  timers may be suspended. When both layers independently scheduled the same
  background deadline, Native closed the real link but JavaScript canceled its
  still pending timer on foreground and resumed a stale connected workspace.
- **Fix:** Keep the close deadline Native-owned. Record background entry time in
  the application service and decide short resume versus full reconnect from
  elapsed time on foreground. Project one application-scoped connection phase,
  retain the paused workspace until a hydrated replacement is ready, and let a
  root overlay render that phase without owning recovery logic.
- **Validation:** Cover foreground before and after the grace boundary, an
  active live-stream loss, failed reconnect plus explicit retry, and generation
  fencing when the app backgrounds during recovery. On a physical device, lock
  beyond the deadline, unlock, observe reconnect/synchronize presentation, and
  send from the original conversation without revisiting the computer list.
- **References:**
  `apps/mobile/src/services/mobileApplicationService.ts`,
  `apps/mobile/android/app/src/main/java/sh/tutti/mobile/DeviceLinkModule.kt`

## iOS App crashes after loading the JavaScript bundle

- **Symptom:** A physical iOS device downloads or evaluates the React Native
  bundle, then the App exits with `SIGSEGV`. The crash report points at
  `objc_retain` or `objc_storeStrong` below
  `ObjCTurboModule::performMethodInvocation` on the JavaScript thread.
- **Quick checks:** Capture the App console and the latest `.ips` crash report.
  If the last log is JavaScript bundle evaluation and the faulting stack is a
  synchronous Objective-C TurboModule invocation, inspect every blocking
  synchronous Swift export used during startup before investigating Metro or
  DeviceLink.
- **Root cause:** React Native's Objective-C interoperability path expects an
  object from a blocking synchronous method. Exporting a Swift method with a
  primitive `Bool` return can leave the invocation result buffer shaped like an
  object pointer; retaining that value then causes an invalid-address crash.
- **Fix:** Return `NSNumber` from the Swift export. React Native converts it to
  a JavaScript boolean, so the TypeScript contract remains `boolean`.
- **Validation:** Build and sign the physical-device target, install it, launch
  it with the device console attached, and keep the process alive beyond the
  previous post-bundle crash window. Confirm the initial lifecycle state still
  arrives as a JavaScript boolean.
- **References:** `apps/mobile/ios/TuttiMobile/AppLifecycleModule.swift`,
  `apps/mobile/ios/TuttiMobile/MobileNativeModules.m`,
  `apps/mobile/src/native/appLifecyclePort.ts`

## iOS pod install intermittently reports pathname contains null byte

- **Symptom:** `pnpm --filter @tutti-os/mobile ios:pods` downloads and installs
  every Pod, then fails during `Generating Pods project` with
  `ArgumentError: pathname contains null byte` from
  `Pod::Project#group_for_path_in_group`. Re-running may succeed.
- **Quick checks:** Confirm the stack ends in `Pathname#realdirpath` and the
  workspace uses pnpm-linked React Native packages. CocoaPods version changes or
  deleting `Pods/` may change the frequency but do not identify a durable fix.
- **Root cause:** CocoaPods preserves the filesystem layout for local Pods and
  resolves their common base path through `realdirpath`. That resolution is
  intermittently unsafe for pnpm-backed local Pod symlinks while the Pods
  project is generated.
- **Fix:** Keep `apps/mobile/ios/cocoapods_pathname_workaround.rb` loaded from
  the Podfile. It retains CocoaPods' group-building behavior but normalizes the
  local Pod base with `cleanpath` instead of resolving the pnpm symlink through
  `realdirpath`. Do not depend on retries or a CocoaPods downgrade.
- **Validation:** Run `ios:pods` from a clean checkout, confirm the Pods project
  is generated, then archive the `TuttiMobile` workspace on the GitHub macOS 26
  runner to exercise the same pnpm and CocoaPods path.
- **References:** `apps/mobile/ios/Podfile`,
  `apps/mobile/ios/cocoapods_pathname_workaround.rb`,
  [CocoaPods #12798](https://github.com/CocoaPods/CocoaPods/issues/12798)

## Mobile Jest discovers tests inside iOS Pods

- **Symptom:** `pnpm --filter @tutti-os/mobile test` starts hundreds of Hermes
  or third-party suites under `apps/mobile/ios/Pods` after Pods are installed.
  Project suites may pass, but the command fails on upstream fixtures, Flow
  syntax, or snapshots.
- **Quick checks:** Inspect the failing test paths. Paths below `ios/Pods`
  identify test discovery crossing into CocoaPods output rather than a product
  test failure.
- **Root cause:** Jest recursively searches the package root. CocoaPods can
  vendor JavaScript sources and tests, and generated native dependency
  directories are not excluded by the default React Native preset.
- **Fix:** Keep `/ios/Pods/` in the Mobile Jest `testPathIgnorePatterns`,
  alongside the Android generated tree and `node_modules`. Do not adjust Babel
  transforms to make vendored test suites run.
- **Validation:** Install iOS Pods, run the Mobile test command, and confirm
  Jest discovers only repository-owned suites.
- **References:** `apps/mobile/jest.config.js`

## React Native Pressable rows stack their children vertically

- **Symptom:** A Native button, list row, or app-owned tappable row declares
  `flexDirection: "row"` but its icon, label, count, or trailing action appears
  vertically stacked on a Fabric Android device. Plain `View` rows on the same
  screen remain horizontal.
- **Quick checks:** Inspect the real device rather than relying only on
  TypeScript or snapshots. Compare the bounds from `uiautomator dump` for the
  direct children of the `Pressable`; consecutive vertical bounds identify the
  failure even when the parent style contains the expected row declaration.
- **Root cause:** In the current React Native NativeWind/CSS interop renderer,
  layout declarations on the `Pressable` host are not reliable for arranging
  its direct children. Interaction, surface, size, and pressed-state styles
  still apply, which makes this easy to mistake for stale Fast Refresh state.
- **Fix:** Keep interaction and surface styling on `Pressable`, but wrap its
  visual children in a plain token-backed `View` that owns
  `flexDirection: "row"` and alignment. Shared buttons and list rows should fix
  this once in `@tutti-os/ui-system/native`; app-specific tappable rows should
  follow the same inner-layout pattern.
- **Validation:** Perform a full JavaScript reload, then verify on Android that
  button icon/label, list title/trailing action, and section label/count remain
  horizontal. Confirm touch and accessibility actions still reach the outer
  `Pressable`.
- **References:** `packages/ui/system/src/native/button.tsx`,
  `packages/ui/system/src/native/list-row.tsx`