fix(GWC-25,CLI-35,CLI-36): make the empty-ring ReplayGap resumable end to end

An empty replay ring reported oldest_available_sequence = 0 even when gap was
true. Clients follow the documented after_worker_sequence = oldest - 1 formula,
so an unsigned client computed ulong.MaxValue: the follow-up resume replayed
nothing, reported no gap, and the live filter dropped every subsequent event —
a silently dead stream in the headline detach-and-resume scenario, reachable on
default config once ReplayRetentionSeconds (300) age-evicts the ring.

GWC-25: SessionEventDistributor.RegisterWithReplay's empty-ring branch now
reports _highestSequenceSeen + 1 — the next sequence that can possibly be
delivered — when gap is true, so oldest - 1 lands exactly on the highest
observed sequence and the resume delivers everything newer. Still 0 when there
is no gap, where the field is meaningless and never emitted. Nothing is lost:
the evicted interval was unrecoverable either way, and the sentinel's job is to
say "re-snapshot".

CLI-35: the Python CLI fed every stream item into MessageToDict, which raised on
the ReplayGap dataclass and aborted the command after consuming the stream. A
new _event_row helper renders a gap as {"replayGap": {...}} — the same camelCase
shape the Rust CLI emits — and leaves proto events on the existing path.

CLI-36: the Go CLI formatted result.Event on every row, but the library
deliberately clears Event on a gap, so text mode printed
"0 MX_EVENT_FAMILY_UNSPECIFIED" and JSON mode an empty object, discarding the
resume cursors. The loop now branches on result.IsReplayGap() and renders the
typed row in both modes, counting it toward -limit like any other row. The JSON
row's cursors are typed by hand rather than marshalled with protojson: the
proto3 JSON mapping renders 64-bit integers as strings ("7") while the Rust and
Python CLIs emit numbers (7), so going through protojson would have made Go the
only canonical CLI with a different value type.

Docs in the same change: docs/Sessions.md documents the empty-ring sentinel
value and that oldest - 1 is the universal resume formula in both the retained
and fully-evicted cases; docs/CrossLanguageSmokeMatrix.md gains a per-CLI
gap-rendering table covering both client findings, and records exactly what is
and is not comparable across CLIs (same keys and numeric cursors for Rust/Go/
Python; quoted cursors for .NET/Java; differing key order, whitespace, and
container), so a matrix runner compares parsed values rather than raw bytes.

Tests, all written red first and each reproducing its defect verbatim:
- SessionEventDistributorTests: RegisterWithReplayReportsNextDeliverableSequence
  WhenRingEmptiedByAge, ...WithRetentionDisabled, and
  ResumeUsingSentinelFormulaAfterEmptyRingGapDeliversLiveEvents.
- GatewayEndToEndReconnectReplayTests.ReconnectAfterFullAgeEvictionResumesWith
  SentinelFormula — fake-worker e2e resume walk on a fake clock; the fixture now
  takes a retention window and a TimeProvider.
- clients/python test_stream_events_renders_replay_gap.
- clients/go TestRunStreamEventsPrintsReplayGap.

GWC-25's ReplayGap.oldest_available_sequence proto-comment amendment is
deliberately deferred to the later codegen wave (see the tracker change log): it
is comment-only but triggers the full five-client regen fan-out.

clients/python/src/zb_mom_ww_mxgateway_cli/commands.py

@@ -21,6 +21,7 @@ from zb_mom_ww_mxgateway import __version__
 from zb_mom_ww_mxgateway.auth import redact_secret
 from zb_mom_ww_mxgateway.client import GatewayClient
 from zb_mom_ww_mxgateway.errors import MxGatewayError
+from zb_mom_ww_mxgateway.events import ReplayGap
 from zb_mom_ww_mxgateway.galaxy import GalaxyRepositoryClient
 from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
 from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
@@ -1103,7 +1104,7 @@ async def _stream_events(**kwargs: Any) -> dict[str, Any]:
             max_events=kwargs["max_events"],
             timeout=kwargs["timeout"],
         )
