python-voiceio 1.17.0__tar.gz → 1.17.1__tar.gz

{python_voiceio-1.17.0/python_voiceio.egg-info → python_voiceio-1.17.1}/PKG-INFO

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

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/pyproject.toml

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

{python_voiceio-1.17.0 → python_voiceio-1.17.1/python_voiceio.egg-info}/PKG-INFO

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

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/tests/test_security_hardening.py

@@ -85,6 +85,94 @@ def test_check_permissions_flags_loose_and_clears_after_harden(tmp_path, monkeyp
     assert config.check_permissions() == []
 
 
+@pytest.fixture
+def umask_002():
+    """The user-private-group umask of Debian/Fedora desktops: plain mkdir
+    gives 0775, which is how the reported ~/.local/state/voiceio got there."""
+    import os
+    old = os.umask(0o002)
+    try:
+        yield
+    finally:
+        os.umask(old)
+
+
+@posix_only
+def test_private_dir_creates_0700_with_missing_parents(tmp_path, umask_002):
+    (tmp_path / "home").mkdir(mode=0o755)
+    target = tmp_path / "home" / ".local" / "state" / "voiceio"
+    assert config.private_dir(target) == target
+    assert _mode(target) == 0o700
+    assert _mode(target.parent) == 0o700          # XDG: created dirs are 0700
+    assert _mode(tmp_path / "home") == 0o755      # existing parents untouched
+
+
+@posix_only
+def test_private_dir_tightens_existing_lax_dir(tmp_path):
+    d = tmp_path / "voiceio"
+    d.mkdir()
+    d.chmod(0o775)
+    config.private_dir(d)
+    assert _mode(d) == 0o700
+
+
+@posix_only
+def test_crash_log_dir_is_private(tmp_path, monkeypatch, umask_002, capsys):
+    from voiceio import cli
+    log_dir = tmp_path / "state" / "voiceio"
+    monkeypatch.setattr(config, "LOG_DIR", log_dir)
+
+    def boom():
+        raise RuntimeError("crash before logging")
+
+    monkeypatch.setattr(cli, "main", boom)
+    with pytest.raises(SystemExit):
+        cli._entry_point()
+    assert (log_dir / "crash.log").exists()
+    assert _mode(log_dir) == 0o700
+    assert _mode(log_dir.parent) == 0o700
+
+
+@posix_only
+def test_error_notifier_state_dir_is_private(tmp_path, umask_002):
+    import logging
+    from voiceio.errorlog import RepeatedErrorNotifier
+    state = tmp_path / "state" / "voiceio" / "error-notify.json"
+    handler = RepeatedErrorNotifier(state_path=state, notify=lambda *a, **k: None)
+    handler.emit(logging.LogRecord("voiceio.x", logging.ERROR, __file__, 1, "boom", (), None))
+    assert state.exists()
+    assert _mode(state.parent) == 0o700
+
+
+@posix_only
+def test_secure_write_missing_parents_are_private(tmp_path, umask_002):
+    target = tmp_path / "config" / "voiceio" / "config.toml"
+    config.secure_write(target, "x = 1\n")
+    assert _mode(target.parent) == 0o700
+    assert _mode(target.parent.parent) == 0o700
+
+
+@posix_only
+def test_label_store_dirs_are_private(tmp_path, monkeypatch, umask_002):
+    from voiceio.learn import store
+    monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "share"))
+    store.add_label("a.wav", [], source="test")
+    assert _mode(store.learn_dir()) == 0o700
+    assert _mode(config.data_dir()) == 0o700
+
+
+@posix_only
+def test_check_permissions_flags_lax_learn_dir(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "share"))
+    learn = config.data_dir() / "learn"
+    learn.mkdir(parents=True)
+    learn.chmod(0o775)
+    assert learn in {p for p, _, _ in config.check_permissions()}
+    config.harden_permissions()
+    assert _mode(learn) == 0o700
+    assert learn not in {p for p, _, _ in config.check_permissions()}
+
+
 # ── udev rule (replaces sudo chmod 0666 /dev/uinput) ─────────────────────
 
 def test_uinput_udev_rule_content():

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/tests/test_setup.py

