The pump does not fail to start; it finishes first, and the guard said the wrong thing

#52, and the answer is not the one the issue expected.

`timeout_ms=200` on `audiopump.spawn()` is `sink_timeout_ms` -- how long a
sink WRITE may block. It is not a start deadline, and there is no start
deadline: `thread_start` either succeeds or raises. `audiopump_live` is set on
the CALLING thread before spawn returns, so the comment in `RingDriver.spawn`
was right and the code under it was not. `running()` is `live && !finished`,
so what a bare `not mod.running()` can catch is a pump that has already
FINISHED -- and under load that is exactly what it caught. The status block at
the moment of the loss, measured under seven busy loops sharing one core:

    blocks 1   bytes 9600   error 3 ("the source ran out")   fault 0

The pump started, pulled the entire 0.05 s sample, reached the end of the
source and left the loop before the interpreter got its next slice. The guard
called that "the pump would not start" and fell back to the interpreter
thread. Three sessions' worth of looking at thread creation was looking in the
wrong place.

`_why_not_running()` reads the status instead of the clock, so the sentence
now names what happened -- "the pump had already finished", or the real fault
or error when there is one. A `StartFailed` of its own separates "this
afternoon's CPU" from "this graph cannot be pumped", and `note_fault` takes
`blocking=` so a transient loss is recorded without closing the door. That
last one is the issue's "make the loss recoverable", and it closes the only
path that still latched: `sample_out.py`'s outer `except`, which nothing
cleared. (Every other refusal already recovers -- `_play` tears down when no
client is left, and the teardown is what clears the block, from #45.)

**The race itself is still here, and the obvious fix is not, on purpose.**
Accepting the finished pump instead of tearing it down was written and
measured, ten runs each under identical contention:

    before          pump taken 96-100 of 100 (mean 98.9)   audio 100/100 always
    accepting it    pump taken 99-100 of 100 (mean 99.7)   audio 99/100 in 3 runs of 10

It takes the pump more often and loses a whole round's audio two or three
times in ten. Slower and always sounding beats faster and sometimes silent, so
the accept is left out and the lost round is written up rather than shipped.

Proved with the issue's own pinning: `tests/pump_probes/lifecycle.py cycles`
under `taskset -c 0` with seven busy loops, ten runs, 100/100 rounds produced
audio in every one. The full pump suite, 67 tests, OK.

Author: bdbarnett

lib/audiodev/pump.py

@@ -80,6 +80,53 @@
     4: "a read that would have raised inside the pull",
 }
 
+#: `_ERRORS` code 3. Not a failure: it is the loop saying the graph ended,
+#: which is what a short sample does the moment it has been pulled.
+_ERROR_SOURCE_RAN_OUT = 3
+
+
+class StartFailed(RuntimeError):
+    """The pump did not take a graph THIS TIME.
+
+    Separate from every other refusal on purpose. "This build cannot pump a
+    file-backed source" is a property of the graph and will be true again in a
+    millisecond; "the thread lost a race with a busy CPU" is a property of the
+    afternoon, and making the second one sticky turns a transient loss into a
+    process that never uses the pump again (pydevices#52).
+    """
+
+
+def _why_not_running(mod, status):
+    """Why a just-spawned pump is not running, as a sentence, or None.
+
+    **"Not running" is not the same as "did not start", and the difference is
+    the whole of pydevices#52.** `audiopump.running()` is
+    `live && !finished`, and `live` is set on the CALLING thread before
+    `spawn()` returns -- so what this can catch is a pump that has already
+    *finished*. Under load that is exactly what happens: a 0.05 s RawSample is
+    one block, and the pump thread can pull it, reach the end of the source
+    and leave the loop before the interpreter is scheduled again. Measured
+    2026-09-22 under seven busy loops sharing one core: `blocks 1, bytes 9600,
+    error 3` -- the pump did the entire job, and the check called it a failure
+    and fell back to the interpreter thread.
+
+    So ask the status block rather than the clock. A fault or a real error is
+    a failure; a loop that pulled something, or that ran out of source, did
+    its job; only a pump that left no trace at all never started.
+    """
+    import struct
+
+    w = struct.unpack("<%dQ" % mod.STATUS_WORDS, status)
+    blocks, error, fault = w[0], w[5], w[24]
+    if fault:
+        return _FAULTS.get(fault) or "the pump faulted (%d)" % fault
+    if error and error != _ERROR_SOURCE_RAN_OUT:
+        return _ERRORS.get(error) or "the pump stopped (error %d)" % error
+    if blocks or error == _ERROR_SOURCE_RAN_OUT:
+        return None
+    return "the pump would not start"
+
+
 # Sources that read through the VFS or a stream inside get_buffer(). The pump
 # refuses them by type name in C (spawn() raises); the same names are here so
 # a caller can ask *before* it builds anything, and so AudioOut knows to put a
