# Changelog

## Session 2026-06-06

### faster-whisper backend (`lib/fw-stt.mjs`, `faster-whisper-server.py`)
- Added faster-whisper as an alternative STT backend with word-level timestamps
- Select with `--stt faster-whisper` flag on `query-demo.mjs`
- Python subprocess protocol: JSON lines over stdin/stdout, `ready\n` on startup
- Sherpa-onnx VAD still used for segment detection; transcription goes to Python

### Install script (`install-faster-whisper.sh`)
- Rewritten to use persistent build directory (`build/ctranslate2/`) instead of tmpfs temp dir — cmake's incremental build now works across runs
- Each step (clone, cmake build, Python bindings, faster-whisper) is skipped if already done
- Builds ctranslate2 C++ library from source against system CUDA 13 (PyPI wheel requires CUDA 12)
- Installs C++ library into venv so Python bindings find headers and library automatically
- Detects and removes PyPI ctranslate2 wheel (which bundles its own CUDA 12 library) before installing source-built bindings
- Fixed: `set -euo pipefail` was silently killing the script when `ls` found no files in symlink loop

### Bug fixes
- **`pending-query.mjs` alignment bug**: `new Int16Array(chunk.buffer, chunk.byteOffset, ...)` threw on odd byte offsets from Node.js Buffer pool slices, silently killing audio-based timer resets and causing premature silence timeouts mid-sentence. Fixed by copying to aligned buffer when `byteOffset % 2 !== 0`.
- **`query-demo.mjs` URL parsing**: `--debug-waveform` without a value was grabbing the next flag (`--stt`) as the URL. Fixed by checking that the parsed value doesn't start with `--`.
- **`fw-stt.mjs` silent fetch errors**: `_post_debug` was calling `fetch().catch(() => {})`, swallowing connection errors to the waveform viewer silently. Now logs failures.
- **`pending-query.mjs` instant dispatch timer leak**: silence timer was not cleared on instant dispatch, causing double-submit. Fixed by clearing timer and resetting state in the instant dispatch path.

### Global exception handling (`query-demo.mjs`)
- Added `process.on('uncaughtException')` and `process.on('unhandledRejection')` handlers to surface hidden errors in stderr.

### Command dispatch design (`COMMAND-DISPATCH.md`)
- Documented planned mode stack architecture with `check_parent` rule, frame types, and dispatch targets