agent-toggle 0.15.0__tar.gz → 0.16.0__tar.gz

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.15.0
+Version: 0.16.0
 Summary: Temporarily disable / re-enable AI-agent skills, agents, commands, rules, plugins and MCP servers across harnesses (Claude Code, Codex, Grok, OpenCode, OpenClaw, Copilot, Vibe, Devin, Antigravity)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/weskao/agent-toggle
@@ -25,7 +25,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: telegram-kit<0.3,>=0.2.2
-Requires-Dist: update-kit<0.2,>=0.1
+Requires-Dist: update-kit<0.3,>=0.2.1
 Provides-Extra: windows
 Requires-Dist: windows-curses; sys_platform == "win32" and extra == "windows"
 Provides-Extra: telegram
@@ -41,6 +41,10 @@ rules, plugins (mods included), MCP servers — across Claude Code, Codex, Grok
 OpenClaw, Copilot, Vibe, Devin and Antigravity — and show what each one costs at
 session start.
 
+It ships in two forms: a **CLI** (`agent-toggle`, all harnesses) and a **Claude Code mod**
+(the `/agent-toggle` pane, claude harness only; see [Claude Code pane mod](#claude-code-pane-mod)).
+Both drive the same toggle engine and state.
+
 **Nothing is ever deleted.** Everything is parked and recorded, and `enable`
 puts it back where it came from.
 
@@ -203,7 +207,7 @@ agent-toggle <command> [args]          # or: python3 agent_toggle.py <command> [
 | `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs, and state entries whose parked item is gone (a `stale` row with the fix command; read-only, still exit `0`) |
 | `list [type]` | what is currently disabled (`--project <dir>` filters to one project) |
 | `cost [--type T]` | estimated startup tokens per item, biggest first (read-only; `--harness H` filters; `--project <dir>` prices a repo's `.claude/` and `.mcp.json` instead of user scope) |
-| `update` (also `--update`) | install the newest release tag (`uv tool install --force --no-sources git+<repo>@<tag>`, or `pipx install --force` for a pipx install), then, with the new version, update the Claude Code plugin (when installed) and the shims. Never asks. Exit `0` updated or already current, `1` the check or install failed (offline, rate limit), `2` a dev install (use `git pull`) or an install it cannot manage (the manual command is printed). Messages go to stderr; `--json` has no JSON for it. The `/agent-toggle` pane command has no `update`: run it in a terminal |
+| `update` (also `--update`) | install the newest release tag (`uv tool install --force --no-sources git+<repo>@<tag>`, or `pipx install --force` for a pipx install), then, with the new version, update the Claude Code plugin (when installed) and the shims. Never asks. Always the newest tag: a dev checkout, a branch or an unmanaged install is replaced by it. Exit `0` updated or already current, `1` the check or install failed (offline, rate limit), `2` neither uv nor pipx is found (the manual command is printed). Messages go to stderr; `--json` has no JSON for it. The `/agent-toggle` pane command has no `update`: run it in a terminal |
 | `install-shims` | write the skill shim into every installed harness that is on in the settings (an off one is skipped unless named with `--harness`); refuses to overwrite a file it did not write (`--dry-run` shows the plan); reports stale legacy `<dir>-disabled/` lines in a harness-home `.gitignore` (`--gitignore` removes them, `--no-gitignore` skips the check); on a terminal, then asks y/n for each problem `doctor` can fix (see [Fixing](#fixing)) |
 | `disable <type> <name>...` | park one or more items (`--dry-run` shows the plan; `--project <dir>` for a repo's own `.claude/` and `.mcp.json`) |
 | `enable <type> <name>...` | put them back (`--dry-run` shows the plan; `--project <dir>` likewise) |
@@ -488,16 +492,41 @@ invalid value in either is ignored with one warning on stderr.
 - `default_harness` is what `disable` / `enable` act on without `--harness`, even when that
   harness is switched off (with one warning on stderr);
   `disable` / `enable --project` without `--harness` still default to `claude`.
-- `language` translates the config menu, help, update messages and picker chrome; command output stays English.
+- `language` translates the config menu, help, update prompt and picker chrome; command output stays English.
 - telegram-kit is a regular dependency now, so reinstalling keeps the Telegram settings working;
   `agent-toggle[telegram]` still resolves.
 
+## Update check
+
+On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
+`update` and `completion` skip it.
+
+- **On a terminal** (stdin and stderr are TTYs, no `--json`): a panel on stderr, "agent-toggle X
+  is available (you have Y)", with `Update now`, `Skip` and `Skip until next version`, a release
+  notes link, and `↑` `↓` `Enter` `q`. `Update now` runs [`agent-toggle update`](#update) (the
+  newest release tag, then the Claude Code plugin and the shims). A failure gives a yellow warning
+  naming the command to run yourself.
+- **Windows**: a running `agent-toggle.exe` cannot be replaced, so there is no `Update now`; the
+  command is printed instead (as below), to run once agent-toggle has exited.
+- **Off a terminal** (or `--json`): a stderr line, `agent-toggle X is available (you have Y)`,
+  then `  agent-toggle update`.
+- It never changes the exit code or stdout, so `--json` output stays one document.
+
+It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
+timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
+normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
+to off (the settings menu's "Check for updates").
+
 ## Update
 
 `agent-toggle update` (or `agent-toggle --update`) is a self-update through
 update-kit (a small stdlib-only helper library): it asks the repository for its newest `vX.Y.Z`
-tag (`git ls-remote --tags`), and when that is newer than the running version it installs it with
+tag (`git ls-remote --tags`) and always installs that tag with
 `uv tool install --force --no-sources git+<repo>@<tag>` (`pipx install --force` for a pipx install).
+A dev checkout, a branch or commit install, or an unmanaged install is replaced by the tag too
+(with uv, else pipx); only an install made from exactly that tag is already up to date.
 It then runs, with the new binary and in order: when the Claude Code plugin is installed,
 `claude plugin marketplace update agent-toggle` and `claude plugin update agent-toggle@agent-toggle`,
 then `agent-toggle install-shims`. A failing step prints a warning and makes the exit code `1`.
@@ -507,19 +536,11 @@ It never prompts and writes to stderr only.
 |---|---|
 | `0` | updated, or already up to date |
 | `1` | could not check (offline, rate limit) or the install failed |
-| `2` | a dev install (`git pull` instead), or an install kind it cannot manage (the manual command is printed) |
+| `2` | neither uv nor pipx is found (the manual command is printed) |
 
 On Windows a running `agent-toggle.exe` cannot be replaced, so the install runs detached after
 agent-toggle exits (log in `%USERPROFILE%\.update-kit\`).
 
-**The hint.** After a command, on an interactive terminal only (stderr is a TTY, never under
-`--json`, pipes, launchd or timers), agent-toggle prints one stderr line when a newer release
-exists, `agent-toggle vX.Y.Z is available (you have A) — run `agent-toggle update``. The check is
-`git ls-remote` with a 1.5 s timeout, cached for 24 hours (failures too) in
-`~/.update-kit/state.json`. It never changes the exit code or stdout. To turn it off, set
-`AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting to off (the settings menu's
-"Check for updates").
-
 ## Help
 
 ```sh
@@ -910,6 +931,7 @@ bookkeeping.
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
 | `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
+| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
 
 A killed run loses at most the one item in flight. If that was a flag write or a
 dir move (with its companions), its `pending` record (the full entry, a flag's

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/README.md

@@ -7,6 +7,10 @@ rules, plugins (mods included), MCP servers — across Claude Code, Codex, Grok
 OpenClaw, Copilot, Vibe, Devin and Antigravity — and show what each one costs at
 session start.
 
+It ships in two forms: a **CLI** (`agent-toggle`, all harnesses) and a **Claude Code mod**
+(the `/agent-toggle` pane, claude harness only; see [Claude Code pane mod](#claude-code-pane-mod)).
+Both drive the same toggle engine and state.
+
 **Nothing is ever deleted.** Everything is parked and recorded, and `enable`
 puts it back where it came from.
 
@@ -169,7 +173,7 @@ agent-toggle <command> [args]          # or: python3 agent_toggle.py <command> [
 | `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs, and state entries whose parked item is gone (a `stale` row with the fix command; read-only, still exit `0`) |
 | `list [type]` | what is currently disabled (`--project <dir>` filters to one project) |
 | `cost [--type T]` | estimated startup tokens per item, biggest first (read-only; `--harness H` filters; `--project <dir>` prices a repo's `.claude/` and `.mcp.json` instead of user scope) |
-| `update` (also `--update`) | install the newest release tag (`uv tool install --force --no-sources git+<repo>@<tag>`, or `pipx install --force` for a pipx install), then, with the new version, update the Claude Code plugin (when installed) and the shims. Never asks. Exit `0` updated or already current, `1` the check or install failed (offline, rate limit), `2` a dev install (use `git pull`) or an install it cannot manage (the manual command is printed). Messages go to stderr; `--json` has no JSON for it. The `/agent-toggle` pane command has no `update`: run it in a terminal |
+| `update` (also `--update`) | install the newest release tag (`uv tool install --force --no-sources git+<repo>@<tag>`, or `pipx install --force` for a pipx install), then, with the new version, update the Claude Code plugin (when installed) and the shims. Never asks. Always the newest tag: a dev checkout, a branch or an unmanaged install is replaced by it. Exit `0` updated or already current, `1` the check or install failed (offline, rate limit), `2` neither uv nor pipx is found (the manual command is printed). Messages go to stderr; `--json` has no JSON for it. The `/agent-toggle` pane command has no `update`: run it in a terminal |
 | `install-shims` | write the skill shim into every installed harness that is on in the settings (an off one is skipped unless named with `--harness`); refuses to overwrite a file it did not write (`--dry-run` shows the plan); reports stale legacy `<dir>-disabled/` lines in a harness-home `.gitignore` (`--gitignore` removes them, `--no-gitignore` skips the check); on a terminal, then asks y/n for each problem `doctor` can fix (see [Fixing](#fixing)) |
 | `disable <type> <name>...` | park one or more items (`--dry-run` shows the plan; `--project <dir>` for a repo's own `.claude/` and `.mcp.json`) |
 | `enable <type> <name>...` | put them back (`--dry-run` shows the plan; `--project <dir>` likewise) |
@@ -454,16 +458,41 @@ invalid value in either is ignored with one warning on stderr.
 - `default_harness` is what `disable` / `enable` act on without `--harness`, even when that
   harness is switched off (with one warning on stderr);
   `disable` / `enable --project` without `--harness` still default to `claude`.
-- `language` translates the config menu, help, update messages and picker chrome; command output stays English.
+- `language` translates the config menu, help, update prompt and picker chrome; command output stays English.
 - telegram-kit is a regular dependency now, so reinstalling keeps the Telegram settings working;
   `agent-toggle[telegram]` still resolves.
 
+## Update check
+
+On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
+`update` and `completion` skip it.
+
+- **On a terminal** (stdin and stderr are TTYs, no `--json`): a panel on stderr, "agent-toggle X
+  is available (you have Y)", with `Update now`, `Skip` and `Skip until next version`, a release
+  notes link, and `↑` `↓` `Enter` `q`. `Update now` runs [`agent-toggle update`](#update) (the
+  newest release tag, then the Claude Code plugin and the shims). A failure gives a yellow warning
+  naming the command to run yourself.
+- **Windows**: a running `agent-toggle.exe` cannot be replaced, so there is no `Update now`; the
+  command is printed instead (as below), to run once agent-toggle has exited.
+- **Off a terminal** (or `--json`): a stderr line, `agent-toggle X is available (you have Y)`,
+  then `  agent-toggle update`.
+- It never changes the exit code or stdout, so `--json` output stays one document.
+
+It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
+timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
+normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
+to off (the settings menu's "Check for updates").
+
 ## Update
 
 `agent-toggle update` (or `agent-toggle --update`) is a self-update through
 update-kit (a small stdlib-only helper library): it asks the repository for its newest `vX.Y.Z`
-tag (`git ls-remote --tags`), and when that is newer than the running version it installs it with
+tag (`git ls-remote --tags`) and always installs that tag with
 `uv tool install --force --no-sources git+<repo>@<tag>` (`pipx install --force` for a pipx install).
+A dev checkout, a branch or commit install, or an unmanaged install is replaced by the tag too
+(with uv, else pipx); only an install made from exactly that tag is already up to date.
 It then runs, with the new binary and in order: when the Claude Code plugin is installed,
 `claude plugin marketplace update agent-toggle` and `claude plugin update agent-toggle@agent-toggle`,
 then `agent-toggle install-shims`. A failing step prints a warning and makes the exit code `1`.
@@ -473,19 +502,11 @@ It never prompts and writes to stderr only.
 |---|---|
 | `0` | updated, or already up to date |
 | `1` | could not check (offline, rate limit) or the install failed |
-| `2` | a dev install (`git pull` instead), or an install kind it cannot manage (the manual command is printed) |
+| `2` | neither uv nor pipx is found (the manual command is printed) |
 
 On Windows a running `agent-toggle.exe` cannot be replaced, so the install runs detached after
 agent-toggle exits (log in `%USERPROFILE%\.update-kit\`).
 
-**The hint.** After a command, on an interactive terminal only (stderr is a TTY, never under
-`--json`, pipes, launchd or timers), agent-toggle prints one stderr line when a newer release
-exists, `agent-toggle vX.Y.Z is available (you have A) — run `agent-toggle update``. The check is
-`git ls-remote` with a 1.5 s timeout, cached for 24 hours (failures too) in
-`~/.update-kit/state.json`. It never changes the exit code or stdout. To turn it off, set
-`AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting to off (the settings menu's
-"Check for updates").
-
 ## Help
 
 ```sh
@@ -876,6 +897,7 @@ bookkeeping.
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
 | `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
+| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
 
 A killed run loses at most the one item in flight. If that was a flag write or a
 dir move (with its companions), its `pending` record (the full entry, a flag's

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/agent_toggle/__init__.py

@@ -1,3 +1,3 @@
 """agent-toggle: temporarily disable / re-enable AI-agent resources."""
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/agent_toggle/cli.py

@@ -36,7 +36,7 @@ Usage:
     failure, 2 usage error, 3 locked, 4 unsupported pair / harness missing.
     Settings: $HOME/.agent-toggle/config.json (see `config`); env overrides
     AGENT_TOGGLE_UPDATE_CHECK / _COLOR / _LANG / _DEFAULT_HARNESS.
-    Update hint: on by default, a terminal's stderr only; AGENT_TOGGLE_UPDATE_CHECK=0 turns it off.
+    Update check: on by default, stderr only; AGENT_TOGGLE_UPDATE_CHECK=0 turns it off.
 """
 from __future__ import annotations
 
@@ -723,9 +723,9 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> int:
     """Run one command and return its exit code (the process exit code).
 
-    Settings apply first; the update hint is printed in a `finally`, so every way out
-    (a command, --help/--version, a usage error, Locked, CliError) gets it. It writes
-    to stderr only and never changes the exit code."""
+    Settings apply first; the update check starts before dispatch and is offered in a
+    `finally`, so every way out (a command, --help/--version, a usage error, Locked,
+    CliError) gets it. It writes to stderr only and never changes the exit code."""
     argv = normalize_argv(sys.argv[1:] if argv is None else argv)
     try:
         language, color = settings.get("language"), settings.get("color")
@@ -734,17 +734,16 @@ def main(argv: list[str] | None = None) -> int:
     i18n.set_language(language)
     color = scan_color(argv, color)     # --color > env > setting > auto
     i = _command_index(argv)
-    hint = True
+    # `update` is the update; `completion` may run on every shell start (eval "$(...)")
+    started = None if argv[i:i + 1] in (["update"], ["completion"]) else update_prompt.start()
     try:
         return _main(argv, color)
     except KeyboardInterrupt:
-        hint = False                    # never ask anything after the user hit Ctrl-C
+        started = None                  # never prompt after the user hit Ctrl-C
         raise
     finally:
-        # `update` is the update; `completion` may run on every shell start (eval "$(...)")
-        if hint and argv[i:i + 1] not in (["update"], ["completion"]):
-            with contextlib.suppress(KeyboardInterrupt):
-                update_prompt.hint(json_mode="--json" in argv)
+        with contextlib.suppress(KeyboardInterrupt):     # Ctrl-C while waiting on the check
+            update_prompt.offer(started, json_mode="--json" in argv, color_mode=color)
 
 
 def _main(argv: list[str], color: str) -> int:

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/agent_toggle/help.py

@@ -140,9 +140,10 @@ def commands(default_harness: str = "claude") -> dict[str, Cmd]:
             t("help.update.summary", "install the newest release; refresh the plugin and shims"),
             t("help.update.desc", "Install the newest release tag (uv tool or pipx), then, with the "
                                   "new version, update the Claude Code plugin (if installed) and "
-                                  "reinstall the shims. Never asks; `--update` is the same. A dev "
-                                  "install says to git pull (exit 2). Exit 1 when the check or "
-                                  "the install fails."),
+                                  "reinstall the shims. Never asks; `--update` is the same. Always "
+                                  "the newest tag: a dev or unmanaged install is replaced by it. "
+                                  "Exit 1 when the check or the install fails, 2 when neither uv "
+                                  "nor pipx is found."),
             examples=["update"]),
         "completion": Cmd(
             "completion bash|zsh|fish|powershell",

{agent_toggle-0.15.0 → agent_toggle-0.16.0}/agent_toggle/locales/zh_tw_cli.py

@@ -29,7 +29,8 @@ CATALOG: dict[str, str] = {
                       "以及暫存項目已省下多少。",
     "help.update.summary": "安裝最新版本，並更新外掛與 shim",
     "help.update.desc": "安裝最新的發行標籤（uv tool / pipx），完成後以新版更新 Claude Code 外掛（若已安裝）"
-                        "並重新安裝 shim。不會提問；`--update` 等同 `update`。開發版安裝請改用 git pull（結束碼 2）。",
+                        "並重新安裝 shim。不會提問；`--update` 等同 `update`。一律安裝最新標籤：開發版或非受管安裝也會被取代。"
+                        "檢查或安裝失敗時結束碼 1；找不到 uv 與 pipx 時結束碼 2。",
     "help.completion.summary": "印出 shell 自動補完腳本",
     "help.completion.desc": "在 stdout 印出某個 shell 的 Tab 補完腳本；"
                             "存到該 shell 載入補完的位置（見 README「Shell completion」）。",
@@ -85,4 +86,16 @@ CATALOG: dict[str, str] = {
     "help.opt.help": "顯示說明（`help <command>` 看單一指令）",
     "help.arguments": "參數",
     "help.options": "選項",
+    # update prompt
+    "update.available": "agent-toggle %s 已推出（目前版本 %s）",
+    "update.keys": "↑↓ 選擇 · ⏎ 確認 · q/Ctrl+C 略過",
+    "update.keys_ascii": "上/下 選擇，Enter 確認，q/Ctrl+C 略過",
+    "update.choose": "請選擇 1-3（Enter = 1，q/Ctrl+C = 略過）：",
+    "update.now": "立即更新",
+    "update.skip": "略過",
+    "update.skip_detail": "下次執行再問",
+    "update.skip_version": "略過到下一個版本",
+    "update.skip_version_detail": "有更新的版本時再問",
+    "update.notes": "版本說明：%s",
+    "update.failed": "更新未完成 — 請自行執行：%s",
 }

agent_toggle-0.16.0/agent_toggle/update_check.py

@@ -0,0 +1,361 @@
+"""Update check against PyPI or GitHub releases. Stdlib only — copied from
+aicp's ``update_check.py`` essentially verbatim; only the UI (``ask``) differs.
+
+    from agent_toggle.update_check import check
+    found = check(
+        "agent-toggle",
+        current="1.0.0",
+        cache_path=Path.home() / ".agent-toggle" / "update-check.json",
+    )
+    if found:
+        print(f"{found.latest} is available (you have {found.current})")
+
+A project released as GitHub tags instead of PyPI passes
+``fetch=fetch_github`` and its ``owner/repo`` in place of the dist name;
+``latest`` is then the tag as published (``v1.2.0``).
+
+To overlap the request with the command's own work instead of paying for
+it at exit, start it early and collect the result at the end:
+
+    started = start("agent-toggle", current="1.0.0", cache_path=...)
+    ...  # the command's own work
+    found = collect(started)
+
+To ask the user what to do instead of only hinting, hand :func:`offer` the
+UI as a callback — it owns what each answer does, the UI only picks one:
+
+    offer(started, ask, cache_path=..., upgrade=["uv", "tool", "upgrade", "agent-toggle"])
+
+where ``ask(found)`` returns ``UPDATE_NOW``, ``SKIP`` or ``SKIP_VERSION``.
+When the upgrade depends on the version or takes several steps, pass a
+callable instead: ``upgrade=lambda found: [[...], [...]]`` runs each command
+in order and stops at the first one that fails.
+``SKIP_VERSION`` is remembered in the cache; a newer release asks again.
+
+Nothing here is allowed to raise to the caller: a missing cache, a bad
+payload, or a dead network all become ``None``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import threading
+import time
+import urllib.error
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_TTL",
+    "SKIP",
+    "SKIP_VERSION",
+    "UPDATE_NOW",
+    "UPGRADE_FAILED",
+    "Started",
+    "UpdateAvailable",
+    "check",
+    "collect",
+    "fetch_github",
+    "fetch_pypi",
+    "offer",
+    "skip",
+    "start",
+]
+
+#: Short because a project can cut several releases in one day; stays far
+#: under PyPI's rate limits even checked every command.
+DEFAULT_TTL = 600
+DEFAULT_TIMEOUT = 0.8
+
+#: Answers an ``ask`` callback returns to :func:`offer`.
+UPDATE_NOW = "update-now"
+SKIP = "skip"
+SKIP_VERSION = "skip-version"
+#: What :func:`offer` returns when UPDATE_NOW's command could not run or failed.
+UPGRADE_FAILED = "upgrade-failed"
+
+
+#: What a version may look like before it is trusted: it gets printed to a terminal.
+_VERSION_RE = re.compile(r"v?\d{1,6}(\.\d{1,6}){1,3}([a-zA-Z0-9.+-]{0,20})?")
+_MAX_BODY = 1_000_000
+
+
+@dataclass(frozen=True)
+class UpdateAvailable:
+    current: str
+    latest: str
+
+
+def _get(request, timeout: float) -> str:
+    """GET over an opener that follows https redirects only; body capped at 1 MB."""
+    import urllib.request  # lazy: ~12 ms saved on every run where the check is off
+
+    class _HttpsOnly(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, req, fp, code, msg, headers, newurl):
+            if not newurl.lower().startswith("https://"):
+                raise urllib.error.URLError(f"refusing non-https redirect: {newurl[:80]!r}")
+            return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+    send = urllib.request.build_opener(_HttpsOnly).open  # network, not file I/O
+    with send(request, timeout=timeout) as response:
+        return response.read(_MAX_BODY).decode("utf-8")
+
+
+def fetch_pypi(dist_name: str, timeout: float) -> str:
+    """GET ``https://pypi.org/pypi/<dist>/json`` and return the raw body."""
+    import urllib.request
+
+    request = urllib.request.Request(
+        f"https://pypi.org/pypi/{dist_name}/json",
+        headers={
+            "Accept": "application/json",
+            "User-Agent": f"{dist_name}-update-check",
+        },
+    )
+    return _get(request, timeout)
+
+
+def fetch_github(repo: str, timeout: float) -> str:
+    """GET ``https://api.github.com/repos/<owner/repo>/releases/latest``; raw body."""
+    import urllib.request
+
+    request = urllib.request.Request(
+        f"https://api.github.com/repos/{repo}/releases/latest",
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": f"{repo.rsplit('/', 1)[-1]}-update-check",
+        },
+    )
+    return _get(request, timeout)
+
+
+def check(
+    dist_name: str,
+    current: str,
+    *,
+    cache_path: Path,
+    ttl_seconds: int = DEFAULT_TTL,
+    timeout: float = DEFAULT_TIMEOUT,
+    now: float | None = None,
+    fetch: Callable[[str, float], str] | None = None,
+    ignore_skip: bool = False,
+) -> UpdateAvailable | None:
+    """Return an update when the latest release is newer than *current*, else None.
+    *ignore_skip* reports a "skip this version" release too (an explicit ask)."""
+    current_parts = _numeric_tuple(current)
+    if current_parts is None:
+        return None
+    stamp = _now(now)
+    cached = _load_cache(cache_path)
+    latest = _valid_version(cached.get("latest"))
+    checked_at = cached.get("checked_at")
+    try:
+        age = stamp - float(checked_at) if isinstance(checked_at, (int, float)) else -1.0
+    except OverflowError:                       # a huge int in a hand-edited cache
+        age = -1.0
+    fresh = 0 <= age < ttl_seconds              # a future, inf or nan stamp is stale
+    if not fresh:
+        try:
+            fetched = _latest_from_body((fetch or fetch_pypi)(dist_name, timeout))
+        except (OSError, urllib.error.URLError, TimeoutError, ValueError):
+            fetched = None
+        # A failed fetch is cached too (keeping the old answer), so being
+        # offline costs one timeout per TTL, not one per command.
+        latest = fetched or latest
+        _save_cache(cache_path, stamp, latest)
+    if not isinstance(latest, str) or (not ignore_skip and latest == _valid_version(cached.get("skipped"))):
+        return None
+    latest_parts = _numeric_tuple(latest)
+    if latest_parts is None or latest_parts <= current_parts:
+        return None
+    return UpdateAvailable(current=current, latest=latest)
+
+
+@dataclass
+class Started:
+    """A background check in flight; pass to :func:`collect` to get its result."""
+
+    thread: threading.Thread
+    _result: list = field(default_factory=list)
+
+
+def start(
+    dist_name: str,
+    current: str,
+    *,
+    cache_path: Path,
+    ttl_seconds: int = DEFAULT_TTL,
+    timeout: float = DEFAULT_TIMEOUT,
+    fetch: Callable[[str, float], str] | None = None,
+) -> Started:
+    """Run :func:`check` on a daemon thread so it overlaps the caller's own work."""
+    result: list = []
+
+    def run() -> None:
+        try:
+            result.append(
+                check(
+                    dist_name,
+                    current,
+                    cache_path=cache_path,
+                    ttl_seconds=ttl_seconds,
+                    timeout=timeout,
+                    fetch=fetch,
+                )
+            )
+        except Exception:  # noqa: BLE001, S110 - a background check must never raise
+            pass
+
+    thread = threading.Thread(target=run, name=f"{dist_name}-update-check", daemon=True)
+    thread.start()
+    return Started(thread=thread, _result=result)
+
+
+def collect(started: Started | None, *, timeout: float = DEFAULT_TIMEOUT) -> UpdateAvailable | None:
+    """Wait for a :func:`start`-ed check and return its result. Never raises."""
+    if started is None:
+        return None
+    try:
+        # Usually already done: it ran alongside the caller's own work.
+        started.thread.join(timeout)
+        return started._result[0] if started._result else None
+    except Exception:  # noqa: BLE001 - a hint must never fail the command
+        return None
+
+
+def skip(cache_path: Path, version: str) -> None:
+    """Stop reporting *version*; a newer release is reported again. Never raises."""
+    data = _load_cache(cache_path)
+    data["skipped"] = version
+    _write_cache(cache_path, data)
+
+
+def offer(
+    started: Started | None,
+    ask: Callable[[UpdateAvailable], str],
+    *,
+    cache_path: Path,
+    upgrade: Sequence[str] | Callable[[UpdateAvailable], Sequence[Sequence[str]]],
+    run: Callable[..., object] = subprocess.run,
+) -> str | None:
+    """Collect *started*, let *ask* pick an answer, then act on it.
+
+    *upgrade* is one command, or a callable building the commands from the
+    found release, run in order. Returns the answer acted on
+    (``UPGRADE_FAILED`` when a command is missing or exits nonzero — the
+    rest are then skipped), or None when there was nothing to offer. Ctrl+C
+    inside *ask* is ``SKIP``. Never raises.
+    """
+    try:
+        found = collect(started)
+        if found is None:
+            return None
+        try:
+            answer = ask(found)
+        except KeyboardInterrupt:
+            return SKIP
+        if answer == SKIP_VERSION:
+            skip(cache_path, found.latest)
+        elif answer == UPDATE_NOW:
+            steps = upgrade(found) if callable(upgrade) else [upgrade]
+            for step in steps:
+                try:
+                    done = run(list(step), check=False)
+                except OSError:
+                    return UPGRADE_FAILED
+                if getattr(done, "returncode", 1) != 0:
+                    return UPGRADE_FAILED
+        return answer
+    except Exception:  # noqa: BLE001 - an update offer must never fail the command
+        return None
+
+
+def _now(now: float | None) -> float:
+    return time.time() if now is None else now
+
+
+def _numeric_tuple(version: str) -> tuple[int, ...] | None:
+    """Leading dotted integers. ``0.10.0`` > ``0.9.1``; ``v1.2`` is ``1.2``. Needs at least X.Y."""
+    parts: list[int] = []
+    for chunk in version.strip().lstrip("vV").split("."):
+        digits = ""
+        for char in chunk:
+            if char in "0123456789":
+                digits += char
+            else:
+                break
+        if not digits or len(digits) > 6:
+            break
+        parts.append(int(digits))
+    if len(parts) < 2:
+        return None
+    return tuple(parts)
+
+
+def _valid_version(value: object) -> str | None:
+    """*value* if it is a plausible version string (no control characters), else None."""
+    return value if isinstance(value, str) and _VERSION_RE.fullmatch(value) else None
+
+
+def _latest_from_body(body: str) -> str | None:
+    """PyPI's ``info.version``, or a GitHub release's ``tag_name``."""
+    data = json.loads(body)
+    if not isinstance(data, dict):
+        return None
+    tag = data.get("tag_name")
+    if isinstance(tag, str) and tag:
+        return _valid_version(tag)
+    info = data.get("info")
+    if not isinstance(info, dict):
+        return None
+    version = info.get("version")
+    return _valid_version(version)
+
+
+def _load_cache(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, RecursionError):    # RecursionError: a deeply nested file
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    # Only the known keys with valid scalar types survive: a hostile file can't
+    # smuggle anything (e.g. a 100k-deep dict that json.dumps can't write back).
+    clean: dict = {}
+    checked_at = data.get("checked_at")
+    if isinstance(checked_at, (int, float)) and not isinstance(checked_at, bool):
+        clean["checked_at"] = checked_at
+    for key in ("latest", "skipped"):
+        version = _valid_version(data.get(key))
+        if version is not None:
+            clean[key] = version
+    return clean
+
+
+def _save_cache(path: Path, checked_at: float, latest: str | None) -> None:
+    data = _load_cache(path)
+    data.update(checked_at=checked_at, latest=latest)
+    _write_cache(path, data)
+
+
+def _write_cache(path: Path, data: dict) -> None:
+    # tmp + os.replace never follows a symlink at *path*; 0600 from creation.
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        tmp.unlink(missing_ok=True)
+        fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(json.dumps(data) + "\n")
+            os.replace(tmp, path)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+    except (OSError, RecursionError, ValueError):
+        return