Awesome Reviewers

Establish a single concurrency standard: in async code, never block the event loop; in multi-thread/state-machine code, make ownership and cancellation atomic; and in cleanup/shutdown, use bounded, interrupt-friendly paths.

1) Keep async nonblocking

• Any subprocess.run, CPU-heavy work (ffprobe/ffmpeg, compressors, summary generation), synchronous SDK calls, or blocking I/O must be offloaded.
• Pattern: ```py

  BAD: blocks event loop

  result = subprocess.run([…], timeout=60)

GOOD

result = await asyncio.to_thread(subprocess.run, […], timeout=60)

or

result = await adapter._run_blocking(func, *args)

2) Re-check cancellation/flags after waits
- If a worker can be paused in `Event.wait()` (or similar), it must re-check the controlling mode/flag at every boundary where it could restart capture/playback/processing.
- Pattern:
```py
await voice_done.wait()
if cli_ref._voice_continuous is False:
    return  # cancel boundary

3) Lock/claim correctly; snapshot atomically

• When multiple pieces of state must be consistent (e.g., status + payload), take the same lock for a single snapshot.
• When there is a single owner (wake-word listener, shared callback transport, adapter connection-local services), implement a real lease/claim/release so late callers can’t steal delivery.

4) Shutdown/cleanup must be bounded and interrupt-friendly

• Never perform blocking cleanup (e.g., shutdown(wait=True)) before the code path that needs to deliver an interrupt/watchdog action.
• Prefer bounded waits or non-blocking cancellation first: ```py

  BAD if interrupt must run promptly

  pool.shutdown(wait=True, cancel_futures=True)

BETTER: cancel first, then bounded wait, then allow interrupt to proceed

pool.shutdown(wait=False, cancel_futures=True)

or wait with a timeout in your own logic

```

5) Add regression coverage for the real concurrency boundary

• For cross-thread queueing (e.g., put_threadsafe()), tests must involve a real worker thread, not only same-loop calls.
• For ownership/leases and cross-process locks, add OS-process regressions (where supported) to validate the intended guard behavior.

This site is open source. Improve this page.