code-coordinator 0.5.90__tar.gz → 0.5.91__tar.gz

{code_coordinator-0.5.90 → code_coordinator-0.5.91}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.90
+Version: 0.5.91
 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.90 → code_coordinator-0.5.91}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.90
+Version: 0.5.91
 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.90 → code_coordinator-0.5.91}/code_coordinator.egg-info/SOURCES.txt

@@ -316,6 +316,7 @@ coord/health/checks/fleet_phantom.py
 coord/health/checks/fleet_unit_drift.py
 coord/health/checks/graph.py
 coord/health/checks/graphify_cli.py
+coord/health/checks/index_lock.py
 coord/health/checks/plan_usage.py
 coord/health/checks/repo_state.py
 coord/health/checks/spawned_coord.py

{code_coordinator-0.5.90 → code_coordinator-0.5.91}/code_coordinator.egg-info/scm_file_list.json

@@ -227,6 +227,7 @@
     "coord/health/checks/fleet_unit_drift.py",
     "coord/health/checks/graph.py",
     "coord/health/checks/graphify_cli.py",
+    "coord/health/checks/index_lock.py",
     "coord/health/checks/plan_usage.py",
     "coord/health/checks/repo_state.py",
     "coord/health/checks/spawned_coord.py",

{code_coordinator-0.5.90 → code_coordinator-0.5.91}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.90",
+  "tag": "0.5.91",
   "distance": 0,
-  "node": "g6262b3b6410205aa0717b6e237898dd957670708",
+  "node": "g39a4e989b2e78a6c7a1571c5f488f9fa1f70ca4f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-15"

{code_coordinator-0.5.90 → code_coordinator-0.5.91}/coord/config.py

@@ -1489,6 +1489,15 @@ class HealthConfig:
     worktree_warn_count: int = 3
     worktree_crit_count: int = 10
 
+    # ── stale .git/index.lock in a known checkout (#2206) ──────────────────
+    # A few minutes is generous: real git index operations are sub-second,
+    # so a lock this old is either a live operation on an enormous repo (rare
+    # and worth a look anyway) or, far more often, a killed git process that
+    # will never clean up after itself.  A lock younger than this is never
+    # flagged regardless of holder; a lock held by a live process is never
+    # flagged regardless of age.
+    index_lock_stale_minutes: float = 10.0
+
     # ── agent install ─────────────────────────────────────────────────────
     # Absolute path to the agent venv's python.  None → autodetect
     # (~/.coord-venv/bin/python3, else the running interpreter).
