synodic-client 0.0.1.dev51__tar.gz → 0.0.1.dev53__tar.gz

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: synodic_client
-Version: 0.0.1.dev51
+Version: 0.0.1.dev53
 Author-Email: Synodic Software <contact@synodic.software>
 License: LGPL-3.0-or-later
 Project-URL: homepage, https://github.com/synodic/synodic-client

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
     "velopack>=0.0.1444.dev49733",
     "typer>=0.24.1",
 ]
-version = "0.0.1.dev51"
+version = "0.0.1.dev53"
 
 [project.license]
 text = "LGPL-3.0-or-later"

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/bootstrap.py

@@ -20,11 +20,12 @@ from synodic_client.logging import configure_logging
 from synodic_client.protocol import extract_uri_from_args
 from synodic_client.updater import initialize_velopack
 
-# Parse --dev flag early so logging uses the right filename.
+# Parse flags early so logging uses the right filename and level.
 _dev_mode = '--dev' in sys.argv[1:]
+_debug = '--debug' in sys.argv[1:]
 set_dev_mode(_dev_mode)
 
-configure_logging()
+configure_logging(debug=_debug)
 initialize_velopack()
 
 if not _dev_mode:
@@ -35,4 +36,4 @@ if not _dev_mode:
 # Heavy imports happen here — PySide6, porringer, etc.
 from synodic_client.application.qt import application
 
-application(uri=extract_uri_from_args(), dev_mode=_dev_mode)
+application(uri=extract_uri_from_args(), dev_mode=_dev_mode, debug=_debug)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/qt.py

@@ -5,14 +5,15 @@ import ctypes
 import logging
 import signal
 import sys
+import traceback
 import types
 from collections.abc import Callable
 
 import qasync
 from porringer.api import API
 from porringer.schema import LocalConfiguration
-from PySide6.QtCore import Qt, QTimer
-from PySide6.QtWidgets import QApplication
+from PySide6.QtCore import QEvent, QObject, Qt, QTimer
+from PySide6.QtWidgets import QApplication, QWidget
 
 from synodic_client.application.icon import app_icon
 from synodic_client.application.init import run_startup_preamble
@@ -23,7 +24,7 @@ from synodic_client.application.screen.tray import TrayScreen
 from synodic_client.application.uri import parse_uri
 from synodic_client.client import Client
 from synodic_client.config import set_dev_mode
