code-coordinator 0.5.315__tar.gz → 0.5.317__tar.gz

{code_coordinator-0.5.315 → code_coordinator-0.5.317}/PKG-INFO

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

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

@@ -126,6 +126,7 @@ coord/release_cordon.py
 coord/release_propagate.py
 coord/release_verify.py
 coord/release_window.py
+coord/repo_dormancy.py
 coord/repo_edit.py
 coord/repo_onboard.py
 coord/reports.py
@@ -706,6 +707,7 @@ tests/test_release_window.py
 tests/test_remote_auto_prune.py
 tests/test_remote_interactive_reaper.py
 tests/test_repo_add.py
+tests/test_repo_dormancy.py
 tests/test_repo_edit_2220.py
 tests/test_repo_graph_fleet_2237.py
 tests/test_repo_onboard_2220.py

{code_coordinator-0.5.315 → code_coordinator-0.5.317}/code_coordinator.egg-info/scm_file_list.json

@@ -231,6 +231,7 @@
     "coord/release_propagate.py",
     "coord/release_verify.py",
     "coord/release_window.py",
+    "coord/repo_dormancy.py",
     "coord/repo_edit.py",
     "coord/repo_onboard.py",
     "coord/reports.py",
@@ -732,6 +733,7 @@
     "tests/test_remote_auto_prune.py",
     "tests/test_remote_interactive_reaper.py",
     "tests/test_repo_add.py",
+    "tests/test_repo_dormancy.py",
     "tests/test_repo_edit_2220.py",
     "tests/test_repo_graph_fleet_2237.py",
     "tests/test_repo_onboard_2220.py",

{code_coordinator-0.5.315 → code_coordinator-0.5.317}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.315",
+  "tag": "0.5.317",
   "distance": 0,
-  "node": "g12da3c4a4320f19ffd6f46fd6eb6b882a5ba5026",
+  "node": "gf4f544e9955eaa18600b99dd2e5c9c0cc421e7e4",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-31"

{code_coordinator-0.5.315 → code_coordinator-0.5.317}/coord/github_ops.py

@@ -1892,7 +1892,9 @@ def list_remote_branch_names(repo: str) -> set[str]:
     }
 
 