@@ -280,3 +280,108 @@ def test_setup_offers_nightly_learning_once(monkeypatch):
     steps._offer_nightly_learning(state)
     steps._offer_nightly_learning(state)      # already on: not asked again
     assert installed == [1] and len(asked) == 1
+
+
+# ── root commands with no terminal (agent, launcher, GUI) ────────────
+
+def _no_terminal(monkeypatch, *, sudo_cached=False, pkexec=True, display=True):
+    monkeypatch.setattr(plat, "_has_tty", lambda: False)
+    monkeypatch.setattr(plat, "_sudo_without_password", lambda: sudo_cached)
+    monkeypatch.setattr(plat.shutil, "which",
+                        lambda name: "/usr/bin/pkexec" if pkexec and name == "pkexec" else None)
+    monkeypatch.delenv("DISPLAY", raising=False)
+    if display:
+        monkeypatch.setenv("WAYLAND_DISPLAY", "wayland-0")
+    else:
+        monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+
+
+def test_privileged_argv_unchanged_with_a_terminal(monkeypatch):
+    monkeypatch.setattr(plat, "_has_tty", lambda: True)
+    argv = ["sudo", "apt", "install", "ibus"]
+    assert plat.privileged_argv(argv) == argv
+
+
+def test_privileged_argv_leaves_unprivileged_commands_alone(monkeypatch):
+    _no_terminal(monkeypatch, pkexec=False)
+    assert plat.privileged_argv(["brew", "install", "x"]) == ["brew", "install", "x"]
+
+
+def test_privileged_argv_uses_pkexec_without_a_terminal(monkeypatch):
+    _no_terminal(monkeypatch)
+    assert plat.privileged_argv(["sudo", "apt", "install", "ibus", "gcc"]) == [
+        "pkexec", "apt", "install", "-y", "ibus", "gcc"]
+    assert plat.privileged_argv(["sudo", "pacman", "-S", "ibus"]) == [
+        "pkexec", "pacman", "-S", "--noconfirm", "ibus"]
+
+
+def test_privileged_argv_runs_shell_scripts_with_inner_sudo_under_pkexec(monkeypatch):
+    _no_terminal(monkeypatch)
+    script = ["sh", "-c", "printf x | sudo tee /etc/udev/rules.d/r > /dev/null"]
+    assert plat.privileged_argv(script) == ["pkexec", *script]
+
+
+def test_privileged_argv_prefers_cached_sudo(monkeypatch):
+    _no_terminal(monkeypatch, sudo_cached=True)
+    assert plat.privileged_argv(["sudo", "apt", "install", "x"]) == [
+        "sudo", "-n", "apt", "install", "-y", "x"]
+
+
+@pytest.mark.parametrize("pkexec,display", [(False, True), (True, False)])
+def test_privileged_argv_gives_up_without_pkexec_or_desktop(monkeypatch, pkexec, display):
+    _no_terminal(monkeypatch, pkexec=pkexec, display=display)
+    assert plat.privileged_argv(["sudo", "apt", "install", "x"]) is None
+
+
+def test_noninteractive_install_deps_without_terminal_prints_command(cfg_paths, monkeypatch, capsys):
+    _patch_noninteractive(monkeypatch)
+    monkeypatch.setattr("voiceio.platform.check_system_deps", lambda: ["portaudio"])
+    monkeypatch.setattr(plat, "system_deps_install_cmd", lambda keys: "sudo apt install libportaudio2")
+    monkeypatch.setattr(plat, "privileged_argv", lambda argv: None)
+    ran = []
+    monkeypatch.setattr(noninteractive.subprocess, "run", lambda *a, **k: ran.append(a))
+    code = noninteractive.run_setup_noninteractive({}, install_deps=True)
+    assert code == 4
+    assert ran == []
+    assert "sudo apt install libportaudio2" in capsys.readouterr().out
+
+
+def test_noninteractive_install_deps_runs_pkexec_argv(cfg_paths, monkeypatch):
+    _patch_noninteractive(monkeypatch)
+    state = {"missing": ["portaudio"]}
+    monkeypatch.setattr("voiceio.platform.check_system_deps", lambda: state["missing"])
+    monkeypatch.setattr(plat, "system_deps_install_cmd", lambda keys: "sudo apt install libportaudio2")
+    _no_terminal(monkeypatch)
+    ran = []
+
+    class _Done:
+        returncode = 0
+
+    def fake_run(argv, **kw):
+        ran.append(argv)
+        state["missing"] = []
+        return _Done()
+
+    monkeypatch.setattr(noninteractive.subprocess, "run", fake_run)
+    assert noninteractive.run_setup_noninteractive({}, install_deps=True) == 0
+    assert ran == [["pkexec", "apt", "install", "-y", "libportaudio2"]]
+
+
+def test_doctor_privileged_fix_asks_first_and_never_runs_when_declined(monkeypatch):
+    from voiceio.cli import doctor
+    ran = []
+    monkeypatch.setattr("subprocess.run", lambda *a, **k: ran.append(a))
+    monkeypatch.setattr(doctor, "_confirm_privileged", lambda d, c: False)
+    assert doctor._run_privileged("Fix x", ["sudo", "true"], 5) is None
+    assert ran == []
+
+
+def test_doctor_privileged_fix_without_terminal_prints_command(monkeypatch, capsys):
+    from voiceio.cli import doctor
+    ran = []
+    monkeypatch.setattr("subprocess.run", lambda *a, **k: ran.append(a))
+    monkeypatch.setattr(doctor, "_confirm_privileged", lambda d, c: True)
+    monkeypatch.setattr(plat, "privileged_argv", lambda argv: None)
+    assert doctor._run_privileged("Fix x", ["sudo", "udevadm", "trigger"], 5) is False
+    assert ran == []
+    assert "sudo udevadm trigger" in capsys.readouterr().out

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/tests/test_tts.py

