@reefclaw/openclaw-plugin 0.1.6 → 0.1.7

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

@@ -4,10 +4,15 @@ import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from '../../ty
 import type { PositionMetadata, CloseReason } from '../../simulator/types.js';
 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';
 export interface HlLiveAdapterOptions {
     credentials: HlCredentials;
     mode: TradingMode;
     marketSlippagePct?: number;
+    /** Test seams. Production omits both. */
+    bracketLedger?: BracketLedger;
+    disableUserStream?: boolean;
 }
 export declare class HyperliquidLiveAdapter extends EventEmitter implements IExchangeAdapter {
     private readonly opts;
@@ -15,16 +20,42 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
     private readonly publicApi;
     private readonly infoCache;
     private readonly slippagePct;
+    /** ★ On HL live, brackets are ALWAYS enforced — there is no watcher fallback
+     *  (the stop-watcher has no live metadata) and no `brackets.mode=off` arm:
+     *  the exchange-side legs ARE the safety floor. Lazily constructed so that
+     *  merely constructing the adapter (registry tests) writes no ledger file. */
+    private _coordinator;
+    private userStream;
+    private truthCheckTimer;
+    private truthCheckRunning;
     private _readiness;
     private openOrdersUnavailableUntil;
     constructor(opts: HlLiveAdapterOptions);
+    /** The HL bracket orchestrator — the venue-aware tools (attach_brackets /
+     *  modify_stop / modify_target / audit) drive brackets through this. */
+    getHlBracketCoordinator(): HlBracketCoordinator;
     /** Boot: load markets + asset rules. Readiness gates `create_order` ONLY —
      *  emergency paths never consult it. */
     initialize(): Promise<void>;
+    /** Stop background machinery (tests / graceful shutdown). The exchange-side
+     *  legs keep protecting the position regardless — that is the point. */
+    stop(): void;
     get readiness(): AdapterReadiness;
     get mode(): TradingMode;
     get isLive(): boolean;
-    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, _metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    /**
+     * Post-submit bracket wiring, mirroring the Binance LiveAdapter sequence:
+     * validate direction against the ACTUAL fill (issue #196 — never the limit
+     * price on a filled order), flatten a filled entry whose bracket is invalid
+     * (a naked entry must not survive), detect scale-ins (T-2: HL legs are fixed
+     * size — the ADDED contracts are naked until resized), then register +
+     * attach. Attach itself is async (non-blocking, mirrors Binance) — retries +
+     * auto-flatten handle failures.
+     */
+    private wireBracketsAfterSubmit;
+    private attachOnFillAsync;
+    private resizeAfterScaleInAsync;
     /** Emergency-safe: never pre-gated, never readiness-gated. */
     cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
     /**
@@ -57,7 +88,9 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
     getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
     getLastPrice(symbol: string): Promise<number | null>;
-    /** Attach protective legs to a filled position — ONE signed action for both. */
+    /** Attach protective legs to a filled position — ONE signed action for both.
+     *  Returns the cloids it generated so the coordinator can persist them (a
+     *  cloid is single-use; the ledger must always match the live legs). */
     attachBrackets(args: {
         bracketId: BracketId;
         symbol: string;
@@ -65,7 +98,11 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
         positionSize: number;
         stopPrice?: number;
         targetPrice?: number;
-    }): Promise<CcxtOrder[]>;
+    }): Promise<{
+        orders: CcxtOrder[];
+        slCid?: string;
+        tpCid?: string;
+    }>;
     /**
      * ★ T-2 REQUIREMENT: resize protective legs after a scale-in.
      *
@@ -80,9 +117,30 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
         positionSize: number;
     }): Promise<{
         resized: boolean;
+        slCid?: string;
+        tpCid?: string;
     }>;
+    /** Cancel one bracket leg by cloid. Idempotent: a leg that is already gone
+     *  (triggered / T-1 auto-cancelled / sibling-cancelled) is SUCCESS, not an
+     *  error — the goal state ("leg not on the book") is reached. */
+    cancelBracketLeg(cloid: string, symbol: string): Promise<void>;
     /** Coverage audit — `covered:false` means part of the position is NAKED. */
     auditBracketCoverage(symbol: string, positionSize: number): Promise<import("./hl-brackets.js").CoverageResult>;
