code-coordinator 0.5.579__tar.gz → 0.5.580__tar.gz

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/PKG-INFO

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

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

@@ -70,6 +70,7 @@ coord/deploy_units.py
 coord/deprecation_telemetry.py
 coord/deps.py
 coord/diagnose.py
+coord/dirlink.py
 coord/dispatch.py
 coord/dispatch_liveness.py
 coord/dist_name.py
@@ -619,6 +620,7 @@ tests/test_deploy_web_unit.py
 tests/test_deprecation_telemetry.py
 tests/test_deps.py
 tests/test_diagnose.py
+tests/test_dirlink.py
 tests/test_dispatch.py
 tests/test_dispatch_liveness.py
 tests/test_dispatch_target_validation.py

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/code_coordinator.egg-info/scm_file_list.json

@@ -132,6 +132,7 @@
     "coord/deprecation_telemetry.py",
     "coord/deps.py",
     "coord/diagnose.py",
+    "coord/dirlink.py",
     "coord/dispatch.py",
     "coord/dispatch_liveness.py",
     "coord/dist_name.py",
@@ -646,6 +647,7 @@
     "tests/test_deprecation_telemetry.py",
     "tests/test_deps.py",
     "tests/test_diagnose.py",
+    "tests/test_dirlink.py",
     "tests/test_dispatch.py",
     "tests/test_dispatch_liveness.py",
     "tests/test_dispatch_target_validation.py",

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.579",
+  "tag": "0.5.580",
   "distance": 0,
-  "node": "gffb8247183c93a6cbb6c084e08884f093c485a20",
+  "node": "gd3b3a8b69209767b94d3b03aeea8d17b2a32d9f9",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-03"

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/coord/agent_update.py

@@ -13,11 +13,16 @@ An update must be all-or-nothing.
 The fix: never write into the venv that's live. Install the target version
 into a **fresh** venv — one of two fixed "slots" next to the live one
 (``~/.coord-venv.blue`` / ``~/.coord-venv.green``) — smoke-check it, and
-only then flip a symlink so ``~/.coord-venv`` always resolves to one
-*complete* slot, old or new, never a mix. Rename of a symlink onto an
-existing path is atomic on POSIX (same filesystem), so any `coord`
-invocation racing the flip sees either the fully-old or the fully-new
-install — there is no observable in-between state.
+only then flip a directory link (see :mod:`coord.dirlink`) so
+``~/.coord-venv`` always resolves to one *complete* slot, old or new, never
+a mix. Rename of a symlink onto an existing path is atomic on POSIX (same
+filesystem), so any `coord` invocation racing the flip sees either the
+fully-old or the fully-new install — there is no observable in-between
+state. #2842: POSIX uses a symlink for exactly that atomicity guarantee;
+win32 has no directory-reparse-point equivalent of an atomic rename-over,
+so there the flip is best-effort (old link removed, new one renamed in
+immediately after) rather than a silent single-platform fiction — see
+:mod:`coord.dirlink` for the full reasoning.
 
 Using exactly two named slots (rather than a fresh directory per release)
 also gives rollback for free: the slot that was live before the swap is
@@ -86,6 +91,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from coord import restart_cmd
+from coord.dirlink import is_dir_link, make_dir_link, read_dir_link, replace_dir_link
 from coord.platform_paths import venv_exe, venv_pip, venv_python
 
 _log = logging.getLogger(__name__)
