code-coordinator 0.5.93__tar.gz → 0.5.95__tar.gz

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/PKG-INFO

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

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

@@ -529,6 +529,7 @@ tests/test_config.py
 tests/test_config_acceptance.py
 tests/test_config_audit.py
 tests/test_config_pricing.py
+tests/test_config_snapshot_noncanonical_2208.py
 tests/test_config_usage_gate.py
 tests/test_conflict_fix.py
 tests/test_conflict_fix_semantic.py

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/code_coordinator.egg-info/scm_file_list.json

@@ -559,6 +559,7 @@
     "tests/test_config_acceptance.py",
     "tests/test_config_audit.py",
     "tests/test_config_pricing.py",
+    "tests/test_config_snapshot_noncanonical_2208.py",
     "tests/test_config_usage_gate.py",
     "tests/test_conflict_fix.py",
     "tests/test_conflict_fix_semantic.py",

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.93",
+  "tag": "0.5.95",
   "distance": 0,
-  "node": "g827590698265fe1d05e3d77e84c364f63d767405",
+  "node": "g100d9f74dd79bd61b86812c4dd3930e4cc7079ce",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-15"

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/coord/acceptance.py

@@ -22,7 +22,7 @@ import json
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Literal
 
 import yaml
 
@@ -1105,3 +1105,46 @@ def clear_expected_red_via_pr(
         f"cleared expected_red for #{issue_number}: {', '.join(sorted(ids))} "
         f"(PR #{pr['number']})"
     )
+
+
+ExpectedRedClearStatus = Literal["cleared", "no_op", "pending_retry", "failed"]
+
+
+def classify_expected_red_clear_result(msg: str) -> ExpectedRedClearStatus:
+    """#2266 review (blocking finding 2): the single source of truth for
+    interpreting :func:`clear_expected_red_via_pr`'s return string.
+
+    Before this, ``coord.merge_queue._maybe_clear_expected_red`` and
+    ``coord.commands.acceptance._clear_stuck_expected_red`` each carried
+    their own ``msg.startswith("cleared expected_red")`` check — two
+    independent implementations of "did the clear succeed?" that agreed
+    today but could silently desync the moment either
+    :func:`clear_expected_red_via_pr`'s wording changed (the exact "One
+    question, one answer" split-brain the epic #2096 review checklist
+    warns about). Both call sites now classify through this function.
+
+    Returns one of four outcomes, not a bare bool — a binary
+    cleared/not-cleared collapsed two very different "not cleared" cases
+    into one (#2266 review, blocking finding 1):
+
+    * ``"cleared"`` — the PR opened *and* merged; entries are gone.
+    * ``"no_op"`` — there was nothing to clear in the first place (no
+      manifest found for this issue, or the issue has no ``expected_red``
+      entries at all). This is the *common* case for an ordinary
+      oracle-loop merge whose issue was never part of a deliberately-red
+      slice — it must never read as a failure.
+    * ``"pending_retry"`` — the clearing PR opened but did not merge yet
+      (branch protection / required checks pending); the caller already
+      knows this will retry on the next merge, not a hard failure.
+    * ``"failed"`` — a genuine failure: everything ``clear_expected_red_via_pr``'s
+      docstring says degrades to a ``"warning: ..."``-prefixed string
+      (unresolvable branch tip, a commit/PR-open/PR-merge exception, an
+      unsupported ``gh_ops``, a JSON manifest, or unchanged text).
+    """
+    if msg.startswith("cleared expected_red"):
+        return "cleared"
+    if msg.startswith("no expected_red entries"):
+        return "no_op"
+    if "did not merge" in msg and "will retry on the next merge" in msg:
+        return "pending_retry"
+    return "failed"

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/coord/commands/_common.py

@@ -27,7 +27,13 @@ from typing import TYPE_CHECKING
 
 import click
 
-from coord.config import Config, ConfigError, load, resolve_config_path
+from coord.config import (
+    Config,
+    ConfigError,
+    is_canonical_config_path,
+    load,
+    resolve_config_path,
+)
 
 if TYPE_CHECKING:  # pragma: no cover — typing only
     from collections.abc import Iterator
