@reefclaw/openclaw-plugin 0.1.13 → 0.1.15

package/venues/hyperliquid/hl-brackets.js

@@ -84,6 +84,11 @@ export function bracketCoversPosition(args) {
         const legs = args.liveLegs.filter((l) => l.role === role);
         if (legs.length === 0) {
             missing.push(role);
+            // A role with no leg at all leaves the WHOLE position uncovered on that
+            // side — report the honest naked size. Leaving this at 0 was audit
+            // 2026-07-26 F4: the resize planner keyed on shortfall, saw zero, and
+            // no-oped forever while a stop-less position stayed naked.
+            shortfall[role] = args.positionSize;
             continue;
         }
         const coveredSize = legs.reduce((sum, l) => sum + l.size, 0);
@@ -91,12 +96,15 @@ export function bracketCoversPosition(args) {
         if (gap > COVERAGE_EPSILON)
             shortfall[role] = gap;
     }
-    const covered = shortfall.stop <= COVERAGE_EPSILON &&
-        shortfall.target <= COVERAGE_EPSILON &&
-        // A missing STOP is never "covered" — that is the naked-position case. A
-        // missing TARGET is a policy choice (requireTakeProfit can be off), so it is
-        // reported in `missing` but does not by itself fail coverage.
-        !missing.includes('stop');
+    const covered = 
+    // A missing STOP is never "covered" — that is the naked-position case
+    // (its shortfall is the full position size, so this arm also fails).
+    !missing.includes('stop') &&
+        shortfall.stop <= COVERAGE_EPSILON &&
+        // A missing TARGET is a policy choice (requireTakeProfit can be off): it
+        // is reported via `missing` + `shortfall` but does not by itself fail
+        // coverage. A PRESENT-but-undersized target still does.
+        (missing.includes('target') || shortfall.target <= COVERAGE_EPSILON);
     return { covered, shortfall, missing };
 }
 /** ★ Resize protective legs after a scale-in (or any position-size change).
@@ -120,20 +128,44 @@ export function planResize(args) {
         positionSize: args.positionSize,
         liveLegs: args.liveLegs,
     });
-    // Nothing to do when every present leg already covers the position exactly.
+    const healable = ['stop', 'target'].filter((role) => {
+        const price = args.registeredPrices?.[role];
+        return (coverage.missing.includes(role) &&
+            typeof price === 'number' && Number.isFinite(price) && price > 0);
+    });
+    // Nothing to do when every present leg already covers the position exactly
+    // and no vanished-but-registered leg needs rebuilding. (A missing role's
+    // shortfall is the full position size, so present-leg sizing is checked
+    // against the PRESENT legs only.)
+    const presentShortfall = ['stop', 'target'].some((role) => !coverage.missing.includes(role) && coverage.shortfall[role] > COVERAGE_EPSILON);
     const oversized = args.liveLegs.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
-    if (coverage.shortfall.stop <= COVERAGE_EPSILON &&
-        coverage.shortfall.target <= COVERAGE_EPSILON &&
-        !oversized) {
+    if (!presentShortfall && !oversized && healable.length === 0) {
         return { cancelCloids: [], submit: [], noop: true };
     }
-    // Rebuild every PRESENT role at the correct size, preserving its trigger price.
+    // Rebuild every PRESENT role at the correct size (preserving its trigger
+    // price), plus every HEALABLE missing role at its registered price.
     const legs = [];
     const cancelCloids = [];
     for (const role of ['stop', 'target']) {
         const existing = args.liveLegs.filter((l) => l.role === role);
-        if (existing.length === 0)
-            continue; // absent leg = attach path's job, not resize's
+        if (existing.length === 0) {
+            if (!healable.includes(role))
+                continue; // no leg, no registered price — coverage alarms own it
+            legs.push({
+                role,
+                triggerPrice: args.registeredPrices[role],
+                size: args.positionSize,
+                cloid: buildHlBracketCloid(args.bracketId, role),
+            });
+            continue;
+        }
+        // A present role that already covers exactly (and isn't oversized) is left
+        // untouched — a heal of the OTHER role must not churn a healthy leg.
+        const coveredSize = existing.reduce((sum, l) => sum + l.size, 0);
+        const roleHealthy = args.positionSize - coveredSize <= COVERAGE_EPSILON &&
+            !existing.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
+        if (roleHealthy)
+            continue;
         // Trigger price is preserved from the live leg (the agent's pinned plan) —
         // resizing must NEVER silently move a stop.
         const triggerPrice = existing[0].triggerPrice;

package/venues/hyperliquid/hl-fill-ingest.d.ts

@@ -0,0 +1,18 @@
+import type { FillEvent } from '@reefclaw/shared';
+import type { HlFillEvent } from './hl-user-stream.js';
+/** Inverse of shared `toHyperliquidCoin`: every HL perp is USDC-quoted, so the
+ *  canonical symbol is `<coin>/USDC` with the coin's case preserved (kPEPE). */
+export declare function hlCoinToCanonical(coin: string): string;
+/**
+ * Map one HL fill to the shared FillEvent contract.
+ *
+ * Returns null (with a warn) when the identity fields the audit trail's
+ * idempotency key needs are absent or garbled — a row we cannot key must be
+ * dropped, never fabricated. `exchange` MUST come from
+ * `fillExchangeId('hyperliquid')` (FILL_EXCHANGE_ID strings are frozen once
+ * rows exist) — this mapper trusts the wiring, it does not mint literals.
+ */
+export declare function hlFillToFillEvent(fill: Partial<HlFillEvent>, wiring: {
+    userId: string;
+    exchange: string;
+}, source: 'ws' | 'rest_reconcile'): FillEvent | null;