@@ -391,23 +397,24 @@ def current_slot(venv_dir: Path) -> Path | None:
     way, since ``install-agent.sh`` creates ``~/.coord-venv`` as a real
     directory.
     """
-    if not venv_dir.is_symlink():
+    if not is_dir_link(venv_dir):
         return None
-    target = venv_dir.readlink()
+    target = read_dir_link(venv_dir)
     if not target.is_absolute():
         target = (venv_dir.parent / target).resolve()
     return target
 
 
 def ensure_symlink_layout(venv_dir: Path) -> Path:
-    """Migrate *venv_dir* to the blue/green symlink layout if it isn't already.
-
-    Idempotent: if *venv_dir* is already a symlink, just returns its current
-    target. Otherwise renames the existing plain directory into the
-    ``.blue`` slot and replaces *venv_dir* with a symlink pointing at it.
-    This is the one-time, one-machine migration every pre-#1241 install
-    needs; every update after that stays in the symlink layout, so this
-    becomes a no-op for the rest of that machine's life.
+    """Migrate *venv_dir* to the blue/green link layout if it isn't already.
+
+    Idempotent: if *venv_dir* is already a directory link (a symlink on
+    POSIX, a junction on win32 — see :mod:`coord.dirlink`), just returns
+    its current target. Otherwise renames the existing plain directory
+    into the ``.blue`` slot and replaces *venv_dir* with a link pointing at
+    it. This is the one-time, one-machine migration every pre-#1241
+    install needs; every update after that stays in the link layout, so
+    this becomes a no-op for the rest of that machine's life.
     """
     existing = current_slot(venv_dir)
     if existing is not None:
@@ -418,13 +425,13 @@ def ensure_symlink_layout(venv_dir: Path) -> Path:
     if blue.exists():
         # Should be unreachable — `blue`/`green` only ever come into being
         # via this function or `perform_update`, both gated on `venv_dir`
-        # not already being a symlink. Refuse rather than clobber whatever
-        # is there.
+        # not already being a directory link. Refuse rather than clobber
+        # whatever is there.
         raise FileExistsError(
             f"{blue} already exists — refusing to migrate {venv_dir} over it"
         )
     venv_dir.rename(blue)
-    venv_dir.symlink_to(blue, target_is_directory=True)
+    make_dir_link(venv_dir, blue)
     return blue
 
 
@@ -517,20 +524,18 @@ def running_slot(venv_dir: Path) -> Path | None:
 
 
 def _atomic_swap(venv_dir: Path, new_slot: Path) -> None:
