# Companion Android app background diagnostics

This adds no screen, button or employee log-export workflow. The updated Android
app automatically buffers structured operational events and sends them to petaV3
while signed in. This is diagnostic telemetry, not audio capture or session replay.

## Deployment

1. Deploy the combined app-update/diagnostics backend changes and run the normal
   `php artisan migrate --force` deployment step. The new table is
   `agent_app_diagnostics`; no existing recordings are modified.
2. Ensure the existing Laravel scheduler runs. `agent-app:prune-diagnostics` runs
   daily and removes events received more than 14 days ago.
3. Distribute an APK containing `feat(diagnostics)` (first build: 1.0.52 / 52).
   Earlier APKs cannot retrospectively report these events. The oldest APKs also
   need one manual upgrade before managed in-app update checks work.
4. Sign in, scan/connect a Badge, make a short test recording, stop it, and keep
   the app open and online for at least one minute. Verify receipt using the
   command below. This is a deployment smoke test, not yet a production result.

## Read diagnostics (server operator only)

```sh
php artisan agent-app:diagnostics --errors --limit=50
php artisan agent-app:diagnostics --admin=123 --limit=100
php artisan agent-app:diagnostics --installation=11111111-1111-4111-8111-111111111111
```

Each output line is JSON. `admin_id` is the sales admin/profile ID, not the user
ID; it is set from the authenticated JWT, never accepted from the client. Use
`agent_app_installations` to correlate installation UUID, current app build and
device model with a sales account. For an error timeline, query without `--errors`
so that preceding state transitions are included. Both event time and server
receipt time are stored as UTC. `no_active_capture` identifies the reported
“Native AAC write failed: No active capture” class; this feature observes that
failure and does not itself repair the native capture lifecycle.

## Scope and safeguards

- Captures app open/resume/pause/heartbeat, scan start/count/failure, BLE
  connect/disconnect/native error, recorder phase, session/upload state, retry,
  Flutter errors and uncaught Dart asynchronous errors while signed in.
- Samples the latest 100 sessions every minute, including when the Sessions tab
  is closed. It records state changes, not every audio/progress packet.
- Contains app version/build, model/OS, installation UUID, account association,
  interaction UUID, Badge SN, byte count, fixed error code and optionally one
  app-package source location. Treat these operational identifiers as restricted
  support data; limit production shell/database access and include telemetry in
  the internal app's data-use notice.
- No raw error text, tokens, request/response bodies, audio, transcript, customer
  name/phone, or full stack dumps. Client and server allowlists reject/strip
  unknown fields. There is no public or agent-facing read endpoint.
- Authenticated POST `/agent-api/agent-app/diagnostics`: at most 25 events per
  request, 10 requests/minute. Deduplicated by account + installation + event UUID.
- Client outbox is private app storage, separated by API origin and account,
  capped at 200 events / 256 KiB and 14 days; oldest events may be dropped. Events
  save after a 250 ms debounce. Network batches wait while recording/recovering,
  then retry on a one-minute timer or foreground resume. Failures retain the
  bounded queue; another account cannot upload it. Logout cancels pending sends.
- Not real-time monitoring or a guarantee of capturing every crash. Android may
  suspend/kill the app; native JVM/process crashes and events just before sudden
  termination are not guaranteed. Headless upload results become visible on the
  next app database sample/reopen. No notification/alerting or new web UI is added.

## Validation

Backend feature tests cover authentication, ownership attribution, idempotency,
strict fields/batch bounds, missing staff profile and server-time retention.
Flutter tests cover offline restart/retry, bounded batches, privacy, capture-time
network deferral, error-handler chaining/restoration and stale-session rejection.