package/venues/hyperliquid/hl-fill-ingest.js

@@ -0,0 +1,88 @@
+// Per-fill audit-trail ingest for the Hyperliquid venue (audit 2026-07-26 F26).
+//
+// Binance fills reach the `trades` table via ws-ingest (ORDER_TRADE_UPDATE →
+// FillEvent → TradeStoreClient). HL's user stream had no equivalent: fills
+// drove bracket wiring and were then DROPPED — a live book and P&L with no
+// independent per-trade record, nothing to reconcile against when a number
+// looks wrong, and fills during a WS gap lost forever. This module is the HL
+// analog: a pure mapper from the WS fill shape (also satisfied by REST
+// `userFillsByTime` rows) to the shared FillEvent contract. The adapter calls
+// it from the WS hot path and from the reconnect gap backfill; idempotency is
+// the server-side (exchange, exchange_trade_id) upsert, so double-delivery
+// between the two paths is harmless by design.
+import { logger } from '../../logger.js';
+const TAG = 'hl-fill-ingest';
+/** Inverse of shared `toHyperliquidCoin`: every HL perp is USDC-quoted, so the
+ *  canonical symbol is `<coin>/USDC` with the coin's case preserved (kPEPE). */
+export function hlCoinToCanonical(coin) {
+    return `${coin}/USDC`;
+}
+const num = (v) => {
+    const n = typeof v === 'string' ? Number(v) : typeof v === 'number' ? v : Number.NaN;
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * Map one HL fill to the shared FillEvent contract.
+ *
+ * Returns null (with a warn) when the identity fields the audit trail's
+ * idempotency key needs are absent or garbled — a row we cannot key must be
+ * dropped, never fabricated. `exchange` MUST come from
+ * `fillExchangeId('hyperliquid')` (FILL_EXCHANGE_ID strings are frozen once
+ * rows exist) — this mapper trusts the wiring, it does not mint literals.
+ */
+export function hlFillToFillEvent(fill, wiring, source) {
+    const price = num(fill.px);
+    const quantity = num(fill.sz);
+    const time = num(fill.time);
+    if (typeof fill.tid !== 'number' || !Number.isFinite(fill.tid) ||
+        typeof fill.oid !== 'number' || !Number.isFinite(fill.oid) ||
+        typeof fill.coin !== 'string' || fill.coin.length === 0 ||
+        price === undefined || quantity === undefined || quantity <= 0 ||
+        time === undefined ||
+        (fill.side !== 'A' && fill.side !== 'B')) {
+        // Log the DIAGNOSIS (which identity fields failed + what shape arrived),
+        // never the raw payload — fills carry account trading data that doesn't
+        // belong in journals.
+        const bad = [];
+        if (typeof fill.tid !== 'number' || !Number.isFinite(fill.tid))
+            bad.push('tid');
+        if (typeof fill.oid !== 'number' || !Number.isFinite(fill.oid))
+            bad.push('oid');
+        if (typeof fill.coin !== 'string' || fill.coin.length === 0)
+            bad.push('coin');
+        if (price === undefined)
+            bad.push('px');
+        if (quantity === undefined || quantity <= 0)
+            bad.push('sz');
+        if (time === undefined)
+            bad.push('time');
+        if (fill.side !== 'A' && fill.side !== 'B')
+            bad.push('side');
+        logger.warn(TAG, `Dropping unmappable HL fill (source=${source}): invalid=[${bad.join(',')}] ` +
+            `keys=[${Object.keys(fill).join(',')}]`);
+        return null;
+    }
+    return {
+        exchange: wiring.exchange,
+        exchangeTradeId: String(fill.tid),
+        exchangeOrderId: String(fill.oid),
+        clientOrderId: typeof fill.cloid === 'string' && fill.cloid.length > 0 ? fill.cloid : undefined,
+        source,
+        userId: wiring.userId,
+        symbol: hlCoinToCanonical(fill.coin),
+        side: fill.side === 'B' ? 'BUY' : 'SELL',
+        quantity,
+        price,
+        // HL `crossed` is the taker flag; maker is its inverse. Absent → unknown.
+        maker: typeof fill.crossed === 'boolean' ? !fill.crossed : undefined,
+        // `fee` is inclusive of builderFee, and we hard-disable the builder fee
+        // (options.builderFee:false, pinned by hl-private.test.ts) so this is the
+        // whole commission either way. HL fees settle in USDC unless feeToken says
+        // otherwise.
+        commission: num(fill.fee),
+        commissionAsset: typeof fill.feeToken === 'string' ? fill.feeToken : 'USDC',
+        realizedPnl: num(fill.closedPnl),
+        exchangeTime: time,
+        rawPayload: fill,
+    };
+}

package/venues/hyperliquid/hl-live-adapter.d.ts

@@ -6,10 +6,23 @@ import { type HlCredentials } from './hl-private.js';
 import type { BracketId } from '../../live/bracket-types.js';
 import { BracketLedger } from '../../live/bracket-ledger.js';
 import { HlBracketCoordinator } from './hl-bracket-coordinator.js';
+import type { TradeIngestWiring } from '../../live/live-adapter.js';
 export interface HlLiveAdapterOptions {
     credentials: HlCredentials;
     mode: TradingMode;
     marketSlippagePct?: number;
+    /** MICRO_LIVE per-order notional cap in quote-USD (USDC here). Defaults to
+     *  $50 in MICRO_LIVE — the same default Binance's LiveAdapter has enforced
+     *  since the mode existed. HL shipped Phase 3 without any cap, making
+     *  "micro" a label (audit 2026-07-26 F8). Ignored in LIVE. */
+    microLive?: {
+        maxPositionUSDT?: number;
+    };
+    /** Audit-trail wiring (audit 2026-07-26 F26): when present, every user-stream
+     *  fill is POSTed to /api/internal/trades and reconnect gaps are backfilled
+     *  via userFillsByTime. Same object boot passes the Binance adapter —
+     *  `exchange` MUST be fillExchangeId('hyperliquid'). */
+    tradeIngest?: TradeIngestWiring;
     /** Test seams. Production omits both. */
     bracketLedger?: BracketLedger;
     disableUserStream?: boolean;
@@ -25,11 +38,22 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     private _coordinator;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    readonly bracketsAlwaysEnforced = true;
     private userStream;
     private truthCheckTimer;
     private truthCheckRunning;
     private _readiness;
     private openOrdersUnavailableUntil;
+    /** MICRO_LIVE per-order notional cap (USD). null = LIVE, uncapped. */
+    private readonly maxPositionUsd;
+    /** Resolved audit-trail wiring (F26). undefined = ingest not configured. */
+    private readonly fillIngest?;
+    /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
+     *  low-water mark the reconnect gap backfill widens from. */
+    private lastFillIngestMs;
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -132,6 +156,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
         symbol: string;
         positionSide: 'long' | 'short';
         positionSize: number;
+        registeredPrices?: {
+            stop?: number;
+            target?: number;
+        };
     }): Promise<{
         resized: boolean;
         slCid?: string;
@@ -147,6 +175,14 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  cleanup before a fresh attach). THROWS when order state is unknown —
      *  the caller logs and still attaches (protection beats hygiene). */
     cancelSymbolBracketLegs(symbol: string): Promise<number>;
