fix(logging): keep console output to spinner banners only

Console sinks ignored log level, so debug diagnostics (run_conditions
evaluation, guard skip/call lines, dataclass dumps) leaked to the
terminal and GUI console. Gate sinks on level: debug now goes to the
file log only; info and above reach the console.

Stop the guard decorator from announcing skips on-console — it logs at
debug only; meaningful skips are reported by the step's caller under its
banner.

Make the GUI console 1-to-1 with the terminal: clear the transient
status line when a banner finishes, and render the finished banner as
the plain done-title (no checkmark), exactly as the terminal prints it.

Add parity and level-gating tests.

Author: vagabondHustler

src/subsearch/core/run_conditions.py

@@ -28,6 +28,17 @@ class PipelineStep(StrEnum):
 
 ConditionList = list[tuple[str, "bool | Callable[[], bool]"]]
 
+STEP_DISPLAY_NAMES = {
+    PipelineStep.SUBTITLE_POST_PROCESSING: "Post-processing",
+    PipelineStep.EXTRACT_FILES: "Extracting subtitles",
+    PipelineStep.SUBTITLE_RENAME: "Renaming subtitle",
+    PipelineStep.SUBTITLE_MOVE_BEST: "Moving best subtitle",
+    PipelineStep.SUBTITLE_MOVE_ALL: "Moving all subtitles",
+    PipelineStep.RUN_PROVIDER_DIAGNOSTICS: "Provider diagnostics",
+    PipelineStep.FINISH_NOTIFICATION: "Finish notification",
+    PipelineStep.DOWNLOAD_FILES: "Downloading subtitles",
+}
+
 SKIP_LABEL_EXPLANATIONS = {
     "provider_enabled": "disabled in settings",
     "language_supports_opensubtitles": "does not support the selected language",
@@ -55,17 +66,6 @@ class PipelineStep(StrEnum):
     "diagnostics_enabled": "diagnostics are disabled in settings",
 }
 
-STEP_DISPLAY_NAMES = {
-    PipelineStep.SUBTITLE_POST_PROCESSING: "Post-processing",
-    PipelineStep.EXTRACT_FILES: "Extracting subtitles",
-    PipelineStep.SUBTITLE_RENAME: "Renaming subtitle",
-    PipelineStep.SUBTITLE_MOVE_BEST: "Moving best subtitle",
-    PipelineStep.SUBTITLE_MOVE_ALL: "Moving all subtitles",
-    PipelineStep.RUN_PROVIDER_DIAGNOSTICS: "Provider diagnostics",
-    PipelineStep.FINISH_NOTIFICATION: "Finish notification",
-    PipelineStep.DOWNLOAD_FILES: "Downloading subtitles",
-}
-
 
 class RunConditions:
     def __init__(self, bootstrap: Bootstrap) -> None:

src/subsearch/decorators/conditional_execution.py

@@ -6,6 +6,9 @@
 
 
 def run_if_conditions_met(func: Callable[..., Any]) -> Callable[..., Any]:
+    # The guard's skip/call/explanation lines are diagnostics for the file log
+    # only (debug level), never the console. Meaningful skips a user should see
+    # are reported explicitly by the step's caller, swallowed by its banner.
 
     @functools.wraps(func)
     def wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -16,7 +19,7 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
             log.event(LogEvent.GUARD_STEP_SKIPPED, level="debug", qualified_name=qualified_name)
             skip_explanation = instance.call_conditions.skip_explanation(func.__name__)
             if skip_explanation is not None:
-                log.event(LogEvent.PIPELINE_STEP_SKIPPED, message=skip_explanation)
+                log.event(LogEvent.PIPELINE_STEP_SKIPPED, level="debug", message=skip_explanation)
             return None
         log.event(LogEvent.GUARD_STEP_CALLED, level="debug", qualified_name=qualified_name)
         return func(*args, **kwargs)

src/subsearch/decorators/process_guard.py

@@ -38,7 +38,7 @@ def _release_mutex(kernel32: Any, mutex: Any) -> None:
 def _log_single_instance_setting() -> None:
     try:
         single_instance = config_session.get_config_session().read(ConfigKey.APPLICATION_SINGLE_INSTANCE)
