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

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

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

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

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

{code_coordinator-0.5.317 → code_coordinator-0.5.318}/coord/confirm_test.py

@@ -171,6 +171,23 @@ CONFIRM_DEFAULT_TIMEOUT_SECONDS = 60 * 20
 #: so a pass can confirm ~4 branches back to back) while the daemon-side worst
 #: case stays a number the thin client can actually be given — see
 #: :func:`notify_client_timeout_seconds`.
+#:
+#: #2975: that "~6 min serial" sizing is calibrated on THIS repo and does not
+#: hold everywhere — quadraui's ``cargo test --features tui`` builds every
+#: example/test executable (#305 in coordinator.yml) and blows straight past
+#: it, and every ceiling in this module (this one, ``CONFIRM_DEFAULT_
+#: TIMEOUT_SECONDS``, ``deploy/coord-notify.service``'s ``TimeoutStartSec``)
+#: is bigger than ``coord-notify.timer``'s 5-minute cadence, so one such
+#: confirmation can span several fires. Two changes close that without
+#: shrinking this constant (which would just make the COMMON case degrade to
+#: UNCONFIRMED instead): ``coord.notify``'s drain now dispatches pending
+#: Test/Review/PR-opens BEFORE running any confirmation each pass, so a slow
+#: suite on one repo can no longer queue another repo's dispatch behind it;
+#: and :func:`expected_confirmation_seconds` remembers how long a repo's
+#: confirmation last took, so :func:`confirmation_timeout` can recognise a
+#: repo whose suite structurally cannot fit this budget and skip straight to
+#: UNCONFIRMED instead of re-discovering that identical fact — and re-paying
+#: the full ceiling for it — on every single PASS claim.
 CONFIRM_PASS_BUDGET_SECONDS = 60 * 25
 
 #: Don't *start* a confirmation with less than this left in the pass budget.
@@ -232,6 +249,31 @@ KIND_NO_OUTPUT = "no_output"
 #: docstring's fail-direction section — this frozenset IS that safety property.
 REFUTING_KINDS = frozenset({KIND_BUILD, KIND_SUITE})
 