@@ -100,7 +106,55 @@ _CONFIG_OPTION = click.option(
 )
 
 
-def _save_config_snapshot(config: Config) -> None:
+def _note_withheld_snapshot(config: Config, config_path: Path) -> None:
+    """Tell the operator that the #2208 guard just withheld a snapshot — but
+    only when withholding it actually changed the outcome.
+
+    Silence is what turned the original incident into an hour of
+    misdiagnosis: the fleet's ``machines`` table said ``ci-runner`` and
+    nothing anywhere said why. So when a non-canonical ``--config`` would
+    have *replaced a populated table with a different fleet* — the exact
+    shape of that incident — say so on stderr.
+
+    Everything else stays quiet, and that restraint is load-bearing rather
+    than cosmetic. ``--config <tmpfile>`` is the normal way to run coord
+    against a scratch config: CI stubs, the config *validator* in
+    ``scripts/azure-workers/coordinator-machine.py``, and every one of this
+    repo's ~110 CLI test modules. Emitting a note on each of those would
+    have made the guard a per-invocation nag, and — because Click's
+    ``CliRunner`` folds stderr into ``result.output`` — would have corrupted
+    the machine-readable stdout of commands like ``coord plans --json`` and
+    ``coord scorecard --json`` for anyone parsing combined output.
+
+    A skip with nothing to clobber (empty table, or a table that already
+    matches) withheld nothing observable, so it warrants no words.
+    """
+    try:
+        from coord.db import get_connection
+        conn = get_connection()
+        existing = [
+            str(row[0])
+            for row in conn.execute("SELECT name FROM machines ORDER BY name")
+        ]
+    except Exception:  # noqa: BLE001 — advisory only; never break the command
+        return
+    if not existing:
+        # Nothing to protect: no snapshot has ever landed here (a fresh
+        # host, or a CI runner whose DB only exists for this one command).
+        return
+    if existing == sorted(m.name for m in config.machines):
+        # The override names the same fleet — the write would have been a
+        # no-op, so the skip cost the operator nothing.
+        return
+    click.echo(
+        f"note: --config points at a non-canonical path ({config_path}); "
+        f"leaving the shared machines/pipeline snapshot untouched (#2208). "
+        f"Fleet machines on record: {', '.join(existing)}.",
+        err=True,
+    )
+
+
+def _save_config_snapshot(config: Config, config_path: Path | None = None) -> None:
     """Persist machine + pipeline metadata to the DB so dashboards can read it.
 
     Writes:
@@ -111,6 +165,13 @@ def _save_config_snapshot(config: Config) -> None:
 
     The pipeline keys let the TUI Pipeline panel pick up coordinator.yml
     settings without having to parse YAML itself.
+
+    *config_path* is the file *config* was actually loaded from. When given
+    and it is not the canonical resolution (see
+    ``coord.config.is_canonical_config_path``), the write is skipped
+    entirely — see the #2208 guard below. Callers that omit it (mainly
+    direct unit tests exercising the write itself) get the pre-#2208
+    behavior: always write.
     """
     # #584: a thin client (board_service configured) must not create/write a
     # local DB — the daemon/host owns the config snapshot.  On the host
@@ -118,6 +179,14 @@ def _save_config_snapshot(config: Config) -> None:
     from coord.client import resolve_board_service
     if resolve_board_service() is not None:
         return
+    # #2208: an explicit `--config <file>` pointed away from the fleet's real
+    # config (a scratch fixture, a CI-only stub) must not be treated as a
+    # request to redefine the shared `machines` table — that table is global
+    # state every client's `/board` and the TUI read, not something a single
+    # throwaway invocation should own.
+    if config_path is not None and not is_canonical_config_path(config_path):
+        _note_withheld_snapshot(config, config_path)
+        return
     conn = None
     try:
         from coord.db import get_connection