-        return {"events": [_message_dict(event) for event in events]}
+        return {"events": [_event_row(event) for event in events]}
 
 
 async def _stream_alarms(**kwargs: Any) -> dict[str, Any]:
@@ -1500,14 +1501,14 @@ async def _collect_events(
     *,
     max_events: int,
     timeout: float,
-) -> list[pb.MxEvent]:
+) -> list[pb.MxEvent | ReplayGap]:
     if max_events > MAX_AGGREGATE_EVENTS:
         raise click.BadParameter(
             f"must be less than or equal to {MAX_AGGREGATE_EVENTS}",
             param_hint="--max-events",
         )
 
-    collected: list[pb.MxEvent] = []
+    collected: list[pb.MxEvent | ReplayGap] = []
     iterator = events.__aiter__()
     try:
         while len(collected) < max_events:
@@ -1630,3 +1631,26 @@ def _message_dict(message: Any) -> dict[str, Any]:
         preserving_proto_field_name=False,
         use_integers_for_enums=False,
     )
+
+
+def _event_row(item: Any) -> dict[str, Any]:
+    """Render one item of an event stream as a JSON row.
+
+    ``Session.stream_events`` yields ``MxEvent | ReplayGap``. ``ReplayGap`` is a
+    plain dataclass, so it has no protobuf descriptor and cannot go through
+    ``MessageToDict`` — it gets its own distinct row instead, matching the shape
+    the Rust and Go CLIs emit so the cross-language matrix can compare rows.
+    Keys are camelCase for the same reason ``_message_dict`` uses
+    ``preserving_proto_field_name=False``. The gap is always rendered: never
+    dropped, and never re-synthesized into an event.
+    """
+
+    if isinstance(item, ReplayGap):
+        return {
+            "replayGap": {
+                "requestedAfterSequence": item.requested_after_sequence,
+                "oldestAvailableSequence": item.oldest_available_sequence,
+            },
+        }
+
+    return _message_dict(item)

clients/python/tests/test_cli.py

@@ -817,3 +817,65 @@ def test_write_secured_command_does_not_echo_value_on_failure(
 def test_write_secured_and_authenticate_user_commands_are_registered() -> None:
     names = set(main.commands)
     assert {"write-secured", "authenticate-user"} <= names
+
+
+class _FakeReplayGapSession:
+    """Session stand-in whose event stream starts with a ReplayGap sentinel.
+
+    Mirrors what ``Session.stream_events`` yields on a resume that predates the
+    gateway's retained replay ring: the typed gap first, then normal events.
+    """
+
+    def __init__(self, gap, event) -> None:
+        self._gap = gap
+        self._event = event
+
+    def stream_events(self, **_kwargs):
+        async def _iterate():
+            yield self._gap
+            yield self._event
+
+        return _iterate()
+
+
+def test_stream_events_renders_replay_gap(monkeypatch: pytest.MonkeyPatch) -> None:
+    """CLI-35: a ReplayGap renders as its own JSON row instead of crashing the command."""
+    from zb_mom_ww_mxgateway.events import ReplayGap
+    from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+
+    gap = ReplayGap(requested_after_sequence=7, oldest_available_sequence=42)
+    event = pb.MxEvent(session_id="cli-test-session", worker_sequence=43)
+
+    async def fake_connect(options, **_kwargs):
+        return _FakeAsyncClient()
+
+    monkeypatch.setattr(commands_module.GatewayClient, "connect", fake_connect)
+    monkeypatch.setattr(
+        commands_module,
+        "_session",
+        lambda _client, _session_id: _FakeReplayGapSession(gap, event),
+    )
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "stream-events",
+            "--plaintext",
+            "--session-id",
+            "cli-test-session",
+            "--after-worker-sequence",
+            "7",
+            "--max-events",
+            "2",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    rows = json.loads(result.output)["events"]
+    assert rows[0] == {
+        "replayGap": {"requestedAfterSequence": 7, "oldestAvailableSequence": 42},
+    }
+    # The gap is rendered, never swallowed, and the normal event still follows it.
+    assert "replayGap" not in rows[1]
+    assert rows[1]["workerSequence"] == "43"