syncade 0.6.2__tar.gz → 0.6.3__tar.gz

{syncade-0.6.2/src/syncade.egg-info → syncade-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syncade
-Version: 0.6.2
+Version: 0.6.3
 Summary: External blind multi-judge review orchestrator for AI-assisted coding
 Author-email: Syncade <build@syncade.ai>
 License-Expression: Apache-2.0
@@ -87,9 +87,15 @@ terminal or copy-paste between tools.
 ## Install
 
 ```bash
-uv tool install git+https://github.com/syncade-ai/syncade-ai.git   # recommended
+uv tool install syncade   # recommended
 # or with pip:
-pip install git+https://github.com/syncade-ai/syncade-ai.git
+pip install syncade
+```
+
+To track unreleased `main` instead of the latest release:
+
+```bash
+uv tool install git+https://github.com/syncade-ai/syncade-ai.git
 ```
 
 Then install the harness integration so you can invoke it as `/syncade`:
@@ -104,6 +110,24 @@ touching the directory and names every file at risk. Ordinary upgrades need no f
 recognises its own past output by content, not by filename. Use `--force-install` to overwrite
 deliberately; it still lists what it destroys.
 
+### Staying up to date
+
+The first time you run syncade in a new terminal or harness window, it checks once whether a
+newer release exists and prints a line if so. It only ever prints — it never blocks a run,
+changes an exit code, or fails one, and every error (offline, bad response) is silent. Nothing
+about your repo, diff, or run is sent. Turn it off with `syncade --config set update.check false`,
+or set `CI` in automation.
+
+```bash
+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
+checkout. A running process cannot switch to the version it just installed, so it exits and asks
+you to re-run.
+
 **Requirements**
 - **Python 3.11+**, on **macOS or Linux** (on Windows, use WSL).
 - **`codex`** (OpenAI), on your `PATH` and authenticated — required for the default

{syncade-0.6.2 → syncade-0.6.3}/README.md

@@ -57,9 +57,15 @@ terminal or copy-paste between tools.
 ## Install
 
 ```bash
-uv tool install git+https://github.com/syncade-ai/syncade-ai.git   # recommended
+uv tool install syncade   # recommended
 # or with pip:
-pip install git+https://github.com/syncade-ai/syncade-ai.git
+pip install syncade
+```
+
+To track unreleased `main` instead of the latest release:
+
+```bash
+uv tool install git+https://github.com/syncade-ai/syncade-ai.git
 ```
 
 Then install the harness integration so you can invoke it as `/syncade`:
@@ -74,6 +80,24 @@ touching the directory and names every file at risk. Ordinary upgrades need no f
 recognises its own past output by content, not by filename. Use `--force-install` to overwrite
 deliberately; it still lists what it destroys.
 
+### Staying up to date
+
+The first time you run syncade in a new terminal or harness window, it checks once whether a
+newer release exists and prints a line if so. It only ever prints — it never blocks a run,
+changes an exit code, or fails one, and every error (offline, bad response) is silent. Nothing
+about your repo, diff, or run is sent. Turn it off with `syncade --config set update.check false`,
+or set `CI` in automation.
+
+```bash
+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
+checkout. A running process cannot switch to the version it just installed, so it exits and asks
+you to re-run.
+
 **Requirements**
 - **Python 3.11+**, on **macOS or Linux** (on Windows, use WSL).
 - **`codex`** (OpenAI), on your `PATH` and authenticated — required for the default

{syncade-0.6.2 → syncade-0.6.3}/docs/config-reference.md

@@ -99,6 +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). |
 | `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). |
@@ -229,6 +230,21 @@ deleted — only bulky subprocess transcripts. CLI `--gc-keep` / `--gc-max-age-d
 | `keep` | int ≥ 0 | `20` | Newest N runs whose transcripts are always kept. |
 | `max_age_days` | int ≥ 0 | `0` | Additional age floor: a beyond-`keep` run is pruned only if also older than this. `0` disables the age floor. |
 
+## `[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.
+
+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.
+
+<!-- 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. |
+
 ## `[[checks]]` — `CheckConfig`
 
 Each `[[checks]]` block is one mechanical command gate run after the review. `blocking` checks can

{syncade-0.6.2 → syncade-0.6.3}/pyproject.toml

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