@@ -2860,6 +2869,7 @@ _HEALTH_FLOAT_FIELDS: dict[str, float] = {
     "cargo_target_crit_gb": 0.0,
     "cargo_scan_budget_secs": 0.0,
     "worktree_stale_hours": 0.0,
+    "index_lock_stale_minutes": 0.0,
     "network_timeout_secs": 0.0,
     "graph_stale_warn_hours": 0.0,
     "graph_stale_crit_hours": 0.0,

code_coordinator-0.5.91/coord/health/checks/index_lock.py

@@ -0,0 +1,204 @@
+"""Stale ``.git/index.lock`` across known checkouts (#2206).
+
+**The elitebook incident, 2026-08-13.** A zero-byte ``index.lock`` sat in
+the base ``claude-coordinator`` checkout for 8h45m — created by a git
+process that got killed before it wrote anything, and never cleaned up.
+``git pull`` is fetch + merge, and only the *working-tree* half is blocked
+by the lock: the fetch kept succeeding the whole time, so ``origin/*`` refs
+stayed current and every worktree cut from ``origin/main`` was unaffected.
+That's exactly why the condition is silent by construction — the host
+reports online and idle, ``coord status`` shows nothing, the agent keeps
+accepting work, and the only thing actually wrong is that the *base
+checkout's files* sat 8h45m stale while the graphify graph, tooling, and any
+human reading source from it all read code that no longer matched HEAD.
+``grep -rn "index.lock" coord/`` returned nothing before this file: no
+surface anywhere reported it. The only signal was a human happening to run
+``git pull`` by hand and reading the error.
+
+**Both conditions matter, and either one alone is not enough.** A lock
+that's merely old could still be a legitimate multi-minute operation on an
+enormous repo — flagging on age alone would false-positive on that. A lock
+with no way to check for a holder could still be actively held by a process
+this box can't see into — flagging without ever trying to check for a
+holder would be reckless. So: present, older than a generous threshold
+(``index_lock_stale_minutes`` — real git index operations are sub-second),
+**and** no live process holding it, is what gets reported. A lock a running
+git legitimately holds is never flagged, at any age.
+
+**This check never deletes anything.** ``coord diagnose`` already has a
+history of being destructive when it looked read-only (#1693 destroyed a
+worker worktree base with an unguarded operation), and the one case where
+deleting a lock is wrong — a live holder — is exactly the case a false
+"no holder" verdict would produce. The finding names the path and the
+remedy (``rm -f <path>``, once a human has confirmed no live git process
+holds it) and stops there.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from coord.health.models import CheckResult, HealthContext, Severity
+from coord.health.registry import check
+from coord.health.units import human_hours
+
+# Overridable in tests; there is no config knob for this because /proc is a
+# platform fact, not an operator preference.
+_PROC_ROOT = Path("/proc")
+
+_DEFAULT_STALE_MINUTES = 10.0
+
+# A fd symlink whose target has been unlinked while still open (exactly the
+# state of a lock a git process is mid-delete on) reads as
+# "/path/to/index.lock (deleted)", not the bare path.
+_DELETED_SUFFIX = " (deleted)"
+
+
+def _fd_target(link: str) -> str:
+    if link.endswith(_DELETED_SUFFIX):
+        return link[: -len(_DELETED_SUFFIX)]
+    return link
+
+
+def has_open_holder(lock_path: Path, *, proc_root: Path | None = None) -> bool | None:
+    """Whether a live process holds *lock_path* open right now.
+
+    Answers what ``fuser <path>`` answers, without assuming ``fuser`` is
+    installed: walk ``/proc/*/fd`` looking for a descriptor whose target is
+    this exact path.
+
+    Returns ``True``/``False`` when the scan actually ran, ``None`` when
+    ``/proc`` itself could not be listed at all — no Linux ``/proc``, or a
+    sandbox that hides it entirely. The caller treats ``None`` as "fell back
+    to age-only" and says so in the finding at reduced confidence, rather
+    than either silently assuming a holder (never flags) or silently
+    assuming none (flags something a live process might hold).
+
+    A single process whose own ``fd`` directory can't be read (another
+    user's, or one that exited between the pid listing and the read) is
+    skipped, not treated as a scan failure — every relevant process on this
+    fleet runs as the same user, and letting one unreadable pid abort the
+    whole scan would hide a holder this box *can* see among the rest.
+    """
+    root = proc_root or _PROC_ROOT
+    try:
+        pids = [entry.name for entry in root.iterdir() if entry.name.isdigit()]
+    except OSError:
+        return None
+
+    target = str(lock_path)
+    for pid in pids:
+        try:
+            fds = list((root / pid / "fd").iterdir())
+        except OSError:
+            continue
+        for fd in fds:
+            try:
+                link = os.readlink(fd)
+            except OSError:
+                continue
+            if _fd_target(link) == target:
+                return True
+    return False
+
+
+@check(
+    id="index_lock",
+    scope="machine",
+    title="index lock",
+    order=31,
+    description="Stale .git/index.lock files blocking a checkout's working tree.",
+)
+def probe_index_lock(ctx: HealthContext) -> CheckResult | None:
+    """One machine-scope result: every known checkout's index.lock, if stale."""
+    if not ctx.checkouts:
+        return None
+
+    th = ctx.thresholds
+    stale_minutes = float(
+        getattr(th, "index_lock_stale_minutes", _DEFAULT_STALE_MINUTES)
+    )
+    stale_seconds = stale_minutes * 60.0
+
+    stale: list[tuple[str, str, float, str]] = []  # name, path, age_secs, confidence
+    held: list[str] = []
+    reduced_confidence = False
+
+    for checkout in ctx.checkouts:
+        lock_path = checkout.path / ".git" / "index.lock"
+        try:
+            mtime = lock_path.stat().st_mtime
+        except OSError:
+            continue  # no lock — the overwhelmingly common state
+
+        age = ctx.now - mtime
+        if age < stale_seconds:
+            continue  # young enough to be an in-flight git operation
+
+        holder = has_open_holder(lock_path)
+        if holder is True:
+            held.append(checkout.name)
+            continue
+
+        if holder is None:
+            reduced_confidence = True
+            confidence = "reduced (no /proc access to confirm no holder)"
+        else:
+            confidence = "high"
+        stale.append((checkout.name, str(lock_path), age, confidence))
+
+    if not stale:
+        headroom = "no stale locks"
+        if held:
+            headroom += f" ({', '.join(held)} in use)"
+        return CheckResult(
+            check_id="index_lock",
+            scope="machine",
+            severity=Severity.OK,
+            headroom=headroom,
+            threshold=f"crit past {stale_minutes:.0f}m with no live holder",
+            values={
+                "checked": len(ctx.checkouts),
+                "stale": [],
+                "held": held,
+                "stale_minutes_threshold": stale_minutes,
+            },
+        )
+
+    stale.sort(key=lambda row: row[2], reverse=True)
+    named = "; ".join(
+        f"{name}: {path} ({human_hours(age)} old)" for name, path, age, _ in stale
+    )
+    plural = "s" if len(stale) != 1 else ""
+    headroom = f"{len(stale)} stale lock{plural}: {named}"
+    if reduced_confidence:
+        headroom += " [holder check unavailable on this box — age-only]"
+
+    detail = "; ".join(
+        f"rm -f {path}  # once no live git process is confirmed holding it"
+        for _, path, _age, _conf in stale
+    )
+
+    return CheckResult(
+        check_id="index_lock",
+        scope="machine",
+        severity=Severity.CRIT,
+        headroom=headroom,
+        threshold=f"crit past {stale_minutes:.0f}m with no live holder",
+        detail=detail,
+        values={
+            "checked": len(ctx.checkouts),
+            "stale": [
+                {
+                    "name": name,
+                    "path": path,
+                    "age_hours": round(age / 3600.0, 2),
+                    "confidence": confidence,
+                }
+                for name, path, age, confidence in stale
+            ],
+            "held": held,
+            "stale_minutes_threshold": stale_minutes,
+        },
+    )

{code_coordinator-0.5.90 → code_coordinator-0.5.91}/tests/test_health_checks.py

@@ -20,6 +20,7 @@ from coord.health.checks import (
     claude_binary,
     disk,
     graph,
+    index_lock,
     plan_usage,
     repo_state,
     worktrees,
@@ -356,6 +357,121 @@ def test_worktrees_crit_above_ten_stale(tmp_path) -> None:
     assert "coord diagnose --orphan-worktrees" in result.detail
 
 
+# ── index lock (#2206) ───────────────────────────────────────────────────────
+
+
+def _lock_checkout(
+    tmp_path: Path, name: str, *, age_seconds: float | None, now: float = NOW
+) -> tuple[Checkout, Path]:
+    """A checkout whose ``.git/index.lock`` is *age_seconds* old, or absent
+    if *age_seconds* is ``None``."""
+    repo = tmp_path / name
+    lock = repo / ".git" / "index.lock"
+    lock.parent.mkdir(parents=True)
+    if age_seconds is not None:
+        lock.write_bytes(b"")
+        stamp = now - age_seconds
+        import os
+
+        os.utime(lock, (stamp, stamp))
+    return Checkout(name=name, path=repo), lock
+
+
+def _fake_proc_holder(tmp_path: Path, pid: int, target: Path) -> Path:
+    """A ``/proc`` fixture where *pid* holds an fd open on *target*."""
+    proc_root = tmp_path / "proc"
+    fd_dir = proc_root / str(pid) / "fd"
+    fd_dir.mkdir(parents=True)
+    import os
+
+    os.symlink(str(target), fd_dir / "5")
+    return proc_root
+
+
+def test_index_lock_no_checkouts_reports_nothing(tmp_path) -> None:
+    assert index_lock.probe_index_lock(make_ctx(tmp_path)) is None
+
+
+def test_index_lock_absent_is_ok(tmp_path) -> None:
+    checkout, _lock = _lock_checkout(tmp_path, "vimcode", age_seconds=None)
+    result = index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert result.severity is Severity.OK
+    assert result.headroom == "no stale locks"
+
+
+def test_index_lock_younger_than_threshold_is_not_flagged(tmp_path) -> None:
+    checkout, _lock = _lock_checkout(tmp_path, "vimcode", age_seconds=30.0)
+    result = index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert result.severity is Severity.OK
+
+
+def test_index_lock_stale_with_no_holder_is_reported(tmp_path, monkeypatch) -> None:
+    """The exact elitebook condition: present, no holder, older than the
+    threshold — must be reported, naming the path. This must fail before
+    the #2206 fix exists."""
+    checkout, lock = _lock_checkout(tmp_path, "claude-coordinator", age_seconds=3600.0)
+    # An empty (but readable) /proc fixture -> the scan actually ran and
+    # legitimately found nothing holding it, not "couldn't check".
+    proc_root = tmp_path / "proc"
+    proc_root.mkdir()
+    monkeypatch.setattr(index_lock, "_PROC_ROOT", proc_root)
+    result = index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert result.severity is Severity.CRIT
+    assert str(lock) in result.headroom
+    assert f"rm -f {lock}" in result.detail
+    assert result.values["stale"][0]["confidence"] == "high"
+
+
+def test_index_lock_held_by_live_process_is_never_flagged(tmp_path, monkeypatch) -> None:
+    """A lock a live process holds must not be flagged, at any age."""
+    checkout, lock = _lock_checkout(tmp_path, "vimcode", age_seconds=999_999.0)
+    proc_root = _fake_proc_holder(tmp_path, pid=4242, target=lock)
+    monkeypatch.setattr(index_lock, "_PROC_ROOT", proc_root)
+    result = index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert result.severity is Severity.OK
+    assert "vimcode" in result.headroom
+
+
+def test_index_lock_no_proc_access_falls_back_to_age_with_reduced_confidence(
+    tmp_path, monkeypatch
+) -> None:
+    checkout, _lock = _lock_checkout(tmp_path, "vimcode", age_seconds=3600.0)
+    # Point at a /proc that doesn't exist at all.
+    monkeypatch.setattr(index_lock, "_PROC_ROOT", tmp_path / "no-such-proc")
+    result = index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert result.severity is Severity.CRIT
+    assert result.values["stale"][0]["confidence"].startswith("reduced")
+    assert "holder check unavailable" in result.headroom
+
+
+def test_index_lock_never_modifies_the_filesystem(tmp_path, monkeypatch) -> None:
+    checkout, lock = _lock_checkout(tmp_path, "vimcode", age_seconds=3600.0)
+    monkeypatch.setattr(index_lock, "_PROC_ROOT", tmp_path / "proc")
+    index_lock.probe_index_lock(make_ctx(tmp_path, checkouts=(checkout,)))
+    assert lock.exists()
+
+
+def test_has_open_holder_matches_an_open_fd(tmp_path) -> None:
+    target = tmp_path / "repo" / ".git" / "index.lock"
+    target.parent.mkdir(parents=True)
+    target.write_bytes(b"")
+    proc_root = _fake_proc_holder(tmp_path, pid=99, target=target)
+    assert index_lock.has_open_holder(target, proc_root=proc_root) is True
+
+
+def test_has_open_holder_returns_false_when_scan_completes_clean(tmp_path) -> None:
+    target = tmp_path / "repo" / ".git" / "index.lock"
+    proc_root = tmp_path / "proc"
+    (proc_root / "1" / "fd").mkdir(parents=True)
+    assert index_lock.has_open_holder(target, proc_root=proc_root) is False
+
+
+def test_has_open_holder_returns_none_when_proc_is_unreadable(tmp_path) -> None:
+    proc_root = tmp_path / "does-not-exist"
+    target = tmp_path / "repo" / ".git" / "index.lock"
+    assert index_lock.has_open_holder(target, proc_root=proc_root) is None
+
+
 # ── agent install ────────────────────────────────────────────────────────────