-    """Flip *venv_dir* to point at *new_slot* in one filesystem operation.
-
-    Builds the new symlink at a temp path next to *venv_dir* and renames it
-    directly onto *venv_dir* — ``rename()`` replacing an existing path is
-    atomic on POSIX when both are on the same filesystem (true here: both
-    are siblings under the same parent directory), so any `coord`
-    invocation racing this always sees either the old, complete slot or the
-    new, complete slot — never a half-updated ``venv_dir``.
+    """Flip *venv_dir* to point at *new_slot*.
+
+    Delegates to :func:`coord.dirlink.replace_dir_link`: atomic on POSIX
+    (a symlink `rename()` onto an existing path is a single filesystem
+    operation there, so any `coord` invocation racing this always sees
+    either the old, complete slot or the new, complete slot — never a
+    half-updated ``venv_dir``) and best-effort on win32, where a directory
+    junction has no equivalent single-syscall replace (#2842) — see that
+    module's docstring for the platform difference this does *not* paper
+    over.
     """
-    tmp_link = venv_dir.parent / f".{venv_dir.name}.next-link"
-    if tmp_link.is_symlink() or tmp_link.exists():
-        tmp_link.unlink()
-    tmp_link.symlink_to(new_slot, target_is_directory=True)
-    tmp_link.replace(venv_dir)
+    replace_dir_link(venv_dir, new_slot)
 
 
 def _smoke_check(slot: Path, *, target_version: str | None) -> tuple[bool, str | None, str]:

code_coordinator-0.5.580/coord/dirlink.py

@@ -0,0 +1,124 @@
+"""Cross-platform directory links: symlinks on POSIX, junctions on win32 (#2842).
+
+``coord.agent_update``'s blue/green venv swap used to call
+``Path.symlink_to``/``Path.readlink``/``Path.is_symlink`` directly, which is
+POSIX-correct but breaks two ways on win32:
+
+1. **Creating a directory symlink needs a privilege** most installs don't
+   have (Developer Mode or ``SeCreateSymbolicLinkPrivilege``) — relying on it
+   is not portable even when it happens to be available on a given box.
+2. **Replacing an existing directory symlink via ``os.replace``/
+   ``Path.replace`` fails outright** with ``[WinError 5] Access is denied``.
+   The POSIX guarantee that ``rename(2)`` atomically replaces a symlink has
+   no direct win32 equivalent for directory reparse points.
+
+The portable substitute is a **directory junction**
+(``_winapi.CreateJunction``, the same thing ``mklink /J`` produces), which
+needs no special privilege. This is the identical substitution #1163 (CP-7)
+already names for the git-worktree symlink problem — so this module is
+intentionally generic (it knows nothing about venvs or worktrees) and
+*both* call sites should route through it rather than each growing their
+own win32 branch. :mod:`coord.agent_update` is the first consumer; #1163's
+worktree-junction work should become the second rather than reinventing
+this.
+
+Junctions are not atomically swappable the way a POSIX symlink rename is —
+there is no win32 "replace this directory reparse point with that one in
+one syscall" primitive — so :func:`replace_dir_link` is atomic on POSIX
+(same guarantee ``coord.agent_update`` already documents) and best-effort
+on win32: the old link is removed (not its target — see
+:func:`remove_dir_link`) and the new one renamed into place immediately
+after, which leaves a sub-millisecond window with no link rather than no
+atomicity guarantee at all. That is a real, documented platform difference,
+not a silent gap: see ``coord.agent_update._atomic_swap``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def make_dir_link(link_path: Path, target: Path) -> None:
+    """Create a directory link at *link_path* pointing at *target*.
+
+    POSIX: a directory symlink (``Path.symlink_to``). win32: a directory
+    junction (``_winapi.CreateJunction``), which — unlike a Windows
+    symlink — needs no Developer Mode / ``SeCreateSymbolicLinkPrivilege``.
+    """
+    if sys.platform == "win32":
+        import _winapi  # noqa: PLC0415 -- win32-only stdlib module
+
+        _winapi.CreateJunction(str(target), str(link_path))
+    else:
+        link_path.symlink_to(target, target_is_directory=True)
+
+
+def remove_dir_link(link_path: Path) -> None:
+    """Remove the link itself at *link_path* — never the directory it
+    points at.
+
+    POSIX: ``Path.unlink()`` on a symlink removes the link, not its
+    target. win32: a junction is a reparse point on an otherwise-empty
+    directory entry, removed with ``Path.rmdir()`` rather than
+    ``shutil.rmtree`` — a recursive ``rmtree`` would be wrong here since a
+    junction is transparent to many APIs, and could walk straight through
+    it into the target and delete *its* contents instead of just the link.
+    """
+    if sys.platform == "win32":
+        link_path.rmdir()
+    else:
+        link_path.unlink()
+
+
+def is_dir_link(path: Path) -> bool:
+    """Whether *path* is a directory link this module manages.
+
+    A symlink on POSIX; a symlink *or* a junction on win32 — both are
+    reparse points, and :func:`make_dir_link` only ever produces a
+    junction there, but a pre-existing or hand-made symlink should still
+    be recognized rather than silently mishandled.
+    """
+    if path.is_symlink():
+        return True
+    if sys.platform == "win32":
+        is_junction = getattr(path, "is_junction", None)
+        if is_junction is not None:
+            return is_junction()
+    return False
+
+
+def read_dir_link(link_path: Path) -> Path:
+    """Return the literal target *link_path* was created pointing at.
+
+    ``Path.readlink()`` resolves junctions as well as symlinks on win32
+    (support landed in CPython 3.8), so one call covers both platforms.
+    """
+    return link_path.readlink()
+
+
+def replace_dir_link(link_path: Path, target: Path) -> None:
+    """Flip *link_path* to point at *target*, replacing whatever (if
+    anything) is there.
+
+    Builds the new link at a temp path next to *link_path* first, so a
+    failure constructing it never touches the existing link. Atomic on
+    POSIX — the temp link is ``rename()``d directly onto *link_path*,
+    which POSIX guarantees replaces an existing path (symlink or
+    otherwise) in one filesystem operation when both are on the same
+    filesystem (true here: siblings under the same parent). Best-effort on
+    win32 — there is no equivalent single-syscall replace for a directory
+    reparse point, so the old link is removed and the new one renamed into
+    place immediately after; see the module docstring.
+    """
+    tmp_link = link_path.parent / f".{link_path.name}.next-link"
+    if is_dir_link(tmp_link) or tmp_link.exists():
+        remove_dir_link(tmp_link) if is_dir_link(tmp_link) else tmp_link.unlink()
+    make_dir_link(tmp_link, target)
+
+    if sys.platform == "win32":
+        if is_dir_link(link_path):
+            remove_dir_link(link_path)
+        tmp_link.rename(link_path)
+    else:
+        tmp_link.replace(link_path)

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/tests/test_agent_update_bluegreen.py

@@ -24,6 +24,7 @@ from coord.agent_update import (
     perform_update,
     rollback,
 )
+from coord.dirlink import is_dir_link
 from coord.platform_paths import venv_bin, venv_exe, venv_pip, venv_python
 
 #: #2684 (W4): `current_slot()`/`ensure_symlink_layout()` call `Path.resolve()`
@@ -159,7 +160,7 @@ class TestSymlinkLayout:
         active = ensure_symlink_layout(venv_dir)
 
         assert active == tmp_path / ".coord-venv.blue"
-        assert venv_dir.is_symlink()
+        assert is_dir_link(venv_dir)
         assert _same_path(current_slot(venv_dir), active)
         assert (venv_dir / "marker").read_text() == "original install\n"
 

code_coordinator-0.5.580/tests/test_dirlink.py

@@ -0,0 +1,192 @@
+"""``coord.dirlink`` -- directory links, symlink on POSIX / junction on win32 (#2842).
+
+The win32 ``_winapi.CreateJunction`` call itself can't run on this (Linux)
+CI box -- same reasoning as ``tests/test_platform_paths.py``'s Windows
+cases: there is no real win32 API to call. So the win32-branch tests here
+monkeypatch ``sys.platform`` and stub ``coord.dirlink``'s own
+``make_dir_link``/``remove_dir_link``/``is_dir_link`` to assert on
+*orchestration* -- the thing #2842 is actually about (no atomic
+single-syscall replace on that platform, so the old link must be removed
+before the new one is renamed in) -- rather than on the win32 API call
+itself, which only a real Windows box can exercise.
+
+The POSIX-branch tests run the real production code path against the real
+filesystem: no stubbing, because there's nothing to stub.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from coord.dirlink import (
+    is_dir_link,
+    make_dir_link,
+    read_dir_link,
+    remove_dir_link,
+    replace_dir_link,
+)
+
+
+# ── POSIX: real symlinks, real filesystem ───────────────────────────────
+
+
+def test_make_dir_link_creates_a_real_symlink(tmp_path: Path) -> None:
+    if sys.platform == "win32":
+        pytest.skip("POSIX-only: exercises the real symlink branch")
+    target = tmp_path / "target"
+    target.mkdir()
+    link = tmp_path / "link"
+
+    make_dir_link(link, target)
+
+    assert link.is_symlink()
+    assert is_dir_link(link)
+    assert read_dir_link(link) == target
+
+
+def test_is_dir_link_false_for_plain_directory_and_missing_path(tmp_path: Path) -> None:
+    plain = tmp_path / "plain"
+    plain.mkdir()
+    assert not is_dir_link(plain)
+    assert not is_dir_link(tmp_path / "does-not-exist")
+
+
+def test_replace_dir_link_atomically_flips_to_a_new_target(tmp_path: Path) -> None:
+    if sys.platform == "win32":
+        pytest.skip("POSIX-only: exercises the real symlink rename branch")
+    blue = tmp_path / "slot.blue"
+    green = tmp_path / "slot.green"
+    blue.mkdir()
+    green.mkdir()
+    (blue / "marker").write_text("blue\n")
+    (green / "marker").write_text("green\n")
+    link = tmp_path / "venv"
+
+    make_dir_link(link, blue)
+    assert (link / "marker").read_text() == "blue\n"
+
+    replace_dir_link(link, green)
+
+    assert read_dir_link(link) == green
+    assert (link / "marker").read_text() == "green\n"
+    # Both generations survive the flip -- only the link moved.
+    assert (blue / "marker").read_text() == "blue\n"
+    # The temp link used mid-swap doesn't leak into the directory listing.
+    assert sorted(p.name for p in tmp_path.iterdir()) == [
+        "slot.blue",
+        "slot.green",
+        "venv",
+    ]
+
+
+def test_replace_dir_link_cleans_up_a_stale_temp_link(tmp_path: Path) -> None:
+    if sys.platform == "win32":
+        pytest.skip("POSIX-only: exercises the real symlink branch")
+    target = tmp_path / "target"
+    target.mkdir()
+    link = tmp_path / "venv"
+    # Simulate a previous swap that died mid-flight, leaving the temp link
+    # behind -- `replace_dir_link` must not trip over it on the next call.
+    stale_tmp = tmp_path / ".venv.next-link"
+    stale_tmp.symlink_to(target, target_is_directory=True)
+
+    replace_dir_link(link, target)
+
+    assert read_dir_link(link) == target
+    assert not stale_tmp.exists()
+
+
+def test_remove_dir_link_removes_the_link_not_the_target(tmp_path: Path) -> None:
+    if sys.platform == "win32":
+        pytest.skip("POSIX-only: exercises the real symlink branch")
+    target = tmp_path / "target"
+    target.mkdir()
+    (target / "marker").write_text("still here\n")
+    link = tmp_path / "link"
+    make_dir_link(link, target)
+
+    remove_dir_link(link)
+
+    assert not link.exists()
+    assert (target / "marker").read_text() == "still here\n"
+
+
+# ── win32: orchestration, stubbed at the module seam ────────────────────
+
+
+def test_replace_dir_link_on_win32_removes_old_link_before_renaming(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """#2842: the bug this issue is about. win32 has no single-syscall
+    "replace this directory link with that one" the way POSIX `rename()`
+    does, so `replace_dir_link` must fall back to remove-then-rename on
+    that platform instead of calling `Path.replace()` on an existing
+    directory reparse point (which is exactly the `[WinError 5]` from the
+    issue). This asserts the fallback actually happens, in order, rather
+    than attempting the POSIX-only atomic path.
+    """
+    import coord.dirlink as dirlink_module
+
+    monkeypatch.setattr(dirlink_module.sys, "platform", "win32")
+    calls: list[tuple[str, Path]] = []
+
+    def fake_make_dir_link(link_path: Path, target: Path) -> None:
+        calls.append(("make", link_path))
+        link_path.mkdir()
+
+    def fake_remove_dir_link(link_path: Path) -> None:
+        calls.append(("remove", link_path))
+        link_path.rmdir()
+
+    monkeypatch.setattr(dirlink_module, "make_dir_link", fake_make_dir_link)
+    monkeypatch.setattr(dirlink_module, "remove_dir_link", fake_remove_dir_link)
+    monkeypatch.setattr(dirlink_module, "is_dir_link", lambda p: p.exists())
+
+    link = tmp_path / "venv"
+    link.mkdir()
+    target = tmp_path / "slot.green"
+    target.mkdir()
+    tmp_link = tmp_path / ".venv.next-link"
+
+    dirlink_module.replace_dir_link(link, target)
+
+    assert calls == [("make", tmp_link), ("remove", link)]
+    assert link.exists()
+    assert not tmp_link.exists()
+
+
+def test_replace_dir_link_on_win32_skips_remove_when_nothing_is_there_yet(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The first-ever migration (#1241's `ensure_symlink_layout`) swaps a
+    link into a path that doesn't exist yet -- `remove_dir_link` must not
+    be called (and must not raise) in that case, on either platform.
+    """
+    import coord.dirlink as dirlink_module
+
+    monkeypatch.setattr(dirlink_module.sys, "platform", "win32")
+    calls: list[str] = []
+
+    def fake_make_dir_link(link_path: Path, target: Path) -> None:
+        calls.append("make")
+        link_path.mkdir()
+
+    def fake_remove_dir_link(link_path: Path) -> None:
+        calls.append("remove")
+        link_path.rmdir()
+
+    monkeypatch.setattr(dirlink_module, "make_dir_link", fake_make_dir_link)
+    monkeypatch.setattr(dirlink_module, "remove_dir_link", fake_remove_dir_link)
+    monkeypatch.setattr(dirlink_module, "is_dir_link", lambda p: p.exists())
+
+    link = tmp_path / "venv"  # does not exist yet
+    target = tmp_path / "slot.blue"
+    target.mkdir()
+
+    dirlink_module.replace_dir_link(link, target)
+
+    assert calls == ["make"]
+    assert link.exists()

{code_coordinator-0.5.579 → code_coordinator-0.5.580}/tests/test_venv_live_install_2121.py

@@ -41,6 +41,7 @@ from coord.agent_update import (
     rollback,
 )
 from coord.audit import query_audit_log
+from coord.platform_paths import venv_bin, venv_exe, venv_pip, venv_python
 
 @pytest.fixture
 def proc_root(tmp_path: Path) -> Path:
@@ -87,19 +88,18 @@ def _run_stub(*, version: str = "9.9.9", calls: list | None = None):
             calls.append(cmd)
         if "-m" in cmd and "venv" in cmd:
             slot = Path(cmd[-1])
-            (slot / "bin").mkdir(parents=True, exist_ok=True)
-            for name in ("python", "pip", "coord"):
-                f = slot / "bin" / name
-                f.write_text("#!/bin/sh\n")
-                f.chmod(0o755)
+            venv_bin(slot).mkdir(parents=True, exist_ok=True)
+            for target in (venv_python(slot), venv_pip(slot), venv_exe(slot, "coord")):
+                target.write_text("#!/bin/sh\n")
+                target.chmod(0o755)
             (slot / "VERSION").write_text(version)
             return subprocess.CompletedProcess(cmd, 0, "created\n", "")
-        if cmd[0].endswith("/bin/pip") and "install" in cmd:
+        if Path(cmd[0]) == venv_pip(Path(cmd[0]).parent.parent) and "install" in cmd:
             return subprocess.CompletedProcess(cmd, 0, "Successfully installed\n", "")
-        if cmd[0].endswith("/bin/python") and "-c" in cmd:
+        if Path(cmd[0]) == venv_python(Path(cmd[0]).parent.parent) and "-c" in cmd:
             slot = Path(cmd[0]).parent.parent
             return subprocess.CompletedProcess(cmd, 0, f"{_slot_version(slot)}\n", "")
-        if cmd[0].endswith("/bin/coord") and "--version" in cmd:
+        if Path(cmd[0]) == venv_exe(Path(cmd[0]).parent.parent, "coord") and "--version" in cmd:
             slot = Path(cmd[0]).parent.parent
             return subprocess.CompletedProcess(
                 cmd, 0, f"coord, version {_slot_version(slot)}\n", ""