fix(photon): label upstream CatchUpEvents failures

[SidUParis]

Summary

• label Photon Spectrum CatchUpEvents internal server errors as upstream of Hermes
• keep the existing re-subscribe behavior, but add an operator hint that local allowlists/pairing are not the cause
• add a regression assertion so the diagnostic does not disappear

Background

While dogfooding Photon iMessage through Hermes, the gateway and sidecar were healthy (/healthz returned {"ok": true}), but inbound delivery stopped and the sidecar repeatedly logged:

/photon.imessage.v1.EventService/CatchUpEvents UNKNOWN: Unknown server error occurred

Restarting the gateway/sidecar re-established the stream and replies resumed. This failure happens before Hermes receives an inbound event, so chasing PHOTON_ALLOWED_USERS or pairing state is misleading. The PR makes that distinction explicit in logs for future operators.

Tests

• node --check plugins/platforms/photon/sidecar/index.mjs
• python -m pytest tests/plugins/platforms/photon/test_spectrum_patch.py -q

[Copilot]

Pull request overview

This PR improves operational diagnostics for the Photon iMessage sidecar by distinguishing Photon Spectrum CatchUpEvents internal server errors as upstream of Hermes, helping operators avoid chasing local allowlist/pairing issues when inbound delivery stalls.

Changes:

• Add inboundStreamErrorMessage() in the Photon sidecar to enrich inbound stream error logs when CatchUpEvents failures occur.
• Update the inbound stream retry loop to use the new diagnostic message.
• Add a regression test to ensure the diagnostic strings remain present in the sidecar source.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
plugins/platforms/photon/sidecar/index.mjs	Adds error classification for CatchUpEvents failures and routes the retry-loop logging through it.
tests/plugins/platforms/photon/test_spectrum_patch.py	Adds a regression assertion to prevent the new diagnostic from disappearing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[huntsyea]

We saw this exact diagnostic gap on a live gateway today: the local sidecar was alive and listening, but CatchUpEvents was failing upstream.

Local state during failure:

Photon sidecar: running, 127.0.0.1:8789 listening
spectrum-ts: 5.2.0
@spectrum-ts/imessage: 5.2.0
Photon credentials: stored

Errors included both:

/photon.imessage.v1.EventService/CatchUpEvents PERMISSION_DENIED: [upstream] Authentication failed. grpcCode: 7
/photon.imessage.v1.EventService/CatchUpEvents UNAVAILABLE: upstream connect error or disconnect/reset before headers. reset reason: connection termination. grpcCode: 14

The added operator hint is useful because the failure is upstream of Hermes receiving an event. Without that label, it is easy to waste time checking PHOTON_ALLOWED_USERS, pairing state, or local sidecar health even though none of those can cause CatchUpEvents to fail before inbound delivery.

Cherry-picked locally with the existing fatal-inbound recovery logic preserved; focused checks passed:

node --check plugins/platforms/photon/sidecar/index.mjs
python3 -m pytest tests/plugins/platforms/photon/test_spectrum_patch.py -q -o 'addopts='
# 4 passed