python-voiceio 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

{python_voiceio-0.5.0.dist-info → python_voiceio-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.5.0
+Version: 0.7.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT

{python_voiceio-0.5.0.dist-info → python_voiceio-0.7.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-python_voiceio-0.5.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=LBK46heutvn3KmsCrKIYu8RQikbfnjZaj2xFrXaeCzQ,22
+python_voiceio-0.7.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=Xrd3UKJD109Bge0Qp6MiI_M_ztoHE7-18ltMxrpVUoI,63884
+voiceio/app.py,sha256=4o3nOv_Z_NCBr6KTHr1eSGT159ZE98dVBAy5wUOpzAo,64398
 voiceio/audit.py,sha256=vX3x-YAhmt6EZYRZd0_6wvTquZu5sxGMvH45BhSBnCk,14915
 voiceio/autocorrect.py,sha256=jGsglEYwAHWk2uWedeEZzyAMW2LWO_8nQGZgrWYy4Dc,26552
 voiceio/autocorrect_state.py,sha256=BNzdHP5slcOV_-OU4MlaKE7xgVJzrPncsYFK30JWTs8,6858
@@ -9,7 +9,7 @@ voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
 voiceio/cli.py,sha256=_HfcWQt2Jf34YfI4W1RavsyqegQy9jrg0nwLe6DvD6E,71639
 voiceio/clipboard_read.py,sha256=CqbHSvOztcQ3u2I2EzFm0jdcDVKv56gl0T1YfWxNpmI,3390
 voiceio/commands.py,sha256=Vhtn8s5G5OcCbRN44YZ-_14Fa85ISXl_3Ix-KqSHs2A,4694
-voiceio/config.py,sha256=L8_us8nthnNWFH1igJzyofuHf3ZQvGt-tz2WiXLRh7A,12925
+voiceio/config.py,sha256=CHDtEigtv-aKPsDFFGkc1AiqmubiFHeU1HaEaPgoIMc,14343
 voiceio/consent.py,sha256=jtdp1TkTbicUSTCDmV4qo4SdbS4kQpYzy1Kjc_7pJVw,1883
 voiceio/corrections.py,sha256=7moKhkVvo5CZU1mZobV2-MajkcHiwliKBY1dSBFh0w0,7445
 voiceio/demo.py,sha256=QRNJuNObXCsjwGD-Cz3dh81cfb21xiuSeVyyU720U9Q,8673
@@ -18,19 +18,19 @@ voiceio/health.py,sha256=5YNu1mMzwTo6I_Z_Mu3Bs46ZHDpVmxP0AXyMNAbaczc,15707
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
 voiceio/history.py,sha256=v7ciyZui8MndaKtTF5TdTKmql2ALOZNYKguE0Mo_lTY,5581
 voiceio/llm.py,sha256=_m13jodMVB1iEtze3VGkBCafkg85OssTPBEVyaRabgA,9250
-voiceio/llm_api.py,sha256=ex1brY10a8xNtw4cHCYC0yCth3Z02NkCQaHdB4XQPag,7497
+voiceio/llm_api.py,sha256=1wLLi6pliNmg-gS-bUKgwsGQSsLWAhX2XkEWXk292V8,9441
 voiceio/numbers.py,sha256=MP8jag4_F2OqUU5H14KzOmR9L8gWg48yQhLoUbGg_YI,8376
 voiceio/pidlock.py,sha256=RInlF_8H7wR0nqkdlhUfxYs7OGzHIvb5p-XDjjQSTNg,619
 voiceio/platform.py,sha256=f_8MmC5q1sCEuEPyKjRqlVvV9FExuGmwn_aJXhkpiEk,11809
-voiceio/postcorrect.py,sha256=lxm3zxdz3yzoR6qpf0bKRycBrF5y91bVnU4DqyTRbxU,8163
+voiceio/postcorrect.py,sha256=iyO7MPIR4a4XIASEGOs9Y3iUXVTfwtVkhVOWj2vY1lk,11201
 voiceio/postprocess.py,sha256=9grkq3I6XgiQV6ZQbIw2_fOUe57tzC7GBPvLXqhhdTs,2979
 voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
 voiceio/recorder.py,sha256=p1r0mH_plBD3BHqBbIGV_m2N4Mj5RAF7LfMu8u6mk5I,12813
-voiceio/retention.py,sha256=VrN261qL4C2_mSbjI6yPnMNiTVMxpo16wYua27TQb_Q,3330
+voiceio/retention.py,sha256=i_VWPCyykT4kQ1uKilTplpiIrACTYljn09BU1vL71A0,6019
 voiceio/service.py,sha256=jqX1opZyQh_dOJMK4bVf8Aoei0zOuuk1Ogta9BXTWGY,12106
 voiceio/snapshots.py,sha256=bm-lzIeYucDUDlPBZiFiWd-jyB2I6Ft1jRANZCO6go4,2351
-voiceio/streaming.py,sha256=90D6r162DQJd-s4fTb1NuLylrdh9gVyAnfNbaMbLQ6Y,15916
-voiceio/transcriber.py,sha256=D6_RLO8K3bGUV4CsS2q_k5rxkHTMB_6DqnzDka5mEb0,9939
+voiceio/streaming.py,sha256=3JMXBU1DAIDvItGRKlh7RGlD1zcGwgNcrFCKLkWdmTI,23215
+voiceio/transcriber.py,sha256=2ev_hwdusve7ZZqht9A9wtjjT72rcr7SuhmSIW8aClk,10721
 voiceio/vad.py,sha256=72_ICk4jSuSPYvTHdHYtHzY8W5uaGEOz5FTdqkolJi8,5327
 voiceio/vocabulary.py,sha256=eGV7QZs3tN6Cw5YpyoZsVEk2M5fJvie1n2XFi9CD4hw,6321
 voiceio/wizard.py,sha256=AwjwrocrQp0DPSOMZ0m6z6G3hlo9VPceEwPzR9-xXe0,80227
@@ -71,8 +71,8 @@ voiceio/typers/pynput_type.py,sha256=DTtkT59M-EKOAlTNkvcZrRvf_Fq52OpI8S5t_8S-QAY
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=dt0W9ot__W8LQG2so8vZLGIw9leK2Q6g3i-Voo0LXE4,5327
-python_voiceio-0.5.0.dist-info/METADATA,sha256=kdTrm0Dg20K3plJVL0hlhXcu9LOJRSUTkgyiupAHag0,15877
-python_voiceio-0.5.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_voiceio-0.5.0.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
-python_voiceio-0.5.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-0.5.0.dist-info/RECORD,,
+python_voiceio-0.7.0.dist-info/METADATA,sha256=hV7gmFjuAjAJpCb9O01qqobjZfk7qxk3Kjow7l5-oaI,15877
+python_voiceio-0.7.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_voiceio-0.7.0.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
+python_voiceio-0.7.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-0.7.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "0.5.0"
+__version__ = "0.7.0"

voiceio/app.py

@@ -393,6 +393,7 @@ class VoiceIO:
                 voice_input_prefix=self._voice_input_prefix,
                 on_typer_broken=self._on_typer_broken,
                 on_interim=self._on_interim_text,
+                freeze_secs=self.cfg.output.streaming_freeze_secs,
             )
             self._session.start()
         log.info("Recording... press [%s] again to stop", self.cfg.hotkey.key)
@@ -545,6 +546,16 @@ class VoiceIO:
                 duration=elapsed,
                 extra=extra,
             )
