code-coordinator 0.5.511__tar.gz → 0.5.512__tar.gz

{code_coordinator-0.5.511 → code_coordinator-0.5.512}/PKG-INFO

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

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

@@ -76,6 +76,7 @@ coord/dr_promote.py
 coord/dr_verify.py
 coord/drive.py
 coord/drive_queue.py
+coord/drive_sessions_snapshot.py
 coord/drive_state.py
 coord/events.py
 coord/failure_class.py
@@ -622,6 +623,7 @@ tests/test_drive_queue_max_parallel_config.py
 tests/test_drive_queue_max_parallel_per_repo_config.py
 tests/test_drive_queue_roll_pending.py
 tests/test_drive_queue_self_cordon_escalation.py
+tests/test_drive_sessions_snapshot.py
 tests/test_drive_state.py
 tests/test_drive_tmux.py
 tests/test_epic_up_capability_detection.py

{code_coordinator-0.5.511 → code_coordinator-0.5.512}/code_coordinator.egg-info/scm_file_list.json

@@ -136,6 +136,7 @@
     "coord/dr_verify.py",
     "coord/drive.py",
     "coord/drive_queue.py",
+    "coord/drive_sessions_snapshot.py",
     "coord/drive_state.py",
     "coord/events.py",
     "coord/failure_class.py",
@@ -648,6 +649,7 @@
     "tests/test_drive_queue_max_parallel_per_repo_config.py",
     "tests/test_drive_queue_roll_pending.py",
     "tests/test_drive_queue_self_cordon_escalation.py",
+    "tests/test_drive_sessions_snapshot.py",
     "tests/test_drive_state.py",
     "tests/test_drive_tmux.py",
     "tests/test_epic_up_capability_detection.py",

code_coordinator-0.5.512/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.512",
+  "distance": 0,
+  "node": "g51bbafd70baf84cb0ed6d0a735815b56ea39f604",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-21"
+}

{code_coordinator-0.5.511 → code_coordinator-0.5.512}/coord/board_schema.py

@@ -62,6 +62,11 @@ import typing
 from collections.abc import Mapping
 from typing import Any, Union
 
+# #3428: the `concurrency` block's `occupancy_state` value set — owned by the
+# snapshot module that produces it (see `BoardConcurrency` below).  Safe at
+# module scope: that module imports nothing from `coord` at import time.
+from coord.drive_sessions_snapshot import OCCUPANCY_UNOBSERVED
+
 #: What the read path actually hands the projection.  ``sqlite3.Row`` is *not*
 #: a ``Mapping`` (see :func:`_as_dict`), so it has to be named explicitly.
 RowLike = Union[Mapping[str, Any], sqlite3.Row]
@@ -310,6 +315,236 @@ class BoardDriveQueueEntry:
     apply_verdict_at: float | None = None
 
 
