code-coordinator 0.5.283__tar.gz → 0.5.285__tar.gz

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/PKG-INFO

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

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

@@ -589,6 +589,7 @@ tests/test_health_unit_enablement.py
 tests/test_hooks.py
 tests/test_human_attended_437.py
 tests/test_init.py
+tests/test_install_agent_venv_2911.py
 tests/test_integration.py
 tests/test_interactive_briefing_echo.py
 tests/test_interactive_pane_log_2541.py

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/code_coordinator.egg-info/scm_file_list.json

@@ -615,6 +615,7 @@
     "tests/test_hooks.py",
     "tests/test_human_attended_437.py",
     "tests/test_init.py",
+    "tests/test_install_agent_venv_2911.py",
     "tests/test_integration.py",
     "tests/test_interactive_briefing_echo.py",
     "tests/test_interactive_pane_log_2541.py",

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.283",
+  "tag": "0.5.285",
   "distance": 0,
-  "node": "g4b5eca8c49f1e13cbcaea527779fa44b44583acb",
+  "node": "g20de37c9769bbedc43a885378d37737a25b31ac4",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-29"

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/coord/commands/status.py

@@ -923,6 +923,39 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
         click.echo("FLEET: ?  (health footer unavailable — coord health for detail)")
 
 
+def _host_resolution_lines(machine, ts_map: dict[str, tuple[str, str]] | None) -> list[tuple[bool, str]]:
+    """#2912: does ``host:`` actually resolve to THIS machine's tailnet
+    address? A LAN DHCP/DNS entry that shares a name with a tailnet node
+    (e.g. a WSL2 box named ``dell64`` whose Windows host also registers
+    ``dell64.lan``) shadows MagicDNS in the resolver order — HTTP-by-name
+    times out against the wrong LAN device while ``tailscale ping`` and the
+    agent's own ``/health`` are both perfectly healthy, so the symptom is
+    indistinguishable from a dead agent, a firewall, or a crashed unit.
+
+    Fires regardless of whether the machine is currently reachable — that's
+    the whole point: it names the cause a plain "unreachable" cannot, and it
+    also catches a collision BEFORE it manifests as an outage. Silent when
+    ``coord.network.check_host_resolution`` can't determine an answer (no
+    local ``tailscale``, node not in this box's peer list, ``host:`` doesn't
+    resolve at all) — those are absence-of-evidence, not a finding.
+
+    Pure function over :func:`coord.network.check_host_resolution`'s result
+    — no I/O of its own — so it's testable without a live tailnet.
+    """
+    from coord import network  # noqa: PLC0415
+
+    result = network.check_host_resolution(machine, ts_map)
+    if result.matches is not False:
+        return []
+    return [(
+        True,
+        f"  ✗ CRIT machines.host_resolves_offtailnet: {result.reason} "
+        f"(#2912). Remedy: set `host: {result.magicdns_fqdn}` in "
+        "coordinator.yml — the MagicDNS FQDN — instead of the bare "
+        "hostname, which a LAN DNS entry can shadow.",
+    )]
+
+
 def _health_vs_config_lines(machine, health: dict) -> list[tuple[bool, str]]:
     """Cross-check a machine's ``/health`` against what ``coordinator.yml``
     declares for it. Returns ``(is_problem, line)`` pairs (#1712).
@@ -1323,6 +1356,7 @@ def doctor(
     expected: str | None,
     use_pypi: bool,
 ) -> None:
+    from coord import network
     from coord.network import check_all
     from coord.prereqs import ToolProbe, unmet_capabilities
 
@@ -1339,10 +1373,23 @@ def doctor(
             sys.exit(2)
 
     statuses = check_all(machines, timeout=timeout)
+    # #2912: resolved once, locally, up front — every machine's `host:` is
+    # checked against the SAME local tailscale peer list, and a single
+    # `tailscale status --json` covers the whole fleet. `None` when
+    # tailscale isn't available on THIS box; `_host_resolution_lines`
+    # renders nothing in that case rather than fabricating a mismatch.
+    ts_map = network.tailscale_ip_map(timeout=timeout)
     any_problem = False
     for s in statuses:
         m = s.machine
         click.echo(f"{m.name} ({m.host}):")
+        # Runs even when unreachable — that's the case this exists for:
+        # naming why "unreachable" is misleading instead of leaving it
+        # indistinguishable from a dead agent or a crashed unit.
+        for is_problem, line in _host_resolution_lines(m, ts_map):
+            click.echo(line)
+            if is_problem:
+                any_problem = True
         if not s.is_online:
             click.echo(f"  ✗ unreachable — {s.reason}")
             any_problem = True

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/coord/network.py

@@ -8,7 +8,9 @@ a generic "offline".
 
 from __future__ import annotations
 
+import json
 import socket
+import subprocess
 import time
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
@@ -119,6 +121,150 @@ def check_all(
         return list(pool.map(lambda m: check_machine(m, timeout=timeout), machines))
 
 
+# #2912: `coord doctor` checks reachability by resolving `host:` and hitting
+# it — but never checks whether `host:` resolves to the RIGHT thing. A LAN
+# DHCP/DNS entry that happens to share a name with a tailnet node (e.g. a
+# WSL2 box named `dell64` whose Windows host also registers `dell64.lan`)
+# shadows MagicDNS in the resolver order: `tailscale ping <name>` succeeds
+# (it talks to tailscaled directly, not the resolver) while plain HTTP by
+# name times out against the wrong LAN device — indistinguishable from a
+# dead agent, a firewall, or a crashed unit. The two helpers below let
+# `coord doctor` name that specific cause instead.
+
+
+def tailscale_ip_map(timeout: float = 5.0) -> dict[str, tuple[str, str]] | None:
+    """Map each tailnet node's short hostname (lowercased) to its
+    ``(tailnet_ipv4, magicdns_fqdn)``, read from the LOCAL machine's own
+    ``tailscale status --json`` — i.e. what THIS box's tailscaled believes,
+    which is what its own DNS resolver should agree with.
+
+    Returns ``None`` when the ``tailscale`` CLI is missing, not logged in,
+    or anything else goes wrong. This check is best-effort and must fail
+    soft: a probe that cannot tell tailnet truth from LAN truth must stay
+    silent rather than fabricate a mismatch.
+    """
+    try:
+        result = subprocess.run(
+            ["tailscale", "status", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout)
+    except ValueError:
+        return None
+
+    nodes = list((data.get("Peer") or {}).values())
+    self_node = data.get("Self")
+    if self_node:
+        nodes.append(self_node)
+
+    out: dict[str, tuple[str, str]] = {}
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        host_name = (node.get("HostName") or "").strip().lower()
+        if not host_name:
+            continue
+        ipv4 = next(
+            (ip for ip in (node.get("TailscaleIPs") or []) if ":" not in ip), None
+        )
+        if not ipv4:
+            continue
+        dns_name = (node.get("DNSName") or "").rstrip(".")
+        out[host_name] = (ipv4, dns_name)
+    return out
+
+
+def resolve_host_ip(host: str, timeout: float = 5.0) -> str | None:
+    """Resolve *host* via normal system DNS/hosts resolution — the same
+    resolution path plain HTTP-by-name takes. ``None`` on any failure."""
+    old_timeout = socket.getdefaulttimeout()
+    socket.setdefaulttimeout(timeout)
+    try:
+        return socket.gethostbyname(host)
+    except OSError:
+        return None
+    finally:
+        socket.setdefaulttimeout(old_timeout)
+
+
+@dataclass
+class HostResolutionCheck:
+    """Does a machine's configured ``host:`` resolve to ITS tailnet address?
+
+    ``matches is None`` means "could not determine" (no local ``tailscale``,
+    the node wasn't found in this box's peer list, or ``host:`` didn't
+    resolve at all) — that's a different, softer story than ``False``
+    ("resolved, but to the wrong place") and callers must not conflate them.
+    """
+
+    matches: bool | None
+    resolved_ip: str | None = None
+    tailnet_ip: str | None = None
+    magicdns_fqdn: str | None = None
+    reason: str = ""
+
+
+def check_host_resolution(
+    machine: Machine, ts_map: dict[str, tuple[str, str]] | None
+) -> HostResolutionCheck:
+    """Compare ``machine.host``'s DNS resolution against what *ts_map*
+    (from :func:`tailscale_ip_map`) says this tailnet node's real address
+    is. Pure function of its inputs — no I/O — so it's unit-testable
+    without a live tailnet or DNS resolver.
+    """
+    if ts_map is None:
+        return HostResolutionCheck(
+            matches=None, reason="tailscale not available locally — skipped"
+        )
+
+    peer = ts_map.get(machine.name.strip().lower())
+    if peer is None:
+        # `machine.name` and `machine.host`'s leading label don't always
+        # agree (host aliases, an already-FQDN host, ...) — fall back to
+        # the host's own short label before giving up.
+        peer = ts_map.get(machine.host.split(".")[0].strip().lower())
+    if peer is None:
+        return HostResolutionCheck(
+            matches=None,
+            reason=f"{machine.name!r} not found in local tailscale peer list — skipped",
+        )
+
+    tailnet_ip, magicdns_fqdn = peer
+    resolved = resolve_host_ip(machine.host)
+    if resolved is None:
+        return HostResolutionCheck(
+            matches=None,
+            tailnet_ip=tailnet_ip,
+            magicdns_fqdn=magicdns_fqdn,
+            reason=f"{machine.host!r} did not resolve at all",
+        )
+    if resolved == tailnet_ip:
+        return HostResolutionCheck(
+            matches=True,
+            resolved_ip=resolved,
+            tailnet_ip=tailnet_ip,
+            magicdns_fqdn=magicdns_fqdn,
+        )
+    return HostResolutionCheck(
+        matches=False,
+        resolved_ip=resolved,
+        tailnet_ip=tailnet_ip,
+        magicdns_fqdn=magicdns_fqdn,
+        reason=(
+            f"{machine.host!r} resolves to {resolved}, not this machine's "
+            f"tailnet address {tailnet_ip} — a LAN DNS entry is very likely "
+            "shadowing MagicDNS for this name"
+        ),
+    )
+
+
 @dataclass
 class StatusResult:
     """Result of fetching /status from an agent.

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/install-agent.sh

