socketduct 0.1.21 → 0.1.23

package/changelog.d/20260928120416-reverse-gateway-spool-directory.md

@@ -0,0 +1,3 @@
+# Outbound reverse gateway spool directory environment variable
+
+The standalone outbound reverse gateway runtime now accepts `SOCKETDUCT_SPOOL_DIRECTORY`, which points the gateway's durable target-output spool at an operator-chosen persistent path. The default remains the process temporary directory, so containerized gateways can move the bounded spool behind exactly-once resume replay onto a host volume instead of the container's ephemeral, size-bounded `/tmp`. The variable is accepted only in `reverse-gateway` mode and is rejected in every other mode.

package/changelog.d/20260928124500-critical-reserve-bound-test.md

@@ -0,0 +1,3 @@
+# Bound the compressed-log critical reserve test to a coverable charge
+
+The compressed-log queue-pressure test asserted that a critical disconnect record is accepted while a 4096-byte queue holds a 1024-byte critical reserve, but the record's conservative charge (line bytes × 3 + 128) exceeds the reserve, so the writer correctly dropped it and the test failed on every run. Accepted log sequences are append-only and cannot be evicted without tearing the durable journal, so the test now reserves 2048 bytes — covering the critical record's charge — and the logging docs state the reserve sizing bound explicitly.

package/changelog.d/20260928233813-reverse-retained-terminal-outcomes.md

@@ -0,0 +1,3 @@
+# Preserve terminal outcomes and coordinate paired resume deadlines for retained reverse streams
+
+The reverse hub now retains the exact terminal code and incident attribution for a stream that ends while its peer owner is still resumable, so a reconnecting peer that presents the stream in its resume manifest receives the causal result instead of `RESUME_SESSION_LOST` (genuinely absent state still fails closed with `RESUME_SESSION_LOST`). While a final resume manifest waits on a temporarily detached counterpart, the hub extends the pair's original resume deadline by at most one additional resume window, once per retention episode, so reconnect backoff equal to the window no longer loses resumable streams.

package/changelog.d/20260929023727-reverse-terminal-outcome-bounds.md

@@ -0,0 +1,3 @@
+# Bound retained reverse terminal outcomes and retain them only when delivery may have been missed
+
+The reverse hub now retains a stream's exact terminal outcome only for an owner that may genuinely have missed the terminal delivery (physically absent, closing, or in paired-resume/pending-manifest state) — a healthy attached owner that receives the frame retains nothing — and hard-caps each owner's retained outcomes at the configured per-owner stream bound, evicting the oldest first. This prevents unbounded hub memory growth from authenticated stream churn while evicted streams still fail closed with `RESUME_SESSION_LOST` (never a replay or a target reopen).

package/docs/logging.md

@@ -28,7 +28,11 @@ SOCKETDUCT_LOG_COMPRESSION_LEVEL=19
 Those values are the defaults. Reaching the uncompressed frame limit starts a
 flush immediately. Flush deadlines are measured from the oldest queued work and
 are never extended by later records; critical lifecycle, security, and resume
-events use the shorter deadline and may use the reserved queue capacity.
+events use the shorter deadline and may use the reserved queue capacity. A
+critical record is guaranteed acceptance only while its conservative charge
+(line bytes × 3 + 128) fits the reserve, because accepted sequences are
+append-only and can never be evicted from the durable journal; size the
+reserve for the largest critical record you must retain under queue pressure.
 Segment size, age, and directory quota are bounded independently. Invalid or mutually
 inconsistent values stop startup.
 The former `SOCKETDUCT_LOG_MAX_FILE_BYTES` and `SOCKETDUCT_LOG_MAX_FILES`

package/docs/reverse-gateway.md

@@ -98,7 +98,13 @@ replays only durable chunks above the receiver-confirmed high-water position,
 with its flow-control window reduced by bytes already buffered but not yet
 consumed at the receiver. A registered gateway completing this paired resume is
 not healthy or eligible for a new selection or `OPEN`; retained peers alone may
-attach to submit their resume manifests.
+attach to submit their resume manifests. A stream that terminates while its
+peer owner is still retained keeps its exact terminal code and incident
+attribution, and a reconnecting peer that presents the stream in its resume
+manifest receives that causal result; genuinely absent state still fails closed
+with `RESUME_SESSION_LOST`. While a final resume manifest waits on a
+temporarily detached counterpart, the hub extends the pair's original resume
+deadline by at most one additional resume window, once per retention episode.
 
 The hub owns a separate ordered output queue for every client and gateway
 physical connection. Each queue defaults to a 32 MiB bound and can be set with
@@ -298,9 +304,17 @@ SOCKETDUCT_REVERSE_TOKEN='<secret>' \
 SOCKETDUCT_REVERSE_HUB_CA_FILE=/certs/hub-ca.crt \
 SOCKETDUCT_REVERSE_HUB_SERVERNAME=server3.example.net \
 SOCKETDUCT_TARGET_ALLOWLIST=docker-a:2375 \