+# ── #3428 (#3408 item 3): concurrency ceilings + provenance + occupancy ──────
+#
+# The three dataclasses below are NOT a table projection — there is no
+# `concurrency` table — so they are absent from `BOARD_PROJECTIONS` and
+# `decode_row()` never touches them. They exist to give the *computed*
+# `coord.drive_queue.CeilingResolution` (already resolved on the daemon host
+# by `coord config --effective`'s own machinery — see that command's
+# docstring) an explicit wire shape, the same way `BoardAssignment` etc. give
+# one to a raw DB row. `coord/serve_app.py`'s `board()` handler builds a
+# `BoardConcurrency` per request (never persisted) and adds it to the
+# `/board` payload as the sibling key ``concurrency`` — same posture as
+# ``roll_pending``/``goal_header``: additive, absent-tolerant, never required.
+#
+# Deliberately does NOT import `coord.drive_queue` at module scope:
+# `coord.drive_queue` transitively imports THIS module (via
+# `coord.merge_queue` -> `coord.state` -> `coord.board_schema`), so a
+# top-level `from coord.drive_queue import CeilingResolution` here would be a
+# real import cycle, not just an ugly one. `CeilingResolution` is referenced
+# only for typing (`from __future__ import annotations` makes the annotation
+# itself lazy) and duck-typed at runtime by :func:`board_ceiling_from_resolution`.
+# (`coord.drive_sessions_snapshot`, which owns the `occupancy_state` value
+# set `BoardConcurrency` below defaults to, is by contrast imported at the
+# TOP of this file: it imports nothing from `coord` at module scope — its own
+# tmux/queue imports are deferred into `refresh()` — so it cannot close a
+# cycle back through here.)
+if typing.TYPE_CHECKING:  # pragma: no cover — typing only
+    from coord.drive_queue import CeilingResolution
+
+
+#: `BoardCeiling.source_kind` / `BoardCeilingSource.source_kind`'s closed
+#: value set (#3428) — a machine-readable classification of
+#: `CeilingResolution.source`'s free-text prose (written for `coord config
+#: --effective`'s human-readable output), so a client can style/filter a
+#: ceiling's provenance without string-matching wording that is free to
+#: change. See :func:`classify_ceiling_source` for the mapping.
+CEILING_SOURCE_KIND_SYSTEMD_FLAG = "systemd_flag"
+CEILING_SOURCE_KIND_CLI_FLAG = "cli_flag"
+CEILING_SOURCE_KIND_COORDINATOR_YML_REPO = "coordinator_yml_repo"
+CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE = "coordinator_yml_pipeline"
+CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY = "coordinator_yml_concurrency"
+CEILING_SOURCE_KIND_DERIVED = "derived"
+CEILING_SOURCE_KIND_DEFAULT = "default"
+#: A `CeilingResolution.source` this classifier doesn't recognise — should
+#: never actually appear on a real `/board` payload (every source string
+#: `coord.drive_queue`'s resolvers produce is covered below), but a client
+#: must still be able to parse it rather than choke: unlike the DTOs above,
+#: `source_kind` degrading to "unknown" is a display nit, not a #632-class
+#: parse failure.
+CEILING_SOURCE_KIND_UNKNOWN = "unknown"
+
+CEILING_SOURCE_KINDS: frozenset[str] = frozenset(
+    {
+        CEILING_SOURCE_KIND_SYSTEMD_FLAG,
+        CEILING_SOURCE_KIND_CLI_FLAG,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_REPO,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY,
+        CEILING_SOURCE_KIND_DERIVED,
+        CEILING_SOURCE_KIND_DEFAULT,
+        CEILING_SOURCE_KIND_UNKNOWN,
+    }
+)
+
+
+def classify_ceiling_source(source: str) -> str:
+    """Map one `CeilingResolution.source` (or one of its `losing` entries'
+    source names) prose string to a :data:`CEILING_SOURCE_KINDS` enum value.
+
+    Ordered by specificity, matching the exact strings
+    `coord.drive_queue`'s resolvers / `coord.commands.setup._print_effective_
+    concurrency` actually construct today:
+
+    * ``"systemd ExecStart --max-parallel..."`` (`read_systemd_max_parallel_
+      flags` via `coord.commands.setup`'s ``per_repo_source``/
+      ``max_parallel_source``) -> ``systemd_flag`` — the #3408 incident
+      source: a machine-local flag a thin client can never see for itself.
+    * ``"--max-parallel[-per-repo] flag"`` (an explicit CLI override on
+      `coord drive-queue tick`'s own invocation) -> ``cli_flag``.
+    * ``"coordinator.yml repos[<name>].max_parallel"`` (#3423 per-repo
+      override) -> ``coordinator_yml_repo``.
+    * ``"coordinator.yml pipeline.max_parallel..."`` -> ``coordinator_yml_pipeline``.
+    * ``"coordinator.yml concurrency.max_workers"`` (this module's own
+      synthetic resolution for the fleet worker cap — see
+      :func:`board_ceiling_from_resolution`'s caller in `coord/serve_app.py`)
+      -> ``coordinator_yml_concurrency``.
+    * ``"derived (...)"`` (`default_max_parallel`'s repo-shape derivation)
+      -> ``derived``.
+    * ``"default (...)"`` (the hardcoded fallback, config unreadable) ->
+      ``default``.
+    * anything else -> ``unknown`` (fail-soft; see that constant's docstring).
+    """
+    if source.startswith("systemd ExecStart"):
+        return CEILING_SOURCE_KIND_SYSTEMD_FLAG
+    if source.startswith("coordinator.yml repos["):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_REPO
+    if source.startswith("coordinator.yml pipeline."):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE
+    if source.startswith("coordinator.yml concurrency."):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY
+    if source.startswith("derived"):
+        return CEILING_SOURCE_KIND_DERIVED
+    if source.startswith("default"):
+        return CEILING_SOURCE_KIND_DEFAULT
+    if source.startswith("--") and source.endswith("flag"):
+        return CEILING_SOURCE_KIND_CLI_FLAG
+    return CEILING_SOURCE_KIND_UNKNOWN
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardCeilingSource:
+    """One LOSING source's own opinion for a :class:`BoardCeiling` (#3428) —
+    the wire twin of one ``(name, value)`` pair in a
+    `coord.drive_queue.CeilingResolution.losing` tuple. This is the whole
+    point of shipping provenance at all: it is what tells an operator that
+    editing ``coordinator.yml``/``coord-settings`` is futile while a
+    machine-local systemd flag outranks it (#3408's reported incident).
+    """
+
+    source: str
+    source_kind: str
+    value: int
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardCeiling:
+    """One resolved concurrency ceiling + provenance (#3428) — the `/board`
+    wire twin of `coord.drive_queue.CeilingResolution`, the exact resolution
+    `coord config --effective` and `coord drive-queue tick` itself already
+    use (#2085 "one question, one answer": this block is never a second,
+    independently-derived answer).
+
+    ``source`` carries the same free-text `CeilingResolution.source` a human
+    reads in `coord config --effective`'s output; ``source_kind`` is the
+    machine-readable classification of it (:func:`classify_ceiling_source`)
+    a client should actually branch on. ``losing`` is ``None`` (not ``[]``)
+    when nothing else was configured, matching `CeilingResolution.losing`'s
+    own "empty means nobody else had an opinion" contract.
+    """
+
+    name: str
+    value: int
+    source: str
+    source_kind: str
+    losing: list[BoardCeilingSource] | None = None
+
+
+def board_ceiling_from_resolution(resolution: "CeilingResolution") -> BoardCeiling:
+    """`coord.drive_queue.CeilingResolution` -> its `/board` wire shape.
+
+    Duck-typed on purpose (reads ``.name``/``.value``/``.source``/``.losing``
+    rather than importing the real class) — see the module note above this
+    section for why `coord.drive_queue` cannot be imported here at runtime.
+    """
+    losing = [
+        BoardCeilingSource(
+            source=name, source_kind=classify_ceiling_source(name), value=value
+        )
+        for name, value in resolution.losing
+    ] or None
+    return BoardCeiling(
+        name=resolution.name,
+        value=resolution.value,
+        source=resolution.source,
+        source_kind=classify_ceiling_source(resolution.source),
+        losing=losing,
+    )
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardConcurrency:
+    """The `/board` payload's ``concurrency`` block (#3428, #3408 item 3):
+    every ceiling `coord drive-queue tick` actually enforces, resolved on
+    THIS (the daemon) host, plus current occupancy against each.
+
+    **Resolved server-side, always** — the systemd-flag source
+    (:data:`CEILING_SOURCE_KIND_SYSTEMD_FLAG`) is machine-local and invisible
+    to a thin client (a Rust TUI, a phone webapp) by construction; a client
+    deriving ceilings from its own cached ``coordinator.yml`` would
+    confidently print the config value while a host-local flag silently
+    outranked it — the exact #3408 failure this block exists to end.
+
+    ``repo_overrides`` carries only the repos whose OWN ``repos[].max_parallel``
+    (#3423) actually differs from ``max_parallel_per_repo``'s fleet-wide
+    value — mirroring `coord.drive_queue.effective_repo_capacities`'s own
+    "only the repos that disagree" trim (see that function's docstring):
+    listing every repo would bury the ones that matter and make an
+    all-default fleet look like something was overridden everywhere.
+
+    ``occupied``/``repo_occupied`` are `coord.drive_queue.
+    compute_running_occupancy`'s own output, verbatim — the SAME "is this
+    entry still occupying a slot" verdict `plan_tick` enforces, never a
+    second, independently-recounted number (#2085 "one question, one
+    answer").
+
+    **Occupancy is nullable, and says why (#2096).** That verdict's first
+    question about a `running` entry is "is its drive session live?", which
+    only a ``tmux list-sessions`` reading can answer — and that reading is a
+    SUBPROCESS, so it is taken on the daemon's tick cadence
+    (`coord.drive_sessions_snapshot`), never inline off this read path (the
+    `/board` invariant 1 that `tests/test_board_read_path.py` enforces). When
+    the daemon has not taken a reading yet, or its refresh loop has stalled
+    (#2862) and the last one is too old to be evidence about now,
+    ``occupied``/``repo_occupied`` are ``None`` and ``occupancy_state`` says
+    which — never a confidently-wrong ``0`` that a client would render as
+    "all slots free". ``occupancy_observed_at`` is the wall-clock moment of
+    the reading behind the numbers (``None`` when there has never been one),
+    so a client can show — and age out — the numbers itself.
+
+    The CEILINGS are unaffected by any of that: they are resolved from
+    config + this host's systemd unit on every build, so they stay populated
+    even when occupancy is unknown.
+
+    Absent-tolerant in both directions (#3428 acceptance): an older daemon
+    simply omits the ``concurrency`` key entirely (never ships it as e.g. an
+    empty object), and a newer client must not require the key to parse an
+    otherwise-valid board.
+    """
+
+    max_parallel: BoardCeiling
+    max_parallel_per_repo: BoardCeiling
+    max_workers: BoardCeiling
+    repo_overrides: dict[str, BoardCeiling]
+    #: ``None`` unless ``occupancy_state`` is
+    #: :data:`~coord.drive_sessions_snapshot.OCCUPANCY_OBSERVED`.
+    occupied: int | None = None
+    repo_occupied: dict[str, int] | None = None
+    #: One of :data:`~coord.drive_sessions_snapshot.OCCUPANCY_STATES`.
+    occupancy_state: str = OCCUPANCY_UNOBSERVED
+    occupancy_observed_at: float | None = None
+
 
 #: ``table name`` → the DTO that defines its ``/board`` wire shape.  These are
 #: exactly the seven projections ``coord/serve_app.py`` publishes under