+#: #2975: kinds whose elapsed wall-clock time is a trustworthy signal of how
+#: long THIS repo's confirmation genuinely takes, worth remembering for next
+#: time via :func:`record_confirmation_duration`.
+#:
+#: ``KIND_OK``/``KIND_BUILD``/``KIND_SUITE``/``KIND_BASELINE_RED``/
+#: ``KIND_NO_OUTPUT`` all ran the command to actual completion — a real
+#: measurement. ``KIND_TIMEOUT`` ran for at least the ceiling it was given —
+#: not exact, but a valid LOWER BOUND, and a lower bound is exactly what lets
+#: a chronically-too-slow repo (quadraui's ``cargo test --features tui``
+#: builds every example/test executable, #305 in coordinator.yml) be
+#: recognised as such after a single attempt instead of re-discovering it on
+#: every PASS claim — see :func:`expected_confirmation_seconds`.
+#:
+#: ``KIND_SETUP``/``KIND_INFRA``/``KIND_SIGNAL`` are deliberately excluded:
+#: none of them ran the real command for a representative duration (no
+#: checkout, no toolchain, or killed externally mid-run), and recording their
+#: near-zero elapsed time would silently erase a previously-learned
+#: expectation — exactly the failure mode that would make a single lock
+#: contention hiccup or a missing checkout reset a repo's hard-won "this one
+#: is slow" memory back to "assume it's fast."
+RECORDABLE_DURATION_KINDS = frozenset({
+    KIND_OK, KIND_BUILD, KIND_SUITE, KIND_BASELINE_RED, KIND_NO_OUTPUT,
+    KIND_TIMEOUT,
+})
+
 #: Kinds meaning "the check could not reach a verdict". The caller falls back to
 #: the worker's own claim on any of these, which is pre-#2464 behaviour.
 INCONCLUSIVE_KINDS = frozenset({
@@ -270,7 +312,7 @@ def begin_confirmation_pass(total: float = CONFIRM_PASS_BUDGET_SECONDS) -> None:
     _pass_state.remaining = float(total)
 
 
-def confirmation_timeout() -> int | None:
+def confirmation_timeout(expected_seconds: float | None = None) -> int | None:
     """Seconds the next confirmation in this pass may take, or ``None``.
 
     ``None`` means the pass budget is spent (or too nearly spent to be worth
@@ -279,13 +321,31 @@ def confirmation_timeout() -> int | None:
 
     Outside a pass — a direct :func:`confirm_branch` call, a unit test — there
     is no budget to draw down and the full per-run ceiling applies.
+
+    *expected_seconds* (#2975) is the caller's best estimate of how long THIS
+    repo's confirmation will actually take — see
+    :func:`expected_confirmation_seconds`, which reads it back from what
+    :func:`record_confirmation_duration` learned last time. When it is
+    already at or past what this pass has left to spend, starting the run
+    would only spend the remainder re-discovering a fact already on record —
+    this repo cannot be confirmed in what is left — so this returns ``None``
+    immediately instead of paying for that discovery again. This is what
+    turns a repo whose suite structurally cannot fit the ceiling (quadraui's
+    ``cargo test --features tui``, #2975) from a repeated worst-case cost —
+    every PASS claim spending the full budget to learn the identical lesson —
+    into a one-time one: the FIRST attempt still spends up to the full
+    ceiling discovering the suite is too slow, and every attempt after that
+    skips straight to UNCONFIRMED.
     """
     remaining = getattr(_pass_state, "remaining", None)
     if remaining is None:
         return int(CONFIRM_DEFAULT_TIMEOUT_SECONDS)
     if remaining < CONFIRM_MIN_RUN_SECONDS:
         return None
-    return int(min(float(CONFIRM_DEFAULT_TIMEOUT_SECONDS), remaining))
+    ceiling = min(float(CONFIRM_DEFAULT_TIMEOUT_SECONDS), remaining)
+    if expected_seconds is not None and expected_seconds >= ceiling:
+        return None
+    return int(ceiling)
 
 
 def spend_confirmation_budget(seconds: float) -> None:
@@ -300,6 +360,112 @@ def spend_confirmation_budget(seconds: float) -> None:
     _pass_state.remaining = max(0.0, remaining - max(0.0, float(seconds)))
 
 
+#: #2975: filename under ``COORD_DIR`` for the per-repo measured-duration map
+#: :func:`record_confirmation_duration` / :func:`expected_confirmation_seconds`
+#: read and write. A tiny flat file, not a lock-guarded store: the worst case
+#: of a torn read/write is one stale or missing estimate, which degrades to
+#: exactly pre-#2975 behaviour (attempt the run, learn the hard way) — never
+#: a correctness problem, so it does not warrant the ceremony
+#: ``confirm_lock_path`` needs for the worktree lifecycle it guards.
+_CONFIRM_HISTORY_FILENAME = "confirm_test_history.json"
+
+
+def _confirm_history_path() -> Path:
+    """Where per-repo measured confirmation durations are persisted (#2975).
+
+    Resolved against ``coord.state.COORD_DIR`` freshly on every call — the
+    same discipline :func:`confirm_worktree_path` /
+    :func:`write_confirmation_output` already use above — so a test's
+    ``monkeypatch.setattr("coord.state.COORD_DIR", ...)`` is honoured rather
+    than this module caching a stale path at import time.
+    """
+    from coord.state import COORD_DIR  # noqa: PLC0415
+
+    return COORD_DIR / _CONFIRM_HISTORY_FILENAME
+
+
+def _load_confirm_history() -> dict[str, float]:
+    """Best-effort read of the persisted per-repo duration map.
+
+    Fail-soft on everything — a missing file, corrupt JSON, an unexpected
+    shape, a hand-edited value — because this is purely an optimisation hint
+    for :func:`confirmation_timeout`, never a correctness dependency. A file
+    this cannot make sense of must read as "nothing learned yet", the same
+    posture as :func:`coord.commands.drive_queue.read_roll_pending`.
+    """
+    import json  # noqa: PLC0415
+
+    try:
+        raw = _confirm_history_path().read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    out: dict[str, float] = {}
+    for key, value in data.items():
+        if isinstance(key, str) and isinstance(value, (int, float)) and value > 0:
+            out[key] = float(value)
+    return out
+
+
+def record_confirmation_duration(repo_name: str, seconds: float) -> None:
+    """Remember how long *repo_name*'s confirmation attempt just took (#2975).
+
+    Callers pass this only results whose ``kind`` is in
+    :data:`RECORDABLE_DURATION_KINDS` — see that frozenset's docstring for
+    which outcomes are a trustworthy signal of real suite duration.
+
+    Overwrites any previous value for this repo outright, with no averaging:
+    the LAST attempt is a better estimate of the CURRENT suite than a rolling
+    average across however long ago the repo's test suite was this size.
+
+    Best-effort and atomic (tempfile-then-rename, mirroring
+    :func:`coord.commands.drive_queue.write_roll_pending`) — a full disk, an
+    unwritable ``COORD_DIR``, or a concurrent writer must not break the
+    confirmation this is charging against; the caller already has its real
+    result, this is purely a hint for next time.
+    """
+    if seconds <= 0:
+        return
+    import json  # noqa: PLC0415
+    import tempfile  # noqa: PLC0415
+
+    path = _confirm_history_path()
+    history = _load_confirm_history()
+    history[repo_name] = float(seconds)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(
+            prefix=".confirm_test_history.", suffix=".tmp", dir=str(path.parent),
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(history, fh)
+            os.replace(tmp_name, path)
+        except OSError:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def expected_confirmation_seconds(repo_name: str) -> float | None:
+    """The most recently measured confirmation duration for *repo_name*.
+
+    ``None`` when this repo has never produced a
+    :data:`RECORDABLE_DURATION_KINDS` result — the common case for most
+    repos most of the time, and the caller's cue to fall back to the
+    un-informed ceiling exactly as before #2975.
+    """
+    return _load_confirm_history().get(repo_name)
+
+
 def notify_client_timeout_seconds(
     budget: float = CONFIRM_PASS_BUDGET_SECONDS,
 ) -> float:
@@ -1067,6 +1233,7 @@ __all__ = [
     "KIND_SIGNAL",
     "NOTIFY_BASE_CLIENT_TIMEOUT_SECONDS",
     "PERMISSION_DENIED_EXIT",
+    "RECORDABLE_DURATION_KINDS",
     "REFUTING_KINDS",
     "STALE_WORKTREE_MAX_AGE_HOURS",
     "ConfirmationResult",
@@ -1077,7 +1244,9 @@ __all__ = [
     "confirm_worktree_path",
     "confirmation_enabled",
     "confirmation_timeout",
+    "expected_confirmation_seconds",
     "notify_client_timeout_seconds",
+    "record_confirmation_duration",
     "spend_confirmation_budget",
     "sweep_stale_confirm_worktrees",
     "unmet_confirmation_capabilities",

{code_coordinator-0.5.317 → code_coordinator-0.5.318}/coord/notify.py

@@ -2033,9 +2033,12 @@ def _run_pass_confirmation(transition: Transition, entry: dict):
     that cannot run must degrade to pre-#2464 behaviour, never break the reap.
     """
     from coord.confirm_test import (  # noqa: PLC0415
+        RECORDABLE_DURATION_KINDS,
         confirm_branch,
         confirmation_enabled,
         confirmation_timeout,
+        expected_confirmation_seconds,
+        record_confirmation_duration,
         spend_confirmation_budget,
     )
 
@@ -2066,15 +2069,34 @@ def _run_pass_confirmation(transition: Transition, entry: dict):
     # `/notify` request the thin client is blocked on — scale with board
     # activity. Exhausted budget means UNCONFIRMED, which is pre-#2464
     # behaviour, and it is said out loud rather than truncating silently.
-    timeout = confirmation_timeout()
+    #
+    # #2975: also hand in whatever this repo's OWN last confirmation measured
+    # (`expected_confirmation_seconds`) — a repo whose suite structurally
+    # cannot finish inside the budget (quadraui's `cargo test --features
+    # tui`) would otherwise spend the full ceiling relearning that identical
+    # fact on every single PASS claim, serialising every other repo's Test/
+    # Review dispatch behind it each time. Knowing the answer already lets
+    # `confirmation_timeout` skip straight to UNCONFIRMED instead.
+    expected = expected_confirmation_seconds(transition.repo_name)
+    timeout = confirmation_timeout(expected)
     if timeout is None:
-        log.warning(
-            "smoke %s: this notify pass has spent its confirmation budget "
-            "(coord.confirm_test.CONFIRM_PASS_BUDGET_SECONDS) — recording the "
-            "worker's own claim for %s UNCONFIRMED rather than holding "
-            "notify.lock any longer (#2464).",
-            transition.assignment_id, transition.repo_name,
-        )
+        if expected is not None:
+            log.warning(
+                "smoke %s: %s's last measured confirmation took about %.0fs, "
+                "at or beyond what this pass has left to spend — skipping "
+                "the run and recording the worker's own claim UNCONFIRMED "
+                "rather than repeating a run already known not to finish "
+                "(#2975).",
+                transition.assignment_id, transition.repo_name, expected,
+            )
+        else:
+            log.warning(
+                "smoke %s: this notify pass has spent its confirmation budget "
+                "(coord.confirm_test.CONFIRM_PASS_BUDGET_SECONDS) — recording the "
+                "worker's own claim for %s UNCONFIRMED rather than holding "
+                "notify.lock any longer (#2464).",
+                transition.assignment_id, transition.repo_name,
+            )
         return None
 
     branch = entry.get("branch")
@@ -2084,10 +2106,12 @@ def _run_pass_confirmation(transition: Transition, entry: dict):
         transition.assignment_id, transition.repo_name, branch, timeout,
     )
     started = time.monotonic()
+    result: ConfirmationResult | None = None
     try:
-        return confirm_branch(
+        result = confirm_branch(
             transition.repo_name, branch, config, timeout=timeout,
         )
+        return result
     except Exception as exc:  # noqa: BLE001
         log.warning(
             "smoke %s: confirmation run raised (%s) — falling back to the "
@@ -2100,7 +2124,15 @@ def _run_pass_confirmation(transition: Transition, entry: dict):
         # It really did hold the drain (and `notify.lock`) for those seconds,
         # and a run that reliably blows up after ten minutes must not be able
         # to repeat that for every row on the board free of charge.
-        spend_confirmation_budget(time.monotonic() - started)
+        elapsed = time.monotonic() - started
+        spend_confirmation_budget(elapsed)
+        # #2975: only remember the duration when the result is actually a
+        # trustworthy measurement (see RECORDABLE_DURATION_KINDS) — an
+        # exception, a disabled config load, or a KIND_SETUP/INFRA/SIGNAL
+        # short-circuit tells us nothing about how long the real suite takes
+        # and must never overwrite a previously-learned expectation.
+        if result is not None and result.kind in RECORDABLE_DURATION_KINDS:
+            record_confirmation_duration(transition.repo_name, elapsed)
 
 
 def _confirmed_pass_verdict(
@@ -4155,6 +4187,20 @@ def run_drain(
     *notifications*, not pipeline advancement, and giving the daemon a
     periodic detector is #1632's job (which is blocked on this).
 
+    **Dispatch order (#2975).** Smoke/review/PR-open dispatch also runs as a
+    HEAD START right at the top of the pass, before this pass's own
+    transition detection (which is where a #2464 out-of-band confirmation
+    runs — see :mod:`coord.confirm_test`). A confirmation re-runs a repo's
+    real build+test synchronously and can hold this very lock for the whole
+    confirmation-pass budget, several timer fires' worth for a repo whose
+    suite is structurally too slow. Every row already eligible for dispatch
+    as of the top of the pass must not queue behind that — a slow suite on
+    one repo must delay only its own confirmation, never another repo's
+    Test/Review dispatch. The three dispatch functions run a second time
+    afterward too, in their historical place, to pick up anything the
+    transition-detection step below made newly eligible; all three are
+    idempotent, so the repeat costs only a second, mostly-empty scan.
+
     **Concurrency.**  The whole pass runs under ``~/.coord/notify.lock`` —
     literally :class:`coord.filelock.FileLock`, the same class on the same
     path ``coord drive``'s ``run_notify()`` takes — so a drive's nudge and the
@@ -4203,6 +4249,56 @@ def _run_drain_locked(config: Config) -> DrainResult:
 
     begin_confirmation_pass()
 
+    # Step 0a (#2803, moved up by #2975): clear any work row wedged at
+    # test_state='running' well past its Test-stage child's own terminal
+    # resolution (or absence) — a lost verdict write, never a fabricated one
+    # (see `sweep_stuck_test_state_rows`'s docstring). It still runs BEFORE
+    # every smoke dispatch in this pass, which is #2803's invariant: a row
+    # this clears is picked up and redispatched in THIS SAME pass, not the
+    # next one. It now runs before step 0b's head start as well, so a row it
+    # clears gets that head start too rather than waiting behind step 1's
+    # confirmations. Nothing is lost by sweeping before transition detection:
+    # every case the sweep acts on is gated on
+    # `STUCK_TEST_STATE_GRACE_SECONDS` (10 minutes) having elapsed since the
+    # child's own resolution, so a child that only just went terminal in
+    # THIS pass is out of scope either way.
+    try:
+        _sweep_stuck_test_state(config)
+    except Exception:  # noqa: BLE001
+        log.exception("notify drain: stuck test_state sweep failed")
+
+    # Step 0b (#2975): dispatch pending Test-stage smoke / PR-opens / reviews
+    # from the board exactly as it reads RIGHT NOW — before step 1 below gets
+    # anywhere near a `confirm_branch` call. A confirmation re-runs one
+    # repo's real build+test synchronously inside THIS pass and can
+    # legitimately hold `notify.lock` for the whole `CONFIRM_PASS_BUDGET_
+    # SECONDS` ceiling — several `coord-notify.timer` fires' worth (#2975).
+    # Every row already eligible for dispatch as of the top of this pass
+    # must not queue behind that: a slow suite on one repo should delay only
+    # its own confirmation, never another repo's Test/Review dispatch.
+    #
+    # Steps 2-3 below repeat these same three calls after the transition
+    # detection has had a chance to add anything newly eligible (a work leg
+    # that just finished, a PR that just opened) — this head start is
+    # additive, not a replacement.
+    # All three are idempotent (`_dispatch_board_pending_pr_opens`'s and
+    # `_dispatch_board_pending_smoke`'s own docstrings: "safe to call even
+    # when the board file doesn't exist", find-or-create PRs, dedupe via
+    # `has_active_followup`), so calling each twice in one pass costs
+    # nothing beyond a second, mostly-empty scan.
+    try:
+        _dispatch_board_pending_pr_opens(config)
+    except Exception:  # noqa: BLE001
+        log.exception("notify drain: head-start PR-open dispatch failed")
+    try:
+        _dispatch_board_pending_smoke(config)
+    except Exception:  # noqa: BLE001
+        log.exception("notify drain: head-start smoke dispatch failed")
+    try:
+        _dispatch_board_pending_reviews(config)
+    except Exception:  # noqa: BLE001
+        log.exception("notify drain: head-start review dispatch failed")
+
     # Step 1: post completion/failure/advisory/plan/review comments for rows
     # the agent reports terminal.  This is what stamps `finished_at` (via
     # mark_notified) and captures cost / SMOKE_TESTS / summary / session id /
@@ -4234,18 +4330,7 @@ def _run_drain_locked(config: Config) -> DrainResult:
     except Exception:  # noqa: BLE001
         log.exception("notify drain: detect_transitions failed")
 
-    # Step 2 (#2803): clear any work row wedged at test_state='running' well
-    # past its Test-stage child's own terminal resolution (or absence) — a
-    # lost verdict write, never a fabricated one (see `sweep_stuck_test_
-    # state_rows`'s docstring). Runs BEFORE step 3's smoke dispatch so a row
-    # this clears is picked up and redispatched in THIS SAME pass, not the
-    # next one.
-    try:
-        _sweep_stuck_test_state(config)
-    except Exception:  # noqa: BLE001
-        log.exception("notify drain: stuck test_state sweep failed")
-
-    # Step 2.5 (#2844): open PRs for work-leg completions still missing one —
+    # Step 2 (#2844): open PRs for work-leg completions still missing one —
     # BEFORE the Test-stage dispatch below, so the pull_request CI run starts
     # overlapping smoke instead of waiting for review dispatch to open the
     # PR ~20 minutes later.
@@ -4447,6 +4532,31 @@ def run(
     # why this reads the marker but never writes it.
     _roll_pending = _roll_pending_blocks_new_dispatch()
 
+    # Step 0 (#2975): same head start `_run_drain_locked` takes, and for the
+    # identical reason — dispatch pending Test-stage smoke / PR-opens /
+    # reviews from the board exactly as it reads RIGHT NOW, before the
+    # transition-detection loop below gets anywhere near a `confirm_branch`
+    # call that can hold `notify.lock` for up to `CONFIRM_PASS_BUDGET_
+    # SECONDS`. Gated on `_roll_pending` like every other NEW-leg dispatch in
+    # this function (#2587) — the later calls to the same three functions,
+    # a few dozen lines down, repeat this after the loop below has had a
+    # chance to add anything newly eligible; this is a head start, not a
+    # replacement, and all three are idempotent so calling each twice costs
+    # only a second, mostly-empty scan.
+    if not _roll_pending:
+        try:
+            _dispatch_board_pending_pr_opens(config)
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            _dispatch_board_pending_smoke(config)
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            _dispatch_board_pending_reviews(config)
+        except Exception:  # noqa: BLE001
+            pass
+
     # #522: one terminal-state cache shared across every gh-hitting check in
     # this notify run (the auto-loop review/fix dispatches below, and the
     # #1441 stalled-pipeline sweep at the end), so a burst of activity for

{code_coordinator-0.5.317 → code_coordinator-0.5.318}/tests/test_confirm_test.py

@@ -1698,3 +1698,196 @@ class TestConfirmationRespectsCapabilityRouting:
         read that as 'gate not applicable', never as 'nothing required'
         collapsing into a refusal."""
         assert ct.branch_touched_files(tmp_path, BRANCH, "main") == []
+
+
+# ── #2975: per-repo measured duration, so a chronically-too-slow repo stops
+#    re-learning the same lesson on every PASS claim ─────────────────────────
+
+
+class TestExpectedConfirmationDurationHistory:
+    """quadraui's `cargo test --features tui` builds every example/test
+    executable (#305 in coordinator.yml) and structurally cannot finish
+    inside any ceiling this module hands out from the reap path. Before
+    #2975, every PASS claim on that repo spent the FULL pass budget
+    rediscovering that identical fact, serialising every other repo's
+    Test/Review dispatch behind it each time (#2975's reported symptom:
+    coord-tui#17 sat idle ~20 minutes with three machines free). Remembering
+    the last measured duration lets `confirmation_timeout` recognise a
+    doomed run and skip it instead of repeating it.
+    """
+
+    def test_never_measured_reports_no_expectation(self) -> None:
+        assert ct.expected_confirmation_seconds("quadraui") is None
+
+    def test_records_and_reads_back_a_measured_duration(self) -> None:
+        ct.record_confirmation_duration("quadraui", 1234.5)
+        assert ct.expected_confirmation_seconds("quadraui") == 1234.5
+
+    def test_recording_is_per_repo(self) -> None:
+        ct.record_confirmation_duration("quadraui", 1200.0)
+        ct.record_confirmation_duration("claude-coordinator", 360.0)
+        assert ct.expected_confirmation_seconds("quadraui") == 1200.0
+        assert ct.expected_confirmation_seconds("claude-coordinator") == 360.0
+
+    def test_a_later_measurement_overwrites_the_earlier_one(self) -> None:
+        """The LAST attempt is a better estimate of the CURRENT suite than an
+        average across however long ago the suite was this size — no
+        averaging, straight overwrite."""
+        ct.record_confirmation_duration("quadraui", 1200.0)
+        ct.record_confirmation_duration("quadraui", 90.0)
+        assert ct.expected_confirmation_seconds("quadraui") == 90.0
+
+    def test_a_non_positive_duration_is_never_recorded(self) -> None:
+        ct.record_confirmation_duration("quadraui", 0.0)
+        ct.record_confirmation_duration("quadraui", -5.0)
+        assert ct.expected_confirmation_seconds("quadraui") is None
+
+    def test_recordable_kinds_are_exactly_the_ones_that_ran_for_real(self) -> None:
+        """`KIND_OK`/`KIND_BUILD`/`KIND_SUITE`/`KIND_BASELINE_RED`/
+        `KIND_NO_OUTPUT` ran to completion; `KIND_TIMEOUT` ran for at least
+        its ceiling — all six are a trustworthy signal. `KIND_SETUP`/
+        `KIND_INFRA`/`KIND_SIGNAL` never ran the command for a representative
+        duration and must stay excluded, or a single lock-contention hiccup
+        or missing checkout would erase a hard-won 'this one is slow'
+        expectation back down to near zero."""
+        assert ct.RECORDABLE_DURATION_KINDS == {
+            KIND_OK, KIND_BUILD, KIND_SUITE, KIND_BASELINE_RED,
+            ct.KIND_NO_OUTPUT, KIND_TIMEOUT,
+        }
+        for excluded in (KIND_SETUP, KIND_INFRA, ct.KIND_SIGNAL):
+            assert excluded not in ct.RECORDABLE_DURATION_KINDS
+
+    def test_a_corrupt_history_file_reads_as_never_measured(
+        self, isolated_coord_dir: Path,
+    ) -> None:
+        history_path = isolated_coord_dir / "confirm_test_history.json"
+        history_path.write_text("not json{{{", encoding="utf-8")
+        assert ct.expected_confirmation_seconds("quadraui") is None
+
+    def test_history_survives_being_read_back_from_a_fresh_process_view(
+        self, isolated_coord_dir: Path,
+    ) -> None:
+        """The store is a plain file, not process memory — write it once and
+        a completely separate read must see it, exactly like
+        `coord.commands.drive_queue`'s roll-pending marker."""
+        import json
+
+        history_path = isolated_coord_dir / "confirm_test_history.json"
+        ct.record_confirmation_duration("quadraui", 777.0)
+        assert json.loads(history_path.read_text())["quadraui"] == 777.0
+
+
+class TestConfirmationTimeoutSkipsAKnownDoomedRepo:
+    """`confirmation_timeout`'s *expected_seconds* parameter — the wiring
+    that turns a measured history entry into an actual skip."""
+
+    def test_expected_well_below_the_ceiling_still_hands_out_the_ceiling(
+        self,
+    ) -> None:
+        ct.begin_confirmation_pass(600)
+        assert ct.confirmation_timeout(expected_seconds=100) == 600
+
+    def test_expected_at_the_ceiling_skips_the_run(self) -> None:
+        ct.begin_confirmation_pass(600)
+        assert ct.confirmation_timeout(expected_seconds=600) is None
+
+    def test_expected_past_the_ceiling_skips_the_run(self) -> None:
+        ct.begin_confirmation_pass(600)
+        assert ct.confirmation_timeout(expected_seconds=900) is None
+
+    def test_no_expectation_falls_back_to_the_ordinary_ceiling(self) -> None:
+        ct.begin_confirmation_pass(600)
+        assert ct.confirmation_timeout(expected_seconds=None) == 600
+        assert ct.confirmation_timeout() == 600
+
+    def test_expectation_is_irrelevant_outside_a_pass(self) -> None:
+        """No `begin_confirmation_pass()` call — the full per-run ceiling
+        applies regardless of history, exactly like calling this with no
+        argument at all."""
+        assert ct.confirmation_timeout(expected_seconds=10**9) == int(
+            ct.CONFIRM_DEFAULT_TIMEOUT_SECONDS
+        )
+
+    def test_a_shrinking_budget_can_flip_a_previously_eligible_repo_to_skipped(
+        self,
+    ) -> None:
+        """Spending most of the pass on other rows first must make the SAME
+        expectation newly disqualifying — this is what protects every OTHER
+        repo's confirmation from a known-slow one eating the tail of the
+        budget on a run that was already unlikely to finish."""
+        ct.begin_confirmation_pass(600)
+        assert ct.confirmation_timeout(expected_seconds=500) == 600
+        ct.spend_confirmation_budget(550)
+        assert ct.confirmation_timeout(expected_seconds=500) is None
+
+
+class TestNotifyReapSkipsAKnownDoomedConfirmation:
+    """Integration: `coord.notify._run_pass_confirmation` actually consults
+    the history and actually records into it — the two ends of #2975's fix
+    wired together, not just the pure functions in isolation."""
+
+    @staticmethod
+    def _transition():
+        from coord.notify import EVENT_COMPLETION, Transition
+
+        return Transition(
+            assignment_id="smoke-1", machine_name="laptop", repo_name="api",
+            issue_number=42, event=EVENT_COMPLETION, exit_code=0,
+        )
+
+    def test_a_timeout_is_remembered_and_the_next_attempt_skips_the_run(
+        self,
+    ) -> None:
+        from coord.notify import _run_pass_confirmation
+
+        entry = {"branch": BRANCH}
+        ct.begin_confirmation_pass(600)
+        clock = _FakeClock()
+
+        def _timed_out(*_a, **_k):
+            # The real `confirm_branch` blocks until it hits its deadline —
+            # simulate that by advancing the fake clock the same amount
+            # `_run_pass_confirmation`'s `finally` will charge to the budget.
+            clock.now += 600.0
+            return ct.ConfirmationResult(
+                kind=KIND_TIMEOUT,
+                reason="confirmation suite timed out after 600s",
+            )
+
+        # First attempt: nothing measured yet for 'api', so it really runs —
+        # and this one times out, the #2975 shape (a suite that structurally
+        # cannot finish inside the ceiling).
+        with (
+            patch("coord.config.load", return_value=_StubConfig()),
+            patch("coord.notify.time.monotonic", side_effect=clock),
+            patch(
+                "coord.confirm_test.confirm_branch", side_effect=_timed_out,
+            ) as confirm,
+        ):
+            result = _run_pass_confirmation(self._transition(), entry)
+
+        assert result is not None and result.kind == KIND_TIMEOUT
+        confirm.assert_called_once()
+        assert ct.expected_confirmation_seconds("api") == 600.0, (
+            "a KIND_TIMEOUT result must be remembered as (at least) how long "
+            "it ran — it's a valid lower bound on how long this repo's "
+            "suite takes"
+        )
+
+        # Second attempt, same repo, a FRESH pass with a full budget again —
+        # so the skip below is attributable to the measured expectation
+        # alone, not to a budget the first attempt happened to exhaust.
+        ct.begin_confirmation_pass(600)
+        with (
+            patch("coord.config.load", return_value=_StubConfig()),
+            patch(
+                "coord.confirm_test.confirm_branch",
+                return_value=ct.ConfirmationResult(
+                    kind=KIND_OK, reason="should not be reached",
+                ),
+            ) as confirm2,
+        ):
+            result2 = _run_pass_confirmation(self._transition(), entry)
+
+        confirm2.assert_not_called()
+        assert result2 is None