@origintrail-official/dkg-core 10.0.19 → 10.0.21

package/dist/protocol-router.js

@@ -1,4 +1,5 @@
 import { LibP2PNetwork } from './network/libp2p-network.js';
+import { startRequestAbortLifecycle } from './request-abort-lifecycle.js';
 import { MessageStreamPool, POOLED_MESSAGE_PROTOCOL, } from './message-stream-pool.js';
 import { withSpan, getMetrics } from './telemetry-api.js';
 /** Default max bytes readAll will buffer before aborting (10 MB). */
@@ -452,8 +453,8 @@ export class ProtocolRouter {
      * probe opens and immediately aborts the stream before any payload bytes.
      */
     async probeProtocol(peerIdStr, protocolId, timeoutMs = 3_000) {
-        const deadline = AbortSignal.timeout(timeoutMs);
-        const signal = composeAbortSignals(deadline, this.node.stopSignal) ?? deadline;
+        const lifecycle = startRequestAbortLifecycle(timeoutMs, [this.node.stopSignal]);
+        const signal = lifecycle.signal;
         try {
             await this.requirePeerAccepted(peerIdStr, protocolId, 'outbound', { signal, timeoutMs });
             // Match send()'s resolver contract before opening a stream. For the
@@ -475,10 +476,237 @@ export class ProtocolRouter {
                 throw error;
             return isProtocolUnsupportedError(error) ? 'unsupported' : 'unavailable';
         }
+        finally {
+            lifecycle.release();
+        }
+    }
+    /**
+     * Own one dedicated duplex stream. Only negotiation may change routes;
+     * after callback entry no authenticated request is retried or replayed.
+     */
+    async withDuplexStream(peerIdStr, protocolId, options, exchange) {
+        this.validateDuplexStreamOptions(options);
+        const lifecycle = startRequestAbortLifecycle(options.timeoutMs, [options.signal, this.node.stopSignal]);
+        const signal = lifecycle.signal;
+        let stream;
+        const abortOwned = () => { if (stream)
+            abortStream(stream, signal.reason); };
+        signal.addEventListener('abort', abortOwned, { once: true });
+        try {
+            const openStream = await this.createAdmittedPeerStreamOperation(peerIdStr, protocolId, signal, options.timeoutMs);
+            ({ stream } = await openStream({
+                resolverTimeoutMs: options.timeoutMs,
+                afterDialFailure: 'reuse-limited',
+                cancelledResolution: 'throw',
+            }));
+            this.boundDuplexStreamBuffers(stream, options.maxReadBufferBytes);
+            const result = await exchange(stream, signal);
+            if (signal.aborted)
+                throw asAbortError(signal.reason);
+            await this.closeDuplexStream(stream, signal);
+            return result;
+        }
+        finally {
+            if (stream && stream.status !== 'closed')
+                abortStream(stream, new Error('duplex stream scope ended'));
+            signal.removeEventListener('abort', abortOwned);
+            lifecycle.release();
+        }
+    }
+    /** Read a bounded request, then retain its continuation for duplex work. */
+    registerDuplexStream(protocolId, readRequest, handler, options) {
+        this.validateDuplexStreamOptions(options);
+        if (!Number.isSafeInteger(options.maxRequestBytes) || options.maxRequestBytes <= 0
+            || options.maxRequestBytes > this.maxReadBytes)
+            throw new RangeError('Invalid duplex request limit');
+        this.node.libp2p.handle(protocolId, async (stream, connection) => {
+            const peerId = connection.remotePeer.toString();
+            const closed = new AbortController();
+            const onClose = () => closed.abort(new Error('duplex peer stream closed'));
+            const lifecycle = startRequestAbortLifecycle(options.timeoutMs, [options.signal, this.node.stopSignal, closed.signal]);
+            const signal = lifecycle.signal;
+            const onAbort = () => abortStream(stream, signal.reason);
+            let request;
+            stream.addEventListener('close', onClose, { once: true });
+            signal.addEventListener('abort', onAbort, { once: true });
+            try {
+                if (signal.aborted)
+                    throw asAbortError(signal.reason);
+                this.rejectKnownRejectedInboundPeer(peerId, protocolId);
+                this.boundDuplexStreamBuffers(stream, options.maxReadBufferBytes);
+                request = await readRequest(stream, signal);
+                if (request.requestData.byteLength > options.maxRequestBytes)
+                    throw new RangeError('Duplex request byte limit exceeded');
+                await this.requirePeerAccepted(peerId, protocolId, 'inbound', { signal, timeoutMs: options.timeoutMs });
+                if (signal.aborted)
+                    throw asAbortError(signal.reason);
+                await handler({ ...request, peerId, stream, signal });
+                if (signal.aborted)
+                    throw asAbortError(signal.reason);
+                stream.removeEventListener('close', onClose);
+                await this.closeDuplexStream(stream, signal);
+            }
+            catch (error) {
+                // Do not log authenticated request bytes, metadata, URLs or tokens.
+                abortStream(stream, error instanceof Error ? error : new Error('duplex stream failed'));
+            }
+            finally {
+                stream.removeEventListener('close', onClose);
+                signal.removeEventListener('abort', onAbort);
+                if (stream.status !== 'closed')
+                    abortStream(stream, new Error('duplex stream scope ended'));
+                await request?.dispose?.().catch(() => undefined);
+                lifecycle.release();
+            }
+        }, { runOnLimitedConnection: true });
+    }
+    validateDuplexStreamOptions(options) {
+        if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0
+            || !Number.isSafeInteger(options.maxReadBufferBytes) || options.maxReadBufferBytes <= 0
+            || options.maxReadBufferBytes > this.maxReadBytes)
+            throw new RangeError('Invalid duplex stream limits');
+    }
+    boundDuplexStreamBuffers(stream, limit) {
+        stream.maxReadBufferLength = Math.min(stream.maxReadBufferLength || limit, limit);
+        stream.maxWriteBufferLength = Math.min(stream.maxWriteBufferLength || limit, limit);
+    }
+    async closeDuplexStream(stream, signal) {
+        // close() flushes and half-closes only the writable end. Wait for the
+        // peer's half-close too: resetting immediately could discard final bytes
+        // already handed to the transport but not yet consumed by the peer.
+        let onClose;
+        let onAbort;
+        const settled = new Promise((resolve, reject) => {
+            onClose = () => stream.status === 'closed' ? resolve() : reject(new Error('Duplex stream closed before settlement'));
+            onAbort = () => reject(asAbortError(signal.reason));
+            stream.addEventListener('close', onClose, { once: true });
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        // The close operation may fail before the close-event promise is awaited.
+        void settled.catch(() => undefined);
+        try {
+            if (signal.aborted)
+                throw asAbortError(signal.reason);
+            await stream.close({ signal });
+            if (stream.status !== 'closed')
+                await settled;
+        }
+        finally {
+            stream.removeEventListener('close', onClose);
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+    /**
+     * Admission is checked once for the operation, before any transport work.
+     * Each open uses a fresh connection snapshot and resolver watch. The caller
+     * owns payload retries and chooses when a failed direct dial permits relay
+     * reuse; this operation never sends or replays application bytes.
+     */
+    async createAdmittedPeerStreamOperation(peerIdStr, protocolId, signal, timeoutMs) {
+        if (signal.aborted)
+            throw asAbortError(signal.reason);
+        await this.requirePeerAccepted(peerIdStr, protocolId, 'outbound', { signal, timeoutMs });
+        if (signal.aborted)
+            throw asAbortError(signal.reason);
+        // Keep parsing lazy: pooled sends may settle without a one-shot open.
+        let peerId;
+        return async (options) => {
+            if (signal.aborted)
+                throw asAbortError(signal.reason);
+            peerId ??= (await import('@libp2p/peer-id')).peerIdFromString(peerIdStr);
+            const targetPeer = peerId;
+            const libp2p = this.node.libp2p;
+            // Raw walks heal keyed-lookup misses. Remember every observed connection
+            // so the resolver yields only to a connection this pass has not tried.
+            const considered = new WeakSet();
+            const getConnections = () => {
+                const connections = rawGetConnectionsFor(libp2p, targetPeer);
+                for (const connection of connections)
+                    considered.add(connection);
+                return connections;
+            };
+            const reuseOptions = {
+                peerHasDirectAddrs: async () => {
+                    const peer = await libp2p.peerStore.get(targetPeer);
+                    return (peer.addresses ?? []).some(({ multiaddr }) => {
+                        const address = multiaddr?.toString?.() ?? '';
+                        return Boolean(address) && !address.includes('/p2p-circuit');
+                    });
+                },
+                allowLimitedWithDirectAddrs: options.allowLimitedWithDirectAddrs,
+                excludeConnections: options.excludeConnections,
+            };
+            let reused = await tryReuseExistingConnection(getConnections, protocolId, signal, reuseOptions);
+            if (!reused && this.peerResolver && !signal.aborted) {
+                // Only resolution follows the connection event signal. Negotiation and
+                // payload work keep the caller's original cancellation/deadline signal.
+                const connected = watchForNewPeerConnection(libp2p, targetPeer, considered);
+                const resolution = composeAbortSignalsScoped(signal, connected?.signal);
+                try {
+                    if (!connected?.signal.aborted) {
+                        await this.peerResolver.resolve(peerIdStr, {
+                            signal: resolution.signal ?? signal,
+                            perStepTimeoutMs: options.resolverTimeoutMs,
+                        }).catch(() => undefined);
+                    }
+                }
+                finally {
+                    resolution.dispose();
+                    connected?.dispose();
+                }
+                if (connected?.signal.aborted) {
+                    reused = await tryReuseExistingConnection(getConnections, protocolId, signal, reuseOptions);
+                }
+            }
+            if (signal.aborted && (reused || options.cancelledResolution === 'throw')) {
+                if (reused)
+                    abortStream(reused.stream, signal.reason);
+                throw asAbortError(signal.reason);
+            }
+            const dialStartedAt = Date.now();
+            let stream;
+            if (reused)
+                stream = reused.stream;
+            else {
+                options.onNormalDial?.();
+                try {
+                    stream = await this.network.dialProtocol(peerIdStr, protocolId, { signal });
+                }
+                catch (error) {
+                    if (options.afterDialFailure === 'throw')
+                        throw error;
+                    if (signal.aborted)
+                        throw asAbortError(signal.reason);
+                    // No application bytes have been sent. A duplex scope may use an
+                    // existing relay after the normal dial actually failed.
+                    reused = await tryReuseExistingConnection(getConnections, protocolId, signal, { ...reuseOptions, allowLimitedWithDirectAddrs: true });
+                    if (!reused)
+                        throw error;
+                    stream = reused.stream;
+                }
+            }
+            if (signal.aborted) {
+                abortStream(stream, signal.reason);
+                throw asAbortError(signal.reason);
+            }
+            return { stream, connection: reused?.connection ?? null, dialDurationMs: Date.now() - dialStartedAt };
+        };
     }
     async sendInner(peerIdStr, protocolId, data, timeoutMsOrOpts = DEFAULT_SEND_TIMEOUT_MS) {
         const opts = typeof timeoutMsOrOpts === 'number' ? { timeoutMs: timeoutMsOrOpts } : timeoutMsOrOpts;
         const timeoutMs = opts.timeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
+        // One deadline for the whole send, following the caller's signal and
+        // node.stopSignal. Once the send settles nothing of it stays attached to
+        // either (#2812).
+        const lifecycle = startRequestAbortLifecycle(timeoutMs, [opts.signal, this.node.stopSignal]);
+        try {
+            return await this.sendWithinLifecycle(peerIdStr, protocolId, data, opts, timeoutMs, lifecycle);
+        }
+        finally {
+            lifecycle.release();
+        }
+    }
+    async sendWithinLifecycle(peerIdStr, protocolId, data, opts, timeoutMs, lifecycle) {
         const singleUsePayload = opts.payloadReuse === 'single-use';
         const maxAttempts = singleUsePayload ? 1 : 3;
         const parallelPaths = Math.max(1, Math.floor(opts.parallelPaths ?? 1));
@@ -487,16 +715,10 @@ export class ProtocolRouter {
         }
         const maxReadBytes = resolveSendMaxReadBytes(opts.maxReadBytes, this.maxReadBytes);
         const overallStartedAt = Date.now();
-        const overallDeadline = AbortSignal.timeout(timeoutMs);
+        const overallDeadline = lifecycle.deadline;
         const stopSignal = this.node.stopSignal;
-        const budgetSignal = composeAbortSignals(overallDeadline, opts.signal) ?? overallDeadline;
-        const overallSignal = composeAbortSignals(budgetSignal, stopSignal) ?? budgetSignal;
-        if (overallSignal.aborted)
-            throw asAbortError(overallSignal.reason);
-        await this.requirePeerAccepted(peerIdStr, protocolId, 'outbound', {
-            signal: overallSignal,
-            timeoutMs,
-        });
+        const overallSignal = lifecycle.signal;
+        const openStream = await this.createAdmittedPeerStreamOperation(peerIdStr, protocolId, overallSignal, timeoutMs);
         // Pooled overlay short-circuit. When `enablePooling(protocolId)`
         // has been called for this logical protocol AND the peer hasn't
         // been pinned to the one-shot wire variant by a prior fallback,
@@ -625,11 +847,11 @@ export class ProtocolRouter {
         if (remainingMs === 0) {
             throw new Error(`send timeout: pooled fallback exhausted the ${timeoutMs}ms budget before one-shot attempt`);
         }
-        const libp2p = this.node.libp2p;
-        const { peerIdFromString } = await import('@libp2p/peer-id');
-        const peerId = peerIdFromString(peerIdStr);
         const startedAt = overallStartedAt;
         if (parallelPaths > 1) {
+            const libp2p = this.node.libp2p;
+            const { peerIdFromString } = await import('@libp2p/peer-id');
+            const peerId = peerIdFromString(peerIdStr);
             // Reuse the overall budget rather than starting a fresh one
             // — see comment above. Codex PR #560 round 4.
             const multipathSignalWithStop = overallSignal;
@@ -706,8 +928,9 @@ export class ProtocolRouter {
                 lastErr = new Error('send timeout elapsed');
                 throw lastErr;
             }
-            const attemptDeadline = AbortSignal.timeout(remaining);
-            const attemptSignal = composeAbortSignals(attemptDeadline, overallSignal) ?? attemptDeadline;
+            // The request deadline already ends where this attempt's remaining
+            // budget does, so every attempt shares the request signal.
+            const attemptSignal = overallSignal;
             if (attemptSignal.aborted)
                 throw asAbortError(attemptSignal.reason);
             // Track which connection (if any) the fast path picked this
@@ -717,153 +940,19 @@ export class ProtocolRouter {
             let pickedConnection = null;
             let attemptedNormalDial = false;
             try {
-                // RFC 07 §3.2: re-prime the libp2p peerStore on EVERY attempt.
-                //
-                // Was originally a single pre-loop call (PR #497) but that left
-                // a real cold-dial gap surfaced during the two-laptop debug
-                // session that produced PR #517 + the MessageOutbox PR: if the
-                // first resolver call landed during a transient routing-table
-                // miss (peer's K-bucket entry expired, no live gossip source,
-                // DHT walk happened to time out), all 3 dialProtocol attempts
-                // hit the same empty peerStore in the next ~1.5s and the loop
-                // gave up with `'no valid addresses for peer'` before any DHT
-                // advertisement / `connection:open` event from the recipient
-                // could populate addresses for a later attempt.
-                //
-                // Re-running per-attempt is cheap on the warm path (the
-                // resolver's step 1 is a sub-millisecond live-connection check
-                // that short-circuits when we already have the peer connected
-                // or its addresses cached in the peerStore) and only pays the
-                // DHT-walk / registry-lookup cost on the cold path — which is
-                // exactly the case we want to keep paying for, because that's
-                // where address staleness actually hurts. The resolver itself
-                // never throws (returns empty array on miss); the dial below
-                // surfaces a real transport error if the peer is genuinely
-                // unreachable.
-                //
-                // Codex review feedback on PR #497: pass the same AbortSignal +
-                // remaining time budget to the resolver so a caller's
-                // `timeoutMs` bounds the entire send (resolver + dial + read).
-                // First try the existing-connection fast path: if we already
-                // have at least one open connection to this peer (of ANY
-                // direction, direct OR circuit-relay-limited), open the new
-                // stream on that connection directly via `newStream` instead
-                // of going through `dialProtocol`. This sidesteps the entire
-                // address-resolution + peerStore lookup path that returns
-                // "no valid addresses for peer" when libp2p's peerStore is
-                // empty or stale for the peer — the "Window D" failure class
-                // identified in the May 2026 Miles↔Lex 6h soak postmortem,
-                // where 31 inbound circuit `connection:open` events from peer
-                // P over 4 minutes failed to heal any of 20 opportunistic
-                // outbound flushes because each one went through dialProtocol
-                // and lost the peerStore race.
-                //
-                // Crucially: when peerStore is empty for P (the Window D
-                // shape), the connection-manager-auto-dial side effect of
-                // `peerStore.merge` documented at
-                // docs/archive/UPSTREAM_ISSUE_DRAFT.md does NOT fire — there
-                // are no direct addresses to upgrade to. So this fast path
-                // does not introduce the mid-stream-negotiation race the doc
-                // warns about; it benefits exactly the case where the doc's
-                // race cannot apply.
-                //
-                // Failure here (connection died between `getConnections` and
-                // `newStream`, peer dropped protocol support, etc.) falls
-                // through to the dialProtocol path below WITHIN THE SAME
-                // ATTEMPT, so we don't waste a retry slot on the fast-path
-                // miss.
-                // CRITICAL: feed the fast path from a RAW `getConnections()`
-                // walk filtered by `remotePeer`, NOT from the peerId-keyed
-                // `libp2p.getConnections(peerId)` lookup.
-                //
-                // The PR #533 diagnostic surface (`PeerDiagnostics`) is
-                // explicitly built around the divergence
-                // `rawConnectionCount > getConnectionsReturnsForPeer` as the
-                // smoking-gun Window D signature: libp2p's peerId-keyed
-                // lookup can return `[]` even when a raw walk over all
-                // connections shows one or more open connections whose
-                // `remotePeer` matches the target peerId. Using the keyed
-                // lookup here would make the fast path miss the EXACT case
-                // it was built to heal — `tryReuseExistingConnection` would
-                // get an empty candidate list, fall through to the resolver
-                // + dialProtocol path, and still fail with "no valid
-                // addresses for peer". Walk raw, filter ourselves, and
-                // accept that we pay the O(N) cost over the whole
-                // connection table per send — N is the total open-conn
-                // count of the node, typically <100, so the cost is a few
-                // microseconds and the correctness win is large.
-                //
-                // Every connection the walk hands the fast path is recorded, so
-                // the resolver watch below can tell a connection that opened
-                // after this pass from one the pass already skipped or failed on.
-                const consideredConnections = new WeakSet();
-                const getPeerConnections = () => {
-                    const connections = rawGetConnectionsFor(libp2p, peerId);
-                    for (const connection of connections)
-                        consideredConnections.add(connection);
-                    return connections;
-                };
-                const fastPathOptions = {
-                    // Probe peerStore for non-circuit (direct) addresses; the
-                    // fast path uses this to gate whether reusing a LIMITED
-                    // (circuit-relay-v2) connection is safe or whether
-                    // libp2p's CM is about to auto-upgrade and prune it
-                    // mid-stream. See the JSDoc inside
-                    // `tryReuseExistingConnection` + the PR #537 CI
-                    // postmortem for the DCUtR upgrade race detail.
-                    peerHasDirectAddrs: async () => {
-                        const peer = await libp2p.peerStore.get(peerId);
-                        const addrs = peer.addresses ?? [];
-                        for (const a of addrs) {
-                            const ma = a.multiaddr?.toString?.() ?? '';
-                            if (ma && !ma.includes('/p2p-circuit'))
-                                return true;
-                        }
-                        return false;
-                    },
+                // Re-prime on each cold retry, while warm reuse skips resolution.
+                // A failed normal dial unlocks limited reuse on the next attempt;
+                // unlike a duplex scope, send() keeps its existing retry/backoff gate.
+                const opened = await openStream({
+                    resolverTimeoutMs: remaining,
                     allowLimitedWithDirectAddrs: normalDialFailed,
                     excludeConnections: triedConnections,
-                };
-                let fastResult = await tryReuseExistingConnection(getPeerConnections, protocolId, attemptSignal, fastPathOptions);
-                if (this.peerResolver && !fastResult) {
-                    // One resolver step can spend the whole remaining budget:
-                    // kad-dht parks a findPeer until its signal aborts while the
-                    // routing table is empty. A connection to the peer that opens
-                    // meanwhile (the peer dialing us, or a concurrent dial) makes
-                    // further resolution pointless, just as the resolver's own
-                    // live-connection step would, so it ends the resolver early and
-                    // the fast path runs again over it. Only the resolver's signal
-                    // is cut short; the rest of the attempt keeps `attemptSignal`.
-                    const peerConnected = watchForNewPeerConnection(libp2p, peerId, consideredConnections);
-                    try {
-                        if (!peerConnected?.signal.aborted) {
-                            await this.peerResolver
-                                .resolve(peerIdStr, {
-                                signal: composeAbortSignals(attemptSignal, peerConnected?.signal) ?? attemptSignal,
-                                perStepTimeoutMs: remaining,
-                            })
-                                .catch(() => undefined);
-                        }
-                    }
-                    finally {
-                        peerConnected?.dispose();
-                    }
-                    if (peerConnected?.signal.aborted) {
-                        fastResult = await tryReuseExistingConnection(getPeerConnections, protocolId, attemptSignal, fastPathOptions);
-                    }
-                }
-                const fastStream = fastResult?.stream ?? null;
-                pickedConnection = fastResult?.connection ?? null;
-                const dialStartedAt = Date.now();
-                let stream;
-                if (fastStream) {
-                    stream = fastStream;
-                }
-                else {
-                    attemptedNormalDial = true;
-                    stream = await this.network.dialProtocol(peerIdStr, protocolId, { signal: attemptSignal });
-                }
-                const dialDurationMs = Date.now() - dialStartedAt;
+                    afterDialFailure: 'throw',
+                    cancelledResolution: 'dial-with-signal',
+                    onNormalDial: () => { attemptedNormalDial = true; },
+                });
+                const { stream, dialDurationMs } = opened;
+                pickedConnection = opened.connection;
                 if (stream.writeStatus === 'closed' || stream.writeStatus === 'closing') {
                     stream.abort(new Error('stream closed before send'));
                     throw new Error('stream returned in closed state');
@@ -916,7 +1005,10 @@ export class ProtocolRouter {
                 // during the backoff, we throw immediately rather than
                 // continuing into another attempt that's already over budget.
                 await new Promise((resolve, reject) => {
-                    const t = setTimeout(resolve, backoff);
+                    const t = setTimeout(() => {
+                        overallSignal.removeEventListener('abort', onAbort);
+                        resolve();
+                    }, backoff);
                     const onAbort = () => {
                         clearTimeout(t);
                         if (stopSignal?.aborted) {
@@ -1220,7 +1312,21 @@ export async function raceMultiPath(args) {
     const picked = candidates.slice(0, parallelPaths);
     const streams = picked.map(() => null);
     let winnerIdx = -1;
+    // One controller per path, following the shared signal, so a loser is
+    // cancelled as soon as the winner settles even while it is still waiting
+    // for `newStream`, instead of running on until the shared signal aborts.
+    const pathControllers = picked.map(() => new AbortController());
+    const forwardShared = () => {
+        for (const controller of pathControllers) {
+            if (!controller.signal.aborted)
+                controller.abort(signal.reason);
+        }
+    };
+    signal.addEventListener('abort', forwardShared, { once: true });
     const abortPath = (idx, reason) => {
+        const controller = pathControllers[idx];
+        if (!controller.signal.aborted)
+            controller.abort(reason);
         const s = streams[idx];
         if (!s || s.aborted)
             return;
@@ -1240,9 +1346,10 @@ export async function raceMultiPath(args) {
         }
     };
     const attempts = picked.map(async (conn, idx) => {
+        const pathSignal = pathControllers[idx].signal;
         const stream = await conn.newStream(protocolId, {
             runOnLimitedConnection: true,
-            signal,
+            signal: pathSignal,
         });
         streams[idx] = { stream, aborted: false };
         if (winnerIdx !== -1 && winnerIdx !== idx) {
@@ -1259,8 +1366,8 @@ export async function raceMultiPath(args) {
             throw new Error('multipath: stream returned in closed state');
         }
         stream.send(data);
-        await stream.close({ signal });
-        return await readAllWithSignal(stream, maxReadBytes, signal);
+        await stream.close({ signal: pathSignal });
+        return await readAllWithSignal(stream, maxReadBytes, pathSignal);
     });
     let winnerResponse = null;
     try {
@@ -1308,6 +1415,9 @@ export async function raceMultiPath(args) {
             throw asAbortError(signal.reason);
         return null;
     }
+    finally {
+        signal.removeEventListener('abort', forwardShared);
+    }
     return { response: winnerResponse, attemptedPaths: picked.length };
 }
 /**
@@ -1373,6 +1483,11 @@ export async function readAllWithSignal(stream, maxBytes, signal) {
  * Uses Node's `AbortSignal.any` when available (Node 20.3+, current
  * production target). Falls back to a manual composer for older Node
  * — keeps tests / older sandboxes working.
+ *
+ * Not for per-request use against a long-lived signal: when an input is an
+ * `AbortSignal.timeout` signal, Node keeps the result, and its entry on the
+ * other input, alive until that input is collected (#2812). The router's
+ * own requests use `startRequestAbortLifecycle` instead.
  */
 export function composeAbortSignals(primary, secondary) {
     if (!primary)