@@ -36,6 +36,9 @@ echo "=== code-coordinator agent installer ==="
 python3 --version | grep -qE "3\.(1[2-9]|[2-9][0-9])" || {
     echo "error: Python 3.12+ required"; exit 1
 }
+# Used later to size the apt hint if `python3 -m venv` fails; failure here
+# just means the hint falls back to the unversioned package name.
+PY_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")' 2>/dev/null || echo "")
 
 # Check claude CLI
 which claude >/dev/null 2>&1 || {
@@ -44,11 +47,59 @@ which claude >/dev/null 2>&1 || {
 }
 
 # Create/update venv
-if [ -d "$VENV_DIR" ]; then
+#
+# #2911: a first run that fails partway (e.g. Ubuntu 24.04 shipping python3
+# without ensurepip) can leave $VENV_DIR existing with a bin/ that has
+# python3 but no pip. Trusting `-d "$VENV_DIR"` alone then skips
+# `python3 -m venv` on retry and the script dies later at
+# "$VENV_DIR/bin/pip: No such file or directory" - a message that names pip,
+# not the actual problem. Validate the venv is actually usable instead of
+# just present, and recreate it if not. Also trap failures so a venv this
+# run itself created (but never finished installing into) doesn't poison
+# the next retry either.
+CREATED_VENV=0
+on_exit() {
+    local status=$?
+    if [ "$status" -ne 0 ] && [ "$CREATED_VENV" -eq 1 ] && [ -d "$VENV_DIR" ]; then
+        echo "" >&2
+        echo "install failed - removing the venv this run created at $VENV_DIR" >&2
+        echo "so the next attempt starts clean instead of finding a partial one." >&2
+        rm -rf "$VENV_DIR"
+    fi
+    exit "$status"
+}
+trap on_exit EXIT
+
+if [ -d "$VENV_DIR" ] && [ -x "$VENV_DIR/bin/pip" ]; then
     echo "Updating existing installation at $VENV_DIR..."
 else
+    if [ -d "$VENV_DIR" ]; then
+        echo "Existing $VENV_DIR has no bin/pip (partial or failed install) - recreating..."
+        # Note: if a `coord agent update` blue/green swap (coord/agent_update.py)
+        # has ever run here, $VENV_DIR is normally a symlink to
+        # .coord-venv.blue/.coord-venv.green, not a plain directory — but a
+        # symlink with a working bin/pip would have taken the branch above,
+        # so reaching here means it's either a plain broken directory (the
+        # common first-install case this fix targets) or an already-broken
+        # symlink. `rm -rf` on a symlink unlinks just the symlink, not its
+        # target, which would strand the real blue/green slot on disk; that's
+        # an existing-corruption corner case outside a first-install script's
+        # scope, not something this fix introduces.
+        rm -rf "$VENV_DIR"
+    fi
     echo "Creating virtual environment at $VENV_DIR..."
-    python3 -m venv "$VENV_DIR"
+    CREATED_VENV=1
+    if ! python3 -m venv "$VENV_DIR"; then
+        echo "" >&2
+        echo "error: 'python3 -m venv' failed to create $VENV_DIR." >&2
+        echo "  On Debian/Ubuntu this usually means venv/ensurepip support isn't installed:" >&2
+        if [ -n "$PY_VERSION" ]; then
+            echo "    sudo apt install python3-venv python${PY_VERSION}-venv" >&2
+        else
+            echo "    sudo apt install python3-venv" >&2
+        fi
+        exit 1
+    fi
 fi
 
 # Install/upgrade
@@ -56,6 +107,16 @@ fi
 "$VENV_DIR/bin/pip" install --upgrade "$INSTALL_SOURCE" -q
 echo "Installed: $("$VENV_DIR/bin/coord" version)"
 
+# The venv is now fully installed and verified working (coord version printed
+# above). Disarm the cleanup trap here: everything from this point on
+# (machine-name detection, the systemd unit, node shims, systemctl,
+# loginctl) is unrelated to venv creation, and a failure in any of it must
+# NOT delete a venv that already works — that would poison the retry with a
+# from-scratch pip re-install just to get back to the same later failure
+# (#2911 review).
+trap - EXIT
+CREATED_VENV=0
+
 # Detect machine name if not provided
 if [ -z "$MACHINE_NAME" ]; then
     MACHINE_NAME=$(hostname -s)

{code_coordinator-0.5.283 → code_coordinator-0.5.285}/tests/test_cli_doctor.py

@@ -16,8 +16,13 @@ from coord.commands.status import doctor
 from coord.network import ONLINE, OFFLINE, MachineStatus
 
 
-def _run_doctor(config_path, monkeypatch, statuses, *, extra_args=None):
+def _run_doctor(config_path, monkeypatch, statuses, *, extra_args=None, ts_map=None):
     monkeypatch.setattr(network_mod, "check_all", lambda *a, **k: statuses)
+    # #2912: default the new host-resolution check to "tailscale not
+    # available" (matches=None, silent) so every PRE-EXISTING test here
+    # stays hermetic and unaffected — tests that actually exercise the
+    # check pass their own `ts_map`.
+    monkeypatch.setattr(network_mod, "tailscale_ip_map", lambda *a, **k: ts_map)
     runner = CliRunner()
     # #2082: doctor resolves --expected from PyPI by default now. Default
     # these tests to --no-pypi so they stay hermetic (no real network call);
@@ -101,6 +106,61 @@ def test_doctor_flags_unreachable_machine(valid_config_path, monkeypatch) -> Non
     assert "connection refused" in result.output
 
 
+def test_doctor_names_lan_dns_shadow_even_when_unreachable(
+    valid_config_path, monkeypatch,
+) -> None:
+    """#2912: `laptop`'s `host: laptop.tailnet` resolving to something other
+    than laptop's own tailnet address must be named EVEN on the branch that
+    reports "unreachable" — that's the whole failure mode: a DNS shadow
+    makes a healthy agent look dead with no clue why."""
+    from coord.config import load
+
+    cfg = load(valid_config_path)
+    statuses = [
+        MachineStatus(machine=cfg.machines[0], state=network_mod.TIMEOUT, reason="timed out"),
+        MachineStatus(
+            machine=cfg.machines[1], state=ONLINE,
+            health=_health({"git": _ok_probe(), "gh": _ok_probe()}, cfg.machines[1]),
+        ),
+    ]
+    ts_map = {"laptop": ("100.64.0.1", "laptop.tailf46ef8.ts.net")}
+    monkeypatch.setattr(
+        network_mod, "resolve_host_ip", lambda host, **k: "192.168.1.183"
+    )
+    result = _run_doctor(valid_config_path, monkeypatch, statuses, ts_map=ts_map)
+    assert result.exit_code == 1
+    assert "machines.host_resolves_offtailnet" in result.output
+    assert "100.64.0.1" in result.output
+    assert "laptop.tailf46ef8.ts.net" in result.output
+    assert "unreachable" in result.output
+
+
+def test_doctor_is_silent_when_host_matches_tailnet_address(
+    valid_config_path, monkeypatch,
+) -> None:
+    from coord.config import load
+
+    cfg = load(valid_config_path)
+    statuses = [
+        MachineStatus(
+            machine=m, state=ONLINE,
+            health=_health({"git": _ok_probe(), "gh": _ok_probe()}, m),
+        )
+        for m in cfg.machines
+    ]
+    ts_map = {
+        "laptop": ("100.64.0.1", "laptop.tailf46ef8.ts.net"),
+        "server": ("100.64.0.2", "server.tailf46ef8.ts.net"),
+    }
+    monkeypatch.setattr(
+        network_mod, "resolve_host_ip",
+        lambda host, **k: {"laptop.tailnet": "100.64.0.1", "server.tailnet": "100.64.0.2"}[host],
+    )
+    result = _run_doctor(valid_config_path, monkeypatch, statuses, ts_map=ts_map)
+    assert result.exit_code == 0, result.output
+    assert "host_resolves_offtailnet" not in result.output
+
+
 def test_doctor_flags_missing_baseline_tool(valid_config_path, monkeypatch) -> None:
     from coord.config import load
 

code_coordinator-0.5.285/tests/test_install_agent_venv_2911.py

@@ -0,0 +1,225 @@
+"""install-agent.sh: a partial ``~/.coord-venv`` must not poison retries (#2911).
+
+A first run that fails partway (e.g. Ubuntu 24.04 shipping python3 without
+ensurepip) can leave ``$VENV_DIR`` existing with a ``bin/`` that has
+``python3`` but no ``pip``. The pre-fix script trusted ``-d "$VENV_DIR"``
+alone, so a retry skipped ``python3 -m venv`` entirely and died later at
+``"$VENV_DIR/bin/pip": No such file or directory`` — a message that names
+pip, not the actual problem — and the only way out was ``rm -rf
+~/.coord-venv`` by hand.
+
+This drives the real ``install-agent.sh`` end to end (not just a snippet)
+in an isolated ``$HOME``, with ``python3``/``systemctl``/``loginctl``/
+``claude`` stubbed out on ``$PATH`` so it never touches the real system.
+Three scenarios, matching the issue:
+
+* a venv left over from a run that failed inside ``python3 -m venv``
+  (``bin/`` with no ``pip``) is detected as unusable and recreated, so the
+  retry succeeds instead of re-failing at ``bin/pip``;
+* when ``python3 -m venv`` itself fails (the ensurepip case), the script
+  exits non-zero with a message naming the apt package to install, and
+  removes the venv directory it just created rather than leaving a
+  poisoned one behind for the next retry;
+* an already-good venv (``bin/pip`` present) is left alone and just
+  updated in place — no spurious recreation.
+* a failure *after* the venv is fully installed (e.g. ``systemctl
+  --user daemon-reload`` failing with "Failed to connect to bus" because
+  the SSH session has no lingering user session yet — the exact reason
+  the next line is ``loginctl enable-linger``) must NOT delete the
+  now-working venv: only a failure during venv creation/pip install
+  should trigger cleanup, otherwise the retry has to re-download and
+  re-install everything from scratch just to reach the same later
+  failure again.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from .conftest import POSIX_BASH
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+INSTALLER = REPO_ROOT / "install-agent.sh"
+
+
+def _write_exe(path: Path, body: str) -> None:
+    path.write_text(body)
+    path.chmod(path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _make_fake_bin(tmp_path: Path, *, venv_fails: bool, systemctl_fails: bool = False) -> Path:
+    """A directory of stub commands so the script never touches the real system."""
+    fake_bin = tmp_path / "fake-bin"
+    fake_bin.mkdir()
+
+    venv_failure_snippet = (
+        """
+        echo "Error: Command '['$target/bin/python3', '-Im', 'ensurepip', ...]'"
+        "returned non-zero exit status 1." >&2
+        echo "The virtual environment was not created successfully because" >&2
+        echo "ensurepip is not available." >&2
+        exit 1
+        """
+        if venv_fails
+        else ""
+    )
+
+    _write_exe(
+        fake_bin / "python3",
+        f"""#!/usr/bin/env bash
+if [ "$1" = "--version" ]; then
+    echo "Python 3.12.3"
+    exit 0
+fi
+if [ "$1" = "-c" ]; then
+    echo "3.12"
+    exit 0
+fi
+if [ "$1" = "-m" ] && [ "$2" = "venv" ]; then
+    target="$3"
+    mkdir -p "$target/bin"
+    printf '#!/bin/sh\\n' > "$target/bin/python3"
+    chmod +x "$target/bin/python3"
+    {venv_failure_snippet}
+    for name in pip coord; do
+        printf '#!/bin/sh\\necho "coord, version 9.9.9"\\n' > "$target/bin/$name"
+        chmod +x "$target/bin/$name"
+    done
+    exit 0
+fi
+echo "fake python3: unhandled args: $*" >&2
+exit 1
+""",
+    )
+
+    if systemctl_fails:
+        # Simulate the real-world "Failed to connect to bus" error: on a
+        # brand-new SSH session there is no lingering user session yet, so
+        # `systemctl --user ...` fails until `loginctl enable-linger` runs
+        # (which is the *next* line in install-agent.sh — too late for this
+        # call).
+        _write_exe(
+            fake_bin / "systemctl",
+            '#!/usr/bin/env bash\necho "Failed to connect to bus: No such file or directory" >&2\nexit 1\n',
+        )
+    else:
+        _write_exe(fake_bin / "systemctl", "#!/usr/bin/env bash\nexit 0\n")
+
+    for noop in ("loginctl", "claude"):
+        _write_exe(fake_bin / noop, "#!/usr/bin/env bash\nexit 0\n")
+
+    return fake_bin
+
+
+def _run_installer(tmp_path: Path, fake_bin: Path, *, extra_path: str = "") -> subprocess.CompletedProcess:
+    home = tmp_path / "home"
+    home.mkdir(exist_ok=True)
+    env = dict(os.environ)
+    path_parts = [str(fake_bin)]
+    if extra_path:
+        path_parts.append(extra_path)
+    path_parts.append(env.get("PATH", "/usr/bin:/bin"))
+    env["PATH"] = ":".join(path_parts)
+    env["HOME"] = str(home)
+    return subprocess.run(
+        [POSIX_BASH, str(INSTALLER), "--machine", "testhost"],
+        cwd=tmp_path,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+
+
+def test_partial_venv_from_a_failed_run_is_recreated_not_trusted(tmp_path: Path) -> None:
+    """A leftover venv with bin/python3 but no bin/pip must not take the
+    "existing installation" branch — that's exactly what died at bin/pip
+    on retry pre-fix."""
+    fake_bin = _make_fake_bin(tmp_path, venv_fails=False)
+    home = tmp_path / "home"
+    home.mkdir()
+    venv_dir = home / ".coord-venv"
+    (venv_dir / "bin").mkdir(parents=True)
+    (venv_dir / "bin" / "python3").write_text("#!/bin/sh\n")
+    (venv_dir / "bin" / "python3").chmod(0o755)
+    # Deliberately no bin/pip: this is the partial state left by ensurepip
+    # failing partway through `python3 -m venv`.
+
+    result = _run_installer(tmp_path, fake_bin)
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "Updating existing installation" not in result.stdout
+    assert "recreating" in result.stdout
+    assert (venv_dir / "bin" / "pip").exists()
+    assert (venv_dir / "bin" / "coord").exists()
+
+
+def test_venv_creation_failure_exits_with_apt_hint_and_cleans_up(tmp_path: Path) -> None:
+    """The ensurepip case: `python3 -m venv` itself fails. The script must
+    exit non-zero naming the apt package (not a bare "no such file: pip"
+    later on), and must not leave a poisoned venv dir behind for the next
+    retry."""
+    fake_bin = _make_fake_bin(tmp_path, venv_fails=True)
+
+    result = _run_installer(tmp_path, fake_bin)
+
+    assert result.returncode != 0
+    assert "apt install" in result.stderr
+    assert "python3.12-venv" in result.stderr or "python3-venv" in result.stderr
+    home = tmp_path / "home"
+    assert not (home / ".coord-venv").exists(), (
+        "a venv this run created but never finished installing into must be "
+        "removed, not left behind to poison the next retry"
+    )
+
+
+def test_already_good_venv_is_updated_in_place_not_recreated(tmp_path: Path) -> None:
+    """An existing venv with a working bin/pip is the happy path: skip
+    `python3 -m venv` entirely and just reinstall into it."""
+    fake_bin = _make_fake_bin(tmp_path, venv_fails=False)
+    home = tmp_path / "home"
+    home.mkdir()
+    venv_dir = home / ".coord-venv"
+    (venv_dir / "bin").mkdir(parents=True)
+    for name in ("python3", "pip", "coord"):
+        _write_exe(venv_dir / "bin" / name, '#!/bin/sh\necho "coord, version 9.9.9"\n')
+    marker = venv_dir / "bin" / "coord"
+    before = marker.read_bytes()
+
+    result = _run_installer(tmp_path, fake_bin)
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "Updating existing installation" in result.stdout
+    assert "recreating" not in result.stdout
+    # untouched by a `python3 -m venv` recreation (the fake would overwrite it)
+    assert marker.read_bytes() == before
+
+
+def test_failure_after_venv_installed_does_not_delete_the_working_venv(tmp_path: Path) -> None:
+    """The cleanup trap must be scoped to venv creation/pip install, not the
+    whole script (#2911 review). `systemctl --user daemon-reload` failing
+    with "Failed to connect to bus" — the ordinary first-run case before
+    `loginctl enable-linger` has ever run — happens *after* the venv is
+    fully created and installed into. That must exit non-zero but leave the
+    now-working venv alone: deleting it would force the retry to re-download
+    and re-install code-coordinator from scratch just to reach the exact
+    same systemd failure again."""
+    fake_bin = _make_fake_bin(tmp_path, venv_fails=False, systemctl_fails=True)
+
+    result = _run_installer(tmp_path, fake_bin)
+
+    assert result.returncode != 0, result.stdout + result.stderr
+    home = tmp_path / "home"
+    venv_dir = home / ".coord-venv"
+    assert venv_dir.exists(), (
+        "a venv that finished creation and pip install successfully must "
+        "survive a later, unrelated failure (systemd here) instead of being "
+        "deleted by the cleanup trap"
+    )
+    assert (venv_dir / "bin" / "pip").exists()
+    assert (venv_dir / "bin" / "coord").exists()