{code_coordinator-0.5.511 → code_coordinator-0.5.512}/coord/drive_queue.py

@@ -988,6 +988,109 @@ def compute_running_occupancy(
     return occupied, repo_occupied
 
 
+@dataclass(frozen=True)
+class ConcurrencyReport:
+    """Every concurrency ceiling `coord drive-queue tick` enforces, resolved
+    together in the SAME order + SAME primitives ``coord config --effective``
+    (`coord.commands.setup._print_effective_concurrency`) already applies
+    (#3408), plus current occupancy against each — the one call a daemon-host
+    caller should make rather than re-deriving the wiring itself (#3428,
+    #2085 "one question, one answer").
+
+    ``repo_resolutions`` is EVERY repo's own :class:`CeilingResolution`
+    (#3423), keyed by name — :func:`resolve_repo_ceilings`'s full table.
+    ``repo_overrides`` is the trimmed subset that actually differs from
+    ``max_parallel_per_repo``'s fleet-wide value —
+    :func:`effective_repo_capacities`'s own shape, and also what
+    ``max_parallel``'s own resolution is computed against (a repo with no
+    override contributes the fleet figure to that sum, not its own name).
+    """
+
+    max_parallel: CeilingResolution
+    max_parallel_per_repo: CeilingResolution
+    max_workers: CeilingResolution
+    repo_resolutions: dict[str, CeilingResolution]
+    repo_overrides: dict[str, int]
+    occupied: int
+    repo_occupied: dict[str, int]
+
+
+def resolve_concurrency_report(
+    *,
+    repo_overrides: Mapping[str, int | None],
+    pipeline_max_parallel: int | None,
+    pipeline_max_parallel_per_repo: int | None,
+    max_workers_cap: int,
+    systemd_flags: Mapping[str, int] | None = None,
+    entries: Sequence["QueueEntry"] = (),
+    board: "BoardView | None" = None,
+    max_attempts: int = DEFAULT_MAX_ATTEMPTS,
+    now: float | None = None,
+    local_host: str | None = None,
+) -> ConcurrencyReport:
+    """Resolve every concurrency ceiling in one call (#3428).
+
+    *repo_overrides* is ``{repo_name: repos[].max_parallel or None}`` for
+    EVERY repo in the fleet (not just the overridden ones — see
+    :func:`resolve_repo_ceilings`). *systemd_flags* defaults to a fresh
+    :func:`read_systemd_max_parallel_flags` read of THIS machine's own
+    installed unit when not given (a caller with an already-read dict, e.g.
+    a test, passes it explicitly rather than touching the filesystem).
+
+    *board*/*entries* are `compute_running_occupancy`'s own arguments;
+    *board* left ``None`` (the default) skips occupancy entirely
+    (``occupied=0``, ``repo_occupied={}``) rather than raising — a caller
+    that only wants the ceilings (no live queue state) does not need to
+    fabricate an empty :class:`BoardView`.
+    """
+    flags = systemd_flags if systemd_flags is not None else read_systemd_max_parallel_flags()
+
+    per_repo_resolution = resolve_max_parallel_per_repo(
+        override_value=flags.get("max_parallel_per_repo"),
+        override_source="systemd ExecStart --max-parallel-per-repo",
+        config_value=pipeline_max_parallel_per_repo,
+    )
+    repo_resolutions = resolve_repo_ceilings(repo_overrides, fleet=per_repo_resolution)
+    effective_repo_overrides = effective_repo_capacities(
+        repo_resolutions, fleet_value=per_repo_resolution.value
+    )
+
+    global_resolution = resolve_max_parallel(
+        override_value=flags.get("max_parallel"),
+        override_source="systemd ExecStart --max-parallel",
+        config_value=pipeline_max_parallel,
+        repo_count=len(repo_overrides),
+        max_parallel_per_repo=per_repo_resolution.value,
+        max_workers_cap=max_workers_cap,
+        repo_overrides=effective_repo_overrides,
+    )
+    # `concurrency.max_workers` has exactly one source today — nothing can
+    # beat `coordinator.yml`'s own value — but the wire/report shape stays
+    # uniform across all three ceilings (#3428's own contract), so it is
+    # wrapped in the same `CeilingResolution` shape the other two use, with
+    # an always-empty `losing`.
+    max_workers_resolution = CeilingResolution(
+        "max_workers", max_workers_cap, "coordinator.yml concurrency.max_workers"
+    )
+
+    if board is not None:
+        occupied, repo_occupied = compute_running_occupancy(
+            entries, board, max_attempts, now=now, local_host=local_host
+        )
+    else:
+        occupied, repo_occupied = 0, {}
+
+    return ConcurrencyReport(
+        max_parallel=global_resolution,
+        max_parallel_per_repo=per_repo_resolution,
+        max_workers=max_workers_resolution,
+        repo_resolutions=repo_resolutions,
+        repo_overrides=effective_repo_overrides,
+        occupied=occupied,
+        repo_occupied=repo_occupied,
+    )
+
+
 # ── the startup grace window (#1794) ─────────────────────────────────────────
 #
 # A drive is NOT established the instant `coord drive --tmux` exits 0.  #1606's

code_coordinator-0.5.512/coord/drive_sessions_snapshot.py

@@ -0,0 +1,177 @@
+"""Tick-refreshed snapshot of this host's live drive tmux sessions (#3428).
+
+**Invariant 1 of the ``/board`` read path: read endpoints perform no
+third-party I/O** (``coord.gate_snapshot``'s own opening line, and the
+enforcement test ``tests/test_board_read_path.py::
+test_board_read_makes_zero_gh_calls``, which fails the build on *any*
+subprocess spawned while a board is built).
+
+:func:`coord.drive.list_drive_sessions` is a ``tmux list-sessions``
+**subprocess** with a 5 s timeout.  The #3428 ``concurrency`` block needs its
+answer — occupancy is computed by :func:`coord.drive_queue.
+compute_running_occupancy`, whose very first question about a ``running``
+entry is "is its drive session live?" — but calling it inline off the board
+handler would put a process spawn (and, on a wedged tmux server, a 5 s stall)
+on the hottest read path in the daemon, once per cold build.  That is exactly
+the ``gh``-on-``/board`` mechanism of the #762/#715/#1336 timeout-overrun
+class, with tmux swapped in for GitHub.
+
+So the reading moves to the daemon's tick cadence, the same shape
+``GateSnapshotRefresher`` / ``FleetHealthRefresher`` / ``MachineMetricsSampler``
+already use: :meth:`DriveSessionsRefresher.refresh` (tick side, the ONLY
+subprocess) publishes an immutable :class:`DriveSessionsSnapshot`, and the
+board handler consumes the last one published with a bare attribute read.
+
+**The snapshot states its own freshness, and "I did not observe this" is a
+reachable verdict (#2096).**  An occupancy count is only as true as the
+session reading behind it, and *two* real conditions leave that reading
+absent rather than merely empty:
+
+* the daemon has not taken one yet — a just-restarted ``coord serve``, or a
+  deployment with the refresh loop disabled (``COORD_DRIVE_SESSIONS_REFRESH_
+  INTERVAL=0``); and
+* the refresh loop stopped — the bare ``asyncio.create_task`` loops in
+  ``coord/serve_app.py`` have no supervisor (#2862), so a loop that dies
+  stays dead until the daemon restarts, and its last snapshot would otherwise
+  keep being served as current forever.
+
+In both cases occupancy is reported as ``None`` with an
+:data:`OCCUPANCY_STATES` label saying which, never as a confidently-wrong
+``0``.  A "0 of 4 slots in use" that actually meant "nobody looked" is the
+same defect class as a green gate that only proves the request was issued.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+#: How old the last reading may be before it stops counting as current.
+#: Deliberately several multiples of the daemon's default refresh cadence
+#: (``COORD_DRIVE_SESSIONS_REFRESH_INTERVAL``, 15 s) so an ordinary slow tick
+#: — or one pass that lost its race with a 5 s ``tmux`` timeout — does not
+#: flap the label, while a loop that has genuinely stopped (#2862) crosses it
+#: within a minute.
+STALE_AFTER_SECONDS = 90.0
+
+#: A reading was taken within :data:`STALE_AFTER_SECONDS` — the occupancy
+#: numbers built from it are current.
+OCCUPANCY_OBSERVED = "observed"
+#: No reading has EVER been taken by this daemon (fresh start, or the refresh
+#: loop is disabled).  Occupancy is unknown, not zero.
+OCCUPANCY_UNOBSERVED = "unobserved"
+#: A reading was taken, but too long ago to be evidence about now — the
+#: refresh loop has stalled or died.  Occupancy is unknown, not last-known.
+OCCUPANCY_STALE = "stale"
+
+#: The closed value set for the ``/board`` ``concurrency.occupancy_state``
+#: field (#3428).  Only :data:`OCCUPANCY_OBSERVED` carries numbers.
+OCCUPANCY_STATES: frozenset[str] = frozenset(
+    {OCCUPANCY_OBSERVED, OCCUPANCY_UNOBSERVED, OCCUPANCY_STALE}
+)
+
+
+@dataclass(frozen=True)
+class DriveSessionsSnapshot:
+    """One immutable reading of this host's live ``coord-drive-*`` sessions.
+
+    *keys* are ``coord.drive_queue.entry_key`` strings (``"repo#N"``) —
+    exactly what :func:`coord.drive_queue.build_board_view` accepts as its
+    ``live_sessions`` argument, so the board's occupancy is computed from the
+    identical input ``coord drive-queue tick`` feeds it.
+
+    *observed_at* is the wall-clock (``time.time()``) moment the reading was
+    taken, or ``None`` for the never-refreshed default — the distinction
+    :meth:`state` turns into a label.  Wall-clock rather than monotonic on
+    purpose: it is also carried on the wire so a client can show how old the
+    numbers are.
+    """
+
+    keys: frozenset[str] = field(default_factory=frozenset)
+    observed_at: float | None = None
+
+    def state(
+        self,
+        *,
+        now: float | None = None,
+        stale_after: float = STALE_AFTER_SECONDS,
+    ) -> str:
+        """This snapshot's freshness as one of :data:`OCCUPANCY_STATES`."""
+        if self.observed_at is None:
+            return OCCUPANCY_UNOBSERVED
+        age = (time.time() if now is None else now) - self.observed_at
+        if age > stale_after:
+            return OCCUPANCY_STALE
+        return OCCUPANCY_OBSERVED
+
+    def is_current(
+        self,
+        *,
+        now: float | None = None,
+        stale_after: float = STALE_AFTER_SECONDS,
+    ) -> bool:
+        """Whether occupancy derived from this snapshot may be reported as a
+        number at all (``state() == OCCUPANCY_OBSERVED``)."""
+        return self.state(now=now, stale_after=stale_after) == OCCUPANCY_OBSERVED
+
+
+class DriveSessionsRefresher:
+    """Owns the current :class:`DriveSessionsSnapshot`; refreshed by the tick.
+
+    :meth:`snapshot` is what the read path consumes — a bare attribute read
+    (atomic under CPython), never I/O.  :meth:`refresh` is the only method
+    that spawns ``tmux`` and must only ever run from the daemon's tick
+    machinery (or a test driving it explicitly).
+    """
+
+    def __init__(self, initial: DriveSessionsSnapshot | None = None) -> None:
+        """*initial* seeds the published snapshot — for tests that need a
+        specific freshness (a reading from 20 minutes ago, say) without
+        waiting on a real tick or spawning ``tmux``.  Production callers
+        omit it and get the never-refreshed default, whose
+        :meth:`DriveSessionsSnapshot.state` is
+        :data:`OCCUPANCY_UNOBSERVED`."""
+        self._snapshot = initial if initial is not None else DriveSessionsSnapshot()
+
+    def snapshot(self) -> DriveSessionsSnapshot:
+        return self._snapshot
+
+    # ── the tick-side refresh (the ONLY subprocess) ─────────────────────────
+    def refresh(self) -> DriveSessionsSnapshot:
+        """Take one ``tmux list-sessions`` reading and publish it.
+
+        Reads through :func:`coord.drive.list_drive_sessions` rather than
+        re-implementing the tmux call, so the board's notion of "which drives
+        are live" is literally the same function ``coord drive-queue tick``
+        consults before deciding whether a slot is occupied (#2085 "one
+        question, one answer") — including its own fail-soft contract, where
+        an unavailable tmux and a genuinely idle host both read as "no live
+        sessions".
+
+        Raises nothing of its own; a failure inside ``list_drive_sessions``
+        propagates to the caller's loop (which logs and keeps serving the
+        PREVIOUS snapshot, which then ages into :data:`OCCUPANCY_STALE` on
+        its own if the failures persist).  Publishes only after the read
+        returned — a pass that raised must never stamp a fresh
+        ``observed_at`` on data nobody actually observed.
+        """
+        from coord.drive import list_drive_sessions  # noqa: PLC0415
+        from coord.drive_queue import entry_key  # noqa: PLC0415
+
+        rows: list[dict[str, Any]] = list_drive_sessions()
+        keys: set[str] = set()
+        for row in rows:
+            repo = row.get("repo") or ""
+            number = row.get("issue")
+            if not repo or number is None:
+                continue
+            try:
+                keys.add(entry_key(repo, int(number)))
+            except (TypeError, ValueError):
+                continue
+        snapshot = DriveSessionsSnapshot(
+            keys=frozenset(keys), observed_at=time.time()
+        )
+        self._snapshot = snapshot
+        return snapshot