refrain 0.2.4__tar.gz → 0.2.6__tar.gz

{refrain-0.2.4 → refrain-0.2.6}/.github/workflows/release.yml

@@ -104,10 +104,38 @@ jobs:
           mv *.AppImage.zsync ../../dist/ 2>/dev/null || true
           ls -la ../../dist/
 
+      # Extract the matching `## [X.Y.Z]` section from CHANGELOG.md
+      # and feed it into the GitHub release body. Without this we'd
+      # fall back to GitHub's auto-generated "Full Changelog: …"
+      # one-liner — which is also what the in-app
+      # Settings → Updates → "Latest release notes" pane renders, so
+      # users would only ever see the bare compare-link there.
+      - name: Extract CHANGELOG section for the release body
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          # awk: print everything between `## [TAG]` and the next
+          # top-level ## section, excluding the heading lines themselves.
+          awk -v ver="${TAG}" '
+            $0 ~ "^## \\[" ver "\\]" { p=1; next }
+            p && /^## \[/ { exit }
+            p { print }
+          ' CHANGELOG.md > release-notes.md
+          echo "::group::release-notes.md"
+          cat release-notes.md
+          echo "::endgroup::"
+          if [ ! -s release-notes.md ]; then
+            echo "::error::CHANGELOG section for v${TAG} extracted to nothing"
+            exit 1
+          fi
+
       - name: Create GitHub release
         uses: softprops/action-gh-release@v3
         with:
-          generate_release_notes: true
+          # Use our CHANGELOG section (extracted above), not GitHub's
+          # auto-generated notes — the in-app update dialog renders
+          # this body verbatim so it has to actually be the changelog.
+          body_path: release-notes.md
+          generate_release_notes: false
           draft: false
           prerelease: ${{ contains(github.ref, '-') }}   # e.g. v0.2.0-rc1
           name: "Refrain ${{ github.ref_name }}"

{refrain-0.2.4 → refrain-0.2.6}/CHANGELOG.md