+    /** Audit-trail ingest (F26): fire-and-forget POST of one fill. The client
+     *  never blocks the WS hot path; the server-side (exchange, trade id) upsert
+     *  makes WS/backfill double-delivery a no-op. */
+    private ingestFill;
+    /** Reconnect gap backfill (F26): the WS replays NOTHING (T-5), so fills that
+     *  landed while the socket was down exist ONLY via REST. Over-fetch with a
+     *  60s overlap is harmless (idempotent upsert); under-fetch loses audit rows. */
+    private backfillFillGap;
     /** Entry fills drive attach (resting limits) / resize (partial-fill growth).
      *  `startPosition` is the position BEFORE this fill — the WS-authoritative
      *  way to know the after-fill total without an extra REST read. */

package/venues/hyperliquid/hl-live-adapter.js

@@ -38,6 +38,7 @@ import { generateBracketId } from '../../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.js';
 import { HlBracketCoordinator, isRejectedOrder, isTerminalBracketState, } from './hl-bracket-coordinator.js';
 import { HyperliquidUserStream } from './hl-user-stream.js';
+import { hlFillToFillEvent } from './hl-fill-ingest.js';
 import { formatError } from '../../logger.js';
 const TAG = 'hl-live-adapter';
 /** Venue-distinct ledger storage — a venue switch on the same box must never
@@ -65,11 +66,22 @@ export class HyperliquidLiveAdapter extends EventEmitter {
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     _coordinator = null;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    bracketsAlwaysEnforced = true;
     userStream = null;
     truthCheckTimer = null;
     truthCheckRunning = false;
     _readiness = 'INIT_PENDING';
     openOrdersUnavailableUntil = 0;
+    /** MICRO_LIVE per-order notional cap (USD). null = LIVE, uncapped. */
+    maxPositionUsd;
+    /** Resolved audit-trail wiring (F26). undefined = ingest not configured. */
+    fillIngest;
+    /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
+     *  low-water mark the reconnect gap backfill widens from. */
+    lastFillIngestMs = 0;
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -81,6 +93,23 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         this.api = new HyperliquidPrivateApi(opts.credentials);
         this.publicApi = new HyperliquidPublicApi({ testnet: opts.credentials.testnet });
         this.slippagePct = clampSlippage(opts.marketSlippagePct ?? DEFAULT_MARKET_SLIPPAGE);
