syncade 0.6.3__tar.gz → 0.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syncade
-Version: 0.6.3
+Version: 0.7.1
 Summary: External blind multi-judge review orchestrator for AI-assisted coding
 Author-email: Syncade <build@syncade.ai>
 License-Expression: Apache-2.0
@@ -287,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
@@ -302,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.3 → syncade-0.7.1}/README.md

@@ -257,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
@@ -272,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.3 → syncade-0.7.1}/docs/config-reference.md

@@ -222,13 +222,18 @@ 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`
 

{syncade-0.6.3 → syncade-0.7.1}/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.3 → syncade-0.7.1}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "syncade"
-version = "0.6.3"
+version = "0.7.1"
 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.3 → syncade-0.7.1}/src/syncade/__init__.py

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

{syncade-0.6.3 → syncade-0.7.1}/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.3 → syncade-0.7.1}/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.3 → syncade-0.7.1}/src/syncade/cli/parser.py

@@ -381,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.",
     )

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

@@ -24,8 +24,12 @@ 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
 
 _UPGRADE_TIMEOUT = 300.0
+#: Reading one version string out of a fresh interpreter. Generous, because a cold venv
+#: import is slower than it looks; short, because we already hold the operator's terminal.
+_VERSION_TIMEOUT = 60.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.
@@ -149,6 +153,86 @@ def _resync_skills(out) -> bool:
     return all_ok
 
 
+def _installed_version() -> str | None:
+    """The version on disk NOW, or ``None`` when it cannot be established.
+
+    It CANNOT be ``syncade.__version__``: this process imported that before the upgrade ran, so
+    it is by definition the old number. A fresh interpreter re-reads the metadata the upgrade
+    just rewrote, and ``sys.executable`` is the tool venv's own python under both uv and pipx —
+    precisely the environment that changed.
+
+    ``None`` means "could not verify", which is deliberately NOT the same as "did not change":
+    the caller must not turn an unreadable version into a failure report.
+    """
+    try:
+        result = run_subprocess(
+            # `-I` (isolated) is load-bearing, not tidiness. Without it the probe inherits
+            # PYTHONPATH and the user site dir, so a `sitecustomize` on that path runs inside
+            # the answer and can emit stdout before OR after the version print.
+            # `-I` keeps the venv's own site-packages, so `importlib.metadata` still finds
+            # the install (verified) — but it does NOT suppress `sitecustomize.py` that lives
+            # in those site-packages. An atexit hook registered there (syncade ships such a
+            # shim for worktree imports) can append a version-shaped line AFTER the real one.
+            # `os._exit(0)` bypasses all atexit handlers: the process terminates immediately
+            # after `os.write`, so nothing can append to our stdout (reproduced: a hostile
+            # sitecustomize turned "0.7.0" into "0.7.0\n99.0.0" before this fix).
+            # `os.write` is used instead of `print` because `os._exit` skips stdio flushing;
+            # an unbuffered syscall guarantees the version byte reaches the pipe.
+            [
+                sys.executable,
+                "-I",
+                "-c",
+                "import importlib.metadata as m, os; "
+                "os.write(1, (m.version('syncade') + '\\n').encode()); "
+                "os._exit(0)",
+            ],
+            timeout=_VERSION_TIMEOUT,
+        )
+    except SubprocessError:
+        return None
+    if result.returncode != 0:
+        return None
+    raw = result.stdout.strip()
+    if not raw:
+        return None
+    # sitecustomize from PYTHONPATH (suppressed by -I) could emit noise before -c runs;
+    # the venv's own sitecustomize can still do so. Take the LAST line — atexit is now
+    # impossible (os._exit), so the last line is what os.write put there — and validate it
+    # parses as a version. Noise that accidentally ends in a dotted string still fails _parse.
+    candidate = raw.splitlines()[-1].strip()
+    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.
+
+    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.
+
+    **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
+    only usually coincide. They part company in the documented critical-no-fix state: when
+    ``critical_below`` is above the installed version and no newer release exists, ``evaluate()``
+    returns a notice while the operator is genuinely current, so reading its ``None``-ness told a
+    fully up-to-date install that its upgrade had failed and it was probably pinned. Two dogfood
+    rounds landed on this function for the same underlying reason — a near-miss reuse of a
+    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.
+    """
+    manifest = _fetch(MANIFEST_URL) or {}
+    latest = _parse(_text(manifest.get("latest")))
+    current = _parse(installed)
+    return latest is not None and current is not None and current >= latest
+
+
 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
@@ -213,9 +297,38 @@ def run_update(*, cwd: Path | None = None, out=None) -> int:
         )
         return WORKTREE_ERROR
 
+    # THE POST-CONDITION. Exit 0 from the package manager means "the command ran", NOT "the
+    # version moved", and the two come apart routinely: `uv tool install syncade==0.6.3` records
+    # `specifier = "==0.6.3"` in its receipt, so `uv tool upgrade` honours the pin, prints
+    # "Nothing to upgrade" and exits 0. Held packages, resolver conflicts and a manifest that is
+    # ahead of PyPI all land in the same place. Without this check syncade says "updated. Re-run
+    # your command", the operator re-runs, gets the same version, and is told again next session
+    # — forever. Measured live on the 0.7.0 release, which is why item 5 of that release existed.
+    now = _installed_version()
+    if now is not None and now == syncade.__version__:
+        # The version did not move. There are TWO reasons for that and they need opposite
+        # answers, so ask the manifest which one this is rather than guessing. Guessing was the
+        # 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):
+            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,
+        )
+        return WORKTREE_ERROR
+
     skills_ok = _resync_skills(out)
+    moved = f" to {now}" if now else ""
     print(
-        "[syncade] updated. Re-run your command to use the new version — this process is\n"
+        f"[syncade] updated{moved}. 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,
     )

{syncade-0.6.3 → syncade-0.7.1}/src/syncade/config_gc.py

@@ -18,6 +18,9 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
 # Drift-guarded literal mirrors of syncade.gc.DEFAULT_KEEP / DEFAULT_MAX_AGE_DAYS (see docstring).
 _DEFAULT_KEEP = 20
 _DEFAULT_MAX_AGE_DAYS = 0
+#: Calibrated on 421 runs / 65 resume-protected: 14d releases 86% while keeping 9.
+#: 7d buys 6% more for half the margin; 30d leaves 19 runs at ~130 MB/round accruing.
+_DEFAULT_WORKTREE_MAX_AGE_DAYS = 14  # mirrors gc.DEFAULT_WORKTREE_MAX_AGE_DAYS
 
 
 class GcConfig(BaseModel):
@@ -41,7 +44,21 @@ class GcConfig(BaseModel):
         ),
     )
 
-    @field_validator("keep", "max_age_days", mode="before")
+    worktree_max_age_days: int = Field(
+        default=_DEFAULT_WORKTREE_MAX_AGE_DAYS,
+        ge=0,
+        description=(
+            "Days after which a run's WORKTREE is removed even though the run is still "
+            f"resume-eligible (default {_DEFAULT_WORKTREE_MAX_AGE_DAYS}; 0 disables the bound "
+            "and restores the previous never-ending protection). Tier 3 of the retention "
+            "policy: a worktree is reconstructible from the SHA the run already records, so "
+            "removing one costs a `git worktree add` and never history. Distinct from "
+            "`max_age_days`, which gates TRANSCRIPTS only — one key cannot be non-zero for "
+            "worktrees and zero for transcripts at once."
+        ),
+    )
+
+    @field_validator("keep", "max_age_days", "worktree_max_age_days", mode="before")
     @classmethod
     def _strict_int(cls, value: object) -> object:
         # Pydantic's lax mode coerces a quoted number ("0"→0), an exact float (1.0→1), and a boolean

{syncade-0.6.3 → syncade-0.7.1}/src/syncade/gc.py

@@ -79,6 +79,12 @@ DEFAULT_KEEP: int = 20
 """Default number of most-recent non-protected runs to keep."""
 
 DEFAULT_MAX_AGE_DAYS: int = 0
+
+#: Tier 3 (PR-h-12 item 2). Calibrated on this repo's corpus rather than picked round: over 421
+#: runs, 65 of them resume-protected, a 14-day floor releases 56 (86%) and keeps 9. A 7-day floor
+#: buys 6% more for half the safety margin; 30 leaves 19 runs at ~130 MB/round still accruing,
+#: which is the unbounded growth this exists to stop. ``0`` disables the bound entirely.
+DEFAULT_WORKTREE_MAX_AGE_DAYS: int = 14
 """Default age floor in days. ``0`` disables the age gate."""
 
 
@@ -116,6 +122,7 @@ def plan_gc(
     *,
     keep: int = DEFAULT_KEEP,
     max_age_days: int = DEFAULT_MAX_AGE_DAYS,
+    worktree_max_age_days: int = DEFAULT_WORKTREE_MAX_AGE_DAYS,
     worktree_base: Path = DEFAULT_WORKTREE_BASE,
     skip_worktrees: bool = False,
 ) -> GcPlan:
@@ -145,11 +152,27 @@ def plan_gc(
             worktree_trees_to_remove=[],
             orphan_worktree_trees=[],
             worktree_tree_identities={},
+            worktree_age_released=[],
         )
 
+    # TIER 3 (PR-h-12 item 2). Worktree removal is independent of tier-2 transcript slimming:
+    # `slim_names` is the transcript filter (beyond-keep AND old-enough), but a run INSIDE the
+    # keep window can still have an ancient worktree nobody is inspecting. The two tiers must be
+    # selected by their own criteria — `worktree_max_age_days` for tier 3, `keep`/`max_age_days`
+    # for tier 2 — so they can be non-zero for one and zero for the other simultaneously.
+    #
+    # `released` is the PROTECTED half: protected runs aged past the floor, with a TOCTOU bypass
+    # flag so execute_gc skips the on-disk protection re-check (the disk state hasn't changed —
+    # only age releases it). `worktree_aged` is the UNPROTECTED half: candidates aged past the
+    # floor, selected independently of slim_names. Both are empty when worktree_max_age_days=0
+    # (the opt-out that reproduces the pre-PR-h-12 behaviour).
+    # TIER 3, selected by its OWN rule — never derived from `slim_names`. See
+    # `_worktree_removable`: deriving tier-3 targets from tier-2's selection is what let a
+    # one-day-old worktree be deleted because its transcripts had aged out.
+    all_worktree_ids, released = _worktree_removable(run_dirs, protected, worktree_max_age_days)
     worktree_trees = [
         tree
-        for tree in existing_worktree_trees(worktree_base, slim_names)
+        for tree in existing_worktree_trees(worktree_base, all_worktree_ids)
         if not tree_contains_repo_root(tree, repo_root)
     ]
     known_run_ids = {d.name for d in run_dirs} | protected
@@ -168,6 +191,7 @@ def plan_gc(
         worktree_trees_to_remove=worktree_trees,
         orphan_worktree_trees=orphan_trees,
         worktree_tree_identities=tree_identities,
+        worktree_age_released=released,
     )
 
 
@@ -197,6 +221,39 @@ def _started_at_timestamp(run_dir: Path) -> float | None:
     return dt.timestamp()
 
 
+def _worktree_removable(
+    run_dirs: list[Path], protected: set[str], worktree_max_age_days: int
+) -> tuple[list[str], list[str]]:
+    """``(removable_run_ids, of_those_that_were_protected)`` — TIER 3's only rule.
+
+    One predicate, because the coupling was the defect. Worktree selection used to be a union
+    with ``slim_names``, so a run beyond ``gc.keep`` lost its worktree the moment its TRANSCRIPTS
+    became eligible — a one-day-old inspection worktree deleted under normal run volume, with the
+    age floor bypassed entirely. That contradicted the four-tier policy in ``CLAUDE.md``, which
+    says tier 3 is removed on its own age rule; the document was right and the code never matched
+    it. Two dogfood rounds fixed half of it each, because each added a source instead of removing
+    the coupling.
+
+    A worktree is removable when it is OLDER than the floor, and — for a run that is still
+    resume-eligible — only when a floor is actually configured::
+
+        age > floor  and  (not protected  or  floor > 0)
+
+    ``worktree_max_age_days = 0`` is the opt-out and keeps its meaning at both ends: an
+    unprotected run's worktree is collectable immediately, exactly as before PR-h-12, while a
+    resumable run's is never released. The second return value is the protected subset, which
+    ``execute_gc`` needs to bypass its protection re-check for those specific runs.
+    """
+    cutoff = datetime.now(UTC).timestamp() - (worktree_max_age_days * 86400)
+    removable = [d for d in run_dirs if _run_sort_key(d) < cutoff]
+    if worktree_max_age_days <= 0:
+        removable = [d for d in removable if d.name not in protected]
+    return (
+        sorted(d.name for d in removable),
+        sorted(d.name for d in removable if d.name in protected),
+    )
+
+
 def _select_for_slimming(
     candidates_newest_first: list[Path],
     *,

{syncade-0.6.3 → syncade-0.7.1}/src/syncade/gc_execute.py

@@ -28,10 +28,21 @@ def execute_gc(plan: GcPlan, *, dry_run: bool, repo_root: Path) -> GcReport:
     pids_reaped: list[int] = []
     worktrees_removed: list[Path] = []
     protected = set(plan.protected_run_ids) | current_protected_run_ids(repo_root)
+    # Tier-3 age release (PR-h-12 item 2). Subtracting these from `protected` above does NOT
+    # work and the first version tried it: `run_id_protected_now` falls through to a DISK
+    # re-check that re-derives protection from the run directory, which has not changed —
+    # only the run's AGE releases it. So the bound computed correctly and then removed nothing.
+    # Unit tests over `plan_gc` could not see that; the end-to-end CLI run did.
+    #
+    # Bypassing the re-check here is safe precisely because age is the criterion: the TOCTOU
+    # guard exists for a run that became resume-eligible BETWEEN plan and execute, and these
+    # were already resume-eligible at plan time and released on an age that cannot change in
+    # the seconds since. Transcripts still go through the unmodified guard.
+    age_released = set(plan.worktree_age_released)
 
     pruned_any = False
     for tree in plan.worktree_trees_to_remove:
-        if run_id_protected_now(repo_root, tree.name, protected):
+        if tree.name not in age_released and run_id_protected_now(repo_root, tree.name, protected):
             continue
         if tree_contains_repo_root(tree, repo_root):
             errors.append(f"skipping worktree tree {tree}: it contains repo root {repo_root}")

{syncade-0.6.3 → syncade-0.7.1}/src/syncade/gc_types.py

@@ -19,8 +19,13 @@ GC used to ``rmtree`` whole run directories. That is now a data-loss bug, not a
 cleanup: ``.syncade/metrics.db`` is a *derived, rebuildable view* over
 ``.syncade/runs/`` — it drop-and-recreates itself on schema drift — so deleting a run
 directory destroys that run's history permanently the next time the view rebuilds.
-Retention is therefore two-tier: **transcripts are disposable, everything else is
-kept forever.**"""
+Retention is therefore **four-tier**: run history (``runs/``) kept forever; transcripts
+disposable beyond the configured keep window; worktrees removed once a run can no longer
+plausibly be resumed (age-bounded by ``gc.worktree_max_age_days``, default 14 days);
+and ``metrics.db`` is a droppable derived view. The asymmetry between tiers 1 and 3 is
+intentional: a worktree is reconstructible from the run's recorded SHA (costs a
+``git worktree add``, never history), so GC can safely remove it; a run directory is
+not reconstructible, so it is never deleted."""
 
 
 @dataclass(frozen=True)
@@ -33,6 +38,12 @@ class GcPlan:
     every structured artifact in it SURVIVE — see :data:`BULK_ARTIFACT_SUFFIXES`."""
     worktree_trees_to_remove: list[Path]
     orphan_worktree_trees: list[Path]
+    worktree_age_released: list[str] = field(default_factory=list)
+    """Run-ids still resume-eligible whose WORKTREES have aged past
+    ``gc.worktree_max_age_days``. Their transcripts and run directories stay protected — this
+    releases tier 3 only. Carried on the plan so ``execute_gc`` can keep its TOCTOU re-check
+    (a run may have become protected since planning) without that re-check silently undoing
+    the age bound."""
     worktree_tree_identities: dict[Path, tuple[int, int, int]] = field(default_factory=dict)