data-hub-watcher 0.2.2__tar.gz → 0.2.4__tar.gz

{data_hub_watcher-0.2.2/src/data_hub_watcher.egg-info → data_hub_watcher-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-hub-watcher
-Version: 0.2.2
+Version: 0.2.4
 Summary: File-watcher agent for lab instrument PCs that ingests data into Data Hub.
 Author-email: Arcadia Science <swe@arcadiascience.com>
 License-Expression: MIT

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-hub-watcher"
-version = "0.2.2"
+version = "0.2.4"
 description = "File-watcher agent for lab instrument PCs that ingests data into Data Hub."
 readme = "README.md"
 requires-python = ">=3.12"

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/src/data_hub_watcher/service.py

@@ -113,13 +113,57 @@ def _install_upgrade_worker(config_dir: Path) -> None:
     request/result paths in at render time, so a mismatch here results
     in the worker reading from one directory while the service writes
     to another (and the auto-update silently no-ops every tick).
+
+    The operator's uv tool directories are resolved here (rather than
+    inside the worker) because the SYSTEM account that later executes
+    the worker resolves them against the wrong profile —
+    ``C:\\Windows\\System32\\config\\systemprofile\\.local\\...`` rather
+    than ``C:\\Users\\<op>\\.local\\...``. We capture the operator's
+    paths once at install time and bake them into the rendered
+    template via ``UV_TOOL_DIR`` / ``UV_TOOL_BIN_DIR`` overrides; see
+    :func:`data_hub_watcher.upgrade_worker.resolve_uv_tool_dirs` for
+    the long form of the rationale.
     """
     from data_hub_watcher.scheduled_task import install_upgrade_task
-    from data_hub_watcher.upgrade_worker import write_worker_script
+    from data_hub_watcher.self_update import (
+        UvExecutableNotFoundError,
+        _resolve_uv_executable,
+    )
+    from data_hub_watcher.upgrade_worker import (
+        UvToolDirResolutionError,
+        resolve_uv_tool_dirs,
+        write_worker_script,
+    )
 
-    script_path = write_worker_script(config_dir, service_name=SERVICE_NAME)
+    uv_path, _tried = _resolve_uv_executable()
+    if uv_path is None:
+        # The same `UvExecutableNotFoundError` the in-process updater
+        # raises — re-uses the operator-facing message format so a
+        # ``service install`` failure here looks identical to a stuck
+        # ``self-update``, which lab-PC docs already cover.
+        raise UvExecutableNotFoundError(_tried)
+    try:
+        tool_dir, tool_bin_dir = resolve_uv_tool_dirs(uv_path)
+    except UvToolDirResolutionError:
+        # Re-raise so ``service install`` aborts loudly. Letting the
+        # install proceed with default tool dirs (i.e. omitting the
+        # env-var overrides) would just reproduce the SYSTEM-installs-
+        # to-wrong-place bug we're trying to fix.
+        raise
+
+    script_path = write_worker_script(
+        config_dir,
+        service_name=SERVICE_NAME,
+        tool_dir=tool_dir,
+        tool_bin_dir=tool_bin_dir,
+    )
     install_upgrade_task(script_path)
-    logger.info("Upgrade worker script + scheduled task registered under %s", config_dir)
+    logger.info(
+        "Upgrade worker script + scheduled task registered under %s (uv tool dir=%s, bin dir=%s)",
+        config_dir,
+        tool_dir,
+        tool_bin_dir,
+    )
 
 
 def _store_paths_in_registry(config_path: Path, env_path: Path) -> None:
@@ -400,25 +444,37 @@ def query_service_status() -> dict[str, Any]:
 
 
 def _repair_upgrade_worker_if_missing(sm: Any, config_dir: Path) -> None:
-    """Re-install the upgrade scheduled task on startup if it has gone missing.
+    """Re-register the upgrade scheduled task on startup if it has gone missing.
 
     Lab PCs that auto-update into the version that introduced the
     out-of-process worker won't have run ``service install`` with the
     new code, so the scheduled task simply isn't there — and the next
     auto-update tick would fail loudly. Repairing on each service
     startup means the host self-heals on the very next service restart
-    (which the auto-updater triggers anyway), without any operator
-    intervention.
+    (which the auto-updater triggers anyway) for the common case where
+    the rendered worker script is still on disk and only the task
+    record was lost (e.g. an operator manually deleted it in
+    ``taskschd.msc``).
+
+    Critical scope limit: this helper does NOT re-render the worker
+    template. Re-rendering requires the *operator's* uv tool
+    directories from ``uv tool dir`` / ``uv tool dir --bin``, and the
+    service runs as LocalSystem so any uv invocation from here would
+    resolve those paths against the SYSTEM profile rather than the
+    operator's. A SYSTEM-rendered template would bake in the wrong
+    ``UV_TOOL_DIR`` / ``UV_TOOL_BIN_DIR`` and silently install future
+    upgrades into ``C:\\Windows\\System32\\config\\systemprofile\\
+    .local\\...`` instead of the operator's profile — exactly the bug
+    we're trying to prevent. If the rendered script is also missing
+    from *config_dir*, the only safe recovery is for the operator to
+    run ``data-hub-watcher service reinstall`` from their own shell;
+    we log a clear pointer and punt rather than render-against-SYSTEM
+    a worker that would corrupt the next auto-update.
 
     *config_dir* must be the operator's resolved config directory (the
-    parent of the registry-stored config path) — NOT
-    ``DEFAULT_CONFIG_DIR``, because under the LocalSystem account the
-    service runs as the latter resolves to
-    ``C:\\Windows\\System32\\config\\systemprofile\\.data-hub`` rather
-    than the operator's ``~\\.data-hub``. Rendering the worker template
-    against the wrong directory bakes in a sentinel path the running
-    service will never actually write to, which silently breaks every
-    subsequent auto-update.
+    parent of the registry-stored config path) — see the comment on
+    :class:`~data_hub_watcher.runtime.WatcherRuntime.config_dir` for
+    why ``DEFAULT_CONFIG_DIR`` would resolve incorrectly here.
 
     Failures are logged via the Windows event log but do not raise:
     a host that can't register the task should still be able to run
@@ -432,7 +488,7 @@ def _repair_upgrade_worker_if_missing(sm: Any, config_dir: Path) -> None:
             install_upgrade_task,
             task_exists,
         )
-        from data_hub_watcher.upgrade_worker import write_worker_script
+        from data_hub_watcher.upgrade_worker import upgrade_worker_script_path
     except Exception as exc:
         sm.LogWarningMsg(f"Cannot import upgrade worker modules during startup: {exc}")
         return
@@ -450,12 +506,27 @@ def _repair_upgrade_worker_if_missing(sm: Any, config_dir: Path) -> None:
     if present:
         return
 
+    script_path = upgrade_worker_script_path(config_dir)
+    if not script_path.exists():
+        # We deliberately do NOT re-render here — see the docstring
+        # for why a SYSTEM-rendered template would silently break the
+        # very thing the repair is meant to fix.
+        sm.LogWarningMsg(
+            f"Upgrade scheduled task is missing AND the rendered worker "
+            f"script is absent from {script_path}. Cannot self-repair "
+            "from a LocalSystem context. Run "
+            "'data-hub-watcher service reinstall' as Administrator to "
+            "re-render the worker against the operator's uv tool "
+            "directories and re-register the task."
+        )
+        return
+
     sm.LogInfoMsg(
-        "Upgrade scheduled task missing; re-registering it now (one-time "
-        "self-repair after auto-update into worker-aware code)."
+        f"Upgrade scheduled task missing but worker script is present at "
+        f"{script_path}; re-registering the task pointing at the existing "
+        "rendered script."
     )
     try:
-        script_path = write_worker_script(config_dir, service_name=SERVICE_NAME)
         install_upgrade_task(script_path)
     except (OSError, ScheduledTaskError) as exc:
         sm.LogWarningMsg(

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/src/data_hub_watcher/updater.py

@@ -85,6 +85,20 @@ class UpdaterConfig:
     # reason about heartbeat timing.
     min_run_age_seconds: float | None = None
     run_quiet_multiplier: int = DEFAULT_RUN_QUIET_MULTIPLIER
+    # When True (the production default), the very first heartbeat tick
+    # after process startup fires an ``/update-check`` API call instead
+    # of waiting a full ``check_interval_ticks`` window — so a fresh
+    # service restart picks up a pending release within one heartbeat
+    # interval (~60 s) rather than up to an hour. The activity-window
+    # gates inside ``should_attempt_update`` still apply: if an upload
+    # or run was happening when the previous instance died, the
+    # ``last_run_age_seconds`` / ``idle_ticks_required`` checks defer
+    # the actual upgrade attempt as designed. The on-start fast path
+    # only short-circuits the *cadence* part of the gate, not the
+    # *safety* part. Tests opt out via ``check_on_start=False`` so
+    # their existing cadence assertions (``for _ in range(N): on_tick();
+    # then trigger on the (N+1)th``) keep working unchanged.
+    check_on_start: bool = True
 
 
 @dataclass
@@ -336,7 +350,22 @@ class Updater:
         self._upgrade_executor = upgrade_executor or _default_upgrade_executor
 
         self._idle_ticks = 0
-        self._ticks_since_check = 0
+        # Seed the cadence counter so the very first tick fires an
+        # ``/update-check`` API call when ``check_on_start`` is set
+        # (the production default). With ``check_interval_ticks=60``
+        # and a 60-second heartbeat, the cold-start latency for
+        # picking up a pending release drops from "up to 60 minutes"
+        # to "~60 seconds" — which matters most during testing
+        # iteration (operator runs ``service reinstall``, then sees
+        # the next attempt within one heartbeat instead of an hour)
+        # but is also a small operability win in production: a host
+        # that just rebooted picks up the latest version immediately
+        # rather than running stale code for the first hour after
+        # boot. The activity-window gates in ``should_attempt_update``
+        # still defer the actual upgrade if there's recent run /
+        # upload activity, so this short-circuits cadence only — not
+        # safety.
+        self._ticks_since_check = c.check_interval_ticks if c.check_on_start else 0
         self._upgrade_in_progress = False
         # Per-target memo for the "ineligible install method" refusal
         # path: we want one ``UPDATE_FAILED`` event per *new* server

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/src/data_hub_watcher/upgrade_worker.py

@@ -40,6 +40,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import subprocess
 import sys
 import uuid
 from dataclasses import dataclass
@@ -355,6 +356,82 @@ def build_pkg_spec(
     return spec
 
 
+# ---------------------------------------------------------------------------
+# uv tool directory resolution
+# ---------------------------------------------------------------------------
+
+
+class UvToolDirResolutionError(RuntimeError):
+    """Raised when ``uv tool dir`` / ``uv tool dir --bin`` can't be resolved.
+
+    Carries the failing argv and uv's stderr so the caller can surface a
+    diagnosable error rather than silently rendering a worker template
+    against an empty path.
+    """
+
+    def __init__(self, argv: list[str], *, stderr: str = "", returncode: int = -1) -> None:
+        super().__init__(
+            f"`{' '.join(argv)}` failed (exit {returncode}): {stderr.strip() or '<no stderr>'}"
+        )
+        self.argv = argv
+        self.stderr = stderr
+        self.returncode = returncode
+
+
+def resolve_uv_tool_dirs(uv_executable: str) -> tuple[Path, Path]:
+    """Return ``(tool_dir, tool_bin_dir)`` for the operator's uv install.
+
+    Captured at install time so the worker template can bake them in
+    explicitly. The worker runs as LocalSystem via the scheduled task,
+    and uv resolves its install directories from ``$env:USERPROFILE``
+    plus the platform-specific defaults — under SYSTEM that resolves
+    to ``C:\\Windows\\System32\\config\\systemprofile\\.local\\share\\
+    uv\\tools`` (and ``…\\.local\\bin``), which is **not** where the
+    running watcher service was originally installed from. Without
+    this override uv happily installs a *second* copy of the package
+    into SYSTEM's profile while the operator's profile (where the
+    Windows-service registered ``ImagePath`` actually points) keeps
+    serving the old version. The next service restart loads the old
+    code and the marker comparison fails with "expected X, running Y".
+
+    By shelling out to ``uv tool dir`` from the install context (where
+    ``$env:USERPROFILE`` correctly points at the operator's home),
+    we capture the *operator's* tool directories and bake them in so
+    the SYSTEM-running worker can force ``uv`` to install in place at
+    the right location via ``UV_TOOL_DIR`` / ``UV_TOOL_BIN_DIR``.
+
+    Raises :class:`UvToolDirResolutionError` on a non-zero exit. The
+    caller (``_install_upgrade_worker``) treats this as fatal so a
+    silent miss surfaces during ``service install`` — by far the
+    cheapest place to catch it.
+    """
+    tool_dir = _run_uv_tool_dir(uv_executable, [])
+    tool_bin_dir = _run_uv_tool_dir(uv_executable, ["--bin"])
+    return tool_dir, tool_bin_dir
+
+
+def _run_uv_tool_dir(uv_executable: str, extra_args: list[str]) -> Path:
+    argv = [uv_executable, "tool", "dir", *extra_args]
+    try:
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise UvToolDirResolutionError(argv, stderr=str(exc)) from exc
+
+    if proc.returncode != 0:
+        raise UvToolDirResolutionError(argv, stderr=proc.stderr, returncode=proc.returncode)
+
+    raw = proc.stdout.strip()
+    if not raw:
+        raise UvToolDirResolutionError(argv, stderr="empty stdout", returncode=proc.returncode)
+    return Path(raw)
+
+
 # ---------------------------------------------------------------------------
 # PowerShell worker template
 # ---------------------------------------------------------------------------
@@ -385,6 +462,18 @@ $ServiceName  = "{service_name}"
 $RequestPath  = "{request_path}"
 $ResultPath   = "{result_path}"
 $LogPath      = "{log_path}"
+# Operator-context paths captured at install time. The scheduled task
+# runs as LocalSystem, so without these overrides `uv tool install`
+# would resolve UV_TOOL_DIR / UV_TOOL_BIN_DIR against
+# C:\\Windows\\System32\\config\\systemprofile\\.local\\... and install
+# a SECOND copy of the package into SYSTEM's profile while the
+# operator's tool venv (which the Windows-service ImagePath actually
+# points at) is left at the old version. The env-var assignments
+# below force uv to reinstall *in place* at the operator's tool dir
+# so the existing service binary path resolves to the new wheel on
+# the next service restart.
+$ToolDir      = "{tool_dir}"
+$ToolBinDir   = "{tool_bin_dir}"
 
 function Write-Log($msg) {{
     $ts = (Get-Date).ToUniversalTime().ToString("o")
@@ -393,8 +482,19 @@ function Write-Log($msg) {{
 }}
 
 function Write-ResultJson($payload) {{
+    # PowerShell 5.1 (the default on Windows 10/11) emits UTF-8 *with*
+    # a BOM when invoked as `Set-Content -Encoding UTF8`. Python's
+    # `json.loads(path.read_text(encoding="utf-8"))` then fails on the
+    # leading U+FEFF and `read_upgrade_result` silently swallows the
+    # JSONDecodeError, returning None. The post-restart inspection in
+    # runtime.py then flags `worker_result_missing=True` even though
+    # the file was written successfully — the operator sees no actual
+    # error context in the failure event and has to remote in to find
+    # it. Use the .NET API with an explicit BOM-less UTF-8 encoder so
+    # the result sentinel is readable on every supported PowerShell.
     $tmp = "$ResultPath.tmp"
-    $payload | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $tmp -Encoding UTF8
+    $json = $payload | ConvertTo-Json -Depth 4
+    [System.IO.File]::WriteAllText($tmp, $json, [System.Text.UTF8Encoding]::new($false))
     Move-Item -LiteralPath $tmp -Destination $ResultPath -Force
 }}
 
@@ -453,6 +553,16 @@ try {{
     # the in-process path produce equivalent uv invocations.
     $uvArgs = @("tool", "install", "--reinstall", "--index-url", $IndexUrl, $PkgSpec)
 
+    # Pin uv's view of the tool directories to the operator's profile,
+    # not LocalSystem's. See the comment on `$ToolDir` / `$ToolBinDir`
+    # above for why this matters. We set them on the process
+    # environment so the subprocess `uv` inherits them; setting via
+    # `Start-Process -Environment` would be cleaner but is not
+    # available on Windows PowerShell 5.1.
+    $env:UV_TOOL_DIR     = $ToolDir
+    $env:UV_TOOL_BIN_DIR = $ToolBinDir
+    Write-Log "uv env: UV_TOOL_DIR=$ToolDir UV_TOOL_BIN_DIR=$ToolBinDir"
+
     Write-Log "running: $UvExe $($uvArgs -join ' ')"
 
     $stdoutFile = [System.IO.Path]::GetTempFileName()
@@ -531,6 +641,8 @@ def render_worker_script(
     request_path: Path,
     result_path: Path,
     log_path: Path,
+    tool_dir: Path,
+    tool_bin_dir: Path,
     generated_at: str | None = None,
 ) -> str:
     """Render :data:`WORKER_SCRIPT_TEMPLATE` with concrete paths.
@@ -540,6 +652,13 @@ def render_worker_script(
     the request sentinel so a post-install relocation of ``uv.exe``
     doesn't require regenerating the script.
 
+    *tool_dir* and *tool_bin_dir* MUST be the paths reported by
+    ``uv tool dir`` / ``uv tool dir --bin`` from the operator's
+    install context. See :func:`resolve_uv_tool_dirs` for the full
+    rationale; the short version is that without these baked into
+    the SYSTEM-running worker, ``uv`` installs into the wrong profile
+    and the auto-update silently no-ops.
+
     The ``.upgrade-in-progress`` marker is intentionally not handed to
     the worker: its full lifecycle (write before dispatch, evaluate
     and clear on the next process start) lives on the Python side in
@@ -551,6 +670,8 @@ def render_worker_script(
         request_path=str(request_path),
         result_path=str(result_path),
         log_path=str(log_path),
+        tool_dir=str(tool_dir),
+        tool_bin_dir=str(tool_bin_dir),
     )
 
 
@@ -558,12 +679,21 @@ def write_worker_script(
     config_dir: Path,
     *,
     service_name: str,
+    tool_dir: Path,
+    tool_bin_dir: Path,
     generated_at: str | None = None,
 ) -> Path:
     """Render the worker script and drop it under *config_dir*.
 
     Returns the resulting path so callers (the service installer) can
     hand it to ``schtasks`` as the action target.
+
+    *tool_dir* / *tool_bin_dir* are required because rendering against
+    a default that resolves under LocalSystem (the account the worker
+    later runs as) silently produces a worker that installs to the
+    wrong profile. Forcing the caller to supply them at install time
+    — when the operator-context :func:`resolve_uv_tool_dirs` lookup
+    is available — keeps the failure mode loud rather than silent.
     """
     script_path = upgrade_worker_script_path(config_dir)
     script = render_worker_script(
@@ -571,6 +701,8 @@ def write_worker_script(
         request_path=upgrade_request_path(config_dir),
         result_path=upgrade_result_path(config_dir),
         log_path=upgrade_worker_log_path(config_dir),
+        tool_dir=tool_dir,
+        tool_bin_dir=tool_bin_dir,
         generated_at=generated_at,
     )
     script_path.parent.mkdir(parents=True, exist_ok=True)

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4/src/data_hub_watcher.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-hub-watcher
-Version: 0.2.2
+Version: 0.2.4
 Summary: File-watcher agent for lab instrument PCs that ingests data into Data Hub.
 Author-email: Arcadia Science <swe@arcadiascience.com>
 License-Expression: MIT

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/tests/test_service.py

@@ -303,6 +303,21 @@ class TestInstallUpgradeWorker:
             "data_hub_watcher.scheduled_task.install_upgrade_task",
             lambda script_path: install_calls.append(script_path),
         )
+        # `_install_upgrade_worker` resolves the operator's uv path
+        # and tool dirs at install time so the SYSTEM-running worker
+        # later forces uv to install in place at the operator's
+        # profile via UV_TOOL_DIR / UV_TOOL_BIN_DIR overrides. Stub
+        # both so the test doesn't depend on a real uv install.
+        operator_tool_dir = tmp_path / "tools"
+        operator_tool_bin_dir = tmp_path / "bin"
+        monkeypatch.setattr(
+            "data_hub_watcher.self_update._resolve_uv_executable",
+            lambda: (str(tmp_path / "uv.exe"), [str(tmp_path / "uv.exe")]),
+        )
+        monkeypatch.setattr(
+            "data_hub_watcher.upgrade_worker.resolve_uv_tool_dirs",
+            lambda _uv: (operator_tool_dir, operator_tool_bin_dir),
+        )
 
         service_module._install_upgrade_worker(tmp_path)
 
@@ -315,19 +330,76 @@ class TestInstallUpgradeWorker:
 
         script_path = upgrade_worker_script_path(tmp_path)
         assert script_path.exists()
-        assert "Stop-Service" in script_path.read_text(encoding="utf-8")
+        rendered = script_path.read_text(encoding="utf-8")
+        assert "Stop-Service" in rendered
         # The rendered template MUST bake in sentinel paths under
         # the supplied config dir — anything else means the running
         # service (which writes sentinels to its own resolved
         # ``config_dir``) would write to a different directory than
         # the worker reads from, and every auto-update silently
         # no-ops with "no request sentinel".
-        rendered = script_path.read_text(encoding="utf-8")
         assert str(tmp_path / ".upgrade-request.json") in rendered
         assert str(tmp_path / ".upgrade-result.json") in rendered
+        # The operator's tool dirs must be baked in too — without the
+        # UV_TOOL_DIR override the SYSTEM-running worker installs to
+        # the wrong profile and the upgrade silently no-ops at the
+        # next service restart even though uv exited 0.
+        assert str(operator_tool_dir) in rendered
+        assert str(operator_tool_bin_dir) in rendered
+        assert "$env:UV_TOOL_DIR" in rendered
+        assert "$env:UV_TOOL_BIN_DIR" in rendered
         # Task installer was handed the same path.
         assert install_calls == [script_path]
 
+    def test_install_raises_when_uv_cannot_be_located(
+        self,
+        service_module: ModuleType,
+        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
+    ) -> None:
+        # A `service install` on a host without uv on PATH and without
+        # uv in any of the sys.prefix-derived candidates must fail
+        # loudly here — proceeding would render a template against
+        # default tool dirs, which under SYSTEM would silently install
+        # future upgrades into the wrong profile.
+        from data_hub_watcher.self_update import UvExecutableNotFoundError
+
+        monkeypatch.setattr(
+            "data_hub_watcher.self_update._resolve_uv_executable",
+            lambda: (None, ["/no/such/uv"]),
+        )
+
+        with pytest.raises(UvExecutableNotFoundError):
+            service_module._install_upgrade_worker(tmp_path)
+
+    def test_install_raises_when_uv_tool_dir_lookup_fails(
+        self,
+        service_module: ModuleType,
+        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
+    ) -> None:
+        # Same loud-failure rule for the second half of the lookup:
+        # if `uv tool dir` itself can't tell us where the operator's
+        # tool venvs live, we have no business rendering a worker
+        # template that pretends to know.
+        from data_hub_watcher.upgrade_worker import UvToolDirResolutionError
+
+        monkeypatch.setattr(
+            "data_hub_watcher.self_update._resolve_uv_executable",
+            lambda: (str(tmp_path / "uv.exe"), [str(tmp_path / "uv.exe")]),
+        )
+
+        def boom(_uv: str) -> tuple[Path, Path]:
+            raise UvToolDirResolutionError(["uv", "tool", "dir"], stderr="nope")
+
+        monkeypatch.setattr(
+            "data_hub_watcher.upgrade_worker.resolve_uv_tool_dirs",
+            boom,
+        )
+
+        with pytest.raises(UvToolDirResolutionError):
+            service_module._install_upgrade_worker(tmp_path)
+
     def test_uninstall_removes_task_and_script(
         self,
         service_module: ModuleType,
@@ -401,12 +473,22 @@ class TestRepairUpgradeWorkerOnStartup:
 
         assert install_calls == []
 
-    def test_repair_re_registers_when_task_missing(
+    def test_repair_re_registers_when_task_missing_and_script_present(
         self,
         service_module: ModuleType,
         monkeypatch: pytest.MonkeyPatch,
         tmp_path: Path,
     ) -> None:
+        # A pre-existing rendered script means a previous valid
+        # `service install` ran in operator context and captured the
+        # right uv tool dirs. Re-registering the task to point at
+        # that script is the safe self-repair — no need to re-render.
+        from data_hub_watcher.upgrade_worker import upgrade_worker_script_path
+
+        script_path = upgrade_worker_script_path(tmp_path)
+        script_path.parent.mkdir(parents=True, exist_ok=True)
+        script_path.write_text("# previously rendered worker", encoding="utf-8")
+
         sm = MagicMock(name="servicemanager")
         monkeypatch.setattr("data_hub_watcher.scheduled_task.task_exists", lambda: False)
         install_calls: list[Path] = []
@@ -417,16 +499,46 @@ class TestRepairUpgradeWorkerOnStartup:
 
         service_module._repair_upgrade_worker_if_missing(sm, tmp_path)
 
-        from data_hub_watcher.upgrade_worker import upgrade_worker_script_path
+        # Task is re-registered against the existing script.
+        assert install_calls == [script_path]
+        # CRITICAL: existing script content is NOT overwritten — the
+        # operator's UV_TOOL_DIR / UV_TOOL_BIN_DIR baked at install
+        # time must be preserved. Re-rendering under SYSTEM (which
+        # is what runs the repair) would resolve the wrong tool dirs
+        # and silently break future auto-updates.
+        assert script_path.read_text(encoding="utf-8") == "# previously rendered worker"
+
+    def test_repair_punts_when_task_and_script_both_missing(
+        self,
+        service_module: ModuleType,
+        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
+    ) -> None:
+        # Without a rendered script on disk we have no way to
+        # reconstruct the operator's UV_TOOL_DIR from a SYSTEM
+        # context. Re-rendering with whatever LocalSystem's
+        # `uv tool dir` would return bakes in the wrong profile and
+        # silently corrupts future auto-updates. The only safe move
+        # is to log a clear pointer at `service reinstall` and punt;
+        # the next auto-update tick will fail loudly with a usable
+        # error.
+        sm = MagicMock(name="servicemanager")
+        monkeypatch.setattr("data_hub_watcher.scheduled_task.task_exists", lambda: False)
+        install_calls: list[Path] = []
+        monkeypatch.setattr(
+            "data_hub_watcher.scheduled_task.install_upgrade_task",
+            lambda script_path: install_calls.append(script_path),
+        )
 
-        # The repair must render against the supplied *config_dir*,
-        # not ``DEFAULT_CONFIG_DIR`` — this is the regression guard
-        # for the "service runs as LocalSystem so ~ resolves to the
-        # SYSTEM profile" failure mode.
-        assert install_calls == [upgrade_worker_script_path(tmp_path)]
-        assert upgrade_worker_script_path(tmp_path).exists()
-        rendered = upgrade_worker_script_path(tmp_path).read_text(encoding="utf-8")
-        assert str(tmp_path / ".upgrade-request.json") in rendered
+        service_module._repair_upgrade_worker_if_missing(sm, tmp_path)
+
+        # No re-registration happened — punted to operator action.
+        assert install_calls == []
+        # …and the operator-facing message points at the recovery
+        # command, not a bare error code.
+        sm.LogWarningMsg.assert_called_once()
+        msg = sm.LogWarningMsg.call_args.args[0]
+        assert "service reinstall" in msg
 
     def test_repair_swallows_query_errors(
         self,
@@ -457,6 +569,13 @@ class TestRepairUpgradeWorkerOnStartup:
         tmp_path: Path,
     ) -> None:
         from data_hub_watcher.scheduled_task import ScheduledTaskError
+        from data_hub_watcher.upgrade_worker import upgrade_worker_script_path
+
+        # Need an existing script for the repair to attempt task
+        # registration; the failure is on `install_upgrade_task`.
+        script_path = upgrade_worker_script_path(tmp_path)
+        script_path.parent.mkdir(parents=True, exist_ok=True)
+        script_path.write_text("# previously rendered worker", encoding="utf-8")
 
         sm = MagicMock(name="servicemanager")
         monkeypatch.setattr("data_hub_watcher.scheduled_task.task_exists", lambda: False)

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/tests/test_updater.py

@@ -147,6 +147,15 @@ def _make_updater(
             idle_ticks_required=2,
             check_interval_ticks=3,
             min_run_age_seconds=10.0,
+            # Opt out of the production-default "fire /update-check
+            # on the very first tick" fast path so the existing
+            # ``for _ in range(N): on_tick(); then trigger on the
+            # (N+1)th tick`` cadence assertions throughout this file
+            # keep working unchanged. The on-start fast path has its
+            # own dedicated test class below — pinning the default-on
+            # behaviour separately keeps each test focused on the
+            # specific behaviour it's exercising.
+            check_on_start=False,
         ),
         upgrade_runner=upgrade_runner,
         upgrade_executor=upgrade_executor,
@@ -328,9 +337,16 @@ class TestUpdaterOnTick:
         h.request_restart.assert_not_called()
         h.reporter.queue_event.assert_not_called()
 
-    def test_first_ticks_are_no_op_until_check_interval(self, tmp_path: Path) -> None:
+    def test_first_ticks_are_no_op_until_check_interval_when_check_on_start_disabled(
+        self, tmp_path: Path
+    ) -> None:
+        # The default test helper opts out of the on-start fast path
+        # (see comment in ``_make_updater``) so this still pins the
+        # cadence-only behaviour: with ``check_interval_ticks=3``,
+        # ticks 1 and 2 are no-ops and tick 3 fires the API call.
+        # The on-start fast path's effect on this same shape is
+        # pinned in ``TestUpdaterChecksOnStart`` below.
         h = _make_updater(tmp_path)
-        # Below check_interval_ticks=3 we should not call the API at all.
         h.counters.last_files_uploaded = 0
         assert h.updater.on_tick() is None
         assert h.updater.on_tick() is None
@@ -345,6 +361,10 @@ class TestUpdaterOnTick:
                 idle_ticks_required=2,
                 check_interval_ticks=2,
                 min_run_age_seconds=1.0,
+                # See helper-level comment in ``_make_updater`` for
+                # why cadence-focused tests opt out of the on-start
+                # fast path.
+                check_on_start=False,
             ),
         )
         h.client.get_update_info.return_value = _info(latest="9.9.9")
@@ -386,6 +406,12 @@ class TestUpdaterOnTick:
                 idle_ticks_required=0,
                 check_interval_ticks=1,  # fire on every tick
                 min_run_age_seconds=0.0,
+                # ``check_interval_ticks=1`` already fires on every
+                # tick so the on-start fast path would be a no-op
+                # here anyway, but pin the opt-out so the test's
+                # "exactly 3 invocations → exactly 3 failures"
+                # arithmetic stays explicit.
+                check_on_start=False,
             ),
         )
         h.client.get_update_info.side_effect = ApiError("dead", status_code=502)
