## Summary
Addresses **Phase 1** of the inference infrastructure roadmap (#1661).
Six correctness and resilience issues fixed across adapters, workers,
and the unified protocol layer.
**Scope:** `packages/stage-ui/src/libs/inference/`,
`packages/stage-ui/src/libs/workers/`, `packages/stage-ui/src/workers/`
---
## Problems & Motivation
### 1. Kokoro Singleton cannot recover from terminal state
`getKokoroAdapter()` creates a singleton that is never reset. Once the
adapter reaches `terminated` or `error` (restarts exhausted), the
singleton is permanently dead -- users must refresh the page.
**Root cause:** `globalAdapter` is only re-created when `null`, never
checks the state of the existing instance. `scheduleRestart()` silently
returns when retries are exhausted, leaving state stuck at `'error'`
instead of transitioning to `'terminated'`.
**Fix:**
- `getKokoroAdapter()` now detects `terminated` / `error` states and
re-creates the adapter automatically
- `scheduleRestart()` in both Kokoro and Whisper adapters transitions to
`'terminated'` when max restarts are exhausted, making the dead state
detectable
### 2. `voices!` non-null assertion after nullable assignment
`kokoro.ts:275` assigns `voices = (response.metadata?.voices as Voices)
?? null` (can be null), but L288 returns `voices!` -- if the worker
returns unexpected metadata, callers receive `null` but the type system
promises `Voices`, causing downstream crashes.
**Fix:** Replaced with explicit null check + throw, routing into the
existing error recovery path.
### 3. Whisper Worker silently drops concurrent requests
The worker's `runInference()` has `if (processing) return` which
silently drops the request. The adapter's `waitForMessage()` never
receives a response, causing the Promise to hang for 120 seconds until
timeout.
**Root cause:** The bare boolean is safe in a single-threaded worker --
the real bug is the silent `return` with no error response.
**Fix:** Replaced with `sendError(requestId, ...)` so the adapter
receives an immediate rejection.
### 4. Whisper adapter leaks event listeners on worker restart
`ensureWorker()` attaches anonymous `message` and `error` listeners each
time a new Worker is created. `destroyWorker()` only calls
`worker.terminate()` without removing listeners. On restart paths
(`scheduleRestart -> ensureWorker`), old Worker listener closures may
prevent GC.
**Impact:** Whisper is most critical (2 listeners + restart logic).
Kokoro and Background Removal have the same pattern but lower risk.
**Fix:** All 3 adapters now store listener references and call
`removeEventListener` before `terminate()`. Whisper's
`terminateAdapter()` routes through `destroyWorker()` instead of direct
`worker.terminate()`.
### 5. Error classification is incomplete
`classifyError()` only matches 3 string patterns (OOM, DEVICE_LOST,
TIMEOUT). `LOAD_FAILED` and `INFERENCE_FAILED` are defined in the
`InferenceErrorCode` type but never produced. All workers hardcode
`recoverable: false`.
**Fix:**
- `classifyError(error, phase?)` gains a `phase` parameter: specific
patterns (OOM etc.) take priority, unmatched errors fall through to
`LOAD_FAILED` / `INFERENCE_FAILED` based on phase
- New `isRecoverable(code)` helper: TIMEOUT and DEVICE_LOST are
recoverable
- All 3 workers' `sendError()` updated to pass phase and use dynamic
recoverability
### 6. No dtype/device fallback chain
Kokoro Worker attempts model loading once with the requested dtype;
failure is terminal. Whisper Worker hardcodes `encoder_model: 'fp16'`
which crashes on devices that don't support it.
**Fix:**
- **Kokoro Worker:** New `DTYPE_FALLBACK` and `DEVICE_FALLBACK` maps.
Tries `fp16 -> fp32 -> q8 -> q4` on the same device, then `webgpu ->
wasm` device fallback. Reports `actualDtype` and `actualDevice` in
`ModelReadyResponse.metadata`
- **Whisper Worker:** Wraps fp16 encoder load in try-catch; falls back
to fp32
---
## State after changes
| Component | Before | After |
|-----------|--------|-------|
| Kokoro singleton | Returns dead instance forever after terminal error
| Auto-detects and re-creates |
| `voices` return | `voices!` can return null, lying to type system |
Explicit throw, enters error recovery path |
| Whisper Worker concurrency | Silent drop, Promise hangs 120s |
Immediate error response |
| Event listeners | Anonymous, never cleaned up | Stored references,
removeEventListener on destroy |
| Error classification | 4/6 codes reachable, recoverable hardcoded
false | 6/6 codes reachable, dynamic recoverability |
| dtype loading | Single attempt, failure is terminal | Progressive
fallback chain, reports actual config used |
---
## Files changed
| File | Changes |
|------|---------|
| `libs/inference/protocol.ts` | `classifyError` phase param, new
`isRecoverable` helper |
| `libs/inference/protocol.test.ts` | **New** -- 14 tests for
classification and recoverability |
| `libs/workers/worker.ts` | Silent drop fix, sendError phase, fp16
fallback |
| `workers/kokoro/worker.ts` | sendError phase, dtype/device fallback
chain |
| `workers/background-removal/worker.ts` | sendError phase |
| `libs/inference/adapters/whisper.ts` | Listener cleanup,
terminateAdapter uses destroyWorker, scheduleRestart terminal state |
| `libs/inference/adapters/kokoro.ts` | Singleton recovery, voices
assertion fix, listener cleanup, scheduleRestart terminal state |
| `libs/inference/adapters/kokoro.test.ts` | **New** -- 5 tests for
singleton and state transitions |
| `libs/inference/adapters/background-removal.ts` | Listener cleanup,
extracted destroyWorker |
## Test plan
- [x] `pnpm exec vitest run packages/stage-ui/src/libs/inference/` --
30/30 tests pass (protocol, kokoro adapter, GPU coordinator, load queue)
- [x] `pnpm -F @proj-airi/stage-ui typecheck` -- clean
- [x] `npx eslint` on all 9 changed files -- clean
- [x] Pre-commit hooks pass
Co-authored-by-agent: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
NJX
5187572c42