syncade 0.7.1__tar.gz → 0.7.3__tar.gz

{syncade-0.7.1/src/syncade.egg-info → syncade-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syncade
-Version: 0.7.1
+Version: 0.7.3
 Summary: External blind multi-judge review orchestrator for AI-assisted coding
 Author-email: Syncade <build@syncade.ai>
 License-Expression: Apache-2.0
@@ -123,11 +123,35 @@ syncade --update        # upgrade, then re-run your command
 ```
 
 `--update` works out how syncade was installed by looking for a marker inside its own install
-tree, and **refuses rather than guessing** if it cannot tell — printing the manual `pip` command
-instead. It also refuses while a review is still running, and declines to touch a source
+tree — `uv`, `pipx`, or the `INSTALLER` record pip leaves — and **refuses rather than guessing**
+if no marker proves one, printing the manual command instead. It also refuses while a review is still running, and declines to touch a source
 checkout. A running process cannot switch to the version it just installed, so it exits and asks
 you to re-run.
 
+> **Installed before 0.6.3? You will never be told about updates.** The check itself arrived in
+> **0.6.3**; every release before it — `0.1.0` through `0.6.2` — has no such code, so it cannot
+> announce anything and `--update` is not a flag it knows. There is no way for us to reach those
+> installs, which is why this paragraph exists. Check with `syncade --version`, and if it is below
+> `0.6.3`, upgrade once by hand:
+>
+> ```bash
+> uv tool install --force syncade          # if you installed with uv
+> pipx upgrade syncade                     # if you installed with pipx
+> python3 -m pip install --user -U syncade   # if you installed with pip --user
+> python3 -m pip install -U syncade          # if you installed with pip
+> ```
+>
+> **Check `syncade --version` afterwards either way** — do not trust the success message. Each
+> of these can report success while changing nothing: `pipx` refuses a package you have
+> `pipx pin`ned, `pip` may target a different interpreter than the one `syncade` resolves to,
+> and on `0.6.3`/`0.7.0` `--update` itself could claim success having installed nothing (fixed
+> in `0.7.1`). The `uv` line is the exception: it upgrades *and* clears any pin.
+>
+> From `0.6.3` on syncade tells you about updates itself — **when it can reach the manifest**.
+> That check is silent on failure by design, so a machine that cannot reach it looks exactly
+> like a machine that is up to date. If you want certainty, compare `syncade --version` against
+> the [releases page](https://github.com/syncade-ai/syncade-ai/releases).
+
 **Requirements**
 - **Python 3.11+**, on **macOS or Linux** (on Windows, use WSL).
 - **`codex`** (OpenAI), on your `PATH` and authenticated — required for the default
@@ -287,7 +311,7 @@ syncade runs AI coding-agent CLIs with **elevated tool access on your repo**:
 - **Reviewers** run headless inside throwaway worktree copies under `/tmp/syncade/` (Codex reviewers are additionally sandboxed to theirs).
 - **The producer** runs unsandboxed and **commits to your current branch** (syncade refuses the default branch by default).
 - Full LLM transcripts — including source a reviewer read — are written to `.syncade/runs/` (gitignored, auto-pruned). **A secret in a file a reviewer opens lands there in plaintext.**
-- syncade makes **one network call of its own**: a once-per-session GET to its public update manifest to check for a newer version (suppressible via `[update] check = false`). `syncade --update` additionally invokes your package manager (`uv tool upgrade`, `pipx upgrade`, or `pip install -U`) — operator-requested and only when you run that flag. All other egress is the provider CLIs you already authenticated and the test/check commands you configure.
+- syncade makes a small number of network calls of its own: a **once-per-session** GET to its public update manifest at the first invocation in each terminal or harness window (suppressible via `[update] check = false`, or set `CI`). `syncade --update` and `syncade --doctor` check every time you run them — operator-requested, so not session-gated. **At most one manifest GET per invocation** either way: a single `syncade` process fetches once and shares it, so `--doctor` does not add a request on top of the session check. `syncade --update` also invokes your package manager (`uv tool upgrade`, `pipx upgrade`, or your own interpreter's `-m pip install -U`) — only when you run that flag. All other egress is the provider CLIs you already authenticated and the test/check commands you configure.
 
 Running syncade is comparable to running the target repo's `Makefile` — it executes code
 with your permissions. See **[SECURITY.md](SECURITY.md)** for the full threat model and how

{syncade-0.7.1 → syncade-0.7.3}/README.md

@@ -93,11 +93,35 @@ syncade --update        # upgrade, then re-run your command
 ```
 
 `--update` works out how syncade was installed by looking for a marker inside its own install
-tree, and **refuses rather than guessing** if it cannot tell — printing the manual `pip` command
-instead. It also refuses while a review is still running, and declines to touch a source
+tree — `uv`, `pipx`, or the `INSTALLER` record pip leaves — and **refuses rather than guessing**
+if no marker proves one, printing the manual command instead. It also refuses while a review is still running, and declines to touch a source
 checkout. A running process cannot switch to the version it just installed, so it exits and asks
 you to re-run.
 
+> **Installed before 0.6.3? You will never be told about updates.** The check itself arrived in
+> **0.6.3**; every release before it — `0.1.0` through `0.6.2` — has no such code, so it cannot
+> announce anything and `--update` is not a flag it knows. There is no way for us to reach those
+> installs, which is why this paragraph exists. Check with `syncade --version`, and if it is below
+> `0.6.3`, upgrade once by hand:
+>
+> ```bash
+> uv tool install --force syncade          # if you installed with uv
+> pipx upgrade syncade                     # if you installed with pipx
+> python3 -m pip install --user -U syncade   # if you installed with pip --user
+> python3 -m pip install -U syncade          # if you installed with pip
+> ```
+>
+> **Check `syncade --version` afterwards either way** — do not trust the success message. Each
+> of these can report success while changing nothing: `pipx` refuses a package you have
+> `pipx pin`ned, `pip` may target a different interpreter than the one `syncade` resolves to,
+> and on `0.6.3`/`0.7.0` `--update` itself could claim success having installed nothing (fixed
+> in `0.7.1`). The `uv` line is the exception: it upgrades *and* clears any pin.
+>
+> From `0.6.3` on syncade tells you about updates itself — **when it can reach the manifest**.
+> That check is silent on failure by design, so a machine that cannot reach it looks exactly
+> like a machine that is up to date. If you want certainty, compare `syncade --version` against
+> the [releases page](https://github.com/syncade-ai/syncade-ai/releases).
+
 **Requirements**
 - **Python 3.11+**, on **macOS or Linux** (on Windows, use WSL).
 - **`codex`** (OpenAI), on your `PATH` and authenticated — required for the default
@@ -257,7 +281,7 @@ syncade runs AI coding-agent CLIs with **elevated tool access on your repo**:
 - **Reviewers** run headless inside throwaway worktree copies under `/tmp/syncade/` (Codex reviewers are additionally sandboxed to theirs).
 - **The producer** runs unsandboxed and **commits to your current branch** (syncade refuses the default branch by default).
 - Full LLM transcripts — including source a reviewer read — are written to `.syncade/runs/` (gitignored, auto-pruned). **A secret in a file a reviewer opens lands there in plaintext.**
-- syncade makes **one network call of its own**: a once-per-session GET to its public update manifest to check for a newer version (suppressible via `[update] check = false`). `syncade --update` additionally invokes your package manager (`uv tool upgrade`, `pipx upgrade`, or `pip install -U`) — operator-requested and only when you run that flag. All other egress is the provider CLIs you already authenticated and the test/check commands you configure.
+- syncade makes a small number of network calls of its own: a **once-per-session** GET to its public update manifest at the first invocation in each terminal or harness window (suppressible via `[update] check = false`, or set `CI`). `syncade --update` and `syncade --doctor` check every time you run them — operator-requested, so not session-gated. **At most one manifest GET per invocation** either way: a single `syncade` process fetches once and shares it, so `--doctor` does not add a request on top of the session check. `syncade --update` also invokes your package manager (`uv tool upgrade`, `pipx upgrade`, or your own interpreter's `-m pip install -U`) — only when you run that flag. All other egress is the provider CLIs you already authenticated and the test/check commands you configure.
 
 Running syncade is comparable to running the target repo's `Makefile` — it executes code
 with your permissions. See **[SECURITY.md](SECURITY.md)** for the full threat model and how

{syncade-0.7.1 → syncade-0.7.3}/docs/config-reference.md

@@ -99,7 +99,7 @@ below; `worktree_base` is the one top-level scalar.
 | `review` | `[review]` table | — | What reviewers see. See [`[review]`](#review--reviewconfig). |
 | `retry` | `[retry]` table | — | Transient-error retry bound. See [`[retry]`](#retry--retryconfig). |
 | `gc` | `[gc]` table | — | Run-artifact retention. See [`[gc]`](#gc--gcconfig). |
-| `update` | `[update]` table | — | The once-per-session update check. See [`[update]`](#update--updateconfig). |
+| `update` | `[update]` table | — | Background update check and opt-out. See [`[update]`](#update--updateconfig). |
 | `worktree_base` | path | `/tmp/syncade` | Base dir for per-run git worktrees. Overridable with `--worktree-base`; point it at a fast local disk if `/tmp` is small or slow. |
 | `checks` | `[[checks]]` list | none | Mechanical exit-code gates. See [`[[checks]]`](#checks--checkconfig). |
 | `pricing` | `[pricing]` table | packaged price table | Per-model token pricing for cost estimation. See [`[pricing]`](#pricing--pricingconfig). |
@@ -237,10 +237,17 @@ the first two; the worktree bound is config-only (set it with
 
 ## `[update]` — `UpdateConfig`
 
-Whether syncade checks for a newer release. The check only ever **prints**: it cannot block a run,
-change an exit code, or fail one — every error (offline, timeout, bad JSON) is silent. It fires at
-most once per window, at the first syncade invocation, and is skipped entirely whenever `CI` is
-set. Nothing about your repo, diff, run, or identity is sent.
+Whether syncade checks for a newer release. Nothing about your repo, diff, run, or identity is
+sent. The check has two distinct modes with different behaviors:
+
+**Background check** (automatic, at first invocation): fires at most once per session window,
+only ever **prints** — it cannot block a run, change an exit code, or fail one. Every error
+(offline, timeout, bad JSON) is silent. Skipped entirely when `CI` is set.
+
+**Explicit check** (`--doctor` and `--update`): each makes its own manifest fetch (one per
+process, independent of the background check). `--doctor` displays the result as a row in the
+preflight table and exits 60 if the manifest is unreachable. `--update` surfaces an unreachable
+manifest as an explicit message. Both are also skipped when `check = false` or `CI` is set.
 
 The advisory source is deliberately not configurable — a repo-local file that could repoint or
 silence a security notice would be a hole, not a feature.
@@ -248,7 +255,7 @@ silence a security notice would be a hole, not a feature.
 <!-- config-fields: UpdateConfig -->
 | Field | Type | Default | What it does |
 |---|---|---|---|
-| `check` | bool | `true` | Check once per session whether a newer syncade is published. Set `false` to never make the request. |
+| `check` | bool | `true` | Enable update checks. Set `false` to suppress all manifest fetches — background, `--doctor`, and `--update`. Also skipped whenever `CI` is set. At most one fetch per invocation: the background check is once per session, `--doctor` and `--update` check whenever you run them, and a single process never fetches twice. |
 
 ## `[[checks]]` — `CheckConfig`
 

{syncade-0.7.1 → syncade-0.7.3}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "syncade"
-version = "0.7.1"
+version = "0.7.3"
 description = "External blind multi-judge review orchestrator for AI-assisted coding"
 readme = "README.md"
 requires-python = ">=3.11"

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/__init__.py

@@ -1,3 +1,3 @@
 """Syncade — external blind multi-judge review orchestrator."""
 
-__version__ = "0.7.1"
+__version__ = "0.7.3"

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/cli/parser.py

@@ -310,8 +310,8 @@ def build_parser() -> argparse.ArgumentParser:
         "--update",
         action="store_true",
         help="Upgrade syncade to the latest published release, then exit. Detects how syncade "
-        "was installed by finding a marker inside its own install tree (uv tool / pipx) and "
-        "REFUSES rather than guessing when it cannot tell, printing the manual pip command "
+        "was installed by finding a marker inside its own install tree (uv tool / pipx / pip) "
+        "and REFUSES rather than guessing when it cannot tell, printing the manual pip command "
         "instead. Refuses while a run is still going. Re-installs any skill you already have, "
         "using the upgraded code. A running process cannot switch to the new version, so this "
         "exits and asks you to re-run your command.",

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/cli/update_mode.py

@@ -16,6 +16,8 @@ the PR-h-04.5 shape one layer up: refuse rather than act on an unproven belief.
 
 from __future__ import annotations
 
+import os
+import site
 import subprocess
 import sys
 from dataclasses import dataclass
@@ -24,7 +26,7 @@ from pathlib import Path
 import syncade
 from syncade.exit_codes import SUCCESS, WORKTREE_ERROR
 from syncade.process import SubprocessError, run_subprocess
-from syncade.update_check import MANIFEST_URL, _fetch, _parse, _text
+from syncade.update_check import _parse, _text, manifest_once
 
 _UPGRADE_TIMEOUT = 300.0
 #: Reading one version string out of a fresh interpreter. Generous, because a cold venv
@@ -38,11 +40,91 @@ _MARKER_DEPTH = 7
 
 @dataclass(frozen=True)
 class InstallMethod:
-    kind: str  # "uv" | "pipx" | "source" | "unknown"
+    kind: str  # "uv" | "pipx" | "pip" | "source" | "unknown"
     command: list[str] | None  # the upgrade to run, or None when we must not run anything
     where: Path | None
 
 
+def _in_user_site() -> bool:
+    """Whether THIS syncade lives in the per-user site directory.
+
+    Decides one thing: whether the pip upgrade needs ``--user``. A user-site install requires it
+    and a system-site install rejects it, so guessing either way breaks half the population. The
+    answer is derivable from paths we already hold, so it is derived rather than assumed.
+    """
+    try:
+        user_site = Path(site.getusersitepackages()).resolve()
+    except (AttributeError, OSError):  # no user site on this interpreter
+        return False
+    return user_site in Path(syncade.__file__).resolve().parents
+
+
+def _read_scoped_installer() -> str:
+    """Read INSTALLER from the dist-info directory that BELONGS to this syncade install.
+
+    Path-scoped to the site-packages directory containing ``syncade/__init__.py``, so an
+    unrelated dist-info for a different interpreter's syncade cannot prove this tree as pip.
+    Returns the installer name (e.g. ``"pip"``), or empty string when not found or ambiguous.
+
+    Contradictory duplicate dist-info directories (a broken packaging state) are refused
+    conservatively: if two ``syncade-*.dist-info`` entries disagree on INSTALLER, the result
+    is empty string — the same as not found.  First-match would misclassify in that state,
+    which contradicts the PROVE-or-refuse posture the rest of this module maintains.
+    """
+    site_packages = Path(syncade.__file__).resolve().parent.parent
+    found: list[str] = []
+    try:
+        for entry in site_packages.iterdir():
+            if (
+                entry.name.startswith("syncade-")
+                and entry.name.endswith(".dist-info")
+                and entry.is_dir()
+            ):
+                try:
+                    found.append((entry / "INSTALLER").read_text(encoding="utf-8").strip())
+                except OSError:
+                    pass  # No INSTALLER file — this dist-info cannot prove anything.
+    except OSError:
+        pass
+    if not found:
+        return ""
+    # Contradictory entries in a broken packaging state are not proof of anything.
+    return found[0] if len(set(found)) == 1 else ""
+
+
+def _pip_or_unknown(where: Path | None) -> InstallMethod:
+    """``pip`` when the distribution records pip as its installer, else ``unknown``.
+
+    Reached ONLY after the marker walk has failed to prove uv, pipx or a checkout. That ordering
+    is load-bearing, not tidiness: uv and pipx write ``dist-info/INSTALLER`` naming THEMSELVES, so
+    consulting it earlier would run pip against a uv tool. Their own markers are the specific ones
+    and they are checked first.
+
+    ``INSTALLER`` is a marker file naming its writer, exactly like ``uv-receipt.toml`` — reading it
+    keeps this PROVING rather than guessing, which is the distinction the refusal exists to
+    protect. Before this, a plain pip install was ``unknown`` and ``--update`` refused: correct
+    under the rule, and wrong about the facts, because pip had left proof all along and syncade
+    never looked. Found by an operator whose real install was exactly this shape.
+
+    The lookup is PATH-SCOPED to the site-packages directory containing ``syncade/__init__.py``.
+    Reading by project name from ambient ``importlib.metadata`` would match an unrelated
+    dist-info (e.g. from a different interpreter's install) and classify a markerless tree as
+    pip when it is not — measured in a worktree where ``syncade.__file__`` was the reviewed
+    source while metadata pointed at a real installed dist-info.
+
+    ``sys.executable -m pip``, never a bare ``pip`` from PATH — that resolves to whichever pip
+    comes first and would upgrade some other interpreter's syncade as often as this one's.
+    """
+    installer = _read_scoped_installer()
+    if installer != "pip":
+        # Some other installer, or a name we do not recognise. Unproven is still unproven.
+        return InstallMethod("unknown", None, where)
+    user = ["--user"] if _in_user_site() else []
+    return InstallMethod(
+        "pip", [sys.executable, "-m", "pip", "install", "-U", *user, "syncade"], where
+    )
+
+
 def detect_install() -> InstallMethod:
     """Prove how syncade got here by finding a marker inside its own install tree."""
     start = Path(syncade.__file__).resolve().parent
@@ -59,7 +141,7 @@ def detect_install() -> InstallMethod:
         # specific; reaching here means the environment exists but its manager is unproven,
         # which is exactly what "unknown" is for.
         if (parent / "pyvenv.cfg").is_file():
-            return InstallMethod("unknown", None, parent)
+            return _pip_or_unknown(parent)
         # A checkout is the one case where upgrading would be actively wrong: the operator's
         # own working tree is the install, and `uv tool upgrade` would neither touch it nor
         # tell them why nothing changed. Detected by the project file naming THIS project, so a
@@ -67,7 +149,7 @@ def detect_install() -> InstallMethod:
         pyproject = parent / "pyproject.toml"
         if pyproject.is_file() and 'name = "syncade"' in _read(pyproject):
             return InstallMethod("source", None, parent)
-    return InstallMethod("unknown", None, None)
+    return _pip_or_unknown(None)
 
 
 def _read(path: Path) -> str:
@@ -203,16 +285,21 @@ def _installed_version() -> str | None:
     return candidate if _parse(candidate) is not None else None
 
 
-def _is_newest(installed: str) -> bool:
-    """Whether ``installed`` is at or beyond the newest version the manifest advertises.
+def _is_newest(installed: str, *, enabled: bool = True) -> bool | None:
+    """Whether ``installed`` is at or beyond the newest the manifest advertises, or ``None``.
+
+    THREE answers, because the caller has three outcomes and two states could not express
+    them. ``None`` means the manifest could not be read AT ALL, which is NOT "a newer version
+    exists" — collapsing those is a shipped defect: on a machine whose TLS verification fails,
+    an already-current install was told "nothing was installed, most often the install pins a
+    version" and sent hunting a pin that did not exist.
 
     Only ever consulted on the unhappy path — the version failed to move — so the happy path
     stays offline. Anything that leaves the question unanswered (unreachable manifest, no usable
-    ``latest``, an installed version we cannot parse) returns ``False``, i.e. "cannot prove you
-    are current", which routes to the louder message. That is the safe direction: telling someone
-    to check for a pin when they were merely current is a wasted minute; telling someone they are
-    up to date when the upgrade silently failed strands them on an old version believing it is
-    the new one.
+    ``latest``, an installed version we cannot parse) returns ``None`` — the third state meaning
+    "could not determine". That is the safe direction when used with care: the caller must render
+    ``None`` as "manifest unreachable" rather than a pin diagnosis, because collapsing the two was
+    the shipped defect this three-valued return exists to fix.
 
     **This compares versions itself and must never delegate to ``evaluate()``.** That function
     answers a DIFFERENT question — "should the operator see a notice?" — and the two answers
@@ -224,13 +311,23 @@ def _is_newest(installed: str) -> bool:
     neighbouring answer — and the fix both times was to ask the actual question.
 
     There is deliberately no special case for an unreachable manifest: ``{}`` has no usable
-    ``latest``, so the one parse rule already answers it. An explicit branch was there and a
-    mutation run proved it dead — every input reached the same verdict without it.
+    ``latest``, so the one parse rule already answers it. An explicit ``if manifest is None``
+    branch has been added and removed TWICE, both times proved dead by a mutation run — the
+    second time by the same person who wrote this sentence, four lines below it. If you are about
+    to add it again, mutate it first: replace ``manifest_once(...) or {}`` and watch nothing
+    fail.
+
+    ``enabled=False`` fetches NOTHING and yields ``None`` — an operator who set
+    ``[update] check = false`` gets no egress from the explicit path either, which is what
+    makes README's "one network call of its own, suppressible" true. The caller already
+    reports ``None`` as "could not check", so honouring the opt-out costs no new branch.
     """
-    manifest = _fetch(MANIFEST_URL) or {}
+    manifest = manifest_once(enabled=enabled) or {}
     latest = _parse(_text(manifest.get("latest")))
     current = _parse(installed)
-    return latest is not None and current is not None and current >= latest
+    if latest is None or current is None:
+        return None
+    return current >= latest
 
 
 def run_update(*, cwd: Path | None = None, out=None) -> int:
@@ -270,7 +367,7 @@ def run_update(*, cwd: Path | None = None, out=None) -> int:
     if method.command is None:
         print(
             "[syncade] could not determine how syncade was installed, so nothing was run.\n"
-            "          If you used pip:  pip install -U syncade",
+            f"          If you used pip:  {sys.executable} -m pip install -U syncade",
             file=out,
         )
         return WORKTREE_ERROR
@@ -311,18 +408,55 @@ def run_update(*, cwd: Path | None = None, out=None) -> int:
         # first version of this guard and it told an operator who was simply already current
         # that their install was pinned and broken — a fresh false claim inside the fix for a
         # false claim, caught by testing the path instead of reasoning about it.
-        if _is_newest(now):
+        # The opt-out reaches HERE too, not just the startup notice: `[update] check = false`
+        # means no manifest request from any path, which is the documented contract.
+        from syncade.cli.update_notice import _check_enabled
+
+        # CI is honoured here for the same reason check_for_update honours it: no human is
+        # reading the output, so a manifest request adds no value and contradicts the
+        # documented "also skipped whenever CI is set" guarantee for [update] check.
+        newest = _is_newest(now, enabled=_check_enabled(cwd) and not bool(os.environ.get("CI")))
+        if newest:
             skills_ok = _resync_skills(out)
             print(f"[syncade] already up to date ({now}).", file=out)
             return SUCCESS if skills_ok else WORKTREE_ERROR
-        print(
-            f"[syncade] the upgrade command succeeded but syncade is still "
-            f"{syncade.__version__} — nothing was installed.\n"
-            f"          Most often the install pins a version: check `uv tool list` / "
-            f"`pipx list`, then\n"
-            f"          reinstall unpinned (e.g. `uv tool install --force syncade`).",
-            file=out,
-        )
+        if newest is None:
+            # Cannot read the manifest, so whether an upgrade was even due is unknown. Rendering
+            # the pin diagnosis here sends the operator hunting a pin that may not exist —
+            # measured on macOS framework Python, where a missing CA bundle fails TLS in 0.05s
+            # and leaves every update check silently dead. The manifest may also be reachable
+            # but malformed; either way, the CA remedy is a conditional suggestion, not a
+            # diagnosis.
+            print(
+                f"[syncade] syncade is still {now}, and the update manifest could not be\n"
+                "          read, so whether that is correct is unknown. Compare your version\n"
+                "          against https://github.com/syncade-ai/syncade-ai/releases\n"
+                "          On macOS python.org builds a missing CA bundle can cause this —\n"
+                "          run `Install Certificates.command` from your Python's Applications\n"
+                "          folder if you see TLS errors.",
+                file=out,
+            )
+            return WORKTREE_ERROR
+        if method.kind == "pip":
+            user_flag = " --user" if _in_user_site() else ""
+            print(
+                f"[syncade] the upgrade command succeeded but syncade is still "
+                f"{syncade.__version__} — nothing was installed.\n"
+                "          Most often a resolver constraint or pinned requirement prevented "
+                "the upgrade.\n"
+                "          Reinstall unpinned: "
+                f"{sys.executable} -m pip install -U{user_flag} --force-reinstall syncade",
+                file=out,
+            )
+        else:
+            print(
+                f"[syncade] the upgrade command succeeded but syncade is still "
+                f"{syncade.__version__} — nothing was installed.\n"
+                f"          Most often the install pins a version: check `uv tool list` / "
+                f"`pipx list`, then\n"
+                f"          reinstall unpinned (e.g. `uv tool install --force syncade`).",
+                file=out,
+            )
         return WORKTREE_ERROR
 
     skills_ok = _resync_skills(out)

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/config.py

@@ -355,8 +355,9 @@ class SyncadeConfig(BaseModel):
     # Run-artifact retention (PR-v2-9). Defaults reproduce gc.DEFAULT_KEEP / DEFAULT_MAX_AGE_DAYS;
     # governs BOTH the per-loop auto-prune and an explicit ``syncade --gc``.
     gc: GcConfig = Field(default_factory=GcConfig)
-    # One-key off switch for the once-per-session update check (PR-h-field-07). The check
-    # only ever prints — it cannot block a run or change an exit code.
+    # One-key opt-out for update manifest fetches (PR-h-field-07). Suppresses background
+    # check, --update, and --doctor's manifest row when false. --doctor's red manifest row
+    # exits 60; the background check only prints, silent errors.
     update: UpdateConfig = Field(default_factory=UpdateConfig)
     # Where per-run git worktrees are provisioned (PR-v2-9). A single top-level value (not a
     # ``[worktree]`` block — Q5); default reproduces worktree.DEFAULT_WORKTREE_BASE.

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/config_update.py

@@ -19,11 +19,12 @@ class UpdateConfig(BaseModel):
     check: bool = Field(
         default=True,
         description=(
-            "Check once per session whether a newer syncade is published (default true). One "
-            "HTTPS GET to the public repo's update manifest, 1.5s timeout, at the first syncade "
-            "invocation in a window and never again in that window. It only ever PRINTS: it "
-            "cannot block a run, change an exit code, or fail one — every error is silent. "
-            "Nothing about your repo, diff, run, or identity is sent. Also skipped whenever CI "
+            "Enable update checks (default true). An HTTPS GET to the public repo's update "
+            "manifest, 1.5s timeout. Nothing about your repo, diff, run, or identity is sent. "
+            "Set false to suppress all fetches — background, --update, and --doctor. "
+            "Background: fires at most once per session window, only prints, every error is "
+            "silent. Explicit (--update, --doctor): each makes its own fetch per process; "
+            "--doctor exits 60 when the manifest is unreachable. Also skipped whenever CI "
             "is set."
         ),
     )

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/doctor.py

@@ -37,15 +37,16 @@ from syncade.config import SyncadeConfig
 from syncade.config_auth import ALL_BLOCKS
 
 # Re-exported for import stability after the PR-h-field-01 split (Decomposition Rule): callers
-# keep importing these from `syncade.doctor`. MONKEYPATCH TARGETS ARE `doctor_env`, NOT
-# here — these names are bindings, and rebinding one does not change what the function
-# bodies in doctor_env read.
+# keep importing these from `syncade.doctor`. MONKEYPATCH TARGETS ARE `syncade.doctor`, NOT
+# `doctor_env` — `collect_checks()` calls these names through the binding HERE, so patching
+# `doctor_env` does not affect what the function body reads.
 from syncade.doctor_env import (  # noqa: F401
     _CLI_LAUNCH_TIMEOUT,
     _MIN_FREE_DISK_BYTES,
     _PROVIDER_CLI,
     _check_config,
     _check_provider_clis,
+    _check_update_manifest,
     _check_worktree_root,
     _configured_providers,
     _probe_cli_launch,
@@ -330,6 +331,10 @@ def collect_checks(
         check_cost(config, repo_root, max_rounds=max_rounds),
         check_budget(config),
     ]
+    # The update-manifest check is informational: an unreachable manifest does not refuse a real
+    # run, so it must NOT be in `cheap` (whose reds gate the live legs). It is run after the
+    # gating decision, and its red status does not suppress auth or producer-commit.
+    update_check = _check_update_manifest(enabled=config.update.check)
     checks = list(cheap)
     if quick:
         checks.append(DoctorCheck("auth", _SKIP, "skipped (--quick): credential probe not run"))
@@ -355,6 +360,9 @@ def collect_checks(
             )
         else:
             checks.append(_check_producer_commit(config, timeout_seconds=timeout_seconds))
+    # Append the update-manifest check after the live-legs decision: it is informational and
+    # its red status must not appear to gate the live legs (which were decided above without it).
+    checks.append(update_check)
     return checks
 
 

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/doctor_env.py

@@ -216,3 +216,50 @@ def _check_worktree_root(worktree_base: Path) -> DoctorCheck:
             fix="free up disk space; each reviewer/producer/test leg checks out a worktree",
         )
     return DoctorCheck("worktree", _OK, f"{probe_dir} writable, {free_gib:.1f} GiB free")
+
+
+def _check_update_manifest(*, enabled: bool = True) -> DoctorCheck:
+    """Can this machine reach the update manifest at all?
+
+    A red row here does not affect a review — the background check is silent by design and must
+    never slow or fail a run. It is worth a row because its failure is INVISIBLE everywhere else:
+    an unreachable manifest and an up-to-date syncade look identical, forever, so an operator can
+    sit years behind believing they are current. Doctor exists to surface exactly that kind of
+    quietly-broken setup for $0.
+
+    Measured cause on the reporting machine: python.org's macOS framework build ships no CA
+    bundle, its `openssl_cafile` points at a `cert.pem` that does not exist, and TLS verification
+    fails in 0.05s. Not a timeout — no timeout value would have changed it.
+
+    Costs one bounded GET (1.5s ceiling, fails open), the same request the first run of any
+    session already makes, so this adds no capability doctor did not already exercise.
+
+    Skipped (with a SKIP row, not red) when ``enabled`` is False or when the ``CI`` environment
+    variable is set — the same gate ``check_for_update`` applies to the background notice.
+    A disabled check cannot be meaningfully diagnosed, and CI environments rarely have a human
+    to act on the result.
+    """
+    import os
+
+    from syncade.update_check import _parse, _text, manifest_once
+
+    if not enabled or os.environ.get("CI"):
+        return DoctorCheck(
+            "update check",
+            _SKIP,
+            "skipped: update check is disabled (check=false or CI is set)",
+        )
+    manifest = manifest_once(enabled=True)  # `enabled` already gated above
+    if manifest is None:
+        return DoctorCheck(
+            "update check",
+            _RED,
+            "cannot reach the update manifest — new releases will never be announced",
+            "on macOS python.org builds, run `Install Certificates.command` from your "
+            "Python's Applications folder; otherwise check network/proxy access to "
+            "raw.githubusercontent.com",
+        )
+    latest = _text(manifest.get("latest"))
+    if _parse(latest) is None:
+        return DoctorCheck("update check", _RED, f"manifest reachable but unusable: {latest!r}")
+    return DoctorCheck("update check", _OK, f"reachable; latest release is {latest}")

{syncade-0.7.1 → syncade-0.7.3}/src/syncade/update_check.py

@@ -18,11 +18,13 @@ could stop a run would be a remote kill switch, and a cheap one — one JSON lin
 write plus a release plus a publish, and needing no action from the operator to take effect.
 Print-only means the worst a compromised manifest can do is lie, which is visible and survivable.
 
-**It pings ONCE PER SESSION.** Not once per invocation and not once per N hours: the operator's
-rule is that a later invocation in the same window must not re-ping. The session is marked
-checked BEFORE the fetch, deliberately — marking after a *successful* fetch would make a flaky
-network cost a 1.5s stall on every invocation for the whole session, where marking first costs
-at most one missed notice.
+**The background check pings ONCE PER SESSION via ``check_for_update``.** Not once per
+invocation and not once per N hours: the operator's rule is that a later invocation in the same
+window must not re-ping. The session is marked checked BEFORE the fetch, deliberately — marking
+after a *successful* fetch would make a flaky network cost a 1.5s stall on every invocation for
+the whole session, where marking first costs at most one missed notice. Explicit operator
+invocations (``--update``, ``--doctor``) bypass the session gate and make their own fetch — they
+are diagnostic tools, not background checks, and the docs say so.
 
 Severity cannot come from PyPI's JSON, which has no such field. It comes from a manifest we host,
 so a version can be marked critical the day a hole is found rather than when the fix ships.
@@ -239,6 +241,36 @@ def _exclusive_check_and_mark(path: Path, key: str) -> bool:
         return _mark_checked(path, key)
 
 
+#: Sentinel distinguishing "not fetched yet" from a fetch that legitimately returned ``None``.
+_UNFETCHED = object()
+_manifest_cache: object = _UNFETCHED
+
+
+def manifest_once(*, enabled: bool) -> dict | None:
+    """The update manifest, fetched AT MOST ONCE per process. ``None`` when disabled or unreadable.
+
+    THE single egress point for the manifest. Three callers want it — the startup notice,
+    ``--update`` and ``--doctor`` — and before this each fetched independently, so a CLI
+    ``--doctor`` made two requests and ``--update`` fetched even with ``[update] check = false``.
+    That made `README`'s "one network call of its own, suppressible" FALSE, which is a published
+    privacy claim rather than a tidiness point. A blind panel raised it in all four rounds of one
+    dogfood and three producer attempts each fixed a different facet, because the fix is to remove
+    the duplication, not to patch each site.
+
+    ``enabled`` is a PARAMETER, not read here: this module is a stdlib-only leaf and importing the
+    config surface to answer it would end that. Callers hold the config; this holds the socket.
+
+    A failed fetch is cached too. A syncade process is short-lived, and retrying inside one would
+    reintroduce exactly the multiplication this exists to prevent.
+    """
+    global _manifest_cache
+    if not enabled:
+        return None
+    if _manifest_cache is _UNFETCHED:
+        _manifest_cache = _fetch(MANIFEST_URL)
+    return _manifest_cache
+
+
 def check_for_update(installed: str, *, enabled: bool = True) -> UpdateNotice | None:
     """One ping per session, or ``None``. Never raises, never blocks, never touches exit codes.
 
@@ -255,7 +287,7 @@ def check_for_update(installed: str, *, enabled: bool = True) -> UpdateNotice |
         # first invocations from all fetching simultaneously.
         if not _exclusive_check_and_mark(path, key):
             return None
-        return evaluate(_fetch(MANIFEST_URL), installed)
+        return evaluate(manifest_once(enabled=True), installed)
     except Exception:  # noqa: BLE001
         # The outermost guarantee, not a duplicate of the inner ones: `Path.home()` raises
         # RuntimeError with no $HOME and no passwd entry, and this runs on the review path where