(chore) add hard exit clarifications

Author: collapsinghierarchy

src/commands/recv.js

@@ -209,13 +209,29 @@ export async function run(outDir, opts, ctx = {}) {
       mode,
       appID,
     };
-    // --- Silent workaround: exit cleanly before wrtc finalizers run
-    // Close signaling so the relay doesn't hang on our socket, then bail.
   } catch (e) {
     const msg = e?.message || String(e);
     process.stderr.write(`\nError: ${msg}\n`);
     throw e;
   } finally {
+    // --- Workaround: exit before `wrtc` finalizers run
+    // Proactively close signaling so the relay doesn’t keep our socket open,
+    // then exit. This avoids a shutdown hang caused by known issues in the
+    // node-webrtc fork(s):
+    //   - https://github.com/WonderInventions/node-webrtc/issues/37
+    //   - https://github.com/WonderInventions/node-webrtc/issues/35
+    //
+    // Until these are resolved, we exit early to prevent JS/GC finalizers from
+    // tearing down RTCPeerConnection/libwebrtc threads in a way that can stall
+    // the event loop.
+    //
+    // Suggested shutdown order:
+    // 1) await signaling.close()          // stop outbound/inbound signaling
+    // 2) await peer?.close()              // close data channels/transceivers
+    // 3) process.exit(0)                  // ensure a clean, bounded exit
+    //
+    // TODO: remove once upstream fixes land.
+
     try {
       offSenderReady?.();
     } catch {}

src/commands/send.js

@@ -251,7 +251,24 @@ export async function run(paths, opts, ctx = {}) {
     process.stderr.write(summary + "\n");
     // --- Silent workaround on success
   } finally {
-    // Hard, handler-safe close sequence
+    // --- Workaround: exit before `wrtc` finalizers run
+    // Proactively close signaling so the relay doesn’t keep our socket open,
+    // then exit. This avoids a shutdown hang caused by known issues in the
+    // node-webrtc fork(s):
+    //   - https://github.com/WonderInventions/node-webrtc/issues/37
+    //   - https://github.com/WonderInventions/node-webrtc/issues/35
+    //
+    // Until these are resolved, we exit early to prevent JS/GC finalizers from
+    // tearing down RTCPeerConnection/libwebrtc threads in a way that can stall
+    // the event loop.
+    //
+    // Suggested shutdown order:
+    // 1) await signaling.close()          // stop outbound/inbound signaling
+    // 2) await peer?.close()              // close data channels/transceivers
+    // 3) process.exit(0)                  // ensure a clean, bounded exit
+    //
+    // TODO: remove once upstream fixes land.
+
     await closeTransport(rtc, {
       signal,
       waitForCloseMs: 0,