Hermes-agent

tests/plugins/platforms/photon/test_auth.py

@@ -0,0 +1,609 @@
+"""Tests for the Photon auth module (device login + dashboard API)."""
+from __future__ import annotations
+
+import json
+import os
+from base64 import b64encode
+from pathlib import Path
+from typing import Any, Dict
+
+import pytest
+
+from plugins.platforms.photon import auth as photon_auth
+
+
+# ---------------------------------------------------------------------------
+# Fake httpx — we don't want to hit the real Photon API in unit tests.
+
+class _FakeResponse:
+    def __init__(
+        self,
+        *,
+        status: int = 200,
+        json_body: Any = None,
+        headers: Dict[str, str] | None = None,
+        text: str = "",
+    ) -> None:
+        self.status_code = status
+        self._json = json_body if json_body is not None else {}
+        self.headers = headers or {}
+        self.text = text
+
+    def json(self) -> Any:
+        return self._json
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= 400:
+            raise RuntimeError(f"HTTP {self.status_code}")
+
+
+_PHOTON_ENV = (
+    "PHOTON_PROJECT_ID",
+    "PHOTON_PROJECT_SECRET",
+    "PHOTON_DASHBOARD_PROJECT_ID",
+    "PHOTON_SPECTRUM_HOST",
+    "PHOTON_ALLOWED_USERS",
+    "PHOTON_HOME_CHANNEL",
+)
+
+
+@pytest.fixture
+def tmp_hermes_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    home = tmp_path / "hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    for key in _PHOTON_ENV:
+        monkeypatch.delenv(key, raising=False)
+    yield home
+    # save_env_value() mutates os.environ directly, so scrub any leakage.
+    for key in _PHOTON_ENV:
+        os.environ.pop(key, None)
+
+
+# ---------------------------------------------------------------------------
+# Credential storage
+
+def test_store_and_load_photon_token(tmp_hermes_home: Path) -> None:
+    photon_auth.store_photon_token("abc123def456")
+    assert photon_auth.load_photon_token() == "abc123def456"
+
+    auth_json = json.loads((tmp_hermes_home / "auth.json").read_text())
+    assert auth_json["credential_pool"]["photon"][0]["access_token"] == "abc123def456"
+
+
+def test_store_project_credentials_round_trip(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Don't touch .env / os.environ here — exercise the auth.json path.
+    monkeypatch.setattr(photon_auth, "_persist_runtime_env", lambda *a, **k: None)
+    photon_auth.store_project_credentials(
+        spectrum_project_id="sp-123",
+        project_secret="secret-key",
+        dashboard_project_id="dash-456",
+        name="Hermes Agent",
+    )
+    for key in _PHOTON_ENV:
+        monkeypatch.delenv(key, raising=False)
+
+    sid, secret = photon_auth.load_project_credentials()
+    assert sid == "sp-123"
+    assert secret == "secret-key"
+    assert photon_auth.load_dashboard_project_id() == "dash-456"
+
+
+def test_store_project_credentials_writes_env(tmp_hermes_home: Path) -> None:
+    photon_auth.store_project_credentials(
+        spectrum_project_id="sp-789",
+        project_secret="sek-ret",
+        dashboard_project_id="dash-1",
+    )
+    env_text = (tmp_hermes_home / ".env").read_text()
+    assert "PHOTON_PROJECT_ID=sp-789" in env_text
+    assert "PHOTON_PROJECT_SECRET=sek-ret" in env_text
+
+
+def test_store_user_numbers_round_trip(tmp_hermes_home: Path) -> None:
+    photon_auth.store_user_numbers(
+        phone_number="+15551234567",
+        assigned_phone_number="+16282679185",
+        user_id="user-uuid",
+        dashboard_project_id="dash-uuid",
+    )
+
+    phone, assigned = photon_auth.load_user_numbers()
+    assert phone == "+15551234567"
+    assert assigned == "+16282679185"
+
+    summary = photon_auth.credential_summary()
+    assert summary["phone_number"] == "+15551234567"
+    assert summary["assigned_phone_number"] == "+16282679185"
+
+    rendered: list[str] = []
+    photon_auth.print_credential_summary(rendered.append)
+    assert "  my number           : +15551234567" in rendered[0]
+    assert "  assigned number     : +16282679185" in rendered[0]
+
+
+def test_load_user_numbers_falls_back_to_home_channel(
+    tmp_hermes_home: Path,
+) -> None:
+    from hermes_cli.config import save_env_value
+
+    save_env_value("PHOTON_HOME_CHANNEL", "+15551234567")
+
+    phone, assigned = photon_auth.load_user_numbers()
+    assert phone == "+15551234567"
+    assert assigned is None
+
+
+def test_refresh_user_numbers_reads_existing_assignment(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    photon_auth.store_user_numbers(phone_number="+15551234567")
+
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        assert kwargs.get("headers", {}).get("Authorization") == (
+            "Basic " + b64encode(b"sp:secret").decode("ascii")
+        )
+        assert url.endswith("/projects/sp/users/")
+        return _FakeResponse(json_body={"succeed": True, "data": {"users": [{
+            "id": "user-uuid",
+            "phoneNumber": "+1 (555) 123-4567",
+            "assignedPhoneNumber": "+16282679185",
+        }]}})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+
+    phone, assigned = photon_auth.refresh_user_numbers("sp", "secret")
+    assert phone == "+15551234567"
+    assert assigned == "+16282679185"
+    assert photon_auth.load_user_numbers() == ("+15551234567", "+16282679185")
+
+
+def test_load_project_credentials_env_override(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(photon_auth, "_persist_runtime_env", lambda *a, **k: None)
+    photon_auth.store_project_credentials(
+        spectrum_project_id="from-file", project_secret="secret-file",
+    )
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "from-env")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "secret-env")
+    sid, secret = photon_auth.load_project_credentials()
+    assert sid == "from-env"
+    assert secret == "secret-env"
+
+
+# ---------------------------------------------------------------------------
+# Device login flow
+
+def test_request_device_code_uses_photon_cli(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: Dict[str, Any] = {}
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        captured["url"] = url
+        captured["body"] = kwargs.get("json")
+        return _FakeResponse(json_body={
+            "device_code": "dev-code-xyz",
+            "user_code": "ABCD-1234",
+            "verification_uri": "https://app.photon.codes/device",
+            "verification_uri_complete": "https://app.photon.codes/device?code=ABCD-1234",
+            "expires_in": 600,
+            "interval": 5,
+        })
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+
+    code = photon_auth.request_device_code()
+    assert code.device_code == "dev-code-xyz"
+    assert code.user_code == "ABCD-1234"
+    assert "/api/auth/device/code" in captured["url"]
+    # Hosted Photon allowlists registered device clients — an unregistered
+    # client_id is rejected with 400 invalid_client. We use Photon's published
+    # CLI device client and send the standard scope.
+    assert captured["body"]["client_id"] == "photon-cli"
+    assert captured["body"]["scope"] == "openid profile email"
+
+
+def _device_code() -> "photon_auth.DeviceCode":
+    return photon_auth.DeviceCode(
+        device_code="d", user_code="u",
+        verification_uri="https://x", verification_uri_complete=None,
+        expires_in=10, interval=0,
+    )
+
+
+def test_poll_for_token_body_access_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(status=200, json_body={"access_token": "tok-body"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    assert photon_auth.poll_for_token(_device_code(), interval=0, timeout=2) == "tok-body"
+
+
+def test_poll_for_token_session_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(status=200, json_body={"session": {"access_token": "tok-sess"}})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    assert photon_auth.poll_for_token(_device_code(), interval=0, timeout=2) == "tok-sess"
+
+
+def test_poll_for_token_header_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(status=200, json_body={}, headers={"set-auth-token": "tok-hdr"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    assert photon_auth.poll_for_token(_device_code(), interval=0, timeout=2) == "tok-hdr"
+
+
+def test_poll_for_token_pending_then_success(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = {"n": 0}
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return _FakeResponse(status=400, json_body={"error": "authorization_pending"})
+        return _FakeResponse(status=200, json_body={"access_token": "tok-eventual"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    assert photon_auth.poll_for_token(_device_code(), interval=0, timeout=5) == "tok-eventual"
+    assert calls["n"] == 2
+
+
+def test_poll_for_token_access_denied(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(status=400, json_body={"error": "access_denied"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    with pytest.raises(RuntimeError, match="access_denied"):
+        photon_auth.poll_for_token(_device_code(), interval=0, timeout=2)
+
+
+# ---------------------------------------------------------------------------
+# Projects
+
+def test_list_projects_unwraps_list(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body=[{"id": "p1", "name": "Hermes Agent"}])
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    projects = photon_auth.list_projects("tok")
+    assert projects[0]["id"] == "p1"
+
+
+def test_find_project_by_name_case_insensitive(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"data": [
+            {"id": "p1", "name": "Other"},
+            {"id": "p2", "name": "hermes agent"},
+        ]})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    proj = photon_auth.find_project_by_name("tok", "Hermes Agent")
+    assert proj is not None and proj["id"] == "p2"
+
+
+def test_create_project_sends_spectrum_true(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: Dict[str, Any] = {}
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        captured["url"] = url
+        captured["body"] = kwargs.get("json")
+        captured["headers"] = kwargs.get("headers")
+        return _FakeResponse(json_body={"success": True, "id": "new-proj"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    data = photon_auth.create_project("tok", name="Hermes Agent")
+    assert data["id"] == "new-proj"
+    assert captured["body"]["spectrum"] is True
+    assert captured["body"]["name"] == "Hermes Agent"
+    assert captured["headers"]["Authorization"] == "Bearer tok"
+    assert captured["url"].endswith("/api/projects")
+
+
+def test_create_project_raises_without_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"success": True})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    with pytest.raises(RuntimeError, match="project id"):
+        photon_auth.create_project("tok")
+
+
+def test_ensure_spectrum_enabled_toggles_when_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    get_calls = {"n": 0}
+    posted = {"toggle": False}
+
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        get_calls["n"] += 1
+        if get_calls["n"] == 1:
+            return _FakeResponse(json_body={"id": "p", "spectrum": False, "spectrumProjectId": None})
+        return _FakeResponse(json_body={"id": "p", "spectrum": True, "spectrumProjectId": "sp-1"})
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        if url.endswith("/spectrum/toggle"):
+            posted["toggle"] = True
+        return _FakeResponse(json_body={"success": True})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    proj = photon_auth.ensure_spectrum_enabled("tok", "p")
+    assert posted["toggle"] is True
+    assert proj["spectrumProjectId"] == "sp-1"
+
+
+def test_ensure_spectrum_enabled_skips_toggle_when_on(monkeypatch: pytest.MonkeyPatch) -> None:
+    posted = {"toggle": False}
+
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"id": "p", "spectrum": True, "spectrumProjectId": "sp-1"})
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        if url.endswith("/spectrum/toggle"):
+            posted["toggle"] = True
+        return _FakeResponse(json_body={"success": True})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    proj = photon_auth.ensure_spectrum_enabled("tok", "p")
+    assert posted["toggle"] is False
+    assert proj["spectrumProjectId"] == "sp-1"
+
+
+def test_regenerate_project_secret(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        assert url.endswith("/regenerate-secret")
+        return _FakeResponse(json_body={"success": True, "projectSecret": "rotated"})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    assert photon_auth.regenerate_project_secret("tok", "p") == "rotated"
+
+
+# ---------------------------------------------------------------------------
+# Users
+
+def test_create_user_rejects_invalid_phone() -> None:
+    with pytest.raises(ValueError, match="E.164"):
+        photon_auth.create_user("proj", "secret", phone_number="not-a-number")
+
+
+def test_create_user_posts_dashboard_shape(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: Dict[str, Any] = {}
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        captured["url"] = url
+        captured["body"] = kwargs.get("json")
+        captured["headers"] = kwargs.get("headers")
+        return _FakeResponse(json_body={"succeed": True, "data": {
+            "id": "user-uuid", "phoneNumber": "+15551234567",
+        }})
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    user = photon_auth.create_user("proj-id", "secret", phone_number="+15551234567")
+    assert user["id"] == "user-uuid"
+    assert captured["body"]["type"] == "shared"
+    assert captured["body"]["phoneNumber"] == "+15551234567"
+    assert captured["headers"]["Authorization"] == (
+        "Basic " + b64encode(b"proj-id:secret").decode("ascii")
+    )
+    assert captured["url"].endswith("/projects/proj-id/users/")
+
+
+def test_register_user_if_absent_dedup(monkeypatch: pytest.MonkeyPatch) -> None:
+    posted = {"n": 0}
+
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"succeed": True, "data": {"users": [{
+            "id": "u1",
+            "phoneNumber": "+1 (555) 123-4567",
+            "assignedPhoneNumber": "+16282679185",
+        }]}})
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        posted["n"] += 1
+        return _FakeResponse(json_body={"success": True, "user": {}})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    # Same number, different formatting — should match and NOT create.
+    user, created = photon_auth.register_user_if_absent(
+        "proj", "secret", phone_number="+15551234567",
+    )
+    assert created is False
+    assert user["id"] == "u1"
+    assert posted["n"] == 0
+    # The reused user carries the assigned iMessage line ("TEXTS ON").
+    assert photon_auth.user_assigned_line(user) == "+16282679185"
+
+
+def test_user_assigned_line() -> None:
+    assert (
+        photon_auth.user_assigned_line({"assignedPhoneNumber": "+16282679185"})
+        == "+16282679185"
+    )
+    # Own number present but no assignment yet (e.g. freshly created user).
+    assert photon_auth.user_assigned_line({"phoneNumber": "+15551234567"}) is None
+    assert photon_auth.user_assigned_line({"assignedPhoneNumber": ""}) is None
+    assert photon_auth.user_assigned_line({}) is None
+    assert photon_auth.user_assigned_line(None) is None
+
+
+def test_register_user_if_absent_creates(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"succeed": True, "data": {"users": []}})
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body={"succeed": True, "data": {"id": "u-new"}})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    user, created = photon_auth.register_user_if_absent(
+        "proj", "secret", phone_number="+15551234567",
+    )
+    assert created is True
+    assert user["id"] == "u-new"
+
+
+# ---------------------------------------------------------------------------
+# Lines (assigned number)
+
+def test_get_imessage_line_returns_existing(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body=[
+            {"id": "l1", "platform": "imessage", "phoneNumber": "+15559999999", "status": "active"},
+        ])
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    line = photon_auth.get_imessage_line("tok", "proj")
+    assert line is not None and line["phoneNumber"] == "+15559999999"
+
+
+def test_get_imessage_line_provisions_when_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    added = {"n": 0}
+
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        return _FakeResponse(json_body=[])
+
+    def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+        added["n"] += 1
+        assert kwargs.get("json", {}).get("platform") == "imessage"
+        return _FakeResponse(json_body={"success": True, "line": {
+            "id": "l-new", "platform": "imessage", "phoneNumber": "+15558888888",
+        }})
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    line = photon_auth.get_imessage_line("tok", "proj")
+    assert added["n"] == 1
+    assert line["phoneNumber"] == "+15558888888"
+
+
+# ---------------------------------------------------------------------------
+# Credential summary (no secret leakage)
+
+def test_credential_summary_no_secret_leak(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(photon_auth, "_persist_runtime_env", lambda *a, **k: None)
+    photon_auth.store_photon_token("token-aaaaaaaaaaaaaaaa")
+    photon_auth.store_project_credentials(
+        spectrum_project_id="sp-uuid",
+        project_secret="secret-bbbbbbbbbbb",
+        dashboard_project_id="dash-uuid",
+    )
+    summary = photon_auth.credential_summary()
+    blob = "\n".join(summary.values())
+    assert "token-aaaa" not in blob
+    assert "secret-bbbb" not in blob
+    assert summary["device_token"].startswith("✓")
+    assert summary["project_key"].startswith("✓")
+    assert summary["spectrum_project_id"] == "sp-uuid"
+    assert summary["dashboard_project_id"] == "dash-uuid"
+    assert summary["phone_number"].startswith("✗ missing")
+    assert summary["assigned_phone_number"].startswith("✗ missing")
+
+
+# ---------------------------------------------------------------------------
+# Device-token candidate extraction + dashboard validation.
+
+def test_device_response_candidates_covers_known_shapes() -> None:
+    candidates = photon_auth._device_response_token_candidates(
+        {
+            "access_token": "tok-snake",
+            "accessToken": "tok-camel",
+            "data": {"access_token": "tok-data"},
+        },
+        headers={"set-auth-token": "Bearer tok-header"},
+    )
+    by_source = {c.source: c.token for c in candidates}
+    assert by_source["access_token"] == "tok-snake"
+    assert by_source["accessToken"] == "tok-camel"
+    assert by_source["data.access_token"] == "tok-data"
+    # "Bearer " prefix is stripped from the header value.
+    assert by_source["set-auth-token"] == "tok-header"
+
+
+def test_device_response_candidates_dedupes() -> None:
+    candidates = photon_auth._device_response_token_candidates(
+        {"access_token": "same", "accessToken": "same"},
+    )
+    assert [c.token for c in candidates] == ["same"]
+
+
+def test_validate_photon_token_rejects_unrecognized_session(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_get(url: str, *, headers: Dict[str, str], timeout: float) -> _FakeResponse:
+        if url.endswith("/api/auth/get-session"):
+            return _FakeResponse(json_body={})  # no "user" key
+        return _FakeResponse(json_body=[])
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    with pytest.raises(photon_auth.PhotonDashboardAuthError):
+        photon_auth.validate_photon_token("some-token")
+
+
+def test_validate_photon_token_rejects_project_api_denial(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_get(url: str, *, headers: Dict[str, str], timeout: float) -> _FakeResponse:
+        if url.endswith("/api/auth/get-session"):
+            return _FakeResponse(json_body={"user": {"id": "u1"}})
+        return _FakeResponse(status=403)  # project API rejects
+
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+    with pytest.raises(photon_auth.PhotonDashboardAuthError):
+        photon_auth.validate_photon_token("some-token")
+
+
+def test_login_device_flow_validates_before_persisting(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_post(url: str, *, json: Dict[str, Any], timeout: float) -> _FakeResponse:
+        if url.endswith("/api/auth/device/code"):
+            return _FakeResponse(json_body={
+                "device_code": "dev", "user_code": "AAAA",
+                "verification_uri": "https://app.photon.codes/device",
+                "verification_uri_complete": None,
+                "expires_in": 600, "interval": 0,
+            })
+        # device/token approval
+        return _FakeResponse(json_body={"access_token": "good-token"})
+
+    def fake_get(url: str, *, headers: Dict[str, str], timeout: float) -> _FakeResponse:
+        if url.endswith("/api/auth/get-session"):
+            return _FakeResponse(json_body={"user": {"id": "u1"}})
+        return _FakeResponse(json_body=[])  # projects OK
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+
+    token = photon_auth.login_device_flow(open_browser=False)
+    assert token == "good-token"
+    assert photon_auth.load_photon_token() == "good-token"
+
+
+def test_login_device_flow_raises_when_token_invalid(
+    tmp_hermes_home: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_post(url: str, *, json: Dict[str, Any], timeout: float) -> _FakeResponse:
+        if url.endswith("/api/auth/device/code"):
+            return _FakeResponse(json_body={
+                "device_code": "dev", "user_code": "AAAA",
+                "verification_uri": "https://app.photon.codes/device",
+                "verification_uri_complete": None,
+                "expires_in": 600, "interval": 0,
+            })
+        return _FakeResponse(json_body={"access_token": "bad-token"})
+
+    def fake_get(url: str, *, headers: Dict[str, str], timeout: float) -> _FakeResponse:
+        return _FakeResponse(status=401)  # session lookup rejects
+
+    monkeypatch.setattr(photon_auth.httpx, "post", fake_post)
+    monkeypatch.setattr(photon_auth.httpx, "get", fake_get)
+
+    with pytest.raises(photon_auth.PhotonDashboardAuthError):
+        photon_auth.login_device_flow(open_browser=False)
+    # A token that failed validation must never be persisted.
+    assert photon_auth.load_photon_token() is None

tests/plugins/platforms/photon/test_inbound.py

@@ -0,0 +1,314 @@
+"""Inbound dispatch + dedup tests for PhotonAdapter.
+
+These bypass the loopback HTTP stream — they call ``_dispatch_inbound`` /
+``_on_inbound_line`` / ``_is_duplicate`` directly, exercising the
+sidecar-event parsing without spawning the Node sidecar or binding ports.
+"""
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pytest
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import MessageEvent, MessageType
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    return PhotonAdapter(cfg)
+
+
+def _capture(adapter: PhotonAdapter, monkeypatch: pytest.MonkeyPatch) -> List[MessageEvent]:
+    captured: List[MessageEvent] = []
+
+    async def fake_handle(event: MessageEvent) -> None:
+        captured.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    return captured
+
+
+def _dm_event(text: str, msg_id: str = "spc-msg-abc") -> Dict[str, Any]:
+    return {
+        "messageId": msg_id,
+        "platform": "iMessage",
+        "space": {"id": "+15551234567", "type": "dm", "phone": "+15551234567"},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "text", "text": text},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+
+
+@pytest.mark.asyncio
+async def test_dispatch_text_dm(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_dm_event("hello world"))
+
+    assert len(captured) == 1
+    event = captured[0]
+    assert event.text == "hello world"
+    assert event.message_type == MessageType.TEXT
+    assert event.message_id == "spc-msg-abc"
+    src = event.source
+    assert src is not None
+    assert src.platform == Platform("photon")
+    assert src.chat_id == "+15551234567"
+    assert src.chat_type == "dm"
+    assert src.user_id == "+15551234567"
+
+
+@pytest.mark.asyncio
+async def test_dispatch_group_type(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    event = {
+        "messageId": "spc-msg-grp",
+        "space": {"id": "group-guid-xyz", "type": "group", "phone": None},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "text", "text": "hi group"},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+    await adapter._dispatch_inbound(event)
+    assert captured[0].source.chat_type == "group"
+
+
+# A real 1x1 transparent PNG (passes base.py's _looks_like_image magic check).
+_PNG_1X1_B64 = (
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhf"
+    "DwAChwGA60e6kgAAAABJRU5ErkJggg=="
+)
+
+
+def _attachment_event(
+    content: Dict[str, Any], msg_id: str = "spc-msg-att"
+) -> Dict[str, Any]:
+    return {
+        "messageId": msg_id,
+        "space": {"id": "+15551234567", "type": "dm", "phone": "+15551234567"},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "attachment", **content},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+
+
+def _voice_event(
+    content: Dict[str, Any], msg_id: str = "spc-msg-voice"
+) -> Dict[str, Any]:
+    return {
+        "messageId": msg_id,
+        "space": {"id": "+15551234567", "type": "dm", "phone": "+15551234567"},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "voice", **content},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+
+
+@pytest.mark.asyncio
+async def test_dispatch_attachment_without_bytes_surfaces_marker(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """No inline ``data`` (over cap / failed sidecar read) -> text marker, no media."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    event = _attachment_event(
+        {"name": "IMG_4127.HEIC", "mimeType": "image/heic", "size": 12345}
+    )
+    await adapter._dispatch_inbound(event)
+    assert len(captured) == 1
+    ev = captured[0]
+    assert "Photon attachment received" in ev.text
+    assert "IMG_4127.HEIC" in ev.text
+    assert ev.message_type == MessageType.PHOTO
+    assert ev.media_urls == []
+    assert ev.media_types == []
+
+
+@pytest.mark.asyncio
+async def test_dispatch_attachment_downloads_image(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Inline base64 image bytes are decoded, cached, and exposed as media."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    raw = base64.b64decode(_PNG_1X1_B64)
+    event = _attachment_event(
+        {
+            "name": "photo.png",
+            "mimeType": "image/png",
+            "size": len(raw),
+            "data": _PNG_1X1_B64,
+            "encoding": "base64",
+        }
+    )
+    await adapter._dispatch_inbound(event)
+
+    assert len(captured) == 1
+    ev = captured[0]
+    assert ev.message_type == MessageType.PHOTO
+    assert ev.media_types == ["image/png"]
+    assert len(ev.media_urls) == 1
+    cached = Path(ev.media_urls[0])
+    try:
+        assert cached.is_file()
+        assert cached.read_bytes() == raw
+        assert ev.text == "(attachment)"
+    finally:
+        cached.unlink(missing_ok=True)
+
+
+@pytest.mark.asyncio
+async def test_dispatch_voice_downloads_audio(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Inbound Spectrum voice content is cached and routed to auto-STT."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    raw = b"OggS" + b"\x00" * 32
+    event = _voice_event(
+        {
+            "name": "note.ogg",
+            "mimeType": "audio/ogg",
+            "duration": 7,
+            "size": len(raw),
+            "data": base64.b64encode(raw).decode("ascii"),
+            "encoding": "base64",
+        }
+    )
+    await adapter._dispatch_inbound(event)
+
+    assert len(captured) == 1
+    ev = captured[0]
+    assert ev.message_type == MessageType.VOICE
+    assert ev.media_types == ["audio/ogg"]
+    assert len(ev.media_urls) == 1
+    cached = Path(ev.media_urls[0])
+    try:
+        assert cached.is_file()
+        assert cached.read_bytes() == raw
+        assert ev.text == "(voice)"
+    finally:
+        cached.unlink(missing_ok=True)
+
+
+@pytest.mark.asyncio
+async def test_dispatch_voice_without_bytes_surfaces_marker(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Metadata-only voice still tells the agent a voice note arrived."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    event = _voice_event(
+        {"name": "note.m4a", "mimeType": "audio/mp4", "duration": 12, "size": 12345}
+    )
+    await adapter._dispatch_inbound(event)
+
+    assert len(captured) == 1
+    ev = captured[0]
+    assert "Photon voice received" in ev.text
+    assert "note.m4a" in ev.text
+    assert "duration: 12s" in ev.text
+    assert ev.message_type == MessageType.VOICE
+    assert ev.media_urls == []
+    assert ev.media_types == []
+
+
+@pytest.mark.asyncio
+async def test_dispatch_attachment_downloads_document(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Non-image attachments route through the document cache as DOCUMENT."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    raw = b"%PDF-1.4 hermes test document"
+    event = _attachment_event(
+        {
+            "name": "report.pdf",
+            "mimeType": "application/pdf",
+            "size": len(raw),
+            "data": base64.b64encode(raw).decode("ascii"),
+            "encoding": "base64",
+        }
+    )
+    await adapter._dispatch_inbound(event)
+
+    assert len(captured) == 1
+    ev = captured[0]
+    assert ev.message_type == MessageType.DOCUMENT
+    assert ev.media_types == ["application/pdf"]
+    assert len(ev.media_urls) == 1
+    cached = Path(ev.media_urls[0])
+    try:
+        assert cached.is_file()
+        assert cached.read_bytes() == raw
+        assert ev.text == "(attachment)"
+    finally:
+        cached.unlink(missing_ok=True)
+
+
+@pytest.mark.asyncio
+async def test_on_inbound_line_dispatches_and_dedups(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    line = json.dumps(_dm_event("ping", msg_id="dup-1"))
+    await adapter._on_inbound_line(line)
+    await adapter._on_inbound_line(line)  # same messageId -> deduped
+
+    assert len(captured) == 1
+    assert captured[0].text == "ping"
+
+
+@pytest.mark.asyncio
+async def test_on_inbound_line_ignores_bad_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._on_inbound_line("{not json")
+    assert captured == []
+
+
+def test_is_duplicate_window(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    assert adapter._is_duplicate("id-1") is False
+    assert adapter._is_duplicate("id-1") is True
+    assert adapter._is_duplicate("id-2") is False
+    assert adapter._is_duplicate("id-1") is True  # still dup
+
+
+def test_is_duplicate_hard_size_bound(monkeypatch: pytest.MonkeyPatch) -> None:
+    # A burst of unique ids within the window must not grow the dedup map past
+    # its bound — evict oldest (LRU), not only expired entries.
+    import plugins.platforms.photon.adapter as ad
+
+    monkeypatch.setattr(ad, "_DEDUP_MAX_SIZE", 5)
+    adapter = _make_adapter(monkeypatch)
+    for i in range(100):
+        adapter._is_duplicate(f"id-{i}")
+    assert len(adapter._seen_messages) <= 5
+    assert adapter._is_duplicate("id-99") is True  # recent still deduped
+    assert adapter._is_duplicate("id-0") is False  # oldest evicted
+
+
+def test_check_requirements_without_node(monkeypatch: pytest.MonkeyPatch) -> None:
+    # If no node binary on PATH the adapter should refuse to start.
+    from plugins.platforms.photon import adapter as adapter_mod
+
+    monkeypatch.setattr(adapter_mod.shutil, "which", lambda _name: None)
+    assert adapter_mod.check_requirements() is False

tests/plugins/platforms/photon/test_markdown.py

@@ -0,0 +1,129 @@
+"""Markdown handling tests for PhotonAdapter.
+
+Markdown is on by default (the sidecar sends it via spectrum-ts'
+``markdown()`` builder and iMessage renders it); ``PHOTON_MARKDOWN=false``
+reverts to the stripped-plain-text path.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+import pytest
+
+from gateway.config import PlatformConfig
+from plugins.platforms.photon import adapter as photon_adapter
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+_MD = "**bold** and `code`"
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    return PhotonAdapter(cfg)
+
+
+def _capture_sidecar(adapter: PhotonAdapter) -> List[Tuple[str, Dict[str, Any]]]:
+    calls: List[Tuple[str, Dict[str, Any]]] = []
+
+    async def _fake_call(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        calls.append((path, body))
+        return {"ok": True, "messageId": "msg-123"}
+
+    adapter._sidecar_call = _fake_call  # type: ignore[assignment]
+    return calls
+
+
+def test_format_message_passthrough_by_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHOTON_MARKDOWN", raising=False)
+    adapter = _make_adapter(monkeypatch)
+    assert adapter.format_message(_MD) == _MD
+
+
+def test_format_message_strips_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("PHOTON_MARKDOWN", "false")
+    adapter = _make_adapter(monkeypatch)
+    assert adapter.format_message(_MD) == "bold and code"
+
+
+def test_supports_code_blocks_mirrors_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PHOTON_MARKDOWN", raising=False)
+    assert _make_adapter(monkeypatch).supports_code_blocks is True
+    monkeypatch.setenv("PHOTON_MARKDOWN", "false")
+    assert _make_adapter(monkeypatch).supports_code_blocks is False
+
+
+@pytest.mark.asyncio
+async def test_sidecar_send_includes_markdown_format(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHOTON_MARKDOWN", raising=False)
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.send("+15551234567", _MD)
+
+    path, body = calls[0]
+    assert path == "/send"
+    assert body["format"] == "markdown"
+    assert body["text"] == _MD  # passed through unstripped
+
+
+@pytest.mark.asyncio
+async def test_sidecar_send_omits_format_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Old-sidecar compat: the key is absent, not "text", when disabled."""
+    monkeypatch.setenv("PHOTON_MARKDOWN", "false")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.send("+15551234567", _MD)
+
+    _, body = calls[0]
+    assert "format" not in body
+    assert body["text"] == "bold and code"
+
+
+@pytest.mark.asyncio
+async def test_standalone_send_includes_markdown_format(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHOTON_MARKDOWN", raising=False)
+    monkeypatch.setenv("PHOTON_SIDECAR_TOKEN", "tok")
+
+    posted: List[Tuple[str, Dict[str, Any]]] = []
+
+    class _Resp:
+        status_code = 200
+
+        @staticmethod
+        def json() -> Dict[str, Any]:
+            return {"ok": True, "messageId": "m-9"}
+
+    class _FakeClient:
+        def __init__(self, *a, **k):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+        async def post(self, url: str, json: Dict[str, Any], headers=None):
+            posted.append((url, json))
+            return _Resp()
+
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _FakeClient)
+
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    result = await photon_adapter._standalone_send(cfg, "+15551234567", _MD)
+
+    assert result.get("success") is True
+    assert posted[0][1]["format"] == "markdown"

tests/plugins/platforms/photon/test_mention_gating.py

@@ -0,0 +1,138 @@
+"""Group-chat mention-gating tests for PhotonAdapter.
+
+Parity with the BlueBubbles iMessage channel: when ``require_mention`` is
+enabled, group messages are dropped unless they hit a wake-word pattern,
+and the leading wake word is stripped from the ones that pass. DMs are
+never gated.
+
+These call ``_dispatch_inbound`` directly (no aiohttp / ports) and assert
+on what reaches ``handle_message``.
+"""
+from __future__ import annotations
+
+from typing import List
+
+import pytest
+
+from gateway.config import PlatformConfig
+from gateway.platforms.base import MessageEvent
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch, extra: dict | None = None) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    monkeypatch.delenv("PHOTON_REQUIRE_MENTION", raising=False)
+    monkeypatch.delenv("PHOTON_MENTION_PATTERNS", raising=False)
+    cfg = PlatformConfig(enabled=True, token="", extra=extra or {})
+    return PhotonAdapter(cfg)
+
+
+def _group_payload(text: str) -> dict:
+    return {
+        "messageId": f"grp-{abs(hash(text))}",
+        "space": {"id": "group-guid-xyz", "type": "group", "phone": None},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "text", "text": text},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+
+
+def _dm_payload(text: str) -> dict:
+    return {
+        "messageId": f"dm-{abs(hash(text))}",
+        "space": {"id": "+15551234567", "type": "dm", "phone": "+15551234567"},
+        "sender": {"id": "+15551234567"},
+        "content": {"type": "text", "text": text},
+        "timestamp": "2026-05-14T19:06:32.000Z",
+    }
+
+
+def _capture(adapter: PhotonAdapter, monkeypatch: pytest.MonkeyPatch) -> List[MessageEvent]:
+    captured: List[MessageEvent] = []
+
+    async def fake_handle(event: MessageEvent) -> None:
+        captured.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    return captured
+
+
+def test_require_mention_defaults_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    assert adapter.require_mention is False
+    # Defaults compile to the two Hermes wake-word patterns.
+    assert len(adapter._mention_patterns) == 2
+
+
+@pytest.mark.asyncio
+async def test_group_message_dropped_without_mention(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch, extra={"require_mention": True})
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_group_payload("just chatting, no wake word"))
+    assert captured == []
+
+
+@pytest.mark.asyncio
+async def test_group_message_passes_and_strips_wake_word(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch, extra={"require_mention": True})
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_group_payload("Hermes what's the weather"))
+    assert len(captured) == 1
+    # Leading wake word stripped before dispatch.
+    assert captured[0].text == "what's the weather"
+
+
+@pytest.mark.asyncio
+async def test_dm_never_gated(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch, extra={"require_mention": True})
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_dm_payload("no wake word here"))
+    assert len(captured) == 1
+    assert captured[0].text == "no wake word here"
+
+
+@pytest.mark.asyncio
+async def test_require_mention_off_passes_group_messages(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)  # require_mention defaults off
+    captured = _capture(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_group_payload("plain group chatter"))
+    assert len(captured) == 1
+    assert captured[0].text == "plain group chatter"
+
+
+def test_custom_mention_patterns_from_config(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(
+        monkeypatch,
+        extra={"require_mention": True, "mention_patterns": [r"(?<![\w@])@?amos\b[,:\-]?"]},
+    )
+    assert adapter.require_mention is True
+    assert len(adapter._mention_patterns) == 1
+    assert adapter._message_matches_mention_patterns("amos help me") is True
+    assert adapter._message_matches_mention_patterns("hermes help me") is False
+
+
+def test_mention_patterns_env_comma_separated(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    monkeypatch.setenv("PHOTON_REQUIRE_MENTION", "true")
+    monkeypatch.setenv("PHOTON_MENTION_PATTERNS", r"bot\b, assistant\b")
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    adapter = PhotonAdapter(cfg)
+    assert adapter.require_mention is True
+    assert len(adapter._mention_patterns) == 2
+    assert adapter._message_matches_mention_patterns("hey bot") is True
+
+
+def test_invalid_pattern_skipped(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(
+        monkeypatch,
+        extra={"require_mention": True, "mention_patterns": ["(unclosed", r"good\b"]},
+    )
+    # Bad regex dropped, good one kept.
+    assert len(adapter._mention_patterns) == 1
+    assert adapter._message_matches_mention_patterns("a good thing") is True

tests/plugins/platforms/photon/test_outbound_media.py

@@ -0,0 +1,255 @@
+"""Outbound-media tests for PhotonAdapter.
+
+Photon ships outbound attachments via spectrum-ts' ``attachment()`` /
+``voice()`` content builders, reached through the Node sidecar's
+``/send-attachment`` endpoint. These tests stub ``_sidecar_call`` so we
+can assert the endpoint + body shape each ``send_*`` override produces
+without spawning Node or binding ports.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Tuple
+
+import pytest
+
+from gateway.config import PlatformConfig
+from plugins.platforms.photon import adapter as photon_adapter
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    monkeypatch.delenv("PHOTON_WEBHOOK_SECRET", raising=False)
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    return PhotonAdapter(cfg)
+
+
+def _capture_sidecar(adapter: PhotonAdapter) -> List[Tuple[str, Dict[str, Any]]]:
+    """Replace ``_sidecar_call`` with a recorder that returns a fixed id."""
+    calls: List[Tuple[str, Dict[str, Any]]] = []
+
+    async def _fake_call(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        calls.append((path, body))
+        return {"ok": True, "messageId": "msg-123"}
+
+    adapter._sidecar_call = _fake_call  # type: ignore[assignment]
+    return calls
+
+
+@pytest.fixture()
+def real_file(tmp_path) -> str:
+    p = tmp_path / "photo.jpg"
+    p.write_bytes(b"\xff\xd8\xff\xe0fake-jpeg")
+    return str(p)
+
+
+def _patch_safe_path(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Make path validation a passthrough so tmp files outside the cache pass."""
+    monkeypatch.setattr(
+        PhotonAdapter,
+        "validate_media_delivery_path",
+        staticmethod(lambda p: p if os.path.exists(p) else None),
+    )
+
+
+@pytest.mark.asyncio
+async def test_send_image_file_hits_attachment_endpoint(
+    monkeypatch: pytest.MonkeyPatch, real_file: str
+) -> None:
+    _patch_safe_path(monkeypatch)
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    result = await adapter.send_image_file(
+        "any;-;+15551234567", real_file, caption="look"
+    )
+
+    assert result.success is True
+    assert result.message_id == "msg-123"
+    assert len(calls) == 1
+    path, body = calls[0]
+    assert path == "/send-attachment"
+    assert body["spaceId"] == "any;-;+15551234567"
+    assert body["path"] == real_file
+    assert body["kind"] == "attachment"
+    assert body["caption"] == "look"
+    assert body["mimeType"] == "image/jpeg"  # inferred from .jpg
+
+
+@pytest.mark.asyncio
+async def test_send_voice_marks_kind_voice(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _patch_safe_path(monkeypatch)
+    audio = tmp_path / "note.m4a"
+    audio.write_bytes(b"fake-audio")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    result = await adapter.send_voice("any;-;+1", str(audio))
+
+    assert result.success is True
+    path, body = calls[0]
+    assert path == "/send-attachment"
+    assert body["kind"] == "voice"
+
+
+@pytest.mark.asyncio
+async def test_send_document_passes_filename(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _patch_safe_path(monkeypatch)
+    doc = tmp_path / "report.pdf"
+    doc.write_bytes(b"%PDF-1.4 fake")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.send_document("any;-;+1", str(doc), file_name="Q3.pdf")
+
+    _, body = calls[0]
+    assert body["kind"] == "attachment"
+    assert body["name"] == "Q3.pdf"
+    assert body["mimeType"] == "application/pdf"
+
+
+@pytest.mark.asyncio
+async def test_send_video_passes_through(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _patch_safe_path(monkeypatch)
+    vid = tmp_path / "clip.mp4"
+    vid.write_bytes(b"fake-mp4")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.send_video("any;+;groupguid", str(vid), caption="watch")
+
+    _, body = calls[0]
+    assert body["kind"] == "attachment"
+    assert body["caption"] == "watch"
+
+
+@pytest.mark.asyncio
+async def test_send_image_url_caches_then_sends_attachment(
+    monkeypatch: pytest.MonkeyPatch, real_file: str
+) -> None:
+    _patch_safe_path(monkeypatch)
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    async def _fake_cache(url: str, *a, **k) -> str:
+        assert url == "https://example.com/cat.jpg"
+        return real_file
+
+    import gateway.platforms.base as base_mod
+
+    monkeypatch.setattr(base_mod, "cache_image_from_url", _fake_cache)
+
+    result = await adapter.send_image(
+        "any;-;+1", "https://example.com/cat.jpg", caption="cat"
+    )
+
+    assert result.success is True
+    path, body = calls[0]
+    assert path == "/send-attachment"
+    assert body["path"] == real_file
+    assert body["caption"] == "cat"
+
+
+@pytest.mark.asyncio
+async def test_send_image_url_fetch_failure_falls_back_to_text(
+    monkeypatch: pytest.MonkeyPatch
+) -> None:
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    async def _boom(url: str, *a, **k) -> str:
+        raise RuntimeError("network down")
+
+    import gateway.platforms.base as base_mod
+
+    monkeypatch.setattr(base_mod, "cache_image_from_url", _boom)
+
+    result = await adapter.send_image(
+        "any;-;+1", "https://example.com/cat.jpg", caption="cat"
+    )
+
+    # Fallback path: base send_image() routes to send() → /send (text).
+    assert result.success is True
+    assert calls[0][0] == "/send"
+    assert "https://example.com/cat.jpg" in calls[0][1]["text"]
+
+
+@pytest.mark.asyncio
+async def test_send_attachment_rejects_unsafe_path(
+    monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Default validation (no passthrough patch) should reject a nonexistent /
+    # traversal path, returning a failed SendResult without calling the sidecar.
+    monkeypatch.setattr(
+        PhotonAdapter,
+        "validate_media_delivery_path",
+        staticmethod(lambda p: None),
+    )
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    result = await adapter.send_image_file("any;-;+1", "/etc/passwd")
+
+    assert result.success is False
+    assert "unsafe" in (result.error or "")
+    assert calls == []  # never reached the sidecar
+
+
+@pytest.mark.asyncio
+async def test_standalone_send_text_then_attachments(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _patch_safe_path(monkeypatch)
+    img = tmp_path / "a.png"
+    img.write_bytes(b"\x89PNG fake")
+    monkeypatch.setenv("PHOTON_SIDECAR_TOKEN", "tok")
+
+    posted: List[Tuple[str, Dict[str, Any]]] = []
+
+    class _Resp:
+        status_code = 200
+
+        @staticmethod
+        def json() -> Dict[str, Any]:
+            return {"ok": True, "messageId": "m-9"}
+
+    class _FakeClient:
+        def __init__(self, *a, **k):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+        async def post(self, url: str, json: Dict[str, Any], headers=None):
+            posted.append((url, json))
+            return _Resp()
+
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _FakeClient)
+
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    result = await photon_adapter._standalone_send(
+        cfg,
+        "any;-;+1",
+        "hello",
+        media_files=[(str(img), False)],
+    )
+
+    assert result.get("success") is True
+    # First call is the text /send, second is /send-attachment.
+    assert posted[0][0].endswith("/send")
+    assert posted[0][1]["text"] == "hello"
+    assert posted[1][0].endswith("/send-attachment")
+    assert posted[1][1]["path"] == str(img)
+    assert posted[1][1]["kind"] == "attachment"
+    assert posted[1][1]["mimeType"] == "image/png"

tests/plugins/platforms/photon/test_reactions.py

@@ -0,0 +1,275 @@
+"""Reaction (tapback) tests for PhotonAdapter.
+
+Outbound reactions go through the sidecar's ``/react`` / ``/unreact``
+endpoints; these tests stub ``_sidecar_call`` to assert endpoint + body
+shape. Inbound reaction events are fed straight to ``_dispatch_inbound``.
+Neither path spawns the Node sidecar or binds ports.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Tuple
+
+import pytest
+
+from gateway.config import PlatformConfig
+from gateway.platforms.base import MessageEvent, MessageType, ProcessingOutcome
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+_EYES = "\U0001f440"
+_THUMBS_UP = "\U0001f44d"
+_THUMBS_DOWN = "\U0001f44e"
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    return PhotonAdapter(cfg)
+
+
+def _capture_sidecar(adapter: PhotonAdapter) -> List[Tuple[str, Dict[str, Any]]]:
+    calls: List[Tuple[str, Dict[str, Any]]] = []
+
+    async def _fake_call(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        calls.append((path, body))
+        return {"ok": True, "messageId": "msg-123", "reactionId": "react-1"}
+
+    adapter._sidecar_call = _fake_call  # type: ignore[assignment]
+    return calls
+
+
+def _capture_handled(
+    adapter: PhotonAdapter, monkeypatch: pytest.MonkeyPatch
+) -> List[MessageEvent]:
+    captured: List[MessageEvent] = []
+
+    async def fake_handle(event: MessageEvent) -> None:
+        captured.append(event)
+
+    monkeypatch.setattr(adapter, "handle_message", fake_handle)
+    return captured
+
+
+def _message_event(adapter: PhotonAdapter) -> MessageEvent:
+    return MessageEvent(
+        text="hi",
+        message_type=MessageType.TEXT,
+        source=adapter.build_source(
+            chat_id="+15551234567",
+            chat_name="+15551234567",
+            chat_type="dm",
+            user_id="+15551234567",
+            user_name=None,
+        ),
+        message_id="target-msg-1",
+        timestamp=datetime.now(tz=timezone.utc),
+    )
+
+
+def _reaction_event(
+    emoji: str = "❤️",
+    target_id: str = "bot-msg-1",
+    target_direction: Any = "outbound",
+    space_type: str = "dm",
+) -> Dict[str, Any]:
+    return {
+        "messageId": "reaction-evt-1",
+        "platform": "iMessage",
+        "space": {"id": "+15551234567", "type": space_type, "phone": "+15551234567"},
+        "sender": {"id": "+15551234567"},
+        "content": {
+            "type": "reaction",
+            "emoji": emoji,
+            "targetMessageId": target_id,
+            "targetDirection": target_direction,
+        },
+        "timestamp": "2026-06-11T10:00:00.000Z",
+    }
+
+
+# -- Outbound: /react and /unreact body shapes ------------------------------
+
+@pytest.mark.asyncio
+async def test_add_reaction_posts_react(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    ok = await adapter._add_reaction("+15551234567", "target-msg-1", _EYES)
+
+    assert ok is True
+    assert calls == [
+        (
+            "/react",
+            {
+                "spaceId": "+15551234567",
+                "messageId": "target-msg-1",
+                "emoji": _EYES,
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_remove_reaction_posts_unreact(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    ok = await adapter._remove_reaction("+15551234567", "target-msg-1")
+
+    assert ok is True
+    assert calls == [
+        ("/unreact", {"spaceId": "+15551234567", "messageId": "target-msg-1"})
+    ]
+
+
+@pytest.mark.asyncio
+async def test_reaction_failure_is_soft(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+
+    async def _boom(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        raise RuntimeError("sidecar down")
+
+    adapter._sidecar_call = _boom  # type: ignore[assignment]
+
+    assert await adapter._add_reaction("+1", "m", _EYES) is False
+    assert await adapter._remove_reaction("+1", "m") is False
+
+
+# -- Lifecycle hooks ---------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_hooks_noop_when_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PHOTON_REACTIONS", raising=False)
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    event = _message_event(adapter)
+    await adapter.on_processing_start(event)
+    await adapter.on_processing_complete(event, ProcessingOutcome.SUCCESS)
+
+    assert calls == []
+
+
+@pytest.mark.asyncio
+async def test_processing_start_adds_eyes(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PHOTON_REACTIONS", "true")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.on_processing_start(_message_event(adapter))
+
+    assert len(calls) == 1
+    path, body = calls[0]
+    assert path == "/react"
+    assert body["emoji"] == _EYES
+    assert body["messageId"] == "target-msg-1"
+
+
+@pytest.mark.asyncio
+async def test_processing_success_swaps_to_thumbs_up(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("PHOTON_REACTIONS", "true")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.on_processing_complete(
+        _message_event(adapter), ProcessingOutcome.SUCCESS
+    )
+
+    assert [path for path, _ in calls] == ["/unreact", "/react"]
+    assert calls[1][1]["emoji"] == _THUMBS_UP
+
+
+@pytest.mark.asyncio
+async def test_processing_failure_swaps_to_thumbs_down(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("PHOTON_REACTIONS", "true")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.on_processing_complete(
+        _message_event(adapter), ProcessingOutcome.FAILURE
+    )
+
+    assert [path for path, _ in calls] == ["/unreact", "/react"]
+    assert calls[1][1]["emoji"] == _THUMBS_DOWN
+
+
+@pytest.mark.asyncio
+async def test_processing_cancelled_only_removes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("PHOTON_REACTIONS", "true")
+    adapter = _make_adapter(monkeypatch)
+    calls = _capture_sidecar(adapter)
+
+    await adapter.on_processing_complete(
+        _message_event(adapter), ProcessingOutcome.CANCELLED
+    )
+
+    assert [path for path, _ in calls] == ["/unreact"]
+
+
+# -- Inbound reaction routing ------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_inbound_reaction_on_bot_message_routed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture_handled(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_reaction_event(emoji="❤️"))
+
+    assert len(captured) == 1
+    event = captured[0]
+    assert event.text == "reaction:added:❤️"
+    assert event.message_type == MessageType.TEXT
+    assert event.source.chat_id == "+15551234567"
+
+
+@pytest.mark.asyncio
+async def test_inbound_reaction_sent_ids_fallback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """No targetDirection from the provider — gate on our own sent-id cache."""
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture_handled(adapter, monkeypatch)
+    adapter._record_sent_message("bot-msg-1")
+
+    await adapter._dispatch_inbound(
+        _reaction_event(target_id="bot-msg-1", target_direction=None)
+    )
+
+    assert len(captured) == 1
+
+
+@pytest.mark.asyncio
+async def test_inbound_reaction_on_foreign_message_dropped(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture_handled(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(
+        _reaction_event(target_id="someone-elses-msg", target_direction=None)
+    )
+
+    assert captured == []
+
+
+@pytest.mark.asyncio
+async def test_inbound_reaction_bypasses_require_mention(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A tapback never carries a wake word — it must skip group gating."""
+    monkeypatch.setenv("PHOTON_REQUIRE_MENTION", "true")
+    adapter = _make_adapter(monkeypatch)
+    captured = _capture_handled(adapter, monkeypatch)
+
+    await adapter._dispatch_inbound(_reaction_event(space_type="group"))
+
+    assert len(captured) == 1

tests/plugins/platforms/photon/test_setup_access.py

@@ -0,0 +1,112 @@
+"""Tests for `hermes photon setup`'s access auto-configuration.
+
+`_autoconfigure_access` allowlists the operator and points the cron home
+channel at their DM, writing to the per-test ~/.hermes/.env (the hermetic
+HERMES_HOME fixture isolates this). It must fill only unset keys so a re-run
+never clobbers a hand-tuned allowlist.
+"""
+from __future__ import annotations
+
+import argparse
+
+import pytest
+
+from hermes_cli.config import get_env_value, save_env_value
+from plugins.platforms.photon.adapter import _env_enablement
+from plugins.platforms.photon import cli
+
+
+def test_autoconfigure_access_fills_unset(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PHOTON_ALLOWED_USERS", raising=False)
+    monkeypatch.delenv("PHOTON_HOME_CHANNEL", raising=False)
+
+    cli._autoconfigure_access("+15551234567")
+
+    assert get_env_value("PHOTON_ALLOWED_USERS") == "+15551234567"
+    assert get_env_value("PHOTON_HOME_CHANNEL") == "+15551234567"
+
+
+def test_autoconfigure_access_preserves_existing_allowlist(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHOTON_ALLOWED_USERS", raising=False)
+    monkeypatch.delenv("PHOTON_HOME_CHANNEL", raising=False)
+    # A hand-tuned allowlist already in place must survive a setup re-run.
+    save_env_value("PHOTON_ALLOWED_USERS", "+19998887777,+15551112222")
+
+    cli._autoconfigure_access("+15551234567")
+
+    assert get_env_value("PHOTON_ALLOWED_USERS") == "+19998887777,+15551112222"
+    # The still-unset home channel is filled.
+    assert get_env_value("PHOTON_HOME_CHANNEL") == "+15551234567"
+
+
+def test_env_enablement_seeds_home_channel(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "project_123")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "secret_123")
+    monkeypatch.setenv("PHOTON_HOME_CHANNEL", "+15551234567")
+    monkeypatch.setenv("PHOTON_HOME_CHANNEL_NAME", "Primary DM")
+
+    seed = _env_enablement()
+
+    assert seed is not None
+    assert seed["home_channel"] == {
+        "chat_id": "+15551234567",
+        "name": "Primary DM",
+    }
+
+
+def test_env_enablement_home_channel_defaults_name(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "project_123")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "secret_123")
+    monkeypatch.setenv("PHOTON_HOME_CHANNEL", "+15551234567")
+    monkeypatch.delenv("PHOTON_HOME_CHANNEL_NAME", raising=False)
+
+    seed = _env_enablement()
+
+    assert seed is not None
+    assert seed["home_channel"] == {
+        "chat_id": "+15551234567",
+        "name": "Home",
+    }
+
+
+def test_setup_hint_uses_gateway_service_command(monkeypatch: pytest.MonkeyPatch, capsys) -> None:
+    monkeypatch.setattr(cli.photon_auth, "load_photon_token", lambda: "token")
+    monkeypatch.setattr(cli.photon_auth, "load_dashboard_project_id", lambda: "dashboard")
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "ensure_spectrum_enabled",
+        lambda token, dashboard_id: {"spectrumProjectId": "project_123"},
+    )
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "regenerate_project_secret",
+        lambda token, dashboard_id: "secret_123",
+    )
+    monkeypatch.setattr(cli.photon_auth, "store_project_credentials", lambda **kwargs: None)
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "register_user_if_absent",
+        lambda *args, **kwargs: ({"id": "user_123", "phoneNumber": "+15551234567"}, True),
+    )
+    monkeypatch.setattr(cli.photon_auth, "user_assigned_line", lambda user: "+15557654321")
+    monkeypatch.setattr(cli.photon_auth, "store_user_numbers", lambda **kwargs: None)
+    monkeypatch.setattr(cli, "_install_sidecar", lambda: 0)
+
+    rc = cli._cmd_setup(
+        argparse.Namespace(
+            project_name=None,
+            phone="+15551234567",
+            first_name=None,
+            last_name=None,
+            email=None,
+            no_browser=True,
+            skip_sidecar_install=False,
+        )
+    )
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "Start the gateway:  hermes gateway start" in out
+    assert "--platform photon" not in out

tests/plugins/platforms/photon/test_sidecar_lifecycle.py

@@ -0,0 +1,171 @@
+"""Sidecar lifecycle tests: orphan reaping and parent-death wiring.
+
+A hard gateway exit used to leave the detached Node sidecar squatting the
+loopback port with a token the next gateway run doesn't know — every
+replacement spawn then died on EADDRINUSE. These tests cover the startup
+reaper (`_reap_stale_sidecar`) and the stdin-pipe lifetime binding, without
+spawning Node or binding ports.
+"""
+from __future__ import annotations
+
+import subprocess
+from typing import Any, Dict, List, Tuple
+
+import pytest
+
+from gateway.config import PlatformConfig
+from plugins.platforms.photon import adapter as photon_adapter
+from plugins.platforms.photon.adapter import PhotonAdapter
+
+
+def _make_adapter(monkeypatch: pytest.MonkeyPatch) -> PhotonAdapter:
+    monkeypatch.setenv("PHOTON_PROJECT_ID", "test-project-id")
+    monkeypatch.setenv("PHOTON_PROJECT_SECRET", "test-project-secret")
+    cfg = PlatformConfig(enabled=True, token="", extra={})
+    return PhotonAdapter(cfg)
+
+
+class _ProbeClient:
+    """Fake httpx.AsyncClient whose /healthz probe behavior is injectable."""
+
+    connects = True
+
+    def __init__(self, *a: Any, **k: Any) -> None:
+        pass
+
+    async def __aenter__(self) -> "_ProbeClient":
+        return self
+
+    async def __aexit__(self, *a: Any) -> bool:
+        return False
+
+    async def post(self, *a: Any, **k: Any) -> Any:
+        if not self.connects:
+            raise photon_adapter.httpx.ConnectError("connection refused")
+
+        class _Resp:
+            status_code = 401  # orphan with a different token
+
+        return _Resp()
+
+
+def _capture_kills(monkeypatch: pytest.MonkeyPatch) -> List[Tuple[int, int]]:
+    kills: List[Tuple[int, int]] = []
+
+    def _fake_kill(pid: int, sig: int) -> None:
+        kills.append((pid, sig))
+
+    monkeypatch.setattr(photon_adapter.os, "kill", _fake_kill)
+    return kills
+
+
+@pytest.mark.asyncio
+async def test_reap_noop_when_port_free(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+
+    class _Refused(_ProbeClient):
+        connects = False
+
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _Refused)
+    kills = _capture_kills(monkeypatch)
+
+    await adapter._reap_stale_sidecar()
+
+    assert kills == []
+
+
+@pytest.mark.asyncio
+async def test_reap_kills_verified_orphan(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _ProbeClient)
+    monkeypatch.setattr(adapter, "_find_listener_pids", lambda port: [4242])
+    monkeypatch.setattr(adapter, "_pid_is_sidecar", lambda pid: True)
+    # Dies promptly on SIGTERM — no escalation expected.
+    monkeypatch.setattr(adapter, "_pid_alive", lambda pid: False)
+    kills = _capture_kills(monkeypatch)
+
+    await adapter._reap_stale_sidecar()
+
+    assert kills == [(4242, photon_adapter.signal.SIGTERM)]
+
+
+@pytest.mark.asyncio
+async def test_reap_escalates_to_sigkill(monkeypatch: pytest.MonkeyPatch) -> None:
+    adapter = _make_adapter(monkeypatch)
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _ProbeClient)
+    monkeypatch.setattr(adapter, "_find_listener_pids", lambda port: [4242])
+    monkeypatch.setattr(adapter, "_pid_is_sidecar", lambda pid: True)
+    monkeypatch.setattr(adapter, "_pid_alive", lambda pid: True)  # ignores TERM
+    # No clock fakery (logging also calls time.time, which makes a fake clock
+    # fragile) — this test rides out the real 3s SIGTERM grace window.
+    kills = _capture_kills(monkeypatch)
+
+    await adapter._reap_stale_sidecar()
+
+    assert (4242, photon_adapter.signal.SIGTERM) in kills
+    assert (4242, photon_adapter.signal.SIGKILL) in kills
+
+
+@pytest.mark.asyncio
+async def test_reap_raises_for_foreign_listener(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Never signal a process whose command line isn't our sidecar."""
+    adapter = _make_adapter(monkeypatch)
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _ProbeClient)
+    monkeypatch.setattr(adapter, "_find_listener_pids", lambda port: [777])
+    monkeypatch.setattr(adapter, "_pid_is_sidecar", lambda pid: False)
+    kills = _capture_kills(monkeypatch)
+
+    with pytest.raises(RuntimeError, match="in use by another process"):
+        await adapter._reap_stale_sidecar()
+
+    assert kills == []
+
+
+@pytest.mark.asyncio
+async def test_start_sidecar_spawns_with_stdin_pipe(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    """The spawn must hold a stdin pipe and enable the sidecar's EOF watch."""
+    adapter = _make_adapter(monkeypatch)
+
+    async def _no_reap() -> None:
+        pass
+
+    monkeypatch.setattr(adapter, "_reap_stale_sidecar", _no_reap)
+    (tmp_path / "node_modules").mkdir()
+    monkeypatch.setattr(photon_adapter, "_SIDECAR_DIR", tmp_path)
+
+    spawned: Dict[str, Any] = {}
+
+    class _FakeProc:
+        pid = 999
+        stdout = None
+        stdin = None
+
+        @staticmethod
+        def poll() -> None:
+            return None
+
+    def _fake_popen(cmd: List[str], **kwargs: Any) -> _FakeProc:
+        spawned["cmd"] = cmd
+        spawned["kwargs"] = kwargs
+        return _FakeProc()
+
+    monkeypatch.setattr(photon_adapter.subprocess, "Popen", _fake_popen)
+
+    class _HealthyClient(_ProbeClient):
+        async def post(self, *a: Any, **k: Any) -> Any:
+            class _Resp:
+                status_code = 200
+
+            return _Resp()
+
+    monkeypatch.setattr(photon_adapter.httpx, "AsyncClient", _HealthyClient)
+
+    await adapter._start_sidecar()
+
+    kwargs = spawned["kwargs"]
+    assert kwargs["stdin"] is subprocess.PIPE
+    assert kwargs["env"]["PHOTON_SIDECAR_WATCH_STDIN"] == "1"