@@ -7,6 +7,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-05-07
+
+Localization expansion plus a bundle of reliability fixes accumulated
+since v0.2.5 across the config layer, restart path, cover cache, IPC
+sandbox bridge, and update flow.
+
+### Added
+
+- **8 new UI languages.** Refrain ships full translations (127 / 127
+  strings each) for Spanish (`es`), French (`fr`), Portuguese (`pt`),
+  Italian (`it`), Russian (`ru`), Polish (`pl`), Japanese (`ja`), and
+  Simplified Chinese (`zh_CN`) on top of the existing English source
+  + German. The Settings → Advanced → Language dropdown lists each
+  language under its native endonym ("Español", "Français",
+  "Português", "Italiano", "Русский", "Polski", "日本語",
+  "简体中文"). Picking a language restarts Refrain so the
+  QTranslator picks up the new `.qm`. Together with English and
+  German, this covers roughly 3 billion native speakers.
+
+### Fixed
+
+- **GitHub release bodies were one-line "Full Changelog: …"** — the
+  release workflow used `generate_release_notes: true`, which is
+  GitHub's auto-generated content (just a compare-link to the
+  previous tag). The in-app inline release-notes pane and the
+  popup dialog rendered that 79-character body verbatim. The
+  workflow now extracts the matching `## [X.Y.Z]` section from
+  CHANGELOG.md via awk and feeds it as the release `body_path`.
+  Existing v0.1.0 – v0.2.5 release bodies were backfilled out-of-
+  band via `gh release edit --notes-file …` against the same
+  extraction.
+- **Release-notes pane stayed empty after every Refrain restart** —
+  the orchestrator's 24-hour startup cooldown blocks
+  `maybe_check_on_startup` whenever `last_check_ts` is recent, and
+  a fresh process has no cached `_latest`. `SettingsWindow` now
+  emits `updatesTabRequested` when the user activates the Updates
+  tab; app.py wires that to a slot that triggers
+  `updater.check_now(manual=True)` only when no cached release is
+  available this session. First visit fetches in the background;
+  subsequent visits use the cache.
+- **`os.execvp` failure during Restart had no fallback** — if
+  `sys.argv[0]` wasn't a runnable script (typical of
+  `python -m refrain` source-checkout invocation, where argv[0] is
+  `__main__.py`), execvp raised an unhandled OSError. Detect
+  unrunnable paths up front and fall back to
+  `<sys.executable> -m refrain`, which always works because
+  Refrain is currently importable. The fallback is also retried
+  from the actual OSError handler if the first execvp fails for
+  any other reason.
+- **`Config.save` leaked .tmp files on write failure** — a disk-
+  full / read-only / permission-denied error during the atomic
+  write left a stale `*.tmp` sibling next to the real config
+  forever. Now wrapped in a `try/finally` that unlinks the partial
+  file before re-raising.
+- **`Config._format_value` didn't escape newline / tab / CR** —
+  any string value with those characters (extremely rare in our
+  schema, but possible via a hand-edited config or a future
+  field) would produce broken TOML that tomllib rejects on next
+  load, tripping the "config unreadable, using defaults" fallback
+  and silently losing every setting. Added `\n` / `\r` / `\t`
+  escapes alongside the existing `\\` / `\"`.
+- **CHANGELOG link `[0.2.1]` was a 404** — pointed at a non-
+  existent `v0.2.1` tag (the v0.2.1 commit was made but never
+  tagged or published; its content rolled into v0.2.2). Replaced
+  with a commit-hash link to `6b339ba`. ROADMAP gained a matching
+  `(rolled into v0.2.2; never separately tagged)` suffix.
+- **Settings → Apply with a non-writable config directory crashed
+  silently.** `Config.save` raised OSError (read-only home, disk
+  full, permissions). PySide6's signal-slot machinery logged
+  "uncaught exception in slot" and Apply visibly did nothing.
+  Now wrapped in try/except: the user gets a `QMessageBox.critical`
+  naming the path + the OS error, and the in-memory daemon state
+  still updates so the rest of the session works.
+- **`autostart.enable` / `disable` raised on filesystem failure**
+  with no user feedback. Now they return a bool and log a warning
+  on failure; Settings → Apply continues instead of crashing.
+- **Update dialog `_on_update_clicked` could TypeError on a
+  re-entered click** — `close_btn.clicked.disconnect()` raises if
+  the signal has no connections (unusual but possible during
+  fast double-clicks while runner setup is in flight). Wrapped
+  in `contextlib.suppress(TypeError)` like the matching
+  `_on_runner_finished` path.
+- **Refrain crashed at startup when no D-Bus session bus was
+  available** — `single_instance.acquire()` propagated
+  `dbus.DBusException` past `app.py`'s `except AlreadyRunning`,
+  giving the user an unhandled exception traceback instead of a
+  message box. New `SessionBusUnavailable` exception type
+  surfaces the actual reason ("D-Bus session bus unavailable")
+  with hints about `dbus-daemon` / `DBUS_SESSION_BUS_ADDRESS`.
+- **`setup_logging(level)` and `_apply_log_level` crashed on
+  non-string `log_level`** — a hand-edited config with
+  `log_level = false` (boolean) or `log_level = 5` (int) would
+  AttributeError on `.upper()`. Now coerced to str defensively.
+- **`Config._construct` accepted wrongly-typed values silently** —
+  `cover_cache_size = "200"` (string) would survive the dataclass
+  __init__ but then crash in `_prune_cover_cache` with TypeError on
+  `len(files) - "200"`. The new `_coerce_value()` helper coerces
+  primitives where it makes sense (int from numeric string,
+  bool from "true"/"false") and drops + warns when it doesn't
+  (e.g. `log_level = false` → use the field default). 1 new test
+  in test_config.py.
+- **Cover-art cache writes leaked .tmp files on disk failure** —
+  `cover_art._write_cache` and `download_cover_image` called
+  `tmp.write_bytes()` / `os.replace()` without exception
+  handling. A read-only `~/.cache/refrain/covers/` left a stale
+  `*.tmp` next to the real file forever. Both now wrap in
+  try/except, clean up the partial tmp, and log debug.
+- **`_bridge_sandboxed_ipc_socket` could raise on locked-down
+  sandbox dirs** — a permission-denied `iterdir()` of one of the
+  Snap/Flatpak candidate paths used to propagate up through
+  `DiscordRPC._ensure_connected` → daemon `_tick`'s except, killing
+  the connect attempt every poll. Now wrapped: failures log debug
+  and the connect proceeds without sandbox-bridging.
+- **iTunes search shape-check.** A malformed response (string
+  error, list-not-dict, missing fields) used to AttributeError
+  on `data.get("results", [])` or `first.get(...)`. Now both
+  layers check `isinstance(...)` first and treat unexpected
+  shapes as "no result" — caller falls back to the bundled
+  brand icon.
+- **`_prune_cover_cache` could crash daemon startup** on a
+  permission-denied or corrupt cache dir. Now wraps the
+  enumerate/sort in try/except, logs debug, returns 0 — the
+  daemon starts normally and lives without prune until next
+  session. Plus defensive int() coercion of `max_entries`.
+
+### Tests
+
+- 3 new in `tests/test_config.py` covering newline-escape
+  round-trip and the .tmp cleanup-on-failure path.
+
+## [0.2.5] - 2026-05-07
+
+A same-day patch on top of v0.2.4 driven by user feedback that the
+AUR / Flatpak update path was effectively unusable from the GUI — the
+dialog only displayed the package-manager command in a popup and
+expected the user to copy + paste it into a terminal themselves.
+
+### Changed
+
+- **AUR + Flatpak updates now spawn a terminal automatically** with
+  the package-manager command pre-typed. The user confirms any sudo
+  prompt in the terminal, the package manager retains state, and
+  Refrain just needs a restart afterwards. The
+  "Refrain never modifies system files directly" guarantee is
+  preserved — we only spawn the user's own AUR helper / `flatpak`,
+  and only inside a terminal the user can read / cancel.
+  - `_run_in_terminal()` walks a probe list (konsole, gnome-terminal,
+    xfce4-terminal, kitty, alacritty, foot, xterm, wezterm) and
+    spawns the first hit. Falls back to the previous "show command
+    in a popup" behaviour when no terminal is on PATH.
+  - `_aur_helper()` picks `yay` → `paru` → `trizen` → `pikaur` in
+    that order; falls back to `sudo pacman -Syu refrain` when no
+    helper is installed.
+  - Update dialog button label flips from "Show update command" to
+    "Run update in terminal" when the install is AUR or Flatpak.
+
+### Tests
+
+- 4 new tests in `tests/test_updater.py` covering the fallback
+  message-box path, terminal-spawn for both AUR + Flatpak, and the
+  `_aur_helper` pacman fallback when no helper is installed.
+
 ## [0.2.4] - 2026-05-07
 
 A polish + reliability release built on the v0.2.3 distro-portability
