fix(photon): support immutable install trees for the sidecar (NS-606)

The Photon iMessage sidecar needs node_modules under
plugins/platforms/photon/sidecar/, but hosted/managed images keep the
whole install tree under an immutable /opt/hermes — every install and
self-heal path (setup CLI, stale-deps reinstall, cold install) died on
EROFS, and hosted users have no shell to work around it.

Three-layer fix, mirroring the WhatsApp bridge resolver pattern:

1. Bake the deps into the image. The Dockerfile now runs npm ci for the
   sidecar in the layer-cached dependency stage (deterministic installs
   from the committed lockfile; the postinstall spectrum-ts patch runs
   at build time). Hosted happy path needs no runtime install at all.

2. New sidecar_paths.resolve_sidecar_dir() decides where the sidecar
   runs from: PHOTON_SIDECAR_DIR override > writable source dir (dev
   installs, unchanged) > read-only dir with baked fresh deps (managed
   image) > mirror to $HERMES_HOME/photon/sidecar (writable data
   volume) when deps are missing or stale in a read-only tree. The
   mirror refreshes changed source files on image updates while
   keeping node_modules, so the existing lockfile-staleness self-heal
   works there.

3. connect() can now cold-install: _start_sidecar() runs the bounded
   npm ci bootstrap when node_modules is missing instead of raising
   immediately, and check_requirements() reports available when a
   self-install is possible (npm present + writable resolved dir) so
   the gateway actually creates the adapter on hosted instances. A
   failed bootstrap still raises the actionable error, which connect()
   surfaces as the retryable SIDECAR_FAILED fatal state on the
   dashboard.

Tests: resolver decision table (env override, in-place, mirror,
refresh, fail-open), cold-install lifecycle paths, and a Dockerfile
contract test guarding the baked-deps + no-chown invariants.

Fixes NS-606.

tests/plugins/platforms/photon/test_check_requirements_risks.py

@@ -105,6 +105,9 @@ def test_fix_logs_debug_with_sidecar_path_when_node_modules_missing(
     WARNING here would spam logs on every probe when photon is not configured."""
     monkeypatch.setattr(adapter_mod, "HTTPX_AVAILABLE", True)
     monkeypatch.setattr(adapter_mod, "_SIDECAR_DIR", tmp_path)
+    # NS-606: disable the connect-time self-heal branch (npm + writable dir
+    # would short-circuit to True) so this exercises the no-self-install path.
+    monkeypatch.setattr(adapter_mod, "_dir_writable", lambda _p: False)
     # node_modules intentionally NOT created — simulates failed npm install
 
     with caplog.at_level(logging.DEBUG, logger="plugins.platforms.photon.adapter"):
@@ -148,6 +151,9 @@ def test_risk2_fix_empty_node_modules_no_longer_passes_guard(
     monkeypatch.setattr(adapter_mod, "HTTPX_AVAILABLE", True)
     monkeypatch.setattr(adapter_mod, "_SIDECAR_DIR", tmp_path)
     monkeypatch.setattr(adapter_mod, "_NPM_ERROR_LOG", tmp_path / ".photon-npm-error.log")
+    # NS-606: disable the connect-time self-heal branch so the guard itself
+    # (empty node_modules must not read as installed) is what's under test.
+    monkeypatch.setattr(adapter_mod, "_dir_writable", lambda _p: False)
     (tmp_path / "node_modules").mkdir()  # empty — spectrum-ts absent
 
     # Fix verified: False instead of the old false-positive True.
@@ -264,6 +270,8 @@ def test_fix_risk3_check_requirements_surfaces_npm_error_in_debug_log(
     monkeypatch.setattr(adapter_mod, "HTTPX_AVAILABLE", True)
     monkeypatch.setattr(adapter_mod, "_SIDECAR_DIR", tmp_path)
     monkeypatch.setattr(adapter_mod, "_NPM_ERROR_LOG", error_log)
+    # NS-606: disable self-heal so the npm-error surfacing branch is reached.
+    monkeypatch.setattr(adapter_mod, "_dir_writable", lambda _p: False)
     # node_modules NOT created
 
     with caplog.at_level(logging.DEBUG, logger="plugins.platforms.photon.adapter"):

tests/plugins/platforms/photon/test_npm_error_log_regression.py

@@ -118,6 +118,8 @@ def test_regression_oserror_on_log_read_does_not_propagate(
 
     monkeypatch.setattr(adapter_mod, "HTTPX_AVAILABLE", True)
     monkeypatch.setattr(adapter_mod, "_SIDECAR_DIR", tmp_path)
+    # NS-606: disable self-heal so the log-read branch is reached.
+    monkeypatch.setattr(adapter_mod, "_dir_writable", lambda _p: False)
     monkeypatch.setattr(adapter_mod, "_NPM_ERROR_LOG", _UnreadablePath(tmp_path / ".err"))
 
     result = adapter_mod.check_requirements()
@@ -264,6 +266,8 @@ def test_regression_debug_log_emitted_even_without_error_log(
     monkeypatch.setattr(adapter_mod, "HTTPX_AVAILABLE", True)
     monkeypatch.setattr(adapter_mod, "_SIDECAR_DIR", tmp_path)
     monkeypatch.setattr(adapter_mod, "_NPM_ERROR_LOG", tmp_path / ".photon-npm-error.log")
+    # NS-606: disable self-heal so the debug-log branch is reached.
+    monkeypatch.setattr(adapter_mod, "_dir_writable", lambda _p: False)
     # node_modules NOT created, error log NOT created
 
     with caplog.at_level(logging.DEBUG, logger="plugins.platforms.photon.adapter"):

tests/plugins/platforms/photon/test_sidecar_lifecycle.py

@@ -191,20 +191,106 @@ async def test_start_sidecar_spawns_with_stdin_pipe(
 
 
 @pytest.mark.asyncio
-async def test_start_sidecar_rejects_empty_node_modules(
+async def test_start_sidecar_cold_installs_missing_deps(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    """Missing node_modules must trigger an install attempt, not a bare raise.
+
+    NS-606: on hosted images the user cannot shell in to run
+    `hermes photon setup`, so the connect path is the only chance to
+    bootstrap the sidecar deps (into the writable resolved dir).
+    """
+    adapter = _make_adapter(monkeypatch)
+    monkeypatch.setattr(photon_adapter, "_SIDECAR_DIR", tmp_path)
+
+    installs: List[str] = []
+
+    def _fake_install() -> None:
+        installs.append("ran")
+        (tmp_path / "node_modules" / "spectrum-ts").mkdir(parents=True)
+
+    monkeypatch.setattr(photon_adapter, "_reinstall_sidecar_deps", _fake_install)
+
+    async def _no_reap() -> None:
+        pass
+
+    monkeypatch.setattr(adapter, "_reap_stale_sidecar", _no_reap)
+
+    class _PatchResult:
+        returncode = 0
+        stdout = ""
+        stderr = ""
+
+    monkeypatch.setattr(
+        photon_adapter.subprocess, "run", lambda *a, **k: _PatchResult()
+    )
+
+    class _FakeProc:
+        pid = 999
+        stdout = None
+        stdin = None
+
+        @staticmethod
+        def poll() -> None:
+            return None
+
+    monkeypatch.setattr(
+        photon_adapter.subprocess, "Popen", lambda *a, **k: _FakeProc()
+    )
+
+    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()
+
+    assert installs == ["ran"]
+
+
+@pytest.mark.asyncio
+async def test_start_sidecar_reinstalls_empty_node_modules(
     monkeypatch: pytest.MonkeyPatch, tmp_path
 ) -> None:
     """A partial/aborted npm install leaves an empty node_modules/ behind.
 
-    _start_sidecar() must reject it the same way check_requirements() does
-    (both go through sidecar_deps_installed()) instead of spawning a sidecar
-    that immediately crashes on a missing spectrum-ts module.
+    _start_sidecar() must treat it as not-installed the same way
+    check_requirements() does (both go through sidecar_deps_installed())
+    instead of spawning a sidecar that immediately crashes on a missing
+    spectrum-ts module. With the NS-606 cold-install path, "treat as
+    not-installed" means: attempt a reinstall, and raise the actionable
+    error if that still doesn't produce spectrum-ts.
     """
     adapter = _make_adapter(monkeypatch)
     (tmp_path / "node_modules").mkdir()  # empty — spectrum-ts absent
     monkeypatch.setattr(photon_adapter, "_SIDECAR_DIR", tmp_path)
 
-    with pytest.raises(RuntimeError, match="not installed"):
+    installs: List[str] = []
+    monkeypatch.setattr(
+        photon_adapter, "_reinstall_sidecar_deps", lambda: installs.append("ran")
+    )
+
+    with pytest.raises(RuntimeError, match="could not be installed"):
+        await adapter._start_sidecar()
+
+    assert installs == ["ran"]
+
+
+@pytest.mark.asyncio
+async def test_start_sidecar_raises_when_cold_install_fails(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    """If the bootstrap install can't produce node_modules, fail with the
+    actionable error (surfaced as SIDECAR_FAILED by connect())."""
+    adapter = _make_adapter(monkeypatch)
+    monkeypatch.setattr(photon_adapter, "_SIDECAR_DIR", tmp_path)
+    monkeypatch.setattr(photon_adapter, "_reinstall_sidecar_deps", lambda: None)
+
+    with pytest.raises(RuntimeError, match="could not be installed"):
         await adapter._start_sidecar()
 
 

tests/plugins/platforms/photon/test_sidecar_paths.py

@@ -0,0 +1,149 @@
+"""Tests for the Photon sidecar directory resolver (NS-606).
+
+Hosted/managed images keep the plugin tree under an immutable
+``/opt/hermes``; ``resolve_sidecar_dir`` must run in place when the deps are
+baked and current, and mirror the sidecar to the writable ``HERMES_HOME``
+volume when a runtime install is unavoidable.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+import plugins.platforms.photon.sidecar_paths as sidecar_paths
+
+
+def _seed_source(source: Path, *, with_node_modules: bool = False) -> None:
+    source.mkdir(parents=True, exist_ok=True)
+    for name in sidecar_paths._MIRROR_FILES:
+        (source / name).write_text(f"// {name}\n", encoding="utf-8")
+    if with_node_modules:
+        (source / "node_modules").mkdir()
+        (source / "node_modules" / ".package-lock.json").write_text(
+            "{}", encoding="utf-8"
+        )
+
+
+def _freeze_writability(monkeypatch, *, writable: bool) -> None:
+    monkeypatch.setattr(sidecar_paths, "_dir_writable", lambda _p: writable)
+
+
+def test_env_override_wins(tmp_path, monkeypatch) -> None:
+    override = tmp_path / "custom"
+    monkeypatch.setenv("PHOTON_SIDECAR_DIR", str(override))
+    assert sidecar_paths.resolve_sidecar_dir(tmp_path / "src") == override
+
+
+def test_writable_source_runs_in_place(tmp_path, monkeypatch) -> None:
+    """Dev installs: writable tree keeps today's behavior exactly."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    source = tmp_path / "src"
+    _seed_source(source)
+    _freeze_writability(monkeypatch, writable=True)
+    assert sidecar_paths.resolve_sidecar_dir(source) == source
+
+
+def test_readonly_source_with_baked_fresh_deps_runs_in_place(
+    tmp_path, monkeypatch
+) -> None:
+    """Managed-image happy path: deps baked at build time, no mirror needed."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    source = tmp_path / "src"
+    _seed_source(source, with_node_modules=True)
+    # Marker newer than lockfile == fresh install.
+    lock = source / "package-lock.json"
+    marker = source / "node_modules" / ".package-lock.json"
+    os.utime(lock, (1000.0, 1000.0))
+    os.utime(marker, (2000.0, 2000.0))
+    _freeze_writability(monkeypatch, writable=False)
+    assert sidecar_paths.resolve_sidecar_dir(source) == source
+
+
+def test_readonly_source_missing_deps_mirrors_to_hermes_home(
+    tmp_path, monkeypatch
+) -> None:
+    """Immutable tree without baked deps must relocate to the data volume."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    home = tmp_path / "home"
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    source = tmp_path / "src"
+    _seed_source(source)  # no node_modules
+    _freeze_writability(monkeypatch, writable=False)
+
+    resolved = sidecar_paths.resolve_sidecar_dir(source)
+
+    assert resolved == home / "photon" / "sidecar"
+    for name in sidecar_paths._MIRROR_FILES:
+        assert (resolved / name).read_text(encoding="utf-8") == f"// {name}\n"
+
+
+def test_readonly_source_stale_baked_deps_mirrors(tmp_path, monkeypatch) -> None:
+    """Baked deps older than the lockfile (image skew) must not run in place."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    home = tmp_path / "home"
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    source = tmp_path / "src"
+    _seed_source(source, with_node_modules=True)
+    lock = source / "package-lock.json"
+    marker = source / "node_modules" / ".package-lock.json"
+    os.utime(lock, (2000.0, 2000.0))
+    os.utime(marker, (1000.0, 1000.0))
+    _freeze_writability(monkeypatch, writable=False)
+
+    assert sidecar_paths.resolve_sidecar_dir(source) == home / "photon" / "sidecar"
+
+
+def test_mirror_refresh_updates_changed_files_and_keeps_node_modules(
+    tmp_path, monkeypatch
+) -> None:
+    """Image update changes index.mjs → re-copied; installed deps survive."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    home = tmp_path / "home"
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    source = tmp_path / "src"
+    _seed_source(source)
+    _freeze_writability(monkeypatch, writable=False)
+
+    mirror = sidecar_paths.resolve_sidecar_dir(source)
+    # Simulate a completed npm install in the mirror.
+    (mirror / "node_modules").mkdir()
+    (mirror / "node_modules" / "installed.txt").write_text("x", encoding="utf-8")
+
+    # Image update rewrites a source file.
+    (source / "index.mjs").write_text("// index.mjs v2\n", encoding="utf-8")
+
+    resolved = sidecar_paths.resolve_sidecar_dir(source)
+
+    assert resolved == mirror
+    assert (mirror / "index.mjs").read_text(encoding="utf-8") == "// index.mjs v2\n"
+    assert (mirror / "node_modules" / "installed.txt").exists()
+
+
+def test_mirror_failure_falls_back_to_source(tmp_path, monkeypatch) -> None:
+    """If HERMES_HOME is unusable too, return the source dir (fail-open)."""
+    monkeypatch.delenv("PHOTON_SIDECAR_DIR", raising=False)
+    # Point HERMES_HOME at a path under a file so mkdir fails.
+    blocker = tmp_path / "blocker"
+    blocker.write_text("", encoding="utf-8")
+    monkeypatch.setenv("HERMES_HOME", str(blocker / "home"))
+    source = tmp_path / "src"
+    _seed_source(source)
+    _freeze_writability(monkeypatch, writable=False)
+
+    assert sidecar_paths.resolve_sidecar_dir(source) == source
+
+
+def test_dir_writable_probe(tmp_path) -> None:
+    assert sidecar_paths.dir_writable(tmp_path) is True
+    ro = tmp_path / "ro"
+    ro.mkdir()
+    ro.chmod(0o555)
+    try:
+        if os.geteuid() == 0:  # pragma: no cover - root ignores perms
+            pytest.skip("root bypasses directory permissions")
+        assert sidecar_paths.dir_writable(ro) is False
+    finally:
+        ro.chmod(0o755)