{syncade-0.6.2 → syncade-0.6.3}/src/syncade/__init__.py

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

{syncade-0.6.2 → syncade-0.6.3}/src/syncade/cli/__init__.py

@@ -492,11 +492,35 @@ def main(argv: list[str] | None = None) -> int:
     # re-inject after parsing. Also detect the forbidden prefix form (--repo before --config).
     _config_operands, _argv_parsed, _repo_prefix = _extract_config_operands(_argv)
     parser = build_parser()
+
+    # NOTE `--version` / `--help` never reach the notice below: argparse handles and exits
+    # during parse_args(). That is deliberate, and the brief says so rather than the code
+    # working around it. A pre-parse emit was tried and REVERTED — it could not pass `--quiet`
+    # through, could not honour a prompt answer (argparse exits first), and matched only the
+    # literal spellings, so argparse's own abbreviations (`--ver`, `--he`) still bypassed it.
+    # Matching those means reimplementing argparse's prefix matching: an enumeration, for the
+    # two flags least worth notifying on. `--version` in particular is what scripts call.
     args = parser.parse_args(_argv_parsed)
     if _config_operands is not None:
         # Merge any trailing non-flag operands that argparse still captured (e.g. `--config list
         # extra`) with the dash-prefixed ones we extracted before parsing.
         args.config = _config_operands + (args.config or [])
+
+    # FIRST thing after argv is parsed, deliberately — before the `--repo` shape check and
+    # before `validate_command_shape`, both of which return early. Placing it after them made
+    # every parsed-but-invalid invocation a silent third exception to "every invocation is
+    # eligible": `syncade --update --gc` reached syncade code, emitted nothing, marked nothing,
+    # and the NEXT valid command in that window printed the stale notice instead. This is the
+    # second blocker that one sentence produced, so the position is now structural rather than
+    # remembered: nothing can return ahead of it. It can only print — no exit code, no gate.
+    # Returns True in a terminal TTY when the operator chose to update now.
+    from syncade.cli.update_notice import emit_update_notice
+
+    _notice_root = Path(args.repo_root).expanduser() if args.repo_root else Path.cwd()
+    if emit_update_notice(quiet=args.quiet, repo_root=_notice_root):
+        from syncade.cli.update_mode import run_update
+
+        return run_update(cwd=_notice_root)
     # Reject the prefix form: --repo before --config set violates the suffix-only contract (D1).
     # Only applies to "set" — for other verbs (list/get) or no verb, _reject_config_mode_conflicts
     # will catch the --repo misuse with the appropriate "meaningful only with --config set" message.
@@ -515,6 +539,13 @@ def main(argv: list[str] | None = None) -> int:
     # --install-skill is a standalone local operation — copies bundled skill files into the
     # harness dirs. Dispatched after command-shape validation so --doctor/--quick combinations
     # are rejected before the filesystem mutation.
+    if args.update:
+        from syncade.cli.update_mode import run_update
+
+        # Pass the --repo-root hint so run_update() can resolve the actual git root and check
+        # for a live run there, rather than always defaulting to Path.cwd().
+        _update_cwd = Path(args.repo_root).expanduser() if args.repo_root else Path.cwd()
+        return run_update(cwd=_update_cwd)
     if args.install_skill is not None:
         from syncade.cli.install_skill import install_skill
 

{syncade-0.6.2 → syncade-0.6.3}/src/syncade/cli/install_skill.py

@@ -162,6 +162,22 @@ def _is_plain_name(key: str) -> bool:
     return bool(key) and key not in (".", "..") and "/" not in key and not Path(key).is_absolute()
 
 
+def resolve_homes(home: Path | None, codex_home: Path | None) -> tuple[Path, Path]:
+    """The ONE place harness home directories are resolved.
+
+    Extracted in PR-h-field-07 because it was not one place: the installer honoured
+    ``CODEX_HOME`` while the new runtime skill-status path re-derived ``~/.codex`` by hand. A
+    Codex skill installed under a custom home then read as ABSENT, so no stale notice fired and
+    ``--update`` skipped re-installing it — the exact drift this PR exists to close, hidden by
+    the copy. Both reviewers flagged it independently.
+    """
+    home = home or Path.home()
+    if codex_home is None:
+        env_cx = os.environ.get("CODEX_HOME")
+        codex_home = Path(env_cx) if env_cx else home / ".codex"
+    return home, codex_home
+
+
 def _dest(harness: str, home: Path, codex_home: Path) -> Path:
     if harness == "claude":
         return home / ".claude" / "skills" / "syncade"
