@relayfile/sdk 0.6.10 → 0.6.12

package/dist/client.d.ts

@@ -51,6 +51,18 @@ export declare class RelayFileClient {
     private readonly userAgent?;
     private readonly retryOptions;
     constructor(options: RelayFileClientOptions);
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    getToken(): Promise<string>;
     listTree(workspaceId: string, options?: ListTreeOptions): Promise<TreeResponse>;
     readFile(workspaceId: string, path: string, correlationId?: string, signal?: AbortSignal): Promise<FileReadResponse>;
     readFile(input: ReadFileInput): Promise<FileReadResponse>;

package/dist/client.js

@@ -171,6 +171,20 @@ export class RelayFileClient {
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);
     }
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    async getToken() {
+        return resolveToken(this.tokenProvider);
+    }
     async listTree(workspaceId, options = {}) {
         const query = buildQuery({
             path: options.path ?? "/",

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
-export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState } from "./sync.js";
+export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";
 export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnWriteHandlerError, type OnWriteOptions } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";

package/dist/onWrite.d.ts

@@ -1,6 +1,6 @@
 import type { WriteEvent, WriteEventOperation } from "@relayfile/core";
 import { RelayFileClient } from "./client.js";
-import { type RelayFileSyncSocket } from "./sync.js";
+import { type RelayFileSyncSocket, type RelayFileSyncTokenProvider } from "./sync.js";
 export type OnWriteHandler = (event: WriteEvent) => void | Promise<void>;
 export interface OnWriteHandlerError {
     pattern: string;
@@ -17,8 +17,30 @@ export interface OnWriteOptions {
     operations?: WriteEventOperation[];
     signal?: AbortSignal;
     baseUrl?: string;
-    token?: string;
+    /**
+     * Optional WebSocket auth override. Accepts the same `string | () =>
+     * string | Promise<string>` shape as the underlying sync.
+     *
+     * If omitted, onWrite auto-derives WS auth from `client.getToken()` — the
+     * same JWT the REST API is using — and re-resolves it on every reconnect
+     * so token rotation propagates without restart. **Most callers should
+     * leave this unset.** Passing a literal string is back-compat for older
+     * code; passing a factory is the right shape for production.
+     */
+    token?: RelayFileSyncTokenProvider;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
+    pingIntervalMs?: number;
+    pongTimeoutMs?: number;
+    /**
+     * Notification hook fired when the underlying sync degrades to HTTP
+     * polling because the WebSocket failed to open. Useful for surfacing a
+     * "live updates paused" banner. The SDK also `console.warn`s and emits
+     * an `error` regardless.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export declare function pathMatches(pattern: string, path: string): boolean;
 export declare function onWrite(pattern: string, handler: OnWriteHandler, options?: OnWriteOptions): () => void;

package/dist/onWrite.js

@@ -6,6 +6,23 @@ const DEFAULT_RECONNECT_MAX_DELAY_MS = 30000;
 const dispatchers = new WeakMap();
 let nextRegistrationId = 1;
 let defaultClient;
+const debugEnabled = (() => {
+    try {
+        const value = globalThis.process?.env?.RELAYFILE_SDK_DEBUG;
+        return value === "1" || value === "true";
+    }
+    catch {
+        return false;
+    }
+})();
+function debugLog(...args) {
+    if (!debugEnabled) {
+        return;
+    }
+    if (typeof console !== "undefined" && typeof console.error === "function") {
+        console.error("[relayfile-sdk:onWrite]", ...args);
+    }
+}
 export function pathMatches(pattern, path) {
     const patternSegments = normalizePattern(pattern);
     const pathSegments = normalizePath(path);
@@ -50,8 +67,12 @@ export function onWrite(pattern, handler, options = {}) {
         signal: options.signal,
         baseUrl: options.baseUrl,
         token: options.token,
-        webSocketFactory: options.webSocketFactory
+        webSocketFactory: options.webSocketFactory,
+        pingIntervalMs: options.pingIntervalMs,
+        pongTimeoutMs: options.pongTimeoutMs,
+        onPollingFallback: options.onPollingFallback
     });
+    debugLog("registered", { id: registration.id, pattern: normalizedPattern, workspaceId });
     return () => {
         dispatcher?.unregister(registration.id);
     };
@@ -95,16 +116,29 @@ class OnWriteDispatcher {
         if (this.sync) {
             return;
         }
+        // Token resolution order:
+        //  1. options.token (literal or factory) — back-compat for callers that
+        //     mint their own auth.
+        //  2. RELAYFILE_TOKEN env var.
+        //  3. fall through to undefined → RelayFileSync auto-derives from
+        //     `client.getToken()` (the recommended path; same JWT as REST).
+        // (Bug 1 fix: previously, omitting `token` here passed `undefined` and
+        // the WS handshake silently failed with no auth, dropping us into
+        // backwards-walking polling forever.)
+        const token = options.token ?? readEnv("RELAYFILE_TOKEN") ?? undefined;
         this.sync = RelayFileSync.connect({
             client: this.client,
             workspaceId: options.workspaceId,
             baseUrl: options.baseUrl ?? readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL,
-            token: options.token ?? readEnv("RELAYFILE_TOKEN"),
+            token,
             reconnect: {
                 minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
                 maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
             },
             webSocketFactory: options.webSocketFactory,
+            pingIntervalMs: options.pingIntervalMs,
+            pongTimeoutMs: options.pongTimeoutMs,
+            onPollingFallback: options.onPollingFallback,
             onEvent: (event) => {
                 void this.dispatch(event);
             }
@@ -119,10 +153,26 @@ class OnWriteDispatcher {
             if (!registration.operations.has(writeEvent.operation) || !pathMatches(registration.pattern, writeEvent.path)) {
                 continue;
             }
+            debugLog("dispatch", {
+                registrationId: registration.id,
+                pattern: registration.pattern,
+                path: writeEvent.path,
+                operation: writeEvent.operation
+            });
+            // patternChains serializes handlers per pattern. runHandler is the only
+            // thing chained here and it already swallows handler errors, so the
+            // chain itself can never reject — but we still defensively `.catch`
+            // before chaining so a future refactor of runHandler cannot silently
+            // break the chain (which is the failure mode hypothesis 3 in the bug
+            // report).
             const previous = this.patternChains.get(registration.pattern) ?? Promise.resolve();
             const next = previous
                 .catch(() => undefined)
-                .then(() => this.runHandler(registration, writeEvent));
+                .then(() => this.runHandler(registration, writeEvent))
+                .catch((error) => {
+                // Belt-and-braces: should be unreachable because runHandler catches.
+                debugLog("patternChain unexpectedly rejected", { pattern: registration.pattern, error });
+            });
             this.patternChains.set(registration.pattern, next);
             void next.finally(() => {
                 if (this.patternChains.get(registration.pattern) === next) {

package/dist/sync.d.ts

@@ -1,5 +1,13 @@
 import type { RelayFileClient } from "./client.js";
 import type { FilesystemEvent } from "./types.js";
+/**
+ * WebSocket auth source for {@link RelayFileSyncOptions.token}.
+ *
+ * The function form is preferred for production: it is re-invoked on every
+ * (re)connect, so token rotation/refresh propagates without restarting the
+ * sync. The plain string form is kept for backward compatibility and tests.
+ */
+export type RelayFileSyncTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
 export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
 export interface RelayFileSyncPong {
     type: "pong";
@@ -14,15 +22,36 @@ export interface RelayFileSyncOptions {
     client: RelayFileClient;
     workspaceId: string;
     baseUrl?: string;
-    token?: string;
+    /**
+     * WebSocket auth token. Accepts either a literal string or a (sync/async)
+     * factory. The factory form is re-invoked on every (re)connect so token
+     * rotation propagates transparently.
+     *
+     * If omitted, sync resolves the token via `client.getToken()` on each
+     * connect — i.e. the same JWT the REST methods are using. Callers should
+     * normally NOT pass this and let it inherit from the client.
+     */
+    token?: RelayFileSyncTokenProvider;
     cursor?: string;
     preferPolling?: boolean;
     pollIntervalMs?: number;
     pingIntervalMs?: number;
+    pongTimeoutMs?: number;
     reconnect?: boolean | RelayFileSyncReconnectOptions;
     signal?: AbortSignal;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
     onEvent?: (event: FilesystemEvent) => void;
+    /**
+     * Notification hook invoked when the sync degrades to HTTP polling because
+     * the WebSocket failed to open or was rejected by the server. Live events
+     * will be delayed by `pollIntervalMs` while in this mode. Use this to
+     * surface a UI banner or alert; the SDK also emits `console.warn` and an
+     * `error` event regardless of whether this is wired.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export interface RelayFileSyncSocket {
     addEventListener(type: "open", handler: (event: Event) => void): void;
@@ -45,22 +74,29 @@ export declare class RelayFileSync {
     private readonly client;
     private readonly workspaceId;
     private readonly baseUrl?;
-    private readonly token?;
+    private readonly tokenProvider?;
     private readonly pollIntervalMs;
     private readonly pingIntervalMs;
+    private readonly pongTimeoutMs;
     private readonly reconnect;
     private readonly preferPolling;
     private readonly signal?;
     private readonly webSocketFactory;
+    private readonly onPollingFallback?;
     private readonly handlers;
     private state;
     private cursor?;
+    private readonly polledEventIds;
+    private readonly polledEventOrder;
+    private firstPollComplete;
     private socket?;
     private started;
     private stopped;
     private pollingPromise?;
     private reconnectTimer?;
     private pingTimer?;
+    private lastFrameAt;
+    private lastPingSentAt;
     private reconnectAttempts;
     private readonly abortHandler?;
     constructor(options: RelayFileSyncOptions);
@@ -70,11 +106,15 @@ export declare class RelayFileSync {
     stop(): Promise<void>;
     on<TEventName extends RelayFileSyncEventName>(event: TEventName, handler: RelayFileSyncHandlerMap[TEventName]): () => void;
     private shouldUsePolling;
+    private resolveWsTokenMaybeSync;
     private openWebSocket;
+    private openWebSocketWithToken;
     private startPolling;
     private pollLoop;
+    private rememberPolledEvent;
     private handleSocketMessage;
     private startPingLoop;
+    private forceReconnect;
     private scheduleReconnect;
     private computeReconnectDelayMs;
     private sleep;

package/dist/sync.js

@@ -2,6 +2,40 @@ const DEFAULT_POLL_INTERVAL_MS = 5000;
 const DEFAULT_PING_INTERVAL_MS = 30000;
 const DEFAULT_RECONNECT_MIN_DELAY_MS = 250;
 const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
+// Cap on the dedupe cache used in polling mode. Sized large enough that no
+// realistic workspace burst can churn through it within one poll interval
+// (the events API is itself capped at ~1000 per page), small enough to keep
+// memory bounded across long-lived processes.
+const POLLING_DEDUPE_CACHE_LIMIT = 2048;
+function warnPollingFallback(reason, cause) {
+    // Always-on warning (NOT gated by RELAYFILE_SDK_DEBUG) because silent
+    // degradation to polling has historically masked real auth/connectivity
+    // bugs for hours at a time. Customers running the SDK in a Node service
+    // see the warning in their normal logs without any opt-in.
+    if (typeof console === "undefined" || typeof console.warn !== "function") {
+        return;
+    }
+    const detail = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : "";
+    const suffix = detail ? ` (${reason}: ${detail})` : ` (${reason})`;
+    console.warn(`[relayfile-sdk] WebSocket connect failed; falling back to HTTP polling. Live events will be delayed.${suffix}`);
+}
+const debugEnabled = (() => {
+    try {
+        const value = globalThis.process?.env?.RELAYFILE_SDK_DEBUG;
+        return value === "1" || value === "true";
+    }
+    catch {
+        return false;
+    }
+})();
+function debugLog(...args) {
+    if (!debugEnabled) {
+        return;
+    }
+    if (typeof console !== "undefined" && typeof console.error === "function") {
+        console.error("[relayfile-sdk:sync]", ...args);
+    }
+}
 function normalizeReconnectOptions(reconnect) {
     if (reconnect === false) {
         return {
@@ -58,13 +92,18 @@ export class RelayFileSync {
     client;
     workspaceId;
     baseUrl;
-    token;
+    // Resolved on every connect attempt (string form is wrapped into a constant
+    // factory at construction time). `undefined` means "fall back to
+    // client.getToken()" — same JWT the REST methods use.
+    tokenProvider;
     pollIntervalMs;
     pingIntervalMs;
+    pongTimeoutMs;
     reconnect;
     preferPolling;
     signal;
     webSocketFactory;
+    onPollingFallback;
     handlers = {
         event: new Set(),
         error: new Set(),
@@ -75,22 +114,49 @@ export class RelayFileSync {
     };
     state = "idle";
     cursor;
+    polledEventIds = new Set();
+    polledEventOrder = [];
+    firstPollComplete = false;
     socket;
     started = false;
     stopped = false;
     pollingPromise;
     reconnectTimer;
     pingTimer;
+    // Tracks the last time *any* WebSocket frame was received (event, pong, or
+    // otherwise). The watchdog uses this to detect silent socket death.
+    lastFrameAt = 0;
+    // Tracks when the most recent ping was sent. We only enforce the pong
+    // timeout once a ping has actually gone out; otherwise a quiet workspace
+    // (no broadcasts and no pings yet) would falsely trip the watchdog.
+    lastPingSentAt = 0;
     reconnectAttempts = 0;
     abortHandler;
     constructor(options) {
         this.client = options.client;
         this.workspaceId = options.workspaceId;
         this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
-        this.token = options.token;
+        // Normalize token into a factory. `undefined` is preserved so the open
+        // path knows to fall back to `client.getToken()` (the recommended path —
+        // the WebSocket then auto-uses the same JWT the REST API is using).
+        if (options.token === undefined) {
+            this.tokenProvider = undefined;
+        }
+        else if (typeof options.token === "function") {
+            this.tokenProvider = options.token;
+        }
+        else {
+            const literal = options.token;
+            this.tokenProvider = () => literal;
+        }
         this.cursor = options.cursor;
+        this.onPollingFallback = options.onPollingFallback;
         this.pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
         this.pingIntervalMs = Math.max(1, Math.floor(options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS));
+        // Default the pong timeout to 2x ping interval so a single missed pong
+        // does not cause a flap, but two consecutive misses force a reconnect.
+        const defaultPongTimeoutMs = this.pingIntervalMs * 2;
+        this.pongTimeoutMs = Math.max(1, Math.floor(options.pongTimeoutMs ?? defaultPongTimeoutMs));
         this.reconnect = normalizeReconnectOptions(options.reconnect);
         this.preferPolling = options.preferPolling ?? false;
         this.signal = options.signal;
@@ -132,7 +198,9 @@ export class RelayFileSync {
         }
         this.started = true;
         if (this.shouldUsePolling()) {
-            this.startPolling();
+            // Caller explicitly opted into polling, or there's no baseUrl to
+            // upgrade to wss. NOT a fallback — no warn here.
+            this.startPolling("explicit");
             return;
         }
         this.openWebSocket(false);
@@ -164,9 +232,63 @@ export class RelayFileSync {
         };
     }
     shouldUsePolling() {
-        return this.preferPolling || !this.baseUrl || !this.token;
+        // Token availability is no longer required up-front — the WS opener
+        // resolves it on demand from either `options.token` (a literal/factory)
+        // or `client.getToken()`. We only force polling when the caller asked
+        // for it or there is no baseUrl to derive a wss URL from.
+        return this.preferPolling || !this.baseUrl;
+    }
+    // Resolve a token for the WS upgrade. Returns either a string directly
+    // (sync fast-path; preserves the synchronous "start() → factory called"
+    // contract that pre-existed Bug 1's fix) or a Promise (async slow-path;
+    // factory is invoked on the next microtask). `undefined` means "no token
+    // available — the server may still accept the upgrade if it's configured
+    // for unauthenticated mode in tests/local-dev".
+    resolveWsTokenMaybeSync() {
+        if (this.tokenProvider) {
+            // Most production providers return synchronously (JWT pulled from a
+            // mutable cell that a refresh task updates in the background), so the
+            // sync path is the common case.
+            return this.tokenProvider();
+        }
+        // Auto-derive from the client's tokenProvider — the same JWT the REST
+        // surface is using. Bug 1 fix: callers no longer have to thread
+        // `token: await client.tokenProvider()` through every onWrite() call.
+        // client.getToken is always async (returns a Promise), so we land on
+        // the slow path here. That's fine: the WS open is async anyway.
+        return this.client.getToken();
     }
     openWebSocket(isReconnect) {
+        if (this.stopped) {
+            return;
+        }
+        this.setState(isReconnect ? "reconnecting" : "connecting");
+        // Resolve a fresh token on every (re)connect attempt. This is what
+        // makes mid-session token rotation transparent: the watchdog/close
+        // handler reconnects, we re-call the factory, and the new socket comes
+        // up with the new JWT. (Bug 4: pre-fix, the token was captured once at
+        // construction and a 4001/auth close on rotation triggered an infinite
+        // reconnect loop with the stale token.)
+        let resolved;
+        try {
+            resolved = this.resolveWsTokenMaybeSync();
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+            this.startPolling("token-resolution-failed", error);
+            return;
+        }
+        if (resolved && typeof resolved.then === "function") {
+            // Async path. The factory call gets deferred to the next microtask.
+            resolved.then((token) => this.openWebSocketWithToken(token), (error) => {
+                this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+                this.startPolling("token-resolution-failed", error);
+            });
+            return;
+        }
+        this.openWebSocketWithToken(resolved);
+    }
+    openWebSocketWithToken(token) {
         if (this.stopped) {
             return;
         }
@@ -174,17 +296,16 @@ export class RelayFileSync {
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         // Pass token in query string — the server authenticates during the HTTP
         // upgrade handshake via r.URL.Query().Get("token").
-        if (this.token) {
-            url.searchParams.set("token", this.token);
+        if (token) {
+            url.searchParams.set("token", token);
         }
-        this.setState(isReconnect ? "reconnecting" : "connecting");
         let socket;
         try {
             socket = this.webSocketFactory(url.toString());
         }
         catch (error) {
             this.emit("error", error instanceof Error ? error : new Error("Failed to create WebSocket connection."));
-            this.startPolling();
+            this.startPolling("ws-factory-threw", error);
             return;
         }
         this.socket = socket;
@@ -193,43 +314,80 @@ export class RelayFileSync {
                 return;
             }
             this.reconnectAttempts = 0;
+            // Reset frame/ping bookkeeping for the freshly opened socket so the
+            // watchdog has a clean baseline. lastPingSentAt=0 disables the pong
+            // timeout until we actually send our first ping.
+            this.lastFrameAt = Date.now();
+            this.lastPingSentAt = 0;
             this.setState("open");
             this.startPingLoop(socket);
+            debugLog("ws open", { workspaceId: this.workspaceId });
             this.emit("open", event);
         });
         socket.addEventListener("message", (event) => {
             if (this.socket !== socket || this.stopped) {
                 return;
             }
+            // Stamp lastFrameAt for *any* inbound frame so the watchdog sees both
+            // application events and pongs as proof of life.
+            this.lastFrameAt = Date.now();
             this.handleSocketMessage(event);
         });
         socket.addEventListener("error", (event) => {
             if (this.socket !== socket || this.stopped) {
                 return;
             }
+            debugLog("ws error", event);
             this.emit("error", normalizeError(event));
         });
         socket.addEventListener("close", (event) => {
-            if (this.socket === socket) {
-                this.socket = undefined;
+            // forceReconnect (called from the watchdog or a failed ping send) nulls
+            // out this.socket and opens a replacement before the OS-layer close
+            // event for the old socket actually fires. If this handler treated a
+            // stale close as authoritative it would (a) clearPingTimer() and kill
+            // the new socket's heartbeat and (b) potentially scheduleReconnect()
+            // a second time (the timer guard would skip it most of the time, but
+            // not after the timer has already fired). Either way: don't touch
+            // shared state when the socket we're attached to is no longer current.
+            if (this.socket !== socket) {
+                debugLog("ws close (stale, ignored)", {
+                    code: event?.code,
+                    reason: event?.reason,
+                });
+                return;
             }
+            this.socket = undefined;
             this.clearPingTimer();
+            debugLog("ws close", { code: event?.code, reason: event?.reason, stopped: this.stopped });
             this.emit("close", event);
             if (this.stopped) {
                 this.setState("closed");
                 return;
             }
             if (!this.reconnect.enabled) {
-                this.startPolling();
+                this.startPolling("ws-closed-no-reconnect", { code: event?.code, reason: event?.reason });
                 return;
             }
             this.scheduleReconnect();
         });
     }
-    startPolling() {
+    startPolling(reason = "fallback", cause) {
         if (this.pollingPromise || this.stopped) {
             return;
         }
+        // Always-on warning + structured callback whenever we drop into polling
+        // *involuntarily*. `explicit` means the caller asked for it (preferPolling
+        // or no baseUrl) and we stay quiet — anything else is a real degradation
+        // signal that previously took hours to detect.
+        if (reason !== "explicit") {
+            warnPollingFallback(reason, cause);
+            try {
+                this.onPollingFallback?.({ reason, cause });
+            }
+            catch (error) {
+                debugLog("onPollingFallback handler threw", error);
+            }
+        }
         this.setState("polling");
         this.pollingPromise = this.pollLoop().finally(() => {
             this.pollingPromise = undefined;
@@ -245,16 +403,58 @@ export class RelayFileSync {
                 throw createAbortError();
             }
             try {
-                const response = await this.client.getEvents(this.workspaceId, {
-                    cursor: this.cursor,
-                    signal: this.signal
-                });
+                // The current server implementation paginates events from oldest to
+                // newest. Empty cursor starts at index 0, and nextCursor advances
+                // forward through history. To avoid replaying the whole event log on
+                // startup while still preserving live forward progress, the first poll
+                // drains to the tip and seeds `this.cursor` without emitting. Later
+                // polls resume from that live cursor and emit only newly appended
+                // events.
+                let cursor = this.cursor;
+                let latestCursor = cursor;
+                const pending = [];
+                for (;;) {
+                    const response = await this.client.getEvents(this.workspaceId, {
+                        cursor,
+                        limit: 1000,
+                        signal: this.signal
+                    });
+                    const events = response.events ?? [];
+                    if (!this.firstPollComplete) {
+                        for (const event of events) {
+                            this.rememberPolledEvent(event.eventId);
+                        }
+                    }
+                    else {
+                        for (const event of events) {
+                            if (!event.eventId || this.polledEventIds.has(event.eventId)) {
+                                continue;
+                            }
+                            this.rememberPolledEvent(event.eventId);
+                            pending.push(event);
+                        }
+                    }
+                    const nextCursor = response.nextCursor || null;
+                    if (events.length > 0) {
+                        latestCursor = events[events.length - 1]?.eventId ?? latestCursor;
+                    }
+                    if (nextCursor) {
+                        latestCursor = nextCursor;
+                    }
+                    if (!nextCursor || nextCursor === cursor) {
+                        break;
+                    }
+                    cursor = nextCursor;
+                }
                 retryAttempt = 0;
-                for (const event of response.events) {
-                    this.emit("event", event);
+                this.cursor = latestCursor;
+                if (!this.firstPollComplete) {
+                    this.firstPollComplete = true;
                 }
-                if (response.nextCursor) {
-                    this.cursor = response.nextCursor;
+                else {
+                    for (const event of pending) {
+                        this.emit("event", event);
+                    }
                 }
                 await this.sleep(this.pollIntervalMs);
             }
@@ -269,6 +469,19 @@ export class RelayFileSync {
             }
         }
     }
+    rememberPolledEvent(eventId) {
+        if (!eventId || this.polledEventIds.has(eventId)) {
+            return;
+        }
+        this.polledEventIds.add(eventId);
+        this.polledEventOrder.push(eventId);
+        while (this.polledEventOrder.length > POLLING_DEDUPE_CACHE_LIMIT) {
+            const evicted = this.polledEventOrder.shift();
+            if (evicted) {
+                this.polledEventIds.delete(evicted);
+            }
+        }
+    }
     handleSocketMessage(event) {
         if (typeof event.data !== "string") {
             return;
@@ -302,29 +515,100 @@ export class RelayFileSync {
             return;
         }
         if (parsed.type === "pong") {
+            debugLog("pong", { timestamp: parsed.timestamp ?? parsed.ts });
             this.emit("pong", {
                 type: "pong",
                 timestamp: parsed.timestamp ?? parsed.ts
             });
             return;
         }
-        this.emit("event", normalizeFilesystemEvent(parsed));
+        const normalized = normalizeFilesystemEvent(parsed);
+        debugLog("event", { type: normalized.type, path: normalized.path, revision: normalized.revision });
+        this.emit("event", normalized);
     }
     startPingLoop(socket) {
         this.clearPingTimer();
+        // The "ping loop" doubles as the heartbeat watchdog. The contract for
+        // pongTimeoutMs is "how long to wait, after sending a ping, before
+        // assuming the socket is dead." So the timeout window must be measured
+        // from `lastPingSentAt` — the moment we sent the unanswered ping — not
+        // from the last inbound frame. (CodeRabbit P1 on PR #93: with
+        // pingIntervalMs=30_000 + pongTimeoutMs=45_000, measuring from
+        // lastFrameAt would reconnect at t=60s — only 30s after the first
+        // ping went out, which violates the documented "wait 45s after a
+        // ping" semantics.)
+        //
+        // An unanswered ping = `lastPingSentAt > lastFrameAt`. Any inbound
+        // frame (event OR pong) advances lastFrameAt past lastPingSentAt and
+        // proves the socket is alive. While a ping is unanswered we DO NOT
+        // pile up another — that would just race the timeout window and make
+        // tuning meaningless.
+        //
+        // Load-bearing for the silent socket-death failure mode where the
+        // server keeps broadcasting frames the JS layer never receives (e.g.
+        // NAT/LB idle drop, half-open TCP) and neither `error` nor `close`
+        // ever fires.
         this.pingTimer = setInterval(() => {
             if (this.socket !== socket || this.stopped) {
                 this.clearPingTimer();
                 return;
             }
+            const now = Date.now();
+            const hasOutstandingPing = this.lastPingSentAt > this.lastFrameAt;
+            if (hasOutstandingPing) {
+                const sincePing = now - this.lastPingSentAt;
+                if (sincePing > this.pongTimeoutMs) {
+                    debugLog("watchdog tripped — forcing reconnect", {
+                        workspaceId: this.workspaceId,
+                        sincePingMs: sincePing,
+                        pongTimeoutMs: this.pongTimeoutMs
+                    });
+                    this.forceReconnect(socket, "heartbeat-timeout");
+                    return;
+                }
+                // Within the timeout — still waiting for the pong/frame. Don't
+                // pile up a second ping while one is outstanding.
+                return;
+            }
             try {
                 socket.send(JSON.stringify({ type: "ping" }));
+                this.lastPingSentAt = now;
             }
             catch (error) {
+                debugLog("ping send failed", error);
                 this.emit("error", error instanceof Error ? error : new Error("Failed to send WebSocket ping."));
+                // A failed send strongly implies the socket is dead. Force a
+                // reconnect rather than waiting for the next tick to notice.
+                this.forceReconnect(socket, "ping-send-failed");
             }
         }, this.pingIntervalMs);
     }
+    // Tear down a socket that the watchdog or a failed send has decided is
+    // dead. We close it (so any later async events from the OS layer become
+    // no-ops via the `this.socket !== socket` guards) and trigger the standard
+    // reconnect path. Catches errors from `close()` because some socket
+    // implementations throw when closing an already-broken connection.
+    forceReconnect(socket, reason) {
+        this.clearPingTimer();
+        if (this.socket === socket) {
+            this.socket = undefined;
+        }
+        try {
+            socket.close(4000, reason);
+        }
+        catch (error) {
+            debugLog("socket.close threw during forceReconnect", error);
+        }
+        if (this.stopped) {
+            this.setState("closed");
+            return;
+        }
+        if (!this.reconnect.enabled) {
+            this.startPolling("forced-reconnect-no-retry", reason);
+            return;
+        }
+        this.scheduleReconnect();
+    }
     scheduleReconnect() {
         if (this.stopped || this.reconnectTimer) {
             return;
@@ -332,6 +616,7 @@ export class RelayFileSync {
         this.reconnectAttempts += 1;
         this.setState("reconnecting");
         const delayMs = this.computeReconnectDelayMs(this.reconnectAttempts);
+        debugLog("scheduling reconnect", { attempt: this.reconnectAttempts, delayMs });
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = undefined;
             if (this.stopped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.6.10"
+    "@relayfile/core": "0.6.12"
   },
   "devDependencies": {
     "typescript": "^5.7.3",