code-coordinator 0.5.195__tar.gz → 0.5.197__tar.gz

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/.github/workflows/test.yml

@@ -153,6 +153,39 @@ jobs:
       # gated separately through the #2164 CI wrapper.
       - run: scripts/run_tests_without_gh.sh python -m pytest tests/ -q --ignore=tests/acceptance
 
+  # #2135 (child of epic #1902): "every `gh` argv construction lives inside
+  # coord/github_ops.py" is the load-bearing assumption under the #1902
+  # forge-portability cost estimate — it's the fact that makes the eventual
+  # port a refactor instead of a rewrite. #1483 already guarded direct
+  # call-argument leaks with an AST scan (formerly
+  # tests/test_no_direct_gh_calls.py), but that walk missed the
+  # variable-indirection shape (`cmd = ["gh", ...]; subprocess.run(cmd)`).
+  # This job's dedicated regex scan catches that gap too, so
+  # test_no_direct_gh_calls.py was retired in its favor rather than kept
+  # running alongside it as a second, disagreeing implementation of the
+  # same invariant (#2135 review) — see scripts/check_gh_argv_containment.py's
+  # module docstring for the full reconciliation.
+  #
+  # scripts/check_gh_argv_containment.py scans coord/**/*.py for a bare
+  # `"gh"`/`'gh'` token outside coord/github_ops.py, with one explicit,
+  # commented allowlist entry for coord/prereqs.py's binary-version probe
+  # (it checks `gh` is installed; it doesn't drive the forge). See that
+  # script's module docstring for the full rationale and
+  # tests/test_check_gh_argv_containment.py for the negative-test proof
+  # that the guard can actually fail.
+  #
+  # Stdlib-only (re/pathlib/dataclasses), so no `pip install` needed here —
+  # this is meant to be as cheap as `no-gh-on-path` above, a grep-shaped
+  # check, not a build step.
+  gh-argv-containment:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python scripts/check_gh_argv_containment.py .
+
   # #2170: run the full suite in the environment of a REAL FLEET MACHINE — a
   # populated `~/.coord/` (thin-client shaped), no `sqlite3` on PATH, and a
   # `$TMPDIR` under an ancestor pytest config.

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/PKG-INFO

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

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

@@ -309,6 +309,7 @@ docs/mocks/web/pipeline-narrow.html
 docs/mocks/web/pipeline-wide.html
 graphify-out/.gitignore
 scripts/audit_review_verdict_overrides.py
+scripts/check_gh_argv_containment.py
 scripts/codegen.py
 scripts/coord-test-runner.sh
 scripts/drive-batch.sh
@@ -379,6 +380,7 @@ tests/test_branch_model.py
 tests/test_bug_intake.py
 tests/test_build_worker_image_env_update.py
 tests/test_cargo_cache.py
+tests/test_check_gh_argv_containment.py
 tests/test_ci_acceptance_gate_1950.py
 tests/test_ci_parity_2091.py
 tests/test_ci_store.py
@@ -554,7 +556,6 @@ tests/test_needs_attention.py
 tests/test_network.py
 tests/test_new_issue_chat.py
 tests/test_next_release_tag.py
-tests/test_no_direct_gh_calls.py
 tests/test_node_shim.py
 tests/test_notifier_baseline.py
 tests/test_notifier_cli.py
@@ -607,6 +608,7 @@ tests/test_refine_chat.py
 tests/test_release_cordon_2101.py
 tests/test_release_cordon_daemon_leads_2176.py
 tests/test_release_cordon_deadlock_2240.py
+tests/test_release_cordon_stuck_2490.py
 tests/test_release_propagate.py
 tests/test_release_unified_1242.py
 tests/test_release_verify.py

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/code_coordinator.egg-info/scm_file_list.json

@@ -313,6 +313,7 @@
     "scripts/azure-workers/scrub-and-generalize.sh",
     "scripts/azure-workers/tailnet-acl.hujson",
     "scripts/azure-workers/verify-github-token.sh",
+    "scripts/check_gh_argv_containment.py",
     "scripts/codegen.py",
     "scripts/coord-test-runner.sh",
     "scripts/drive-batch.sh",
@@ -441,6 +442,7 @@
     "tests/test_bug_intake.py",
     "tests/test_build_worker_image_env_update.py",
     "tests/test_cargo_cache.py",
