@reefclaw/openclaw-plugin 0.1.0

package/bridge/providers/gateway.js

@@ -0,0 +1,2302 @@
+// GatewayProvider — real OpenClaw gateway integration.
+// Connects to the OpenClaw gateway via HTTP and WebSocket,
+// streams live trading data, and emits ProviderEvents.
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { logger, formatError } from '../logger.js';
+import { isTradingMode } from '../types.js';
+import { GatewayHttpClient } from '../gateway/gateway-http-client.js';
+import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
+import { discoverTools } from '../gateway/tool-discovery.js';
+import { EventParser, mapCcxtBalance, mapCcxtOrder, extractLiquidationFields, extractBracketField, } from '../gateway/event-parser.js';
+import { Poller } from '../gateway/poller.js';
+import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, } from './risk-calculator.js';
+import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
+import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, } from './onboarding-commands.js';
+const TAG = 'gateway';
+// ---- Session NAV persistence ----
+// Persists sessionStartNav per date so Day P&L survives skill restarts.
+const SESSION_NAV_FILENAME = 'session-nav.json';
+const TRADING_MODE_FILENAME = 'trading-mode.json';
+function getSessionNavPath() {
+    return join(homedir(), '.openclaw', 'workspace', SESSION_NAV_FILENAME);
+}
+function getTradingModePath() {
+    return join(homedir(), '.openclaw', 'workspace', TRADING_MODE_FILENAME);
+}
+function todayDateStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Decide whether the session-start-NAV anchor needs to be (re)set. Pure so it
+ *  can be unit-tested without the full provider. Returns true when the anchor
+ *  has never been set, OR — for PAPER only — when it belongs to a previous UTC
+ *  day (so Day P&L re-anchors at midnight). Live/shadow anchor once and then
+ *  sync to the plugin's Binance income-endpoint value, so they never
+ *  self-re-anchor here. */
+export function shouldAnchorSessionNav(args) {
+    if (args.sessionStartNav < 0)
+        return true; // never anchored
+    return args.mode === 'PAPER' && args.sessionDate !== args.today; // paper midnight rollover
+}
+function loadSessionStartNav() {
+    try {
+        const raw = readFileSync(getSessionNavPath(), 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.date === todayDateStr() && typeof data.sessionStartNav === 'number' && data.sessionStartNav > 0) {
+            return data.sessionStartNav;
+        }
+        return null; // Different day or invalid
+    }
+    catch {
+        return null; // File doesn't exist or is corrupt
+    }
+}
+/**
+ * Persisted across skill restarts so the FIRST snapshot the gateway emits
+ * after boot reflects the last-known trading mode instead of the hardcoded
+ * 'PAPER' default. Otherwise every skill deploy clobbers the dashboard's
+ * localStorage cache with PAPER and the badge sticks until a hard refresh.
+ * The fresh fetchBalance round-trip will still correct any drift via the
+ * trading_mode event in fetchFreshBalance() — but until then, this prevents
+ * the visible PAPER flash.
+ */
+function loadLastTradingMode() {
+    try {
+        const raw = readFileSync(getTradingModePath(), 'utf-8');
+        const data = JSON.parse(raw);
+        if (isTradingMode(data.mode)) {
+            return data.mode;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveLastTradingMode(mode) {
+    try {
+        const dir = join(homedir(), '.openclaw', 'workspace');
+        mkdirSync(dir, { recursive: true });
+        const data = { mode, savedAt: new Date().toISOString() };
+        writeFileSync(getTradingModePath(), JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch {
+        /* non-fatal — next save will retry */
+    }
+}
+function saveSessionStartNav(nav) {
+    try {
+        const dir = join(homedir(), '.openclaw', 'workspace');
+        mkdirSync(dir, { recursive: true });
+        const data = { date: todayDateStr(), sessionStartNav: nav };
+        writeFileSync(getSessionNavPath(), JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (err) {
+        logger.warn(TAG, `Failed to save session NAV: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ---- Agent state emission interval ----
+const AGENT_STATE_INTERVAL_MS = 5_000;
+// ---- GatewayProvider ----
+export class GatewayProvider {
+    config;
+    // ---- Sub-components (created during initialization) ----
+    http = null;
+    wsClient = null;
+    poller = null;
+    eventParser = null;
+    toolMap = {};
+    // ---- Internal state ----
+    agentMode = 'ACTIVE';
+    // 'agent_discretionary' is the honest default for trades the agent opens
+    // via create_order without a named strategy-engine signal firing. The
+    // legacy 'Unknown' value polluted every trade_results row on intel — see
+    // [[feedback_skill_bridge_version_compare_pitfall]] adjacent bug. Agents
+    // should classify by setup_type (validated NOT NULL on position_entries),
+    // not by this skill-side hint field.
+    lastKnownStrategy = { name: 'agent_discretionary', version: '0.0.0' };
+    /** Agent display name + live model id, resolved from the gateway (best-effort).
+     *  Surfaced in agent_state so the dashboard header can show the real agent +
+     *  model instead of a hardcoded placeholder. Empty until the gateway answers. */
+    agentIdentity = {};
+    /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
+    loggedAgentIdentityProbe = false;
+    /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
+    heartbeatSeconds;
+    heartbeatReadAtMs = 0;
+    loggedHeartbeat = false;
+    lastTicker = null;
+    positions = [];
+    balance = { currency: 'USDT', total: 0, available: 0, locked: 0 };
+    /** Today's realized PnL (filtered by closedAt) from plugin trade history. */
+    realizedPnlToday = null;
+    /** Cumulative all-time realized PnL — used for the webapp KPI strip. */
+    realizedPnlAllTime = null;
+    /** Paper session execution costs (since plugin boot), forwarded to the
+     *  dashboard cost cells so "Fees"/"Avg Slip" reflect the drag already in NAV
+     *  instead of reading $0 (M1). Null in live (LiveAdapter omits them). */
+    paperSessionFees = null;
+    paperAvgSlippageBps = null;
+    /** Mark-to-market equity from plugin (wallet + collateral + unrealized). */
+    equity = null;
+    openOrders = [];
+    startTime = Date.now();
+    /** Session start NAV — -1 means "not yet set", 0 is valid (fresh account). */
+    sessionStartNav = -1;
+    /** UTC date (YYYY-MM-DD) the current sessionStartNav anchor belongs to.
+     *  Null until first anchored. Used to re-anchor Day P&L at UTC midnight —
+     *  without it a long-running PAPER session kept yesterday's anchor and Day
+     *  P&L / Realized accumulated across days. */
+    sessionDate = null;
+    /** Track whether we've received at least one positions poll (needed for equity calculation). */
+    hasReceivedPositions = false;
+    /** Track whether we've received at least one balance poll (needed for equity calculation). */
+    hasReceivedBalance = false;
+    quoteCurrency;
+    // ---- Rate tracking ----
+    orderTimestamps = [];
+    cancelTimestamps = [];
+    // ---- Timers ----
+    agentStateInterval = null;
+    toolRetryInterval = null;
+    regimeInterval = null;
+    signalInterval = null;
+    missionInterval = null;
+    analyticsInterval = null;
+    decisionTraceInterval = null;
+    pendingStartTimers = [];
+    started = false;
+    startedAt = 0;
+    // ---- Mission tracking ----
+    lastSeenMissionIds = new Set();
+    // ---- Intelligence poller error tracking (circuit-breaker) ----
+    intelErrors = {};
+    // ---- Event listeners ----
+    // ---- Cached data for trade journaling (Feature C) ----
+    lastCryptoMetrics = null;
+    lastVolumeAnalysis = null;
+    // ---- ATR data for volatility-adaptive risk limits ----
+    atrData = null;
+    atrSampleCount = 0;
+    // ---- Current regime (Phase 9e: regime-conditional risk) ----
+    currentRegime = 'UNKNOWN';
+    // ---- Trade tracking ----
+    /** Timestamp of the most recent trade (fill event) — used in buildAgentState */
+    lastTradeTs = null;
+    /** Tracks open position entries for computing trade results on close.
+     *  Key: `symbol:side` (e.g. "BTC/USDT:long"), Value: { entryPrice, quantity, side, entryTime, missionId?, setupType?, regime?, confluenceScore? } */
+    openTradeEntries = new Map();
+    /** Potential closes awaiting 2-poll confirmation. Binance's fetchPositions
+     *  occasionally returns a held position as missing or zero-contract for a
+     *  single poll; those transient drops were the root cause of ~350 phantom
+     *  trade_results rows/day. We only treat a position as closed after it's
+     *  been absent on TWO consecutive polls. Key: `symbol:side`. */
+    pendingCloses = new Map();
+    /** Tracks whether the previous poll returned an empty / all-flat positions
+     *  snapshot while we were holding non-zero positions. A single empty poll is
+     *  treated as tentative (most often a Binance 429 / partial response). We
+     *  skip the diff detector and do NOT overwrite this.positions until the
+     *  next poll confirms — without this guard, the next non-empty poll re-emits
+     *  synthetic OPEN fills for positions that were there all along (the
+     *  open-side mirror of the close-side phantom that pendingCloses guards
+     *  against). See Track 1 verification 2026-04-21 +
+     *  docs/TRADE_AUDIT_TRAIL_PLAN.md Phase 0. */
+    pendingEmptyPoll = false;
+    /** In-flight trade result reports — drained on stop() to prevent data loss during kill/flatten. */
+    inFlightReports = [];
+    /** File-backed retry queue for failed trade reports */
+    retryQueuePath;
+    retryTimer = null;
+    // ---- Trading mode (Phase 9b) ----
+    // Initial value is loaded from the persisted file written on every prior
+    // mode change. Falls back to 'PAPER' only on first-ever boot (or after
+    // file is corrupt/deleted). Prevents the "dashboard flashes PAPER on every
+    // skill restart" UX bug — see saveLastTradingMode() comment above.
+    tradingMode = loadLastTradingMode() ?? 'PAPER';
+    listeners = {
+        ticker: new Set(),
+        candle: new Set(),
+        orderUpdate: new Set(),
+        agentState: new Set(),
+        riskUpdate: new Set(),
+        chatMessage: new Set(),
+        chatMessageStart: new Set(),
+        chatMessageChunk: new Set(),
+        chatMessageEnd: new Set(),
+        chatStreamingKeepAlive: new Set(),
+        marketStructure: new Set(),
+        cryptoMetrics: new Set(),
+        volumeAnalysis: new Set(),
+        tradeJournal: new Set(),
+        regimeUpdate: new Set(),
+        signalUpdate: new Set(),
+        missionUpdate: new Set(),
+        analyticsUpdate: new Set(),
+        fillError: new Set(),
+        shadowComparison: new Set(),
+        tradingModeUpdate: new Set(),
+        decisionTraceUpdate: new Set(),
+    };
+    constructor(config) {
+        this.config = config;
+        // Extract quote currency from symbol (e.g. "BTC/USDT" -> "USDT")
+        const parts = config.symbol.split('/');
+        this.quoteCurrency = parts.length > 1 ? parts[1] : 'USDT';
+        // Retry queue for failed trade reports
+        const retryDir = join(homedir(), '.reefclaw');
+        try {
+            mkdirSync(retryDir, { recursive: true });
+        }
+        catch { /* exists */ }
+        this.retryQueuePath = join(retryDir, 'trade-report-queue.json');
+        logger.debug(TAG, `Config: url=${config.gatewayUrl}, symbol=${config.symbol}, quote=${this.quoteCurrency}`);
+    }
+    // ---- Provider interface ----
+    start() {
+        if (this.started) {
+            logger.warn(TAG, 'GatewayProvider already started');
+            return;
+        }
+        this.started = true;
+        this.startedAt = Date.now();
+        this.startTime = Date.now();
+        logger.info(TAG, 'Starting GatewayProvider');
+        this.startRetryTimer();
+        // Async initialization — errors are logged, not thrown
+        void this.initialize().catch((err) => {
+            logger.error(TAG, `Initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+            this.agentMode = 'ERROR';
+            this.emitAgentState();
+        });
+    }
+    stop() {
+        logger.info(TAG, 'Stopping GatewayProvider');
+        this.stopRetryTimer();
+        this.started = false;
+        if (this.toolRetryInterval) {
+            clearInterval(this.toolRetryInterval);
+            this.toolRetryInterval = null;
+        }
+        if (this.agentStateInterval) {
+            clearInterval(this.agentStateInterval);
+            this.agentStateInterval = null;
+        }
+        if (this.regimeInterval) {
+            clearInterval(this.regimeInterval);
+            this.regimeInterval = null;
+        }
+        if (this.signalInterval) {
+            clearInterval(this.signalInterval);
+            this.signalInterval = null;
+        }
+        if (this.missionInterval) {
+            clearInterval(this.missionInterval);
+            this.missionInterval = null;
+        }
+        if (this.analyticsInterval) {
+            clearInterval(this.analyticsInterval);
+            this.analyticsInterval = null;
+        }
+        if (this.decisionTraceInterval) {
+            clearInterval(this.decisionTraceInterval);
+            this.decisionTraceInterval = null;
+        }
+        // Clear any pending delayed-start timers (prevents orphaned setInterval after stop)
+        for (const timer of this.pendingStartTimers) {
+            clearTimeout(timer);
+        }
+        this.pendingStartTimers = [];
+        if (this.poller) {
+            this.poller.stop();
+            this.poller = null;
+        }
+        if (this.wsClient) {
+            this.wsClient.destroy();
+            this.wsClient = null;
+        }
+        // Reset trade tracking state to avoid stale data on restart
+        this.hasReceivedPositions = false;
+        this.hasReceivedBalance = false;
+        this.openTradeEntries.clear();
+        this.pendingCloses.clear();
+        this.pendingEmptyPoll = false;
+        this.lastTradeTs = null;
+        this.realizedPnlToday = null;
+        this.realizedPnlAllTime = null;
+        this.paperSessionFees = null;
+        this.paperAvgSlippageBps = null;
+        this.equity = null;
+        this.http = null;
+        this.eventParser = null;
+    }
+    /**
+     * Drain in-flight trade result reports. Call during shutdown to prevent
+     * data loss during kill/flatten sequences. Returns when all pending
+     * reports have completed (or timed out).
+     */
+    async drainReports() {
+        if (this.inFlightReports.length === 0)
+            return;
+        logger.info(TAG, `Draining ${this.inFlightReports.length} in-flight trade report(s)...`);
+        await Promise.allSettled(this.inFlightReports);
+        logger.info(TAG, 'All trade reports drained');
+    }
+    // ---- Trade report retry queue ----
+    loadRetryQueue() {
+        try {
+            const raw = readFileSync(this.retryQueuePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    saveRetryQueue(queue) {
+        try {
+            writeFileSync(this.retryQueuePath, JSON.stringify(queue));
+        }
+        catch (err) {
+            logger.warn(TAG, `Failed to save retry queue: ${formatError(err)}`);
+        }
+    }
+    /** Guards processRetryQueue against overlapping runs — the retry timer fires
+     *  every 60s and startRetryTimer also kicks an immediate run, so a slow
+     *  (100-item × 10s-timeout) drain could still be in flight when the next
+     *  timer ticks. Two concurrent drains would double-POST every queued report
+     *  AND race their reconcile-saves against each other. */
+    retryInProgress = false;
+    /** Monotonic tag stamped on every queued report so processRetryQueue can
+     *  remove EXACTLY the reports it delivered when it reconciles the file — a
+     *  blind `save(remaining)` would clobber any report enqueued DURING the
+     *  network phase (read-modify-write race with enqueueFailedReport). */
+    nextRetryQid = 0;
+    enqueueFailedReport(tradeResult) {
+        // Synchronous read-modify-write: no `await` between load and save, so a
+        // concurrent processRetryQueue (which only touches the file synchronously
+        // outside its network phase) can never interleave and clobber this push.
+        const queue = this.loadRetryQueue();
+        queue.push({ ...tradeResult, _qid: `${Date.now()}-${this.nextRetryQid++}` });
+        // Cap at 100 to prevent unbounded growth
+        if (queue.length > 100)
+            queue.splice(0, queue.length - 100);
+        this.saveRetryQueue(queue);
+        logger.info(TAG, `Trade report queued for retry (${queue.length} pending)`);
+    }
+    async processRetryQueue() {
+        // Timer-overlap / in-flight guard — single-drainer at a time.
+        if (this.retryInProgress)
+            return;
+        let snapshot = this.loadRetryQueue();
+        if (snapshot.length === 0)
+            return;
+        // One-time migration: reports queued by a pre-_qid binary carry no tag, so
+        // the reconcile-by-qid below couldn't remove them and they'd retry forever
+        // (harmless idempotent dup POSTs, but never clearing). Backfill a _qid for
+        // any legacy entry. Synchronous read-modify-write — atomic vs enqueue.
+        if (snapshot.some((it) => typeof it._qid !== 'string')) {
+            snapshot = snapshot.map((it) => typeof it._qid === 'string' ? it : { ...it, _qid: `${Date.now()}-${this.nextRetryQid++}` });
+            this.saveRetryQueue(snapshot);
+        }
+        const url = this.config.intelligenceUrl;
+        const token = this.config.connectionToken;
+        if (!url || !token)
+            return;
+        this.retryInProgress = true;
+        try {
+            const fullUrl = `${url}/api/trades`;
+            const deliveredQids = new Set();
+            for (const item of snapshot) {
+                const qid = typeof item._qid === 'string' ? item._qid : undefined;
+                // Strip the internal tag so the POST body is byte-identical to the
+                // original report (the intel /api/trades endpoint never sees _qid).
+                const tradeResult = { ...item };
+                delete tradeResult._qid;
+                try {
+                    const res = await fetch(fullUrl, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                        body: JSON.stringify(tradeResult),
+                        signal: AbortSignal.timeout(10_000),
+                    });
+                    if (res.ok) {
+                        if (qid)
+                            deliveredQids.add(qid);
+                        logger.info(TAG, `Retry succeeded: ${tradeResult.symbol} ${tradeResult.direction}`);
+                    }
+                    // else: still failing — leave it in the queue (not marked delivered)
+                }
+                catch {
+                    // Network error — stop retrying; leave this + the rest in the queue.
+                    break;
+                }
+            }
+            // Reconcile synchronously (no await between load and save): re-read the
+            // CURRENT file — it may now hold reports enqueued while we were POSTing —
+            // and drop ONLY the ones we actually delivered. Everything else (still-
+            // failing + newly-enqueued) is preserved. A blind save(remaining) here
+            // would silently lose any report enqueued during the network phase.
+            const current = this.loadRetryQueue();
+            const remaining = deliveredQids.size > 0
+                ? current.filter((item) => !(typeof item._qid === 'string' && deliveredQids.has(item._qid)))
+                : current;
+            if (remaining.length !== current.length) {
+                this.saveRetryQueue(remaining);
+                logger.info(TAG, `Retry queue: ${deliveredQids.size} delivered, ${remaining.length} remaining`);
+            }
+        }
+        finally {
+            this.retryInProgress = false;
+        }
+    }
+    startRetryTimer() {
+        // Retry every 60 seconds
+        this.retryTimer = setInterval(() => void this.processRetryQueue(), 60_000);
+        // Also process immediately on startup (recover from prior crash)
+        void this.processRetryQueue();
+    }
+    stopRetryTimer() {
+        if (this.retryTimer) {
+            clearInterval(this.retryTimer);
+            this.retryTimer = null;
+        }
+    }
+    /** Dual-fire dedup. Every critical command fires on BOTH WebSocket and
+     *  HTTP simultaneously (CLAUDE.md: "Agent handles idempotency; first to
+     *  arrive wins") — so each emergency action normally arrives here TWICE,
+     *  ~0-200ms apart. Without dedup a second `flatten` re-fetches positions
+     *  before the first close settles on-exchange and submits a second market
+     *  close — a position-flip risk. Duplicates of the same action while one
+     *  is in flight (or within a short post-completion window) share the
+     *  first invocation's promise/result instead of executing again. */
+    static EMERGENCY_DEDUP_MS = 3_000;
+    emergencyInFlight = new Map();
+    async executeEmergency(action) {
+        const existing = this.emergencyInFlight.get(action);
+        if (existing &&
+            (existing.settledAt === null ||
+                Date.now() - existing.settledAt < GatewayProvider.EMERGENCY_DEDUP_MS)) {
+            logger.warn(TAG, `Emergency ${action}: duplicate (dual-fire) — returning first invocation's result`);
+            return existing.promise;
+        }
+        const entry = { promise: Promise.resolve({ action, executed: false, timestamp: '' }), settledAt: null };
+        entry.promise = this.runEmergency(action).finally(() => {
+            entry.settledAt = Date.now();
+        });
+        this.emergencyInFlight.set(action, entry);
+        return entry.promise;
+    }
+    async runEmergency(action) {
+        logger.info(TAG, `Emergency command: ${action}`);
+        switch (action) {
+            case 'kill':
+                return this.executeKill();
+            case 'flatten':
+                return this.executeFlatten();
+            case 'pause':
+                return this.executePause();
+            case 'resume':
+                return this.executeResume();
+            default:
+                return { action, executed: false, timestamp: new Date().toISOString(), details: `Unknown action: ${action}` };
+        }
+    }
+    // ---- Emergency command implementations (delegated to emergency-commands.ts) ----
+    async executeKill() {
+        const ctx = { http: this.http, toolMap: this.toolMap, symbol: this.config.symbol };
+        // Pass a FRESH, all-symbols order snapshot so Kill cancels every working
+        // order portfolio-wide and correctly identifies (and preserves) protective
+        // reduceOnly brackets. fetchFreshOpenOrders falls back to this.openOrders on
+        // any fetch error, so this never blocks the kill.
+        const freshOrders = await this.fetchFreshOpenOrders();
+        const result = await _executeKill(ctx, freshOrders);
+        this.agentMode = 'STOPPED';
+        this.emitAgentState();
+        return result;
+    }
+    async executeFlatten() {
+        const ctx = { http: this.http, toolMap: this.toolMap, symbol: this.config.symbol };
+        const result = await _executeFlatten(ctx, this.positions);
+        this.agentMode = 'STOPPED';
+        this.emitAgentState();
+        return result;
+    }
+    executePause() {
+        const { result, newMode } = _executePause(this.agentMode);
+        if (newMode !== this.agentMode) {
+            this.agentMode = newMode;
+            this.emitAgentState();
+        }
+        return result;
+    }
+    executeResume() {
+        const { result, newMode } = _executeResume(this.agentMode);
+        if (newMode !== this.agentMode) {
+            this.agentMode = newMode;
+            this.emitAgentState();
+        }
+        return result;
+    }
+    async handleChat(content) {
+        // Capture reference before await — defensive against stop() mid-execution
+        const ws = this.wsClient;
+        if (!ws) {
+            const reason = 'Gateway WebSocket not initialized';
+            logger.error(TAG, `Chat send failed: ${reason}`);
+            return { received: false, error: reason };
+        }
+        if (!this.started) {
+            const reason = 'Provider not started';
+            logger.error(TAG, `Chat send failed: ${reason}`);
+            return { received: false, error: reason };
+        }
+        const wsState = ws.getState();
+        if (wsState !== 'connected') {
+            const reason = `Gateway WebSocket is ${wsState} (not connected)`;
+            logger.error(TAG, `Chat send failed: ${reason}`);
+            return { received: false, error: reason };
+        }
+        try {
+            const idempotencyKey = `chat-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            await ws.sendRpc('agent', { message: content, idempotencyKey, agentId: 'main' });
+            return { received: true };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error(TAG, `Chat send failed: ${reason}`);
+            return { received: false, error: reason };
+        }
+    }
+    async closePosition(symbol) {
+        const tool = this.toolMap.close_position;
+        if (!tool || !this.http) {
+            return { closed: false, symbol, error: 'close_position tool not available' };
+        }
+        try {
+            // reason='operator_command' is MANDATORY: close_position's schema gate
+            // (validateClosePosition) rejects a reason-less close, and only
+            // operator_command bypasses the assessment requirement. Without it the
+            // operator's per-symbol Close is silently rejected and never executes.
+            // See plugin/src/tools/close-position.ts.
+            const result = await this.http.invoke(tool, { symbol, reason: 'operator_command' });
+            if (result.data && typeof result.data === 'object' && 'error' in result.data) {
+                return { closed: false, symbol, error: String(result.data.error) };
+            }
+            return { closed: true, symbol };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error(TAG, `Close position failed for ${symbol}: ${reason}`);
+            return { closed: false, symbol, error: reason };
+        }
+    }
+    // ---- Operator onboarding (PR2) ----
+    // Thin wrappers — real logic lives in providers/onboarding-commands.ts
+    // so unit tests can drive pure functions with a mocked HTTP client.
+    async setTradingMode(mode, acknowledged) {
+        return executeSetTradingMode({ http: this.http, toolMap: this.toolMap }, mode, acknowledged);
+    }
+    async setExchangeCredentials(apiKey, secret, testnet) {
+        return executeSetExchangeCredentials({ http: this.http, toolMap: this.toolMap }, apiKey, secret, testnet);
+    }
+    async testExchangeCredentials(apiKey, secret, testnet) {
+        return executeTestExchangeCredentials({ http: this.http, toolMap: this.toolMap }, apiKey, secret, testnet);
+    }
+    async clearExchangeCredentials() {
+        return executeClearExchangeCredentials({ http: this.http, toolMap: this.toolMap });
+    }
+    /** Operator-only. Read the current bracket-orders config from the plugin. */
+    async getBracketConfig() {
+        return executeGetBracketConfig({ http: this.http, toolMap: this.toolMap });
+    }
+    /** Operator-only. Flip requireStopLoss or requireTakeProfit. */
+    async setBracketRequirement(flag, value) {
+        return executeSetBracketRequirement({ http: this.http, toolMap: this.toolMap }, flag, value);
+    }
+    async getSnapshot() {
+        logger.info(TAG, 'Reconciliation snapshot requested');
+        // Parallel fetch — fresh data with cached fallback
+        const [posResult, balResult, ordersResult, healthResult] = await Promise.allSettled([
+            this.fetchFreshPositions(),
+            this.fetchFreshBalance(),
+            this.fetchFreshOpenOrders(),
+            this.fetchAgentHealth(),
+        ]);
+        // Guard: stop() may have been called during the fetches
+        if (!this.started) {
+            logger.info(TAG, 'Snapshot aborted — provider stopped during fetch');
+            return {
+                positions: [],
+                balance: this.balance,
+                openOrders: [],
+                agentState: this.buildAgentState(),
+                riskMetrics: this.computeRiskMetrics(),
+                gapFill: [],
+            };
+        }
+        // Extract results (all have fallbacks, so fulfilled is guaranteed by the helper methods)
+        const positions = posResult.status === 'fulfilled' ? posResult.value : this.positions;
+        const balance = balResult.status === 'fulfilled' ? balResult.value : this.balance;
+        const openOrders = ordersResult.status === 'fulfilled' ? ordersResult.value : this.openOrders;
+        const agentState = healthResult.status === 'fulfilled' ? healthResult.value : this.buildAgentState();
+        // Log if all fetches used cached data (degraded snapshot)
+        const freshCount = [posResult, balResult, ordersResult, healthResult]
+            .filter((r) => r.status === 'fulfilled').length;
+        if (freshCount === 0) {
+            logger.error(TAG, 'Snapshot DEGRADED — all fetches failed, returning cached data');
+        }
+        // Canonicalize symbols at the snapshot ingress too — same single-form
+        // invariant as onPollerPositions. The reconnect fetch hits the same
+        // plugin getPositions WS-store(unsuffixed)↔REST(suffixed) flip, so
+        // without this the first poll AFTER a snapshot diffs a suffixed prev
+        // against an unsuffixed curr (or vice-versa) and re-triggers the
+        // phantom-fill / NAV-thrash flip (2026-05-16 incident).
+        for (const p of positions) {
+            if (typeof p.symbol === 'string')
+                p.symbol = this.canonicalSymbol(p.symbol);
+        }
+        // Update internal state with fresh data (poller may be paused during reconnect)
+        this.positions = positions;
+        this.balance = balance;
+        this.openOrders = openOrders;
+        // Compute current NAV for portfolio percent calculation (consistent with computeRiskMetrics)
+        const equity = this.computeEquity();
+        const nav = this.sessionStartNav > 0 ? this.sessionStartNav : Math.max(equity, 1);
+        // Map CCXT positions to snapshot format
+        const snapshotPositions = [];
+        for (const pos of positions) {
+            const signedNotional = this.computePositionNotional(pos);
+            if (signedNotional === 0) {
+                logger.warn(TAG, `Skipping zero-notional position: ${pos.symbol} ${pos.side} contracts=${pos.contracts} notional=${pos.notional} markPrice=${pos.markPrice} entryPrice=${pos.entryPrice}`);
+                continue;
+            }
+            const contractSize = pos.contractSize ?? 1;
+            const quantity = Math.abs(pos.contracts ?? 0) * contractSize;
+            const entryPrice = pos.entryPrice ?? 0;
+            const currentPrice = pos.markPrice ?? pos.entryPrice ?? this.lastTicker?.lastPrice ?? 0;
+            // Side mapping — guard against non-standard CCXT values (e.g. 'both' in hedge mode)
+            let side;
+            if (pos.side === 'short') {
+                side = 'SHORT';
+            }
+            else if (pos.side === 'long') {
+                side = 'LONG';
+            }
+            else {
+                logger.warn(TAG, `Unknown position side "${pos.side}" for ${pos.symbol}, defaulting to LONG`);
+                side = 'LONG';
+            }
+            // Unrealized PnL — prefer exchange-provided value, compute as fallback
+            let unrealizedPnl = pos.unrealizedPnl;
+            if (unrealizedPnl == null && entryPrice > 0 && currentPrice > 0) {
+                unrealizedPnl = pos.side === 'long'
+                    ? (currentPrice - entryPrice) * quantity
+                    : (entryPrice - currentPrice) * quantity;
+            }
+            unrealizedPnl ??= 0;
+            const costBasis = entryPrice * quantity;
+            const unrealizedPnlPercent = costBasis > 0 ? (unrealizedPnl / costBasis) * 100 : 0;
+            const portfolioPercent = (Math.abs(signedNotional) / nav) * 100;
+            const liqFields = extractLiquidationFields(pos);
+            const bracketField = extractBracketField(pos);
+            snapshotPositions.push({
+                symbol: pos.symbol,
+                side,
+                quantity,
+                entryPrice,
+                currentPrice,
+                unrealizedPnl: +unrealizedPnl.toFixed(4),
+                unrealizedPnlPercent: +unrealizedPnlPercent.toFixed(2),
+                portfolioPercent: +portfolioPercent.toFixed(2),
+                // Component C: MFE / give-back surfacing. The plugin computes these on
+                // every mark-price tick (paper) or every getPositions call (live);
+                // we just pass them through unchanged. Undefined when the position
+                // opened without a stop (R-multiple denominator missing). Index
+                // signature on CcxtPosition is `unknown`, so narrow at the boundary.
+                mfeR: typeof pos.mfeR === 'number' ? pos.mfeR : undefined,
+                mfePeakPrice: typeof pos.mfePeakPrice === 'number' ? pos.mfePeakPrice : undefined,
+                giveBackRatio: typeof pos.giveBackRatio === 'number' ? pos.giveBackRatio : undefined,
+                originalStopPrice: typeof pos.originalStopPrice === 'number' ? pos.originalStopPrice : undefined,
+                ...(bracketField !== undefined ? { bracket: bracketField } : {}),
+                ...liqFields,
+            });
+        }
+        logger.info(TAG, `Snapshot: ${positions.length} raw positions → ${snapshotPositions.length} in snapshot (equity=${equity.toFixed(2)}, wallet=${balance.total?.toFixed(2)})`);
+        // Compute risk metrics (reuse existing logic)
+        const riskMetrics = this.computeRiskMetrics();
+        // NAV must equal Binance's "Margin Balance" = wallet + unrealized.
+        // Compute directly from the fresh wallet (balance.total — BNFCR-aware,
+        // uPnl-excluded) + unrealized already summed across snapshotPositions.
+        // We deliberately do NOT use this.equity: it is only assigned in
+        // fetchFreshBalance() (dormant under userDataStream.mode=enforce), so
+        // the old `this.equity ?? balance.total` collapsed live NAV to wallet-
+        // only on reconnect (2026-05-16 KPI incident). Paper keeps computeEquity
+        // (adds back entry notional — correct, paper deducts full notional at
+        // open).
+        const snapshotUnrealizedTotal = snapshotPositions.reduce((sum, p) => sum + p.unrealizedPnl, 0);
+        const snapshotTotal = this.tradingMode !== 'PAPER'
+            ? balance.total + snapshotUnrealizedTotal // live: wallet + unrealized
+            : equity; // paper: wallet + notional
+        const adjustedBalance = {
+            ...balance,
+            total: snapshotTotal,
+            available: balance.available,
+            locked: snapshotTotal - balance.available,
+        };
+        return {
+            positions: snapshotPositions,
+            balance: adjustedBalance,
+            openOrders,
+            agentState,
+            riskMetrics,
+            gapFill: [],
+            sessionStartNav: this.sessionStartNav > 0 ? this.sessionStartNav : undefined,
+            realizedPnlToday: this.realizedPnlToday ?? undefined,
+            realizedPnlAllTime: this.realizedPnlAllTime ?? undefined,
+            sessionFeesPaid: this.paperSessionFees ?? undefined,
+            sessionAvgSlippageBps: this.paperAvgSlippageBps ?? undefined,
+            equity: this.equity ?? undefined,
+            tradingMode: this.tradingMode,
+        };
+    }
+    on(event, listener) {
+        this.listeners[event].add(listener);
+    }
+    off(event, listener) {
+        this.listeners[event].delete(listener);
+    }
+    // ---- Async initialization ----
+    async initialize() {
+        // Step 1: Create HTTP client (initially with raw gateway token)
+        this.http = new GatewayHttpClient(this.config);
+        logger.info(TAG, 'HTTP client created');
+        // Step 2: Create event parser with async event callback for inactivity timeouts.
+        // When the parser's inactivity timer fires (no new chunks for 5s), it flushes
+        // the buffer and emits chatMessageEnd outside the normal parseAgentEvent flow.
+        this.eventParser = new EventParser(this.quoteCurrency, (events) => {
+            for (const evt of events) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this.fire(evt.event, evt.data);
+            }
+        });
+        // Step 3: Create WS client and connect FIRST to obtain device token.
+        // OpenClaw's REST API requires a device token from the WS handshake,
+        // not the raw gateway auth token. Tool discovery must wait for this.
+        this.wsClient = new GatewayWsClient(this.config);
+        this.wireWsEvents();
+        // Wait for WS handshake to complete (or fail)
+        const deviceToken = await this.waitForDeviceToken();
+        if (!this.started) {
+            logger.info(TAG, 'Stopped during WS handshake — aborting initialization');
+            this.http = null;
+            return;
+        }
+        // Update HTTP client with device token for REST API calls
+        if (deviceToken) {
+            this.http.setToken(deviceToken);
+        }
+        else {
+            logger.warn(TAG, 'No device token from WS handshake — REST calls may fail (using raw gateway token)');
+        }
+        // Step 4: Discover available tools (async — check for stop() after)
+        const discovery = await discoverTools(this.http);
+        if (!this.started) {
+            logger.info(TAG, 'Stopped during tool discovery — aborting initialization');
+            this.http = null;
+            return;
+        }
+        this.toolMap = discovery.toolMap;
+        const noToolsFound = discovery.found.length === 0;
+        if (noToolsFound) {
+            // No trading tools found — enter PAUSED mode and start retry loop.
+            // Still connect WS + relay so the dashboard shows the agent is alive.
+            logger.warn(TAG, 'No trading tools found. Agent will connect but cannot trade.');
+            logger.info(TAG, 'Install a trading plugin: openclaw skills install reefclaw-paper-trading');
+            this.agentMode = 'PAUSED';
+        }
+        else {
+            if (discovery.missingRequired.length > 0) {
+                logger.error(TAG, `Missing required tools: ${discovery.missingRequired.join(', ')}`);
+            }
+            logger.info(TAG, `Tools discovered: ${discovery.found.join(', ')}`);
+            // Warn if emergency tools are missing
+            if (!this.toolMap.cancel_all_orders && !this.toolMap.cancel_order) {
+                logger.warn(TAG, 'Kill switch degraded: no cancel tools discovered (cancel_all_orders, cancel_order)');
+            }
+            if (!this.toolMap.close_position && !this.toolMap.create_order) {
+                logger.warn(TAG, 'Flatten degraded: no position close tools discovered (close_position, create_order)');
+            }
+        }
+        // Start retry loop if not all essential tools are discovered.
+        // This handles both "no tools at all" and "partial discovery during gateway startup".
+        if (!this.hasAllEssentialTools()) {
+            const missing = GatewayProvider.ESSENTIAL_OPTIONAL_TOOLS.filter(t => !this.toolMap[t]);
+            const missingRequired = ['fetch_ticker', 'fetch_balance'].filter(t => !this.toolMap[t]);
+            const allMissing = [...missingRequired, ...missing];
+            logger.info(TAG, `Retrying tool discovery every 30s for missing tools: ${allMissing.join(', ')}`);
+            this.startToolRetry();
+        }
+        // Step 5: Start poller if tools available (previously started from onWsConnected)
+        const hasTools = Object.keys(this.toolMap).length > 0;
+        if (hasTools && this.http && !this.poller) {
+            this.poller = this.createPoller();
+            this.poller.start();
+        }
+        // Step 6: Start regime poller if intelligence service is configured
+        this.startRegimePoller();
+        // Step 7: Start signal poller if intelligence service is configured
+        this.startSignalPoller();
+        // Step 8: Start mission poller if intelligence service is configured
+        this.startMissionPoller();
+        // Step 9: Start analytics poller if intelligence service is configured
+        this.startAnalyticsPoller();
+        // Step 10: Start decision trace poller if intelligence service is configured
+        this.startDecisionTracePoller();
+        // Step 11: Seed lastTradeTs from Intelligence API (one-shot, best-effort)
+        // Without this, "Last Trade" shows "Never" after every restart until a new trade fires.
+        void this.seedLastTradeTs();
+        // Emit initial agent state
+        this.emitAgentState();
+    }
+    /**
+     * Wait for the WS handshake to complete and return the device token.
+     * Returns null if handshake fails or times out.
+     */
+    waitForDeviceToken() {
+        return new Promise((resolve) => {
+            if (!this.wsClient) {
+                resolve(null);
+                return;
+            }
+            let settled = false;
+            const cleanup = () => {
+                if (this.wsClient) {
+                    this.wsClient.off('connected', onConnected);
+                    this.wsClient.off('failed', onFailed);
+                }
+            };
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                cleanup();
+                resolve(value);
+            };
+            const timeout = setTimeout(() => {
+                logger.warn(TAG, 'WS handshake timed out after 15s — proceeding without device token');
+                settle(null);
+            }, 15_000);
+            const onConnected = (helloOk) => {
+                const token = helloOk.auth?.deviceToken ?? null;
+                if (token) {
+                    logger.info(TAG, 'Got device token from WS handshake');
+                }
+                settle(token);
+            };
+            const onFailed = () => {
+                logger.warn(TAG, 'WS handshake failed — proceeding without device token');
+                settle(null);
+            };
+            this.wsClient.on('connected', onConnected);
+            this.wsClient.on('failed', onFailed);
+            // Initiate the connection
+            this.wsClient.connect();
+        });
+    }
+    /**
+     * Essential optional tools — retry loop keeps running until these are discovered.
+     * These are needed for position tracking, emergency controls, and trade display.
+     */
+    static ESSENTIAL_OPTIONAL_TOOLS = [
+        'fetch_positions',
+        'create_order',
+        'close_position',
+        'cancel_all_orders',
+    ];
+    /** Check if all essential tools are discovered. */
+    hasAllEssentialTools() {
+        for (const tool of GatewayProvider.ESSENTIAL_OPTIONAL_TOOLS) {
+            if (!this.toolMap[tool])
+                return false;
+        }
+        // Also need the required tools
+        if (!this.toolMap.fetch_ticker || !this.toolMap.fetch_balance)
+            return false;
+        return true;
+    }
+    /** Retry tool discovery every 30s until all essential tools are found. */
+    startToolRetry() {
+        if (this.toolRetryInterval)
+            return;
+        const RETRY_MS = 30_000;
+        this.toolRetryInterval = setInterval(async () => {
+            if (!this.started || !this.http) {
+                if (this.toolRetryInterval) {
+                    clearInterval(this.toolRetryInterval);
+                    this.toolRetryInterval = null;
+                }
+                return;
+            }
+            logger.info(TAG, 'Retrying tool discovery...');
+            try {
+                // Capture http ref before await — stop() can nullify it
+                const http = this.http;
+                const discovery = await discoverTools(http);
+                // Guard: stop() may have been called during async discovery
+                if (!this.started || !this.http)
+                    return;
+                if (discovery.found.length > 0) {
+                    // Merge newly discovered tools into existing toolMap
+                    const prevCount = Object.keys(this.toolMap).length;
+                    for (const [key, val] of Object.entries(discovery.toolMap)) {
+                        this.toolMap[key] = val;
+                    }
+                    const newCount = Object.keys(this.toolMap).length;
+                    logger.info(TAG, `Tools discovered on retry: ${discovery.found.join(', ')} (total: ${newCount})`);
+                    // Transition from PAUSED to ACTIVE once we have required tools
+                    if (this.agentMode === 'PAUSED' && this.toolMap.fetch_ticker && this.toolMap.fetch_balance) {
+                        this.agentMode = 'ACTIVE';
+                        this.emitAgentState();
+                    }
+                    // If new tools were added, restart the poller with the updated toolMap
+                    if (newCount > prevCount && this.started && this.http) {
+                        if (this.poller) {
+                            logger.info(TAG, 'Stopping poller to restart with updated tools');
+                            this.poller.stop();
+                            this.poller = null;
+                        }
+                        this.poller = this.createPoller();
+                        this.poller.start();
+                        logger.info(TAG, `Poller (re)started with ${newCount} tools`);
+                    }
+                    else if (!this.poller && this.started && this.http) {
+                        // First time finding tools — create poller
+                        this.poller = this.createPoller();
+                        this.poller.start();
+                        logger.info(TAG, `Poller started with ${newCount} tools`);
+                    }
+                    // Stop retry loop only when ALL essential tools are discovered
+                    if (this.hasAllEssentialTools()) {
+                        logger.info(TAG, 'All essential tools discovered — stopping retry loop');
+                        if (this.toolRetryInterval) {
+                            clearInterval(this.toolRetryInterval);
+                            this.toolRetryInterval = null;
+                        }
+                    }
+                    else {
+                        const missing = GatewayProvider.ESSENTIAL_OPTIONAL_TOOLS
+                            .filter(t => !this.toolMap[t]);
+                        logger.info(TAG, `Still waiting for essential tools: ${missing.join(', ')}`);
+                    }
+                }
+                else {
+                    logger.debug(TAG, 'Tool retry: still no trading tools found');
+                }
+            }
+            catch (err) {
+                logger.warn(TAG, `Tool retry failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }, RETRY_MS);
+    }
+    // ---- Poller factory (DRY helper for all Poller creation sites) ----
+    createPoller() {
+        return new Poller(this.http, this.toolMap, this.config.symbol, {
+            onTicker: (data) => this.onPollerTicker(data),
+            onCandle: (data) => this.fire('candle', data),
+            onPositions: (positions) => this.onPollerPositions(positions),
+            onBalance: (balance) => this.onPollerBalance(balance),
+            onOpenOrders: (orders) => this.onPollerOpenOrders(orders),
+            onMarketStructure: (data) => this.onPollerMarketStructure(data),
+            onCryptoMetrics: (data) => this.onPollerCryptoMetrics(data),
+            onVolumeAnalysis: (data) => this.onPollerVolumeAnalysis(data),
+        }, this.quoteCurrency);
+    }
+    // ---- WS event wiring ----
+    wireWsEvents() {
+        if (!this.wsClient)
+            return;
+        this.wsClient.on('connected', (helloOk) => this.onWsConnected(helloOk));
+        this.wsClient.on('disconnected', ({ code, reason }) => {
+            logger.warn(TAG, `WS disconnected: ${code} ${reason}`);
+            this.poller?.pause();
+        });
+        this.wsClient.on('reconnecting', ({ attempt, delayMs }) => {
+            logger.info(TAG, `WS reconnecting: attempt ${attempt}, delay ${Math.round(delayMs)}ms`);
+        });
+        this.wsClient.on('failed', ({ reason }) => {
+            logger.error(TAG, `WS connection failed permanently: ${reason}`);
+            this.agentMode = 'ERROR';
+            this.emitAgentState();
+        });
+        this.wsClient.on('agent', (payload) => this.onAgentEvent(payload));
+    }
+    onWsConnected(helloOk) {
+        if (!this.started)
+            return; // Guard: stop() called before WS connected
+        logger.info(TAG, 'WS reconnected — resuming poller');
+        // Log snapshot info from hello-ok
+        const snap = helloOk.snapshot;
+        if (snap) {
+            logger.info(TAG, `Gateway uptime: ${Math.round((snap.uptimeMs ?? 0) / 1000)}s, stateVersion: ${JSON.stringify(snap.stateVersion)}`);
+        }
+        // Update device token on reconnect
+        if (helloOk.auth?.deviceToken && this.http) {
+            this.http.setToken(helloOk.auth.deviceToken);
+        }
+        // Resume poller on reconnect (initial poller creation is in initialize())
+        if (this.poller) {
+            this.poller.resume();
+        }
+        // Emit agent state
+        this.emitAgentState();
+        this.emitRiskUpdate();
+        // Resolve the agent's real name + model from the gateway (best-effort,
+        // fire-and-forget; re-emits agent_state if it finds anything). Refreshed on
+        // every (re)connect so a model swap — which restarts the gateway and drops
+        // this socket — is reflected on the next handshake.
+        void this.refreshAgentIdentity();
+        // Start periodic agent state emission (every 5s)
+        if (!this.agentStateInterval) {
+            this.agentStateInterval = setInterval(() => {
+                this.emitAgentState();
+            }, AGENT_STATE_INTERVAL_MS);
+        }
+    }
+    // ---- Agent event handling (from WS) ----
+    onAgentEvent(payload) {
+        if (!this.started || !this.eventParser)
+            return;
+        const parsed = this.eventParser.parseAgentEvent(payload);
+        for (const evt of parsed) {
+            // Track order/cancel rates for risk computation
+            if (evt.event === 'orderUpdate') {
+                const data = evt.data;
+                if (data.status === 'CANCELLED') {
+                    this.cancelTimestamps.push(Date.now());
+                }
+                else {
+                    this.orderTimestamps.push(Date.now());
+                }
+                // Track last trade timestamp for agent state
+                if (data.status === 'FILLED') {
+                    this.lastTradeTs = data.timestamp ?? new Date().toISOString();
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.fire(evt.event, evt.data);
+        }
+    }
+    // ---- Poller callbacks ----
+    onPollerTicker(data) {
+        this.lastTicker = data;
+        this.fire('ticker', data);
+    }
+    /** Strip the live-Binance settle suffix (`SOL/USDT:USDT` → `SOL/USDT`)
+     *  to ONE canonical form, matching the webapp/plugin normalizeSymbol
+     *  convention (chart/DB are unsuffixed). The plugin's getPositions
+     *  returns the suffixed CCXT form via REST but the unsuffixed form via
+     *  the WS store; under weight pressure isStoreTrusted() flickers between
+     *  the two, so the raw symbol alternates poll-to-poll. */
+    canonicalSymbol(s) {
+        return typeof s === 'string' ? s.replace(/:[A-Z]+$/, '') : s;
+    }
+    async onPollerPositions(positions) {
+        // Canonicalize symbols at this single position-ingress chokepoint so
+        // the ENTIRE skill (position-diff, openTradeEntries keys, snapshots,
+        // NAV/unrealized, trade journal) sees ONE stable symbol form. Without
+        // this, the plugin's WS-store(unsuffixed)↔REST(suffixed) flip — driven
+        // by isStoreTrusted() flickering under weight pressure — made
+        // detectPositionChanges read every flip as close+open: phantom
+        // round-trip fills into the journal/analytics AND a thrashing position
+        // set behind NAV/unrealized. Realized still matched the exchange
+        // because the unrealized term cancels in (NAV−anchor)−unrealized;
+        // NAV/Day P&L/Unrealized did not (2026-05-16 incident). Unsuffixed is
+        // already a live-exercised form through every skill path (it was half
+        // the flip), so this removes the other form, it does not add a new one.
+        for (const p of positions) {
+            if (typeof p.symbol === 'string')
+                p.symbol = this.canonicalSymbol(p.symbol);
+        }
+        // Empty-poll guard: a snapshot showing zero positions while we were
+        // holding open positions is most often a Binance flake (429, partial
+        // response, listenKey rotation). A single empty poll is treated as
+        // tentative — we skip the entire detector path and preserve this.positions
+        // as-is. If the next poll is also empty we fall through and let the
+        // existing 2-poll close-confirmation logic emit confirmed closes. If
+        // positions reappear we silently recover with no synthetic fills emitted.
+        //
+        // Without this guard, an empty-poll flake clears prevMap and the very next
+        // non-empty poll re-emits OPEN fills for positions that were there all
+        // along — the open-side mirror of the close-side phantom. Track 1
+        // (2026-04-21) confirmed 56 phantom rows on 2026-04-20 19:50-19:56 UTC
+        // were caused by this exact failure mode.
+        const prevHadPositions = this.positions.some(p => (p.contracts ?? 0) !== 0);
+        const currIsEmpty = positions.length === 0 || positions.every(p => (p.contracts ?? 0) === 0);
+        if (this.hasReceivedPositions && prevHadPositions && currIsEmpty) {
+            if (!this.pendingEmptyPoll) {
+                this.pendingEmptyPoll = true;
+                logger.warn(TAG, `Position poll returned empty but prev had ${this.positions.length} non-zero positions — treating as tentative (likely Binance flake), awaiting next-poll confirmation`);
+                return;
+            }
+            // Second consecutive empty poll — fall through; existing 2-poll close
+            // confirmation in detectPositionChanges queues + confirms.
+        }
+        this.pendingEmptyPoll = false;
+        // Skip synthetic fill detection on the very first poll after startup —
+        // the skill has no prior state, so every position looks "new". Emitting
+        // synthetic opens here causes phantom trades (and phantom closes on the
+        // next poll cycle). The first poll is just the skill learning what exists.
+        if (this.hasReceivedPositions) {
+            this.detectPositionChanges(this.positions, positions);
+        }
+        else {
+            // Seed openTradeEntries on first poll so we can track closes later
+            for (const pos of positions) {
+                const contracts = pos.contracts ?? 0;
+                if (contracts !== 0 && pos.entryPrice) {
+                    const contractSize = pos.contractSize ?? 1;
+                    const side = pos.side === 'short' ? 'short' : 'long';
+                    const key = `${pos.symbol}:${side}`;
+                    this.openTradeEntries.set(key, {
+                        entryPrice: pos.entryPrice,
+                        quantity: Math.abs(contracts) * contractSize,
+                        side,
+                        entryTime: new Date().toISOString(), // Approximate — true entry time unknown on restart
+                        setupType: pos.setupType,
+                        regime: pos.regime,
+                        confluenceScore: pos.confluenceScore,
+                    });
+                    logger.info(TAG, `Seeded trade entry for ${pos.symbol}: ${side} ${Math.abs(contracts)} @ ${pos.entryPrice}`);
+                }
+            }
+        }
+        // Paper mark-to-market: update all positions with fresh prices BEFORE
+        // emitting risk update. Live modes preserve Binance's exchange-provided
+        // unrealizedPnl, which is mark-price based and matches the app.
+        if (this.tradingMode === 'PAPER') {
+            const updatePromises = [];
+            for (const pos of positions) {
+                if (this.lastTicker && pos.symbol === this.lastTicker.symbol) {
+                    this.applyMarkPrice(pos, this.lastTicker.lastPrice);
+                }
+                else if (pos.symbol && pos.symbol !== this.config.symbol && this.http && this.toolMap.fetch_ticker) {
+                    const sym = pos.symbol;
+                    const p = this.http.invoke(this.toolMap.fetch_ticker, { symbol: sym }).then(result => {
+                        const raw = result.data;
+                        if (!raw || typeof raw !== 'object')
+                            return;
+                        const lastPrice = Number(raw.last ?? raw.lastPrice ?? 0);
+                        if (lastPrice <= 0)
+                            return;
+                        this.applyMarkPrice(pos, lastPrice);
+                    }).catch(() => { });
+                    updatePromises.push(p);
+                }
+            }
+            // Wait for all ticker fetches (typically <100ms) so risk_update has fresh marks.
+            if (updatePromises.length > 0) {
+                await Promise.all(updatePromises);
+            }
+        }
+        this.positions = positions;
+        this.hasReceivedPositions = true;
+        this.trySetSessionStartNav();
+        this.emitRiskUpdate();
+    }
+    /**
+     * Compare previous and current positions from polling.
+     * When a position appears, changes size, or disappears,
+     * emit synthetic orderUpdate events so chart markers show trades.
+     */
+    /** Apply a fresh mark price to a position (mutates in place). */
+    applyMarkPrice(pos, markPrice) {
+        pos.markPrice = markPrice;
+        const contracts = Math.abs(pos.contracts ?? 0);
+        const contractSize = pos.contractSize ?? 1;
+        const quantity = contracts * contractSize;
+        const entryPrice = pos.entryPrice ?? 0;
+        const pnlMultiplier = pos.side === 'short' ? -1 : 1;
+        pos.unrealizedPnl = (markPrice - entryPrice) * quantity * pnlMultiplier;
+        pos.notional = quantity * markPrice;
+        pos.percentage = entryPrice > 0
+            ? ((markPrice - entryPrice) / entryPrice) * 100 * pnlMultiplier
+            : 0;
+    }
+    detectPositionChanges(prev, curr) {
+        // Build lookup by symbol:side to handle hedge mode (both long + short on same symbol)
+        const posKey = (p) => `${p.symbol}:${p.side}`;
+        const prevMap = new Map();
+        for (const p of prev) {
+            if ((p.contracts ?? 0) !== 0)
+                prevMap.set(posKey(p), p);
+        }
+        const currMap = new Map();
+        for (const p of curr) {
+            if ((p.contracts ?? 0) !== 0)
+                currMap.set(posKey(p), p);
+        }
+        // Detect new or changed positions
+        for (const [, pos] of currMap) {
+            const prevPos = prevMap.get(posKey(pos));
+            const prevContracts = prevPos?.contracts ?? 0;
+            const currContracts = pos.contracts ?? 0;
+            if (prevContracts === 0) {
+                // New position opened
+                this.emitSyntheticFill(pos, Math.abs(currContracts));
+            }
+            else if (prevPos && prevPos.side !== pos.side) {
+                // Side flipped (long→short or short→long) — close old + open new
+                this.emitSyntheticFill(prevPos, Math.abs(prevContracts), true);
+                this.emitSyntheticFill(pos, Math.abs(currContracts));
+            }
+            else if (Math.abs(currContracts) !== Math.abs(prevContracts)) {
+                const delta = Math.abs(currContracts) - Math.abs(prevContracts);
+                if (delta > 0) {
+                    // Position increased
+                    this.emitSyntheticFill(pos, delta);
+                }
+                else {
+                    // Position partially closed
+                    this.emitSyntheticFill(pos, Math.abs(delta), true);
+                }
+            }
+        }
+        // Detect fully closed positions — require 2-poll confirmation to reject
+        // Binance fetchPositions flakes. A position gone for one poll is treated
+        // as tentative; we emit the synthetic close (which writes to
+        // trade_results) only if it's still gone on the next poll. Positions
+        // that reappear after one missed poll were API artifacts, not real closes.
+        //
+        // Two-phase:
+        //   1. Resolve every existing pending-close: if it reappeared, clear
+        //      (phantom avoided); if it's still missing, emit the real close.
+        //   2. Queue any new missing-from-curr positions as pending for the
+        //      NEXT poll to confirm.
+        //
+        // Note: we process pending FIRST, then queue new, so a pending entry
+        // never races with the same-poll new-queue for the same key. We also
+        // pull pending keys from this.pendingCloses (not prevMap) because a
+        // pending close may survive across polls where prevMap has already
+        // moved on (e.g. side-flip: long → short, after poll 1 prev is [short]).
+        for (const [key, pendingPrevPos] of this.pendingCloses) {
+            if (currMap.has(key)) {
+                this.pendingCloses.delete(key);
+                logger.info(TAG, `Position ${key} reappeared — phantom-close avoided`);
+            }
+            else {
+                this.emitSyntheticFill(pendingPrevPos, Math.abs(pendingPrevPos.contracts ?? 0), true);
+                this.pendingCloses.delete(key);
+            }
+        }
+        for (const [key, prevPos] of prevMap) {
+            if (!currMap.has(key) && !this.pendingCloses.has(key)) {
+                this.pendingCloses.set(key, prevPos);
+                logger.debug(TAG, `Pending close for ${key} — awaiting next-poll confirmation`);
+            }
+        }
+    }
+    /**
+     * Emit a synthetic orderUpdate event derived from position polling data.
+     * Used when WS agent events are unavailable (gateway event filtering).
+     */
+    emitSyntheticFill(pos, quantity, isClose = false) {
+        const now = new Date().toISOString();
+        const id = `poll-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        // Determine order side from position
+        let side;
+        if (isClose) {
+            side = pos.side === 'long' ? 'SELL' : 'BUY';
+        }
+        else {
+            side = pos.side === 'long' ? 'BUY' : 'SELL';
+        }
+        // For opens, use entryPrice. For closes, use markPrice / lastTicker (exit price).
+        const fillPrice = isClose
+            ? (pos.markPrice ?? this.lastTicker?.lastPrice ?? pos.entryPrice ?? 0)
+            : (pos.entryPrice ?? pos.markPrice ?? this.lastTicker?.lastPrice ?? 0);
+        const order = {
+            id,
+            symbol: pos.symbol,
+            side,
+            type: 'MARKET',
+            status: 'FILLED',
+            quantity,
+            filledQuantity: quantity,
+            averageFillPrice: fillPrice,
+            timeInForce: 'GTC',
+            createdAt: now,
+            updatedAt: now,
+        };
+        const payload = {
+            orderId: id,
+            status: 'FILLED',
+            order,
+            fill: {
+                id: `fill-${id}`,
+                orderId: id,
+                symbol: pos.symbol,
+                side,
+                quantity,
+                price: fillPrice,
+                expectedPrice: fillPrice,
+                slippage: 0,
+                slippageBps: 0,
+                fee: 0,
+                feeCurrency: this.quoteCurrency,
+                timestamp: now,
+                reduceOnly: isClose,
+            },
+            timestamp: now,
+        };
+        logger.info(TAG, `Synthetic fill: ${side} ${quantity} ${pos.symbol} @ ${fillPrice} (from position poll)`);
+        this.lastTradeTs = now;
+        this.fire('orderUpdate', payload);
+        // Track open entries for trade result reporting
+        const tradeSide = pos.side === 'short' ? 'short' : 'long';
+        const tradeKey = `${pos.symbol}:${tradeSide}`;
+        if (!isClose) {
+            this.openTradeEntries.set(tradeKey, {
+                entryPrice: fillPrice,
+                quantity,
+                side: tradeSide,
+                entryTime: now,
+                setupType: pos.setupType,
+                regime: pos.regime,
+                confluenceScore: pos.confluenceScore,
+            });
+        }
+        else {
+            // Report completed trade to Intelligence API (with actual closed quantity)
+            this.reportTradeResult(tradeKey, pos.symbol, fillPrice, quantity);
+        }
+        // Feature C: emit trade journal entry with market/risk context
+        const action = isClose ? 'CLOSE' : 'OPEN';
+        this.emitTradeJournal(pos.symbol, side, action, quantity, fillPrice);
+    }
+    onPollerBalance(balance) {
+        // Defensive guard: never downgrade a known-good wallet balance to zero.
+        // Binance Futures 429 rate-limits were causing fetchBalance responses
+        // to come back with an empty currency map; mapCcxtBalance then returned
+        // { total: 0, available: 0, locked: 0 }, overwriting the real wallet.
+        // A genuine liquidation would be reflected in positions + drawdown
+        // before the wallet total reaches exactly 0, so a delta from a real
+        // non-zero total to exactly 0 in one poll is almost always an API
+        // artifact. Keep the previous value and wait for a valid poll.
+        if (balance.total === 0 && this.hasReceivedBalance && this.balance.total > 0) {
+            logger.warn(TAG, `Balance poll returned total=0 but last known was ${this.balance.total.toFixed(2)} ${this.balance.currency} — ignoring (likely Binance rate limit or empty response)`);
+            return;
+        }
+        this.balance = balance;
+        this.hasReceivedBalance = true;
+        this.trySetSessionStartNav();
+        this.emitRiskUpdate();
+    }
+    /**
+     * Set session start NAV once both balance AND positions have been received.
+     * Checks persisted file first — if today's NAV was already captured in a
+     * previous skill run, reuse it so Day P&L is stable across restarts.
+     */
+    trySetSessionStartNav() {
+        // Re-anchor Day P&L at UTC midnight — PAPER only. Without it a long-running
+        // paper session held yesterday's anchor and Day P&L / Realized accumulated
+        // across days (the plugin re-anchors every UTC day; the skill must too).
+        // Called every poll from onPollerBalance/onPollerPositions, so paper
+        // re-anchors within one poll of midnight. Live/shadow are intentionally
+        // excluded: they anchor to the plugin's Binance income-endpoint value
+        // (synced in fetchFreshBalance), and a self-recomputed midnight anchor
+        // would risk the KPI-must-equal-Binance invariant on real money.
+        const today = todayDateStr();
+        if (!shouldAnchorSessionNav({
+            sessionStartNav: this.sessionStartNav,
+            sessionDate: this.sessionDate,
+            today,
+            mode: this.tradingMode,
+        }))
+            return; // Already anchored for today (or live/shadow already set)
+        if (!this.hasReceivedPositions)
+            return; // Wait for positions
+        if (!this.hasReceivedBalance)
+            return; // Wait for balance
+        if (this.balance.total === 0 && this.positions.length === 0)
+            return; // No data yet
+        // Try loading from file first (persisted across restarts within same day).
+        // loadSessionStartNav() itself returns null on a different day, so on a
+        // fresh UTC day this falls through to recompute.
+        const saved = loadSessionStartNav();
+        if (saved !== null) {
+            this.sessionStartNav = saved;
+            this.sessionDate = today;
+            logger.info(TAG, `Session start NAV restored from file: ${saved} ${this.quoteCurrency}`);
+            return;
+        }
+        // First anchor of the (UTC) day — compute and persist.
+        this.sessionStartNav = this.computeEquity();
+        this.sessionDate = today;
+        saveSessionStartNav(this.sessionStartNav);
+        logger.info(TAG, `Session start NAV: ${this.sessionStartNav} ${this.quoteCurrency} (wallet=${this.balance.total}, positions=${this.positions.length})`);
+    }
+    onPollerOpenOrders(orders) {
+        this.openOrders = orders;
+        // Open orders stored internally for reconciliation (Phase 7j)
+        // and emergency commands (Phase 7h). No event emission here —
+        // real-time order updates come from the WS agent event stream.
+    }
+    onPollerMarketStructure(data) {
+        this.lastMarketStructure = data;
+        this.fire('marketStructure', data);
+        // Cache ATR data for volatility-adaptive risk limits
+        if (data.atr && data.atr.atr14 > 0) {
+            const currentAtr = data.atr.atr14;
+            this.atrSampleCount++;
+            if (!this.atrData) {
+                // First sample — baseline equals current
+                this.atrData = { currentAtr, baselineAtr: currentAtr };
+            }
+            else {
+                // Update baseline with EMA (capped at 20 samples)
+                const n = Math.min(this.atrSampleCount, 20);
+                const alpha = 2 / (n + 1);
+                const newBaseline = alpha * currentAtr + (1 - alpha) * this.atrData.baselineAtr;
+                this.atrData = { currentAtr, baselineAtr: newBaseline };
+            }
+        }
+    }
+    onPollerCryptoMetrics(data) {
+        this.lastCryptoMetrics = data;
+        this.fire('cryptoMetrics', data);
+    }
+    onPollerVolumeAnalysis(data) {
+        this.lastVolumeAnalysis = data;
+        this.fire('volumeAnalysis', data);
+    }
+    // ---- Trade journal emission (Feature C) ----
+    /**
+     * Build and emit a trade journal entry whenever a synthetic fill is detected.
+     * Called from emitSyntheticFill — captures market + risk context at trade time.
+     */
+    emitTradeJournal(symbol, side, action, quantity, price) {
+        // Gather market structure snapshot (if available)
+        const ms = this.lastMarketStructure;
+        const find = (tf) => ms?.timeframes.find(t => t.timeframe === tf) ?? null;
+        // Gather risk snapshot
+        const risk = this.computeRiskMetrics();
+        const entry = {
+            id: `journal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            symbol,
+            side,
+            action,
+            quantity,
+            price,
+            marketContext: {
+                direction5m: find('5m')?.direction ?? null,
+                direction1h: find('1h')?.direction ?? null,
+                direction4h: find('4h')?.direction ?? null,
+                alignment: ms?.alignment?.summary ?? null,
+                fundingRate: this.lastCryptoMetrics?.fundingRate ?? null,
+                volumeExpansion: this.lastVolumeAnalysis?.volumeExpansion ?? null,
+                closePosition: this.lastVolumeAnalysis?.closePosition ?? null,
+            },
+            riskContext: {
+                grossExposure: risk.utilization.grossExposure,
+                netExposure: risk.utilization.netExposure,
+                dailyDrawdown: risk.utilization.dailyDrawdown,
+                heatScore: this.computeHeatScoreSimple(risk),
+            },
+            timestamp: new Date().toISOString(),
+        };
+        logger.info(TAG, `Trade journal: ${action} ${side} ${quantity} ${symbol} @ ${price}`);
+        this.fire('tradeJournal', entry);
+    }
+    /** Simple heat score (0–100) matching webapp's HeatGauge logic */
+    computeHeatScoreSimple(metrics) {
+        const { grossExposure, dailyDrawdown, ordersPerMinute, cancelsPerMinute } = metrics.utilization;
+        const limits = DEFAULT_RISK_LIMITS;
+        const scores = [
+            limits.position.maxGrossExposure > 0 ? (grossExposure / limits.position.maxGrossExposure) * 100 : 0,
+            limits.loss.maxDailyDrawdown < 0 ? (dailyDrawdown / limits.loss.maxDailyDrawdown) * 100 : 0,
+            limits.rate.maxOrdersPerMinute > 0 ? (ordersPerMinute / limits.rate.maxOrdersPerMinute) * 100 : 0,
+            limits.rate.maxCancelsPerMinute > 0 ? (cancelsPerMinute / limits.rate.maxCancelsPerMinute) * 100 : 0,
+        ];
+        return Math.min(100, Math.max(0, Math.max(...scores)));
+    }
+    /** Cache last market structure for journal entries */
+    lastMarketStructure = null;
+    // ---- Snapshot fetch helpers (fresh data with cache fallback) ----
+    async fetchFreshPositions() {
+        const tool = this.toolMap.fetch_positions;
+        if (!tool || !this.http)
+            return this.positions;
+        try {
+            // Fetch ALL positions (no symbol filter) so multi-symbol trades are visible
+            const result = await this.http.invoke(tool, {});
+            if (!Array.isArray(result.data)) {
+                logger.warn(TAG, `fetch_positions returned non-array: ${typeof result.data}`);
+                return this.positions;
+            }
+            return result.data;
+        }
+        catch (err) {
+            logger.warn(TAG, `Fresh positions fetch failed, using cached: ${err instanceof Error ? err.message : String(err)}`);
+            return this.positions;
+        }
+    }
+    async fetchFreshBalance() {
+        const tool = this.toolMap.fetch_balance;
+        if (!tool || !this.http)
+            return this.balance;
+        try {
+            const result = await this.http.invoke(tool, {});
+            // Extract trading mode piggybacked on balance response (Phase 9b)
+            const mode = result.data.tradingMode;
+            if (isTradingMode(mode)) {
+                // Persist the confirmed mode to disk so the next skill restart starts
+                // up reading the correct value instead of the 'PAPER' constructor
+                // default. Cheap, idempotent — safe to write on every balance fetch
+                // even when no transition happened.
+                saveLastTradingMode(mode);
+                if (mode !== this.tradingMode) {
+                    const prevMode = this.tradingMode;
+                    this.tradingMode = mode;
+                    this.fire('tradingModeUpdate', {
+                        event: 'trading_mode',
+                        mode: this.tradingMode,
+                        timestamp: new Date().toISOString(),
+                    });
+                    logger.info(TAG, `Trading mode: ${prevMode} → ${this.tradingMode}`);
+                    // Reset session NAV when mode changes — different modes have different
+                    // balances (paper ~$8k vs real ~$65), so the old anchor would produce
+                    // wildly wrong Day P&L. Delete the persisted file too so
+                    // trySetSessionStartNav() recomputes from the new mode's equity.
+                    this.sessionStartNav = -1;
+                    this.sessionDate = null;
+                    this.hasReceivedBalance = false;
+                    this.hasReceivedPositions = false;
+                    this.pendingEmptyPoll = false;
+                    try {
+                        unlinkSync(getSessionNavPath());
+                    }
+                    catch { /* ok if missing */ }
+                    logger.info(TAG, `Session start NAV reset on mode change (${prevMode} → ${this.tradingMode})`);
+                }
+            }
+            // Extract realized P&L fields (roundtrip-fee inclusive, plugin-computed).
+            if (typeof result.data.realizedPnlToday === 'number') {
+                this.realizedPnlToday = result.data.realizedPnlToday;
+            }
+            if (typeof result.data.realizedPnlAllTime === 'number') {
+                this.realizedPnlAllTime = result.data.realizedPnlAllTime;
+            }
+            // Paper session execution costs (M1) — paper only; LiveAdapter omits them.
+            if (typeof result.data.sessionFeesPaid === 'number') {
+                this.paperSessionFees = result.data.sessionFeesPaid;
+            }
+            if (typeof result.data.sessionAvgSlippageBps === 'number') {
+                this.paperAvgSlippageBps = result.data.sessionAvgSlippageBps;
+            }
+            if (typeof result.data.equity === 'number') {
+                this.equity = result.data.equity;
+            }
+            // In non-PAPER modes, the plugin anchors sessionStartNav to Binance's
+            // /fapi/v1/income at UTC midnight on every balance fetch — that's the
+            // authoritative truth. Sync continuously, not just on first set: the
+            // pre-2026-05-14 guard `this.sessionStartNav < 0` meant once the skill
+            // had ANY value (from file load or computeEquity), the plugin's correct
+            // value was ignored forever. The skill's self-computed value drifts
+            // whenever trading has already happened before the skill first polls
+            // (operator screenshot 2026-05-14 found a $3.92 dashboard-vs-Binance
+            // gap from a $1095.95 self-computed seed vs the plugin's $1099.86
+            // midnight-anchored truth). Crossing UTC midnight is also handled
+            // automatically — plugin's anchor refreshes, skill syncs next poll.
+            if (this.tradingMode !== 'PAPER') {
+                const pluginNav = result.data.sessionStartNav;
+                if (typeof pluginNav === 'number' && pluginNav > 0
+                    && Math.abs(this.sessionStartNav - pluginNav) > 0.001) {
+                    const prev = this.sessionStartNav;
+                    this.sessionStartNav = pluginNav;
+                    saveSessionStartNav(pluginNav);
+                    logger.info(TAG, `Session start NAV synced from plugin: ${prev.toFixed(4)} -> ${pluginNav} (${this.tradingMode} mode)`);
+                }
+            }
+            return mapCcxtBalance(result.data, this.quoteCurrency);
+        }
+        catch (err) {
+            logger.warn(TAG, `Fresh balance fetch failed, using cached: ${err instanceof Error ? err.message : String(err)}`);
+            return this.balance;
+        }
+    }
+    async fetchFreshOpenOrders() {
+        const tool = this.toolMap.fetch_open_orders;
+        if (!tool || !this.http)
+            return this.openOrders;
+        try {
+            // Fetch ALL open orders (no symbol filter). Multi-symbol orphan orders
+            // submitted while the browser was disconnected must show up in the
+            // reconcile snapshot — single-symbol filtering here was the orphan-order
+            // failure mode CLAUDE.md warns about.
+            const result = await this.http.invoke(tool, {});
+            if (!Array.isArray(result.data)) {
+                logger.warn(TAG, `fetch_open_orders returned non-array: ${typeof result.data}`);
+                return this.openOrders;
+            }
+            const mapped = result.data
+                .map((o) => mapCcxtOrder(o))
+                .filter((o) => o !== null);
+            const dropped = result.data.length - mapped.length;
+            if (dropped > 0) {
+                logger.error(TAG, `Snapshot: ${dropped}/${result.data.length} open orders dropped (malformed data)`);
+            }
+            return mapped;
+        }
+        catch (err) {
+            logger.warn(TAG, `Fresh open orders fetch failed, using cached: ${err instanceof Error ? err.message : String(err)}`);
+            return this.openOrders;
+        }
+    }
+    async fetchAgentHealth() {
+        const ws = this.wsClient;
+        if (!ws)
+            return this.buildAgentState();
+        try {
+            // health RPC returns an agent health snapshot from the gateway. Its shape
+            // doesn't map directly to our AgentStateData format (we keep our internal,
+            // event-driven state for mode/health), but it can carry the resolved model
+            // id — so we mine it for identity as a cheap secondary source.
+            const resp = await ws.sendRpc('health', {});
+            const model = this.extractAgentModel(resp);
+            if (model)
+                this.mergeAgentIdentity({ model });
+            return this.buildAgentState();
+        }
+        catch (err) {
+            logger.warn(TAG, `Health RPC failed, using internal state: ${err instanceof Error ? err.message : String(err)}`);
+            return this.buildAgentState();
+        }
+    }
+    /**
+     * Resolve the agent's display name + live model id directly from the gateway.
+     * The primary carrier is the `sessions.list` RPC (rows carry agentId + the
+     * live model); `health` (above) is a secondary feed. Best-effort and
+     * fail-open — the gateway/version may not expose either, in which case the
+     * header simply falls back to its placeholder. Re-emits agent_state on a hit
+     * so the dashboard updates without waiting for the next periodic tick.
+     */
+    async refreshAgentIdentity() {
+        const ws = this.wsClient;
+        if (!ws)
+            return;
+        let sessionsResp;
+        let sessionsErr;
+        try {
+            sessionsResp = await ws.sendRpc('sessions.list', {});
+        }
+        catch (err) {
+            sessionsErr = err instanceof Error ? err.message : String(err);
+        }
+        // Model from the gateway (live, authoritative); name from the local
+        // OpenClaw workspace IDENTITY.md (sessions rows carry only chat ids).
+        const model = this.extractAgentModel(sessionsResp);
+        const name = this.resolveAgentNameFromIdentity();
+        // One-time rollout probe: the sessions.list shape isn't contractually stable
+        // across gateway versions, so log its top-level keys + what we resolved on the
+        // first attempt — makes an unexpected shape diagnosable instead of silent.
+        if (!this.loggedAgentIdentityProbe) {
+            this.loggedAgentIdentityProbe = true;
+            const keys = sessionsResp && typeof sessionsResp === 'object'
+                ? Object.keys(sessionsResp).join(',') || '(none)'
+                : sessionsErr
+                    ? `error:${sessionsErr}`
+                    : typeof sessionsResp;
+            logger.info(TAG, `Agent identity probe: sessions.list keys=[${keys}] -> model=${model ?? '(none)'} identityName=${name ?? '(none)'}`);
+        }
+        if (this.mergeAgentIdentity({ name, model })) {
+            logger.info(TAG, `Agent identity updated: name=${this.agentIdentity.name ?? '(none)'} model=${this.agentIdentity.model ?? '(none)'}`);
+            this.emitAgentState();
+        }
+    }
+    /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
+    mergeAgentIdentity(found) {
+        let changed = false;
+        if (found.name && found.name !== this.agentIdentity.name) {
+            this.agentIdentity.name = found.name;
+            changed = true;
+        }
+        if (found.model && found.model !== this.agentIdentity.model) {
+            this.agentIdentity.model = found.model;
+            changed = true;
+        }
+        return changed;
+    }
+    /**
+     * Extract the live model id from a `sessions.list` (or `health`) gateway
+     * payload. We deliberately do NOT take the agent NAME from here: sessions
+     * rows are per-chat and their `name` is a channel/chat id (e.g. a Telegram
+     * id), not the agent's identity — the display name comes from
+     * resolveAgentNameFromIdentity(). The exact shape isn't contractually stable,
+     * so probe the documented paths (row → runtime → defaults → root) and accept
+     * either a bare string or a `{ primary }` object.
+     */
+    extractAgentModel(payload) {
+        if (!payload || typeof payload !== 'object')
+            return undefined;
+        const pickStr = (v) => typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+        const asObj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+        const flatModel = (v) => {
+            const o = asObj(v);
+            return pickStr(v) ?? pickStr(o?.primary) ?? pickStr(o?.id);
+        };
+        const root = payload;
+        const rowsRaw = (Array.isArray(payload) && payload) ||
+            (Array.isArray(root.sessions) && root.sessions) ||
+            (Array.isArray(root.items) && root.items) ||
+            (Array.isArray(root.data) && root.data) ||
+            [root];
+        const rows = rowsRaw.filter((r) => !!r && typeof r === 'object');
+        const row = rows.find((r) => r.agentId === 'main') ?? rows[0];
+        const runtime = row ? (asObj(row.agentRuntime) ?? asObj(row.runtime)) : undefined;
+        const defaults = asObj(root.defaults);
+        return flatModel(row?.model) ?? flatModel(runtime?.model) ?? flatModel(defaults?.model) ?? flatModel(root.model);
+    }
+    /**
+     * Resolve the agent's display name from the OpenClaw workspace IDENTITY.md
+     * (`- **Name:** <X>`), local to this deployment (per-tenant correct — each
+     * trader's own agent has its own IDENTITY.md). Best-effort + fail-open:
+     * returns undefined when the file is missing/unreadable, the field is the
+     * unfilled placeholder, or the value looks like an id rather than a name.
+     */
+    resolveAgentNameFromIdentity() {
+        const candidates = [
+            process.env.OPENCLAW_WORKSPACE ? join(process.env.OPENCLAW_WORKSPACE, 'IDENTITY.md') : undefined,
+            join(homedir(), '.openclaw', 'workspace', 'IDENTITY.md'),
+        ].filter((p) => !!p);
+        for (const p of candidates) {
+            try {
+                const txt = readFileSync(p, 'utf8');
+                const m = txt.match(/\*\*\s*Name\s*:?\s*\*\*\s*:?\s*(.+)/i);
+                let name = m?.[1]?.trim();
+                if (!name)
+                    continue;
+                name = name.replace(/^[_*`]+|[_*`]+$/g, '').trim(); // strip stray markdown emphasis
+                if (!name || /^\d+$/.test(name) || /\btbd\b|fill this in/i.test(name))
+                    continue;
+                return name;
+            }
+            catch {
+                /* not found / unreadable — try the next candidate */
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Live heartbeat cadence in seconds — the agent's TRUE beat interval, read
+     * from the OpenClaw cron store (`~/.openclaw/cron/jobs.json` → the enabled
+     * heartbeat job's `schedule.everyMs`). This is the source of truth: the old
+     * hardcoded 1800 and `agents.defaults.heartbeat` are both stale/wrong once
+     * the operator edits the cron (`openclaw cron ... --every 15m`). Drives both
+     * the "beat every Nm" label and the unresponsive (2×) threshold. Cached 60s;
+     * returns undefined (caller defaults to 1800) when unreadable.
+     */
+    resolveHeartbeatSeconds() {
+        const now = Date.now();
+        if (this.heartbeatSeconds !== undefined && now - this.heartbeatReadAtMs < 60_000) {
+            return this.heartbeatSeconds;
+        }
+        const candidates = [
+            process.env.OPENCLAW_HOME ? join(process.env.OPENCLAW_HOME, 'cron', 'jobs.json') : undefined,
+            join(homedir(), '.openclaw', 'cron', 'jobs.json'),
+        ].filter((p) => !!p);
+        const everyMsOf = (j) => {
+            if (!j || typeof j !== 'object')
+                return undefined;
+            const job = j;
+            if (job.enabled === false)
+                return undefined;
+            const s = job.schedule;
+            return s?.kind === 'every' && typeof s.everyMs === 'number' && s.everyMs > 0 ? s.everyMs : undefined;
+        };
+        const nameOf = (j) => {
+            const n = j?.name;
+            return typeof n === 'string' ? n : '';
+        };
+        for (const p of candidates) {
+            try {
+                const parsed = JSON.parse(readFileSync(p, 'utf8'));
+                const jobs = parsed?.jobs;
+                if (!Array.isArray(jobs))
+                    continue;
+                const everyJobs = jobs.filter((j) => everyMsOf(j) !== undefined);
+                // Prefer the explicitly heartbeat-named job; else fall back only when a
+                // single recurring job exists (avoid mislabelling some other cron).
+                const hb = everyJobs.find((j) => /heart\s*beat/i.test(nameOf(j))) ??
+                    (everyJobs.length === 1 ? everyJobs[0] : undefined);
+                const ms = hb ? everyMsOf(hb) : undefined;
+                if (ms) {
+                    this.heartbeatSeconds = Math.round(ms / 1000);
+                    this.heartbeatReadAtMs = now;
+                    if (!this.loggedHeartbeat) {
+                        this.loggedHeartbeat = true;
+                        logger.info(TAG, `Heartbeat cadence resolved: ${this.heartbeatSeconds}s (~${Math.round(this.heartbeatSeconds / 60)}m) from ${p}`);
+                    }
+                    return this.heartbeatSeconds;
+                }
+            }
+            catch {
+                /* unreadable / malformed — try the next candidate */
+            }
+        }
+        this.heartbeatReadAtMs = now; // don't hammer the FS when absent
+        return this.heartbeatSeconds; // last known (may be undefined)
+    }
+    /** Build agent state from internal fields (used by both emitAgentState and getSnapshot). */
+    buildAgentState() {
+        return {
+            mode: this.agentMode,
+            strategy: this.lastKnownStrategy,
+            // Conditional spread keeps the payload byte-identical to the pre-feature
+            // shape when the gateway hasn't surfaced an identity yet.
+            ...(this.agentIdentity.name ? { agentName: this.agentIdentity.name } : {}),
+            ...(this.agentIdentity.model ? { model: this.agentIdentity.model } : {}),
+            health: {
+                uptime: Math.floor((Date.now() - this.startTime) / 1000),
+                lastDecision: this.eventParser?.getLastDecision() ?? new Date(this.startTime).toISOString(),
+                lastTrade: this.lastTradeTs,
+                errorRate: this.eventParser?.getErrorRate() ?? 0,
+                thinkingInterval: this.resolveHeartbeatSeconds() ?? 1800,
+                gatewayWs: this.wsClient?.getState() ?? 'disconnected',
+            },
+        };
+    }
+    // ---- State emission ----
+    emitAgentState() {
+        this.fire('agentState', {
+            state: this.buildAgentState(),
+            timestamp: new Date().toISOString(),
+        });
+    }
+    emitRiskUpdate() {
+        const metrics = this.computeRiskMetrics();
+        // Auto-flatten on RED zone: if drawdown exceeds -2.5% and agent is active, flatten all.
+        // SAFETY guards — all three must be clear before we trust the RED verdict:
+        //  1. Startup grace (30s): on restart, wallet loads instantly but positions lag,
+        //     making equity look artificially low.
+        //  2. Balance freshness: hasReceivedBalance must be true AND balance.total > 0.
+        //     Binance 429 rate limits were leaving `this.balance` stale at 0 in live mode,
+        //     and computeEquity() (paper-mode formula) then read equity ≈ position_notional
+        //     only — a $186 account with a $20 short showed as -89% drawdown, triggering
+        //     an auto-flatten loop every minute. If we don't have fresh wallet data we
+        //     cannot trust the drawdown number; wait for the next poll.
+        //  3. Sanity floor: a single-minute drawdown more negative than -50% is
+        //     physically impossible under normal market conditions on a bracketed
+        //     account. If the math says worse than that, it's bad data — log loudly
+        //     and skip instead of closing real positions on a calculation error.
+        const uptimeMs = Date.now() - this.startedAt;
+        const STARTUP_GRACE_PERIOD_MS = 30_000;
+        const IMPOSSIBLE_DRAWDOWN = -0.5;
+        if (metrics.drawdownZone === 'RED' && this.agentMode === 'ACTIVE') {
+            if (uptimeMs < STARTUP_GRACE_PERIOD_MS) {
+                logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) but within startup grace period (${Math.round(uptimeMs / 1000)}s) — skipping auto-flatten`);
+            }
+            else if (!this.hasReceivedBalance || this.balance.total <= 0) {
+                logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) but balance data is stale/missing (received=${this.hasReceivedBalance}, total=${this.balance.total}) — skipping auto-flatten, waiting for fresh wallet data`);
+            }
+            else if (metrics.utilization.dailyDrawdown < IMPOSSIBLE_DRAWDOWN) {
+                logger.error(TAG, `RED zone drawdown ${(metrics.utilization.dailyDrawdown * 100).toFixed(1)}% exceeds sanity floor ${IMPOSSIBLE_DRAWDOWN * 100}% — refusing auto-flatten, likely equity calculation error (balance.total=${this.balance.total}, sessionStartNav=${this.sessionStartNav}, positions=${this.positions.length})`);
+            }
+            else {
+                logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) — auto-flattening all positions`);
+                // Route through executeEmergency (NOT executeFlatten directly) so the
+                // dual-fire dedup guard applies: emitRiskUpdate runs on every risk
+                // recompute, and a fire-and-forget flatten only flips agentMode→STOPPED
+                // once it resolves. Two rapid RED recomputes (or a concurrent operator
+                // Flatten) would otherwise each launch a separate flatten — a second
+                // market close against not-yet-settled positions is a position-flip
+                // risk. The dedup collapses them to ONE in-flight execution.
+                void this.executeEmergency('flatten').catch(err => {
+                    logger.error(TAG, `Auto-flatten failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+        }
+        // Include position snapshots + balance in risk_update so the webapp can
+        // update KPI/PnL without depending on market_data ticker events.
+        const equity = this.computeEquity();
+        const nav = this.sessionStartNav > 0 ? this.sessionStartNav : Math.max(equity, 1);
+        const positionSnapshots = this.positions
+            .filter(p => (p.contracts ?? 0) !== 0)
+            .map(p => {
+            const contracts = Math.abs(p.contracts ?? 0);
+            const contractSize = p.contractSize ?? 1;
+            const quantity = contracts * contractSize;
+            const entryPrice = p.entryPrice ?? 0;
+            const currentPrice = p.markPrice ?? entryPrice;
+            const pnlMul = p.side === 'short' ? -1 : 1;
+            const unrealizedPnl = p.unrealizedPnl ?? (currentPrice - entryPrice) * quantity * pnlMul;
+            const costBasis = entryPrice * quantity;
+            const liqFields = extractLiquidationFields(p);
+            const bracketField = extractBracketField(p);
+            return {
+                symbol: p.symbol,
+                side: (p.side === 'short' ? 'SHORT' : 'LONG'),
+                quantity,
+                entryPrice,
+                currentPrice,
+                unrealizedPnl: +unrealizedPnl.toFixed(4),
+                unrealizedPnlPercent: costBasis > 0 ? +((unrealizedPnl / costBasis) * 100).toFixed(2) : 0,
+                portfolioPercent: +(((quantity * currentPrice) / nav) * 100).toFixed(2),
+                // Component C: MFE / give-back passthrough (see snapshotPositions site).
+                mfeR: typeof p.mfeR === 'number' ? p.mfeR : undefined,
+                mfePeakPrice: typeof p.mfePeakPrice === 'number' ? p.mfePeakPrice : undefined,
+                giveBackRatio: typeof p.giveBackRatio === 'number' ? p.giveBackRatio : undefined,
+                originalStopPrice: typeof p.originalStopPrice === 'number' ? p.originalStopPrice : undefined,
+                ...(bracketField !== undefined ? { bracket: bracketField } : {}),
+                ...liqFields,
+            };
+        });
+        // Live KPI NAV must equal Binance's "Margin Balance" = wallet +
+        // unrealized. Compute it directly from the fresh poller wallet
+        // (this.balance.total — BNFCR-aware, uPnl-excluded) + the unrealized
+        // already summed across positionSnapshots. We deliberately do NOT use
+        // this.equity here: it is only ever assigned in fetchFreshBalance(),
+        // which is dormant under userDataStream.mode=enforce, so it stayed null
+        // and the old `this.equity ?? this.balance.total` collapsed NAV to
+        // wallet-only (2026-05-16: dashboard NAV ≈ wallet, Realized off by the
+        // unrealized vs the Binance app). Paper keeps computeEquity (wallet +
+        // notional + unrealized) — correct there because paper deducts the full
+        // notional at open.
+        const liveUnrealizedTotal = positionSnapshots.reduce((sum, p) => sum + p.unrealizedPnl, 0);
+        const balanceTotal = this.tradingMode !== 'PAPER'
+            ? this.balance.total + liveUnrealizedTotal // live: wallet + unrealized = Binance Margin Balance
+            : equity; // paper: wallet + notional + unrealized
+        this.fire('riskUpdate', {
+            event: 'risk_update',
+            metrics,
+            positions: positionSnapshots,
+            balance: { total: balanceTotal, available: this.balance.available, locked: balanceTotal - this.balance.available },
+            sessionStartNav: this.sessionStartNav > 0 ? this.sessionStartNav : undefined,
+            realizedPnlToday: this.realizedPnlToday ?? undefined,
+            realizedPnlAllTime: this.realizedPnlAllTime ?? undefined,
+            sessionFeesPaid: this.paperSessionFees ?? undefined,
+            sessionAvgSlippageBps: this.paperAvgSlippageBps ?? undefined,
+            equity: this.equity ?? undefined,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /** Compute risk metrics — delegates to pure functions in risk-calculator.ts */
+    computeRiskMetrics() {
+        const result = _computeRiskMetrics({
+            balanceTotal: this.balance.total,
+            positions: this.positions,
+            lastTickerPrice: this.lastTicker?.lastPrice ?? null,
+            sessionStartNav: this.sessionStartNav,
+            orderTimestamps: this.orderTimestamps,
+            cancelTimestamps: this.cancelTimestamps,
+            atrData: this.atrData ?? undefined,
+            regime: this.currentRegime,
+            realizedPnlToday: this.realizedPnlToday ?? undefined,
+        });
+        // Store pruned timestamps back (non-mutating function returns new arrays)
+        this.orderTimestamps = result.prunedOrderTimestamps;
+        this.cancelTimestamps = result.prunedCancelTimestamps;
+        return result.metrics;
+    }
+    /** Compute total equity — delegates to pure function in risk-calculator.ts */
+    computeEquity() {
+        return _computeEquity({
+            balanceTotal: this.balance.total,
+            positions: this.positions,
+            lastTickerPrice: this.lastTicker?.lastPrice ?? null,
+        });
+    }
+    /** Compute signed notional — delegates to pure function in risk-calculator.ts */
+    computePositionNotional(pos) {
+        return _computePositionNotional(pos, this.lastTicker?.lastPrice ?? null);
+    }
+    // ---- Trade result reporting to Intelligence API ----
+    /**
+     * Report a completed trade to the Intelligence API for persistent cross-session analytics.
+     * Called when a position closes (detected via position polling diffs).
+     * Handles partial closes: updates remaining quantity in openTradeEntries instead of deleting.
+     *
+     * @param key       Composite key `symbol:side` into openTradeEntries
+     * @param symbol    CCXT symbol (e.g. "BTC/USDT")
+     * @param exitPrice Fill price for the close
+     * @param closedQty Quantity actually closed (may be less than full position for partial closes)
+     */
+    reportTradeResult(key, symbol, exitPrice, closedQty) {
+        const entry = this.openTradeEntries.get(key);
+        if (!entry) {
+            logger.debug(TAG, `No tracked entry for ${key} — skipping trade result report`);
+            return;
+        }
+        // Determine if this is a partial or full close
+        const remaining = entry.quantity - closedQty;
+        if (remaining > 0.0001) {
+            // Partial close — update remaining quantity, keep entry alive
+            this.openTradeEntries.set(key, { ...entry, quantity: remaining });
+        }
+        else {
+            // Full close — remove entry
+            this.openTradeEntries.delete(key);
+        }
+        const url = this.config.intelligenceUrl;
+        const token = this.config.connectionToken;
+        if (!url || !token) {
+            logger.debug(TAG, 'Intelligence not configured — skipping trade result report');
+            return;
+        }
+        const direction = entry.side === 'long' ? 'LONG' : 'SHORT';
+        const pnlMultiplier = entry.side === 'long' ? 1 : -1;
+        const realizedPnl = (exitPrice - entry.entryPrice) * closedQty * pnlMultiplier;
+        const realizedPnlPct = entry.entryPrice > 0
+            ? ((exitPrice - entry.entryPrice) / entry.entryPrice) * 100 * pnlMultiplier
+            : 0;
+        const durationSeconds = Math.floor((Date.now() - new Date(entry.entryTime).getTime()) / 1000);
+        const tradeResult = {
+            missionId: entry.missionId ?? `trade-${Date.now()}`,
+            symbol: symbol.replace('/', ''), // BTC/USDT → BTCUSDT for Intelligence API
+            direction,
+            strategy: this.lastKnownStrategy.name,
+            regime: entry.regime ?? this.currentRegime,
+            entryPrice: entry.entryPrice,
+            exitPrice,
+            quantity: closedQty,
+            realizedPnl: +realizedPnl.toFixed(4),
+            realizedPnlPct: +realizedPnlPct.toFixed(4),
+            durationSeconds,
+            fees: 0, // Fees tracked separately by simulator
+            timestamp: new Date().toISOString(),
+            setupType: entry.setupType,
+            confluenceScore: entry.confluenceScore,
+        };
+        const fullUrl = `${url}/api/trades`;
+        const report = fetch(fullUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(tradeResult),
+            signal: AbortSignal.timeout(10_000),
+        })
+            .then((res) => {
+            if (!res.ok) {
+                logger.warn(TAG, `Trade result report failed: HTTP ${res.status} — queuing for retry`);
+                this.enqueueFailedReport(tradeResult);
+            }
+            else {
+                logger.info(TAG, `Trade result reported: ${symbol} ${direction} ${closedQty} @ ${exitPrice} PnL=${realizedPnl > 0 ? '+' : ''}${realizedPnl.toFixed(2)} (${durationSeconds}s)`);
+            }
+        })
+            .catch((err) => {
+            logger.warn(TAG, `Trade result report error: ${formatError(err)} — queuing for retry`);
+            this.enqueueFailedReport(tradeResult);
+        })
+            .finally(() => {
+            this.inFlightReports = this.inFlightReports.filter((p) => p !== report);
+        });
+        this.inFlightReports.push(report);
+    }
+    /**
+     * Seed lastTradeTs from Intelligence API on startup. One-shot, best-effort.
+     * Prevents "Last Trade: Never" after every restart when the agent is flat.
+     */
+    async seedLastTradeTs() {
+        if (this.lastTradeTs)
+            return; // Already set (e.g. from WS event during init)
+        const url = this.config.intelligenceUrl;
+        const token = this.config.connectionToken;
+        if (!url || !token)
+            return;
+        try {
+            const res = await fetch(`${url}/api/analytics/${this.config.symbol.replace('/', '')}/trades?limit=1`, {
+                headers: { Authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (!res.ok)
+                return;
+            const trades = await res.json();
+            if (trades.length > 0 && trades[0].timestamp) {
+                this.lastTradeTs = trades[0].timestamp;
+                logger.info(TAG, `Seeded lastTradeTs from Intelligence: ${this.lastTradeTs}`);
+                this.emitAgentState(); // Re-emit with updated timestamp
+            }
+        }
+        catch {
+            // Best-effort — don't log noise on failure
+        }
+    }
+    // ---- Intelligence service polling ----
+    /** Symbol formatted for intelligence API (BTC/USDT → BTCUSDT). */
+    get intelligenceSymbol() {
+        return this.config.symbol.replace('/', '');
+    }
+    /** Shared intelligence poller with circuit-breaker (exponential backoff on errors). */
+    startIntelligencePoller(name, endpoint, intervalMs, onData, intervalRef, delayFirstMs = 0) {
+        const url = this.config.intelligenceUrl;
+        const token = this.config.connectionToken;
+        if (!url || !token) {
+            if (name === 'regime') {
+                logger.info(TAG, 'Intelligence service not configured — intelligence polling disabled');
+            }
+            return;
+        }
+        const symbol = this.intelligenceSymbol;
+        const fullUrl = `${url}/api/${endpoint}/${symbol}`;
+        logger.info(TAG, `Starting ${name} poller: ${fullUrl}`);
+        const poll = async () => {
+            if (!this.started)
+                return;
+            try {
+                const res = await fetch(fullUrl, {
+                    headers: { Authorization: `Bearer ${token}` },
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!res.ok) {
+                    this.trackIntelError(name, `HTTP ${res.status}`);
+                    return;
+                }
+                // Reset error tracking on success
+                this.intelErrors[name] = 0;
+                onData(await res.json());
+            }
+            catch (err) {
+                this.trackIntelError(name, formatError(err));
+            }
+        };
+        const start = () => {
+            void poll();
+            this[intervalRef] = setInterval(() => void poll(), intervalMs);
+        };
+        if (delayFirstMs > 0) {
+            const timer = setTimeout(start, delayFirstMs);
+            this.pendingStartTimers.push(timer);
+        }
+        else {
+            start();
+        }
+    }
+    /** Log first error per poller, suppress subsequent repeats. */
+    trackIntelError(name, detail) {
+        const count = (this.intelErrors[name] ?? 0) + 1;
+        this.intelErrors[name] = count;
+        if (count === 1) {
+            logger.warn(TAG, `${name} poll failed: ${detail} (suppressing repeats)`);
+        }
+    }
+    startRegimePoller() {
+        this.startIntelligencePoller('regime', 'regime', 60_000, (raw) => {
+            const data = raw;
+            const symbol = this.intelligenceSymbol;
+            // Store regime for regime-conditional risk limits
+            if (data.regime) {
+                this.currentRegime = data.regime;
+            }
+            this.fire('regimeUpdate', { ...data, event: 'regime_update', symbol });
+        }, 'regimeInterval');
+    }
+    startSignalPoller() {
+        this.startIntelligencePoller('signals', 'signals', 10_000, (raw) => {
+            const data = raw;
+            this.fire('signalUpdate', { ...data, event: 'signal_update' });
+        }, 'signalInterval');
+    }
+    startMissionPoller() {
+        this.startIntelligencePoller('missions', 'missions', 10_000, (raw) => {
+            const data = raw;
+            this.fire('missionUpdate', { ...data, event: 'mission_update' });
+            // Detect new PENDING missions — present to agent for execution
+            const currentIds = new Set(data.activeMissions.map((m) => m.missionId));
+            for (const m of data.activeMissions) {
+                if (!this.lastSeenMissionIds.has(m.missionId)) {
+                    logger.info(TAG, `New mission: ${m.missionId} (${m.strategy} ${m.direction} ${m.symbol}, size: ${(m.sizePct * 100).toFixed(2)}%)`);
+                    if (m.status === 'PENDING') {
+                        void this.presentMissionToAgent(m);
+                    }
+                }
+            }
+            this.lastSeenMissionIds = currentIds;
+        }, 'missionInterval');
+    }
+    startAnalyticsPoller() {
+        this.startIntelligencePoller('analytics', 'analytics', 30_000, (raw) => {
+            const data = raw;
+            this.fire('analyticsUpdate', { ...data, event: 'analytics_update' });
+        }, 'analyticsInterval', 15_000);
+    }
+    startDecisionTracePoller() {
+        this.startIntelligencePoller('decision-trace', 'decision-trace', 30_000, (raw) => {
+            const data = raw;
+            this.fire('decisionTraceUpdate', { ...data, event: 'decision_trace' });
+        }, 'decisionTraceInterval', 10_000);
+    }
+    // ---- Mission → Agent presentation ----
+    static STRATEGY_LABELS = {
+        trend_continuation: 'Trend Continuation',
+        liquidity_sweep: 'Liquidity Sweep',
+        funding_reversion: 'Funding Reversion',
+    };
+    async presentMissionToAgent(mission) {
+        const ws = this.wsClient;
+        if (!ws || !this.started)
+            return;
+        // Compute absolute position size from sizePct * NAV
+        const nav = this.computeEquity();
+        if (nav <= 0) {
+            logger.warn(TAG, `Cannot present mission ${mission.missionId}: NAV is ${nav}`);
+            return;
+        }
+        const absoluteSize = nav * mission.sizePct;
+        const lastPrice = this.lastTicker?.lastPrice ?? mission.entryZone.high;
+        const quantity = lastPrice > 0 ? absoluteSize / lastPrice : 0;
+        const strategyLabel = GatewayProvider.STRATEGY_LABELS[mission.strategy] ?? mission.strategy;
+        const conditionsSummary = mission.conditions
+            .map((c) => `${c.met ? '[x]' : '[ ]'} ${c.description}`)
+            .join('\n');
+        const targetLines = mission.targets
+            .map((t, i) => `  T${i + 1}: $${t.price.toFixed(2)} (${(t.pct * 100).toFixed(0)}%)`)
+            .join('\n');
+        const message = [
+            `TRADE MISSION: ${strategyLabel} ${mission.direction} ${mission.symbol}`,
+            '',
+            `Strategy: ${strategyLabel}`,
+            `Direction: ${mission.direction}`,
+            `Regime: ${mission.regime} (${(mission.regimeConfidence * 100).toFixed(0)}% confidence)`,
+            `Confluence: ${mission.confluenceScore}/${mission.conditions.length} conditions met`,
+            '',
+            'Conditions:',
+            conditionsSummary,
+            '',
+            `Entry zone: $${mission.entryZone.low.toFixed(2)} — $${mission.entryZone.high.toFixed(2)}`,
+            `Stop: $${mission.stopLevel.toFixed(2)}`,
+            `Targets:`,
+            targetLines,
+            '',
+            `Position size: ${(mission.sizePct * 100).toFixed(2)}% of NAV = $${absoluteSize.toFixed(2)} (≈${quantity.toFixed(6)} ${mission.symbol.replace(/\/.*/, '')})`,
+            `Sizing: Kelly=${(mission.sizingDetails.kellyFraction * 100).toFixed(1)}%, WR=${(mission.sizingDetails.winRate * 100).toFixed(0)}%, ${mission.sizingDetails.tradeCount} trades${mission.sizingDetails.cappedReason ? `, capped: ${mission.sizingDetails.cappedReason}` : ''}`,
+            '',
+            `Mission ID: ${mission.missionId}`,
+            `Expires: ${new Date(mission.expiresAt).toLocaleTimeString()}`,
+            '',
+            'Evaluate this setup and execute if you agree. Use place_order to enter. Respect your risk limits.',
+        ].join('\n');
+        try {
+            const idempotencyKey = `mission-${mission.missionId}-${Date.now()}`;
+            await ws.sendRpc('agent', { message, idempotencyKey, agentId: 'main' });
+            logger.info(TAG, `Presented mission ${mission.missionId} to agent ($${absoluteSize.toFixed(2)}, ${quantity.toFixed(6)} units)`);
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to present mission ${mission.missionId}: ${formatError(err)}`);
+        }
+    }
+    // ---- Event emission ----
+    fire(event, ...args) {
+        for (const listener of this.listeners[event]) {
+            try {
+                listener(...args);
+            }
+            catch (err) {
+                logger.error(TAG, `Event listener error (${event}): ${formatError(err)}`);
+            }
+        }
+    }
+}