@@ -499,3 +499,54 @@ def test_chain_passes_language_to_supertonic():
     from voiceio.tts import chain
     engine = chain._create("supertonic", TTSConfig(engine="supertonic", language="de"))
     assert engine.name == "supertonic" and engine._language == "de"
+
+
+# ── no engine installed: the default config stays quiet ─────────────
+
+def _no_engines(cfg):
+    names = ["piper", "supertonic", "edge-tts", "espeak"] if cfg.engine == "auto" else [cfg.engine]
+    return [(n, ProbeResult(ok=False, reason=f"{n} not installed")) for n in names]
+
+
+def test_doctor_tts_auto_without_engine_is_quiet_off():
+    from voiceio import health
+    with patch("voiceio.tts.probe_all", side_effect=_no_engines):
+        status = health._tts_status(TTSConfig())
+    assert status.startswith("off")
+    assert "enabled but" not in status
+    assert "⚠" not in health._feature_line("Text-to-speech", status)
+
+
+def test_doctor_tts_named_engine_missing_still_warns():
+    from voiceio import health
+    with patch("voiceio.tts.probe_all", side_effect=_no_engines):
+        status = health._tts_status(TTSConfig(engine="piper"))
+    assert status.startswith("enabled but piper unavailable")
+
+
+def test_doctor_tts_on_when_engine_present():
+    from voiceio import health
+    with patch("voiceio.tts.probe_all",
+               return_value=[("piper", ProbeResult(ok=False, reason="x")),
+                             ("espeak", ProbeResult(ok=True))]):
+        assert health._tts_status(TTSConfig()) == "on (espeak)"
+
+
+def test_doctor_tts_disabled_is_off():
+    from voiceio import health
+    assert health._tts_status(TTSConfig(enabled=False)) == "off"
+
+
+def test_auto_select_without_engine_logs_no_warning(caplog):
+    import logging
+    from voiceio.tts.chain import select, _create
+
+    def none_ok(name, cfg):
+        engine = _create(name, cfg)
+        engine.probe = lambda: ProbeResult(ok=False, reason="not installed")
+        return engine
+
+    with patch("voiceio.tts.chain._create", side_effect=none_ok), \
+            caplog.at_level(logging.DEBUG, logger="voiceio.tts.chain"):
+        assert select(TTSConfig()) is None
+    assert not [r for r in caplog.records if r.levelno >= logging.WARNING]