+    "tests/test_check_gh_argv_containment.py",
     "tests/test_ci_acceptance_gate_1950.py",
     "tests/test_ci_parity_2091.py",
     "tests/test_ci_store.py",
@@ -616,7 +618,6 @@
     "tests/test_network.py",
     "tests/test_new_issue_chat.py",
     "tests/test_next_release_tag.py",
-    "tests/test_no_direct_gh_calls.py",
     "tests/test_node_shim.py",
     "tests/test_notifier_baseline.py",
     "tests/test_notifier_cli.py",
@@ -669,6 +670,7 @@
     "tests/test_release_cordon_2101.py",
     "tests/test_release_cordon_daemon_leads_2176.py",
     "tests/test_release_cordon_deadlock_2240.py",
+    "tests/test_release_cordon_stuck_2490.py",
     "tests/test_release_propagate.py",
     "tests/test_release_unified_1242.py",
     "tests/test_release_verify.py",

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.195",
+  "tag": "0.5.197",
   "distance": 0,
-  "node": "g2bb7d7ad4f498cd537a6acf1e85b0ee9e8573117",
+  "node": "gac6cd7be56630a9693710286586d56b6c59bc767",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/coord/commands/release.py

@@ -1354,6 +1354,7 @@ def _apply_cordons(  # noqa: PLR0912 — one linear apply-the-plan pass
     outcome.cooling_seconds = plan.cooling_seconds
     outcome.collateral_spared = list(plan.collateral_spared)
     outcome.blocked_behind = plan.blocked_behind
+    outcome.stuck_in_cooldown = list(plan.stuck_in_cooldown)
     if plan.released is not None:
         outcome.released = plan.released.to_dict()
         # stderr as well as stdout: on the timer host this line IS the
@@ -2148,8 +2149,18 @@ def release_cordon(
             )
         )
         return
+    # #2490: hosts the newest propagate run flagged as behind, idle, and
+    # left uncordoned only because the #2240 cooldown is suppressing new
+    # cordons. These are exactly the machines an operator would otherwise
+    # have to notice by hand (`coord status` showing `online • idle` on a
+    # host that's actually stuck on an old version) — surface them even when
+    # `active` is empty, since a stuck host is by definition NOT cordoned.
+    stuck_hosts, stuck_target = _stuck_hosts_from_journal()
     if not active:
-        click.echo("no machines are cordoned — the fleet is free to take work")
+        if stuck_hosts:
+            _echo_stuck_hosts(stuck_hosts, stuck_target)
+        else:
+            click.echo("no machines are cordoned — the fleet is free to take work")
         return
     for name, record in sorted(active.items()):
         remaining = max(0.0, record.expires_at - now) / 60.0
@@ -2180,6 +2191,8 @@ def release_cordon(
             f"`coord release propagate` releases it by itself after "
             f"{rc.DEFAULT_MAX_DEFERRALS}."
         )
