fix(nrf): stop a stalled USB host and stuck transfers from wedging loop()

[davelee98]

Three related fixes to paths that can leave loop() wedged or spinning on nRF52840, plus the shared plumbing they need. Rebased onto main at 987c6d9 (post-#132), so the diff is purely additive: 5 commits, +524/-47 across 9 files under src/.

nRF has no watchdog and every fault handler is b ., so anything that can block loop() indefinitely is unrecoverable without a power cycle. Each change below closes one such path.

1. The logger can no longer be blocked by a stalled USB host

Adafruit_USBD_CDC::write()'s send loop is bounded only by tud_cdc_n_connected() — literally "DTR is high" — so it spins forever when a host holds the port open but stops draining the IN endpoint. A blocked log write blocks loop().

nRF now writes through tud_cdc_write() directly, which is a bare tu_fifo_write_n that takes what fits and returns the count, making a stalled host structurally incapable of blocking. The delivery contract becomes best-effort and is documented in od_log.h:

• A record that will not fit waits up to 20 ms, then is discarded and counted.
• The count is reported on the next record that gets out, spliced after the level as [DROP: n] — one line, never an extra one, absent when zero.
• Records logged from a task other than loop() get a zero wait budget: waiting there would invert priority above loop().
• After 3 consecutive loop-task drops the budget goes to zero until something gets through. Without that backoff a stalled host costs the full budget per record — ~300 records per image push × 20 ms ≈ 6 s of added loop() latency, enough to starve BLE ACK draining and time out a transfer that would otherwise complete. It resets on any successful write, so recovery needs no detection of its own.

ESP32 output is unchanged. It keeps Stream::write and never drops or counts: neither of its log ports can block on host backpressure (HWCDC is bounded by max_consec_timeouts × tx_timeout_ms; the log UART has flow control hardwired off, so its FIFO always drains at the baud rate). Short writes there are deliberately ignored rather than counted, so ESP32 can never take the tagged path.

Two implementation details worth review attention, both load-bearing in non-obvious ways:

• In od_budget_ms(), the s_loopTask != NULL test must come first. xTaskGetCurrentTaskHandle() never returns NULL under a running scheduler, so without it an uncaptured handle would make the inequality true for every caller and silently put the whole firmware into try-once-then-drop.
• In od_port_wait_ready(), the room test must precede the expiry test, or a zero budget degenerates from "try once, then discard" into "discard without trying".

vTaskDelay(1) is used rather than delay(): the nRF core's delay() flushes CDC and returns early without ever calling vTaskDelay when that flush spans a tick, which would busy-spin at priority 2 and never yield to loop() (time slicing is disabled).

A static mutex covers the span from the capacity reservation to the last write of a record. It is not a hang guard — TinyUSB's FIFO is already multi-writer safe via CFG_FIFO_MUTEX — it prevents another producer consuming the reserved space mid-record and truncating the line.

2. A direct-write timeout no longer leaves its PIPE session running

A full PIPE transfer owns a direct-write session as its hardware half. The direct-write watchdog tore down the panel but left pipeState.active set, so the 0x0081 handler kept accepting frames into a torn-down session — and because cleanup zeroes the byte counters, the uncompressed auto-complete test read 0 >= 0 and drove a full refresh at an unpowered panel.

Both transfer watchdogs now live in display_service.cpp beside the state they terminate, sharing one TRANSFER_WATCHDOG_MS, and the direct-write branch resets the pipe half with it. A closing postcondition check ("a live, non-errored pipe session always has a hardware half") heals an orphan rather than only reporting it; it runs last so it also sees state either watchdog just created.

The && startTime > 0 sentinels are removed. This is invariant cleanup, not a live fix: zero is a legitimate millis() stamp, and treating it as "unset" would permanently disable the watchdog for a transfer beginning in the ~1 ms window where millis() wraps through zero — order 1 in 10^9 transfers.

3. A transport event interrupts the cooperative idle wait

An event raised after serviceBleEvents() ran in a pass was invisible until the next pass — and that pass may be about to park. A new non-destructive eventPending() peek joins workInFlight and idleDelay()'s early return, while serviceBleEvents() remains the single consumer, so event ordering, the disconnect RX-boundary capture and the deferred-cleanup flags are unaffected.

idleDelay() gains the membership rule for its break set: a term qualifies only if it can go false→true asynchronously on a task other than loop() and idleDelay cannot service that work itself. RX and transport events are the only two that qualify; the comment walks each excluded term against the rule.

Also: transferActive() splits in two

Callers were asking two different questions of the same flags.

• transferActive() — "is viable work in flight?" Now excludes a fatally NACKed pipe, whose panel sendPipeNack() has already released, so touch I2C polling and full-channel WiFi scans resume immediately rather than waiting for the client to speak.
• imageWriteFramesMayStillArrive() — "would logging this frame spam?" Keeps the errored pipe, because frames keep arriving after a fatal NACK: a client may already have a full window in flight. At ~90 frames/s and two lines each, un-suppressing them would evict the NACK itself from the log ring.

The split also keeps the new pipeState.error read off the logging path, which imageWriteLogQuietFrame() reaches cross-task from bleRxQueuePush().

Deliberately not changed

• No transfer-state term in workInFlight. A live transfer already has its connected BLE or LAN owner holding the gate, and one whose transport is gone cannot progress — holding the loop awake for it burns power for work that will never happen (on nRF a delay(1) gate is below the tickless threshold and spins rather than sleeping). That state is healed in checkTransferTimeouts() instead.
• The event take/clear protocol's coalescing weakness. A second same-type event arriving inside the check-then-clear window is lost. This is pre-existing; the new peek neither introduces nor worsens it, and fixing it belongs in a separate change.
• The watchdogs still measure from START, not from the last accepted frame, so they bound the whole transfer rather than a stall.

Validation

• tests/serial_stall_test.py is included as a hardware-in-the-loop repro for the USB CDC stall (it holds the port open without draining and checks that the tag keeps responding); tests/README.md documents running it.
• Build coverage is left to CI, which builds every environment.
• src/command_queue.cpp is comment-only — it retracts a cost claim ("blocking ~9 ms serial write") the rewrite invalidates.

Notes for reviewers

Design rationale for both halves is in the two plan docs added here: docs/PLAN_NONBLOCKING_LOG_2026-07-29.md and docs/PLAN_WORK_GATE_TRANSFER_TERMS_2026-07-29.md.

[davelee98]

Series of bugfixes to patch up edge cases that leave the Display stuck. Wait to merge until the next PR lands with a couple additional fixes and I have done a "burn-in" test.