python_voiceio-1.17.1/voiceio/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.17.1"

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/app.py

@@ -202,8 +202,11 @@ class VoiceIO:
                 # Create a second hotkey backend for TTS
                 self._tts_hotkey = hotkey_chain.select(platform, cfg.hotkey.backend)
                 log.info("TTS: engine=%s, hotkey=%s", self._tts_engine.name, cfg.tts.hotkey)
+            elif cfg.tts.engine == "auto":
+                # The default config: read aloud once an engine is installed.
+                log.info("TTS: no engine installed, read-aloud hotkey off")
             else:
-                log.warning("TTS enabled but no engine available")
+                log.warning("TTS: engine '%s' is configured but unavailable", cfg.tts.engine)
 
         # Optional key that cancels a dictation (read only, never grabbed: the
         # key also reaches the focused app). Needs a backend that sees keys.
@@ -1007,11 +1010,11 @@ class VoiceIO:
             self._cancel_hotkey.start(self.cfg.hotkey.cancel_key, self.cancel)
 
     def run(self) -> None:
-        from voiceio.config import PID_PATH, LOG_DIR
+        from voiceio.config import PID_PATH, LOG_DIR, private_dir
 
         self._typers.redetect_at_start()
 
-        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        private_dir(LOG_DIR)
         self._pid_fd = open(PID_PATH, "a")   # not "w": the running daemon's PID stays
         try:
             from voiceio.pidlock import lock_pid_file

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/cli/__init__.py

@@ -112,9 +112,9 @@ def _cmd_run(args: argparse.Namespace) -> None:
     console.setLevel(getattr(logging, cfg.daemon.log_level))
 
     # File: always log DEBUG to rotating file
-    from voiceio.config import LOG_DIR, LOG_PATH
+    from voiceio.config import LOG_DIR, LOG_PATH, private_dir
     from logging.handlers import RotatingFileHandler
-    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    private_dir(LOG_DIR)
     file_handler = RotatingFileHandler(
         str(LOG_PATH), maxBytes=2_000_000, backupCount=2,
     )
@@ -212,8 +212,8 @@ def _entry_point() -> None:
         import traceback
         tb = traceback.format_exc()
         try:
-            from voiceio.config import LOG_DIR
-            LOG_DIR.mkdir(parents=True, exist_ok=True)
+            from voiceio.config import LOG_DIR, private_dir
+            private_dir(LOG_DIR)
             with open(LOG_DIR / "crash.log", "a", encoding="utf-8") as f:
                 f.write(f"\n===== {datetime.datetime.now().isoformat()} =====\n"
                         f"argv: {sys.argv}\n{tb}")

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/cli/doctor.py

@@ -42,6 +42,35 @@ def _confirm_privileged(description: str, command_str: str) -> bool:
     return answer in ("y", "yes")
 
 
+def _run_privileged(description: str, argv: list[str], timeout: float,
+                    cmd_str: str | None = None) -> bool | None:
+    """Ask first, then run a root command: sudo with a terminal, else pkexec
+    (see platform.privileged_argv), else print it for the user to run.
+
+    Returns True when it ran, False when it failed or could not run, None
+    when the user declined. Raises nothing.
+    """
+    import shlex
+    import subprocess
+
+    from voiceio import platform as plat
+    cmd_str = cmd_str or shlex.join(argv)
+    if not _confirm_privileged(description, cmd_str):
+        return None
+    run_argv = plat.privileged_argv(argv)
+    if run_argv is None:
+        print("  No terminal for sudo to ask your password, and no pkexec. Run it yourself:")
+        print(f"    {cmd_str}")
+        return False
+    try:
+        subprocess.run(run_argv, check=True, timeout=timeout)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError) as e:
+        print(f"  Failed: {e} — run the command above manually.")
+        return False
+    print("  Done.")
+    return True
+
+
 def _cmd_doctor(args: argparse.Namespace) -> None:
     """Run diagnostic health check, offer to fix issues."""
     if not sys.platform.startswith("linux"):