@@ -336,10 +352,7 @@ def install_skill(
         )
         return CLI_USAGE_ERROR
 
-    home = home or Path.home()
-    if codex_home is None:
-        env_cx = os.environ.get("CODEX_HOME")
-        codex_home = Path(env_cx) if env_cx else home / ".codex"
+    home, codex_home = resolve_homes(home, codex_home)
 
     harnesses = ["claude", "codex"] if target == "all" else [target]
     plan = [

{syncade-0.6.2 → syncade-0.6.3}/src/syncade/cli/parser.py

@@ -306,6 +306,16 @@ def build_parser() -> argparse.ArgumentParser:
         "Leaves the instant config / PATH / worktree / branch / plan / cost checks. The "
         "skipped legs are reported as 'skipped', never as passed.",
     )
+    parser.add_argument(
+        "--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 "
+        "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.",
+    )
     parser.add_argument(
         "--install-skill",
         nargs="?",

syncade-0.6.3/src/syncade/cli/skill_status.py

@@ -0,0 +1,142 @@
+"""Is the operator's INSTALLED skill still the one this package ships? — PR-h-field-07 item 3.
+
+Read-only. It classifies; it never writes, and it never touches the destination beyond reading
+the files the current bundle names.
+
+**Staleness is decided by CONTENT, not by a recorded version number**, which is a deliberate
+departure from the brief and the safer of the two designs for three separate reasons:
+
+1. *The record cannot carry a version without being reshaped.* ``.syncade-install.json`` is
+   exactly ``{"files": {…}}`` and is protected by a self-hash over its canonical BYTES; any extra
+   top-level key fails it closed (measured). Failing closed means "we can prove nothing", which
+   makes every differing file the operator's — so the very installs this feature exists to help
+   would start REFUSING to upgrade.
+2. *It would break every existing install.* Records already on disk are the old shape. Accepting
+   both shapes means two canonical forms and two self-hash paths, in the one structure that took
+   three consecutive dogfood rounds to make bypass-proof.
+3. *Content is a strictly better signal anyway.* The documented install has been an unpinned
+   ``git+https://`` URL, so two installs reporting the same ``__version__`` routinely ship
+   different skill files. A version compare is blind to exactly that case; hashes are not.
+
+The three states the brief asks for fall straight out of data that already exists — what the
+package would write now, versus what is on disk, versus what the record says we wrote.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from syncade.cli.install_skill import (
+    _MANIFEST,
+    _bundle,
+    _dest,
+    _read_manifest,
+    _sha,
+    resolve_homes,
+)
+
+HARNESSES = ("claude", "codex")
+
+#: ``absent``   nothing installed here — not a problem, and never reported.
+#: ``in_sync``  every packaged file is present and byte-identical.
+#: ``stale``    ours, unmodified, but from an older package. THE actionable state.
+#: ``modified`` at least one file is not what we wrote — the operator's. Never nagged about.
+#: ``unknown``  files differ and there is no usable record, so ownership is unproven.
+Status = Literal["absent", "in_sync", "stale", "modified", "unknown"]
+
+
+@dataclass(frozen=True)
+class SkillStatus:
+    harness: str
+    status: Status
+    path: Path
+
+
+def _classify(dest: Path, bundle: dict[str, bytes], record: dict[str, str]) -> Status:
+    # The self-hash entry is the record vouching for itself, not a file we wrote; excluding it
+    # is what makes `known` mean "files we can actually account for".
+    known = {k: v for k, v in record.items() if k != _MANIFEST}
+    differing: list[str] = []
+
+    for name, packaged in bundle.items():
+        try:
+            on_disk = (dest / name).read_bytes()
+        except OSError:
+            # Missing or unreadable. If we recorded writing it, someone removed it — theirs.
+            # If we did not, the file is new in this package version — that is staleness.
+            if name in known:
+                return "modified"
+            differing.append(name)
+            continue
+        if _sha(on_disk) != _sha(packaged):
+            differing.append(name)
+            # `known and` is load-bearing. An ABSENT record proves nothing, so it cannot
+            # convict the operator — without this guard every recordless install (which is
+            # every install predating the current installer, including both of mine) is
+            # misreported as operator-edited and silently skipped. Only a record that
+            # CONTRADICTS the file on disk is evidence of an edit.
+            if known and known.get(name) != _sha(on_disk):
+                # Returns immediately so a mixed tree is "modified" rather than "stale": an
+                # update notice aimed at someone's own edits is worse than no notice at all.
+                return "modified"
+
+    # Any entry in the destination that neither the current bundle nor the installer manifest
+    # accounts for is the operator's. A mixed tree — bundled files that look stale PLUS an
+    # extra file we never wrote — resolves to "modified" (silent) rather than "stale"
+    # (actionable): pointing at --install-skill for a tree it would immediately refuse is
+    # worse than no notice. The conservative direction misses a stale notice; the other
+    # costs the operator's trust.
+    #
+    # Exception: a file proven ours by the install record (hash matches the recorded hash) is
+    # syncade-owned — it was in an older bundle but was since removed or renamed. Treat it as
+    # a stale difference, not an operator modification, so --install-skill can fix it.
+    try:
+        for entry in dest.iterdir():
+            if entry.name not in bundle and entry.name != _MANIFEST:
+                if entry.is_file() and known:
+                    try:
+                        on_disk_hash = _sha(entry.read_bytes())
+                    except OSError:
+                        return "modified"
+                    if known.get(entry.name) == on_disk_hash:
+                        differing.append(entry.name)
+                        continue
+                return "modified"
+    except OSError:
+        pass  # cannot scan dest; treat as clean and continue
+
+    if not differing:
+        return "in_sync"
+    # Every difference is explained by the record, so this is our own older output — unless
+    # there is no record, in which case we can prove nothing and must not claim it is ours.
+    return "stale" if known else "unknown"
+
+
+def skill_status(
+    harness: str, *, home: Path | None = None, codex_home: Path | None = None
+) -> SkillStatus:
+    """Classify one harness's installed skill. Never raises."""
+    # Resolved by the installer's own function, never re-derived here: an independent default
+    # is how CODEX_HOME got ignored at runtime while being honoured at install time.
+    home, codex_home = resolve_homes(home, codex_home)
+    dest = _dest(harness, home, codex_home)
+    try:
+        if not dest.is_dir():
+            return SkillStatus(harness, "absent", dest)
+        return SkillStatus(harness, _classify(dest, _bundle(harness), _read_manifest(dest)), dest)
+    except Exception:  # noqa: BLE001
+        # Same contract as the update check: a skill-drift notice must never be able to fail a
+        # run. An unreadable destination or a missing packaged bundle reads as "nothing to say".
+        return SkillStatus(harness, "absent", dest)
+
+
+def stale_skills(*, home: Path | None = None, codex_home: Path | None = None) -> list[SkillStatus]:
+    """Every installed harness whose skill is out of date or of unproven origin.
+
+    ``absent``/``in_sync``/``modified`` are all silent — the first two have nothing to say, and
+    the third is the operator's own work.
+    """
+    found = [skill_status(h, home=home, codex_home=codex_home) for h in HARNESSES]
+    return [s for s in found if s.status in ("stale", "unknown")]

syncade-0.6.3/src/syncade/cli/update_mode.py

@@ -0,0 +1,226 @@
+"""``syncade --update`` — PR-h-field-07 item 5.
+
+**A process cannot upgrade itself.** Its modules are already imported; if the files change
+underneath it, anything imported LATER comes back new while everything already loaded stays old.
+A half-and-half process is worse than either version, so this upgrades and then EXITS, asking to
+be re-run. `os.execv` was considered and rejected: replacing an executable mid-replacement, plus
+argv preservation and loop-guarding, for a cosmetic gain. In a terminal the re-run is one
+keystroke; in a harness the skill does it, which is what makes it seamless from the chat side.
+
+**Install-method detection PROVES or REFUSES; it never guesses.** The method is read from where
+``syncade`` actually lives — a marker file inside its own install tree — not from a table of
+default paths, which vary with ``UV_TOOL_DIR``, ``PIPX_HOME``, XDG settings and platform. When no
+marker is found, this prints the manual command and says plainly that it could not tell. That is
+the PR-h-04.5 shape one layer up: refuse rather than act on an unproven belief.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import syncade
+from syncade.exit_codes import SUCCESS, WORKTREE_ERROR
+from syncade.process import SubprocessError, run_subprocess
+
+_UPGRADE_TIMEOUT = 300.0
+#: How far up from ``syncade/__init__.py`` an install marker can sit. A venv layout is
+#: ``<root>/lib/python3.x/site-packages/syncade/__init__.py`` — five parents to the root; the
+#: extra headroom costs nothing and covers layouts that nest one deeper.
+_MARKER_DEPTH = 7
+
+
+@dataclass(frozen=True)
+class InstallMethod:
+    kind: str  # "uv" | "pipx" | "source" | "unknown"
+    command: list[str] | None  # the upgrade to run, or None when we must not run anything
+    where: Path | None
+
+
+def detect_install() -> InstallMethod:
+    """Prove how syncade got here by finding a marker inside its own install tree."""
+    start = Path(syncade.__file__).resolve().parent
+    for parent in [start, *start.parents][:_MARKER_DEPTH]:
+        if (parent / "uv-receipt.toml").is_file():
+            return InstallMethod("uv", ["uv", "tool", "upgrade", "syncade"], parent)
+        if (parent / "pipx_metadata.json").is_file():
+            return InstallMethod("pipx", ["pipx", "upgrade", "syncade"], parent)
+        # An ENVIRONMENT ends the walk before any enclosing checkout can claim it. A plain
+        # venv install commonly lives at `<checkout>/.venv/lib/pythonX/site-packages/syncade`,
+        # and without this the ancestor `pyproject.toml` made it read as a source checkout — so
+        # `--update` refused with "use git", which would not update the installed package at
+        # all. Checked AFTER the uv/pipx markers, which sit at this same root and are more
+        # 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)
+        # 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
+        # coincidental pyproject.toml higher up cannot claim it.
+        pyproject = parent / "pyproject.toml"
+        if pyproject.is_file() and 'name = "syncade"' in _read(pyproject):
+            return InstallMethod("source", None, parent)
+    return InstallMethod("unknown", None, None)
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def live_run(cwd: Path) -> Path | None:
+    """A run in ``cwd`` that is still going, or ``None``.
+
+    Upgrading underneath a running review is the same half-and-half hazard from outside the
+    process: the reviewers and producer it has yet to spawn would load the new code while the
+    orchestrator that planned them is the old one. Scoped to this repo's ``.syncade/runs/``,
+    which is where the breadcrumb lives; a run in some other checkout is not visible here and
+    the message says so rather than implying a global guarantee.
+    """
+    import json
+
+    from syncade.run_status import STATUS_FILENAME, is_stale_running
+
+    runs = cwd / ".syncade" / "runs"
+    if not runs.is_dir():
+        return None
+    for status_path in sorted(runs.glob(f"*/{STATUS_FILENAME}")):
+        try:
+            status = json.loads(status_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        # `is_stale_running` is true for a HARD-KILLED run, i.e. running-but-dead. A live run is
+        # running and NOT stale — reusing the existing predicate rather than re-deriving
+        # liveness, so the two cannot drift apart on what "still going" means.
+        if isinstance(status, dict) and status.get("state") == "running":
+            if not is_stale_running(status):
+                return status_path.parent
+    return None
+
+
+def _syncade_argv() -> list[str]:
+    # Use sys.executable rather than shutil.which("syncade"): the latter resolves against
+    # ambient PATH and would invoke a shadow when the operator ran syncade by absolute path
+    # or from a venv while a different syncade is earlier on PATH. sys.executable is the
+    # interpreter of the upgraded install, so the subprocess always runs the right package.
+    return [sys.executable, "-m", "syncade"]
+
+
+def _resync_skills(out) -> bool:
+    """Re-install every skill the operator ALREADY has, using the UPGRADED code.
+
+    A subprocess, not an in-process call: this process is still running the OLD package, so
+    installing from here would faithfully write the OLD skill files — the exact drift the
+    upgrade is meant to close. Harnesses with no skill installed are skipped rather than gaining
+    one they never asked for.
+
+    Returns True when every installed skill was successfully re-synced, False when at least one
+    was refused (so the caller can propagate the partial failure rather than claiming success).
+    """
+    from syncade.cli.skill_status import HARNESSES, skill_status
+
+    all_ok = True
+    for harness in HARNESSES:
+        if skill_status(harness).status == "absent":
+            continue
+        result = subprocess.run(  # noqa: S603
+            [*_syncade_argv(), "--install-skill", harness],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == SUCCESS:
+            print(f"[syncade] re-installed the {harness} skill", file=out)
+        else:
+            all_ok = False
+            # `--install-skill` refuses rather than destroying — a non-zero here usually means
+            # the operator edited their copy or the skill has no install record (unknown state).
+            # Tell them the exact command to force a resync with their explicit consent.
+            print(
+                f"[syncade] the {harness} skill was NOT re-installed — syncade refused rather "
+                f"than overwrite it. Run `syncade --install-skill {harness} --force-install` "
+                "to sync it regardless.",
+                file=out,
+            )
+    return all_ok
+
+
+def run_update(*, cwd: Path | None = None, out=None) -> int:
+    """Upgrade syncade in place, then exit asking to be re-run."""
+    out = out or sys.stderr
+    cwd = cwd or Path.cwd()
+
+    # Resolve to the actual git repo root so live_run() does not miss a run when invoked
+    # from a subdirectory — `.syncade/runs/` is at the root, not at the invocation directory.
+    # Fails open: if discovery raises (not in a git repo, git not on PATH, etc.) we fall back
+    # to cwd and check there, which is correct behaviour for a non-repo invocation.
+    try:
+        from syncade.snapshot import discover_repo_root
+
+        cwd = discover_repo_root(cwd)
+    except Exception:  # noqa: BLE001
+        pass
+
+    running = live_run(cwd)
+    if running is not None:
+        print(
+            f"[syncade] refusing to update: a run is still going ({running.name}).\n"
+            "          Upgrading underneath it would leave the run half-old and half-new.\n"
+            "          Wait for it to finish, then run `syncade --update` again.",
+            file=out,
+        )
+        return WORKTREE_ERROR
+
+    method = detect_install()
+    if method.kind == "source":
+        print(
+            f"[syncade] this syncade runs from a source checkout at {method.where}.\n"
+            "          Update it with git, not a package manager.",
+            file=out,
+        )
+        return WORKTREE_ERROR
+    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",
+            file=out,
+        )
+        return WORKTREE_ERROR
+
+    print(f"[syncade] {' '.join(method.command)}", file=out)
+    # `SubprocessResult.returncode` — NOT `exit_code`, which does not exist. The first version
+    # read `exit_code` and every test passed, because the test double was hand-written with that
+    # attribute: the fake encoded the belief instead of the type, so the suite and the mutation
+    # run both validated the same wrong contract. A real upgrade would have raised AttributeError
+    # AFTER upgrading, losing the skill re-sync and the re-run instruction. The tests now build
+    # the real SubprocessResult, so a rename breaks them instead of hiding in them.
+    try:
+        result = run_subprocess(method.command, timeout=_UPGRADE_TIMEOUT)
+    except SubprocessError as exc:
+        # `uv`/`pipx` absent from PATH, or unlaunchable. Reported, not escaped: an operator who
+        # ran --update deserves to be told the package manager is missing.
+        print(f"[syncade] update failed: {exc}", file=out)
+        return WORKTREE_ERROR
+    if result.returncode != 0:
+        print(
+            f"[syncade] update failed (exit {result.returncode}). Nothing was changed.\n"
+            + (result.stderr.strip() or result.stdout.strip())[:800],
+            file=out,
+        )
+        return WORKTREE_ERROR
+
+    skills_ok = _resync_skills(out)
+    print(
+        "[syncade] updated. Re-run your command to use the new version — this process is\n"
+        "          still running the old one and cannot switch to it.",
+        file=out,
+    )
+    if not skills_ok:
+        # The package upgrade succeeded but at least one skill resync was refused. The operator
+        # now has a fresh CLI and a stale or recordless skill — not a clean update end to end.
+        return WORKTREE_ERROR
+    return SUCCESS