@adaptic/utils 0.0.1002 → 0.0.1004

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { format, sub, set, add, startOfDay, endOfDay, isBefore, differenceInMill
 import { formatInTimeZone, toZonedTime, fromZonedTime } from 'date-fns-tz';
 import require$$0$4, { EventEmitter } from 'events';
 import WebSocket from 'ws';
+import { createHash } from 'node:crypto';
 import ms from 'ms';
 import require$$0$1 from 'fs';
 import require$$1 from 'path';
@@ -2403,6 +2404,19 @@ class DataFormatError extends AdapticUtilsError {
  * const result = await makeAlpacaApiCall();
  * ```
  */
+/** Number of milliseconds in one second, used for token-refill timing math. */
+const MS_PER_SECOND$1 = 1000;
+/**
+ * Minimum delay (ms) for a scheduled queue wake-up. Guards against a `0`/`NaN`
+ * delay when the token deficit rounds down, ensuring the timer always makes
+ * forward progress rather than busy-looping on the event loop.
+ */
+const MIN_WAKE_DELAY_MS = 1;
+/**
+ * Number of whole tokens required to release a single queued request. The token
+ * bucket consumes exactly one token per admitted request.
+ */
+const TOKENS_PER_REQUEST = 1;
 /**
  * Token bucket rate limiter implementation
  *
@@ -2418,6 +2432,13 @@ class TokenBucketRateLimiter {
     queue = [];
     timeoutMs;
     processingQueue = false;
+    /**
+     * Single pending timer that wakes the limiter to refill tokens and drain the
+     * queue. Without this, a queued request would only be released by a
+     * subsequent {@link acquire} call and would otherwise stall until its own
+     * timeout fired. `null` means no wake-up is currently scheduled.
+     */
+    wakeTimer = null;
     /**
      * Creates a new rate limiter instance
      *
@@ -2491,8 +2512,48 @@ class TokenBucketRateLimiter {
                 reject(error);
             }, this.timeoutMs);
             this.queue.push({ resolve, reject, timeoutHandle });
+            // Ensure the queue is actively drained even if no further acquire() calls
+            // arrive: schedule a wake-up to refill tokens and release this request.
+            this.scheduleQueueWake();
         });
     }
+    /**
+     * Schedules a single wake-up timer that refills tokens and drains the queue.
+     *
+     * The delay is the time required to accrue the tokens still needed to release
+     * the next queued request at the configured refill rate. Only one timer is
+     * ever outstanding (guarded by {@link wakeTimer}); the timer is `unref`'d so
+     * it never keeps the Node.js process alive on its own. When it fires it
+     * refills, drains what it can, and re-arms itself if work remains.
+     */
+    scheduleQueueWake() {
+        // A wake-up is already pending, or there is nothing to wake for.
+        if (this.wakeTimer !== null || this.queue.length === 0) {
+            return;
+        }
+        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
+        const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
+        const timer = setTimeout(() => {
+            this.wakeTimer = null;
+            // refill() drains the queue via processQueue(); if requests remain
+            // afterwards, processQueue() re-arms the wake-up.
+            this.refill();
+        }, deficitMs);
+        // Do not let a pending rate-limiter wake-up keep the process alive.
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        this.wakeTimer = timer;
+    }
+    /**
+     * Clears any pending wake-up timer.
+     */
+    clearWakeTimer() {
+        if (this.wakeTimer !== null) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
+        }
+    }
     /**
      * Refills tokens based on elapsed time and processes queued requests
      *
@@ -2537,6 +2598,15 @@ class TokenBucketRateLimiter {
         finally {
             this.processingQueue = false;
         }
+        // Keep the wake-up state consistent with the queue: if requests are still
+        // waiting (tokens ran out mid-drain), ensure a wake-up is armed; otherwise
+        // release any pending timer so it cannot fire needlessly.
+        if (this.queue.length > 0) {
+            this.scheduleQueueWake();
+        }
+        else {
+            this.clearWakeTimer();
+        }
     }
     /**
      * Gets the current number of available tokens
@@ -2568,6 +2638,7 @@ class TokenBucketRateLimiter {
             clearTimeout(request.timeoutHandle);
             request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
         }
+        this.clearWakeTimer();
         this.queue = [];
         this.tokens = this.config.maxTokens;
         this.lastRefill = Date.now();
@@ -4317,6 +4388,46 @@ const limitPriceSlippagePercent100 = 0.1; // 0.1%
 const ORDER_PAGE_LIMIT = 500;
 /** Delay between order pagination pages to stay clear of rate limits. */
 const ORDER_PAGINATION_DELAY_MS = 300;
+/**
+ * HTTP status at or above which a Multi-Status (207) sub-result is a failure.
+ * Alpaca's bulk `DELETE /orders` and `DELETE /positions` endpoints return a 207
+ * envelope whose top-level status is 2xx even when individual orders/positions
+ * failed to cancel or close; each element carries its own per-item HTTP status.
+ * Treating >= 300 as a failure lets the engine failsafe see partial failures
+ * instead of recording a false success.
+ */
+const HTTP_STATUS_MIN_ERROR = 300;
+/**
+ * Prefix applied to engine-derived `client_order_id` idempotency keys so they
+ * are visibly attributable in Alpaca's dashboard and can never collide with a
+ * caller-supplied identifier.
+ */
+const CLIENT_ORDER_ID_PREFIX = "adaptic-";
+/**
+ * Number of leading hex characters of the SHA-256 digest retained in a derived
+ * `client_order_id`. 32 hex chars = 128 bits of entropy (collision-negligible),
+ * and keeps the full id (prefix + digest = 40 chars) within Alpaca's identifier
+ * length limit.
+ */
+const CLIENT_ORDER_ID_HASH_LENGTH = 32;
+/**
+ * Idempotency window (ms) used when deriving a default `client_order_id`.
+ *
+ * A client request timeout followed by an automatic retry re-submits the SAME
+ * logical order. Deriving the id from the order's semantic parameters plus the
+ * current time-window bucket makes Alpaca reject the retried duplicate
+ * (`client_order_id must be unique`) instead of double-filling. The window is
+ * deliberately much larger than the 30s Alpaca request timeout so a full
+ * timeout+retry sequence lands in the same bucket, while a genuinely new but
+ * otherwise-identical order placed in a later window still receives a distinct
+ * id.
+ *
+ * This derived default is a best-effort safety net; the guaranteed-idempotent
+ * path is for the caller to pass an explicit `clientOrderId` tied to the
+ * originating signal/decision id (which also permits legitimately-repeated
+ * identical orders inside a single window).
+ */
+const CLIENT_ORDER_ID_WINDOW_MS = 300_000;
 /**
 Websocket example
   const alpacaAPI = createAlpacaTradingAPI(credentials); // type AlpacaCredentials
@@ -4397,6 +4508,114 @@ class AlpacaTradingAPI {
             ? Math.round(price * 100) / 100
             : Math.round(price * 10000) / 10000;
     };
+    /**
+     * Derive a deterministic `client_order_id` from an order's semantic
+     * parameters so that a client-timeout-triggered retry re-submits the SAME id
+     * and Alpaca rejects the duplicate broker-side instead of double-filling.
+     *
+     * The id is stable for identical parameters within a single
+     * {@link CLIENT_ORDER_ID_WINDOW_MS} bucket and scoped per account. Callers
+     * that must place genuinely distinct yet otherwise-identical orders should
+     * pass an explicit `clientOrderId` rather than relying on this default.
+     *
+     * @param parts - Ordered, stringifiable components uniquely describing the
+     *   order (e.g. order kind, symbol, side, quantity, price, intent).
+     * @returns An Alpaca-safe `client_order_id` (prefix + truncated SHA-256 hex).
+     */
+    deriveClientOrderId(parts) {
+        const windowBucket = Math.floor(Date.now() / CLIENT_ORDER_ID_WINDOW_MS);
+        const material = [
+            this.credentials.accountName,
+            windowBucket,
+            ...parts.map((part) => (part === undefined ? "" : String(part))),
+        ].join("|");
+        const digest = createHash("sha256")
+            .update(material)
+            .digest("hex")
+            .slice(0, CLIENT_ORDER_ID_HASH_LENGTH);
+        return `${CLIENT_ORDER_ID_PREFIX}${digest}`;
+    }
+    /**
+     * Collect the human-readable failure entries from a bulk Multi-Status (207)
+     * response body (`DELETE /orders`, `DELETE /positions`). Each element carries
+     * its own per-item HTTP status; any element with status >=
+     * {@link HTTP_STATUS_MIN_ERROR} is a failure the caller must be able to see.
+     *
+     * @param entries - Parsed 207 response array.
+     * @returns One `"<identifier>:<status>"` string per failed entry.
+     */
+    collectMultiStatusFailures(entries) {
+        return entries
+            .filter((entry) => typeof entry.status === "number" &&
+            entry.status >= HTTP_STATUS_MIN_ERROR)
+            .map((entry) => `${entry.symbol ?? entry.id ?? "unknown"}:${entry.status}`);
+    }
+    /**
+     * Flatten a single position with a marketable limit order, deriving the
+     * closing side, intent, and slippage-adjusted limit price from the latest
+     * quote. Throws when no usable quote/price is available for the symbol so the
+     * caller can record a per-position failure via {@link Promise.allSettled}
+     * without aborting the flatten of the remaining positions.
+     *
+     * @param position - The position to close.
+     * @param quotesResponse - Latest quotes keyed by symbol.
+     * @param extendedHours - Whether the closing order is an extended-hours order.
+     */
+    async closePositionWithLimitOrder(position, quotesResponse, extendedHours) {
+        const quote = quotesResponse.quotes[position.symbol];
+        if (!quote) {
+            throw new Error(`No quote available for ${position.symbol}`);
+        }
+        const qty = Math.abs(parseFloat(position.qty));
+        const side = position.side === "long" ? "sell" : "buy";
+        const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
+        // Use bid for sells, ask for buys.
+        const currentPrice = side === "sell" ? quote.bp : quote.ap;
+        if (!currentPrice) {
+            throw new Error(`No valid price available for ${position.symbol}`);
+        }
+        const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
+        const limitPrice = side === "sell"
+            ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
+            : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
+        this.log(`Creating ${extendedHours ? "extended hours " : ""}limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
+            symbol: position.symbol,
+        });
+        await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, extendedHours);
+    }
+    /**
+     * Flatten every supplied position independently and surface an aggregate
+     * failure if any could not be closed. Positions are attempted concurrently
+     * with {@link Promise.allSettled} so a data gap or broker rejection on one
+     * symbol never silently prevents the others from being flattened.
+     *
+     * @param positions - Positions to flatten.
+     * @param extendedHours - Whether the closing orders are extended-hours orders.
+     * @throws Error listing every symbol that failed to flatten.
+     */
+    async flattenPositionsWithLimitOrders(positions, extendedHours) {
+        const symbols = positions.map((position) => position.symbol);
+        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
+        const results = await Promise.allSettled(positions.map((position) => this.closePositionWithLimitOrder(position, quotesResponse, extendedHours)));
+        const failures = [];
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                const symbol = positions[index]?.symbol ?? "unknown";
+                const reason = result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason);
+                failures.push(`${symbol}: ${reason}`);
+                this.log(`Failed to close position ${symbol}: ${reason}`, {
+                    symbol,
+                    type: "error",
+                });
+            }
+        });
+        if (failures.length > 0) {
+            throw new Error(`Failed to close ${failures.length} of ${positions.length} positions: ${failures.join("; ")}`);
+        }
+        this.log(`All positions closed: ${symbols.join(", ")}`);
+    }
     handleAuthMessage(data) {
         if (data.status === "authorized") {
             this.authenticated = true;
@@ -4768,21 +4987,31 @@ class AlpacaTradingAPI {
      * @param position_intent (string) - the position intent of the order
      * @returns The created AlpacaOrder with order ID and details
      */
-    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent) {
+    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent, clientOrderId) {
         this.log(`Creating trailing stop ${side.toUpperCase()} ${qty} shares for ${symbol} with trail percent ${trailPercent100}%`, {
             symbol,
         });
+        const body = {
+            symbol,
+            qty: Math.abs(qty).toString(),
+            side,
+            position_intent,
+            order_class: "simple",
+            type: "trailing_stop",
+            trail_percent: trailPercent100.toString(), // Already in decimal form (e.g., 4 for 4%)
+            time_in_force: "gtc",
+            client_order_id: clientOrderId ??
+                this.deriveClientOrderId([
+                    "trailing_stop",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    trailPercent100,
+                ]),
+        };
         try {
-            const order = await this.makeRequest(`/orders`, "POST", {
-                symbol,
-                qty: Math.abs(qty),
-                side,
-                position_intent,
-                order_class: "simple",
-                type: "trailing_stop",
-                trail_percent: trailPercent100, // Already in decimal form (e.g., 4 for 4%)
-                time_in_force: "gtc",
-            });
+            const order = await this.makeRequest(`/orders`, "POST", body);
             this.log(`Trailing stop order created for ${symbol}: orderId=${order.id}, trailPercent=${trailPercent100}%`, { symbol });
             return order;
         }
@@ -4814,9 +5043,15 @@ class AlpacaTradingAPI {
             time_in_force: "day",
             order_class: "simple",
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "market",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -4917,16 +5152,31 @@ class AlpacaTradingAPI {
         }
     }
     /**
-     * Cancel all open orders
+     * Cancel all open orders.
+     *
+     * Alpaca's bulk cancel returns a 207 Multi-Status body whose top-level status
+     * is 2xx even when individual orders failed to cancel; this method inspects
+     * the per-order statuses and throws if any order could not be canceled, so a
+     * caller acting as a live-stop failsafe cannot record success while orders
+     * remain live. Transport/HTTP errors propagate unchanged (matching the
+     * throw-on-failure contract of {@link cancelOrder}).
+     *
+     * @throws Error if the bulk cancel request fails or any individual order
+     *   could not be canceled.
      */
     async cancelAllOrders() {
         this.log(`Canceling all open orders`);
-        try {
-            await this.makeRequest("/orders", "DELETE");
+        const results = await this.makeRequest("/orders", "DELETE");
+        if (!Array.isArray(results)) {
+            return;
         }
-        catch (error) {
-            this.log(`Error canceling all orders: ${error}`, { type: "error" });
+        const failures = this.collectMultiStatusFailures(results);
+        if (failures.length > 0) {
+            const detail = failures.join(", ");
+            this.log(`Error canceling all orders: ${failures.length}/${results.length} orders failed to cancel (${detail})`, { type: "error" });
+            throw new Error(`Failed to cancel ${failures.length} of ${results.length} orders: ${detail}`);
         }
+        this.log(`Successfully canceled ${results.length} open orders`);
     }
     /**
      * Cancel a specific order by its ID
@@ -4977,9 +5227,17 @@ class AlpacaTradingAPI {
             order_class: "simple",
             extended_hours,
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "limit",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    this.roundPriceForAlpaca(limitPrice),
+                    extended_hours,
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -5007,55 +5265,21 @@ class AlpacaTradingAPI {
                 return;
             }
             this.log(`Found ${positions.length} positions to close`);
-            // Get latest quotes for all positions
-            const symbols = positions.map((position) => position.symbol);
-            const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-            const lengthOfQuotes = Object.keys(quotesResponse.quotes).length;
-            if (lengthOfQuotes === 0) {
-                this.log("No quotes available for positions, received 0 quotes", {
-                    type: "error",
-                });
-                return;
-            }
-            if (lengthOfQuotes !== positions.length) {
-                this.log(`Received ${lengthOfQuotes} quotes for ${positions.length} positions, expected ${positions.length} quotes`, { type: "warn" });
-                return;
-            }
-            // Create limit orders to close each position
-            for (const position of positions) {
-                const quote = quotesResponse.quotes[position.symbol];
-                if (!quote) {
-                    this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                const qty = Math.abs(parseFloat(position.qty));
-                const side = position.side === "long" ? "sell" : "buy";
-                const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-                // Get the current price from the quote
-                const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-                if (!currentPrice) {
-                    this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                // Apply slippage from config
-                const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-                const limitPrice = side === "sell"
-                    ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                    : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-                this.log(`Creating limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                    symbol: position.symbol,
-                });
-                await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent);
-            }
+            // Flatten each position independently. A missing quote or broker
+            // rejection on one symbol must never abort the flatten of the others; any
+            // per-position failure is surfaced as an aggregate error.
+            await this.flattenPositionsWithLimitOrders(positions, false);
         }
         else {
-            await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            const results = await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            if (Array.isArray(results)) {
+                const failures = this.collectMultiStatusFailures(results);
+                if (failures.length > 0) {
+                    const detail = failures.join(", ");
+                    this.log(`Error closing all positions: ${failures.length}/${results.length} positions failed to close (${detail})`, { type: "error" });
+                    throw new Error(`Failed to close ${failures.length} of ${results.length} positions: ${detail}`);
+                }
+            }
         }
     }
     /**
@@ -5072,44 +5296,22 @@ class AlpacaTradingAPI {
             this.log("No positions to close");
             return;
         }
-        await this.cancelAllOrders();
-        this.log(`Cancelled all open orders`);
-        // Get latest quotes for all positions
-        const symbols = positions.map((position) => position.symbol);
-        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-        // Create limit orders to close each position
-        for (const position of positions) {
-            const quote = quotesResponse.quotes[position.symbol];
-            if (!quote) {
-                this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            const qty = Math.abs(parseFloat(position.qty));
-            const side = position.side === "long" ? "sell" : "buy";
-            const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-            // Get the current price from the quote
-            const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-            if (!currentPrice) {
-                this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            // Apply slippage from config
-            const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-            const limitPrice = side === "sell"
-                ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-            this.log(`Creating extended hours limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                symbol: position.symbol,
-            });
-            await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, true);
+        // Cancelling stale open orders is secondary to the primary failsafe goal of
+        // flattening positions. A cancel failure is logged but must not abort the
+        // flatten, otherwise a single un-cancelable order would leave every position
+        // open. The flatten step below surfaces its own aggregate failure.
+        try {
+            await this.cancelAllOrders();
+            this.log(`Cancelled all open orders`);
         }
-        this.log(`All positions closed: ${positions.map((p) => p.symbol).join(", ")}`);
+        catch (error) {
+            this.log(`Proceeding to flatten despite cancelAllOrders failure: ${error instanceof Error ? error.message : String(error)}`, { type: "error" });
+        }
+        // Flatten each position independently with extended-hours limit orders. A
+        // missing quote or broker rejection on one symbol must never silently leave
+        // the remaining positions open; per-position failures are surfaced as an
+        // aggregate error.
+        await this.flattenPositionsWithLimitOrders(positions, true);
     }
     onTradeUpdate(callback) {
         this.tradeUpdateCallback = callback;
@@ -5188,9 +5390,12 @@ class AlpacaTradingAPI {
      * @param position_intent Position intent (buy_to_open, buy_to_close, sell_to_open, sell_to_close)
      * @param type Order type (market or limit)
      * @param limitPrice Limit price (required for limit orders)
+     * @param clientOrderId Optional idempotency key; a deterministic one is
+     *   derived from the order parameters when omitted so a client-timeout retry
+     *   is de-duplicated broker-side.
      * @returns The created order
      */
-    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice) {
+    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5215,6 +5420,19 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "option",
+                    type,
+                    symbol,
+                    side,
+                    position_intent,
+                    qty,
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                ]);
         return this.makeRequest("/orders", "POST", orderData);
     }
     /**
@@ -5223,9 +5441,12 @@ class AlpacaTradingAPI {
      * @param qty Quantity of the multi-leg order (must be a whole number)
      * @param type Order type (market or limit)
      * @param limitPrice Limit price (required for limit orders)
+     * @param clientOrderId Optional idempotency key; a deterministic one is
+     *   derived from the legs and order parameters when omitted so a
+     *   client-timeout retry is de-duplicated broker-side.
      * @returns The created multi-leg order
      */
-    async createMultiLegOptionOrder(legs, qty, type, limitPrice) {
+    async createMultiLegOptionOrder(legs, qty, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5251,6 +5472,17 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "mleg",
+                    type,
+                    qty,
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                    ...legs.map((leg) => `${leg.symbol}:${leg.side}:${leg.ratio_qty}:${leg.position_intent}`),
+                ]);
         return this.makeRequest("/orders", "POST", orderData);
     }
     /**
@@ -5728,9 +5960,26 @@ class AlpacaTradingAPI {
             extended_hours: extendedHours,
             position_intent: side === "buy" ? "buy_to_open" : "sell_to_open",
         };
-        if (clientOrderId) {
-            orderData.client_order_id = clientOrderId;
-        }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "equities",
+                    orderClass,
+                    type,
+                    symbol,
+                    side,
+                    Math.abs(qty),
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                    extendedHours,
+                    useStopLoss && calculatedStopPrice !== undefined
+                        ? this.roundPriceForAlpaca(calculatedStopPrice)
+                        : undefined,
+                    useTakeProfit && calculatedTakeProfitPrice !== undefined
+                        ? this.roundPriceForAlpaca(calculatedTakeProfitPrice)
+                        : undefined,
+                ]);
         // Add limit price for limit orders
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
@@ -8406,6 +8655,13 @@ var atrNs = /*#__PURE__*/Object.freeze({
 });
 
 const ALPACA_API_BASE = MARKET_DATA_API.CRYPTO;
+/**
+ * Hard upper bound on the number of paginated news pages fetched in a single
+ * {@link fetchNews} call. Acts as a runaway-loop backstop that is independent of
+ * the caller-supplied `limit`, mirroring the max-page guard the equities
+ * paginator already enforces.
+ */
+const MAX_NEWS_PAGES = 100;
 /**
  * Fetches cryptocurrency bars for the specified parameters.
  * This function retrieves historical price data for multiple cryptocurrencies.
@@ -8505,17 +8761,25 @@ async function fetchNews(params, auth) {
         include_content: includeContent.toString(),
         limit: limit.toString(),
     });
-    const url = `${ALPACA_API_BASE}/news?${queryParams}`;
-    logIfDebug(`Fetching news from: ${url}`);
-    let newsArticles = [];
+    const authHeaders = {
+        "APCA-API-KEY-ID": auth.APIKey,
+        "APCA-API-SECRET-KEY": auth.APISecret,
+    };
+    const newsArticles = [];
     let pageToken = null;
-    let hasMorePages = true;
-    while (hasMorePages) {
+    let pageCount = 0;
+    while (pageCount < MAX_NEWS_PAGES) {
+        // Rebuild the request URL on every iteration so the pagination cursor is
+        // actually applied. Using `set` (not `append`) overwrites the previous
+        // cursor instead of accumulating stale `page_token` values across pages.
         if (pageToken) {
-            queryParams.append("page_token", pageToken);
+            queryParams.set("page_token", pageToken);
         }
+        const url = `${ALPACA_API_BASE}/news?${queryParams.toString()}`;
+        logIfDebug(`Fetching news from: ${url}`);
         await withRetry(async () => {
             const response = await fetch(url, {
+                headers: authHeaders,
                 signal: createTimeoutSignal(DEFAULT_TIMEOUTS.ALPACA_API),
             });
             if (!response.ok) {
@@ -8523,7 +8787,7 @@ async function fetchNews(params, auth) {
                 throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
             }
             const data = await response.json();
-            newsArticles = newsArticles.concat(data.news.map((article) => ({
+            const pageArticles = (data.news ?? []).map((article) => ({
                 id: article.id,
                 author: article.author,
                 content: article.content,
@@ -8535,11 +8799,17 @@ async function fetchNews(params, auth) {
                 url: article.url,
                 symbols: article.symbols,
                 images: article.images,
-            })));
+            }));
+            newsArticles.push(...pageArticles);
             pageToken = data.next_page_token ?? null;
-            hasMorePages = !!pageToken;
-            logIfDebug(`Received ${data.news.length} news articles. More pages: ${hasMorePages}`);
+            logIfDebug(`Received ${pageArticles.length} news articles. Next page token: ${pageToken ? "present" : "none"}`);
         }, API_RETRY_CONFIGS.CRYPTO, `Crypto.fetchNews(${symbol})`);
+        pageCount++;
+        // Terminate once the API reports no further pages or once we have
+        // accumulated at least the requested number of articles.
+        if (!pageToken || newsArticles.length >= limit) {
+            break;
+        }
     }
     // If sort is "asc" and limit is 10, return only the 10 most recent articles
     if (sort === "asc" && limit === 10) {
@@ -9756,33 +10026,138 @@ const formatIndicesBarData = (data) => {
 };
 
 // price-utils.ts
+// ---------------------------------------------------------------------------
+// Transaction-cost (fee) model
+//
+// Alpaca's REST order object does not expose the realized per-order fee, so the
+// transaction cost is reconstructed from the published fee schedules, branching
+// on the order's ACTUAL asset class (never a hardcoded STOCK). Every rate is a
+// named constant sourced from Alpaca / SEC / FINRA public schedules (2024-2025)
+// so it can be audited and updated in one place.
+// ---------------------------------------------------------------------------
+/** Basis points in one whole unit (1 = 10,000 bps). */
+const BPS_PER_UNIT = 10_000;
+/** Shares represented by one US listed option contract. */
+const OPTIONS_CONTRACT_MULTIPLIER = 100;
+/**
+ * SEC Section 31 fee, charged on the principal of SELL orders for equities and
+ * options. FY2024+ rate: USD 8.00 per USD 1,000,000 of principal.
+ */
+const SEC_SECTION31_FEE_PER_USD = 8.0 / 1_000_000;
+/** FINRA Trading Activity Fee (TAF) for equity sells: USD per share sold. */
+const FINRA_TAF_EQUITY_PER_SHARE = 0.000166;
+/** FINRA TAF for option sells: USD per contract sold. */
+const FINRA_TAF_OPTIONS_PER_CONTRACT = 0.00279;
+/** FINRA TAF is capped per trade regardless of size. */
+const FINRA_TAF_MAX_PER_TRADE = 8.3;
+/** OCC clearing fee per option contract, capped per trade. */
+const OCC_CLEARING_FEE_PER_CONTRACT = 0.02;
+const OCC_CLEARING_FEE_MAX_PER_TRADE = 55.0;
+/**
+ * Options Regulatory Fee (ORF) pass-through, charged on both sides, USD per
+ * contract. Published, exchange-set pass-through rate.
+ */
+const OPTIONS_REGULATORY_FEE_PER_CONTRACT = 0.02685;
+/**
+ * Alpaca crypto TAKER fee schedule as `[minTrailing30dVolumeUsd, takerBps]`,
+ * ordered ascending by volume threshold. Market orders are takers; absent a
+ * known trailing-30-day volume we conservatively select the tier-1 (highest)
+ * taker rate. Source: Alpaca Crypto fee schedule.
+ */
+const ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS = [
+    [0, 25],
+    [100_000, 22],
+    [500_000, 20],
+    [1_000_000, 18],
+    [10_000_000, 15],
+    [25_000_000, 13],
+    [50_000_000, 12],
+    [100_000_000, 10],
+];
+/**
+ * Resolve the applicable Alpaca crypto taker fee (in bps) for a trailing
+ * 30-day USD volume. Defaults to the tier-1 rate when the volume is unknown.
+ * @param trailing30dVolumeUsd - Trailing 30-day traded notional in USD.
+ * @returns The taker fee in basis points.
+ */
+function resolveCryptoTakerBps(trailing30dVolumeUsd) {
+    let bps = ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS[0][1];
+    for (const [threshold, tierBps] of ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS) {
+        if (trailing30dVolumeUsd >= threshold) {
+            bps = tierBps;
+        }
+        else {
+            break;
+        }
+    }
+    return bps;
+}
+/**
+ * Computes the realized transaction cost (fees + regulatory charges) for the
+ * Alpaca order backing a single {@link types.Action}, branching on the order's
+ * actual asset class. Returns 0 only when there is genuinely no order to price
+ * (no linked order id, order not found, or nothing filled) — never as a
+ * fabricated success.
+ * @param action - The action whose linked Alpaca order should be priced.
+ * @param trade - The parent trade (supplies the Alpaca account id).
+ * @param alpacaAccount - The Alpaca account supplying broker credentials.
+ * @returns The total fee in account currency (USD).
+ */
 const calculateFees = async (action, trade, alpacaAccount) => {
-    let fee = 0;
     const alpacaOrderId = action.alpacaOrderId;
     if (!alpacaOrderId)
-        return fee;
+        return 0;
     const order = await getOrder$1({
         adapticAccountId: trade.alpacaAccountId,
         alpacaApiKey: alpacaAccount.APIKey,
         alpacaApiSecret: alpacaAccount.APISecret,
     }, alpacaOrderId);
     if (!order)
-        return fee;
-    const assetType = "STOCK";
-    Number(order.qty) || 0;
-    order.notional || 0;
-    Number(order.filled_avg_price || order.limit_price || order.stop_price) ||
+        return 0;
+    const filledQty = Number(order.filled_qty) || 0;
+    const filledPrice = Number(order.filled_avg_price ?? order.limit_price ?? order.stop_price) ||
         0;
-    switch (assetType) {
-        case "STOCK":
-            // Currently zero fees for stocks via Alpaca
-            fee = 0;
-            break;
-        default:
-            fee = 0;
-            break;
+    // Realized notional prefers the actual fill (qty * avg price); it falls back
+    // to the order's notional field for dollar-notional (fractional) orders.
+    const notional = filledQty > 0 && filledPrice > 0
+        ? filledQty * filledPrice
+        : Number(order.notional ?? 0) || 0;
+    if (notional <= 0)
+        return 0;
+    const isSell = order.side === "sell";
+    switch (order.asset_class) {
+        case "crypto": {
+            // Crypto fees are bps of notional. Without a known 30-day volume we use
+            // the conservative tier-1 taker rate.
+            const takerBps = resolveCryptoTakerBps(0);
+            return (notional * takerBps) / BPS_PER_UNIT;
+        }
+        case "us_option": {
+            const contracts = filledQty > 0 ? filledQty : Number(order.qty) || 0;
+            const occFee = Math.min(contracts * OCC_CLEARING_FEE_PER_CONTRACT, OCC_CLEARING_FEE_MAX_PER_TRADE);
+            const orfFee = contracts * OPTIONS_REGULATORY_FEE_PER_CONTRACT;
+            let fee = occFee + orfFee;
+            if (isSell) {
+                // Option premium is quoted per share; SEC fee applies to the full
+                // principal (premium * contract multiplier).
+                const optionPrincipal = notional * OPTIONS_CONTRACT_MULTIPLIER;
+                const secFee = optionPrincipal * SEC_SECTION31_FEE_PER_USD;
+                const taf = Math.min(contracts * FINRA_TAF_OPTIONS_PER_CONTRACT, FINRA_TAF_MAX_PER_TRADE);
+                fee += secFee + taf;
+            }
+            return fee;
+        }
+        case "us_equity":
+        default: {
+            // Alpaca charges USD 0 commission on US equities; only sell-side
+            // regulatory charges (SEC Section 31 + FINRA TAF) apply.
+            if (!isSell)
+                return 0;
+            const secFee = notional * SEC_SECTION31_FEE_PER_USD;
+            const taf = Math.min(filledQty * FINRA_TAF_EQUITY_PER_SHARE, FINRA_TAF_MAX_PER_TRADE);
+            return secFee + taf;
+        }
     }
-    return fee;
 };
 const computeTotalFees = async (trade) => {
     let totalFees = 0;
@@ -10651,16 +11026,76 @@ async function calculateExpenseRatio({ accountId, client, alpacaAccount, }) {
         return "N/A";
     }
     const equity = parseFloat(accountDetails.equity);
-    // Fetch portfolio expenses from your system (Assuming you have this data)
-    const expenses = await getPortfolioExpensesFromYourSystem();
-    // Calculate expense ratio
+    // Fetch the account's real trailing fee expenses from Alpaca account
+    // activities. A genuine data-source failure yields "N/A" (unknown) rather
+    // than a fabricated 0.00%.
+    const auth = {
+        adapticAccountId: alpacaAccountId,
+        alpacaApiKey: alpacaAccount?.APIKey,
+        alpacaApiSecret: alpacaAccount?.APISecret,
+    };
+    let expenses;
+    try {
+        expenses = await fetchTrailingFeeExpenses(auth);
+    }
+    catch (error) {
+        getLogger().warn("Failed to fetch Alpaca account fee activities for expense ratio.", { error });
+        return "N/A";
+    }
+    // Calculate expense ratio (trailing fees as a percentage of current equity).
     const expenseRatio = (expenses / equity) * 100;
     return `${expenseRatio.toFixed(2)}%`;
 }
-// Mock function to represent fetching expenses from your system
-async function getPortfolioExpensesFromYourSystem(_accountId) {
-    // Implement this function based on your data storage
-    return 0; // Placeholder
+/** Trailing window over which account fees are aggregated for the expense ratio. */
+const EXPENSE_TRAILING_WINDOW_DAYS = 365;
+/** Milliseconds in one day. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Alpaca account-activity types that represent fees/regulatory charges. */
+const FEE_ACTIVITY_TYPES = "FEE,REG,CFEE";
+/** Page size for the paginated Alpaca account-activities endpoint. */
+const ACTIVITIES_PAGE_SIZE = 100;
+/** Hard cap on activity pages to bound pagination on unexpected responses. */
+const ACTIVITIES_MAX_PAGES = 1000;
+/**
+ * Aggregates the account's fee/regulatory charges over the trailing window from
+ * the Alpaca account-activities endpoint, following id-based pagination.
+ * @param auth - Alpaca authentication (account id and/or direct API keys).
+ * @returns Total fees in account currency (USD) as a positive number.
+ */
+async function fetchTrailingFeeExpenses(auth) {
+    const after = new Date(Date.now() - EXPENSE_TRAILING_WINDOW_DAYS * MS_PER_DAY).toISOString();
+    let total = 0;
+    let pageToken;
+    for (let page = 0; page < ACTIVITIES_MAX_PAGES; page++) {
+        const queryParams = new URLSearchParams({
+            activity_types: FEE_ACTIVITY_TYPES,
+            after,
+            page_size: String(ACTIVITIES_PAGE_SIZE),
+        });
+        if (pageToken) {
+            queryParams.append("page_token", pageToken);
+        }
+        const activities = await makeRequest(auth, {
+            endpoint: "/account/activities",
+            method: "GET",
+            queryString: `?${queryParams.toString()}`,
+        });
+        if (!Array.isArray(activities) || activities.length === 0) {
+            break;
+        }
+        for (const activity of activities) {
+            const amount = parseFloat(activity.net_amount ?? "");
+            if (Number.isFinite(amount)) {
+                // Fee entries are debits (negative net_amount); accumulate magnitude.
+                total += Math.abs(amount);
+            }
+        }
+        if (activities.length < ACTIVITIES_PAGE_SIZE) {
+            break;
+        }
+        pageToken = activities[activities.length - 1].id;
+    }
+    return total;
 }
 /**
  * Calculates the liquidity ratio for a given Alpaca account.
@@ -11320,6 +11755,58 @@ async function calculateInformationRatio(portfolioHistory, benchmarkBars) {
     }
     return informationRatio.toFixed(4);
 }
+/**
+ * Maps a portfolio-history timeframe token to the Alpaca market-data
+ * {@link TimeFrame} accepted by the historical-bars endpoint. Benchmark
+ * comparison is daily by default when no timeframe is supplied.
+ * @param timeframe - The portfolio-history timeframe token.
+ * @returns The equivalent Alpaca market-data timeframe.
+ */
+function toAlpacaTimeFrame(timeframe) {
+    switch (timeframe) {
+        case "1Min":
+            return "1Min";
+        case "5Min":
+            return "5Min";
+        case "15Min":
+            return "15Min";
+        case "1H":
+            return "1Hour";
+        case "1D":
+            return "1Day";
+        default:
+            return "1Day";
+    }
+}
+/** Milliseconds per second, for RFC-3339 → Unix-second conversion. */
+const MS_PER_SECOND = 1000;
+/**
+ * Fetches benchmark OHLCV bars from the wrapped Alpaca market-data vendor and
+ * maps them into {@link BenchmarkBar}s (Unix-second timestamp + close price)
+ * expected by the alpha/beta/information-ratio calculators.
+ * @param request - Benchmark symbol, RFC-3339 start/end, and timeframe token.
+ * @returns The benchmark bars, sorted ascending by time; empty if none.
+ */
+async function fetchBenchmarkBars(request) {
+    const { symbol, start, end, timeframe } = request;
+    const response = await marketDataAPI.getHistoricalBars({
+        symbols: [symbol],
+        timeframe: toAlpacaTimeFrame(timeframe),
+        start,
+        end,
+        sort: "asc",
+    });
+    const bars = response.bars[symbol];
+    if (!Array.isArray(bars) || bars.length === 0) {
+        return [];
+    }
+    return bars
+        .map((bar) => ({
+        t: Math.floor(new Date(bar.t).getTime() / MS_PER_SECOND),
+        c: bar.c,
+    }))
+        .filter((bar) => Number.isFinite(bar.t) && Number.isFinite(bar.c));
+}
 /**
  * Fetches performance metrics for a given Alpaca account.
  * @param params - The parameters for fetching performance metrics.
@@ -11384,7 +11871,10 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
             getLogger().error("[fetchPerformanceMetrics] Error fetching portfolio history:", error);
             throw new Error("Failed to retrieve portfolio history data");
         }
-        // Fetch benchmark data with enhanced error handling
+        // Fetch benchmark data directly from the wrapped Alpaca market-data vendor.
+        // (Previously this hit a relative "/api/market-data/historical-prices"
+        // Next.js route that only resolves in a browser; in a Node/engine runtime
+        // the relative fetch always threw, silently zeroing out alpha/beta/IR.)
         const benchmarkSymbol = "SPY";
         let benchmarkBars = [];
         try {
@@ -11395,24 +11885,16 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
                     : params?.period
                         ? params?.period
                         : "1Y",
-                outputFormat: "unix-ms",
+                outputFormat: "iso",
                 intraday_reporting: params?.intraday_reporting,
             });
-            const response = await fetch(`/api/market-data/historical-prices?symbol=${benchmarkSymbol}&start=${start.toString()}&end=${end.toString()}&timeframe=${params.timeframe}`, {
-                method: "GET",
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                signal: createTimeoutSignal(DEFAULT_TIMEOUTS.GENERAL),
+            benchmarkBars = await fetchBenchmarkBars({
+                symbol: benchmarkSymbol,
+                start: String(start),
+                end: String(end),
+                timeframe: params.timeframe,
             });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new Error(`Failed to fetch benchmark data: ${response.statusText} - ${errorText}`);
-            }
-            benchmarkBars = await response.json();
-            if (!benchmarkBars ||
-                !Array.isArray(benchmarkBars) ||
-                benchmarkBars.length === 0) {
+            if (benchmarkBars.length === 0) {
                 throw new Error("Received empty or invalid benchmark data");
             }
         }
@@ -14079,17 +14561,17 @@ var hasRequiredBrowser;
 function requireBrowser () {
 	if (hasRequiredBrowser) return browser.exports;
 	hasRequiredBrowser = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		/**
 		 * This is the web browser implementation of `debug()`.
 		 */
 
-		exports.formatArgs = formatArgs;
-		exports.save = save;
-		exports.load = load;
-		exports.useColors = useColors;
-		exports.storage = localstorage();
-		exports.destroy = (() => {
+		exports$1.formatArgs = formatArgs;
+		exports$1.save = save;
+		exports$1.load = load;
+		exports$1.useColors = useColors;
+		exports$1.storage = localstorage();
+		exports$1.destroy = (() => {
 			let warned = false;
 
 			return () => {
@@ -14104,7 +14586,7 @@ function requireBrowser () {
 		 * Colors.
 		 */
 
-		exports.colors = [
+		exports$1.colors = [
 			'#0000CC',
 			'#0000FF',
 			'#0033CC',
@@ -14269,7 +14751,7 @@ function requireBrowser () {
 		 *
 		 * @api public
 		 */
-		exports.log = console.debug || console.log || (() => {});
+		exports$1.log = console.debug || console.log || (() => {});
 
 		/**
 		 * Save `namespaces`.
@@ -14280,9 +14762,9 @@ function requireBrowser () {
 		function save(namespaces) {
 			try {
 				if (namespaces) {
-					exports.storage.setItem('debug', namespaces);
+					exports$1.storage.setItem('debug', namespaces);
 				} else {
-					exports.storage.removeItem('debug');
+					exports$1.storage.removeItem('debug');
 				}
 			} catch (error) {
 				// Swallow
@@ -14299,7 +14781,7 @@ function requireBrowser () {
 		function load() {
 			let r;
 			try {
-				r = exports.storage.getItem('debug') || exports.storage.getItem('DEBUG') ;
+				r = exports$1.storage.getItem('debug') || exports$1.storage.getItem('DEBUG') ;
 			} catch (error) {
 				// Swallow
 				// XXX (@Qix-) should we be logging these?
@@ -14335,7 +14817,7 @@ function requireBrowser () {
 			}
 		}
 
-		module.exports = requireCommon()(exports);
+		module.exports = requireCommon()(exports$1);
 
 		const {formatters} = module.exports;
 
@@ -14524,7 +15006,7 @@ var hasRequiredNode$1;
 function requireNode$1 () {
 	if (hasRequiredNode$1) return node$1.exports;
 	hasRequiredNode$1 = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		const tty = require$$1$1;
 		const util = require$$1$2;
 
@@ -14532,13 +15014,13 @@ function requireNode$1 () {
 		 * This is the Node.js implementation of `debug()`.
 		 */
 
-		exports.init = init;
-		exports.log = log;
-		exports.formatArgs = formatArgs;
-		exports.save = save;
-		exports.load = load;
-		exports.useColors = useColors;
-		exports.destroy = util.deprecate(
+		exports$1.init = init;
+		exports$1.log = log;
+		exports$1.formatArgs = formatArgs;
+		exports$1.save = save;
+		exports$1.load = load;
+		exports$1.useColors = useColors;
+		exports$1.destroy = util.deprecate(
 			() => {},
 			'Instance method `debug.destroy()` is deprecated and no longer does anything. It will be removed in the next major version of `debug`.'
 		);
@@ -14547,7 +15029,7 @@ function requireNode$1 () {
 		 * Colors.
 		 */
 
-		exports.colors = [6, 2, 3, 4, 5, 1];
+		exports$1.colors = [6, 2, 3, 4, 5, 1];
 
 		try {
 			// Optional dependency (as in, doesn't need to be installed, NOT like optionalDependencies in package.json)
@@ -14555,7 +15037,7 @@ function requireNode$1 () {
 			const supportsColor = requireSupportsColor();
 
 			if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
-				exports.colors = [
+				exports$1.colors = [
 					20,
 					21,
 					26,
@@ -14644,7 +15126,7 @@ function requireNode$1 () {
 		 *   $ DEBUG_COLORS=no DEBUG_DEPTH=10 DEBUG_SHOW_HIDDEN=enabled node script.js
 		 */
 
-		exports.inspectOpts = Object.keys(process.env).filter(key => {
+		exports$1.inspectOpts = Object.keys(process.env).filter(key => {
 			return /^debug_/i.test(key);
 		}).reduce((obj, key) => {
 			// Camel-case
@@ -14676,8 +15158,8 @@ function requireNode$1 () {
 		 */
 
 		function useColors() {
-			return 'colors' in exports.inspectOpts ?
-				Boolean(exports.inspectOpts.colors) :
+			return 'colors' in exports$1.inspectOpts ?
+				Boolean(exports$1.inspectOpts.colors) :
 				tty.isatty(process.stderr.fd);
 		}
 
@@ -14703,7 +15185,7 @@ function requireNode$1 () {
 		}
 
 		function getDate() {
-			if (exports.inspectOpts.hideDate) {
+			if (exports$1.inspectOpts.hideDate) {
 				return '';
 			}
 			return new Date().toISOString() + ' ';
@@ -14714,7 +15196,7 @@ function requireNode$1 () {
 		 */
 
 		function log(...args) {
-			return process.stderr.write(util.formatWithOptions(exports.inspectOpts, ...args) + '\n');
+			return process.stderr.write(util.formatWithOptions(exports$1.inspectOpts, ...args) + '\n');
 		}
 
 		/**
@@ -14754,13 +15236,13 @@ function requireNode$1 () {
 		function init(debug) {
 			debug.inspectOpts = {};
 
-			const keys = Object.keys(exports.inspectOpts);
+			const keys = Object.keys(exports$1.inspectOpts);
 			for (let i = 0; i < keys.length; i++) {
-				debug.inspectOpts[keys[i]] = exports.inspectOpts[keys[i]];
+				debug.inspectOpts[keys[i]] = exports$1.inspectOpts[keys[i]];
 			}
 		}
 
-		module.exports = requireCommon()(exports);
+		module.exports = requireCommon()(exports$1);
 
 		const {formatters} = module.exports;
 
@@ -15334,7 +15816,7 @@ function requireFollowRedirects () {
 	// Wraps the key/value object of protocols with redirect functionality
 	function wrap(protocols) {
 	  // Default settings
-	  var exports = {
+	  var exports$1 = {
 	    maxRedirects: 21,
 	    maxBodyLength: 10 * 1024 * 1024,
 	  };
@@ -15344,7 +15826,7 @@ function requireFollowRedirects () {
 	  Object.keys(protocols).forEach(function (scheme) {
 	    var protocol = scheme + ":";
 	    var nativeProtocol = nativeProtocols[protocol] = protocols[scheme];
-	    var wrappedProtocol = exports[scheme] = Object.create(nativeProtocol);
+	    var wrappedProtocol = exports$1[scheme] = Object.create(nativeProtocol);
 
 	    // Executes a request, following redirects
 	    function request(input, options, callback) {
@@ -15367,8 +15849,8 @@ function requireFollowRedirects () {
 
 	      // Set defaults
 	      options = Object.assign({
-	        maxRedirects: exports.maxRedirects,
-	        maxBodyLength: exports.maxBodyLength,
+	        maxRedirects: exports$1.maxRedirects,
+	        maxBodyLength: exports$1.maxBodyLength,
 	      }, input, options);
 	      options.nativeProtocols = nativeProtocols;
 	      if (!isString(options.host) && !isString(options.hostname)) {
@@ -15393,7 +15875,7 @@ function requireFollowRedirects () {
 	      get: { value: get, configurable: true, enumerable: true, writable: true },
 	    });
 	  });
-	  return exports;
+	  return exports$1;
 	}
 
 	function noop() { /* empty */ }
@@ -16999,7 +17481,7 @@ var hasRequiredLodash;
 function requireLodash () {
 	if (hasRequiredLodash) return lodash$1.exports;
 	hasRequiredLodash = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 (function() {
 
 		  /** Used as a safe reference for `undefined` in pre-ES5 environments. */
@@ -17430,7 +17912,7 @@ function requireLodash () {
 		  var root = freeGlobal || freeSelf || Function('return this')();
 
 		  /** Detect free variable `exports`. */
-		  var freeExports = exports && !exports.nodeType && exports;
+		  var freeExports = exports$1 && !exports$1.nodeType && exports$1;
 
 		  /** Detect free variable `module`. */
 		  var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -35260,12 +35742,12 @@ var hasRequiredIsBuffer;
 function requireIsBuffer () {
 	if (hasRequiredIsBuffer) return isBuffer.exports;
 	hasRequiredIsBuffer = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		var root = require_root(),
 		    stubFalse = requireStubFalse();
 
 		/** Detect free variable `exports`. */
-		var freeExports = exports && !exports.nodeType && exports;
+		var freeExports = exports$1 && !exports$1.nodeType && exports$1;
 
 		/** Detect free variable `module`. */
 		var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -35485,11 +35967,11 @@ var hasRequired_nodeUtil;
 function require_nodeUtil () {
 	if (hasRequired_nodeUtil) return _nodeUtil.exports;
 	hasRequired_nodeUtil = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		var freeGlobal = require_freeGlobal();
 
 		/** Detect free variable `exports`. */
-		var freeExports = exports && !exports.nodeType && exports;
+		var freeExports = exports$1 && !exports$1.nodeType && exports$1;
 
 		/** Detect free variable `module`. */
 		var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -44411,7 +44893,7 @@ var hasRequiredSafeBuffer;
 function requireSafeBuffer () {
 	if (hasRequiredSafeBuffer) return safeBuffer.exports;
 	hasRequiredSafeBuffer = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		/* eslint-disable node/no-deprecated-api */
 		var buffer = require$$0$5;
 		var Buffer = buffer.Buffer;
@@ -44426,8 +44908,8 @@ function requireSafeBuffer () {
 		  module.exports = buffer;
 		} else {
 		  // Copy properties from require('buffer')
-		  copyProps(buffer, exports);
-		  exports.Buffer = SafeBuffer;
+		  copyProps(buffer, exports$1);
+		  exports$1.Buffer = SafeBuffer;
 		}
 
 		function SafeBuffer (arg, encodingOrOffset, length) {
@@ -47625,22 +48107,22 @@ var hasRequiredReadable;
 function requireReadable () {
 	if (hasRequiredReadable) return readable.exports;
 	hasRequiredReadable = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		var Stream = require$$0$3;
 		if (process.env.READABLE_STREAM === 'disable' && Stream) {
 		  module.exports = Stream.Readable;
 		  Object.assign(module.exports, Stream);
 		  module.exports.Stream = Stream;
 		} else {
-		  exports = module.exports = require_stream_readable();
-		  exports.Stream = Stream || exports;
-		  exports.Readable = exports;
-		  exports.Writable = require_stream_writable();
-		  exports.Duplex = require_stream_duplex();
-		  exports.Transform = require_stream_transform();
-		  exports.PassThrough = require_stream_passthrough();
-		  exports.finished = requireEndOfStream();
-		  exports.pipeline = requirePipeline();
+		  exports$1 = module.exports = require_stream_readable();
+		  exports$1.Stream = Stream || exports$1;
+		  exports$1.Readable = exports$1;
+		  exports$1.Writable = require_stream_writable();
+		  exports$1.Duplex = require_stream_duplex();
+		  exports$1.Transform = require_stream_transform();
+		  exports$1.PassThrough = require_stream_passthrough();
+		  exports$1.finished = requireEndOfStream();
+		  exports$1.pipeline = requirePipeline();
 		} 
 	} (readable, readable.exports));
 	return readable.exports;
@@ -49075,12 +49557,12 @@ var hasRequiredWebsocket;
 function requireWebsocket () {
 	if (hasRequiredWebsocket) return websocket$1;
 	hasRequiredWebsocket = 1;
-	(function (exports) {
+	(function (exports$1) {
 		var __importDefault = (websocket$1 && websocket$1.__importDefault) || function (mod) {
 		    return (mod && mod.__esModule) ? mod : { "default": mod };
 		};
-		Object.defineProperty(exports, "__esModule", { value: true });
-		exports.AlpacaWebsocket = exports.ERROR = exports.CONN_ERROR = exports.EVENT = exports.STATE = void 0;
+		Object.defineProperty(exports$1, "__esModule", { value: true });
+		exports$1.AlpacaWebsocket = exports$1.ERROR = exports$1.CONN_ERROR = exports$1.EVENT = exports$1.STATE = void 0;
 		const events_1 = __importDefault(require$$0$4);
 		const ws_1 = __importDefault(requireWs());
 		const msgpack5_1 = __importDefault(requireMsgpack5());
@@ -49094,7 +49576,7 @@ function requireWebsocket () {
 		    STATE["DISCONNECTED"] = "disconnected";
 		    STATE["WAITING_TO_CONNECT"] = "waiting to connect";
 		    STATE["WAITING_TO_RECONNECT"] = "waiting to reconnect";
-		})(STATE || (exports.STATE = STATE = {}));
+		})(STATE || (exports$1.STATE = STATE = {}));
 		// Client events
 		var EVENT;
 		(function (EVENT) {
@@ -49113,9 +49595,9 @@ function requireWebsocket () {
 		    EVENT["CORRECTIONS"] = "corrections";
 		    EVENT["ORDERBOOKS"] = "orderbooks";
 		    EVENT["NEWS"] = "news";
-		})(EVENT || (exports.EVENT = EVENT = {}));
+		})(EVENT || (exports$1.EVENT = EVENT = {}));
 		// Connection errors by code
-		exports.CONN_ERROR = new Map([
+		exports$1.CONN_ERROR = new Map([
 		    [400, "invalid syntax"],
 		    [401, "not authenticated"],
 		    [402, "auth failed"],
@@ -49134,7 +49616,7 @@ function requireWebsocket () {
 		    ERROR["MISSING_SECERT_KEY"] = "missing secret key";
 		    ERROR["MISSING_API_KEY"] = "missing api key";
 		    ERROR["UNEXPECTED_MESSAGE"] = "unexpected message";
-		})(ERROR || (exports.ERROR = ERROR = {}));
+		})(ERROR || (exports$1.ERROR = ERROR = {}));
 		class AlpacaWebsocket extends events_1.default.EventEmitter {
 		    constructor(options) {
 		        super();
@@ -49291,7 +49773,7 @@ function requireWebsocket () {
 		                this.updateSubscriptions(data[0]);
 		                break;
 		            case "error":
-		                this.emit(EVENT.CLIENT_ERROR, exports.CONN_ERROR.get(data[0].code));
+		                this.emit(EVENT.CLIENT_ERROR, exports$1.CONN_ERROR.get(data[0].code));
 		                break;
 		            default:
 		                this.dataHandler(data);
@@ -49320,7 +49802,7 @@ function requireWebsocket () {
 		        }
 		    }
 		}
-		exports.AlpacaWebsocket = AlpacaWebsocket; 
+		exports$1.AlpacaWebsocket = AlpacaWebsocket; 
 	} (websocket$1));
 	return websocket$1;
 }
@@ -49954,8 +50436,8 @@ var hasRequiredWebsockets;
 function requireWebsockets () {
 	if (hasRequiredWebsockets) return websockets;
 	hasRequiredWebsockets = 1;
-	(function (exports) {
-		Object.defineProperty(exports, "__esModule", { value: true });
+	(function (exports$1) {
+		Object.defineProperty(exports$1, "__esModule", { value: true });
 		const events = require$$0$4;
 		const WebSocket = requireWs();
 		const entity = requireEntity();
@@ -49970,7 +50452,7 @@ function requireWebsockets () {
 		    STATE.DISCONNECTED = "disconnected";
 		    STATE.WAITING_TO_CONNECT = "waiting to connect";
 		    STATE.WAITING_TO_RECONNECT = "waiting to reconnect";
-		})((STATE = exports.STATE || (exports.STATE = {})));
+		})((STATE = exports$1.STATE || (exports$1.STATE = {})));
 		// Client events
 		var EVENT;
 		(function (EVENT) {
@@ -49984,7 +50466,7 @@ function requireWebsockets () {
 		    EVENT.STOCK_QUOTES = "stock_quotes";
 		    EVENT.STOCK_AGG_SEC = "stock_agg_sec";
 		    EVENT.STOCK_AGG_MIN = "stock_agg_min";
-		})((EVENT = exports.EVENT || (exports.EVENT = {})));
+		})((EVENT = exports$1.EVENT || (exports$1.EVENT = {})));
 		// Connection errors Each of these will also emit EVENT.ERROR
 		var ERROR;
 		(function (ERROR) {
@@ -49993,7 +50475,7 @@ function requireWebsockets () {
 		    ERROR.MISSING_API_KEY = "missing api key";
 		    ERROR.MISSING_SECRET_KEY = "missing secret key";
 		    ERROR.UNKNOWN = "unknown error";
-		})((ERROR = exports.ERROR || (exports.ERROR = {})));
+		})((ERROR = exports$1.ERROR || (exports$1.ERROR = {})));
 		/**
 		 * AlpacaStreamClient manages a connection to Alpaca's websocket api
 		 */
@@ -50306,7 +50788,7 @@ function requireWebsockets () {
 		        }
 		    }
 		}
-		exports.AlpacaStreamClient = AlpacaStreamClient; 
+		exports$1.AlpacaStreamClient = AlpacaStreamClient; 
 	} (websockets));
 	return websockets;
 }
@@ -50558,13 +51040,13 @@ var hasRequiredDist;
 function requireDist () {
 	if (hasRequiredDist) return dist$1.exports;
 	hasRequiredDist = 1;
-	(function (module, exports) {
+	(function (module, exports$1) {
 		var __importDefault = (dist && dist.__importDefault) || function (mod) {
 		    return (mod && mod.__esModule) ? mod : { "default": mod };
 		};
-		Object.defineProperty(exports, "__esModule", { value: true });
+		Object.defineProperty(exports$1, "__esModule", { value: true });
 		const alpaca_trade_api_1 = __importDefault(requireAlpacaTradeApi());
-		exports.default = alpaca_trade_api_1.default;
+		exports$1.default = alpaca_trade_api_1.default;
 		module.exports = alpaca_trade_api_1.default; 
 	} (dist$1, dist$1.exports));
 	return dist$1.exports;
@@ -62673,6 +63155,7 @@ class StampedeProtectedCache {
         coalescedRequests: 0,
         backgroundRefreshes: 0,
         refreshErrors: 0,
+        loadTimeouts: 0,
     };
     constructor(options) {
         this.options = {
@@ -62946,6 +63429,7 @@ class StampedeProtectedCache {
             coalescedRequests: this.stats.coalescedRequests,
             backgroundRefreshes: this.stats.backgroundRefreshes,
             refreshErrors: this.stats.refreshErrors,
+            loadTimeouts: this.stats.loadTimeouts,
         };
     }
     /**
@@ -62996,8 +63480,9 @@ class StampedeProtectedCache {
             this.options.logger.debug("Request coalesced", { key });
             return existingPromise;
         }
-        // Create new promise and store it
-        const promise = this.loadAndCache(key, loader, ttl);
+        // Create new promise and store it — bounded by loadTimeoutMs so a
+        // never-settling loader cannot pin the key (see loadWithTimeout).
+        const promise = this.loadWithTimeout(key, loader, ttl);
         this.pendingRefreshes.set(key, promise);
         try {
             const result = await promise;
@@ -63008,6 +63493,51 @@ class StampedeProtectedCache {
             this.pendingRefreshes.delete(key);
         }
     }
+    /**
+     * Race {@link loadAndCache} against the configured load timeout.
+     *
+     * On timeout: rejects with a typed timeout error, evicts the pending
+     * single-flight entry so the NEXT caller retries with a fresh loader
+     * (instead of coalescing onto the hung one), and attaches a settlement
+     * observer to the abandoned loader so its eventual resolution/rejection
+     * is logged rather than surfacing as an unhandled rejection.
+     */
+    async loadWithTimeout(key, loader, ttl) {
+        const timeoutMs = this.options.loadTimeoutMs ?? 30000;
+        const loadPromise = this.loadAndCache(key, loader, ttl);
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                this.stats.loadTimeouts++;
+                // Evict the pin so the next caller retries fresh.
+                this.pendingRefreshes.delete(key);
+                this.options.logger.warn("Cache loader timed out — pin evicted", {
+                    key,
+                    timeoutMs,
+                });
+                // Observe the abandoned loader; never let it become unhandled.
+                loadPromise
+                    .then(() => {
+                    this.options.logger.warn("Abandoned cache loader eventually resolved", { key });
+                })
+                    .catch((error) => {
+                    this.options.logger.warn("Abandoned cache loader eventually rejected", {
+                        key,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                reject(new Error(`StampedeProtectedCache loader timed out after ${timeoutMs}ms for key "${key}"`));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([loadPromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutHandle !== undefined) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
     /**
      * Load data and cache it
      */
@@ -63157,6 +63687,7 @@ const DEFAULT_CACHE_OPTIONS = {
     minJitter: 0.9, // 90%
     maxJitter: 1.1, // 110%
     enableBackgroundRefresh: true,
+    loadTimeoutMs: 30000, // 30s hard loader ceiling (anti-pinning)
 };
 
 /**