@@ -270,7 +339,7 @@ def _load_config(path: Path | None) -> Config:
     except ConfigError as e:
         click.echo(f"error: {e}", err=True)
         sys.exit(2)
-    _save_config_snapshot(cfg)
+    _save_config_snapshot(cfg, path)
     return cfg
 
 

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/coord/commands/acceptance.py

@@ -50,6 +50,7 @@ from coord.acceptance_drivers import DriverError, run_driver
 from coord.commands._common import _CONFIG_OPTION, _load_config
 from coord.comments import format_needs_attention
 from coord.dispatch import DispatchRefused
+from coord.models import Repo
 
 
 @click.group("acceptance")
@@ -642,12 +643,42 @@ def acceptance_record(
         "merge` right after that issue's fix merges) may have failed, or "
         "the fix landed by some other path. A long-lived expected_red "
         "entry is exactly the invisible debt this command exists to "
-        "surface."
+        "surface. #2266: `--clear` acts on it — for every STUCK entry this "
+        "listing finds, invoke the same `clear_expected_red_via_pr` PR "
+        "path `coord merge` uses, so a registry stuck because the merge-"
+        "time trust-gate guards never fired (acceptance never recorded, or "
+        "the PR merged out of band) has a re-fire path instead of only a "
+        "detector. Never touches an entry whose issue is still open — "
+        "those are read as legitimately red, not stuck."
     ),
 )
 @click.argument("repo")
 @_CONFIG_OPTION
-def acceptance_expected_red(repo: str, config_path: Path) -> None:
+@click.option(
+    "--clear", "do_clear", is_flag=True, default=False,
+    help=(
+        "Open+merge the expected_red-clearing PR for every STUCK entry "
+        "this listing finds (issue closed, entries still live). Skips — "
+        "never clears — any entry whose issue is still open."
+    ),
+)
+@click.option(
+    "--issue", "only_issue", type=int, default=None,
+    help="With --clear, restrict clearing to this issue number.",
+)
+def acceptance_expected_red(
+    repo: str, config_path: Path, do_clear: bool, only_issue: int | None,  # noqa: FBT001
+) -> None:
+    if only_issue is not None and not do_clear:
+        # #2266 review nit: `--issue` only narrows what `--clear` acts on
+        # (per its own help text) — silently accepting it without `--clear`
+        # looks like it did something when it didn't.
+        click.echo(
+            "warning: --issue has no effect without --clear; the listing "
+            "below covers every issue.",
+            err=True,
+        )
+
     cfg = _load_config(config_path)
     repo_entry = cfg.repo(repo)
     if repo_entry is None:
@@ -660,23 +691,117 @@ def acceptance_expected_red(repo: str, config_path: Path) -> None:
         return
 
     total = 0
+    # #2266: STUCK entries found while rendering the listing above — the
+    # exact set `--clear` acts on, so the remedy can never drift from the
+    # detector that names the debt.
+    stuck: list[tuple[str, int, frozenset[str]]] = []
     for ms, by_issue in sorted(by_ms.items()):
         click.echo(f"{ms}:")
         for issue_number, ids in sorted(by_issue.items()):
             total += len(ids)
             closed_note = ""
+            is_stuck = False
             try:
                 issue_data = github_ops.get_issue(repo_entry.github, issue_number)
                 if str((issue_data or {}).get("state", "")).lower() == "closed":
                     closed_note = "  [STUCK: issue is closed but entries remain]"
+                    is_stuck = True
             except Exception:  # noqa: BLE001 — a lookup hiccup shouldn't hide the entry itself
                 pass
             click.echo(
                 f"  #{issue_number}: {', '.join(sorted(ids))}{closed_note}"
             )
+            if is_stuck:
+                stuck.append((ms, issue_number, ids))
     click.echo(f"\n{total} expected_red test-id(s) across "
                f"{sum(len(v) for v in by_ms.values())} issue(s).")
 