+        this.maxPositionUsd =
+            opts.mode === 'MICRO_LIVE' ? opts.microLive?.maxPositionUSDT ?? 50 : null;
+        if (opts.tradeIngest) {
+            if (opts.tradeIngest.exchange) {
+                this.fillIngest = {
+                    client: opts.tradeIngest.client,
+                    userId: opts.tradeIngest.userId,
+                    exchange: opts.tradeIngest.exchange,
+                };
+                logger.info(TAG, 'Per-fill audit-trail ingest wired (WS + reconnect gap backfill)');
+            }
+            else {
+                // FILL_EXCHANGE_ID strings are frozen once rows exist — refusing beats
+                // minting rows under a guessed exchange id.
+                logger.warn(TAG, 'tradeIngest provided WITHOUT an exchange id — fill ingest disabled');
+            }
+        }
         this.infoCache = new HyperliquidInfoCache(async () => {
             // `meta` is a keyless info read — the public client owns it.
             return this.publicApi.fetchMeta();
@@ -109,7 +138,8 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         const rules = await this.infoCache.load();
         if (markets && rules && this.infoCache.size > 0) {
             this._readiness = 'READY';
-            logger.info(TAG, `HL live adapter READY (${this.infoCache.size} assets, mode=${this.opts.mode})`);
+            logger.info(TAG, `HL live adapter READY (${this.infoCache.size} assets, mode=${this.opts.mode}` +
+                `${this.maxPositionUsd != null ? `, micro cap $${this.maxPositionUsd}/order` : ''})`);
         }
         else {
             // DEGRADED, not BLOCKED: reads/exits still work; entries are refused
@@ -135,13 +165,17 @@ export class HyperliquidLiveAdapter extends EventEmitter {
                 walletAddress: this.opts.credentials.walletAddress,
                 testnet: this.opts.credentials.testnet,
                 callbacks: {
-                    onFill: (fill) => this.onUserFill(fill),
+                    onFill: (fill, meta) => this.onUserFill(fill, meta),
                     onOrderUpdate: (update) => this.onUserOrderUpdate(update),
                     onUserEvent: () => {
                         /* liquidation/funding — liquidation fills also arrive via onFill */
                     },
                     onResyncNeeded: (window) => {
                         void this.runTruthCheck(`ws_resync_blind_${Math.round(window.wasDisconnectedMs / 1000)}s`);
+                        // Fills that landed inside the blind window exist only via REST
+                        // (T-5: the WS replays nothing) — recover them for the audit
+                        // trail (F26). Bracket state is healed by the truth-check above.
+                        void this.backfillFillGap(window.sinceMs).catch((err) => logger.warn(TAG, `Fill gap backfill threw: ${msg(err)}`));
                     },
                 },
             });
@@ -183,6 +217,21 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             }
             referencePrice = mark;
         }
