code-coordinator 0.5.46__py3-none-any.whl

coord/branch_model.py

@@ -0,0 +1,214 @@
+"""Pipeline v2 Phase 4 git model (#934, docs/PIPELINE_V2.md "Git model").
+
+Resolves the *base branch* a milestone issue's work should branch off of,
+a PR should diff/merge against, and a review should compare to — instead of
+the flat ``repo.default_branch`` every dispatch/review/merge/reconcile call
+site assumed before #934.
+
+The model: a repo that opts in (sets ``Repo.develop_branch`` in
+``coordinator.yml``) gets a ``develop`` integration branch; each milestone
+gets its own ``feature/ms-NN`` branch off ``develop``; issues that belong to
+that milestone (its GitHub Milestone, per ``coord.github_ops.get_issue``'s
+``milestone`` field) branch off ``feature/ms-NN`` and merge back into it.
+``feature/ms-NN`` itself only merges to ``develop`` via ``coord milestone
+ship`` (Gate D, ``coord/commands/milestone.py``), gated on Gate B + Gate C.
+
+**Opt-in, not a rewrite.** A repo that never sets ``develop_branch`` — or an
+issue with no GitHub Milestone — resolves to exactly today's behavior
+(``repo.default_branch or "main"``). This is deliberate: it's the guard
+against breaking in-flight work on ``main`` the moment one repo adopts the
+new model (#934's own "migration story" requirement). Every call site also
+skips the milestone-number lookup entirely (no `gh` call at all) when the
+repo hasn't set ``develop_branch`` — a repo that hasn't opted in pays zero
+extra cost, network or otherwise.
+
+Wired into the 5 call sites named in #934's scope: ``coord/dispatch.py``
+(worker branch-from), ``coord/review.py`` (PR base + diff base),
+``coord/merge_queue.py`` (merge target), ``coord/reconcile.py`` (retry /
+stale-PR default-branch comparisons). Deliberately NOT wired (yet) into
+``coord/commands/dispatch_workers.py``'s interactive dispatch surface
+(``--review-of``/``--smoke-of``/``--fix-of``/``--merge-of``/etc.) — same
+mechanical swap, much larger surface, left for a follow-up issue per #934's
+own "expect to decompose further when picked up" guidance.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from coord import github_ops
+
+if TYPE_CHECKING:
+    from coord.models import Repo
+
+__all__ = [
+    "feature_branch_name",
+    "resolve_base_branch",
+    "resolve_base_branch_for_issue",
+    "resolve_base_branch_for_issue_number",
+    "ensure_feature_branch_exists",
+    "fetch_issue_milestone_number",
+]
+
+# (repo_github, branch) -> exists on remote. Mirrors github_ops.branch_exists_on_remote.
+BranchExistsFetch = Callable[[str, str], bool]
+# (repo_github, branch) -> tip SHA. Mirrors github_ops.get_default_branch_head.
+BranchShaFetch = Callable[[str, str], str]
+# (repo_github, branch, sha) -> True on success. Mirrors a new github_ops.create_remote_branch.
+BranchCreate = Callable[[str, str, str], bool]
+
+
+def feature_branch_name(milestone_number: int) -> str:
+    """The per-milestone feature branch name: ``feature/ms-NN``."""
+    return f"feature/ms-{milestone_number}"
+
+
+def resolve_base_branch(repo: "Repo", milestone_number: int | None) -> str:
+    """The branch a milestone issue's work/review/merge should target.
+
+    Returns ``feature_branch_name(milestone_number)`` only when *repo* has
+    opted into the git model (``develop_branch`` set) **and** the issue
+    belongs to a known milestone. Otherwise falls back to
+    ``repo.default_branch or "main"`` — today's behavior, unchanged.
+
+    Reads both attributes via ``getattr`` (default ``None``) rather than
+    direct attribute access — some test doubles construct a minimal
+    ``Repo``-shaped stand-in that predates ``develop_branch``, and a
+    fail-open default (today's flat ``default_branch`` behavior) is exactly
+    what a repo without the field should get anyway.
+    """
+    develop_branch = getattr(repo, "develop_branch", None)
+    if develop_branch and milestone_number is not None:
+        return feature_branch_name(milestone_number)
+    return getattr(repo, "default_branch", None) or "main"
+
+
+def fetch_issue_milestone_number(
+    repo_github: str, issue_number: int, *, cache: dict | None = None,
+) -> int | None:
+    """Best-effort fetch of an issue's GitHub Milestone number.
+
+    ``None`` when the issue has no milestone OR the fetch fails — **fail
+    open**, mirroring ``coord.github_ops.work_is_terminal``: a transient
+    ``gh`` error must never block a legitimate dispatch/review/merge/
+    reconcile pass, it just falls back to :func:`resolve_base_branch`'s
+    ``default_branch`` behavior for that one call.
+
+    *cache* — optional ``dict`` keyed by ``(repo_github, issue_number)``,
+    shared across a batch (e.g. one ``enqueue_approved_work`` pass), so a
+    burst of entries for the same repo/issue costs one ``gh`` round-trip.
+    Shared-module-level fetchers (``coord.review._fetch_issue_milestone_
+    number`` and friends) delegate here rather than duplicating the ``gh``
+    call, so every call site fails open the same way.
+
+    Callers should only invoke this when the repo has opted into the git
+    model (``repo.develop_branch`` set) — see each call site's own guard —
+    so a repo that hasn't opted in never pays for this ``gh`` round-trip at
+    all, not even a fail-open one.
+    """
+    key = (repo_github, issue_number)
+    if cache is not None and key in cache:
+        return cache[key]
+    try:
+        issue_data = github_ops.get_issue(repo_github, issue_number)
+        milestone = issue_data.get("milestone") or {}
+        result = milestone.get("number") if isinstance(milestone, dict) else None
+    except Exception:  # noqa: BLE001 — fail-open: a transient gh error (incl.
+        # subprocess.TimeoutExpired on a `gh` hang, json.JSONDecodeError on
+        # truncated output — neither is a RuntimeError) must never abort a
+        # whole dispatch/review/merge/reconcile batch pass over one bad
+        # milestone lookup. Mirrors github_ops.get_branch_diff_size's broad
+        # "fail open, unknown is not blocking" catch.
+        result = None
+    if cache is not None:
+        cache[key] = result
+    return result
+
+
+def resolve_base_branch_for_issue(repo: "Repo", issue_data: dict) -> str:
+    """Like :func:`resolve_base_branch`, deriving the milestone from a
+    ``coord.github_ops.get_issue()``-shaped dict (its ``milestone`` field —
+    ``None`` or ``{"number": ..., "title": ...}``).
+
+    Callers that already fetched the issue (nearly every call site in
+    ``dispatch.py``/``review.py``/``merge_queue.py``/``reconcile.py`` does,
+    for the title/body) get milestone-awareness for free — no extra GitHub
+    call, no new field threaded through ``Assignment``/DB persistence.
+    """
+    milestone = issue_data.get("milestone") or {}
+    milestone_number = milestone.get("number") if isinstance(milestone, dict) else None
+    return resolve_base_branch(repo, milestone_number)
+
+
+def resolve_base_branch_for_issue_number(
+    repo: "Repo", repo_github: str, issue_number: int, *, cache: dict | None = None,
+) -> str:
+    """Like :func:`resolve_base_branch_for_issue`, but for a call site that
+    only has an issue *number* rather than an already-fetched issue dict.
+
+    #1479-review: unifies "does this repo opt into the git model, and if so
+    which milestone/base branch does this issue resolve to" for call sites
+    that hadn't already fetched the full issue payload —
+    ``coord.merge_queue.enqueue_approved_work`` and
+    ``coord.state._stamp_test_staleness_anchor`` each reimplemented this
+    guard-then-lookup slightly differently before this helper existed
+    (one via :func:`fetch_issue_milestone_number` directly, the other via
+    :func:`resolve_base_branch_for_issue` plus a raw ``get_issue`` call). A
+    single implementation means the two can't silently drift apart.
+
+    Skips the milestone lookup entirely (no ``gh`` call at all) when the repo
+    hasn't opted into the git model (``repo.develop_branch`` unset) —
+    mirrors :func:`resolve_base_branch`'s own zero-extra-cost guarantee for
+    repos that haven't adopted it. *cache* is forwarded unchanged to
+    :func:`fetch_issue_milestone_number` for batch call sites that want to
+    dedupe repeated lookups across a pass.
+    """
+    if not getattr(repo, "develop_branch", None):
+        return getattr(repo, "default_branch", None) or "main"
+    milestone_number = fetch_issue_milestone_number(repo_github, issue_number, cache=cache)
+    return resolve_base_branch(repo, milestone_number)
+
+
+def ensure_feature_branch_exists(
+    repo: "Repo",
+    milestone_number: int,
+    *,
+    exists: BranchExistsFetch = github_ops.branch_exists_on_remote,
+    get_sha: BranchShaFetch = github_ops.get_default_branch_head,
+    create: BranchCreate = github_ops.create_remote_branch,
+) -> str:
+    """Idempotently create ``feature/ms-NN`` off ``repo.develop_branch`` if
+    it doesn't already exist on the remote. Returns the branch name.
+
+    Raises ``ValueError`` if *repo* hasn't opted into the git model
+    (``develop_branch`` unset) — callers should only invoke this after
+    confirming ``repo.develop_branch`` is set (mirrors the guard in
+    :func:`resolve_base_branch`). Raises ``RuntimeError`` if *create* reports
+    failure (e.g. ``github_ops.create_remote_branch`` returning ``False`` on
+    a permissions error, transient API failure, or branch-protection
+    rejecting a direct ref-create) — callers must not treat the returned
+    branch name as guaranteed to exist on the remote unless this call
+    returns normally.
+    """
+    if not repo.develop_branch:
+        raise ValueError(
+            f"repo {repo.name!r} has no develop_branch configured — "
+            "cannot create a feature branch for it"
+        )
+    branch = feature_branch_name(milestone_number)
+    if exists(repo.github, branch):
+        return branch
+    sha = get_sha(repo.github, repo.develop_branch)
+    if not create(repo.github, branch, sha):
+        # github_ops.create_remote_branch catches its own RuntimeError and
+        # returns False on failure rather than raising (permissions,
+        # transient API error, a race, branch-protection requiring a PR
+        # instead of a direct ref-create) — check the return value and raise
+        # here so callers (e.g. milestone_dispatch.dispatch_entry's
+        # `except (ValueError, RuntimeError)`) actually catch it, instead of
+        # silently returning a branch name that doesn't exist on the remote.
+        raise RuntimeError(
+            f"failed to create feature branch {branch!r} for repo "
+            f"{repo.name!r} off {repo.develop_branch!r}"
+        )
+    return branch

coord/cargo_cache.py

@@ -0,0 +1,258 @@
+"""#1402: a shared, per-machine cargo target directory with a bounded GC.
+
+Every Rust assignment used to pay a cold ``cargo`` build. Workers run inside an
+ephemeral ``~/.coord/worktrees/<assignment_id>`` checkout, so cargo's default
+``<workspace>/target`` lived *inside* the worktree and
+:meth:`AgentServer._cleanup_worktree` deleted it along with the tree. Two
+workers on the same machine, on the same repo, shared nothing either — each
+worktree was its own cold build. Measured on ``tui/``: ~3 min cold vs ~18 s
+warm.
+
+This module points every worker on a machine at one cache per repo::
+
+    ~/.coord/cargo-target/<repo_name>/
+
+Concurrency is cargo's problem and cargo already solves it: it takes a build
+lock on the target dir, so two workers building the same repo at the same time
+block each other briefly rather than corrupting the cache. Correctness across
+branches is likewise cargo's: it keys artifacts on a fingerprint of the source,
+profile, features and rustc version, so a stale artifact from another branch is
+rebuilt rather than reused.
+
+Because the cache now *outlives* the worktree, it needs a bound. :func:`sweep`
+is a least-recently-used GC: it totals the per-repo cache directories and
+evicts whole directories, oldest-used first, until the total is back under the
+cap (default 20 GiB, override with ``COORD_CARGO_CACHE_CAP_GB``). Evicting a
+whole repo cache is safe by construction — it is a cache, and the next build
+repopulates it. Caches belonging to a repo with a live assignment are never
+evicted, so the GC can't delete a target dir out from under a running build.
+
+Set ``COORD_SHARED_CARGO_TARGET=0`` to disable the whole feature; an operator
+who exports their own ``CARGO_TARGET_DIR`` also wins (we never override it).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from pathlib import Path
+
+# Directory under the agent state dir (``~/.coord``) that holds one
+# subdirectory per repo.
+CACHE_DIRNAME = "cargo-target"
+
+# Total cap across every per-repo cache on this machine.  A cold ``tui/``
+# debug build is ~2 GiB, so 20 GiB comfortably holds several repos warm.
+DEFAULT_CACHE_CAP_GB = 20.0
+
+CAP_ENV = "COORD_CARGO_CACHE_CAP_GB"
+ENABLE_ENV = "COORD_SHARED_CARGO_TARGET"
+CARGO_ENV = "CARGO_TARGET_DIR"
+
+_FALSEY = {"0", "false", "no", "off", ""}
+
+# Repo names become a path component, so they must be a single safe segment.
+# Anything else (a slash, "..", a control character) disables the cache for
+# that repo rather than writing outside the cache root.
+_SAFE_COMPONENT = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def _env(env: dict[str, str] | None) -> dict[str, str]:
+    return dict(os.environ) if env is None else env
+
+
+def enabled(env: dict[str, str] | None = None) -> bool:
+    """True unless ``COORD_SHARED_CARGO_TARGET`` is set to a falsey value."""
+    raw = _env(env).get(ENABLE_ENV)
+    if raw is None:
+        return True
+    return raw.strip().lower() not in _FALSEY
+
+
+def cache_root(state_dir: Path) -> Path:
+    """The per-machine cache root: ``<state_dir>/cargo-target``."""
+    return Path(state_dir) / CACHE_DIRNAME
+
+
+def target_dir_for_repo(repo_name: str, state_dir: Path) -> Path | None:
+    """The shared target dir for *repo_name*, or ``None`` if the name is not a
+    safe single path component (never guessed, never sanitized into a
+    collision — an unusable name simply opts that repo out)."""
+    if not repo_name or not _SAFE_COMPONENT.match(repo_name):
+        return None
+    if repo_name in (".", ".."):
+        return None
+    return cache_root(state_dir) / repo_name
+
+
+def cargo_env(
+    repo_name: str,
+    state_dir: Path,
+    base_env: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Environment overlay pointing cargo at the shared cache.
+
+    Returns ``{}`` (a no-op overlay) when the feature is disabled, the repo
+    name is unusable, or *base_env* already carries a ``CARGO_TARGET_DIR`` —
+    an operator's explicit choice always wins.
+
+    The directory is **not** created here: cargo does its own ``mkdir -p``, so
+    a repo that never invokes cargo never leaves an empty dir behind.
+    """
+    env = _env(base_env)
+    if not enabled(env):
+        return {}
+    if env.get(CARGO_ENV):
+        return {}
+    target = target_dir_for_repo(repo_name, state_dir)
+    if target is None:
+        return {}
+    return {CARGO_ENV: str(target)}
+
+
+def cap_bytes(env: dict[str, str] | None = None) -> int | None:
+    """The GC cap in bytes, or ``None`` when GC is disabled (cap <= 0)."""
+    raw = _env(env).get(CAP_ENV)
+    gb = DEFAULT_CACHE_CAP_GB
+    if raw is not None:
+        try:
+            gb = float(raw)
+        except (TypeError, ValueError):
+            gb = DEFAULT_CACHE_CAP_GB
+    if gb <= 0:
+        return None
+    return int(gb * 1024 * 1024 * 1024)
+
+
+def dir_size(path: Path) -> int:
+    """Total size of the regular files under *path* (symlinks not followed)."""
+    total = 0
+    for root, dirnames, filenames in os.walk(path, onerror=lambda _e: None):
+        # Never follow a symlinked subdirectory out of the cache.
+        dirnames[:] = [
+            d for d in dirnames if not os.path.islink(os.path.join(root, d))
+        ]
+        for name in filenames:
+            fp = os.path.join(root, name)
+            try:
+                st = os.lstat(fp)
+            except OSError:
+                continue
+            total += st.st_size
+    return total
+
+
+def _last_used(path: Path) -> float:
+    """Best-effort "when was this cache last built into".
+
+    cargo rewrites files throughout a build, so the newest mtime anywhere in
+    the tree is a good proxy — but walking a multi-GiB tree twice is wasteful,
+    so we sample the shallow entries cargo always touches (the profile dirs and
+    their lock/fingerprint children) plus the directory itself.
+    """
+    try:
+        newest = path.stat().st_mtime
+    except OSError:
+        return 0.0
+    try:
+        children = list(path.iterdir())
+    except OSError:
+        return newest
+    for child in children:
+        try:
+            newest = max(newest, child.stat().st_mtime)
+        except OSError:
+            continue
+        if child.is_dir() and not child.is_symlink():
+            try:
+                grandchildren = list(child.iterdir())
+            except OSError:
+                continue
+            for entry in grandchildren:
+                try:
+                    newest = max(newest, entry.stat().st_mtime)
+                except OSError:
+                    continue
+    return newest
+
+
+def sweep(
+    state_dir: Path,
+    *,
+    cap: int | None = -1,
+    protect_repos: "set[str] | frozenset[str] | None" = None,
+    dry_run: bool = False,
+) -> dict:
+    """Evict least-recently-used repo caches until the total is under the cap.
+
+    *cap* defaults to the sentinel ``-1`` meaning "read it from the
+    environment" (:func:`cap_bytes`); pass an explicit int to override, or
+    ``None`` to disable eviction (the sweep then only reports sizes).
+
+    *protect_repos* names repos with a live (pending/running) assignment on
+    this machine — their caches are never evicted, so a build in flight can't
+    have its target dir deleted underneath it. If the protected set alone
+    exceeds the cap, the sweep evicts everything it may and reports the
+    remaining overage via ``cargo_over_cap``; it never deletes a protected
+    cache.
+
+    Returns ``{"cargo_cache_bytes": B, "cargo_caches_evicted": N,
+    "cargo_evicted_repos": [...], "cargo_cap_bytes": C|None,
+    "cargo_over_cap": bool, "cargo_dry_run": bool}`` — ``cargo_cache_bytes``
+    is the total *after* the sweep (or, for ``dry_run``, what it would be).
+    """
+    limit = cap_bytes() if cap == -1 else cap
+    protected = set(protect_repos or ())
+    result: dict = {
+        "cargo_cache_bytes": 0,
+        "cargo_caches_evicted": 0,
+        "cargo_evicted_repos": [],
+        "cargo_cap_bytes": limit,
+        "cargo_over_cap": False,
+        "cargo_dry_run": dry_run,
+    }
+
+    root = cache_root(state_dir)
+    if not root.is_dir():
+        return result
+
+    entries: list[tuple[float, str, Path, int]] = []
+    total = 0
+    try:
+        children = sorted(root.iterdir())
+    except OSError:
+        return result
+    for child in children:
+        # Skip symlinks outright — we never chase one out of the cache root.
+        if child.is_symlink() or not child.is_dir():
+            continue
+        size = dir_size(child)
+        total += size
+        entries.append((_last_used(child), child.name, child, size))
+
+    result["cargo_cache_bytes"] = total
+    if limit is None or total <= limit:
+        return result
+
+    # Oldest-used first; ties broken by name so the sweep is deterministic.
+    entries.sort(key=lambda e: (e[0], e[1]))
+    evicted: list[str] = []
+    for _mtime, name, path, size in entries:
+        if total <= limit:
+            break
+        if name in protected:
+            continue
+        if not dry_run:
+            try:
+                shutil.rmtree(path)
+            except OSError:
+                continue
+        total -= size
+        evicted.append(name)
+
+    result["cargo_cache_bytes"] = total
+    result["cargo_caches_evicted"] = len(evicted)
+    result["cargo_evicted_repos"] = evicted
+    result["cargo_over_cap"] = total > limit
+    return result