@@ -379,6 +541,11 @@ of reliability + UX work driven by live-testing the v0.2.1 build.
 
 ## [0.2.1] - 2026-05-06
 
+> **Note:** v0.2.1 was never tagged or published as a separate
+> release. The changes documented below were rolled into the
+> subsequent v0.2.2 release. Kept here for changelog continuity —
+> see [v0.2.2](#022---2026-05-06) for the actually-shipped delta.
+
 Polish release built around the v0.2.0 surface. The Settings window got
 a UI overhaul, two notification cover-art races are gone, and the
 external code-review punch list landed in full (atomic config writes,
@@ -812,10 +979,13 @@ with a proper, installable Linux app.
   pip-audit, trufflehog, release), Dependabot, issue + PR templates,
   `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
 
-[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.2.6...HEAD
+[0.2.6]: https://github.com/Rockykln/refrain/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/Rockykln/refrain/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/Rockykln/refrain/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/Rockykln/refrain/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/Rockykln/refrain/compare/v0.2.1...v0.2.2
-[0.2.1]: https://github.com/Rockykln/refrain/compare/v0.2.0...v0.2.1
+[0.2.1]: https://github.com/Rockykln/refrain/commit/6b339ba
 [0.2.0]: https://github.com/Rockykln/refrain/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/Rockykln/refrain/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/Rockykln/refrain/compare/v0.1.3...v0.1.4

{refrain-0.2.4 → refrain-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.4
+Version: 0.2.6
 Summary: Discord Rich Presence for Apple Music on Linux
 Project-URL: Homepage, https://github.com/Rockykln/refrain
 Project-URL: Repository, https://github.com/Rockykln/refrain

{refrain-0.2.4 → refrain-0.2.6}/ROADMAP.md

@@ -145,7 +145,7 @@ What's done, what's next, what's deliberately not in scope.
 - **Window-title cleanup** — no more "Refrain — Settings — Refrain"
   triple; Qt's auto-suffix is the only place "Refrain" appears.
 
-## Done — v0.2.1
+## Done — v0.2.1 (rolled into v0.2.2; never separately tagged)
 
 - **Settings UI overhaul** — consistent `QGroupBox` + form-layout
   across every tab, left-aligned group titles via stylesheet

{refrain-0.2.4 → refrain-0.2.6}/packaging/appimage/AppImageBuilder.yml

@@ -30,7 +30,7 @@ AppDir:
     id: io.github.Rockykln.Refrain
     name: Refrain
     icon: refrain
-    version: 0.2.4
+    version: 0.2.6
     exec: usr/bin/python3
     exec_args: -m refrain $@
 

{refrain-0.2.4 → refrain-0.2.6}/packaging/aur/refrain/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = refrain
 	pkgdesc = Discord Rich Presence for Apple Music on Linux
-	pkgver = 0.2.3
+	pkgver = 0.2.5
 	pkgrel = 1
 	url = https://github.com/Rockykln/refrain
 	arch = any
@@ -14,7 +14,7 @@ pkgbase = refrain
 	depends = python-dbus
 	depends = pyside6
 	optdepends = python-gobject: enables MPRIS-server publication so Plasma media controls reach Refrain
-	source = refrain-0.2.3.tar.gz::https://github.com/Rockykln/refrain/archive/v0.2.3.tar.gz
-	sha256sums = 29f2371393d855f508730238a096cbdc85219616a9fab240745c1072a005b23d
+	source = refrain-0.2.5.tar.gz::https://github.com/Rockykln/refrain/archive/v0.2.5.tar.gz
+	sha256sums = 7ee7b991fab3ba2149fe72745b1432ef11abd7714ffba71cafd3bf1b6af5a6c4
 
 pkgname = refrain

{refrain-0.2.4 → refrain-0.2.6}/packaging/aur/refrain/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Rockykln <contact@rockykln.com>
 
 pkgname=refrain
-pkgver=0.2.4
+pkgver=0.2.6
 pkgrel=1
 pkgdesc="Discord Rich Presence for Apple Music on Linux"
 arch=('any')
@@ -23,7 +23,7 @@ makedepends=(
     'python-wheel'
 )
 source=("$pkgname-$pkgver.tar.gz::https://github.com/Rockykln/refrain/archive/v$pkgver.tar.gz")
-sha256sums=('SKIP')
+sha256sums=('7ee7b991fab3ba2149fe72745b1432ef11abd7714ffba71cafd3bf1b6af5a6c4')
 
 build() {
     cd "$pkgname-$pkgver"

{refrain-0.2.4 → refrain-0.2.6}/packaging/flatpak/io.github.Rockykln.Refrain.metainfo.xml

@@ -51,6 +51,33 @@
   <content_rating type="oars-1.1" />
 
   <releases>
+    <release version="0.2.6" date="2026-05-07">
+      <description>
+        <p>
+          Localization expansion. Refrain now ships full UI
+          translations for 8 additional languages — Spanish,
+          French, Portuguese, Italian, Russian, Polish, Japanese,
+          and Simplified Chinese — covering an additional ~3
+          billion native speakers worldwide on top of English and
+          German. Also fixes the empty "Latest release notes" pane
+          that pipx-installed v0.2.5 showed on the Updates tab
+          when no auto-check had fetched the body yet.
+        </p>
+      </description>
+    </release>
+    <release version="0.2.5" date="2026-05-07">
+      <description>
+        <p>
+          Same-day patch over v0.2.4. AUR and Flatpak updates now
+          spawn a terminal emulator running the package-manager
+          command (yay -Syu / flatpak update) instead of just
+          displaying the command in a popup for the user to retype.
+          The user confirms any sudo prompt in the terminal, the
+          package manager retains state. Falls back to the previous
+          message-box hint when no terminal is on PATH.
+        </p>
+      </description>
+    </release>
     <release version="0.2.4" date="2026-05-07">
       <description>
         <p>

{refrain-0.2.4 → refrain-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refrain"
-version = "0.2.4"
+version = "0.2.6"
 description = "Discord Rich Presence for Apple Music on Linux"
 readme = "README.md"
 requires-python = ">=3.11"

refrain-0.2.6/src/refrain/__init__.py

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

{refrain-0.2.4 → refrain-0.2.6}/src/refrain/app.py

@@ -41,7 +41,7 @@ from refrain.config import Config
 from refrain.daemon import Daemon
 from refrain.logging_setup import attach_qt_log_bridge, setup_logging
 from refrain.paths import assets_dir
-from refrain.single_instance import AlreadyRunning
+from refrain.single_instance import AlreadyRunning, SessionBusUnavailable
 from refrain.single_instance import acquire as acquire_lock
 from refrain.ui.log_window import LogWindow
 from refrain.ui.settings_window import SettingsWindow
@@ -340,7 +340,10 @@ def _apply_log_level(config: Config) -> None:
     Settings dialog takes effect immediately, instead of silently
     waiting for the next restart.
     """
-    level_name = (config.advanced.log_level or "INFO").upper()
+    # Defensive str() coercion: a hand-edited config with
+    # `log_level = 5` would otherwise AttributeError on .upper().
+    raw = config.advanced.log_level
+    level_name = str(raw if raw else "INFO").upper()
     level = getattr(logging, level_name, logging.INFO)
     root = logging.getLogger()
     if root.level != level:
@@ -520,6 +523,24 @@ def main() -> int:
             _tr("app", "Refrain is already running."),
         )
         return 0
+    except SessionBusUnavailable as e:
+        log.error("Cannot start without a session bus")
+        QMessageBox.critical(
+            None,
+            _tr("app", "D-Bus session bus unavailable"),
+            _tr(
+                "app",
+                "Refrain needs a working D-Bus session bus to run "
+                "(it's used for the single-instance lock, MPRIS metadata "
+                "from your browser, and the Plasma-panel media-controls "
+                "publication).\n\n"
+                "Underlying error: {error}\n\n"
+                "On a desktop session this should normally be available "
+                "automatically. Check that dbus-daemon is running and "
+                "that DBUS_SESSION_BUS_ADDRESS is set in your environment.",
+            ).format(error=str(e)),
+        )
+        return 1
     app._refrain_bus_lock = bus_lock  # keep alive for the lifetime of the app
 
     if not QSystemTrayIcon.isSystemTrayAvailable():
@@ -587,6 +608,19 @@ def main() -> int:
     )
     updater.releaseInfoFetched.connect(settings.set_latest_release)
 
+    # Auto-fetch on first visit to Settings → Updates so the inline
+    # release-notes pane populates without the user needing to click
+    # "Check for updates now". Skipped when we already have a cached
+    # release this session — re-fetching every tab open is wasteful
+    # and can hit GitHub's unauthenticated rate limit on multi-restart
+    # debug sessions. The 24-hour startup cooldown stays in place for
+    # actual auto-checks; this is opt-in via tab activation.
+    def _maybe_fetch_for_tab() -> None:
+        if updater.latest is None and updater._thread is None:
+            updater.check_now(manual=True)
+
+    settings.updatesTabRequested.connect(_maybe_fetch_for_tab)
+
     # Log-window wireup
     def _show_log() -> None:
         log_window.show()
@@ -717,7 +751,42 @@ def main() -> int:
         # so the rotating file handler's buffer doesn't lose the last
         # restart line.
         logging.shutdown()
-        os.execvp(binary, [binary, *new_argv])
+        # Two failure modes we have to handle:
+        #   1. binary is empty or not a real path (sys.argv[0] missing,
+        #      or `python -m refrain` invocation where argv[0] is the
+        #      __main__.py file rather than an executable).
+        #   2. execvp itself fails (binary not on PATH, permission denied).
+        # Fall back to `<sys.executable> -m refrain`, which always works
+        # if Refrain is currently importable (which it must be, since
+        # we just ran it). Without this fallback, source-checkout dev
+        # users would get an OSError traceback instead of a working
+        # restart.
+        is_runnable_script = binary and (
+            os.path.isabs(binary)
+            and os.access(binary, os.X_OK)
+            and not binary.endswith(".py")
+        )
+        if not is_runnable_script:
+            log.info(
+                "Restart: %r isn't a runnable script; falling back to `%s -m refrain`",
+                binary,
+                sys.executable,
+            )
+            binary = sys.executable
+            new_argv = ["-m", "refrain", *new_argv]
+        try:
+            os.execvp(binary, [binary, *new_argv])
+        except OSError as e:
+            log.error(
+                "Re-exec failed (%s) — falling back to `%s -m refrain`",
+                e,
+                sys.executable,
+            )
+            try:
+                os.execvp(sys.executable, [sys.executable, "-m", "refrain", *new_argv])
+            except OSError as e2:
+                log.error("Fallback re-exec also failed (%s); exiting non-zero", e2)
+                return 1
 
     log.info("Refrain shutting down with rc=%d", rc)
     return rc

{refrain-0.2.4 → refrain-0.2.6}/src/refrain/autostart.py

@@ -83,15 +83,33 @@ def is_enabled() -> bool:
     return autostart_path().exists()
 
 
-def enable() -> None:
+def enable() -> bool:
+    """Write the autostart .desktop file. Returns True on success.
+
+    Returning False (instead of raising) keeps the Settings → Apply
+    flow alive when ~/.config/autostart/ is read-only or out of
+    space — the user gets a logged warning and the rest of Apply
+    (config save, daemon update_config) still runs.
+    """
     p = autostart_path()
-    p.parent.mkdir(parents=True, exist_ok=True)
-    p.write_text(_desktop_entry(), encoding="utf-8")
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(_desktop_entry(), encoding="utf-8")
+    except OSError as e:
+        log.warning("Could not enable autostart at %s: %s", p, e)
+        return False
     log.info("Autostart enabled at %s", p)
+    return True
 
 
-def disable() -> None:
+def disable() -> bool:
     p = autostart_path()
-    if p.exists():
+    if not p.exists():
+        return True
+    try:
         p.unlink()
-        log.info("Autostart disabled (removed %s)", p)
+    except OSError as e:
+        log.warning("Could not disable autostart at %s: %s", p, e)
+        return False
+    log.info("Autostart disabled (removed %s)", p)
+    return True

{refrain-0.2.4 → refrain-0.2.6}/src/refrain/config.py

@@ -15,22 +15,102 @@ from refrain.paths import config_path
 log = logging.getLogger(__name__)
 
 
+def _coerce_value(annot, name: str, value):
+    """Best-effort coercion of a single config value to its declared
+    field type. Raises TypeError when the value can't be made to fit.
+
+    Coercion rules:
+      bool → accept bool; "true"/"false"/"yes"/"no"/"0"/"1" strings
+        from a hand-edit get converted; otherwise reject.
+      int  → accept int (but reject bool, since
+        ``poll_interval_ms = true`` is much more likely a typo than
+        a literal 1); coerce floats by truncating; coerce numeric
+        strings; reject otherwise.
+      str  → accept str; coerce other primitives via str(); reject
+        otherwise.
+    """
+    if annot is bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            low = value.strip().lower()
+            if low in ("true", "1", "yes"):
+                return True
+            if low in ("false", "0", "no"):
+                return False
+        if isinstance(value, (int, float)):
+            return bool(value)
+        raise TypeError(f"{name}={value!r} is not a bool")
+    if annot is int:
+        if isinstance(value, bool):
+            raise TypeError(f"{name}={value!r} is bool, not int")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, float):
+            return int(value)
+        if isinstance(value, str) and value.strip().lstrip("-").isdigit():
+            return int(value.strip())
+        raise TypeError(f"{name}={value!r} is not an int")
+    if annot is str:
+        if isinstance(value, str):
+            return value
+        # Accept numeric primitives (rare hand-edit case where someone
+        # wrote `client_id = 1234` instead of `"1234"`). Reject bool
+        # explicitly — `log_level = false` is much more likely a typo
+        # for `log_level = "INFO"` than the literal string "False".
+        if isinstance(value, bool):
+            raise TypeError(f"{name}={value!r} is bool, not str")
+        if isinstance(value, (int, float)):
+            return str(value)
+        raise TypeError(f"{name}={value!r} is not a str")
+    # Un-annotated / non-primitive field type — accept as-is.
+    return value
+
+
+# Populated lazily from typing.get_type_hints() the first time each
+# section is loaded. Keyed by ``cls.__qualname__`` so reloads (tests,
+# hot-reload) refresh per-section without rebuilding everything.
+_DATACLASS_HINTS: dict[str, dict[str, type]] = {}
+
+
 def _construct(cls, payload):
-    """Build a dataclass from ``payload`` while ignoring unknown keys.
+    """Build a dataclass from ``payload`` while ignoring unknown keys
+    AND coercing/dropping wrongly-typed values.
 
     Plain ``cls(**payload)`` raises TypeError on any key that isn't a
     declared field — including keys written by a *newer* Refrain that
     the user has since downgraded from, or hand-edited typos. The
     surrounding except in ``Config.load`` would then drop the *whole*
     config back to defaults, silently losing every other setting the
-    user picked. Filtering first means a single stray key just gets
+    user picked. Filtering + per-field coercion means a single stray
+    key (or a wrong type, e.g. ``log_level = false``) just gets
     dropped (with a warning) and the rest of the section survives.
     """
+    import typing
+
+    qual = cls.__qualname__
+    if qual not in _DATACLASS_HINTS:
+        _DATACLASS_HINTS[qual] = typing.get_type_hints(cls)
+    hints = _DATACLASS_HINTS[qual]
+
     if not payload:
         return cls()
-    known = {f.name for f in dataclasses.fields(cls)}
-    accepted = {k: v for k, v in payload.items() if k in known}
-    dropped = set(payload) - known
+    known_field_names = {f.name for f in dataclasses.fields(cls)}
+    accepted: dict = {}
+    dropped: list[str] = []
+    for k, v in payload.items():
+        if k not in known_field_names:
+            dropped.append(k)
+            continue
+        try:
+            accepted[k] = _coerce_value(hints.get(k), k, v)
+        except (TypeError, ValueError) as e:
+            log.warning(
+                "Config: dropping wrongly-typed %s.%s value (%s) — using default",
+                cls.__name__,
+                k,
+                e,
+            )
     if dropped:
         log.warning(
             "Config: ignoring unknown %s keys %s — likely from a different "
@@ -210,8 +290,19 @@ class Config:
         # half-written config — and refrain falls back to defaults on
         # malformed TOML, silently losing every setting the user picked.
         tmp = path.with_suffix(path.suffix + ".tmp")
-        tmp.write_text(_serialize(self.to_dict()), encoding="utf-8")
-        os.replace(tmp, path)
+        try:
+            tmp.write_text(_serialize(self.to_dict()), encoding="utf-8")
+            os.replace(tmp, path)
+        except Exception:
+            # Disk full / permission denied / read-only fs — clean up
+            # the partial tmp file before re-raising so we don't leak
+            # a stale .tmp next to the real config.
+            if tmp.exists():
+                import contextlib
+
+                with contextlib.suppress(OSError):
+                    tmp.unlink()
+            raise
         log.info("Config saved to %s", path)
 
 
@@ -231,5 +322,18 @@ def _format_value(v: Any) -> str:
         return "true" if v else "false"
     if isinstance(v, (int, float)):
         return str(v)
-    s = str(v).replace("\\", "\\\\").replace('"', '\\"')
+    # TOML basic-string escaping: backslash + double-quote are
+    # required by the spec; tab / newline / carriage-return are
+    # added so an accidentally-multiline value (paste from a wider
+    # field) doesn't produce a half-line that tomllib would then
+    # reject on next load and trip the "config unreadable, using
+    # defaults" fallback.
+    s = (
+        str(v)
+        .replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+        .replace("\t", "\\t")
+    )
     return f'"{s}"'