+        // ---- Micro-live notional cap (audit 2026-07-26 F8) ----
+        // Same semantics as Binance's LiveAdapter: clamp NEW exposure to the cap;
+        // never touch risk-reducing orders (blocking a close is worse than an
+        // uncapped close, and reduce-only cannot increase the position). A
+        // reference price is always in hand by this point — market orders fetched
+        // the mark above, limit orders carry their own price.
+        let effectiveAmount = amount;
+        if (this.maxPositionUsd != null && !options?.reduceOnly) {
+            const maxAmount = this.maxPositionUsd / referencePrice;
+            if (effectiveAmount > maxAmount) {
+                logger.info(TAG, `Micro-live cap: reducing ${symbol} amount ${effectiveAmount} → ${maxAmount} ` +
+                    `(max $${this.maxPositionUsd} notional at ref ${referencePrice})`);
+                effectiveAmount = maxAmount;
+            }
+        }
         const submitPrice = type === 'market'
             ? this.infoCache.marketPrice({
                 symbol,
@@ -193,7 +242,7 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             : this.infoCache.roundPrice(symbol, referencePrice, side === 'buy' ? 'down' : 'up');
         const check = this.infoCache.validate({
             symbol,
-            amount,
+            amount: effectiveAmount,
             side,
             price: type === 'limit' ? submitPrice : undefined,
             referencePrice,
@@ -303,6 +352,13 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         const ledger = this.getHlBracketCoordinator().getLedger();
         const existing = ledger.getBySymbol(symbol);
         if (existing && !isTerminalBracketState(existing.state) && existing.state !== 'pending_entry') {
+            // ★ F5: record THIS order's cloid against the live row FIRST. A scale-in
+            // submitted as a resting limit fills later, and `onUserFill` matches
+            // fills to rows by cid — without this its fill matched nothing, so no
+            // resize ever ran and the added contracts stayed NAKED (T-2: legs are
+            // fixed size) until the 60s truth-check sweep. Registered before the
+            // resize below so a fast fill can never race ahead of the bookkeeping.
+            this.getHlBracketCoordinator().registerAdditionalEntryCid(symbol, entryCloid);
             if (isFilled) {
                 void this.resizeAfterScaleInAsync(symbol);
             }
@@ -709,14 +765,67 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         return cancelled;
     }
     // ---- User-stream handlers (issue #209 wiring) ----
+    /** Audit-trail ingest (F26): fire-and-forget POST of one fill. The client
+     *  never blocks the WS hot path; the server-side (exchange, trade id) upsert
+     *  makes WS/backfill double-delivery a no-op. */
+    ingestFill(fill, source) {
+        if (!this.fillIngest)
+            return false;
+        const event = hlFillToFillEvent(fill, this.fillIngest, source);
+        if (!event)
+            return false;
+        this.fillIngest.client.post(this.fillIngest.userId, event);
+        if (event.exchangeTime > this.lastFillIngestMs)
+            this.lastFillIngestMs = event.exchangeTime;
+        return true;
+    }
+    /** Reconnect gap backfill (F26): the WS replays NOTHING (T-5), so fills that
+     *  landed while the socket was down exist ONLY via REST. Over-fetch with a
+     *  60s overlap is harmless (idempotent upsert); under-fetch loses audit rows. */
+    async backfillFillGap(sinceMs) {
+        if (!this.fillIngest)
+            return;
+        const floor = Date.now() - 24 * 3600_000; // never sweep more than a day
+        const from = Math.max(floor, Math.min(sinceMs, this.lastFillIngestMs > 0 ? this.lastFillIngestMs : Number.POSITIVE_INFINITY) - 60_000);
+        const fills = await this.api.fetchFillsSince(from);
+        if (fills === null) {
+            // null ≠ empty: the fetch FAILED — the gap stays open, the next resync
+            // (or the periodic truth-check path) retries. Never treat as "no fills".
+            logger.warn(TAG, `Fill gap backfill fetch FAILED (since=${new Date(from).toISOString()}) — retried on next resync`);
+            return;
+        }
+        let posted = 0;
+        for (const f of fills) {
+            if (this.ingestFill(f, 'rest_reconcile'))
+                posted++;
+        }
+        if (fills.length > 0) {
+            logger.info(TAG, `Fill gap backfill: posted ${posted}/${fills.length} fill(s) since ${new Date(from).toISOString()}`);
+        }
+    }
     /** Entry fills drive attach (resting limits) / resize (partial-fill growth).
      *  `startPosition` is the position BEFORE this fill — the WS-authoritative
      *  way to know the after-fill total without an extra REST read. */
-    onUserFill(fill) {
+    onUserFill(fill, meta) {
+        // Audit trail first — bracket bookkeeping below must not gate the record.
+        // Snapshot fills ARE ingested on purpose: the ledger is idempotent on
+        // (exchange, exchange_trade_id), so replayed history upserts harmlessly and
+        // backfills rows we'd otherwise miss (F26).
+        this.ingestFill(fill, 'ws');
+        // ★ F44: but bracket bookkeeping is a STATE MUTATION, not an idempotent
+        // write. Every (re)subscribe ships a snapshot of recent fills, and acting on
+        // one recomputes the position as that old fill's `startPosition + sz` — a
+        // stale total — then resizes the LIVE protective legs down to it. Observed
+        // on the rig 2026-07-27: ETH legs cut 0.027 → 0.0231 thirteen seconds after
+        // a user-stream connect, leaving 0.0039 unprotected until the 60s sweep
+        // healed it, in a repeating flap. Exchange truth is the resync's job.
+        if (meta?.isSnapshot)
+            return;
         try {
-            const ledger = this.getHlBracketCoordinator().getLedger();
-            const rows = ledger.getAll().filter((r) => !isTerminalBracketState(r.state));
-            const row = rows.find((r) => r.entryCid && fill.cloid && r.entryCid === fill.cloid);
+            // Matches the primary entry cid OR any additional cid recorded for a
+            // scale-in / second resting entry (F5) — matching on `entryCid` alone
+            // silently dropped those fills.
+            const row = this.getHlBracketCoordinator().findRowByEntryCid(fill.cloid);
             if (!row)
                 return;
             const sz = Math.abs(Number(fill.sz ?? 0));

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;
             }

package/venues/registry.js

@@ -1,12 +1,13 @@
 // Venue registry — the single seam where a trading venue's LIVE adapter is
-// constructed (Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
+// constructed (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
 //
-// Phase 0 scope: Binance is the ONLY venue this build can trade live;
-// 'hyperliquid' is a recognised-but-unsupported config value that boot handles
-// by falling back to PAPER (never by crashing register() — OpenClaw treats a
-// throwing register as "ignored" and the agent silently loses every tool).
-// Phase 3 adds the HyperliquidLiveAdapter arm HERE and nowhere else, so the
-// boot path never grows a second venue branch.
+// This build trades live on BOTH supported venues: Binance (LiveAdapter) and
+// Hyperliquid (HyperliquidLiveAdapter, Phase 3 — brackets always enforced by
+// HlBracketCoordinator). A venue with missing/invalid credentials falls back
+// to PAPER at boot (never by crashing register() — OpenClaw treats a throwing
+// register as "ignored" and the agent silently loses every tool). Any future
+// venue adds its arm HERE and nowhere else, so the boot path never grows a
+// second venue branch.
 //
 // Venue is LOCAL mechanism (TOOL_DISTRIBUTION_ARCHITECTURE.md §2 decision
 // rule: it holds keys + is part of the safety floor) — it is read from

package/wave9/paper-admission-guard.d.ts

@@ -1,7 +1,18 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 /** One catalog toggle represents both frozen Wave 9 strategy legs. */
 export declare const WAVE9_BUNDLE_SETUP_TYPE = "wave9_28d_momentum_reversal";
+/** TOOL-level close reason: what close_position args + beginExit redemption
+ *  requests must carry. The `wave9_` namespace keeps it from colliding with
+ *  generic CloseReason values. */
 export declare const WAVE9_MECHANICAL_EXIT_REASON = "wave9_signal_reversal";
+/** DECISION-level exit cause: what the authorization decision
+ *  (Wave9PaperExitTokenDecision.reason) records at issuance. Deliberately a
+ *  DIFFERENT string from WAVE9_MECHANICAL_EXIT_REASON — the decision names
+ *  WHY the strategy exits (its only exit cause is a signal reversal), the
+ *  tool reason names WHICH namespaced close path redeems it. issueExitBatch
+ *  validates this constant; beginExit validates the tool constant. Two fields
+ *  on two layers, each checked against its own value — not an asymmetry. */
+export declare const WAVE9_EXIT_DECISION_REASON = "signal_reversal";
 export type Wave9ExecutionMode = 'PAPER' | 'LIVE';
 /** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
 export declare function isWave9ManagedPosition(position: {
@@ -93,7 +104,7 @@ export interface Wave9PaperExitTokenDecision {
     missionId: string;
     symbol: string;
     positionSide: 'long' | 'short';
-    reason: 'signal_reversal';
+    reason: typeof WAVE9_EXIT_DECISION_REASON;
     notBeforeMs: number;
     deadlineMs: number;
     positionFingerprint: string;