@@ -414,6 +440,10 @@ class TestUpdaterOnTick:
                 idle_ticks_required=0,
                 check_interval_ticks=1,
                 min_run_age_seconds=0.0,
+                # See sibling test for why we pin the opt-out even
+                # though check_interval_ticks=1 makes the on-start
+                # fast path effectively a no-op here.
+                check_on_start=False,
             ),
         )
         # 2 failures, then a success, then 2 more failures.
@@ -769,6 +799,219 @@ class TestUpdaterOnTick:
         assert all(e.details["install_method"] == "unknown" for e in emitted)
 
 
+class TestUpdaterChecksOnStart:
+    """Pin the production-default ``check_on_start=True`` behaviour.
+
+    Why this matters: lab PCs only run ``/update-check`` once an hour
+    by default, so a fresh ``service install`` / ``service reinstall``
+    / boot would otherwise wait up to 60 minutes before noticing a
+    pending release. That latency is fine in steady state but
+    disastrous during fix-forward iteration on the auto-update path
+    itself: the operator pushes a release, manually reinstalls the
+    watcher, then twiddles their thumbs for an hour to see if the
+    next auto-update tick works. Seeding ``_ticks_since_check`` to
+    ``check_interval_ticks`` at construction collapses that wait to
+    one heartbeat (~60 s) without disturbing the steady-state
+    cadence — and without bypassing the activity-window safety
+    gates, which still defer the actual upgrade dispatch as designed.
+    """
+
+    def _make_updater_with_on_start(
+        self,
+        tmp_path: Path,
+        *,
+        idle_ticks_required: int = 0,
+        check_interval_ticks: int = 60,
+        last_run_age_seconds: float | None = None,
+    ) -> _UpdaterHarness:
+        # ``check_on_start=True`` is the production default but the
+        # default helper opts out, so build directly here. Tests in
+        # this class want the production wiring exactly.
+        h = _make_updater(
+            tmp_path,
+            updater_cfg=UpdaterConfig(
+                idle_ticks_required=idle_ticks_required,
+                check_interval_ticks=check_interval_ticks,
+                min_run_age_seconds=10.0,
+                check_on_start=True,
+            ),
+        )
+        if last_run_age_seconds is not None:
+            from datetime import datetime, timedelta, timezone
+
+            # ``state_db.last_run_reported_at`` returns an ISO-8601
+            # string (it's a SQLite TEXT column), not a datetime —
+            # ``_last_run_age_seconds`` parses it via ``fromisoformat``.
+            past = datetime.now(timezone.utc) - timedelta(seconds=last_run_age_seconds)
+            h.state_db.last_run_reported_at.return_value = past.isoformat()
+        return h
+
+    def test_default_config_enables_check_on_start(self) -> None:
+        # Pin the production default explicitly so a future refactor
+        # that flips the default to False (and only updates the
+        # docstring) trips here rather than silently regressing the
+        # cold-start latency back to ~60 minutes.
+        cfg = UpdaterConfig()
+        assert cfg.check_on_start is True
+
+    def test_first_tick_fires_update_check_immediately(self, tmp_path: Path) -> None:
+        # The headline behaviour: with the production-default
+        # ``check_on_start=True`` and the production-default
+        # ``check_interval_ticks=60``, the very first tick after
+        # construction calls ``/update-check`` rather than waiting 59
+        # more ticks. Without this, an operator who just ran
+        # ``service reinstall`` to apply a fix-forward release would
+        # have to wait up to an hour to confirm whether the fix
+        # actually unblocked the auto-update path.
+        h = self._make_updater_with_on_start(tmp_path)
+        h.client.get_update_info.return_value = _info(latest="0.0.0+unknown")
+        h.counters.last_files_uploaded = 0
+
+        result = h.updater.on_tick()
+
+        assert result is not None, (
+            "first tick must call /update-check when check_on_start=True; "
+            "got None which means we waited for the cadence window"
+        )
+        h.client.get_update_info.assert_called_once()
+
+    def test_subsequent_ticks_resume_normal_cadence(self, tmp_path: Path) -> None:
+        # The on-start fast path is one-shot: tick 1 fires, then
+        # ticks 2..(check_interval_ticks) are no-ops, then the
+        # check_interval_ticks+1-th tick fires again. Otherwise we'd
+        # be calling /update-check every single heartbeat which
+        # would 60x the load on the watcher-update endpoint.
+        h = self._make_updater_with_on_start(tmp_path, check_interval_ticks=3)
+        h.client.get_update_info.return_value = _info(latest="0.0.0+unknown")
+        h.counters.last_files_uploaded = 0
+
+        # Tick 1 — on-start fast path fires.
+        assert h.updater.on_tick() is not None
+        assert h.client.get_update_info.call_count == 1
+
+        # Ticks 2 and 3 — within the cadence window after the reset.
+        assert h.updater.on_tick() is None
+        assert h.updater.on_tick() is None
+        assert h.client.get_update_info.call_count == 1
+
+        # Tick 4 — cadence window elapsed, fires again.
+        assert h.updater.on_tick() is not None
+        assert h.client.get_update_info.call_count == 2
+
+    def test_opt_out_preserves_pre_existing_cadence(self, tmp_path: Path) -> None:
+        # The opt-out path must produce exactly the historical
+        # behaviour: ticks 1 and 2 are no-ops with check_interval=3,
+        # tick 3 fires the API call. This is what every other test
+        # class in this file relies on, so a regression here would
+        # cascade into many false failures.
+        h = _make_updater(
+            tmp_path,
+            updater_cfg=UpdaterConfig(
+                idle_ticks_required=0,
+                check_interval_ticks=3,
+                min_run_age_seconds=10.0,
+                check_on_start=False,
+            ),
+        )
+        h.client.get_update_info.return_value = _info(latest="0.0.0+unknown")
+        h.counters.last_files_uploaded = 0
+
+        assert h.updater.on_tick() is None
+        assert h.updater.on_tick() is None
+        assert h.client.get_update_info.call_count == 0
+        assert h.updater.on_tick() is not None
+        assert h.client.get_update_info.call_count == 1
+
+    def test_on_start_check_still_respects_idle_gate(self, tmp_path: Path) -> None:
+        # Critical safety pin: the on-start fast path short-circuits
+        # the *cadence* window, NOT the activity-window safety gate.
+        # If the operator restarts the service while uploads are
+        # actively flowing, the first tick should DO the API call
+        # (we want the operator to see "yes, an upgrade is pending"
+        # in the logs / dashboard immediately) but DEFER the actual
+        # upgrade dispatch until the upload activity quiets down —
+        # exactly as the steady-state cadence would. Without this
+        # pin a future refactor could conflate the two and start
+        # interrupting in-flight uploads on every restart.
+        h = self._make_updater_with_on_start(
+            tmp_path,
+            idle_ticks_required=5,
+            check_interval_ticks=60,
+        )
+        h.client.get_update_info.return_value = _info(latest="9.9.9")
+        # Simulate active upload activity: the heartbeat reports
+        # files uploaded on this tick.
+        h.counters.last_files_uploaded = 3
+
+        result = h.updater.on_tick()
+
+        # API was called (the fast path's job)…
+        h.client.get_update_info.assert_called_once()
+        # …but the dispatch was deferred (the safety gate's job).
+        assert result is not None
+        assert result.attempted is False
+        assert "idle ticks" in result.reason
+        h.request_restart.assert_not_called()
+
+    def test_on_start_check_still_respects_recent_run_gate(self, tmp_path: Path) -> None:
+        # Same shape as the idle-gate pin above, but for the
+        # ``last_run_age_seconds`` half of the activity-window
+        # check. A run reported 5 seconds before service restart
+        # (operator restarted mid-experiment to apply a fix) must
+        # NOT trigger an immediate upgrade just because the on-start
+        # fast path enabled the API call.
+        h = self._make_updater_with_on_start(
+            tmp_path,
+            idle_ticks_required=0,  # Idle gate disabled.
+            last_run_age_seconds=5.0,  # Recent run, gate active.
+        )
+        h.client.get_update_info.return_value = _info(latest="9.9.9")
+        h.counters.last_files_uploaded = 0
+
+        result = h.updater.on_tick()
+
+        h.client.get_update_info.assert_called_once()
+        assert result is not None
+        assert result.attempted is False
+        assert "recent run" in result.reason
+        h.request_restart.assert_not_called()
+
+    def test_on_start_check_dispatches_when_safety_gates_pass(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # The flip side of the safety pins above: when nothing's
+        # happening (clean restart on an idle host with no recent
+        # runs and no pending uploads — the common case), the
+        # on-start fast path SHOULD result in an immediate dispatch.
+        # This is the behaviour the operator-facing testing-iteration
+        # win actually depends on.
+        runner = MagicMock(return_value=_success_completed_process())
+        h = _make_updater(
+            tmp_path,
+            updater_cfg=UpdaterConfig(
+                idle_ticks_required=0,
+                check_interval_ticks=60,
+                min_run_age_seconds=10.0,
+                check_on_start=True,
+            ),
+            upgrade_runner=runner,
+        )
+        h.client.get_update_info.return_value = _info(latest="9.9.9")
+        h.state_db.last_run_reported_at.return_value = None
+        h.counters.last_files_uploaded = 0
+
+        monkeypatch.setattr(
+            "data_hub_watcher.updater.detect_install_method",
+            lambda: InstallMethod.UV_TOOL,
+        )
+
+        result = h.updater.on_tick()
+
+        h.request_restart.assert_called_once()
+        assert result is not None
+        assert result.attempted is True
+
+
 class TestUpdaterAsyncDispatch:
     """The upgrade subprocess runs off the heartbeat thread.
 

{data_hub_watcher-0.2.2 → data_hub_watcher-0.2.4}/tests/test_upgrade_worker.py

@@ -10,6 +10,7 @@ that breaks the contract surfaces here rather than as a stuck
 
 from __future__ import annotations
 import json
+import subprocess
 from pathlib import Path
 
 import pytest
@@ -259,6 +260,8 @@ class TestRenderWorkerScript:
             request_path=tmp_path / ".upgrade-request.json",
             result_path=tmp_path / ".upgrade-result.json",
             log_path=tmp_path / "upgrade-worker.log",
+            tool_dir=Path(r"C:\Users\op\AppData\Roaming\uv\tools"),
+            tool_bin_dir=Path(r"C:\Users\op\.local\bin"),
             generated_at="2026-05-04T22:30:00+00:00",
         )
 
@@ -313,7 +316,12 @@ class TestRenderWorkerScript:
         assert "Start-Service" in finally_block
 
     def test_write_worker_script_drops_file_at_expected_path(self, tmp_path: Path) -> None:
-        path = write_worker_script(tmp_path, service_name="DataHubWatcher")
+        path = write_worker_script(
+            tmp_path,
+            service_name="DataHubWatcher",
+            tool_dir=Path(r"C:\Users\op\AppData\Roaming\uv\tools"),
+            tool_bin_dir=Path(r"C:\Users\op\.local\bin"),
+        )
         assert path == upgrade_worker_script_path(tmp_path)
         assert path.exists()
         assert path.name == UPGRADE_WORKER_SCRIPT_FILENAME
@@ -370,6 +378,90 @@ class TestRenderWorkerScript:
         # uv emits on the host.
         assert "`r?`n" in script or "\\r?\\n" in script
 
+    def test_uv_tool_dir_overrides_are_baked_in(self, tmp_path: Path) -> None:
+        # Regression guard for the silent "uv installed into SYSTEM
+        # profile" failure mode: the worker runs as LocalSystem via
+        # the scheduled task, and uv resolves UV_TOOL_DIR /
+        # UV_TOOL_BIN_DIR from $env:USERPROFILE which under SYSTEM
+        # is C:\Windows\System32\config\systemprofile\.local\... —
+        # NOT where the running watcher service was originally
+        # installed from. The rendered worker MUST set both env
+        # vars to the operator-context paths captured at install
+        # time so uv reinstalls in place at the operator's tool
+        # dir; otherwise the upgrade succeeds (uv exits 0) but
+        # produces a SECOND copy of the package that the running
+        # service never loads, and the marker comparison fails
+        # with "expected X, running Y" on the next restart.
+        script = render_worker_script(
+            service_name="DataHubWatcher",
+            request_path=tmp_path / ".upgrade-request.json",
+            result_path=tmp_path / ".upgrade-result.json",
+            log_path=tmp_path / "upgrade-worker.log",
+            tool_dir=Path(r"C:\Users\op\AppData\Roaming\uv\tools"),
+            tool_bin_dir=Path(r"C:\Users\op\.local\bin"),
+            generated_at="2026-05-04T22:30:00+00:00",
+        )
+
+        # The literal paths are baked in as PowerShell variables…
+        assert r'$ToolDir      = "C:\Users\op\AppData\Roaming\uv\tools"' in script
+        assert r'$ToolBinDir   = "C:\Users\op\.local\bin"' in script
+        # …and assigned to the env vars uv actually consults BEFORE
+        # the uv invocation. Order matters: setting them after
+        # `Start-Process -FilePath $UvExe` would have no effect on
+        # the subprocess.
+        env_idx = script.find("$env:UV_TOOL_DIR")
+        uv_invoke_idx = script.find("Start-Process -FilePath $UvExe")
+        assert env_idx != -1, "worker must set $env:UV_TOOL_DIR"
+        assert uv_invoke_idx != -1, "worker must invoke uv via Start-Process"
+        assert env_idx < uv_invoke_idx, (
+            "$env:UV_TOOL_DIR must be set BEFORE uv is invoked, "
+            "otherwise the override has no effect on the subprocess"
+        )
+        # Both env vars present.
+        assert "$env:UV_TOOL_DIR     = $ToolDir" in script
+        assert "$env:UV_TOOL_BIN_DIR = $ToolBinDir" in script
+
+    def test_result_sentinel_is_written_without_utf8_bom(self, tmp_path: Path) -> None:
+        # Regression guard for the secondary symptom of the silent
+        # auto-update failure: PowerShell 5.1's `Set-Content -Encoding
+        # UTF8` writes a UTF-8 BOM, and Python's `json.loads(
+        # path.read_text(encoding="utf-8"))` raises JSONDecodeError on
+        # the leading U+FEFF. `read_upgrade_result` then swallows the
+        # error and returns None, causing the post-restart inspection
+        # to flag `worker_result_missing=True` even though the file
+        # was written successfully — the operator sees no actual
+        # error context in the failure event.
+        #
+        # The fix uses [System.IO.File]::WriteAllText with an explicit
+        # UTF8Encoding($false) so the BOM is omitted on every supported
+        # PowerShell version. Pin the encoder choice here.
+        script = render_worker_script(
+            service_name="DataHubWatcher",
+            request_path=tmp_path / ".upgrade-request.json",
+            result_path=tmp_path / ".upgrade-result.json",
+            log_path=tmp_path / "upgrade-worker.log",
+            tool_dir=tmp_path / "tools",
+            tool_bin_dir=tmp_path / "bin",
+            generated_at="2026-05-04T22:30:00+00:00",
+        )
+        # The .NET UTF8Encoding constructor takes a bool encoderShouldEmitUTF8Identifier
+        # — `$false` means "no BOM". We pin both the type and the
+        # `$false` argument so a future refactor can't accidentally
+        # flip it back to BOM-emitting.
+        assert "[System.IO.File]::WriteAllText" in script
+        assert "[System.Text.UTF8Encoding]::new($false)" in script
+        # The original BOM-emitting `Set-Content` invocation must
+        # not appear as an actual command anywhere in the rendered
+        # template. Search line-by-line, ignoring lines that start
+        # with `#` (PowerShell comments) so the regression-context
+        # commentary describing the *old* behaviour doesn't trip
+        # the assertion.
+        for line in script.splitlines():
+            stripped = line.lstrip()
+            if stripped.startswith("#"):
+                continue
+            assert "Set-Content -LiteralPath $tmp -Encoding UTF8" not in stripped
+
 
 # ---------------------------------------------------------------------------
 # Filename constants
@@ -384,3 +476,99 @@ def test_sentinel_filenames_are_dotfiles_under_config_dir(tmp_path: Path) -> Non
     assert upgrade_result_path(tmp_path).name == UPGRADE_RESULT_FILENAME
     assert UPGRADE_REQUEST_FILENAME.startswith(".")
     assert UPGRADE_RESULT_FILENAME.startswith(".")
+
+
+# ---------------------------------------------------------------------------
+# resolve_uv_tool_dirs
+# ---------------------------------------------------------------------------
+
+
+class TestResolveUvToolDirs:
+    """Capture the operator's uv tool directories at install time.
+
+    Required because the worker later runs as LocalSystem and uv would
+    otherwise resolve UV_TOOL_DIR / UV_TOOL_BIN_DIR against the SYSTEM
+    profile rather than the operator's profile — silently installing
+    upgrades into the wrong location.
+    """
+
+    def test_returns_paths_from_uv_tool_dir_invocations(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from data_hub_watcher import upgrade_worker as worker_mod
+
+        invocations: list[list[str]] = []
+
+        def fake_run(argv: list[str], **_kw: object) -> subprocess.CompletedProcess[str]:
+            invocations.append(argv)
+            if "--bin" in argv:
+                stdout = r"C:\Users\op\.local\bin"
+            else:
+                stdout = r"C:\Users\op\AppData\Roaming\uv\tools"
+            return subprocess.CompletedProcess(argv, returncode=0, stdout=stdout, stderr="")
+
+        monkeypatch.setattr(worker_mod.subprocess, "run", fake_run)
+
+        tool_dir, tool_bin_dir = worker_mod.resolve_uv_tool_dirs(r"C:\Users\op\.local\bin\uv.exe")
+
+        assert tool_dir == Path(r"C:\Users\op\AppData\Roaming\uv\tools")
+        assert tool_bin_dir == Path(r"C:\Users\op\.local\bin")
+        # Both invocations must use the supplied uv path (not e.g. a
+        # PATH-resolved fallback) so the helper reflects the same uv
+        # the worker will eventually drive.
+        assert invocations[0] == [r"C:\Users\op\.local\bin\uv.exe", "tool", "dir"]
+        assert invocations[1] == [r"C:\Users\op\.local\bin\uv.exe", "tool", "dir", "--bin"]
+
+    def test_nonzero_exit_raises_with_stderr_attached(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from data_hub_watcher import upgrade_worker as worker_mod
+
+        def fake_run(argv: list[str], **_kw: object) -> subprocess.CompletedProcess[str]:
+            return subprocess.CompletedProcess(
+                argv, returncode=2, stdout="", stderr="uv: command does not exist"
+            )
+
+        monkeypatch.setattr(worker_mod.subprocess, "run", fake_run)
+
+        with pytest.raises(worker_mod.UvToolDirResolutionError) as excinfo:
+            worker_mod.resolve_uv_tool_dirs("uv")
+
+        # Operator-facing message must include the failing argv and
+        # uv's stderr — diagnostically those are the two pieces an
+        # operator needs to recover from a stuck install.
+        msg = str(excinfo.value)
+        assert "uv tool dir" in msg
+        assert "command does not exist" in msg
+
+    def test_empty_stdout_raises(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        # An exit-0 with empty stdout would otherwise silently bake
+        # `Path("")` into the worker template, which uv interprets
+        # as "use the default" — i.e. the very SYSTEM-profile path
+        # we're trying to override. Treat it as a hard failure.
+        from data_hub_watcher import upgrade_worker as worker_mod
+
+        def fake_run(argv: list[str], **_kw: object) -> subprocess.CompletedProcess[str]:
+            return subprocess.CompletedProcess(argv, returncode=0, stdout="\n", stderr="")
+
+        monkeypatch.setattr(worker_mod.subprocess, "run", fake_run)
+
+        with pytest.raises(worker_mod.UvToolDirResolutionError):
+            worker_mod.resolve_uv_tool_dirs("uv")
+
+    def test_oserror_raises_uv_tool_dir_resolution_error(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # uv.exe missing from disk surfaces as FileNotFoundError from
+        # subprocess.run; the helper must convert that to its typed
+        # error so callers don't have to know about subprocess
+        # internals.
+        from data_hub_watcher import upgrade_worker as worker_mod
+
+        def boom(argv: list[str], **_kw: object) -> subprocess.CompletedProcess[str]:
+            raise FileNotFoundError("uv.exe not found")
+
+        monkeypatch.setattr(worker_mod.subprocess, "run", boom)
+
+        with pytest.raises(worker_mod.UvToolDirResolutionError):
+            worker_mod.resolve_uv_tool_dirs("uv")