code-coordinator 0.5.582__tar.gz → 0.5.584__tar.gz

{code_coordinator-0.5.582 → code_coordinator-0.5.584}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.582",
+  "tag": "0.5.584",
   "distance": 0,
-  "node": "g66c11e8b562c82e18514dbd82f17849abf5c1df2",
+  "node": "g9c11468b5bebc2d9a592eb89d3d9f3491f59754a",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-03"

{code_coordinator-0.5.582 → code_coordinator-0.5.584}/coord/audit.py

@@ -41,6 +41,7 @@ __all__ = [
     "audit_lock_contention_losses",
     "flush_lock_contention_summary",
     "sweep_operational_retention",
+    "resolve_operational_retention_days",
 ]
 
 # Valid values are documented in the issue but not enforced here — callers
@@ -325,6 +326,21 @@ def _resolve_operational_retention_days() -> float:
         return 0.0
 
 
+def resolve_operational_retention_days() -> float:
+    """Public wrapper around :func:`_resolve_operational_retention_days`.
+
+    ``coord.reports``' ``deprecated-routes`` report (#1947) needs the exact
+    same number this module's own sweep caps itself to: a ``zero_calls``
+    route cannot be trusted for longer than data has actually been kept
+    around, so the gate's "observed window" must be capped at this value,
+    not re-derived from ``coordinator.yml`` a second way. One source of
+    truth for "how far back is audit data trustworthy" — see #2085 (one
+    question, one answer) for why a second config read here would be a bug
+    waiting to happen rather than a convenience.
+    """
+    return _resolve_operational_retention_days()
+
+
 def sweep_operational_retention(*, now: float | None = None, dry_run: bool = False) -> int:
     """Delete ``tier='operational'`` ``audit_log`` rows older than
     ``audit.operational_retention_days`` (#3469).  Returns the number of

{code_coordinator-0.5.582 → code_coordinator-0.5.584}/coord/commands/_common.py

@@ -330,7 +330,23 @@ def _save_config_snapshot(
                 pass
 
 
-def _load_config(path: Path | None, *, allow_thin_client: bool = True) -> Config:
+def resolve_and_load_config(path: Path | None, *, allow_thin_client: bool = True) -> Config:
+    """Resolve *path* (thin-client aware) and parse it — the one place this
+    question is asked, so every caller that needs a *freshly loaded* config
+    (not just the one-time CLI boot in :func:`_load_config`, which also
+    writes the DB snapshot and exits the process on a parse failure) gets
+    the SAME resolution rule rather than a second, drifting copy (#2096,
+    "one question, one answer"). :func:`coord.drive.Driver`'s per-poll
+    config reload (#1654) is the other caller: unlike `_load_config`, it
+    must never call ``sys.exit`` (a bad mid-run edit must warn, not kill the
+    drive) and must never re-run ``_save_config_snapshot`` every poll (a
+    DELETE+INSERT into the shared ``machines`` table, meant for "this
+    process just booted", not "it's still running 50 polls later").
+
+    Raises :class:`ConfigError` on any resolution/parse failure — never
+    exits, never echoes. Callers that want the CLI's print-and-exit-2
+    behavior still go through :func:`_load_config`.
+    """
     # Resolve the default location ($COORD_CONFIG → ~/.coord/coordinator.yml →
     # ./coordinator.yml) when no explicit --config was given, so `coord` works on
     # a machine without a repo checkout and isn't sensitive to the CWD.
@@ -366,24 +382,28 @@ def _load_config(path: Path | None, *, allow_thin_client: bool = True) -> Config
     # caller of ``_load_config`` legitimately wants thin-client resolution
     # (they ARE clients of the daemon's board) — this flag exists so ONLY
     # `coord serve`'s own bootstrap can opt out.
+    if allow_thin_client:
+        from coord.client import resolve_board_service  # noqa: PLC0415
+
+        svc = resolve_board_service()
+        if svc is not None:
+            from coord.client import fetch_remote_config  # noqa: PLC0415
+
+            try:
+                path = fetch_remote_config(svc)
+            except Exception as exc:  # noqa: BLE001 — do NOT fall through to
+                # load(path): path may point at a local file that happens to
+                # exist (the exact bypass this issue closes). Fail loudly
+                # instead of silently trusting whatever is on disk.
+                raise ConfigError(
+                    f"could not fetch config from {svc.url}: {exc}"
+                ) from exc
+    return load(path)
+
+
+def _load_config(path: Path | None, *, allow_thin_client: bool = True) -> Config:
     try:
-        if allow_thin_client:
-            from coord.client import resolve_board_service  # noqa: PLC0415
-
-            svc = resolve_board_service()
-            if svc is not None:
-                from coord.client import fetch_remote_config  # noqa: PLC0415
-
-                try:
-                    path = fetch_remote_config(svc)
-                except Exception as exc:  # noqa: BLE001 — do NOT fall through to
-                    # load(path): path may point at a local file that happens to
-                    # exist (the exact bypass this issue closes). Fail loudly
-                    # instead of silently trusting whatever is on disk.
-                    raise ConfigError(
-                        f"could not fetch config from {svc.url}: {exc}"
-                    ) from exc
-        cfg = load(path)
+        cfg = resolve_and_load_config(path, allow_thin_client=allow_thin_client)
     except ConfigError as e:
         click.echo(f"error: {e}", err=True)
         sys.exit(2)

{code_coordinator-0.5.582 → code_coordinator-0.5.584}/coord/drive.py

@@ -384,6 +384,33 @@ def _current_self_head() -> str | None:
     return self_freshness(fetch=False).head_sha
 
 
+def _load_config_for_drive(config_path: str) -> Any:
+    """Real default for `Driver.config_loader` (#1654): re-read
+    coordinator.yml fresh — ``config_path`` empty resolves the usual
+    ``$COORD_CONFIG`` → ``~/.coord/coordinator.yml`` → ``./coordinator.yml``
+    chain, AND the thin-client (board_service) redirect, exactly like the
+    construction-time load in ``coord.commands._common._load_config`` —
+    calls the SAME ``resolve_and_load_config`` helper that function now
+    wraps, so a mid-run reload can never resolve a *different* file (or
+    skip the thin-client branch an ordinary client is expected to take)
+    than the one this drive started with (#2096, "one question, one
+    answer"). Deliberately NOT ``_load_config`` itself: that one also
+    ``sys.exit``s on a parse failure (a bad mid-run edit must warn, never
+    kill the drive — see ``Driver._reload_config``) and re-writes the
+    shared ``machines`` DB snapshot (meant for a one-time boot, not every
+    poll).
+
+    Imported lazily: ``coord.commands._common`` pulls in ``click``/
+    ``httpx``, and every pure decision function in this module already
+    takes an already-loaded config rather than touching disk itself — this
+    keeps that true for every caller except the one that's explicitly an
+    I/O shell.
+    """
+    from coord.commands._common import resolve_and_load_config  # noqa: PLC0415
+
+    return resolve_and_load_config(Path(config_path) if config_path else None)
+
+
 def _bounded_tail(text: str, limit: int = _CAPTURED_OUTPUT_LIMIT) -> str:
     """*text*, or its last *limit* characters if longer — the tail, because
     the actionable line (a traceback's final "raise ...", a guard's remedy)
@@ -2111,6 +2138,39 @@ class Preflight:
     warnings: tuple[str, ...] = ()
 
 
+def check_usage_gate(
+    config: Any, usage_limits: PlanLimits | None,
+) -> str | None:
+    """Evaluate the usage gate — raise on ``block``, return a warn message
+    on ``warn``, ``None`` otherwise.
+
+    #1654: the SOLE place this question is asked, so :func:`preflight`'s
+    one-time call at the top of a run and :meth:`Driver._loop`'s per-poll
+    re-check (added for #1654, since the gate's own ``mode``/thresholds can
+    change mid-run) can never drift into two different answers for the
+    same inputs (#2096, "one question, one answer").
+
+    *config* of ``None`` skips the gate entirely (no ``usage_gate`` section
+    to consult) — mirrors every pre-#1466 caller.
+    """
+    if config is None:
+        return None
+    gate_cfg = config.usage_gate
+    limits = usage_limits if usage_limits is not None else PlanLimits(status="unknown")
+    gate_result = evaluate_usage_gate(limits, gate_cfg)
+    if gate_result.action == "block":
+        raise DriveError(
+            f"{gate_result.message} (usage_gate.mode: block) — refusing to "
+            "dispatch. Wait for the window to reset, or lower urgency by "
+            "raising the threshold / setting usage_gate.mode: warn in "
+            "coordinator.yml.",
+            EXIT_USAGE,
+        )
+    if gate_result.action == "warn":
+        return f"{gate_result.message} (usage_gate.mode: warn — proceeding anyway)"
+    return None
+
+
 def preflight(
     state: IssueState,
     opts: DriveOptions,
@@ -2165,20 +2225,9 @@ def preflight(
 
     warnings: list[str] = []
 
-    if config is not None:
-        gate_cfg = config.usage_gate
-        limits = usage_limits if usage_limits is not None else PlanLimits(status="unknown")
-        gate_result = evaluate_usage_gate(limits, gate_cfg)
-        if gate_result.action == "block":
-            raise DriveError(
-                f"{gate_result.message} (usage_gate.mode: block) — refusing to "
-                "dispatch. Wait for the window to reset, or lower urgency by "
-                "raising the threshold / setting usage_gate.mode: warn in "
-                "coordinator.yml.",
-                EXIT_USAGE,
-            )
-        if gate_result.action == "warn":
-            warnings.append(f"{gate_result.message} (usage_gate.mode: warn — proceeding anyway)")
+    gate_warning = check_usage_gate(config, usage_limits)
+    if gate_warning:
+        warnings.append(gate_warning)
 
     if not state.auto_loop:
         warnings.append(
@@ -5399,6 +5448,13 @@ class Driver:
     # without a real git checkout — same shape as *usage_prober* above.
     # Defaults to the real, local-only (`fetch=False`) probe.
     self_head_probe: Callable[[], str | None] = _current_self_head
+    # #1654: injected so tests can script a fake coordinator.yml reload
+    # sequence without real YAML I/O — same injection shape as
+    # *usage_prober*/*self_head_probe* above. Defaults to the real loader,
+    # re-reading ``self.opts.config_path`` (empty string resolves the usual
+    # ``$COORD_CONFIG`` → ``~/.coord/coordinator.yml`` → ``./coordinator.yml``
+    # chain) fresh every call — see ``_reload_config``.
+    config_loader: Callable[[str], Any] = _load_config_for_drive
 
     _run_log: Path | None = field(default=None, init=False, repr=False)
     # #2443: this session's own on-disk `coord` HEAD, captured once by
@@ -5426,6 +5482,17 @@ class Driver:
     # call, so it is only ever trustworthy read immediately after one, which
     # is exactly how `_loop` uses it.
     _last_run_output: str = field(default="", init=False, repr=False)
+    # #1654: latches so a coordinator.yml that fails to parse mid-run (an
+    # operator mid-edit, a truncated write) warns ONCE for the whole broken
+    # window, not once per poll — `_reload_config` sets this on a failed
+    # reload and clears it (with a short recovery log line) the first time a
+    # reload succeeds again.
+    _config_reload_broken: bool = field(default=False, init=False, repr=False)
+    # #1654: the last usage-gate WARN message this run already printed, so a
+    # `mode: warn` config that stays warn-worthy across many polls (the
+    # common case — the usage window doesn't reset every poll) logs once per
+    # DISTINCT message rather than spamming the identical line every tick.
+    _last_usage_gate_warning: str | None = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         self.out = self.out or sys.stdout
@@ -5473,6 +5540,68 @@ class Driver:
         except DriveStateError as exc:
             raise DriveError(str(exc), EXIT_USAGE) from exc
 
+    def _reload_config(self) -> None:
+        """Re-read coordinator.yml at the top of every poll (#1654).
+
+        `self.config` used to be a pure construction-time snapshot the poll
+        loop never revisited — a ladder/usage-gate edit made while a drive
+        was already running had no effect until the NEXT invocation, which
+        is exactly backwards for a lever (#1649's reroute mode, a tightened
+        threshold) most likely to be flipped reactively, mid-window, because
+        a drive is already running and burning credits. Cheap: one YAML
+        parse against a loop that already shells out to a `coord`
+        subprocess (`run_coord`) every tick.
+
+        A config that fails to parse (an operator mid-edit, a truncated
+        write) must never kill an otherwise-healthy run: this keeps the
+        last-good `self.config` and only warns — exactly ONCE for the whole
+        broken window (`_config_reload_broken` latches it), not once per
+        poll. `self.opts` (this invocation's own identity — the CLI flags)
+        is never touched here; only `self.config` is replaced.
+        """
+        try:
+            new_config = self.config_loader(self.opts.config_path)
+        except Exception as exc:  # noqa: BLE001 — a bad edit must never kill the drive
+            if not self._config_reload_broken:
+                self.warn(
+                    "coordinator.yml reload failed, keeping the last-known-"
+                    f"good config: {exc}"
+                )
+                self._config_reload_broken = True
+            return
+        if self._config_reload_broken:
+            self.log(
+                "coordinator.yml reload recovered — back to a fresh config"
+            )
+            self._config_reload_broken = False
+        self._log_config_change(self.config, new_config)
+        self.config = new_config
+
+    def _log_config_change(self, old: Any, new: Any) -> None:
+        """Narrate a reload that changes a decision this loop actually makes
+        (#1654), so a mid-run behaviour change is explicable from this run's
+        own log afterwards rather than looking like nondeterminism.
+
+        Deliberately narrow — only the usage gate, the one knob this loop
+        re-consults every poll (see `check_usage_gate` below) — rather than
+        a full recursive diff of the whole `Config` object, which would be
+        noisy (most fields are per-repo/machine topology this driver never
+        reads for THIS issue) and risks echoing a secret accidentally pasted
+        into coordinator.yml into this run's log.
+        """
+        old_gate, new_gate = old.usage_gate, new.usage_gate
+        old_shape = (old_gate.mode, old_gate.session_threshold_pct, old_gate.week_threshold_pct)
+        new_shape = (new_gate.mode, new_gate.session_threshold_pct, new_gate.week_threshold_pct)
+        if old_shape != new_shape:
+            self.log(
+                "coordinator.yml reload: usage_gate changed "
+                f"mode {old_gate.mode!r} -> {new_gate.mode!r}, "
+                f"session_threshold_pct {old_gate.session_threshold_pct!r} -> "
+                f"{new_gate.session_threshold_pct!r}, week_threshold_pct "
+                f"{old_gate.week_threshold_pct!r} -> {new_gate.week_threshold_pct!r} "
+                "— this run's next dispatch decision reflects the new config."
+            )
+
     # ── execution ───────────────────────────────────────────────────────
     def run_coord(self, args: tuple[str, ...], *, serialize_merge: bool = False) -> int:
         """Run a ``coord`` subcommand, echoing its output and appending to the log.
@@ -5751,12 +5880,15 @@ class Driver:
         if state is None:
             raise DriveError("could not read board state", EXIT_USAGE)
 
-        # #1466: probe ONCE here (not per-poll) — the underlying `claude -p
-        # "/usage"` call is itself cached ~60s (coord.usage_limits), but
-        # there's no reason to re-shell-out every loop iteration for a
-        # decision only made at the top of the run. Skipped entirely when
-        # the gate is off, so a `disabled` config never pays the subprocess
-        # cost.
+        # #1466: this is the ONE-TIME preflight check — raises/warns before
+        # the loop below ever starts, using whatever config this run was
+        # launched with. #1654 added a SECOND, per-poll re-check
+        # (`check_usage_gate`, called again right before every RUN action
+        # below) against `self.config` AS RELOADED THAT TICK, so a mid-run
+        # `usage_gate.mode`/threshold edit reaches the very next dispatch —
+        # this first call only ever decides whether the run gets to start at
+        # all. Skipped entirely when the gate is off, so a `disabled`
+        # config never pays the subprocess cost.
         usage_limits = (
             self.usage_prober() if self.config.usage_gate.mode != "disabled" else None
         )
@@ -5876,6 +6008,12 @@ class Driver:
                     )
                 return EXIT_DEADLINE
 
+            # #1654: re-read coordinator.yml before every decision this tick
+            # makes — see `_reload_config`'s own docstring for why (a
+            # construction-time snapshot made a mid-run ladder/usage-gate
+            # edit invisible for the drive's entire remaining life).
+            self._reload_config()
+
             state = self.read_state()
             if state is None:
                 self.sleeper(self.opts.poll)
@@ -6076,6 +6214,22 @@ class Driver:
                 self.log(action.label)
 
             if action.kind == RUN:
+                # #1654: re-check the usage gate against THIS poll's
+                # (possibly just-reloaded) config, not the snapshot
+                # `preflight()` consulted once before the loop started —
+                # `check_usage_gate` is the SAME question preflight asks, so
+                # a mid-run `usage_gate.mode` edit (warn -> block, or a
+                # tightened threshold) reaches the very next dispatch
+                # instead of only the next `coord drive` invocation.
+                usage_limits = (
+                    self.usage_prober()
+                    if self.config.usage_gate.mode != "disabled"
+                    else None
+                )
+                gate_warning = check_usage_gate(self.config, usage_limits)
+                if gate_warning and gate_warning != self._last_usage_gate_warning:
+                    self.warn(gate_warning)
+                    self._last_usage_gate_warning = gate_warning
                 rc = self.run_coord(
                     action.command, serialize_merge=action.serialize_merge
                 )

{code_coordinator-0.5.582 → code_coordinator-0.5.584}/coord/reports.py

@@ -4409,6 +4409,22 @@ def _validate_issue_cost_status(value: str) -> None:
 # the corpus level: if literally zero deprecation-category rows exist
 # anywhere (any route), collection cannot be confirmed live, so EVERY route
 # reads `no_data` rather than the misleadingly reassuring `zero_calls`.
+#
+# #1947's gate needs one more number this report didn't used to carry: NOT
+# just "zero calls ever recorded" but "zero calls across a window of at
+# least 30 days" — a route deprecated yesterday with zero calls so far is
+# not evidence of anything yet. `observed_secs`/`eligible` below answer that
+# without a second config read or a second place to get it wrong (#2085):
+# `observed_secs` is seeded from the EARLIEST deprecation-category row across
+# the whole corpus (a lower bound on how long telemetry has been live — it
+# can only ever UNDERSTATE the true window, never overstate it, which is the
+# safe direction for a retirement gate) and then capped at
+# `audit.operational_retention_days` — resolved by `run_deprecated_routes`
+# through `coord.audit.resolve_operational_retention_days`, the same cap that
+# module's own sweep enforces, and passed DOWN into the pure fold rather than
+# read inside it — because a row older than retention could have been swept
+# without a trace, so claiming a window longer than retention allows would
+# be exactly the "belief" #1945/#1947 exist to rule out.
 
 DEPRECATED_ROUTES_COLUMNS = [
     "route",
@@ -4417,6 +4433,8 @@ DEPRECATED_ROUTES_COLUMNS = [
     "last_call",
     "call_count",
     "clients",
+    "observed_secs",
+    "eligible",
 ]
 
 # One entry per DEPRECATED_ROUTES_COLUMNS entry, same order (#1760).
@@ -4427,6 +4445,8 @@ DEPRECATED_ROUTES_COLUMN_META = [
     ColumnMeta(id="last_call", label="Last Call", kind="timestamp"),
     ColumnMeta(id="call_count", label="Calls", kind="int", align="right"),
     ColumnMeta(id="clients", label="Clients", kind="list"),
+    ColumnMeta(id="observed_secs", label="Observed For", kind="duration", align="right"),
+    ColumnMeta(id="eligible", label="Retirement", kind="enum"),
 ]
 
 # `status` values.  `no_data` and `zero_calls` are BOTH "nothing seen for
@@ -4436,12 +4456,26 @@ DEPRECATED_ROUTE_NO_DATA = "no_data"
 DEPRECATED_ROUTE_ZERO_CALLS = "zero_calls"
 DEPRECATED_ROUTE_IN_USE = "in_use"
 
+# `eligible` values (#1947) — the gate's own verdict, never the belief of
+# whoever is reading the table. `not_yet` covers every disqualifying case
+# (in_use, no_data, or zero_calls but not observed long enough) on purpose:
+# a reader who only checks for the literal string `eligible` can never be
+# fooled by a value this report predates adding.
+DEPRECATED_ROUTE_ELIGIBLE = "eligible"
+DEPRECATED_ROUTE_NOT_ELIGIBLE = "not_yet"
+
+# The gate's own number (issue #1947): "a window of at least 30 days".
+# Named so it cannot silently drift between the report and anything that
+# later re-checks its verdict.
+DEPRECATION_RETIREMENT_WINDOW_DAYS = 30.0
+
 
 def fold_deprecated_routes(
     entries: Iterable[Mapping[str, Any]],
     generated_at: float,
     *,
     routes: Mapping[str, str] | None = None,
+    retention_days: float = 0.0,
 ) -> ReportResult:
     """Fold already-fetched deprecation-telemetry audit rows into a
     per-route snapshot.  **Pure** — no DB, no daemon, no clock.
@@ -4456,6 +4490,18 @@ def fold_deprecated_routes(
     report reads it rather than redeclaring it (the ``routes=`` override
     exists purely so this stays a pure function a test can call without
     importing the daemon module).
+
+    ``retention_days`` is a PLAIN NUMBER here, defaulting to ``0``
+    (uncapped), and is deliberately NOT resolved from ``coordinator.yml`` by
+    this function: reading the ambient config would make a function
+    documented as pure answer differently on a machine that happens to have
+    a ``coordinator.yml`` with a small ``audit.operational_retention_days``
+    than on one that has none — the host-dependent-result class #2170 exists
+    to keep out of this suite. :func:`run_deprecated_routes` (the impure
+    runner, which already owns the clock and the DB walk) resolves it from
+    :func:`coord.audit.resolve_operational_retention_days` and passes it
+    down, exactly as ``run_drive_queue_status`` resolves ``queue_escalation``
+    for ``fold_drive_queue_status``.
     """
     if routes is None:
         from coord.serve_app import RPC_SUPERSEDED_BY_RESOURCE  # noqa: PLC0415
@@ -4464,6 +4510,14 @@ def fold_deprecated_routes(
 
     entries = list(entries)
     any_data = bool(entries)
+    # `or generated_at` would be wrong here: a `ts` of exactly `0.0` (epoch,
+    # or a deliberately-zeroed test fixture) is falsy and must still count
+    # as a real, very-old timestamp — not get silently replaced by "now".
+    earliest_ts = (
+        min(e.get("ts") if e.get("ts") is not None else generated_at for e in entries)
+        if entries
+        else None
+    )
 
     by_route: dict[str, list[Mapping[str, Any]]] = {r: [] for r in routes}
     for entry in entries:
@@ -4495,6 +4549,18 @@ def fold_deprecated_routes(
             status = DEPRECATED_ROUTE_ZERO_CALLS
         else:
             status = DEPRECATED_ROUTE_NO_DATA
+
+        observed_secs: float | None = None
+        eligible = DEPRECATED_ROUTE_NOT_ELIGIBLE
+        if status == DEPRECATED_ROUTE_ZERO_CALLS and earliest_ts is not None:
+            # `any_data` is True here, so `earliest_ts` is always set — the
+            # `is not None` above is what lets a type checker see that too.
+            observed_secs = max(0.0, generated_at - earliest_ts)
+            if retention_days > 0:
+                observed_secs = min(observed_secs, retention_days * 86400.0)
+            if observed_secs >= DEPRECATION_RETIREMENT_WINDOW_DAYS * 86400.0:
+                eligible = DEPRECATED_ROUTE_ELIGIBLE
+
         rows.append(
             {
                 "route": route,
@@ -4503,6 +4569,8 @@ def fold_deprecated_routes(
                 "last_call": last_call,
                 "call_count": len(calls),
                 "clients": clients,
+                "observed_secs": observed_secs,
+                "eligible": eligible,
             }
         )
 
@@ -4517,6 +4585,14 @@ def fold_deprecated_routes(
             "`no_data`, not `zero_calls` — treat it as UNKNOWN, never as "
             "evidence it is safe to retire."
         )
+    if any_data and 0 < retention_days < DEPRECATION_RETIREMENT_WINDOW_DAYS:
+        notes.append(
+            f"audit.operational_retention_days is {retention_days:g}, below "
+            f"the {DEPRECATION_RETIREMENT_WINDOW_DAYS:g}-day window #1947's "
+            "retirement gate requires — a `zero_calls` route can never "
+            "accumulate enough trustworthy observed time to read `eligible` "
+            "until this is raised (or disabled with `0`)."
+        )
 
     return ReportResult(
         report_id="deprecated-routes",
@@ -4540,29 +4616,49 @@ def run_deprecated_routes(
     now: float | None = None,
     fetch: Callable[[float], tuple[Sequence[Mapping[str, Any]], bool]] | None = None,
     routes: Mapping[str, str] | None = None,
+    retention_days: float | None = None,
 ) -> ReportResult:
     """Fetch every recorded deprecated-RPC-route call and fold it (#1945).
 
-    ``fetch``/``routes`` are test seams (mirrors every other ``run_*``'s
-    ``fetch=`` seam). Production always walks the FULL audit history
-    (``since=0``), never a recent window — "this route has not been called
-    in months" is exactly the number #1945 exists to produce, and a
-    windowed report would silently hide the very evidence retirement needs.
-    ``query_audit_log`` orders newest-first, so ``last_call`` is accurate
-    even if the walk is truncated by the page cap; only the full
-    client/version set and total ``call_count`` could then be incomplete,
-    which is called out in a note exactly like every other truncated fold
-    in this module.
+    ``fetch``/``routes``/``retention_days`` are test seams (mirrors every
+    other ``run_*``'s ``fetch=`` seam). Production always walks the FULL
+    audit history (``since=0``), never a recent window — "this route has not
+    been called in months" is exactly the number #1945 exists to produce,
+    and a windowed report would silently hide the very evidence retirement
+    needs. ``query_audit_log`` orders newest-first, so ``last_call`` is
+    accurate even if the walk is truncated by the page cap; ``clients``/
+    ``call_count``, and ``observed_secs``/``eligible`` (#1947) — which is
+    seeded from the OLDEST entry in the walk — could then UNDERSTATE the
+    true observed window (the oldest rows are exactly what truncation drops
+    first), which is called out in a note exactly like every other truncated
+    fold in this module. Understating is the safe direction for a
+    retirement gate: it can only make `eligible` harder to earn, never
+    easier.
+
+    ``retention_days`` defaults to :func:`coord.audit.
+    resolve_operational_retention_days` — the SAME number
+    ``coord.audit.sweep_operational_retention`` caps itself to, read here
+    (the impure runner that already owns the clock and the DB walk) rather
+    than inside the pure fold, so a direct fold caller never gets a
+    host-dependent answer. Passing it explicitly is the test seam.
     """
     generated_at = time.time() if now is None else float(now)
+    if retention_days is None:
+        from coord.audit import resolve_operational_retention_days  # noqa: PLC0415
+
+        retention_days = resolve_operational_retention_days()
     fetch_fn = _default_fetch_deprecation_entries if fetch is None else fetch
     entries, truncated = fetch_fn(generated_at)
-    result = fold_deprecated_routes(entries, generated_at, routes=routes)
+    result = fold_deprecated_routes(
+        entries, generated_at, routes=routes, retention_days=retention_days
+    )
     if truncated:
         result.notes.append(
             "Audit history walk hit its page cap before covering the full "
             "history — `clients`/`call_count` may be missing older calls, "
-            "though `last_call` (newest-first order) is still accurate."
+            "and `observed_secs` may understate the true window (the "
+            "oldest rows are dropped first), though `last_call` "
+            "(newest-first order) is still accurate."
         )
     return result
 
@@ -4959,7 +5055,14 @@ DEPRECATED_ROUTES = ReportDef(
         "count — evidence for retirement instead of belief (#1945). "
         "`status` distinguishes `in_use` from `zero_calls` (a real, "
         "actionable signal) from `no_data` (telemetry not confirmed live — "
-        "never safe to read as `zero_calls`)."
+        "never safe to read as `zero_calls`). `eligible` is #1947's own "
+        "gate verdict: `eligible` only when `status` is `zero_calls` AND "
+        "`observed_secs` (capped at `audit.operational_retention_days`, "
+        "never a config-trusting guess) covers at least 30 days — `not_yet` "
+        "otherwise. A route's own `eligible` reading is still only one of "
+        "#1947's three gate conditions; `coord release verify` showing "
+        "every lane past the client migration is the other, checked "
+        "separately."
     ),
     params=(),
     run=run_deprecated_routes,