+    if not do_clear:
+        return
+
+    _clear_stuck_expected_red(repo, repo_entry, stuck, only_issue)
+
+
+def _clear_stuck_expected_red(
+    repo: str, repo_entry: Repo, stuck: list[tuple[str, int, frozenset[str]]],
+    only_issue: int | None,
+) -> None:
+    """#2266: the remedy half of `coord acceptance expected-red --clear`.
+
+    Acts ONLY on *stuck* — the STUCK (issue closed, entries still live) set
+    the listing above already computed — never on an issue whose entries
+    are legitimately still red (still open). `--issue` narrows to one
+    issue but does not widen scope: naming an open issue's number here
+    finds nothing to clear, same as naming one that isn't in *stuck* at
+    all.
+
+    Exits non-zero when at least one entry hard-fails to clear (#2266
+    review, non-blocking finding: without this, a caller scripting this
+    command in CI/cron could only detect a fully-failed run by reading
+    stdout or separately querying the audit log).
+    """
+    from coord.acceptance import (  # noqa: PLC0415
+        classify_expected_red_clear_result,
+        clear_expected_red_via_pr,
+    )
+    from coord.audit import record_audit  # noqa: PLC0415
+
+    if only_issue is not None:
+        stuck = [s for s in stuck if s[1] == only_issue]
+        if not stuck:
+            click.echo(
+                f"\n--issue {only_issue}: not STUCK (open, or no "
+                "expected_red entries recorded for it) — nothing to clear."
+            )
+            return
+
+    if not stuck:
+        click.echo("\nno STUCK entries to clear.")
+        return
+
+    click.echo(f"\nclearing {len(stuck)} STUCK issue(s)...")
+    # #2266 review (blocking finding 2): classify through the same shared
+    # helper `coord.merge_queue._maybe_clear_expected_red` uses, instead of
+    # each surface independently re-deriving "did this succeed?" from the
+    # message text — a split-brain waiting to happen if the message
+    # wording ever changes (epic #2096's "one question, one answer").
+    any_failed = False
+    for ms, issue_number, ids in stuck:
+        msg = clear_expected_red_via_pr(
+            repo_entry.github, repo, repo_entry.default_branch, issue_number,
+            gh_ops=github_ops,
+        )
+        click.echo(f"  #{issue_number}: {msg}")
+        status = classify_expected_red_clear_result(msg)
+        if status == "no_op":
+            # These entries were just listed as STUCK, so this should be
+            # rare (e.g. a race — another process already cleared them) —
+            # but it's still not a failure worth a durable audit row.
+            continue
+        if status == "failed":
+            any_failed = True
+        event_type = {
+            "cleared": "expected_red_clear",
+            "pending_retry": "expected_red_clear_pending",
+            "failed": "expected_red_clear_failed",
+        }[status]
+        # #2266 scope 2: a failed clear must land somewhere durable — the
+        # audit log — so the next pass over this repo can say "this
+        # registry is still stuck" without anyone re-reading this output.
+        record_audit(
+            tier="business",
+            category="acceptance",
+            event_type=event_type,
+            actor="user",
+            summary=f"coord acceptance expected-red --clear {repo} #{issue_number}: {msg}",
+            repo=repo,
+            issue=issue_number,
+            details={"ms": ms, "test_ids": sorted(ids), "result": msg},
+        )
+
+    if any_failed:
+        sys.exit(1)
+
 
 def _acceptance_record_local(
     repo: str,

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/coord/config.py

@@ -51,6 +51,27 @@ def resolve_config_path() -> Path:
             return candidate
     return USER_CONFIG_PATH
 
+
+def is_canonical_config_path(path: Path) -> bool:
+    """Whether *path* is what :func:`resolve_config_path` resolves to *right now*.
+
+    #2208: a coord command run with an explicit ``--config <file>`` pointed
+    somewhere other than the fleet's real config — a scratch fixture, a
+    CI-only stub someone wrote specifically so ``coord.config.load()`` has
+    something to parse — is not a request to redefine the fleet. This gates
+    the shared machines/pipeline DB snapshot (``_save_config_snapshot`` in
+    ``coord/commands/_common.py``): only a *path* that matches the ordinary
+    resolution order ($COORD_CONFIG → ``~/.coord/coordinator.yml`` →
+    ``./coordinator.yml``) counts as canonical and is allowed to overwrite
+    that shared table. An explicit ``--config`` that happens to name the
+    same file the default resolution would have picked still counts as
+    canonical — this only catches a genuine *override*.
+    """
+    candidate = Path(path).expanduser().resolve()
+    canonical = resolve_config_path().expanduser().resolve()
+    return candidate == canonical
+
+
 # Safety-by-default: repos without explicit worker_permissions get this deny-list.
 DEFAULT_DENY_COMMANDS: list[str] = [
     "Bash(gh *)",

{code_coordinator-0.5.93 → code_coordinator-0.5.95}/coord/merge_queue.py

@@ -4387,26 +4387,36 @@ def _test_author_effective_issue_number(entry: QueuedMerge, board) -> int | None
     return None
 
 
-def _issue_has_expected_red_entries(entry: QueuedMerge, gh_ops: GhOps) -> bool:
-    """#2199 review (blocking finding 2): whether *entry*'s issue has at
-    least one ``expected_red`` entry recorded against it in some
-    ``ms-*/manifest.yml`` on ``entry.target_branch`` — the scope check
-    that keeps :func:`_maybe_clear_expected_red`'s loud "no passing
-    trust-gate verdict" diagnostic from firing on every ordinary
-    ``CLOSES_ISSUE_TYPES`` merge fleet-wide (no driver configured, no
-    oracle-opted-in milestone, an ``oracle:exempt`` issue — none of which
-    ever populate ``expected_red`` for their issue, #2191). Those merges
-    have nothing here for ``coord acceptance record`` to ever have cleared
-    and never will; before this check, the diagnostic branch below could
-    not tell them apart from an issue that genuinely IS in scope and
-    genuinely IS stuck red, so it printed the same actionable-looking
-    (and, for a driverless repo, un-followable) advice on every single one.
+def _expected_red_ids_for_entry(entry: QueuedMerge, gh_ops: GhOps) -> frozenset[str]:
+    """#2199 review (blocking finding 2) / #2266 review (non-blocking
+    finding): the ``expected_red`` test ids, if any, recorded against
+    *entry*'s issue in some ``ms-*/manifest.yml`` on ``entry.target_branch``.
+
+    Two call sites need this:
+
+    * :func:`_issue_has_expected_red_entries` — the scope check that keeps
+      :func:`_maybe_clear_expected_red`'s loud "no passing trust-gate
+      verdict" diagnostic from firing on every ordinary
+      ``CLOSES_ISSUE_TYPES`` merge fleet-wide (no driver configured, no
+      oracle-opted-in milestone, an ``oracle:exempt`` issue — none of which
+      ever populate ``expected_red`` for their issue, #2191). Those merges
+      have nothing here for ``coord acceptance record`` to ever have
+      cleared and never will; before this check, the diagnostic branch
+      below could not tell them apart from an issue that genuinely IS in
+      scope and genuinely IS stuck red, so it printed the same
+      actionable-looking (and, for a driverless repo, un-followable)
+      advice on every single one.
+    * :func:`_maybe_clear_expected_red`'s clear branch, to put the actual
+      test ids (not just a pr/branch pair) into the durable audit row —
+      matching ``coord acceptance expected-red --clear``'s
+      ``details["test_ids"]`` so a merge-queue-triggered clear is just as
+      correlatable back to specific stuck tests as a CLI-triggered one.
 
     Reuses the exact API-only lookup ``coord.acceptance.
     clear_expected_red_via_pr`` already performs on the success path —
     best-effort/read-only like the rest of this sweep: any lookup failure
     (unreachable API, older ``gh_ops`` stub missing the list/get methods)
-    reads as "not in scope", matching :func:`coord.acceptance.
+    reads as "nothing recorded", matching :func:`coord.acceptance.
     find_ms_manifest_for_issue_via_api`'s own fail-soft posture.
     """
     from coord.acceptance import find_ms_manifest_for_issue_via_api  # noqa: PLC0415
@@ -4416,11 +4426,59 @@ def _issue_has_expected_red_entries(entry: QueuedMerge, gh_ops: GhOps) -> bool:
             entry.repo_github, entry.target_branch, entry.issue_number, gh_ops=gh_ops,
         )
     except Exception:  # noqa: BLE001 — best-effort, same posture as callers
-        return False
+        return frozenset()
     if found is None:
-        return False
+        return frozenset()
     _path, _text, _blob_sha, data = found
-    return bool(data.expected_red.get(entry.issue_number))
+    return frozenset(data.expected_red.get(entry.issue_number, frozenset()))
+
+
+def _issue_has_expected_red_entries(entry: QueuedMerge, gh_ops: GhOps) -> bool:
+    """Whether *entry*'s issue has at least one ``expected_red`` entry
+    recorded against it. See :func:`_expected_red_ids_for_entry` for why
+    this scope check exists."""
+    return bool(_expected_red_ids_for_entry(entry, gh_ops))
+
+
+def _record_expected_red_audit(
+    entry: QueuedMerge,
+    event_type: str,
+    message: str,
+    *,
+    test_ids: frozenset[str] | None = None,
+) -> None:
+    """#2266: durable half of an `expected_red` clear/skip/failure — a
+    `MergeEvent` alone only reaches the operator as a `coord merge` output
+    line that scrolls past (issue #2266's framing: "nothing durable,
+    nothing re-checked"). ``record_audit`` gives the same outcomes
+    (cleared, skipped for one of two distinct reasons, pending retry, or
+    attempted-and-failed) a queryable row (`coord audit` / `query_audit_log`)
+    so a repo with a stuck registry is discoverable without re-reading
+    merge output. Best-effort like every other audit call site in this
+    module — ``record_audit`` itself never raises.
+
+    *test_ids*, when given, lands in ``details["test_ids"]`` — matching the
+    CLI path's (`coord.commands.acceptance._clear_stuck_expected_red`)
+    audit payload, per #2266 review non-blocking finding: without it,
+    merge-queue-triggered audit rows were harder to correlate back to the
+    specific stuck test ids than CLI-triggered ones.
+    """
+    details: dict[str, object] = {
+        "pr_number": entry.pr_number, "target_branch": entry.target_branch,
+    }
+    if test_ids:
+        details["test_ids"] = sorted(test_ids)
+    record_audit(
+        tier="business",
+        category="acceptance",
+        event_type=event_type,
+        actor="system",
+        summary=f"{entry.repo_name}#{entry.issue_number}: {message}",
+        repo=entry.repo_name,
+        issue=entry.issue_number,
+        assignment_id=entry.assignment_id,
+        details=details,
+    )
 
 
 def _maybe_clear_expected_red(entry: QueuedMerge, board, gh_ops: GhOps) -> MergeEvent | None:
@@ -4462,21 +4520,29 @@ def _maybe_clear_expected_red(entry: QueuedMerge, board, gh_ops: GhOps) -> Merge
         )
     acceptance_state = getattr(work, "acceptance_state", None)
     if acceptance_state != "passed":
-        if not _issue_has_expected_red_entries(entry, gh_ops):
+        ids = _expected_red_ids_for_entry(entry, gh_ops)
+        if not ids:
             # Not in scope for the oracle loop at all — the pre-#2199
             # silent no-op is still correct here, not a regression (see
             # the docstring above and #2199 review finding 2).
             return None
-        return MergeEvent(
-            entry, "expected_red_clear_skipped_no_acceptance",
+        msg = (
             f"no passing trust-gate verdict recorded on {work.assignment_id} "
             f"(acceptance_state={acceptance_state!r}) — the external `coord "
             "acceptance record` re-run either never happened or did not "
             "pass; skipping expected_red clear. Run `coord acceptance "
             f"record --repo {entry.repo_name} --issue {entry.issue_number} "
             "--sha <merged sha>` by hand, or re-drive the issue, to clear "
-            "any listed entries.",
+            "any listed entries."
+        )
+        # #2266: distinct from the SHA-mismatch guard below — "acceptance
+        # never recorded" and "recorded SHA is stale" are different
+        # problems with different fixes, so they get distinct event types
+        # rather than reaching the operator as the same silence.
+        _record_expected_red_audit(
+            entry, "expected_red_clear_skipped_no_acceptance", msg, test_ids=ids,
         )
+        return MergeEvent(entry, "expected_red_clear_skipped_no_acceptance", msg)
     acceptance_sha = getattr(work, "acceptance_sha", None)
     if acceptance_sha is None or acceptance_sha != entry.branch_head_sha:
         # The recorded trust-gate verdict isn't for the exact commit that
@@ -4486,20 +4552,56 @@ def _maybe_clear_expected_red(entry: QueuedMerge, board, gh_ops: GhOps) -> Merge
         # fresh SHA and this issue's fix merges again... though ordinarily
         # a merge only happens once per issue, so a mismatch here more
         # likely means acceptance was simply never recorded for this SHA.
-        return MergeEvent(
-            entry, "expected_red_clear_skipped",
+        msg = (
             "acceptance_sha does not match the merged commit — skipping "
             "expected_red clear (re-run `coord acceptance record` against "
-            "the merged SHA if entries should have cleared)",
+            "the merged SHA if entries should have cleared)"
         )
+        _record_expected_red_audit(
+            entry, "expected_red_clear_skipped_sha_mismatch", msg,
+            test_ids=_expected_red_ids_for_entry(entry, gh_ops),
+        )
+        return MergeEvent(entry, "expected_red_clear_skipped", msg)
 
-    from coord.acceptance import clear_expected_red_via_pr  # noqa: PLC0415
+    from coord.acceptance import (  # noqa: PLC0415
+        classify_expected_red_clear_result,
+        clear_expected_red_via_pr,
+    )
 
+    # Captured *before* the clear attempt: a successful clear edits the
+    # manifest, so looking this up afterwards would just find the ids the
+    # clear itself just removed (#2266 review non-blocking finding).
+    ids = _expected_red_ids_for_entry(entry, gh_ops)
     msg = clear_expected_red_via_pr(
         entry.repo_github, entry.repo_name, entry.target_branch, entry.issue_number,
         gh_ops=gh_ops,
     )
-    return MergeEvent(entry, "expected_red_clear", msg)
+    # #2266 review (blocking finding 1): a binary "did the message start
+    # with 'cleared expected_red'" conflated a genuine failure with "there
+    # was nothing to clear in the first place" — the *common* case for an
+    # ordinary oracle-loop merge whose issue was never part of a
+    # deliberately-red slice. `classify_expected_red_clear_result` (shared
+    # with the CLI `--clear` path, review blocking finding 2) tells those
+    # apart; the "no_op" case is reported back via `MergeEvent` for `coord
+    # merge` output but never gets a durable audit row — recording one for
+    # every ordinary passing merge would drown the genuinely actionable
+    # `expected_red_clear_failed` rows this audit trail exists to surface.
+    status = classify_expected_red_clear_result(msg)
+    if status == "no_op":
+        return MergeEvent(entry, "expected_red_clear_noop", msg)
+    event_type = {
+        "cleared": "expected_red_clear",
+        "pending_retry": "expected_red_clear_pending",
+        "failed": "expected_red_clear_failed",
+    }[status]
+    # #2266 review (non-blocking finding): `clear_expected_red_via_pr`
+    # never raises — every genuine failure degrades to a "warning: ..."
+    # string. Make that durable too, not just a merge-output line: a
+    # repeated `expected_red_clear_failed` for the same issue is exactly
+    # the signal `coord acceptance expected-red --clear` (the re-fire
+    # path) exists for.
+    _record_expected_red_audit(entry, event_type, msg, test_ids=ids)
+    return MergeEvent(entry, event_type, msg)
 
 
 def process(