socketduct 0.1.18 → 0.1.20

package/docs/reverse-gateway.md

@@ -125,8 +125,10 @@ in-memory gateway registry across independent cluster workers.
 
 Gateway registration reconnects with bounded exponential delay and a higher
 generation. An established Docker stream survives a transient physical loss
-when the hub process and its retained state, live client object, outbound gateway process, and
+when the hub process and its retained state, outbound gateway process, and
 original target socket remain available through the configured resume window.
+The original client object may reconnect in place, or a replacement reverse
+client process may reconstruct a new `VirtualSocket` from durable spool state.
 Socketduct keeps
 the app-facing socket open, durably spools each direction's unacknowledged raw
 chunks before sending them, reconciles the two receiver-committed ACK positions,
@@ -145,14 +147,39 @@ mismatches, invalid manifests, spool/buffer limits, and authorization failures
 fail closed.
 
 Reverse replay state is bounded per stream and connection and stored in private
-temporary spool directories. ACKed chunks are truncated, and terminal
-close/reset removes the spool. `status().spoolBytes` reports retained durable
-payload. `registerRecoveredConnection()` remains unsupported for reverse mode:
-a process replacement cannot inherit the live target socket or the prior
-`VirtualSocket`. If either endpoint process disappears, the target socket is
-lost, or the hub resume window expires, the logical stream fails once with the
-causal session-loss/reset code and the application must reconcile at its own
-protocol layer.
+spool directories. ACKed chunks are truncated, and terminal close/reset removes
+the spool. `status().spoolBytes` reports retained durable payload. Reverse-client
+replacement requires the same explicit `connectionId`, an explicit persistent
+`spoolDirectory`, and the same stream identifier, name, target, and one original
+selector (`gatewayId` or `routeClass`). Register every stream with
+`registerRecoveredConnection({...options, recover: true})` before `connect()`;
+registration synchronously rejects missing, expired, corrupt, wrong-owner,
+mismatched, noncontiguous, or oversized state before any network attempt. The
+stored generation is advanced and persisted before AUTH, recovered outbound
+replay starts above the gateway high-water position, and inbound delivery starts
+at the durable receive ACK because unread bytes in the dead `VirtualSocket` no
+longer exist. Receive ACKs advance only after the application consumes bytes,
+not when `VirtualSocket` merely accepts them into its readable buffer. Recovery
+uses the committed recovery record to discard an uncommitted chunk tail and
+repair derivable usage accounting after an abrupt process loss; structural,
+identity, sequence, quota, and non-tail corruption still fail closed. Recovery
+never sends `OPEN`.
+
+The default reverse spool is under `/tmp`, and the sample reverse-gateway
+Compose mounts `/tmp` as tmpfs. Those defaults do not survive a container or
+host replacement. A caller claiming process/container recovery must supply a
+private persistent directory; Socketduct maintains `0700` directories and
+`0600` files and never writes hub credentials or session tokens there.
+
+This boundary does not reconstruct a hub after hub process loss: the current
+manifests have no durable hub epoch, hub-minted bridge identity, endpoint-pairing
+journal, or split-brain fence. It also does not transfer gateway worker file
+descriptors, recover an outbound gateway process, reopen a lost target socket,
+or replay a Docker request after gateway/container/host loss. A newly constructed
+gateway owns no inherited targets; if the hub reports retained bridges, it sends
+an empty resume manifest so omitted bridges reset once, without calling the
+target factory or emitting `OPEN`. Loss outside the supported boundary fails the
+logical stream and leaves higher-level reconciliation to the application.
 
 Target bytes already observed by the gateway are ordered before a subsequent
 target-error reset. Stream `END` remains a directional half-close, while protocol
@@ -171,6 +198,9 @@ SOCKETDUCT_TLS_KEY_FILE=/certs/hub.key \
 SOCKETDUCT_AUTH_TOKENS='server-a-starlink:<secret>,server-b-starlink:<secret>,tensorbuzz:<secret>' \
 SOCKETDUCT_REVERSE_GATEWAY_BINDINGS='server-a-starlink:server-a-starlink,server-b-starlink:server-b-starlink' \
 SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES='tensorbuzz:starlink:server-a-starlink:docker-a:2375,tensorbuzz:starlink:server-b-starlink:docker-b:2375' \
+SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct \
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY='<unpadded-base64url-secret>' \
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH='2026-09' \
 node src/index.js
 ```
 
@@ -182,6 +212,37 @@ Route-class rows use `username:routeClass:gatewayId:host:port`. If two rows make
 different gateways eligible for the same authenticated class and target, that
 `OPEN` is rejected as ambiguous rather than choosing one implicitly.
 
+When hub logging is enabled, the fingerprint key is mandatory, hub-only, at
+least 32 random bytes encoded as canonical unpadded base64url, and never transmitted or
+logged. Rotate it at least every 30 days. The public epoch label identifies the
+key generation used for a 128-bit role-separated HMAC correlation value.
+
+## Disconnect attribution
+
+Every reverse physical loss has one 128-bit random `disconnectIncidentId` and
+one first local `disconnectReason`. The initial socket error, EOF, peer GOAWAY,
+protocol violation, output limit, replacement, shutdown, or send-after-loss
+cause wins over later close callbacks. The incident records its originating
+component, physical client/gateway role, explicitly named connection
+generations, and fan-out/resume/terminal stream counts. A public RESET code such
+as `RESUME_WINDOW_EXPIRED` classifies the stream outcome; it does not replace
+the physical cause.
+
+The hub propagates its validated incident in RESET/GOAWAY controls and typed
+`SocketductStreamError` / `SocketductSessionLostError` instances. Direct client
+or gateway loss creates and caches an equivalent local incident so concurrent
+stream errors share it, including writes racing the close callback. A new
+authenticated physical clears that cache. Peer-provided reserved attribution
+fields are stripped; peers cannot claim hub origin, inject correlation values,
+or alter named generations.
+
+Terminal, non-resumable hub paths assign the incident before removing their
+bridges, including protocol violations, output overflow, replacement, peer
+GOAWAY, and shutdown. A safe peer GOAWAY code survives as terminal
+classification while the first hub-observed `peer_goaway` cause and hub-created
+incident identity remain authoritative; fatal client and gateway connection
+errors retain that validated attribution.
+
 ## One outbound member per target and route class
 
 Run this once in each target server's route-pinned network namespace, changing
@@ -238,6 +299,11 @@ Callers cannot override either selection per open. Reverse streams remain
 sticky to their selected gateway/target but resume transparently after a
 transient physical transport replacement.
 
+For process replacement, call `recoverConnection()` before `start()` with
+exactly the socket's immutable original selector: `gatewayId` for an exact set
+or `routeClass` for a route-class set. Recovery derives the original member
+identity and spool namespace and never falls back to or probes a sibling.
+
 The socket is returned immediately and waits inside Socketduct until the set
 reaches minimum readiness. New sockets rotate equally across ready members and
 stay on their assigned member. If all members are reconnecting, new sockets wait

package/docs/running.md

@@ -58,16 +58,18 @@ roles and always uses verified TLS plus adaptive zstd. See
 [Native reverse gateway](reverse-gateway.md) for the environment contract and
 three-member TensorBuzz API.
 
-## Persistent JSONL logs
-
-Set `SOCKETDUCT_LOG_DIRECTORY` to opt into bounded, per-process JSONL files. A
-Docker deployment should bind mount persistent host storage at that directory.
-`SOCKETDUCT_LOG_MAX_FILE_BYTES` defaults to 10 MiB and
-`SOCKETDUCT_LOG_MAX_FILES` defaults to five total files per process/role family.
-Existing stdout/stderr output is preserved. See
-[Persistent structured logging](logging.md) for the mount example, embedded
-client `logger` option, rotation layout, event list, and strict redaction
-contract.
+## Durable compressed diagnostic logs
+
+Set `SOCKETDUCT_LOG_DIRECTORY` to opt into private, bounded `.jsonl.zst`
+segments and checksummed sidecar indexes. A dedicated worker writes level-19
+checksummed frames; orderly shutdown awaits data and index sync. Defaults are
+1 MiB frames, 128 MiB segments, 30 days/4 GiB retention, and a 64 MiB queue
+with an 8 MiB critical reserve. A logging reverse hub must also configure its
+hub-only connection-fingerprint key and public key epoch. Existing stdout/stderr
+output is preserved. Use `socketduct logs tail` or `socketduct logs search`, not
+`tail -f` on compressed bytes. See [durable compressed diagnostic
+logs](logging.md) for all settings, lifecycle semantics, CLI exits, embedded
+API, and the strict privacy contract.
 
 ## Minimal programmatic relay/edge shape
 
@@ -107,7 +109,8 @@ Do not hard-code real passwords or token values. Feed credentials through a secr
 
 ## MVP limitations
 
-- No stable CLI flags yet.
+- The stable CLI surface currently covers owned compressed-log tail/search;
+  tunnel configuration remains environment/programmatic.
 - Relay targets are requested per session and must be explicitly authorized by the injected target policy.
 - User/session stores are in-memory in the current MVP skeleton.
 - Spool files are temporary local files and may contain raw application payload.
@@ -210,6 +213,6 @@ inspect its ordered aggregate causes or privacy-safe per-member status codes.
 No extra physical member is created. Configure the set-wide buffer/spool/queue
 limits for the whole process rather than multiplying a desired budget by
 gateway count.
-For process replacement, call `recoverConnection()` with each stream's original
-gateway ID before `start()`; see the exact sequence in
+For process replacement, call `recoverConnection()` with exactly each stream's
+original gateway ID or reverse route class before `start()`; see the sequence in
 [Node-compatible socket API design](socket-api.md#multiplexedsocketducttransportset-multi-gateway-v3-api).

package/docs/security.md

@@ -100,7 +100,7 @@ Optional later hardening:
 
 ## Logging
 
-The optional persistent JSONL logger uses a closed event/field allowlist. It
+The optional durable compressed logger uses a closed event/field allowlist. It
 records process/role identity, lifecycle state, bounded counters, validated
 gateway IDs, and normalized error codes/classes. Unknown event names are
 dropped and unknown error codes become `UNKNOWN`.
@@ -112,8 +112,12 @@ diagnostics retain bounded error names, messages, and stacks so operational
 failures can be investigated while credential-shaped values are redacted. Each
 JSON line is capped at 1024 bytes. Logger I/O and custom-writer failures are
 isolated from network behavior and produce only one bounded stderr
-classification. See [Persistent structured logging](logging.md) for
-configuration and rotation.
+classification. Managed files are private checksummed zstd frames with a
+checksummed structural index and no plaintext fallback. Reverse-hub connection
+correlation uses only a hub-held, role-separated HMAC truncated to 128 bits;
+raw connection IDs, the key, unkeyed digests, targets, and payloads are never
+persisted. See [durable compressed diagnostic logs](logging.md) for
+configuration, key rotation, recovery, and retention.
 
 V3 status is payload-free and credential-free: physical counts/generation,
 virtual stream state counts, active local targets, bounded queued/spool bytes,
@@ -176,8 +180,15 @@ only above it. This preserves exact-once delivery without reopening or
 reissuing a privileged Docker request. Ownership mismatches, missing targets,
 invalid or incomplete manifests, resource-bound failures, and expired resume
 windows fail the affected logical stream once instead of falling back to a new
-stream. Process replacement remains terminal because the live app and target
-sockets cannot be inherited safely.
+stream. Reverse-client process replacement is allowed only from caller-selected
+private persistent storage with the same stable connection/stream identities
+and exactly one original gateway or route-class selector. Recovery validates
+ownership, age, identity, lifecycle, contiguous chunks, and bounds before
+network activity; spool files contain no bearer credential or session token.
+The same in-memory hub bridge, gateway process, and live target socket must
+survive. Hub reconstruction, gateway FD transfer, and target reopen/retry remain
+unsupported, and a replacement gateway resets retained bridges with an empty
+manifest rather than recreating a privileged operation.
 
 ## Network exposure
 

package/docs/session-lifecycle.md

@@ -27,9 +27,20 @@ without opening a second target or retrying an application operation.
 
 If the original target socket disappears, an owner/identifier or sequence does
 not match, a buffer/spool bound is exceeded, or the resume window expires, that
-logical stream fails once with the causal error and releases both sides. Reverse
-process-replacement recovery remains unsupported because the live target and
-app-facing socket cannot be transferred to replacement JavaScript objects.
+logical stream fails once with the causal error and releases both sides. A dead
+reverse-client process may be replaced: the new object creates a new
+`VirtualSocket`, restores the durable generation/lifecycle and replay state, and
+registers every stream before connecting. The same hub bridge, outbound gateway
+process, and original target socket must still exist. The dead app-facing socket
+is not transferred; target bytes above its durable receive ACK replay to the new
+socket. That ACK covers bytes returned to the application, not bytes merely
+buffered in the dead process. An orderly `detach()` drains already-queued frame
+handling before its final durable snapshot and handoff.
+
+Hub process reconstruction, gateway process or file-descriptor transfer, and
+target reopen/retry are unsupported. A replacement gateway has no live target
+sockets and therefore completes retained-state registration with an empty
+manifest, resetting omitted bridges rather than issuing a second `OPEN`.
 
 The bounded, paginated resume manifest carries stable identifiers and both
 directional acknowledgement positions. The relay returns an independent result

package/docs/socket-api.md

@@ -219,24 +219,23 @@ the callback, which runs exactly once only after `secureConnect` or failure.
 Both methods count only completed member assignments and preserve stream
 stickiness. Every returned raw or TLS socket exposes enumerable `gatewayId` and
 `routeClass` allocation metadata. Only the configured identity is set. Persist
-an exact set's immutable `gatewayId` after connection so a replacement can
-recover the stream on its original member. Reverse route-class streams are not
-recoverable across process replacement, but they do recover transparently from
-a transient physical transport loss while the original objects and target
-socket remain alive.
+an exact set's immutable original selector after connection: `gatewayId` for a
+gateway member or `routeClass` for a reverse member. A replacement uses that
+selector to recover the stream on its original member without running selection
+again.
 
 Process-replacement recovery is deliberately separate from ordinary selection.
 First detach the old set when an orderly handoff is possible. Construct the
-replacement with the same base `connectionId`, spool directory, gateway IDs and
-pinned endpoints. Then register each durable stream with its original
-`gatewayId` before calling `start()`:
+replacement with the same base `connectionId`, spool directory, and configured
+member endpoints. Then register each durable stream with exactly its original
+`gatewayId` or `routeClass` before calling `start()`:
 
 ```js
 await set.detach()
 
 const replacement = new MultiplexedSocketductTransportSet(sameSetOptions)
 const recovered = replacement.recoverConnection({
-  gatewayId: durableRecord.gatewayId, // captured from the original socket
+  routeClass: durableRecord.routeClass, // exact sets use gatewayId instead
   host: "api.internal",
   port: 443,
   identifier: "build_stream_01",
@@ -245,10 +244,11 @@ const recovered = replacement.recoverConnection({
 await replacement.start()
 ```
 
-`recoverConnection()` implies durable recovery and rejects a missing or unknown
-gateway ID, an explicit `recover` option, or registration after `start()` has
-begun. It bypasses round-robin only to reach that configured member; it never
-migrates or replays the stream on a sibling. Ordinary `createConnection()` and
+`recoverConnection()` implies durable recovery and rejects a missing,
+ambiguous, invalid, or unknown original selector, an explicit `recover` option,
+or registration after `start()` has begun. It bypasses selection only to reach
+that configured member; it never migrates or replays the stream on a sibling.
+Ordinary `createConnection()` and
 `createTlsConnection()` reject `recover: true`, `gatewayId`, and `routeClass`,
 so new opens cannot force a path. `detach()` coalesces with concurrent shutdown calls,
 preserves active member spools, and retires empty warmed lanes; `close()` remains
@@ -401,13 +401,47 @@ Target `ca`, `cert`, and `key` accept Node TLS certificate material. `cert` and
 It selects exactly one registered gateway during `connect()`. The existing
 `MultiplexedSocketductTransportSet` accepts `endpoint.reverseHub`, allowing
 three ready members to retain deterministic health-aware round-robin behavior.
-Reverse established operations deliberately do not support
-`registerRecoveredConnection()` across process replacement. They do durably
-spool unacknowledged send chunks during the lifetime of the client and gateway
-objects, then use paired v3 resume manifests to survive physical transport
-replacement without reopening the target or replaying an application request
-as a new logical stream. Target loss, resume expiry, identity mismatch, or a
-configured bound remains terminal and requires application reconciliation.
+An established reverse stream can be cold-registered in a replacement client
+process before its first physical connection:
+
+```js
+const replacement = new ReverseGatewayConnection({
+  routeClass: durableRecord.routeClass,
+  connectionId: durableRecord.connectionId,
+  spoolDirectory: "/srv/socketduct/recovery",
+  hub,
+  tls
+})
+const socket = replacement.registerRecoveredConnection({
+  recover: true,
+  host: durableRecord.host,
+  port: durableRecord.port,
+  identifier: durableRecord.identifier,
+  sessionName: durableRecord.sessionName
+})
+await replacement.connect()
+```
+
+Recovery restores the durable stream lifecycle, sequences, acknowledgements,
+and generation. It never emits a new `OPEN` or recreates the target; target data
+above the durable receive acknowledgement is replayed by the surviving gateway.
+Reverse receive ACKs cover bytes returned to the application, not unread bytes
+held only in the old process. `detach()` resolves only after queued physical
+frame handling is quiescent and the resulting recovery state is durable, so a
+replacement cannot race a late write from the retired object.
+The caller must supply stable `connectionId` and private persistent
+`spoolDirectory` values. The default `/tmp` spool and the sample gateway
+Compose tmpfs do not survive container or host replacement. Spool directories
+remain mode 0700, files remain mode 0600, and credentials or session tokens are
+not persisted.
+
+This boundary requires the same hub bridge, reverse-gateway process, and target
+TCP socket to survive. It does not reconstruct a restarted hub, keep or transfer
+gateway sockets between processes, reopen a lost target, or replay an ambiguous
+target request after gateway, container, or host loss. If a newly constructed
+outbound gateway finds retained hub bridges but owns no live target sockets, it
+sends an empty resume manifest so the hub resets those omitted streams instead
+of creating targets.
 
 Reverse virtual sockets accept individual writes larger than their configured
 retained-byte limit. The connection progresses those writes in slices bounded by

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "socketduct",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",
+  "bin": {
+    "socketduct": "./src/cli/socketduct.js"
+  },
   "exports": {
     ".": "./src/index.js",
     "./http": "./src/client/http-agent.js",
@@ -21,6 +24,7 @@
     "release:patch": "npm run check && release-patch",
     "start": "node src/index.js",
     "test": "node scripts/test.js",
+    "verify:zstd-logs": "node scripts/verify-zstd-interoperability.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0"
   },

package/scripts/verify-zstd-interoperability.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict"
+import {execFile} from "node:child_process"
+import {mkdtemp, readdir, rm} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {promisify} from "node:util"
+
+import {readCompressedLogDirectory} from "../src/logging/compressed-log-reader.js"
+import {createCompressedJsonlFileLogger} from "../src/logging/compressed-log-writer.js"
+
+const run = promisify(execFile)
+const root = await mkdtemp(join(tmpdir(), "socketduct-zstd-reference-"))
+const directory = join(root, "logs")
+
+try {
+  let tick = 0
+  const logger = createCompressedJsonlFileLogger({
+    directory,
+    role: "reverse-hub",
+    now: () => new Date(1_795_000_000_000 + tick++),
+    frameMaxBytes: 256,
+    maxSegmentBytes: 1024 * 1024
+  })
+  logger.log("process.started", {runtimeMode: "reverse-hub"})
+  for (let value = 1; value <= 4; value += 1) logger.log("runtime.status", {virtualStreams: value})
+  await logger.close()
+
+  const segmentNames = (await readdir(directory)).filter((name) => name.endsWith(".jsonl.zst"))
+  assert.equal(segmentNames.length, 1)
+  const segment = join(directory, /** @type {string} */ (segmentNames[0]))
+  const owned = await readCompressedLogDirectory(directory)
+  assert.equal(owned.incomplete, false)
+  const expected = Buffer.from(owned.records.map((record) => `${JSON.stringify(record)}\n`).join(""))
+
+  const decoded = await run("zstdcat", [segment], {encoding: "buffer", maxBuffer: 4 * 1024 * 1024})
+  assert.deepEqual(Buffer.from(decoded.stdout), expected)
+  const searched = await run("zstdgrep", ["-c", '"event":"runtime.status"', segment], {encoding: "utf8"})
+  assert.equal(searched.stdout.trim(), "4")
+} finally {
+  await rm(root, {recursive: true, force: true})
+}

package/src/cli/socketduct.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/no-undefined-types, jsdoc/require-param-type, jsdoc/require-returns */
+import {once} from "node:events"
+
+import {CompressedLogTailReader, readCompressedLogDirectory} from "../logging/compressed-log-reader.js"
+
+const FILTER_OPTIONS = new Map([
+  ["--event", "event"],
+  ["--incident", "incident"],
+  ["--gateway", "gateway"],
+  ["--route-class", "routeClass"],
+  ["--client-generation", "clientGeneration"],
+  ["--gateway-generation", "gatewayGeneration"],
+  ["--reason", "reason"],
+  ["--since", "since"],
+  ["--until", "until"]
+])
+
+/** @typedef {{kind: 'search' | 'tail', directory: string, filters: Record<string, unknown>, follow: boolean, pollMs: number}} LogCommand */
+
+/**
+ *
+ * @param argv
+ * @param streams
+ */
+export async function runSocketductCli(/** @type {string[]} */ argv, /** @type {{stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream}} */ streams = {}) {
+  const stdout = streams.stdout ?? process.stdout
+  const stderr = streams.stderr ?? process.stderr
+  try {
+    const command = parseArguments(argv)
+    if (command.kind === "search") {
+      const result = await readCompressedLogDirectory(command.directory, {filters: command.filters})
+      if (result.incomplete) {
+        await writeOutput(stderr, `Socketduct log evidence error (${result.errors[0]?.code ?? "LOG_EVIDENCE_INVALID"})\n`)
+        return 2
+      }
+      for (const record of result.records) await writeOutput(stdout, `${JSON.stringify(record)}\n`)
+      return result.records.length > 0 ? 0 : 1
+    }
+    const reader = new CompressedLogTailReader(command.directory, {filters: command.filters})
+    let stopping = false
+    const stop = () => { stopping = true }
+    if (command.follow) {
+      process.once("SIGINT", stop)
+      process.once("SIGTERM", stop)
+    }
+    try {
+      do {
+        const result = await reader.poll()
+        if (result.incomplete) {
+          await writeOutput(stderr, `Socketduct log evidence error (${result.errors[0]?.code ?? "LOG_EVIDENCE_INVALID"})\n`)
+          return 2
+        }
+        for (const record of result.records) {
+          await writeOutput(stdout, `${JSON.stringify(record)}\n`)
+        }
+        if (command.follow && !stopping) await waitForPoll(command.pollMs)
+      } while (command.follow && !stopping)
+      return 0
+    } finally {
+      if (command.follow) {
+        process.off("SIGINT", stop)
+        process.off("SIGTERM", stop)
+      }
+    }
+  } catch {
+    await writeOutput(stderr, "Socketduct logs error (INVALID_ARGUMENT_OR_IO)\n")
+    return 2
+  }
+}
+
+/** @param {string[]} argv - CLI arguments. @returns {LogCommand} */
+function parseArguments(argv) {
+  if (argv[0] !== "logs" || (argv[1] !== "search" && argv[1] !== "tail")) throw new Error("Expected logs search or logs tail")
+  const kind = argv[1]
+  let directory
+  let follow = false
+  let pollMs = 250
+  /** @type {Record<string, unknown>} */
+  const filters = {}
+  for (let index = 2; index < argv.length; index += 1) {
+    const option = argv[index]
+    if (option === undefined) throw new Error("Missing option")
+    if (option === "--follow" && kind === "tail") { follow = true; continue }
+    const value = argv[++index]
+    if (value === undefined || value.length === 0) throw new Error("Missing option value")
+    if (option === "--directory") { directory = value; continue }
+    if (option === "--poll-ms" && kind === "tail") {
+      pollMs = positiveInteger(value, "poll interval")
+      if (pollMs > 60_000) throw new Error("Poll interval exceeds 60000 milliseconds")
+      continue
+    }
+    const filter = FILTER_OPTIONS.get(option)
+    if (filter === undefined) throw new Error("Unknown logs option")
+    filters[filter] = validateFilter(filter, value)
+  }
+  if (directory === undefined) throw new Error("Log directory is required")
+  return {kind, directory, filters, follow, pollMs}
+}
+
+/**
+ * @param {string} filter - Internal filter name. @param {string} value - User input. @returns {string | number}
+ * @param value
+ */
+function validateFilter(filter, value) {
+  if (filter === "clientGeneration" || filter === "gatewayGeneration") return positiveInteger(value, "connection generation", true)
+  if (filter === "since" || filter === "until") {
+    const timestamp = Date.parse(value)
+    if (!Number.isSafeInteger(timestamp)) throw new Error("Invalid time filter")
+    return timestamp
+  }
+  if (filter === "incident" && !/^[A-Za-z0-9_-]{22}$/.test(value)) throw new Error("Invalid incident filter")
+  if ((filter === "gateway" || filter === "routeClass") && !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) throw new Error("Invalid route filter")
+  if ((filter === "event" || filter === "reason") && !/^[a-zA-Z][a-zA-Z0-9_.-]{0,95}$/.test(value)) throw new Error("Invalid diagnostic filter")
+  return value
+}
+
+/**
+ * @param {string} value - User input. @param {string} name - Setting name. @param {boolean} [allowZero] - Whether zero is valid.
+ * @param name
+ * @param allowZero
+ */
+function positiveInteger(value, name, allowZero = false) {
+  if (!/^(?:0|[1-9][0-9]*)$/.test(value)) throw new Error(`Invalid ${name}`)
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || (allowZero ? parsed < 0 : parsed < 1)) throw new Error(`Invalid ${name}`)
+  return parsed
+}
+
+/**
+ * @param {NodeJS.WriteStream} stream - Output stream. @param {string} text - Text to write.
+ * @param text
+ */
+async function writeOutput(stream, text) {
+  if (!stream.write(text)) await once(stream, "drain")
+}
+
+/** @param {number} milliseconds - Poll interval. */
+async function waitForPoll(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exitCode = await runSocketductCli(process.argv.slice(2))

package/src/client/multiplexed-transport-set.js

@@ -399,20 +399,27 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
   }
 
   /**
-   * Registers a durable stream on its original gateway before any member starts.
-   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & {gatewayId: string}} options - Original gateway and recovery identity.
+   * Registers a durable stream on its one original member before any member starts.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & ({gatewayId: string, routeClass?: never} | {routeClass: string, gatewayId?: never})} options - Original gateway or route-class recovery identity.
    * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
    * @returns {GatewayVirtualSocket} Original member-owned virtual socket with stable gateway metadata.
    */
   recoverConnection(options, callback) {
     if (this.#closed) throw closedError()
     if (this.#started) throw new Error("Recovered streams must be registered before start()")
-    if (typeof options !== "object" || options === null || typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId)) throw new TypeError("recoverConnection requires a valid configured gatewayId")
+    if (typeof options !== "object" || options === null) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
+    const hasGatewayId = Object.hasOwn(options, "gatewayId")
+    const hasRouteClass = Object.hasOwn(options, "routeClass")
+    if (hasGatewayId === hasRouteClass) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
+    if (hasGatewayId && (typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId))) throw new TypeError("recoverConnection requires a valid configured gatewayId")
+    if (hasRouteClass && (typeof options.routeClass !== "string" || !ROUTE_CLASS.test(options.routeClass))) throw new TypeError("recoverConnection requires a valid configured routeClass")
     if (Object.hasOwn(options, "recover")) throw new TypeError("recoverConnection owns the recover option")
-    const member = this.#members.find((candidate) => candidate.gatewayId === options.gatewayId)
-    if (member === undefined) throw new Error(`Unknown gatewayId: ${options.gatewayId}`)
+    const selector = hasGatewayId ? options.gatewayId : options.routeClass
+    const member = this.#members.find((candidate) => hasGatewayId ? candidate.gatewayId === selector : candidate.routeClass === selector)
+    if (member === undefined) throw new Error(`Unknown ${hasGatewayId ? "gatewayId" : "routeClass"}: ${selector}`)
     const virtualOptions = {...options}
     delete /** @type {{gatewayId?: string}} */ (virtualOptions).gatewayId
+    delete /** @type {{routeClass?: string}} */ (virtualOptions).routeClass
     const allocation = memberAllocation(member)
     /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
     const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeAllocation(socket, allocation))