driverclient 0.2.3__tar.gz → 0.2.5__tar.gz

{driverclient-0.2.3 → driverclient-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.3
+Version: 0.2.5
 Summary: Driver Server client with an embeddable connector for config injection at runtime.
 Project-URL: Homepage, https://example.com/driverclient
 Author-email: Raja Sanaullah <sanaullah@99technologies.com>

{driverclient-0.2.3 → driverclient-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "driverclient"
-version = "0.2.3"
+version = "0.2.5"
 description = "Driver Server client with an embeddable connector for config injection at runtime."
 readme = "README.md"
 requires-python = ">=3.10"

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/__init__.py

@@ -25,7 +25,7 @@ from driverclient.main import run as _run
 
 __all__ = ["DriverClient", "ClientEvent"]
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 
 class DriverClient:

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/config.py

@@ -54,6 +54,11 @@ DEFAULTS: dict = {
     # ── Automate flags ────────────────────────────────────────────────────
     "automate_wu_fallback": True,
     "automate_re_resolve":  False,
+    # Extra same-boot scan→resolve→install passes after the first install, to
+    # pick up devices exposed only once a parent driver binds (chained deps).
+    # 0 disables the loop (single install pass). Stops early when a pass finds
+    # no new repo drivers or installs nothing.
+    "automate_rescan_passes": 3,
     "force_resolve":        False,
 
     # ── HTTP timeouts (seconds) ───────────────────────────────────────────

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/main.py

@@ -19,7 +19,13 @@ from pathlib import Path
 from driverclient import events
 from driverclient.config import get
 from driverclient.ops.automate import run_automation
-from driverclient.ops.capture import capture_all, capture_missing, wu_full, wu_update
+from driverclient.ops.capture import (
+    capture_all,
+    capture_delta,
+    capture_missing,
+    wu_full,
+    wu_update,
+)
 from driverclient.ops.install import resolve_and_install
 from driverclient.ops.resolve import resolve
 from driverclient.ops.scan import scan
@@ -30,6 +36,7 @@ _OPERATIONS: dict[str, callable] = {
     "resolve-and-install": resolve_and_install,
     "capture-all":         capture_all,
     "capture-missing":     capture_missing,
+    "capture-delta":       capture_delta,
     "wu-update":           wu_update,
     "wu-full":             wu_full,
     "automate":            run_automation,

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/ops/automate.py

@@ -18,7 +18,7 @@ from datetime import datetime, timezone
 from driverclient import events
 from driverclient.config import get
 from driverclient.ops.capture import CaptureResult, classify_missing, wu_update
-from driverclient.ops.install import InstallResult, resolve_and_install
+from driverclient.ops.install import DriverResult, InstallResult, resolve_and_install
 from driverclient.ops.resolve import ResolveResult, resolve
 from driverclient.ops.scan import ScanResult, scan
 
@@ -34,8 +34,13 @@ class AutomateResult:
 
     @property
     def reboot_required(self) -> bool:
-        """True if this pass installed a driver that needs a reboot to take effect."""
-        return bool(self.install and self.install.reboot_required)
+        """True if this pass needs a reboot for drivers to take effect — either a
+        repo install returned a reboot code (3010), or Windows Update installed
+        drivers that left a pending-reboot flag. Either source must reboot so the
+        drivers bind before the end-of-pass re-scan + delta harvest."""
+        install_reboot = bool(self.install and self.install.reboot_required)
+        wu_reboot      = bool(self.wu and self.wu.reboot_required)
+        return install_reboot or wu_reboot
 
     @property
     def made_progress(self) -> bool:
@@ -71,13 +76,9 @@ def run_automation() -> AutomateResult:
         _summary(result)
         return result
 
-    # ── Step 3: Install from repo ─────────────────────────────────────────────
+    # ── Step 3: Install from repo (bounded same-boot re-scan loop) ────────────
     _step(3, f"Install  ({len(result.resolve.drivers)} driver(s) from repo)")
-    if result.resolve.has_drivers:
-        result.install = resolve_and_install(force=False)
-    else:
-        events.progress("pipeline", "[automate] No drivers available in repo — skipping install")
-        result.install = InstallResult(trace_id=result.resolve.trace_id)
+    result.install = _install_with_rescan(result, cfg)
 
     # ── Step 4: Windows Update fallback ──────────────────────────────────────
     wu_enabled = cfg.get("automate_wu_fallback", True)
@@ -112,6 +113,77 @@ def _step(n: int, label: str) -> None:
                     step=n, label=label)
 
 
+def _bid(driver: dict) -> str:
+    """Stable identity for a repo driver entry (matches install's dedup key)."""
+    return driver.get("binding_id") or driver.get("package_id", "")
+
+
+def _merge_install(combined: InstallResult, inst: InstallResult) -> None:
+    """Fold one pass's results into the running total, deduped by binding_id so a
+    same-boot re-attempt of an already-recorded driver is not double-counted; a
+    later success upgrades an earlier failure."""
+    by_id: dict[str, DriverResult] = {}
+    for r in (combined.installed_ok + combined.install_failed
+              + inst.installed_ok + inst.install_failed):
+        prev = by_id.get(r.binding_id)
+        if prev is None or (r.success and not prev.success):
+            by_id[r.binding_id] = r
+    combined.installed_ok   = [r for r in by_id.values() if r.success]
+    combined.install_failed = [r for r in by_id.values() if not r.success]
+
+
+def _install_with_rescan(result: AutomateResult, cfg: dict) -> InstallResult:
+    """Install repo drivers, then re-scan → re-resolve → install again in the
+    SAME boot to pick up devices that only appear once a parent's driver is
+    bound (chained dependencies), rather than making them wait for a reboot.
+
+    Bounded by automate_rescan_passes (extra passes after the first install) and
+    stops early as soon as a pass surfaces no genuinely-new repo drivers or
+    installs nothing (a failed install exposes no children). result.resolve is
+    updated to the converged view so the WU step and summary see the true
+    still-missing set.
+    """
+    combined      = InstallResult(trace_id=result.resolve.trace_id)
+    max_extra     = max(0, int(cfg.get("automate_rescan_passes", 3)))
+    attempted:      set[str] = set()
+    resolve_result = result.resolve
+
+    for pass_idx in range(max_extra + 1):
+        if not resolve_result.has_drivers:
+            events.progress(
+                "pipeline",
+                "[automate] No drivers available in repo — skipping install"
+                if pass_idx == 0 else
+                f"[automate] Re-scan {pass_idx}/{max_extra}: repo has nothing new — stable")
+            break
+
+        new_ids = [_bid(d) for d in resolve_result.drivers if _bid(d) not in attempted]
+        if pass_idx > 0 and not new_ids:
+            events.progress("pipeline",
+                            f"[automate] Re-scan {pass_idx}/{max_extra}: "
+                            f"no new repo drivers — stable")
+            break
+
+        attempted.update(_bid(d) for d in resolve_result.drivers)
+        inst = resolve_and_install(force=False)
+        _merge_install(combined, inst)
+
+        if inst.ok_count == 0:
+            events.progress("pipeline",
+                            "[automate] No successful installs this pass — "
+                            "no new devices to surface, stable")
+            break
+        if pass_idx == max_extra:
+            break
+
+        _step(3, f"Re-scan (same boot) {pass_idx + 1}/{max_extra} — "
+                 f"checking for newly-exposed devices")
+        resolve_result = resolve(force=True)
+        result.resolve = resolve_result
+
+    return combined
+
+
 def _summary(r: AutomateResult) -> None:
     inst   = r.install or InstallResult()
     wu     = r.wu      or CaptureResult()
@@ -134,8 +206,10 @@ def _summary(r: AutomateResult) -> None:
                     total_hwids=r.resolve.total_hwids)
     events.done("done", f"  Installed: {inst.ok_count} ok  {inst.fail_count} failed",
                 installed_ok=inst.ok_count, installed_failed=inst.fail_count)
-    if inst.reboot_required:
-        events.done("done", "  Reboot   : REQUIRED (a driver needs a reboot to take effect)",
+    if r.reboot_required:
+        source = "repo install" if inst.reboot_required else "Windows Update"
+        events.done("done",
+                    f"  Reboot   : REQUIRED ({source} — a driver needs a reboot to take effect)",
                     reboot_required=True)
     if buckets:
         inbox = len(buckets["inbox"])

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/ops/capture.py

@@ -40,7 +40,7 @@ from driverclient.config import get
 from driverclient.core.hardware import compute_fingerprint, get_model_profile
 from driverclient.core.http import BadRequestError, http_post_retry, http_upload_package, pack_driver_archive
 from driverclient.ops.resolve import ResolveResult, resolve
-from driverclient.ops.scan import Device, ScanResult, _looks_like_hwid, scan
+from driverclient.ops.scan import Device, ScanResult, scan
 
 
 def _post_wu_session(cfg: dict, wu_start, hwids_tried: list, captured: int) -> None:
@@ -104,16 +104,18 @@ _PNPUTIL_KEYS: dict[str, str] = {
 
 @dataclass
 class CaptureResult:
-    submitted:     int  = 0
-    skipped:       int  = 0
-    failed:        int  = 0
-    still_missing: int  = 0
-    wu_triggered:  bool = False
+    submitted:       int  = 0
+    skipped:         int  = 0
+    failed:          int  = 0
+    still_missing:   int  = 0
+    wu_triggered:    bool = False
+    reboot_required: bool = False   # WU installed drivers that left a pending-reboot flag
 
     def merge(self, other: "CaptureResult") -> None:
-        self.submitted += other.submitted
-        self.skipped   += other.skipped
-        self.failed    += other.failed
+        self.submitted      += other.submitted
+        self.skipped        += other.skipped
+        self.failed         += other.failed
+        self.reboot_required = self.reboot_required or other.reboot_required
 
 
 # ══ Public operations ══════════════════════════════════════════════════════════
@@ -188,6 +190,77 @@ def capture_missing(force: bool = False) -> CaptureResult:
     return result
 
 
+def capture_delta(force: bool = False) -> CaptureResult:
+    """
+    Resolve-driven DELTA harvest — the correct harvest for the two-speed
+    lifecycle (golden rule 2: upload a package iff the repo lacks it OR has an
+    older version; never re-upload an identical one).
+
+    The delta comes straight from the /resolve response, not a fresh
+    enumeration:
+      not_found — repo has no package for the HWID (new hardware to seed)
+      stale     — repo has an OLDER version than the one installed locally
+                  (server-computed from installed_versions)
+
+    For each delta HWID that has an OEM driver installed locally, export that
+    package and submit it. Genuinely-driverless HWIDs (no local driver) are not
+    capturable here — they are Windows Update's job.
+
+    FAST PATH: when the delta is empty (repo already complete for this machine)
+    it short-circuits with no scan/enumerate/export — nothing to harvest.
+    """
+    cfg         = get()
+    scan_result = scan(force=force)
+    res_result  = resolve(force=force)
+
+    if not res_result.has_delta:
+        events.done("capture",
+                    "[capture-delta] Repo complete for this machine — empty delta, "
+                    "nothing to harvest",
+                    total=0, not_found=0, stale=0)
+        return CaptureResult()
+
+    # Bucket the not_found side for a truthful log; stale HWIDs always have a
+    # local OEM package (that is how the server knew a newer version exists).
+    buckets = classify_missing(res_result.not_found, scan_result)
+    genuinely_missing = len(buckets["driverless"]) + len(buckets["unknown"])
+    events.progress(
+        "capture",
+        f"[capture-delta] delta = {len(res_result.not_found)} not-in-repo + "
+        f"{len(res_result.stale)} stale  |  "
+        f"{len(buckets['inbox'])} inbox (n/a)  "
+        f"{len(buckets['oem_local'])} local-OEM (not_found)  "
+        f"{genuinely_missing} genuinely missing (WU)",
+        not_found=len(res_result.not_found), stale=len(res_result.stale),
+        inbox=len(buckets["inbox"]), oem_local=len(buckets["oem_local"]),
+        genuinely_missing=genuinely_missing)
+
+    delta_hwids = set(res_result.not_found) | set(res_result.stale)
+    to_export = _find_installed_packages_for_hwids(delta_hwids, scan_result, cfg)
+
+    if not to_export:
+        events.done("capture",
+                    f"[capture-delta] Nothing capturable — {len(buckets['inbox'])} inbox, "
+                    f"{genuinely_missing} genuinely missing (WU candidates)",
+                    total=0, still_missing=genuinely_missing)
+        return CaptureResult(still_missing=genuinely_missing)
+
+    events.progress("capture",
+                    f"[capture-delta] Exporting {len(to_export)} locally-installed "
+                    f"OEM package(s) backing the delta…",
+                    total=len(to_export))
+    result = _export_and_submit(to_export, cfg)
+    result.still_missing = genuinely_missing
+    events.done("capture",
+                f"[capture-delta] Done — {result.submitted} submitted  "
+                f"{result.skipped} skipped  {result.failed} failed  "
+                f"({genuinely_missing} genuinely missing)",
+                total=len(to_export), submitted=result.submitted,
+                skipped=result.skipped, failed=result.failed,
+                still_missing=result.still_missing)
+    return result
+
+
 def wu_update(force: bool = False) -> CaptureResult:
     """
     Scan → resolve → filter not-found HWIDs to those with no local driver
@@ -230,11 +303,14 @@ def wu_update(force: bool = False) -> CaptureResult:
     total    = _poll_and_submit_incremental(wu_start, cfg)
     total.wu_triggered  = True
     total.still_missing = max(0, len(wu_hwids) - total.submitted)
+    total.reboot_required = _wu_reboot_pending()
     _post_wu_session(cfg, wu_start, list(wu_hwids), total.submitted)
+    reboot_tag = "  — reboot required" if total.reboot_required else ""
     events.done("windows_update",
                 f"[wu-update] Done — {total.submitted} captured  "
-                f"{total.still_missing} still missing",
-                submitted=total.submitted, still_missing=total.still_missing)
+                f"{total.still_missing} still missing{reboot_tag}",
+                submitted=total.submitted, still_missing=total.still_missing,
+                reboot_required=total.reboot_required)
     return total
 
 
@@ -396,87 +472,82 @@ def _norm_hwid(hwid: str) -> str:
     return up[:idx] if idx != -1 else up
 
 
+def _published_names_for_hwids(
+    delta_hwids: set[str],
+    scan_result: ScanResult,
+) -> set[str]:
+    """Published INF names (oemNN.inf) of the locally-installed OEM packages that
+    back the given delta HWIDs.
+
+    Reads the driver_name the scan already captured from
+    `pnputil /enum-devices /ids` — no second pnputil enumeration. The old path
+    parsed `pnputil /enum-devices /drivers` for Hardware IDs it does not print,
+    so the mapping came back empty and nothing was ever harvested (broken link
+    B). Only OEM packages are eligible: inbox (Windows-shipped) drivers are not
+    redistributable and the repo never needs them.
+    """
+    targets = {_norm_hwid(h) for h in delta_hwids}
+    names: set[str] = set()
+    for dev in scan_result.devices:
+        if not dev.has_driver or dev.is_inbox or not dev.driver_name:
+            continue
+        if any(_norm_hwid(h) in targets for h in dev.hwids):
+            names.add(dev.driver_name)
+    return names
+
+
 def _find_installed_packages_for_hwids(
     not_found_hwids: set[str],
     scan_result: ScanResult,
     cfg: dict,
 ) -> list[dict]:
-    # A missing HWID is capturable when it belongs to a scanned device that
-    # already has a driver bound. Match on the device's own HWID list (which
-    # includes every variant) using normalized HWIDs, rather than exact
-    # membership in installed_versions whose keys are the full &REV_xx form.
-    not_found_norm = {_norm_hwid(h) for h in not_found_hwids}
-    locally_installed: set[str] = set()
-    for dev in scan_result.devices:
-        if not dev.has_driver:
-            continue
-        if any(_norm_hwid(h) in not_found_norm for h in dev.hwids):
-            locally_installed.update(h.upper() for h in dev.hwids)
-    if not locally_installed:
+    """Full package records (for export) of the OEM packages backing the given
+    HWIDs. The HWID→published mapping comes from the scan's driver_name (see
+    _published_names_for_hwids); this only enriches each name with the metadata
+    /enum-drivers carries (provider, class, version) needed to submit."""
+    names = _published_names_for_hwids(not_found_hwids, scan_result)
+    if not names:
         return []
-
-    hwid_to_published = _map_hwids_to_published(locally_installed, cfg)
     all_packages = {
         p["published_name"]: p
         for p in _enumerate_all_packages(cfg)
         if p.get("published_name")
     }
-    return [
-        all_packages[pub]
-        for pub in set(hwid_to_published.values())
-        if pub in all_packages
-    ]
+    return [all_packages[n] for n in sorted(names) if n in all_packages]
 
 
-def _map_hwids_to_published(hwids: set[str], cfg: dict) -> dict[str, str]:
-    mapping: dict[str, str] = {}
-    try:
-        r = subprocess.run(
-            ["pnputil", "/enum-devices", "/drivers"],
-            capture_output=True, text=True,
-            timeout=cfg.get("timeout_short", 30),
-        )
-    except Exception:
-        return mapping
-
-    state: dict = {"published": "", "hwids": [], "in_hwids": False}
-    for line in r.stdout.splitlines():
-        stripped = line.strip()
-        if not stripped:
-            _commit_hwid_block(state, hwids, mapping)
-        else:
-            _parse_hwid_line(line, stripped, state)
-
-    return mapping
-
+# ══ Windows Update ═════════════════════════════════════════════════════════════
 
-def _commit_hwid_block(state: dict, hwids: set[str], mapping: dict) -> None:
-    """Flush accumulated HWIDs for the current device into mapping."""
-    if state["published"]:
-        targets = {_norm_hwid(h) for h in hwids}
-        for h in state["hwids"]:
-            if _norm_hwid(h) in targets:
-                mapping[h] = state["published"]
-    state["published"] = ""
-    state["hwids"]     = []
-    state["in_hwids"]  = False
+def _wu_reboot_pending() -> bool:
+    """Best-effort check for a Windows 'reboot pending' state after WU installs.
 
+    WU-installed drivers frequently need a reboot to bind, but that never
+    surfaces in an installer exit code — it is only reflected in these
+    well-known registry flags. Checked once after the WU poll so automate can OR
+    it into reboot_required and let the orchestrator (SA) drive the single
+    end-of-pass reboot → re-scan → harvest. Windows clears these keys once the
+    pending servicing completes after the reboot, so it self-terminates.
 
-def _parse_hwid_line(line: str, stripped: str, state: dict) -> None:
-    """Update parser state from one non-empty pnputil /enum-devices line."""
-    low = stripped.lower()
-    if low.startswith("published name") and ":" in stripped:
-        state["published"] = stripped.split(":", 1)[1].strip()
-        state["in_hwids"]  = False
-    elif low.startswith(("hardware ids", "compatible ids")):
-        state["in_hwids"] = True
-    elif state["in_hwids"] and _looks_like_hwid(stripped):
-        state["hwids"].append(stripped.upper())
-    elif ":" in stripped and not line.startswith(" "):
-        state["in_hwids"] = False
+    Only consulted on runs that actually triggered WU, so an unrelated stale
+    flag cannot spuriously reboot a machine that did no WU work.
+    """
+    try:
+        import winreg
+    except Exception:
+        return False
 
+    checks = (
+        r"SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\RebootRequired",
+        r"SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending",
+    )
+    for subkey in checks:
+        try:
+            with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, subkey):
+                return True
+        except OSError:
+            continue
+    return False
 
-# ══ Windows Update ═════════════════════════════════════════════════════════════
 
 def _trigger_wu() -> bool:
     for cmd in (["usoclient", "StartScan"], ["wuauclt", "/detectnow"]):

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/ops/install.py

@@ -43,6 +43,21 @@ _REBOOT_CODES: frozenset[int] = frozenset({3010, 1641})
 #         updating (driver already present / "Already exists in the system").
 _SUCCESS_NO_CHANGE_CODES: frozenset[int] = frozenset({259})
 
+# pnputil's exit code is unreliable: it can be nonzero on a logical success
+# (notably "already exists in the system") and its numeric meaning varies across
+# Windows builds. When stdout/stderr carry one of these markers we trust the
+# text over the exit code. Matched case-insensitively.
+_PNPUTIL_REBOOT_MARKERS: tuple[str, ...] = (
+    "reboot required",
+    "restart required",
+)
+_PNPUTIL_SUCCESS_MARKERS: tuple[str, ...] = (
+    "added successfully",           # "Driver package added successfully."
+    "already exists in the system",  # package already present — success, not a failure
+    "installed on matching devices",  # /install applied to a device
+    "successfully installed",
+)
+
 
 @dataclass
 class DriverResult:
@@ -230,20 +245,37 @@ def _level_label(level: int) -> str:
 
 # ── Driver installation ─────────────────────────────────────────────────────────
 
-def _classify(returncode: int, err_text: str = "") -> tuple[bool, str, bool]:
+def _classify(returncode: int, stdout: str = "", stderr: str = "") -> tuple[bool, str, bool]:
     """
-    Map an installer exit code to (success, error, reboot_required).
-
-    0                  -> success, no reboot
-    259                -> success, no reboot (package already present / no change)
-    3010 / 1641        -> success, reboot required (NOT a failure)
-    anything else      -> failure, carry err_text
+    Map a pnputil/installer result to (success, error, reboot_required).
+
+    stdout is authoritative when it carries a known pnputil marker, because the
+    exit code alone falsely fails legitimate outcomes (e.g. "already exists in
+    the system"). The exit code is only the fallback.
+
+    stdout/stderr markers (case-insensitive):
+      "reboot required" / "restart required"  -> success, reboot required
+      "added successfully" /
+      "already exists in the system" /
+      "installed on matching devices" /
+      "successfully installed"                 -> success (reboot iff a reboot
+                                                  exit code rode along)
+    exit-code fallback:
+      0 / 259 (ERROR_NO_MORE_ITEMS)            -> success, no reboot
+      3010 / 1641                              -> success, reboot required
+      anything else                            -> failure, carry stderr/stdout
     """
+    text = f"{stdout}\n{stderr}".lower()
+
+    if any(m in text for m in _PNPUTIL_REBOOT_MARKERS):
+        return True, "", True
+    if any(m in text for m in _PNPUTIL_SUCCESS_MARKERS):
+        return True, "", returncode in _REBOOT_CODES
     if returncode == 0 or returncode in _SUCCESS_NO_CHANGE_CODES:
         return True, "", False
     if returncode in _REBOOT_CODES:
         return True, "", True
-    return False, err_text, False
+    return False, (stderr.strip() or stdout.strip() or f"exit {returncode}")[:200], False
 
 
 def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, str, bool]:
@@ -259,7 +291,7 @@ def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, st
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return _classify(r.returncode, r.stdout[:200])
+            return _classify(r.returncode, r.stdout, r.stderr)
 
         if install_type == "exe_silent":
             exe_files = list(driver_dir.glob("*.exe"))
@@ -282,7 +314,7 @@ def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, st
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return _classify(r.returncode)
+            return _classify(r.returncode, r.stdout, r.stderr)
 
     except subprocess.TimeoutExpired:
         return False, "Install timed out", False

{driverclient-0.2.3 → driverclient-0.2.5}/src/driverclient/ops/resolve.py

@@ -27,6 +27,11 @@ from driverclient.ops.scan import ScanResult, scan
 class ResolveResult:
     drivers:    list[dict]  = field(default_factory=list)
     not_found:  list[str]   = field(default_factory=list)
+    # HWIDs the repo HAS a package for but whose LOCAL installed version is newer
+    # than the repo's — the "stale" side of the harvest delta. Server-computed
+    # from installed_versions and exposed by /resolve as `stale` (older servers
+    # that predate the contract omit it → treated as empty). See capture_delta.
+    stale:      list[str]   = field(default_factory=list)
     trace_id:   str         = ""
     machine_id: str         = ""
     timestamp:  str         = ""
@@ -41,6 +46,12 @@ class ResolveResult:
     def has_missing(self) -> bool:
         return bool(self.not_found)
 
+    @property
+    def has_delta(self) -> bool:
+        """True if there is anything to harvest: a HWID the repo lacks a package
+        for, or one the repo has only an older version of."""
+        return bool(self.not_found or self.stale)
+
 
 def resolve(force: bool = False) -> ResolveResult:
     """
@@ -88,6 +99,9 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
     result = ResolveResult(
         drivers=resp.get("drivers", []),
         not_found=resp.get("not_found", []),
+        # Accept either key name the server may use for the stale/to-harvest set;
+        # absent on servers that predate the contract → empty (no stale harvest).
+        stale=resp.get("stale", resp.get("to_harvest", [])),
         trace_id=resp.get("trace_id", ""),
         machine_id=scan_result.machine_id,
         timestamp=datetime.now(timezone.utc).isoformat(),
@@ -103,10 +117,11 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
         f"[resolve] HWIDs: {total_hwids}  |  "
         f"Already current: {already_current}  |  "
         f"To install: {len(result.drivers)}  |  "
-        f"Not found: {len(result.not_found)}  ({elapsed}ms)",
+        f"Not found: {len(result.not_found)}  |  "
+        f"Stale: {len(result.stale)}  ({elapsed}ms)",
         total=total_hwids, already_current=already_current,
         to_install=len(result.drivers), not_found=len(result.not_found),
-        elapsed_ms=elapsed,
+        stale=len(result.stale), elapsed_ms=elapsed,
     )
 
     _save_cache(result, cfg)