@mentra/acs-meeting 3.2.0-dev.221 → 3.2.0-dev.223

package/android/src/main/java/com/mentra/acsmeeting/telemetry/VideoRateVerdict.kt

@@ -0,0 +1,145 @@
+package com.mentra.acsmeeting.telemetry
+
+/**
+ * Names what is holding the outgoing frame rate down.
+ *
+ * The fps question kept being answered by inference: a soak put ~8.8 fps on the
+ * wire, so the ACS software encoder "holds 8.8 fps". That does not follow. At
+ * least four different things produce a low wire rate, they are trivial to tell
+ * apart from numbers we already collect, and two of them want opposite fixes —
+ * cutting resolution rescues an encoder that is genuinely CPU-bound and makes a
+ * bitrate-starved stream strictly worse.
+ *
+ * So this prints the answer instead of leaving it to be guessed:
+ *
+ * - [Bound.SOURCE_SHORT] the glasses are not sending enough frames. Nothing
+ *   downstream of the decoder can raise the rate.
+ * - [Bound.PACER_SHORT] our own gate is the limit — it admitted fewer frames
+ *   than we advertised while the source had plenty. This is what a greedy
+ *   `FramePacer` did: 14.6 fps in, 7.3 out, against an advertised 8.
+ * - [Bound.ENCODER_SHORT] ACS took the frames and put fewer on the wire while
+ *   the CPU was busy. The real encoder ceiling. Cut pixels.
+ * - [Bound.BITRATE_STARVED] ACS took the frames and put fewer on the wire with
+ *   CPU to spare and the bitrate far under the budget we granted. The rate
+ *   controller is throttling an encoder that could keep up. Cutting fps or
+ *   pixels here makes it worse; fix delivery consistency.
+ * - [Bound.CAP_BOUND] every frame is on the wire and the bitrate is pressed
+ *   against the ceiling we granted. Nothing is broken; the grant is simply the
+ *   limit, so the picture cannot get sharper until the number does.
+ */
+object VideoRateVerdict {
+  enum class Bound {
+    OK,
+    SOURCE_SHORT,
+    PACER_SHORT,
+    ENCODER_SHORT,
+    BITRATE_STARVED,
+    CAP_BOUND,
+    UNKNOWN,
+  }
+
+  /** Below this fraction of the target a rate counts as short rather than noise. */
+  const val SHORT_FRACTION = 0.85
+
+  /**
+   * The pacer is held to a tighter tolerance than anything else, because it is
+   * deterministic code we own rather than a jittery encoder or radio. The bug
+   * this class was written for delivered 7.3 against an advertised 8 — a 9%
+   * chronic shortfall, comfortably inside [SHORT_FRACTION] and still enough to
+   * bias the ACS rate controller down on every hiccup.
+   */
+  const val PACER_SHORT_FRACTION = 0.95
+
+  /** Process CPU at or above this is treated as the encoder being the cost. */
+  const val CPU_BUSY_PERCENT = 80.0
+
+  /** Wire bitrate below this fraction of the granted budget is a throttled stream. */
+  const val STARVED_FRACTION = 0.6
+
+  /**
+   * Wire bitrate at or above this fraction of the grant counts as riding the ceiling.
+   *
+   * The grant is a target rather than a wall — a device run recorded the wire at 1623 kbps
+   * against a 1.5 Mbps grant, 108% — so "pressed against it" has to mean near, not exactly at.
+   * 0.95 is below the noise on a controller that routinely overshoots and well above the 0.85
+   * that [VideoQuality.SPENDING_FRACTION] treats as merely spending the budget.
+   */
+  const val CAP_BOUND_FRACTION = 0.95
+
+  fun of(
+    advertisedFps: Double,
+    sinkFps: Double,
+    admittedFps: Double,
+    wireFps: Double?,
+    wireBitrateBps: Long?,
+    budgetBps: Int,
+    cpuPercent: Double?,
+  ): Bound {
+    if (advertisedFps <= 0.0) return Bound.UNKNOWN
+    // Source first: when the glasses are short, every rate below them is short
+    // too, and blaming the encoder for that sends the next fix to the wrong leg.
+    if (sinkFps < advertisedFps * SHORT_FRACTION) return Bound.SOURCE_SHORT
+    // Against what the source actually supplied, not against the advertise. The
+    // pacer cannot admit frames that never arrived, and scoring it on the
+    // advertise alone would read a merely slow source as our own bug.
+    val deliverable = minOf(advertisedFps, sinkFps)
+    if (admittedFps < deliverable * PACER_SHORT_FRACTION) return Bound.PACER_SHORT
+    if (wireFps == null) return Bound.UNKNOWN
+    if (wireFps >= admittedFps * SHORT_FRACTION) {
+      // A full frame rate is not the same as a good picture, and this is the one case where the
+      // fix is the ceiling itself. Reporting it as a plain OK is how "the quality is low" turns
+      // into an argument about the encoder: every rate number looks healthy, so the grant — the
+      // one thing actually holding the bits down — never comes up.
+      val capBound =
+        wireBitrateBps != null && budgetBps > 0 && wireBitrateBps >= budgetBps * CAP_BOUND_FRACTION
+      return if (capBound) Bound.CAP_BOUND else Bound.OK
+    }
+    if (cpuPercent != null && cpuPercent >= CPU_BUSY_PERCENT) return Bound.ENCODER_SHORT
+    val starved =
+      wireBitrateBps != null && budgetBps > 0 && wireBitrateBps < budgetBps * STARVED_FRACTION
+    return if (starved) Bound.BITRATE_STARVED else Bound.ENCODER_SHORT
+  }
+
+  /** What to do about it, so the log line does not need a reader who has this file open. */
+  fun hint(bound: Bound): String = when (bound) {
+    Bound.OK -> "wire is holding the advertised rate"
+    Bound.SOURCE_SHORT -> "glasses/WHIP leg is short; raising ACS fps cannot help"
+    Bound.PACER_SHORT -> "our gate drops frames the source supplied; check FramePacer interval"
+    Bound.ENCODER_SHORT -> "ACS encoder is the ceiling; cut pixels (VideoProfile.SD) not fps"
+    Bound.BITRATE_STARVED -> "rate controller is throttling, not CPU; do not cut fps or pixels"
+    Bound.CAP_BOUND -> "wire is riding the granted ceiling; raising maxBitrateBps is the only lever"
+    Bound.UNKNOWN -> "not enough evidence yet"
+  }
+
+  /**
+   * One line per tick. Prints every input beside the verdict: a verdict whose
+   * inputs are not visible is the same guess this class exists to replace.
+   */
+  fun line(
+    advertisedFps: Double,
+    sinkFps: Double,
+    admittedFps: Double,
+    wireFps: Double?,
+    wireBitrateBps: Long?,
+    budgetBps: Int,
+    cpuPercent: Double?,
+    codecName: String,
+  ): String {
+    val bound = of(
+      advertisedFps = advertisedFps,
+      sinkFps = sinkFps,
+      admittedFps = admittedFps,
+      wireFps = wireFps,
+      wireBitrateBps = wireBitrateBps,
+      budgetBps = budgetBps,
+      cpuPercent = cpuPercent,
+    )
+    val wireLabel = wireFps?.let { PipelineStats.formatRate(it) } ?: "na"
+    val wireKbps = wireBitrateBps?.let { (it / 1000).toString() } ?: "na"
+    return "P7 rate bound=$bound advertised=${PipelineStats.formatRate(advertisedFps)} " +
+      "sink=${PipelineStats.formatRate(sinkFps)} admitted=${PipelineStats.formatRate(admittedFps)} " +
+      "wire=$wireLabel kbps=$wireKbps budgetKbps=${budgetBps / 1000} " +
+      "cpu=${cpuPercent?.let { PipelineStats.formatRate(it) } ?: "na"} " +
+      "codec=${codecName.ifBlank { "na" }.replace(' ', '_')} -- ${hint(bound)}"
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/trace/SoftApTrace.kt

@@ -0,0 +1,143 @@
+package com.mentra.acsmeeting.trace
+
+import android.os.SystemClock
+import android.util.Log
+
+/**
+ * Correlated stage logging for the SoftAP calling pipeline (phone side).
+ *
+ * TEMPORARY DIAGNOSTIC. Every line carries the literal `SOFTAP_TRACE` marker so a single
+ * `rg -n 'SOFTAP_TRACE'` finds all of them at cleanup time. Flip [ENABLED] to false to mute the
+ * layer for a release without deleting call sites.
+ *
+ * The logcat tag is deliberately distinct from the module's `ACS-SPIKE` tag so that
+ * `adb logcat -s SOFTAP-TRACE` isolates the whole SoftAP pipeline in one stream.
+ *
+ * The phone mints [traceId] when it starts the hotspot and passes it to the glasses in
+ * `start_stream`. Both devices stamp the same id on every line, which is the only way to correlate
+ * two logs whose clocks were never synchronised.
+ */
+object SoftApTrace {
+
+    /** Master switch. Flip to false to mute the trace without removing call sites. */
+    const val ENABLED = true
+
+    /** Grep marker. Never build this by concatenation — a single grep must be exhaustive. */
+    const val MARKER = "SOFTAP_TRACE"
+
+    const val TAG = "SOFTAP-TRACE"
+
+    private const val REDACTED = "<redacted>"
+
+    /** Keys whose values must never reach logcat. Matched case-insensitively as substrings. */
+    private val SENSITIVE_KEYS = listOf(
+        "password", "passwd", "passphrase", "psk", "token", "secret",
+        "credential", "authorization", "bearer", "meetingurl",
+    )
+
+    @Volatile
+    private var traceId: String = ""
+
+    @Volatile
+    private var originMs: Long = 0L
+
+    @Volatile
+    private var lastStage: String = ""
+
+    /** Mint a new trace id and reset the elapsed-time origin. Called when the hotspot request starts. */
+    fun begin(id: String = newTraceId()): String {
+        traceId = id
+        originMs = SystemClock.elapsedRealtime()
+        lastStage = ""
+        return id
+    }
+
+    fun reset() {
+        traceId = ""
+        originMs = 0L
+        lastStage = ""
+    }
+
+    fun traceId(): String = traceId
+
+    /** Last stage successfully logged; use as failure context when reporting an error. */
+    fun lastStage(): String = lastStage
+
+    /** Short, collision-resistant enough for correlating one call's logs. */
+    fun newTraceId(): String = java.lang.Long.toHexString(System.nanoTime() and 0xFFFFFFFFL)
+
+    /**
+     * Log one pipeline stage transition.
+     *
+     * @param stage stable snake_case stage name, e.g. `scoped_network_available`
+     */
+    fun stage(stage: String, vararg fields: Pair<String, Any?>) {
+        if (!ENABLED) return
+        lastStage = stage
+        val elapsedMs = if (originMs == 0L) 0L else SystemClock.elapsedRealtime() - originMs
+        Log.i(TAG, format(traceId, stage, elapsedMs, *fields))
+    }
+
+    /** Error-level variant so genuine failures survive a logcat level filter. */
+    fun failure(stage: String, vararg fields: Pair<String, Any?>) {
+        if (!ENABLED) return
+        val elapsedMs = if (originMs == 0L) 0L else SystemClock.elapsedRealtime() - originMs
+        Log.e(TAG, format(traceId, stage, elapsedMs, *fields, "afterStage" to lastStage))
+    }
+
+    /**
+     * Pure formatter. Split out from [stage] so it can be unit tested without the Android logging
+     * framework, which is not available to plain JVM tests in this module.
+     */
+    fun format(
+        traceId: String,
+        stage: String,
+        elapsedMs: Long,
+        vararg fields: Pair<String, Any?>,
+    ): String = buildString {
+        append('[').append(MARKER).append(']')
+        if (traceId.isNotEmpty()) append(" traceId=").append(traceId)
+        append(" stage=").append(stage)
+        append(" elapsedMs=").append(elapsedMs)
+        for ((key, value) in fields) {
+            append(' ').append(key).append('=').append(sanitize(key, value))
+        }
+    }
+
+    /**
+     * Redact secrets outright and strip query strings from URLs. The local WHIP URL is genuinely
+     * useful in a trace, but a URL carrying a watch token is not, so query and userinfo go.
+     */
+    fun sanitize(key: String, value: Any?): String {
+        if (isSensitive(key)) return REDACTED
+        if (value == null) return "null"
+
+        val text = value.toString()
+        if (text.isEmpty()) return "\"\""
+        val cleaned = stripUrlSecrets(text)
+        return if (cleaned.contains(' ')) "\"$cleaned\"" else cleaned
+    }
+
+    private fun isSensitive(key: String): Boolean {
+        val lower = key.lowercase()
+        return SENSITIVE_KEYS.any { lower.contains(it) }
+    }
+
+    /** Drop `?query`, `#fragment`, and `user:pass@` from anything URL-shaped. */
+    private fun stripUrlSecrets(text: String): String {
+        val schemeIndex = text.indexOf("://")
+        if (schemeIndex < 0) return text
+
+        var result = text
+        val query = result.indexOf('?')
+        if (query >= 0) result = result.substring(0, query) + "?" + REDACTED
+        val fragment = result.indexOf('#')
+        if (fragment >= 0) result = result.substring(0, fragment)
+
+        val at = result.indexOf('@', schemeIndex + 3)
+        if (at >= 0) {
+            result = result.substring(0, schemeIndex + 3) + REDACTED + "@" + result.substring(at + 1)
+        }
+        return result
+    }
+}

package/android/src/main/java/com/mentra/acsmeeting/video/AcsFrameSender.kt

@@ -14,6 +14,7 @@ import com.mentra.acsmeeting.source.AcsInvestigation
 import com.mentra.acsmeeting.source.I420Planes
 import com.mentra.acsmeeting.source.PixelFormatArm
 import com.mentra.acsmeeting.source.TargetSize
+import com.mentra.acsmeeting.telemetry.AvSyncProbe
 import com.mentra.acsmeeting.telemetry.ChromaProbe
 import com.mentra.acsmeeting.telemetry.PipelineStats
 import java.nio.ByteBuffer
@@ -28,12 +29,16 @@ import java.util.concurrent.atomic.AtomicInteger
 import java.util.concurrent.atomic.AtomicReference
 
 /**
- * I420 to ACS: three independent direct planes (Y, U, V). No inter-arrival
- * pacer — [SendGate] is the only backpressure. Size mismatch drops; the sink
- * owns scaling to the negotiated size.
+ * I420 to ACS: three independent direct planes (Y, U, V).
+ *
+ * [SendGate] serializes in-flight sends. [FramePacer] is the time gate: ACS's
+ * software encoder holds ~8 fps, so extras have to be dropped here or the rate
+ * controller reserves budget for frames that encoder never produces. Size
+ * mismatch drops; the sink owns scaling to the negotiated size.
  */
 class AcsFrameSender(
   private val stats: PipelineStats = PipelineStats(),
+  private val avSync: AvSyncProbe? = null,
 ) {
   private val running = AtomicBoolean(false)
   private val stream = AtomicReference<RawOutgoingVideoStream?>(null)
@@ -42,6 +47,7 @@ class AcsFrameSender(
     Thread(runnable, "acs-i420-send").apply { isDaemon = true }
   }
   private val gate = SendGate()
+  private val pacer = FramePacer()
   private val pool = ConcurrentHashMap<Int, ConcurrentLinkedQueue<ByteBuffer>>()
   private val sendSeq = AtomicInteger(0)
   private val lastTicks = AtomicReference(0L)
@@ -57,6 +63,7 @@ class AcsFrameSender(
 
   fun attach(outgoing: VirtualOutgoingVideoStream, onFormat: ((TargetSize) -> Unit)? = null) {
     detach()
+    pacer.reset()
     this.onFormat = onFormat
     stream.set(outgoing)
     attachedStream = outgoing
@@ -111,9 +118,14 @@ class AcsFrameSender(
       )
       return
     }
+    if (!pacer.tryAdmit(FramePacer.intervalNs(negotiated.framesPerSecond))) {
+      stats.onDropPaced()
+      return
+    }
 
     val prepared = prepareSend(planes, negotiated)
     stats.setChroma(prepared.chroma)
+    avSync?.onVideoLuma(prepared.chroma.y)
 
     if (!gate.tryAcquire()) {
       stats.onDropBusy()
@@ -123,6 +135,7 @@ class AcsFrameSender(
 
     val seq = sendSeq.incrementAndGet()
     stats.onQueued()
+    val enqueuedAt = System.nanoTime()
     if (seq <= TRACE_SENDS) {
       Log.i(
         TAG,
@@ -135,6 +148,7 @@ class AcsFrameSender(
 
     val submitted = try {
       sender.execute {
+        stats.queue.record(System.nanoTime() - enqueuedAt)
         var result = "ok"
         // A timed-out future is NOT cancelled: ACS still reads these direct buffers.
         var reclaimable = true
@@ -157,7 +171,11 @@ class AcsFrameSender(
           frame.timestampInTicks = ticks
           val sendStart = System.nanoTime()
           out.sendRawVideoFrame(frame).get(SEND_TIMEOUT_MS, TimeUnit.MILLISECONDS)
-          stats.send.record(System.nanoTime() - sendStart)
+          val sendDone = System.nanoTime()
+          stats.send.record(sendDone - sendStart)
+          if (planes.timestampNs > 0) {
+            stats.e2e.record(sendDone - planes.timestampNs)
+          }
           stats.onSub()
           if (seq <= TRACE_SENDS) {
             Log.i(
@@ -342,6 +360,7 @@ class AcsFrameSender(
     format.set(null)
     sendSeq.set(0)
     lastTicks.set(0L)
+    pacer.reset()
     pool.clear()
     onFormat = null
   }

package/android/src/main/java/com/mentra/acsmeeting/video/FramePacer.kt

@@ -0,0 +1,70 @@
+package com.mentra.acsmeeting.video
+
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Drops frames that arrive sooner than the rate we advertised to ACS.
+ *
+ * [SendGate] only serializes in-flight sends. `sendRawVideoFrame` returns in about
+ * a millisecond, so without a time gate we hand ACS fifteen frames a second and
+ * its software encoder — which holds ~8.8 fps — is the one that has to drop them.
+ * That is exactly the over-reservation that collapses the wire bitrate.
+ *
+ * The gate keeps an absolute schedule rather than measuring from the last admit.
+ * That distinction is the whole rate: a "has [minIntervalNs] elapsed since the
+ * last admit" test turns a 14.6 fps source into exact 2:1 decimation, because the
+ * frame 68 ms after an admit is inside the 125 ms window and the next one lands at
+ * 137 ms. Admits then run at 7.3 fps against an advertised 8 — the same
+ * under-delivery this class exists to prevent, just one ladder rung down. Device
+ * logs showed it: `sub` sat at 7.0 with `wire=960x540@7.0`, and every arrival
+ * hiccup cost another 50% of the ACS bitrate budget. Advancing a deadline by whole
+ * intervals lets a frame that lands late still fill its own slot, so the average
+ * locks to the advertised rate for any source faster than it.
+ */
+class FramePacer {
+  private val nextDueNs = AtomicLong(UNSET)
+
+  fun reset() {
+    nextDueNs.set(UNSET)
+  }
+
+  /**
+   * True when this frame is due. [minIntervalNs] is derived from the advertised
+   * fps so the emit rate cannot drift from the format we declared.
+   */
+  fun tryAdmit(minIntervalNs: Long, nowNs: Long = System.nanoTime()): Boolean {
+    if (minIntervalNs <= 0) return true
+    while (true) {
+      val due = nextDueNs.get()
+      if (due == UNSET) {
+        if (nextDueNs.compareAndSet(due, nowNs + minIntervalNs)) return true
+        continue
+      }
+      if (nowNs < due) return false
+      // Resync instead of catching up when the source has been away for longer
+      // than RESYNC_INTERVALS. Carrying that whole debt forward would admit a
+      // burst back-to-back, which is over-delivery against the same advertised
+      // rate and hits the ACS encoder the way the ungated path did.
+      val next =
+        if (nowNs - due > minIntervalNs * RESYNC_INTERVALS) {
+          nowNs + minIntervalNs
+        } else {
+          due + minIntervalNs
+        }
+      if (nextDueNs.compareAndSet(due, next)) return true
+    }
+  }
+
+  companion object {
+    /** Not a legal timestamp. 0 is — [System.nanoTime] can start there in tests. */
+    private const val UNSET = Long.MIN_VALUE
+
+    /** How far behind schedule we still treat as catch-up rather than a new start. */
+    private const val RESYNC_INTERVALS = 2
+
+    fun intervalNs(fps: Float): Long {
+      if (fps <= 0f) return 0L
+      return (1_000_000_000.0 / fps).toLong()
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/video/I420FormatSpec.kt

@@ -46,7 +46,7 @@ data class I420FormatSpec(
     const val MAX_FPS = 30f
 
     /** VirtualOutgoingVideoStream join allowlist. P540 is 960×540, never 540×960. */
-    private val ALLOWED_SIZES = setOf(1280 to 720, 960 to 540)
+    private val ALLOWED_SIZES = setOf(1280 to 720, 960 to 540, 858 to 480)
 
     fun of(width: Int = 1280, height: Int = 720, fps: Float = 20f): I420FormatSpec {
       val chroma = I420Packer.chromaStride(width)

package/android/src/main/java/com/mentra/acsmeeting/video/VideoProfile.kt

@@ -22,31 +22,64 @@ data class VideoProfile(
   /** Bits available per frame at the ceiling. Below ~20 kbit the encoder starts dropping. */
   fun bitsPerFrame(): Int = maxBitrateBps / fps
 
+  /**
+   * The format ACS's software encoder can actually hold on the phones we ship.
+   *
+   * Media statistics on SM_S948U (and earlier 720p soaks) report `codecName: "h264 sw"`
+   * and a wire rate of ~8.8 fps no matter whether we asked for 15 or 30. Advertising
+   * the faster rate makes ACS reserve budget for frames that encoder never produces,
+   * and the wire collapses to a few hundred kbps while our own `sub` still reads 15.
+   * Size stays; only the declared rate moves, so Teams still gets 540p/720p, just at
+   * a cadence the software encoder can keep.
+   */
+  fun forSoftwareEncoder(): VideoProfile =
+    if (fps <= SOFTWARE_ENCODER_FPS) this else copy(fps = SOFTWARE_ENCODER_FPS)
+
   companion object {
     /**
      * 720p15. ACS encodes this in software on mid-range hardware (the media
      * statistics report `codecName: "h264 sw"`), so the pixel count is a real
      * CPU cost, not just a bitrate cost.
      */
-    val HD = VideoProfile(width = 1280, height = 720, fps = 15, maxBitrateBps = 2_500_000)
+    val HD = VideoProfile(width = 1280, height = 720, fps = 15, maxBitrateBps = 3_000_000)
 
     /** Quarter the pixels of [HD]. Use when the software encoder cannot hold 15 fps at 720p. */
     val SD = VideoProfile(width = 640, height = 360, fps = 15, maxBitrateBps = 1_000_000)
 
+    /**
+     * Fastest rate the ACS software H.264 encoder has held on device.
+     *
+     * Every soak that reported `h264 sw` also reported wire ≈ 8.8 fps — 720p15,
+     * 540p15, I420 and NV12. 8 is just under that so the rate controller is
+     * never asked for a frame the encoder cannot produce.
+     */
+    const val SOFTWARE_ENCODER_FPS = 8
+
     /** Investigation flip. Ships as HD. SD is 360p — a quarter of the encode work. */
     val DEFAULT = HD
 
     /**
      * ACS P540. VirtualOutgoingVideoStream documents 960×540, not 540×960.
      * 540p A/B uses this size on both WHIP and ACS.
+     *
+     * The ceiling sits above the glasses→phone WHIP default (2.5 Mbps) so the
+     * Teams hop is not the quality bottleneck. Mentra Call Auto sends this
+     * number as `maxBitrateBps`; an explicit picker value still overrides it.
      */
-    val P540 = VideoProfile(width = 960, height = 540, fps = 30, maxBitrateBps = 1_500_000)
+    val P540 = VideoProfile(width = 960, height = 540, fps = 30, maxBitrateBps = 3_000_000)
 
     /**
      * Same P540 geometry at 15 fps. Selectable from Mentra Call; not the default.
      * Isolates pixel-count savings without doubling frame work versus [P540].
+     *
+     * The ceiling is sized from the picture rather than copied from an older
+     * 1.5 Mbps grant. By the Kush gauge a high-motion 960x540 at 15 fps needs
+     * `960·540·15·0.28` ≈ 2.18 Mbps to avoid visible blocking, and a
+     * head-mounted camera is high motion by definition. It also has to clear
+     * the 2.5 Mbps glasses→phone WHIP default, so the grant is 3 Mbps — the
+     * next discrete step above that link.
      */
-    val P540_15 = VideoProfile(width = 960, height = 540, fps = 15, maxBitrateBps = 1_500_000)
+    val P540_15 = VideoProfile(width = 960, height = 540, fps = 15, maxBitrateBps = 3_000_000)
 
     fun parse(width: Int, height: Int, fps: Int, maxBitrateBps: Int): VideoProfile? {
       if (maxBitrateBps <= 0) return null

package/android/src/test/java/com/mentra/acsmeeting/AbandonedCallAgentTest.kt

@@ -0,0 +1,74 @@
+package com.mentra.acsmeeting
+
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.Future
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class AbandonedCallAgentTest {
+
+  @Test
+  fun `a completed future still yields the agent after we stop waiting`() {
+    val agent = Any()
+    val pending: Future<Any> = CompletableFuture.completedFuture(agent)
+
+    assertSame(agent, AbandonedCallAgent.takeIfDone(pending))
+  }
+
+  @Test
+  fun `an incomplete future is left for a later sweep`() {
+    val pending = CompletableFuture<Any>()
+
+    assertNull(AbandonedCallAgent.takeIfDone(pending))
+    assertFalse(pending.isCancelled)
+  }
+
+  @Test
+  fun `a cancelled future cannot hand back the native agent`() {
+    val pending = CompletableFuture<Any>()
+    pending.cancel(true)
+
+    assertTrue(pending.isCancelled)
+    assertNull(AbandonedCallAgent.takeIfDone(pending))
+  }
+
+  @Test
+  fun `a short wait returns the agent once the future completes`() {
+    val agent = Any()
+    val pending = CompletableFuture<Any>()
+    pending.complete(agent)
+
+    assertSame(agent, AbandonedCallAgent.take(pending, 50))
+  }
+
+  @Test
+  fun `a short wait does not cancel an agent that is still signing in`() {
+    val pending = CompletableFuture<Any>()
+
+    assertNull(AbandonedCallAgent.take(pending, 20))
+    assertFalse(pending.isDone)
+    assertFalse(pending.isCancelled)
+  }
+
+  @Test
+  fun `already-exists is recognized through wrapped execution exceptions`() {
+    val native = IllegalStateException(
+      "Failed to create CallAgent, an instance of CallAgent associated with this identity already exists.",
+    )
+    val wrapped = java.util.concurrent.ExecutionException(native)
+
+    assertTrue(AbandonedCallAgent.isExistingAgentError(wrapped))
+    assertFalse(AbandonedCallAgent.isExistingAgentError(IllegalStateException("ACS_AGENT_TIMEOUT")))
+  }
+
+  @Test
+  fun `take with no wait is the same as takeIfDone`() {
+    val pending = CompletableFuture<Any>()
+    assertNull(AbandonedCallAgent.take(pending, 0))
+    pending.complete("agent")
+    assertSame("agent", AbandonedCallAgent.take(pending, 0))
+  }
+}

package/android/src/test/java/com/mentra/acsmeeting/CallCapabilitiesTest.kt

@@ -0,0 +1,47 @@
+package com.mentra.acsmeeting
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class CallCapabilitiesTest {
+
+    @Test
+    fun `an allowed capability proceeds`() {
+        assertNull(EndForEveryonePolicy.refusalFor(CapabilityStatus(allowed = true, reason = "capable")))
+    }
+
+    @Test
+    fun `a denied capability is refused with its reason`() {
+        assertEquals(
+            "hang_up_for_everyone_not_allowed:role_restricted",
+            EndForEveryonePolicy.refusalFor(CapabilityStatus(allowed = false, reason = "role_restricted")),
+        )
+    }
+
+    @Test
+    fun `a denied capability with no reason still names itself`() {
+        assertEquals(
+            "hang_up_for_everyone_not_allowed:unknown",
+            EndForEveryonePolicy.refusalFor(CapabilityStatus(allowed = false, reason = "  ")),
+        )
+    }
+
+    /**
+     * Unknown is the ordinary state between joining and the first capabilities event. Treating it as
+     * a refusal would hide End on every call that taps it early; letting ACS answer is honest.
+     */
+    @Test
+    fun `an unknown capability is attempted, not refused`() {
+        assertNull(EndForEveryonePolicy.refusalFor(CapabilityStatus()))
+        assertNull(EndForEveryonePolicy.refusalFor(CapabilityStatus(reason = "capabilities_unavailable")))
+    }
+
+    @Test
+    fun `serializes the tri-state for the miniapp`() {
+        assertEquals(
+            mapOf("allowed" to null, "reason" to "not_reported"),
+            CapabilityStatus(reason = "not_reported").toMap(),
+        )
+    }
+}