fix(photon): don't kill sidecar at boot when legacy spectrum-ts dist is absent

[Mengchee118]

Summary

The Photon Spectrum sidecar dies at every boot once the spectrum-ts SDK layout drifts away from the legacy @spectrum-ts/imessage/dist path (e.g. after the rename to top-level spectrum-ts/dist + @photon-ai/* scopes).

patchSpectrumTs() in patch-spectrum-mixed-attachments.mjs hard-codes that legacy path and does throw new Error(...) when it's missing. index.mjs catches that and turns it into process.exit(3) — so the sidecar exits immediately on startup.

User-visible symptoms:

• Gateway reports Photon connected, but the status is stale — the sidecar is actually dead.
• No inbound iMessage is ever delivered.
• Outbound fails with Photon standalone send requires a running sidecar.
• Gateway loops on Reconnect photon failed, next retry in 300s.

Fix

The mixed-attachment shim only adjusts text + multi-attachment child ordering, so a missing legacy dist should be a no-op — not fatal. Return { patched: false } and skip gracefully instead of throwing. The spectrum-ts package itself is intact in this scenario; only the patch's hard-coded old path is stale.

   if (!fs.existsSync(dist)) {
-    throw new Error(`@spectrum-ts/imessage dist not found: ${dist}`);
+    // Layout drift: newer spectrum-ts ships as top-level spectrum-ts/dist
+    // (+ @photon-ai/* scopes) and no longer exposes @spectrum-ts/imessage/dist.
+    // The shim only affects text+multi-attachment ordering; skip gracefully
+    // instead of killing the sidecar at boot.
+    return { patched: false, reason: "legacy @spectrum-ts/imessage dist absent" };
   }

Test plan

• With the legacy dist absent, the sidecar boots, listens on 127.0.0.1:8789, and [photon] connected — streaming inbound over gRPC appears in the gateway log.
• /healthz returns {"ok":false,"error":"unauthorized"} (alive + enforcing the sidecar token).
• Verified on macOS against a drifted SDK layout (@photon-ai/* scopes present, @spectrum-ts/imessage/dist absent).

[tonydwb]

Code Review Summary

Verdict: LGTM

Clean 1-file fix tolerating absent legacy spectrum-ts dist in photon sidecar boot. Gracefully returns instead of killing the sidecar.

Looks Good

• Minimal fix with clear rationale
• Proper fallback (patched: false, reason provided)
• Prevents unnecessary sidecar crashes on SDK layout drift

---

Reviewed by Hermes Agent

[teknium1]

Thanks for isolating the boot-failure branch.

Problems

• This adds no regression test for the new return path. The existing patch tests create node_modules/@spectrum-ts/imessage/dist at tests/plugins/platforms/photon/test_spectrum_patch.py:155-160, so they do not exercise an absent directory.
• Current main deliberately pins spectrum-ts 8.0.0 (plugins/platforms/photon/sidecar/package.json:16), whose lockfile contains @spectrum-ts/imessage (package-lock.json:605-621), and documents that scoped dist directory as the patch target (plugins/platforms/photon/README.md:174-183). Please establish why an installation missing that required artifact should continue without the mixed-attachment patch.

Suggested changes

• Add a temp-root Node regression test asserting that a missing dist returns nonfatally.
• Clarify the supported SDK/layout scenario, and consider aligning this narrow case with the broader nonfatal patch-failure handling proposed in #58047.

Automated hermes-sweeper review.

[teknium1]

Please add a regression test that invokes this patcher against a temp root without node_modules/@spectrum-ts/imessage/dist and asserts a successful nonfatal result; the current tests only create and patch the scoped dist fixture.

[teknium1]

Closing as subsumed — #58047 (merged via #73563) made spectrum-patch failure non-fatal across the board, which covers the absent-legacy-dist case as a special case.