syncade 0.6.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syncade
-Version: 0.6.2
+Version: 0.7.0
 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
@@ -263,7 +287,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 **no network calls of its own**; its only egress is the provider CLIs you already authenticated and the test/check commands you configure.
+- 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.
 
 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
@@ -278,12 +302,12 @@ Early access. These are measured, not suspected.
   Both findings were real. If a SHIP arrives over code you did not change since a NO-SHIP, treat
   it as the weaker signal — compare the verdict to what the *code* changed, not to the previous
   verdict.
-- **NO-SHIP runs keep their worktrees.** They are preserved so you can inspect what a reviewer
-  saw, and `syncade --gc` deliberately will not reclaim a run that is still resumable — so
-  `<worktree_base>` grows, and each worktree is a full checkout. It reached 4.4 GB on this
-  machine before a cleanup. Point `worktree_base` somewhere you do not mind, delete old run
-  directories once you are done with them, and run `git worktree prune` afterwards: removing the
-  directory does not remove git's registration of it.
+- **Worktrees accumulate under `<worktree_base>`.** NO-SHIP runs keep their worktrees for
+  inspection. `syncade --gc` removes worktrees once a run can no longer plausibly be resumed —
+  controlled by `gc.worktree_max_age_days` (default 14 days), which applies even to runs that are
+  technically still resume-eligible. It reached 4.4 GB on this machine before a cleanup. Point
+  `worktree_base` somewhere you do not mind, and run `git worktree prune` after manual removals:
+  removing the directory does not remove git's registration of it.
 - **A hard-killed run keeps almost all of what its reviewers had written.** Reviewer stdout and
   stderr are copied to `<round>/<name>.stdout` / `<round>/<name>.stderr` as the child produces
   them, rather than held in memory until it exits, so a run ended by `SIGKILL` (or a machine

{syncade-0.6.2 → syncade-0.7.0}/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
@@ -233,7 +257,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 **no network calls of its own**; its only egress is the provider CLIs you already authenticated and the test/check commands you configure.
+- 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.
 
 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
@@ -248,12 +272,12 @@ Early access. These are measured, not suspected.
   Both findings were real. If a SHIP arrives over code you did not change since a NO-SHIP, treat
   it as the weaker signal — compare the verdict to what the *code* changed, not to the previous
   verdict.
-- **NO-SHIP runs keep their worktrees.** They are preserved so you can inspect what a reviewer
-  saw, and `syncade --gc` deliberately will not reclaim a run that is still resumable — so
-  `<worktree_base>` grows, and each worktree is a full checkout. It reached 4.4 GB on this
-  machine before a cleanup. Point `worktree_base` somewhere you do not mind, delete old run
-  directories once you are done with them, and run `git worktree prune` afterwards: removing the
-  directory does not remove git's registration of it.
+- **Worktrees accumulate under `<worktree_base>`.** NO-SHIP runs keep their worktrees for
+  inspection. `syncade --gc` removes worktrees once a run can no longer plausibly be resumed —
+  controlled by `gc.worktree_max_age_days` (default 14 days), which applies even to runs that are
+  technically still resume-eligible. It reached 4.4 GB on this machine before a cleanup. Point
+  `worktree_base` somewhere you do not mind, and run `git worktree prune` after manual removals:
+  removing the directory does not remove git's registration of it.
 - **A hard-killed run keeps almost all of what its reviewers had written.** Reviewer stdout and
   stderr are copied to `<round>/<name>.stdout` / `<round>/<name>.stderr` as the child produces
   them, rather than held in memory until it exits, so a run ended by `SIGKILL` (or a machine

{syncade-0.6.2 → syncade-0.7.0}/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). |
@@ -221,13 +222,33 @@ any spend.
 ## `[gc]` — `GcConfig`
 
 Governs both the per-loop auto-prune and an explicit `syncade --gc`. Run directories are never
-deleted — only bulky subprocess transcripts. CLI `--gc-keep` / `--gc-max-age-days` override these.
+deleted. `keep` / `max_age_days` prune bulky subprocess transcripts; `worktree_max_age_days`
+removes stale worktrees under `worktree_base`, which is a separate retention tier because a
+worktree is reconstructible from a recorded SHA. CLI `--gc-keep` / `--gc-max-age-days` override
+the first two; the worktree bound is config-only (set it with
+`syncade --config set gc.worktree_max_age_days N`).
 
 <!-- config-fields: GcConfig -->
 | Field | Type | Default | What it does |
 |---|---|---|---|
 | `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. |
+| `worktree_max_age_days` | int ≥ 0 | `14` | Days a run's **worktree** is kept, after which it is removed — including while the run is still resume-eligible. This is the ONLY rule that selects a worktree: one is never removed because its transcripts became prunable, so a young worktree you are still inspecting survives a busy week of runs. Separate from `max_age_days`, which gates transcripts only — a worktree is reconstructible from the SHA the run records, so removing one costs a `git worktree add` and never history. `0` disables the bound and restores the previous never-ending protection. |
+
+## `[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`
 

{syncade-0.6.2 → syncade-0.7.0}/docs/how-to-use.md

@@ -450,9 +450,10 @@ below** before you commit anything yourself.
 - **Loop mode refuses a tracked-modified dirty tree** unless you pass `--force-dirty`. Single-pass
   review does not refuse: reviewers see committed HEAD, so uncommitted work is invisible to them.
 - **`<worktree_base>` grows.** NO-SHIP runs keep their worktrees so you can inspect what a reviewer
-  saw, and `syncade --gc` deliberately will not reclaim a run that is still resumable. It reached
-  4.4 GB on this machine before a cleanup. Point `worktree_base` somewhere you don't mind, delete
-  old run directories when you're done, and run `git worktree prune` afterward — removing the
+  saw. `syncade --gc` removes worktrees once a run can no longer plausibly be resumed, controlled by
+  `gc.worktree_max_age_days` (default 14 days) — this applies even to runs that remain
+  resume-eligible. It reached 4.4 GB on this machine before a cleanup. Point `worktree_base`
+  somewhere you don't mind and run `git worktree prune` after manual removals — removing the
   directory does not remove git's registration of it.
 - **Run artifacts are never deleted**, only transcripts are pruned. `syncade --metrics` is derived
   from that tree and would lose your history otherwise.

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

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "syncade"
-version = "0.6.2"
+version = "0.7.0"
 description = "External blind multi-judge review orchestrator for AI-assisted coding"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -73,6 +73,7 @@ syncade = ["templates/*.md", "templates/presets/*.toml", "skills/*/*.md"]
 testpaths = ["tests"]
 markers = [
     "smoke: end-to-end integration tests that shell out to real provider CLIs (opt-in via `pytest -m smoke`)",
+    "real_worktree_base: opt out of the autouse worktree-base isolation, for the drift tests that must assert the REAL default (PR-h-12 item 1b)",
 ]
 addopts = "-m 'not smoke'"
 

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

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

{syncade-0.6.2 → syncade-0.7.0}/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.7.0}/src/syncade/cli/gc_mode.py

@@ -70,7 +70,15 @@ def _run_gc(args) -> int:
     # worktree_base: clean the base the runs actually use (config.worktree_base / --worktree-base),
     # not the hardcoded default — else a relocated base leaves worktree leftovers uncollected.
     plan = plan_gc(
-        repo_root, keep=keep, max_age_days=max_age_days, worktree_base=config.worktree_base
+        repo_root,
+        keep=keep,
+        max_age_days=max_age_days,
+        # Tier 3 has no CLI flag on purpose: it is a machine-level retention preference set once,
+        # not a per-invocation choice, and `--config set gc.worktree_max_age_days N` already
+        # reaches it. Another flag would need parser, validation, docs and two drift-test entries
+        # for a knob nobody tunes twice.
+        worktree_max_age_days=config.gc.worktree_max_age_days,
+        worktree_base=config.worktree_base,
     )
     report = execute_gc(plan, dry_run=args.gc_dry_run, repo_root=repo_root)
 

{syncade-0.6.2 → syncade-0.7.0}/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.7.0}/src/syncade/cli/metrics_mode.py

@@ -17,6 +17,7 @@ from syncade import billing
 from syncade.billing import Billing
 from syncade.exit_codes import SUCCESS, WORKTREE_ERROR
 from syncade.metrics.aggregate import backfill
+from syncade.metrics.findings import blocker_curve, consensus_stats
 from syncade.metrics.schema import open_db
 from syncade.snapshot import SnapshotError, discover_repo_root
 
@@ -238,7 +239,10 @@ def render_report(conn: sqlite3.Connection, last_n: int | None = None) -> str:
         "SELECT COALESCE(SUM(blockers),0), COALESCE(SUM(minors),0), COALESCE(SUM(nits),0), "
         "COALESCE(SUM(dismissed),0) FROM runs"
     ).fetchone()
-    rounds = conn.execute("SELECT COALESCE(SUM(rounds_executed),0) FROM runs").fetchone()[0]
+    # From `rounds`, not `runs.rounds_executed`: the latter comes from loop-manifest.json, so an
+    # interrupted run with perfectly good round artifacts reported "rounds: 0 total" while the
+    # blocker curve simultaneously knew round 0 had happened.
+    rounds = conn.execute("SELECT COUNT(*) FROM rounds").fetchone()[0]
     handoffs, decisions = conn.execute(
         "SELECT COALESCE(SUM(handoff),0), COALESCE(SUM(decision_needed),0) FROM runs"
     ).fetchone()
@@ -294,11 +298,86 @@ def render_report(conn: sqlite3.Connection, last_n: int | None = None) -> str:
     if reviewer_rows:
         lines.append("  reviewers by model (findings/wall-clock):")
         for provider, model, findings, run_count, wall, tok in reviewer_rows:
-            label = f"{provider}/{model}" if model else (provider or "?")
+            # A row with no model is reported as UNKNOWN, never as a bare provider. A bare
+            # provider reads like a panel that had no model, which is a claim we cannot make;
+            # "unknown" says the thing that is actually true. (No such row exists in this
+            # corpus today — every recorded panel carries both — but the renderer must not be
+            # the reason a future one silently looks answered.)
+            label = f"{provider}/{model}" if model else f"{provider or '?'}/unknown"
             lines.append(
                 f"    {label:24} findings={findings} runs={run_count} "
                 f"wall={int(wall)}s tok={int(tok)}"
             )
+        # Rounds whose panel was never recorded are INVISIBLE in the table above, which is worse
+        # than being wrong: anyone dividing findings by runs gets a denominator quietly missing
+        # them. They come from runs interrupted before the loop terminator wrote a manifest, so
+        # nothing ever summarised their reviewers. Never guessed — the configured roster is not
+        # evidence of what a killed run actually dispatched.
+        #
+        # DO NOT write a measured count here. This comment said "all 49" until the release audit
+        # found the line below printing 22: excluding known-empty panels changed the number and
+        # the prose kept the old one. A count in a comment is a measurement with no test reading
+        # it, which is the same defect this release had to fix in its own CHANGELOG.
+
+    # OUTSIDE the `if reviewer_rows` block on purpose. Nested inside it, a corpus where EVERY
+    # panel is unknown printed no warning at all — the one corpus that most needs it, silent.
+    # panel_source='unknown' means no manifest had a `reviewers` key for that round. This is
+    # independent of blockers_source: a manifest can record a blocker count without a reviewer
+    # list, and a no-dispatch round (no_changes_to_review) has panel_source='recorded' and
+    # panel_size=0 — explicitly empty, not unknown.
+    unknown_rounds, total_rounds = conn.execute(
+        "SELECT COALESCE(SUM(CASE WHEN panel_source = 'unknown' THEN 1 ELSE 0 END), 0), "
+        "COUNT(*) FROM rounds"
+    ).fetchone()
+    if unknown_rounds:
+        lines.append(
+            f"  {unknown_rounds} of {total_rounds} rounds record no reviewer panel "
+            f"(no manifest evidence; excluded from consensus)"
+        )
+    manifest_only, unknown_only = conn.execute(
+        "SELECT "
+        "COALESCE(SUM(CASE WHEN blockers_source='manifest' THEN 1 ELSE 0 END), 0), "
+        "COALESCE(SUM(CASE WHEN blockers_source='unknown' THEN 1 ELSE 0 END), 0) "
+        "FROM rounds "
+        "WHERE NOT (panel_source='recorded' AND panel_size=0 AND blockers=0)"
+    ).fetchone()
+    if manifest_only:
+        lines.append(
+            f"  {manifest_only} of {total_rounds} rounds have no synthesizer artifact; their "
+            f"blocker counts come from round manifests and carry no provenance"
+        )
+    if unknown_only:
+        lines.append(
+            f"  {unknown_only} of {total_rounds} rounds have no blocker evidence "
+            f"(killed/interrupted before any artifact or manifest); "
+            f"excluded from the blocker curve"
+        )
+
+    consensus = consensus_stats(conn)
+    if consensus is not None:
+        total, single = consensus
+        lines.append(
+            f"  consensus: {single} of {total} active blockers ({single / total:.0%}) were "
+            f"raised by exactly ONE reviewer"
+        )
+        lines.append("    (over runs with a multi-reviewer panel; what a second reviewer earns)")
+
+    curve = blocker_curve(conn)
+    if curve:
+        # Density, never the raw total alone. The blocker count falls steeply across rounds and
+        # reads as convergence; it is SURVIVORSHIP — fewer runs reach each round, so the
+        # denominator falls with it. This repo published the raw sequence as convergence once
+        # and had to correct it, so the renderer shows both numbers and the per-round rate.
+        lines.append(
+            "  blockers by round (artifact- or manifest-backed only; "
+            "killed runs with no evidence excluded):"
+        )
+        for round_index, blockers, rounds in curve:
+            density = blockers / rounds if rounds else 0.0
+            lines.append(
+                f"    round {round_index}: {blockers} blockers over {rounds} rounds "
+                f"({density:.2f}/round)"
+            )
 
     if last_n:
         ids = [

{syncade-0.6.2 → syncade-0.7.0}/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="?",
@@ -371,22 +381,25 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--gc",
         action="store_true",
-        help="Run a one-shot maintenance pass. Retention is TWO-TIER: run "
+        help="Run a one-shot maintenance pass. Retention is FOUR-TIER: run "
         "history is kept FOREVER (loop-manifest.json, findings.md, run-init.json, "
-        "round manifests, summaries) and only the bulky subprocess transcripts "
-        "(round-*/*.stdout, *.stderr - 90%% of the corpus) are pruned, for runs "
-        "beyond --gc-keep and any --gc-max-age-days floor. NO run directory is "
-        "ever deleted: .syncade/metrics.db is a derived view over .syncade/runs/, "
-        "so deleting a run would destroy its history the next time that view "
-        "rebuilds. Also removes matching <worktree_base>/<run-id>/ worktree leftovers "
-        "whose directory identity still matches the GC plan, and safely reaps "
-        "orphaned reviewer/producer subprocesses whose working dir is INSIDE a "
-        "worktree being removed. Runs also auto-prune their transcripts at the "
-        "start of every fresh loop, so --gc is for worktree/process cleanup and "
-        "one-off maintenance rather than routine disk hygiene. Resume-eligible "
-        "runs are ALWAYS protected (they keep even their transcripts); non-run "
-        "state (config.toml, last-reviewed.json, draft-spec-*.md) is never "
-        "touched. "
+        "round manifests, summaries); transcripts (round-*/*.stdout, *.stderr - "
+        "90%% of the corpus) are pruned beyond --gc-keep and any --gc-max-age-days "
+        "floor; worktrees are removed once a run can no longer plausibly be resumed "
+        "(worktrees are reconstructible from the recorded SHA, so removing one "
+        "costs a git worktree add, never history) — resume-eligible runs keep their "
+        "worktree while younger than gc.worktree_max_age_days (default 14 days, "
+        "set via syncade --config set gc.worktree_max_age_days N); "
+        "and metrics.db is a droppable derived view. NO run directory is ever "
+        "deleted: .syncade/metrics.db is a derived view over .syncade/runs/, so "
+        "deleting a run would destroy its history the next time that view rebuilds. "
+        "Also removes matching <worktree_base>/<run-id>/ worktree leftovers whose "
+        "directory identity still matches the GC plan, and safely reaps orphaned "
+        "reviewer/producer subprocesses whose working dir is INSIDE a worktree "
+        "being removed. Runs also auto-prune their transcripts at the start of "
+        "every fresh loop, so --gc is for worktree/process cleanup and one-off "
+        "maintenance rather than routine disk hygiene. Non-run state "
+        "(config.toml, last-reviewed.json, draft-spec-*.md) is never touched. "
         "Mutually exclusive with PR_DOC, --selfcheck, --auth-check, "
         "--spec-audit, --draft-spec, --resume, --openspec.",
     )