fix(photon): recover degraded upstream stream

[helix4u]

What does this PR do?

Recover Photon iMessage when the local sidecar is still alive but the upstream Spectrum inbound stream has degraded. The sidecar now tracks upstream stream health from Spectrum stream errors, exposes that state through /healthz, and exits after sustained degradation so Hermes can restart the adapter instead of leaving inbound delivery silent.

The gateway also queues retryable runtime adapter failures for immediate reconnect rather than waiting for the idle reconnect watcher sleep.

Related Issue

No GitHub issue for the support report. Related Discord support thread: https://discord.com/channels/1053877538025386074/1518762066289361018

Related open draft PR reviewed while scoping this: #50974

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• plugins/platforms/photon/sidecar/index.mjs: track upstream stream state, expose it from /healthz, and exit after sustained degraded stream state so the adapter can be restarted.
• plugins/platforms/photon/adapter.py: poll sidecar stream health and promote degraded upstream stream state into a retryable fatal adapter error.
• gateway/run.py: reconnect retryable runtime adapter failures immediately instead of waiting for the startup retry delay / idle watcher sleep.
• Added regression coverage for Photon degraded stream health, sidecar /healthz stream state, and immediate runtime reconnect scheduling.

How to Test

1. node --check plugins/platforms/photon/sidecar/index.mjs
2. venv/bin/python -m py_compile plugins/platforms/photon/adapter.py gateway/run.py
3. venv/bin/python -m pytest tests/plugins/platforms/photon/test_overflow_recovery.py tests/plugins/platforms/photon/test_spectrum_patch.py tests/gateway/test_platform_reconnect.py -q
4. git diff --check -- gateway/run.py plugins/platforms/photon/adapter.py plugins/platforms/photon/sidecar/index.mjs tests/plugins/platforms/photon/test_overflow_recovery.py tests/plugins/platforms/photon/test_spectrum_patch.py tests/gateway/test_platform_reconnect.py

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: WSL / Linux checkout with focused unit tests

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A

Screenshots / Logs

Focused validation:

• node --check plugins/platforms/photon/sidecar/index.mjs
• venv/bin/python -m py_compile plugins/platforms/photon/adapter.py gateway/run.py
• venv/bin/python -m pytest tests/plugins/platforms/photon/test_overflow_recovery.py tests/plugins/platforms/photon/test_spectrum_patch.py tests/gateway/test_platform_reconnect.py -q
  • 46 passed, 2 warnings
• git diff --check -- gateway/run.py plugins/platforms/photon/adapter.py plugins/platforms/photon/sidecar/index.mjs tests/plugins/platforms/photon/test_overflow_recovery.py tests/plugins/platforms/photon/test_spectrum_patch.py tests/gateway/test_platform_reconnect.py

[helix4u]

this exists because the other was left as a draft. if the other PR is now ready for review and resolves the same things, this can be closed in favor of that.

[underthestars-zhy]

it looks good to merge! thanks for helping us fix the issue.