code-coordinator 0.5.499__tar.gz → 0.5.501__tar.gz

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/.github/workflows/test.yml

@@ -111,12 +111,34 @@ jobs:
   # — the matrix axis there is Python versions on Linux; this job's axis is
   # the platform. See docs/CROSS_PLATFORM.md §9.
   windows:
-    # #2039: on `push` (i.e. merges to main) only. On a `pull_request` event
-    # this evaluates false and the job is SKIPPED — conclusion `skipped`,
-    # which is already in `ci_store._PASSING_CONCLUSIONS`, so the merge gate
-    # is satisfied rather than merely tolerant. `windows` is not a required
-    # status check either, so branch protection is unaffected.
-    if: github.event_name == 'push'
+    # #3394, 2026-09-18: taken out of automatic CI by operator decision —
+    # Windows is not current work. Everything in the block above about this
+    # being a real gate (#2000) remains true of the job's SHAPE and is
+    # deliberately left intact; what changed is WHEN it runs.
+    #
+    # Why: it has failed every run sampled back to 2026-09-10 (~614
+    # AssertionError plus WinError / BackupError / FileNotFoundError / OSError,
+    # concentrated in tests/test_dr_azure_scripts.py and tests/test_agent.py).
+    # A gate that is always red gates nothing — it only kept `main` permanently
+    # red, at ~85 min of runner time per push, and that permanent redness is
+    # what made coord mark every branch baseline-red and SKIP its test stage
+    # while the gate still reported `test: passed`. #3378 item 1, #3380 and
+    # #3385 were all scoped as "make main green" and all misattributed that
+    # redness to the (advisory) postgres job.
+    #
+    # The #2039 note this replaces still describes the restore target: on
+    # `push` only, so the job is SKIPPED on `pull_request` — conclusion
+    # `skipped`, already in `ci_store._PASSING_CONCLUSIONS`, so a red Windows
+    # run surfaces on main and never blocks a PR. `windows` is not a required
+    # status check either, so branch protection is unaffected in either shape.
+    #
+    # RESTORE by putting `github.event_name == 'push'` back here when Windows
+    # becomes active work — THEN fix the ~614 failures. Only once it is green
+    # is it a gate again. Do NOT add `continue-on-error` as a shortcut: #2026
+    # found that softens the run conclusion while the check still reports
+    # `failure` to the Checks API, which stalled the whole drive queue
+    # overnight on 2026-08-08.
+    if: github.event_name == 'workflow_dispatch'
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v4

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/PKG-INFO

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

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

@@ -143,6 +143,7 @@ coord/repo_edit.py
 coord/repo_onboard.py
 coord/reports.py
 coord/rest_schema.py
+coord/restart_cmd.py
 coord/revalidate.py
 coord/review.py
 coord/scorecard.py
@@ -541,6 +542,7 @@ tests/test_cli_status_merge_queue.py
 tests/test_cli_status_provider.py
 tests/test_cli_status_retried_3340.py
 tests/test_cli_status_review_finalizing.py
+tests/test_cli_status_supervisor_3366.py
 tests/test_cli_status_test_failed_tag.py
 tests/test_cli_status_usage_limit.py
 tests/test_cli_sync_comments_873.py
@@ -786,6 +788,7 @@ tests/test_repo_graph_fleet_2237.py
 tests/test_repo_onboard_2220.py
 tests/test_report_result_push.py
 tests/test_reports.py
+tests/test_restart_cmd.py
 tests/test_retry.py
 tests/test_retry_advisory_1606.py
 tests/test_retry_escalation_classify_3360.py

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/code_coordinator.egg-info/scm_file_list.json

@@ -257,6 +257,7 @@
     "coord/repo_onboard.py",
     "coord/reports.py",
     "coord/rest_schema.py",
+    "coord/restart_cmd.py",
     "coord/revalidate.py",
     "coord/review.py",
     "coord/scorecard.py",
@@ -567,6 +568,7 @@
     "tests/test_cli_status_provider.py",
     "tests/test_cli_status_retried_3340.py",
     "tests/test_cli_status_review_finalizing.py",
+    "tests/test_cli_status_supervisor_3366.py",
     "tests/test_cli_status_test_failed_tag.py",
     "tests/test_cli_status_usage_limit.py",
     "tests/test_cli_sync_comments_873.py",
@@ -812,6 +814,7 @@
     "tests/test_repo_onboard_2220.py",
     "tests/test_report_result_push.py",
     "tests/test_reports.py",
+    "tests/test_restart_cmd.py",
     "tests/test_retry.py",
     "tests/test_retry_advisory_1606.py",
     "tests/test_retry_escalation_classify_3360.py",

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.499",
+  "tag": "0.5.501",
   "distance": 0,
-  "node": "gf300cdf9d6d4ef1871e0b1016a2875ac0572ea95",
+  "node": "gf1c4fc8c6aabba829d2631892fc576fd10bbc58a",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-19"

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/agent_app.py

@@ -7,6 +7,7 @@ import json
 import logging
 import os
 import re
+import shutil
 import subprocess
 import sys
 import threading
@@ -20,7 +21,7 @@ from starlette.requests import Request
 from starlette.responses import JSONResponse, PlainTextResponse, Response, StreamingResponse
 from starlette.routing import Route
 
-from coord import __version__, agent_update
+from coord import __version__, agent_update, restart_cmd
 from coord.agent import RUNNING, PENDING, AgentAssignment, AgentServer, AssignmentSpec
 from coord.dist_name import DistributionNotFoundError, resolve_installed, resolve_installed_name
 from coord.dist_name import pkg_spec as _dist_pkg_spec
@@ -129,8 +130,13 @@ def _running_under_systemd() -> bool:
     ``INVOCATION_ID`` is set by systemd for every unit invocation (since
     v232) and is the standard "am I running under systemd" signal — unlike
     checking the parent PID, it survives the process being reparented.
+
+    Delegates to :mod:`coord.restart_cmd` (#3366) — the single place that
+    answers this, shared with the SSH-side escalation and every
+    operator-facing remediation string, so this process's own idea of its
+    supervisor can never drift from what those tell an operator.
     """
-    return bool(os.environ.get("INVOCATION_ID"))
+    return restart_cmd.running_under_systemd()
 
 
 def _systemctl_env() -> dict[str, str]:
@@ -1157,6 +1163,12 @@ def build_app(
         # liveness or PID.
         data["version"] = __version__
         data["installed_version"] = _installed_version()
+        # #3366: this process's own live self-report of what supervises
+        # it — "systemd", "launchd", or null when neither is known (a dev
+        # box, Windows). The freshest possible answer to "what restarts
+        # this host," ahead of any static config an operator may also set
+        # (see `coord.restart_cmd.resolve_supervisor`).
+        data["supervisor"] = restart_cmd.local_supervisor()
         # Surface the most recent /update attempt so the CLI can show
         # "0.3.0 → 0.4.0" or "no_change (0.3.0)" or "failed: <error>".
         last = _read_last_update(server.state_dir)
@@ -1625,6 +1637,33 @@ def build_app(
             body = {}
         dry_run = bool(body.get("dry_run"))
 
+        # #3366: this whole lane is systemd-unit management — on a host
+        # with no `systemctl` at all (every macOS agent today; #1158's
+        # launchd port ships no unit-file equivalent) every one of the
+        # packaged units reads as "new"/"not installed here", every run,
+        # forever. That is not drift, it is the platform, and reporting it
+        # as drift-adjacent noise on every propagation trains the operator
+        # to ignore this lane. Short-circuit with an honest n/a instead of
+        # calling into `du.install_units`, which has no way to tell "not
+        # installed yet" apart from "cannot ever be installed here".
+        if shutil.which("systemctl") is None:
+            supervisor = restart_cmd.local_supervisor()
+            return JSONResponse(
+                {
+                    "ok": True,
+                    "units": [],
+                    "dry_run": dry_run,
+                    "reloaded": False,
+                    "reload_detail": "",
+                    "timers_enabled": {},
+                    "detail": (
+                        f"n/a — no systemd on this host (supervisor: "
+                        f"{supervisor or 'unknown'})"
+                    ),
+                },
+                status_code=200,
+            )
+
         report = du.install_units(
             machine_name=getattr(server, "machine_name", None),
             port=AGENT_PORT,
@@ -1714,12 +1753,20 @@ def build_app(
             )
 
         if not _running_under_systemd():
+            # #3366: name the actual supervisor, when known, instead of
+            # only ever saying what this ISN'T (systemd) — a launchd host
+            # reads as clearly out of scope for a systemd-only lane rather
+            # than as unexplained drift-adjacent noise on every run.
+            supervisor = restart_cmd.local_supervisor()
             return JSONResponse(
                 {
                     "units": {},
                     "detail": (
-                        "this agent is not running under systemd — nothing here "
-                        "can restart a sibling unit"
+                        f"this agent runs under {supervisor}, not systemd — "
+                        "nothing here can restart a sibling unit"
+                        if supervisor
+                        else "this agent is not running under systemd — nothing "
+                        "here can restart a sibling unit"
                     ),
                 },
                 status_code=200,

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/agent_update.py

@@ -85,6 +85,7 @@ import sys
 from dataclasses import dataclass
 from pathlib import Path
 
+from coord import restart_cmd
 from coord.platform_paths import venv_exe, venv_pip, venv_python
 
 _log = logging.getLogger(__name__)
@@ -698,8 +699,8 @@ def perform_update(
             f"and rebuild — {listed}. Replacing a running process's "
             "site-packages leaves it executing a mix of two versions (the "
             "2026-08-11 dellserver incident, #2121). Restart or stop those "
-            "processes — `systemctl --user restart coord-agent` for the "
-            "agent — and retry.",
+            f"processes — {restart_cmd.restart_hint(restart_cmd.local_supervisor())} "
+            "for the agent — and retry.",
             holders=[
                 {"pid": h.pid, "source": h.source, "cmdline": h.cmdline}
                 for h in holders[:20]

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/commands/agent_ops.py

@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING, Any
 import click
 import httpx
 
-from coord import __version__
+from coord import __version__, restart_cmd
 # Aliased: `agent_update` is also the name of this module's click command.
 from coord.agent_update import cli_initiator as _cli_initiator
 from coord.config import Config
@@ -726,10 +726,12 @@ def agent_update(
                 err = outcome.get("error") or "pip failed; see ~/.coord/last_update.log"
                 click.echo(f"  {machine.name}: ✗ failed — {err}", err=True)
             elif outcome.get("escalated"):
+                hint = restart_cmd.resolve_supervisor(machine, live=outcome.get("supervisor"))
                 click.echo(
                     f"  {machine.name}: ✗ pip upgraded to {target_version} but the "
-                    f"process is stuck reporting {version_now} even after a "
-                    "`systemctl --user restart` — needs manual investigation",
+                    f"process is stuck reporting {version_now} even after a driven "
+                    f"restart ({restart_cmd.restart_shell_command(hint)}) — needs "
+                    "manual investigation",
                     err=True,
                 )
             elif not outcome.get("came_online"):
@@ -743,12 +745,15 @@ def agent_update(
                     # Distinguishing this from a bare "still reporting X"
                     # is the whole point: it says the process needs a
                     # restart, not another pip attempt.
+                    hint = restart_cmd.resolve_supervisor(
+                        machine, live=outcome.get("supervisor")
+                    )
                     click.echo(
                         f"  {machine.name}: ✗ installed {installed_now} but the "
                         f"running process still reports {version_now} (expected "
                         f"{target_version}) — it hasn't restarted since the "
-                        "update; try `systemctl --user restart coord-agent` "
-                        "on that machine",
+                        f"update; try {restart_cmd.restart_hint(hint)} on that "
+                        "machine",
                         err=True,
                     )
                 else:
@@ -1169,6 +1174,7 @@ def _wait_agents_updated(
             "result": None,
             "error": None,
             "escalated": False,
+            "supervisor": None,
         }
         for m in machines
     }
@@ -1199,6 +1205,11 @@ def _wait_agents_updated(
         info["result"] = last.get("result")
         info["error"] = last.get("error")
         info["version_before"] = last.get("version_before")
+        # #3366: the agent's own live self-report — when this ever
+        # disagrees with the machine's static `supervisor:` config, this
+        # wins (see `restart_cmd.resolve_supervisor`), because it's the
+        # host answering right now, not a fact someone typed once.
+        info["supervisor"] = health.get("supervisor")
 
         if machine.name in pre:
             pre_val = pre[machine.name]
@@ -1255,7 +1266,8 @@ def _wait_agents_updated(
 
 
 def _escalate_restart(machine) -> bool:
-    """Best-effort ``systemctl --user restart coord-agent`` over SSH.
+    """Best-effort driven restart of ``coord-agent`` over SSH — systemd or
+    launchd, whichever the target host actually runs (#3366).
 
     #404 / #1568: ``/update``'s ``os.execv`` self-restart does not take
     under systemd — same PID, stale version.  ``XDG_RUNTIME_DIR=/run/user/
@@ -1263,17 +1275,44 @@ def _escalate_restart(machine) -> bool:
     silently no-ops in a non-interactive SSH session.  See
     docs/AGENT_OPERATIONS.md for the manual runbook this automates.
 
-    Returns True if the ssh command itself exited 0 — NOT whether the
-    agent actually came back on the new version; the caller re-polls
-    /health afterwards to confirm that.
+    #3366: macOS ships no systemd at all, so the command above always
+    failed there — this was the whole escalation channel, and a fleet mac
+    (``docs/MAC_MINI.md``) simply had none: no automated recovery, and
+    every operator-facing message also only ever named ``systemctl``. The
+    working command is ``launchctl kickstart -k gui/<uid>/<label>``
+    (:mod:`coord.restart_cmd`). Rather than branching ahead of time on
+    possibly-stale config, the remote shell tries systemd FIRST — zero
+    behaviour change for the rest of the fleet — and only falls back to
+    launchd when ``systemctl`` genuinely isn't there to ask, discovering
+    the real launchd Label from the host's own plist (falling back to
+    :data:`coord.restart_cmd.LAUNCHD_LABEL` only if that read fails) so
+    this keeps working even if a second mac ever uses a different label.
+
+    Returns True if a restart command itself exited 0 on the target host —
+    NOT whether the agent actually came back on the new version; the
+    caller re-polls /health afterwards to confirm that.
     """
+    from coord.restart_cmd import LAUNCHD_LABEL  # noqa: PLC0415
+
+    remote_script = (
+        "if command -v systemctl >/dev/null 2>&1 && "
+        "XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart coord-agent "
+        "2>/dev/null; then exit 0; fi; "
+        'plist=$(ls "$HOME/Library/LaunchAgents"/*coord-agent*.plist 2>/dev/null | head -1); '
+        'if [ -n "$plist" ]; then '
+        "label=$(/usr/libexec/PlistBuddy -c 'Print :Label' \"$plist\" 2>/dev/null); "
+        f'label="${{label:-{LAUNCHD_LABEL}}}"; '
+        'exec launchctl kickstart -k "gui/$(id -u)/$label"; '
+        "fi; "
+        "exit 1"
+    )
     cmd = [
         "ssh",
         "-o", "BatchMode=yes",
         "-o", "ConnectTimeout=10",
         "-o", "StrictHostKeyChecking=accept-new",
         machine.host,
-        "XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart coord-agent",
+        remote_script,
     ]
     try:
         result = subprocess.run(cmd, capture_output=True, text=True, timeout=20)

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/commands/release.py

@@ -24,6 +24,7 @@ from typing import Any
 
 import click
 
+from coord import restart_cmd
 from coord.commands._common import _CONFIG_OPTION
 
 
@@ -1779,9 +1780,11 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
                 "ROLLBACK LEFT AGENTS DOWN: "
                 + ", ".join(down)
                 + " — these hosts answered the rollback but never came back "
-                "on /health, and an SSH `systemctl --user restart "
-                "coord-agent` did not revive them either. Recover by hand "
-                "before anything else."
+                "on /health, and a driven SSH restart (systemd "
+                f"({restart_cmd.restart_shell_command(restart_cmd.SYSTEMD)}) or "
+                f"launchd ({restart_cmd.restart_shell_command(restart_cmd.LAUNCHD)}), "
+                "whichever applies) did not revive them either. Recover by "
+                "hand before anything else."
             )
             click.echo(f"error: {record.error}", err=True)
         _finish(rp.STATUS_ROLLED_BACK, 2)
@@ -2715,6 +2718,16 @@ def _roll_units(machine, *, agent_port: int) -> tuple[bool | None, str]:
     # report" / a false-positive success.
     if status != 200 and not (status == 500 and "units" in body):
         return False, str(body.get("error") or body.get("summary") or f"HTTP {status}")
+    # #3366: the agent itself already told us this host has no systemd to
+    # deploy units onto (see `agent_app.py`'s `deploy_units` handler) —
+    # every packaged unit reading as "new"/"not installed here" on THAT
+    # host, every run, is the platform, not drift, so this is a structural
+    # gap like the pre-#1835 404 branch above, not a failed lane: `None`,
+    # same "not accountable for a lane it cannot roll" verdict #2052
+    # already established for that case.
+    detail = str(body.get("detail") or "")
+    if detail.startswith("n/a"):
+        return None, detail
     units = body.get("units") or []
     changed = [u.get("name") for u in units if u.get("action") == "updated"]
     new = [u.get("name") for u in units if u.get("action") == "new"]
@@ -3111,8 +3124,9 @@ def _rollback_host(
         )
         if back:
             return _back_on_target(
-                f"rolled back; agent needed an SSH `systemctl --user restart "
-                f"coord-agent` but is serving again on v{version}"
+                "rolled back; agent needed a driven SSH restart "
+                f"({restart_cmd.restart_hint(restart_cmd.resolve_supervisor(machine))}) "
+                f"but is serving again on v{version}"
             )
     return False, (
         "rolled back the venv but the agent is DOWN — it never came back on "
@@ -3120,8 +3134,9 @@ def _rollback_host(
         + (
             "the SSH restart did not revive it"
             if escalated
-            else "the SSH `systemctl --user restart coord-agent` escalation "
-            "could not run"
+            else "the SSH "
+            f"{restart_cmd.restart_hint(restart_cmd.resolve_supervisor(machine))} "
+            "escalation could not run"
         )
         + f". Recover by hand on {machine.name}."
     )

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/commands/status.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING
 
 import click
 
-from coord import __version__, github_ops
+from coord import __version__, github_ops, restart_cmd
 
 from coord.commands._common import _CONFIG_OPTION, _load_config
 
@@ -375,6 +375,16 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
                 version_line = f"  agent-version: {agent_version} ⚠ (coord is {__version__})"
             else:
                 version_line = f"  agent-version: {agent_version}"
+        # #3366: surface the non-default supervisor (launchd) up front,
+        # before it matters — "this agent is not running under systemd"
+        # used to only ever show up mid-incident, buried in a propagate
+        # run's output. Silent for the systemd case: that's every other
+        # machine in the fleet today, and naming it there would just be
+        # noise on every `coord status`.
+        live_supervisor = s.health.get("supervisor") if s.is_online and s.health else None
+        supervisor = restart_cmd.resolve_supervisor(m, live=live_supervisor)
+        if supervisor == restart_cmd.LAUNCHD:
+            version_line += "  supervisor: launchd"
         click.echo(f"    host: {m.host}  repos: {repos}{version_line}")
 
         # #1886 Path B: `/health` exposes `installed_version` (a disk read
@@ -399,7 +409,7 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
                 click.echo(
                     f"    ⚠ running v{running_version} but installed "
                     f"v{installed_version} — process hasn't restarted since "
-                    "its last update (`systemctl --user restart coord-agent` "
+                    f"its last update ({restart_cmd.restart_hint(supervisor)} "
                     "on that machine, or `coord agent update` to retry)"
                 )
 

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/config.py

@@ -3071,6 +3071,23 @@ def _parse_machines(raw: Any, repos: list[Repo]) -> list[Machine]:
             entry.get("quiet_hours"), machine_index=i, machine_name=name,
         )
 
+        # #3366: optional fact about which init system supervises this
+        # host's `coord agent` — see `Machine.supervisor`'s docstring for
+        # why it isn't inferred. Validated against the two names
+        # `coord.restart_cmd` actually knows rather than left free-form,
+        # so a typo (`launchD`, `Systemd`) fails config load loudly
+        # instead of silently falling through to the systemd default the
+        # same way an unset field does.
+        machine_supervisor = entry.get("supervisor")
+        if machine_supervisor is not None:
+            if not isinstance(machine_supervisor, str) or machine_supervisor not in (
+                "systemd", "launchd",
+            ):
+                raise ConfigError(
+                    f"machines[{i}].supervisor must be 'systemd' or 'launchd', "
+                    f"got {machine_supervisor!r}"
+                )
+
         # #3340: optional per-machine floor for the `/health` reachability
         # probe timeout — see `Machine.health_timeout`'s docstring for why
         # this exists instead of just raising `network.DEFAULT_TIMEOUT`.
@@ -3094,6 +3111,7 @@ def _parse_machines(raw: Any, repos: list[Repo]) -> list[Machine]:
                 max_workers=machine_max_workers,
                 quiet_hours=quiet_hours,
                 health_timeout=machine_health_timeout,
+                supervisor=machine_supervisor,
             )
         )
     return machines

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/machine_onboard.py

@@ -96,6 +96,7 @@ from typing import TYPE_CHECKING
 # vocabulary is imported rather than restated so a third role added there
 # needs no edit here, and so no second default can drift into existence.
 from coord.deploy_manifest import ROLE_DAEMON, ROLE_WORKER
+from coord import restart_cmd
 
 if TYPE_CHECKING:  # pragma: no cover — typing only
     from coord.config import Config
@@ -419,6 +420,11 @@ class MachineFacts:
     #: Diagnostic only — the verdict comes from the agent's own probes, never
     #: from re-deriving a lookup against this string.
     agent_path: str | None = None
+    #: #3366: "systemd" / "launchd" / None (unprobed, or neither finder
+    #: found the agent) — which init system supervises this host's agent,
+    #: read straight off the SSH probe above (`ShellProbe.supervisor`).
+    #: Only known when :attr:`shell_probed` is True.
+    supervisor: str | None = None
 
     # ── Layer 8: identity ────────────────────────────────────────────────
     identity: IdentityFacts = field(default_factory=IdentityFacts)
@@ -656,14 +662,27 @@ def _agent_path_from_launchd():
     return declared
 
 
+#: #3366: which finder actually answered the last `discover_agent_path()`
+#: call — "systemd", "launchd", or None (neither found anything). Same
+#: side-channel shape as `_LAUNCHD_LIVE_PATH` above: `discover_agent_path()`
+#: must keep returning a single string (it's shared by two scripts, see the
+#: module comment), so a caller that wants to know WHICH supervisor found
+#: the agent (`OUT["agent_supervisor"]` below, ultimately
+#: `MachineFacts.supervisor`) reads this global right after calling it.
+_AGENT_PATH_SOURCE = None
+
+
 def discover_agent_path():
     \"\"\"The PATH the coord agent process on THIS host runs with, or None.\"\"\"
-    for finder in (_agent_path_from_systemd, _agent_path_from_launchd):
+    global _AGENT_PATH_SOURCE
+    _AGENT_PATH_SOURCE = None
+    for source, finder in (("systemd", _agent_path_from_systemd), ("launchd", _agent_path_from_launchd)):
         try:
             found = finder()
         except Exception:
             found = None
         if found:
+            _AGENT_PATH_SOURCE = source
             return found
     return None
 
@@ -961,6 +980,11 @@ OUT["login_path"] = so.strip() or None
 # of the #1671 comparison works on a launchd host too, instead of silently
 # reporting None on every mac.
 OUT["agent_path"] = discover_agent_path()
+# #3366: which of the two finders above actually found it — "systemd",
+# "launchd", or null. Lets a PATH-fix remediation on the coordinator side
+# name the right override mechanism (a systemd drop-in vs. the plist's
+# EnvironmentVariables) instead of only ever describing the systemd one.
+OUT["agent_supervisor"] = _AGENT_PATH_SOURCE
 
 # ── role: #3128's resolver, on the host that owns the declaration ──────
 try:
@@ -1112,6 +1136,10 @@ class ShellProbe:
     login_path_tools: dict[str, str | None] = field(default_factory=dict)
     login_path: str | None = None
     agent_path: str | None = None
+    #: #3366: "systemd" / "launchd" / None — which finder in
+    #: `_AGENT_PATH_DISCOVERY` actually resolved `agent_path` above, i.e.
+    #: which supervisor is running the agent on the probed host.
+    supervisor: str | None = None
     role: str = ROLE_WORKER
     role_source: str = "default"
     role_valid: bool = True
@@ -1235,11 +1263,13 @@ def parse_shell_probe(stdout: str) -> ShellProbe:
         board_reason=_reason("board_reason"),
         backup_env_present=_tri("backup_env_present"),
     )
+    supervisor_raw = payload.get("agent_supervisor")
     return ShellProbe(
         role_error=redact(str(role_error)) if role_error else None,
         login_path_tools=tools,
         login_path=str(payload["login_path"]) if payload.get("login_path") else None,
         agent_path=str(payload["agent_path"]) if payload.get("agent_path") else None,
+        supervisor=str(supervisor_raw) if supervisor_raw in ("systemd", "launchd") else None,
         role=role,
         role_source=str(role_block.get("source") or "default"),
         role_valid=bool(role_block.get("valid", True)),
@@ -1443,6 +1473,7 @@ def gather_facts(
         facts.login_path_tools = probe.login_path_tools
         facts.login_path = probe.login_path
         facts.agent_path = probe.agent_path
+        facts.supervisor = probe.supervisor
         facts.identity = (
             probe.identity if probe.error is None
             else IdentityFacts(probed=False, error=probe.error)
@@ -2313,12 +2344,30 @@ def _toolchain_finding(facts: MachineFacts, prereq: "Prereq") -> Finding:
                     "retries forever, and no board readout says why"
                 ),
                 subject=prereq.tool,
+                # #3366: the override mechanism itself is supervisor-specific
+                # (a systemd drop-in vs. the launchd plist's own
+                # EnvironmentVariables), not just the trailing restart
+                # command — a launchd host has no `~/.config/systemd/user/`
+                # to write a drop-in into at all. `facts.supervisor` comes
+                # from the same SSH probe that found `agent_path` above, so
+                # this can only be `None` when that probe didn't run
+                # (`--ssh` omitted) or found neither — in which case the
+                # pre-#3366 systemd-only text is exactly right for every
+                # machine that predates this fix.
                 fix=(
+                    f"put {login}'s directory on the AGENT's PATH — edit this "
+                    "host's launchd plist's `EnvironmentVariables/PATH` "
+                    "(`~/Library/LaunchAgents/*coord-agent*.plist`), then "
+                    f"{restart_cmd.restart_hint(restart_cmd.LAUNCHD)}. Fixing "
+                    "your login shell's PATH changes nothing: the agent "
+                    "never reads it."
+                    if facts.supervisor == "launchd"
+                    else
                     f"put {login}'s directory on the AGENT's PATH — a `PATH=` line "
                     "in ~/.config/systemd/user/coord-agent.service.d/*.conf (or a "
                     "~/.local/bin shim, as deploy/node-shim.sh does for Node), then "
-                    "`systemctl --user restart coord-agent`. Fixing your login "
-                    "shell's PATH changes nothing: the agent never reads it."
+                    f"{restart_cmd.restart_hint(restart_cmd.SYSTEMD)}. Fixing your "
+                    "login shell's PATH changes nothing: the agent never reads it."
                 ),
             )
         where = (

{code_coordinator-0.5.499 → code_coordinator-0.5.501}/coord/models.py

@@ -446,6 +446,19 @@ class Machine:
     # caller's requested timeout and this value — a per-machine floor, never
     # a ceiling that could silently shrink a caller's own longer request.
     health_timeout: float | None = None
+    # #3366: optional operator-set fact about which init system supervises
+    # `coord agent` on this host — "systemd" or "launchd" (see
+    # `coord.restart_cmd`). `None` (the default, and every config that
+    # predates this field) means "unknown, assume systemd" — the exact
+    # pre-#3366 behaviour, never a guess: launchd hosts do not reliably
+    # carry any other distinguishing config (macmini's own capabilities
+    # are `[python, rust]`, not `macos` — `docs/MAC_MINI.md`), so this is
+    # deliberately a fact an operator states, not one inferred. Only
+    # consulted as a FALLBACK behind a live `/health` "supervisor"
+    # self-report — see `coord.restart_cmd.resolve_supervisor` — and never
+    # by the SSH escalation itself, which auto-detects on the target host
+    # regardless of what this says.
+    supervisor: str | None = None
 
     def can_work_on(self, repo_name: str) -> bool:
         return repo_name in self.repos