+    /** Cancel every OUR-cloid bracket leg on a symbol (recovery-path orphan
+     *  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>;
+    /** 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. */
+    private onUserFill;
+    /** `orderUpdates` is authoritative for leg lifecycle (the ALGO_UPDATE
+     *  analog). A trigger = the exchange closed the position — surface the same
+     *  `drift_detected` close shape the Binance reconciler emits so the journal
+     *  close-bypass cleanup fires at once, not ≤5 min late. */
+    private onUserOrderUpdate;
+    /** T-5 REST truth-check — serialized so a slow pass can't stack. */
+    private runTruthCheck;
     /** Our protective legs currently on the exchange. Throws on unknown (never []). */
     private readLiveLegs;
 }

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

@@ -32,7 +32,21 @@ import { HyperliquidPublicApi } from './hl-public.js';
 import { planBracket, planResize, buildBracketOrders, bracketCoversPosition, } from './hl-brackets.js';
 import { deriveHlNav, toCcxtBalance } from './hl-balance.js';
 import { buildHlOrderCloid, parseHlBracketCloid } from './hl-cloid.js';
+import { BracketLedger } from '../../live/bracket-ledger.js';
+import { generateBracketId } from '../../live/bracket-id.js';
+import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.js';
+import { HlBracketCoordinator, isTerminalBracketState } from './hl-bracket-coordinator.js';
+import { HyperliquidUserStream } from './hl-user-stream.js';
+import { formatError } from '../../logger.js';
 const TAG = 'hl-live-adapter';
+/** Venue-distinct ledger storage — a venue switch on the same box must never
+ *  read the Binance ledger's rows as HL brackets (or vice versa). */
+const HL_LEDGER_PLUGIN_ID = 'reefclaw-paper-trading-hl';
+/** Periodic REST truth-check cadence. T-5: HL's WS replays nothing, and a
+ *  dropped frame while connected is invisible — the sweep is the backstop
+ *  that catches missed fills/triggers and T-2 under-sized legs. ~4 IP weight
+ *  per pass against a 1200/min budget. */
+const TRUTH_CHECK_INTERVAL_MS = 60_000;
 /** Default IOC slippage bound for an emulated market order. 0.5% — NOT ccxt's
  *  5% default, which would be a silent execution-quality disaster. */
 const DEFAULT_MARKET_SLIPPAGE = 0.005;
@@ -45,6 +59,14 @@ export class HyperliquidLiveAdapter extends EventEmitter {
     publicApi;
     infoCache;
     slippagePct;
+    /** ★ On HL live, brackets are ALWAYS enforced — there is no watcher fallback
+     *  (the stop-watcher has no live metadata) and no `brackets.mode=off` arm:
+     *  the exchange-side legs ARE the safety floor. Lazily constructed so that
+     *  merely constructing the adapter (registry tests) writes no ledger file. */
+    _coordinator = null;
+    userStream = null;
+    truthCheckTimer = null;
+    truthCheckRunning = false;
     _readiness = 'INIT_PENDING';
     openOrdersUnavailableUntil = 0;
     constructor(opts) {
@@ -58,6 +80,21 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             return this.publicApi.fetchMeta();
         });
     }