+            from voiceio import retention
+            retention.save_trace(self.cfg.data, {
+                "ts": time.time(),
+                "audio": extra.get("audio"),
+                "duration": round(elapsed, 2),
+                "latency": latency,
+                # Snapshot: a timed-out worker join means the thread may
+                # still be appending while we serialize.
+                "passes": list(session.trace),
+            })
         log.info("Streaming done (%.1fs): '%s'", elapsed, final_text)
         # Release the IBus input source now that the final commit is done.
         # Generation-checked inside: if a newer recording started, it already

voiceio/config.py

@@ -33,6 +33,11 @@ PID_PATH = LOG_DIR / "voiceio.pid"
 # and the retired-rule state consulted by the mining side.
 CORRECTIONS_AUDIT_PATH = LOG_DIR / "corrections_audit.jsonl"
 METRICS_PATH = LOG_DIR / "metrics.jsonl"
+# Intermediate pipeline data kept for debugging/profiling and future training:
+# per-pass streaming decode traces and postcorrect before/after pairs. These
+# live in their own JSONL files (not the rotating log) so they survive.
+TRACES_PATH = LOG_DIR / "streaming_trace.jsonl"
+POSTCORRECT_PAIRS_PATH = LOG_DIR / "postcorrect_pairs.jsonl"
 SNAPSHOTS_DIR = CONFIG_DIR / "snapshots"
 AUDIT_STATE_PATH = CONFIG_DIR / "audit_state.json"
 AUTOCORRECT_STATE_PATH = CONFIG_DIR / "autocorrect_state.json"
@@ -79,6 +84,11 @@ class OutputConfig:
     punctuation_cleanup: bool = True
     number_conversion: bool = True
     voice_input_prefix: str = ""           # e.g. "[voice]" — empty disables
+    # Incremental finalization: once the un-finalized audio tail grows past
+    # this many seconds AND ends in silence, beam-decode and freeze it during
+    # recording, so interim passes and the stop-time final decode only cover
+    # the short remaining tail. 0 disables (full re-decode at stop).
+    streaming_freeze_secs: float = 25.0
     # Mirror transcribed text to the system clipboard so it can be pasted:
     #   "off"   — never
     #   "final" — the corrected final text, once ready
