@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

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

@@ -0,0 +1,728 @@
+// HyperliquidLiveAdapter — IExchangeAdapter over Hyperliquid (plan §5.1).
+//
+// A SIBLING of Binance's LiveAdapter, not a refactor of it: ~1800 lines of
+// incident-hardened live-money logic stay untouched, and the invariants are held
+// by the SHARED CONTRACT SUITE that runs against both adapters (plan §9.1).
+//
+// THE INHERITED CONTRACTS (each one is an incident, not a preference):
+//   ★ null ≠ empty. `getPositionsOrNull()` returns null when the fetch FAILED;
+//     `getOpenOrders()` THROWS rather than return `[]` on a failed fetch (a
+//     phantom-empty order list once drove ~17 cycles of re-attach against real
+//     protective orders — the 2026-05-14 ATOM naked-bracket loop).
+//   ★ `closePosition()` distinguishes null (unknown) from [] (confirmed flat).
+//   ★ Emergency paths (cancel/close) are NEVER gated by our own pacer or by
+//     readiness — an exit must always be attemptable.
+//   ★ A sticky cooldown after a failed order-list fetch, so a tight agent retry
+//     loop cannot pin the rate budget and blind the whole agent.
+//
+// THE HL-SPECIFIC RULES (all measured on testnet 2026-07-12):
+//   ★ No native market order → IOC limit at a slippage-bounded price, and ccxt
+//     REQUIRES that reference price (it throws without one).
+//   ★ Reduce-only trigger legs auto-cancel on flat and behave OCO (T-1) → no
+//     sibling-canceller needed.
+//   ★ Legs are FIXED SIZE and do NOT follow a scale-in (T-2) → `resizeBrackets()`
+//     exists and the auditor treats an under-sized leg as NAKED size.
+//   ★ Positions/balance are queried on the MASTER address; the agent wallet only
+//     signs (it holds nothing).
+import { EventEmitter } from 'node:events';
+import { logger } from '../../logger.js';
+import { HyperliquidPrivateApi } from './hl-private.js';
+import { HyperliquidInfoCache } from './hl-info-cache.js';
+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;
+/** Sticky cooldown after a failed open-orders fetch (the Binance lesson: the
+ *  SKILL.md audit→attach loop re-calls every ~3s and would pin the budget). */
+const OPEN_ORDERS_COOLDOWN_MS = 45_000;
+export class HyperliquidLiveAdapter extends EventEmitter {
+    opts;
+    api;
+    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) {
+        super();
+        this.opts = opts;
+        this.api = new HyperliquidPrivateApi(opts.credentials);
+        this.publicApi = new HyperliquidPublicApi({ testnet: opts.credentials.testnet });
+        this.slippagePct = clampSlippage(opts.marketSlippagePct ?? DEFAULT_MARKET_SLIPPAGE);
+        this.infoCache = new HyperliquidInfoCache(async () => {
+            // `meta` is a keyless info read — the public client owns it.
+            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. */
+    async initialize() {
+        const markets = await this.api.loadMarkets();
+        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})`);
+        }
+        else {
+            // DEGRADED, not BLOCKED: reads/exits still work; entries are refused
+            // upstream by the readiness gate.
+            this._readiness = 'DEGRADED';
+            logger.error(TAG, 'HL live adapter DEGRADED — markets/asset rules unavailable; entries blocked, exits still work');
+        }
+        // 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;
+    }
+    get mode() {
+        return this.opts.mode;
+    }
+    get isLive() {
+        return true;
+    }
+    // ---- Core trading ----
+    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;
+        if (type === 'market' || referencePrice === undefined) {
+            const mark = await this.publicApi.fetchMarkPrice(symbol);
+            if (mark === null || !(mark > 0)) {
+                throw new Error(`Cannot price a ${type} order on ${symbol}: mark price unavailable. ` +
+                    'Hyperliquid has no native market order — an IOC bound needs a reference price.');
+            }
+            referencePrice = mark;
+        }
+        const submitPrice = type === 'market'
+            ? this.infoCache.marketPrice({
+                symbol,
+                side,
+                referencePrice,
+                slippagePct: this.slippagePct,
+            })
+            : this.infoCache.roundPrice(symbol, referencePrice, side === 'buy' ? 'down' : 'up');
+        const check = this.infoCache.validate({
+            symbol,
+            amount,
+            side,
+            price: type === 'limit' ? submitPrice : undefined,
+            referencePrice,
+        });
+        if (!check.valid)
+            throw new Error(check.error ?? 'Hyperliquid order validation failed');
+        const cloid = options?.clientOrderId ?? buildHlOrderCloid();
+        const order = await this.api.submitOrder({
+            symbol,
+            side,
+            type,
+            amount: check.roundedAmount,
+            price: submitPrice,
+            reduceOnly: options?.reduceOnly,
+            cloid,
+        });
+        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)
+            throw new Error('Hyperliquid cancelOrder requires a symbol');
+        const res = await this.api.cancelOrder(orderId, symbol);
+        if (!res)
+            throw new Error(`Cancel returned no result for ${orderId}`);
+        return res;
+    }
+    /**
+     * Cancel WORKING orders — protective legs are PRESERVED.
+     *
+     * This is the plugin-side half of the kill-preserve rule (the skill has its own,
+     * broader layer). A Kill must never strip the stop off a live position.
+     */
+    async cancelAllOrders(symbol) {
+        const open = await this.api.fetchOpenOrders(symbol);
+        if (open === null) {
+            // Unknown ≠ nothing. Refuse to "cancel all" against an unknown book.
+            throw new Error('cancelAllOrders: could not read open orders (fetch failed) — refusing to act on an unknown order book');
+        }
+        const cancelled = [];
+        for (const o of open) {
+            const cloid = (o.clientOrderId ?? '');
+            // Preserve OUR bracket legs…
+            if (cloid && parseHlBracketCloid(cloid))
+                continue;
+            // …and any other protective order (externally placed stops included).
+            const raw = o.info ?? {};
+            if (raw.reduceOnly === true ||
+                raw.isTrigger === true ||
+                raw.isPositionTpsl === true) {
+                continue;
+            }
+            try {
+                const res = await this.api.cancelOrder(String(o.id), o.symbol ?? symbol ?? '');
+                if (res)
+                    cancelled.push(res);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelAllOrders: cancel ${o.id} failed: ${msg(err)}`);
+            }
+        }
+        return cancelled;
+    }
+    /**
+     * Close a position at market (reduce-only IOC).
+     *
+     * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
+     * against an unknown book could open a NEW position in the opposite direction);
+     * a CONFIRMED-flat account is a benign no-op.
+     */
+    async closePosition(symbol, _closeReason) {
+        const positions = await this.api.fetchPositions(symbol);
+        if (positions === null) {
+            throw new Error(`closePosition(${symbol}): position state UNKNOWN (fetch failed) — refusing to submit a ` +
+                'close that could open an opposite position. Retry once the exchange responds.');
+        }
+        const pos = positions.find((p) => p.symbol?.startsWith(symbol.split(':')[0]));
+        if (!pos || Math.abs(Number(pos.contracts ?? 0)) === 0) {
+            throw new Error(`closePosition(${symbol}): no open position (exchange confirmed flat)`);
+        }
+        const size = Math.abs(Number(pos.contracts));
+        const side = pos.side === 'long' ? 'sell' : 'buy';
+        const mark = await this.publicApi.fetchMarkPrice(symbol);
+        if (mark === null || !(mark > 0)) {
+            throw new Error(`closePosition(${symbol}): mark price unavailable — cannot bound the IOC close`);
+        }
+        const price = this.infoCache.marketPrice({
+            symbol,
+            side,
+            referencePrice: mark,
+            // A CLOSE is not the place to be precious about slippage — use a wider
+            // bound than an entry so an exit does not silently fail to fill.
+            slippagePct: Math.min(this.slippagePct * 2, 0.02),
+        });
+        const order = await this.api.submitOrder({
+            symbol,
+            side,
+            type: 'market',
+            amount: this.infoCache.roundSize(symbol, size),
+            price,
+            reduceOnly: true,
+            cloid: buildHlOrderCloid(),
+        });
+        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 ----
+    async getBalance() {
+        const state = await this.api.rawInfo({
+            type: 'clearinghouseState',
+            user: this.opts.credentials.walletAddress,
+        }).catch(() => null);
+        const nav = deriveHlNav(state);
+        if (!nav) {
+            throw new Error('getBalance: clearinghouseState unreadable — balance UNKNOWN (never reported as $0)');
+        }
+        return toCcxtBalance(nav);
+    }
+    /** Display contract (`?? []`) — the 20+ KPI/display callers. */
+    async getPositions(symbol) {
+        return (await this.api.fetchPositions(symbol)) ?? [];
+    }
+    /** ★ Decision contract — null means UNKNOWN, and destructive paths must not act. */
+    async getPositionsOrNull(symbol) {
+        return this.api.fetchPositions(symbol);
+    }
+    /**
+     * ★ THROWS on a failed fetch — never returns [].
+     *
+     * An empty list is positive information ("the exchange has no orders"); a failed
+     * fetch is not. Collapsing the two is what drove the ATOM naked-bracket loop on
+     * Binance. A sticky cooldown then prevents a retry loop from pinning the budget.
+     */
+    async getOpenOrders(symbol) {
+        const now = Date.now();
+        if (now < this.openOrdersUnavailableUntil) {
+            const waitS = Math.ceil((this.openOrdersUnavailableUntil - now) / 1000);
+            throw new Error(`getOpenOrders: Hyperliquid unavailable — sticky cooldown active (~${waitS}s left, no call made). ` +
+                'Caller must NOT proceed as if the exchange has zero orders.');
+        }
+        const orders = await this.api.fetchOpenOrders(symbol);
+        if (orders === null) {
+            this.openOrdersUnavailableUntil = Date.now() + OPEN_ORDERS_COOLDOWN_MS;
+            throw new Error('getOpenOrders: fetch FAILED (rate limit / transient) — order state UNKNOWN. ' +
+                'This is NOT "zero orders": a caller that treats it as empty would re-attach or cancel ' +
+                'against real protective orders.');
+        }
+        this.openOrdersUnavailableUntil = 0;
+        return orders;
+    }
+    async fetchOrder(orderId, symbol) {
+        return this.api.fetchOrder(orderId, symbol);
+    }
+    async getLastPrice(symbol) {
+        return this.publicApi.fetchMarkPrice(symbol);
+    }
+    // ---- Brackets (the safety floor) ----
+    /** 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,
+            positionSize: this.infoCache.roundSize(args.symbol, args.positionSize),
+            // Round each trigger to the PROTECTIVE side: a long's stop rounds DOWN
+            // (never tighter than the agent asked), its target rounds UP.
+            stopPrice: args.stopPrice === undefined
+                ? undefined
+                : this.infoCache.roundPrice(args.symbol, args.stopPrice, args.positionSide === 'long' ? 'down' : 'up'),
+            targetPrice: args.targetPrice === undefined
+                ? undefined
+                : this.infoCache.roundPrice(args.symbol, args.targetPrice, args.positionSide === 'long' ? 'up' : 'down'),
+        });
+        const orders = await this.api.submitOrders(buildBracketOrders(plan));
+        if (!orders)
+            throw new Error(`attachBrackets(${args.symbol}): submission returned nothing`);
+        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.
+     *
+     * HL legs are FIXED SIZE and do not follow the position (measured). Without this
+     * the added contracts are NAKED. Submit-then-cancel: a moment of over-protection
+     * (harmless — reduce-only cannot flip a position) beats a naked window.
+     */
+    async resizeBrackets(args) {
+        const live = await this.readLiveLegs(args.symbol);
+        const plan = planResize({
+            ...args,
+            positionSize: this.infoCache.roundSize(args.symbol, args.positionSize),
+            liveLegs: live,
+        });
+        if (plan.noop)
+            return { resized: false };
+        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);
+            }
+            catch (err) {
+                // A stale leg that refuses to cancel is over-protection, not risk.
+                logger.warn(TAG, `resizeBrackets: stale leg ${cloid} cancel failed: ${msg(err)}`);
+            }
+        }
+        logger.info(TAG, `resized brackets on ${args.symbol} to ${args.positionSize} (T-2: HL legs do not auto-resize)`);
+        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
+        const legs = [];
+        for (const o of orders) {
+            const cloid = (o.clientOrderId ?? '');
+            const parsed = cloid ? parseHlBracketCloid(cloid) : null;
+            if (!parsed || parsed.role === 'entry')
+                continue;
+            const raw = o.info ?? {};
+            legs.push({
+                role: parsed.role,
+                cloid,
+                size: Number(o.remaining ?? o.amount ?? raw.sz ?? 0),
+                triggerPrice: Number(raw.triggerPx ?? o.price ?? 0),
+            });
+        }
+        return legs;
+    }
+}
+function clampSlippage(pct) {
+    if (!Number.isFinite(pct) || pct <= 0)
+        return DEFAULT_MARKET_SLIPPAGE;
+    return Math.min(pct, 0.02); // hard ceiling 2%
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}