syncade 0.6.2__py3-none-any.whl

syncade/gc_execute.py

@@ -0,0 +1,372 @@
+"""Best-effort destructive execution for ``syncade --gc`` plans."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import sys
+from pathlib import Path
+
+from syncade.gc_protection import (
+    current_protected_run_ids,
+    orphan_worktree_still_orphan_now,
+    run_dir_slimmable_now,
+    run_id_protected_now,
+)
+from syncade.gc_types import BULK_ARTIFACT_SUFFIXES, GcPlan, GcReport
+from syncade.gc_worktrees import tree_contains_repo_root, tree_identity
+from syncade.process import SubprocessError, run_subprocess
+
+_LSOF_TIMEOUT_SECONDS: float = 30.0
+_GIT_PRUNE_TIMEOUT_SECONDS: float = 30.0
+
+
+def execute_gc(plan: GcPlan, *, dry_run: bool, repo_root: Path) -> GcReport:
+    """Carry out a :class:`GcPlan`. Best-effort; never raises out."""
+    errors: list[str] = []
+    pids_reaped: list[int] = []
+    worktrees_removed: list[Path] = []
+    protected = set(plan.protected_run_ids) | current_protected_run_ids(repo_root)
+
+    pruned_any = False
+    for tree in plan.worktree_trees_to_remove:
+        if 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}")
+            continue
+        if not _planned_tree_identity_still_matches(plan, tree, errors, dry_run=dry_run):
+            continue
+        reaped, removed = _reap_and_remove_tree(tree, dry_run=dry_run, errors=errors)
+        pids_reaped.extend(reaped)
+        if removed:
+            worktrees_removed.append(tree)
+            pruned_any = True
+
+    for tree in plan.orphan_worktree_trees:
+        if tree_contains_repo_root(tree, repo_root):
+            errors.append(f"skipping worktree tree {tree}: it contains repo root {repo_root}")
+            continue
+        if not _planned_tree_identity_still_matches(plan, tree, errors, dry_run=dry_run):
+            continue
+        if not orphan_worktree_still_orphan_now(repo_root, tree, protected):
+            continue
+        reaped, removed = _reap_and_remove_tree(tree, dry_run=dry_run, errors=errors)
+        pids_reaped.extend(reaped)
+        if removed:
+            worktrees_removed.append(tree)
+            pruned_any = True
+
+    if pruned_any and not dry_run:
+        _git_worktree_prune(repo_root, errors)
+
+    runs_slimmed: list[str] = []
+    bytes_freed = 0
+    runs_root = repo_root / ".syncade" / "runs"
+    for run_id in plan.runs_to_slim:
+        run_dir = runs_root / run_id
+        if not run_dir_slimmable_now(run_dir, run_id, protected):
+            continue
+        slimmed = _slim_run_dir(run_dir, runs_root, dry_run=dry_run, errors=errors)
+        if slimmed is None:
+            continue
+        freed, removed = slimmed
+        bytes_freed += freed
+        # Report on artifacts REMOVED, not bytes freed. Bytes are the wrong proxy for
+        # "did anything happen": a run whose transcripts are all zero-byte gets its
+        # files unlinked while `freed` stays 0, so keying off bytes made the report
+        # claim nothing was slimmed while the tree was mutated — and made --gc-dry-run
+        # promise the same. An already-slim run removes nothing, so idempotence still
+        # holds.
+        if removed > 0:
+            runs_slimmed.append(run_id)
+
+    return GcReport(
+        runs_slimmed=runs_slimmed,
+        worktrees_removed=worktrees_removed,
+        pids_reaped=pids_reaped,
+        bytes_freed=bytes_freed,
+        errors=errors,
+        dry_run=dry_run,
+    )
+
+
+def _slim_run_dir(
+    run_dir: Path, runs_root: Path, *, dry_run: bool, errors: list[str]
+) -> tuple[int, int] | None:
+    """Prune only the bulky subprocess transcripts under ``round-*/``.
+
+    The run directory itself, its run-root artifacts (``loop-manifest.json``,
+    ``run-init.json``, ``findings.md``, ``handoff.md``, ``status.json`` …) and every
+    structured per-round artifact (round manifests, parsed findings, summaries, exit
+    codes) all SURVIVE. See :data:`BULK_ARTIFACT_SUFFIXES` for why.
+
+    Returns ``(bytes_freed, artifacts_removed)`` — both 0 if the run was already slim —
+    or ``None`` if the run dir could not be walked at all, in which case the caller
+    skips it rather than reporting a slim that did not happen.
+
+    The count is returned alongside the bytes because bytes alone cannot answer "did
+    anything happen": a zero-byte transcript is still an artifact that gets unlinked.
+
+    **Symlinks are refused, not followed, and containment is anchored to THIS RUN's
+    resolved directory — not merely to the corpus root.** Four escapes have been
+    reproduced against earlier drafts of this function:
+
+    1. a ``round-*`` entry that is a symlink → refused in the listing filter AND
+       rechecked at the top of :func:`_bulk_artifacts_under` (TOCTOU defense);
+    2. a symlinked subdirectory beneath a legitimate round dir → ``os.walk`` runs with
+       ``followlinks=False``;
+    3. **the run directory itself swapped for a symlink between plan and execute** —
+       :func:`~syncade.gc_protection.run_dir_slimmable_now` independently refuses a
+       symlinked run dir; ``run_dir_resolved.relative_to(corpus_root)`` is the
+       second, load-bearing containment layer;
+    4. **a round directory swapped for a symlink pointing at a protected run inside the
+       same corpus** (intra-corpus TOCTOU, found by round-1 reviewers, 2026-07-12).
+       Anchoring containment on ``corpus_root`` alone would allow this: a file from
+       another run inside the corpus would pass the corpus-relative check. Anchoring on
+       ``run_dir_resolved`` closes it — a file inside a different run is not relative to
+       this run's resolved path.
+    """
+    if run_dir.is_symlink():
+        errors.append(f"skipping run dir {run_dir}: it is a symlink")
+        return None
+    try:
+        corpus_root = runs_root.resolve(strict=True)
+        # The run dir must genuinely live inside the corpus — not merely claim to.
+        run_dir_resolved = run_dir.resolve(strict=True)
+        run_dir_resolved.relative_to(corpus_root)
+        entries = list(run_dir.iterdir())
+    except (OSError, ValueError) as exc:
+        errors.append(
+            f"skipping run dir {run_dir}: not a real directory inside {runs_root} ({exc})"
+        )
+        return None
+    round_dirs = [
+        d for d in entries if d.name.startswith("round-") and not d.is_symlink() and d.is_dir()
+    ]
+
+    freed = 0
+    removed = 0
+    for round_dir in round_dirs:
+        for artifact in _bulk_artifacts_under(round_dir, run_dir_resolved, errors):
+            try:
+                size = artifact.stat().st_size
+            except OSError:
+                continue
+            if dry_run:
+                freed += size
+                removed += 1
+                continue
+            try:
+                artifact.unlink()
+                freed += size
+                removed += 1
+            except OSError as exc:
+                errors.append(f"failed to remove transcript {artifact}: {exc}")
+    return freed, removed
+
+
+def _bulk_artifacts_under(round_dir: Path, run_root: Path, errors: list[str]) -> list[Path]:
+    """Transcripts under ``round_dir`` that provably live inside ``run_root``
+    (the resolved run directory).
+
+    Walks with ``followlinks=False`` so a symlinked subdirectory cannot widen the
+    blast radius, skips symlinked files, and containment-checks every survivor against
+    the resolved run root — not the corpus root. Anchoring on the run rather than the
+    corpus is the key fix for the intra-corpus round-dir TOCTOU: a symlinked round dir
+    pointing at a *different* run inside the same corpus would pass a corpus-anchored
+    check, but fails a run-anchored one. **GC never unlinks anything outside this run.**
+
+    The first line is a TOCTOU recheck: ``round_dir`` may have been swapped to a
+    symlink after the caller's ``not d.is_symlink()`` filter; ``os.walk`` still
+    traverses a top-level symlink even with ``followlinks=False``, so we must recheck
+    before walking.
+    """
+    if round_dir.is_symlink():
+        errors.append(f"skipping round dir {round_dir}: became a symlink (TOCTOU)")
+        return []
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(round_dir, followlinks=False):
+        here = Path(dirpath)
+        # os.walk(followlinks=False) still *lists* symlinked dirs; don't descend.
+        dirnames[:] = [d for d in dirnames if not (here / d).is_symlink()]
+        for name in filenames:
+            candidate = here / name
+            if candidate.suffix not in BULK_ARTIFACT_SUFFIXES:
+                continue
+            if candidate.is_symlink():
+                continue
+            try:
+                candidate.resolve(strict=True).relative_to(run_root)
+            except (OSError, ValueError):
+                errors.append(f"skipping transcript outside the run directory: {candidate}")
+                continue
+            found.append(candidate)
+    return found
+
+
+def _planned_tree_identity_still_matches(
+    plan: GcPlan, tree: Path, errors: list[str], *, dry_run: bool
+) -> bool:
+    expected = plan.worktree_tree_identities.get(tree)
+    if expected is None:
+        if dry_run:
+            return True
+        if tree_identity(tree) is None:
+            return True
+        errors.append(f"skipping worktree tree {tree}: GC plan has no recorded directory identity")
+        return False
+    actual = tree_identity(tree)
+    if actual == expected:
+        return True
+    errors.append(
+        f"skipping worktree tree {tree}: it changed since GC planning "
+        f"(planned identity={expected!r}, current identity={actual!r})"
+    )
+    return False
+
+
+def _reap_and_remove_tree(
+    tree: Path, *, dry_run: bool, errors: list[str]
+) -> tuple[list[int], bool]:
+    """Reap in-cwd processes, then rmtree a single worktree tree."""
+    try:
+        if tree.is_symlink():
+            errors.append(f"skipping unsafe symlink worktree tree {tree}")
+            return [], False
+    except OSError as exc:
+        errors.append(f"failed to inspect worktree tree {tree}: {exc}")
+        return [], False
+
+    reaped = _reap_processes_in_tree(tree, errors, dry_run=dry_run)
+
+    if dry_run:
+        return reaped, True
+
+    shutil.rmtree(tree, ignore_errors=True)
+    if tree.exists():
+        errors.append(
+            f"failed to remove worktree tree {tree} (still present after rmtree; "
+            f"permission denied?)"
+        )
+        return reaped, False
+    return reaped, True
+
+
+def _reap_processes_in_tree(tree: Path, errors: list[str], *, dry_run: bool = False) -> list[int]:
+    """Return or reap PIDs whose current working directory is inside ``tree``."""
+    pids = _lsof_pids_in_tree(tree, errors)
+    if dry_run:
+        return pids
+    reaped: list[int] = []
+    for pid in pids:
+        if not _pid_cwd_is_still_in_tree(pid, tree, errors):
+            continue
+        try:
+            os.kill(pid, signal.SIGKILL)
+            reaped.append(pid)
+        except (ProcessLookupError, PermissionError) as exc:
+            errors.append(f"could not reap pid {pid} in {tree}: {exc}")
+    return reaped
+
+
+def reap_processes_in_tree(tree: Path) -> list[int]:
+    """SIGKILL every process whose cwd is inside ``tree``; return reaped PIDs.
+
+    Public seam shared by GC and resume cleanup so both apply the SAME
+    cwd-scoped live-process safety before an ``rmtree`` — a directory is
+    never removed out from under a running (orphaned) subprocess. Best
+    effort: an ``lsof`` recheck failure is swallowed and that pid is skipped.
+    """
+    errors: list[str] = []
+    return _reap_processes_in_tree(tree, errors)
+
+
+def _pid_cwd_is_still_in_tree(pid: int, tree: Path, errors: list[str]) -> bool:
+    try:
+        result = run_subprocess(
+            ["lsof", "-t", "-a", "-d", "cwd", "-p", str(pid), "+D", str(tree)],
+            timeout=_LSOF_TIMEOUT_SECONDS,
+        )
+    except SubprocessError as exc:
+        msg = (
+            f"WARNING: lsof recheck unavailable for pid {pid} in {tree} ({exc}); skipping this pid."
+        )
+        print(msg, file=sys.stderr)
+        errors.append(msg)
+        return False
+
+    if pid in _parse_lsof_pids(result.stdout):
+        return True
+    if result.returncode != 0 and result.stderr.strip():
+        msg = (
+            f"WARNING: lsof recheck errored for pid {pid} in {tree} "
+            f"(rc={result.returncode}: {result.stderr.strip()}); skipping this pid."
+        )
+        print(msg, file=sys.stderr)
+        errors.append(msg)
+    return False
+
+
+def _lsof_pids_in_tree(tree: Path, errors: list[str]) -> list[int]:
+    try:
+        result = run_subprocess(
+            ["lsof", "-t", "-a", "-d", "cwd", "+D", str(tree)],
+            timeout=_LSOF_TIMEOUT_SECONDS,
+        )
+    except SubprocessError as exc:
+        msg = (
+            f"WARNING: lsof unavailable for {tree} ({exc}); skipping process "
+            f"reaping for this tree (still removing the directory)."
+        )
+        print(msg, file=sys.stderr)
+        errors.append(msg)
+        return []
+
+    if result.returncode != 0 and result.stderr.strip():
+        msg = (
+            f"WARNING: lsof errored for {tree} (rc={result.returncode}: "
+            f"{result.stderr.strip()}); skipping process reaping for this tree "
+            f"(still removing the directory)."
+        )
+        print(msg, file=sys.stderr)
+        errors.append(msg)
+        return []
+
+    return _parse_lsof_pids(result.stdout)
+
+
+def _parse_lsof_pids(stdout: str) -> list[int]:
+    """Parse unique PIDs from terse or tabular ``lsof`` output."""
+    pids: list[int] = []
+    seen: set[int] = set()
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        token = line.split()[0]
+        if token.startswith("p") and token[1:].isdigit():
+            token = token[1:]
+        if token.isdigit():
+            pid = int(token)
+        else:
+            parts = line.split()
+            if len(parts) < 2 or not parts[1].isdigit():
+                continue
+            pid = int(parts[1])
+        if pid not in seen:
+            seen.add(pid)
+            pids.append(pid)
+    return pids
+
+
+def _git_worktree_prune(repo_root: Path, errors: list[str]) -> None:
+    try:
+        run_subprocess(
+            ["git", "worktree", "prune"],
+            cwd=repo_root,
+            timeout=_GIT_PRUNE_TIMEOUT_SECONDS,
+        )
+    except SubprocessError as exc:
+        errors.append(f"git worktree prune failed in {repo_root}: {exc}")

syncade/gc_protection.py

@@ -0,0 +1,129 @@
+"""Run-protection checks shared by GC planning and execution."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from syncade.gc_worktrees import repo_owned_orphan_trees
+from syncade.orchestrator.resume import find_resumable_runs
+from syncade.orchestrator.resume_types import _RESUMABLE_EXIT_CODES, LOOP_MANIFEST_FILENAME
+from syncade.persistence import RUN_INIT_FILENAME
+
+
+def protected_run_ids_for_gc(runs_root: Path, run_dirs: list[Path] | None = None) -> set[str]:
+    """Return run IDs GC must not slim."""
+    if run_dirs is None:
+        run_dirs = safe_iter_subdirs(runs_root)
+
+    try:
+        protected = set(find_resumable_runs(runs_root))
+    except OSError:
+        protected = set()
+
+    for run_dir in run_dirs:
+        if gc_should_conservatively_protect(run_dir):
+            protected.add(run_dir.name)
+    return protected
+
+
+def gc_should_conservatively_protect(run_dir: Path) -> bool:
+    run_init = run_dir / RUN_INIT_FILENAME
+    try:
+        has_run_init = run_init.is_file()
+    except OSError:
+        return True
+    if not has_run_init:
+        return True
+
+    loop_manifest = run_dir / LOOP_MANIFEST_FILENAME
+    try:
+        has_loop_manifest = loop_manifest.is_file()
+    except OSError:
+        return True
+    if not has_loop_manifest:
+        return True
+
+    try:
+        data = json.loads(loop_manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return True
+
+    exit_code = data.get("final_exit_code")
+    return isinstance(exit_code, int) and exit_code in _RESUMABLE_EXIT_CODES
+
+
+def current_protected_run_ids(repo_root: Path) -> set[str]:
+    return protected_run_ids_for_gc(repo_root / ".syncade" / "runs")
+
+
+def run_id_protected_now(repo_root: Path, run_id: str, protected_run_ids: set[str]) -> bool:
+    if run_id in protected_run_ids:
+        return True
+    return run_dir_protected_now(repo_root / ".syncade" / "runs" / run_id)
+
+
+def run_dir_slimmable_now(run_dir: Path, run_id: str, protected_run_ids: set[str]) -> bool:
+    """Re-checked at execution time, not just at plan time: a run that became
+    resume-eligible between plan and execute must not be touched.
+
+    A **symlinked run dir is refused outright**. ``plan_gc`` never selects one, so the
+    only way to reach here with a symlink is a plan/execute race (or a stale plan):
+    plan against the real ``.syncade/runs/<id>/``, swap it for a symlink to an
+    external directory dressed up with valid run markers, then execute. Both
+    reviewers reproduced exactly that, and it let GC unlink ``*.stdout`` outside the
+    corpus. ``is_dir()`` follows symlinks, so it cannot be the check.
+    """
+    if run_id in protected_run_ids:
+        return False
+    if run_dir_protected_now(run_dir):
+        return False
+    try:
+        if run_dir.is_symlink():
+            return False
+        return run_dir.is_dir()
+    except OSError:
+        return False
+
+
+def run_dir_protected_now(run_dir: Path) -> bool:
+    try:
+        if not run_dir.is_dir():
+            return False
+    except OSError:
+        return True
+    return gc_should_conservatively_protect(run_dir)
+
+
+def orphan_worktree_still_orphan_now(
+    repo_root: Path, tree: Path, protected_run_ids: set[str]
+) -> bool:
+    run_id = tree.name
+    if run_id in protected_run_ids:
+        return False
+    try:
+        if (repo_root / ".syncade" / "runs" / run_id).exists():
+            return False
+    except OSError:
+        return False
+    runs_root = repo_root / ".syncade" / "runs"
+    known_run_ids = {d.name for d in safe_iter_subdirs(runs_root)} | protected_run_ids
+    return tree in repo_owned_orphan_trees(repo_root, [tree], known_run_ids)
+
+
+def safe_iter_subdirs(path: Path) -> list[Path]:
+    """Return immediate subdirectories, or ``[]`` on any ``OSError``."""
+    try:
+        entries = list(path.iterdir())
+    except OSError:
+        return []
+    subdirs: list[Path] = []
+    for entry in entries:
+        try:
+            if entry.is_symlink():
+                continue
+            if entry.is_dir():
+                subdirs.append(entry)
+        except OSError:
+            continue
+    return subdirs

syncade/gc_types.py

@@ -0,0 +1,50 @@
+"""Shared data shapes for ``syncade --gc`` planning and execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+BULK_ARTIFACT_SUFFIXES = (".stdout", ".stderr")
+"""Raw subprocess transcripts under ``round-*/`` — the only artifacts GC removes.
+
+Measured over the real 263-run corpus (2026-07-12): ``.stdout`` + ``.stderr`` are
+**45.97 MB of 50.59 MB — 90.9%** — across 2138 files (1069 of each), while every
+structured artifact combined (round manifests, parsed findings, summaries, exit
+codes, and the whole run root) is **4.62 MB**, about 18 KB per run. So pruning
+transcripts frees essentially all the disk while costing none of the data that
+anything reads for a verdict or a metric.
+
+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.**"""
+
+
+@dataclass(frozen=True)
+class GcPlan:
+    """The result of ``plan_gc``: what GC would do."""
+
+    protected_run_ids: list[str]
+    runs_to_slim: list[str]
+    """Runs whose ``round-*/`` transcripts will be pruned. The run directory and
+    every structured artifact in it SURVIVE — see :data:`BULK_ARTIFACT_SUFFIXES`."""
+    worktree_trees_to_remove: list[Path]
+    orphan_worktree_trees: list[Path]
+    worktree_tree_identities: dict[Path, tuple[int, int, int]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GcReport:
+    """The result of ``execute_gc``: what GC did, or would do on dry-run."""
+
+    runs_slimmed: list[str]
+    """Runs whose transcripts were pruned. A run already slim contributes nothing
+    (slimming is idempotent) and does not appear here."""
+    worktrees_removed: list[Path]
+    pids_reaped: list[int]
+    bytes_freed: int = 0
+    errors: list[str] = field(default_factory=list)
+    dry_run: bool = False