@cortexkit/subc-client 0.2.1 → 0.3.1

package/dist/socket.d.ts

@@ -0,0 +1,45 @@
+export declare class SocketClosedError extends Error {
+}
+export declare class SocketTimeoutError extends Error {
+}
+export declare class SocketWriteNotQueuedError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class SocketWriteQueuedError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export interface SocketWriteResult {
+    /** True once bytes were handed to Node's net.Socket.write. This is not a delivery guarantee. */
+    queued: boolean;
+    /** Resolves when Node reports the write complete; rejects with a classified write error. */
+    completed: Promise<void>;
+}
+export declare class SubcSocket {
+    private readonly sock;
+    private chunks;
+    private buffered;
+    private waiter;
+    private closedErr;
+    /** Bytes currently buffered but not yet consumed by a reader. A timeout
+     * arbitration uses this to tell "a reply already arrived, keep draining" from
+     * "nothing is here, settle the timeout". */
+    bufferedBytes(): number;
+    private constructor();
+    /**
+     * The OS-assigned local TCP port of this connection, or null if not yet
+     * connected/closed. Used to correlate a client-side timeout with a specific
+     * socket in a packet capture when diagnosing reply-delivery issues.
+     */
+    localPort(): number | null;
+    static connect(host: string, port: number, deadlineMs: number): Promise<SubcSocket>;
+    /** Read exactly `n` bytes, rejecting if `deadlineMs` (epoch ms) passes first. */
+    readExact(n: number, deadlineMs: number): Promise<Uint8Array>;
+    write(bytes: Uint8Array, deadlineMs: number): Promise<void>;
+    writeTracked(bytes: Uint8Array, deadlineMs: number): SocketWriteResult;
+    close(): void;
+    private tryServe;
+    private take;
+}
+//# sourceMappingURL=socket.d.ts.map

package/dist/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAQA,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD,qBAAa,yBAA0B,SAAQ,KAAK;IAGhD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK;gBADtB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,KAAK,YAAA;CAIzB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK;gBADtB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,KAAK,YAAA;CAIzB;AAED,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,MAAM,EAAE,OAAO,CAAC;IAChB,4FAA4F;IAC5F,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AASD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAsB;IAEvC;;gDAE4C;IAC5C,aAAa,IAAI,MAAM;IAIvB,OAAO;IAgBP;;;;OAIG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBnF,iFAAiF;IACjF,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAyBvD,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjE,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB;IA4EtE,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,IAAI;CAmBb"}

package/dist/socket.js

@@ -0,0 +1,208 @@
+// A pull-based buffered wrapper over a node TCP socket. Node sockets are
+// event-driven; the handshake and frame loop want "give me exactly N bytes, but
+// don't exceed this absolute deadline". readExact provides that, draining an
+// internal buffer and parking a single waiter until enough bytes arrive, the
+// deadline passes, or the socket ends.
+import net from "node:net";
+export class SocketClosedError extends Error {
+}
+export class SocketTimeoutError extends Error {
+}
+export class SocketWriteNotQueuedError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+export class SocketWriteQueuedError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+export class SubcSocket {
+    sock;
+    chunks = [];
+    buffered = 0;
+    waiter = null;
+    closedErr = null;
+    /** Bytes currently buffered but not yet consumed by a reader. A timeout
+     * arbitration uses this to tell "a reply already arrived, keep draining" from
+     * "nothing is here, settle the timeout". */
+    bufferedBytes() {
+        return this.buffered;
+    }
+    constructor(sock) {
+        this.sock = sock;
+        sock.on("data", (chunk) => {
+            this.chunks.push(chunk);
+            this.buffered += chunk.length;
+            this.tryServe();
+        });
+        const fail = (err) => {
+            if (!this.closedErr)
+                this.closedErr = err;
+            this.tryServe();
+        };
+        sock.on("error", (err) => fail(err instanceof Error ? err : new Error(String(err))));
+        sock.on("end", () => fail(new SocketClosedError("subc closed the connection")));
+        sock.on("close", () => fail(new SocketClosedError("subc connection closed")));
+    }
+    /**
+     * The OS-assigned local TCP port of this connection, or null if not yet
+     * connected/closed. Used to correlate a client-side timeout with a specific
+     * socket in a packet capture when diagnosing reply-delivery issues.
+     */
+    localPort() {
+        return this.sock.localPort ?? null;
+    }
+    static connect(host, port, deadlineMs) {
+        return new Promise((resolve, reject) => {
+            const sock = net.connect({ host, port });
+            sock.setNoDelay(true);
+            const timer = setTimeout(() => {
+                sock.destroy();
+                reject(new SocketTimeoutError(`timed out connecting to ${host}:${port}`));
+            }, Math.max(0, deadlineMs - Date.now()));
+            sock.once("connect", () => {
+                clearTimeout(timer);
+                resolve(new SubcSocket(sock));
+            });
+            sock.once("error", (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    /** Read exactly `n` bytes, rejecting if `deadlineMs` (epoch ms) passes first. */
+    readExact(n, deadlineMs) {
+        if (this.waiter) {
+            return Promise.reject(new Error("concurrent readExact is not supported"));
+        }
+        if (n === 0)
+            return Promise.resolve(new Uint8Array(0));
+        return new Promise((resolve, reject) => {
+            // A non-finite deadline means "wait indefinitely" (the background frame
+            // loop relies on this; per-request timeouts live on the request waiters).
+            let timer = null;
+            if (Number.isFinite(deadlineMs)) {
+                const remaining = deadlineMs - Date.now();
+                if (remaining <= 0) {
+                    reject(new SocketTimeoutError(`timed out waiting for ${n} bytes`));
+                    return;
+                }
+                timer = setTimeout(() => {
+                    this.waiter = null;
+                    reject(new SocketTimeoutError(`timed out waiting for ${n} bytes`));
+                }, remaining);
+            }
+            this.waiter = { need: n, resolve, reject, timer };
+            this.tryServe();
+        });
+    }
+    async write(bytes, deadlineMs) {
+        try {
+            await this.writeTracked(bytes, deadlineMs).completed;
+        }
+        catch (err) {
+            if (err instanceof SocketWriteNotQueuedError || err instanceof SocketWriteQueuedError) {
+                throw err.cause ?? err;
+            }
+            throw err;
+        }
+    }
+    writeTracked(bytes, deadlineMs) {
+        if (this.closedErr) {
+            return {
+                queued: false,
+                completed: Promise.reject(new SocketWriteNotQueuedError("subc socket was closed before bytes could be queued", this.closedErr)),
+            };
+        }
+        let queued = false;
+        let settled = false;
+        let timer = null;
+        const completed = new Promise((resolve, reject) => {
+            const settle = (run) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                run();
+            };
+            const remaining = deadlineMs - Date.now();
+            if (remaining <= 0) {
+                settle(() => reject(new SocketWriteNotQueuedError("timed out before bytes could be queued to subc", new SocketTimeoutError("timed out writing to subc"))));
+                return;
+            }
+            timer = setTimeout(() => {
+                const timeout = new SocketTimeoutError("timed out writing to subc");
+                settle(() => reject(queued
+                    ? new SocketWriteQueuedError("timed out after bytes were handed to the subc socket", timeout)
+                    : new SocketWriteNotQueuedError("timed out before bytes could be queued to subc", timeout)));
+            }, remaining);
+            try {
+                this.sock.write(Buffer.from(bytes), (err) => {
+                    settle(() => {
+                        if (err) {
+                            reject(new SocketWriteQueuedError("subc socket reported a write error after bytes were handed to the socket", err instanceof Error ? err : new Error(String(err))));
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                });
+                queued = true;
+            }
+            catch (err) {
+                settle(() => reject(new SocketWriteNotQueuedError("subc socket write threw before bytes could be queued", err instanceof Error ? err : new Error(String(err)))));
+            }
+        });
+        return { queued, completed };
+    }
+    close() {
+        this.sock.destroy();
+    }
+    tryServe() {
+        const w = this.waiter;
+        if (!w)
+            return;
+        if (this.buffered >= w.need) {
+            const out = this.take(w.need);
+            this.waiter = null;
+            if (w.timer)
+                clearTimeout(w.timer);
+            w.resolve(out);
+            return;
+        }
+        if (this.closedErr) {
+            this.waiter = null;
+            if (w.timer)
+                clearTimeout(w.timer);
+            w.reject(this.closedErr);
+        }
+    }
+    take(n) {
+        const out = Buffer.allocUnsafe(n);
+        let off = 0;
+        while (off < n) {
+            const head = this.chunks[0];
+            const want = n - off;
+            if (head.length <= want) {
+                head.copy(out, off);
+                off += head.length;
+                this.chunks.shift();
+            }
+            else {
+                head.copy(out, off, 0, want);
+                this.chunks[0] = head.subarray(want);
+                off += want;
+            }
+        }
+        this.buffered -= n;
+        return out;
+    }
+}
+//# sourceMappingURL=socket.js.map

package/dist/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@cortexkit/subc-client",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "TypeScript client for the subc daemon. Wire-compatible (byte-for-byte) with the Rust subc-transport handshake and subc-protocol envelope.",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
+    "dist",
     "src",
     "README.md"
   ],
   "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
     "test": "bun test",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit"
   },

package/src/client.ts

@@ -10,6 +10,7 @@
 // correlation id, not arrival order.
 
 import { promises as fs } from "node:fs";
+import { debuglog } from "node:util";
 
 import { AuthError, authenticateClient } from "./auth.js";
 import { ConnectionFileError, readConnectionFile, type ConnectionInfo } from "./connection-file.js";
@@ -31,8 +32,38 @@ import {
   SubcSocket,
 } from "./socket.js";
 
+const debug = debuglog("subc-client");
+
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+// When a request-timeout timer fires, its reply may already be sitting in the
+// socket read buffer, unprocessed only because the event loop was starved (Node
+// runs the TIMERS phase before the POLL phase, so an expired timer can beat an
+// already-arrived frame). Rather than settle as a timeout immediately, arbitrate:
+// yield one check-phase turn (setImmediate) so a fully-buffered reply dispatches
+// and wins, and — only while the reader is actively draining the same socket —
+// allow a small hard-capped grace for a reply whose header/body spans more than
+// one loop turn. This is a demux tiebreak for a reply that RACED the deadline,
+// NOT a deadline extension: an absent reply still settles right after the check
+// phase. Capped so it can never approach BODY_READ_TIMEOUT_MS.
+const TIMEOUT_ARBITRATION_GRACE_MS = 50;
+// Internal marker set as the `code` on the SubcError a request-deadline timeout
+// rejects with, so the managed classifier can tell a deadline (reply may simply
+// not have been read in time) from an actual connection drop. Never surfaced to
+// callers directly — it is refined into DEADLINE_NO_DROP_CODE by classifyFailure.
+const REQUEST_DEADLINE_MARKER = "request_deadline";
+// The consumer-facing code for a managed call whose deadline elapsed while its
+// bytes were queued to the local socket and NO connection drop / GOODBYE was
+// observed. Distinct from "connection_dropped" so a caller can skip a
+// was-it-even-sent recovery path — but still kind=outcome_unknown (never safe to
+// retry: "queued to the local socket" is NOT proof the daemon received or ran it).
+const DEADLINE_NO_DROP_CODE = "deadline_exceeded_no_drop_observed";
+// A retryable route.open rejection (target booting / reloading / momentarily
+// absent) is retried in-place against the same connection up to this deadline
+// before it is surfaced as not_sent. Mirrors subc-client-rs
+// DEFAULT_ROUTE_RETRY_DEADLINE so a target that is briefly unavailable at daemon
+// restart recovers without a misleading terminal error.
+const ROUTE_OPEN_RETRY_DEADLINE_MS = 10_000;
 // Once a header arrives, its body must follow promptly; bound it so a truncated
 // frame cannot wedge the read loop forever.
 const BODY_READ_TIMEOUT_MS = 30_000;
@@ -194,6 +225,14 @@ export interface ConnectOptions {
   reconnectBackoff?: ReconnectBackoff;
   /** Injectable sleep for timer-free reconnect tests. */
   sleep?: (ms: number) => Promise<void>;
+  /**
+   * Hard cap on the timeout-arbitration grace window (see
+   * TIMEOUT_ARBITRATION_GRACE_MS). A reply whose bytes are actively arriving when
+   * the request deadline fires is given up to this long to finish dispatching
+   * before the call settles as a timeout. Bounded and never a deadline extension;
+   * exposed mainly so tests can prove the arbitration deterministically.
+   */
+  timeoutArbitrationGraceMs?: number;
 }
 
 interface NormalizedConnectOptions {
@@ -203,6 +242,7 @@ interface NormalizedConnectOptions {
   targetKind: ManagedRouteKind;
   reconnectBackoff: ReconnectBackoff;
   sleep: (ms: number) => Promise<void>;
+  timeoutArbitrationGraceMs: number;
 }
 
 interface OpenedConnection {
@@ -238,6 +278,11 @@ export class SubcClient {
   private closeStarted = false;
   private reconnecting: Promise<void> | null = null;
   private generation = 1;
+  // True while the read loop is actively reading/dispatching a frame off the
+  // current socket (between reading a header and finishing its dispatch). The
+  // timeout arbitration reads it to decide whether a just-fired timeout should
+  // grant a reply mid-arrival a small grace window before settling.
+  private readerActive = false;
 
   private constructor(
     private sock: SubcSocket,
@@ -319,7 +364,11 @@ export class SubcClient {
           }
           continue;
         }
-        if (err.kind === "outcome_unknown") {
+        if (err.kind === "outcome_unknown" && err.code !== DEADLINE_NO_DROP_CODE) {
+          // A real drop schedules a reconnect. A deadline-with-no-drop does NOT:
+          // the socket was never observed to fail (the reply was likely just read
+          // late under load), so tearing it down would abandon a healthy connection
+          // and its other in-flight routes for nothing.
           this.scheduleReconnectAfterDrop(err);
         }
         throw err;
@@ -521,7 +570,7 @@ export class SubcClient {
         timer: null,
       };
       pending.timer = setTimeout(() => {
-        this.rejectPending(key, pending, new SubcError(this.timeoutMessage(channel, corr, ms)));
+        this.arbitrateTimeout(key, pending, channel, corr, ms);
       }, ms);
       this.pending.set(key, pending);
       this.sock.write(encodeFrame(frame), Date.now() + ms).catch((err) => {
@@ -531,6 +580,42 @@ export class SubcClient {
     });
   }
 
+  /**
+   * A request-deadline timer has fired. Before settling as a timeout, arbitrate
+   * the timer-vs-poll race: a reply may already be in the socket buffer, unread
+   * only because the loop was starved. Yield one check phase (setImmediate) so a
+   * fully-buffered reply dispatches and wins via settle()'s identity guard; then,
+   * only while the reader is actively draining THIS socket (a frame mid-arrival),
+   * grant a single hard-capped grace before finally settling. Absent replies
+   * still settle right after the check phase. The settle carries the deadline
+   * marker so the managed classifier reports deadline-not-drop.
+   */
+  private arbitrateTimeout(key: string, pending: Pending, channel: number, corr: bigint, ms: number): void {
+    const settleAsTimeout = (): void => {
+      this.rejectPending(
+        key,
+        pending,
+        new SubcError(this.timeoutMessage(channel, corr, ms), REQUEST_DEADLINE_MARKER),
+      );
+    };
+    const graceDeadline = Date.now() + this.opts.timeoutArbitrationGraceMs;
+    const arbitrate = (): void => {
+      // Already settled (by dispatch, fail, GOODBYE, or close)? Nothing to do.
+      if (this.pending.get(key) !== pending) return;
+      // A reply is mid-arrival on this socket (or bytes are buffered), and we are
+      // still inside the grace window: give the reader another turn to finish
+      // dispatching it. The generation guard in readLoop keeps this scoped to the
+      // live socket; the grace cap keeps it from approaching the body-read timeout.
+      const readerDraining = this.readerActive || this.sock.bufferedBytes() > 0;
+      if (readerDraining && Date.now() < graceDeadline) {
+        setImmediate(arbitrate);
+        return;
+      }
+      settleAsTimeout();
+    };
+    setImmediate(arbitrate);
+  }
+
   private async managedRequest(
     routeChannel: number,
     body: unknown,
@@ -572,6 +657,18 @@ export class SubcClient {
       if (!handedToSocket) {
         return this.notSentCallError("request bytes were not queued to the subc socket", err);
       }
+      // A request-deadline timeout (arbitration expired without observing a drop)
+      // is refined from a real connection drop: the socket was NOT seen to fail, so
+      // the caller can skip a was-it-even-sent recovery path. Still outcome_unknown
+      // — queued-to-local-socket is not proof the daemon received or ran it.
+      if (err instanceof SubcError && err.code === REQUEST_DEADLINE_MARKER) {
+        return new SubcCallError(
+          "outcome_unknown",
+          `managed call deadline exceeded after request bytes were queued to the local socket; no terminal response was observed; outcome unknown${causeMessage(err)}`,
+          DEADLINE_NO_DROP_CODE,
+          err,
+        );
+      }
       return this.outcomeUnknownCallError("connection dropped before the managed call returned a response", err);
     };
 
@@ -586,7 +683,7 @@ export class SubcClient {
         classifyFailure,
       };
       pending.timer = setTimeout(() => {
-        this.rejectPending(key, pending, new SubcError(this.timeoutMessage(channel, corr, ms)));
+        this.arbitrateTimeout(key, pending, channel, corr, ms);
       }, ms);
       this.pending.set(key, pending);
 
@@ -642,6 +739,9 @@ export class SubcClient {
   }
 
   private async openCachedRoute(cached: CachedRoute): Promise<number> {
+    const routeRetryDeadline = Date.now() + ROUTE_OPEN_RETRY_DEADLINE_MS;
+    let routeRetryDelay = this.opts.reconnectBackoff.baseMs;
+    let routeRetryAttempt = 0;
     for (;;) {
       if (cached.closed) throw this.routeClosedDuringOpen();
       try {
@@ -679,6 +779,29 @@ export class SubcClient {
           }
           continue;
         }
+        // A daemon-rejected route.open with a RETRYABLE code (target booting /
+        // reloading / momentarily absent) is retried IN-PLACE against the same live
+        // connection — never a socket reconnect, which would needlessly disrupt this
+        // connection's other routes — until the route-retry deadline. Past the
+        // deadline it surfaces as not_sent: provably pre-send (no data frame ever
+        // left the client) AND still transient, so the caller's own retry policy may
+        // safely re-attempt later. Reason and set kept in parity with subc-client-rs.
+        if (!this.closeStarted && err instanceof SubcError && isRetryableRouteOpenCode(err.code)) {
+          routeRetryAttempt += 1;
+          if (routeRetryAttempt < this.opts.reconnectBackoff.maxAttempts && Date.now() < routeRetryDeadline) {
+            await this.opts.sleep(routeRetryDelay);
+            routeRetryDelay = Math.min(routeRetryDelay * 2, this.opts.reconnectBackoff.capMs);
+            continue;
+          }
+          throw this.notSentCallError(
+            `route.open failed for module ${cached.moduleId}: ${err.code} (retry budget exhausted)`,
+            err,
+          );
+        }
+        // A permanent route.open rejection (bad_consumer_identity, config_divergence,
+        // unknown_target, ...) is pre-send but would never succeed on retry, so it
+        // stays terminal — a not_sent class here would invite a retry storm against a
+        // request the daemon will always reject.
         throw this.terminalCallError(`route.open failed for module ${cached.moduleId}`, err);
       }
     }
@@ -789,14 +912,29 @@ export class SubcClient {
   private async readLoop(sock: SubcSocket, generation: number): Promise<void> {
     try {
       for (;;) {
-        // Header read waits indefinitely — idle time between frames is normal.
+        // Header read waits indefinitely — idle time between frames is normal, and
+        // the reader is NOT "active" while parked here (a racing timeout must not
+        // grant grace just because the connection is idle between frames).
         const headerBytes = await sock.readExact(HEADER_LEN, Number.POSITIVE_INFINITY);
-        const header = decodeHeader(headerBytes);
-        const body =
-          header.len === 0
-            ? new Uint8Array(0)
-            : await sock.readExact(header.len, Date.now() + BODY_READ_TIMEOUT_MS);
-        this.dispatch({ header, body });
+        // A frame is now arriving. Mark the reader active THROUGH dispatch so a
+        // timeout that fires mid-arrival grants the reply its bounded grace window
+        // instead of settling as a spurious timeout.
+        this.readerActive = true;
+        try {
+          const header = decodeHeader(headerBytes);
+          const body =
+            header.len === 0
+              ? new Uint8Array(0)
+              : await sock.readExact(header.len, Date.now() + BODY_READ_TIMEOUT_MS);
+          // Drop a frame read off a socket this client has already replaced
+          // (reconnect): its pendings were settled by fail(), and dispatching it
+          // against the current pending map could match a re-used (channel, corr).
+          if (this.sock === sock && this.generation === generation) {
+            this.dispatch({ header, body });
+          }
+        } finally {
+          this.readerActive = false;
+        }
       }
     } catch (err) {
       if (this.sock === sock && this.generation === generation) {
@@ -829,15 +967,46 @@ export class SubcClient {
       this.failChannel(frame.header.channel, new SubcError("route closed by subc (GOODBYE)"));
       return;
     }
+    // A terminal frame (Response/Error/StreamEnd) with no waiter is almost always
+    // a reply that arrived AFTER its request already settled — the fingerprint of a
+    // premature timeout under event-loop starvation (the reply raced the deadline
+    // and lost). Metadata-only debug log (never the body) so every future
+    // occurrence is a one-line diagnosis instead of an invisible drop. Enable with
+    // NODE_DEBUG=subc-client.
+    if (
+      frame.header.ty === FrameType.Response ||
+      frame.header.ty === FrameType.Error ||
+      frame.header.ty === FrameType.StreamEnd
+    ) {
+      debug(
+        "dropped terminal frame with no waiter: type=%d channel=%d corr=%s port=%s",
+        frame.header.ty,
+        frame.header.channel,
+        frame.header.corr,
+        this.sock.localPort() ?? "?",
+      );
+      return;
+    }
     // Unmatched Push or stray frame: no registered waiter. Drop it — v1 has no
     // unsolicited-push consumers.
   }
 
-  private settle(key: string, pending: Pending, run: () => void): void {
+  /**
+   * Settle a pending exactly once. The object-identity guard (the map still
+   * holds THIS pending under `key`) is the single-winner primitive: whichever of
+   * dispatch, a timeout, fail(), failChannel(), a GOODBYE, or a deferred timeout
+   * arbitration reaches it first wins, and every later caller no-ops. This is what
+   * makes the deferred-timeout arbitration safe — it cannot double-settle, reject
+   * an already-resolved promise, or delete a pending re-created for a later corr.
+   * Returns true when this call was the settler.
+   */
+  private settle(key: string, pending: Pending, run: () => void): boolean {
+    if (this.pending.get(key) !== pending) return false;
     this.pending.delete(key);
     if (pending.timer) clearTimeout(pending.timer);
     run();
     pending.onSettle?.();
+    return true;
   }
 
   private rejectPending(key: string, pending: Pending, err: Error): void {
@@ -909,6 +1078,27 @@ export function isConsumerReconnectTransient(err: unknown): boolean {
   return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE" || code === "ETIMEDOUT" || code === "ENOENT";
 }
 
+/**
+ * The closed set of route.open rejection codes that mean "the target is
+ * momentarily unavailable but the request could succeed on retry" — the target
+ * is booting, mid-reload, transiently absent, or the bind relay timed out. A
+ * daemon-rejected route.open is provably pre-send (no data frame ever left the
+ * client), so these classify as not_sent; the managed path retries them in-place
+ * within ROUTE_OPEN_RETRY_DEADLINE_MS. Permanent rejections (bad_consumer_identity,
+ * config_divergence, unknown_target, ...) are excluded — they are pre-send but
+ * would never succeed, so retrying them would only storm the daemon. Kept
+ * byte-identical to subc-client-rs is_retryable_route_open_code for cross-client
+ * classification parity.
+ */
+export function isRetryableRouteOpenCode(code: string | undefined): boolean {
+  return (
+    code === "unknown_module" ||
+    code === "module_reloading" ||
+    code === "target_unavailable" ||
+    code === "module_timeout"
+  );
+}
+
 export async function connectionFileExists(path: string): Promise<boolean> {
   try {
     await fs.access(path);
@@ -926,6 +1116,7 @@ function normalizeConnectOptions(opts: ConnectOptions): NormalizedConnectOptions
     targetKind: opts.targetKind ?? DEFAULT_MANAGED_TARGET_KIND,
     reconnectBackoff: opts.reconnectBackoff ?? DEFAULT_RECONNECT_BACKOFF,
     sleep: opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    timeoutArbitrationGraceMs: opts.timeoutArbitrationGraceMs ?? TIMEOUT_ARBITRATION_GRACE_MS,
   };
 }
 

package/src/socket.ts

@@ -48,6 +48,13 @@ export class SubcSocket {
   private waiter: Waiter | null = null;
   private closedErr: Error | null = null;
 
+  /** Bytes currently buffered but not yet consumed by a reader. A timeout
+   * arbitration uses this to tell "a reply already arrived, keep draining" from
+   * "nothing is here, settle the timeout". */
+  bufferedBytes(): number {
+    return this.buffered;
+  }
+
   private constructor(sock: net.Socket) {
     this.sock = sock;
     sock.on("data", (chunk: Buffer) => {