+    /** The HL bracket orchestrator — the venue-aware tools (attach_brackets /
+     *  modify_stop / modify_target / audit) drive brackets through this. */
+    getHlBracketCoordinator() {
+        if (!this._coordinator) {
+            this._coordinator = new HlBracketCoordinator({
+                attachBrackets: (args) => this.attachBrackets(args),
+                resizeBrackets: (args) => this.resizeBrackets(args),
+                cancelBracketLeg: (cloid, symbol) => this.cancelBracketLeg(cloid, symbol),
+                auditBracketCoverage: (symbol, size) => this.auditBracketCoverage(symbol, size),
+                getPositionsOrNull: (symbol) => this.getPositionsOrNull(symbol),
+                closePosition: (symbol, reason) => this.closePosition(symbol, reason),
+            }, this.opts.bracketLedger ?? new BracketLedger(HL_LEDGER_PLUGIN_ID));
+        }
+        return this._coordinator;
+    }
     // ---- Lifecycle ----
     /** Boot: load markets + asset rules. Readiness gates `create_order` ONLY —
      *  emergency paths never consult it. */
@@ -76,6 +113,42 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         }
         // Prime the ADDRESS action budget (the starvation guard, §5.6).
         await this.api.refreshAddressBudget();
+        // ---- Bracket wiring (issue #209) ----
+        // Fast path: the user stream (fills drive attach for resting limits;
+        // orderUpdates is the authoritative leg-lifecycle signal — the HL analog
+        // of Binance's ALGO_UPDATE). Truth path: T-5 proved the WS replays
+        // NOTHING, so every (re)connect AND a periodic sweep run the REST
+        // truth-check in resyncAgainstExchange.
+        if (!this.opts.disableUserStream) {
+            this.userStream = new HyperliquidUserStream({
+                walletAddress: this.opts.credentials.walletAddress,
+                testnet: this.opts.credentials.testnet,
+                callbacks: {
+                    onFill: (fill) => this.onUserFill(fill),
+                    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`);
+                    },
+                },
+            });
+            this.userStream.start();
+        }
+        this.truthCheckTimer = setInterval(() => {
+            void this.runTruthCheck('periodic');
+        }, TRUTH_CHECK_INTERVAL_MS);
+        this.truthCheckTimer.unref?.();
+    }
+    /** Stop background machinery (tests / graceful shutdown). The exchange-side
+     *  legs keep protecting the position regardless — that is the point. */
+    stop() {
+        this.userStream?.stop();
+        this.userStream = null;
+        if (this.truthCheckTimer)
+            clearInterval(this.truthCheckTimer);
+        this.truthCheckTimer = null;
     }
     get readiness() {
         return this._readiness;
@@ -87,7 +160,7 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         return true;
     }
     // ---- Core trading ----
-    async createOrder(symbol, side, type, amount, price, _metadata, options) {
+    async createOrder(symbol, side, type, amount, price, metadata, options) {
         // A market order NEEDS a reference price on HL (no native market order; ccxt
         // derives the slippage cap from it and THROWS without one — verified live).
         let referencePrice = price;
@@ -128,8 +201,163 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         });
         if (!order)
             throw new Error(`Hyperliquid order submission returned no order for ${symbol}`);
+        // ---- Bracket wiring (issue #209): protection attaches HERE, at the fill ----
+        // Closes / reduce-only orders never carry brackets.
+        const hasBracketMeta = metadata !== undefined &&
+            (metadata.stopPrice !== undefined || metadata.targetPrice !== undefined);
+        if (!options?.reduceOnly && hasBracketMeta) {
+            await this.wireBracketsAfterSubmit(symbol, side, order, metadata, cloid);
+        }
         return order;
     }
+    /**
+     * Post-submit bracket wiring, mirroring the Binance LiveAdapter sequence:
+     * validate direction against the ACTUAL fill (issue #196 — never the limit
+     * price on a filled order), flatten a filled entry whose bracket is invalid
+     * (a naked entry must not survive), detect scale-ins (T-2: HL legs are fixed
+     * size — the ADDED contracts are naked until resized), then register +
+     * attach. Attach itself is async (non-blocking, mirrors Binance) — retries +
+     * auto-flatten handle failures.
+     */
+    async wireBracketsAfterSubmit(symbol, side, order, metadata, entryCloid) {
+        const filled = Number(order.filled ?? 0);
+        const isFilled = filled > 0;
+        // Direction check vs the actual fill (filled) or the limit (resting).
+        let dirRef = null;
+        if (isFilled) {
+            const avg = Number(order.average ?? 0);
+            const cost = Number(order.cost ?? 0);
+            dirRef = avg > 0 ? avg : cost > 0 && filled > 0 ? cost / filled : null;
+            if (dirRef === null) {
+                logger.warn(TAG, `Post-fill bracket direction check skipped for ${symbol}: fill price unresolvable — ` +
+                    'the exchange-side trigger validation is the arbiter (issue #196 rule)');
+            }
+        }
+        else {
+            const lim = Number(order.price ?? 0);
+            dirRef = lim > 0 ? lim : null;
+        }
+        let dirMsg = null;
+        if (dirRef !== null && dirRef > 0) {
+            if (metadata.stopPrice !== undefined) {
+                dirMsg = validateStopDirection(side, dirRef, metadata.stopPrice);
+            }
+            if (!dirMsg && metadata.targetPrice !== undefined) {
+                dirMsg = validateTargetDirection(side, dirRef, metadata.targetPrice);
+            }
+        }
+        if (dirMsg) {
+            if (isFilled) {
+                logger.error(TAG, `Post-fill bracket direction invalid for ${symbol} (${dirMsg}, fill=${dirRef}) — ` +
+                    'flattening the just-filled position to avoid a naked entry');
+                let flattened = false;
+                for (let a = 1; a <= 4 && !flattened; a++) {
+                    try {
+                        await this.closePosition(symbol, 'bracket_attach_failed');
+                        flattened = true;
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `Post-fill flatten attempt ${a}/4 for ${symbol} failed: ${msg(err)}`);
+                        if (a < 4)
+                            await new Promise((r) => setTimeout(r, 1500));
+                    }
+                }
+                if (!flattened) {
+                    logger.error(TAG, `CRITICAL: post-fill flatten of ${symbol} FAILED after 4 attempts — position is NAKED, ` +
+                        'immediate operator intervention required');
+                    this.emit('emergency_progress', {
+                        action: 'flatten',
+                        status: 'failed',
+                        symbol,
+                        message: `Naked ${symbol} after invalid bracket — manual close required`,
+                    });
+                }
+            }
+            else {
+                logger.error(TAG, `Post-submit bracket direction invalid for ${symbol} (${dirMsg}) — cancelling the ` +
+                    'resting entry so it cannot fill unprotected');
+                try {
+                    await this.api.cancelOrderByCloid(entryCloid, symbol);
+                }
+                catch (err) {
+                    logger.error(TAG, `Cancel of resting entry after invalid bracket failed: ${msg(err)}`);
+                }
+            }
+            throw new Error(`Bracket rejected (post-submit): ${dirMsg}`);
+        }
+        // ★ Scale-in (T-2): a non-terminal active/partial row means legs are live
+        // at the OLD size — the added contracts are NAKED until resized. Resolve
+        // the new total from exchange truth and resize; on an unknown read the
+        // 60s truth-check sweep is the backstop (and we say so loudly).
+        const ledger = this.getHlBracketCoordinator().getLedger();
+        const existing = ledger.getBySymbol(symbol);
+        if (existing && !isTerminalBracketState(existing.state) && existing.state !== 'pending_entry') {
+            if (isFilled) {
+                void this.resizeAfterScaleInAsync(symbol);
+            }
+            return;
+        }
+        const bracketId = generateBracketId();
+        this.getHlBracketCoordinator().registerEntry({ symbol, side, stopPrice: metadata.stopPrice, targetPrice: metadata.targetPrice }, bracketId, entryCloid);
+        if (isFilled) {
+            // Do NOT await — attach can take seconds; retries + auto-flatten own
+            // the failure path (same contract as Binance attachBracketsAsync).
+            void this.attachOnFillAsync(symbol, filled);
+        }
+        // Resting limit: the user-stream fill event (or the truth-check sweep,
+        // if the fill lands in a WS gap — T-5) drives the attach.
+    }
+    async attachOnFillAsync(symbol, filledSize) {
+        try {
+            const result = await this.getHlBracketCoordinator().attachOnFill(symbol, filledSize);
+            if (!result.ok && result.error !== 'attach_in_flight') {
+                logger.error(TAG, `Bracket attach FAILED for ${symbol} after ${result.attempts} attempts: ${result.error}. ` +
+                    'Auto-flattening position (a naked HL live position has NO fallback watcher).');
+                try {
+                    await this.closePosition(symbol, 'bracket_attach_failed');
+                }
+                catch (err) {
+                    logger.error(TAG, `Auto-flatten after bracket failure ALSO failed: ${msg(err)}`);
+                    this.emit('emergency_progress', {
+                        action: 'flatten',
+                        status: 'failed',
+                        symbol,
+                        message: `Naked ${symbol} after failed bracket attach — manual close required`,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `attachOnFillAsync unexpected error for ${symbol}: ${formatError(err)}`);
+        }
+    }
+    async resizeAfterScaleInAsync(symbol) {
+        try {
+            // Exchange truth for the new total — never arithmetic on local state.
+            let total = null;
+            for (let a = 1; a <= 3 && total === null; a++) {
+                const positions = await this.getPositionsOrNull(symbol);
+                if (positions !== null) {
+                    const pos = positions.find((p) => p.symbol?.startsWith(symbol.split(':')[0]));
+                    total = Math.abs(Number(pos?.contracts ?? 0));
+                }
+                else if (a < 3) {
+                    await new Promise((r) => setTimeout(r, 1500));
+                }
+            }
+            if (total === null) {
+                logger.error(TAG, `scale-in resize for ${symbol}: position size UNKNOWN after 3 reads — the added size ` +
+                    'may be NAKED until the 60s truth-check sweep resizes the legs (T-2)');
+                return;
+            }
+            if (total > 0) {
+                await this.getHlBracketCoordinator().resizeToPosition(symbol, total);
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `scale-in resize for ${symbol} failed: ${formatError(err)} — truth-check sweep will retry`);
+        }
+    }
     /** Emergency-safe: never pre-gated, never readiness-gated. */
     async cancelOrder(orderId, symbol) {
         if (!symbol)
@@ -217,6 +445,16 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         });
         if (!order)
             throw new Error(`closePosition(${symbol}) returned no order`);
+        // Ledger hygiene: mark the bracket row terminal. T-1 auto-cancels the
+        // exchange legs when the position goes flat, so this is bookkeeping (plus
+        // a harmless defensive cancel), never load-bearing. Fire-and-forget — a
+        // close must never fail on ledger cleanup.
+        const row = this.getHlBracketCoordinator().getLedger().getBySymbol(symbol);
+        if (row && !isTerminalBracketState(row.state)) {
+            void this.getHlBracketCoordinator()
+                .cancelBrackets(symbol, `position_closed:${_closeReason ?? 'unspecified'}`)
+                .catch((err) => logger.warn(TAG, `bracket cleanup after close(${symbol}): ${msg(err)}`));
+        }
         return order;
     }
     // ---- State queries ----
@@ -270,7 +508,9 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         return this.publicApi.fetchMarkPrice(symbol);
     }
     // ---- Brackets (the safety floor) ----
-    /** Attach protective legs to a filled position — ONE signed action for both. */
+    /** Attach protective legs to a filled position — ONE signed action for both.
+     *  Returns the cloids it generated so the coordinator can persist them (a
+     *  cloid is single-use; the ledger must always match the live legs). */
     async attachBrackets(args) {
         const plan = planBracket({
             ...args,
@@ -287,7 +527,11 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         const orders = await this.api.submitOrders(buildBracketOrders(plan));
         if (!orders)
             throw new Error(`attachBrackets(${args.symbol}): submission returned nothing`);
-        return orders;
+        return {
+            orders,
+            slCid: plan.legs.find((l) => l.role === 'stop')?.cloid,
+            tpCid: plan.legs.find((l) => l.role === 'target')?.cloid,
+        };
     }
     /**
      * ★ T-2 REQUIREMENT: resize protective legs after a scale-in.
@@ -305,8 +549,16 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         });
         if (plan.noop)
             return { resized: false };
-        await this.api.submitOrders(plan.submit); // protect FIRST
+        const submitted = await this.api.submitOrders(plan.submit); // protect FIRST
+        if (!submitted) {
+            // Old legs untouched — the position keeps its ORIGINAL protection; the
+            // added size stays naked until the caller retries (truth-check sweep).
+            throw new Error(`resizeBrackets(${args.symbol}): submission returned nothing — old legs left in place`);
+        }
         for (const cloid of plan.cancelCloids) {
+            // Register BEFORE the request: the WS 'canceled' event can beat the
+            // ledger update and must not read as stripped protection (canary).
+            this.getHlBracketCoordinator().noteOwnLegCancel(cloid);
             try {
                 await this.api.cancelOrderByCloid(cloid, args.symbol);
             }
@@ -316,13 +568,136 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             }
         }
         logger.info(TAG, `resized brackets on ${args.symbol} to ${args.positionSize} (T-2: HL legs do not auto-resize)`);
-        return { resized: true };
+        let slCid;
+        let tpCid;
+        for (const o of plan.submit) {
+            const parsed = typeof o.cloid === 'string' ? parseHlBracketCloid(o.cloid) : null;
+            if (parsed?.role === 'stop')
+                slCid = o.cloid;
+            if (parsed?.role === 'target')
+                tpCid = o.cloid;
+        }
+        return { resized: true, slCid, tpCid };
+    }
+    /** Cancel one bracket leg by cloid. Idempotent: a leg that is already gone
+     *  (triggered / T-1 auto-cancelled / sibling-cancelled) is SUCCESS, not an
+     *  error — the goal state ("leg not on the book") is reached. */
+    async cancelBracketLeg(cloid, symbol) {
+        this.getHlBracketCoordinator().noteOwnLegCancel(cloid);
+        try {
+            await this.api.cancelOrderByCloid(cloid, symbol);
+        }
+        catch (err) {
+            const m = msg(err).toLowerCase();
+            if (m.includes('never placed') || m.includes('already') || m.includes('filled') || m.includes('not found')) {
+                return; // already gone — idempotent success
+            }
+            throw err;
+        }
     }
     /** Coverage audit — `covered:false` means part of the position is NAKED. */
     async auditBracketCoverage(symbol, positionSize) {
         const live = await this.readLiveLegs(symbol);
         return bracketCoversPosition({ positionSize, liveLegs: live });
     }
+    /** Cancel every OUR-cloid bracket leg on a symbol (recovery-path orphan
+     *  cleanup before a fresh attach). THROWS when order state is unknown —
+     *  the caller logs and still attaches (protection beats hygiene). */
+    async cancelSymbolBracketLegs(symbol) {
+        const legs = await this.readLiveLegs(symbol); // throws on failed fetch
+        let cancelled = 0;
+        for (const leg of legs) {
+            try {
+                await this.cancelBracketLeg(leg.cloid, symbol);
+                cancelled++;
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelSymbolBracketLegs(${symbol}): ${leg.cloid} failed: ${msg(err)}`);
+            }
+        }
+        return cancelled;
+    }
+    // ---- User-stream handlers (issue #209 wiring) ----
+    /** 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) {
+        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);
+            if (!row)
+                return;
+            const sz = Math.abs(Number(fill.sz ?? 0));
+            const before = Math.abs(Number(fill.startPosition ?? 0));
+            const isOpen = (fill.dir ?? '').toLowerCase().startsWith('open');
+            if (!isOpen || sz <= 0)
+                return;
+            const afterTotal = before + sz;
+            if (row.state === 'pending_entry') {
+                void this.attachOnFillAsync(row.symbol, afterTotal);
+            }
+            else if (row.state === 'active' || row.state === 'partial') {
+                // Further fills of the same resting entry — grow the legs (T-2).
+                void this.getHlBracketCoordinator()
+                    .resizeToPosition(row.symbol, afterTotal)
+                    .catch((err) => logger.warn(TAG, `partial-fill resize ${row.symbol}: ${msg(err)} — sweep will retry`));
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `onUserFill handler error: ${formatError(err)}`);
+        }
+    }
+    /** `orderUpdates` is authoritative for leg lifecycle (the ALGO_UPDATE
+     *  analog). A trigger = the exchange closed the position — surface the same
+     *  `drift_detected` close shape the Binance reconciler emits so the journal
+     *  close-bypass cleanup fires at once, not ≤5 min late. */
+    onUserOrderUpdate(update) {
+        try {
+            const transition = this.getHlBracketCoordinator().handleOrderUpdate(update);
+            if (transition === 'triggered_sl' || transition === 'triggered_tp' || transition === 'forced_close') {
+                const row = this.getHlBracketCoordinator().getLedger().getAll().find((r) => update.order.cloid && (r.slCid === update.order.cloid || r.tpCid === update.order.cloid));
+                const symbol = row?.symbol;
+                if (symbol) {
+                    this.emit('drift_detected', {
+                        timestamp: new Date().toISOString(),
+                        drifts: [
+                            {
+                                type: 'closed',
+                                symbol,
+                                localContracts: row?.qty ?? 0,
+                            },
+                        ],
+                    });
+                }
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `onUserOrderUpdate handler error: ${formatError(err)}`);
+        }
+    }
+    /** T-5 REST truth-check — serialized so a slow pass can't stack. */
+    async runTruthCheck(reasonTag) {
+        if (this.truthCheckRunning)
+            return;
+        this.truthCheckRunning = true;
+        try {
+            const { closedSymbols } = await this.getHlBracketCoordinator().resyncAgainstExchange(reasonTag);
+            for (const symbol of closedSymbols) {
+                const row = this.getHlBracketCoordinator().getLedger().getBySymbol(symbol);
+                this.emit('drift_detected', {
+                    timestamp: new Date().toISOString(),
+                    drifts: [{ type: 'closed', symbol, localContracts: row?.qty ?? 0 }],
+                });
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `truth-check(${reasonTag}) failed: ${formatError(err)}`);
+        }
+        finally {
+            this.truthCheckRunning = false;
+        }
+    }
     /** Our protective legs currently on the exchange. Throws on unknown (never []). */
     async readLiveLegs(symbol) {
         const orders = await this.getOpenOrders(symbol); // throws on failed fetch

package/venues/hyperliquid/hl-public.js

@@ -241,7 +241,14 @@ export class HyperliquidPublicApi {
             logger.warn(TAG, `fetchTicker(${symbol}) — no usable price on ticker`);
             return null;
         }
-        const timestamp = Number.isFinite(raw.timestamp) ? Number(raw.timestamp) : Date.now();
+        // Timestamp honesty (issue #202): this fallback serves the background-
+        // refreshed FULL SNAPSHOT price, which can be minutes old. When the raw
+        // ticker carries no timestamp, stamp the snapshot's fetch time — never
+        // Date.now(), which would disguise a stale price as fresh and defeat the
+        // paper engine's stale-quote fill guard.
+        const timestamp = Number.isFinite(raw.timestamp)
+            ? Number(raw.timestamp)
+            : this.tickersCache?.at ?? Date.now();
         return {
             // Key on the symbol the CALLER used so per-symbol maps line up.
             symbol,