@@ -137,7 +147,12 @@ class PostCorrectConfig:
     model can be overridden here; empty falls back to the autocorrect model.
     """
     enabled: bool = False
-    model: str = ""              # empty = use [autocorrect].model
+    # Latency-critical (blocks the commit): default to a fast cheap model.
+    # Bake-off on the real correction prompt: gemini-2.5-flash-lite 0.44s
+    # with fixes identical to kimi-k2's 2.0s. OpenRouter model id — on a
+    # custom base_url set a model your endpoint serves (empty = use
+    # [autocorrect].model).
+    model: str = "google/gemini-2.5-flash-lite"
     timeout_secs: float = 8.0
     min_words: int = 4           # skip utterances shorter than this
 
@@ -179,7 +194,14 @@ class DataConfig:
     """
     retain_audio: bool = True
     max_audio_mb: int = 4096   # prune oldest recordings beyond this
+    # Never let retention squeeze the disk: skip saving and prune harder
+    # when the filesystem has less than this much free space.
+    min_free_gb: float = 5.0
     capture_context: bool = True  # best-effort active-window title
+    # Per-pass streaming decode traces + postcorrect before/after pairs
+    # (streaming_trace.jsonl / postcorrect_pairs.jsonl) for debugging,
+    # profiling, and future fine-tuning.
+    capture_intermediates: bool = True
 
 
 @dataclass
@@ -283,6 +305,8 @@ def _content_files() -> list[Path]:
         HISTORY_PATH,
         CORRECTIONS_AUDIT_PATH,
         METRICS_PATH,
+        TRACES_PATH,
+        POSTCORRECT_PAIRS_PATH,
         AUDIT_STATE_PATH,
         AUTOCORRECT_STATE_PATH,
         CONSENT_PATH,

voiceio/llm_api.py