+SOCKETDUCT_SPOOL_DIRECTORY=/var/lib/socketduct/spool \
 node src/index.js
 ```
 
+`SOCKETDUCT_SPOOL_DIRECTORY` is reverse-gateway-only and points the gateway's
+durable target-output spool — the bounded store behind exactly-once resume
+replay — at an operator-chosen path. Without it the spool lives under the
+process temporary directory, which is ephemeral and size-bounded inside a
+container; set it to a persistent host mount so spool capacity and retention
+do not depend on container lifetime. The runtime rejects it in every other mode.
+
 The namespace/default-route configuration remains outside Socketduct. Each
 gateway registration represents one exact target server and WAN class;
 Socketduct does not aggregate away either identity. Socketduct needs no inbound

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

package/src/config/environment.js

@@ -54,6 +54,7 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
  * @property {string} relayHost - Relay listen host.
  * @property {number} relayPort - Relay listen port.
  * @property {number} resumeWindowMs - Resume window in milliseconds.
+ * @property {string} [spoolDirectory] - Outbound gateway durable spool root; reverse-gateway mode only.
  * @property {number} maxTargetBufferBytes - Per-session byte limit for buffered target data while the tunnel is detached.
  * @property {number} maxTotalBufferBytes - Process-wide byte limit for buffered target data across all sessions.
  * @property {number} [initialTargetRetryDelayMs] - Initial delay between target acquisition attempts. Default 250.
@@ -143,6 +144,8 @@ export function loadEnvironmentConfig(env = process.env) {
     ...(reverseClientCertFile === undefined ? {} : {certFile: reverseClientCertFile, keyFile: /** @type {string} */ (reverseClientKeyFile)}),
     ...(env.SOCKETDUCT_REVERSE_HUB_SERVERNAME?.trim() ? {servername: env.SOCKETDUCT_REVERSE_HUB_SERVERNAME.trim()} : {})
   }
+  const spoolDirectory = env.SOCKETDUCT_SPOOL_DIRECTORY?.trim() || undefined
+  if (spoolDirectory !== undefined && mode !== "reverse-gateway") throw new Error("SOCKETDUCT_SPOOL_DIRECTORY is reverse-gateway-only")
   const logDirectory = env.SOCKETDUCT_LOG_DIRECTORY?.trim() || undefined
   if (env.SOCKETDUCT_LOG_MAX_FILE_BYTES !== undefined || env.SOCKETDUCT_LOG_MAX_FILES !== undefined) throw new Error("SOCKETDUCT_LOG_MAX_FILE_BYTES and SOCKETDUCT_LOG_MAX_FILES were replaced by compressed log frame, segment, and retention settings")
   let fileLogging
@@ -251,7 +254,8 @@ export function loadEnvironmentConfig(env = process.env) {
         port: parsePort(env.SOCKETDUCT_REVERSE_HUB_PORT, "SOCKETDUCT_REVERSE_HUB_PORT", DEFAULT_RELAY_PORT),
         token: reverseToken ?? ""
       },
-      reverseHubTls
+      reverseHubTls,
+      ...(spoolDirectory === undefined ? {} : {spoolDirectory})
     } : {})
   }
 }

package/src/reverse/hub.js

@@ -32,6 +32,7 @@ import {
   sanitizePeerControlDetail,
   validateFingerprintKeyEpoch
 } from "./disconnect-attribution.js"
+import {insertBoundedTerminalOutcome, ownerMayMissTerminalDelivery} from "./terminal-outcomes.js"
 
 const DEFAULT_OUTPUT_BUFFER_BYTES = 32 * 1024 * 1024
 const DEFAULT_RESUME_MS = 60_000
@@ -84,8 +85,9 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {number} resumeNextPage
  * @property {Array<Record<string, unknown>>} resumeItems
  * @property {boolean} resumeFinal
- * @property {Array<{streamId: number, bridge: Bridge | undefined, code?: string}>} resumeEntries
+ * @property {Array<{streamId: number, bridge: Bridge | undefined, code?: string, attribution?: import('./disconnect-attribution.js').DisconnectAttribution}>} resumeEntries
  * @property {ReturnType<typeof setTimeout> | undefined} resumeTimer
+ * @property {boolean} resumeExtended - Whether this physical already used its one bounded paired-resume extension.
  * @property {(() => void) | undefined} clearHandshake
  * @property {HubOutputItem[]} outputQueue
  * @property {number} outputBytes
@@ -97,6 +99,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @typedef {object} HubOutputItem
  * @property {Buffer} bytes
  * @property {(delivered: boolean) => void} resolve
+ * @typedef {{code: string, attribution: import('./disconnect-attribution.js').DisconnectAttribution | undefined}} TerminalOutcome
  * @typedef {object} GatewayOwner
  * @property {string} gatewayId
  * @property {string} connectionId
@@ -104,7 +107,10 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {number} generation
  * @property {HubPhysical | undefined} physical
  * @property {Map<number, Bridge>} streams
+ * @property {Map<string, TerminalOutcome>} terminalOutcomes - Exact terminal outcomes for streams this owner may still present.
  * @property {ReturnType<typeof setTimeout> | undefined} expiryTimer
+ * @property {number | undefined} detachedAt - Epoch start of the current retention episode.
+ * @property {boolean} expiryExtended - Whether the current episode already used its one bounded extension.
  * @typedef {object} ClientOwner
  * @property {string} connectionId
  * @property {string} userId
@@ -113,7 +119,10 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {Map<number, Bridge>} streams
  * @property {string | undefined} gatewayId
  * @property {string | undefined} routeClass
+ * @property {Map<string, TerminalOutcome>} terminalOutcomes - Exact terminal outcomes for streams this owner may still present.
  * @property {ReturnType<typeof setTimeout> | undefined} expiryTimer
+ * @property {number | undefined} detachedAt - Epoch start of the current retention episode.
+ * @property {boolean} expiryExtended - Whether the current episode already used its one bounded extension.
  * @typedef {object} Bridge
  * @property {HubPhysical} client
  * @property {ClientOwner} clientOwner
@@ -225,6 +234,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       resumeFinal: false,
       resumeEntries: [],
       resumeTimer: undefined,
+      resumeExtended: false,
       clearHandshake: undefined,
       outputQueue: [],
       outputBytes: 0,
@@ -362,11 +372,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       streams: new Map(),
       gatewayId: undefined,
       routeClass: undefined,
-      expiryTimer: undefined
+      terminalOutcomes: new Map(),
+      expiryTimer: undefined,
+      detachedAt: undefined,
+      expiryExtended: false
     }
     owner.generation = physical.generation
     owner.physical = physical
     owner.expiryTimer = undefined
+    owner.detachedAt = undefined
+    owner.expiryExtended = false
     physical.streams = owner.streams
     physical.lastClientStreamId = Math.max(0, ...owner.streams.keys())
     physical.resumeRequired = existing !== undefined && owner.streams.size > 0
@@ -415,11 +430,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       generation: physical.generation,
       physical: undefined,
       streams: new Map(),
-      expiryTimer: undefined
+      terminalOutcomes: new Map(),
+      expiryTimer: undefined,
+      detachedAt: undefined,
+      expiryExtended: false
     }
     owner.generation = physical.generation
     owner.physical = physical
     owner.expiryTimer = undefined
+    owner.detachedAt = undefined
+    owner.expiryExtended = false
     physical.streams = owner.streams
     physical.nextGatewayStreamId = Math.max(0, ...owner.streams.keys()) + 2
     physical.resumeRequired = existing !== undefined && owner.streams.size > 0
@@ -480,7 +500,15 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       presented.add(item.streamId)
       const bridge = physical.streams.get(item.streamId)
       if (bridge === undefined) {
-        physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: "RESUME_SESSION_LOST"})
+        const owner = physical.role === "client" ? clients.get(/** @type {string} */ (physical.connectionId)) : gateways.get(/** @type {string} */ (physical.gatewayId))
+        const retainedKey = `${item.streamId}\0${item.identifier}`
+        const retained = owner === undefined ? undefined : owner.terminalOutcomes.get(retainedKey)
+        if (owner !== undefined && retained !== undefined) {
+          owner.terminalOutcomes.delete(retainedKey)
+          physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: retained.code, ...(retained.attribution === undefined ? {} : {attribution: retained.attribution})})
+        } else {
+          physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: "RESUME_SESSION_LOST"})
+        }
         continue
       }
       if (bridge.identifier !== item.identifier) {
@@ -506,6 +534,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     physical.resumeItems = []
     physical.resumeFinal = true
     await tryCompleteResumes()
+    if (physical.resumeRequired) coordinateResumeDeadlines(physical)
   }
 
   /** Completes physical resume responses only after both logical endpoints have declared durable positions. */
@@ -538,7 +567,19 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
         for (const entry of physical.resumeEntries) {
           const bridge = entry.bridge
           if (bridge === undefined || !bridgeStillOwned(bridge)) {
-            results.push({streamId: entry.streamId, status: "reset", code: entry.code ?? "RESUME_SESSION_LOST"})
+            let code = entry.code ?? "RESUME_SESSION_LOST"
+            let attribution = entry.attribution
+            if (bridge !== undefined) {
+              const owner = physical.role === "client" ? clients.get(/** @type {string} */ (physical.connectionId)) : gateways.get(/** @type {string} */ (physical.gatewayId))
+              const retainedKey = `${entry.streamId}\0${bridge.identifier}`
+              const retained = owner === undefined ? undefined : owner.terminalOutcomes.get(retainedKey)
+              if (owner !== undefined && retained !== undefined) {
+                owner.terminalOutcomes.delete(retainedKey)
+                code = retained.code
+                attribution = retained.attribution
+              }
+            }
+            results.push({streamId: entry.streamId, status: "reset", code, ...(attribution === undefined ? {} : attribution)})
             continue
           }
           try {
@@ -594,6 +635,37 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     physical.resumeTimer = undefined
   }
 
+  /**
+   * Coordinates the paired resume deadlines while a final manifest waits on a
+   * temporarily detached counterpart: one bounded extension of the original
+   * retention deadlines so reconnect backoff equal to the window cannot win.
+   */
+  function coordinateResumeDeadlines(/** @type {HubPhysical} */ physical) {
+    let deadline
+    for (const entry of physical.resumeEntries) {
+      const bridge = entry.bridge
+      if (bridge === undefined || !bridgeStillOwned(bridge)) continue
+      const peerOwner = physical.role === "client" ? bridge.gatewayOwner : bridge.clientOwner
+      if (peerOwner.physical !== undefined || peerOwner.expiryTimer === undefined || peerOwner.detachedAt === undefined) continue
+      if (peerOwner.expiryExtended !== true) {
+        peerOwner.expiryExtended = true
+        const extendedDeadline = peerOwner.detachedAt + 2 * resumeWindowMs
+        clearTimeout(peerOwner.expiryTimer)
+        peerOwner.expiryTimer = setTimeout(() => {
+          void expireOwner(peerOwner, physical.role === "client" ? "gateway" : "client")
+        }, Math.max(0, extendedDeadline - Date.now()))
+        peerOwner.expiryTimer.unref?.()
+      }
+      const peerDeadline = peerOwner.detachedAt + (peerOwner.expiryExtended === true ? 2 : 1) * resumeWindowMs
+      deadline = Math.max(deadline ?? peerDeadline, peerDeadline)
+    }
+    if (deadline === undefined || physical.resumeExtended === true || physical.resumeTimer === undefined || deadline <= Date.now()) return
+    physical.resumeExtended = true
+    clearTimeout(physical.resumeTimer)
+    physical.resumeTimer = setTimeout(() => terminate(physical, "RESUME_WINDOW_EXPIRED"), deadline - Date.now())
+    physical.resumeTimer.unref?.()
+  }
+
   /** Reconciles one bridge to receiver-committed byte positions for a fresh physical generation. */
   function reconcileBridge(/** @type {Bridge} */ bridge) {
     const client = bridge.clientResume
@@ -808,6 +880,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       forwardControl(destination, frame.type, destinationStreamId, frame.sequence, detail)
       if (frame.type === V3FrameType.RESET || fromClient) {
         removeBridge(bridge)
+        if (typeof detail.code === "string") retainTerminalOutcome(bridge, detail.code, attribution)
         if (attribution !== undefined && bridge.disconnectAttribution !== undefined) {
           logDiagnostic(options.logger, "reverse_hub.streams_reset", {
             ...attribution,
@@ -840,6 +913,33 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     forwardOutput(destination, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)))
   }
 
+  /**
+   * Retains the exact terminal outcome for each still-registered owner that may
+   * genuinely have missed the terminal delivery, bounded to that owner's stream
+   * limit. A healthy attached owner already received the frame and will not
+   * re-present the stream, so it retains nothing.
+   * @param {Bridge} bridge - Stream.
+   * @param {string} code - Terminal code.
+   * @param {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Incident attribution.
+   */
+  function retainTerminalOutcome(bridge, code, attribution) {
+    retainTerminalOutcomeFor(clients.get(bridge.clientOwner.connectionId), bridge.clientOwner, `${bridge.clientStreamId}\0${bridge.identifier}`, code, attribution)
+    retainTerminalOutcomeFor(gateways.get(bridge.gatewayOwner.gatewayId), bridge.gatewayOwner, `${bridge.gatewayStreamId}\0${bridge.identifier}`, code, attribution)
+  }
+
+  /**
+   * @param {ClientOwner | GatewayOwner | undefined} owner - Current owner record.
+   * @param {ClientOwner | GatewayOwner} bridgeOwner - Owner recorded on the bridge.
+   * @param {string} key - Stream identity key.
+   * @param {string} code - Terminal code.
+   * @param {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Incident attribution.
+   */
+  function retainTerminalOutcomeFor(owner, bridgeOwner, key, code, attribution) {
+    if (owner === undefined || owner !== bridgeOwner) return
+    if (ownerMayMissTerminalDelivery(owner.physical) !== true) return
+    insertBoundedTerminalOutcome(owner.terminalOutcomes, key, {code, attribution}, maxStreams)
+  }
+
   /** @param {Bridge} bridge - Stream. @param {string} code - Reset code. @param {HubPhysical} [excluded] - Already-dead peer. @returns {Promise<void>} Terminal control delivery. */
   function closeBridge(bridge, code, excluded) {
     const owned = bridgeStillOwned(bridge)
@@ -854,6 +954,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     if (bridge.client !== excluded && !bridge.client.socket.destroyed) deliveries.push(sendControl(bridge.client, V3FrameType.RESET, bridge.clientStreamId, 0, detail))
     if (bridge.gateway !== excluded && !bridge.gateway.socket.destroyed) deliveries.push(sendControl(bridge.gateway, V3FrameType.RESET, bridge.gatewayStreamId, 0, detail))
     removeBridge(bridge)
+    retainTerminalOutcome(bridge, code, attribution)
     if (attribution !== undefined) logDiagnostic(options.logger, "reverse_hub.streams_reset", {
       ...attribution,
       gatewayId: bridge.gatewayOwner.gatewayId,
@@ -999,6 +1100,10 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
   /** @param {GatewayOwner | ClientOwner} owner - Detached identity. @param {'gateway' | 'client'} role - Owner role. */
   function scheduleOwnerExpiry(owner, role) {
     if (owner.expiryTimer !== undefined) clearTimeout(owner.expiryTimer)
+    if (owner.detachedAt === undefined) {
+      owner.detachedAt = Date.now()
+      owner.expiryExtended = false
+    }
     owner.expiryTimer = setTimeout(() => {
       void expireOwner(owner, role)
     }, resumeWindowMs)
@@ -1010,6 +1115,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     owner.expiryTimer = undefined
     if (owner.physical !== undefined) return
     for (const bridge of [...owner.streams.values()]) await closeBridge(bridge, "RESUME_WINDOW_EXPIRED")
+    owner.terminalOutcomes.clear()
     if (role === "gateway") {
       const gatewayOwner = /** @type {GatewayOwner} */ (owner)
       if (gateways.get(gatewayOwner.gatewayId) === gatewayOwner) gateways.delete(gatewayOwner.gatewayId)

package/src/reverse/runtime.js

@@ -80,6 +80,7 @@ export async function startOutboundReverseGatewayRuntime(config, logger) {
     maxStreamBufferBytes: config.maxTargetBufferBytes,
     maxTotalBufferBytes: config.maxTotalBufferBytes,
     compressionLimits: compressionLimits(config),
+    ...(config.spoolDirectory === undefined ? {} : {spoolDirectory: config.spoolDirectory}),
     ...(logger === undefined ? {} : {logger})
   })
   await gateway.start()

package/src/reverse/terminal-outcomes.js

@@ -0,0 +1,55 @@
+/**
+ * Bounded, eligibility-gated retention of exact terminal outcomes for reverse
+ * stream owners.
+ *
+ * A retained terminal outcome only matters to an owner that may genuinely have
+ * missed the terminal frame. A healthy attached physical receives the frame and
+ * retires the stream locally, so it never re-presents the stream and must not
+ * accumulate retained outcomes — unbounded growth under authenticated stream
+ * churn would otherwise exhaust hub memory. Retention is additionally hard-capped
+ * to the owner's configured stream bound so that even a detached/resuming owner
+ * cannot retain more outcomes than it could ever present; eviction is fail-closed
+ * (the evicted stream later resolves as RESUME_SESSION_LOST, never a replay or a
+ * target reopen).
+ */
+
+/**
+ * @typedef {object} TerminalOutcome
+ * @property {string} code - Exact terminal classification.
+ * @property {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Validated incident, when one was in flight.
+ */
+
+/**
+ * @typedef {object} OwnerPhysicalState
+ * @property {boolean} closing - Whether the physical close has begun.
+ * @property {boolean} resumeRequired - Whether the physical is still in its paired-resume / pending-manifest state.
+ */
+
+/**
+ * Decides whether an owner may have missed a terminal delivery and therefore
+ * needs the exact outcome retained for a later resume manifest.
+ * @param {OwnerPhysicalState | undefined} physical - The owner's current physical state.
+ * @returns {boolean} Whether the terminal outcome should be retained for the owner.
+ */
+export function ownerMayMissTerminalDelivery(/** @type {OwnerPhysicalState | undefined} */ physical) {
+  if (physical === undefined) return true
+  return physical.closing || physical.resumeRequired
+}
+
+/**
+ * Inserts one terminal outcome into an owner's bounded retention map, evicting
+ * the oldest entry (deterministic Map insertion order) whenever the insertion
+ * would exceed the bound. Re-inserting a retained key updates it in place.
+ * @param {Map<string, TerminalOutcome>} outcomes - The owner's retained outcomes.
+ * @param {string} key - The stream identity key.
+ * @param {TerminalOutcome} outcome - The terminal outcome to retain.
+ * @param {number} limit - The maximum number of retained outcomes.
+ */
+export function insertBoundedTerminalOutcome(/** @type {Map<string, TerminalOutcome>} */ outcomes, /** @type {string} */ key, /** @type {TerminalOutcome} */ outcome, /** @type {number} */ limit) {
+  outcomes.set(key, outcome)
+  while (outcomes.size > limit) {
+    const oldest = outcomes.keys().next()
+    if (oldest.done === true) break
+    outcomes.delete(/** @type {string} */ (oldest.value))
+  }
+}

package/test/e2e/reverse-gateway-process.test.js

@@ -1,7 +1,7 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
 import assert from "node:assert/strict"
 import {spawn} from "node:child_process"
-import {mkdtemp, rm} from "node:fs/promises"
+import {mkdtemp, readFile, readdir, rm} from "node:fs/promises"
 import {createServer} from "node:net"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
@@ -131,6 +131,31 @@ async function withTimeout(promise, label) {
   }
 }
 
+/** @param {string} directory - Directory. @returns {Promise<string[]>} Entries, or an empty list for a missing directory. */
+async function readDirectoryOrEmpty(directory) {
+  try {
+    return await readdir(directory)
+  } catch (error) {
+    if (error instanceof Error && /** @type {Error & {code?: string}} */ (error).code === "ENOENT") return []
+    throw error
+  }
+}
+
+/**
+ * Polls until the probe resolves truthy, bounded by the process timeout.
+ * @param {() => boolean | Promise<boolean>} probe - Condition to test.
+ * @param {string} label - Timeout label.
+ * @returns {Promise<void>}
+ */
+async function waitUntil(probe, label) {
+  const deadline = Date.now() + PROCESS_TIMEOUT_MS
+  for (;;) {
+    if (await probe()) return
+    if (Date.now() >= deadline) throw new Error(`Timed out: ${label}`)
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+}
+
 /** @param {import('node:events').EventEmitter} emitter - Source. @param {string} event - Event. */
 async function onceEvent(emitter, event) {
   await new Promise((resolve, reject) => {
@@ -377,3 +402,97 @@ test("one route-class client physical connection interleaves streams through dif
   streamA.destroy()
   streamB.destroy()
 })
+
+test("outbound gateway process spools durably under SOCKETDUCT_SPOOL_DIRECTORY when the hub link is lost", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-spool-process-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const gatewaySpoolDirectory = join(root, "gateway-spool")
+  const clientSpoolDirectory = join(root, "client-spool")
+  /** @type {import('node:net').Socket | undefined} */
+  let targetSocket
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetSocket = socket
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("docker:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => {
+    for (const socket of targetSockets) socket.destroy()
+    return new Promise((resolve) => target.close(() => resolve(undefined)))
+  })
+  const {child: hub, port: hubPort} = await startProcessOnReservedPort({
+    SOCKETDUCT_MODE: "reverse-hub",
+    SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+    SOCKETDUCT_TLS_CERT_FILE: certificates.serverCertFile,
+    SOCKETDUCT_TLS_KEY_FILE: certificates.serverKeyFile,
+    SOCKETDUCT_AUTH_TOKENS: "home-o2:spool-gateway-token,tensorbuzz:spool-client-token",
+    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
+    SOCKETDUCT_REVERSE_ROUTES: `tensorbuzz:o2:127.0.0.1:${targetPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+  }, "reverse-hub.started")
+  const gateway = await startProcess({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "o2",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "spool_process_gateway",
+    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+    SOCKETDUCT_REVERSE_TOKEN: "spool-gateway-token",
+    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0",
+    SOCKETDUCT_SPOOL_DIRECTORY: gatewaySpoolDirectory
+  }, "reverse-gateway.started")
+  t.after(() => stopProcess(gateway))
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "spool_process_client",
+    hub: {host: "127.0.0.1", port: hubPort, token: "spool-client-token"},
+    tls: {caFile: certificates.caCertFile, servername: "localhost"},
+    spoolDirectory: clientSpoolDirectory,
+    reconnectDelayMs: 50,
+    maxReconnectDelayMs: 100
+  })
+  t.after(() => client.close())
+  await withTimeout(client.connect(), "spool client connect")
+  const socket = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "docker-spool-process"})
+  await withTimeout(onceEvent(socket, "connect"), "spool stream open")
+  const initialResponse = new Promise((resolve, reject) => { socket.once("error", reject); socket.once("data", resolve) })
+  socket.write("GET /version")
+  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(initialResponse, "spool initial response"))).toString(), "docker:GET /version")
+
+  hub.kill("SIGKILL")
+  await withTimeout(new Promise((resolve) => hub.once("exit", () => resolve(undefined))), "hub exit")
+  assert(targetSocket !== undefined)
+  const spooledMarker = Buffer.alloc(32, 0x61)
+  targetSocket.write(spooledMarker)
+  const spoolHasPayload = async () => {
+    const markerBase64 = spooledMarker.toString("base64")
+    for (const session of await readDirectoryOrEmpty(gatewaySpoolDirectory)) {
+      const files = await readDirectoryOrEmpty(join(gatewaySpoolDirectory, session))
+      if (!files.includes("chunks.jsonl")) continue
+      const lines = (await readFile(join(gatewaySpoolDirectory, session, "chunks.jsonl"), "utf8")).split("\n")
+      if (lines.some((line) => {
+        if (line === "") return false
+        try {
+          return /** @type {{dataBase64?: unknown}} */ (JSON.parse(line)).dataBase64 === markerBase64
+        } catch (error) {
+          if (error instanceof SyntaxError) return false
+          throw error
+        }
+      })) return true
+    }
+    return false
+  }
+  await waitUntil(spoolHasPayload, "durable spool chunk under SOCKETDUCT_SPOOL_DIRECTORY")
+  const defaultGatewaySpoolRoot = join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "reverse-gateway")
+  const defaultSpooled = (await readDirectoryOrEmpty(defaultGatewaySpoolRoot)).some((entry) => entry.startsWith("o2-spool_process_gateway"))
+  assert.equal(defaultSpooled, false, "spool must not fall back to the ephemeral default root")
+
+  socket.destroy()
+  client.close()
+  await stopProcess(gateway)
+})

package/test/integration/reverse-resume-continuity.test.js

@@ -0,0 +1,333 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {mkdtemp, rm} from "node:fs/promises"
+import {connect as connectTcp, createServer} from "node:net"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {Duplex} from "node:stream"
+import test from "node:test"
+
+import {StaticTokenStore} from "../../src/auth/static-token-store.js"
+import {OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "../../src/reverse/index.js"
+import {generateTestCertificates} from "../helpers/tls-certificates.js"
+
+/** @param {import('node:net').Server} server - Server. */
+async function listen(server) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(undefined) })
+  })
+  const address = server.address()
+  assert(address !== null && typeof address !== "string")
+  return address.port
+}
+
+/** @param {import('node:events').EventEmitter} emitter - Emitter. @param {string} event - Event. */
+async function onceEvent(emitter, event) {
+  await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    emitter.once(event, () => { emitter.off("error", reject); resolve(undefined) })
+  })
+}
+
+/** @param {import('node:stream').Duplex} socket - Socket. @param {number} bytes - Expected bytes. */
+async function readBytes(socket, bytes) {
+  return await new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
+    const chunks = []
+    let length = 0
+    const cleanup = () => { socket.off("data", onData); socket.off("error", onError) }
+    /** @param {Error} error - Stream failure. */
+    const onError = (error) => { cleanup(); reject(error) }
+    /** @param {Buffer} chunk - Stream bytes. */
+    const onData = (chunk) => {
+      chunks.push(chunk)
+      length += chunk.length
+      if (length < bytes) return
+      cleanup()
+      resolve(Buffer.concat(chunks))
+    }
+    socket.on("data", onData)
+    socket.on("error", onError)
+  })
+}
+
+/** @param {Promise<unknown>} promise - Work. @param {string} label - Timeout label. */
+async function withTimeout(promise, label) {
+  let timer
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), 2_000) })
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** @param {() => boolean} predicate - Completion predicate. @param {string} label - Failure label. */
+async function waitUntil(predicate, label) {
+  const deadline = Date.now() + 4_000
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`Timed out: ${label}`)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+}
+
+/** @param {import('node:stream').Duplex} socket - Stream. @returns {Promise<Error & {code?: string}>} Next stream error. */
+async function nextError(socket) {
+  return await new Promise((resolve) => socket.once("error", (error) => resolve(/** @type {Error & {code?: string}} */ (error))))
+}
+
+/** Target that records received bytes and can flood the gateway buffer on demand while the peer physical is down. */
+class RecordingInterruptibleTarget extends Duplex {
+  /** @type {Buffer[]} */
+  chunks = []
+
+  constructor() {
+    super()
+    setImmediate(() => this.emit("connect"))
+  }
+
+  /** @override */
+  _read() {}
+
+  /** @param {Buffer} chunk - Received bytes. @param {BufferEncoding} _encoding - Ignored encoding. @param {(error?: Error | null) => void} callback - Completion. @override */
+  _write(chunk, _encoding, callback) {
+    this.chunks.push(Buffer.from(chunk))
+    callback()
+  }
+
+  /** @param {Buffer} payload - Target-originated bytes delivered to the gateway. */
+  flood(payload) { this.emit("data", payload) }
+}
+
+test("a paired resume completes when the first counterpart return lands just past the original resume window", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-resume-extension-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("target:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 250})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "extension_gateway_01", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 350, maxReconnectDelayMs: 350})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "extension_client_01", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({identifier: "extension_stream_01", sessionName: "extension-stream", host: "127.0.0.1", port: targetPort})
+  await onceEvent(socket, "connect")
+  socket.write("before|")
+  const preResponse = readBytes(socket, 14)
+  assert.equal((await withTimeout(preResponse, "pre-resume target echo")).toString(), "target:before|")
+
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  socket.write("after|")
+  const postResponse = readBytes(socket, 13)
+  // The gateway's first return (~350ms) lands after the original 250ms window;
+  // the bounded paired-resume extension must keep both deadlines open for it.
+  await waitUntil(() => gateway.status().physicalConnects >= 2 && gateway.status().physicalState === "ready", "gateway return just past the original window")
+  assert.equal((await withTimeout(postResponse, "post-resume target echo")).toString(), "target:after|")
+  assert.equal(targetAccepts, 1, "resume must keep the original logical target socket")
+  assert.equal(hub.status().virtualStreams, 1)
+
+  const closed = onceEvent(socket, "close")
+  socket.end()
+  await withTimeout(closed, "post-resume cleanup close")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "post-resume ownership cleanup")
+})
+
+test("a retained terminal outcome answers a reconnecting peer with the causal code instead of RESUME_SESSION_LOST", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-retained-outcome-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let acceptsA = 0
+  const targetSocketsA = new Set()
+  const targetA = createServer((socket) => {
+    acceptsA += 1
+    targetSocketsA.add(socket)
+    socket.once("close", () => targetSocketsA.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("a:"), chunk])))
+  })
+  const portA = await listen(targetA)
+  t.after(() => { for (const socket of targetSocketsA) socket.destroy(); return new Promise((resolve) => targetA.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 2_000})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  /** @type {RecordingInterruptibleTarget | undefined} */
+  let targetB
+  let targetBCreates = 0
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "outcome_gateway_01",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"},
+    tls,
+    spoolDirectory: join(root, "gateway-spool"),
+    authorizeTarget: () => true,
+    reconnectDelayMs: 300,
+    maxReconnectDelayMs: 300,
+    maxStreamBufferBytes: 32,
+    createTargetConnection: (target) => {
+      if (target.port === 2376) {
+        targetBCreates += 1
+        targetB = new RecordingInterruptibleTarget()
+        return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (targetB))
+      }
+      return connectTcp(target)
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "outcome_client_01", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 500, maxReconnectDelayMs: 500})
+  t.after(() => client.close())
+  await client.connect()
+  const socketA = client.createConnection({identifier: "outcome_stream_a", sessionName: "outcome-a", host: "127.0.0.1", port: portA})
+  const socketB = client.createConnection({identifier: "outcome_stream_b", sessionName: "outcome-b", host: "target-b", port: 2376})
+  await Promise.all([onceEvent(socketA, "connect"), onceEvent(socketB, "connect")])
+  socketA.write("one|")
+  const preA = readBytes(socketA, 6)
+  assert.equal((await withTimeout(preA, "stream A pre-interruption echo")).toString(), "a:one|")
+  socketB.write("two|")
+  await waitUntil(() => targetB !== undefined && Buffer.concat(targetB.chunks).toString() === "two|", "stream B bytes reached its target")
+  const terminalB = nextError(socketB)
+
+  // The gateway physical dies and the client peer is kicked into a slow (500ms)
+  // reconnect. While both are apart, target B overflows the gateway stream
+  // buffer: the gateway resets and destroys B in memory, but its RESET cannot
+  // reach the hub, so the hub still owns B when the gateway re-registers.
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  await new Promise((resolve) => setTimeout(resolve, 100))
+  assert.equal(client.status().physicalState, "reconnecting", "the client peer must still be mid-reconnect when target B overflows")
+  targetB?.flood(Buffer.alloc(64, 0x42))
+  await waitUntil(() => hub.status().gatewayPhysicalConnections >= 1, "gateway re-registration before the peer returns")
+  assert.equal(targetB?.destroyed, true, "the overflowed stream target must be released in memory")
+
+  const error = /** @type {Error & Record<string, unknown>} */ (await withTimeout(terminalB, "stream B terminal outcome after peer return"))
+  assert.equal(error.code, "RESUME_STREAM_OMITTED", "the reconnecting peer must receive the retained causal code")
+  assert.match(String(error.disconnectIncidentId ?? ""), /^[A-Za-z0-9_-]{22}$/, "the retained outcome must carry the incident attribution")
+
+  const postA = readBytes(socketA, 12)
+  socketA.write("one-after|")
+  assert.equal((await withTimeout(postA, "stream A post-resume echo")).toString(), "a:one-after|")
+  assert.equal(acceptsA, 1, "the surviving stream must resume on its original target")
+  assert.equal(targetBCreates, 1, "the terminal stream must never reopen its target")
+  assert.equal(targetB?.destroyed, true, "the terminal stream target must be released exactly once")
+
+  const closedA = onceEvent(socketA, "close")
+  socketA.end()
+  await withTimeout(closedA, "stream A cleanup close")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSocketsA.size === 0, "retained-outcome ownership cleanup")
+})
+
+test("a paired resume extension is bounded by one window and genuine expiry still releases state", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-resume-bounded-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 250})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "bounded_expiry_gateway", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 1_000, maxReconnectDelayMs: 1_000})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "bounded_expiry_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({identifier: "bounded_stream_01", sessionName: "bounded-stream", host: "127.0.0.1", port: targetPort})
+  const terminal = nextError(socket)
+  await onceEvent(socket, "connect")
+
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  // The gateway returns at ~1000ms, far beyond the one bounded extension
+  // (original 250ms window extended once to 500ms), so the pair must expire.
+  const error = /** @type {Error & {code?: string}} */ (await withTimeout(terminal, "bounded expired resume"))
+  assert.equal(error.code, "RESUME_WINDOW_EXPIRED")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "bounded expiry releases all retained state")
+  assert.equal(targetAccepts, 1, "the expired stream must not reopen its target")
+})
+
+test("multiple concurrent streams share one physical interruption and resume together on their original targets", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-multi-stream-resume-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("t:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 2_000})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "multi_resume_gateway", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 30, maxReconnectDelayMs: 30})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "multi_resume_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  /** @type {import('node:stream').Duplex[]} */
+  const sockets = []
+  /** @type {Promise<string>[]} */
+  const echoes = []
+  for (let index = 1; index <= 3; index += 1) {
+    const socket = client.createConnection({identifier: `multi_stream_${index}`, sessionName: `multi-stream-${index}`, host: "127.0.0.1", port: targetPort})
+    sockets.push(socket)
+    await onceEvent(socket, "connect")
+  }
+  let echoIndex = 1
+  for (const socket of sockets) {
+    socket.write(`pre${echoIndex}|`)
+    echoes.push(readBytes(socket, 2 + 3 + String(echoIndex).length + 1).then((bytes) => bytes.toString()))
+    echoIndex += 1
+  }
+  const preEchoes = await Promise.all(echoes.map((promise) => withTimeout(promise, "pre-resume echo")))
+  assert.deepEqual(preEchoes, ["t:pre1|", "t:pre2|", "t:pre3|"])
+  assert.equal(targetAccepts, 3)
+
+  await hub.closeActiveGateway("o2")
+  let postIndex = 1
+  for (const socket of sockets) {
+    socket.write(`post${postIndex}|`)
+    postIndex += 1
+  }
+  /** @type {Promise<string>[]} */
+  const postEchoes = sockets.map((socket, index) => readBytes(socket, 2 + 4 + String(index + 1).length + 1).then((bytes) => bytes.toString()))
+  await waitUntil(() => gateway.status().physicalConnects >= 2 && gateway.status().physicalState === "ready", "shared gateway re-registration")
+  const postEchoesReceived = await Promise.all(postEchoes.map((promise) => withTimeout(promise, "post-resume echo")))
+  assert.deepEqual(postEchoesReceived, ["t:post1|", "t:post2|", "t:post3|"], "every stream must resume on its original target without cross-stream loss")
+  assert.equal(targetAccepts, 3, "the shared interruption must not create replacement targets")
+  assert.equal(hub.status().virtualStreams, 3)
+
+  const closes = sockets.map((socket) => { socket.end(); return onceEvent(socket, "close") })
+  await Promise.all(closes.map((promise) => withTimeout(promise, "multi-stream cleanup close")))
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "multi-stream ownership cleanup")
+})

package/test/unit/config/environment.test.js

@@ -337,6 +337,31 @@ test("loadEnvironmentConfig parses outbound reverse gateway verified TLS setting
   assert.deepEqual(config.reverseHubTls, {caFile: "/certs/ca.crt", certFile: "/certs/client.crt", keyFile: "/certs/client.key", servername: "server3.example.test"})
 })
 
+test("loadEnvironmentConfig parses the reverse-gateway spool directory", () => {
+  const config = loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: " /spool/reverse-gateway "
+  })
+  assert.equal(config.spoolDirectory, "/spool/reverse-gateway")
+  assert.equal("spoolDirectory" in loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: "   "
+  }), false)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "relay", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+})
+
 test("loadEnvironmentConfig rejects malformed reverse mode policy and credentials", () => {
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"}), /Unsupported SOCKETDUCT_MODE/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"}), /gatewayId:username/)

package/test/unit/logging/compressed-log-writer.test.js

@@ -61,11 +61,13 @@ test("compressed logger durably acknowledges ordered records and closes asynchro
 test("compressed logger enforces one shared bounded queue with a critical reserve", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-pressure-"))
   const directory = join(root, "logs")
+  // The reserve must cover the critical event's conservative charge (line bytes × 3 + 128);
+  // an accepted-but-undelivered sequence can never be evicted without tearing the durable journal.
   const logger = createCompressedJsonlFileLogger({
     directory,
     role: "reverse-client",
     maxQueueBytes: 4096,
-    criticalReserveBytes: 1024,
+    criticalReserveBytes: 2048,
     frameMaxBytes: 1024,
     flushIntervalMs: 60_000,
     criticalFlushIntervalMs: 60_000

package/test/unit/reverse-terminal-outcomes.test.js

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {insertBoundedTerminalOutcome, ownerMayMissTerminalDelivery} from "../../src/reverse/terminal-outcomes.js"
+
+test("a healthy attached physical does not retain a terminal outcome; absent, closing, and pending-resume states do", () => {
+  // Healthy attached: the peer receives the terminal frame and retires the
+  // stream locally, so it never re-presents it. Retaining here is the
+  // unbounded-growth bug: it must be a no-eligibility (no retention).
+  assert.equal(ownerMayMissTerminalDelivery({closing: false, resumeRequired: false}), false)
+  // Detached (no physical): the terminal frame cannot be delivered.
+  assert.equal(ownerMayMissTerminalDelivery(undefined), true)
+  // Closing: the frame may not be flushed.
+  assert.equal(ownerMayMissTerminalDelivery({closing: true, resumeRequired: false}), true)
+  // Paired-resume / pending-manifest state: the frame is answered through the
+  // RESUME manifest instead of a live relay.
+  assert.equal(ownerMayMissTerminalDelivery({closing: false, resumeRequired: true}), true)
+})
+
+test("retention is capped at the owner stream bound, evicting the oldest first in deterministic insertion order", () => {
+  const outcomes = new Map()
+  const limit = 3
+  const outcome = (/** @type {string} */ code) => ({code, attribution: undefined})
+
+  // Within the bound: every outcome is retained, in insertion order.
+  insertBoundedTerminalOutcome(outcomes, "s1\0a", outcome("RESUME_STREAM_OMITTED"), limit)
+  insertBoundedTerminalOutcome(outcomes, "s2\0b", outcome("BUFFER_LIMIT"), limit)
+  assert.equal(outcomes.size, 2)
+  assert.deepEqual([...outcomes.keys()], ["s1\0a", "s2\0b"])
+
+  // Exactly at the bound: no eviction yet.
+  insertBoundedTerminalOutcome(outcomes, "s3\0c", outcome("TARGET_CLOSED"), limit)
+  assert.equal(outcomes.size, 3)
+  assert.equal(outcomes.get("s1\0a")?.code, "RESUME_STREAM_OMITTED")
+
+  // One past the bound: the oldest (s1) is evicted, the newest (s3) is kept.
+  insertBoundedTerminalOutcome(outcomes, "s4\0d", outcome("RESUME_SESSION_LOST"), limit)
+  assert.equal(outcomes.size, 3)
+  assert.equal(outcomes.has("s1\0a"), false, "the oldest outcome must be evicted (fail-closed to RESUME_SESSION_LOST)")
+  assert.deepEqual([...outcomes.keys()], ["s2\0b", "s3\0c", "s4\0d"])
+  assert.equal(outcomes.get("s4\0d")?.code, "RESUME_SESSION_LOST", "the newest causal code must be retained")
+
+  // Further churn keeps the bound and evicts the next-oldest, deterministically.
+  insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("GATEWAY_MAINTENANCE"), limit)
+  assert.equal(outcomes.size, 3)
+  assert.deepEqual([...outcomes.keys()], ["s3\0c", "s4\0d", "s5\0e"])
+  assert.equal(outcomes.has("s2\0b"), false)
+
+  // Re-inserting a retained key updates it in place without disturbing the bound.
+  insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("BUFFER_LIMIT"), limit)
+  assert.equal(outcomes.size, 3)
+  assert.equal(outcomes.get("s5\0e")?.code, "BUFFER_LIMIT")
+  assert.deepEqual([...outcomes.keys()], ["s3\0c", "s4\0d", "s5\0e"])
+})