@@ -96,12 +125,17 @@ def _cmd_doctor(args: argparse.Namespace) -> None:
     import subprocess
 
     if missing_deps and dep_cmd:
-        print(f"  Fixing system packages: {dep_cmd}")
-        try:
-            subprocess.run(dep_cmd.split(), check=True, timeout=600)
-            print("  Done.")
-        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError) as e:
-            print(f"  Failed: {e} — run the command above manually.")
+        if dep_cmd.startswith("sudo "):
+            if _run_privileged("Install system packages", dep_cmd.split(), 600,
+                               cmd_str=dep_cmd) is None:
+                print("  Skipped system packages (declined).")
+        else:
+            print(f"  Fixing system packages: {dep_cmd}")
+            try:
+                subprocess.run(dep_cmd.split(), check=True, timeout=600)
+                print("  Done.")
+            except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError) as e:
+                print(f"  Failed: {e} — run the command above manually.")
 
     fixed_any = False
 
@@ -114,11 +148,12 @@ def _cmd_doctor(args: argparse.Namespace) -> None:
         if not b.ok and b.fix_cmd:
             cmd_str = " ".join(b.fix_cmd)
             if _is_privileged_cmd(b.fix_cmd):
-                if not _confirm_privileged(f"Fix {b.name}", cmd_str):
+                ran = _run_privileged(f"Fix {b.name}", b.fix_cmd, 120, cmd_str=cmd_str)
+                if ran is None:
                     print(f"  Skipped {b.name} (declined).")
-                    continue
-            else:
-                print(f"  Fixing {b.name}: {cmd_str}")
+                fixed_any = fixed_any or bool(ran)
+                continue
+            print(f"  Fixing {b.name}: {cmd_str}")
             try:
                 subprocess.run(b.fix_cmd, check=True, timeout=30)
                 print("  Done.")

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/cli/learn.py

@@ -536,7 +536,8 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     from voiceio.learn import quiet
     learn_cfg = _maintain_settings(args)
     if getattr(args, "when_idle", False) and os.environ.get(quiet.WORKER_ENV) != "1":
-        store.learn_dir().mkdir(parents=True, exist_ok=True)
+        from voiceio.config import private_dir
+        private_dir(store.learn_dir())
         code = quiet.run_while_away(
             quiet.worker_argv(), max_load=learn_cfg.max_load,
             away_minutes=learn_cfg.away_minutes, wait_hours=learn_cfg.wait_hours,

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/cli/uninstall.py

@@ -165,8 +165,13 @@ def _cmd_uninstall() -> None:
                 continue
             cmd = f"sudo rm {rule_path}"
             if _confirm_privileged(f"Remove the voiceio {what} udev rule", cmd):
+                from voiceio.platform import privileged_argv
+                argv = privileged_argv(["sudo", "rm", rule_path])
+                if argv is None:
+                    print(f"  No terminal for sudo to ask your password. Run manually: {cmd}")
+                    continue
                 try:
-                    subprocess.run(["sudo", "rm", rule_path], timeout=30)
+                    subprocess.run(argv, timeout=120)
                     removed.append(rule_path)
                 except (FileNotFoundError, subprocess.TimeoutExpired):
                     print(f"  Failed. Run manually: {cmd}")

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/config.py

@@ -247,6 +247,9 @@ class PostCorrectConfig:
 
 @dataclass
 class TTSConfig:
+    # With engine = "auto" this means "read aloud once an engine is
+    # installed": no engine is a quiet no-op (doctor says "off"), never a
+    # warning. Naming an engine that is missing does warn.
     enabled: bool = True
     engine: str = "auto"         # "auto" | "piper" | "supertonic" | "espeak" | "edge-tts"
     hotkey: str = "ctrl+alt+s"   # "s" for speak
@@ -452,9 +455,17 @@ def _content_files() -> list[Path]:
     ]
 
 