+    if stuck_hosts:
+        _echo_stuck_hosts(stuck_hosts, stuck_target)
     click.echo(
         f"\nclear one with `coord release cordon --clear <machine>` "
         f"(default lifetime {rc.DEFAULT_TTL_SECONDS / 60:.0f}m — a cordon "
@@ -2197,6 +2210,59 @@ def _read_propagation_records() -> list[dict]:
         return []
 
 
+def _stuck_hosts_from_journal() -> tuple[list[str], str | None]:
+    """Hosts the NEWEST propagate run flagged as stuck-in-cooldown (#2490).
+
+    ``CordonPlan.stuck_in_cooldown`` (mirrored onto ``CordonOutcome`` and
+    journalled under a run's ``cordons`` key) names behind, idle hosts a run
+    left uncordoned only because the #2240 deadlock-release cooldown is
+    still active — the gap the issue is about: nothing gave such a host a
+    signal or a path back to rolling for up to the cooldown's full length.
+
+    Only the single newest record counts, deliberately: this is a
+    point-in-time reading ("as of the last tick"), and a host named in an
+    older record may since have gone busy, rolled, or had its cooldown
+    lift — reporting it from a stale record would be a false alarm, which is
+    exactly the kind of noise this fleet already has too much of. No
+    journal (a thin client, or a host that has never run propagate)
+    degrades to nothing rather than raising — mirrors every other reader of
+    this journal in this module.
+    """
+    try:
+        records = _read_propagation_records()
+    except Exception:  # noqa: BLE001 — never load-bearing
+        return [], None
+    if not records:
+        return [], None
+    newest = records[-1]
+    if not isinstance(newest, dict):
+        return [], None
+    cordons = newest.get("cordons")
+    if not isinstance(cordons, dict):
+        return [], None
+    stuck = cordons.get("stuck_in_cooldown") or []
+    if not isinstance(stuck, list):
+        return [], None
+    target = newest.get("target_version")
+    return [str(h) for h in stuck], (str(target) if target else None)
+
+
+def _echo_stuck_hosts(stuck_hosts: list[str], stuck_target: str | None) -> None:
+    """The #2490 notice both branches of ``release_cordon`` share.
+
+    One line per host, each naming its own override command — the format
+    the issue itself asks for: "precision: 18m behind v0.5.192, idle, cordon
+    suppressed by cooldown (#2240) — consider `coord agent update --machine
+    precision`."
+    """
+    version = f"v{stuck_target}" if stuck_target else "the release"
+    click.echo(f"\n! STUCK (#2490): behind {version}, idle, cordon suppressed "
+               "by the #2240 deadlock-release cooldown — no automatic path "
+               "back to rolling until it lifts on its own:")
+    for host in sorted(stuck_hosts):
+        click.echo(f"  ! {host}: consider `coord agent update --machine {host}`")
+
+
 @release_group.command(
     "rollback",
     help=(

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/coord/commands/status.py

@@ -55,6 +55,30 @@ def _cordon_stall_suffix(cordons: dict) -> str:
     return f" ({described})" if described else ""
 
 
+def _stuck_in_cooldown_hosts() -> dict[str, str | None]:
+    """Machine name -> target version, for hosts stuck-in-cooldown (#2490).
+
+    Thin wrapper around :func:`coord.commands.release._stuck_hosts_from_journal`
+    — same journal, same "newest record only" reading, reused rather than
+    reimplemented. A host in this dict is behind the target version, was
+    idle as of the last `coord release propagate` tick, and is NOT cordoned
+    (the #2240 cooldown is suppressing it) — which is exactly why it shows
+    up everywhere else in this command as a flatly ordinary `online • idle`.
+    That silence is the whole finding of #2490: a human noticed only because
+    they happened to be watching `coord status` themselves.
+
+    Degrades to ``{}`` on any error (no journal, an unreadable one, a thin
+    client) — never load-bearing, same contract as `_cordon_stall_suffix`.
+    """
+    from coord.commands.release import _stuck_hosts_from_journal  # noqa: PLC0415
+
+    try:
+        hosts, target = _stuck_hosts_from_journal()
+    except Exception:  # noqa: BLE001 — a status render must never fail on this
+        return {}
+    return {h: target for h in hosts}
+
+
 def _live_advisory_entries(
     entries: list[dict],
     cfg: "Config",
@@ -187,6 +211,9 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
     # same, which is why the 70-minute stall was invisible.
     cordon_stall = _cordon_stall_suffix(cordons)
     quiet_windows = effective_quiet_hours(cfg.machines)
+    # #2490: hosts the last propagate run flagged as behind + idle + stuck
+    # behind an active #2240 cooldown — see `_stuck_in_cooldown_hosts`.
+    stuck_in_cooldown = _stuck_in_cooldown_hosts()
 
     statuses = check_all(machines, timeout=timeout)
     agent_completed: dict[str, dict] = {}
@@ -314,6 +341,22 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
             for repo_name, reason in degraded.items():
                 click.echo(f"    ⚠ degraded: {repo_name} — {reason}")
 
+        # #2490: this host is behind the release, was idle last tick, and
+        # nothing is cordoning it because a #2240 deadlock-release cooldown
+        # is suppressing all new cordons fleet-wide. Without this line the
+        # machine above reads as a plain `online • idle` — indistinguishable
+        # from a machine with nothing to do, which is exactly how the
+        # 2026-08-20 incident went unnoticed for the length of the cooldown.
+        if m.name in stuck_in_cooldown:
+            stuck_target = stuck_in_cooldown[m.name]
+            stuck_version = f"v{stuck_target}" if stuck_target else "the release"
+            click.echo(
+                f"    ⚠ STUCK: behind {stuck_version} and idle, but cordoning "
+                "is suppressed by an active #2240 deadlock-release cooldown "
+                "(#2490) — no automatic path back to rolling until it lifts; "
+                f"consider `coord agent update --machine {m.name}`"
+            )
+
         if status_result and status_result.ok and status_result.data:
             for entry in status_result.data.get("active", []):
                 progress = entry.get("progress")

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/coord/release_cordon.py

@@ -658,6 +658,17 @@ class CordonPlan:
     #: exactly when `collateral_spared` is non-empty. The single fact that
     #: would have turned a 40-minute puzzle into one line of output.
     blocked_behind: str | None = None
+    #: #2490: hosts that are BEHIND *target_version*, have no busy signal of
+    #: their own this run (idle), and are not being cordoned only because an
+    #: unexpired deadlock-release cooldown is suppressing all new cordons —
+    #: set exactly when ``cooling_seconds > 0``. This is the gap the issue
+    #: names: a host in this state has no automatic path back to rolling for
+    #: up to the cooldown's full length, and nothing surfaced that it was
+    #: sitting there idle, behind, and unflagged. Reported separately from
+    #: ``collateral_spared`` (blocked behind a busy daemon host — a different
+    #: reason a behind host stays uncordoned) so each surface can name the
+    #: actual cause instead of collapsing both into "not cordoned".
+    stuck_in_cooldown: tuple[str, ...] = ()
 
     @property
     def empty(self) -> bool:
@@ -668,6 +679,7 @@ class CordonPlan:
             or self.expired
             or self.released
             or self.collateral_spared
+            or self.stuck_in_cooldown
         )
 
     def to_dict(self) -> dict:
@@ -681,6 +693,7 @@ class CordonPlan:
             "cooling_seconds": self.cooling_seconds,
             "collateral_spared": list(self.collateral_spared),
             "blocked_behind": self.blocked_behind,
+            "stuck_in_cooldown": list(self.stuck_in_cooldown),
         }
 
     def render(self) -> list[str]:
@@ -718,6 +731,13 @@ class CordonPlan:
                 "release (#2240) is still letting the fleet work; nothing was "
                 "cordoned this run"
             )
+        for host in self.stuck_in_cooldown:
+            lines.append(
+                f"  ! STUCK: {host} is behind and idle, but cordoning is "
+                "suppressed by the deadlock-release cooldown above (#2490) — "
+                f"it has no automatic path back to rolling until the cooldown "
+                f"lifts. Consider `coord agent update --machine {host}`."
+            )
         for esc in self.escalations:
             lines.append(f"  ! {esc.message}")
         return lines
@@ -880,6 +900,21 @@ def plan_cordons(
     pressure = pressure or DeferralPressure()
     cooling = pressure.cooling_for(now, release_cooldown)
     if cooling > 0:
+        # #2490: a behind host with no busy signal of its own has nothing
+        # left holding it back except this cooldown — it is idle, it is
+        # behind, and it will sit exactly like that until the cooldown
+        # lifts (up to `release_cooldown` seconds) with no cordon and,
+        # before this, no signal anywhere that it needs attention.
+        # `collateral` hosts are excluded: those are uncordoned for an
+        # unrelated reason (blocked behind a busy daemon host) that already
+        # has its own name (`collateral_spared`/`blocked_behind`).
+        stuck = tuple(
+            sorted(
+                host
+                for host in (drift.behind - collateral)
+                if not (busy_reasons or {}).get(host)
+            )
+        )
         return CordonPlan(
             uncordon=to_uncordon,
             expired=expired,
@@ -887,6 +922,7 @@ def plan_cordons(
             unknown=tuple(sorted(drift.undecided & set(live))),
             collateral_spared=tuple(sorted(collateral)),
             blocked_behind=blocked_behind,
+            stuck_in_cooldown=stuck,
         )
     if max_deferrals > 0 and pressure.consecutive >= max_deferrals:
         return CordonPlan(
@@ -984,6 +1020,12 @@ class CordonOutcome:
     #: #2176: the daemon host `collateral_spared` was spared on account of.
     #: Mirrors `CordonPlan.blocked_behind`.
     blocked_behind: str | None = None
+    #: #2490: mirrors `CordonPlan.stuck_in_cooldown` — behind, idle hosts this
+    #: run left uncordoned only because the #2240 deadlock cooldown is still
+    #: active. Journalled (not just printed) so a read-only surface like
+    #: `coord status` can flag them without recomputing `plan_cordons` itself
+    #: — see `coord.commands.status._stuck_in_cooldown_hosts`.
+    stuck_in_cooldown: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict:
         return {
@@ -999,4 +1041,5 @@ class CordonOutcome:
             "max_deferrals": self.max_deferrals,
             "collateral_spared": list(self.collateral_spared),
             "blocked_behind": self.blocked_behind,
+            "stuck_in_cooldown": list(self.stuck_in_cooldown),
         }

{code_coordinator-0.5.195 → code_coordinator-0.5.197}/coord/release_propagate.py

@@ -1294,6 +1294,14 @@ def render_record(record: PropagationRecord | Mapping[str, Any]) -> list[str]:
             "    cordons held off (post-release cooldown, #2240): "
             f"{float(cordons['cooling_seconds']) / 60.0:.0f}m left"
         )
+    # #2490: name the hosts that were behind and idle but left uncordoned
+    # purely because of the cooldown above — the gap that let `precision`
+    # sit stuck for 30 minutes with no automatic path back to rolling.
+    if cordons.get("stuck_in_cooldown"):
+        lines.append(
+            "    ! STUCK (idle, behind, cooldown-suppressed, #2490): "
+            + ", ".join(cordons["stuck_in_cooldown"])
+        )
     for esc in cordons.get("escalated") or []:
         lines.append(f"    ! {esc.get('message') or esc}")
     for err in cordons.get("errors") or []:

code_coordinator-0.5.197/scripts/check_gh_argv_containment.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""check_gh_argv_containment.py -- CI guard for #2135 (child of epic #1902).
+
+The epic's headline finding (#1902) is that **every `["gh", ...]` argv
+construction in this repo already lives inside `coord/github_ops.py`** --
+that single fact is what makes the eventual forge-portability port a
+*refactor* instead of a rewrite, and it is the load-bearing assumption
+under the whole #1902 cost estimate. Until this script, that invariant was
+protected by nothing but convention: whoever last thought to grep for it.
+
+Same spirit as `scripts/run_tests_without_gh.sh` (#1484, the `no-gh-on-path`
+CI job) -- that script proved `gh` calls are *mockable* by making the
+binary unresolvable and watching the suite still pass; this script proves
+they are *contained* by refusing any `gh` argv construction that lives
+outside the one file that owns them. Deliberately kept a plain regex scan,
+not an AST walk -- cheap enough to run on every PR, and the invariant it
+guards ("does this file spell the literal string `gh` as its own quoted
+token") does not need a parser to detect.
+
+Supersedes `tests/test_no_direct_gh_calls.py` (#1483's original AST-based
+guard for this same invariant, added when only `github_ops.py`'s
+call-site shape needed catching). #2135 review flagged that the two
+guards were an undocumented split-brain: the AST walk only fires when a
+`["gh", ...]` literal is a *direct call argument*
+(`subprocess.run(["gh", ...])`), so it silently missed the
+variable-indirection shape (`cmd = ["gh", ...]; subprocess.run(cmd)`) that
+this regex scan does catch, since it matches the token wherever it sits on
+the line. Rather than keep two independently-maintained implementations of
+one invariant with two different blind spots, `test_no_direct_gh_calls.py`
+was deleted and this script is now the single implementation, exercised
+both by the dedicated `gh-argv-containment` CI job (`.github/workflows/
+test.yml`) and by the ordinary `pytest tests/` run, via
+`tests/test_check_gh_argv_containment.py::test_real_tree_is_clean` and
+friends -- one scan, reachable both ways, per the repo's "one question,
+one answer" rule (epic #2096). The trade-off this leaves: being a plain
+token scan rather than an AST walk, it can false-positive on a `"gh"`
+token that isn't argv (e.g. inside a docstring or an unrelated string
+literal) -- accepted deliberately, since a false positive costs an
+allowlist entry or a reword, while a false negative (the AST gap above)
+costs a silent regression of the epic's #1902 load-bearing assumption.
+
+Usage:
+    python scripts/check_gh_argv_containment.py [repo-root]
+
+Exit codes: 0 if the tree is clean, 1 if a `gh` argv construction is found
+in coord/**/*.py outside coord/github_ops.py.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+SEAM = "coord/github_ops.py"
+
+# Matches a bare `"gh"` or `'gh'` token -- the exact spelling every gh argv
+# construction in this repo starts with, whether written `["gh", ...]`,
+# `("gh", ...)`, or (as in github_ops.py's PR-checks call, where the list is
+# opened on the previous line) as a bare leading element `"gh", "pr", ...,`.
+# The closing quote must land immediately after the 'h', so this does not
+# match longer identifiers that merely contain "gh", like "github" or
+# "ghost".
+_GH_TOKEN_RE = re.compile(r"""(["'])gh\1""")
+
+# Explicit allowlist: (file, substring-of-the-matched-line) pairs for
+# known-legitimate `gh` mentions outside the seam. Keyed on line CONTENT,
+# not a line number -- numbers drift as a file changes (this very entry's
+# line moved from prereqs.py:288, where #2135 was filed, to prereqs.py:290
+# by the time this script was written), and a number-keyed allowlist would
+# either miss a real leak that later lands on that number, or stop
+# exempting the intended line the moment it shifts.
+#
+# Add an entry here ONLY with a comment explaining why the mention is not
+# an argv construction -- a loose pattern (e.g. "any line in prereqs.py")
+# would let a real leak through under cover of the exemption, which is
+# exactly the failure mode this script exists to prevent.
+_ALLOWLIST: tuple[tuple[str, str], ...] = (
+    (
+        "coord/prereqs.py",
+        'tool="gh", binary="gh"',
+    ),
+    # ^ Prereq(tool="gh", binary="gh", version_args=("--version",), ...)
+    # probes for the `gh` BINARY's presence/version via shutil.which +
+    # `gh --version` -- it does not drive the forge, so it correctly lives
+    # outside the seam (#2135).
+)
+
+
+@dataclass(frozen=True)
+class Violation:
+    path: str
+    lineno: int
+    line: str
+
+
+def _is_allowlisted(rel_path: str, line: str) -> bool:
+    return any(
+        rel_path == allow_path and allow_substr in line
+        for allow_path, allow_substr in _ALLOWLIST
+    )
+
+
+def find_violations(repo_root: Path) -> list[Violation]:
+    """Scan coord/**/*.py for `gh` argv construction outside the seam.
+
+    Pure function of the filesystem under ``repo_root`` -- no subprocess,
+    no network -- so it is cheap to point at a synthetic fixture tree in
+    tests, not just the real repo.
+    """
+    violations: list[Violation] = []
+    coord_dir = repo_root / "coord"
+    if not coord_dir.is_dir():
+        return violations
+    for path in sorted(coord_dir.rglob("*.py")):
+        rel = path.relative_to(repo_root).as_posix()
+        if rel == SEAM:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError) as exc:
+            # Every file under coord/ is expected to be UTF-8 Python
+            # source, so this should never actually fire -- but if it
+            # ever does, skipping silently would mean a real `gh` leak in
+            # that file goes undetected with no trace. Surface it on
+            # stderr rather than swallow it (#2135 review).
+            print(
+                f"check_gh_argv_containment: skipping {rel} "
+                f"(unreadable: {exc}) -- unable to scan for `gh` argv "
+                f"construction in this file",
+                file=sys.stderr,
+            )
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            if _GH_TOKEN_RE.search(line) and not _is_allowlisted(rel, line):
+                violations.append(Violation(rel, lineno, line.strip()))
+    return violations
+
+
+def format_report(violations: list[Violation]) -> str:
+    lines = [
+        f"check_gh_argv_containment: found `gh` argv construction outside "
+        f"{SEAM}:",
+        "",
+    ]
+    for v in violations:
+        lines.append(f"  {v.path}:{v.lineno}: {v.line}")
+    lines += [
+        "",
+        "Every `gh` invocation must go through coord/github_ops.py -- that "
+        "chokepoint is the load-bearing assumption behind the #1902 "
+        "forge-portability epic (it's what makes the eventual port a "
+        "refactor instead of a rewrite), and it's what makes `gh` mockable "
+        "for tests (the no-gh-on-path CI job, #1484, depends on it too).",
+        "",
+        'Fix: move this call into coord/github_ops.py. If it is a genuine '
+        'non-forge use of the literal string "gh" (like the binary-version '
+        "probe in coord/prereqs.py), add it to the ALLOWLIST in "
+        "scripts/check_gh_argv_containment.py with a comment explaining "
+        "why -- see #2135.",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    repo_root = Path(argv[1]) if len(argv) > 1 else Path(".")
+    violations = find_violations(repo_root.resolve())
+    if not violations:
+        return 0
+    print(format_report(violations), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))