-def branch_exists_on_remote(repo: str, branch: str) -> bool:
+def branch_exists_on_remote(
+    repo: str, branch: str, *, cache: dict | None = None
+) -> bool:
     """Return True if `branch` currently exists on `repo` (owner/name) at GitHub.
 
     Uses a targeted ``gh api`` call rather than listing all branches.  Fails
@@ -1903,7 +1905,27 @@ def branch_exists_on_remote(repo: str, branch: str) -> bool:
 
     Called by ``dispatch_review`` and ``_dispatch_fix`` (#586) to avoid
     routing a follow-on assignment to a machine that can't fetch the branch.
-    """
+
+    *cache* (#2989) is an optional caller-owned ``dict`` used to memoise the
+    lookup for the duration of ONE sweep, mirroring
+    :func:`work_is_terminal`'s ``cache=``.  A single ``reconcile_board_merges``
+    pass measured 1,304 ref lookups for only 851 distinct refs (1.53x
+    redundancy) because sibling assignment rows — a work row and its
+    conflict-fix, or a re-dispatch — legitimately share one branch.  The
+    cache is deliberately **per-pass and caller-scoped**, never module-level:
+    branch existence is exactly the kind of fact that must be re-read on the
+    next pass.
+    """
+    key = (repo, branch)
+    if cache is not None and key in cache:
+        return cache[key]
+    result = _branch_exists_on_remote_uncached(repo, branch)
+    if cache is not None:
+        cache[key] = result
+    return result
+
+
+def _branch_exists_on_remote_uncached(repo: str, branch: str) -> bool:
     try:
         _gh("api", f"repos/{repo}/git/refs/heads/{branch}",
             caller="github_ops.branch_exists_on_remote")

{code_coordinator-0.5.315 → code_coordinator-0.5.317}/coord/reconcile.py

@@ -31,6 +31,23 @@ if TYPE_CHECKING:
 # and treating a huge, all-matching-so-far diff as inconclusive (fail open).
 _FALSE_MERGE_AUDIT_MAX_FILES = 20
 
+# #2989: bounds the OUTER candidate set of that same sweep — the loop #2639
+# left unbounded. Without it the set is proportional to project history
+# (1,302 rows on the drive host, +1 per merge, never shrinking), re-probed
+# every 30s. This is a per-pass ceiling applied newest-first as a backstop
+# behind the persistent terminal marker (`state.mark_false_merge_audit_
+# clean`); the older tail drains over subsequent passes as newer rows are
+# confirmed and drop out permanently. Not applied to a targeted
+# `--issue N` audit.
+_FALSE_MERGE_AUDIT_MAX_ROWS = 50
+
+# #2989: how often the sweep may run when the caller opts into throttling
+# (the daemon's reconcile tick does; a manual `coord reconcile-merges` does
+# not). It detects a rare, non-urgent condition — a merged-marked row whose
+# branch still differs from base — which is an hourly sweep, not a
+# twice-a-minute one.
+_FALSE_MERGE_AUDIT_MIN_INTERVAL_SECONDS = 3600.0
+
 
 def _query_agent(host: str, port: int = AGENT_PORT, timeout: float = 5.0) -> dict | None:
     try:
@@ -2774,9 +2791,11 @@ def _extract_issue_number(branch: str) -> int | None:
 def close_stale_prs(
     config: Config,
     *,
+    board: Board | None = None,
     repo: str | None = None,
     issue: int | None = None,
     dry_run: bool = False,
+    skip_dormant_repos: bool = False,
 ) -> list[str]:
     """Close open PRs whose work is already on main or whose issue is closed.
 
@@ -2791,15 +2810,46 @@ def close_stale_prs(
 
     Stale PRs are closed with an explanatory comment.  Non-stale PRs are left
     untouched.  *dry_run* lists what would change without writing.  Idempotent.
+
+    #2994: when *skip_dormant_repos* is set (the daemon tick's opt-in — see
+    ``coord.serve_app._reconcile_merges_tick``; a manual ``coord
+    reconcile-merges`` leaves this False), a repo with no open assignment, no
+    drive-queue entry, and no coord-authored open PR (``coord.repo_dormancy.
+    should_skip_sweep``) is skipped this call rather than costing a
+    ``list_open_prs`` call — bounded by ``coord.repo_dormancy.
+    DORMANT_SWEEP_FLOOR_S`` so it's still swept eventually. Requires *board*
+    to evaluate; with *board* left ``None`` this is a no-op regardless of
+    *skip_dormant_repos* (no activity signal to check against, so never
+    skip).
+
+    Note: the floor is recorded as soon as a repo is deemed due, before
+    ``list_open_prs`` is even attempted, and it stays recorded if that call
+    then raises (deliberate — see ``coord.repo_dormancy.record_swept``'s
+    docstring: it tracks "a real gh call was spent", not "and it worked").
+    One operator-facing consequence: a repo that is persistently failing
+    (renamed, deleted, secondary-rate-limited) goes quiet for up to
+    ``DORMANT_SWEEP_FLOOR_S`` between retries rather than being retried
+    sooner, same as a genuinely idle repo would be.
     """
     from coord import github_ops  # noqa: PLC0415
 
     actions: list[str] = []
+    dormant_skipped = 0
 
     for repo_cfg in config.repos:
         if repo is not None and repo_cfg.name != repo:
             continue
 
+        if skip_dormant_repos and board is not None:
+            from coord import repo_dormancy  # noqa: PLC0415
+
+            if repo_dormancy.should_skip_sweep(
+                repo_cfg.name, board, repo_dormancy.KIND_PRS
+            ):
+                dormant_skipped += 1
+                continue
+            repo_dormancy.record_swept(repo_cfg.name, repo_dormancy.KIND_PRS)
+
         try:
             open_prs = github_ops.list_open_prs(repo_cfg.github)
         except Exception as exc:  # noqa: BLE001
@@ -2874,6 +2924,14 @@ def close_stale_prs(
                 except Exception as exc:  # noqa: BLE001
                     actions.append(f"  ↳ error closing PR #{pr_number}: {exc}")
 
+    if dormant_skipped:
+        # #2994: one aggregate line rather than one per repo — visible
+        # without being noisy on a fleet with many idle repos.
+        actions.append(
+            f"stale-PR sweep: skipped {dormant_skipped} dormant repo(s) "
+            "(no open assignment, drive-queue entry, or open PR)"
+        )
+
     return actions
 
 
@@ -2908,6 +2966,8 @@ def reconcile_board_merges(
     repo: str | None = None,
     issue: int | None = None,
     dry_run: bool = False,
+    throttle_false_merge_audit: bool = False,
+    skip_dormant_repos: bool = False,
 ) -> list[str]:
     """Reconcile done work assignments against git/GitHub reality.
 
@@ -2970,7 +3030,20 @@ def reconcile_board_merges(
     catching a historical false ``status='merged'`` flip that predates this
     fix (or any future bug shaped like it) rather than leaving it invisible
     to every other diagnostic forever. See its own inline comment for the
-    full methodology and false-positive guards.)
+    full methodology and false-positive guards.
+
+    #2989 bounds sweep (h)'s candidate set — it used to select every
+    ``merged`` work-like row in project history and re-probe all of them on
+    the daemon's 30s tick (97% of a pass's ``gh`` calls). Set
+    *throttle_false_merge_audit* to run that sweep at most hourly; the
+    daemon tick does, a manual ``coord reconcile-merges`` deliberately does
+    not. See the inline block above ``_false_merge_candidates``.
+
+    #2994: *skip_dormant_repos* (also daemon-tick-only, also off for a
+    manual ``coord reconcile-merges``) is threaded through to sweep (c),
+    :func:`close_stale_prs` — see its own docstring — so a repo with no open
+    assignment, no drive-queue entry, and no coord-authored open PR doesn't
+    cost a ``list_open_prs`` call on every tick either.)
     """
     from coord import github_ops, state  # noqa: PLC0415
 
@@ -3114,7 +3187,16 @@ def reconcile_board_merges(
                     state.mark_work_review_settled(a.assignment_id or "")
 
     # (c) #721 — close open PRs whose work has already landed.
-    actions.extend(close_stale_prs(config, repo=repo, issue=issue, dry_run=dry_run))
+    actions.extend(
+        close_stale_prs(
+            config,
+            board=board,
+            repo=repo,
+            issue=issue,
+            dry_run=dry_run,
+            skip_dormant_repos=skip_dormant_repos,
+        )
+    )
 
     # (d) #732 — prune stale merge_queue entries for closed issues / merged PRs.
     # Runs after the board sweeps so a just-marked-merged assignment doesn't
@@ -3456,28 +3538,121 @@ def reconcile_board_merges(
     # this is a FLAG for a human to check, exactly like the manual sweep this
     # automates, not a verdict. Fail-open at every layer: any fetch failure
     # skips that row/file rather than either flagging or clearing it.
-    _false_merge_candidates = [
-        a
-        for a in board.active + board.completed
-        if a.status == "merged"
-        and a.branch
-        and (a.type in WORK_LIKE_TYPES or is_interactive_merge_session(a))
-        and (repo is None or a.repo_name == repo)
-        and (issue is None or a.issue_number == issue)
-    ]
+    #
+    # BOUNDING (#2989) — three mechanisms, applied in this order.  Before
+    # them this sweep selected EVERY `merged` work-like row in the board:
+    # 1,302 rows on the drive host, proportional to project history rather
+    # than to work in flight, re-probed on the daemon's 30s tick.  Measured,
+    # that was 1,304 of one pass's 1,346 `gh` invocations (97%), and the
+    # generator behind the fleet-wide secondary rate limiting #2809/#2858/
+    # #2934/#2977 all treated symptomatically.  (#2639 had already capped
+    # the inner per-file loop — the wrong loop; the outer candidate set was
+    # left unbounded.)
+    #
+    #   (1) CADENCE.  This detects a rare, non-urgent condition — a
+    #       merged-marked row whose branch still differs from base, which is
+    #       recovered by a human days later regardless.  Twice a minute is
+    #       absurd for that.  The daemon tick passes
+    #       `throttle_false_merge_audit=True` and the sweep then runs at most
+    #       once an hour (~120x fewer passes on its own).  A manual `coord
+    #       reconcile-merges` / `coord diagnose` never throttles: an operator
+    #       who asked for a sweep gets one, deterministically.
+    #   (2) TERMINAL MARKER.  A clean verdict is clean forever (branch
+    #       deleted, merged PR at the tip, already an ancestor of base, or
+    #       content byte-identical on base — none of those un-happen for a
+    #       terminal row).  Persisting it (`state.mark_false_merge_audit_
+    #       clean`) drops the row from the candidate list permanently, which
+    #       makes the set proportional to *unaudited* merges — bounded by
+    #       recent throughput, not project age.  This is the real fix, and
+    #       the same discipline `coord.gate_snapshot`'s refresh already
+    #       states ("merged history is never refreshed").
+    #   (3) RECENCY CAP.  A backstop for the first pass after this ships (and
+    #       for any board whose marker was lost): audit at most
+    #       `_FALSE_MERGE_AUDIT_MAX_ROWS` rows per pass, newest first.  A
+    #       false merge that has gone unnoticed for two months is not being
+    #       caught by a 30-second sweep anyway; the older tail is simply
+    #       drained over the following passes as newer rows get marked.
+    #
+    # An explicit `--issue N` bypasses (2) and (3) entirely: a targeted
+    # re-audit must always re-probe, so a previously-cleared row stays
+    # re-checkable by hand.  Nothing here changes what the sweep CONCLUDES,
+    # only how many probes it takes to conclude it.
+    _false_merge_targeted = issue is not None
+    _run_false_merge_audit = True
+    if throttle_false_merge_audit and not _false_merge_targeted:
+        _last_run = state.get_false_merge_audit_last_run()
+        if (time.time() - _last_run) < _FALSE_MERGE_AUDIT_MIN_INTERVAL_SECONDS:
+            _run_false_merge_audit = False
+
+    _false_merge_candidates: list[Assignment] = []
+    if _run_false_merge_audit:
+        _false_merge_candidates = [
+            a
+            for a in board.active + board.completed
+            if a.status == "merged"
+            and a.branch
+            and (a.type in WORK_LIKE_TYPES or is_interactive_merge_session(a))
+            and (repo is None or a.repo_name == repo)
+            and (issue is None or a.issue_number == issue)
+            # #2989: a row whose repo has no GitHub mapping is unprobeable —
+            # drop it HERE rather than after the recency cap, so a pile of
+            # orphaned rows (a repo since removed from coordinator.yml) can't
+            # eat the cap's slots and starve the rows we can actually audit.
+            and getattr(config.repo(a.repo_name), "github", None)
+        ]
+        if not _false_merge_targeted:
+            _already_clean = state.load_false_merge_audit_clean()
+            if _already_clean:
+                _false_merge_candidates = [
+                    a
+                    for a in _false_merge_candidates
+                    if a.assignment_id not in _already_clean
+                ]
+            if len(_false_merge_candidates) > _FALSE_MERGE_AUDIT_MAX_ROWS:
+                _false_merge_candidates.sort(
+                    key=lambda a: (a.finished_at or a.dispatched_at or 0.0),
+                    reverse=True,
+                )
+                _false_merge_candidates = _false_merge_candidates[
+                    :_FALSE_MERGE_AUDIT_MAX_ROWS
+                ]
+
+    if (
+        _run_false_merge_audit
+        and throttle_false_merge_audit
+        and not _false_merge_targeted
+        and not dry_run  # a dry-run must not consume the real run's turn
+    ):
+        # Stamp even when there was nothing to do — the point of the stamp is
+        # "this sweep had its turn this hour", not "this sweep found work".
+        state.set_false_merge_audit_last_run(time.time())
+
     if _false_merge_candidates:
         from coord.branch_model import resolve_base_branch_for_issue_number  # noqa: PLC0415
 
         _false_merge_milestone_cache: dict = {}
+        # #2989 mechanism (3'): one ref lookup per DISTINCT (repo, branch)
+        # per pass, not one per row.  Sibling rows legitimately share a
+        # branch (a work row and its conflict-fix, a re-dispatch), which
+        # measured 1.53x redundancy — ~453 wasted calls in a single pass.
+        _false_merge_branch_cache: dict = {}
+        _false_merge_confirmed_clean: list[str] = []
         for a in _false_merge_candidates:
             repo_cfg = config.repo(a.repo_name)
             if repo_cfg is None or not repo_cfg.github:
                 continue
             try:
-                if not github_ops.branch_exists_on_remote(repo_cfg.github, a.branch):
-                    continue  # branch gone — presumed genuinely merged + cleaned up
+                if not github_ops.branch_exists_on_remote(
+                    repo_cfg.github, a.branch, cache=_false_merge_branch_cache
+                ):
+                    # branch gone — presumed genuinely merged + cleaned up,
+                    # and permanently so (#2989).
+                    _false_merge_confirmed_clean.append(a.assignment_id)
+                    continue
                 if github_ops.pr_is_merged(repo_cfg.github, a.branch):
-                    continue  # correctly tracked: a merged PR sits at this exact tip
+                    # correctly tracked: a merged PR sits at this exact tip
+                    _false_merge_confirmed_clean.append(a.assignment_id)
+                    continue
                 base_branch = resolve_base_branch_for_issue_number(
                     repo_cfg,
                     repo_cfg.github,
@@ -3487,13 +3662,20 @@ def reconcile_board_merges(
                 ahead = github_ops.branch_commits_ahead(
                     repo_cfg.github, base_branch, a.branch
                 )
-                if not ahead:  # None (fail-open) or 0 (already an ancestor)
+                if ahead is None:
+                    # fail-open: the probe itself failed, so this row is NOT
+                    # confirmed clean — re-probe it next pass (#2989).
+                    continue
+                if ahead == 0:
+                    # already an ancestor of base: its content landed, and
+                    # that is permanent (#2989).
+                    _false_merge_confirmed_clean.append(a.assignment_id)
                     continue
                 changed_files = github_ops.get_compare_files(
                     repo_cfg.github, base_branch, a.branch
                 )
                 if not changed_files:
-                    continue  # can't confirm anything — fail open
+                    continue  # can't confirm anything — fail open, re-probe
                 content_differs = False
                 differing_path = None
                 for _path in changed_files[:_FALSE_MERGE_AUDIT_MAX_FILES]:
@@ -3514,7 +3696,10 @@ def reconcile_board_merges(
                         differing_path = _path
                         break
                 if not content_differs:
-                    continue  # verbatim on base already — rebase/squash, not lost
+                    # verbatim on base already — rebase/squash, not lost, and
+                    # a terminal row's content cannot un-land (#2989).
+                    _false_merge_confirmed_clean.append(a.assignment_id)
+                    continue
                 actions.append(
                     f"POSSIBLY LOST (#2639): {a.assignment_id} "
                     f"({a.repo_name} #{a.issue_number}, branch={a.branch}) is "
@@ -3535,4 +3720,10 @@ def reconcile_board_merges(
                     f"({a.repo_name} #{a.issue_number}): {exc}"
                 )
 
+        # #2989: persist the terminal marker once, at the end of the sweep —
+        # one board_meta write per pass, not one per row.  Never on a
+        # dry-run: `--dry-run` must not change what the next real pass does.
+        if _false_merge_confirmed_clean and not dry_run:
+            state.mark_false_merge_audit_clean(_false_merge_confirmed_clean)
+
     return actions

code_coordinator-0.5.317/coord/repo_dormancy.py

@@ -0,0 +1,225 @@
+"""Per-repo dormancy skip for the daemon's periodic GitHub sweeps (#2994).
+
+**The problem this closes.** Two of the daemon's slow-cadence ticks —
+``coord.serve_app._sync_issues_tick`` and the stale-PR sweep inside
+``coord.reconcile.close_stale_prs`` (driven by ``_reconcile_merges_tick``) —
+loop over *every registered repo, unconditionally, every tick* and spend a
+``gh`` call (or two) on each. GitHub call volume this way scales with how
+many repos have ever been registered, not with how much work is actually in
+flight: a repo nobody has touched in months costs exactly as much per tick
+as a repo mid-pipeline.
+
+**This module's job.** A repo counts as dormant when it has no open
+assignment, no drive-queue entry, and no coord-authored open PR — see
+:func:`repo_has_activity`, computed live from in-memory board state plus a
+local (non-GitHub) drive-queue read, never cached. Because it is live, the
+instant work is queued for a dormant repo the very next tick sees it as
+active again — there is no separate "wake" call to remember to make.
+
+A dormant repo is not *permanently* skipped, only skipped until
+:data:`DORMANT_SWEEP_FLOOR_S` has passed since its last real sweep — a
+floor, not a wall — so out-of-band activity (a human-opened PR, an issue
+filed by someone who isn't coord) is still noticed eventually even though
+nothing coord-side would otherwise prompt a look. Same best-effort,
+JSON-backed, never-raises shape as the sibling starvation-floor tracker
+:mod:`coord.issues_sync_status` established for exactly this kind of
+bookkeeping — one file, one dict, no new persistence layer.
+
+**Two independent sweep kinds, two independent floors (#2994 review).**
+``_sync_issues_tick`` (issues-sync, ``gh issue list``) and
+``close_stale_prs`` (stale-PR sweep, ``gh pr list``) both call this module
+for the *same repo* in the same daemon tick, one right after the other
+(``_tick_loop``). They are unrelated ``gh`` calls that happen to run
+back-to-back — if they shared one ``{repo_name: last_swept_at}`` clock,
+whichever tick ran first would refresh it before the second ever saw a
+stale-enough value, permanently starving the loser. So every entry point
+takes a mandatory ``kind`` (a short tag like ``"issues"`` or ``"prs"``) and
+the on-disk state is keyed by ``f"{repo_name}:{kind}"`` — same file, two
+disjoint sets of keys, each consumer only ever reads/writes its own.
+
+Both consumers follow the same two-call contract:
+
+* :func:`should_skip_sweep` before spending the real ``gh`` call — True
+  means skip this repo this tick.
+* :func:`record_swept` right after deciding *not* to skip (regardless of
+  whether the sweep itself succeeded) — resets the floor timer.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from coord.platform_paths import default_coord_dir
+
+if TYPE_CHECKING:
+    from coord.models import Board
+
+_log = logging.getLogger(__name__)
+
+_STATE_FILENAME = "repo_dormancy_status.json"
+
+# How long a genuinely-idle repo may go without a real sweep before the next
+# tick forces one anyway, so out-of-band activity is still noticed within a
+# bounded window rather than never. Comfortably above the default 300s tick
+# cadence (COORD_RECONCILE_MERGES_INTERVAL) so an idle repo actually saves
+# calls on most ticks, short enough that "eventually" reads as "within the
+# hour" to an operator rather than "whenever someone notices."
+DORMANT_SWEEP_FLOOR_S = 3600.0
+
+# Sweep-kind tags (#2994 review): each gets its own floor timer, keyed by
+# f"{repo_name}:{kind}" on disk, so the issues-sync tick and the stale-PR
+# sweep never clobber each other's clock even when they run back-to-back
+# for the same repo in the same tick (`_tick_loop`).
+KIND_ISSUES = "issues"
+KIND_PRS = "prs"
+
+
+def _state_path() -> Path:
+    """Resolve the dormancy state file path.
+
+    ``$COORD_REPO_DORMANCY_STATE`` overrides first — same seam
+    ``coord.issues_sync_status._state_path`` documents: lets a test redirect
+    this with a one-line ``monkeypatch.setenv`` instead of risking a stray
+    write into the operator's real ``~/.coord``.
+    """
+    override = os.environ.get("COORD_REPO_DORMANCY_STATE")
+    if override:
+        return Path(override).expanduser()
+    return default_coord_dir() / _STATE_FILENAME
+
+
+def _read_all() -> dict[str, float]:
+    path = _state_path()
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: float(v) for k, v in data.items() if isinstance(v, (int, float))}
+
+
+def _write_all(data: dict[str, float]) -> None:
+    try:
+        path = _state_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(
+            prefix=".repo_dormancy.", suffix=".tmp", dir=path.parent
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(data, fh, sort_keys=True)
+                fh.write("\n")
+            os.replace(tmp, path)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception as exc:  # noqa: BLE001 -- best-effort, never raises
+        _log.debug("repo_dormancy: write failed: %s", exc)
+
+
+def _key(repo_name: str, kind: str) -> str:
+    return f"{repo_name}:{kind}"
+
+
+def record_swept(repo_name: str, kind: str, *, now: float | None = None) -> None:
+    """Best-effort: stamp *repo_name*'s *kind* sweep as having run just now.
+
+    *kind* is a short tag identifying which independent sweep this is (e.g.
+    ``"issues"`` for the issues-sync tick, ``"prs"`` for the stale-PR sweep)
+    — each gets its own floor timer, keyed by ``f"{repo_name}:{kind}"``, so
+    the two sweeps never clobber each other's clock.
+
+    Called right after a tick decides NOT to skip a repo — regardless of
+    whether the sweep itself goes on to succeed or fail — so the floor timer
+    reflects "a real gh call was spent on this repo", not "and it worked".
+    """
+    now = now if now is not None else time.time()
+    data = _read_all()
+    data[_key(repo_name, kind)] = now
+    _write_all(data)
+
+
+def _last_swept_at(repo_name: str, kind: str) -> float | None:
+    return _read_all().get(_key(repo_name, kind))
+
+
+def repo_has_activity(repo_name: str, board: Board) -> bool:
+    """True when *repo_name* is NOT idle: an open assignment, a
+    coord-authored open PR, or a drive-queue entry.
+
+    * "Open assignment" — anything in ``board.active`` for this repo
+      (pending or running work/review/smoke/conflict-fix sessions).
+    * "Coord-authored open PR" — a ``board.completed`` row for this repo
+      still sitting at ``status == 'done'`` (landed, PR presumably open,
+      not yet flipped to ``'merged'``) — this is tracked locally already
+      (it's exactly what the merge-reconcile sweeps exist to resolve), so
+      no extra GitHub call is needed to answer this half of the question.
+    * "Drive-queue entry" — a local (non-GitHub) DB read via
+      :func:`coord.state.list_drive_queue`.
+
+    Deliberately fails OPEN on a drive-queue read error: a repo we can't
+    positively confirm is idle is treated as active, never skipped.
+    """
+    for a in board.active:
+        if a.repo_name == repo_name:
+            return True
+    for a in board.completed:
+        if a.repo_name == repo_name and a.status == "done":
+            return True
+
+    from coord import state  # noqa: PLC0415 -- avoid a state<->reconcile import cycle
+
+    try:
+        if state.list_drive_queue(repo_name):
+            return True
+    except Exception:  # noqa: BLE001 -- best-effort; treat as active on doubt
+        return True
+
+    return False
+
+
+def should_skip_sweep(
+    repo_name: str, board: Board, kind: str, *, now: float | None = None
+) -> bool:
+    """True when this tick should skip *repo_name*'s *kind* GitHub sweep.
+
+    *kind* must match the tag the corresponding :func:`record_swept` call
+    uses (``"issues"`` vs. ``"prs"``) — the two sweeps are independent
+    ``gh`` call types with independent floors; see the module docstring for
+    why they must not share one clock.
+
+    Only ever True for a repo with zero activity (see
+    :func:`repo_has_activity`) that was also swept for real inside
+    :data:`DORMANT_SWEEP_FLOOR_S`. A repo with no recorded sweep at all
+    counts as due, not skippable — there is no prior sweep to protect, and a
+    freshly-registered repo should get its first real sweep immediately.
+    """
+    if repo_has_activity(repo_name, board):
+        return False
+    last = _last_swept_at(repo_name, kind)
+    if last is None:
+        return False
+    now = now if now is not None else time.time()
+    return (now - last) < DORMANT_SWEEP_FLOOR_S
+
+
+def clear() -> None:
+    """Drop all recorded sweep timestamps. Best-effort; never raises. Tests only."""
+    try:
+        _state_path().unlink()
+    except OSError:
+        pass