@@ -5,16 +5,73 @@ local Ollama (via /v1/chat/completions), etc. Zero dependencies beyond stdlib.
 """
 from __future__ import annotations
 
+import http.client
+import io
 import json
 import logging
 import os
+import threading
 import urllib.error
-import urllib.request
+from urllib.parse import urlsplit
 
 from voiceio.config import AutocorrectConfig
 
 log = logging.getLogger(__name__)
 
+# Keep-alive connection pool: a fresh TLS handshake costs ~0.2-0.5s per call,
+# which lands directly on postcorrect's stop-to-commit latency. Connections
+# are checked OUT for the duration of a request and returned only on clean
+# completion, so a deadline-abandoned postcorrect thread can never share a
+# socket with a later call.
+_POOL_LOCK = threading.Lock()
+_CONN_POOL: dict[str, http.client.HTTPConnection] = {}
+
+
+def _post_json(url: str, headers: dict, body: dict, timeout: float) -> dict:
+    """POST JSON over a pooled keep-alive connection; return the parsed reply.
+
+    A stale pooled connection (server closed it while idle) gets one retry on
+    a fresh one. Non-2xx raises urllib.error.HTTPError so callers keep their
+    existing status-code handling.
+    """
+    parts = urlsplit(url)
+    pool_key = f"{parts.scheme}://{parts.netloc}"
+    path = parts.path or "/"
+    payload = json.dumps(body).encode()
+
+    for attempt in (1, 2):
+        with _POOL_LOCK:
+            conn = _CONN_POOL.pop(pool_key, None)
+        pooled = conn is not None
+        if conn is None:
+            cls = (http.client.HTTPSConnection if parts.scheme == "https"
+                   else http.client.HTTPConnection)
+            conn = cls(parts.hostname, parts.port, timeout=timeout)
+        elif conn.sock is not None:
+            conn.sock.settimeout(timeout)
+        try:
+            conn.request("POST", path, body=payload, headers=headers)
+            resp = conn.getresponse()
+            data = resp.read()
+        except (http.client.HTTPException, OSError):
+            conn.close()
+            if not pooled or attempt == 2:
+                raise
+            continue  # stale keep-alive — retry once on a fresh connection
+        if resp.status // 100 != 2:
+            conn.close()
+            raise urllib.error.HTTPError(
+                url, resp.status, resp.reason, dict(resp.getheaders()),
+                io.BytesIO(data),
+            )
+        with _POOL_LOCK:
+            if pool_key in _CONN_POOL:
+                conn.close()  # keep at most one idle connection per host
+            else:
+                _CONN_POOL[pool_key] = conn
+        return json.loads(data)
+    raise AssertionError("unreachable")
+
 
 _LOCAL_HOSTS = ("localhost", "127.0.0.1", "0.0.0.0", "[::1]", "::1")
 _consent_warned = False
@@ -94,11 +151,7 @@ def _anthropic_request(
         "anthropic-version": "2023-06-01",
     }
 
-    req = urllib.request.Request(
-        url, data=json.dumps(body).encode(), headers=headers, method="POST",
-    )
-    with urllib.request.urlopen(req, timeout=timeout) as resp:
-        data = json.loads(resp.read())
+    data = _post_json(url, headers, body, timeout)
     # Anthropic returns content as a list of blocks; some thinking models
     # may also include `thinking` blocks which we ignore.
     blocks = data.get("content") or []
@@ -137,11 +190,7 @@ def _openai_request(
         "Authorization": f"Bearer {api_key}",
     }
 
-    req = urllib.request.Request(
-        url, data=json.dumps(body).encode(), headers=headers, method="POST",
-    )
-    with urllib.request.urlopen(req, timeout=timeout) as resp:
-        data = json.loads(resp.read())
+    data = _post_json(url, headers, body, timeout)
     # Be defensive: thinking models (Kimi K2.6, GPT reasoning, etc.) can
     # return content=None when the answer is in `reasoning` / `reasoning_content`
     # instead. Also some malformed responses lack `choices` entirely.

voiceio/postcorrect.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import dataclasses
 import difflib
 import logging
+import threading
 import time
 
 from voiceio.config import AutocorrectConfig, Config
@@ -90,6 +91,13 @@ class PostCorrector:
         self._vocabulary = ""
         self._recent: list[str] = []
         self._context: str | None = None
+        # Context actually sent with the in-progress correct() call (what
+        # _record must persist — may differ from self._context).
+        self._effective_ctx: str | None = None
+        # A worker abandoned at the deadline may block indefinitely on a hung
+        # endpoint; cap leakage at one thread/socket by skipping new calls
+        # while it is still alive.
+        self._abandoned: threading.Thread | None = None
 
     # ── availability ────────────────────────────────────────────────────
 
@@ -140,6 +148,27 @@ class PostCorrector:
         parts.append(f"Transcript to correct:\n{text}")
         return "\n\n".join(parts)
 
+    def _record(self, before: str, after: str | None, outcome: str) -> None:
+        """Persist one LLM attempt (before/after/outcome) as training data.
+
+        Pairs land in postcorrect_pairs.jsonl — unlike the rotating log they
+        survive, so accepted AND rejected corrections stay available for
+        tuning guards or training a local corrector later.
+        """
+        if not self._cfg.data.capture_intermediates:
+            return
+        from voiceio import retention
+        from voiceio.config import POSTCORRECT_PAIRS_PATH
+        retention.append_jsonl(POSTCORRECT_PAIRS_PATH, {
+            "ts": time.time(),
+            "before": before,
+            "after": after,
+            "outcome": outcome,
+            "secs": round(self.last_secs, 3) if self.last_secs is not None else None,
+            "model": self._pc.model or self._ac.model,
+            "context": self._effective_ctx,
+        })
+
     def correct(
         self, text: str, *, vocabulary: str = "",
         recent: list[str] | None = None, context: str | None = None,
@@ -161,28 +190,65 @@ class PostCorrector:
         vocab = vocabulary or self._vocabulary
         rec = recent if recent is not None else self._recent
         ctx = context if context is not None else self._context
+        self._effective_ctx = ctx
+
+        if self._abandoned is not None:
+            if self._abandoned.is_alive():
+                log.warning(
+                    "PostCorrector: previous request still hung — skipping this one",
+                )
+                self._record(text, None, "skipped_busy")
+                return text
+            self._abandoned = None
 
         from voiceio.llm_api import chat
         user_msg = self._build_user_message(text, vocab, rec, ctx)
+        # timeout_secs must bound the WALL CLOCK the user waits, but urllib's
+        # timeout is per-socket-read — a slowly streaming response can run
+        # far past it (observed ~14s with an 8s config). Run the call in a
+        # thread and abandon it at the deadline.
         t0 = time.monotonic()
-        try:
-            response = chat(self._client_cfg(), _SYSTEM_PROMPT, user_msg, max_tokens=1024)
-        except Exception as e:
-            log.debug("PostCorrector LLM error: %s — keeping original", e)
+        outcome: dict = {}
+
+        def _call() -> None:
+            try:
+                outcome["response"] = chat(
+                    self._client_cfg(), _SYSTEM_PROMPT, user_msg, max_tokens=1024,
+                )
+            except Exception as e:
+                outcome["error"] = e
+
+        worker = threading.Thread(target=_call, daemon=True)
+        worker.start()
+        worker.join(self._pc.timeout_secs)
+        self.last_secs = time.monotonic() - t0
+        if worker.is_alive():
+            log.debug(
+                "PostCorrector deadline (%.1fs) exceeded — keeping original",
+                self._pc.timeout_secs,
+            )
+            self._abandoned = worker
+            self._record(text, None, "timeout")
+            return text
+        if "error" in outcome:
+            log.debug("PostCorrector LLM error: %s — keeping original", outcome["error"])
+            self._record(text, None, "error")
             return text
-        finally:
-            self.last_secs = time.monotonic() - t0
+        response = outcome.get("response")
 
         if not response:
             log.debug("PostCorrector: empty/failed response — keeping original")
+            self._record(text, None, "empty")
             return text
 
         corrected = _strip_wrapping(response)
         if not corrected:
             log.debug("PostCorrector: response empty after stripping — keeping original")
+            self._record(text, None, "empty")
             return text
 
         if corrected == text:
+            self._record(text, corrected, "unchanged")
             return text
 
         # Guard: word-count must not change materially.
@@ -192,6 +258,7 @@ class PostCorrector:
                 "PostCorrector reject: word count %d→%d (>%.0f%%) — keeping original",
                 orig_wc, new_wc, _MAX_WORDCOUNT_DELTA * 100,
             )
+            self._record(text, corrected, "rejected_wordcount")
             return text
 
         # Guard: only a small fraction of words may change.
@@ -201,7 +268,9 @@ class PostCorrector:
                 "PostCorrector reject: edit ratio %.2f > %.2f — keeping original",
                 ratio, _MAX_EDIT_RATIO,
             )
+            self._record(text, corrected, "rejected_editratio")
             return text
 
         log.info("PostCorrector fixed: %s", ", ".join(_changed_words(text, corrected)))
+        self._record(text, corrected, "applied")
         return corrected

voiceio/retention.py

@@ -7,17 +7,19 @@ mining measurable and personal fine-tuning possible later.
 from __future__ import annotations
 
 import functools
+import json
 import logging
 import shutil
 import subprocess
 import time
 import wave
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 
 from voiceio import config
-from voiceio.config import RECORDINGS_DIR
+from voiceio.config import RECORDINGS_DIR, TRACES_PATH
 
 if TYPE_CHECKING:
     from voiceio.config import DataConfig
@@ -27,11 +29,25 @@ log = logging.getLogger(__name__)
 _which = functools.lru_cache(maxsize=8)(shutil.which)
 
 
+def _free_gb(path: Path) -> float:
+    """Free space (GB) on the filesystem holding `path`. Inf on failure."""
+    try:
+        return shutil.disk_usage(path).free / 1024**3
+    except OSError:
+        return float("inf")
+
+
 def save_audio(audio: np.ndarray, ts: float, cfg: DataConfig) -> str | None:
     """Persist one utterance as 16kHz mono int16 WAV. Returns the filename
     (relative to the recordings dir) or None if disabled/failed."""
     if not cfg.retain_audio or audio is None or len(audio) == 0:
         return None
+    if _free_gb(RECORDINGS_DIR.parent) < cfg.min_free_gb:
+        log.warning(
+            "Disk has <%.0fGB free — skipping audio retention for this utterance",
+            cfg.min_free_gb,
+        )
+        return None
     name = time.strftime("%Y%m%d-%H%M%S", time.localtime(ts)) + f"-{int(ts * 1000) % 1000:03d}.wav"
     path = RECORDINGS_DIR / name
     try:
@@ -70,6 +86,15 @@ def prune(cfg: DataConfig) -> None:
         )
         total = sum(p.stat().st_size for p in files)
         budget = cfg.max_audio_mb * 1024 * 1024
+        # Below the free-disk floor, shrink the budget so retention yields
+        # space back instead of holding its full cap on a squeezed disk.
+        free = _free_gb(RECORDINGS_DIR.parent)
+        if free < cfg.min_free_gb:
+            budget = min(budget, total // 2)
+            log.warning(
+                "Disk has %.1fGB free (<%.0fGB floor) — pruning recordings to %.0fMB",
+                free, cfg.min_free_gb, budget / 1024 / 1024,
+            )
         while total > budget and files:
             oldest = files.pop(0)
             total -= oldest.stat().st_size
@@ -79,6 +104,45 @@ def prune(cfg: DataConfig) -> None:
         log.debug("Recording prune failed", exc_info=True)
 
 
+_JSONL_MAX_BYTES = 64 * 1024 * 1024  # per capture file; oldest half dropped
+
+
+def append_jsonl(path: Path, entry: dict) -> None:
+    """Append one JSON line to a 0600 data file. Best-effort, never raises.
+
+    Capture files are bounded: past _JSONL_MAX_BYTES the oldest half of the
+    lines is dropped, so intermediate-data capture can never grow unbounded
+    on a disk the min_free_gb floor is trying to protect.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        config._chmod(path.parent, config._SECURE_DIR)
+        newly_created = not path.exists()
+        if not newly_created and path.stat().st_size > _JSONL_MAX_BYTES:
+            lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+            path.write_text("".join(lines[len(lines) // 2:]), encoding="utf-8")
+            log.info("Trimmed %s to newest %d entries", path.name, len(lines) - len(lines) // 2)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        if newly_created:
+            config._chmod(path, config._SECURE_FILE)
+    except (OSError, TypeError, ValueError) as e:
+        log.warning("Failed to write %s: %s", path.name, e)
+
+
+def save_trace(cfg: DataConfig, entry: dict) -> None:
+    """Persist one utterance's per-pass streaming decode trace.
+
+    One line per utterance in streaming_trace.jsonl: pass timings, kinds
+    (interim/freeze/final), tail lengths, and raw tail texts — the data
+    needed to debug/profile streaming behaviour and to train on interim
+    hypotheses later. Linked to history via ts + audio filename.
+    """
+    if not cfg.capture_intermediates:
+        return
+    append_jsonl(TRACES_PATH, entry)
+
+
 def active_window_title() -> str | None:
     """Best-effort title of the focused window (dictation target context).
 

voiceio/streaming.py

@@ -8,11 +8,12 @@ import threading
 import time
 from typing import TYPE_CHECKING, Callable
 
+import numpy as np
+
 from voiceio.transcriber import transcribe_timeout
 from voiceio.typers.base import StreamingTyper
 
 if TYPE_CHECKING:
-    import numpy as np
     from voiceio.commands import CommandProcessor
     from voiceio.corrections import CorrectionDict
     from voiceio.llm import LLMProcessor
@@ -24,6 +25,35 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 DELETE_SETTLE_SECS = 0.05  # delay between delete and type for ydotool reliability
 
+# Incremental finalization: a freeze cut is only safe at a speech pause, so
+# require the tail's trailing window to be quiet before cutting there.
+_FREEZE_SILENCE_WINDOW_SECS = 0.3
+# Quiet is judged RELATIVE to the tail's own level: mic gains vary wildly
+# and the decode path normalizes audio anyway, so an absolute threshold
+# would read a quiet mic's speech as silence (mid-word cuts) and a hot
+# noise floor as speech (freeze never fires).
+# Calibrated on real recordings: between-words noise floor sits at
+# ~0.27-0.38 of overall tail RMS, speech windows at >=0.9. 0.6 separates
+# both with margin; 0.15 never fired on a mic with a normal noise floor.
+_FREEZE_SILENCE_RATIO = 0.6
+_FREEZE_SILENCE_FLOOR = 1e-4  # digital silence is always quiet
+# Whisper conditions on ~224 prompt tokens; more frozen context is wasted.
+_FREEZE_CONTEXT_CHARS = 400
+
+
+def _rms(samples: np.ndarray) -> float:
+    return float(np.sqrt(np.mean(np.square(samples, dtype=np.float64))))
+
+
+def _tail_ends_in_silence(tail: np.ndarray, sample_rate: int) -> bool:
+    """True when the last _FREEZE_SILENCE_WINDOW_SECS of audio are quiet
+    relative to the tail's overall level."""
+    window = tail[-int(_FREEZE_SILENCE_WINDOW_SECS * sample_rate):]
+    if len(window) == 0:
+        return False
+    threshold = max(_FREEZE_SILENCE_RATIO * _rms(tail), _FREEZE_SILENCE_FLOOR)
+    return _rms(window) < threshold
+
 
 def _common_prefix_len(a: str, b: str) -> int:
     """Length of the longest common prefix between two strings."""
@@ -34,6 +64,16 @@ def _common_prefix_len(a: str, b: str) -> int:
     return limit
 
 
+def _join_text(a: str, b: str) -> str:
+    """Join two transcript fragments with a single space."""
+    a, b = a.strip(), (b or "").strip()
+    if not a:
+        return b
+    if not b:
+        return a
+    return a + " " + b
+
+
 def _clean_word(w: str) -> str:
     """Strip punctuation for fuzzy word matching."""
     return re.sub(r'[^\w]', '', w).lower()
@@ -85,6 +125,7 @@ class StreamingSession:
         on_typer_broken: Callable[[], None] | None = None,
         is_current: Callable[[], bool] | None = None,
         on_interim: Callable[[str], None] | None = None,
+        freeze_secs: float = 25.0,
     ):
         self._transcriber = transcriber
         self._typer = typer
@@ -113,10 +154,27 @@ class StreamingSession:
         self._stop_event = threading.Event()
         self._worker_thread: threading.Thread | None = None
         self._final_audio: np.ndarray | None = None  # set on stop
+        # Incremental finalization: audio before _frozen_samples has already
+        # been beam-decoded into _frozen_raw and is never decoded again.
+        # Interim and final passes only decode the tail after this offset.
+        self._freeze_secs = freeze_secs
+        self._frozen_samples = 0
+        self._frozen_raw = ""
+        self._frozen_segments: list[dict] = []
+        # Decode backpressure: when the CPU is contended, decodes slow down
+        # and 1s-tick interim passes would queue back-to-back, each covering
+        # a longer tail — a starvation spiral. Require at least as much NEW
+        # audio as the last decode took before starting another interim.
+        self._last_decode_end = 0     # samples covered by the last decode
+        self._last_decode_secs = 0.0  # how long that decode took
         # Raw (pre-pipeline) text + confidence of the final pass, for history
         self.raw_final_text: str | None = None
         self.final_latency: dict = {}
         self.final_segments: list[dict] = []
+        # Per-pass decode trace (interim/freeze/final) for debugging,
+        # profiling, and future training. Persisted via retention.save_trace.
+        self.trace: list[dict] = []
+        self._t0 = time.monotonic()
 
     @property
     def interim_text(self) -> str:
@@ -213,10 +271,22 @@ class StreamingSession:
             log.exception("Final transcribe/apply error")
         self._final_audio = None  # release memory
 
+    def _frozen_context(self) -> str | None:
+        """Frozen-text suffix used to condition the tail decode."""
+        if not self._frozen_raw:
+            return None
+        return self._frozen_raw[-_FREEZE_CONTEXT_CHARS:]
+
     def _transcribe_and_apply(
         self, min_seconds: float = 1.0, final: bool = False,
     ) -> None:
-        """Get audio, transcribe, apply correction."""
+        """Get audio, transcribe the un-frozen tail, apply correction.
+
+        Incremental finalization: audio before _frozen_samples was already
+        beam-decoded and frozen, so every pass — including the final one —
+        only decodes the tail. Long dictations finalize in O(tail), not
+        O(recording).
+        """
         if final and self._final_audio is not None:
             # Use the snapshot passed to stop() — recorder may be gone
             audio = self._final_audio
@@ -230,22 +300,96 @@ class StreamingSession:
         if len(audio) < self._sample_rate * min_seconds:
             return
 
+        tail = audio[self._frozen_samples:]
+        if not final and len(tail) < self._sample_rate * min_seconds:
+            return  # not enough new audio since the last freeze
+        grown_secs = (len(audio) - self._last_decode_end) / self._sample_rate
+        if not final and grown_secs < max(min_seconds, self._last_decode_secs):
+            return  # backpressure: don't decode faster than we can keep up
+
+        # Freeze when the tail has grown long AND ends at a speech pause
+        # (never cut mid-word). The freeze pass gets beam search because its
+        # text is never decoded again.
+        freeze = (
+            not final
+            and self._freeze_secs > 0
+            and len(tail) >= self._freeze_secs * self._sample_rate
+            and _tail_ends_in_silence(tail, self._sample_rate)
+        )
+
+        tail_text = ""
+        tail_segments: list[dict] = []
         t0 = time.monotonic()
-        try:
-            text = self._transcriber.transcribe(audio, final=final)
-        except Exception:
-            log.exception("Streaming transcription failed")
-            return
+        # The final pass decodes ANY remaining audio (a clipped last word
+        # must not be dropped); interim/freeze passes skip sub-0.3s tails.
+        if len(tail) > (0 if final else self._sample_rate * 0.3):
+            try:
+                tail_text = self._transcriber.transcribe(
+                    tail, final=final or freeze, context=self._frozen_context(),
+                )
+            except Exception:
+                # Decode FAILED (timeout/crash) — this is not silence. Never
+                # advance the freeze boundary or char-diff against a partial
+                # transcript; on final, commit what is already on screen.
+                log.exception("Streaming transcription failed")
+                if final:
+                    self.raw_final_text = ""
+                    self.final_latency = {
+                        "audio_secs": round(len(audio) / self._sample_rate, 2),
+                        "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+                        "tail_secs": round(len(tail) / self._sample_rate, 2),
+                        "transcribe": round(time.monotonic() - t0, 3),
+                        "decode_failed": True,
+                    }
+                    self._commit_interim_on_final()
+                return
+            tail_segments = list(getattr(self._transcriber, "last_segments", []))
         t_transcribe = time.monotonic() - t0
+        self._last_decode_end = len(audio)
+        self._last_decode_secs = t_transcribe
+
+        self.trace.append({
+            "t": round(time.monotonic() - self._t0, 2),
+            "kind": "final" if final else ("freeze" if freeze else "interim"),
+            "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+            "tail_secs": round(len(tail) / self._sample_rate, 2),
+            "secs": round(t_transcribe, 3),
+            "text": tail_text,
+        })
+
+        if freeze:
+            self._frozen_raw = _join_text(self._frozen_raw, tail_text)
+            self._frozen_samples = len(audio)
+            self._frozen_segments.extend(tail_segments)
+            log.debug(
+                "Froze %.1fs of audio (frozen text now %d chars)",
+                len(tail) / self._sample_rate, len(self._frozen_raw),
+            )
+        raw = self._frozen_raw if freeze else _join_text(self._frozen_raw, tail_text)
+
+        # A slow interim decode can complete AFTER the user pressed stop
+        # (observed: 29s under CPU contention). Applying it would overwrite
+        # the preedit with stale partial text moments before the final
+        # commit rewrites it again — discard it. Freeze bookkeeping above
+        # is kept: it is beam-quality and shrinks the final tail.
+        if not final and self._stop_event.is_set():
+            return
+        # An interim pass that decoded nothing must not touch the display:
+        # rewriting to frozen-only text would visibly delete the un-frozen
+        # words the previous pass just showed (transient decoder flake).
+        if not final and not tail_text:
+            return
 
         if final:
-            self.raw_final_text = text
-            self.final_segments = getattr(self._transcriber, "last_segments", [])
+            self.raw_final_text = raw
+            self.final_segments = self._frozen_segments + tail_segments
             self.final_latency = {
                 "audio_secs": round(len(audio) / self._sample_rate, 2),
+                "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+                "tail_secs": round(len(tail) / self._sample_rate, 2),
                 "transcribe": round(t_transcribe, 3),
             }
-            if not text:
+            if not raw:
                 # The final pass produced nothing. If we already have interim
                 # text (e.g. the final transcription timed out on a long
                 # dictation), commit that instead of silently dropping it —
@@ -253,11 +397,11 @@ class StreamingSession:
                 self._commit_interim_on_final()
                 return
 
-        if text and isinstance(text, str):
+        if raw:
             from voiceio.postprocess import apply_pipeline
             t1 = time.monotonic()
             text, abort = apply_pipeline(
-                text,
+                raw,
                 do_cleanup=self._cleanup,
                 number_conversion=self._number_conversion,
                 language=self._language,
@@ -274,6 +418,11 @@ class StreamingSession:
                 if pc_secs is not None:
                     self.final_latency["postcorrect"] = round(pc_secs, 3)
             if abort:
+                # A voice command wiped the utterance — discard frozen text
+                # too, or the next pass would resurrect it.
+                self._frozen_raw = ""
+                self._frozen_segments = []
+                self._frozen_samples = len(audio)
                 # A superseded session must not touch the typer on the final
                 # path (would corrupt the newer session's output).
                 if final and not self._is_current():

voiceio/transcriber.py

@@ -18,6 +18,12 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 
 TRANSCRIBE_TIMEOUT = 30  # seconds (floor; scaled up for long audio)
+
+
+class TranscriptionError(RuntimeError):
+    """Decode failed (timeout / worker crash). Distinct from a legitimate
+    empty result ("" = silence) so callers never treat lost audio as decoded
+    silence — the streaming freeze/final paths must not advance state on it."""
 # Realtime-factor headroom for the read timeout. Whisper decodes well faster
 # than realtime, so 1.5x the audio duration is a generous ceiling that still
 # never kills a long dictation mid-decode.
@@ -152,10 +158,17 @@ class Transcriber:
         log.warning("Worker died, restarting (attempt %d/%d)", self._restarts, MAX_RESTARTS)
         self._start_worker()
 
-    def transcribe(self, audio: np.ndarray, final: bool = False) -> str:
+    def transcribe(
+        self, audio: np.ndarray, final: bool = False, context: str | None = None,
+    ) -> str:
         """Transcribe audio. `final=True` marks the pass whose text the user
         keeps (streaming final / batch): it gets beam search; interim streaming
-        passes stay greedy for latency."""
+        passes stay greedy for latency.
+
+        `context` is per-call text appended to the initial_prompt — used by
+        incremental finalization to condition a tail decode on the already-
+        frozen transcript so sentences stay coherent across the cut.
+        """
         with self._lock:
             self._ensure_worker()
 
@@ -165,8 +178,9 @@ class Transcriber:
             audio = normalize_audio(audio)
             audio_b64 = base64.b64encode(audio.tobytes()).decode("ascii")
             req = {"audio_b64": audio_b64, "options": {"beam_size": 5 if final else 1}}
-            if self._initial_prompt:
-                req["initial_prompt"] = self._initial_prompt
+            prompt = "\n".join(p for p in (self._initial_prompt, context) if p)
+            if prompt:
+                req["initial_prompt"] = prompt
             if self._hotwords:
                 req["hotwords"] = self._hotwords
             try:
@@ -184,16 +198,18 @@ class Transcriber:
             timeout = transcribe_timeout(duration)
             result_line = self._read_with_timeout(timeout)
             if result_line is None:
+                self.last_segments = []
                 log.warning("Transcription timed out after %.0fs, restarting worker", timeout)
                 self._kill_worker()
                 self._ensure_worker()
-                return ""
+                raise TranscriptionError(f"decode timed out after {timeout:.0f}s")
 
             try:
                 result = json.loads(result_line)
             except (json.JSONDecodeError, TypeError):
+                self.last_segments = []
                 log.warning("Invalid response from worker: %s", repr(result_line)[:100])
-                return ""
+                raise TranscriptionError("invalid worker response")
             text = result.get("text", "")
             self.last_segments = result.get("segments", [])