+def data_dir() -> Path:
+    """$XDG_DATA_HOME/voiceio: the learning corpus and the IBus launcher.
+    Read at call time, like the learn paths built on it."""
+    base = os.environ.get("XDG_DATA_HOME", "")
+    root = Path(base) if os.path.isabs(base) else Path.home() / ".local" / "share"
+    return root / "voiceio"
+
+
 def _content_dirs() -> list[Path]:
     """Directories that hold user content (0700)."""
-    return [CONFIG_DIR, LOG_DIR, RECORDINGS_DIR]
+    return [CONFIG_DIR, LOG_DIR, RECORDINGS_DIR, data_dir(), data_dir() / "learn"]
 
 
 def _chmod(path: Path, mode: int) -> None:
@@ -467,6 +478,33 @@ def _chmod(path: Path, mode: int) -> None:
         log.debug("Could not chmod %s", path, exc_info=True)
 
 
+def private_dir(path: Path) -> Path:
+    """Create `path` (and any missing parents) as 0700 and return it.
+
+    `mkdir(parents=True)` gives every new directory the umask's mode, which
+    is 0775 under the 002 umask of user-private-group distros (Debian,
+    Fedora): the state dir was group-readable until the daemon's startup
+    hardening caught up, and never fixed when only setup, doctor or the CLI
+    ran. Missing parents (e.g. ~/.local/state) get 0700 too, as the XDG
+    base directory spec asks. Existing parents are left alone.
+    """
+    missing: list[Path] = []
+    p = path
+    while not p.exists() and p.parent != p:
+        missing.append(p)
+        p = p.parent
+    for d in reversed(missing):
+        try:
+            d.mkdir(mode=_SECURE_DIR)
+        except FileExistsError:
+            pass
+        _chmod(d, _SECURE_DIR)   # mkdir's mode is masked by the umask
+    if (not missing and sys.platform != "win32" and path.is_dir()
+            and stat.S_IMODE(path.stat().st_mode) != _SECURE_DIR):
+        _chmod(path, _SECURE_DIR)
+    return path
+
+
 def secure_write(path: Path, text: str, *, encoding: str = "utf-8") -> None:
     """Write text to a file guaranteed to be 0600 with a 0700 parent dir.
 
@@ -474,8 +512,7 @@ def secure_write(path: Path, text: str, *, encoding: str = "utf-8") -> None:
     over the target, so there is no world-readable window and a crash never
     leaves a half-written file.
     """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    _chmod(path.parent, _SECURE_DIR)
+    private_dir(path.parent)
     tmp = path.with_name(f".{path.name}.tmp")
     fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _SECURE_FILE)
     try:

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/core/decoders/faster_whisper/__init__.py

@@ -117,8 +117,8 @@ class Transcriber:
             "cpu_threads": self._cfg.cpu_threads,
             "language": language,
         })
-        from voiceio.config import LOG_DIR
-        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        from voiceio.config import LOG_DIR, private_dir
+        private_dir(LOG_DIR)
         self._stderr_path = LOG_DIR / "worker.log"
         # Append (rotating at 1 MB) so a crash's stack dump survives the restart.
         if self._stderr_path.exists() and self._stderr_path.stat().st_size > 1_000_000:

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/corrections.py

@@ -7,6 +7,7 @@ import re
 import threading
 from pathlib import Path
 
+from voiceio import config
 from voiceio.config import CORRECTIONS_PATH, FLAGGED_PATH
 
 log = logging.getLogger(__name__)
@@ -59,7 +60,7 @@ class CorrectionDict:
         """Write corrections.json atomically."""
         with self._lock:
             data = {orig: right for orig, right in self._corrections.values()}
-            self._path.parent.mkdir(parents=True, exist_ok=True)
+            config.private_dir(self._path.parent)
             tmp = self._path.with_suffix(".tmp")
             tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n",
                            encoding="utf-8")
@@ -110,7 +111,7 @@ class CorrectionDict:
             return
         word = word.strip()
         try:
-            self._flagged_path.parent.mkdir(parents=True, exist_ok=True)
+            config.private_dir(self._flagged_path.parent)
             with open(self._flagged_path, "a", encoding="utf-8") as f:
                 f.write(word + "\n")
             log.info("Flagged word: '%s'", word)

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/errorlog.py

