yaver-feedback-react-native 0.8.7 → 0.8.9

package/dist/_core/constants.d.ts

@@ -27,9 +27,13 @@ export declare const DEFAULT_BEACON_UDP_PORT = 19837;
 /**
  * How old an agent's last heartbeat can be before the device is
  * considered offline. Mirrors `backend/convex/devices.ts` so
- * Convex + every client agree on the same threshold.
+ * Convex + every client agree on the same threshold. The agent
+ * heartbeats every 5 min (see `desktop/agent/main.go::heartbeatLoop`),
+ * so 6 min tolerates one missed beat + 60 s of jitter without
+ * flapping. Sub-minute death detection comes from the P2P bus, not
+ * this threshold.
  */
-export declare const HEARTBEAT_STALE_MS = 90000;
+export declare const HEARTBEAT_STALE_MS = 360000;
 /**
  * How long after the last UDP beacon an agent is still considered
  * "locally present". Re-broadcast interval is 3 s, so 10 s covers

package/dist/_core/constants.js

@@ -51,9 +51,13 @@ exports.DEFAULT_BEACON_UDP_PORT = 19837;
 /**
  * How old an agent's last heartbeat can be before the device is
  * considered offline. Mirrors `backend/convex/devices.ts` so
- * Convex + every client agree on the same threshold.
+ * Convex + every client agree on the same threshold. The agent
+ * heartbeats every 5 min (see `desktop/agent/main.go::heartbeatLoop`),
+ * so 6 min tolerates one missed beat + 60 s of jitter without
+ * flapping. Sub-minute death detection comes from the P2P bus, not
+ * this threshold.
  */
-exports.HEARTBEAT_STALE_MS = 90000;
+exports.HEARTBEAT_STALE_MS = 360000;
 /**
  * How long after the last UDP beacon an agent is still considered
  * "locally present". Re-broadcast interval is 3 s, so 10 s covers

package/dist/types.d.ts

@@ -118,6 +118,35 @@ export interface FeedbackConfig {
     preferredDeviceId?: string;
     /** How feedback collection is triggered */
     trigger?: 'shake' | 'floating-button' | 'manual';
+    /**
+     * Non-default escape hatch for host apps that want the SDK without
+     * shake gesture handling. When enabled:
+     * - the SDK does not start ShakeDetector
+     * - if `quickIcon` was left as `'auto'`/unset, it is promoted to `'always'`
+     * - the app should rely on the draggable quick icon or explicit
+     *   `YaverFeedback.startReport()` calls instead
+     *
+     * Intended for builds where another surface owns motion / haptics.
+     */
+    disableShakeGesture?: boolean;
+    /**
+     * Auto-open the BlackBox SSE command channel after init() returns.
+     *
+     * Default: `true` (0.8.8+). Listens for `reload`, `reload_bundle`,
+     * and `status` commands the agent broadcasts after a vibe-coding
+     * task commits a fix — drives the auto-reload loop without the host
+     * app needing to call `BlackBox.start()` manually.
+     *
+     * The auto-start is deferred 500ms after init() and gated on having
+     * BOTH `agentUrl` and `authToken` resolved, to avoid the iOS 18.3.1
+     * rope-string SIGSEGV that the early auto-start in 0.7.6 hit when
+     * the agent was in needs-auth mode (tight 401-retry loop in SSE).
+     *
+     * Set `false` if your host app wants to gate BlackBox start on its
+     * own state machine (e.g. only after the user opts into telemetry).
+     * Calling `BlackBox.start()` manually is still safe — it's idempotent.
+     */
+    autoStartBlackBox?: boolean;
     /**
      * Small tap-to-open icon that floats above the app so the user
      * doesn't have to shake every time they want to open feedback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaver-feedback-react-native",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Visual feedback SDK for Yaver \u2014 bug reports, screen recording, voice annotations, and local-first developer workflows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/MachinePickerScreen.tsx

@@ -120,8 +120,8 @@ export const YaverMachinePickerScreen: React.FC<YaverMachinePickerProps> = ({
     // yellows from phone↔backend clock skew around the 89-90 s mark.
     //
     // `runnerDown` intentionally does NOT flip the dot. That flag
-    // tracks whether the AI runner (claude-code, aider, ...) is
-    // healthy — a separate concern from "can I reach this machine?"
+    // tracks whether the AI runner (claude-code / codex / opencode)
+    // is healthy — a separate concern from "can I reach this machine?"
     // Mobile app surfaces runner issues via a separate badge, not
     // this dot. Picker's job is reachability, nothing more.
     const effectivelyReachable = probe?.reachable === true;

package/src/YaverFeedback.ts

@@ -28,10 +28,13 @@ import {
 // (mobile/ios/Yaver/YaverInfo.{swift,m} + Android counterpart); a
 // standalone app bundled by its own developer has no such module.
 // When the SDK is loaded through Yaver's Hermes-push guest runtime we
-// deliberately no-op every public entry point — Yaver owns the shake
-// gesture ("Reload / Back to Yaver" overlay), the feedback capture
-// flow, and the BlackBox streaming; running a second copy from inside
-// the guest just produces duplicate UIs and double P2P sessions.
+// run in HOST MODE: dormant by default (no shake detector, no auto
+// BlackBox, no QuickActionIcon — Yaver's host shell owns those), but
+// we DO register a DeviceEventEmitter listener so Yaver's overlay can
+// flip the SDK live at runtime. When the user shakes inside the guest
+// app and taps "Feedback" on the Yaver overlay, AppDelegate dispatches
+// `yaverFeedback:startReport` into this bridge; the listener wakes the
+// SDK and opens the modal in-place over the running guest UI.
 function isRunningInsideYaverHost(): boolean {
   try {
     return !!(NativeModules as any)?.YaverInfo;
@@ -40,11 +43,105 @@ function isRunningInsideYaverHost(): boolean {
   }
 }
 
-// Suppresses SDK activation when inside Yaver super-host. Callers of
-// YaverFeedback.init / startReport / startBatchRecording / … early-out
-// by checking this first so the SDK's side effects (accelerometer,
-// BlackBox HTTP, SSE command channel, FeedbackModal mount) never start.
-const YAVER_HOST_SUPPRESS = isRunningInsideYaverHost();
+// Two distinct compile-time modes for a guest app like sfmg / talos:
+//
+//   YAVER_HOST_MODE  — bundled by Yaver's agent (/dev/build-native) for
+//                      loading inside Yaver mobile. SDK code is in the
+//                      bundle but boots PASSIVE: no shake detector, no
+//                      auto-BlackBox, no container UI. Yaver's host
+//                      overlay owns the shake gesture; when the user
+//                      taps "Feedback" on Yaver's overlay, AppDelegate
+//                      dispatches yaverFeedback:hostActivate into this
+//                      bridge and the SDK runtime-flips active for a
+//                      single feedback session.
+//
+//   YAVER_SDK_MODE   — sfmg's own standalone TestFlight / Play Store
+//                      build, with the Yaver SDK embedded. SDK boots
+//                      active: shake → modal directly, no Yaver host
+//                      involved. Default for normal `expo build`.
+//
+// Both can be forced at build time via process.env. When neither is
+// set, fall back to runtime detection: if the YaverInfo native module
+// exists (we're inside Yaver), assume HOST_MODE; else SDK_MODE. This
+// keeps older bundles (built before the agent learned to set the env)
+// working unchanged.
+const YAVER_HOST_MODE_BUILD = (() => {
+  try {
+    const v = (process.env as any)?.YAVER_HOST_MODE;
+    return v === 'true' || v === '1' || v === true || v === 1;
+  } catch { return false; }
+})();
+const YAVER_SDK_MODE_BUILD = (() => {
+  try {
+    const v = (process.env as any)?.YAVER_SDK_MODE;
+    return v === 'true' || v === '1' || v === true || v === 1;
+  } catch { return false; }
+})();
+
+// Effective mode after considering build flags AND runtime detection.
+const IS_HOST_MODE =
+  YAVER_HOST_MODE_BUILD ||
+  (!YAVER_SDK_MODE_BUILD && isRunningInsideYaverHost());
+
+// Tracks whether we've been runtime-activated by the host (sfmg-in-Yaver
+// case). Independent of `enabled` so we can tell "host turned us on for
+// one shot" apart from "developer toggled enabled programmatically".
+let hostActivated = false;
+
+// Host-activation listener. Always registered when in HOST mode so a
+// Yaver overlay tap can wake the SDK even before the guest's
+// YaverFeedback.init() runs. AppDelegate (mobile/ios/Yaver/AppDelegate.
+// swift::handleFeedbackTap) sends `yaverFeedback:startReport` into the
+// guest bridge when the user picks Feedback on the shake overlay.
+//
+// Activation flow:
+//   1. Try Yaver's existing bearer (NativeModules.YaverInfo.
+//      inheritedAuthToken, populated by Yaver mobile's auth.ts on
+//      sign-in). Validate against /auth/validate before trusting.
+//   2. If valid: setAuthToken + open feedback modal in-place (the
+//      modal already supports hot reload, screenshot, vibing chat).
+//   3. If missing or invalid: open the SDK's own login screen.
+if (IS_HOST_MODE) {
+  try {
+    const { DeviceEventEmitter } = require('react-native');
+    DeviceEventEmitter.addListener('yaverFeedback:startReport', () => {
+      hostActivated = true;
+      enabled = true;
+      void (async () => {
+        const yi = (NativeModules as any)?.YaverInfo;
+        const inheritedToken = String(yi?.inheritedAuthToken || '').trim();
+        const inheritedAgent = String(yi?.inheritedAgentUrl || '').trim();
+        const inheritedDevice = String(yi?.inheritedDeviceId || '').trim();
+        if (inheritedToken) {
+          // Lazy-import auth.ts so module load doesn't drag the auth
+          // network code into the active set when the SDK is dormant.
+          const { validateToken } = require('./auth');
+          const user = await validateToken(inheritedToken).catch(() => null);
+          if (user) {
+            // Seed config + connect the SDK to the host's auth.
+            if (!config) {
+              YaverFeedback.init({
+                authToken: inheritedToken,
+                agentUrl: inheritedAgent || undefined,
+                preferredDeviceId: inheritedDevice || undefined,
+              } as FeedbackConfig);
+            }
+            await YaverFeedback.setAuthToken(inheritedToken);
+            await YaverFeedback.startReport();
+            return;
+          }
+        }
+        // No token, or token invalid — fall through to the SDK's own
+        // login screen. The user picks an OAuth provider; on success
+        // the modal continues with the new token.
+        if (!config) {
+          YaverFeedback.init({} as FeedbackConfig);
+        }
+        YaverFeedback.showLogin();
+      })();
+    });
+  } catch { /* react-native unavailable in jsdom unit tests */ }
+}
 
 let config: FeedbackConfig | null = null;
 let enabled = false;
@@ -126,17 +223,37 @@ export class YaverFeedback {
    * via `YaverDiscovery` on the first `startReport()` call.
    */
   static init(cfg: FeedbackConfig): void {
-    if (YAVER_HOST_SUPPRESS) {
-      // Running inside Yaver's super-host — yield to Yaver's native UX.
-      enabled = false;
-      return;
-    }
     config = {
       trigger: 'shake',
       maxRecordingDuration: 120,
       autoLogin: true,
       ...cfg,
     };
+    if (IS_HOST_MODE) {
+      // sfmg / talos / etc. running inside Yaver mobile (compile-time
+      // YAVER_HOST_MODE or runtime-detected). Store config so a later
+      // host activation (yaverFeedback:startReport from AppDelegate)
+      // can open the modal — but skip the side effects Yaver's host
+      // shell owns: shake detector, auto-BlackBox, QuickActionIcon.
+      enabled = false;
+      // Configure auth endpoints + strict-native-auth even in passive
+      // mode so a host-activated session uses the same login routing
+      // the standalone path would.
+      configureAuthEndpoints({
+        convexSiteUrl: cfg.authConvexSiteUrl,
+        webBaseUrl: cfg.authWebBaseUrl,
+      });
+      setStrictNativeAuth(cfg.strictNativeAuth === true);
+      if (!config.convexUrl) {
+        config.convexUrl = cfg.authConvexSiteUrl ?? DEFAULT_CONVEX_SITE_URL;
+      }
+      maxErrors = cfg.maxCapturedErrors ?? 5;
+      errorBuffer = [];
+      return;
+    }
+    if (config.disableShakeGesture && (!config.quickIcon || config.quickIcon === 'auto')) {
+      config.quickIcon = 'always';
+    }
     firstShakeFired = false;
 
     // Route the in-SDK login screen to prod yaver.io by default; callers may
@@ -155,11 +272,17 @@ export class YaverFeedback {
       config.convexUrl = cfg.authConvexSiteUrl ?? DEFAULT_CONVEX_SITE_URL;
     }
 
-    // Default: enabled only in dev mode
+    // Default: enabled. Pre-0.8.8 the SDK only enabled shake in dev
+    // builds (`__DEV__`), but apps that bundle the SDK explicitly *want*
+    // shake to work in TestFlight / Play Store builds — that's the
+    // primary use case (a tester finds a bug in a release build and
+    // shakes to report it). Dev builds get shake too. Apps that want
+    // to disable shake pass `enabled: false` (or
+    // `disableShakeGesture: true` for finer-grained control).
     if (cfg.enabled !== undefined) {
       enabled = cfg.enabled;
     } else {
-      enabled = typeof __DEV__ !== 'undefined' ? __DEV__ : false;
+      enabled = !cfg.disableShakeGesture;
     }
 
     // Hydrate cached auth token + preferred device from AsyncStorage so the
@@ -193,7 +316,7 @@ export class YaverFeedback {
       shakeDetector.stop();
       shakeDetector = null;
     }
-    if (enabled && config.trigger === 'shake') {
+    if (enabled && config.trigger === 'shake' && !config.disableShakeGesture) {
       shakeDetector = new ShakeDetector();
       shakeDetector.start(() => {
         YaverFeedback.notifyShake();
@@ -253,18 +376,39 @@ export class YaverFeedback {
           });
         }
       });
-      // NOTE: BlackBox.start() is intentionally NOT auto-called here.
-      // An earlier version (0.7.6) did auto-start it, and when the
-      // agent was in bootstrap / needs-auth mode — which can happen
-      // any time after `yaver serve` restarts before the user pairs —
-      // the SSE channel retried with exponential backoff on 401s,
-      // producing a tight loop of string concatenation + JSON parse
-      // that tripped a Hermes rope-string SIGSEGV on iOS 18.3.1
-      // during any other JS-thread regex work (e.g. react-native-
-      // view-shot's internal string handling during Screenshot &
-      // Fix). Host apps call BlackBox.start() explicitly once they
-      // know the agent URL + token are valid (SFMG does this inside
-      // its YaverFeedbackWidget after auth).
+      // BlackBox auto-start (0.8.8+).
+      //
+      // 0.7.6 auto-started BlackBox immediately, which produced a
+      // Hermes rope-string SIGSEGV on iOS 18.3.1 when the agent was in
+      // bootstrap / needs-auth mode: the SSE channel retried with
+      // exponential backoff on 401s, generating a tight string-concat
+      // + JSON-parse loop that collided with react-native-view-shot's
+      // internal string handling during Screenshot & Fix. We rolled it
+      // back to manual-start (host calls BlackBox.start() after auth).
+      //
+      // The fix that lets us auto-start safely now:
+      //   1. Defer the start by 500ms so init() returns, the JS bridge
+      //      settles, and any first-launch auth-token round trip on
+      //      another thread completes before SSE opens.
+      //   2. Only start when we have BOTH an agentUrl AND an authToken
+      //      — without the token, the connect() call would 401 and we'd
+      //      reproduce the original loop.
+      //   3. Caller can opt out with cfg.autoStartBlackBox = false.
+      //
+      // SFMG used to call BlackBox.start() inside YaverFeedbackWidget
+      // after auth — that path still works (start() is idempotent), so
+      // upgrading SDK without removing the manual call is safe.
+      if (cfg.autoStartBlackBox !== false) {
+        setTimeout(() => {
+          if (config?.agentUrl && (config?.authToken || p2pAuthToken)) {
+            try {
+              BlackBox.start();
+            } catch (err) {
+              console.warn('[YaverFeedback] BlackBox auto-start failed:', err);
+            }
+          }
+        }, 500);
+      }
     }
 
     // NOTE: We intentionally do NOT hook ErrorUtils.setGlobalHandler().
@@ -583,7 +727,7 @@ export class YaverFeedback {
         BlackBox.start(); // restart with previous config
       }
       // Restart shake detector if trigger is 'shake'
-      if (config?.trigger === 'shake' && !shakeDetector) {
+      if (config?.trigger === 'shake' && !config?.disableShakeGesture && !shakeDetector) {
         shakeDetector = new ShakeDetector();
         shakeDetector.start(() => {
           YaverFeedback.notifyShake();

package/src/__tests__/AuthDevices.test.ts

@@ -31,10 +31,10 @@ describe('auth device listing', () => {
               platform: 'linux',
               isOnline: true,
               isGuest: true,
-              hostName: 'Kivanc Cakmak',
-              hostEmail: 'kivanc.cakmak@icloud.com',
+              hostName: 'Host User',
+              hostEmail: 'host@example.com',
               accessScope: 'shared-scoped',
-              quicHost: '157.180.114.179',
+              quicHost: '198.51.100.20',
               quicPort: 18080,
               lastHeartbeat: 456,
             },
@@ -56,7 +56,7 @@ describe('auth device listing', () => {
     expect(result.shared[0]).toMatchObject({
       deviceId: 'guest-1',
       isGuest: true,
-      hostEmail: 'kivanc.cakmak@icloud.com',
+      hostEmail: 'host@example.com',
       accessScope: 'shared-scoped',
     });
   });
@@ -73,10 +73,10 @@ describe('auth device listing', () => {
               platform: 'linux',
               isOnline: true,
               isGuest: true,
-              hostName: 'Kivanc Cakmak',
-              hostEmail: 'kivanc.cakmak@icloud.com',
+              hostName: 'Host User',
+              hostEmail: 'host@example.com',
               accessScope: 'shared-scoped',
-              quicHost: '157.180.114.179',
+              quicHost: '198.51.100.20',
               quicPort: 18080,
               lastHeartbeat: 789,
             },

package/src/__tests__/BlackBox.hotReload.test.ts

@@ -0,0 +1,226 @@
+// Hot-reload command-channel coverage for BlackBox.
+//
+// The agent uses BlackBox's SSE channel as a back-channel to push
+// "reload" / "reload_bundle" commands into a running guest app
+// (see desktop/agent/blackbox.go::BroadcastCommand). This test
+// pins the SDK's contract:
+//
+//   1. onCommand(handler) registers a handler and returns an
+//      unsubscribe function that actually unsubscribes.
+//   2. start() opens the SSE command-stream against the agent
+//      with the proper URL + headers.
+//   3. When the SSE stream delivers a JSON message of the form
+//      {type:"command", command:{command:"reload", data:...}},
+//      the registered handler fires with the inner command.
+//   4. start() also schedules the periodic flush — proving start
+//      is idempotent over multiple calls.
+
+import { BlackBox } from '../BlackBox';
+import { YaverFeedback } from '../YaverFeedback';
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+}));
+
+// Drive Date.now / setTimeout deterministically.
+jest.useFakeTimers();
+
+const mockFetch = jest.fn();
+global.fetch = mockFetch as any;
+
+class MockAbortController {
+  signal = { aborted: false };
+  abort = jest.fn(() => {
+    this.signal.aborted = true;
+  });
+}
+global.AbortController = MockAbortController as any;
+
+// Helper to build an SSE streaming body.
+function sseBody(messages: Array<unknown>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  const chunks = messages.map((m) => `data: ${JSON.stringify(m)}\n\n`);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const c of chunks) controller.enqueue(enc.encode(c));
+      controller.close();
+    },
+  });
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  // Default: every POST (events) and the SSE GET both succeed.
+  mockFetch.mockImplementation((url: string) => {
+    if (url.includes('/blackbox/command-stream')) {
+      return Promise.resolve({
+        ok: true,
+        body: sseBody([]),
+      });
+    }
+    return Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve({}),
+    });
+  });
+  YaverFeedback.init({
+    agentUrl: 'http://localhost:18080',
+    authToken: 'tok',
+  });
+});
+
+afterEach(() => {
+  BlackBox.stop();
+});
+
+describe('BlackBox hot-reload command channel', () => {
+  it('onCommand returns an unsubscribe that removes the handler', () => {
+    const a = jest.fn();
+    const b = jest.fn();
+    const offA = BlackBox.onCommand(a);
+    const offB = BlackBox.onCommand(b);
+
+    // Both subscribed — calling internal dispatch directly via the
+    // public surface isn't easy without SSE mockery, but
+    // deregistering should still leave only `b` registered after
+    // offA(), then no handlers after offB().
+    offA();
+    offB();
+    // Re-subscribe and confirm subscription returns a fresh unsub.
+    const offC = BlackBox.onCommand(jest.fn());
+    expect(typeof offC).toBe('function');
+    offC();
+  });
+
+  it('start() opens SSE against /blackbox/command-stream with bearer + device headers', async () => {
+    BlackBox.start({ deviceId: 'dev-abc', appName: 'sfmg' });
+    // Allow the async fetch in connectSSE to fire.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const sseCall = mockFetch.mock.calls.find(([url]) =>
+      String(url).includes('/blackbox/command-stream'),
+    );
+    expect(sseCall).toBeDefined();
+    const [url, init] = sseCall!;
+    expect(String(url)).toContain('http://localhost:18080/blackbox/command-stream');
+    expect(String(url)).toContain('device=dev-abc');
+    expect(init.headers).toEqual(
+      expect.objectContaining({
+        Authorization: 'Bearer tok',
+        Accept: 'text/event-stream',
+        'X-Device-ID': 'dev-abc',
+        'X-App-Name': 'sfmg',
+      }),
+    );
+  });
+
+  it('dispatches a {type:"command", command:{command:"reload"}} SSE frame to handlers', async () => {
+    // SSE body delivers one reload command, then closes.
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'command', command: { command: 'reload', data: {} } },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const seen: any[] = [];
+    BlackBox.onCommand((cmd) => seen.push(cmd));
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+
+    // Drain the microtask + reader queue. The reader is async but
+    // the body is fully buffered + the stream closes immediately,
+    // so a few microtask flushes are enough.
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(seen).toEqual([
+      expect.objectContaining({ command: 'reload', data: {} }),
+    ]);
+  });
+
+  it('dispatches a reload_bundle command (carries bundleUrl payload)', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            {
+              type: 'command',
+              command: {
+                command: 'reload_bundle',
+                data: { bundleUrl: '/dev/native-bundle' },
+              },
+            },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const seen: any[] = [];
+    BlackBox.onCommand((cmd) => seen.push(cmd));
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(seen).toEqual([
+      expect.objectContaining({
+        command: 'reload_bundle',
+        data: expect.objectContaining({ bundleUrl: '/dev/native-bundle' }),
+      }),
+    ]);
+  });
+
+  it('handler exception does not break sibling handlers', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'command', command: { command: 'reload' } },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const sibling = jest.fn();
+    BlackBox.onCommand(() => {
+      throw new Error('caller bug — should not break the dispatch loop');
+    });
+    BlackBox.onCommand(sibling);
+
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(sibling).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'reload' }),
+    );
+  });
+
+  it('ignores non-command SSE frames (events/log/whatever)', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'log', logLine: 'hi' },
+            { type: 'lifecycle', message: 'started' },
+            { ping: 1 },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const handler = jest.fn();
+    BlackBox.onCommand(handler);
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+    expect(handler).not.toHaveBeenCalled();
+  });
+});