python-voiceio 1.9.2__tar.gz → 1.9.3__tar.gz

{python_voiceio-1.9.2/python_voiceio.egg-info → python_voiceio-1.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.9.2
+Version: 1.9.3
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -98,7 +98,7 @@ voiceio learn schedule on             # learn from your recordings while the mac
 voiceio learn status                  # what it learned and how each model scores
 ```
 
-Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
 ## Configure
 

{python_voiceio-1.9.2 → python_voiceio-1.9.3}/README.md

@@ -45,7 +45,7 @@ voiceio learn schedule on             # learn from your recordings while the mac
 voiceio learn status                  # what it learned and how each model scores
 ```
 
-Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
 ## Configure
 

{python_voiceio-1.9.2 → python_voiceio-1.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "1.9.2"
+version = "1.9.3"
 description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"

{python_voiceio-1.9.2 → python_voiceio-1.9.3/python_voiceio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.9.2
+Version: 1.9.3
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -98,7 +98,7 @@ voiceio learn schedule on             # learn from your recordings while the mac
 voiceio learn status                  # what it learned and how each model scores
 ```
 
-Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
 ## Configure
 

{python_voiceio-1.9.2 → python_voiceio-1.9.3}/python_voiceio.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ tests/test_concurrency_lockdown.py
 tests/test_config.py
 tests/test_context_terms.py
 tests/test_corrections.py
+tests/test_dead_mic.py
 tests/test_decoders.py
 tests/test_engine.py
 tests/test_evdev_uaccess.py
@@ -46,6 +47,7 @@ tests/test_learn_language.py
 tests/test_learn_metrics.py
 tests/test_learn_pipeline.py
 tests/test_learn_quiet.py
+tests/test_learn_resume.py
 tests/test_learn_review.py
 tests/test_learn_targets.py
 tests/test_llm.py
@@ -58,6 +60,7 @@ tests/test_platform.py
 tests/test_postcorrect.py
 tests/test_postprocess.py
 tests/test_prebuffer.py
+tests/test_presence.py
 tests/test_prompt.py
 tests/test_quiet_audio.py
 tests/test_recorder_integration.py
@@ -104,6 +107,7 @@ voiceio/platform.py
 voiceio/postcorrect.py
 voiceio/postprocess.py
 voiceio/power.py
+voiceio/presence.py
 voiceio/privacy.py
 voiceio/prompt.py
 voiceio/quiet_audio.py

python_voiceio-1.9.3/tests/test_dead_mic.py

@@ -0,0 +1,94 @@
+"""A mic stream that dies mid-recording is reopened, not recorded to the end.
+
+The real failure: after a suspend/resume the stream delivered 2 s of audio,
+then 102 s of exact zeros; the whole dictation was lost.
+"""
+from __future__ import annotations
+
+import threading
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+
+from voiceio.config import AudioConfig
+from voiceio.recorder import AudioRecorder
+
+
+def _recorder() -> AudioRecorder:
+    rec = AudioRecorder(AudioConfig(sample_rate=16000, prebuffer_secs=0.5,
+                                    auto_stop_silence_secs=0, auto_stop_no_speech_secs=0))
+    rec._stream = MagicMock()
+    return rec
+
+
+def _feed(rec: AudioRecorder, value: float, secs: float) -> None:
+    for _ in range(int(secs * 16000 / 1600)):
+        rec._callback(np.full((1600, 1), value, dtype=np.float32), 1600, None, None)
+
+
+def _armed(rec: AudioRecorder) -> threading.Event:
+    fired = threading.Event()
+    rec.set_on_dead_stream(fired.set)
+    return fired
+
+
+def test_zeros_after_real_audio_fire_once():
+    rec = _recorder()
+    rec.start()
+    fired = _armed(rec)
+    _feed(rec, 0.02, 1.0)
+    _feed(rec, 0.0, 1.2)
+    assert fired.wait(2)
+    fired.clear()
+    _feed(rec, 0.0, 1.2)            # still reviving: not fired again
+    assert not fired.wait(0.2)
+
+
+def test_a_mic_silent_from_the_start_is_left_to_the_muted_check():
+    rec = _recorder()
+    rec.start()
+    fired = _armed(rec)
+    _feed(rec, 0.0, 2.0)
+    assert not fired.wait(0.2)
+
+
+def test_quiet_room_noise_is_not_a_dead_stream():
+    rec = _recorder()
+    rec.start()
+    fired = _armed(rec)
+    _feed(rec, 0.02, 0.5)
+    _feed(rec, 0.0005, 3.0)        # a working mic's silence is never exact zero
+    assert not fired.wait(0.2)
+
+
+def test_revive_reopens_and_allows_at_most_two_attempts():
+    rec = _recorder()
+    rec.start()
+    with patch.object(rec, "open_stream") as opened, patch.object(rec, "close_stream"):
+        for expected in (True, True, False):
+            fired = _armed(rec)
+            _feed(rec, 0.02, 0.2)
+            _feed(rec, 0.0, 1.2)
+            assert fired.wait(0.5) is expected
+            if expected:
+                rec.revive_stream()
+        assert opened.call_count == 2
+    assert rec.is_recording
+
+
+def test_daemon_revives_and_warns_only_when_still_dead():
+    from voiceio.app import VoiceIO, _State
+    vio = VoiceIO.__new__(VoiceIO)
+    vio._hotkey_lock = threading.Lock()
+    vio._state = _State.RECORDING
+    vio._recording = 7
+    vio.recorder = MagicMock(silent_signal_secs=0.0)
+    with patch("voiceio.app.time.sleep"), patch("voiceio.feedback.notify") as notify:
+        vio._revive_mic(7)
+        vio.recorder.revive_stream.assert_called_once()
+        notify.assert_not_called()
+        vio.recorder.silent_signal_secs = 1.5
+        vio._revive_mic(7)
+        notify.assert_called_once()
+        vio._revive_mic(8)              # a later recording: not ours to touch
+        assert vio.recorder.revive_stream.call_count == 2

python_voiceio-1.9.3/tests/test_learn_quiet.py

@@ -0,0 +1,247 @@
+import argparse
+
+import pytest
+
+from voiceio import power
+from voiceio.learn import quiet
+
+
+def _supply(root, name, kind, online):
+    d = root / name
+    d.mkdir()
+    (d / "type").write_text(kind + "\n")
+    (d / "online").write_text(online + "\n")
+
+
+def test_on_battery_needs_a_mains_supply_that_is_offline(tmp_path):
+    assert not power.on_battery(tmp_path)                 # desktop: no supplies listed
+    _supply(tmp_path, "BAT0", "Battery", "0")
+    _supply(tmp_path, "AC", "Mains", "0")
+    assert power.on_battery(tmp_path)
+    (tmp_path / "AC" / "online").write_text("1\n")
+    assert not power.on_battery(tmp_path)
+
+
+def test_busy_reason_is_load_per_cpu_then_battery(monkeypatch):
+    monkeypatch.setattr(quiet.os, "cpu_count", lambda: 8)
+    monkeypatch.setattr(quiet, "on_battery", lambda: False)
+    monkeypatch.setattr(quiet.os, "getloadavg", lambda: (4.0, 0, 0))     # 0.5 per CPU
+    assert "load 0.50 per CPU" in quiet.busy_reason(0.25)
+    monkeypatch.setattr(quiet.os, "getloadavg", lambda: (1.0, 0, 0))
+    assert quiet.busy_reason(0.25) is None
+    monkeypatch.setattr(quiet, "on_battery", lambda: True)
+    assert quiet.busy_reason(0.25) == "on battery"
+
+
+def test_wait_until_quiet_waits_then_gives_up(monkeypatch):
+    now = [0.0]
+    sleeps = []
+    reasons = iter(["busy", "busy", None])
+    monkeypatch.setattr(quiet, "busy_reason", lambda *_: next(reasons))
+    args = dict(poll=300, sleep=lambda s: (sleeps.append(s), now.__setitem__(0, now[0] + s)),
+                clock=lambda: now[0], say=lambda _: None)
+    assert quiet.wait_until_quiet(0.25, 3, **args)
+    assert sleeps == [300, 300]
+
+    monkeypatch.setattr(quiet, "busy_reason", lambda *_: "on battery")
+    said = []
+    now[0] = 0.0
+    assert not quiet.wait_until_quiet(0.25, 1, **{**args, "say": said.append})
+    assert now[0] <= 3600 and said[-1].startswith("still on battery after 1 h")
+
+
+def test_busy_reason_waits_for_the_user_to_be_away(monkeypatch):
+    from voiceio import presence
+    monkeypatch.setattr(quiet, "on_battery", lambda: False)
+    monkeypatch.setattr(quiet.os, "getloadavg", lambda: (0.0, 0, 0))
+    seen = []
+    monkeypatch.setattr(presence, "check",
+                        lambda away: seen.append(away) or presence.Presence(True, "in use (x)"))
+    assert quiet.busy_reason(0.25, away_after=600) == "in use (x)" and seen == [600]
+    assert quiet.busy_reason(0.25) is None              # unattended `maintain`: no presence check
+    monkeypatch.setattr(presence, "check", lambda away: presence.Presence(False, "away"))
+    assert quiet.busy_reason(0.25, away_after=600) is None
+
+
+def test_waiting_logs_each_reason_once_not_every_reading(monkeypatch):
+    readings = iter(["in use (last input 3 s ago)", "in use (last input 9 s ago)",
+                     "on battery", None])
+    monkeypatch.setattr(quiet, "busy_reason", lambda *_: next(readings))
+    said = []
+    assert quiet.wait_until_quiet(0.25, 3, poll=1, sleep=lambda s: None, say=said.append)
+    assert said == ["waiting: in use (last input 3 s ago)", "waiting: on battery"]
+
+
+class _Proc:
+    """A worker that runs for `polls` checks, then exits with `code`."""
+    def __init__(self, polls=99, code=0):
+        self.left, self.code, self.pid, self.stopped = polls, code, 4242, False
+
+    def poll(self):
+        if self.stopped:
+            return -15
+        if self.left <= 0:
+            return self.code
+        self.left -= 1
+        return None
+
+    @property
+    def returncode(self):
+        return self.poll()
+
+
+def _watch(monkeypatch, tmp_path, procs, reasons, *, quiet_ok=True):
+    spawned, said = [], []
+    procs = iter(procs)
+    reasons = iter(reasons)
+
+    def spawn(argv, env):
+        spawned.append(env)
+        return next(procs)
+
+    def stop(proc):
+        proc.stopped = True
+    monkeypatch.setattr(quiet, "wait_until_quiet", lambda *a, **k: quiet_ok)
+    monkeypatch.setattr(quiet, "stop_reason", lambda away: next(reasons, None))
+    code = quiet.run_while_away(["voiceio", "learn", "maintain"], max_load=0.25, away_minutes=10,
+                                wait_hours=3, threads=3, hold_file=tmp_path / "hold",
+                                spawn=spawn, stop=stop, sleep=lambda s: None, say=said.append)
+    return code, spawned, said
+
+
+def test_work_stops_when_the_user_returns_and_resumes_later(monkeypatch, tmp_path):
+    first, second = _Proc(), _Proc(polls=3, code=0)
+    code, spawned, said = _watch(monkeypatch, tmp_path, [first, second],
+                                 [None, None, "in use (last input 0 s ago)"])
+    assert code == 0 and first.stopped and not second.stopped
+    assert said == ["paused: in use (last input 0 s ago); it resumes where it stopped "
+                    "once you've been away 10 min"]
+    assert spawned[0][quiet.WORKER_ENV] == "1" and spawned[0]["OMP_NUM_THREADS"] == "3"
+    assert quiet.RESUMED_ENV not in spawned[0] and spawned[1][quiet.RESUMED_ENV] == "1"
+
+
+def test_watcher_reports_the_work_exit_status_and_gives_up_quietly(monkeypatch, tmp_path):
+    assert _watch(monkeypatch, tmp_path, [_Proc(polls=1, code=3)], [])[0] == 3
+    code, spawned, _ = _watch(monkeypatch, tmp_path, [], [], quiet_ok=False)
+    assert code == 0 and spawned == []          # never away: nothing started, unit doesn't fail
+
+
+def test_a_model_switch_in_progress_is_never_cut_off(monkeypatch, tmp_path):
+    proc = _Proc(polls=3, code=0)
+    reasons = iter(["in use"] * 10)
+
+    def spawn(argv, env):
+        (tmp_path / "hold").touch()            # the worker holds it
+        return proc
+    monkeypatch.setattr(quiet, "wait_until_quiet", lambda *a, **k: True)
+    monkeypatch.setattr(quiet, "stop_reason", lambda away: next(reasons))
+    assert quiet.run_while_away(["x"], max_load=1, away_minutes=1, wait_hours=1, threads=1,
+                                hold_file=tmp_path / "hold", spawn=spawn,
+                                stop=lambda p: pytest.fail("cut off a model switch"),
+                                sleep=lambda s: None, say=print) == 0
+    assert not (tmp_path / "hold").exists()
+
+
+def test_hold_marks_the_file_only_inside_the_block(monkeypatch, tmp_path):
+    flag = tmp_path / "hold"
+    monkeypatch.setenv(quiet.HOLD_ENV, str(flag))
+    with quiet.hold():
+        assert flag.exists()
+    assert not flag.exists()
+    monkeypatch.delenv(quiet.HOLD_ENV)
+    with quiet.hold():                          # not under the watcher: a no-op
+        pass
+
+
+def test_stop_ends_the_whole_process_group_at_once():
+    """The decoder runs in a subprocess of the worker: it must go too."""
+    import os
+    import time
+    proc = quiet._spawn(["sh", "-c", "sleep 30 & sleep 30; wait"], dict(os.environ))
+    time.sleep(0.2)
+    t0 = time.monotonic()
+    quiet._stop(proc)
+    assert time.monotonic() - t0 < 3 and proc.poll() is not None
+    with pytest.raises(ProcessLookupError):
+        os.killpg(proc.pid, 0)                  # nothing left in the group
+
+
+def test_threads_default_to_half_the_cpus(monkeypatch):
+    monkeypatch.setattr(quiet.os, "cpu_count", lambda: 16)
+    assert quiet.worker_threads(0) == 8 and quiet.worker_threads(5) == 5
+
+
+def test_maintain_in_the_worker_does_the_work(monkeypatch):
+    from voiceio.cli import learn as cli
+    monkeypatch.setattr(cli, "_yield_cpu", lambda: None)
+    monkeypatch.setenv(quiet.WORKER_ENV, "1")
+    monkeypatch.setattr(quiet, "run_while_away", lambda *a, **k: pytest.fail("worker must not watch"))
+    ran = []
+    monkeypatch.setattr(cli, "_maintain", lambda args, cfg: ran.append(cfg.away_minutes))
+    cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1, when_idle=True))
+    assert ran == [10.0]
+
+
+def test_scheduled_maintain_fails_when_its_work_does(monkeypatch):
+    from voiceio.cli import learn as cli
+    monkeypatch.setattr(cli, "_yield_cpu", lambda: None)
+    monkeypatch.delenv(quiet.WORKER_ENV, raising=False)
+    monkeypatch.setattr(quiet, "run_while_away", lambda *a, **k: 2)
+    with pytest.raises(SystemExit) as e:
+        cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1, when_idle=True))
+    assert e.value.code == 2
+
+
+def test_scheduled_maintain_waits_for_a_quiet_machine(monkeypatch):
+    from voiceio.cli import learn as cli
+    monkeypatch.setattr(cli, "_yield_cpu", lambda: None)
+    monkeypatch.setattr(quiet, "wait_until_quiet", lambda *a, **k: False)
+    ran = []
+    monkeypatch.setattr(cli, "cmd_label", lambda a: ran.append("label"))
+    cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1, when_idle=True))
+    assert ran == []                                      # busy all night: nothing ran
+
+
+def test_learning_announcement_offers_stop_and_weekly(monkeypatch, tmp_path):
+    from voiceio import feedback
+    from voiceio.cli import learn as cli
+    sent = []
+    monkeypatch.setattr(feedback, "notify_actions", lambda *a: sent.append(a))
+    monkeypatch.setattr(cli.store, "load_labels", lambda: {})
+    monkeypatch.setattr(cli.store, "clips", lambda: [argparse.Namespace(audio=f"a{i}.wav") for i in range(3)])
+    monkeypatch.setattr(cli.store, "latest_dataset", lambda: None)
+    cli._announce_learning(min_new=50)
+    (title, body, actions, _), = sent
+    assert "learning" in title and body.startswith("Labeling 3 new recordings,")
+    assert "while you're away" in body and set(actions) == {"stop", "weekly"}
+
+    sent.clear()
+    monkeypatch.setattr(cli.store, "load_labels", lambda: {f"a{i}.wav": 1 for i in range(3)})
+    monkeypatch.setattr(cli.store, "latest_dataset", lambda: tmp_path)
+    monkeypatch.setattr(cli.store, "dataset_clips", lambda _: {f"a{i}.wav" for i in range(3)})
+    cli._announce_learning(min_new=50)
+    assert sent == []                                     # nothing to do: no notification
+
+
+def test_notify_actions_runs_the_picked_action(monkeypatch):
+    import subprocess
+
+    from voiceio import feedback
+    monkeypatch.setattr("sys.platform", "linux")
+    monkeypatch.setattr(feedback, "_which", lambda _: "/usr/bin/notify-send")
+    monkeypatch.setattr(feedback, "_notify_send_has_actions", lambda: True)
+    calls = []
+
+    def fake_run(args, **kw):
+        calls.append(args)
+        return subprocess.CompletedProcess(args, 0, stdout="weekly\n")
+    monkeypatch.setattr(feedback.subprocess, "run", fake_run)
+    picked = []
+
+    class Now:   # run the waiting thread inline
+        def __init__(self, target, daemon): self.target = target
+        def start(self): self.target()
+    monkeypatch.setattr(feedback.threading, "Thread", Now)
+    feedback.notify_actions("t", "b", {"stop": "Stop", "weekly": "Weekly"}, picked.append)
+    assert picked == ["weekly"]
+    assert "--wait" in calls[0] and "--action=stop=Stop" in calls[0]

python_voiceio-1.9.3/tests/test_learn_resume.py

@@ -0,0 +1,243 @@
+"""A learning run that is stopped part-way carries on where it was."""
+from __future__ import annotations
+
+import argparse
+import json
+import wave
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from voiceio import config
+from voiceio.cli import learn as cli
+from voiceio.learn import evaluate, store, train
+from voiceio.learn.store import Segment
+
+
+def _clip(name: str) -> None:
+    config.RECORDINGS_DIR.mkdir(parents=True, exist_ok=True)
+    with wave.open(str(config.RECORDINGS_DIR / name), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(16000)
+        w.writeframes(np.zeros(3 * 16000, dtype=np.int16).tobytes())
+    config.HISTORY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(config.HISTORY_PATH, "a") as f:
+        f.write(json.dumps({"ts": 1.0, "text": "x", "raw": "x", "duration": 3,
+                            "audio": name}) + "\n")
+    store.add_label(name, [Segment(0, 3, "hello there")], "teacher:fake")
+
+
+class Stopped(Exception):
+    """Stands in for the watcher ending the worker mid-stage."""
+
+
+def _fake_work(monkeypatch, train_fn):
+    evals, trained = [], []
+    monkeypatch.setattr(cli, "cmd_label", lambda a: None)
+    monkeypatch.setattr(cli, "_announce_learning", lambda min_new: None)
+    monkeypatch.setattr(train, "missing_train_deps", lambda: [])
+
+    def run_eval(model, ds):
+        evals.append(model)
+        return SimpleNamespace(wer=0.1, term_recall=0.5, repetitions=0, per_clip=[])
+    monkeypatch.setattr(cli, "_run_eval", run_eval)
+    monkeypatch.setattr(cli, "_train", lambda ds, **k: trained.append(ds.name) or train_fn(ds))
+    monkeypatch.setattr(evaluate, "promotion_verdict", lambda c, b: (False, "table"))
+    return evals, trained
+
+
+def test_a_stopped_retrain_carries_on_instead_of_waiting_for_more_clips(monkeypatch, capsys):
+    for i in range(3):
+        _clip(f"{i}.wav")
+    run = store.learn_dir() / "models" / "v0001-small-20261019-0822"
+
+    def stopped(ds):
+        raise Stopped
+    evals, trained = _fake_work(monkeypatch, stopped)
+    with pytest.raises(Stopped):
+        cli.cmd_maintain(argparse.Namespace(min_new=3, base="small", epochs=1))
+    assert trained == ["v0001"]
+
+    # Before: v0001 counted as done, so it waited for 3 more clips past it.
+    evals, trained = _fake_work(monkeypatch, lambda ds: run)
+    cli.cmd_maintain(argparse.Namespace(min_new=3, base="small", epochs=1))
+    out = capsys.readouterr().out
+    assert "carrying on with v0001" in out and trained == ["v0001"]
+    assert store.latest_dataset().name == "v0001"          # no second dataset built
+
+    cli.cmd_maintain(argparse.Namespace(min_new=3, base="small", epochs=1))
+    assert "retraining waits for 3" in capsys.readouterr().out   # decided: done with it
+
+
+def test_resume_reuses_saved_scores_and_a_finished_model(monkeypatch):
+    for i in range(3):
+        _clip(f"{i}.wav")
+    ds = store.build_dataset()
+    cli._set_pending(ds)
+    run = store.learn_dir() / "models" / f"{ds.name}-small-20261019-0822"
+    (run / "ct2").mkdir(parents=True)
+    (run / "ct2" / "model.bin").write_text("")
+    current = config.load().model.name
+    saved = {current: {"wer": 0.2, "term_recall": 0.5, "repetitions": 0, "per_clip": []}}
+    monkeypatch.setattr(evaluate, "latest", lambda model, dataset, beam=5: saved.get(model))
+    evals, trained = _fake_work(monkeypatch, lambda ds: pytest.fail("already trained"))
+    cli.cmd_maintain(argparse.Namespace(min_new=50, base="small", epochs=1))
+    assert evals == [str(run / "ct2")]        # only the candidate was still unscored
+    assert cli._pending_dataset() is None
+
+
+def test_pending_marker_survives_only_with_its_dataset():
+    for i in range(2):
+        _clip(f"{i}.wav")
+    ds = store.build_dataset()
+    cli._set_pending(ds)
+    assert cli._pending_dataset() == ds
+    cli._set_pending(None)
+    assert cli._pending_dataset() is None
+    (store.learn_dir() / "maintain-pending.json").write_text('{"dataset": "v0099"}')
+    assert cli._pending_dataset() is None and not cli._pending_path().exists()
+
+
+def test_a_half_built_dataset_is_never_the_latest(monkeypatch):
+    _clip("a.wav")
+    real = store.json.dumps
+    calls = []
+
+    def dies_at_manifest(obj, *a, **k):
+        if isinstance(obj, dict) and "schema" in obj:
+            raise Stopped
+        calls.append(1)
+        return real(obj, *a, **k)
+    monkeypatch.setattr(store.json, "dumps", dies_at_manifest)
+    with pytest.raises(Stopped):
+        store.build_dataset()
+    monkeypatch.setattr(store.json, "dumps", real)
+    assert store.latest_dataset() is None
+    assert store.build_dataset().name == "v0001"
+
+
+def test_train_resumes_the_unfinished_run_of_the_same_dataset_and_base(monkeypatch):
+    for i in range(2):
+        _clip(f"{i}.wav")
+    ds = store.build_dataset()
+    folder = store.learn_dir() / "exports" / ds.name
+    folder.mkdir(parents=True)
+    for name in ("train.jsonl", "dev.jsonl", train.HOTWORDS_FILE):
+        (folder / name).write_text("")
+    models = store.learn_dir() / "models"
+    old = models / f"{ds.name}-small-20261018-0330"          # finished before
+    (old / "ct2").mkdir(parents=True)
+    (old / "ct2" / "model.bin").write_text("")
+    stopped = models / f"{ds.name}-small-20261019-0822"      # stopped mid-training
+    stopped.mkdir()
+    (stopped / train.CHECKPOINT).write_text("x")
+    (models / f"{ds.name}-small.en-20261019-0900").mkdir()   # another base: not ours
+    got = {}
+    monkeypatch.setattr(train, "require_train_deps", lambda: None)
+    monkeypatch.setattr(train, "export", lambda *a, **k: pytest.fail("re-exported"))
+    monkeypatch.setattr(train, "train", lambda folder, out, cfg: got.update(out=out, cfg=cfg)
+                        or out / "hf")
+
+    def convert(hf, out):
+        out.mkdir()
+        (out / "model.bin").write_text("")
+    monkeypatch.setattr(train, "convert", convert)
+    config.set_value("learn", "threads", 3)
+    assert cli._train(ds, base="small", epochs=1) == stopped and got["out"] == stopped
+    assert got["cfg"].threads == 3
+    assert not (stopped / train.CHECKPOINT).exists()        # finished: resume state dropped
+    assert cli._finished_run(ds, "small") == stopped
+
+
+# ── the training loop itself ─────────────────────────────────────────────
+
+def _rows(n=10):
+    rng = np.random.default_rng(7)
+    return [{"audio": f"w{i}", "x": rng.normal(size=3).tolist(), "y": float(rng.normal())}
+            for i in range(n)]
+
+
+def _fit(tmp_path, *, stop_at=None, checkpoint_secs=0.0, fp="fp"):
+    """fit() on a tiny model whose forward draws from mix_rng and dropout, so
+    every random state a resume must restore is in play."""
+    torch = pytest.importorskip("torch")
+    torch.manual_seed(0)
+    model = torch.nn.Sequential(torch.nn.Linear(3, 8), torch.nn.Dropout(0.3), torch.nn.Linear(8, 1))
+    mix_rng = np.random.default_rng(1)
+    calls = [0]
+
+    def forward(chunk, *, fixed=False):
+        calls[0] += 1
+        if stop_at is not None and calls[0] == stop_at:
+            raise Stopped
+        x = torch.tensor([r["x"] for r in chunk])
+        noise = 0.0 if fixed else float(mix_rng.random())
+        y = torch.tensor([[r["y"] + noise] for r in chunk])
+        return torch.nn.functional.mse_loss(model(x), y)
+    cfg = train.TrainConfig(epochs=3, batch_size=3, lr=1e-2)
+    rows = _rows()
+    best = train.fit(model, forward, rows[:7], rows[7:], cfg, checkpoint=tmp_path / "ck.pt",
+                     fp=fp, order_rng=np.random.default_rng(0), mix_rng=mix_rng,
+                     save_best=lambda: None, checkpoint_secs=checkpoint_secs)
+    return model, best, calls[0]
+
+
+@pytest.mark.parametrize("stop_at", [2, 4, 6, 9])   # mid-epoch, at a dev pass, epoch 2, 3
+def test_a_resumed_run_takes_exactly_the_steps_of_an_uninterrupted_one(tmp_path, stop_at):
+    torch = pytest.importorskip("torch")
+    (tmp_path / "a").mkdir()
+    whole, best_whole, calls_whole = _fit(tmp_path / "a")
+    assert calls_whole == 12                    # 3 epochs × (3 train steps + 1 dev pass)
+    (tmp_path / "b").mkdir()
+    with pytest.raises(Stopped):
+        _fit(tmp_path / "b", stop_at=stop_at)
+    resumed, best_resumed, calls_resumed = _fit(tmp_path / "b")
+    # It carried on (at most the step in flight is redone), and ended where
+    # the uninterrupted run did, to the last bit of every random draw.
+    assert calls_resumed <= calls_whole - (stop_at - 1) + 1
+    for p, q in zip(whole.parameters(), resumed.parameters()):
+        assert torch.allclose(p, q, atol=1e-6)
+    assert best_resumed == pytest.approx(best_whole)
+
+
+def test_progress_for_other_data_or_settings_starts_over(tmp_path, capsys):
+    (tmp_path / "a").mkdir()
+    with pytest.raises(Stopped):
+        _fit(tmp_path / "a", stop_at=4)
+    assert _fit(tmp_path / "a", fp="other")[2] == 12        # all of it again
+    assert "starting over" in capsys.readouterr().out
+    (tmp_path / "a" / "ck.pt").write_text("not a checkpoint")
+    _fit(tmp_path / "a")                                   # unreadable: starts over, no crash
+
+
+def test_fingerprint_follows_data_and_settings_not_threads(tmp_path):
+    for name in ("train.jsonl", "dev.jsonl"):
+        (tmp_path / name).write_text('{"audio": "a"}\n')
+    fp = train.fingerprint(tmp_path, train.TrainConfig())
+    assert train.fingerprint(tmp_path, train.TrainConfig(threads=3)) == fp
+    assert train.fingerprint(tmp_path, train.TrainConfig(epochs=9)) != fp
+    assert train.fingerprint(tmp_path, train.TrainConfig(), device="cuda") != fp
+    (tmp_path / "train.jsonl").write_text('{"audio": "b"}\n')
+    assert train.fingerprint(tmp_path, train.TrainConfig()) != fp
+
+
+def test_encoder_cache_persists_across_runs_only_for_the_same_data(tmp_path):
+    keys = ["train/0.wav", "train/1.wav", "dev/0.wav"]
+    cache = train.EncoderCache(tmp_path / train.ENCODER_CACHE, keys, frames=4, width=2, fingerprint="a")
+    assert cache.missing(keys) == keys and cache.reused == 0
+    value = np.arange(8, dtype=np.float16).reshape(1, 4, 2)
+    cache.put(["train/1.wav"], value)
+    del cache
+
+    again = train.EncoderCache(tmp_path / train.ENCODER_CACHE, keys, frames=4, width=2, fingerprint="a")
+    assert again.reused == 1 and again.missing(keys) == ["train/0.wav", "dev/0.wav"]
+    np.testing.assert_array_equal(again.get(["train/1.wav"]), value)
+    del again
+
+    other = train.EncoderCache(tmp_path / train.ENCODER_CACHE, keys, frames=4, width=2, fingerprint="b")
+    assert other.missing(keys) == keys
+    del other
+    train.discard_resume_state(tmp_path)
+    assert not list(tmp_path.glob("encoder-cache*"))