@@ -156,7 +156,8 @@ class RepeatedErrorNotifier(logging.Handler):
                 fire = len(seen[key]) >= REPEATS and state.get("notified") != today
                 if fire:
                     state["notified"] = today
-                self._path.parent.mkdir(parents=True, exist_ok=True)
+                from voiceio.config import private_dir
+                private_dir(self._path.parent)
                 self._path.write_text(json.dumps(state))
             if fire:
                 notify = self._notify

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/health.py

@@ -222,17 +222,7 @@ def _check_features() -> FeatureGroups:
         else:
             groups.processing["LLM cleanup"] = "off (enable in config or re-run 'voiceio setup')"
 
-        # TTS
-        if cfg.tts.enabled:
-            from voiceio.tts import probe_all as tts_probe_all
-            results = tts_probe_all(cfg.tts)
-            active = next((name for name, probe in results if probe.ok), None)
-            if active:
-                groups.processing["Text-to-speech"] = f"on ({active})"
-            else:
-                groups.processing["Text-to-speech"] = "enabled but no engine available"
-        else:
-            groups.processing["Text-to-speech"] = "off"
+        groups.processing["Text-to-speech"] = _tts_status(cfg.tts)
 
         # ── Accuracy (learning stack) ──
 
@@ -301,6 +291,30 @@ def _check_features() -> FeatureGroups:
     return groups
 
 
+TTS_INSTALL_HINT = "pip install 'python-voiceio[tts]' or install espeak-ng"
+
+
+def _tts_status(tts_cfg) -> str:
+    """Doctor's Text-to-speech line.
+
+    `enabled = true` with `engine = "auto"` (the default) means "read aloud
+    when an engine is installed", so no engine there is a quiet "off", not a
+    warning: the user never asked for a particular engine. Naming an engine
+    that is missing is a real misconfiguration and still warns.
+    """
+    if not tts_cfg.enabled:
+        return "off"
+    from voiceio.tts import probe_all as tts_probe_all
+    results = tts_probe_all(tts_cfg)
+    active = next((name for name, probe in results if probe.ok), None)
+    if active:
+        return f"on ({active})"
+    if tts_cfg.engine == "auto":
+        return f"off (no engine installed: {TTS_INSTALL_HINT})"
+    reason = next((probe.reason for _, probe in results if probe.reason), "")
+    return f"enabled but {tts_cfg.engine} unavailable" + (f" ({reason})" if reason else "")
+
+
 def _decoder_status(cfg) -> dict[str, str]:
     """For a sherpa-onnx model: whether it can be biased, and why not. For
     Whisper: whether Parakeet would do better here."""

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/hints.py

@@ -52,7 +52,8 @@ def _load_state() -> dict:
 
 def _save_state(state: dict) -> None:
     try:
-        _HINTS_PATH.parent.mkdir(parents=True, exist_ok=True)
+        from voiceio.config import private_dir
+        private_dir(_HINTS_PATH.parent)
         _HINTS_PATH.write_text(json.dumps(state))
     except Exception:
         log.debug("Failed to save hints state", exc_info=True)

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/history.py

@@ -51,8 +51,7 @@ def append(
         return
     p = path or HISTORY_PATH
     try:
-        p.parent.mkdir(parents=True, exist_ok=True)
-        config._chmod(p.parent, config._SECURE_DIR)
+        config.private_dir(p.parent)
         from voiceio import __version__
         # The version lets `doctor` judge the current release on its own
         # numbers instead of months of older ones.

{python_voiceio-1.17.0 → python_voiceio-1.17.1}/voiceio/ibus/install.py

@@ -95,7 +95,8 @@ def refresh_stale_launcher() -> bool:
 
 
 def _write_launcher() -> None:
-    LAUNCHER_DIR.mkdir(parents=True, exist_ok=True)
+    from voiceio.config import private_dir
+    private_dir(LAUNCHER_DIR)
     LAUNCHER_PATH.write_text(_launcher_script())
     LAUNCHER_PATH.chmod(LAUNCHER_PATH.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)