code-coordinator 0.5.240__tar.gz → 0.5.241__tar.gz

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.240
+Version: 0.5.241
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.240
+Version: 0.5.241
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.240",
+  "tag": "0.5.241",
   "distance": 0,
-  "node": "gbfdc750bff3b8352eace6d4ce6ab5dde9b39771a",
+  "node": "gf7a7056ba9c9f723298a0b5f62a8949e5c01bd1f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-23"

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/coord/commands/drive_queue.py

@@ -91,7 +91,9 @@ from coord.overlap_predict import (
     classify_outcome,
     collect_candidate_files,
     declared_footprints,
+    fanout_warnings,
     inflight_footprints,
+    parse_declared_files,
     predict_overlap,
     predictions_from_audit,
     tally,
@@ -296,9 +298,12 @@ def drive_queue_add(
     # yields an empty prediction and this add behaves exactly as it did before
     # the feature existed.
     prediction = Prediction()
+    staleness_note = ""
     auto_after: list[str] = []
     if not no_predict_overlap:
-        prediction = _predict_overlap(config_path, repo, issue, existing_entries)
+        prediction, staleness_note = _predict_overlap(
+            config_path, repo, issue, existing_entries
+        )
         auto_after = _applicable_auto_after(
             existing_entries, repo, issue, after, prediction
         )
@@ -326,7 +331,17 @@ def drive_queue_add(
             gate += " (fleet-wide — nothing anywhere launches)"
         if resume_when:
             gate += f" (auto-resume when `{resume_when}` passes)"
-    overlap_note = f"\n{prediction.reason}" if auto_after else ""
+    # #2601: the reason (if an edge was actually applied), any high-fanout
+    # directory-token warning (independent of whether the edge stuck — a
+    # cycle-dropped edge's token is just as worth narrowing), and a staleness
+    # note when the candidate's own body could only be read from cache.
+    overlap_notes: list[str] = []
+    if auto_after:
+        overlap_notes.append(prediction.reason)
+    overlap_notes.extend(fanout_warnings(prediction))
+    if staleness_note:
+        overlap_notes.append(staleness_note)
+    overlap_note = ("\n" + "\n".join(overlap_notes)) if overlap_notes else ""
     click.echo(
         f"queued {entry_key(repo, issue)}{pinned}{suffix}{gate}"
         f"{scope_downgrade_warning}{overlap_note}"
@@ -372,6 +387,121 @@ def _issue_body(repo_name: str, issue_number: int) -> str:
         return ""
 
 
+def _live_issue_body(repo_github: str, issue_number: int) -> str | None:
+    """A live ``gh issue view`` body for the ONE entry actually being enqueued.
+
+    #2601: `_issue_body` above is a cache read by design — cheap, and correct
+    for the overwhelmingly common case (no ``## Files`` block at all) and for
+    every OTHER issue's declaration this module consults for a footprint. But
+    that same design let a `gh issue edit` made directly against the
+    tracker — bypassing `coord.state.edit_issue_content`'s cache mirror — go
+    unnoticed: the predictor kept citing the removed line forever, because
+    nothing had ever told the cache the edit happened.
+
+    Called ONLY for the candidate (see `_candidate_body`), and only when its
+    cached body already parses to a declaration — never on the common
+    empty-declaration path, so this does not reintroduce the per-``add``
+    GitHub round-trip the module was built to avoid.
+
+    Fails open like every other fetch here: ``None`` on any error, and the
+    caller falls back to the cached body.
+    """
+    if not repo_github:
+        return None
+    try:
+        from coord import github_ops  # noqa: PLC0415
+
+        data = github_ops.get_issue(repo_github, int(issue_number))
+    except Exception:  # noqa: BLE001 — see docstring
+        return None
+    if not data:
+        return None
+    return str(data.get("body") or "")
+
+
+def _mirror_issue_body(repo_name: str, issue_number: int, body: str) -> None:
+    """Write a freshly live-fetched body back into the local cache (#2601).
+
+    Best-effort, mirroring `_edit_issue_content_local`'s own cache write: the
+    live fetch above is authoritative, this only makes the freshness outlive
+    the one predict call it was fetched for — a later `add` for a DIFFERENT
+    issue that compares declaration-to-declaration against this one, or
+    `overlap-report`, should see the same answer without a second round-trip.
+    """
+    try:
+        from coord.db import get_connection  # noqa: PLC0415
+
+        conn = get_connection()
+        conn.execute(
+            "UPDATE issues SET body = ?, synced_at = ? "
+            "WHERE repo_name = ? AND number = ?",
+            (body, time.time(), repo_name, int(issue_number)),
+        )
+        conn.commit()
+    except Exception:  # noqa: BLE001 — the cache write is advisory
+        pass
+
+
+def _cached_body_age_note(repo_name: str, issue_number: int) -> str:
+    """#2601 point 1's fallback: when a live re-read wasn't possible, say how
+    old the cached body actually is, so a stale prediction is at least
+    visible instead of silently trusted.
+    """
+    row = None
+    try:
+        from coord.db import get_connection  # noqa: PLC0415
+
+        row = get_connection().execute(
+            "SELECT synced_at FROM issues WHERE repo_name = ? AND number = ?",
+            (repo_name, int(issue_number)),
+        ).fetchone()
+    except Exception:  # noqa: BLE001 — an unreadable age is still worth flagging
+        pass
+    synced_at = row["synced_at"] if row is not None else None
+    if not synced_at:
+        return (
+            "note: predicted from a cached issue body of unknown age "
+            "(live refresh failed) — the declaration may be stale"
+        )
+    age = _age_str(max(0.0, time.time() - float(synced_at)))
+    return (
+        f"note: predicted from a cached issue body synced {age} ago "
+        "(live refresh failed) — the declaration may be stale"
+    )
+
+
+def _candidate_body(
+    repo_name: str, issue_number: int, repo_github: str,
+) -> tuple[str, str]:
+    """This entry's OWN body — refreshed live when staleness could matter (#2601).
+
+    The natural correction to a bad prediction is editing the issue's ``##
+    Files`` block and re-adding. That did nothing (#2601) because the
+    predictor always read `_issue_body`'s cache, which a direct
+    ``gh issue edit`` never invalidates.
+
+    So the candidate gets one extra check the rest of the module does not:
+    if its cached body already parses to a declaration, re-read it live and
+    mirror the answer back into the cache. A body with NO cached declaration
+    skips the live round-trip entirely — there is nothing to have gone
+    stale, and a declaration ADDED since the last sync just falls back to
+    today's "no prediction" (rule 3), exactly as an unreadable body would.
+
+    Returns ``(body, staleness_note)``: *body* is what prediction runs
+    against; *staleness_note* is non-empty only when a live re-read was
+    warranted but failed.
+    """
+    cached = _issue_body(repo_name, issue_number)
+    if not parse_declared_files(cached):
+        return cached, ""
+    fresh = _live_issue_body(repo_github, issue_number)
+    if fresh is None:
+        return cached, _cached_body_age_note(repo_name, issue_number)
+    if fresh != cached:
+        _mirror_issue_body(repo_name, issue_number, fresh)
+    return fresh, ""
+
+
 def _repo_coordinates(config_path: Path, repo: str) -> tuple[str, str] | None:
     """``(github slug, default branch)`` for *repo*, or ``None``."""
     try:
@@ -387,27 +517,38 @@ def _repo_coordinates(config_path: Path, repo: str) -> tuple[str, str] | None:
 
 def _predict_overlap(
     config_path: Path, repo: str, issue: int, existing_entries: list[QueueEntry],
-) -> Prediction:
+) -> tuple[Prediction, str]:
     """Compare this issue's declared files against work already in flight.
 
     Same-repo only: two repos' paths cannot collide, and comparing them would
     manufacture overlaps out of a shared filename. In-flight branches are
     checked first (ground truth); a queued entry with no branch yet is
     compared declaration-to-declaration, and only when it has one.
+
+    Returns ``(prediction, staleness_note)`` — see `_candidate_body` for when
+    the note is non-empty. Every OTHER body this consults (an in-flight
+    branch's own declaration, an unrelated queued entry's) still comes from
+    the plain cache: re-reading fifteen bodies live on every `add` is exactly
+    the cost the module's docstring rejects, and #2601's own report is about
+    correcting THIS entry's declaration, not anyone else's.
     """
     coordinates = _repo_coordinates(config_path, repo)
     if coordinates is None:
-        return Prediction()
+        return Prediction(), ""
     repo_github, base_branch = coordinates
 
+    candidate_body, staleness_note = _candidate_body(repo, issue, repo_github)
+
     def body_fetcher(repo_name: str, number: int) -> str:
+        if repo_name == repo and number == issue:
+            return candidate_body
         return _issue_body(repo_name, number)
 
     candidate = collect_candidate_files(repo, issue, body_fetcher)
     if not candidate:
         # Rule 3: no prediction is a valid answer. Nothing is fetched, nothing
         # is compared, and the add is byte-identical to the pre-#2247 one.
-        return Prediction()
+        return Prediction(), ""
 
     key = entry_key(repo, issue)
     footprints = inflight_footprints(
@@ -422,7 +563,7 @@ def _predict_overlap(
         and e.state not in TERMINAL_QUEUE_STATES
     ]
     footprints.extend(declared_footprints(queued, body_fetcher, exclude_keys=covered))
-    return predict_overlap(candidate, footprints, exclude_keys={key})
+    return predict_overlap(candidate, footprints, exclude_keys={key}), staleness_note
 
 
 def _applicable_auto_after(

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/coord/commands/milestone.py

@@ -1127,6 +1127,7 @@ def milestone_dispatch_cmd(
         _predict_overlap,
         _record_overlap_prediction,
     )
+    from coord.overlap_predict import fanout_warnings  # noqa: PLC0415
     from coord.drive_queue import (  # noqa: PLC0415
         QueueError,
         entries_from_rows,
@@ -1150,7 +1151,7 @@ def milestone_dispatch_cmd(
             click.echo(f"  {key}: not queued: {exc}", err=True)
             failures += 1
             continue
-        prediction = _predict_overlap(
+        prediction, staleness_note = _predict_overlap(
             config_path, repo_entry.name, qe.issue_number, existing
         )
         auto_after = _applicable_auto_after(
@@ -1163,7 +1164,16 @@ def milestone_dispatch_cmd(
                 repo_entry.name, qe.issue_number, prediction, auto_after
             )
         suffix = f" after {', '.join(after)}" if after else ""
-        overlap_note = f"\n     {prediction.reason}" if auto_after else ""
+        # #2601: same notes `drive-queue add` surfaces — the applied reason,
+        # any high-fanout directory-token warning, and a staleness note when
+        # this entry's own body could only be read from cache.
+        notes = []
+        if auto_after:
+            notes.append(prediction.reason)
+        notes.extend(fanout_warnings(prediction))
+        if staleness_note:
+            notes.append(staleness_note)
+        overlap_note = ("\n     " + "\n     ".join(notes)) if notes else ""
         click.echo(f"  queued {key}{suffix}{overlap_note}")
         queued += 1
 

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/coord/overlap_predict.py

@@ -45,6 +45,16 @@ author's own declaration. The seam for it is
 one up yet, because rule 3 says a missing prediction is fine and a *bad* one
 is not. Ship the cheap, exact source first and let the recorded accuracy
 (see :func:`classify_outcome`) justify adding a fuzzier one.
+
+DELIBERATELY NOT IMPLEMENTED (#2601): a hardcoded exclusion list for
+"universal" directory tokens (``tests/``, ``docs/``) that every issue touches.
+It was considered — #2601 found that a single bare ``tests/`` declaration
+chained one issue behind fourteen others that each named a specific,
+disjoint file — but excluding it outright would make rule 1 lie: those
+fourteen ARE what :func:`paths_overlap`'s directory rule says they are, a
+match. The chosen fix is :func:`fanout_warnings`, which leaves the ORDER
+alone and instead tells the author their token was too broad to carry much
+signal, so they can narrow it on the next ``add``.
 """
 
 from __future__ import annotations
@@ -345,6 +355,47 @@ def predict_overlap(
     return Prediction(predicted_files=files, overlaps=tuple(overlaps))
 
 
+# Above this many DISTINCT entries hit by one declared directory token, the
+# match is far more likely a token that happens to be common across the whole
+# repo (``tests/``, ``docs/``) than a deliberate "this covers one feature's
+# tests" declaration. #2601's incident was 14 against a threshold this
+# conservative; two or three files genuinely clustered under one directory is
+# unremarkable and must not warn.
+FANOUT_WARN_THRESHOLD = 3
+
+
+def fanout_warnings(
+    prediction: Prediction, *, threshold: int = FANOUT_WARN_THRESHOLD,
+) -> list[str]:
+    """Declared directory tokens that matched implausibly many entries (#2601).
+
+    :func:`paths_overlap`'s directory rule — a trailing-slash declaration
+    covers everything beneath it — is deliberate: it is the one
+    generalisation an author can write down unambiguously. But a token that
+    is common across the whole repo (``tests/``, ``docs/``) satisfies that
+    rule while carrying almost no signal: #2601 watched one bare ``tests/``
+    declaration chain an issue behind fourteen others it never actually
+    conflicted with.
+
+    This does NOT change the ORDER — rule 1 ("order, never refuse") holds
+    regardless of fanout; every one of those fourteen edges is still applied.
+    It only surfaces the count, so an author can tell a token was too broad
+    and narrow it to a specific file on the next ``add``.
+    """
+    counts: dict[str, int] = {}
+    for overlap in prediction.overlaps:
+        for path in overlap.files:
+            if path.endswith("/"):
+                counts[path] = counts.get(path, 0) + 1
+    return [
+        f"warning: `{path}` matched {count} entries — did you mean a "
+        "specific file? (#2247 orders against all of them regardless — this "
+        "changes nothing, it only flags the token)"
+        for path, count in sorted(counts.items())
+        if count > threshold
+    ]
+
+
 # ── gathering the two sides ──────────────────────────────────────────────────
 
 # ``(repo_github, base, head) -> changed paths or None`` — same shape as

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/tests/test_cli_drive_queue.py

@@ -398,6 +398,105 @@ def test_an_inferred_edge_never_fails_an_add_it_would_cycle(cli, declare):
     assert queued(306)["after_json"] == []
 
 
+# ── #2601: fanout warning + fresh-body re-read ───────────────────────────────
+
+
+def test_a_bare_directory_declaration_warns_about_high_fanout(cli, declare):
+    # `tests/` matches every one of these disjoint, precisely-declared files —
+    # a real match under #2247's directory rule (still ORDERED, never
+    # refused), but a signal-free one that deserves a warning, not silence.
+    for i, number in enumerate((401, 402, 403, 404)):
+        declare(number, f"tests/test_worker_{i}.py")
+        assert cli("add", REPO, str(number)).exit_code == 0
+
+    declare(405, "tests/")
+    result = cli("add", REPO, "405")
+
+    assert result.exit_code == 0, result.output
+    assert "warning:" in result.output
+    assert "`tests/`" in result.output
+    assert "4 entries" in result.output
+    # ORDER, never REFUSE — every one of the four is still applied.
+    assert len(queued(405)["after_json"]) == 4
+
+
+def test_a_directory_declaration_under_the_fanout_threshold_does_not_warn(cli, declare):
+    declare(410, "tests/test_a.py")
+    declare(411, "tests/test_b.py")
+    assert cli("add", REPO, "410").exit_code == 0
+    assert cli("add", REPO, "411").exit_code == 0
+
+    declare(412, "tests/")
+    result = cli("add", REPO, "412")
+
+    assert result.exit_code == 0, result.output
+    assert "warning:" not in result.output
+
+
+def test_editing_the_issue_live_narrows_a_stale_bare_directory_declaration(
+    cli, declare, monkeypatch,
+):
+    # #2601: the cache still holds the old, bare `tests/` declaration — but
+    # the author has since edited the issue directly on the tracker (`gh
+    # issue edit`, which never mirrors into coord's cache) to a specific file
+    # that touches neither #510 nor #511. A re-`add` must predict from the
+    # LIVE body, not the stale cached one that would otherwise chain it
+    # behind both.
+    declare(510, "tests/test_a.py")
+    declare(511, "tests/test_b.py")
+    assert cli("add", REPO, "510").exit_code == 0
+    assert cli("add", REPO, "511").exit_code == 0
+
+    declare(512, "tests/")
+    monkeypatch.setattr(
+        "coord.github_ops.get_issue",
+        lambda repo, number: {"body": "## Files\n- `coord/only_mine.py`\n"},
+    )
+
+    result = cli("add", REPO, "512")
+
+    assert result.exit_code == 0, result.output
+    assert queued(512)["after_json"] == []
+    assert "predicted file overlap" not in result.output
+    assert "warning:" not in result.output
+    # The live body is mirrored into the cache, not just used for this call.
+    from coord.db import get_connection
+
+    row = get_connection().execute(
+        "SELECT body FROM issues WHERE repo_name = ? AND number = ?", (REPO, 512),
+    ).fetchone()
+    assert "only_mine.py" in row["body"]
+
+
+def test_a_live_refresh_failure_falls_back_to_cache_with_a_staleness_note(
+    cli, declare, monkeypatch,
+):
+    declare(520, "coord/only_mine.py")
+    monkeypatch.setattr(
+        "coord.github_ops.get_issue",
+        lambda repo, number: (_ for _ in ()).throw(RuntimeError("gh unreachable")),
+    )
+
+    result = cli("add", REPO, "520")
+
+    assert result.exit_code == 0, result.output
+    assert "note: predicted from a cached issue body" in result.output
+
+
+def test_an_issue_with_no_cached_declaration_never_triggers_a_live_fetch(
+    cli, monkeypatch,
+):
+    calls: list[int] = []
+    monkeypatch.setattr(
+        "coord.github_ops.get_issue",
+        lambda repo, number: calls.append(number) or {"body": ""},
+    )
+    # No `## Files` block at all — the common case #2247's docstring is
+    # built around; this must stay a pure cache read with zero GitHub calls.
+    assert cli("add", REPO, "521").exit_code == 0
+    assert calls == []
+
+
 def test_overlap_report_scores_a_prediction_against_the_real_diffs(
     cli, declare, seed, branch_diff,
 ):

{code_coordinator-0.5.240 → code_coordinator-0.5.241}/tests/test_overlap_predict.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from types import SimpleNamespace
 
 from coord.overlap_predict import (
+    FANOUT_WARN_THRESHOLD,
     OUTCOME_CONFIRMED,
     OUTCOME_FALSE_POSITIVE,
     OUTCOME_UNKNOWN,
@@ -22,6 +23,7 @@ from coord.overlap_predict import (
     classify_outcome,
     collect_candidate_files,
     declared_footprints,
+    fanout_warnings,
     inflight_assignments,
     inflight_footprints,
     parse_declared_files,
@@ -144,6 +146,54 @@ def test_excluded_keys_never_become_pre_reqs():
     assert not prediction
 
 
+# ── fanout_warnings (#2601) ──────────────────────────────────────────────────
+
+
+def _footprints_declaring_specific_files(count: int) -> list[Footprint]:
+    return [
+        Footprint(
+            key=f"{REPO}#{100 + i}",
+            issue_number=100 + i,
+            files=(f"tests/test_{i}.py",),
+            source=SOURCE_DECLARED,
+        )
+        for i in range(count)
+    ]
+
+
+def test_a_bare_directory_declaration_matching_many_entries_warns():
+    footprints = _footprints_declaring_specific_files(FANOUT_WARN_THRESHOLD + 1)
+    prediction = predict_overlap(["tests/"], footprints)
+    assert len(prediction.overlaps) == FANOUT_WARN_THRESHOLD + 1
+
+    warnings = fanout_warnings(prediction)
+    assert len(warnings) == 1
+    assert "`tests/`" in warnings[0]
+    assert str(FANOUT_WARN_THRESHOLD + 1) in warnings[0]
+    # The order is NOT touched by the warning — every edge is still applied.
+    assert len(prediction.after_keys) == FANOUT_WARN_THRESHOLD + 1
+
+
+def test_a_directory_declaration_at_or_under_the_threshold_does_not_warn():
+    footprints = _footprints_declaring_specific_files(FANOUT_WARN_THRESHOLD)
+    prediction = predict_overlap(["tests/"], footprints)
+    assert fanout_warnings(prediction) == []
+
+
+def test_a_specific_file_match_never_warns_regardless_of_count():
+    footprints = [
+        Footprint(
+            key=f"{REPO}#{200 + i}",
+            issue_number=200 + i,
+            files=("coord/drive_queue.py",),
+            source=SOURCE_DECLARED,
+        )
+        for i in range(FANOUT_WARN_THRESHOLD + 5)
+    ]
+    prediction = predict_overlap(["coord/drive_queue.py"], footprints)
+    assert fanout_warnings(prediction) == []
+
+
 def test_audit_details_carry_both_sides_of_the_claim():
     prediction = Prediction(
         predicted_files=("coord/a.py",),