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.

plugins/platforms/photon/adapter.py

@@ -184,7 +184,13 @@ _DEDUP_WINDOW_SECONDS = 48 * 3600
 
 _FFFC_WAIT_SECONDS = 15.0  # Timeout for waiting on an attachment after a U+FFFC placeholder.
 
-_SIDECAR_DIR = Path(__file__).parent / "sidecar"
+# Resolved once at import: the installed plugin tree when writable (dev
+# installs), or a mirror on the durable data volume when the install tree
+# is immutable and the baked deps are missing/stale (hosted images, NS-606).
+# See sidecar_paths.resolve_sidecar_dir for the full decision table.
+from .sidecar_paths import dir_writable as _dir_writable, resolve_sidecar_dir
+
+_SIDECAR_DIR = resolve_sidecar_dir()
 _NPM_ERROR_LOG = _SIDECAR_DIR / ".photon-npm-error.log"
 _NPM_ERROR_LOG_MAX_CHARS = 300
 
@@ -367,6 +373,16 @@ def check_requirements() -> bool:
         # prevents a false positive where an empty/broken node_modules/ dir
         # causes check_requirements() to return True while the sidecar crashes
         # at runtime with an unrelated-looking missing-module error.
+        #
+        # NS-606: if we can self-install at connect time — npm on PATH and
+        # the (resolved, possibly mirrored) sidecar dir is writable — report
+        # available so the gateway creates the adapter and ``_start_sidecar``
+        # cold-installs from the committed lockfile (on hosted images the
+        # user has no CLI to run `hermes photon setup`, so the connect path
+        # must self-heal). Otherwise keep returning False so
+        # `hermes setup` / status surface the missing-deps state.
+        if bool(shutil.which("npm")) and _dir_writable(_SIDECAR_DIR):
+            return True
         # DEBUG (not WARNING): this is the normal pre-setup state.
         # check_fn() is called from multiple hot paths in the core
         # (load_gateway_config, hermes status, GET /api/status polling) —
@@ -1519,10 +1535,27 @@ class PhotonAdapter(BasePlatformAdapter):
 
     async def _start_sidecar(self) -> None:
         if not sidecar_deps_installed():
-            raise RuntimeError(
-                f"Photon sidecar deps not installed. Run: "
-                f"cd {_SIDECAR_DIR} && npm install   (or `hermes photon setup`)"
+            # Cold install (NS-606): on hosted/managed images the install
+            # tree is immutable and the user has no CLI to run
+            # `hermes photon setup`, so the connect path must be able to
+            # bootstrap the deps itself. _SIDECAR_DIR has already been
+            # resolved to a writable location (or mirrored to the data
+            # volume) by sidecar_paths.resolve_sidecar_dir; `npm ci` off
+            # the committed lockfile is deterministic and bounded by
+            # _NPM_REINSTALL_TIMEOUT. Uses sidecar_deps_installed() — not a
+            # bare node_modules/ existence check — so a partial/aborted npm
+            # install (empty node_modules/) also triggers the reinstall.
+            logger.info(
+                "[photon] sidecar deps not installed; installing into %s",
+                _SIDECAR_DIR,
             )
+            await asyncio.to_thread(_reinstall_sidecar_deps)
+            if not sidecar_deps_installed():
+                raise RuntimeError(
+                    f"Photon sidecar deps could not be installed into "
+                    f"{_SIDECAR_DIR} (see log for the npm error). "
+                    f"Run: cd {_SIDECAR_DIR} && npm ci   (or `hermes photon setup`)"
+                )
         # A `hermes update` that bumps the spectrum-ts pin rewrites
         # package-lock.json but never reinstalls node_modules, so the sidecar
         # spawns against stale deps and dies on every reconnect (the v8 patch

plugins/platforms/photon/cli.py

@@ -30,8 +30,11 @@ from hermes_cli.colors import Colors, color
 
 from . import auth as photon_auth
 from .adapter import _NPM_ERROR_LOG_MAX_CHARS, sidecar_deps_installed
+from .sidecar_paths import resolve_sidecar_dir
 
-_SIDECAR_DIR = Path(__file__).parent / "sidecar"
+# Writable sidecar runtime dir (mirrors to HERMES_HOME on immutable
+# installs — NS-606). All npm/setup work happens here.
+_SIDECAR_DIR = resolve_sidecar_dir()
 # Written on npm failure so check_requirements() can surface the root cause
 # when called later (gateway start, hermes status). Cleared on success.
 _NPM_ERROR_LOG = _SIDECAR_DIR / ".photon-npm-error.log"

plugins/platforms/photon/sidecar_paths.py

@@ -0,0 +1,141 @@
+"""
+Resolve where the Photon sidecar runs from and where its Node deps live.
+
+The sidecar source ships inside the installed plugin tree
+(``plugins/platforms/photon/sidecar/``). On dev/source installs that tree is
+writable and everything — ``npm ci``, the spectrum patch, the sidecar itself —
+happens in place. Hosted/managed images instead keep the whole install tree
+under an immutable ``/opt/hermes`` (read-only for the hermes user), which
+broke every install/self-heal path with EROFS (NS-606).
+
+Resolution order (mirrors ``resolve_whatsapp_bridge_dir`` for the Baileys
+bridge, which hit the same wall):
+
+1. ``PHOTON_SIDECAR_DIR`` env override — operator escape hatch, used as-is.
+2. Source dir writable → run in place (dev installs, unchanged behavior).
+3. Source dir read-only but ``node_modules`` is baked and current → run in
+   place. This is the managed-image happy path: the Dockerfile bakes the
+   sidecar deps with ``npm ci`` at build time (deterministic installs,
+   NS-559), so no runtime install is ever needed.
+4. Source dir read-only and deps missing or stale → mirror the sidecar
+   source files to ``$HERMES_HOME/photon/sidecar`` (the durable data volume,
+   e.g. ``/opt/data`` on hosted) and return that. The caller's normal
+   install/self-heal machinery then works there because it is writable.
+
+The mirror is refreshed on every resolve: when an image update changes a
+sidecar source file, the changed file is re-copied (content compare, not
+mtime) while ``node_modules`` is left in place — the adapter's existing
+lockfile-vs-install-marker staleness check then triggers the ``npm ci``
+self-heal inside the mirror.
+
+This module is import-light on purpose: both ``adapter.py`` (gateway) and
+``cli.py`` (``hermes photon ...``) use it.
+"""
+
+from __future__ import annotations
+
+import filecmp
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SOURCE_SIDECAR_DIR = Path(__file__).parent / "sidecar"
+
+# The files that define the sidecar. Mirrored into the writable runtime dir
+# when the install tree is read-only. node_modules is deliberately absent —
+# it is either baked (managed image) or installed by npm in the mirror.
+_MIRROR_FILES = (
+    "index.mjs",
+    "package.json",
+    "package-lock.json",
+    "patch-spectrum-mixed-attachments.mjs",
+)
+
+
+def dir_writable(path: Path) -> bool:
+    """True when we can create files in ``path`` (probe-based, not stat).
+
+    A stat-mode check lies on containers (root-squash, read-only bind
+    mounts), so probe with a real create+unlink like the WhatsApp bridge
+    resolver does.
+    """
+    probe = path / ".hermes-write-probe"
+    try:
+        probe.touch()
+        probe.unlink()
+        return True
+    except OSError:
+        return False
+
+
+# Backwards-friendly private alias for module-internal use.
+_dir_writable = dir_writable
+
+
+def _lock_newer_than_install(sidecar_dir: Path) -> bool:
+    """True when the committed lockfile postdates npm's install marker.
+
+    Same signal as ``adapter._sidecar_deps_stale`` — duplicated here (three
+    lines) rather than imported so this module stays import-light for the
+    CLI. Returns False on any stat failure so an odd filesystem never forces
+    the mirror path.
+    """
+    lockfile = sidecar_dir / "package-lock.json"
+    marker = sidecar_dir / "node_modules" / ".package-lock.json"
+    try:
+        return lockfile.stat().st_mtime > marker.stat().st_mtime
+    except OSError:
+        return False
+
+
+def resolve_sidecar_dir(source_dir: Optional[Path] = None) -> Path:
+    """Return the directory the sidecar should run from (see module doc).
+
+    ``source_dir`` defaults to the installed plugin tree; tests and callers
+    that monkeypatch the adapter's ``_SIDECAR_DIR`` pass it through so the
+    override keeps working.
+    """
+    source = Path(source_dir) if source_dir is not None else SOURCE_SIDECAR_DIR
+
+    override = os.getenv("PHOTON_SIDECAR_DIR")
+    if override:
+        return Path(override)
+
+    if _dir_writable(source):
+        return source
+
+    # Read-only install tree (hosted/managed image). If the image baked the
+    # deps at build time and they match the lockfile, run in place — the
+    # sidecar itself never writes inside its own directory.
+    if (source / "node_modules").exists() and not _lock_newer_than_install(source):
+        return source
+
+    # Deps missing or stale inside a read-only tree: mirror to the durable
+    # data volume so the normal install/self-heal machinery has somewhere
+    # writable to work.
+    from hermes_constants import get_hermes_home
+
+    mirror = get_hermes_home() / "photon" / "sidecar"
+    try:
+        mirror.mkdir(parents=True, exist_ok=True)
+        for name in _MIRROR_FILES:
+            src = source / name
+            if not src.exists():
+                continue
+            dst = mirror / name
+            if not dst.exists() or not filecmp.cmp(str(src), str(dst), shallow=False):
+                shutil.copy2(str(src), str(dst))
+        return mirror
+    except OSError as exc:
+        logger.warning(
+            "[photon] install tree is read-only and mirroring the sidecar "
+            "to %s failed (%s) — falling back to the read-only source dir; "
+            "dependency installs will not be possible",
+            mirror,
+            exc,
+        )
+        return source