driverclient 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.4
+Version: 0.2.6
 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.4 → driverclient-0.2.6}/pyproject.toml

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

{driverclient-0.2.4 → driverclient-0.2.6}/src/driverclient/__init__.py

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

{driverclient-0.2.4 → driverclient-0.2.6}/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.4 → driverclient-0.2.6}/src/driverclient/core/hardware.py

@@ -10,12 +10,12 @@ Strategy:
 """
 import hashlib
 import json
-import subprocess
 import uuid
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 from driverclient.config import get
+from driverclient.core import proc
 
 # ── PowerShell profile script ──────────────────────────────────────────────────
 # Runs in ONE subprocess and returns all system data as JSON.
@@ -83,7 +83,7 @@ def get_hwids() -> list[str]:
     cfg   = get()
     hwids = []
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["pnputil", "/enum-devices", "/connected", "/ids"],
             capture_output=True, text=True,
             timeout=cfg["timeout_short"],
@@ -134,7 +134,7 @@ def get_installed_versions(hwids: list[str]) -> dict[str, str]:
 def _run_ps(script: str, timeout: int) -> str:
     """Run a PowerShell script inline. Returns stdout or '' on failure."""
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["powershell", "-NoProfile", "-NonInteractive",
              "-ExecutionPolicy", "Bypass", "-Command", script],
             capture_output=True, text=True, timeout=timeout,
@@ -227,7 +227,7 @@ def _profile_from_wmic() -> dict:
 def _installed_versions_wmic(cfg: dict) -> dict[str, str]:
     versions: dict[str, str] = {}
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["wmic", "path", "Win32_PnPSignedDriver",
              "get", "HardWareID,DriverVersion", "/format:csv"],
             capture_output=True, text=True,
@@ -266,7 +266,7 @@ def _wmic(query: str) -> str:
     """Run a wmic query and return the first non-empty value."""
     cfg = get()
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["wmic"] + query.split() + ["/format:value"],
             capture_output=True, text=True,
             timeout=cfg.get("timeout_tiny", 10),

driverclient-0.2.6/src/driverclient/core/hwid.py

@@ -0,0 +1,135 @@
+"""
+hwid.py — Shared HWID identity mechanism. SINGLE SOURCE OF TRUTH.
+
+⚠️  VENDORED: this file is copied BYTE-IDENTICAL into two repos:
+      - client (client-package): driverclient/core/hwid.py
+      - server (driverserver):   backend/server/core/hwid.py
+    Both copies MUST stay identical. The contract is tests/hwid_vectors.json —
+    both repos run it and must produce the same output. Change here → copy there
+    → run vectors on both. Do NOT edit one copy in isolation.
+
+WHY THIS EXISTS
+    A device's HWIDs come from Windows (pnputil / SetupAPI); a driver package's
+    HWIDs come from the INF text. They describe the same hardware but in
+    slightly different string forms and orders. Matching them reliably (for
+    download/resolve) and indexing them reliably (for upload/capture) requires
+    ONE canonical form and ONE specificity ranking used by BOTH sides. Exact
+    string matching without this is why identical drivers looked "not found".
+
+MODEL (mirrors Windows PnP)
+    A device exposes several HWIDs, from most-specific (hardware IDs) down to
+    generic (compatible IDs). A driver INF declares the HWIDs it supports. The
+    correct driver is the INF that matches the device's MOST-SPECIFIC id.
+    - canonicalize(): fold the two string forms of one id together.
+    - specificity(): higher = more specific (drives ranked matching + tie-break).
+    - is_targetable(): can a driver realistically be authored for this id? Used
+      to DROP generic/class/software ids (PCI\\CC_*, bare PCI\\VEN_*, USB\\CLASS_*,
+      SWD\\, ROOT\\, PRINTENUM\\, *PNP…) so they never count as "missing".
+    - matchable_ids(): a device's canonical, targetable ids, most-specific first
+      — exactly what the client should send and the server should walk.
+"""
+import re
+
+# ── Canonicalization ─────────────────────────────────────────────────────────
+
+_ACPI_VENDEV = re.compile(r"^ACPI\\VEN_([0-9A-Z]+)&DEV_([0-9A-Z]+)")
+
+
+def canonicalize(hwid: str) -> str:
+    """Fold the string forms of one HWID into a single comparable key.
+
+    Rules (order matters):
+      1. strip + uppercase
+      2. drop a single leading '*' (enumerator-independent compatible id marker)
+      3. ACPI: 'ACPI\\VEN_INT&DEV_3394' -> 'ACPI\\INT3394' (pnputil/INF form)
+    PCI/USB/HID keep every component (VEN/DEV/SUBSYS/REV/CC) — specificity(),
+    not canonicalize(), handles tiers, so no structural stripping happens here.
+    """
+    s = hwid.strip().upper()
+    if s.startswith("*"):
+        s = s[1:]
+    m = _ACPI_VENDEV.match(s)
+    if m:
+        tail = s[m.end():]  # preserve any &SUBSYS_/&REV_ tail after the fold
+        s = f"ACPI\\{m.group(1)}{m.group(2)}{tail}"
+    return s
+
+
+# ── Specificity (ranked matching + tie-break) ────────────────────────────────
+
+def specificity(hwid: str) -> int:
+    """Higher = more specific. A device's own id list is roughly ordered, but we
+    compute a score so the server can pick the best INF when several match and
+    so both sides rank identically regardless of source ordering.
+
+    Core device identity (DEV_/PID_/specific ACPI/PNP) is worth 100; SUBSYS adds
+    10; REV adds 1. Pure class/compatible/bare-vendor ids score < 100.
+    """
+    c = canonicalize(hwid)
+    score = 0
+    has_core = bool(
+        "&DEV_" in c                      # PCI device
+        or ("VID_" in c and "PID_" in c)  # USB / HID device
+        or re.search(r"PNP[0-9A-F]{4}", c)       # PNP function id, any form (ACPI\PNP… or bare)
+        or re.match(r"^ACPI\\[0-9A-Z]{3,}\d", c) # folded ACPI vendor+device (e.g. INT3394)
+    )
+    if has_core:
+        score += 100
+    if "SUBSYS_" in c:
+        score += 10
+    if "&REV_" in c:
+        score += 1
+    return score
+
+
+def is_targetable(hwid: str) -> bool:
+    """True if a driver package can realistically be authored to cover this id.
+
+    Drops the ids that inflate 'not_found' and that no INF ever targets:
+    class-code only (PCI\\CC_*), bare vendor (PCI\\VEN_8086), USB\\CLASS_* without
+    PID, and software/bus roots (SWD\\, ROOT\\, PRINTENUM\\, SW\\, STORAGE\\Volume).
+    """
+    c = canonicalize(hwid)
+    enumerator = c.split("\\", 1)[0]
+    if enumerator in _NON_TARGETABLE_ENUMERATORS:
+        return False
+    return specificity(c) >= 100
+
+
+_NON_TARGETABLE_ENUMERATORS = {
+    "SWD", "ROOT", "PRINTENUM", "SW", "STORAGE", "HTREE", "BTH", "DISPLAY",
+}
+
+
+# ── Device id ranking ─────────────────────────────────────────────────────────
+
+def matchable_ids(hwids: list[str]) -> list[str]:
+    """A device's canonical, TARGETABLE HWIDs, most-specific first, deduped.
+
+    This is what the client should send per device and what the server should
+    walk (first hit in the repo index = the driver). Generic/class/software ids
+    are dropped, so a device with a working driver never shows as 'missing'
+    just because it also advertises PCI\\CC_0604.
+    """
+    seen: dict[str, int] = {}
+    for h in hwids:
+        c = canonicalize(h)
+        if is_targetable(c) and c not in seen:
+            seen[c] = specificity(c)
+    return sorted(seen, key=lambda c: seen[c], reverse=True)
+
+
+def canonical_all(hwids: list[str]) -> list[str]:
+    """Canonicalize + dedupe every id (targetable or not), order preserved.
+
+    Used when indexing an INF's declared ids: an INF may legitimately declare a
+    less-specific id, so keep them all — but canonicalized so lookups line up.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    for h in hwids:
+        c = canonicalize(h)
+        if c and c not in seen:
+            seen.add(c)
+            out.append(c)
+    return out

