wade-cli 0.29.6__tar.gz → 0.30.2__tar.gz

{wade_cli-0.29.6 → wade_cli-0.30.2}/.github/workflows/auto-version.yml

@@ -8,6 +8,10 @@ on:
 permissions:
   contents: write
 
+concurrency:
+  group: auto-version-bump
+  cancel-in-progress: false
+
 jobs:
   version-bump:
     # Only run when the PR was actually merged
@@ -38,9 +42,18 @@ jobs:
         if: steps.detect.outputs.bump == ''
         run: echo "No conventional commit prefix detected — skipping version bump."
 
+      - name: Generate app token
+        if: steps.detect.outputs.bump != ''
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - uses: actions/checkout@v4
         if: steps.detect.outputs.bump != ''
         with:
+          token: ${{ steps.app-token.outputs.token }}
           fetch-depth: 0
 
       - uses: astral-sh/setup-uv@v3
@@ -69,5 +82,14 @@ jobs:
       - name: Push commit and tag
         if: steps.detect.outputs.bump != ''
         run: |
-          git push
-          git push --tags
+          # Pull any commits that landed since checkout (e.g. from a
+          # concurrent version-bump that finished first), then retry push.
+          for attempt in 1 2 3; do
+            git pull --rebase origin main && git push && git push --tags && exit 0
+            if [ "$attempt" -lt 3 ]; then
+              echo "Push attempt $attempt failed, retrying in $((attempt * 2))s..."
+              sleep $((attempt * 2))
+            fi
+          done
+          echo "All push attempts failed"
+          exit 1