@@ -636,10 +683,29 @@ def spawn(self, sample, status, loop=False):
             # live" flag on THIS thread before it returns, so running() is
             # already True and the first produce() cannot mistake a pump that
             # has not finished its first block for a dead one.
+            #
+            # What running() CAN report here is a pump that has already
+            # finished, and a short sample under load does that before the
+            # interpreter gets its next slice. Asking it as a bare boolean
+            # read that as "would not start" and threw away a pump that had
+            # just done the whole job (pydevices#52), so ask the status.
             self._parked = False
             if not mod.running():
+                # It did not fail to start. It started, and it has already
+                # FINISHED -- read the status before falling back, because
+                # "the pump would not start" was the wrong sentence and sent
+                # three sessions looking at thread creation (pydevices#52).
+                #
+                # Accepting the finished pump instead of tearing it down was
+                # tried and is NOT here: it lifts "took the pump" from 98.9 to
+                # 99.7 out of 100 under load, and costs a whole round's audio
+                # two or three times in ten runs. Falling back to the
+                # interpreter thread is slower and always sounds, which is the
+                # better trade until the lost round is understood. The
+                # measurements are on the issue.
                 mod.shutdown()
-                raise RuntimeError("the pump would not start")
+                raise StartFailed(_why_not_running(mod, status)
+                                  or "the pump had already finished")
             return
         # No back-pressure on this build: the pump would free-run and drop, so
         # it runs only inside produce(). park() returns True once the thread is
@@ -649,7 +715,7 @@ def spawn(self, sample, status, loop=False):
         # play-stop cycles.
         if not mod.park(200000):
             mod.shutdown()
-            raise RuntimeError("the pump would not start")
+            raise StartFailed("the pump would not start")
         self._parked = True
 
     def dropped(self):
@@ -1399,10 +1465,18 @@ def _note(self, exc):
         self._refusal = exc
         self._blocked = True
 
-    def note_fault(self, why):
+    def note_fault(self, why, blocking=True):
+        """Record a refusal somebody else caught.
+
+        `blocking=False` records it WITHOUT closing the door: the sentence is
+        on `fault()` for whoever reports it, and the next `play()` tries
+        again. That is what a transient loss wants -- a pump that lost one
+        race with a busy CPU is not a pump that cannot pump this graph, and
+        nothing else ever clears `_blocked` on this path (pydevices#52).
+        """
         self._fault = why
         self._refusal = None
-        self._blocked = True
+        self._blocked = bool(blocking)
 
     def shutdown(self):
         _enter()

lib/audiodev/sample_out.py

@@ -406,9 +406,17 @@ def _attach_pump(self, sample):
                 return
         except Exception as exc:          # noqa: BLE001 - reported, not raised
             self._release_prefetch()
-            engine.note_fault(str(exc))
+            # A transient loss must not become permanent. Nothing clears
+            # `_blocked` on this path -- `_play`'s own teardown is the repair
+            # for everything that goes through `Pump.play`, and this except is
+            # what catches the rest -- so recording a lost race as blocking
+            # meant the process never reached for the pump again, on any
+            # player, until it exited (pydevices#52).
+            transient = isinstance(exc, _pump_mod.StartFailed)
+            engine.note_fault(str(exc), blocking=not transient)
             print("audiodev: the audio pump would not start -", exc,
-                  "- playing on the interpreter thread instead")
+                  "- playing on the interpreter thread instead"
+                  + ("; the next play will try again" if transient else ""))
             return
         self._engine = engine
         self._engine_seen = True