@torrent-tv/proxy 2.55.8 → 2.55.10

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.55.10
+
+- **Change**: Add `--sctp-debug` (off by default). When enabled, the proxy calls `node-datachannel.initLogger('Verbose')` early so SCTP-level lines (`usrsctp: …`) become visible. Useful only with an image rebuilt with `SCTP_DEBUG=ON` (addon 0.48.0) — there they carry the SACK `a_rwnd` and gap information that separates the two remaining hypotheses for the delivery-side freeze of 2026-08-24/25.
+
+## 2.55.9
+
+- **New**: A send queue that stays wedged for over 30 s now records the wire itself. Field session 2026-08-24 (`research/dead-channel-2026-08-24.md`): the proxy counted bytes as sent that never reached the viewer's SCTP stack, and every counter above the wire reported success for 88 minutes — the two candidate causes inside SCTP separate by one look at the packets (duplicate SACKs naming a missing TSN with no retransmission vs SACKs advertising `a_rwnd=0`), but occurrences are rare, so waiting to be asked meant waiting forever. When the stuck warning crosses 30 s, the proxy spawns a bounded tcpdump on the WebRTC UDP port filtered to that session's remote address: snaplen 128 B, ring of 4 × 30 s files beside the core dumps (`--state-dir`), killed after 120 s + grace, one capture at a time with a 10-minute cooldown, old captures pruned at startup the way core dumps are. Where no tcpdump exists it degrades to a single log line; the address travels into the filter only as a validated IPv4/IPv6 literal (zone suffixes stripped), spawned as an argv array without a shell.
+
 ## 2.55.8
 
 - **Fix**: The proxy died twice in one evening (2026-08-22, 15:50:12 and 16:12:21 UTC) with no stop order given, and both deaths are the same fault. The torrent worker thread ends itself when its event loop drains — every recurring interval there is unref'd, upload is disabled by default, and idle peer connections close about half a minute after the traffic stops — so when a viewer paused or left, the thread finished ~35 s later on its own and Node began tearing it down. That teardown touched memory already freed or overwritten (SIGSEGV inside `uv_timer_stop`, reached through `PerIsolatePlatformData::Shutdown`; two core dumps captured identical stacks), and a fault in any thread kills the whole process instantly — HTTP server, tunnel and data channels together, with no log line and no way to restart anything from inside. The HA supervisor restarted the container each time (~15 s), but the browser's reconnect ladder had already given up by then. The worker now keeps ONE interval accounted for (no `.unref()`): an empty tick every 5 s costs nothing, the event loop can never drain while the process lives, and the teardown path — with whatever structure is corrupted inside it — stays unreachable, regardless of which native module is guilty; the three earlier crashes of this family (2026-08-18..21) stay documented under roadmap item 1.

package/bin/cli.js

@@ -24,6 +24,7 @@ import { createTunnelClient } from "../services/tunnel-client.js";
 import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
 import { pruneCoreDumps } from "../services/core-dumps.js";
+import { createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
 import { classifyNat } from "../services/nat-classifier.js";
@@ -96,6 +97,7 @@ program
     DEFAULT_SEGMENT_FORMAT_ID
   )
   .option("--token <token>", "Registration token", "")
+  .option("--sctp-debug", "Enable verbose SCTP debug logging (SCTP_DEBUG build only)")
   .addHelpText("after", HELP_EXAMPLES);
 
 program.parse(process.argv);
@@ -281,6 +283,23 @@ async function shutdown(signal) {
 
 try {
   logToFile(options.logFile);
+  // Diagnostic: verbose SCTP logging. The binary must have been built with
+  // SCTP_DEBUG=ON (addon 0.48.0); this flag merely sets the log level.
+  if (options.sctpDebug) {
+    try {
+      const dc = await import("node-datachannel");
+      const initLogger =
+        // node-datachannel exports initLogger at the top level; be defensive
+        // about CJS-default interop.
+        dc.initLogger ?? dc.default?.initLogger ?? null;
+      if (typeof initLogger === "function") {
+        initLogger("Verbose");
+        logger.info("SCTP debug verbose logging enabled");
+      }
+    } catch (error) {
+      logger.warn(`Failed to enable SCTP debug: ${error?.message ?? error}`);
+    }
+  }
   if (transcodeAudio) {
     assertFfmpegAvailability();
   }
@@ -307,6 +326,13 @@ try {
   // field host, and four of them nearly filled a 235 GB disk. Keep the newest
   // two, which are the evidence for the fault still open, and drop the rest.
   void pruneCoreDumps(options.stateDir);
+  // Same policy for the packet captures the send-queue witness writes.
+  const packetWitness = createPacketWitness({
+    log: (message) => logger.info(message),
+    dir: options.stateDir || "",
+    port: actualPort
+  });
+  void pruneWitnessCaptures(packetWitness.dir);
 
   logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
   logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
@@ -428,7 +454,10 @@ try {
     sourceRegistry,
     // Lets a stuck send queue ask the transport what it is doing. Late-bound:
     // the manager is created below, with this handler already in hand.
-    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null
+    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
+    // Records the wire when a queue stays wedged — how the rare one-way
+    // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
+    witness: packetWitness
   });
 
   webRtcManager = createWebRtcManager({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.55.8",
+  "version": "2.55.10",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/data-channel-handler.js

@@ -54,6 +54,15 @@ import { deriveSourceKey } from "./torrent-source-key.js";
  *   Incoming requests are forwarded to `http://127.0.0.1:{proxyPort}`.
  * @property {(message: string) => void} [onLog]
  *   Optional log sink.
+ * @property {{ maybeCapture: (trigger: {
+ *   sessionId: string, tag: string, label: string,
+ *   remote: { address: string, port: number } | null,
+ *   queuedBytes: number, stuckForMs: number
+ * }) => boolean }} [witness]
+ *   The packet witness (services/packet-witness.js). When a wedged queue
+ *   crosses {@linkcode SEND_QUEUE_CAPTURE_AFTER_MS} the watcher hands it the
+ *   transport snapshot's remote endpoint so a bounded tcpdump can record what
+ *   the wire actually did. Optional; absent means no captures are taken.
  */
 
 /**
@@ -108,7 +117,7 @@ import { deriveSourceKey } from "./torrent-source-key.js";
  * @param {DataChannel} channel
  * @returns {() => void} Stops the watch.
  */
-function makeSendQueueWatcher({ log, getTransportSnapshot }) {
+function makeSendQueueWatcher({ log, getTransportSnapshot, witness }) {
   // Every channel of one connection reads the SAME transport counters — the
   // snapshot describes the peer connection, not the channel — so the heartbeat
   // belongs to the connection and is printed once for it. Printed per channel
@@ -123,8 +132,10 @@ function makeSendQueueWatcher({ log, getTransportSnapshot }) {
   // a label is whatever the peer chose and two channels can carry the same one
   // (or none, where `getLabel` is missing and both fall back to "?"), and a
   // Map keyed on that would let one channel evict the other and then, on
-  // closing, delete the survivor's entry.
-  /** @type {Map<string, { channels: Map<DataChannel, string>, at: number, previous: object | null, unknown: number }>} */
+  // closing, delete the survivor's entry. `captureStarted` rides on the same
+  // record: both channels of one wedged connection must ask the witness once,
+  // not once per channel.
+  /** @type {Map<string, { channels: Map<DataChannel, string>, at: number, previous: object | null, unknown: number, captureStarted: boolean }>} */
   const connections = new Map();
 
   /**
@@ -153,7 +164,7 @@ function makeSendQueueWatcher({ log, getTransportSnapshot }) {
     let previous = null;
     let connection = connections.get(sessionId);
     if (!connection) {
-      connection = { channels: new Map(), at: 0, previous: null, unknown: 0 };
+      connection = { channels: new Map(), at: 0, previous: null, unknown: 0, captureStarted: false };
       connections.set(sessionId, connection);
     }
     connection.channels.set(channel, label);
@@ -256,6 +267,31 @@ function makeSendQueueWatcher({ log, getTransportSnapshot }) {
         `received=${snapshot.bytesReceived}${recvDelta === null ? "" : ` (+${recvDelta})`} ` +
         `rtt=${snapshot.rtt}ms pc=${snapshot.state} ice=${snapshot.iceState} pair=${snapshot.pair}`
       );
+      // Roadmap item 10, occurrence 2026-08-24: a wedge this old is the moment
+      // the packet-level truth has to be caught, because no counter above the
+      // wire can name the cause. One attempt per connection — the witness
+      // applies its own single-flight and cooldown rules after that.
+      if (
+        witness &&
+        !connection.captureStarted &&
+        now - stuckSince >= SEND_QUEUE_CAPTURE_AFTER_MS
+      ) {
+        connection.captureStarted = true;
+        const started = witness.maybeCapture({
+          sessionId,
+          tag,
+          label,
+          remote: snapshot.remote ?? null,
+          queuedBytes: queued,
+          stuckForMs: now - stuckSince
+        });
+        if (!started) {
+          // Refused for now (no remote endpoint yet, capture already running
+          // elsewhere, cooldown): let the next tick try again rather than
+          // spending the one attempt per wedge on a refusal.
+          connection.captureStarted = false;
+        }
+      }
     }, SEND_QUEUE_SAMPLE_MS);
 
     if (typeof timer.unref === "function") {
@@ -301,7 +337,7 @@ export function encodeFrame(idBytes, bytes, done) {
   return frame;
 }
 
-export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapshot, sourceRegistry }) {
+export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapshot, sourceRegistry, witness }) {
   /**
    * Channels currently interested in one file's subtitle cues, keyed by
    * `sourceKey:fileIndex`. Populated the moment a browser asks for an
@@ -380,7 +416,7 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
   /** Request id → its ASCII bytes; see {@link requestIdBytes}. */
   const requestIdCache = new Map();
 
-  const watchSendQueue = makeSendQueueWatcher({ log: (message) => log(message), getTransportSnapshot });
+  const watchSendQueue = makeSendQueueWatcher({ log: (message) => log(message), getTransportSnapshot, witness });
 
   /**
    * @param {string} message
@@ -867,6 +903,12 @@ const TRANSPORT_HEARTBEAT_MS = 5_000;
 // registry does not end a healthy watch.
 const TRANSPORT_UNKNOWN_HEARTBEATS = 3;
 const SEND_QUEUE_STUCK_MS = 5_000;
+// How long a wedged queue waits before the packet witness starts recording the
+// wire. Long enough to be certain this is not a slow drain (a 6-11 MB segment
+// leaves in well under a second, measured), short enough that the capture is
+// still running while whatever broke is breaking — the 2026-08-24 episode
+// began minutes before anyone could have asked for a capture by hand.
+const SEND_QUEUE_CAPTURE_AFTER_MS = 30_000;
 const DC_BUFFER_HIGH_WATER = 8 * 1024 * 1024;
 /** Resume sending once the channel buffer drains to this many bytes. */
 const DC_BUFFER_LOW_WATER = 1 * 1024 * 1024;

package/services/packet-witness.js

@@ -0,0 +1,406 @@
+/**
+ * @file Automatic packet witness for a send queue that stops draining.
+ *
+ * Roadmap item 10, occurrence 2026-08-24 (`research/dead-channel-2026-08-24.md`):
+ * the proxy counted bytes as sent that never reached the viewer's SCTP stack,
+ * and every counter above the wire reported success for 88 minutes. The two
+ * candidate causes separate by ONE look at the packets — repeated duplicate
+ * SACKs naming a missing TSN with no retransmission (usrsctp retransmit
+ * defect) versus SACKs advertising `a_rwnd=0` with no gaps (receiver stopped
+ * reading). Occurrences are rare and unpredictable, so the witness fires by
+ * itself: a send queue wedged longer than ~30 s starts a bounded tcpdump on
+ * the WebRTC UDP port filtered to that session's remote address, writes a few
+ * small rotating files, and stops. Where no tcpdump exists the whole thing
+ * degrades to a single log line.
+ *
+ * Bounded three ways so it can never cost more than an episode is worth: the
+ * process is killed after {@linkcode WITNESS_CAPTURE_SECONDS} plus grace; the
+ * ring keeps at most {@linkcode WITNESS_RING_FILES} files of
+ * {@linkcode WITNESS_ROTATE_SECONDS} each; and one capture runs at a time,
+ * with a cooldown before the next. Captures land beside the core dumps
+ * (`--state-dir`) and are pruned at startup the same way.
+ */
+
+import { spawn } from "node:child_process";
+import { readdir, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { dumpsToRemove } from "./core-dumps.js";
+
+/** Per-packet capture length. Small: headers are what the signatures need. */
+export const WITNESS_SNAPLEN_BYTES = 128;
+
+/** One rotation step of the ring, in seconds. */
+export const WITNESS_ROTATE_SECONDS = 30;
+
+/** How many rotation steps stay on disk (30 s × 4 = 120 s of evidence). */
+export const WITNESS_RING_FILES = 4;
+
+/** Total wall-clock bound on one capture, seconds. */
+export const WITNESS_CAPTURE_SECONDS = WITNESS_ROTATE_SECONDS * WITNESS_RING_FILES;
+
+/** Extra time before the SIGKILL fallback lands on a hanging tcpdump. */
+export const WITNESS_KILL_GRACE_MS = 5_000;
+
+/** Minimum spacing between captures, whatever the reason for them. */
+export const WITNESS_COOLDOWN_MS = 10 * 60_000;
+
+/** How many old captures survive at startup, newest first. */
+export const WITNESS_CAPTURES_KEPT = 4;
+
+/**
+ * The remote endpoint of a transport snapshot, already structured.
+ *
+ * @typedef {Object} WitnessRemoteEndpoint
+ * @property {string} address - IP literal (may carry a `%zone` suffix).
+ * @property {number} port
+ */
+
+/**
+ * What the watcher hands over when a wedge crosses the capture threshold.
+ *
+ * @typedef {Object} WitnessTrigger
+ * @property {string} sessionId
+ * @property {string} tag       - Session id, first 8 characters.
+ * @property {string} label     - Data channel label ("proxy", "proxy-control").
+ * @property {WitnessRemoteEndpoint | null} remote
+ * @property {number} queuedBytes
+ * @property {number} stuckForMs
+ */
+
+/**
+ * Strip a zone suffix and keep only IPv4/IPv6 literals.
+ *
+ * The address travels into a tcpdump BPF filter argument. The child is spawned
+ * as an argv array (no shell), so injection is not reachable, but a garbage or
+ * hostname value would produce a capture of nothing — rejected instead, so the
+ * log can say why nothing was written.
+ *
+ * @param {unknown} raw - Address as libdatachannel reports it.
+ * @returns {string | null} A clean literal, or null when not usable.
+ */
+export function normalizeRemoteAddress(raw) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const zoneFree = raw.replace(/%.*$/, "");
+  if (zoneFree.length === 0 || zoneFree.length > 45) {
+    return null;
+  }
+  const ipv4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+  // Hex groups and at most one "::" compression — enough to keep hostnames,
+  // decimal-octet junk and shell metacharacters out of the filter.
+  const ipv6 = /^(?:[0-9A-Fa-f]{0,4}:){2,7}[0-9A-Fa-f]{0,4}$/;
+  if (ipv4.test(zoneFree) || (zoneFree.includes(":") && ipv6.test(zoneFree))) {
+    return zoneFree;
+  }
+  return null;
+}
+
+/**
+ * The tcpdump command line for one bounded capture.
+ *
+ * `-i any` covers hosts where the UDP mux socket is not on a named interface;
+ * `-n` keeps DNS out of the hot path; `-S` prints absolute sequence numbers so
+ * duplicate SACKs across file rotations compare equal by eye.
+ *
+ * @param {Object} parts
+ * @param {string} parts.host          - Validated IP literal.
+ * @param {number} parts.port          - The WebRTC UDP port.
+ * @param {string} parts.filePrefix    - Path prefix; tcpdump appends timestamps.
+ * @param {number} [parts.snaplen]     - Bytes per packet to store.
+ * @param {number} [parts.rotateSeconds]
+ * @param {number} [parts.ringFiles]
+ * @returns {string[]}
+ */
+export function buildTcpdumpArgs({
+  host,
+  port,
+  filePrefix,
+  snaplen = WITNESS_SNAPLEN_BYTES,
+  rotateSeconds = WITNESS_ROTATE_SECONDS,
+  ringFiles = WITNESS_RING_FILES
+}) {
+  return [
+    "-n",
+    "-S",
+    "-s",
+    String(snaplen),
+    "-i",
+    "any",
+    "-w",
+    filePrefix,
+    "-G",
+    String(rotateSeconds),
+    "-W",
+    String(ringFiles),
+    "udp",
+    "and",
+    "host",
+    host,
+    "and",
+    "port",
+    String(port)
+  ];
+}
+
+/**
+ * Whether a new capture may start right now.
+ *
+ * Pure, so the gating rule is testable without clocks or processes: never two
+ * at once, and none within the cooldown of the previous one. `lastStartedAt`
+ * of 0 means this process has not captured yet.
+ *
+ * @param {{ running: boolean, lastStartedAt: number, now?: number, cooldownMs?: number }} state
+ * @returns {boolean}
+ */
+export function shouldStartCapture({ running, lastStartedAt, now = Date.now(), cooldownMs = WITNESS_COOLDOWN_MS }) {
+  if (running) {
+    return false;
+  }
+  return lastStartedAt <= 0 || now - lastStartedAt >= cooldownMs;
+}
+
+/**
+ * Whether a file name is a capture this module wrote (including the
+ * timestamp-suffixed rotations tcpdump appends under `-G`).
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isWitnessCapture(name) {
+  return typeof name === "string" && /^packet-witness\.[^/\\]+\.pcap/.test(name);
+}
+
+/**
+ * Delete all but the newest few captures in `dir`.
+ *
+ * Mirrors `pruneCoreDumps`: best-effort, never fatal, one summary line.
+ *
+ * @param {string} dir
+ * @param {number} [keep]
+ * @returns {Promise<void>}
+ */
+export async function pruneWitnessCaptures(dir, keep = WITNESS_CAPTURES_KEPT) {
+  if (typeof dir !== "string" || dir.length === 0) {
+    return;
+  }
+  /** @type {Array<{ name: string, writtenAt: number, bytes: number }>} */
+  const captures = [];
+  try {
+    for (const name of await readdir(dir)) {
+      if (!isWitnessCapture(name)) {
+        continue;
+      }
+      try {
+        const info = await stat(path.join(dir, name));
+        if (info.isFile()) {
+          captures.push({ name, writtenAt: info.mtimeMs, bytes: info.size });
+        }
+      } catch {
+        // silent-ok: vanished between listing and reading.
+      }
+    }
+  } catch {
+    return; // No such directory, or unreadable. Nothing to tidy.
+  }
+  if (captures.length === 0) {
+    return;
+  }
+  const doomed = dumpsToRemove(captures, keep);
+  const freed = captures
+    .filter((capture) => doomed.includes(capture.name))
+    .reduce((total, capture) => total + capture.bytes, 0);
+  for (const name of doomed) {
+    try {
+      await rm(path.join(dir, name), { force: true });
+    } catch {
+      // silent-ok: best effort, retried at the next start.
+    }
+  }
+  const keptBytes = captures
+    .filter((capture) => !doomed.includes(capture.name))
+    .reduce((total, capture) => total + capture.bytes, 0);
+  if (freed > 0 || captures.length > keep) {
+    logLine(
+      `packet witness: ${captures.length} capture(s) present, keeping the newest ${Math.min(keep, captures.length)}, ` +
+      `removed ${doomed.length} (${(freed / 1024).toFixed(1)} KB), keeping ${(keptBytes / 1024).toFixed(1)} KB`
+    );
+  }
+}
+
+/**
+ * The logger handed to {@linkcode createPacketWitness}; module-level so the
+ * pruner can speak without an options bag threaded everywhere.
+ *
+ * @type {(message: string) => void}
+ */
+let logLine = () => {};
+
+/**
+ * Create the witness.
+ *
+ * @param {Object} options
+ * @param {(message: string) => void} options.log - Log sink (the shared logger).
+ * @param {string} [options.dir]   - Where captures go; empty means os.tmpdir().
+ * @param {number} options.port    - The WebRTC UDP port to filter on.
+ * @returns {{ dir: string, maybeCapture: (trigger: WitnessTrigger) => boolean }}
+ */
+export function createPacketWitness({ log, dir = "", port }) {
+  logLine = typeof log === "function" ? log : logLine;
+  const resolvedDir = typeof dir === "string" && dir.length > 0 ? dir : os.tmpdir();
+
+  /** @type {{ running: boolean, lastStartedAt: number, availability: "unknown" | "yes" | "no" }} */
+  const state = { running: false, lastStartedAt: 0, availability: "unknown" };
+
+  /**
+   * Ask whether tcpdump exists at all — once per process, whichever way it
+   * answers. A host without it gets exactly one log line, ever.
+   *
+   * @returns {Promise<boolean>}
+   */
+  const probeAvailability = () =>
+    new Promise((resolve) => {
+      let settled = false;
+      const done = (value) => {
+        if (!settled) {
+          settled = true;
+          resolve(value);
+        }
+      };
+      try {
+        const probe = spawn("tcpdump", ["--version"], { stdio: "ignore" });
+        probe.on("error", () => done(false));
+        probe.on("spawn", () => done(true));
+        probe.on("close", () => done(true));
+      } catch {
+        done(false);
+      }
+    });
+
+  /**
+   * Run one bounded capture and report what it wrote.
+   *
+   * @param {WitnessTrigger} trigger
+   * @param {string} address - Validated remote IP literal.
+   * @returns {Promise<void>}
+   */
+  const runCapture = async (trigger, address) => {
+    const prefix = path.join(
+      resolvedDir,
+      `packet-witness.${trigger.tag}.${Math.floor(Date.now() / 1000)}.pcap`
+    );
+    const args = buildTcpdumpArgs({ host: address, port, filePrefix: prefix });
+    logLine(
+      `packet witness: capturing ${WITNESS_CAPTURE_SECONDS}s of udp port ${port} ↔ ${address} ` +
+      `(session ${trigger.tag}, "${trigger.label}" queue ${trigger.queuedBytes}B wedged ` +
+      `${Math.round(trigger.stuckForMs / 1000)}s) → ${prefix}`
+    );
+    await new Promise((resolve) => {
+      /** @type {ReturnType<typeof setTimeout> | null} */
+      let killer = null;
+      /** @type {NodeJS.Timeout | null} */
+      let hardKill = null;
+      let child;
+      try {
+        child = spawn("tcpdump", args, { stdio: "ignore" });
+      } catch (error) {
+        logLine(`packet witness: could not start tcpdump: ${error?.message ?? error}`);
+        resolve();
+        return;
+      }
+      const finish = () => {
+        if (killer) {
+          clearTimeout(killer);
+          killer = null;
+        }
+        if (hardKill) {
+          clearTimeout(hardKill);
+          hardKill = null;
+        }
+        resolve();
+      };
+      child.on("error", (error) => {
+        state.availability = "no";
+        logLine(`packet witness: tcpdump failed to run: ${error?.message ?? error}`);
+        finish();
+      });
+      child.on("close", (code, signal) => {
+        logLine(
+          `packet witness: capture ended${signal ? ` (${signal})` : ` (exit ${code ?? "?"})`}`
+        );
+        finish();
+      });
+      killer = setTimeout(() => {
+        try { child.kill("SIGTERM"); } catch { /* already gone */ }
+        hardKill = setTimeout(() => {
+          try { child.kill("SIGKILL"); } catch { /* already gone */ }
+        }, WITNESS_KILL_GRACE_MS);
+      }, WITNESS_CAPTURE_SECONDS * 1000);
+    });
+    // Say what landed on disk, so whoever reads the log later knows whether
+    // the evidence exists without listing the directory themselves.
+    try {
+      const names = (await readdir(resolvedDir)).filter((name) => isWitnessCapture(name));
+      const mine = [];
+      for (const name of names) {
+        if (!name.startsWith(path.basename(prefix))) {
+          continue;
+        }
+        try {
+          const info = await stat(path.join(resolvedDir, name));
+          mine.push(`${name} ${(info.size / 1024).toFixed(1)} KB`);
+        } catch { /* gone between listing and reading */ }
+      }
+      logLine(`packet witness: wrote ${mine.length} file(s): ${mine.join(", ") || "none"}`);
+    } catch {
+      logLine("packet witness: could not list the capture directory");
+    }
+  };
+
+  /**
+   * Start a capture for this trigger, if the rules allow one.
+   *
+   * @param {WitnessTrigger} trigger
+   * @returns {boolean} True when a capture actually started.
+   */
+  const maybeCapture = (trigger) => {
+    const address = normalizeRemoteAddress(trigger?.remote?.address);
+    const portNumber = trigger?.remote?.port;
+    if (!address || !Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+      return false;
+    }
+    if (!shouldStartCapture(state)) {
+      return false;
+    }
+    state.running = true;
+    state.lastStartedAt = Date.now();
+    const startedAt = state.lastStartedAt;
+    void (async () => {
+      try {
+        if (state.availability === "unknown") {
+          state.availability = (await probeAvailability()) ? "yes" : "no";
+        }
+        if (state.availability === "no") {
+          logLine(
+            "packet witness: unavailable — no tcpdump on this host; " +
+            "the stuck-queue log lines remain the only evidence here"
+          );
+          return;
+        }
+        await runCapture(trigger, address);
+      } finally {
+        state.running = false;
+        // Keep the requested spacing honest even when the capture ended early.
+        const earliestNext = startedAt + WITNESS_COOLDOWN_MS;
+        if (state.lastStartedAt < earliestNext) {
+          state.lastStartedAt = earliestNext;
+        }
+      }
+    })();
+    return true;
+  };
+
+  return { dir: resolvedDir, maybeCapture };
+}

package/services/webrtc-manager.js

@@ -443,11 +443,11 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort,
    *    collapsed. `bytesReceived` still climbing at the same time proves the
    *    peer is alive and its packets still reach us, i.e. the failure is
    *    one-directional.
-   *  - both flat → nothing crosses in either direction.
-   *
-   * @param {string} sessionId
-   * @returns {{ bytesSent: number, bytesReceived: number, rtt: number, pair: string, state: string, iceState: string } | null}
-   */
+    *  - both flat → nothing crosses in either direction.
+    *
+    * @param {string} sessionId
+    * @returns {{ bytesSent: number, bytesReceived: number, rtt: number, pair: string, remote: { address: string, port: number } | null, state: string, iceState: string } | null}
+    */
   function getTransportSnapshot(sessionId) {
     const pc = peers.get(sessionId);
     if (!pc) {
@@ -469,6 +469,12 @@ export function createWebRtcManager({ sendSignal, onDataChannel, onLog, udpPort,
         ? `${pair.local?.address}:${pair.local?.port}->${pair.remote?.address}:${pair.remote?.port}` +
           ` (${pair.local?.type}/${pair.remote?.type})`
         : "none",
+      // Structured, for consumers that need to act on the endpoint itself (the
+      // packet witness builds a tcpdump filter from it) rather than print it.
+      remote:
+        typeof pair?.remote?.address === "string" && Number.isFinite(pair?.remote?.port)
+          ? { address: pair.remote.address, port: pair.remote.port }
+          : null,
       state: read(() => pc.state(), "?"),
       iceState: read(() => pc.iceState(), "?")
     };

package/test/packet-witness.test.js

@@ -0,0 +1,120 @@
+/**
+ * @file The packet witness's gating rules and command construction.
+ *
+ * Roadmap item 10: a send queue wedged longer than ~30 s must start a bounded
+ * tcpdump on its own, because the 2026-08-24 episode proved no counter above
+ * the wire can name the cause. Everything here is the part that decides WHEN
+ * and WITH WHAT ARGUMENTS — the spawning itself is thin glue around these.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildTcpdumpArgs,
+  createPacketWitness,
+  isWitnessCapture,
+  normalizeRemoteAddress,
+  shouldStartCapture,
+  WITNESS_CAPTURE_SECONDS,
+  WITNESS_RING_FILES,
+  WITNESS_ROTATE_SECONDS
+} from "../services/packet-witness.js";
+
+test("an IPv4 literal survives unchanged", () => {
+  assert.equal(normalizeRemoteAddress("192.168.178.57"), "192.168.178.57");
+});
+
+test("an IPv6 literal survives unchanged", () => {
+  assert.equal(
+    normalizeRemoteAddress("2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"),
+    "2001:1c00:a603:2100:a129:a1a1:7f07:3f0b"
+  );
+});
+
+test("a zone suffix is stripped", () => {
+  assert.equal(normalizeRemoteAddress("fe80::2aca:8001:3ba6:f16f%18"), "fe80::2aca:8001:3ba6:f16f");
+});
+
+test("hostnames, garbage and shell text are rejected", () => {
+  assert.equal(normalizeRemoteAddress("homeassistant.local"), null);
+  assert.equal(normalizeRemoteAddress("8.8.8.8; rm -rf /"), null);
+  assert.equal(normalizeRemoteAddress("999.1.1.1"), null);
+  assert.equal(normalizeRemoteAddress(""), null);
+  assert.equal(normalizeRemoteAddress(undefined), null);
+  assert.equal(normalizeRemoteAddress(42), null);
+});
+
+test("the tcpdump command line is bounded and filtered to one peer", () => {
+  const args = buildTcpdumpArgs({
+    host: "2001:db8::1",
+    port: 9090,
+    filePrefix: "/data/packet-witness.e2b5ef39.1787600000.pcap"
+  });
+  assert.deepEqual(args, [
+    "-n",
+    "-S",
+    "-s",
+    "128",
+    "-i",
+    "any",
+    "-w",
+    "/data/packet-witness.e2b5ef39.1787600000.pcap",
+    "-G",
+    String(WITNESS_ROTATE_SECONDS),
+    "-W",
+    String(WITNESS_RING_FILES),
+    "udp",
+    "and",
+    "host",
+    "2001:db8::1",
+    "and",
+    "port",
+    "9090"
+  ]);
+});
+
+test("the capture window is what the rotation ring adds up to", () => {
+  assert.equal(WITNESS_ROTATE_SECONDS * WITNESS_RING_FILES, WITNESS_CAPTURE_SECONDS);
+});
+
+test("one capture runs at a time", () => {
+  assert.equal(shouldStartCapture({ running: true, lastStartedAt: Date.now() }), false);
+});
+
+test("the first capture of a process is always allowed", () => {
+  assert.equal(shouldStartCapture({ running: false, lastStartedAt: 0, now: 1000 }), true);
+});
+
+test("a capture within the cooldown is refused, one after it is allowed", () => {
+  const state = { running: false, lastStartedAt: 10_000 };
+  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 599_999 }), false);
+  assert.equal(shouldStartCapture({ ...state, now: 10_000 + 600_000 }), true);
+});
+
+test("capture files are recognised by name, rotations included", () => {
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap"), true);
+  assert.equal(isWitnessCapture("packet-witness.e2b5ef39.1787600000.pcap20260825T120000"), true);
+  assert.equal(isWitnessCapture("core.WorkerThread.81.1787600000"), false);
+  assert.equal(isWitnessCapture("proxy.log"), false);
+  assert.equal(isWitnessCapture("../packet-witness.x.pcap"), false);
+});
+
+test("a trigger without a usable remote endpoint is refused without touching anything", () => {
+  const lines = [];
+  const witness = createPacketWitness({
+    log: (message) => lines.push(message),
+    dir: "",
+    port: 9090
+  });
+  const started = witness.maybeCapture({
+    sessionId: "e2b5ef39-0000",
+    tag: "e2b5ef39",
+    label: "proxy",
+    remote: null,
+    queuedBytes: 160_000_000,
+    stuckForMs: 31_000
+  });
+  assert.equal(started, false);
+  assert.deepEqual(lines, []);
+});