Mesh Lab

Mesh Lab

Use the repository's debug-only ADB harness to validate mesh behavior on physical devices. Treat it as a development integration test, not as the privacy-checked release gate and not as proof about a release APK.

Establish current ground truth

Run from the repository root.

Before choosing commands or changing a scenario:

1. Read the Mesh Lab section of AGENTS.md.
2. Read the "mesh lab" appendix in docs/release-gate-runbook.md.
3. Use python3 tools/release_gate/mesh_lab.py --help and the relevant subcommand help.
4. Inspect the selected scenario function in tools/release_gate/mesh_lab.py; its current CLI and assertions are authoritative if documentation has drifted.
5. Inspect app/src/debug/java/com/bitchat/android/testhook/TestHookDriver.kt before using an ad-hoc command, diagnosing hook behavior, or extending coverage.

Do not infer a physical pass from unit tests, compilation, old evidence, or a successful local send call.

Decide the physical coverage

Inspect the change or requested behavior first. Select the smallest scenario set that exercises the affected physical contract, expanding to all for broad, cross-cutting, or release-sensitive changes.

When the selected scenarios do not exercise the new contract, add a focused scenario instead of treating unrelated green tests as coverage.

Protect devices and evidence

Mesh Lab setup is destructive to the app's local data. It force-stops the app, clears package data, regenerates identity, cycles Bluetooth, grants permissions, and changes wake/lock-screen timeout settings without restoring them.

• Use only designated disposable lab app data and deterministic test content.
• Use two authorized physical Android BLE devices on API 26 or newer. Emulators do not exercise the required BLE mesh behavior.
• Before setup, identity_reset, or all, confirm that the selected devices may have bitchat app data cleared. identity_reset clears device B even when setup was skipped. If the user has not already established authorization, ask.
• Never attempt to defeat a secure lock screen. Ask the operator to unlock it.
• Keep every device unlocked, awake, foregrounded, and preferably charging.
• Treat ADB selectors as ephemeral secrets. Do not put serials, device names, peer IDs, addresses, fingerprints, local home paths, or raw logcat in commits, pull requests, issues, or published artifacts.
• Write raw evidence under /tmp, keep it local, and never commit it. Failure evidence can include unsanitized logcat and lab identifiers.
• Use debug APKs only. The exported test-hook receiver intentionally has no production security boundary and must never be moved into src/main.
• Use an authorized, controlled lab area. After setup, inspect peer state locally and stop if an unexpected peer is present before sending broadcasts, files, or raw packets.
• On a non-dedicated device, record the prior Bluetooth, stay-awake, screen timeout, and lock-screen-disabled settings locally. Restore only those recorded values after the run, or tell the operator exactly what remains changed.

If the hardware, operator confirmation, or prerequisites are unavailable, report the physical result as blocked (not run) and provide the exact handoff command. Never soften this to "pass" or "probably works."

Run a two-phone batch

Preflight the environment without copying device selectors into durable output:

python3 --version
adb devices
./gradlew assembleDebug

Set up the disposable pair:

python3 tools/release_gate/mesh_lab.py setup \
  --serial-a "$MESH_SERIAL_A" \
  --serial-b "$MESH_SERIAL_B" \
  --apk app/build/outputs/apk/debug/app-arm64-v8a-debug.apk

Build and pass the current-tree debug APK during normal use. If setup intentionally omits --apk, first verify on both devices that the installed package is debuggable via run-as and that its package dump contains TestHookReceiver; do this before any command that clears data.

Inspect peers on both devices after setup. Continue only when every discovered participant belongs to the controlled lab.

Run either the selected scenario or the full suite. Run this entire block in one shell invocation so the temporary-directory variable cannot disappear between agent shell calls. Abort the block if the directory is empty or missing before passing it to --out; otherwise an empty path can put private evidence in the repository. Replace dm with all only when full-suite data clearing has been authorized.

MESH_EVIDENCE_DIR="$(mktemp -d /tmp/meshlab-evidence.XXXXXX)"
if [ -z "$MESH_EVIDENCE_DIR" ] || [ ! -d "$MESH_EVIDENCE_DIR" ]; then
  echo "mktemp failed; aborting so evidence cannot land in the repository" >&2
  exit 1
fi
chmod 700 "$MESH_EVIDENCE_DIR"

python3 tools/release_gate/mesh_lab.py scenario dm \
  --serial-a "$MESH_SERIAL_A" \
  --serial-b "$MESH_SERIAL_B" \
  --out "$MESH_EVIDENCE_DIR"

Rerun setup before a fresh scenario batch when prior churn, stale identities, or zombie GATT links could contaminate the result.

Keep the private evidence only as long as the active investigation needs it. Do not delete failure evidence that the user still needs; when it is no longer needed, remove it or move it to an explicitly approved protected location.