{wade_cli-0.29.6 → wade_cli-0.30.2}/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v0.30.2] — 2026-07-16
+
+### Bug Fixes
+
+- prevent infinite self-upgrade re-exec loop in `wade update` (#322) (1e7afc7)
+
+## [v0.30.1] — 2026-07-16
+
+### CI/CD
+
+- use GitHub App token for auto-version push (#319) (7045ef8)
+
+## [v0.30.0] — 2026-07-16
+
+### Features
+
+- add `stale` rating to knowledge entries (56f6f44)
+
+## [v0.29.9] — 2026-07-16
+
+### Bug Fixes
+
+- prevent auto-version workflow race condition on concurrent PR merges (2657e8c)
+
+## [v0.29.8] — 2026-07-16
+
+### Bug Fixes
+
+- accept 'in-progress' as a synonym for 'in_progress' in Markdown task state parsing (6d03639)
+
+## [v0.29.7] — 2026-07-16
+
+### Refactoring
+
+- refine auto-stash sync — skip redundant fetch, extend --no-stash to review session, drop dead stash helpers (45b5f49)
+
 ## [v0.29.6] — 2026-07-16
 
 ### Build

{wade_cli-0.29.6 → wade_cli-0.30.2}/KNOWLEDGE.md

@@ -113,3 +113,19 @@ and keep `bot_status` as a secondary input only.
 When a service does 'from datetime import UTC, datetime' and calls datetime.now(UTC), patch the module-level class reference (e.g. wade.services.review_service.datetime). Set mock_datetime.now.return_value = fixed_now. Avoid naming local variables 'now' as datetime when the same function later uses 'now = time.time()' (float) — mypy strict mode flags the type mismatch even across mutually-exclusive code paths (use a distinct name like 'settle_now').
 
 ---
+
+## 4863036c | 2026-07-16 | plan | tags: refactoring, testing, mocking, architecture
+
+When splitting a wade service module into submodules, moving a function to a new module breaks tests that patch its dependencies: the suite patches fully-qualified paths heavily (e.g. mock.patch("wade.services.implementation_service.core.git_sync"), ~200+ such sites), and mock.patch binds where a name is looked up. Repoint every moved function's patch targets to its new submodule. Also note: the implementation_service package re-exports via "from .sub import *", which does NOT re-export underscore-prefixed helpers — re-export those explicitly in __init__.py.
+
+---
+
+## a24d65b0 | 2026-07-16 | plan | tags: update, self-upgrade, gotcha
+
+`wade update` self-upgrade can infinitely re-exec. Three defects combine:
+(1) `utils/install._run_upgrade` treats package-manager exit code 0 as a successful upgrade — but `uv tool upgrade wade-cli` exits 0 for no-ops too (already up to date, or the target version is yanked/unavailable), so a no-op is reported as success;
+(2) `services/init_service._maybe_self_upgrade` calls `re_exec()` with no loop guard — after re-exec it re-runs the same check with no memory it just tried and no check that the version actually advanced;
+(3) `utils/update_check.check_for_update` trusts the 2-hour nag cache at `~/.local/share/wade/update-check.json`. A stale/yanked `latest_version` (observed: cache said 0.30.1 while 0.29.6 was installed and was repo HEAD) makes every re-exec take the identical upgrade path → infinite "wade upgraded — restarting..." loop for the whole cache TTL.
+Fix: add a re-exec breadcrumb env var (WADE_SELF_UPGRADE_FROM=<old version>) so a post-re-exec process detects the version did NOT advance and stops with a warning; force a cache-bypassing fresh PyPI check for the explicit self-upgrade path; and skip yanked releases when selecting the latest version.
+
+---

{wade_cli-0.29.6 → wade_cli-0.30.2}/KNOWLEDGE.ratings.yml

@@ -4,15 +4,18 @@
 1c18f1d4:
   down: 0
   up: 1
+2b4d5319:
+  down: 0
+  up: 2
 3463fbd4:
   down: 0
-  up: 1
+  up: 2
 54326c98:
   down: 1
   up: 0
 b61e247e:
   down: 0
-  up: 2
+  up: 3
 b6a3a637:
   down: 0
   up: 1
@@ -24,4 +27,4 @@ cedeaad0:
   up: 1
 e2a49ac1:
   down: 0
-  up: 2
+  up: 3

{wade_cli-0.29.6 → wade_cli-0.30.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wade-cli
-Version: 0.29.6
+Version: 0.30.2
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade

{wade_cli-0.29.6 → wade_cli-0.30.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wade-cli"
-version = "0.29.6"
+version = "0.30.2"
 description = "WADE — Workflow for AI-Driven Engineering"
 readme = "README.md"
 license = "MIT"

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/__init__.py

@@ -1,3 +1,3 @@
 """WADE (Workflow for AI-Driven Engineering) — AI-agent-driven git workflow management CLI."""
 
-__version__ = "0.29.6"
+__version__ = "0.30.2"

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/cli/knowledge.py

@@ -155,9 +155,9 @@ def get(
 @knowledge_app.command()
 def rate(
     entry_id: str = typer.Argument(help="Entry ID to rate."),
-    direction: str = typer.Argument(help="Rating direction: up or down."),
+    direction: str = typer.Argument(help="Rating direction: up, down, or stale."),
 ) -> None:
-    """Rate a knowledge entry (thumbs up or down)."""
+    """Rate a knowledge entry (up, down, or stale)."""
     from pathlib import Path
 
     from wade.config.loader import load_config
@@ -169,8 +169,8 @@ def rate(
     )
     from wade.ui.console import console
 
-    if direction not in ("up", "down"):
-        console.error(f"Invalid direction '{direction}'. Must be 'up' or 'down'.")
+    if direction not in ("up", "down", "stale"):
+        console.error(f"Invalid direction '{direction}'. Must be 'up', 'down', or 'stale'.")
         raise typer.Exit(1)
 
     config = load_config()
@@ -198,8 +198,11 @@ def rate(
     except OSError as exc:
         console.error(str(exc))
         raise typer.Exit(1) from exc
-    symbol = "+" if direction == "up" else "-"
-    console.success(f"Recorded {symbol}1 for entry {entry_id}")
+    if direction == "stale":
+        console.success(f"Recorded stale vote for entry {entry_id}")
+    else:
+        symbol = "+" if direction == "up" else "-"
+        console.success(f"Recorded {symbol}1 for entry {entry_id}")
 
 
 @knowledge_app.command()

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/cli/review_pr_comments_session.py

@@ -32,6 +32,11 @@ def sync(
     main_branch: str | None = typer.Option(
         None, "--main-branch", help="Override main branch name."
     ),
+    no_stash: bool = typer.Option(
+        False,
+        "--no-stash",
+        help="Disable auto-stash: fail immediately on any uncommitted changes.",
+    ),
 ) -> None:
     """Sync current branch with main."""
     from wade.cli.session_shared import handle_sync_result
@@ -42,6 +47,7 @@ def sync(
         main_branch=main_branch,
         json_output=json_output,
         session_type="review-pr-comments",
+        no_stash=no_stash,
     )
     handle_sync_result(
         result,

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/git/stash.py

@@ -7,7 +7,6 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 import structlog
-from pydantic import BaseModel
 
 from wade.git.repo import GitError, _run_git
 
@@ -16,13 +15,6 @@ log = structlog.get_logger(__name__)
 AUTOSTASH_PREFIX = "wade-autostash"
 
 
-class AutoStashEntry(BaseModel):
-    """A single wade autostash entry from the git stash list."""
-
-    ref: str
-    message: str
-
-
 def _stash_message(session_type: str, branch: str) -> str:
     ts = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
     safe_branch = branch.replace("/", "_")
@@ -82,34 +74,6 @@ def pop_stash(stash_ref: str, cwd: Path) -> subprocess.CompletedProcess[str]:
     return _run_git("stash", "pop", stash_ref, cwd=cwd, check=False)
 
 
-def apply_stash(stash_ref: str, cwd: Path) -> subprocess.CompletedProcess[str]:
-    """Apply *stash_ref* without removing it. Returns CompletedProcess."""
-    return _run_git("stash", "apply", stash_ref, cwd=cwd, check=False)
-
-
-def drop_stash(stash_ref: str, cwd: Path) -> subprocess.CompletedProcess[str]:
-    """Remove *stash_ref* from the stash list. Returns CompletedProcess."""
-    return _run_git("stash", "drop", stash_ref, cwd=cwd, check=False)
-
-
-def list_wade_autostashes(cwd: Path) -> list[AutoStashEntry]:
-    """Return all wade autostash entries."""
-    result = _run_git("stash", "list", "--format=%gd %gs", cwd=cwd, check=False)
-    if result.returncode != 0:
-        return []
-    entries: list[AutoStashEntry] = []
-    for line in result.stdout.splitlines():
-        if not line.strip():
-            continue
-        parts = line.split(" ", 1)
-        if len(parts) < 2:
-            continue
-        ref, subject = parts[0], parts[1]
-        if AUTOSTASH_PREFIX in subject:
-            entries.append(AutoStashEntry(ref=ref, message=subject))
-    return entries
-
-
 def detect_untracked_collisions(cwd: Path, merge_ref: str) -> list[str]:
     """Return untracked file paths that would be overwritten by merging *merge_ref*.
 

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/providers/markdown.py

@@ -230,7 +230,9 @@ def _format_section(section: _Section) -> str:
 
 def _section_to_task(section: _Section) -> Task:
     """Convert a parsed _Section to a Task model."""
-    state_str = (section.meta.get("state") or "open").lower()
+    # Accept ``in-progress`` (dash) as a synonym for ``in_progress`` so a
+    # hand-edited file doesn't silently downgrade to OPEN.
+    state_str = (section.meta.get("state") or "open").lower().replace("-", "_")
     state = TaskState(state_str) if state_str in _VALID_STATES else TaskState.OPEN
 
     label_names = _split_labels(section.meta.get("labels", ""))
@@ -580,11 +582,11 @@ class MarkdownIssueProvider(GitHubPRDelegateMixin, AbstractTaskProvider):
         rejection, signing failure) is logged at WARNING and swallowed —
         the close itself already succeeded on disk.
         """
-        repo_root = self._path.parent
+        cwd = self._path.parent
         try:
             add = run(
                 ["git", "add", str(self._path)],
-                cwd=repo_root,
+                cwd=cwd,
                 check=False,
             )
             if add.returncode != 0:
@@ -596,7 +598,7 @@ class MarkdownIssueProvider(GitHubPRDelegateMixin, AbstractTaskProvider):
                 return
             commit = run(
                 ["git", "commit", "-m", f"chore: close #{task_id}"],
-                cwd=repo_root,
+                cwd=cwd,
                 check=False,
             )
             if commit.returncode != 0:

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/services/implementation_service/core.py

@@ -1726,6 +1726,7 @@ def _merge_base(
     json_output: bool = False,
     abort_on_conflict: bool = False,
     session_type: str = "implementation",
+    already_fetched: bool = False,
 ) -> SyncResult:
     """Fetch, count commits behind, and merge base branch into current branch.
 
@@ -1744,6 +1745,9 @@ def _merge_base(
             path) so the worktree stays clean. When False (sync path), leave
             the merge in progress for the AI to resolve manually.
         session_type: Used in the conflict hint message.
+        already_fetched: Skip the fetch step — the caller already fetched
+            origin (e.g. for the autostash collision probe) and the local
+            ``origin/<main>`` ref is fresh enough for the merge.
 
     Returns:
         SyncResult with success/conflicts/commits_merged (events=[]).
@@ -1756,14 +1760,17 @@ def _merge_base(
         has_remote = False
 
     if has_remote:
-        try:
-            git_sync.fetch_origin(repo_root)
+        if already_fetched:
             merge_ref = f"origin/{resolved_main}"
-            if not json_output:
-                console.detail(f"Fetched latest from origin/{resolved_main}")
-        except GitError:
-            if not json_output:
-                console.warn("Fetch failed; using local main")
+        else:
+            try:
+                git_sync.fetch_origin(repo_root)
+                merge_ref = f"origin/{resolved_main}"
+                if not json_output:
+                    console.detail(f"Fetched latest from origin/{resolved_main}")
+            except GitError:
+                if not json_output:
+                    console.warn("Fetch failed; using local main")
 
     # Count commits behind
     try:
@@ -1884,6 +1891,7 @@ def sync(
     resolved_main = preflight.resolved_main
 
     stash_ref: str | None = None
+    already_fetched = False
 
     if preflight.dirty_category == _DirtyCategory.USER_DIRTY:
         if no_stash:
@@ -1900,6 +1908,7 @@ def sync(
             if has_remote:
                 git_sync.fetch_origin(repo_root)
                 merge_ref_for_probe = f"origin/{resolved_main}"
+                already_fetched = True
         except GitError:
             pass
 
@@ -1966,6 +1975,7 @@ def sync(
         json_output=json_output,
         abort_on_conflict=stash_ref is not None,
         session_type=session_type,
+        already_fetched=already_fetched,
     )
 
     if stash_ref is not None:
@@ -2033,6 +2043,7 @@ def catchup(
     resolved_main = preflight.resolved_main
 
     stash_ref: str | None = None
+    already_fetched = False
 
     if preflight.dirty_category == _DirtyCategory.USER_DIRTY:
         if no_stash:
@@ -2047,6 +2058,7 @@ def catchup(
             if git_repo.has_remote(repo_root):
                 git_sync.fetch_origin(repo_root)
                 merge_ref_for_probe = f"origin/{resolved_main}"
+                already_fetched = True
         except GitError:
             pass
 
@@ -2093,6 +2105,7 @@ def catchup(
         dry_run=dry_run,
         json_output=json_output,
         abort_on_conflict=True,
+        already_fetched=already_fetched,
     )
 
     stash_restored = True

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/services/init_service.py

@@ -795,11 +795,32 @@ def _maybe_self_upgrade() -> bool:
     Checks PyPI first — only upgrades if a newer version is actually available.
     If upgrade is applied, calls re_exec() which replaces this process.
     Returns True if an upgrade was triggered, False if skipped or up to date.
+
+    Guards against an infinite re-exec loop: immediately before re-exec'ing,
+    the pre-upgrade version is recorded in WADE_SELF_UPGRADE_FROM, which
+    os.execv inherits into the replacement process. On entry, if that
+    breadcrumb is present this call is a post-re-exec retry, so it is always
+    cleared and the function returns False without attempting another
+    upgrade — regardless of whether the version actually advanced.
     """
     from wade import __version__
     from wade.utils.install import InstallMethod, detect_install_method, re_exec, self_upgrade
     from wade.utils.update_check import check_for_update
 
+    breadcrumb = os.environ.pop("WADE_SELF_UPGRADE_FROM", None)
+    if breadcrumb is not None:
+        if breadcrumb == __version__:
+            console.warn(
+                f"self-upgrade did not change the installed version ({__version__}); "
+                "the reported latest may be unavailable — continuing with "
+                f"{__version__}. Use --skip-self-upgrade to skip."
+            )
+        else:
+            logger.info(
+                "_maybe_self_upgrade.upgraded", from_version=breadcrumb, to_version=__version__
+            )
+        return False
+
     method = detect_install_method()
 
     if method in (InstallMethod.EDITABLE, InstallMethod.UNKNOWN):
@@ -808,12 +829,13 @@ def _maybe_self_upgrade() -> bool:
 
     console.step("Checking for WADE updates...")
 
-    latest = check_for_update(__version__)
+    latest = check_for_update(__version__, force=True)
     if not latest:
         return False  # Already at the latest version
 
     if self_upgrade():
         console.success("wade upgraded — restarting...")
+        os.environ["WADE_SELF_UPGRADE_FROM"] = __version__
         re_exec()  # Does not return
         return True  # pragma: no cover
 

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/services/knowledge_service.py

@@ -72,6 +72,7 @@ class EntryRating(BaseModel):
 
     up: int = 0
     down: int = 0
+    stale: int = 0
     superseded_by: str | None = None
 
 
@@ -317,19 +318,21 @@ def record_rating(
     entry_id: str,
     direction: str,
 ) -> None:
-    """Increment the up or down counter for an entry in the sidecar file.
+    """Increment the up, down, or stale counter for an entry in the sidecar file.
 
-    ``direction`` must be ``"up"`` or ``"down"``.
+    ``direction`` must be ``"up"``, ``"down"``, or ``"stale"``.
     """
-    if direction not in ("up", "down"):
-        raise ValueError(f"Invalid direction {direction!r}: must be 'up' or 'down'")
+    if direction not in ("up", "down", "stale"):
+        raise ValueError(f"Invalid direction {direction!r}: must be 'up', 'down', or 'stale'")
 
     def _modify(data: dict[str, EntryRating]) -> None:
         entry = data.setdefault(entry_id, EntryRating())
         if direction == "up":
             entry.up += 1
-        else:
+        elif direction == "down":
             entry.down += 1
+        else:
+            entry.stale += 1
 
     _read_modify_write_ratings(ratings_path, _modify)
 
@@ -454,11 +457,12 @@ def get_annotated_knowledge(
         entry_rating = ratings.get(entry.entry_id) if entry.entry_id else None
         up = entry_rating.up if entry_rating else 0
         down = entry_rating.down if entry_rating else 0
+        stale = entry_rating.stale if entry_rating else 0
         net_score = up - down
         total_votes = up + down
         should_annotate = entry.entry_id is not None
 
-        # Score filtering
+        # Score and stale filtering
         if not no_filter:
             if min_score is not None:
                 # Hard cutoff mode
@@ -471,6 +475,9 @@ def get_annotated_knowledge(
                 and net_score < auto_threshold
             ):
                 continue
+            # Stale threshold filter (independent of score filter)
+            if entry.entry_id is not None and stale >= 2:
+                continue
 
         # Search/tag filtering (OR semantics)
         if parsed_query is not None or filter_tags:
@@ -489,7 +496,8 @@ def get_annotated_knowledge(
         if heading_match and should_annotate:
             id_part = f"{entry.entry_id} | " if entry.entry_id else ""
             assert entry.date is not None  # entry_id is always accompanied by a date
-            heading = f"## {id_part}{entry.date} | {entry.heading_rest} [+{up}/-{down}]"
+            stale_part = f"/stale:{stale}" if stale > 0 else ""
+            heading = f"## {id_part}{entry.date} | {entry.heading_rest} [+{up}/-{down}{stale_part}]"
             raw_lines = entry.raw.split("\n")
             raw_lines[0] = heading
             result_parts.append("\n".join(raw_lines))

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/utils/install.py

@@ -106,6 +106,11 @@ def re_exec() -> None:
 
     Replaces the current process image so the newly installed code is loaded.
     Does not return.
+
+    Uses os.execv (not execve), so the replacement process inherits the
+    calling process's environment unchanged — callers rely on this to pass
+    state across the re-exec (e.g. init_service._maybe_self_upgrade sets
+    WADE_SELF_UPGRADE_FROM beforehand to guard against re-exec loops).
     """
     executable = sys.argv[0]
 

{wade_cli-0.29.6 → wade_cli-0.30.2}/src/wade/utils/update_check.py

@@ -26,20 +26,22 @@ PYPI_URL = "https://pypi.org/pypi/wade-cli/json"
 CACHE_FILE = Path.home() / ".local" / "share" / "wade" / "update-check.json"
 
 
-def _is_newer(candidate: str, current: str) -> bool:
-    """Return True if candidate version is strictly newer than current.
+def _version_tuple(v: str) -> tuple[int, ...]:
+    """Parse a dotted version string into a comparable integer tuple.
 
-    Uses simple numeric tuple comparison — sufficient for standard semver.
-    Falls back to False on any parse error.
+    Uses simple numeric tuple parsing — sufficient for standard semver.
+    Non-numeric segments are dropped; falls back to an empty tuple on any
+    parse error.
     """
     try:
+        return tuple(int(x) for x in v.split(".")[:3] if x.isdigit())
+    except (ValueError, TypeError):
+        return ()
 
-        def to_tuple(v: str) -> tuple[int, ...]:
-            return tuple(int(x) for x in v.split(".")[:3] if x.isdigit())
 
-        return to_tuple(candidate) > to_tuple(current)
-    except (ValueError, TypeError):
-        return False
+def _is_newer(candidate: str, current: str) -> bool:
+    """Return True if candidate version is strictly newer than current."""
+    return _version_tuple(candidate) > _version_tuple(current)
 
 
 def _load_cache() -> dict[str, object] | None:
@@ -72,38 +74,63 @@ def _save_cache(latest_version: str, timestamp: float) -> None:
         pass
 
 
+def _select_latest_non_yanked(releases: dict[str, object]) -> str | None:
+    """Return the highest version among releases with at least one non-yanked file.
+
+    A release with no files, or where every file is yanked, is skipped —
+    PyPI's `info.version` does not account for yanking, so it can point at a
+    release that is no longer installable.
+    """
+    candidates = [
+        version
+        for version, files in releases.items()
+        if isinstance(files, list)
+        and files
+        and not all(isinstance(f, dict) and f.get("yanked") for f in files)
+    ]
+    if not candidates:
+        return None
+    return max(candidates, key=_version_tuple)
+
+
 def _fetch_latest_version() -> str | None:
-    """Fetch the latest wade-cli version from PyPI. Returns None on any error."""
+    """Fetch the latest non-yanked wade-cli version from PyPI. Returns None on any error."""
     try:
         with urlopen(PYPI_URL, timeout=5) as resp:
             data = json.loads(resp.read())
-            version = data["info"]["version"]
-            if isinstance(version, str):
-                return version
+            releases = data["releases"]
+            if not isinstance(releases, dict):
+                return None
+            return _select_latest_non_yanked(releases)
     except (URLError, OSError, json.JSONDecodeError, KeyError, TypeError):
         pass
     return None
 
 
-def check_for_update(current_version: str) -> str | None:
+def check_for_update(current_version: str, force: bool = False) -> str | None:
     """Return latest PyPI version if newer than current, else None.
 
-    Uses a 2-hour file cache to avoid hammering PyPI.
+    Uses a 2-hour file cache to avoid hammering PyPI, unless force=True.
 
     Args:
         current_version: The currently installed version string.
+        force: When True, bypass the cache and fetch live from PyPI (the
+            fresh result still refreshes the cache). Used by the explicit
+            self-upgrade path so a stale or yanked cached "latest" cannot
+            drive the upgrade decision.
 
     Returns:
         The latest version string if an update is available, otherwise None.
     """
     now = datetime.now(UTC).timestamp()
 
-    cached = _load_cache()
-    if cached is not None:
-        age = now - float(str(cached["timestamp"]))
-        if age < CHECK_INTERVAL_SECS:
-            latest = str(cached["latest_version"])
-            return latest if _is_newer(latest, current_version) else None
+    if not force:
+        cached = _load_cache()
+        if cached is not None:
+            age = now - float(str(cached["timestamp"]))
+            if age < CHECK_INTERVAL_SECS:
+                latest = str(cached["latest_version"])
+                return latest if _is_newer(latest, current_version) else None
 
     fetched = _fetch_latest_version()
     if fetched: