@torrent-tv/proxy 2.58.3 → 2.59.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.59.0
+
+- **New**: a wedge (roadmap item 11) is now declared, and evidence gathered for it automatically, even when the small-message shape means nothing ever queues. The only trigger that existed (`wedgeIsCertain`) requires a nonzero channel queue — confirmed 2026-08-28 by reading the code, not assuming it from the note: `bufferedAmount()` reads 0 the instant our bytes reach usrsctp, whatever usrsctp does with them next, so a wedge carrying only probes and control messages never set it and the last real episode's ring was never saved automatically. The delivery probe already computes a queue-independent verdict (`association-stopped`); it is now wired to the same evidence-gathering, gated on its OWN certainty rule rather than the raw verdict — a connection can sit behind by a bounded, non-growing amount for minutes (measured the same day, a backgrounded tab: gap held at 6-7 probes for 95+ seconds while `seen` kept climbing right along with `sent`) without anything being wrong. What a true wedge shows instead, checked against a session already known to be one: `seen` frozen at one value for over a minute while `sent` climbs unbounded. `probeWedgeIsCertain` asks whether the counter has stopped moving for longer than this connection's own history says a healthy gap ever takes — the same shape `wedgeIsCertain` already uses, applied to the probe's own counter.
+- **New**: `usrsctp`'s live association state (peer receive window, pending data, retransmission timeout, congestion window) can now be read on either wedge declaration, automatically — `node_datachannel.node` ships unstripped, so the read is a gdb attach against the running process, no rebuild. The walk and its healthy baseline are `research/session-2026-08-27-28-freeze-onset-and-sessions.md`, section 1; the script that performs it ships in the package (`assets/diagnostics/sctpstate.gdb`) instead of surviving only as long as someone remembers to copy it back onto a host after a container is recreated. Nine episodes of this item have lacked exactly this reading.
+
+## 2.59.1
+
+- **Fix**: the usrsctp state script no longer crashes when no association exists yet. Found while verifying 2.59.0 by hand against the live process with no viewer connected: `system_base_info`'s association hash table is a null pointer until usrsctp allocates its first association, and the walk dereferenced it unconditionally — `Cannot access memory at address 0x0` instead of the graceful "no association found" the script already prints for the equivalent case where the table exists but is empty. Guarded the walk behind `$hash != 0`.
+
 ## 2.58.3
 
 - **New**: the proxy says what it is holding, once a minute — resident memory, heap, external and array buffers, the torrent stores in BYTES, and what the machine has left. It was killed on 2026-08-28 by the kernel's own out-of-memory killer at 2.4 GB resident (`exit code 137`, no core dump, `Out of memory: Killed process ... anon-rss: 2422628kB`) and the log had never recorded a single figure about memory. There was one final reading, taken by the kernel, and no series leading to it.

package/assets/diagnostics/sctpstate.gdb

@@ -0,0 +1,31 @@
+set pagination off
+set confirm off
+set $base = (unsigned long) &system_base_info
+set $hash = *(unsigned long *)($base + 0)
+set $mask = *(unsigned long *)($base + 8)
+printf "asochash=%p mask=%lu\n", $hash, $mask
+set $i = 0
+set $stcb = 0
+if $hash != 0
+  while $i <= $mask && $stcb == 0
+    set $head = *(unsigned long *)($hash + $i * 8)
+    if $head != 0
+      set $stcb = $head
+      printf "bucket %lu -> stcb=%p\n", $i, $stcb
+    end
+    set $i = $i + 1
+  end
+end
+if $stcb == 0
+  printf "no association found (no viewer connected?)\n"
+else
+  set $sock = *(unsigned long *)($stcb + 0)
+  printf "socket=%p asoc=%p\n", $sock, $stcb + 88
+  set $buf = (unsigned long) malloc(512)
+  set $lenp = (unsigned long) malloc(8)
+  set *(int *)$lenp = 512
+  set $rc = (int) usrsctp_getsockopt($sock, 132, 256, $buf, $lenp)
+  printf "getsockopt rc=%d len=%d\n", $rc, *(int *)$lenp
+  printf "state=%d rwnd=%u unackdata=%u penddata=%u instrms=%u outstrms=%u fragpoint=%u\n", *(int *)($buf+4), *(unsigned int *)($buf+8), *(unsigned short *)($buf+12), *(unsigned short *)($buf+14), *(unsigned short *)($buf+16), *(unsigned short *)($buf+18), *(unsigned int *)($buf+20)
+  printf "primary: state=%d cwnd=%u srtt=%u rto=%u mtu=%u\n", *(int *)($buf+24+4+128), *(unsigned int *)($buf+24+4+128+4), *(unsigned int *)($buf+24+4+128+8), *(unsigned int *)($buf+24+4+128+12), *(unsigned int *)($buf+24+4+128+16)
+end

package/bin/cli.js

@@ -25,6 +25,7 @@ import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
 import { pruneCoreDumps } from "../services/core-dumps.js";
 import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
+import { createUsrsctpStateReader } from "../services/usrsctp-state.js";
 import { startMemoryReport } from "../services/memory-report.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
@@ -188,6 +189,9 @@ let webRtcManager = null;
  */
 let packetWitness = null;
 
+/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
+let usrsctpStateReader = null;
+
 /** @type {ReturnType<typeof createDataChannelHandler> | null} */
 let dataChannelHandler = null;
 
@@ -335,6 +339,12 @@ try {
   // the pruner recognises BEFORE anything starts a new ring over them.
   void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir));
 
+  // Reads usrsctp's own association state via gdb the moment a wedge is
+  // declared (roadmap item 11) — no source rebuild, the module ships
+  // unstripped. A host without gdb just never gets a reading, the same way a
+  // host without tcpdump never gets a packet capture.
+  usrsctpStateReader = createUsrsctpStateReader({ log: (message) => logger.info(message) });
+
   // What this process holds, once a minute. The kernel killed the proxy on
   // 2026-08-28 at 2.4 GB resident and the log had never said a word about
   // memory, so the growth that ended in that kill has no shape in any record we
@@ -464,7 +474,8 @@ try {
     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
+    witness: packetWitness,
+    usrsctpState: usrsctpStateReader
   });
 
   webRtcManager = createWebRtcManager({

package/package.json

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

package/services/data-channel-handler.js

@@ -159,7 +159,7 @@ export function wedgeIsCertain({ queuedBytes, bytesPerSecond, flatForMs, longest
  * @param {DataChannel} channel
  * @returns {() => void} Stops the watch.
  */
-function makeSendQueueWatcher({ log, getTransportSnapshot, witness }) {
+function makeSendQueueWatcher({ log, getTransportSnapshot, witness, usrsctpState }) {
   // 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
@@ -479,6 +479,14 @@ function makeSendQueueWatcher({ log, getTransportSnapshot, witness }) {
           connection.captureStarted = false;
         }
       }
+      if (usrsctpState && verdict.certain && peerStillSending) {
+        // Its own single-flight and cooldown, independent of the witness's —
+        // one gdb attach per wedge is enough, and a refusal here (already
+        // read, cooling down) costs nothing to retry on the next tick.
+        usrsctpState.maybeRead(
+          `send queue stuck ${queued}B, accepted-byte counter unmoved ${Math.round(flatForMs / 1000)}s`
+        );
+      }
     }, SEND_QUEUE_SAMPLE_MS);
 
     if (typeof timer.unref === "function") {
@@ -526,7 +534,18 @@ export function encodeFrame(idBytes, bytes, done) {
   return frame;
 }
 
-export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapshot, sourceRegistry, witness }) {
+export function createDataChannelHandler({
+  proxyPort,
+  onLog,
+  getTransportSnapshot,
+  sourceRegistry,
+  witness,
+  // Reads usrsctp's own association state (services/usrsctp-state.js) the
+  // moment a wedge is declared, from either detector below. Optional: a host
+  // without gdb simply never gets a reading, same as the witness without
+  // tcpdump.
+  usrsctpState
+}) {
   /**
    * Channels currently interested in one file's subtitle cues, keyed by
    * `sourceKey:fileIndex`. Populated the moment a browser asks for an
@@ -608,13 +627,26 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
   const { watchSendQueue, readDelivery } = makeSendQueueWatcher({
     log: (message) => log(message),
     getTransportSnapshot,
-    witness
+    witness,
+    usrsctpState
   });
   // Numbered probes on every channel, and the browser's echo of what it saw.
   // The proxy's own counters cannot say whether bytes it handed to usrsctp were
   // ever put on the wire; the far end can, and it keeps answering throughout a
   // freeze. See services/delivery-probe.js.
-  const deliveryProbe = createDeliveryProbe({ log: (message) => log(message), readDelivery });
+  //
+  // Also the ONLY wedge signal that does not require a nonzero channel queue —
+  // `wedgeIsCertain` above needs `queuedBytes > 0`, which small, infrequent
+  // traffic never produces (confirmed 2026-08-28: the 2026-08-27 episode's
+  // ring was never saved automatically for exactly this reason). So this is
+  // wired to the same evidence-gathering as the queue watcher.
+  const deliveryProbe = createDeliveryProbe({
+    log: (message) => log(message),
+    readDelivery,
+    getTransportSnapshot,
+    witness,
+    usrsctpState
+  });
 
   /**
    * @param {string} message

package/services/delivery-probe.js

@@ -106,6 +106,32 @@ const ECHO_STALE_FALLBACK_MS = 5_000;
 /** How often the probe state is written to the log while nothing changes. */
 const REPORT_INTERVAL_MS = 5_000;
 
+/**
+ * Whether the `seen` counter has stopped advancing for longer than this
+ * connection's own history says a healthy gap between two advances ever
+ * takes.
+ *
+ * The `association-stopped` verdict alone is not enough to act on: a
+ * connection can sit BEHIND by a bounded, roughly constant amount for
+ * minutes (measured 2026-08-28, session on a backgrounded tab — gap held at
+ * 6-7 probes for 95+ seconds while `seen` kept climbing right along with
+ * `sent`) without anything being wrong. What a true wedge shows instead,
+ * measured the same day against a session already known to be one
+ * (`d85ae4f5`): `seen` FROZEN at one value for over a minute while `sent`
+ * climbs unbounded. So the question is not "is there a gap" but "has the
+ * highest-seen number stopped moving at all, for longer than it has ever
+ * legitimately taken this connection to report an advance" — the same shape
+ * as {@link wedgeIsCertain} in `data-channel-handler.js`, applied to the
+ * probe's own counter instead of the transport's byte counter.
+ *
+ * @param {{ stuckForMs: number, longestHealthySeenGapMs: number, intervalMs?: number }} state
+ * @returns {{ certain: boolean, needMs: number }}
+ */
+export function probeWedgeIsCertain({ stuckForMs, longestHealthySeenGapMs, intervalMs = PROBE_INTERVAL_MS }) {
+  const needMs = Math.max(longestHealthySeenGapMs, intervalMs);
+  return { certain: stuckForMs >= needMs, needMs };
+}
+
 /**
  * One connection's probe state.
  *
@@ -119,6 +145,9 @@ const REPORT_INTERVAL_MS = 5_000;
  * @property {number} echoes     - How many echoes have arrived.
  * @property {string} verdict    - Last verdict reported, so a change is logged at once.
  * @property {number} reportedAt - When the state was last written to the log.
+ * @property {number} lastSeenAdvanceAt - When any label's `seen` value last increased (0 = never yet).
+ * @property {number} longestHealthySeenGapMs - The longest gap between two advances this connection has shown while not flagged as a wedge.
+ * @property {boolean} probeCaptureStarted - One evidence-gathering attempt per wedge; reset once `seen` advances again.
  * @property {ReturnType<typeof setInterval> | null} timer
  */
 
@@ -204,6 +233,11 @@ export function readProbeState(state) {
  * @param {Object} options
  * @param {(message: string) => void} options.log
  * @param {number} [options.intervalMs]
+ * @param {(sessionId: string) => object | null} [options.getTransportSnapshot]
+ *   Needed only to hand the witness a remote endpoint when this probe is the
+ *   one declaring a wedge.
+ * @param {{ maybeCapture: (trigger: object) => boolean }} [options.witness]
+ * @param {{ maybeRead: (reasonText: string) => boolean }} [options.usrsctpState]
  * @returns {{
  *   attach: (sessionId: string, tag: string, label: string, channel: import('node-datachannel').DataChannel) => void,
  *   detach: (sessionId: string, channel: import('node-datachannel').DataChannel) => void,
@@ -211,7 +245,14 @@ export function readProbeState(state) {
  *   dispose: () => void
  * }}
  */
-export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readDelivery }) {
+export function createDeliveryProbe({
+  log,
+  intervalMs = PROBE_INTERVAL_MS,
+  readDelivery,
+  getTransportSnapshot,
+  witness,
+  usrsctpState
+}) {
   /** @type {Map<string, ProbeConnection>} */
   const connections = new Map();
 
@@ -284,6 +325,47 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       connection.reportedAt = now;
       log(`[dc-probe] ${connection.tag} ${verdict} — ${detail} at=${new Date(now).toISOString()}`);
     }
+
+    // `association-stopped` alone is not certainty — see probeWedgeIsCertain.
+    // A connection that is merely lagging by a bounded amount reaches this
+    // verdict too (a hidden tab's own echo cadence, measured 2026-08-28), and
+    // `seen` keeps advancing right along with it. Only a `seen` value that has
+    // stopped moving ENTIRELY, for longer than this connection has ever shown
+    // as a legitimate gap, is the wedge this exists to catch.
+    const stuckForMs = connection.lastSeenAdvanceAt === 0 ? 0 : now - connection.lastSeenAdvanceAt;
+    if (verdict === "association-stopped") {
+      const { certain, needMs } = probeWedgeIsCertain({
+        stuckForMs,
+        longestHealthySeenGapMs: connection.longestHealthySeenGapMs
+      });
+      if (certain && !connection.probeCaptureStarted) {
+        connection.probeCaptureStarted = true;
+        const reasonText =
+          `probe seen-counter unmoved ${Math.round(stuckForMs / 1000)}s against the ` +
+          `${(needMs / 1000).toFixed(1)}s this connection's own history says is legitimate`;
+        if (witness) {
+          const snapshot = getTransportSnapshot?.(connection.id) ?? null;
+          const started = witness.maybeCapture({
+            sessionId: connection.id,
+            tag: connection.tag,
+            label: "probe",
+            remote: snapshot?.remote ?? null,
+            queuedBytes: 0,
+            stuckForMs
+          });
+          if (!started) {
+            connection.probeCaptureStarted = false;
+          }
+        }
+        if (usrsctpState) {
+          usrsctpState.maybeRead(reasonText);
+        }
+      }
+    } else {
+      // Not association-stopped any more: whatever was flagged has cleared,
+      // and a later wedge on the same connection deserves its own attempt.
+      connection.probeCaptureStarted = false;
+    }
   }
 
   return {
@@ -305,6 +387,9 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
           echoes: 0,
           verdict: "",
           reportedAt: 0,
+          lastSeenAdvanceAt: 0,
+          longestHealthySeenGapMs: 0,
+          probeCaptureStarted: false,
           timer: null
         };
         connections.set(sessionId, connection);
@@ -342,15 +427,36 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       if (!connection || !echo || typeof echo !== "object") {
         return;
       }
+      const now = Date.now();
       const seen = echo.seen;
       if (seen && typeof seen === "object") {
+        let advanced = false;
         for (const [label, value] of Object.entries(seen)) {
-          if (Number.isInteger(value)) {
-            connection.seen.set(label, value);
+          if (!Number.isInteger(value)) {
+            continue;
           }
+          const previous = connection.seen.get(label);
+          if (!Number.isInteger(previous) || value > previous) {
+            advanced = true;
+          }
+          connection.seen.set(label, value);
+        }
+        // What a wedge shows is this counter frozen, not merely behind — see
+        // probeWedgeIsCertain. The gap since the last time ANY label moved is
+        // this connection's own answer to "how long may a healthy report take
+        // to arrive", recorded only while nothing is currently flagged (the
+        // same guard `longestHealthyFlatMs` uses): a stretch already under
+        // suspicion must not teach the detector to tolerate it.
+        if (advanced) {
+          if (connection.lastSeenAdvanceAt !== 0 && !connection.probeCaptureStarted) {
+            const gap = now - connection.lastSeenAdvanceAt;
+            if (gap > connection.longestHealthySeenGapMs) {
+              connection.longestHealthySeenGapMs = gap;
+            }
+          }
+          connection.lastSeenAdvanceAt = now;
         }
       }
-      const now = Date.now();
       if (connection.echoAt !== 0) {
         const sinceLast = now - connection.echoAt;
         if (sinceLast > connection.echoIntervalMs) {

package/services/usrsctp-state.js

@@ -0,0 +1,146 @@
+/**
+ * @file Read usrsctp's live association state, without a rebuild.
+ *
+ * Roadmap item 11. `node_datachannel.node` ships unstripped — it carries
+ * usrsctp's own local symbols, including `system_base_info` and
+ * `usrsctp_getsockopt` — so the association's real state (peer receive
+ * window, pending data, retransmission timeout, congestion window) can be
+ * read out of THIS live process with a short gdb attach. No source rebuild,
+ * no SCTP_DEBUG image, no waiting for a packet capture to be read by eye.
+ *
+ * The walk (hash the association table, call `usrsctp_getsockopt` with
+ * `SCTP_STATUS` through the running process) and the healthy baseline it was
+ * checked against are in
+ * `research/session-2026-08-27-28-freeze-onset-and-sessions.md`, section 1.
+ * The script itself is bundled at {@link SCTPSTATE_SCRIPT_PATH} rather than
+ * hand-placed on a host, so it ships with every release instead of surviving
+ * only as long as someone remembers to copy it back after a container is
+ * recreated.
+ *
+ * `gdb` attaching with ptrace pauses every thread of the process for the
+ * duration of the read — one `getsockopt` call, measured at a fraction of a
+ * second in the manual procedure this automates.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { shouldStartCapture, WITNESS_COOLDOWN_MS } from "./packet-witness.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** The bundled gdb script that performs the usrsctp state walk. */
+export const SCTPSTATE_SCRIPT_PATH = path.join(HERE, "..", "assets", "diagnostics", "sctpstate.gdb");
+
+/** How long gdb may run before it is killed. Generous: this is a rare, one-shot read. */
+export const GDB_TIMEOUT_MS = 15_000;
+
+/**
+ * Create the reader.
+ *
+ * Single-flight and cooldown-gated the same way the packet witness is
+ * ({@link shouldStartCapture}) — a wedge that stays certain for minutes must
+ * not spawn a fresh gdb attach on every tick, and two readings ten seconds
+ * apart tell the same story a hundred readings would.
+ *
+ * @param {Object} options
+ * @param {(message: string) => void} options.log
+ * @param {typeof spawn} [options.spawnProcess] - Seam for tests.
+ * @param {number} [options.pid] - Defaults to this process's own pid.
+ * @param {string} [options.scriptPath]
+ * @param {number} [options.cooldownMs]
+ * @returns {{ maybeRead: (reasonText: string) => boolean }}
+ */
+export function createUsrsctpStateReader({
+  log,
+  spawnProcess = spawn,
+  pid = process.pid,
+  scriptPath = SCTPSTATE_SCRIPT_PATH,
+  cooldownMs = WITNESS_COOLDOWN_MS
+}) {
+  /** @type {{ running: boolean, lastStartedAt: number }} */
+  const state = { running: false, lastStartedAt: 0 };
+
+  /**
+   * Read the association state now, if the gating rules allow it.
+   *
+   * @param {string} reasonText - What declared the wedge, for the log line.
+   * @returns {boolean} True when a read actually started.
+   */
+  const maybeRead = (reasonText) => {
+    if (!shouldStartCapture({ ...state, cooldownMs })) {
+      return false;
+    }
+    state.running = true;
+    state.lastStartedAt = Date.now();
+    const startedAt = state.lastStartedAt;
+    void (async () => {
+      let out = "";
+      let err = "";
+      try {
+        await new Promise((resolve) => {
+          let settled = false;
+          let child;
+          const finish = () => {
+            if (settled) {
+              return;
+            }
+            settled = true;
+            clearTimeout(killer);
+            resolve();
+          };
+          try {
+            child = spawnProcess(
+              "gdb",
+              ["-q", "-batch", "-p", String(pid), "-x", scriptPath],
+              { stdio: ["ignore", "pipe", "pipe"] }
+            );
+          } catch (error) {
+            err = `could not start gdb: ${error?.message ?? error}`;
+            resolve();
+            return;
+          }
+          child.stdout?.on("data", (chunk) => {
+            out += chunk.toString();
+          });
+          child.stderr?.on("data", (chunk) => {
+            err += chunk.toString();
+          });
+          child.on("error", (error) => {
+            err += `${err ? " " : ""}gdb error: ${error?.message ?? error}`;
+            finish();
+          });
+          child.on("close", finish);
+          const killer = setTimeout(() => {
+            try {
+              child.kill("SIGKILL");
+            } catch {
+              // already gone
+            }
+          }, GDB_TIMEOUT_MS);
+          if (typeof killer.unref === "function") {
+            killer.unref();
+          }
+        });
+      } finally {
+        const lines = out.trim().length > 0 ? out.trim().split("\n") : [];
+        if (lines.length > 0) {
+          log(`usrsctp state (${reasonText}): ${lines.join(" | ")}`);
+        } else {
+          log(`usrsctp state (${reasonText}): no reading — ${err.trim() || "gdb produced no output"}`);
+        }
+        state.running = false;
+        // Same spacing rule as the packet witness: honour the cooldown even
+        // when the read ended quickly.
+        const earliestNext = startedAt + cooldownMs;
+        if (state.lastStartedAt < earliestNext) {
+          state.lastStartedAt = earliestNext;
+        }
+      }
+    })();
+    return true;
+  };
+
+  return { maybeRead };
+}

package/test/probe-wedge-certainty.test.js

@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { probeWedgeIsCertain, readProbeState, PROBE_INTERVAL_MS } from "../services/delivery-probe.js";
+
+test("a seen-counter bounded lag is not a wedge, however long it lasts", () => {
+  // Session 4dcac61b, field log 2026-08-28: gap held at 6-7 probes for 95+
+  // seconds on a backgrounded tab, but `seen` kept climbing right along with
+  // `sent` — this connection's own history says gaps up to ~3.5 s (7 probes
+  // at 500 ms) are ordinary, so the same 3.5 s stuck must not read as certain.
+  const verdict = probeWedgeIsCertain({
+    stuckForMs: 3400,
+    longestHealthySeenGapMs: 3500
+  });
+  assert.equal(verdict.certain, false);
+});
+
+test("a seen-counter frozen past this connection's own worst legitimate gap is a wedge", () => {
+  // Session d85ae4f5, the same field log: `seen` frozen at one value for over
+  // a minute while `sent` climbed unbounded — this is the shape the detector
+  // exists to catch.
+  const verdict = probeWedgeIsCertain({
+    stuckForMs: 90_000,
+    longestHealthySeenGapMs: 3500
+  });
+  assert.equal(verdict.certain, true);
+});
+
+test("with no healthy history yet, one probe interval is still required", () => {
+  const verdict = probeWedgeIsCertain({
+    stuckForMs: PROBE_INTERVAL_MS - 1,
+    longestHealthySeenGapMs: 0
+  });
+  assert.equal(verdict.certain, false);
+  assert.equal(verdict.needMs, PROBE_INTERVAL_MS);
+});
+
+test("readProbeState calls association-stopped only when the unreliable channel agrees", () => {
+  // Ordered channels behind, but the unordered/no-retransmit one current:
+  // head-of-line blocking in one stream, not the association.
+  const streamStuck = readProbeState({
+    seq: 100,
+    seen: { proxy: 90, "proxy-control": 90, "proxy-fast": 99 },
+    labels: ["proxy", "proxy-control", "proxy-fast"],
+    echoes: 5,
+    echoAgeMs: 100,
+    allowed: { proxy: 2, "proxy-control": 2, "proxy-fast": 2 }
+  });
+  assert.equal(streamStuck.verdict, "stream-stuck");
+
+  const associationStopped = readProbeState({
+    seq: 100,
+    seen: { proxy: 90, "proxy-control": 90, "proxy-fast": 90 },
+    labels: ["proxy", "proxy-control", "proxy-fast"],
+    echoes: 5,
+    echoAgeMs: 100,
+    allowed: { proxy: 2, "proxy-control": 2, "proxy-fast": 2 }
+  });
+  assert.equal(associationStopped.verdict, "association-stopped");
+});

package/test/usrsctp-state.test.js

@@ -0,0 +1,115 @@
+/**
+ * @file The usrsctp state reader's gating and command construction.
+ *
+ * Roadmap item 11: reads usrsctp's live association state via gdb the moment
+ * a wedge is declared. Everything here is the part that decides WHEN and WITH
+ * WHAT ARGUMENTS — the spawning itself is thin glue around these, the same
+ * shape as the packet witness (test/packet-witness.test.js).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+
+import { createUsrsctpStateReader, SCTPSTATE_SCRIPT_PATH } from "../services/usrsctp-state.js";
+
+class FakeChild extends EventEmitter {
+  constructor(command, args) {
+    super();
+    this.command = command;
+    this.args = args;
+    this.stdout = new EventEmitter();
+    this.stderr = new EventEmitter();
+  }
+
+  kill() {
+    // Not exercised by these tests — every fake run finishes on its own.
+    return true;
+  }
+}
+
+/**
+ * @param {string} output - What the fake gdb writes to stdout before closing.
+ * @returns {{ spawnProcess: Function, calls: Array<{ command: string, args: string[] }> }}
+ */
+function makeSpawn(output) {
+  const calls = [];
+  const spawnProcess = (command, args) => {
+    calls.push({ command, args });
+    const child = new FakeChild(command, args);
+    setImmediate(() => {
+      if (output) {
+        child.stdout.emit("data", Buffer.from(output));
+      }
+      child.emit("close", 0);
+    });
+    return child;
+  };
+  return { spawnProcess, calls };
+}
+
+/** Wait until `check` holds, rather than for a chosen interval. */
+async function waitFor(check) {
+  const deadline = Date.now() + 5_000;
+  for (;;) {
+    if (check()) {
+      return;
+    }
+    if (Date.now() > deadline) {
+      throw new Error("timed out waiting for the reading to be logged");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+test("gdb is invoked attached to this process with the bundled script", async () => {
+  const { spawnProcess, calls } = makeSpawn("state=8 rwnd=95890\n");
+  const lines = [];
+  const reader = createUsrsctpStateReader({
+    log: (message) => lines.push(message),
+    spawnProcess,
+    pid: 4242
+  });
+  const started = reader.maybeRead("test wedge");
+  assert.equal(started, true);
+  await waitFor(() => lines.length > 0);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].args, ["-q", "-batch", "-p", "4242", "-x", SCTPSTATE_SCRIPT_PATH]);
+  assert.match(lines[0], /state=8 rwnd=95890/);
+  assert.match(lines[0], /test wedge/);
+});
+
+test("no output is reported as no reading, not silence", async () => {
+  const { spawnProcess } = makeSpawn("");
+  const lines = [];
+  const reader = createUsrsctpStateReader({ log: (message) => lines.push(message), spawnProcess, pid: 1 });
+  reader.maybeRead("empty case");
+  await waitFor(() => lines.length > 0);
+  assert.match(lines[0], /no reading/);
+});
+
+test("a second read is refused within the cooldown, like the packet witness", async () => {
+  const { spawnProcess, calls } = makeSpawn("state=8\n");
+  const lines = [];
+  const reader = createUsrsctpStateReader({
+    log: (message) => lines.push(message),
+    spawnProcess,
+    pid: 1,
+    cooldownMs: 60_000
+  });
+  assert.equal(reader.maybeRead("first"), true);
+  await waitFor(() => lines.length > 0);
+  assert.equal(reader.maybeRead("second, too soon"), false);
+  assert.equal(calls.length, 1);
+});
+
+test("a missing gdb is reported, not thrown", async () => {
+  const lines = [];
+  const spawnProcess = () => {
+    throw new Error("spawn gdb ENOENT");
+  };
+  const reader = createUsrsctpStateReader({ log: (message) => lines.push(message), spawnProcess, pid: 1 });
+  reader.maybeRead("no gdb on this host");
+  await waitFor(() => lines.length > 0);
+  assert.match(lines[0], /could not start gdb/);
+});