driverclient-0.2.6/src/driverclient/core/proc.py

@@ -0,0 +1,41 @@
+"""
+client/core/proc.py — subprocess wrapper that never flashes a console window.
+
+The client shells out to console tools (pnputil, powershell, wmic, usoclient).
+When it runs standalone from a terminal that is harmless. But when it is
+embedded in a windowed host — the System Assistant PyInstaller `--windowed`
+(no-console) exe — every console child is given its own NEW console window by
+Windows, so the operator sees black cmd/PowerShell windows flashing on screen.
+
+CREATE_NO_WINDOW (+ a hidden STARTUPINFO) suppresses that. This mirrors the
+guard the legacy SA driver path already uses (src/windows_update/driver_server.py).
+No-op on non-Windows, where those flags/attrs don't exist.
+
+Route ALL client subprocess calls through proc.run() so the guard can never be
+forgotten at a call site.
+"""
+import subprocess
+import sys
+
+if sys.platform == "win32":
+    _CREATE_NO_WINDOW = 0x08000000
+
+    def _no_window_kwargs() -> dict:
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        startupinfo.wShowWindow = subprocess.SW_HIDE
+        return {"creationflags": _CREATE_NO_WINDOW, "startupinfo": startupinfo}
+else:
+    def _no_window_kwargs() -> dict:
+        return {}
+
+
+def run(cmd, **kwargs) -> subprocess.CompletedProcess:
+    """subprocess.run() that never shows a console window on Windows.
+
+    Injects CREATE_NO_WINDOW + hidden STARTUPINFO unless the caller already
+    supplied those kwargs. All other behavior is identical to subprocess.run.
+    """
+    for key, value in _no_window_kwargs().items():
+        kwargs.setdefault(key, value)
+    return subprocess.run(cmd, **kwargs)

{driverclient-0.2.4 → driverclient-0.2.6}/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.4 → driverclient-0.2.6}/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.4 → driverclient-0.2.6}/src/driverclient/ops/capture.py

@@ -37,10 +37,11 @@ import functools
 
 from driverclient import events
 from driverclient.config import get
+from driverclient.core import hwid as hwid_mod, proc
 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 +105,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 +191,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 +304,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
 
 
@@ -273,13 +350,13 @@ def classify_missing(not_found: list[str], scan_result: ScanResult) -> dict[str,
     hwid_to_device: dict[str, Device] = {}
     for dev in scan_result.devices:
         for h in dev.hwids:
-            hwid_to_device[_norm_hwid(h)] = dev
+            hwid_to_device[hwid_mod.canonicalize(h)] = dev
 
     buckets: dict[str, list[str]] = {
         "inbox": [], "oem_local": [], "driverless": [], "unknown": [],
     }
     for hwid in not_found:
-        dev = hwid_to_device.get(_norm_hwid(hwid))
+        dev = hwid_to_device.get(hwid_mod.canonicalize(hwid))
         if dev is None:
             buckets["unknown"].append(hwid)
         elif not dev.has_driver:
@@ -320,9 +397,9 @@ def _filter_wu_hwids(
     hwid_to_device: dict[str, Device] = {}
     for dev in scan_result.devices:
         for h in dev.hwids:
-            hwid_to_device[_norm_hwid(h)] = dev
+            hwid_to_device[hwid_mod.canonicalize(h)] = dev
     for hwid in buckets["driverless"]:
-        dev = hwid_to_device.get(_norm_hwid(hwid))
+        dev = hwid_to_device.get(hwid_mod.canonicalize(hwid))
         if dev and ignore_classes and dev.class_name.lower() in ignore_classes:
             skipped["ignored_class"] += 1
         else:
@@ -335,7 +412,7 @@ def _filter_wu_hwids(
 
 def _enumerate_all_packages(cfg: dict) -> list[dict]:
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["pnputil", "/enum-drivers"],
             capture_output=True, text=True,
             timeout=cfg.get("timeout_short", 30),
@@ -382,18 +459,28 @@ def _enumerate_packages_since(cutoff: datetime, cfg: dict) -> list[dict]:
     return result
 
 
-def _norm_hwid(hwid: str) -> str:
-    """Normalize an HWID for comparison: uppercase and strip the &REV_* tail.
-
-    The repo's `not_found` list carries the stripped HWID variants
-    (e.g. PCI\\VEN_8086&DEV_9D15&SUBSYS_222C17AA) while the IDs reported by the
-    live machine — both `installed_versions` keys and pnputil /enum-devices —
-    carry a &REV_xx suffix. Comparing the two forms verbatim never matches, so
-    both sides are normalized to the same REV-less, uppercase form.
+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.
     """
-    up  = hwid.upper()
-    idx = up.find("&REV_")
-    return up[:idx] if idx != -1 else up
+    targets = {hwid_mod.canonicalize(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(hwid_mod.canonicalize(h) in targets for h in dev.hwids):
+            names.add(dev.driver_name)
+    return names
 
 
 def _find_installed_packages_for_hwids(
@@ -401,87 +488,58 @@ def _find_installed_packages_for_hwids(
     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
-    ]
-
-
-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 [all_packages[n] for n in sorted(names) if n in all_packages]
 
-    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"]):
         try:
-            subprocess.run(cmd, capture_output=True, timeout=30)
+            proc.run(cmd, capture_output=True, timeout=30)
             events.ok("windows_update", "[wu-update] Windows Update scan triggered")
             return True
         except Exception:
@@ -634,7 +692,7 @@ def _do_export(pkg: dict, cfg: dict) -> dict | None:
         dest.mkdir()
 
         try:
-            r = subprocess.run(
+            r = proc.run(
                 ["pnputil", "/export-driver", published, str(dest)],
                 capture_output=True, text=True, timeout=timeout,
             )

{driverclient-0.2.4 → driverclient-0.2.6}/src/driverclient/ops/install.py

@@ -24,6 +24,7 @@ from pathlib import Path
 
 from driverclient import events
 from driverclient.config import get
+from driverclient.core import proc
 from driverclient.core.http import http_download_retry, http_post_retry
 from driverclient.ops.resolve import ResolveResult, resolve
 
@@ -43,6 +44,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 +246,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]:
@@ -254,19 +287,19 @@ def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, st
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
                 return False, "No INF file found", False
-            r = subprocess.run(
+            r = proc.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install", "/subdirs"],
                 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"))
             if not exe_files:
                 return False, "No EXE file found", False
             flags = driver.get("install_flags", "/S")
-            r = subprocess.run(
+            r = proc.run(
                 [str(exe_files[0])] + flags.split(),
                 capture_output=True,
                 timeout=cfg["timeout_install"],
@@ -277,12 +310,12 @@ def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, st
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
                 return False, "No firmware INF", False
-            r = subprocess.run(
+            r = proc.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install"],
                 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.4 → driverclient-0.2.6}/src/driverclient/ops/resolve.py

@@ -19,6 +19,7 @@ from pathlib import Path
 
 from driverclient import events
 from driverclient.config import get
+from driverclient.core import hwid as hwid_mod
 from driverclient.core.http import http_post_retry
 from driverclient.ops.scan import ScanResult, scan
 
@@ -27,6 +28,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 +47,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:
     """
@@ -64,6 +76,22 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
     repo_url   = cfg["local_repo_url"]
     session_id = str(uuid.uuid4())
 
+    # Per-device ranked, targetable id lists (shared hwid module). The server
+    # matches per device (ranked walk) and a matched device consumes its whole
+    # group, so generic/class ids never inflate not_found.
+    hwid_groups = [
+        ids for ids in (hwid_mod.matchable_ids(d.hwids) for d in scan_result.devices) if ids
+    ]
+    # Version map ALSO keyed by the canonical ids the server matches on, so its
+    # already-current / stale check lands (raw keys kept for back-compat).
+    canon_versions = {
+        hwid_mod.canonicalize(k): v for k, v in scan_result.installed_versions.items()
+    }
+    for d in scan_result.devices:
+        if d.installed_version:
+            for mid in hwid_mod.matchable_ids(d.hwids):
+                canon_versions.setdefault(mid, d.installed_version)
+
     payload = {
         "machine_id":         scan_result.machine_id,
         "session_id":         session_id,
@@ -73,7 +101,8 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
         "arch":               scan_result.arch,
         "firmware_version":   scan_result.firmware_version,
         "hwids":              scan_result.all_hwids,
-        "installed_versions": scan_result.installed_versions,
+        "hwid_groups":        hwid_groups,
+        "installed_versions": {**scan_result.installed_versions, **canon_versions},
         "force":              force or cfg.get("force_resolve", False),
     }
 
@@ -88,6 +117,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 +135,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)

{driverclient-0.2.4 → driverclient-0.2.6}/src/driverclient/ops/scan.py

@@ -9,8 +9,6 @@ Public API:
     scan(force=False) -> ScanResult
 """
 import json
-import re
-import subprocess
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import asdict, dataclass, field
 from datetime import datetime, timedelta, timezone
@@ -18,6 +16,7 @@ from pathlib import Path
 
 from driverclient import events
 from driverclient.config import get
+from driverclient.core import hwid as hwid_mod, proc
 from driverclient.core.hardware import (
     compute_fingerprint,
     get_installed_versions,
@@ -70,9 +69,6 @@ class ScanResult:
         return [d for d in self.devices if d.has_driver]
 
 
-_ACPI_VENDEV = re.compile(r"^ACPI\\VEN_([^&]+)&DEV_(.+)$")
-
-
 def _looks_like_hwid(stripped: str) -> bool:
     """A pnputil ID line: enumerator form (BUS\\...), star compatible ID
     (*PNP0A0A), bare GUID, or a bare token (WireGuard software devices) —
@@ -84,25 +80,6 @@ def _looks_like_hwid(stripped: str) -> bool:
     return len(stripped) >= 3 and not any(c.isspace() for c in stripped)
 
 
-def _canon_hwid(hwid: str) -> str:
-    """Fold the two HWID forms Windows reports for one device into one key.
-
-    `installed_versions` comes from Win32_PnPSignedDriver.HardWareID — the
-    canonical VEN_/DEV_ form with a &REV_xx tail, and ACPI IDs written as
-    ACPI\\VEN_INT&DEV_3394.  The HWIDs sent to /resolve come from pnputil
-    /enum-devices — raw form, no &REV, ACPI as ACPI\\INT3394.  Both collapse to
-    one comparable key: uppercase, &REV_* dropped, ACPI VEN_/DEV_ concatenated.
-    """
-    up  = hwid.upper()
-    idx = up.find("&REV_")
-    if idx != -1:
-        up = up[:idx]
-    m = _ACPI_VENDEV.match(up)
-    if m:
-        up = f"ACPI\\{m.group(1)}{m.group(2)}"
-    return up
-
-
 def _installed_prefix_index(installed_versions: dict[str, str]) -> dict[str, str]:
     """Expand each canonical installed HWID into its &-boundary prefixes.
 
@@ -115,7 +92,7 @@ def _installed_prefix_index(installed_versions: dict[str, str]) -> dict[str, str
     """
     idx: dict[str, str] = {}
     for key, ver in installed_versions.items():
-        canon = _canon_hwid(key)
+        canon = hwid_mod.canonicalize(key)
         parts = canon.split("&")
         acc   = parts[0]
         prefixes = [acc]
@@ -167,7 +144,7 @@ def scan(force: bool = False) -> ScanResult:
         prefix_idx = _installed_prefix_index(installed_versions)
         for h in all_hwids:
             if h not in installed_versions:
-                ver = prefix_idx.get(_canon_hwid(h))
+                ver = prefix_idx.get(hwid_mod.canonicalize(h))
                 if ver:
                     installed_versions[h] = ver
 
@@ -261,7 +238,7 @@ def _enumerate_devices(cfg: dict) -> list[Device]:
 def _run_pnputil_ids(timeout: int) -> str | None:
     """pnputil /enum-devices /connected /ids  — HWIDs + driver_name."""
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["pnputil", "/enum-devices", "/connected", "/ids"],
             capture_output=True, text=True, timeout=timeout,
         )
@@ -278,7 +255,7 @@ def _run_pnputil_ids(timeout: int) -> str | None:
 def _run_pnputil_classes(timeout: int) -> str | None:
     """pnputil /enum-devices /connected  — class_name per device."""
     try:
-        r = subprocess.run(
+        r = proc.run(
             ["pnputil", "/enum-devices", "/connected"],
             capture_output=True, text=True, timeout=timeout,
         )