-    except (FileNotFoundError, KeyError, TypeError):
+    except FileNotFoundError, KeyError, TypeError:
         return
 
     log.event(

src/subsearch/runtime/logging/logger.py

@@ -96,7 +96,7 @@ def _clear_crash_log_periodically() -> None:
     counter_path = FILE_PATHS.crash.with_suffix(".count")
     try:
         run_count = int(counter_path.read_text(encoding="utf-8")) + 1
-    except (FileNotFoundError, ValueError):
+    except FileNotFoundError, ValueError:
         run_count = 1
     if run_count >= CRASH_CLEAR_EVERY_RUNS:
         FILE_PATHS.crash.unlink(missing_ok=True)
@@ -179,6 +179,10 @@ def write(
         is_last: bool = False,
     ) -> None:
         self.file_logger.log(LEVELS[level], message, stacklevel=3)
+        # Debug lines are diagnostics for the file log only; the console (terminal
+        # banner and GUI mirror) shows the user-facing run, so they never reach a sink.
+        if LEVELS[level] < logging.INFO:
+            return
         self._console_history.append(
             ConsoleRecord(
                 message=message,

src/subsearch/ui/widgets/console_view.py

@@ -15,7 +15,6 @@
 # animates with the same glyphs the terminal shows.
 SPINNER_FRAMES = ("◜", "◠", "◝", "◞", "◡", "◟")
 SPINNER_INTERVAL_MS = 100
-SPINNER_DONE_MARK = "✔"
 
 CONSOLE_STYLE_SHEET = """
 QListWidget {
@@ -129,11 +128,20 @@ def _finish_banner(self, done_title: str) -> None:
         if self._banner_item is None:
             return
         self._spinner_timer.stop()
-        self._banner_item.setText(f"{SPINNER_DONE_MARK} {done_title}")
+        # The transient status line is cleared on finish, exactly as the terminal
+        # console drops its in-place line; the spinner glyph is replaced by the
+        # plain done-title the terminal prints (no decoration), so both match.
+        self._remove_status_item()
+        self._banner_item.setText(done_title)
         self._banner_item = None
-        self._status_item = None
         self._banner_title = ""
 
+    def _remove_status_item(self) -> None:
+        if self._status_item is None:
+            return
+        self._list.takeItem(self._list.row(self._status_item))
+        self._status_item = None
+
     def _tick_spinner(self) -> None:
         if self._banner_item is None:
             return

tests/test_console_parity.py

@@ -0,0 +1,87 @@
+from subsearch.runtime.logging.spinner_console import SpinnerConsole
+
+# A representative run: a banner with two transient lines, a plain line before
+# any banner, a second banner, and a final is_last close. The terminal and GUI
+# consoles must end up showing the same visible lines.
+RECORDS = [
+    {"message": "early line"},
+    {"message": "--- [Searching] ---", "is_banner": True, "title": "Searching", "done_title": "Searched"},
+    {"message": "opensubtitles: searching"},
+    {"message": "opensubtitles: found 3"},
+    {"message": "--- [Cleaning up] ---", "is_banner": True, "title": "Cleaning up", "done_title": "Cleaned up"},
+    {"message": "", "is_last": True},
+]
+
+
+def terminal_visible_lines() -> list[str]:
+    printed: list[str] = []
+    transient: list[str] = []
+
+    class StubTransient:
+        def update(self, spinner, message: str) -> None:
+            if transient:
+                transient[-1] = message
+            else:
+                transient.append(message)
+
+        def clear(self, spinner) -> None:
+            transient.clear()
+
+    class StubSpinner:
+        def __init__(self, text: str) -> None:
+            self.text = text
+
+        def start(self) -> None:
+            pass
+
+        def stop(self) -> None:
+            pass
+
+    console = SpinnerConsole(
+        spinner_factory=StubSpinner,
+        printer=printed.append,
+        transient_line=StubTransient(),
+    )
+    for record in RECORDS:
+        console.write(record["message"], **{key: value for key, value in record.items() if key != "message"})
+    return printed
+
+
+def gui_visible_lines(qtbot) -> list[str]:
+    from subsearch.runtime.logging.logger import log
+    from subsearch.ui.services.console_view import ConsoleViewSink
+    from subsearch.ui.widgets.console_view import ConsoleView
+
+    # The logger is a process-wide singleton; other tests leave records in its
+    # history that the sink would replay into the view. Isolate to this sequence.
+    log._console_history.clear()
+    sink = ConsoleViewSink()
+    view = ConsoleView(sink)
+    qtbot.addWidget(view)
+    dispatch = {
+        "line": view._append,
+        "banner": view._start_banner,
+        "finish": view._finish_banner,
+        "status": view._update_status,
+    }
+    try:
+        for record in RECORDS:
+            sink._on_message(
+                record["message"],
+                **{key: value for key, value in record.items() if key != "message"},
+            )
+        # Drive the view directly from the sink's recorded protocol; the live
+        # widget uses queued connections that need an event loop to deliver.
+        for kind, payload in sink.history():
+            dispatch[kind](payload)
+        return [view._list.item(row).text() for row in range(view._list.count())]
+    finally:
+        sink.detach()
+
+
+def test_terminal_and_gui_show_the_same_lines(qtbot) -> None:
+    # No normalization: the GUI must render finished banners as the plain
+    # done-title the terminal prints, with no checkmark or other decoration.
+    terminal = terminal_visible_lines()
+    gui = gui_visible_lines(qtbot)
+    assert terminal == gui

tests/test_logger_console_levels.py

@@ -0,0 +1,29 @@
+from subsearch.runtime.logging.logger import Logger
+
+
+def _capture(logger: Logger) -> list[str]:
+    captured: list[str] = []
+    logger._sinks.clear()
+    logger.add_sink(lambda message, **_: captured.append(message))
+    return captured
+
+
+def test_debug_messages_never_reach_console_sinks() -> None:
+    logger = Logger()
+    captured = _capture(logger)
+
+    logger.debug("diagnostic detail")
+
+    assert captured == []
+    assert logger._console_history == []
+
+
+def test_info_and_above_reach_console_sinks() -> None:
+    logger = Logger()
+    captured = _capture(logger)
+
+    logger.info("user-facing line")
+    logger.warning("heads up")
+    logger.error("something failed")
+
+    assert captured == ["user-facing line", "heads up", "something failed"]

tests/test_run_conditions.py

@@ -287,6 +287,24 @@ def test_unmet_condition_labels_empty_when_provider_runs(fake_cls: FakeBootstrap
     assert fake_cls.call_conditions.unmet_condition_labels("opensubtitles") == []
 
 
+def test_skip_explanation_for_mode_gate(fake_cls: FakeBootstrap) -> None:
+    fake_cls.app_mode = AppMode.SEARCH_MANUAL
+
+    explanation = fake_cls.call_conditions.skip_explanation("subtitle_post_processing")
+    assert explanation is not None
+    assert "Post-processing skipped" in explanation
+
+
+def test_skip_explanation_shown_for_actionable_skip(fake_cls: FakeBootstrap) -> None:
+    fake_cls.app_mode = AppMode.SEARCH_HYBRID
+    fake_cls.extracted_subtitle_archives = 1
+    fake_cls.app_config.post_processing["rename"] = False
+
+    explanation = fake_cls.call_conditions.skip_explanation("subtitle_rename")
+    assert explanation is not None
+    assert "renaming is disabled" in explanation
+
+
 def test_conditions_finish_notification(fake_cls: FakeBootstrap) -> None:
     fake_cls.app_mode = AppMode.SEARCH_HYBRID
     assert fake_cls.call_conditions.conditions_met(fake_cls.func_name) is True

tests/test_ui_entrypoint.py

@@ -6,8 +6,8 @@ def _spinner_titles(events):
 
 
 def _patch_window(monkeypatch, events):
-    from subsearch.ui.application import entrypoint
     from subsearch.runtime.logging.logger import log
+    from subsearch.ui.application import entrypoint
 
     class FakeWindow:
         def __init__(self, *args, **kwargs) -> None: