code-coordinator 0.5.553__tar.gz → 0.5.554__tar.gz

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.553
+Version: 0.5.554
 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.553 → code_coordinator-0.5.554}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.553",
+  "tag": "0.5.554",
   "distance": 0,
-  "node": "g08b8bc7ce4b5def5fdf426d91f30704832a6c88b",
+  "node": "g9153537fcc25cf8e03c74a83899452ecc73a6f92",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-01"

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/acceptance.py

@@ -957,13 +957,22 @@ def build_verdict(
     passed = sum(1 for t in tests if t.get("status") == "pass")
     failed = sum(1 for t in tests if t.get("status") == "fail")
     skipped = sum(1 for t in tests if t.get("status") == "skip")
+    # #3510: a session precheck (win-native/mac-native/gtk-native) that
+    # finds a locked/absent GUI reports a distinct "unavailable" status,
+    # not "fail" — it's an environment condition, not an app bug. It must
+    # still block `green`/`ci_green`: an unconfirmed result is not a pass
+    # (epic #2096's "a gate must be able to fail" / "unconfirmed success
+    # is a defect"). Counted and reported separately so callers can tell
+    # "the app is broken" apart from "go unlock the host".
+    unavailable = sum(1 for t in tests if t.get("status") == "unavailable")
     payload: dict[str, Any] = {
         "scope": scope,
         "total": len(tests),
         "passed": passed,
         "failed": failed,
         "skipped": skipped,
-        "green": failed == 0 and len(tests) > 0,
+        "unavailable": unavailable,
+        "green": failed == 0 and unavailable == 0 and len(tests) > 0,
         "tests": tests,
     }
     if issue_number is not None:
@@ -1038,12 +1047,18 @@ def apply_expected_red(verdict: dict[str, Any], expected_red_ids: "set[str]") ->
     real_failures = sum(
         1 for t in tests if t.get("status") == "fail" and t["id"] not in expected_red_ids
     )
+    # #3510: an `unavailable` entry (locked/absent GUI session) is never
+    # expected-red-eligible — it isn't a test failure to excuse, it's a
+    # precheck that never ran anything — so it always counts against
+    # `ci_green` just like it does against `green` in build_verdict.
+    unavailable = verdict.get("unavailable", 0)
     verdict["unexpected_green"] = unexpected_green
     verdict["expected_red_still_red"] = expected_red_still_red
     verdict["missing_expected_red_ids"] = missing_expected_red_ids
     verdict["ci_green"] = (
         len(tests) > 0
         and real_failures == 0
+        and unavailable == 0
         and not unexpected_green
         and not missing_expected_red_ids
     )

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/acceptance_drivers.py

@@ -782,7 +782,15 @@ def _run_win_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int
     except WinNativeRuntimeError as e:
         raise DriverError(f"win-native driver could not run: {e}") from e
 
-    exit_code = 0 if tests and all(t.get("status") != "fail" for t in tests) else 1
+    # #3510: a locked/absent interactive session reports a distinct
+    # "unavailable" status (coord.win_native_driver's session precheck),
+    # not "fail" — it must still fail this exit code rather than read as a
+    # silent pass. An unconfirmed result is not a pass.
+    exit_code = (
+        0
+        if tests and all(t.get("status") not in ("fail", "unavailable") for t in tests)
+        else 1
+    )
     raw_output = "\n".join(
         f"{t.get('status')}: {t.get('id')} {t.get('message', '')}".rstrip()
         for t in tests
@@ -843,7 +851,14 @@ def _run_mac_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int
     except MacNativeRuntimeError as e:
         raise DriverError(f"mac-native driver could not run: {e}") from e
 
-    exit_code = 0 if tests and all(t.get("status") != "fail" for t in tests) else 1
+    # #3510: a locked/absent GUI session reports a distinct "unavailable"
+    # status (coord.mac_native_driver's session precheck), not "fail" —
+    # it must still fail this exit code rather than read as a silent pass.
+    exit_code = (
+        0
+        if tests and all(t.get("status") not in ("fail", "unavailable") for t in tests)
+        else 1
+    )
     raw_output = "\n".join(
         f"{t.get('status')}: {t.get('id')} {t.get('message', '')}".rstrip()
         for t in tests
@@ -904,7 +919,15 @@ def _run_gtk_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int
     except GtkNativeRuntimeError as e:
         raise DriverError(f"gtk-native driver could not run: {e}") from e
 
-    exit_code = 0 if tests and all(t.get("status") != "fail" for t in tests) else 1
+    # #3510: a missing $DISPLAY/$WAYLAND_DISPLAY reports a distinct
+    # "unavailable" status (coord.gtk_native_driver's session precheck),
+    # not "fail" — it must still fail this exit code rather than read as a
+    # silent pass.
+    exit_code = (
+        0
+        if tests and all(t.get("status") not in ("fail", "unavailable") for t in tests)
+        else 1
+    )
     raw_output = "\n".join(
         f"{t.get('status')}: {t.get('id')} {t.get('message', '')}".rstrip()
         for t in tests

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/bugbash.py

@@ -45,6 +45,20 @@ routing does — a lane only exists when some configured machine actually
 carries the driver's declared ``capability``, so a repo with no capable
 machine for a platform silently gets no lane rather than a lane that can
 never run.
+
+**#3510: an unavailable lane is not a bug finding.** When a win-native/
+mac-native/gtk-native lane's own driver reports a locked or absent GUI
+session (or no usable display), an explorer that sets
+:attr:`ExploreOutcome.unavailable` causes :func:`run_bugbash` to skip that
+lane for the round (:attr:`RoundReport.unavailable_lanes`) rather than
+running the exploration checklist against it or filing any finding from it
+— a locked desktop is an environment condition for the operator to fix,
+not evidence of an app bug. This engine-level behavior is unit-tested
+against a fake explorer in ``tests/test_bugbash.py``; the production
+explorer (:func:`coord.commands.bugbash._dispatch_and_await_lane`) does
+not itself set ``unavailable`` yet — see its own module docstring's
+"KNOWN GAP" note — so a live ``coord bugbash`` run does not currently
+benefit from this skip until that wiring lands.
 """
 
 from __future__ import annotations
@@ -426,12 +440,31 @@ class ExploreOutcome:
     there were findings," the second means "we looked, and there weren't
     any" — :func:`run_bugbash` keeps them distinguishable in
     :attr:`RoundReport.lane_failures` and its termination reason, rather
-    than collapsing both into "zero findings"."""
+    than collapsing both into "zero findings".
+
+    ``unavailable`` is a THIRD, separate outcome (#3510): the lane's own
+    native driver observed a locked/absent GUI session (win-native/
+    mac-native) or no usable display (gtk-native) and ran no exploration at
+    all — a host/environment condition, never a bug finding and never a
+    dispatch/poll failure. An explorer that sets ``unavailable=True`` (as
+    the fake explorers in ``tests/test_bugbash.py`` do, modeling a
+    dispatched worker whose Tier-2 lane result came back
+    ``status="unavailable"`` — see ``coord.win_native_driver``'s/
+    ``coord.mac_native_driver``'s/``coord.gtk_native_driver``'s own
+    precheck) causes :func:`run_bugbash` to skip that lane for the round —
+    recording it in :attr:`RoundReport.unavailable_lanes` instead of
+    :attr:`RoundReport.lane_failures` — and never file findings from it
+    this round, even defensively, regardless of what ``findings`` carries.
+    The production explorer,
+    :func:`coord.commands.bugbash._dispatch_and_await_lane`, does not yet
+    set this flag (tracked as a KNOWN GAP in that module's docstring) —
+    today this is exercised only at the engine/unit-test level."""
 
     findings: tuple[Finding, ...] = ()
     cost: float = 0.0
     notes: str = ""
     ok: bool = True
+    unavailable: bool = False
 
 
 #: ``(lane, round_num) -> ExploreOutcome`` — "go run this lane's
@@ -628,6 +661,16 @@ class RoundReport:
     #: a lane skipped for having blown its per-lane cost cap was never
     #: asked a question this round, so it can't have failed to answer one).
     lane_failures: dict[str, str] = field(default_factory=dict)
+    #: ``{platform: notes}`` for every lane explored this round whose
+    #: :attr:`ExploreOutcome.unavailable` was ``True`` (#3510) — a locked or
+    #: absent GUI session (win-native/mac-native) or no usable display
+    #: (gtk-native). Distinct from :attr:`lane_failures`: this is a verified
+    #: observation (the native driver's own session precheck ran and
+    #: reported it), not a dispatch/poll/log failure — but it is ALSO not a
+    #: verified "ran the checklist and found nothing" either, so it is
+    #: tracked separately rather than folded into either bucket. No
+    #: findings are ever filed from a lane recorded here this round.
+    unavailable_lanes: dict[str, str] = field(default_factory=dict)
 
     @property
     def explored_lanes(self) -> set[str]:
@@ -643,10 +686,27 @@ class RoundReport:
         not a clean pass" signal (#2096). A round with nothing explored at
         all (e.g. every lane skipped on its cost cap) is NOT reported as
         "all failed" — there is nothing to distrust, just nothing that
-        ran."""
+        ran. Does NOT count an ``unavailable`` lane as failed — see
+        :attr:`all_explored_lanes_unavailable_or_failed` for the combined
+        check."""
         explored = self.explored_lanes
         return bool(explored) and explored <= set(self.lane_failures)
 
+    @property
+    def all_explored_lanes_unavailable_or_failed(self) -> bool:
+        """``True`` when every lane explored this round either failed to
+        dispatch/poll/log OR reported its GUI session/display unavailable
+        (#3510) — i.e. NONE of them actually ran the exploration checklist.
+        Used by :func:`run_bugbash` to pick the ``"lanes_unavailable"``
+        termination reason over a false ``"zero_findings"`` clean-pass read
+        when every lane this round was simply locked/absent rather than
+        genuinely explored (#2096: zero findings is only a clean pass when
+        something was actually observed to run)."""
+        explored = self.explored_lanes
+        return bool(explored) and explored <= (
+            set(self.lane_failures) | set(self.unavailable_lanes)
+        )
+
 
 @dataclass
 class BugbashReport:
@@ -677,6 +737,15 @@ class BugbashReport:
         part of what it observed along the way was unverified (#2096)."""
         return any(r.lane_failures for r in self.rounds)
 
+    @property
+    def any_lane_unavailable(self) -> bool:
+        """``True`` if ANY round recorded a lane as unavailable (#3510) —
+        surfaced regardless of whether it happened to be the terminating
+        round, so an operator glancing at a run that otherwise filed/found
+        plenty still sees that one platform was locked/absent the whole
+        time and needs attention, not a bug report."""
+        return any(r.unavailable_lanes for r in self.rounds)
+
 
 def run_bugbash(
     config: BugbashConfig,
@@ -701,14 +770,24 @@ def run_bugbash(
     ``new_count``/cost, never inferred from "no exception was raised":
 
     - ``"zero_findings"`` — this round's non-duplicate finding count is 0,
-      AND at least one explored lane actually completed
-      (``RoundReport.all_explored_lanes_failed`` is ``False``) — a genuine
-      observed clean pass.
+      AND at least one explored lane actually completed its checklist
+      (neither ``RoundReport.all_explored_lanes_failed`` nor
+      ``RoundReport.all_explored_lanes_unavailable_or_failed`` is ``True``)
+      — a genuine observed clean pass.
     - ``"lane_failure"`` — this round's non-duplicate finding count is ALSO
       0, but every lane explored this round came back ``ok=False``
       (dispatch/poll/log failure) — #2096: a fleet-wide dispatch outage
       must never be reported identically to a clean bugbash pass. Check
       ``BugbashReport.rounds[-1].lane_failures`` for what actually broke.
+    - ``"lanes_unavailable"`` — this round's non-duplicate finding count is
+      ALSO 0, no lane came back a dispatch/poll/log failure, but every lane
+      explored this round reported its GUI session/display unavailable
+      (#3510: locked or absent, e.g. a locked dell64) — a different reason
+      from ``"lane_failure"`` (the explorer DID run and DID get a verified
+      answer, it's just "the host is locked", not "I don't know"), and
+      still not a clean pass either, since nothing was actually exercised
+      against the app. Check ``BugbashReport.rounds[-1].unavailable_lanes``
+      for which host needs unlocking.
     - ``"cost_cap"`` — cumulative cost has reached ``cost_cap_total``.
     - ``"round_cap"`` — ``config.max_rounds`` rounds ran without either of
       the above firing.
@@ -730,6 +809,16 @@ def run_bugbash(
             lane_cost[lane.platform] += outcome.cost
             report.lane_cost[lane.platform] = lane_cost[lane.platform]
             total_cost += outcome.cost
+            if outcome.unavailable:
+                # #3510: a locked/absent GUI session (or missing display)
+                # is a host condition, not a finding — recorded separately
+                # from both a clean pass and a dispatch/poll failure, and
+                # NEVER contributes findings this round, even defensively
+                # if the explorer happened to also hand some back.
+                report.unavailable_lanes[lane.platform] = (
+                    outcome.notes or "lane unavailable — no usable GUI session/display"
+                )
+                continue
             report.findings.extend(outcome.findings)
             if not outcome.ok:
                 # #2096: this lane's "findings" (almost certainly empty) are
@@ -788,11 +877,20 @@ def run_bugbash(
 
         if report.new_count == 0:
             # #2096: "zero findings" is only a genuine clean-pass verdict
-            # when at least one lane was actually verified to have run this
-            # round. A round where every explored lane failed to dispatch,
-            # poll, or fetch its log gets its own distinct reason instead —
-            # see RoundReport.lane_failures for what broke.
-            reason = "lane_failure" if report.all_explored_lanes_failed else "zero_findings"
+            # when at least one lane was actually verified to have RUN THE
+            # CHECKLIST this round. A round where every explored lane failed
+            # to dispatch/poll/fetch its log gets "lane_failure"; a round
+            # where every explored lane instead reported its session/display
+            # unavailable (#3510 — locked or absent, never a dispatch
+            # failure) gets its own distinct "lanes_unavailable" reason, in
+            # that priority order since a round can't be "all failed" AND
+            # "all unavailable" (each lane only sets one of the two).
+            if report.all_explored_lanes_failed:
+                reason = "lane_failure"
+            elif report.all_explored_lanes_unavailable_or_failed:
+                reason = "lanes_unavailable"
+            else:
+                reason = "zero_findings"
             break
         if total_cost >= config.cost_cap_total:
             reason = "cost_cap"

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/commands/release.py

@@ -4551,6 +4551,12 @@ def _load_release_gate_observations(
             passed=_require_bool(entry["passed"], field_name="lanes[].passed"),
             detail=entry.get("detail", ""),
             checked_at=entry.get("checked_at"),
+            # #3510: a locked/absent GUI session or missing display, as
+            # reported by the native driver's own session precheck — never
+            # coerced from a truthy non-bool, same discipline as `passed`.
+            unavailable=_require_bool(
+                entry.get("unavailable", False), field_name="lanes[].unavailable",
+            ),
         )
         for entry in payload.get("lanes", []) or []
     ]
@@ -4576,7 +4582,10 @@ def _gate_verdict_to_dict(verdict: "Any") -> dict[str, Any]:
         "gate_passed": verdict.gate_passed,
         "effective_passed": verdict.effective_passed,
         "steps": [
-            {"name": s.name, "passed": s.passed, "detail": s.detail}
+            {
+                "name": s.name, "passed": s.passed, "detail": s.detail,
+                "unavailable": s.unavailable,
+            }
             for s in verdict.steps
         ],
         "override": None if verdict.override is None else {
@@ -4590,7 +4599,15 @@ def _gate_verdict_to_dict(verdict: "Any") -> dict[str, Any]:
 def _render_gate_verdict(verdict: "Any") -> str:
     lines = [f"release gate: {verdict.repo} @ {verdict.release_sha}"]
     for step in verdict.steps:
-        marker = "PASS" if step.passed else "FAIL"
+        # #3510: a locked/absent GUI session is blocking but is NOT the app
+        # failing — labeled distinctly so an operator knows to unlock the
+        # host rather than go debug the app.
+        if step.unavailable:
+            marker = "UNAVAILABLE"
+        elif step.passed:
+            marker = "PASS"
+        else:
+            marker = "FAIL"
         lines.append(f"  [{marker}] {step.name}: {step.detail}")
     if verdict.override is not None:
         lines.append(

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/gtk_native_driver.py

@@ -106,6 +106,18 @@ child. See ``tests/test_gtk_native_driver.py``'s
 regression guard, mirroring :mod:`coord.win_native_driver`'s
 ``test_no_image_name_kill_path_exists_in_the_module`` and
 :mod:`coord.mac_native_driver`'s own equivalent.
+
+**Missing-display precheck (#3510).** Unlike ``win-native``/``mac-native``,
+a missing display here means no ``$DISPLAY``/``$WAYLAND_DISPLAY`` at all —
+no Xvfb/compositor session is up on this host. That's a host-provisioning
+condition, not an app bug, so before :meth:`NativeRunner.run` launches
+anything it calls :meth:`GtkCalls.session_available`. When unavailable, the
+run returns a single ``status="unavailable"`` result — never a ``"fail"``
+— and no step (not even ``launch``) runs. ``LinuxGtkCalls`` itself no
+longer raises at construction time for a missing display (that check moved
+into :meth:`LinuxGtkCalls.session_available` so it's always reachable
+through the seam, including from a fake in tests) — only a non-Linux host
+is still a construction-time :class:`GtkNativeRuntimeError`.
 """
 
 from __future__ import annotations
@@ -129,10 +141,12 @@ class GtkNativeSpecError(Exception):
 
 
 class GtkNativeRuntimeError(Exception):
-    """Raised when the native driver itself can't run: not on Linux, no
-    ``$DISPLAY`` available, a missing ``xdotool``/``xwd`` binary or AT-SPI
-    binding, the launched process/window never appearing, or a step
-    referencing a window before any ``launch`` step ran."""
+    """Raised when the native driver itself can't run: not on Linux, a
+    missing ``xdotool``/``xwd`` binary or AT-SPI binding, the launched
+    process/window never appearing, or a step referencing a window before
+    any ``launch`` step ran. A missing ``$DISPLAY``/``$WAYLAND_DISPLAY`` is
+    NOT one of these (#3510) — that is an "unavailable" lane verdict via
+    :meth:`GtkCalls.session_available`, never a raised exception."""
 
 
 # ── native spec model ───────────────────────────────────────────────────────
@@ -314,6 +328,16 @@ class GtkCalls(Protocol):
 
     def kill(self, pid: int) -> None: ...
 
+    def session_available(self) -> tuple[bool, str]:
+        """``(True, "")`` when a usable display is present for this driver
+        to launch into; ``(False, reason)`` when neither ``$DISPLAY`` nor
+        ``$WAYLAND_DISPLAY`` is set (#3510) — checked by
+        :meth:`NativeRunner.run` BEFORE any step (including ``launch``)
+        runs, so a missing display is reported as ``status="unavailable"``
+        rather than a failed step. Never raises — a probe failure here is
+        itself an "unavailable" verdict, not a crash."""
+        ...
+
 
 def _find_a11y_match(elements: list[dict], role: str, name: str) -> dict | None:
     """The first *elements* entry whose ``role`` matches exactly
@@ -368,7 +392,19 @@ class NativeRunner:
         self._window_id: int | None = None
 
     def run(self, spec: NativeSpec) -> list[dict]:
+        """Run *spec*, first checking :meth:`GtkCalls.session_available`
+        (#3510). A missing display is a host-provisioning condition, not an
+        app bug: when unavailable, this returns a single
+        ``status="unavailable"`` entry and runs NO step at all (not even
+        ``launch``) — never folding it into an ordinary ``"fail"``."""
         self._spec = spec
+        available, reason = self._calls.session_available()
+        if not available:
+            return [{
+                "id": "session",
+                "status": "unavailable",
+                "message": reason or "no usable display is available",
+            }]
         results: list[dict] = []
         try:
             for step in spec.steps:
@@ -557,12 +593,14 @@ class LinuxGtkCalls:
     ``python3-gi``) for the accessibility tree, and ``xwd`` (ships with every
     X11 install) for window captures.
 
-    Linux-only, and requires a live ``$DISPLAY``: raises
-    :class:`GtkNativeRuntimeError` at construction otherwise, mirroring
-    :class:`coord.mac_native_driver.MacOSCalls`'s/
-    :class:`coord.win_native_driver.Win32Calls`'s own platform guards. This
-    driver never starts its own ``Xvfb`` — see the module docstring's
-    "headless by construction" note.
+    Linux-only: raises :class:`GtkNativeRuntimeError` at construction on any
+    other platform, mirroring :class:`coord.mac_native_driver.MacOSCalls`'s/
+    :class:`coord.win_native_driver.Win32Calls`'s own platform guards. A
+    missing ``$DISPLAY``/``$WAYLAND_DISPLAY`` is NOT a construction-time
+    raise (#3510) — see :meth:`session_available`, checked by
+    :class:`NativeRunner` before any step runs. This driver never starts its
+    own ``Xvfb`` — see the module docstring's "headless by construction"
+    note.
     """
 
     def __init__(self) -> None:
@@ -572,11 +610,25 @@ class LinuxGtkCalls:
                 "runs on a real Linux host with a display (e.g. a fleet "
                 "host running a persistent Xvfb session)"
             )
-        if not os.environ.get("DISPLAY"):
-            raise GtkNativeRuntimeError(
-                "gtk-native needs $DISPLAY set — no headless compositor or "
-                "Xvfb session appears to be running on this host"
-            )
+        # Deliberately NOT a construction-time raise for a missing display
+        # (#3510) — that is an "unavailable" lane verdict, not a driver
+        # construction failure, and is checked (and reachable through the
+        # same `GtkCalls` seam a test's fake implements) via
+        # :meth:`session_available`, called by `NativeRunner.run` before any
+        # step — see the module docstring's "missing-display precheck".
+
+    # -- session precheck (#3510) --
+
+    def session_available(self) -> tuple[bool, str]:
+        """Real check: either ``$DISPLAY`` (X11) or ``$WAYLAND_DISPLAY``
+        (Wayland) must be set — no headless compositor or Xvfb session
+        appears to be running on this host otherwise."""
+        if os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"):
+            return True, ""
+        return False, (
+            "neither $DISPLAY nor $WAYLAND_DISPLAY is set — no headless "
+            "compositor or Xvfb session appears to be running on this host"
+        )
 
     # -- process lifecycle --
 
@@ -772,6 +824,12 @@ def run_native_spec(
     assertion fails) do NOT raise — they're folded into the returned list
     as a ``status="fail"`` entry, the same "partial results, not a crash"
     contract :func:`coord.mac_native_driver.run_native_spec` already gives.
+
+    When *calls* reports no usable display
+    (:meth:`GtkCalls.session_available`, #3510), the returned list is a
+    single ``status="unavailable"`` entry and no step runs — a distinct
+    verdict from ``"fail"``, since a missing display is a host-provisioning
+    condition, not an app bug.
     """
     spec = parse_native_spec(spec_text)
     resolved_calls = calls if calls is not None else LinuxGtkCalls()

{code_coordinator-0.5.553 → code_coordinator-0.5.554}/coord/mac_native_driver.py

@@ -84,6 +84,16 @@ own child. See ``tests/test_mac_native_driver.py``'s
 ``test_no_name_based_kill_path_exists_in_the_module`` — a source-level
 regression guard, mirroring :mod:`coord.win_native_driver`'s own
 ``test_no_image_name_kill_path_exists_in_the_module``.
+
+**Locked/absent session precheck (#3510).** The same vimcode#1629 class of
+problem applies here: a locked screen or no GUI session (headless/SSH-only)
+is an environment condition, not an app bug. Before :meth:`NativeRunner.run`
+launches anything it calls :meth:`MacCalls.session_available` — real check:
+``CGSessionCopyCurrentDictionary`` must return a session, with
+``CGSSessionScreenIsLocked`` false and ``kCGSessionOnConsoleKey`` true. When
+unavailable, the run returns a single ``status="unavailable"`` result —
+never a ``"fail"`` — and no step (not even ``launch``) runs. See
+:mod:`coord.win_native_driver`'s own module docstring for the same shape.
 """
 
 from __future__ import annotations
@@ -293,6 +303,17 @@ class MacCalls(Protocol):
 
     def kill(self, pid: int) -> None: ...
 
+    def session_available(self) -> tuple[bool, str]:
+        """``(True, "")`` when an unlocked GUI session is present for this
+        driver to launch into; ``(False, reason)`` when the screen is
+        locked or no GUI session exists (#3510) — checked by
+        :meth:`NativeRunner.run` BEFORE any step (including ``launch``)
+        runs, so a locked/absent session is reported as
+        ``status="unavailable"`` rather than a failed step. Never raises —
+        a probe failure here is itself an "unavailable" verdict, not a
+        crash."""
+        ...
+
 
 def _find_a11y_match(elements: list[dict], role: str, name: str) -> dict | None:
     """The first *elements* entry whose ``role`` matches exactly
@@ -345,7 +366,19 @@ class NativeRunner:
         self._window_id: int | None = None
 
     def run(self, spec: NativeSpec) -> list[dict]:
+        """Run *spec*, first checking :meth:`MacCalls.session_available`
+        (#3510). A locked screen or absent GUI session is an environment
+        condition, not an app bug: when unavailable, this returns a single
+        ``status="unavailable"`` entry and runs NO step at all (not even
+        ``launch``) — never folding it into an ordinary ``"fail"``."""
         self._spec = spec
+        available, reason = self._calls.session_available()
+        if not available:
+            return [{
+                "id": "session",
+                "status": "unavailable",
+                "message": reason or "no unlocked GUI session is available",
+            }]
         results: list[dict] = []
         try:
             for step in spec.steps:
@@ -577,6 +610,31 @@ class MacOSCalls:
         except ProcessLookupError:
             pass
 
+    # -- session precheck (#3510) --
+
+    def session_available(self) -> tuple[bool, str]:
+        """Real check: ``CGSessionCopyCurrentDictionary`` must return an
+        actual session dictionary (``None``/empty means no GUI session is
+        logged in at all — headless or SSH-only), its
+        ``CGSSessionScreenIsLocked`` key must be false, and its
+        ``kCGSessionOnConsoleKey`` must be true (fast-user-switched-away
+        sessions are not on the console)."""
+        quartz = self._quartz
+        session_info = quartz.CGSessionCopyCurrentDictionary()
+        if not session_info:
+            return False, (
+                "CGSessionCopyCurrentDictionary returned no session — no "
+                "GUI session is active on this host (headless, SSH-only, "
+                "or nobody logged in)"
+            )
+        if bool(session_info.get("CGSSessionScreenIsLocked", False)):
+            return False, "the screen is locked (CGSSessionScreenIsLocked)"
+        if not bool(session_info.get("kCGSessionOnConsoleKey", True)):
+            return False, (
+                "the session is not on the console (fast user switched away)"
+            )
+        return True, ""
+
     def find_top_window(self, pid: int, timeout_s: float) -> int:
         quartz = self._quartz
         deadline = time.monotonic() + timeout_s
@@ -785,6 +843,12 @@ def run_native_spec(
     assertion fails) do NOT raise — they're folded into the returned list
     as a ``status="fail"`` entry, the same "partial results, not a crash"
     contract :func:`coord.win_native_driver.run_native_spec` already gives.
+
+    When *calls* reports a locked screen or no GUI session
+    (:meth:`MacCalls.session_available`, #3510), the returned list is a
+    single ``status="unavailable"`` entry and no step runs — a distinct
+    verdict from ``"fail"``, since a locked screen is an environment
+    condition, not an app bug.
     """
     spec = parse_native_spec(spec_text)
     resolved_calls = calls if calls is not None else MacOSCalls()