-from synodic_client.logging import configure_logging
+from synodic_client.logging import configure_logging, set_debug_level
 from synodic_client.protocol import extract_uri_from_args
 from synodic_client.resolution import (
     ResolvedConfig,
@@ -90,6 +91,34 @@ def _install_exception_hook(logger: logging.Logger) -> None:
     sys.excepthook = _exception_hook
 
 
+class _TopLevelShowFilter(QObject):
+    """[DIAG] Application-wide event filter that logs Show/WindowActivate on top-level widgets."""
+
+    _diag_logger = logging.getLogger('synodic_client.diag.window')
+
+    def eventFilter(self, obj: QObject, event: QEvent) -> bool:  # noqa: N802
+        if (
+            event.type() in {QEvent.Type.Show, QEvent.Type.WindowActivate}
+            and isinstance(obj, QWidget)
+            and obj.isWindow()
+        ):
+            geo = obj.geometry()
+            stack = ''.join(traceback.format_stack(limit=12))
+            self._diag_logger.debug(
+                '[DIAG] Top-level window %s: class=%s title=%r geo=(%d,%d %dx%d) visible=%s\n%s',
+                event.type().name,
+                type(obj).__qualname__,
+                obj.windowTitle(),
+                geo.x(),
+                geo.y(),
+                geo.width(),
+                geo.height(),
+                obj.isVisible(),
+                stack,
+            )
+        return False
+
+
 def _init_app() -> QApplication:
     """Create and configure the ``QApplication``."""
     # Set the App User Model ID so Windows uses our icon on the taskbar
@@ -104,6 +133,10 @@ def _init_app() -> QApplication:
     app.setWindowIcon(app_icon())
     app.setAttribute(Qt.ApplicationAttribute.AA_CompressHighFrequencyEvents)
 
+    # [DIAG] Install a global event filter to log every top-level window show.
+    diag_filter = _TopLevelShowFilter(app)  # parented to app, prevented from GC
+    app.installEventFilter(diag_filter)
+
     # Allow Ctrl+C in the terminal to terminate the application.
     # Qt's event loop blocks Python's default SIGINT handling, so we
     # install our own handler and use a short timer to let Python
@@ -116,7 +149,7 @@ def _init_app() -> QApplication:
     return app
 
 
-def application(*, uri: str | None = None, dev_mode: bool = False) -> None:
+def application(*, uri: str | None = None, dev_mode: bool = False, debug: bool = False) -> None:
     """Application entry point.
 
     Args:
@@ -126,13 +159,14 @@ def application(*, uri: str | None = None, dev_mode: bool = False) -> None:
             log files, or single-instance locks with the user-installed
             application.  Velopack initialisation and protocol
             registration are skipped.
+        debug: When ``True``, enable DEBUG-level file logging.
     """
     # Activate dev-mode namespacing before anything reads config paths.
     set_dev_mode(dev_mode)
 
     # Configure logging before Velopack so install/uninstall hooks and
     # first-run diagnostics are captured in the log file.
-    configure_logging()
+    configure_logging(debug=debug)
     logger = logging.getLogger('synodic_client')
     _install_exception_hook(logger)
 
@@ -147,6 +181,11 @@ def application(*, uri: str | None = None, dev_mode: bool = False) -> None:
 
     client, porringer, config = _init_services(logger)
 
+    # Honour the persisted debug_logging preference unless the --debug
+    # flag already activated it.
+    if not debug and config.debug_logging:
+        set_debug_level(enabled=True)
+
     app = _init_app()
 
     loop = qasync.QEventLoop(app)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/install.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import traceback
 from pathlib import Path
 from typing import Any
 
@@ -27,6 +28,7 @@ from porringer.schema import (
     SyncStrategy,
 )
 from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtGui import QShowEvent
 from PySide6.QtWidgets import (
     QFileDialog,
     QFrame,
@@ -890,6 +892,21 @@ class InstallPreviewWindow(QMainWindow):
 
         self._init_ui()
 
+    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+        """[DIAG] Log every show event with a stack trace."""
+        geo = self.geometry()
+        stack = ''.join(traceback.format_stack(limit=10))
+        logger.warning(
+            '[DIAG] InstallPreviewWindow.showEvent: geo=(%d,%d %dx%d) visible=%s\n%s',
+            geo.x(),
+            geo.y(),
+            geo.width(),
+            geo.height(),
+            self.isVisible(),
+            stack,
+        )
+        super().showEvent(event)
+
     def _init_ui(self) -> None:
         """Build the UI layout."""
         central = QWidget()
@@ -952,11 +969,6 @@ class InstallPreviewWindow(QMainWindow):
 
     # --- Lifecycle ---
 
-    def showEvent(self, event: Any) -> None:
-        """Log when the window becomes visible."""
-        super().showEvent(event)
-        logger.info('Install preview window shown (visible=%s)', self.isVisible())
-
     def closeEvent(self, event: Any) -> None:
         """Clean up the temp directory when the window is closed."""
         logger.info('Install preview window closing')

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/plugin_row.py

@@ -37,8 +37,10 @@ from synodic_client.application.theme import (
     PLUGIN_ROW_PROJECT_TAG_STYLE,
     PLUGIN_ROW_PROJECT_TAG_TRANSITIVE_STYLE,
     PLUGIN_ROW_REMOVE_STYLE,
+    PLUGIN_ROW_STATUS_MIN_WIDTH,
     PLUGIN_ROW_STATUS_STYLE,
     PLUGIN_ROW_STYLE,
+    PLUGIN_ROW_TIMESTAMP_MIN_WIDTH,
     PLUGIN_ROW_TIMESTAMP_STYLE,
     PLUGIN_ROW_TOGGLE_STYLE,
     PLUGIN_ROW_UPDATE_STYLE,
@@ -341,7 +343,7 @@ class PluginRow(QFrame):
 
         Controls are always created in the same order with fixed widths
         so that columns align vertically across all rows.  Hidden
-        controls still reserve space.
+        controls reserve space via ``retainSizeWhenHidden``.
         """
         if data.show_toggle:
             self._build_toggle(layout, data)
@@ -352,23 +354,25 @@ class PluginRow(QFrame):
         # Inline auto-update status (e.g. "Up to date", "v1.2 available")
         self._update_status_label = QLabel()
         self._update_status_label.setStyleSheet(PLUGIN_ROW_STATUS_STYLE)
+        self._update_status_label.setMinimumWidth(PLUGIN_ROW_STATUS_MIN_WIDTH)
         self._update_status_label.hide()
         layout.addWidget(self._update_status_label)
+        self._retain_size(layout)
 
-        # Version
-        if data.version:
-            version_label = QLabel(data.version)
-            version_label.setStyleSheet(PLUGIN_ROW_VERSION_STYLE)
-            version_label.setMinimumWidth(PLUGIN_ROW_VERSION_MIN_WIDTH)
-            version_label.setAlignment(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
-            layout.addWidget(version_label)
+        # Version — always created so column width is reserved
+        version_label = QLabel(data.version)
+        version_label.setStyleSheet(PLUGIN_ROW_VERSION_STYLE)
+        version_label.setMinimumWidth(PLUGIN_ROW_VERSION_MIN_WIDTH)
+        version_label.setAlignment(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
+        layout.addWidget(version_label)
 
-        # Timestamp
+        # Timestamp — always created so column width is reserved
+        self._timestamp_label = QLabel(_format_relative_time(data.last_updated) if data.last_updated else '')
+        self._timestamp_label.setStyleSheet(PLUGIN_ROW_TIMESTAMP_STYLE)
+        self._timestamp_label.setMinimumWidth(PLUGIN_ROW_TIMESTAMP_MIN_WIDTH)
         if data.last_updated:
-            self._timestamp_label = QLabel(_format_relative_time(data.last_updated))
-            self._timestamp_label.setStyleSheet(PLUGIN_ROW_TIMESTAMP_STYLE)
             self._timestamp_label.setToolTip(f'Last updated: {data.last_updated}')
-            layout.addWidget(self._timestamp_label)
+        layout.addWidget(self._timestamp_label)
 
         # Transient inline error label (hidden by default)
         self._error_label = QLabel()
@@ -409,6 +413,18 @@ class PluginRow(QFrame):
         update_btn.setVisible(data.has_update)
         self._update_btn = update_btn
         layout.addWidget(update_btn)
+        self._retain_size(layout)
+
+    @staticmethod
+    def _retain_size(layout: QHBoxLayout) -> None:
+        """Mark the most recently added widget as size-retaining when hidden."""
+        item = layout.itemAt(layout.count() - 1)
+        if item is not None:
+            widget = item.widget()
+            if widget is not None:
+                policy = widget.sizePolicy()
+                policy.setRetainSizeWhenHidden(True)
+                widget.setSizePolicy(policy)
 
     def _build_remove_button(self, layout: QHBoxLayout, data: PluginRowData) -> None:
         """Add the remove button — enabled only for global packages."""

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/screen.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+import traceback
 from collections import OrderedDict
 from pathlib import Path
 
@@ -20,6 +21,7 @@ from porringer.schema import (
 )
 from porringer.schema.plugin import PluginKind
 from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtGui import QShowEvent
 from PySide6.QtWidgets import (
     QHBoxLayout,
     QLineEdit,
@@ -197,6 +199,7 @@ class ToolsView(QWidget):
         """Schedule an asynchronous rebuild of the tool list."""
         if self._refresh_in_progress:
             return
+        logger.debug('ToolsView.refresh() called (visible=%s)', self.isVisible())
         asyncio.create_task(self._async_refresh())
 
     async def _async_refresh(self) -> None:
@@ -1104,6 +1107,21 @@ class MainWindow(QMainWindow):
         # Update banner — always available, starts hidden.
         self._update_banner = UpdateBanner(self)
 
+    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+        """[DIAG] Log every show event with a stack trace."""
+        geo = self.geometry()
+        stack = ''.join(traceback.format_stack(limit=10))
+        logger.debug(
+            '[DIAG] MainWindow.showEvent: geo=(%d,%d %dx%d) visible=%s\n%s',
+            geo.x(),
+            geo.y(),
+            geo.width(),
+            geo.height(),
+            self.isVisible(),
+            stack,
+        )
+        super().showEvent(event)
+
     @property
     def porringer(self) -> API | None:
         """Return the porringer API instance, if available."""

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/settings.py

@@ -7,11 +7,12 @@ Updates* button with inline status feedback.
 
 import logging
 import sys
+import traceback
 from collections.abc import Iterator
 from contextlib import contextmanager
 
 from PySide6.QtCore import Qt, QUrl, Signal
-from PySide6.QtGui import QDesktopServices
+from PySide6.QtGui import QDesktopServices, QShowEvent
 from PySide6.QtWidgets import (
     QCheckBox,
     QComboBox,
@@ -31,7 +32,7 @@ from synodic_client.application.icon import app_icon
 from synodic_client.application.screen import _format_relative_time
 from synodic_client.application.screen.card import CardFrame
 from synodic_client.application.theme import SETTINGS_WINDOW_MIN_SIZE, UPDATE_STATUS_CHECKING_STYLE
-from synodic_client.logging import log_path
+from synodic_client.logging import log_path, set_debug_level
 from synodic_client.resolution import ResolvedConfig, update_user_config
 from synodic_client.schema import GITHUB_REPO_URL
 from synodic_client.startup import is_startup_registered, register_startup, remove_startup
@@ -53,6 +54,24 @@ class SettingsWindow(QMainWindow):
     check_updates_requested = Signal()
     """Emitted when the user clicks the *Check for Updates* button."""
 
+    restart_requested = Signal()
+    """Emitted when the user clicks the *Restart & Update* button."""
+
+    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+        """[DIAG] Log every show event with a stack trace."""
+        geo = self.geometry()
+        stack = ''.join(traceback.format_stack(limit=10))
+        logger.debug(
+            '[DIAG] SettingsWindow.showEvent: geo=(%d,%d %dx%d) visible=%s\n%s',
+            geo.x(),
+            geo.y(),
+            geo.width(),
+            geo.height(),
+            self.isVisible(),
+            stack,
+        )
+        super().showEvent(event)
+
     def __init__(
         self,
         config: ResolvedConfig,
@@ -183,6 +202,12 @@ class SettingsWindow(QMainWindow):
         self._update_status_label = QLabel('')
         self._update_status_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
         row.addWidget(self._update_status_label)
+
+        self._restart_btn = QPushButton('Restart \u0026 Update')
+        self._restart_btn.clicked.connect(self.restart_requested.emit)
+        self._restart_btn.hide()
+        row.addWidget(self._restart_btn)
+
         row.addStretch()
         content.addLayout(row)
 
@@ -202,6 +227,12 @@ class SettingsWindow(QMainWindow):
     def _build_advanced_section(self) -> CardFrame:
         """Construct the *Advanced* settings card."""
         card = CardFrame('Advanced')
+
+        self._debug_logging_check = QCheckBox('Debug logging')
+        self._debug_logging_check.setToolTip('Write DEBUG-level messages to the log file')
+        self._debug_logging_check.toggled.connect(self._on_debug_logging_changed)
+        card.content_layout.addWidget(self._debug_logging_check)
+
         row = QHBoxLayout()
         open_log_btn = QPushButton('Open Log\u2026')
         open_log_btn.clicked.connect(self._open_log)
@@ -238,6 +269,9 @@ class SettingsWindow(QMainWindow):
             self._auto_apply_check.setChecked(config.auto_apply)
             self._auto_start_check.setChecked(is_startup_registered())
 
+            # Debug logging
+            self._debug_logging_check.setChecked(config.debug_logging)
+
             # Last client update timestamp
             if config.last_client_update:
                 relative = _format_relative_time(config.last_client_update)
@@ -259,6 +293,7 @@ class SettingsWindow(QMainWindow):
     def set_checking(self) -> None:
         """Enter the *checking* state — disable button and show status."""
         self._check_updates_btn.setEnabled(False)
+        self._restart_btn.hide()
         self._update_status_label.setText('Checking\u2026')
         self._update_status_label.setStyleSheet(UPDATE_STATUS_CHECKING_STYLE)
 
@@ -266,6 +301,10 @@ class SettingsWindow(QMainWindow):
         """Re-enable the *Check for Updates* button after a check completes."""
         self._check_updates_btn.setEnabled(True)
 
+    def show_restart_button(self) -> None:
+        """Show the *Restart & Update* button."""
+        self._restart_btn.show()
+
     def show(self) -> None:
         """Sync controls from config, then show the window."""
         self.sync_from_config()
@@ -297,6 +336,7 @@ class SettingsWindow(QMainWindow):
             self._detect_updates_check,
             self._auto_apply_check,
             self._auto_start_check,
+            self._debug_logging_check,
             self._check_updates_btn,
         )
         for w in widgets:
@@ -346,6 +386,10 @@ class SettingsWindow(QMainWindow):
             remove_startup()
         self.settings_changed.emit(self._config)
 
+    def _on_debug_logging_changed(self, checked: bool) -> None:
+        set_debug_level(enabled=checked)
+        self._persist(debug_logging=checked)
+
     @staticmethod
     def _open_log() -> None:
         """Open the log file in the system's default editor."""

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/tool_update_controller.py

@@ -54,6 +54,7 @@ class ToolUpdateOrchestrator:
         window: MainWindow,
         config_resolver: Callable[[], ResolvedConfig],
         tray: QSystemTrayIcon,
+        is_user_active: Callable[[], bool] | None = None,
     ) -> None:
         """Set up the controller.
 
@@ -61,10 +62,14 @@ class ToolUpdateOrchestrator:
             window: The main application window.
             config_resolver: Callable returning the current resolved config.
             tray: System tray icon for notification messages.
+            is_user_active: Predicate returning ``True`` when the user
+                has a visible window.  Periodic tool updates are
+                deferred while active.
         """
         self._window = window
         self._resolve_config = config_resolver
         self._tray = tray
+        self._is_user_active = is_user_active or (lambda: False)
         self._tool_task: asyncio.Task[None] | None = None
         self._tool_update_timer: QTimer | None = None
 
@@ -108,10 +113,17 @@ class ToolUpdateOrchestrator:
         self._tool_update_timer = self._restart_timer(
             self._tool_update_timer,
             config.tool_update_interval_minutes,
-            self.on_tool_update,
+            self._on_periodic_tool_update,
             'Automatic tool updating',
         )
 
+    def _on_periodic_tool_update(self) -> None:
+        """Timer callback — deferred when the user has a visible window."""
+        if self._is_user_active():
+            logger.debug('Periodic tool update deferred — user is active')
+            return
+        self.on_tool_update()
+
     # -- ToolsView signal wiring --
 
     def connect_tools_view(self, tools_view: ToolsView) -> None:
@@ -293,6 +305,12 @@ class ToolUpdateOrchestrator:
 
         # Clear updating state on widgets
         tools_view = self._window.tools_view
+        logger.info(
+            '[DIAG] _on_tool_update_finished: manual=%s, tools_view_exists=%s, window_visible=%s',
+            manual,
+            tools_view is not None,
+            self._window.isVisible(),
+        )
         if tools_view is not None:
             if updating_plugin is not None:
                 tools_view.set_plugin_updating(updating_plugin, False)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/screen/tray.py

@@ -5,6 +5,7 @@ import logging
 from PySide6.QtGui import QAction
 from PySide6.QtWidgets import (
     QApplication,
+    QMainWindow,
     QMenu,
     QSystemTrayIcon,
 )
@@ -72,15 +73,17 @@ class TrayScreen:
             app,
             client,
             self._banner,
-            self._settings_window,
-            config,
+            settings_window=self._settings_window,
+            config=config,
         )
+        self._update_controller.set_user_active_predicate(self._is_user_active)
 
         # Tool update orchestrator - owns tool/package update lifecycle
         self._tool_orchestrator = ToolUpdateOrchestrator(
             window,
             self._resolve_config,
             self.tray,
+            is_user_active=self._is_user_active,
         )
         self._tool_orchestrator.restart_tool_update_timer()
 
@@ -128,6 +131,16 @@ class TrayScreen:
         """Show the settings window."""
         self._settings_window.show()
 
+    @staticmethod
+    def _is_user_active() -> bool:
+        """Return ``True`` when the user has a visible application window.
+
+        Checks all top-level ``QMainWindow`` instances (main window,
+        settings, install previews) so that auto-apply is deferred
+        whenever *any* window is open.
+        """
+        return any(w.isVisible() for w in QApplication.topLevelWidgets() if isinstance(w, QMainWindow))
+
     def _on_settings_changed(self, config: ResolvedConfig) -> None:
         """React to a change made in the settings window."""
         self._config = config

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/theme.py

@@ -231,6 +231,12 @@ PLUGIN_ROW_UPDATE_WIDTH = 52
 PLUGIN_ROW_VERSION_MIN_WIDTH = 60
 """Minimum width for the version label column."""
 
+PLUGIN_ROW_STATUS_MIN_WIDTH = 90
+"""Minimum width for the inline auto-update status label."""
+
+PLUGIN_ROW_TIMESTAMP_MIN_WIDTH = 40
+"""Minimum width for the relative timestamp label."""
+
 PLUGIN_ROW_SPACING = 1
 """Pixels between individual tool/package rows."""
 

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/application/update_controller.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from collections.abc import Callable
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
@@ -53,6 +54,9 @@ class UpdateController:
         The ``SettingsWindow`` (receives status text + colour).
     config:
         Optional pre-resolved configuration.  ``None`` resolves from disk.
+    is_user_active:
+        Predicate returning ``True`` when the user has a visible window.
+        Auto-apply is deferred while active; checks still run normally.
     """
 
     def __init__(
@@ -60,6 +64,7 @@ class UpdateController:
         app: QApplication,
         client: Client,
         banner: UpdateBanner,
+        *,
         settings_window: SettingsWindow,
         config: ResolvedConfig | None = None,
     ) -> None:
@@ -77,6 +82,7 @@ class UpdateController:
         self._banner = banner
         self._settings_window = settings_window
         self._config = config
+        self._is_user_active: Callable[[], bool] = lambda: False
         self._update_task: asyncio.Task[None] | None = None
 
         # Derive auto-apply preference from config
@@ -93,6 +99,15 @@ class UpdateController:
 
         # Wire settings check-updates button
         self._settings_window.check_updates_requested.connect(self._on_manual_check)
+        self._settings_window.restart_requested.connect(self._apply_update)
+
+    def set_user_active_predicate(self, predicate: Callable[[], bool]) -> None:
+        """Set the predicate used to defer auto-apply when the user is active.
+
+        Args:
+            predicate: Returns ``True`` when the user has a visible window.
+        """
+        self._is_user_active = predicate
 
     # ------------------------------------------------------------------
     # Config helpers
@@ -104,6 +119,14 @@ class UpdateController:
             return self._config
         return resolve_config()
 
+    def _can_auto_apply(self) -> bool:
+        """Return whether a downloaded update should be applied automatically.
+
+        Auto-apply is suppressed when the user has a visible window so
+        the application is never force-restarted during active use.
+        """
+        return self._auto_apply and not self._is_user_active()
+
     # ------------------------------------------------------------------
     # Timer management
     # ------------------------------------------------------------------
@@ -176,7 +199,12 @@ class UpdateController:
         self._do_check(silent=False)
 
     def _on_auto_check(self) -> None:
-        """Handle automatic (periodic) check — silent."""
+        """Handle automatic (periodic) check — silent.
+
+        The check always runs so the settings window can show the
+        latest status and the *last updated* timestamp stays current.
+        Auto-apply is gated separately by :meth:`_can_auto_apply`.
+        """
         self._do_check(silent=True)
 
     def _do_check(self, *, silent: bool) -> None:
@@ -193,9 +221,11 @@ class UpdateController:
 
     async def _async_check(self, *, silent: bool) -> None:
         """Run the update check coroutine and route results."""
+        logger.info('[DIAG] Self-update check starting (silent=%s)', silent)
         try:
             result = await check_for_update(self._client)
             self._on_check_finished(result, silent=silent)
+            logger.info('[DIAG] Self-update check completed (silent=%s)', silent)
         except Exception as exc:
             logger.exception('Update check failed')
             self._on_check_error(str(exc), silent=silent)
@@ -277,7 +307,7 @@ class UpdateController:
         # Persist the client update timestamp
         update_user_config(last_client_update=datetime.now(UTC).isoformat())
 
-        if self._auto_apply:
+        if self._can_auto_apply():
             # Silently apply and restart — no banner, no user interaction
             logger.info('Auto-applying update v%s', version)
             self._settings_window.set_update_status(
@@ -287,12 +317,13 @@ class UpdateController:
             self._apply_update(silent=True)
             return
 
-        # Manual mode — show ready banner and let user choose when to restart
+        # Manual mode (or user is active) — show ready banner and let user choose when to restart
         self._banner.show_ready(version)
         self._settings_window.set_update_status(
             f'v{version} ready',
             UPDATE_STATUS_UP_TO_DATE_STYLE,
         )
+        self._settings_window.show_restart_button()
 
     def _on_download_error(self, error: str) -> None:
         """Handle download error — show error banner."""

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/cli.py

@@ -35,8 +35,12 @@ def main(
         bool,
         typer.Option('--dev', help='Run in dev mode with isolated config, logs, and instance lock.'),
     ] = False,
+    debug: Annotated[
+        bool,
+        typer.Option('--debug', help='Enable DEBUG-level file logging for this session.'),
+    ] = False,
 ) -> None:
     """Launch the Synodic Client GUI application."""
     from synodic_client.application.qt import application
 
-    application(uri=uri, dev_mode=dev)
+    application(uri=uri, dev_mode=dev, debug=debug)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/logging.py

@@ -1,6 +1,7 @@
 """Centralised logging configuration for the Synodic Client.
 
-Provides a rotating file handler with eager flushing.
+Provides a rotating file handler with eager flushing and runtime
+log-level switching via :func:`set_debug_level`.
 """
 
 import logging
@@ -17,6 +18,8 @@ _MAX_BYTES = 5_242_880  # 5 MB
 _BACKUP_COUNT = 3
 _FORMAT = '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
 
+_debug_active: bool = False
+
 
 def log_path() -> Path:
     """Return the path to the application log file.
@@ -43,13 +46,18 @@ class EagerRotatingFileHandler(RotatingFileHandler):
         self.flush()
 
 
-def configure_logging() -> None:
+def configure_logging(*, debug: bool = False) -> None:
     """Set up application-wide logging.
 
     Attaches a :class:`EagerRotatingFileHandler` to the ``synodic_client``
     and ``porringer`` loggers and configures :func:`logging.basicConfig`
     for ``INFO`` level output on *stderr*.
 
+    Args:
+        debug: When ``True``, set the file handler and app logger to
+            ``DEBUG`` level immediately.  Equivalent to calling
+            :func:`set_debug_level` after configuration.
+
     Safe to call more than once — subsequent calls are no-ops.
     """
     app_logger = logging.getLogger('synodic_client')
@@ -80,3 +88,26 @@ def configure_logging() -> None:
         porringer_logger.setLevel(logging.DEBUG)
     else:
         porringer_logger.setLevel(logging.INFO)
+
+    if debug:
+        set_debug_level(enabled=True)
+
+
+def set_debug_level(*, enabled: bool) -> None:
+    """Switch the app logger and file handler between DEBUG and INFO at runtime.
+
+    Safe to call at any time.  Has no effect if logging has not been
+    configured yet.
+
+    Args:
+        enabled: ``True`` for DEBUG, ``False`` for INFO.
+    """
+    global _debug_active  # noqa: PLW0603
+    _debug_active = enabled
+    level = logging.DEBUG if enabled else logging.INFO
+
+    app_logger = logging.getLogger('synodic_client')
+    app_logger.setLevel(level)
+    for h in app_logger.handlers:
+        if isinstance(h, EagerRotatingFileHandler):
+            h.setLevel(level)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/resolution.py

@@ -114,6 +114,7 @@ def _resolve_from_user(user: UserConfig) -> ResolvedConfig:
 
     auto_apply = user.auto_apply if user.auto_apply is not None else True
     auto_start = user.auto_start if user.auto_start is not None else True
+    debug_logging = user.debug_logging if user.debug_logging is not None else False
 
     return ResolvedConfig(
         update_source=user.update_source,
@@ -125,6 +126,7 @@ def _resolve_from_user(user: UserConfig) -> ResolvedConfig:
         prerelease_packages=user.prerelease_packages,
         auto_apply=auto_apply,
         auto_start=auto_start,
+        debug_logging=debug_logging,
         last_client_update=user.last_client_update,
         last_tool_updates=user.last_tool_updates,
     )

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/schema.py

@@ -100,6 +100,10 @@ class UserConfig(BaseModel):
     # auto-startup.
     auto_start: bool | None = None
 
+    # Enable verbose DEBUG-level logging to the log file.
+    # None resolves to False (INFO level).
+    debug_logging: bool | None = None
+
     # ISO 8601 timestamp of the last successful client self-update.
     # None means no update has been recorded.
     last_client_update: str | None = None
@@ -231,5 +235,6 @@ class ResolvedConfig:
     prerelease_packages: dict[str, list[str]] | None
     auto_apply: bool
     auto_start: bool
+    debug_logging: bool
     last_client_update: str | None
     last_tool_updates: dict[str, str] | None

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/synodic_client/updater.py

@@ -7,6 +7,7 @@ and installation.
 For non-installed (development) environments, updates are not supported.
 """
 
+import contextlib
 import logging
 import sys
 from collections.abc import Callable
@@ -114,6 +115,12 @@ class Updater:
         self._velopack_manager: Any = None
         self._velopack_not_installed: bool = False
 
+        # Eagerly resolve the Velopack manager so that
+        # _current_version reflects the installed binary version
+        # rather than the (potentially stale) Python package metadata.
+        with contextlib.suppress(Exception):
+            self._get_velopack_manager()
+
         logger.info(
             'Updater created: version=%s, channel=%s, repo=%s',
             self._current_version,
@@ -406,6 +413,11 @@ def initialize_velopack() -> None:
         return
     _VelopackState.initialized = True
 
+    # During post-update restarts Velopack's App.run() may exit the
+    # current process (to apply the update and relaunch).  Each
+    # short-lived process writes "Initializing Velopack" to the shared
+    # log file before being replaced, so multiple entries followed by a
+    # single "initialized successfully" is expected behaviour.
     logger.info('Initializing Velopack (exe=%s)', sys.executable)
     try:
         app = velopack.App()

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/qt/test_gather_packages.py

@@ -41,6 +41,7 @@ def _make_config() -> ResolvedConfig:
         prerelease_packages=None,
         auto_apply=True,
         auto_start=False,
+        debug_logging=False,
         last_client_update=None,
         last_tool_updates=None,
     )

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/qt/test_settings.py

@@ -27,6 +27,7 @@ def _make_config(**overrides: Any) -> ResolvedConfig:
         'prerelease_packages': None,
         'auto_apply': True,
         'auto_start': True,
+        'debug_logging': False,
         'last_client_update': None,
         'last_tool_updates': None,
     }

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/qt/test_update_controller.py

@@ -38,6 +38,7 @@ def _make_config(**overrides: Any) -> ResolvedConfig:
         'prerelease_packages': None,
         'auto_apply': True,
         'auto_start': True,
+        'debug_logging': False,
         'last_client_update': None,
         'last_tool_updates': None,
     }
@@ -49,6 +50,7 @@ def _make_controller(
     *,
     auto_apply: bool = True,
     auto_update_interval_minutes: int = 0,
+    is_user_active: bool = False,
 ) -> tuple[UpdateController, MagicMock, MagicMock, UpdateBanner, MagicMock]:
     """Build an ``UpdateController`` with mocked collaborators.
 
@@ -69,7 +71,14 @@ def _make_controller(
         mock_ucfg.return_value = MagicMock(
             auto_update_interval_minutes=auto_update_interval_minutes,
         )
-        controller = UpdateController(app, client, banner, settings, config)
+        controller = UpdateController(
+            app,
+            client,
+            banner,
+            settings_window=settings,
+            config=config,
+        )
+        controller.set_user_active_predicate(lambda: is_user_active)
 
     return controller, app, client, banner, settings
 
@@ -189,6 +198,27 @@ class TestDownloadFinished:
             UPDATE_STATUS_UP_TO_DATE_STYLE,
         )
 
+    @staticmethod
+    def test_no_auto_apply_shows_restart_button() -> None:
+        """When auto_apply=False, the restart button should be shown in settings."""
+        ctrl, app, client, banner, settings = _make_controller(auto_apply=False)
+        ctrl._on_download_finished(True, '2.0.0')
+
+        settings.show_restart_button.assert_called_once()
+
+    @staticmethod
+    def test_user_active_shows_restart_button() -> None:
+        """When user is active, the restart button should be shown in settings."""
+        ctrl, app, client, banner, settings = _make_controller(
+            auto_apply=True,
+            is_user_active=True,
+        )
+
+        with patch.object(ctrl, '_apply_update'):
+            ctrl._on_download_finished(True, '2.0.0')
+
+        settings.show_restart_button.assert_called_once()
+
     @staticmethod
     def test_download_failure_shows_error() -> None:
         """A failed download should show an error banner."""
@@ -199,6 +229,84 @@ class TestDownloadFinished:
         settings.set_update_status.assert_called_with('Download failed', UPDATE_STATUS_ERROR_STYLE)
 
 
+# ---------------------------------------------------------------------------
+# User-active gating
+# ---------------------------------------------------------------------------
+
+
+class TestUserActiveGating:
+    """Verify that auto-apply is deferred when the user is active.
+
+    Automatic checks always run so the settings window stays current.
+    Only the silent apply-and-restart is gated by ``_is_user_active``.
+    """
+
+    @staticmethod
+    def test_auto_check_always_runs() -> None:
+        """_on_auto_check should call _do_check even when user is active."""
+        ctrl, _app, _client, banner, settings = _make_controller(is_user_active=True)
+
+        with patch.object(ctrl, '_do_check') as mock_check:
+            ctrl._on_auto_check()
+
+        mock_check.assert_called_once_with(silent=True)
+
+    @staticmethod
+    def test_manual_check_unaffected_by_active_user() -> None:
+        """_on_manual_check should always call _do_check regardless of user activity."""
+        ctrl, _app, _client, banner, settings = _make_controller(is_user_active=True)
+
+        with patch.object(ctrl, '_do_check') as mock_check:
+            ctrl._on_manual_check()
+
+        mock_check.assert_called_once_with(silent=False)
+
+    @staticmethod
+    def test_auto_apply_deferred_when_user_active() -> None:
+        """When auto_apply=True but user is active, show READY banner instead of applying."""
+        ctrl, app, client, banner, settings = _make_controller(
+            auto_apply=True,
+            is_user_active=True,
+        )
+
+        with patch.object(ctrl, '_apply_update') as mock_apply:
+            ctrl._on_download_finished(True, '2.0.0')
+
+        mock_apply.assert_not_called()
+        assert banner.state.name == 'READY'
+
+    @staticmethod
+    def test_auto_apply_proceeds_when_user_inactive() -> None:
+        """When auto_apply=True and user is inactive, _apply_update is called."""
+        ctrl, app, client, banner, settings = _make_controller(
+            auto_apply=True,
+            is_user_active=False,
+        )
+
+        with patch.object(ctrl, '_apply_update') as mock_apply:
+            ctrl._on_download_finished(True, '2.0.0')
+
+        mock_apply.assert_called_once_with(silent=True)
+
+    @staticmethod
+    def test_can_auto_apply_false_when_user_active() -> None:
+        """_can_auto_apply should return False when auto_apply=True but user is active."""
+        ctrl, *_ = _make_controller(auto_apply=True, is_user_active=True)
+        assert ctrl._can_auto_apply() is False
+
+    @staticmethod
+    def test_can_auto_apply_false_when_disabled() -> None:
+        """_can_auto_apply should return False when auto_apply=False."""
+        ctrl, *_ = _make_controller(auto_apply=False, is_user_active=False)
+        assert ctrl._can_auto_apply() is False
+
+    @staticmethod
+    def test_can_auto_apply_true_when_enabled_and_inactive() -> None:
+        """_can_auto_apply should return True only when auto_apply=True and user is inactive."""
+        ctrl, *_ = _make_controller(auto_apply=True, is_user_active=False)
+        assert ctrl._can_auto_apply() is True
+
+
 # ---------------------------------------------------------------------------
 # Apply update
 # ---------------------------------------------------------------------------
@@ -226,6 +334,14 @@ class TestApplyUpdate:
         client.apply_update_on_exit.assert_not_called()
         app.quit.assert_not_called()
 
+    @staticmethod
+    def test_restart_requested_signal_triggers_apply() -> None:
+        """The settings restart_requested signal should be connected to _apply_update."""
+        ctrl, app, client, banner, settings = _make_controller()
+
+        # Verify the signal was connected
+        settings.restart_requested.connect.assert_called_once_with(ctrl._apply_update)
+
 
 # ---------------------------------------------------------------------------
 # Settings changed → immediate check

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/test_cli.py

@@ -36,7 +36,7 @@ class TestCli:
         with patch('synodic_client.application.qt.application') as mock_app:
             result = runner.invoke(app, [])
             assert result.exit_code == 0
-            mock_app.assert_called_once_with(uri=None, dev_mode=False)
+            mock_app.assert_called_once_with(uri=None, dev_mode=False, debug=False)
 
     @staticmethod
     def test_launches_application_with_uri() -> None:
@@ -45,7 +45,7 @@ class TestCli:
         with patch('synodic_client.application.qt.application') as mock_app:
             result = runner.invoke(app, [test_uri])
             assert result.exit_code == 0
-            mock_app.assert_called_once_with(uri=test_uri, dev_mode=False)
+            mock_app.assert_called_once_with(uri=test_uri, dev_mode=False, debug=False)
 
     @staticmethod
     def test_launches_application_with_dev_flag() -> None:
@@ -53,4 +53,4 @@ class TestCli:
         with patch('synodic_client.application.qt.application') as mock_app:
             result = runner.invoke(app, ['--dev'])
             assert result.exit_code == 0
-            mock_app.assert_called_once_with(uri=None, dev_mode=True)
+            mock_app.assert_called_once_with(uri=None, dev_mode=True, debug=False)

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/test_config.py

@@ -49,6 +49,7 @@ class TestUserConfig:
         assert config.prerelease_packages is None
         assert config.auto_apply is None
         assert config.auto_start is None
+        assert config.debug_logging is None
 
     @staticmethod
     def test_prerelease_packages_round_trip() -> None:

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/test_resolution.py

@@ -38,6 +38,7 @@ def _make_resolved(**overrides: Any) -> ResolvedConfig:
         'prerelease_packages': None,
         'auto_apply': True,
         'auto_start': True,
+        'debug_logging': False,
         'last_client_update': None,
         'last_tool_updates': None,
     }

{synodic_client-0.0.1.dev51 → synodic_client-0.0.1.dev53}/tests/unit/test_updater.py

@@ -70,7 +70,12 @@ class TestGithubReleaseAssetUrl:
 @pytest.fixture
 def updater() -> Updater:
     """Create an Updater instance for testing."""
-    return Updater(current_version=Version('1.0.0'))
+    u = Updater(current_version=Version('1.0.0'))
+    # Reset state cached by the eager _get_velopack_manager() call
+    # so each test can independently mock the Velopack SDK.
+    u._velopack_manager = None
+    u._velopack_not_installed = False
+    return u
 
 
 @pytest.fixture
@@ -80,7 +85,10 @@ def updater_with_config() -> Updater:
         repo_url='https://github.com/test/repo',
         channel=UpdateChannel.DEVELOPMENT,
     )
-    return Updater(current_version=Version('1.0.0'), config=config)
+    u = Updater(current_version=Version('1.0.0'), config=config)
+    u._velopack_manager = None
+    u._velopack_not_installed = False
+    return u
 
 
 class TestUpdater: