@reefclaw/openclaw-plugin 0.1.12 → 0.1.14

package/venues/hyperliquid/hl-order.d.ts

@@ -0,0 +1,35 @@
+import type { CcxtOrder } from '../../types.js';
+/**
+ * Collapse HL/ccxt order-type strings into the declared `'market' | 'limit'`
+ * union. HL order types are all execution-styles of one of the two: anything
+ * containing "market" ('Market', 'Stop Market', 'Take Profit Market') executes
+ * as a market when it goes; everything else — including a missing type, which
+ * only occurs on RESTING rows (a market order never rests) — is a limit.
+ * The raw subtype stays readable at `info.orderType`.
+ */
+export declare function normalizeHlOrderType(raw: unknown): 'market' | 'limit';
+/**
+ * Collapse order statuses into `'open' | 'closed' | 'canceled'`.
+ *
+ * ccxt's parseOrderStatus already maps filled→closed, triggered→open,
+ * marginCanceled/liquidatedCanceled→canceled — but lets 'rejected' (and any
+ * future HL status) through verbatim. Directional rule for the residue:
+ *   - 'rejected' and any '*canceled' variant → 'canceled' (positively terminal,
+ *     nothing was or will be executed);
+ *   - 'filled' → 'closed' (in case a raw status bypasses ccxt's map);
+ *   - anything UNKNOWN → 'open' + WARN. 'open' is the conservative direction on
+ *     both consumer classes: destructive bracket decisions treat the leg as
+ *     still live (never "gone" on a guess — the null≠empty doctrine), and the
+ *     entry-order poller just keeps polling into its own timeout.
+ */
+export declare function normalizeHlOrderStatus(raw: unknown): 'open' | 'closed' | 'canceled';
+/**
+ * Normalize one ccxt HL order into a contract-compliant `CcxtOrder`.
+ *
+ * Unlike positions (where a fabricated number is a risk-limit hazard and an
+ * unpriceable row nulls the snapshot), an order row is never dropped: the
+ * fields we default (fee 0, cost from average×filled) are display/accounting
+ * conveniences, while the fields decisions hang on (id, cloid, status, info)
+ * are passed through or conservatively mapped.
+ */
+export declare function normalizeHlOrder(raw: CcxtOrder, nowMs?: number): CcxtOrder;

package/venues/hyperliquid/hl-order.js

@@ -0,0 +1,123 @@
+// Hyperliquid order normalization — brings ccxt's HL order rows up to the
+// `CcxtOrder` contract, the sibling of hl-position.ts (see its header for the
+// class of bug: ccxt emits fields our types declare required as undefined, and
+// TypeScript never checks runtime shapes).
+//
+// What ccxt@4.5.x's hyperliquid `parseOrder` actually emits (verified offline
+// against the real parser, 2026-07-26, surfaced by hl-venue-conformance.test.ts):
+//   - `cost: undefined`, `fee: undefined` (HL carries fees on FILLS only, never
+//     on order objects) — our contract requires both.
+//   - `type: 'take profit market'` / `'take profit limit'` pass straight through
+//     `parseOrderType` (only 'stop limit'/'stop market' are mapped) — outside
+//     our `'market' | 'limit'` union. A resting limit with no `orderType` field
+//     yields `type: undefined`.
+//   - `status: 'rejected'` survives `parseOrderStatus` — outside our
+//     `'open' | 'closed' | 'canceled'` union.
+//   - `average: undefined`, `timeInForce: undefined` on trigger legs.
+//
+// ★ SCOPE: READ paths only (`fetchOpenOrders`, `fetchOrder`). Submit-path
+//   responses (`submitOrder`/`submitOrders`) are deliberately NOT normalized —
+//   `HlBracketCoordinator.isRejectedOrder` keys on the raw `status: 'rejected'`
+//   sentinel there, and blurring it into 'canceled' would break per-item batch
+//   rejection detection.
+//
+// ★ WHAT MUST SURVIVE VERBATIM: `info` (skill-side protective classification
+//   reads `info.orderType` — 'Take Profit Market' etc — via isProtectiveOrder/
+//   classifyProtectiveRole) and `clientOrderId` (bracket reconciliation parses
+//   the cloid). The conformance suite pins both.
+import { logger } from '../../logger.js';
+const TAG = 'hl-order';
+/** HL's settlement asset — the only fee currency on this venue. */
+const HL_FEE_CURRENCY = 'USDC';
+/** Finite number or undefined — never NaN, never a silent 0. */
+function fin(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Collapse HL/ccxt order-type strings into the declared `'market' | 'limit'`
+ * union. HL order types are all execution-styles of one of the two: anything
+ * containing "market" ('Market', 'Stop Market', 'Take Profit Market') executes
+ * as a market when it goes; everything else — including a missing type, which
+ * only occurs on RESTING rows (a market order never rests) — is a limit.
+ * The raw subtype stays readable at `info.orderType`.
+ */
+export function normalizeHlOrderType(raw) {
+    const t = String(raw ?? '').toLowerCase();
+    return t.includes('market') ? 'market' : 'limit';
+}
+/**
+ * Collapse order statuses into `'open' | 'closed' | 'canceled'`.
+ *
+ * ccxt's parseOrderStatus already maps filled→closed, triggered→open,
+ * marginCanceled/liquidatedCanceled→canceled — but lets 'rejected' (and any
+ * future HL status) through verbatim. Directional rule for the residue:
+ *   - 'rejected' and any '*canceled' variant → 'canceled' (positively terminal,
+ *     nothing was or will be executed);
+ *   - 'filled' → 'closed' (in case a raw status bypasses ccxt's map);
+ *   - anything UNKNOWN → 'open' + WARN. 'open' is the conservative direction on
+ *     both consumer classes: destructive bracket decisions treat the leg as
+ *     still live (never "gone" on a guess — the null≠empty doctrine), and the
+ *     entry-order poller just keeps polling into its own timeout.
+ */
+export function normalizeHlOrderStatus(raw) {
+    const s = String(raw ?? '').trim();
+    if (s === 'open' || s === 'closed' || s === 'canceled')
+        return s;
+    const lower = s.toLowerCase();
+    if (lower === 'rejected' || lower.endsWith('canceled') || lower.endsWith('cancelled')) {
+        return 'canceled';
+    }
+    if (lower === 'filled')
+        return 'closed';
+    logger.warn(TAG, `unknown HL order status '${s}' — treating as 'open' (not confirmed terminal)`);
+    return 'open';
+}
+/**
+ * Normalize one ccxt HL order into a contract-compliant `CcxtOrder`.
+ *
+ * Unlike positions (where a fabricated number is a risk-limit hazard and an
+ * unpriceable row nulls the snapshot), an order row is never dropped: the
+ * fields we default (fee 0, cost from average×filled) are display/accounting
+ * conveniences, while the fields decisions hang on (id, cloid, status, info)
+ * are passed through or conservatively mapped.
+ */
+export function normalizeHlOrder(raw, nowMs = Date.now()) {
+    const r = raw;
+    const amount = fin(r.amount) ?? 0;
+    const filledRaw = fin(r.filled);
+    const remainingRaw = fin(r.remaining);
+    const filled = filledRaw ?? (remainingRaw !== undefined ? Math.max(0, amount - remainingRaw) : 0);
+    const remaining = remainingRaw ?? Math.max(0, amount - filled);
+    const average = fin(r.average) ?? null;
+    const price = fin(r.price) ?? null;
+    const cost = fin(r.cost) ?? (average !== null ? average * filled : 0);
+    const fee = r.fee && typeof r.fee === 'object' && Number.isFinite(r.fee.cost)
+        ? r.fee
+        : { cost: 0, currency: HL_FEE_CURRENCY };
+    const timestamp = fin(r.timestamp) ?? nowMs;
+    return {
+        ...raw,
+        id: String(r.id ?? ''),
+        type: normalizeHlOrderType(
+        // Prefer the raw venue subtype — ccxt's unified type may already be
+        // collapsed ('stop market'→'market') or missing; info.orderType is the
+        // authoritative HL string when present.
+        r.info?.orderType ?? r.type),
+        status: normalizeHlOrderStatus(r.status),
+        amount,
+        filled,
+        remaining,
+        average,
+        price,
+        cost,
+        fee,
+        timeInForce: typeof r.timeInForce === 'string' && r.timeInForce.length > 0 ? r.timeInForce : 'GTC',
+        timestamp,
+        datetime: typeof r.datetime === 'string' && r.datetime.length > 0
+            ? r.datetime
+            : new Date(timestamp).toISOString(),
+    };
+}

package/venues/hyperliquid/hl-position.d.ts

@@ -0,0 +1,36 @@
+import type { CcxtPosition } from '../../types.js';
+/** The raw `assetPositions[].position` payload ccxt passes through at
+ *  `position.info.position` (fields per the info-endpoint docs, §3.6 of the
+ *  integration plan). */
+export interface HlRawPositionInfo {
+    coin?: string;
+    /** Signed size — negative for a short. */
+    szi?: string | number;
+    entryPx?: string | number;
+    unrealizedPnl?: string | number;
+    /** |szi| × mark. */
+    positionValue?: string | number;
+}
+/**
+ * Mark price for an HL position, derived from the position payload alone.
+ *
+ * Primary route inverts the documented uPnl formula; secondary route divides
+ * `positionValue` by |szi|. Returns undefined rather than a guess when neither
+ * route yields a positive price.
+ */
+export declare function deriveHlMarkPrice(args: {
+    entryPrice?: number;
+    unrealizedPnl?: number;
+    /** Signed size (negative = short). */
+    signedSize?: number;
+    positionValue?: number;
+}): number | undefined;
+/**
+ * Normalize one ccxt HL position into a contract-compliant `CcxtPosition`.
+ *
+ * Returns **null** when the row cannot be priced or sized — the caller must then
+ * treat the whole snapshot as UNKNOWN (`null`), not drop the row: a silently
+ * missing position is exactly the "empty ≠ unknown" collapse that drove the
+ * naked-bracket incidents on the Binance side.
+ */
+export declare function normalizeHlPosition(raw: CcxtPosition | null | undefined, nowMs?: number): CcxtPosition | null;

package/venues/hyperliquid/hl-position.js

@@ -0,0 +1,127 @@
+// Hyperliquid position normalization — brings ccxt's HL position rows up to the
+// `CcxtPosition` contract the rest of the plugin treats as REQUIRED numbers.
+//
+// ★ WHY THIS FILE EXISTS (the bug it fixes, 2026-07-26): ccxt@4.5.x's hyperliquid
+//   `parsePosition` sets `markPrice: undefined` (hyperliquid.js:3603), plus
+//   `contractSize`/`timestamp`/`datetime: undefined` — and `safePosition()` fills
+//   none of them. `CcxtPosition` declares all four as non-optional numbers, so
+//   every consumer that trusts the type broke on an HL LIVE position:
+//     - `get_risk_summary` threw `Cannot read properties of undefined (reading
+//       'toFixed')` on `+pos.markPrice.toFixed(2)` (the reported symptom),
+//     - `get_wave9_status` / `live-account-capture` reject the position as
+//       non-finite, `stop-watcher` / `modify_stop` / `modify_target` read a
+//       `undefined` reference price, and `pre-trade-check` / `create-order`
+//       silently fall back to entryPrice (stale exposure + stop-distance math).
+//   Fixing it at this boundary fixes all of them at once — which is why the
+//   normalization lives here (the single choke point every HL position read
+//   passes through) and not in the individual tools.
+//
+// ★ THE MARK DERIVATION IS DOC-EXACT AND COSTS NO NETWORK CALL.
+//   `clearinghouseState` carries NO per-position mark price — markPx lives only in
+//   `metaAndAssetCtxs` (weight 20), so ccxt has nothing to parse and a naive fix
+//   would put a heavy call on a per-tick read path (the rule from
+//   memory/project_hl_venue_scoped_scan_jul13: never put a heavy HL info call on a
+//   poll path). Instead we invert Hyperliquid's own documented formula:
+//
+//     "Unrealized pnl is defined as `side * (mark_price - entry_price) *
+//      position_size`"  — hyperliquid.gitbook.io → Trading → Entry price and pnl
+//                          (verified 2026-07-26)
+//
+//   With `szi` the SIGNED size (side × size) that inverts exactly to
+//       mark = entryPx + unrealizedPnl / szi
+//   and the docs' own example confirms both this and the secondary route:
+//       szi 0.0335, entryPx 2986.3, uPnl −0.0134 → mark 2985.9
+//       positionValue 100.02765 / 0.0335        → mark 2985.9  ✓ (|szi| × mark)
+//
+// ★ NEVER FABRICATE. A row we cannot price returns null and the CALLER turns the
+//   whole snapshot into null ("unknown"), never a partial list and never a $0
+//   mark — a phantom zero mark reads as a total loss and would trip risk limits.
+/** Finite number or undefined — never NaN, never a silent 0. */
+function fin(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Mark price for an HL position, derived from the position payload alone.
+ *
+ * Primary route inverts the documented uPnl formula; secondary route divides
+ * `positionValue` by |szi|. Returns undefined rather than a guess when neither
+ * route yields a positive price.
+ */
+export function deriveHlMarkPrice(args) {
+    const { entryPrice, unrealizedPnl, signedSize, positionValue } = args;
+    // Primary: mark = entry + uPnl / szi  (exact inverse of the documented
+    // uPnl = side * (mark - entry) * size). Also correct when uPnl is 0 — a
+    // freshly-filled position marks at its entry.
+    if (entryPrice !== undefined &&
+        entryPrice > 0 &&
+        unrealizedPnl !== undefined &&
+        signedSize !== undefined &&
+        signedSize !== 0) {
+        const mark = entryPrice + unrealizedPnl / signedSize;
+        if (Number.isFinite(mark) && mark > 0)
+            return mark;
+    }
+    // Secondary: positionValue = |szi| × mark.
+    if (positionValue !== undefined &&
+        positionValue > 0 &&
+        signedSize !== undefined &&
+        signedSize !== 0) {
+        const mark = positionValue / Math.abs(signedSize);
+        if (Number.isFinite(mark) && mark > 0)
+            return mark;
+    }
+    return undefined;
+}
+/**
+ * Normalize one ccxt HL position into a contract-compliant `CcxtPosition`.
+ *
+ * Returns **null** when the row cannot be priced or sized — the caller must then
+ * treat the whole snapshot as UNKNOWN (`null`), not drop the row: a silently
+ * missing position is exactly the "empty ≠ unknown" collapse that drove the
+ * naked-bracket incidents on the Binance side.
+ */
+export function normalizeHlPosition(raw, nowMs = Date.now()) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const info = raw.info?.position;
+    const signedFromInfo = fin(info?.szi);
+    const contracts = fin(raw.contracts) ?? (signedFromInfo === undefined ? undefined : Math.abs(signedFromInfo));
+    if (contracts === undefined || contracts <= 0)
+        return null;
+    const side = raw.side === 'short' || (raw.side === undefined && signedFromInfo !== undefined && signedFromInfo < 0)
+        ? 'short'
+        : 'long';
+    const signedSize = signedFromInfo ?? (side === 'short' ? -contracts : contracts);
+    const entryPrice = fin(raw.entryPrice) ?? fin(info?.entryPx);
+    if (entryPrice === undefined || entryPrice <= 0)
+        return null;
+    // HL always sends unrealizedPnl for an open position; 0 is the neutral value
+    // for the impossible branch (it makes the primary mark route degrade to
+    // "marks at entry" rather than inventing a price).
+    const unrealizedPnl = fin(raw.unrealizedPnl) ?? fin(info?.unrealizedPnl) ?? 0;
+    const positionValue = fin(raw.notional) ?? fin(info?.positionValue);
+    const markPrice = fin(raw.markPrice) ??
+        deriveHlMarkPrice({ entryPrice, unrealizedPnl, signedSize, positionValue });
+    if (markPrice === undefined || markPrice <= 0)
+        return null;
+    const notional = positionValue ?? Math.abs(contracts * markPrice);
+    const timestamp = fin(raw.timestamp) ?? nowMs;
+    return {
+        ...raw,
+        side,
+        contracts,
+        contractSize: fin(raw.contractSize) ?? 1, // HL perps: 1 coin per contract
+        entryPrice,
+        markPrice,
+        notional,
+        unrealizedPnl,
+        percentage: fin(raw.percentage) ?? 0,
+        timestamp,
+        datetime: typeof raw.datetime === 'string' && raw.datetime.length > 0
+            ? raw.datetime
+            : new Date(timestamp).toISOString(),
+    };
+}

package/venues/hyperliquid/hl-private.d.ts

@@ -49,16 +49,33 @@ export declare class HyperliquidPrivateApi {
     getExchange(): any;
     loadMarkets(): Promise<boolean>;
     /** Positions for the MASTER account. `null` = fetch failed (state unknown);
-     *  `[]` = the exchange confirmed flat. */
+     *  `[]` = the exchange confirmed flat.
+     *
+     *  ★ Rows are normalized through `normalizeHlPosition` — ccxt leaves
+     *  `markPrice`/`contractSize`/`timestamp`/`datetime` UNDEFINED on this venue
+     *  (clearinghouseState carries no markPx) while `CcxtPosition` declares them
+     *  required, which crashed `get_risk_summary` and degraded every other
+     *  mark-reading consumer. See hl-position.ts for the doc-exact derivation.
+     *  A row that cannot be priced makes the WHOLE snapshot null (unknown) — never
+     *  a partial list, never a fabricated zero. */
     fetchPositions(symbol?: string): Promise<CcxtPosition[] | null>;
     /** Open orders INCLUDING trigger/TPSL legs. CCXT's HL `fetchOpenOrders`
      *  defaults to `frontendOpenOrders`, which is the only endpoint that returns
-     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints. */
+     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints.
+     *
+     *  ★ Rows are normalized through `normalizeHlOrder` (ccxt leaves cost/fee/
+     *  average/timeInForce undefined and leaks 'take profit market' past the
+     *  type union — see hl-order.ts); `info` + `clientOrderId` survive verbatim
+     *  (protective classification + bracket reconciliation read them). */
     fetchOpenOrders(symbol?: string): Promise<CcxtOrder[] | null>;
     fetchBalance(): Promise<CcxtBalance | null>;
     /** Per-order status — the liveness resolver's REST tier (Tier 2 of the
      *  3-tier rule). Weight 2. `null` = lookup FAILED (unknown), which callers
-     *  must treat as "do not act", NOT as "gone". */
+     *  must treat as "do not act", NOT as "gone".
+     *
+     *  Normalized like fetchOpenOrders. Unknown statuses collapse to 'open'
+     *  (= not confirmed terminal — the conservative direction for both the
+     *  liveness resolver and the entry poller); raw status stays in `info`. */
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
     /** Own fills. WS is the authoritative ingress (plan + the audit-trail rule);
      *  this is the gap-fill/truth-check path. NOTE: only the 10,000 most recent

package/venues/hyperliquid/hl-private.js

@@ -29,6 +29,8 @@ import { logger } from '../../logger.js';
 import { toCcxtSymbol } from '../symbols.js';
 import { assertNotLimited, noteError, noteSuccess, exchangeIpWeight, updateAddressBudget, } from './hl-rate-gate.js';
 import { isValidHlCloid } from './hl-cloid.js';
+import { normalizeHlPosition } from './hl-position.js';
+import { normalizeHlOrder } from './hl-order.js';
 // ccxt via CJS require — OpenClaw's ESM loader yields the wrong module shape
 // (same rationale as binance-private.ts / hl-public.ts).
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -124,7 +126,15 @@ export class HyperliquidPrivateApi {
     }
     // ---- Reads (null on failure — NEVER []) ----
     /** Positions for the MASTER account. `null` = fetch failed (state unknown);
-     *  `[]` = the exchange confirmed flat. */
+     *  `[]` = the exchange confirmed flat.
+     *
+     *  ★ Rows are normalized through `normalizeHlPosition` — ccxt leaves
+     *  `markPrice`/`contractSize`/`timestamp`/`datetime` UNDEFINED on this venue
+     *  (clearinghouseState carries no markPx) while `CcxtPosition` declares them
+     *  required, which crashed `get_risk_summary` and degraded every other
+     *  mark-reading consumer. See hl-position.ts for the doc-exact derivation.
+     *  A row that cannot be priced makes the WHOLE snapshot null (unknown) — never
+     *  a partial list, never a fabricated zero. */
     async fetchPositions(symbol) {
         try {
             assertNotLimited('clearinghouseState');
@@ -133,7 +143,19 @@ export class HyperliquidPrivateApi {
             noteSuccess('clearinghouseState');
             if (!Array.isArray(raw))
                 return null;
-            return raw.filter((p) => Math.abs(Number(p.contracts ?? 0)) > 0);
+            const out = [];
+            for (const p of raw) {
+                if (Math.abs(Number(p?.contracts ?? 0)) <= 0)
+                    continue; // flat row — information, not failure
+                const normalized = normalizeHlPosition(p);
+                if (!normalized) {
+                    logger.error(TAG, `fetchPositions: unparseable position row for ${String(p?.symbol ?? 'unknown symbol')} ` +
+                        '— returning null (snapshot UNTRUSTED; a dropped row would read as "flat")');
+                    return null;
+                }
+                out.push(normalized);
+            }
+            return out;
         }
         catch (err) {
             noteError(err, 'fetchPositions');
@@ -143,14 +165,19 @@ export class HyperliquidPrivateApi {
     }
     /** Open orders INCLUDING trigger/TPSL legs. CCXT's HL `fetchOpenOrders`
      *  defaults to `frontendOpenOrders`, which is the only endpoint that returns
-     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints. */
+     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints.
+     *
+     *  ★ Rows are normalized through `normalizeHlOrder` (ccxt leaves cost/fee/
+     *  average/timeInForce undefined and leaks 'take profit market' past the
+     *  type union — see hl-order.ts); `info` + `clientOrderId` survive verbatim
+     *  (protective classification + bracket reconciliation read them). */
     async fetchOpenOrders(symbol) {
         try {
             assertNotLimited('frontendOpenOrders');
             const s = symbol ? toCcxtSymbol('hyperliquid', symbol) : undefined;
             const raw = await this.exchange.fetchOpenOrders(s);
             noteSuccess('frontendOpenOrders');
-            return Array.isArray(raw) ? raw : null;
+            return Array.isArray(raw) ? raw.map((o) => normalizeHlOrder(o)) : null;
         }
         catch (err) {
             noteError(err, 'fetchOpenOrders');
@@ -173,14 +200,18 @@ export class HyperliquidPrivateApi {
     }
     /** Per-order status — the liveness resolver's REST tier (Tier 2 of the
      *  3-tier rule). Weight 2. `null` = lookup FAILED (unknown), which callers
-     *  must treat as "do not act", NOT as "gone". */
+     *  must treat as "do not act", NOT as "gone".
+     *
+     *  Normalized like fetchOpenOrders. Unknown statuses collapse to 'open'
+     *  (= not confirmed terminal — the conservative direction for both the
+     *  liveness resolver and the entry poller); raw status stays in `info`. */
     async fetchOrder(orderId, symbol) {
         try {
             assertNotLimited('orderStatus');
             const s = symbol ? toCcxtSymbol('hyperliquid', symbol) : undefined;
             const raw = await this.exchange.fetchOrder(orderId, s);
             noteSuccess('orderStatus');
-            return raw ?? null;
+            return raw ? normalizeHlOrder(raw) : null;
         }
         catch (err) {
             noteError(err, 'fetchOrder');

package/venues/hyperliquid/hl-public.d.ts

@@ -1,6 +1,7 @@
 import type { CcxtTicker, CcxtOHLCV } from '../../types.js';
 import type { OrderBookDepth } from '../../simulator/types.js';
 import type { PublicMarketDataApi } from '../../ccxt/public-market-data-api.js';
+import { type VenueReachabilityResult } from '@reefclaw/shared';
 export interface HyperliquidPublicApiOptions {
     testnet?: boolean;
     /** Test seam — injected ccxt exchange instance. */
@@ -60,11 +61,17 @@ export declare class HyperliquidPublicApi implements PublicMarketDataApi {
      *  (verified live 2026-07-11: `{"specialStatuses":null,"time":…}`) doubles
      *  as the clock-drift source. Geo classification is best-effort — HL's
      *  API-level geo behavior is UNVERIFIED (plan §3.9); a 403/451 maps to
-     *  geo_blocked, anything else non-2xx/network maps to unreachable. */
-    probeReachability(): Promise<{
-        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
-        driftMs: number | null;
-    }>;
+     *  geo_blocked, anything else non-2xx/network maps to unreachable.
+     *
+     *  ★ Self-stall detection (issue #265): the failure path is wall-clock timed.
+     *  A throw is only evidence about the VENUE if our own abort timer fired
+     *  roughly when it was set for. On a starved host the loop stops running —
+     *  observed live on the HL rig: this 10s timer landed 86s late while the
+     *  agent was trading on HL perfectly well — and blaming the network then
+     *  produces a confident, wrong "check DNS/firewall/region" banner. Past
+     *  STALL_FACTOR× the budget we report `stalled`, which the reporter renders
+     *  as `unknown`: we genuinely did not learn whether HL is reachable. */
+    probeReachability(): Promise<VenueReachabilityResult>;
     /** `meta` — the asset universe (szDecimals, maxLeverage, positional assetIndex).
      *  Keyless info read, weight 20. Feeds HyperliquidInfoCache. Returns null on any
      *  failure (never a partial universe — a half-loaded rules table would silently

package/venues/hyperliquid/hl-public.js

@@ -32,6 +32,7 @@
 // on this venue — logged clearly, null returned (never silently translated).
 import { createRequire } from 'node:module';
 import { logger } from '../../logger.js';
+import { REACHABILITY_STALL_FACTOR } from '@reefclaw/shared';
 import { toCcxtSymbol, toHyperliquidCoin } from '../symbols.js';
 const TAG = 'hl-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
@@ -55,6 +56,10 @@ const DEFAULT_TICKER_TTL_MS = 4_000;
  *  snapshot's ccxt call re-runs the whole fetchMarkets pipeline (weight ~60,
  *  ~13s on a slow host) and nothing price-critical reads these fields. */
 const FULL_SNAPSHOT_REFRESH_MS = 300_000;
+/** Reachability-probe request budget. Also the yardstick for self-stall
+ *  detection — see probeReachability. */
+const PROBE_TIMEOUT_MS = 10_000;
+const STALL_FACTOR = REACHABILITY_STALL_FACTOR;
 function resolveTickerTtlMs() {
     const raw = Number(process.env.RC_HL_TICKER_TTL_MS);
     if (!Number.isFinite(raw) || raw < 500)
@@ -343,10 +348,20 @@ export class HyperliquidPublicApi {
      *  (verified live 2026-07-11: `{"specialStatuses":null,"time":…}`) doubles
      *  as the clock-drift source. Geo classification is best-effort — HL's
      *  API-level geo behavior is UNVERIFIED (plan §3.9); a 403/451 maps to
-     *  geo_blocked, anything else non-2xx/network maps to unreachable. */
+     *  geo_blocked, anything else non-2xx/network maps to unreachable.
+     *
+     *  ★ Self-stall detection (issue #265): the failure path is wall-clock timed.
+     *  A throw is only evidence about the VENUE if our own abort timer fired
+     *  roughly when it was set for. On a starved host the loop stops running —
+     *  observed live on the HL rig: this 10s timer landed 86s late while the
+     *  agent was trading on HL perfectly well — and blaming the network then
+     *  produces a confident, wrong "check DNS/firewall/region" banner. Past
+     *  STALL_FACTOR× the budget we report `stalled`, which the reporter renders
+     *  as `unknown`: we genuinely did not learn whether HL is reachable. */
     async probeReachability() {
         const ac = new AbortController();
-        const tid = setTimeout(() => ac.abort(), 10_000);
+        const tid = setTimeout(() => ac.abort(), PROBE_TIMEOUT_MS);
+        const startedAt = Date.now();
         try {
             const res = await this.fetchImpl(`${this.baseUrl()}/info`, {
                 method: 'POST',
@@ -368,7 +383,13 @@ export class HyperliquidPublicApi {
             return { outcome: 'reachable', driftMs };
         }
         catch (err) {
-            logger.warn(TAG, `probeReachability failed: ${err instanceof Error ? err.message : String(err)}`);
+            const elapsedMs = Date.now() - startedAt;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (elapsedMs > PROBE_TIMEOUT_MS * STALL_FACTOR) {
+                logger.warn(TAG, `probeReachability inconclusive: this process was starved — a ${PROBE_TIMEOUT_MS}ms probe took ${Math.round(elapsedMs / 1000)}s (${msg}). Reporting reachability as unknown, NOT as a Hyperliquid failure.`);
+                return { outcome: 'stalled', driftMs: null, stallMs: elapsedMs };
+            }
+            logger.warn(TAG, `probeReachability failed: ${msg}`);
             return { outcome: 'unreachable', driftMs: null };
         }
         finally {

package/venues/hyperliquid/hl-user-stream.d.ts

@@ -41,7 +41,19 @@ export interface HlOrderUpdateEvent {
     statusTimestamp: number;
 }
 export interface HlUserStreamCallbacks {
-    onFill: (fill: HlFillEvent) => void;
+    /** ★ `meta.isSnapshot` marks a fill from the subscription SNAPSHOT — the batch
+     *  of recent history HL sends on every (re)subscribe — not a live execution.
+     *
+     *  Do NOT confuse this with the T-5 gap rule below: HL not replaying the fills
+     *  you MISSED while disconnected is true and unrelated. It still ships a
+     *  snapshot of recent history on subscribe, and consumers must tell them apart.
+     *  Idempotent consumers (the audit-trail ingest, keyed on exchange trade id)
+     *  should take snapshot fills; state MUTATORS (bracket resize/attach) must not
+     *  — replaying an old fill's `startPosition + sz` resizes live protective legs
+     *  to a stale historical size (audit 2026-07-27 F44). */
+    onFill: (fill: HlFillEvent, meta: {
+        isSnapshot: boolean;
+    }) => void;
     onOrderUpdate: (update: HlOrderUpdateEvent) => void;
     /** userEvents: liquidation / funding / non-user-cancel — the close-bypass feed. */
     onUserEvent: (event: Record<string, unknown>) => void;

package/venues/hyperliquid/hl-user-stream.js

@@ -137,9 +137,12 @@ export class HyperliquidUserStream {
         switch (channel) {
             case 'userFills': {
                 const payload = data;
+                // `isSnapshot` was typed here from the start but never read — so every
+                // (re)connect replayed recent history as if it were live (F44).
+                const isSnapshot = payload?.isSnapshot === true;
                 for (const fill of payload?.fills ?? []) {
                     this.lastEventAt = Math.max(this.lastEventAt, fill.time ?? Date.now());
-                    this.opts.callbacks.onFill(fill);
+                    this.opts.callbacks.onFill(fill, { isSnapshot });
                 }
                 break;
             }