@reefclaw/openclaw-plugin 0.1.0

package/live/live-adapter.js

@@ -0,0 +1,1665 @@
+// LiveAdapter — wraps BinancePrivateApi to implement IExchangeAdapter.
+// Integrates all Sprint 2 safety modules: rate limiter, intent journal,
+// order poller, slippage tracker, and position reconciler.
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { BinancePrivateApi } from '../ccxt/binance-private.js';
+import { ExchangeInfoCache } from './exchange-info-cache.js';
+import { BinanceRateLimiter, ENDPOINT_WEIGHTS } from './rate-limiter.js';
+import { IntentJournal } from './intent-journal.js';
+import { OrderPoller } from './order-poller.js';
+import { SlippageTracker } from './slippage-tracker.js';
+import { PositionReconciler } from './reconciler.js';
+import { parseExchangeError } from './exchange-errors.js';
+import { logger, formatError } from '../logger.js';
+import { getQuoteWalletBalance } from '../balance-utils.js';
+import { LiveBalanceEnricher, utcDateString, utcMidnightMs } from './live-balance-enricher.js';
+import { DepositTracker } from './deposit-tracker.js';
+import { BracketLedger, normalizeBracketSymbol } from './bracket-ledger.js';
+import { noteResponseWeight, assertNotBanned, noteBinanceError, noteSuccess } from '../ccxt/binance-ban-gate.js';
+import { BracketManager } from './bracket-manager.js';
+import { BracketReconciler } from './bracket-reconciler.js';
+import { LiveBracketApi } from './live-bracket-api.js';
+import { generateBracketId, buildBracketCid, parseBracketCid } from './bracket-id.js';
+import { validateStopDirection, validateTargetDirection } from './bracket-params.js';
+import { bracketsEnabled } from '../config/brackets-config.js';
+import { userDataStreamEnabled, userDataStreamAuthoritative, DEFAULT_TUNABLES as USER_DATA_STREAM_DEFAULT_TUNABLES, } from '../config/user-data-stream-config.js';
+import { UserDataStreamController } from './user-data-stream-controller.js';
+import { assertNotShuttingDown, registerOp } from '../lifecycle/shutdown-coordinator.js';
+import { updateMfe } from '../mfe.js';
+import { computeInvalidationHit } from '../pinned-plan.js';
+const TAG = 'live-adapter';
+/** Minimum interval between /fapi/v1/income re-anchor calls.
+ *
+ *  Endpoint: GET /fapi/v1/income, weight=30, no per-call cap — verified
+ *  against developers.binance.com/.../Get-Income-History (2026-05-16).
+ *
+ *  Why this can safely be long (NOT 60s):
+ *    - `sessionStartNav = wallet_now − netNonTransfer = wallet_at_midnight`
+ *      is INVARIANT under non-transfer activity within a UTC day — wallet
+ *      grows by exactly `netNonTransfer` (realized PnL + fees + funding) as
+ *      trades close, so a re-poll recomputes the same constant.
+ *    - The dashboard's Realized + Day P&L are derived by the webapp from
+ *      WS-fresh wallet + unrealized (`totalPnl − unrealizedPnl`), NOT from
+ *      this seed (see live-balance-enricher.seedRealizedPnlToday doc +
+ *      webapp slices/trades.ts:updateLiveKpi). `recordFill` is unused in
+ *      prod, so the seed never moves between re-anchors anyway.
+ *  The only re-anchors that change anything: startup (done once in
+ *  initialize()), UTC-midnight rollover (FORCED — bypasses this throttle
+ *  via the dayRolled branch), and catching a BNFCR/multi-asset transfer
+ *  type DepositTracker can't see (rare; a long safety reconcile suffices —
+ *  DepositTracker handles ordinary transfers within its own poll).
+ *
+ *  Polling this every 60s was ~30 weight/min of permanent, redundant IP
+ *  weight that fed the 2026-05-14→16 steady-state weight floor which paced
+ *  out the bracket audit's getOpenOrders and blinded the agent on live
+ *  protection. 30 min preserves the BNFCR safety reconcile while cutting
+ *  the load ~97% (30w/60s → ~1w/min). Env-overridable for emergency tuning
+ *  without a redeploy; clamp 60s–6h. */
+const INCOME_REFRESH_MIN_INTERVAL_MS = (() => {
+    const raw = Number(process.env.RC_INCOME_REFRESH_MS);
+    return Number.isFinite(raw) && raw >= 60_000 && raw <= 21_600_000
+        ? raw
+        : 30 * 60_000;
+})();
+/** Generate a Binance-compatible client order ID (max 36 chars, alphanumeric). */
+function generateClientOrderId() {
+    return randomUUID();
+}
+/**
+ * Backfill `balance.free[cur] = total[cur]` for currencies where Binance's CCXT
+ * response left the per-currency `free` and `used` at zero despite a non-zero
+ * total. Only safe when `used` is zero — otherwise the exchange really is
+ * reserving margin and we must not inflate availability.
+ */
+export function repairFreeFromTotal(balance) {
+    if (!balance.total || !balance.free)
+        return;
+    for (const cur of Object.keys(balance.total)) {
+        const total = balance.total[cur] ?? 0;
+        const used = balance.used?.[cur] ?? 0;
+        const free = balance.free[cur] ?? 0;
+        if (total > 0 && free <= 0 && used <= 0) {
+            balance.free[cur] = total;
+            // Mirror into the per-currency object shape if present.
+            const perCur = balance[cur];
+            if (perCur && typeof perCur === 'object' && 'free' in perCur) {
+                perCur.free = total;
+            }
+        }
+    }
+}
+export class LiveAdapter extends EventEmitter {
+    mode;
+    isLive = true;
+    api;
+    sizeCapMultiplier;
+    maxPositionUSDT;
+    exchangeInfo = new ExchangeInfoCache();
+    isHedgeMode = false;
+    // Sticky cooldown for getOpenOrders. When fetchOpenOrders is rate-limited
+    // (null / paced / banned), the agent's SKILL.md-mandated recovery loop
+    // (audit_bracket_protection → attach_brackets) re-calls it every ~3 s.
+    // Each unscoped call is 40 weight, so the loop ALONE pins the IP weight at
+    // the pacer ceiling → every other read is shed → the agent never completes
+    // a heartbeat → no operator messages, naked position never healed
+    // (2026-05-15 incident). This makes the failure STICKY: after a rate-limit
+    // failure, every getOpenOrders short-circuits with the same error WITHOUT
+    // touching Binance for the cooldown, so the weight window drains, the
+    // pacer clears, and the next post-cooldown call can actually succeed.
+    getOpenOrdersUnavailableUntil = 0;
+    static OPEN_ORDERS_RL_COOLDOWN_MS = 45_000;
+    // Sprint 2 safety modules — all owned by the adapter
+    rateLimiter = new BinanceRateLimiter();
+    intentJournal;
+    orderPoller;
+    slippageTracker = new SlippageTracker();
+    reconciler;
+    enricher;
+    depositTracker;
+    // Exchange-native bracket orders — null when mode='off' (legacy stop-watcher owns it).
+    bracketMode;
+    bracketLedger = null;
+    bracketManager = null;
+    bracketReconciler = null;
+    // User-data WebSocket stream — null when mode='off' (REST polling owns reads).
+    // In Phase 1 this is dead code on prod (mode='off' is the default); the wiring
+    // is in place so Phase 2 onwards only requires a flag flip. Read paths
+    // (getPositions/getBalance/getOpenOrders) remain REST-backed until
+    // userDataStreamAuthoritative(mode) is true (observe/enforce — Phase 2+).
+    userDataStreamMode;
+    userDataStream = null;
+    // Per-cid last-seen ALGO_UPDATE status — the authoritative WS bracket-leg
+    // signal for resolveBracketLegLiveness()'s Tier-1 fast-path. onAlgoUpdate
+    // does NOT terminalize the ledger on CANCELED (by design — see its doc
+    // block), so the ledger row state is a LOSSY proxy that misses the exact
+    // spiral cancel. This map keeps the real per-leg WS truth. Insertion-order
+    // bounded (oldest evicted past the cap) — cids are one-shot per bracket.
+    wsAlgoStatusByCid = new Map();
+    static WS_ALGO_STATUS_CAP = 1000;
+    // Freshness window for the symbol-scoped trusted-live sweep
+    // (findTrustedLiveBracketCidsForSymbol). The 2026-05-16 INJ spiral's fresh
+    // leg is seconds old when the guard needs it, so this only has to be
+    // generous enough to never miss a genuinely-live leg while short enough
+    // that an ancient record can't suppress a real repair forever. Past this
+    // age the sweep ignores the record and the caller falls back to the
+    // per-leg REST authority — never to a guess.
+    static WS_LIVE_LEG_MAX_AGE_MS = 5 * 60_000;
+    // Session-start NAV — captured once at initialization, used for drawdown calculation.
+    // If not yet captured, getSessionStartNav() returns null.
+    _sessionStartNav = null;
+    // Last time the realized-today seed + sessionStartNav were re-anchored from
+    // Binance's income endpoint. Throttled to INCOME_REFRESH_MIN_INTERVAL_MS
+    // (30 min default) because the anchor is invariant within a UTC day — see
+    // that constant's doc for why a re-poll is otherwise pure redundant
+    // weight. UTC-midnight rollover forces a refresh regardless of throttle.
+    lastIncomeRefreshMs = 0;
+    // Day-anchor tracking. utcDayAnchor = the UTC date the current sessionStartNav
+    // is computed against. Crossing UTC midnight forces a re-anchor on the next
+    // refresh tick regardless of throttle.
+    incomeAnchorUtcDay = utcDateString(Date.now());
+    // Per-symbol position metadata for live mode. Live positions live on Binance,
+    // but the agent-supplied entry context (thesis, setupType, regime, scorecard)
+    // and the running MFE state must live somewhere on our side. In-memory only —
+    // a plugin restart wipes this. Bracket ledger covers stopPrice persistence
+    // through restarts; thesis/setup metadata is recoverable from the create_order
+    // log / heartbeat reasoning if needed. Seeded in createOrder, updated on
+    // getPositions tick, dropped on closePosition or when a symbol vanishes from
+    // the open-positions snapshot.
+    liveMetadata = new Map();
+    // Readiness state — mutable, starts INIT_PENDING
+    _readiness = 'INIT_PENDING';
+    get readiness() {
+        return this._readiness;
+    }
+    /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
+    getSessionStartNav() {
+        return this._sessionStartNav;
+    }
+    constructor(config, mode, microLiveConfig, bracketMode = 'off', userDataStreamMode = 'off', userDataStreamTunables = USER_DATA_STREAM_DEFAULT_TUNABLES, 
+    /** TRADE_AUDIT_TRAIL_PLAN Phase 1 — optional audit-trail wiring.  Wired
+     *  through to UserDataStreamController.  Absent today on every existing
+     *  call site (default off); operator-driven once activation is approved. */
+    tradeIngest, 
+    /** Position-decision auto-capture wiring. When provided alongside
+     *  tradeIngest, ws-ingest also routes every TRADE event through
+     *  `onWsFillObserved` to capture limit-order entries + scale-ins
+     *  (PR1 deferral resolution, 2026-05-03). Optional for back-compat. */
+    autoCapture) {
+        super();
+        this.mode = mode;
+        this.bracketMode = bracketMode;
+        this.userDataStreamMode = userDataStreamMode;
+        this.api = new BinancePrivateApi(config);
+        if (mode === 'MICRO_LIVE') {
+            // sizeCapMultiplier is 1.0 — the agent already sizes for the real wallet.
+            // maxPositionUSDT is the safety cap (e.g., $50 max per position).
+            this.sizeCapMultiplier = 1.0;
+            this.maxPositionUSDT = microLiveConfig?.maxPositionUSDT ?? 50;
+        }
+        else {
+            this.sizeCapMultiplier = 1.0;
+            this.maxPositionUSDT = null;
+        }
+        // Initialize safety modules
+        this.intentJournal = new IntentJournal();
+        this.orderPoller = new OrderPoller(this);
+        this.reconciler = new PositionReconciler(this);
+        this.enricher = new LiveBalanceEnricher();
+        this.depositTracker = new DepositTracker(this.api);
+        // Bracket-orders system — only initialised when the operator has flipped
+        // the flag to 'observe' or 'enforce'. In 'off' mode the legacy stop-watcher
+        // continues to own protection.
+        if (bracketsEnabled(this.bracketMode)) {
+            this.bracketLedger = new BracketLedger();
+            const liveBracketApi = new LiveBracketApi(this.api);
+            this.bracketManager = new BracketManager(liveBracketApi, this.bracketLedger);
+            this.bracketManager.on('event', (ev) => this.emit('bracket_event', ev));
+            this.bracketReconciler = new BracketReconciler(this, this.bracketLedger, this.bracketManager, liveBracketApi);
+            this.bracketReconciler.on('drift', (d) => this.emit('bracket_drift', d));
+            logger.info(TAG, `Bracket orders ENABLED in mode=${this.bracketMode}`);
+        }
+        // Forward poller events
+        this.orderPoller.on('order_event', (event) => {
+            this.emit('order_event', event);
+            // Track slippage on fills
+            if (event.type === 'filled' && event.order.average != null) {
+                this.slippageTracker.recordFill({
+                    orderId: event.orderId,
+                    symbol: event.order.symbol,
+                    side: event.order.side,
+                    expectedPrice: event.order.price ?? event.order.average,
+                    actualPrice: event.order.average,
+                    amount: event.order.filled,
+                    cost: event.order.cost,
+                    fee: event.order.fee?.cost ?? 0,
+                });
+            }
+            // Attach brackets when a pending limit entry fills. For market orders
+            // the attach happens inline in createOrder; this branch covers limits.
+            if (event.type === 'filled' && this.bracketManager && this.bracketLedger) {
+                const pending = this.bracketLedger.getBySymbol(event.order.symbol);
+                if (pending && pending.state === 'pending_entry') {
+                    const filledAmount = event.order.filled;
+                    if (filledAmount > 0) {
+                        this.attachBracketsAsync(event.order.symbol, filledAmount);
+                    }
+                }
+            }
+        });
+        // Forward reconciler events
+        this.reconciler.on('drift_detected', (result) => {
+            this.emit('drift_detected', result);
+        });
+        // User-data WebSocket stream — constructed eagerly but only started in
+        // `initialize()` when mode!='off'. The controller defaults are safe to
+        // instantiate without I/O (no network calls until .start()).
+        if (userDataStreamEnabled(this.userDataStreamMode)) {
+            this.userDataStream = new UserDataStreamController(this.api, {
+                mode: this.userDataStreamMode,
+                testnet: config.testnet ?? false,
+                tunables: userDataStreamTunables,
+                tradeIngest,
+                autoCapture,
+            });
+            this.userDataStream.on('snapshotApplied', (snap) => this.emit('user_data_snapshot', snap));
+            this.userDataStream.on('drift', (drift) => this.emit('user_data_drift', drift));
+            this.userDataStream.on('forcedResync', (cause) => this.emit('user_data_forced_resync', cause));
+            this.userDataStream.on('marginCall', (ev) => this.emit('user_data_margin_call', ev));
+            this.userDataStream.on('reconnecting', (attempt, delay) => this.emit('user_data_reconnecting', attempt, delay));
+            // AUTHORITATIVE bracket-lifecycle signal. Replaces REST-audit guessing
+            // (the audit→re-attach spiral that flushed live positions on
+            // 2026-05-15). Doc-verified status semantics drive the action.
+            this.userDataStream.on('algoUpdate', (ev) => this.onAlgoUpdate(ev));
+            logger.info(TAG, `User-data stream ENABLED in mode=${this.userDataStreamMode}`);
+        }
+        logger.info(TAG, `LiveAdapter created in ${mode} mode (size cap: ${this.sizeCapMultiplier * 100}%, max pos USDT: ${this.maxPositionUSDT ?? 'unlimited'})`);
+    }
+    /** Get the underlying BinancePrivateApi (for advanced queries like fetchTicker). */
+    getApi() {
+        return this.api;
+    }
+    /** Get the exchange info cache (for symbol rules). */
+    getExchangeInfo() {
+        return this.exchangeInfo;
+    }
+    /** Whether the account is in hedge mode. */
+    getIsHedgeMode() {
+        return this.isHedgeMode;
+    }
+    /** Get safety modules for external access (dashboard, tools, etc.). */
+    getRateLimiter() { return this.rateLimiter; }
+    getIntentJournal() { return this.intentJournal; }
+    getOrderPoller() { return this.orderPoller; }
+    getSlippageTracker() { return this.slippageTracker; }
+    getReconciler() { return this.reconciler; }
+    getEnricher() { return this.enricher; }
+    getDepositTracker() { return this.depositTracker; }
+    /** Active user-data-stream mode. `'off'` when the feature flag is disabled. */
+    getUserDataStreamMode() { return this.userDataStreamMode; }
+    /** User-data stream controller, or null if mode='off'. Used by dashboards
+     *  and diagnostic tools to read the live-state store + health. */
+    getUserDataStream() { return this.userDataStream; }
+    /**
+     * Post-registration async initialization.
+     * Must complete before create_order is allowed (readiness gate).
+     * Emergency controls (cancel, close) work regardless of readiness.
+     */
+    async initialize() {
+        try {
+            // 1. Validate API permissions
+            logger.info(TAG, 'Validating API permissions...');
+            const perms = await this.api.validatePermissions();
+            if (!perms.canReadBalance || !perms.canReadPositions) {
+                logger.error(TAG, `API key lacks required permissions: ${perms.errors.join(', ')}`);
+                this._readiness = 'BLOCKED';
+                this.emit('readiness_changed', this._readiness, 'API key missing read permissions');
+                return;
+            }
+            logger.info(TAG, 'API permissions validated');
+            // 2. Fetch real balance and capture session-start NAV (once)
+            const balance = await this.api.fetchBalance();
+            const quoteBalance = getQuoteWalletBalance(balance);
+            if (this._sessionStartNav == null) {
+                // Anchor today's KPIs to Binance's income endpoint so the dashboard
+                // Realized + Day P&L match the Binance app even across plugin
+                // restarts. One call, two uses of the same `netNonTransfer` figure:
+                //   - Realized KPI = netNonTransfer (REALIZED_PNL + COMMISSION +
+                //     FUNDING_FEE + rebates). This is what the Binance app shows
+                //     under "Today's Realized PNL" — verified against the mobile
+                //     app on 2026-05-14 (Binance -$5.98 vs ours when we were
+                //     using gross-only -$3.70 = $2.28 fees/funding gap).
+                //   - sessionStartNav anchor = wallet_now − netNonTransfer = the
+                //     wallet at UTC midnight. Day P&L = NAV − sessionStartNav.
+                // The `realizedPnlGross` field on the breakdown is retained for
+                // debug logging only — it does NOT match Binance's UI label.
+                // Refreshed periodically inside getBalance() — see refreshIncomeAnchor.
+                // forced:true → never-paced context. This boot anchor establishes
+                // the wallet_at_midnight baseline the ENTIRE Day-P&L / Realized KPI
+                // chain is derived from; it must not be shed by a heartbeat scan
+                // burst (2026-05-16 KPI incident).
+                const utcMidnight = utcMidnightMs();
+                const breakdown = await this.api.fetchTodayIncomeBreakdown(utcMidnight, {
+                    forced: true,
+                });
+                if (breakdown != null) {
+                    this.enricher.seedRealizedPnlToday(breakdown.netNonTransfer);
+                    const navAtMidnight = quoteBalance - breakdown.netNonTransfer;
+                    this._sessionStartNav = navAtMidnight;
+                    this.enricher.setSessionStartNav(navAtMidnight);
+                    this.lastIncomeRefreshMs = Date.now();
+                    logger.info(TAG, `Session-start NAV anchored: ${navAtMidnight.toFixed(4)} (wallet ${quoteBalance.toFixed(4)} − netNonTransfer ${breakdown.netNonTransfer.toFixed(4)}); realizedPnlGross ${breakdown.realizedPnlGross.toFixed(4)} (debug only)`);
+                }
+                else {
+                    // null≠empty: do NOT coerce to {0,0} (that pins sessionStartNav to
+                    // wallet_now and zeroes Day P&L — 2026-05-16 KPI incident). Leave
+                    // the anchor uncaptured and lastIncomeRefreshMs at 0 so
+                    // refreshIncomeAnchor() self-heals on the next getBalance cycle
+                    // (forced while _sessionStartNav == null → lands as soon as we're
+                    // not under a real ban).
+                    logger.warn(TAG, 'Session-start NAV NOT anchored — /fapi/v1/income unavailable at boot (real ban/network). Day P&L anchors on the first successful income refresh; refusing to fabricate a {0,0} anchor.');
+                }
+                // Arm the deposit tracker from this instant forward; any pre-init
+                // transfers are already baked into the starting wallet so they must
+                // not be double-counted.
+                this.depositTracker.reset(Date.now());
+            }
+            logger.info(TAG, `Live balance: ${quoteBalance}`);
+            // 3. Check for micro-live minimum balance
+            if (this.mode === 'MICRO_LIVE' && this.maxPositionUSDT != null && quoteBalance < this.maxPositionUSDT) {
+                logger.warn(TAG, `Balance ${quoteBalance} is below micro-live max position ${this.maxPositionUSDT}`);
+                // Not blocking — but log the warning
+            }
+            // 4. Load exchange info + position mode BEFORE position check.
+            //    Emergency controls (close/cancel) need these even in DEGRADED state.
+            logger.info(TAG, 'Loading exchange info...');
+            await this.loadExchangeInfo();
+            await this.detectPositionMode();
+            // 4b. Hedge-mode accounts are not supported in v1 (one-way only — see
+            //     CLAUDE.md "User-Data WebSocket Stream" + BRACKET_ORDERS_DESIGN.md
+            //     §2). The entry path only sends `positionSide` when a caller-
+            //     supplied option is present (the tool path never supplies one) and
+            //     bracket legs always send `reduceOnly:true` with no `positionSide` —
+            //     both are rejected by Binance in Hedge Mode (positionSide is
+            //     mandatory; reduceOnly must not be sent). Going READY here would let
+            //     the agent place entries that fill while their brackets are rejected,
+            //     i.e. naked live positions. Refuse trading instead. Emergency
+            //     controls (close/cancel) are NOT readiness-gated and still work.
+            if (this.isHedgeMode) {
+                this._readiness = 'BLOCKED';
+                const reason = 'Hedge-mode account not supported in v1 — switch the Binance Futures account to One-Way position mode to enable trading';
+                this.emit('readiness_changed', this._readiness, reason);
+                logger.error(TAG, `Adapter BLOCKED: ${reason}`);
+                return;
+            }
+            // 5. Fetch existing positions (reconciliation)
+            const positions = await this.api.fetchPositions();
+            if (positions && positions.length > 0) {
+                logger.warn(TAG, `Found ${positions.length} existing position(s) on exchange at startup`);
+                this._readiness = 'DEGRADED';
+                this.emit('readiness_changed', this._readiness, 'Existing positions found — auto-acknowledging after lockout');
+                this.emit('positions_found_on_startup', { count: positions.length, positions });
+                // Auto-acknowledge after 15s lockout — the agent needs to place protective
+                // stops on existing positions, which requires READY status. Staying DEGRADED
+                // forever leaves live positions unprotected after every deploy/restart.
+                setTimeout(() => {
+                    if (this._readiness === 'DEGRADED') {
+                        logger.info(TAG, 'Auto-acknowledging existing positions after startup lockout');
+                        void this.acknowledgePositions();
+                    }
+                }, 16_000);
+                return;
+            }
+            // 6. Compact the intent journal (prevents unbounded file growth)
+            this.intentJournal.compact();
+            // 7. Resolve any pending order intents from a prior crash
+            const unresolved = this.intentJournal.getUnresolved();
+            let hasUnresolvedIntents = false;
+            if (unresolved.length > 0) {
+                logger.warn(TAG, `Resolving ${unresolved.length} unresolved order intents from prior session`);
+                for (const intent of unresolved) {
+                    try {
+                        const existing = await this.api.fetchOrderByClientId(intent.clientOrderId, intent.symbol);
+                        if (existing) {
+                            this.intentJournal.updateIntent(intent.clientOrderId, { status: 'confirmed', exchangeOrderId: existing.id });
+                            logger.info(TAG, `Resolved intent ${intent.clientOrderId} → order ${existing.id} (${existing.status})`);
+                        }
+                        else {
+                            this.intentJournal.updateIntent(intent.clientOrderId, { status: 'failed', error: 'Order not found on exchange after restart' });
+                            logger.warn(TAG, `Intent ${intent.clientOrderId} not found on exchange — marked failed`);
+                        }
+                    }
+                    catch (err) {
+                        // Resolution failed — this intent's state is ambiguous
+                        logger.error(TAG, `Failed to resolve intent ${intent.clientOrderId}: ${formatError(err)}`);
+                        hasUnresolvedIntents = true;
+                    }
+                }
+            }
+            // If any intents couldn't be resolved, stay DEGRADED — operator must acknowledge
+            if (hasUnresolvedIntents) {
+                const stillUnresolved = this.intentJournal.getUnresolved();
+                logger.warn(TAG, `${stillUnresolved.length} intents still unresolved — holding DEGRADED`);
+                this._readiness = 'DEGRADED';
+                this.emit('readiness_changed', this._readiness, `${stillUnresolved.length} order intents could not be resolved — operator acknowledgment required`);
+                this.emit('unresolved_intents', { count: stillUnresolved.length, intents: stillUnresolved });
+                // Reconciler still starts — read-only ops are fine in DEGRADED
+                this.reconciler.start();
+                return;
+            }
+            // 7. Start periodic position reconciliation (every 60s)
+            this.reconciler.start();
+            // 7b. Bracket restart recovery — one pass before accepting orders, then
+            //     start the periodic reconciler. Any unknown orphans on the exchange
+            //     (from a prior crash) are cancelled here; stale brackets on
+            //     already-closed positions are cleaned up.
+            if (this.bracketReconciler) {
+                try {
+                    const result = await this.bracketReconciler.runPass();
+                    const notable = result.drifts.filter(d => d.kind !== 'healthy');
+                    if (notable.length > 0) {
+                        logger.warn(TAG, `Bracket restart recovery found ${notable.length} drift(s): ${notable.map(d => `${d.kind}:${d.symbol ?? '?'}`).join(', ')}`);
+                    }
+                    this.bracketReconciler.start();
+                }
+                catch (err) {
+                    logger.error(TAG, `Bracket restart recovery pass failed (non-fatal): ${formatError(err)}`);
+                    // Still start the periodic reconciler — next pass may succeed.
+                    this.bracketReconciler.start();
+                }
+            }
+            // 8. Start the user-data WebSocket stream (if enabled). Fires after the
+            //    REST reconciliation is clean so the initial snapshot doesn't race
+            //    with a DEGRADED-state entry. On hedge-mode accounts we refuse to
+            //    enable observe/enforce — the store is one-way-only in v1.
+            if (this.userDataStream) {
+                if (this.isHedgeMode && (this.userDataStreamMode === 'observe' || this.userDataStreamMode === 'enforce')) {
+                    logger.error(TAG, `User-data stream ${this.userDataStreamMode} refused on hedge-mode account — falling back to REST reads`);
+                }
+                else {
+                    try {
+                        await this.userDataStream.start();
+                        logger.info(TAG, `User-data stream started in mode=${this.userDataStreamMode}`);
+                    }
+                    catch (err) {
+                        // Fail-open: a broken WS shouldn't block trading on REST.
+                        logger.error(TAG, `User-data stream start failed (continuing on REST): ${formatError(err)}`);
+                    }
+                }
+            }
+            // 9. All clear
+            this._readiness = 'READY';
+            this.emit('readiness_changed', this._readiness, `Adapter ready in ${this.mode} mode`);
+            logger.info(TAG, `Adapter READY in ${this.mode} mode (${this.exchangeInfo.size} symbols, ${this.isHedgeMode ? 'hedge' : 'one-way'} mode)`);
+        }
+        catch (err) {
+            logger.error(TAG, `Init failed: ${formatError(err)}`);
+            this._readiness = 'BLOCKED';
+            this.emit('readiness_changed', this._readiness, formatError(err));
+        }
+    }
+    /**
+     * Acknowledge existing positions on startup.
+     * Transitions DEGRADED → READY. Exchange info + position mode are already loaded
+     * (they're loaded before the position check in initialize()).
+     */
+    async acknowledgePositions() {
+        if (this._readiness !== 'DEGRADED') {
+            logger.warn(TAG, `acknowledgePositions called in ${this._readiness} state — ignored`);
+            return;
+        }
+        // Start position reconciler (was skipped in initialize() when DEGRADED due to existing positions)
+        this.reconciler.start();
+        // Bracket restart recovery + periodic reconciler — mirrors the block in initialize()
+        // that's skipped when startup finds existing positions (early return before step 7b).
+        if (this.bracketReconciler) {
+            try {
+                const result = await this.bracketReconciler.runPass();
+                const notable = result.drifts.filter(d => d.kind !== 'healthy');
+                if (notable.length > 0) {
+                    logger.warn(TAG, `Bracket restart recovery found ${notable.length} drift(s): ${notable.map(d => `${d.kind}:${d.symbol ?? '?'}`).join(', ')}`);
+                }
+                this.bracketReconciler.start();
+            }
+            catch (err) {
+                logger.error(TAG, `Bracket restart recovery pass failed (non-fatal): ${formatError(err)}`);
+                this.bracketReconciler.start();
+            }
+        }
+        // User-data WebSocket stream — mirrors the block in initialize() that's skipped
+        // on the existing-positions DEGRADED path. Without this, the stream is constructed
+        // but never connects whenever the plugin restarts with an open position.
+        if (this.userDataStream) {
+            if (this.isHedgeMode && (this.userDataStreamMode === 'observe' || this.userDataStreamMode === 'enforce')) {
+                logger.error(TAG, `User-data stream ${this.userDataStreamMode} refused on hedge-mode account — falling back to REST reads`);
+            }
+            else {
+                try {
+                    await this.userDataStream.start();
+                    logger.info(TAG, `User-data stream started in mode=${this.userDataStreamMode}`);
+                }
+                catch (err) {
+                    logger.error(TAG, `User-data stream start failed (continuing on REST): ${formatError(err)}`);
+                }
+            }
+        }
+        this._readiness = 'READY';
+        this.emit('readiness_changed', this._readiness, 'Positions acknowledged — trading enabled');
+        logger.info(TAG, 'Positions acknowledged — adapter now READY (reconciler started)');
+    }
+    /**
+     * Tear down background loops so the adapter can be replaced at runtime
+     * (e.g. when the operator changes credentials or trading mode from the
+     * dashboard). Must be called before discarding the LiveAdapter reference
+     * or the poller + reconciler timers will keep firing against stale state.
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    shutdown() {
+        try {
+            this.orderPoller.stopAll();
+        }
+        catch (err) {
+            logger.warn(TAG, `orderPoller.stopAll failed: ${formatError(err)}`);
+        }
+        try {
+            this.reconciler.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `reconciler.stop failed: ${formatError(err)}`);
+        }
+        try {
+            this.bracketReconciler?.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `bracketReconciler.stop failed: ${formatError(err)}`);
+        }
+        // User-data stream stop is async; fire-and-forget since shutdown is sync.
+        if (this.userDataStream) {
+            void this.userDataStream.stop().catch((err) => logger.warn(TAG, `userDataStream.stop failed: ${formatError(err)}`));
+        }
+        this._readiness = 'BLOCKED';
+        this.removeAllListeners();
+        logger.info(TAG, 'LiveAdapter shut down');
+    }
+    // ---- IExchangeAdapter implementation ----
+    async createOrder(symbol, side, type, amount, price, metadata, options) {
+        // Refuse new entries during shutdown. Risk-reducing orders (emergency
+        // flatten, reduceOnly close) bypass this gate so the operator can still
+        // size down mid-deploy. In-flight orders that already started continue.
+        const isRiskReducing = options?.emergency === true || options?.reduceOnly === true;
+        if (!isRiskReducing) {
+            assertNotShuttingDown(`createOrder(${symbol} ${side} ${type})`);
+        }
+        const releaseOp = registerOp(`createOrder(${symbol} ${side} ${type}${isRiskReducing ? ' reduce' : ''})`);
+        try {
+            // ---- Rate limit check (skipped for emergency close/flatten) ----
+            const weight = ENDPOINT_WEIGHTS.createOrder ?? 1;
+            if (!options?.emergency) {
+                const rateCheck = this.rateLimiter.canSubmitOrder(weight);
+                if (!rateCheck.allowed) {
+                    throw new Error(`Rate limit: ${rateCheck.reason}. Retry after ${rateCheck.retryAfterMs}ms.`);
+                }
+            }
+            // ---- Size caps ----
+            let effectiveAmount = amount * this.sizeCapMultiplier;
+            // Apply max position USDT cap for micro-live
+            if (this.maxPositionUSDT != null) {
+                const ticker = await this.api.fetchTicker(symbol);
+                this.rateLimiter.recordQuery(ENDPOINT_WEIGHTS.fetchTicker ?? 1);
+                const tickerPrice = ticker?.last;
+                if (tickerPrice && tickerPrice > 0) {
+                    const maxAmount = this.maxPositionUSDT / tickerPrice;
+                    if (effectiveAmount > maxAmount) {
+                        logger.info(TAG, `Micro-live cap: reducing amount from ${effectiveAmount} to ${maxAmount} (max $${this.maxPositionUSDT})`);
+                        effectiveAmount = maxAmount;
+                    }
+                }
+                else if (!isRiskReducing) {
+                    // The ticker read is SHED_FIRST under weight pressure — silently
+                    // proceeding uncapped exactly when Binance is pacing us would bypass
+                    // the micro-live size cap on a NEW exposure. Reject instead. Risk-
+                    // reducing orders (emergency / reduceOnly) pass: they cannot increase
+                    // the position, and blocking a close is worse than an unverified cap.
+                    throw new Error(`Micro-live size cap ($${this.maxPositionUSDT}) cannot be verified — ticker unavailable for ${symbol}; ` +
+                        'rejecting order rather than proceeding uncapped');
+                }
+            }
+            // ---- Exchange filter validation ----
+            const refPrice = price ?? (await this.api.fetchTicker(symbol))?.last ?? undefined;
+            const validation = this.exchangeInfo.validate(symbol, effectiveAmount, price, refPrice);
+            if (!validation.valid) {
+                throw new Error(`Order validation failed: ${validation.error}`);
+            }
+            // ---- Bracket direction sanity-check (PRE-submission) ----
+            // A flipped stop/target sign must be caught BEFORE the entry order is
+            // submitted. The old code only validated this AFTER createOrder returned,
+            // so a sign error on a market entry left the position live + unprotected
+            // (the caller saw only the thrown error). Validate against the best
+            // pre-trade reference: the limit price, else the ticker ref price. The
+            // post-fill block below stays as defense-in-depth.
+            if (metadata && (metadata.stopPrice !== undefined || metadata.targetPrice !== undefined)) {
+                const entryRef = price ?? refPrice ?? 0;
+                if (entryRef > 0) {
+                    if (metadata.stopPrice !== undefined) {
+                        const msg = validateStopDirection(side, entryRef, metadata.stopPrice);
+                        if (msg)
+                            throw new Error(`Bracket rejected (pre-submit): ${msg}`);
+                    }
+                    if (metadata.targetPrice !== undefined) {
+                        const msg = validateTargetDirection(side, entryRef, metadata.targetPrice);
+                        if (msg)
+                            throw new Error(`Bracket rejected (pre-submit): ${msg}`);
+                    }
+                }
+            }
+            // ---- Idempotency: clientOrderId + intent journal ----
+            const clientOrderId = options?.clientOrderId ?? generateClientOrderId();
+            // Capture expected price for slippage tracking
+            const expectedPrice = type === 'limit' ? (price ?? refPrice ?? 0) : (refPrice ?? 0);
+            // Write intent to journal BEFORE submitting to exchange
+            this.intentJournal.recordIntent({
+                clientOrderId,
+                symbol,
+                side,
+                type,
+                amount: validation.roundedAmount,
+                price: validation.roundedPrice,
+            });
+            // Build CCXT params — these are actually sent to Binance
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ccxtParams = {
+                newClientOrderId: clientOrderId,
+            };
+            if (this.isHedgeMode && options?.positionSide) {
+                ccxtParams.positionSide = options.positionSide;
+            }
+            else if (!this.isHedgeMode && options?.reduceOnly) {
+                ccxtParams.reduceOnly = true;
+            }
+            // ---- Submit to exchange ----
+            logger.info(TAG, `Submitting ${type} ${side} ${validation.roundedAmount} ${symbol} @ ${validation.roundedPrice ?? 'market'} (clientOrderId: ${clientOrderId})`);
+            let order;
+            try {
+                order = await this.api.createOrder(symbol, side, type, validation.roundedAmount, validation.roundedPrice, ccxtParams);
+                this.syncRateLimits();
+                this.rateLimiter.recordOrder(weight);
+            }
+            catch (err) {
+                // ---- Exchange error handling ----
+                const parsed = parseExchangeError(err);
+                if (parsed.isNetworkError) {
+                    // Network timeout — check if order went through via clientOrderId
+                    logger.warn(TAG, `Network error on submit — checking by clientOrderId ${clientOrderId}`);
+                    const existing = await this.api.fetchOrderByClientId(clientOrderId, symbol);
+                    if (existing) {
+                        // The order DID land during the timeout. Returning here (the old
+                        // behaviour) skipped ALL post-submission bookkeeping — slippage,
+                        // limit-order polling, live metadata, and critically bracket
+                        // registration/attach — so a market entry that filled during the
+                        // timeout came back "recovered" yet permanently NAKED. Resume the
+                        // normal path instead: assign `order` and fall through so brackets
+                        // attach exactly as if createOrder had returned this order.
+                        logger.info(TAG, `Order found after timeout: ${existing.id} status=${existing.status} — resuming full post-submission bookkeeping (brackets/poller/slippage)`);
+                        this.intentJournal.updateIntent(clientOrderId, { status: 'confirmed', exchangeOrderId: existing.id });
+                        this.syncRateLimits();
+                        this.rateLimiter.recordOrder(weight);
+                        order = existing;
+                    }
+                    else {
+                        // Not found — mark failed, throw the original error
+                        this.intentJournal.updateIntent(clientOrderId, { status: 'failed', error: parsed.humanMessage });
+                        throw new Error(parsed.humanMessage);
+                    }
+                }
+                else {
+                    this.intentJournal.updateIntent(clientOrderId, { status: 'failed', error: parsed.humanMessage });
+                    throw new Error(parsed.humanMessage);
+                }
+            }
+            // ---- Post-submission bookkeeping ----
+            this.intentJournal.updateIntent(clientOrderId, { status: 'confirmed', exchangeOrderId: order.id });
+            // Track slippage for market orders that filled immediately
+            if (order.status === 'closed' && order.average != null && expectedPrice > 0) {
+                this.slippageTracker.recordFill({
+                    orderId: order.id,
+                    clientOrderId,
+                    symbol,
+                    side,
+                    expectedPrice,
+                    actualPrice: order.average,
+                    amount: order.filled,
+                    cost: order.cost,
+                    fee: order.fee?.cost ?? 0,
+                });
+            }
+            // Start polling for limit orders that are still open
+            if (order.status === 'open') {
+                this.orderPoller.startPolling(order.id, symbol);
+            }
+            // ---- Per-symbol metadata store (Component C: MFE tracking) ----
+            // Capture entry context so getPositions can decorate Binance's position
+            // snapshot with thesis/setup + freeze the at-fill stop into
+            // originalStopPrice for R-multiple calculations. Only seed on what looks
+            // like a NEW position (no existing entry) — scale-ins preserve the
+            // original entry's frozen stop.
+            if (metadata && !this.liveMetadata.has(symbol)) {
+                const seeded = { ...metadata };
+                if (seeded.originalStopPrice === undefined && seeded.stopPrice !== undefined) {
+                    seeded.originalStopPrice = seeded.stopPrice;
+                }
+                // mfePeakPrice is left undefined — getPositions seeds it from the first
+                // observed markPrice rather than guessing here (createOrder doesn't have
+                // a reliable fill price for limit orders).
+                this.liveMetadata.set(symbol, seeded);
+            }
+            // ---- Bracket orders ----
+            // If the feature flag is on AND the agent asked for at least one protective
+            // leg, register the bracket and (for market orders) attach immediately.
+            // Limit orders defer attach to the poller's 'filled' event handler.
+            if (this.bracketManager && this.bracketLedger && metadata && (metadata.stopPrice !== undefined || metadata.targetPrice !== undefined)) {
+                // Defense-in-depth: the pre-submission check above already rejected sign
+                // errors against the ref price, but re-check against the actual fill
+                // (order.average) in case the fill landed across the level. Crucially, a
+                // failure HERE is post-submission: bare-throwing would abandon a live
+                // position (filled market order) or a resting entry that fills naked
+                // (open limit). So clean up BEFORE throwing.
+                const refPrice = order.average ?? order.price ?? price ?? 0;
+                if (refPrice > 0) {
+                    let dirMsg = null;
+                    if (metadata.stopPrice !== undefined) {
+                        dirMsg = validateStopDirection(side, refPrice, metadata.stopPrice);
+                    }
+                    if (!dirMsg && metadata.targetPrice !== undefined) {
+                        dirMsg = validateTargetDirection(side, refPrice, metadata.targetPrice);
+                    }
+                    if (dirMsg) {
+                        if (order.status === 'closed' && order.filled > 0) {
+                            logger.error(TAG, `Post-fill bracket direction invalid for ${symbol} (${dirMsg}) — flattening the just-filled position to avoid a naked entry`);
+                            // We have HARD evidence the entry filled (status=closed, filled>0).
+                            // closePosition throws "No open position" when its attempt-1
+                            // fetchPositions returns a *confirmed-empty* snapshot — which, in
+                            // the moments right after a fill, is almost always Binance
+                            // position-state lagging the order response, NOT a real flat.
+                            // Accepting that single failure would fail open and leave the
+                            // position naked (the exact high-risk branch this cleanup exists
+                            // for). Retry across the lag window instead of trusting one snapshot.
+                            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: ${formatError(err)}`);
+                                    if (a < 4)
+                                        await sleep(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 if (order.status === 'open') {
+                            logger.error(TAG, `Post-submit bracket direction invalid for ${symbol} (${dirMsg}) — cancelling the resting entry order so it can't fill unprotected`);
+                            try {
+                                await this.api.cancelOrderByClientId(clientOrderId, symbol);
+                            }
+                            catch (err) {
+                                logger.error(TAG, `Cancel of resting entry after invalid bracket failed for ${symbol}: ${formatError(err)}`);
+                            }
+                        }
+                        throw new Error(`Bracket rejected (post-submit): ${dirMsg}`);
+                    }
+                }
+                const bracketId = generateBracketId();
+                this.bracketManager.registerEntry({ symbol, side, stopPrice: metadata.stopPrice, targetPrice: metadata.targetPrice }, bracketId, buildBracketCid(bracketId, 'entry'));
+                if (order.status === 'closed' && order.filled > 0) {
+                    // Market order (or limit-that-filled-instantly) — attach now.
+                    // We do NOT await: attach can take seconds and we don't want to block
+                    // the agent's createOrder return. Auto-flatten handles failures.
+                    this.attachBracketsAsync(symbol, order.filled);
+                }
+                // For status='open' limit orders, the order_event handler attaches
+                // brackets on fill.
+            }
+            logger.info(TAG, `Order confirmed: ${order.id} status=${order.status} filled=${order.filled}`);
+            return order;
+        }
+        finally {
+            releaseOp();
+        }
+    }
+    /**
+     * Attach brackets in the background. Auto-flattens on failure per locked
+     * decision #2. Never throws — errors are surfaced via emitted events and
+     * the subsequent flatten.
+     */
+    async attachBracketsAsync(symbol, entryAmount) {
+        if (!this.bracketManager)
+            return;
+        try {
+            const result = await this.bracketManager.attachBrackets(symbol, entryAmount);
+            if (!result.ok) {
+                logger.error(TAG, `Bracket attach FAILED for ${symbol} after ${result.attempts} attempts: ${result.error}. Auto-flattening position.`);
+                // Best-effort emergency close. closePosition has its own retry logic.
+                try {
+                    await this.closePosition(symbol, 'bracket_attach_failed');
+                }
+                catch (err) {
+                    logger.error(TAG, `Auto-flatten after bracket failure ALSO failed: ${formatError(err)}`);
+                    // Operator alert handled by the bracket.attach_failed event listener upstream.
+                }
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `attachBracketsAsync unexpected error for ${symbol}: ${formatError(err)}`);
+        }
+    }
+    /**
+     * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
+     *
+     * Why this exists (2026-05-15 RCA, doc-verified): pre-fix the plugin
+     * learned bracket state by REST-polling `audit_bracket_protection` /
+     * `fetchOpenOrders` and *guessing* — under a 429 storm that produced the
+     * audit→re-attach→cancel spiral that flushed live positions. Binance
+     * already PUSHES authoritative conditional-order lifecycle. Doc-exact
+     * status semantics (developers.binance.com → Event Algo Order Update):
+     *
+     *   EXPIRED   = SYSTEM cancel. The canonical trigger is "GTE_GTC
+     *               conditional + position closed → Binance auto-cancels the
+     *               surviving sibling". So EXPIRED on our bracket cid ⇒ the
+     *               position just closed by a non-close_position path (bracket
+     *               fill, manual, opposite-side). EXPECTED — not a fault.
+     *   TRIGGERED / FINISHED = the bracket fired (SL/TP hit) → position closed.
+     *   CANCELED  = MANUAL cancel (an explicit cancelOrder from us). Post the
+     *               bracket-reconciler fix we should NOT be doing this while a
+     *               position is open; if we see it, it's the canary that some
+     *               *other* path still strips protection — WARN loudly.
+     *
+     * For EXPIRED/TRIGGERED/FINISHED we (a) mark the ledger terminal so the
+     * attach-brackets re-attach loop STOPS chasing a bracket Binance already
+     * removed, and (b) emit the SAME `drift_detected` shape the position
+     * reconciler emits, so the existing, tested close-bypass cleanup
+     * (`onReconcilerObservedClose` in index.ts) runs immediately instead of
+     * up to 60 s later — which is what clears the stale state-store entry and
+     * stops the NEXT entry on the symbol being mis-classified as a scale-in
+     * (the bug that left fresh positions naked). No auto-flatten here: that
+     * stays deferred until this signal has soaked.
+     */
+    onAlgoUpdate(ev) {
+        const cid = ev.clientAlgoId ?? '';
+        const parsed = parseBracketCid(cid);
+        if (!parsed)
+            return; // not one of our rc-*-{s,t} bracket legs
+        const symbol = normalizeBracketSymbol(ev.symbol);
+        const row = this.bracketLedger?.getBySymbol(symbol);
+        const status = ev.status.toUpperCase();
+        // Record the authoritative per-leg WS status for the Tier-1 fast-path of
+        // resolveBracketLegLiveness(). Every parsed rc-* lifecycle event, every
+        // branch — including CANCELED, which the ledger deliberately does NOT
+        // terminalize. Re-setting an existing cid keeps its insertion position
+        // (Map semantics) so the cap evicts genuinely-old legs, not active ones.
+        this.wsAlgoStatusByCid.set(cid, { status, ts: Date.now(), symbol });
+        if (this.wsAlgoStatusByCid.size > LiveAdapter.WS_ALGO_STATUS_CAP) {
+            const oldest = this.wsAlgoStatusByCid.keys().next().value;
+            if (oldest !== undefined)
+                this.wsAlgoStatusByCid.delete(oldest);
+        }
+        const emitSyntheticClose = (reasonTag) => {
+            // Pre-close size from the reconciler's last poll snapshot — the position
+            // only just closed, so its last-known contracts are still cached there.
+            // The close-bypass cleanup (onReconcilerObservedClose) needs a non-zero
+            // size to post the synthetic close that flips webapp positions.status to
+            // 'closed'. A hardcoded 0 here made every bracket-fill close SKIP that DB
+            // update (fillSize>0 guard) while still wiping the state-store — leaking
+            // the position as status='open' forever. The reduce-only-fill close
+            // handler (ws-ingest → onWsFillObserved) is the primary, exact-PnL closer;
+            // this stays the backstop for a missed WS fill.
+            let lastContracts = 0;
+            try {
+                const lastKnown = this.reconciler
+                    .getLastExchangePositions()
+                    .find((p) => normalizeBracketSymbol(p.symbol) === symbol);
+                if (lastKnown && Number.isFinite(lastKnown.contracts)) {
+                    lastContracts = Math.abs(lastKnown.contracts);
+                }
+            }
+            catch {
+                /* best-effort — fall back to 0 (state-store still gets cleaned) */
+            }
+            // Mirror PositionReconciler's ReconciliationResult shape so the
+            // existing index.ts `drift_detected` → onReconcilerObservedClose
+            // wiring fires without new plumbing.
+            this.emit('drift_detected', {
+                timestamp: new Date().toISOString(),
+                hasDrift: true,
+                exchangePositions: [],
+                exchangeBalance: null,
+                exchangeOpenOrders: [],
+                drifts: [{
+                        symbol,
+                        localSide: row?.entrySide ?? null,
+                        exchangeSide: null,
+                        localContracts: lastContracts,
+                        exchangeContracts: 0,
+                        type: 'closed',
+                    }],
+                source: `algo_update:${reasonTag}`,
+            });
+        };
+        if (status === 'EXPIRED' || status === 'TRIGGERED' || status === 'FINISHED') {
+            if (row && row.state !== 'cancelled' && row.state !== 'triggered_sl'
+                && row.state !== 'triggered_tp' && row.state !== 'failed') {
+                const nextState = status === 'TRIGGERED' || status === 'FINISHED'
+                    ? (parsed.role === 'stop' ? 'triggered_sl' : 'triggered_tp')
+                    : 'cancelled';
+                const closeReason = nextState === 'cancelled'
+                    ? 'cancelled_auto'
+                    : (nextState === 'triggered_sl' ? 'triggered_sl' : 'triggered_tp');
+                try {
+                    this.bracketLedger?.markState(symbol, nextState, { closeReason });
+                    logger.info(TAG, `ALGO_UPDATE ${status} on ${symbol} (${cid}, role=${parsed.role}) — ` +
+                        `ledger→${nextState}. Position closed by exchange/bracket; ` +
+                        `firing close-bypass cleanup so the next entry isn't mis-classified as scale-in.`);
+                }
+                catch (err) {
+                    logger.warn(TAG, `ALGO_UPDATE ${status}: ledger markState(${symbol}) failed: ${formatError(err)}`);
+                }
+            }
+            // Always signal the close even if the ledger row was already terminal
+            // — the state-store/webapp cleanup is idempotent and we want it prompt.
+            emitSyntheticClose(status.toLowerCase());
+            return;
+        }
+        if (status === 'CANCELED') {
+            // Doc: CANCELED = an explicit cancelOrder. Post the bracket-reconciler
+            // null-collapse fix WE should not be cancelling a live position's
+            // brackets. If the ledger still thinks this bracket is active, some
+            // path is still stripping protection — surface it loudly. We do NOT
+            // mark terminal (that would block a legit re-attach by the now-safe
+            // audit/attach path) and we do NOT auto-flatten (deferred).
+            if (row && (row.state === 'active' || row.state === 'partial' || row.state === 'attaching')) {
+                logger.warn(TAG, `ALGO_UPDATE CANCELED on ${symbol} (${cid}) while ledger=${row.state} — ` +
+                    `a bracket leg was explicitly cancelled while we believe the position ` +
+                    `is still protected. This should not happen post the reconciler fix; ` +
+                    `investigate the cancel source (reason=${ev.reason ?? 'none'}).`);
+            }
+            else {
+                logger.info(TAG, `ALGO_UPDATE CANCELED on ${symbol} (${cid}) — ledger=${row?.state ?? 'none'} (benign: cancel of an already-terminal/absent bracket).`);
+            }
+            return;
+        }
+        // NEW / TRIGGERING / REJECTED — informational. REJECTED is worth a WARN
+        // (Binance refused the conditional order — e.g. margin check).
+        if (status === 'REJECTED') {
+            logger.warn(TAG, `ALGO_UPDATE REJECTED on ${symbol} (${cid}) reason=${ev.reason ?? 'none'} — bracket leg refused by Binance; position may be unprotected.`);
+        }
+    }
+    /** Expose the bracket manager for agent-facing tools (modify_stop, etc.).
+     *  Returns null when bracket mode is 'off'. */
+    getBracketManager() {
+        return this.bracketManager;
+    }
+    /** Expose the bracket ledger for reconciliation + admin queries. */
+    getBracketLedger() {
+        return this.bracketLedger;
+    }
+    /** Is the user-data WS store currently trusted (seeded + fresh + no gap)?
+     *  The Tier-1 gate for resolveBracketLegLiveness — when false the WS
+     *  per-cid signal is NOT consulted (a stale/gapped stream that missed a
+     *  CANCELED would otherwise yield a false 'live' on a naked leg — the exact
+     *  flaw the layered design exists to prevent). Null stream (mode=off) ⇒
+     *  never trusted ⇒ always the REST authority. */
+    isUserDataStoreTrusted() {
+        try {
+            return this.userDataStream?.isStoreTrusted() ?? false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Authoritative per-bracket-leg liveness — the Phase 2 disambiguator that
+     *  replaces inferring presence/absence from a broad openOrders snapshot
+     *  (the SOL/INJ spiral root: a *successful* empty /fapi/v1/openAlgoOrders
+     *  is NOT proof a leg is gone).
+     *
+     *  Precedence (the agreed layering):
+     *   1. WS fast-path — ONLY behind isUserDataStoreTrusted(): the real
+     *      per-cid ALGO_UPDATE status (incl. CANCELED, which the ledger does
+     *      NOT record). Zero weight, sub-second. No record for the cid ⇒ no
+     *      WS opinion ⇒ fall through (never infer from absence).
+     *   2. REST authority — queryAlgoOrderStatus(cid): a DIRECT weight-1
+     *      question about that exact order id. Used when WS is untrusted or
+     *      silent on the cid.
+     *   3. 'unknown' — both unavailable. The d59e51b safe floor: callers MUST
+     *      refuse destructive action and retry; NEVER treat 'unknown' as
+     *      'terminal'/'stale'.
+     *
+     *  'live'     = leg is on the exchange (do NOT reattach/clobber).
+     *  'terminal' = positively confirmed gone (CANCELED/EXPIRED/REJECTED) or
+     *               fired (TRIGGERED/FINISHED) — only this licenses repair.
+     *  'unknown'  = could not get an answer — safe-wait. */
+    async resolveBracketLegLiveness(cid) {
+        if (!cid)
+            return 'unknown';
+        const classify = (status) => status === 'NEW' || status === 'WORKING' || status === 'TRIGGERING'
+            ? 'live'
+            : 'terminal'; // CANCELED | EXPIRED | REJECTED | TRIGGERED | FINISHED
+        // Tier 1 — trusted WS fast-path (zero weight).
+        if (this.isUserDataStoreTrusted()) {
+            const rec = this.wsAlgoStatusByCid.get(cid);
+            if (rec)
+                return classify(rec.status);
+            // Healthy stream but no lifecycle event ever seen for this cid — do
+            // NOT infer from absence; fall to the REST authority.
+        }
+        // Tier 2 — REST authority (weight 1, WS-independent).
+        const restStatus = await this.api.queryAlgoOrderStatus(cid);
+        if (restStatus)
+            return classify(restStatus);
+        // Tier 3 — no answer anywhere.
+        return 'unknown';
+    }
+    /** Symbol-scoped generalization of the trusted-WS fast-path — the
+     *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
+     *
+     *  `resolveBracketLegLiveness(cid)` answers about ONE cid. The spiral is:
+     *  a prior `attach_brackets` reattach placed a FRESH bracket that is live
+     *  on the exchange under a NEW cid, while the ledger row still holds the
+     *  PREVIOUS, genuinely-terminal cids. Classifying only the ledger's cids
+     *  yields a false 'stale' → clear+reattach cancels the live fresh bracket
+     *  → naked → audit unprotected → attach → spiral (prod: INJ/USDT cancelled
+     *  every ~15-40s for hours). This asks the question the ledger cids can't:
+     *  "is ANY rc-* bracket leg for this symbol live RIGHT NOW, under any cid?"
+     *
+     *  Trust model (identical to resolveBracketLegLiveness Tier-1): the WS map
+     *  is consulted ONLY when `isUserDataStoreTrusted()` (seeded + fresh +
+     *  no-gap — the property that guarantees no missed CANCELED, so a record
+     *  reading 'live' really is live). When the store is NOT trusted this
+     *  returns `{ trusted:false, liveCids:[] }` and the caller must NOT infer
+     *  "no live leg" from it — it falls back to the per-leg REST authority and,
+     *  failing that, refuses the destructive action (the d59e51b safe floor).
+     *  A record older than WS_LIVE_LEG_MAX_AGE_MS is ignored (caller falls back
+     *  too) so a stale 'live' can never suppress a genuine repair forever. */
+    findTrustedLiveBracketCidsForSymbol(symbol) {
+        if (!this.isUserDataStoreTrusted())
+            return { trusted: false, liveCids: [] };
+        const norm = normalizeBracketSymbol(symbol);
+        const now = Date.now();
+        const liveCids = [];
+        for (const [cid, rec] of this.wsAlgoStatusByCid) {
+            if (rec.symbol !== norm)
+                continue;
+            if (now - rec.ts > LiveAdapter.WS_LIVE_LEG_MAX_AGE_MS)
+                continue;
+            if (rec.status === 'NEW' || rec.status === 'WORKING' || rec.status === 'TRIGGERING') {
+                liveCids.push(cid);
+            }
+        }
+        return { trusted: true, liveCids };
+    }
+    /** Cancel every bracket-tagged (SL or TP) open order for a symbol. Used by
+     *  the `attach_brackets` recovery tool to clear stale bracket orders before
+     *  re-attaching a fresh pair. Does not touch non-bracket orders. Returns
+     *  the number successfully cancelled. Errors are logged + swallowed —
+     *  "already gone" is treated as success by the underlying cancel path. */
+    async cancelSymbolBracketOrders(symbol) {
+        const open = await this.api.fetchOpenOrders(symbol);
+        if (open === null) {
+            // null = order state UNKNOWN — returning 0 here would read as
+            // "checked, no orphans" in the attach_brackets tool result. Throw
+            // instead; the caller logs the cleanup failure and still proceeds
+            // with the attach (protection beats orphan hygiene).
+            throw new Error(`cancelSymbolBracketOrders(${symbol}): fetchOpenOrders returned null (order state unknown)`);
+        }
+        const all = open;
+        let cancelled = 0;
+        for (const o of all) {
+            if (!o.clientOrderId)
+                continue;
+            const parsed = parseBracketCid(o.clientOrderId);
+            if (!parsed || (parsed.role !== 'stop' && parsed.role !== 'target'))
+                continue;
+            try {
+                await this.api.cancelOrderByClientId(o.clientOrderId, symbol);
+                cancelled++;
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelSymbolBracketOrders: ${o.clientOrderId} failed: ${formatError(err)}`);
+            }
+        }
+        return cancelled;
+    }
+    async cancelOrder(orderId, symbol) {
+        return this.api.cancelOrder(orderId, symbol);
+    }
+    async cancelAllOrders(symbol) {
+        // Emergency path — NO readiness gate, 3x retry, progress emission.
+        const openOrders = await this.api.fetchOpenOrders(symbol);
+        if (openOrders === null) {
+            // null = order state UNKNOWN (read failed / paced / banned) — never
+            // report "nothing to cancel" off a failed read. Proceed into the retry
+            // loop: api.cancelAllOrders re-fetches and throws on null, so a
+            // transient blip recovers on retry and a persistent outage escalates
+            // to the loud MANUAL-INTERVENTION failure instead of a silent [].
+            logger.warn(TAG, `KILL: fetchOpenOrders returned null (order state unknown)${symbol ? ` for ${symbol}` : ''} — proceeding with cancel attempts`);
+        }
+        else if (openOrders.length === 0) {
+            return [];
+        }
+        const countLabel = openOrders === null ? 'unknown #' : String(openOrders.length);
+        logger.warn(TAG, `KILL: cancelling ${countLabel} orders${symbol ? ` for ${symbol}` : ''}`);
+        this.emit('emergency_progress', { action: 'kill', status: 'in_progress', orders: openOrders?.length ?? -1 });
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                await this.api.cancelAllOrders(symbol);
+                logger.info(TAG, `KILL: ${countLabel} orders cancelled (attempt ${attempt})`);
+                this.emit('emergency_progress', { action: 'kill', status: 'completed' });
+                // Return empty — all orders are cancelled. Don't fabricate status on the pre-cancel snapshot
+                // because some may have filled between the fetch and the cancel.
+                return [];
+            }
+            catch (err) {
+                logger.warn(TAG, `KILL attempt ${attempt}/3 failed: ${formatError(err)}`);
+                if (attempt < 3)
+                    await sleep(1000);
+            }
+        }
+        // All retries exhausted
+        const msg = 'MANUAL INTERVENTION REQUIRED — cancel orders manually on Binance';
+        logger.error(TAG, msg);
+        this.emit('emergency_progress', { action: 'kill', status: 'failed', message: msg });
+        throw new Error(msg);
+    }
+    async closePosition(symbol, closeReason) {
+        // Risk-reducing — allowed during shutdown, but tracked so the drain awaits
+        // it before the process exits. Without tracking, a SIGTERM mid-close could
+        // leave the position open on Binance with the plugin restarting and
+        // assuming it's still tracked.
+        const releaseOp = registerOp(`closePosition(${symbol})`);
+        try {
+            // Emergency path — NO readiness gate, 3x retry, reduceOnly safety.
+            // closeReason flows onto the symbol's metadata so the next getPositions
+            // cycle's eventual cleanup carries the right reason. The metadata entry
+            // itself is dropped after the close completes (see end of this method).
+            const reasonSuffix = closeReason ? ` (reason=${closeReason})` : '';
+            logger.warn(TAG, `FLATTEN: closing position ${symbol}${reasonSuffix}`);
+            if (closeReason) {
+                const existing = this.liveMetadata.get(symbol);
+                if (existing)
+                    this.liveMetadata.set(symbol, { ...existing, closeReason });
+            }
+            // ---- Trusted position read FIRST — BEFORE the destructive bracket cancel.
+            // The old order (cancelBrackets, then fetchPositions) opened a naked
+            // window: cancelling protection off a position we then couldn't confirm
+            // (paced/failed read → throw) or that didn't exist left live exposure
+            // with no brackets and no close order. Only a TRUSTED read that confirms
+            // an open position licenses stripping its protection.
+            //
+            // CRITICAL null-vs-empty split (2026-05-15 XRP phantom-close incident).
+            // `BinancePrivateApi.fetchPositions` returns `null` on a FAILED fetch
+            // (429 / rate-limited / transient) and `[]` only when the exchange
+            // CONFIRMS zero positions. Conflating them here is catastrophic: under
+            // a rate-limit storm a still-open naked position 429s → `null` → the
+            // old `!positions` branch either threw "No open position" (the agent
+            // interpreted that as "position gone from exchange truth" and recorded
+            // a phantom close, abandoning a live losing short) or, on a retry,
+            // returned a SYNTHETIC closed-success. "Couldn't read" must NEVER be
+            // reported as "closed". Only a real, non-null empty array means flat.
+            // Mirrors the getOpenOrders / reconciler null-collapse rule. See
+            // `memory/feedback_getopenorders_null_collapse_naked_loop.md`.
+            const preCheck = await this.api.fetchPositions(symbol);
+            if (preCheck === null) {
+                throw new Error(`closePosition: exchange position state UNAVAILABLE for ${symbol} ` +
+                    `(fetchPositions failed — 429 / rate-limited / transient). Refusing ` +
+                    `to cancel brackets or treat this as "closed": the position may ` +
+                    `still be open and protected. Retry once exchange reads recover; ` +
+                    `do NOT record a close.`);
+            }
+            if (preCheck.length === 0) {
+                // Confirmed flat (trusted empty read) — nothing to close, and
+                // critically the brackets were NOT touched.
+                throw new Error(`No open position for ${symbol} on exchange`);
+            }
+            let lastKnownContracts = Math.abs(preCheck[0].contracts ?? 0);
+            // Cancel any attached brackets — leaving them on the exchange after
+            // the close would book a phantom reverse trade if the trigger fires on a
+            // re-entry. cancelBrackets is idempotent and swallows not-found errors.
+            if (this.bracketManager) {
+                try {
+                    await this.bracketManager.cancelBrackets(symbol, closeReason ?? 'close_position');
+                }
+                catch (err) {
+                    logger.warn(TAG, `cancelBrackets during closePosition failed: ${formatError(err)}`);
+                }
+            }
+            for (let attempt = 1; attempt <= 3; attempt++) {
+                // Fresh position snapshot each attempt (position may have partially closed)
+                const positions = await this.api.fetchPositions(symbol);
+                // Same null-vs-empty split as the pre-check above.
+                if (positions === null) {
+                    throw new Error(`closePosition: exchange position state UNAVAILABLE for ${symbol} ` +
+                        `(fetchPositions failed — 429 / rate-limited / transient). Refusing ` +
+                        `to treat this as "closed": the position may still be open. Retry ` +
+                        `once exchange reads recover; do NOT record a close.`);
+                }
+                if (positions.length === 0) {
+                    // The pre-check CONFIRMED an open position, so a trusted empty read
+                    // now means it closed while we were working — a prior attempt's
+                    // market order landed, a bracket fired in the race window, or an
+                    // external close. Success either way (confirmed empty, not a failed read).
+                    logger.info(TAG, `FLATTEN: ${symbol} confirmed flat on attempt ${attempt}`);
+                    this.emit('emergency_progress', { action: 'flatten', status: 'completed', symbol });
+                    // Return a synthetic closed order
+                    return { id: 'flatten-done', symbol, side: 'sell', type: 'market', status: 'closed', amount: 0, filled: 0, remaining: 0, average: null, price: null, cost: 0, fee: { cost: 0, currency: 'USDT' }, timestamp: Date.now(), datetime: new Date().toISOString(), timeInForce: 'GTC' };
+                }
+                const position = positions[0];
+                lastKnownContracts = Math.abs(position.contracts ?? 0);
+                const closeSide = position.side === 'long' ? 'sell' : 'buy';
+                // Build CCXT params with reduceOnly/positionSide for close safety
+                const clientOrderId = generateClientOrderId();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const ccxtParams = { newClientOrderId: clientOrderId };
+                if (this.isHedgeMode) {
+                    ccxtParams.positionSide = position.side === 'long' ? 'LONG' : 'SHORT';
+                }
+                else {
+                    ccxtParams.reduceOnly = true;
+                }
+                try {
+                    this.emit('emergency_progress', { action: 'flatten', status: 'in_progress', symbol, attempt });
+                    const order = await this.api.createOrder(symbol, closeSide, 'market', position.contracts, undefined, ccxtParams);
+                    logger.info(TAG, `FLATTEN: ${symbol} close order ${order.id} status=${order.status}`);
+                    this.emit('emergency_progress', { action: 'flatten', status: 'completed', symbol });
+                    return order;
+                }
+                catch (err) {
+                    logger.warn(TAG, `FLATTEN ${symbol} attempt ${attempt}/3 failed: ${formatError(err)}`);
+                    if (attempt < 3)
+                        await sleep(1000);
+                }
+            }
+            // Every close attempt failed AND the brackets were cancelled above — the
+            // position is live and UNPROTECTED. Best-effort re-protect from the
+            // ledger's preserved levels before escalating (cancelBrackets marks the
+            // row terminal but keeps stopPrice/targetPrice/entrySide).
+            if (this.bracketManager) {
+                await this.reattachBracketsAfterFailedClose(symbol, lastKnownContracts);
+            }
+            const msg = `MANUAL INTERVENTION REQUIRED — close ${symbol} manually on Binance`;
+            logger.error(TAG, msg);
+            this.emit('emergency_progress', { action: 'flatten', status: 'failed', symbol, message: msg });
+            throw new Error(msg);
+        }
+        finally {
+            releaseOp();
+        }
+    }
+    /** Re-arm protection on a position whose closePosition flow cancelled the
+     *  brackets and then failed every market-close attempt. Reuses the normal
+     *  attach machinery: re-register the ledger row (terminal row → fresh
+     *  pending_entry with the SAME stop/target levels) and run the standard
+     *  3-retry attach. Never throws — this runs on the already-failing close
+     *  path; on any failure it emits the reconciler's `position_unprotected`
+     *  drift shape (re-emitted upstream as `bracket_drift`) plus a loud log so
+     *  the operator knows re-protection is required. */
+    async reattachBracketsAfterFailedClose(symbol, sizeHint) {
+        const emitUnprotected = (details) => {
+            logger.error(TAG, `UNPROTECTED POSITION after failed close: ${symbol} — brackets were cancelled before the ` +
+                `close attempts and could not be re-attached (${details}). Manual re-protection required ` +
+                `(attach_brackets or close on Binance).`);
+            this.emit('bracket_drift', {
+                kind: 'position_unprotected',
+                symbol: normalizeBracketSymbol(symbol),
+                details: `close failed after bracket cancel; re-attach ${details}`,
+                ts: new Date().toISOString(),
+            });
+        };
+        if (!this.bracketManager || !this.bracketLedger)
+            return;
+        try {
+            const row = this.bracketLedger.getBySymbol(normalizeBracketSymbol(symbol));
+            if (!row || (row.stopPrice === undefined && row.targetPrice === undefined)) {
+                // No preserved levels — either the position never had brackets (no
+                // protection was stripped) or the row is gone. Nothing to restore.
+                if (row)
+                    emitUnprotected('skipped: ledger row has no stop/target levels');
+                return;
+            }
+            const size = sizeHint > 0 ? sizeHint : row.qty ?? 0;
+            if (!(size > 0)) {
+                emitUnprotected('skipped: no valid position size to attach at');
+                return;
+            }
+            const bracketId = generateBracketId();
+            // registerEntry removes the terminal row left by cancelBrackets and
+            // creates a fresh pending_entry carrying the same levels.
+            this.bracketManager.registerEntry({ symbol: row.symbol, side: row.entrySide, stopPrice: row.stopPrice, targetPrice: row.targetPrice }, bracketId, buildBracketCid(bracketId, 'entry'));
+            const result = await this.bracketManager.attachBrackets(row.symbol, size);
+            if (result.ok) {
+                logger.warn(TAG, `closePosition(${symbol}) failed but protection was RE-ATTACHED ` +
+                    `(sl=${row.stopPrice ?? '-'} tp=${row.targetPrice ?? '-'} size=${size}) — position is protected, not closed`);
+            }
+            else {
+                emitUnprotected(`failed after ${result.attempts} attempts: ${result.error ?? 'unknown'}`);
+            }
+        }
+        catch (err) {
+            emitUnprotected(`threw: ${formatError(err)}`);
+        }
+    }
+    async getBalance() {
+        const balance = await this.api.fetchBalance();
+        this.syncRateLimits();
+        this.rateLimiter.recordQuery(ENDPOINT_WEIGHTS.fetchBalance ?? 5);
+        if (!balance) {
+            return { free: {}, used: {}, total: {} };
+        }
+        // Binance USDⓈ-M quirk: `availableBalance` is only populated for the primary
+        // margin asset (USDT). Secondary collaterals like USDC come back with
+        // total > 0 but free = 0 and used = 0 — internally inconsistent. If nothing
+        // is used, everything is free by definition, so backfill free = total.
+        repairFreeFromTotal(balance);
+        const bnfcrWallet = (() => {
+            const assets = balance?.info?.assets;
+            if (!Array.isArray(assets))
+                return undefined;
+            const a = assets.find(x => x?.asset === 'BNFCR');
+            return a == null ? undefined : parseFloat(String(a.walletBalance ?? 0));
+        })();
+        logger.info(TAG, `Raw balance: USDT=${JSON.stringify(balance.total.USDT ?? 0)}, USDC=${JSON.stringify(balance.total.USDC ?? 0)}, BNFCR.wallet=${bnfcrWallet ?? 'n/a'}, free.USDT=${balance.free.USDT ?? 0}, free.USDC=${balance.free.USDC ?? 0}`);
+        // Detect capital inflows/outflows (spot↔futures transfers, deposits,
+        // withdrawals) and re-anchor sessionStartNav so they don't masquerade
+        // as trading P&L. Fire-and-forget the first time (delta resolves on the
+        // next cycle) so an income-endpoint hiccup never blocks a balance fetch.
+        const transferDelta = await this.depositTracker.refresh();
+        if (transferDelta !== 0) {
+            const prev = this.enricher.getSessionStartNav();
+            const next = prev + transferDelta;
+            this.enricher.setSessionStartNav(next);
+            this._sessionStartNav = next;
+            logger.info(TAG, `Session NAV re-anchored for capital flow: ${prev.toFixed(4)} → ${next.toFixed(4)} (delta=${transferDelta >= 0 ? '+' : ''}${transferDelta.toFixed(4)})`);
+        }
+        // Re-anchor today's realized seed + sessionStartNav from Binance's
+        // income endpoint. The anchor is invariant within a UTC day (see
+        // INCOME_REFRESH_MIN_INTERVAL_MS doc), so this is heavily throttled and
+        // exists only as a long safety reconcile against BNFCR/transfer types
+        // DepositTracker can't see. UTC-midnight rollover forces a refresh
+        // (throttle bypassed) to re-anchor the new day.
+        await this.refreshIncomeAnchor(getQuoteWalletBalance(balance));
+        // Enrich with session PnL + equity using cached positions (no extra API call)
+        const cachedPositions = this.reconciler.getLastExchangePositions();
+        return this.enricher.enrich(balance, cachedPositions);
+    }
+    /** Re-anchor the realized-today seed + sessionStartNav from /fapi/v1/income.
+     *  Throttled to {@link INCOME_REFRESH_MIN_INTERVAL_MS}; UTC date rollover
+     *  forces an immediate refresh. Best-effort — failures are logged and
+     *  swallowed so a transient income-endpoint blip never blocks a balance
+     *  read. Called from getBalance() with the fresh quote wallet so we don't
+     *  fetch balance twice.
+     */
+    async refreshIncomeAnchor(quoteBalance) {
+        const now = Date.now();
+        const today = utcDateString(now);
+        const dayRolled = today !== this.incomeAnchorUtcDay;
+        const noAnchorYet = this._sessionStartNav == null;
+        // Throttle bypassed while no anchor exists yet (boot fetch failed) so we
+        // retry promptly until the baseline is established.
+        if (!dayRolled && !noAnchorYet && now - this.lastIncomeRefreshMs < INCOME_REFRESH_MIN_INTERVAL_MS)
+            return;
+        // forced (never-paced) ONLY for the anchors that actually change the
+        // value: a UTC-day rollover (new wallet_at_midnight) and the bootstrap
+        // case (no anchor yet). Routine same-day refreshes stay sheddable — the
+        // anchor is invariant within a UTC day, so a paced miss is a no-op
+        // (we keep the last good value), which is the whole point.
+        const forced = dayRolled || noAnchorYet;
+        const utcMidnight = utcMidnightMs(now);
+        const breakdown = await this.api.fetchTodayIncomeBreakdown(utcMidnight, { forced });
+        if (breakdown == null) {
+            // null≠empty: paced/failed income fetch. sessionStartNav =
+            // wallet_at_midnight is INVARIANT within a UTC day, so keeping the
+            // last good anchor is exactly correct — NEVER coerce to {0,0} (that
+            // pins it to wallet_now and zeroes Day P&L — 2026-05-16 KPI
+            // incident). Routine same-day miss with an anchor already set: arm
+            // the normal cadence (the value can't have changed). Rollover /
+            // bootstrap miss: leave the throttle unarmed so the next getBalance
+            // cycle retries (forced → lands once not under a real ban).
+            if (!dayRolled && !noAnchorYet)
+                this.lastIncomeRefreshMs = now;
+            return;
+        }
+        this.lastIncomeRefreshMs = now;
+        this.incomeAnchorUtcDay = today;
+        // Realized KPI = netNonTransfer (REALIZED_PNL + fees + funding) — matches
+        // Binance's "Today's Realized PNL" UI label. See seedRealizedPnlToday
+        // comment block above for the 2026-05-14 verification against the
+        // Binance mobile app.
+        this.enricher.seedRealizedPnlToday(breakdown.netNonTransfer, today);
+        // sessionStartNav = wallet_now − netNonTransfer = wallet_at_midnight.
+        // This is invariant under non-transfer activity so it self-corrects on
+        // every refresh, including BNFCR transfers that DepositTracker can't
+        // see (TRANSFER incomeType is excluded from netNonTransfer).
+        const navAtMidnight = quoteBalance - breakdown.netNonTransfer;
+        this.enricher.setSessionStartNav(navAtMidnight);
+        this._sessionStartNav = navAtMidnight;
+        if (dayRolled) {
+            logger.info(TAG, `UTC day rolled to ${today}; income anchor reset (netNonTransfer=${breakdown.netNonTransfer.toFixed(4)}, sessionStartNav=${navAtMidnight.toFixed(4)})`);
+        }
+    }
+    async getPositions(symbol) {
+        // Display/KPI contract: a failed REST fetch collapses to []. 20+
+        // display/KPI callers depend on this (KPI-must-equal-Binance). Decision
+        // paths must call getPositionsOrNull() instead. Single code path.
+        return (await this.getPositionsOrNull(symbol)) ?? [];
+    }
+    async getPositionsOrNull(symbol) {
+        if (this.userDataStream &&
+            userDataStreamAuthoritative(this.userDataStreamMode) &&
+            this.userDataStream.isStoreTrusted()) {
+            const positions = this.userDataStream.getStore().getPositions(symbol);
+            // Store is trusted (seeded + fresh) — its state is authoritative and
+            // never "unknown", so this branch never returns null.
+            return this.decoratePositionsWithMetadata(positions, symbol);
+        }
+        // Store not trusted: either not yet seeded by a trusted snapshot
+        // (startup / post-reset) OR stale beyond the dead-socket watchdog
+        // window (extended disconnect / failed-resync). Serving its state here
+        // would be the null≠empty / stale-as-truth collapse on the
+        // authoritative read path — fall through to the REST read instead,
+        // which carries real exchange state (or surfaces the failure honestly
+        // as null below). See isStoreTrusted().
+        const positions = await this.api.fetchPositions(symbol);
+        this.syncRateLimits();
+        this.rateLimiter.recordQuery(ENDPOINT_WEIGHTS.fetchPositions ?? 5);
+        // null = fetch FAILED (429 / weight-paced / transient) → state UNKNOWN.
+        // Propagate it; callers on decision paths must not treat it as "flat".
+        if (positions === null)
+            return null;
+        return this.decoratePositionsWithMetadata(positions, symbol);
+    }
+    /** Merge agent-supplied entry metadata + ratchet MFE state into the raw
+     *  CCXT position list. Side effect: drops metadata for symbols no longer
+     *  in the open-positions snapshot (only when called without a symbol filter
+     *  — symbol-scoped calls skip cleanup so we don't lose context for other
+     *  open positions). */
+    decoratePositionsWithMetadata(positions, symbolFilter) {
+        const out = [];
+        const openSymbols = new Set();
+        // Helper: read live bracket state for a symbol. Only active/partial/attaching
+        // brackets surface — terminal states leave the row in the ledger for the
+        // reconciler but mean "no live protection on exchange right now".
+        const lookupBracket = (symbol) => {
+            if (!this.bracketLedger)
+                return undefined;
+            const row = this.bracketLedger.getBySymbol(symbol);
+            if (!row)
+                return undefined;
+            if (row.state !== 'active' && row.state !== 'partial' && row.state !== 'attaching') {
+                return undefined;
+            }
+            return { slPrice: row.stopPrice, tpPrice: row.targetPrice, state: row.state };
+        };
+        for (const p of positions) {
+            openSymbols.add(p.symbol);
+            const meta = this.liveMetadata.get(p.symbol);
+            if (!meta) {
+                // Position observed without agent metadata (e.g. opened externally via
+                // Binance UI). Still surface the bracket — operator should see live
+                // protection levels regardless of how the position was opened.
+                out.push({ ...p, bracket: lookupBracket(p.symbol) });
+                continue;
+            }
+            // Lazy seed of MFE peak — first observation uses entryPrice (matches the
+            // paper-side seedMfeMetadata behaviour). originalStopPrice is set at
+            // createOrder time when stopPrice was known then, OR opportunistically
+            // here from current stopPrice if the agent supplied one post-entry via
+            // modify_stop. Whichever path sets it first wins (frozen-at-first-known).
+            const freshMeta = { ...meta };
+            if (freshMeta.originalStopPrice === undefined && freshMeta.stopPrice !== undefined) {
+                freshMeta.originalStopPrice = freshMeta.stopPrice;
+            }
+            const out2 = updateMfe({
+                side: p.side,
+                entryPrice: p.entryPrice,
+                originalStopPrice: freshMeta.originalStopPrice,
+                markPrice: p.markPrice,
+                priorPeakPrice: freshMeta.mfePeakPrice ?? p.entryPrice,
+            });
+            freshMeta.mfePeakPrice = out2.mfePeakPrice;
+            freshMeta.mfeR = out2.mfeR;
+            freshMeta.giveBackRatio = out2.giveBackRatio;
+            this.liveMetadata.set(p.symbol, freshMeta);
+            out.push({
+                ...p,
+                setupType: p.setupType ?? freshMeta.setupType,
+                thesis: p.thesis ?? freshMeta.thesis,
+                stopPrice: p.stopPrice ?? freshMeta.stopPrice,
+                targetPrice: p.targetPrice ?? freshMeta.targetPrice,
+                regime: p.regime ?? freshMeta.regime,
+                regimeConfidence: p.regimeConfidence ?? freshMeta.regimeConfidence,
+                scorecardVerdict: p.scorecardVerdict ?? freshMeta.scorecardVerdict,
+                confluenceScore: p.confluenceScore ?? freshMeta.confluenceScore,
+                originalStopPrice: freshMeta.originalStopPrice,
+                mfePeakPrice: freshMeta.mfePeakPrice,
+                mfeR: freshMeta.mfeR,
+                giveBackRatio: freshMeta.giveBackRatio,
+                invalidationPrice: freshMeta.invalidationPrice,
+                realizationRule: freshMeta.realizationRule,
+                invalidationHit: computeInvalidationHit(p.side, p.markPrice, freshMeta.invalidationPrice),
+                bracket: lookupBracket(p.symbol),
+            });
+        }
+        // Cleanup: drop metadata for any symbol that no longer has an open
+        // position. Skip when caller supplied a symbol filter — the snapshot is
+        // partial and would falsely evict every other symbol.
+        if (symbolFilter === undefined) {
+            for (const sym of this.liveMetadata.keys()) {
+                if (!openSymbols.has(sym))
+                    this.liveMetadata.delete(sym);
+            }
+        }
+        return out;
+    }
+    async getOpenOrders(symbol) {
+        if (this.userDataStream &&
+            userDataStreamAuthoritative(this.userDataStreamMode) &&
+            this.userDataStream.isStoreTrusted()) {
+            return this.userDataStream.getStore().getOpenOrders(symbol);
+        }
+        // Store not trusted (unseeded OR stale beyond the watchdog window) —
+        // do NOT serve its order set as authoritative (a phantom-naked or
+        // stale verdict would re-attach / cancel against real protective
+        // orders). See isStoreTrusted(). Fall through to the REST path
+        // below, which throws on a failed/rate-limited fetch rather than
+        // collapsing "unknown" to "no orders".
+        // Sticky rate-limit cooldown: while armed, fail fast WITHOUT a Binance
+        // call so a tight agent retry loop can't pin the IP weight budget and
+        // keep the whole agent blind. Same null/throw contract as below — every
+        // existing caller already handles it safely.
+        const nowMs = Date.now();
+        if (nowMs < this.getOpenOrdersUnavailableUntil) {
+            const waitS = Math.ceil((this.getOpenOrdersUnavailableUntil - nowMs) / 1000);
+            throw new Error(`getOpenOrders: exchange rate-limited — sticky cooldown active (~${waitS}s left, ` +
+                'NO Binance call made so the weight window can drain). Caller must NOT proceed ' +
+                'as if the exchange has zero orders.');
+        }
+        const orders = await this.api.fetchOpenOrders(symbol);
+        this.syncRateLimits();
+        this.rateLimiter.recordQuery(symbol ? (ENDPOINT_WEIGHTS.fetchOpenOrders ?? 1) : (ENDPOINT_WEIGHTS.fetchOpenOrdersAll ?? 40));
+        // Critical: `BinancePrivateApi.fetchOpenOrders` returns `null` on fetch
+        // error (429 / transient network). Collapsing that to `[]` here destroys
+        // the "unknown" signal — downstream consumers (audit-bracket-protection,
+        // attach-brackets verifyLedgerStale, bracket reconciler) then treat
+        // "fetch failed" as "exchange truly has zero orders" and trigger
+        // re-attach / cancel paths against real protective orders that ARE on
+        // the exchange. This caused the 2026-05-14 ATOM naked-bracket loop:
+        // ~17 cycles of spurious re-attach while the agent's bracket-cid
+        // protective orders kept getting clobbered. Throwing here turns the
+        // unknown into an error the existing try/catches in callers handle
+        // safely (audit returns error to agent, verifyLedgerStale returns
+        // `false` = "not stale, can't tell", bracket-reconciler aborts the
+        // cycle). See `memory/feedback_getopenorders_null_collapse_naked_loop.md`.
+        if (orders === null) {
+            // Arm the sticky cooldown so the next ~45 s of retries cost zero
+            // Binance weight and the budget can actually drain.
+            this.getOpenOrdersUnavailableUntil =
+                Date.now() + LiveAdapter.OPEN_ORDERS_RL_COOLDOWN_MS;
+            throw new Error('getOpenOrders: fetchOpenOrders returned null (likely 429 / transient network). ' +
+                'Caller must NOT proceed as if the exchange has zero orders — that path causes ' +
+                'phantom-naked re-attach loops that clobber real protective orders. ' +
+                `Sticky cooldown armed ${LiveAdapter.OPEN_ORDERS_RL_COOLDOWN_MS / 1000}s.`);
+        }
+        // Clean read — clear any cooldown so recovery resumes immediately.
+        this.getOpenOrdersUnavailableUntil = 0;
+        return orders;
+    }
+    async fetchOrder(orderId, symbol) {
+        return this.api.fetchOrder(orderId, symbol);
+    }
+    async getLastPrice(symbol) {
+        const ticker = await this.api.fetchTicker(symbol);
+        return ticker?.last ?? null;
+    }
+    // ---- Internal helpers ----
+    /** Sync rate limiter from exchange response headers after every private API call. */
+    syncRateLimits() {
+        try {
+            const headers = this.api.getLastResponseHeaders();
+            if (Object.keys(headers).length > 0) {
+                this.rateLimiter.syncFromHeaders(headers);
+                // Reconcile the process-wide weight pacer against Binance truth.
+                noteResponseWeight(headers);
+            }
+        }
+        catch {
+            // Best-effort — don't crash on header sync failure
+        }
+    }
+    async loadExchangeInfo() {
+        const exchange = this.api.getExchange();
+        await this.exchangeInfo.load(exchange);
+    }
+    async detectPositionMode() {
+        try {
+            // GET /fapi/v1/positionSide/dual is weight 30 (doc-verified). Route it
+            // through the shared gate like every other Binance read so it can't
+            // pile onto a startup storm or extend an active ban.
+            assertNotBanned('fetchPositionMode');
+            const exchange = this.api.getExchange();
+            const result = await exchange.fapiPrivateGetPositionSideDual();
+            noteSuccess();
+            this.isHedgeMode = result?.dualSidePosition === true;
+            logger.info(TAG, `Account position mode: ${this.isHedgeMode ? 'HEDGE' : 'ONE-WAY'}`);
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.warn(TAG, `Position mode detection failed (assuming one-way): ${formatError(err)}`);
+            this.isHedgeMode = false;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}