@reefclaw/openclaw-plugin 0.1.0

package/index.js

@@ -0,0 +1,2030 @@
+// ReefClaw Trading Plugin — OpenClaw plugin entry point.
+// Registers 40 trading + analysis + learning tools with the OpenClaw gateway.
+// Supports three modes: PAPER → MICRO_LIVE → LIVE.
+// Paper mode: simulated execution, no API keys needed.
+//
+// CRITICAL: register() MUST be synchronous — OpenClaw silently ignores async registration.
+// CRITICAL: Agent needs "group:plugins" in tools.sandbox.tools.allow in openclaw.json.
+// See memory/connection.md for full deployment guide.
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BinancePublicApi } from './ccxt/binance-public.js';
+import { BinancePrivateApi } from './ccxt/binance-private.js';
+import { ExchangeSimulator } from './simulator/exchange-simulator.js';
+import { ShadowTracker } from './shadow/shadow-tracker.js';
+import { StateManager } from './persistence/state-manager.js';
+import { logger, setLogLevel, formatError } from './logger.js';
+import { DEFAULT_CONFIG } from './types.js';
+import { PaperAdapter } from './paper-adapter.js';
+import { LiveAdapter } from './live/live-adapter.js';
+import { loadBracketMode } from './config/brackets-config.js';
+import { loadUserDataStreamMode, loadUserDataStreamTunables, loadUserDataStreamDbWrite, getUserDataStreamIngestBaseUrl, resolveIngestToken, } from './config/user-data-stream-config.js';
+import { TradeStoreClient } from './ingest/trade-store-client.js';
+import { ProposalManager } from './live/proposal-manager.js';
+import { ProposalDecisionListener } from './live/proposal-decision-listener.js';
+import { PositionDecisionsClient } from './ingest/position-decisions-client.js';
+import { PositionStateStore } from './live/position-state-store.js';
+import { PendingEntryStore } from './ingest/pending-entry-metadata.js';
+import { onReconcilerObservedClose, reconcileStateStoreOnStartup } from './ingest/reconciler-cleanup.js';
+import { reconcileDbOpenVsExchange } from './ingest/reconcile-db-vs-exchange.js';
+import { IntelMicrostructureAssembler } from './live/microstructure-assembler.js';
+import { recordPositionReviewsTool } from './tools/record-position-reviews.js';
+import { getMyRecentReviewsTool } from './tools/get-my-recent-reviews.js';
+import { getRelevantLearningsTool } from './tools/get-relevant-learnings.js';
+import { getMyMinedPatternsTool } from './tools/get-my-mined-patterns.js';
+import { getMyProposedLearningsTool } from './tools/get-my-proposed-learnings.js';
+import { proposeLearningTool } from './tools/propose-learning.js';
+import { queryReviewOutcomesTool } from './tools/query-review-outcomes.js';
+import { loadPositionReviewMode } from './config/position-review-config.js';
+import { installSignalHandlers } from './lifecycle/install-signal-handlers.js';
+import { readPluginConfig } from './config/plugin-config-io.js';
+import { startConnectorSupervisor, hasBundledBridge } from './connector-supervisor.js';
+import { ToolGate } from './config/tool-gate.js';
+import { gateStore } from './config/gate-store.js';
+import { startAgentConfigPoller } from './config/agent-config-poller.js';
+import { PositionWatcher } from './live/stop-watcher.js';
+import { PaperMarketFeed } from './simulator/paper-market-feed.js';
+import { PluginRuntime } from './onboarding/runtime.js';
+import { getQuoteBalance, getQuoteWalletBalance } from './balance-utils.js';
+import { setExchangeCredentialsTool } from './tools/set-exchange-credentials.js';
+import { setTradingModeTool } from './tools/set-trading-mode.js';
+import { getBracketConfigTool } from './tools/get-bracket-config.js';
+import { setBracketRequirementTool } from './tools/set-bracket-requirement.js';
+import { testExchangeCredentialsTool } from './tools/test-exchange-credentials.js';
+import { clearExchangeCredentialsTool } from './tools/clear-exchange-credentials.js';
+// Tool implementations
+import { fetchTickerTool } from './tools/fetch-ticker.js';
+import { fetchOhlcvTool } from './tools/fetch-ohlcv.js';
+import { fetchBalanceTool } from './tools/fetch-balance.js';
+import { fetchPositionsTool } from './tools/fetch-positions.js';
+import { fetchOpenOrdersTool } from './tools/fetch-open-orders.js';
+import { createOrderTool } from './tools/create-order.js';
+import { cancelOrderTool } from './tools/cancel-order.js';
+import { cancelAllOrdersTool } from './tools/cancel-all-orders.js';
+import { closePositionTool } from './tools/close-position.js';
+import { modifyStopTool } from './tools/modify-stop.js';
+import { modifyTargetTool } from './tools/modify-target.js';
+import { attachBracketsTool } from './tools/attach-brackets.js';
+import { auditBracketProtectionTool } from './tools/audit-bracket-protection.js';
+import { getMarketStructureTool } from './tools/get-market-structure.js';
+import { computeVolFactor } from './risk/pre-trade-check.js';
+import { getCryptoMetricsTool } from './tools/get-crypto-metrics.js';
+import { getVolumeAnalysisTool } from './tools/get-volume-analysis.js';
+import { getRiskSummaryTool } from './tools/get-risk-summary.js';
+import { getMarketIntelTool } from './tools/get-market-intel.js';
+import { getRegimeTool } from './tools/get-regime.js';
+import { getSignalsTool } from './tools/get-signals.js';
+import { LocalSignalService } from './live/local-signal-service.js';
+import { getAnalyticsTool } from './tools/get-analytics.js';
+import { getOrderbookTool } from './tools/get-orderbook.js';
+import { getVolumeProfileTool } from './tools/get-volume-profile.js';
+import { getLiquidationLevelsTool } from './tools/get-liquidation-levels.js';
+import { getTradeFeedbackTool } from './tools/get-trade-feedback.js';
+import { getTradeFlowTool } from './tools/get-trade-flow.js';
+import { scoreSetupTool } from './tools/score-setup.js';
+import { checkPositionHealthTool } from './tools/check-position-health.js';
+import { getSizingTool } from './tools/get-sizing.js';
+import { getRiskScenarioTool } from './tools/get-risk-scenario.js';
+import { getSessionReviewTool } from './tools/get-session-review.js';
+import { getBacktestTool } from './tools/get-backtest.js';
+import { saveStrategyTool } from './tools/save-strategy.js';
+import { listStrategiesTool } from './tools/list-strategies.js';
+import { toggleStrategyTool } from './tools/toggle-strategy.js';
+import { getPatternScanTool } from './tools/get-pattern-scan.js';
+import { scanPairsTool } from './tools/scan-pairs.js';
+import { getSetupDetailTool } from './tools/get-setup-detail.js';
+import { queryTradesTool } from './tools/query-trades.js';
+import { getAgentProfileTool } from './tools/get-agent-profile.js';
+import { getCvdTool } from './tools/get-cvd.js';
+import { getMarketBreadthTool } from './tools/get-market-breadth.js';
+import { getBasisTool } from './tools/get-basis.js';
+import { getCascadeRiskTool } from './tools/get-cascade-risk.js';
+import { getSentimentTool } from './tools/get-sentiment.js';
+import { getDivergencesTool } from './tools/get-divergences.js';
+import { getLiquidationPulseTool } from './tools/get-liquidation-pulse.js';
+import { getRestingLiquidityTool } from './tools/get-resting-liquidity.js';
+import { getFundingContextTool } from './tools/get-funding-context.js';
+import { refreshTradingParams } from './trading-params-cache.js';
+const TAG = 'paper-trading';
+const PLUGIN_ID = 'reefclaw-paper-trading';
+/* eslint-enable @typescript-eslint/no-explicit-any */
+// ---- Tool parameter schemas (JSON Schema / TypeBox compatible at runtime) ----
+const TOOL_PARAMS = {
+    fetch_ticker: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+        },
+        required: ['symbol'],
+    },
+    fetch_ohlcv: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            timeframe: { type: 'string', description: 'Candle timeframe: 1m, 5m, 15m, 1h, 4h, 1d', default: '1h' },
+            limit: { type: 'number', description: 'Number of candles to fetch (max 1000)', default: 100 },
+        },
+        required: ['symbol'],
+    },
+    fetch_balance: {
+        type: 'object',
+        properties: {},
+    },
+    fetch_positions: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Filter by symbol (optional)' },
+        },
+    },
+    fetch_open_orders: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Filter by symbol (optional)' },
+        },
+    },
+    create_order: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            side: { type: 'string', enum: ['buy', 'sell'], description: 'Order side' },
+            type: { type: 'string', enum: ['market', 'limit'], description: 'Order type' },
+            amount: { type: 'number', description: 'Quantity in base currency (e.g. BTC amount)' },
+            price: { type: 'number', description: 'Limit price (required for limit orders)' },
+            stopPrice: { type: 'number', description: 'Protective stop-loss trigger price. REQUIRED in live mode when brackets.requireStopLoss is on (default). Must be below entry for longs, above entry for shorts.' },
+            setup_type: { type: 'string', description: 'Setup classification (e.g. pullback_to_ema, breakout, mean_reversion). REQUIRED in live mode.' },
+            thesis: { type: 'string', description: 'Entry reason in 1-2 sentences (≥20 chars). REQUIRED in live mode — the heartbeat reassessment compares against this.' },
+            target_price: { type: 'number', description: 'Planned profit target price. REQUIRED in live mode when brackets.requireTakeProfit is on (default).' },
+            regime: { type: 'string', description: 'Market regime at entry (e.g. TREND_UP, RANGE_TIGHT). REQUIRED in live mode — heartbeat uses this to detect regime flips.' },
+            regime_confidence: { type: 'number', description: 'Regime confidence 0-100. REQUIRED in live mode.' },
+            scorecard_verdict: { type: 'string', enum: ['STRONG_GO', 'GO', 'MARGINAL', 'NO_GO'], description: 'Scorecard verdict. REQUIRED in live mode.' },
+            confluence_score: { type: 'number', description: 'Composite scorecard score 0-10. REQUIRED in live mode — heartbeat reassessment compares delta against this.' },
+            invalidation_price: { type: 'number', description: 'Optional (recommended in live). The price at which this entry thesis is WRONG — your pinned "I am wrong here" level, distinct from the protective stopPrice. Surfaced back to you each heartbeat so you hold to your own plan instead of re-deciding. Long: below entry. Short: above entry.' },
+            realization_rule: { type: 'object', description: 'Optional (recommended in live). Your PLAN for taking profit, pinned at entry — indication, NOT auto-enforced. type=fixed_target|trail|scale|manual.', properties: { type: { type: 'string', enum: ['fixed_target', 'trail', 'scale', 'manual'] }, target_price: { type: 'number', description: 'For fixed_target.' }, trail_after_r: { type: 'number', description: 'For trail: begin trailing after +N R.' }, trail_distance_r: { type: 'number', description: 'For trail: distance behind peak, in R.' }, scale: { type: 'array', description: 'For scale: ladder rungs.', items: { type: 'object', properties: { at_r: { type: 'number' }, fraction: { type: 'number' } } } }, note: { type: 'string', description: 'Free-text plan summary.' } } },
+            supersedes_id: { type: 'string', description: 'Optional. When the operator is discussing a pending proposal in chat and wants a modification, pass the proposal_id from the chat-context header here. The webapp atomically marks the old proposal `superseded` and links the new one. No effect when approval mode is off. See SKILL.md Approval Mode section.' },
+        },
+        required: ['symbol', 'side', 'type', 'amount'],
+    },
+    cancel_order: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Order ID to cancel' },
+            symbol: { type: 'string', description: 'Optional symbol (e.g. BTC/USDT). Binance Futures requires a symbol for the underlying cancel call; if omitted, the plugin auto-resolves it from the open-orders snapshot. Provide it when you already know it to skip the lookup.' },
+        },
+        required: ['id'],
+    },
+    cancel_all_orders: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Cancel orders for this symbol only (optional)' },
+        },
+    },
+    close_position: {
+        type: 'object',
+        description: 'Close an open position at market. REQUIRES a documented reason and (except for operator_command) a structured assessment — see SKILL.md v2.10.0 Position Management Discipline. Brackets are the default exit; use this only for the five legitimate triggers.',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol of the position to close' },
+            reason: {
+                type: 'string',
+                enum: ['regime_flip', 'risk_limit', 'bracket_integrity', 'operator_command'],
+                description: 'Why you are closing manually instead of letting brackets handle it. Must match the decision-matrix trigger in your thinking.',
+            },
+            assessment: {
+                type: 'object',
+                description: 'Structured reasoning — populated from a fresh scorecard run this heartbeat. Required for all reasons except operator_command. Reason-specific consistency is enforced server-side.',
+                properties: {
+                    entry_score: { type: 'number', description: 'Scorecard confluence score at entry (0-10).' },
+                    current_score: { type: 'number', description: 'Telemetry only — fresh scorecard confluence this heartbeat (0-10). NOT an exit trigger (scorecard_reversal is deprecated).' },
+                    entry_regime: { type: 'string', description: 'Regime label at entry.' },
+                    current_regime: { type: 'string', description: 'Fresh regime label this heartbeat. For regime_flip, must differ from entry_regime.' },
+                    contradicting_metric: { type: 'string', description: 'Specific metric that flipped or crossed threshold. Required for regime_flip, risk_limit, bracket_integrity.' },
+                    position_age_seconds: { type: 'number', description: 'Telemetry only — how long the position has been open.' },
+                    r_multiple_at_close: { type: 'number', description: 'Telemetry only — R-multiple (profit/risk ratio) at close time.' },
+                },
+            },
+        },
+        required: ['symbol', 'reason'],
+    },
+    modify_stop: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol of the open live position' },
+            new_stop_price: { type: 'number', description: 'New stop-loss price (must be on the protective side of entry)' },
+        },
+        required: ['symbol', 'new_stop_price'],
+    },
+    modify_target: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol of the open live position' },
+            new_target_price: { type: 'number', description: 'New take-profit price (must be on the winning side of entry)' },
+        },
+        required: ['symbol', 'new_target_price'],
+    },
+    attach_brackets: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol of the open live position that needs protection' },
+            stop_price: { type: 'number', description: 'Stop-loss price (must be on the protective side of entry). Optional, but at least one of stop_price or target_price must be provided.' },
+            target_price: { type: 'number', description: 'Take-profit price (must be on the winning side of entry). Optional, but at least one of stop_price or target_price must be provided.' },
+        },
+        required: ['symbol'],
+    },
+    audit_bracket_protection: {
+        type: 'object',
+        properties: {},
+    },
+    record_position_reviews: {
+        type: 'object',
+        description: 'File a structured per-heartbeat review for every open position in one plural call. Pass one entry per open position; the validator REJECTS the whole call if any review is missing required fields, internally inconsistent, or contradicts itself (e.g. verdict=hold + thesis_status=invalidated). Required when positionReview.mode is shadow/observe/enforce. See SKILL.md "Position Reviews" + docs/POSITION_DECISION_JOURNAL_PLAN.md.',
+        properties: {
+            reviews: {
+                type: 'array',
+                description: 'One review per currently-open position. Order does not matter; validator enforces uniqueness by symbol.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        symbol: { type: 'string', description: 'Position symbol (e.g. BTC/USDT, no settle suffix).' },
+                        position_open_at: { type: 'number', description: 'Epoch ms when the position opened — match the value the heartbeat snapshot gave you.' },
+                        verdict: {
+                            type: 'string',
+                            enum: ['hold', 'add_on', 'close_recommended'],
+                            description: 'hold = thesis intact, no action; add_on = scale in (requires +0.5R AND +1.5 score delta); close_recommended = next heartbeat I will close unless something changes.',
+                        },
+                        thesis_status: {
+                            type: 'string',
+                            enum: ['intact', 'weakening', 'invalidated', 'evolving'],
+                            description: 'Health of the original entry thesis. invalidated forbids verdict=hold (call close_position instead).',
+                        },
+                        entry_score: { type: 'number', description: 'Confluence score frozen at entry (0-10).' },
+                        current_score: { type: 'number', description: 'Fresh confluence score this heartbeat (0-10).' },
+                        score_delta: { type: 'number', description: 'current_score - entry_score. Validator checks consistency to ±0.01.' },
+                        confluence_components: {
+                            type: 'object',
+                            description: 'REQUIRED. Which scorecard gates fire NOW, as a named-boolean object. Concrete shape: `{regime: true, structure: true, momentum: false, flow: true}` (four standard gates). At minimum supply ONE key; an empty `{}` passes the validator but corrupts the journal. Pre-2026-05-15 agents kept omitting this and burning a retry round-trip per heartbeat — it is documented here AND in the required[] array below.',
+                        },
+                        regime_entry: { type: 'string', description: 'Regime at entry.' },
+                        regime_current: { type: 'string', description: 'Regime now.' },
+                        regime_confidence: { type: 'number', description: 'Current regime confidence in [0, 1].' },
+                        r_multiple: { type: 'number', description: 'Current PnL in R-multiples (denominated against original stop). Cannot exceed mfe_r.' },
+                        distance_to_stop_bps: { type: 'number', description: 'Distance from current mark to stop, in basis points.' },
+                        distance_to_target_bps: { type: 'number', description: 'Distance from current mark to target, in basis points (optional).' },
+                        time_in_position_minutes: { type: 'number', description: 'Minutes since entry.' },
+                        mfe_r: { type: 'number', description: 'Max favourable excursion since entry, in R-multiples.' },
+                        give_back_pct: { type: 'number', description: 'Fraction of MFE peak surrendered: (mfe_r - r_multiple) / mfe_r when mfe_r > 0.' },
+                        what_changed: { type: 'string', description: 'What shifted since the previous review. ≥20 chars. Avoid template-filling — name the specific signal/level/event.' },
+                        invalidation_trigger: { type: 'string', description: 'The price/event/time that flips this position to verdict=close_recommended next cycle.' },
+                    },
+                    required: [
+                        'symbol',
+                        'position_open_at',
+                        'verdict',
+                        'thesis_status',
+                        'entry_score',
+                        'current_score',
+                        'score_delta',
+                        'confluence_components',
+                        'regime_entry',
+                        'regime_current',
+                        'regime_confidence',
+                        'r_multiple',
+                        'distance_to_stop_bps',
+                        'time_in_position_minutes',
+                        'mfe_r',
+                        'give_back_pct',
+                        'what_changed',
+                        'invalidation_trigger',
+                    ],
+                },
+            },
+        },
+        required: ['reviews'],
+    },
+    get_my_recent_reviews: {
+        type: 'object',
+        description: 'Phase 1 self-reflection: returns your last N position reviews per open position, plus a verdict-streak counter (e.g. "verdict=hold × 4 cycles, thesis_status: intact → weakening → weakening → weakening") and recent same-symbol re-entry context (last 24h opens / closes / realized R, minutes since last close). Call this BEFORE record_position_reviews each heartbeat. Without args returns context for ALL open positions. With symbol returns just that symbol.',
+        properties: {
+            symbol: {
+                type: 'string',
+                description: 'Optional. Canonical un-suffixed symbol (e.g. BTC/USDT). When omitted returns context for every currently-open position.',
+            },
+            review_limit: {
+                type: 'number',
+                description: 'Number of prior reviews to return per position (1–10, default 3).',
+            },
+        },
+    },
+    get_relevant_learnings: {
+        type: 'object',
+        description: 'Phase 4 curated learnings: returns up to 5 operator-confirmed learnings whose trigger_condition matches the current decision context. Each learning is a short directive (e.g. "Avoid macd_oversold_reversal entries unless funding < 30th percentile") backed by stats evidence from a mined pattern. Call BEFORE create_order (applies_at=entry), BEFORE record_position_reviews (applies_at=heartbeat), and BEFORE close_position (applies_at=close). Learnings INFORM your decision — they do not gate it. If a learning conflicts with your in-context reasoning, name the conflict in your thesis (entry) or what_changed (review). Empty list = no curated learning matches the current context; proceed normally.',
+        properties: {
+            applies_at: {
+                type: 'string',
+                enum: ['entry', 'heartbeat', 'close'],
+                description: 'Which decision point you are currently at.',
+            },
+            setup_type: {
+                type: 'string',
+                description: 'Optional. Setup_type the entry/review/close is about (e.g. "breakout"). Filters learnings whose trigger_condition.setup_type matches.',
+            },
+            regime: {
+                type: 'string',
+                description: 'Optional. Current regime (e.g. "trending_up"). Filters learnings whose trigger_condition.regime matches.',
+            },
+            verdict: {
+                type: 'string',
+                enum: ['hold', 'add_on', 'close_recommended'],
+                description: 'Optional, for applies_at=heartbeat. Verdict you intend to file. Filters learnings whose trigger_condition.verdict matches.',
+            },
+        },
+        required: ['applies_at'],
+    },
+    get_my_mined_patterns: {
+        type: 'object',
+        description: 'Phase 4.5 self-assessment: read your own daily-mined statistical patterns from your own trade history. Each row is a pattern with sample_size, effect_size, p_value, match_conditions (e.g. {"setupType":"macd_oversold_reversal"}), and a human_summary. Use BEFORE propose_learning to pick which patterns deserve a directive. Filter by within_days (default 14), min_sample_size (default 20), max_p_value (default 0.05). Includes only your own user_id data — never other users. Returns at most 50 rows ranked by absolute effect size.',
+        properties: {
+            within_days: {
+                type: 'number',
+                description: 'Mined-pattern recency window in days (default 14, max 90).',
+            },
+            min_sample_size: {
+                type: 'number',
+                description: 'Minimum trades in the pattern to consider (default 20).',
+            },
+            max_p_value: {
+                type: 'number',
+                description: 'Maximum p-value (default 0.05). Statistical significance bar.',
+            },
+            include_promoted: {
+                type: 'boolean',
+                description: 'When true, also returns patterns already promoted to learnings. Default false.',
+            },
+        },
+    },
+    get_my_proposed_learnings: {
+        type: 'object',
+        description: 'Phase 4.5 self-audit: read your own learnings across all confidence states (hypothesis / confirmed / retired). Distinct from get_relevant_learnings, which returns only confirmed + context-matched. Call BEFORE propose_learning so you do not draft a duplicate of something already pending review or curated. Returns rows tagged with proposed_by (agent / operator) and auto_confirmed.',
+        properties: {
+            include_hypothesis: { type: 'boolean', description: 'Include hypothesis state (default true).' },
+            include_confirmed: { type: 'boolean', description: 'Include confirmed state (default true).' },
+            include_retired: { type: 'boolean', description: 'Include retired state (default false).' },
+            proposed_by: {
+                type: 'string',
+                enum: ['agent', 'operator'],
+                description: 'Optional: filter to drafts by agent or by operator.',
+            },
+        },
+    },
+    propose_learning: {
+        type: 'object',
+        description: 'Phase 4.5: draft a new learning candidate for the operator to review. Server-side rules: proposed_by is forced to "agent"; confidence is server-determined from the operator\'s trust mode (manual → hypothesis, auto → confirmed). Throttle: max 3 proposals per rolling 24h per user. You MUST cite evidence — either by supplying source_mined_pattern_id (recommended; auto-attaches the pattern stats) or by supplying evidence.sample_size + evidence.p_value yourself. Directive style: quote n / effect size / p-value / a recent concrete example / default action / override conditions. Operators retain agency; learnings inform, they do not gate.',
+        properties: {
+            applies_at: {
+                type: 'string',
+                enum: ['entry', 'heartbeat', 'close'],
+                description: 'Which decision point this directive applies to.',
+            },
+            title: {
+                type: 'string',
+                description: 'Short title for the learning (operator sees this in the curation list). Min 4 chars.',
+            },
+            directive: {
+                type: 'string',
+                description: 'The full directive the agent will read at decision time. Include n, effect size, p-value, recent example, default action, and override conditions. Min 20 chars.',
+            },
+            source_mined_pattern_id: {
+                type: 'string',
+                description: 'UUID of the mined_pattern row this proposal is derived from (recommended). The server auto-attaches the pattern stats and back-links promotion.',
+            },
+            trigger_condition: {
+                type: 'object',
+                description: 'Optional. When the directive should match. E.g. {"setupType":"macd_oversold_reversal"} or {"verdict":"hold","thesisStatus":"weakening"}. If omitted with source_mined_pattern_id, the pattern\'s match_conditions are used.',
+            },
+            evidence: {
+                type: 'object',
+                description: 'Optional. Stats backing the directive. Required when source_mined_pattern_id is omitted: must contain sample_size (positive number) and p_value (0..1).',
+            },
+        },
+        required: ['applies_at', 'title', 'directive'],
+    },
+    query_review_outcomes: {
+        type: 'object',
+        description: 'Phase 2 outcome attribution: aggregate stats over your past position reviews joined to their close outcomes. Returns count, win rate, median R, mean R, median give-back, p25/p75 R distribution, and a histogram of close_reason — over reviews matching the filters. Plus a small newest-first sample. Use to find verdict patterns that bleed edge: if (verdict=hold + thesis_status=weakening) shows median R < 0 across 5+ closed samples, that combination is consistently underperforming and your future verdicts in similar conditions need stronger justification. Call at session start (and daily after first fill) for your most-used (verdict, thesis_status) combinations.',
+        properties: {
+            verdict: {
+                type: 'string',
+                enum: ['hold', 'add_on', 'close_recommended'],
+                description: 'Filter to reviews with this verdict.',
+            },
+            thesis_status: {
+                type: 'string',
+                enum: ['intact', 'weakening', 'invalidated', 'evolving'],
+                description: 'Filter to reviews with this thesis_status.',
+            },
+            regime_current: { type: 'string', description: 'Filter to reviews where regime_current matched (exact match).' },
+            symbol: { type: 'string', description: 'Filter to reviews on this symbol (canonical un-suffixed).' },
+            side: { type: 'string', enum: ['long', 'short'], description: 'Filter to reviews on positions of this side.' },
+            setup_type: { type: 'string', description: 'Filter to reviews on positions whose first non-scale-in entry used this setup_type.' },
+            days_back: {
+                type: 'number',
+                description: 'Window length in days from now (default 7, max 90). Only reviews filed within this window are counted.',
+            },
+            min_score_delta: { type: 'number', description: 'Filter to reviews with score_delta >= this (e.g. -1.0).' },
+            max_score_delta: { type: 'number', description: 'Filter to reviews with score_delta <= this.' },
+            closed_only: {
+                type: 'boolean',
+                description: 'When true, includes only reviews on positions that have closed. Default false (all reviews; outcome columns NULL for open positions).',
+            },
+            sample_limit: { type: 'number', description: 'Number of sample reviews to return alongside the stats (1–25, default 5).' },
+        },
+    },
+    get_market_structure: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            timeframes: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Timeframes to analyze (default: all). Options: 5m, 15m, 1h, 4h, 1d, 1w',
+            },
+        },
+        required: ['symbol'],
+    },
+    get_crypto_metrics: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+        },
+        required: ['symbol'],
+    },
+    get_volume_analysis: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            timeframe: { type: 'string', description: 'Candle timeframe for volume analysis (default: 5m)', default: '5m' },
+        },
+        required: ['symbol'],
+    },
+    get_risk_summary: {
+        type: 'object',
+        properties: {},
+    },
+    get_market_intel: {
+        type: 'object',
+        properties: {
+            category: {
+                type: 'string',
+                enum: ['sentiment', 'news', 'calendar', 'overview', 'derivatives', 'onchain', 'social'],
+                description: 'Category of market intelligence: sentiment (fear/greed, dominance), news (crypto headlines), calendar (economic events), overview (top coins, trending), derivatives (OI, funding, long/short ratios), onchain (BTC network, mempool, whale txs), social (community stats, trending posts)',
+            },
+            symbols: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional symbols to filter results (e.g. ["BTC", "ETH"])',
+            },
+        },
+        required: ['category'],
+    },
+    get_regime: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to classify, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    get_signals: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get signals for, e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Hours of signal history to include (default: 24)', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_analytics: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get analytics for, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    get_orderbook: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            depth: { type: 'number', description: 'Number of price levels (5-100, default: 20)', default: 20 },
+        },
+        required: ['symbol'],
+    },
+    get_volume_profile: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get volume profile for, e.g. BTCUSDT' },
+            period: { type: 'number', description: 'Hours of data to aggregate (24, 168, 720). Default: 24', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_liquidation_levels: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get liquidation levels for, e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Hours of liquidation history (1-168). Default: 24', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_trade_feedback: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get feedback for, e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Hours of trade history to analyze (default: 168 = 7 days)', default: 168 },
+        },
+        required: ['symbol'],
+    },
+    get_trade_flow: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get trade flow for, e.g. BTCUSDT' },
+            minutes: { type: 'number', description: 'Minutes of flow data to aggregate (1-60, default: 5)', default: 5 },
+        },
+        required: ['symbol'],
+    },
+    score_setup: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol (intelligence format), e.g. BTCUSDT' },
+            direction: { type: 'string', enum: ['LONG', 'SHORT'], description: 'Trade direction' },
+            setup_type: { type: 'string', description: 'Setup type tag, e.g. pullback_to_ema, breakout_retest' },
+            entry_price: { type: 'number', description: 'Planned entry price' },
+            stop_price: { type: 'number', description: 'Planned stop-loss price' },
+            target_price: { type: 'number', description: 'Planned take-profit price' },
+        },
+        required: ['symbol', 'direction', 'setup_type', 'entry_price', 'stop_price', 'target_price'],
+    },
+    get_sizing: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol (intelligence format), e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    check_position_health: {
+        type: 'object',
+        properties: {
+            positions: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        symbol: { type: 'string', description: 'Trading pair, e.g. BTC/USDT' },
+                        side: { type: 'string', enum: ['LONG', 'SHORT'], description: 'Position direction' },
+                        entry_price: { type: 'number', description: 'Entry price' },
+                        current_price: { type: 'number', description: 'Current market price' },
+                        stop_price: { type: 'number', description: 'Current stop-loss price' },
+                        target_price: { type: 'number', description: 'Target price (optional)' },
+                        quantity: { type: 'number', description: 'Position size in base currency' },
+                        entry_time: { type: 'string', description: 'Position open time (ISO 8601)' },
+                    },
+                    required: ['symbol', 'side', 'entry_price', 'current_price', 'stop_price', 'quantity', 'entry_time'],
+                },
+                description: 'Array of open positions to check',
+            },
+            account_balance: { type: 'number', description: 'Total account balance in USDT' },
+        },
+        required: ['positions', 'account_balance'],
+    },
+    get_risk_scenario: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            moves: { type: 'string', description: 'Comma-separated % moves to test, e.g. "-3,-5,+5". If omitted, auto-generates ±1/2/3 ATR scenarios.' },
+        },
+        required: ['symbol'],
+    },
+    get_session_review: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol (intelligence format), e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Hours of trading history to review (default: 24, max: 720)', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_backtest: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            strategy: { type: 'string', description: 'Strategy to test: trend_continuation, liquidity_sweep, funding_reversion, or "all" (default: all). Also accepts custom strategy names from the Strategy Box.' },
+            months: { type: 'number', description: 'How many months of history to backtest (default: 6)' },
+            sizing: { type: 'string', description: 'Position sizing method: "fixed" (default) or "kelly"' },
+            regime_filter: { type: 'string', description: 'Comma-separated regimes to trade in, e.g. "TREND_UP,TREND_DOWN". If omitted, trades in all regimes each strategy allows.' },
+            timeframe: { type: 'string', description: 'Candle timeframe for evaluation: "15m", "1h" (default), "4h", "1d". Shorter = more trades but slower. Indicators adapt to the chosen timeframe.' },
+        },
+        required: ['symbol'],
+    },
+    get_pattern_scan: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Trading pair symbol, e.g. BTC/USDT' },
+            timeframe: { type: 'string', description: 'Candle timeframe to analyze (default: 1h). Options: 5m, 15m, 1h, 4h' },
+        },
+        required: ['symbol'],
+    },
+    save_strategy: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Unique strategy name (lowercase, underscores, 3-50 chars), e.g. "ema_bounce_trending"' },
+            description: { type: 'string', description: 'Human-readable description of what this strategy does' },
+            regimes: { type: 'string', description: 'Comma-separated regimes: TREND_UP, TREND_DOWN, RANGE_TIGHT, RANGE_WIDE' },
+            direction_rule: { type: 'string', description: 'How to determine trade direction: from_regime, from_sweep, from_funding, fixed_long, fixed_short' },
+            conditions: { type: 'string', description: 'JSON array of conditions: [{"type":"ema_proximity","params":{"period":21,"maxDistPct":0.003}}, ...]. 23 types: ema_proximity, orderbook_imbalance, funding_not_crowded, oi_slope, no_liquidation_cluster, price_sweep, liquidations_at_sweep, order_flow_absorption, funding_contrarian, funding_extreme, oi_elevated, price_at_level, macd_crossover, macd_divergence, bollinger_squeeze, bollinger_breakout, vwap_position, stoch_rsi_extreme, adx_trending, adx_ranging, ichimoku_cloud, obv_divergence, supertrend_direction' },
+            entry_type: { type: 'string', description: 'Entry zone rule: ema_offset (params: period, atrFraction), sweep_range, atr_offset (params: atrFraction)' },
+            entry_params: { type: 'string', description: 'JSON params for entry rule, e.g. {"period":21,"atrFraction":0.3}' },
+            stop_type: { type: 'string', description: 'Stop rule: swing_atr (params: swingCount, atrFraction, fallbackAtrMultiple), recent_extreme_atr (params: atrFraction), fixed_atr (params: atrMultiple)' },
+            stop_params: { type: 'string', description: 'JSON params for stop rule, e.g. {"swingCount":3,"atrFraction":0.3}' },
+            target_r_multiples: { type: 'string', description: 'Comma-separated R-multiple targets, e.g. "1.5,2.5,3.5"' },
+        },
+        required: ['name', 'regimes', 'direction_rule', 'conditions', 'entry_type', 'stop_type', 'target_r_multiples'],
+    },
+    list_strategies: {
+        type: 'object',
+        properties: {
+            active_only: { type: 'boolean', description: 'If true, only return active strategies (default: false — returns all)' },
+        },
+    },
+    toggle_strategy: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Strategy name to activate/deactivate' },
+            active: { type: 'boolean', description: 'true to activate, false to deactivate' },
+        },
+        required: ['name', 'active'],
+    },
+    scan_pairs: {
+        type: 'object',
+        properties: {
+            min_score: { type: 'number', description: 'Minimum confluence score (0-10) to include in results (default: 4). Lower = more results, higher = stricter filter.' },
+            symbols: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional symbol whitelist (e.g. ["BTCUSDT","ETHUSDT","SOLUSDT"]). When omitted scans all 20 supported pairs. Use this to focus the scan on a specific watchlist when you already know which pairs you care about.',
+            },
+        },
+    },
+    get_setup_detail: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get detailed setup for, e.g. SOLUSDT, BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    query_trades: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Filter by symbol, e.g. BTCUSDT' },
+            setup_type: { type: 'string', description: 'Filter by setup type, e.g. pullback_to_ema' },
+            strategy: { type: 'string', description: 'Filter by strategy name' },
+            regime: { type: 'string', description: 'Filter by regime: TREND_UP, TREND_DOWN, RANGE_TIGHT, RANGE_WIDE, VOLATILITY_EXPANSION, AVOID' },
+            direction: { type: 'string', enum: ['LONG', 'SHORT'], description: 'Filter by trade direction' },
+            outcome: { type: 'string', enum: ['win', 'loss'], description: 'Filter by outcome (win = positive P&L, loss = negative)' },
+            hours: { type: 'number', description: 'Look back N hours (default: all time)' },
+            min_duration_seconds: { type: 'number', description: 'Min hold duration in seconds' },
+            max_duration_seconds: { type: 'number', description: 'Max hold duration in seconds' },
+            min_pnl_pct: { type: 'number', description: 'Min realized P&L % (e.g. -5 for losses > 5%)' },
+            max_pnl_pct: { type: 'number', description: 'Max realized P&L %' },
+            min_confluence_score: { type: 'number', description: 'Min confluence score at entry' },
+            feature_filters: { type: 'string', description: 'JSON array of feature_snapshot filters: [{"field":"adx","op":"gt","value":40}]. Available fields: adx, rsi_14, funding_rate, funding_zscore, oi_ratio, oi_slope, stoch_rsi, bb_width, vwap_distance, macd_histogram, supertrend_direction, volume_ratio, atr_pct, obv_slope, imbalance_ratio, ema20_distance, ema50_distance, ema200_distance, williams_r' },
+            group_by: { type: 'string', description: 'Aggregate results by: setup_type, strategy, regime, direction, or symbol. Returns win_rate, expectancy, count, avg_pnl per group.' },
+            limit: { type: 'number', description: 'Max results (default: 200, max: 500)' },
+        },
+    },
+    get_agent_profile: {
+        type: 'object',
+        properties: {},
+    },
+    get_cvd: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get CVD for, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    get_market_breadth: {
+        type: 'object',
+        properties: {
+            hours: { type: 'number', description: 'Lookback hours for correlation computation (1-168, default: 24)', default: 24 },
+        },
+    },
+    get_basis: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get basis for, e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Lookback hours for basis history (1-168, default: 24)', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_cascade_risk: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to assess cascade risk for, e.g. BTCUSDT' },
+            hours: { type: 'number', description: 'Lookback hours for liquidation history (1-168, default: 24)', default: 24 },
+        },
+        required: ['symbol'],
+    },
+    get_sentiment: {
+        type: 'object',
+        properties: {},
+    },
+    get_divergences: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to scan for divergences, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    get_liquidation_pulse: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get the cascade pulse for, e.g. BTCUSDT. Omit to get the cross-majors aggregate (BTC+ETH+BNB+SOL+XRP).' },
+            window_seconds: { type: 'number', description: 'Rolling window length in seconds (5-300, default: 60).', default: 60 },
+        },
+    },
+    get_resting_liquidity: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get resting limit-order liquidity for, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    get_funding_context: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol to get funding-rate percentile context for, e.g. BTCUSDT' },
+        },
+        required: ['symbol'],
+    },
+    // ---- Operator-only tools (called by the skill's operator scope, NOT the agent) ----
+    set_exchange_credentials: {
+        type: 'object',
+        properties: {
+            apiKey: { type: 'string', description: 'Binance API key' },
+            secret: { type: 'string', description: 'Binance API secret' },
+            testnet: { type: 'boolean', description: 'Use Binance testnet (default: false)' },
+        },
+        required: ['apiKey', 'secret'],
+    },
+    set_trading_mode: {
+        type: 'object',
+        properties: {
+            mode: { type: 'string', enum: ['PAPER', 'MICRO_LIVE', 'LIVE'], description: 'Target trading mode' },
+            acknowledged: { type: 'boolean', description: 'Required when moving to LIVE — explicit operator acknowledgment' },
+        },
+        required: ['mode'],
+    },
+    test_exchange_credentials: {
+        type: 'object',
+        properties: {
+            apiKey: { type: 'string', description: 'Binance API key to verify (not persisted)' },
+            secret: { type: 'string', description: 'Binance API secret to verify (not persisted)' },
+            testnet: { type: 'boolean', description: 'Test against Binance testnet' },
+        },
+        required: ['apiKey', 'secret'],
+    },
+    clear_exchange_credentials: {
+        type: 'object',
+        properties: {
+            confirm: { type: 'boolean', description: 'Must be true — safety gate against accidental probe wipes' },
+        },
+        required: ['confirm'],
+    },
+    get_bracket_config: {
+        type: 'object',
+        properties: {},
+    },
+    set_bracket_requirement: {
+        type: 'object',
+        properties: {
+            flag: { type: 'string', enum: ['requireStopLoss', 'requireTakeProfit'], description: 'Which requirement to flip' },
+            value: { type: 'boolean', description: 'New value. False disables the requirement and returns a warning banner copy.' },
+        },
+        required: ['flag', 'value'],
+    },
+};
+// ---- Helpers ----
+/** Wrap tool result in OpenClaw AgentToolResult format */
+function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+        details: data,
+    };
+}
+// ---- Plugin definition (OpenClaw format) ----
+// Module-level idempotency guard. OpenClaw's `plugins install --link` calls
+// register() 3× inside a single gateway process (once for validation, once
+// for metadata extraction, once for real activation). Without this guard,
+// each call instantiates a fresh LiveAdapter → fresh Binance REST pollers +
+// user-data WebSocket + listenKey. On 2026-04-20 that caused 3× the normal
+// weight consumption → Binance IP ban (418 "Way too many requests"), which
+// each poller's retry cycle then refreshed, creating a self-perpetuating
+// ban. The agent was unable to place protective brackets on live positions
+// for the duration. Fix: first register() wins, subsequent calls no-op.
+// Tools are re-registered on the second+ calls so OpenClaw's tool map stays
+// consistent (the api.registerTool factory closes over the singleton state
+// created on the first call).
+let pluginInitialised = false;
+let pluginToolsFactory = null;
+let pluginToolNames = [];
+const paperTradingPlugin = {
+    id: PLUGIN_ID,
+    name: 'ReefClaw Paper Trading',
+    description: 'Paper trading plugin with real Binance market data and simulated execution. No API keys required.',
+    configSchema: {
+        type: 'object',
+        properties: {
+            startingBalance: {
+                type: 'number',
+                default: 10000,
+                description: 'Starting USDT balance for paper trading',
+            },
+            symbol: {
+                type: 'string',
+                default: 'BTC/USDT',
+                description: 'Default trading symbol',
+            },
+        },
+    },
+    register(api) {
+        setLogLevel('info');
+        // Idempotency guard (see note above module singleton). If already
+        // initialised, re-register the same tools so OpenClaw's tool map stays
+        // populated across its multiple register() calls, but do NOT spin up a
+        // second adapter / stream / poller stack.
+        if (pluginInitialised) {
+            logger.warn(TAG, 'register() called again — reusing existing adapter (singleton)');
+            if (pluginToolsFactory) {
+                api.registerTool(pluginToolsFactory, { names: pluginToolNames });
+            }
+            // The supervisor must be (re)evaluated on EVERY register call, not just
+            // the first: the first full register can run BEFORE the installer has
+            // written connectorSupervisor='on' (the gateway hot-reloads the plugin
+            // the moment `plugins install --link` records it), and OpenClaw's
+            // in-process restart re-invokes register() down THIS early-return path.
+            // startConnectorSupervisor() is itself a singleton — repeat calls no-op.
+            maybeStartConnectorSupervisor();
+            return;
+        }
+        logger.info(TAG, 'Initializing paper trading plugin...');
+        // Resolve config from plugin settings
+        const pluginConfig = {
+            startingBalance: DEFAULT_CONFIG.startingBalance,
+            symbol: DEFAULT_CONFIG.symbol,
+            quoteCurrency: DEFAULT_CONFIG.quoteCurrency,
+        };
+        logger.info(TAG, `Config: ${pluginConfig.startingBalance} ${pluginConfig.quoteCurrency}, symbol: ${pluginConfig.symbol}`);
+        // Load or initialize state (sync — OpenClaw ignores async register())
+        const stateManager = new StateManager(PLUGIN_ID);
+        const state = stateManager.loadOrDefaultSync(pluginConfig.startingBalance, pluginConfig.quoteCurrency);
+        // Create CCXT instance and simulator
+        const binanceApi = new BinancePublicApi();
+        const simulator = new ExchangeSimulator(state);
+        // Wire persistence: save state on every mutation (debounced)
+        simulator.on('stateChanged', (newState) => {
+            stateManager.debouncedSave(newState);
+        });
+        // Reload state from disk before read operations.
+        // Fixes two-process architecture: agent process saves state to disk,
+        // gateway process must reload it before serving HTTP API calls.
+        const reloadState = () => {
+            try {
+                const fresh = stateManager.loadSync();
+                if (fresh) {
+                    simulator.replaceState(fresh);
+                }
+            }
+            catch (err) {
+                logger.warn(TAG, `State reload failed: ${formatError(err)}`);
+            }
+        };
+        // Read config: ReefClaw plugin config from ~/.reefclaw/plugin-config.json
+        // (OpenClaw's schema validation rejects custom keys in plugin entries)
+        let connectionToken = '';
+        let apiBaseUrl = 'https://www.reefclaw.com';
+        let intelligenceUrl = 'https://intel.reefclaw.com';
+        let exchangeConfig = null;
+        let tradingMode = 'PAPER';
+        let signalsEvaluator = 'central';
+        let signalsSymbols = [];
+        try {
+            const rcConfigPath = join(homedir(), '.reefclaw', 'plugin-config.json');
+            if (existsSync(rcConfigPath)) {
+                const rcRaw = readFileSync(rcConfigPath, 'utf-8');
+                const rcConfig = JSON.parse(rcRaw);
+                connectionToken = rcConfig?.connectionToken ?? '';
+                apiBaseUrl = rcConfig?.apiBaseUrl ?? apiBaseUrl;
+                intelligenceUrl = rcConfig?.intelligenceUrl ?? intelligenceUrl;
+                const ev = rcConfig?.signals?.evaluator;
+                if (ev === 'shadow' || ev === 'enforce')
+                    signalsEvaluator = ev;
+                if (Array.isArray(rcConfig?.signals?.symbols)) {
+                    signalsSymbols = rcConfig.signals.symbols.map((s) => String(s).toUpperCase());
+                }
+                // Read exchange credentials (Phase 9b)
+                const exchange = rcConfig?.exchange;
+                if (exchange?.apiKey && exchange?.secret) {
+                    exchangeConfig = {
+                        apiKey: exchange.apiKey,
+                        secret: exchange.secret,
+                        testnet: exchange.testnet ?? false,
+                    };
+                }
+                // Read trading mode (default: PAPER)
+                const mode = rcConfig?.tradingMode?.toUpperCase();
+                if (mode === 'SHADOW' || mode === 'MICRO_LIVE' || mode === 'LIVE') {
+                    tradingMode = mode;
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `Could not read ReefClaw config: ${formatError(err)}`);
+        }
+        if (connectionToken) {
+            logger.info(TAG, `Connection token loaded (prefix: ${connectionToken.slice(0, 7)}...)`);
+        }
+        else {
+            logger.warn(TAG, 'No connection token found — get_market_intel will return errors');
+        }
+        // Validate trading mode vs credentials
+        if (tradingMode !== 'PAPER' && !exchangeConfig) {
+            logger.warn(TAG, `Trading mode ${tradingMode} requires exchange API keys — falling back to PAPER`);
+            tradingMode = 'PAPER';
+        }
+        // Create a BinancePrivateApi for SHADOW mode balance reads whenever
+        // credentials exist — even if we start in PAPER, the user can switch
+        // to SHADOW at runtime via the dashboard.
+        let shadowPrivateApi = null;
+        if (exchangeConfig) {
+            try {
+                shadowPrivateApi = new BinancePrivateApi(exchangeConfig);
+            }
+            catch (err) {
+                logger.warn(TAG, `Failed to create shadow API client: ${formatError(err)}`);
+            }
+        }
+        // Initialize shadow tracker if in shadow mode
+        let shadowTracker = null;
+        if (tradingMode === 'SHADOW' && shadowPrivateApi) {
+            try {
+                shadowTracker = new ShadowTracker(shadowPrivateApi, simulator);
+                shadowTracker.start();
+                // Validate API keys asynchronously (don't block register)
+                shadowPrivateApi.validatePermissions().then(result => {
+                    if (result.canReadBalance && result.canReadPositions) {
+                        logger.info(TAG, 'Shadow mode: API key validation passed');
+                    }
+                    else {
+                        logger.warn(TAG, `Shadow mode: API key validation issues: ${result.errors.join(', ')}`);
+                    }
+                }).catch(err => {
+                    logger.warn(TAG, `Shadow mode: API key validation failed: ${formatError(err)}`);
+                });
+            }
+            catch (err) {
+                logger.warn(TAG, `Failed to initialize shadow mode: ${formatError(err)}`);
+                tradingMode = 'PAPER';
+            }
+        }
+        // ---- Position Decision Journal singletons (hoisted) ----
+        // Mode-agnostic: the state-store + decisions-client run in both PAPER and
+        // LIVE modes once the ingest env vars are present. The record_position_reviews
+        // tool is always registered; off-mode just skips the SKILL.md mandate +
+        // stale-gate. See docs/POSITION_DECISION_JOURNAL_PLAN.md.
+        //
+        // Hoisted above the adapter construction so the autoCapture context can be
+        // passed to LiveAdapter at construction time — the WS-driven ws-ingest
+        // path needs it to capture limit-order entries + scale-ins (PR1 deferral
+        // resolution, 2026-05-03).
+        const positionStateStore = new PositionStateStore();
+        const pendingEntryStore = new PendingEntryStore();
+        const positionReviewMode = loadPositionReviewMode();
+        if (positionReviewMode !== 'off') {
+            logger.info(TAG, `Position-review mode=${positionReviewMode}`);
+        }
+        let positionDecisionsClient;
+        let positionDecisionsUserId;
+        {
+            let cfgForIngest;
+            try {
+                cfgForIngest = readPluginConfig();
+            }
+            catch {
+                cfgForIngest = undefined;
+            }
+            // Ingest token: plugin-config.json `connectionToken` preferred, legacy
+            // WEBAPP_INGEST_TOKEN env as fallback — see resolveIngestToken.
+            const ingestToken = resolveIngestToken(cfgForIngest);
+            const reefclawUserId = process.env.REEFCLAW_USER_ID ?? '';
+            if (ingestToken && reefclawUserId) {
+                const ingestBaseUrl = getUserDataStreamIngestBaseUrl(cfgForIngest);
+                positionDecisionsClient = new PositionDecisionsClient({
+                    baseUrl: ingestBaseUrl,
+                    ingestToken,
+                });
+                positionDecisionsUserId = reefclawUserId;
+                logger.info(TAG, `Position-decisions ingest wired to ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
+            }
+            else {
+                logger.info(TAG, `Position-decisions ingest disabled (ingest token [plugin-config connectionToken / WEBAPP_INGEST_TOKEN] or REEFCLAW_USER_ID missing)`);
+            }
+        }
+        // Reduce-only-fill close capture: when a bracket SL/TP (or other reduce-only
+        // fill) takes a journaled position flat, auto-journal an exact close so the
+        // position doesn't leak as status='open' forever (close-bypass class). On by
+        // default; env kill-switch RC_JOURNAL_CLOSE_ON_FILL=off disables it.
+        const closeOnReduceOnlyFill = process.env.RC_JOURNAL_CLOSE_ON_FILL !== 'off';
+        const autoCapture = {
+            decisionsClient: positionDecisionsClient,
+            stateStore: positionStateStore,
+            pendingEntries: pendingEntryStore,
+            userId: positionDecisionsUserId,
+            closeOnReduceOnlyFill,
+            // Tag each journaled position with the active book so paper and live
+            // entries stay segregated. Read from `runtime` at capture time (deferred
+            // closure — only invoked on a fill, long after `runtime` is built), so it
+            // follows a live<->paper reconnect.
+            resolveMode: () => (runtime.adapter.isLive ? 'live' : 'paper'),
+        };
+        if (positionDecisionsClient) {
+            logger.info(TAG, `Journal close-on-reduce-only-fill ${closeOnReduceOnlyFill ? 'ENABLED' : 'disabled'}`);
+        }
+        // ---- Create exchange adapter based on trading mode ----
+        let adapter;
+        // Hoisted so the SIGTERM handler (declared after this block) can drain it
+        // on shutdown.  Only populated in live modes when dbWrite=on + env present.
+        let tradeIngest;
+        // Approval-mode Phase A — set when APPROVAL_SHADOW_MODE=1 + ingest deps present.
+        // Read by the create_order tool below to dual-write proposals. See §12 of
+        // docs/APPROVAL_MODE_DESIGN.md.
+        let proposalManagerCtx;
+        // Approval mode read at init from env + plugin-config.json; passed to the
+        // create_order tool so it picks the right branch (off / shadow / per_trade).
+        let approvalModeForTool = 'off';
+        // Approval-mode Phase B — listener that fires operator-approved proposals.
+        // Started below only when config.approval.mode === 'per_trade' AND we have
+        // ingest credentials. See docs/APPROVAL_MODE_DESIGN.md §2 + §7.3.
+        let proposalDecisionListener;
+        if (tradingMode === 'MICRO_LIVE' || tradingMode === 'LIVE') {
+            if (!exchangeConfig) {
+                // Already handled above (falls back to PAPER), but safety check
+                logger.error(TAG, `${tradingMode} mode requires exchange config — this should not happen`);
+                adapter = new PaperAdapter(simulator);
+                tradingMode = 'PAPER';
+            }
+            else {
+                // Read micro-live config
+                let microLiveConfig;
+                try {
+                    const rcConfigPath = join(homedir(), '.reefclaw', 'plugin-config.json');
+                    if (existsSync(rcConfigPath)) {
+                        const rcConfig = JSON.parse(readFileSync(rcConfigPath, 'utf-8'));
+                        if (rcConfig?.microLive) {
+                            microLiveConfig = {
+                                sizeCapPercent: rcConfig.microLive.sizeCapPercent,
+                                maxPositionUSDT: rcConfig.microLive.maxPositionUSDT,
+                            };
+                        }
+                    }
+                }
+                catch { /* already read above, best-effort */ }
+                // Bracket-orders feature flag read from plugin-config at construction time.
+                // Default 'off' keeps legacy stop-watcher behaviour while the feature rolls out.
+                const bracketMode = loadBracketMode();
+                if (bracketMode !== 'off') {
+                    logger.info(TAG, `Bracket orders enabled in mode=${bracketMode}`);
+                }
+                // User-data WebSocket stream flag — same mode-ladder pattern as brackets.
+                // Default 'off' keeps REST polling authoritative. Phase 1 ships dead-code;
+                // the flag flip to 'shadow' / 'observe' / 'enforce' is operator-driven.
+                const userDataStreamMode = loadUserDataStreamMode();
+                const userDataStreamTunables = loadUserDataStreamTunables();
+                if (userDataStreamMode !== 'off') {
+                    logger.info(TAG, `User-data stream enabled in mode=${userDataStreamMode}`);
+                }
+                // TRADE_AUDIT_TRAIL_PLAN Phase 1 — opt-in WS audit-trail ingest.
+                // Activates only when ALL of:
+                //   - userDataStream.mode != 'off'  (read path running)
+                //   - userDataStream.dbWrite = 'on' (operator opted in)
+                //   - ingest token resolvable      (plugin-config connectionToken,
+                //                                   else legacy WEBAPP_INGEST_TOKEN env)
+                //   - REEFCLAW_USER_ID env set     (trader identity)
+                // Any missing field → no ingest wired (silent dead-code default).
+                const dbWriteMode = loadUserDataStreamDbWrite();
+                let cfgForIngest;
+                try {
+                    cfgForIngest = readPluginConfig();
+                }
+                catch {
+                    cfgForIngest = undefined;
+                }
+                const ingestToken = resolveIngestToken(cfgForIngest);
+                const reefclawUserId = process.env.REEFCLAW_USER_ID ?? '';
+                if (userDataStreamMode !== 'off' &&
+                    dbWriteMode === 'on' &&
+                    ingestToken &&
+                    reefclawUserId) {
+                    const ingestBaseUrl = getUserDataStreamIngestBaseUrl(cfgForIngest);
+                    tradeIngest = {
+                        client: new TradeStoreClient({ baseUrl: ingestBaseUrl, ingestToken }),
+                        userId: reefclawUserId,
+                    };
+                    logger.info(TAG, `User-data stream dbWrite=on — WS audit-trail ingest wired to ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
+                }
+                else if (userDataStreamMode !== 'off' && dbWriteMode === 'on') {
+                    logger.warn(TAG, `User-data stream dbWrite=on but ingest token (plugin-config connectionToken / WEBAPP_INGEST_TOKEN) or REEFCLAW_USER_ID missing — audit-trail ingest disabled`);
+                }
+                // ---- Approval-mode wiring ----
+                // Two switches gate proposal-related behaviour:
+                //
+                //   1. config approval.mode='per_trade'  → THE feature. create_order
+                //      returns pending_approval (does NOT fire). ProposalDecisionListener
+                //      polls /pending-decisions and fires when the operator approves.
+                //
+                //   2. env APPROVAL_SHADOW_MODE=1        → Phase A telemetry only.
+                //      create_order dual-writes a shadow proposal row AND fires the
+                //      real order. Used to collect proposal-shape distribution before
+                //      flipping per_trade. Retired once per_trade has soaked.
+                //
+                // If both are set, per_trade wins — no point dual-writing shadow rows
+                // when we're collecting real ones. The ProposalManager itself is the
+                // same instance either way; `origin` on each insert distinguishes them.
+                //
+                // See docs/APPROVAL_MODE_DESIGN.md §12.
+                const approvalShadowEnabled = (process.env.APPROVAL_SHADOW_MODE ?? '').trim() === '1';
+                try {
+                    const cfg = readPluginConfig();
+                    if (cfg.approval?.mode === 'per_trade') {
+                        approvalModeForTool = 'per_trade';
+                    }
+                    else if (approvalShadowEnabled) {
+                        approvalModeForTool = 'shadow';
+                    }
+                }
+                catch {
+                    // Config read failed; fall back to env-only.
+                    if (approvalShadowEnabled)
+                        approvalModeForTool = 'shadow';
+                }
+                if (approvalModeForTool !== 'off' && ingestToken && reefclawUserId) {
+                    let cfgForUrl;
+                    try {
+                        cfgForUrl = readPluginConfig();
+                    }
+                    catch {
+                        cfgForUrl = undefined;
+                    }
+                    const ingestBaseUrl = getUserDataStreamIngestBaseUrl(cfgForUrl);
+                    proposalManagerCtx = {
+                        manager: new ProposalManager({ baseUrl: ingestBaseUrl, ingestToken }),
+                        userId: reefclawUserId,
+                    };
+                    logger.info(TAG, `Approval wiring active (mode=${approvalModeForTool}) → ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
+                }
+                else if (approvalModeForTool !== 'off') {
+                    logger.warn(TAG, `approval mode=${approvalModeForTool} but WEBAPP_INGEST_TOKEN or REEFCLAW_USER_ID env missing — proposal path disabled`);
+                    approvalModeForTool = 'off';
+                }
+                const liveAdapter = new LiveAdapter(exchangeConfig, tradingMode, microLiveConfig, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, autoCapture);
+                adapter = liveAdapter;
+                // ---- Approval-mode Phase B — start ProposalDecisionListener ----
+                // Started only when approval.mode='per_trade' AND proposalManagerCtx
+                // is wired (creds present). The listener polls /pending-decisions and
+                // fires approved proposals via createOrderTool with proposalManager
+                // omitted — that path runs the real adapter.createOrder.
+                if (approvalModeForTool === 'per_trade' && proposalManagerCtx) {
+                    try {
+                        const approvalCfg = readPluginConfig().approval;
+                        let cfgForUrl;
+                        try {
+                            cfgForUrl = readPluginConfig();
+                        }
+                        catch {
+                            cfgForUrl = undefined;
+                        }
+                        const ingestBaseUrl = getUserDataStreamIngestBaseUrl(cfgForUrl);
+                        proposalDecisionListener = new ProposalDecisionListener({
+                            baseUrl: ingestBaseUrl,
+                            ingestToken: ingestToken,
+                            userId: reefclawUserId,
+                            adapter: liveAdapter,
+                            binanceApi,
+                            autoCapture,
+                            pollIntervalMs: approvalCfg?.pollIntervalMs ?? 3_000,
+                        });
+                        proposalDecisionListener.start();
+                        logger.info(TAG, `ProposalDecisionListener started (poll ${approvalCfg?.pollIntervalMs ?? 3_000} ms)`);
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `Failed to start ProposalDecisionListener: ${String(err)}`);
+                    }
+                }
+                // Reconciler-driven close-bypass cleanup. The reconciler emits
+                // 'drift_detected' on every poll; we filter for 'closed' drifts
+                // (position observed flat on exchange while local thinks it's open).
+                // Fires for bracket SL/TP fills, opposite-side market orders, and
+                // external closes — all paths that bypass close_position() and
+                // would otherwise leave webapp DB + state-store stale.
+                // See plugin/src/ingest/reconciler-cleanup.ts.
+                liveAdapter.on('drift_detected', (result) => {
+                    for (const drift of result.drifts) {
+                        if (drift.type !== 'closed')
+                            continue;
+                        void onReconcilerObservedClose({
+                            decisionsClient: positionDecisionsClient,
+                            stateStore: positionStateStore,
+                            userId: positionDecisionsUserId,
+                            lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
+                        }, {
+                            symbol: drift.symbol,
+                            lastContracts: drift.localContracts,
+                            observedAtMs: new Date(result.timestamp).getTime(),
+                        }).catch((err) => {
+                            logger.error(TAG, `reconciler cleanup failed for ${drift.symbol}: ${formatError(err)}`);
+                        });
+                    }
+                });
+                // Post-registration async init (fire-and-forget — register must be sync)
+                liveAdapter.initialize().then(async () => {
+                    // After init, run a one-shot startup reconciliation between
+                    // state-store and exchange truth. The runtime drift_detected hook
+                    // only catches NEW close-bypass events (was-on-exchange-now-gone);
+                    // entries that became stale BEFORE the plugin started are invisible
+                    // to that loop. This pass closes that gap by sweeping state-store
+                    // against the current exchange snapshot.
+                    try {
+                        // One trusted fetch reused for all three boot ops (no extra Binance
+                        // weight). getPositionsOrNull() returns null on a failed/weight-paced
+                        // fetch; getPositions() would collapse that to [] (null≠empty trap).
+                        const trusted = await liveAdapter.getPositionsOrNull();
+                        const positions = trusted ?? [];
+                        await reconcileStateStoreOnStartup({
+                            decisionsClient: positionDecisionsClient,
+                            stateStore: positionStateStore,
+                            userId: positionDecisionsUserId,
+                            lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
+                        }, positions.map((p) => p.symbol));
+                        // Seed remaining-contracts for positions still open on the exchange
+                        // so the reduce-only-fill close handler can detect flat for entries
+                        // that opened before this plugin instance started (or before the
+                        // size-tracking field existed). seedRemainingContracts never clobbers
+                        // live fill-tracked state.
+                        for (const p of positions) {
+                            const contracts = Math.abs(Number(p.contracts));
+                            if (Number.isFinite(contracts) && contracts > 0) {
+                                positionStateStore.seedRemainingContracts(p.symbol, contracts);
+                            }
+                        }
+                        // DB-authoritative orphan close: close webapp `positions` rows that
+                        // are status='open' but absent from the exchange (closed on-exchange
+                        // while down / state-store wiped). ONLY on a TRUSTED snapshot — a
+                        // null (failed) fetch must never be read as "flat" and close the book.
+                        if (trusted !== null) {
+                            await reconcileDbOpenVsExchange({ decisionsClient: positionDecisionsClient, userId: positionDecisionsUserId }, trusted.map((p) => p.symbol));
+                        }
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `Startup state-store reconciliation failed: ${formatError(err)}`);
+                    }
+                }).catch(err => {
+                    logger.error(TAG, `Live adapter init failed: ${formatError(err)}`);
+                });
+            }
+        }
+        else {
+            adapter = new PaperAdapter(simulator);
+        }
+        // Build tool dependencies
+        // `simDeps` for tools that need the simulator directly (ticker, market structure, risk scenario)
+        // `adapterDeps` for the 7 adapter-based trading tools
+        const simDeps = { binanceApi, simulator };
+        const adapterDeps = { binanceApi, adapter };
+        // ---- Plugin runtime (mutable holder) ----
+        // Owns the adapter + mode + stop-watcher and exposes `reconnect()` so the
+        // operator can swap credentials / trading mode from the dashboard without
+        // restarting the gateway. Tools read `runtime.adapter` / `runtime.mode`
+        // through closures so a reconnect is visible everywhere at once.
+        //
+        // The stop-watcher polls open positions every 3s and auto-closes any
+        // where mark crosses metadata.stopPrice (see stop-watcher.ts). It runs
+        // independently of the LLM agent.
+        // EFFICIENCY_QUICK_WINS Change 1: default cadence is now 10s (was 3s) —
+        // see stop-watcher.ts. Operators can override / revert with zero deploy
+        // via plugin-config.json `stopWatcher.intervalMs`. Best-effort read;
+        // any failure falls back to the (already-reduced) default.
+        let stopWatcherIntervalMs;
+        try {
+            const swMs = readPluginConfig().stopWatcher?.intervalMs;
+            if (typeof swMs === 'number' && Number.isFinite(swMs) && swMs > 0) {
+                stopWatcherIntervalMs = swMs;
+                logger.info(TAG, `Stop-watcher interval overridden via plugin-config: ${swMs}ms`);
+            }
+        }
+        catch { /* best-effort — default applies */ }
+        const bootstrapWatcher = stopWatcherIntervalMs !== undefined
+            ? new PositionWatcher(adapter, stopWatcherIntervalMs)
+            : new PositionWatcher(adapter);
+        bootstrapWatcher.start();
+        // Paper-mode background market-data feed. Refreshes the simulator's marks
+        // for every symbol with an open position/order (not just the dashboard
+        // symbol), so the stop-watcher sees a fresh mark, NAV/uPnL stay live, and
+        // resting limits fill. Paper-only — started here when the boot adapter is
+        // paper; PluginRuntime.reconnect() stops it on a switch to live and
+        // restarts it on a switch back to paper. Reuses the ban-gated fetchTicker.
+        const marketFeed = new PaperMarketFeed(binanceApi, simulator);
+        if (!adapter.isLive) {
+            marketFeed.start();
+        }
+        const runtime = new PluginRuntime({
+            adapter,
+            mode: tradingMode,
+            simulator,
+            stopWatcher: bootstrapWatcher,
+            marketFeed,
+        });
+        const intelDeps = { connectionToken, apiBaseUrl };
+        const intelApiDeps = { connectionToken, intelligenceUrl };
+        // Facts-out local signal service (step 5). Created ONLY when the operator
+        // flips signals.evaluator to shadow/enforce in plugin-config — default
+        // 'central' leaves the get_signals path byte-identical (no service, no SSE
+        // connection, no behaviour change). Requires the intel fact stream on
+        // (RC_INTEL_FACTS_STREAM=on) + a configured symbols list.
+        let localSignalService = null;
+        if (signalsEvaluator !== 'central' && connectionToken && signalsSymbols.length > 0) {
+            localSignalService = new LocalSignalService({ intelligenceUrl, connectionToken, symbols: signalsSymbols });
+            localSignalService.start().catch((err) => logger.warn(TAG, `Local signal service start failed: ${formatError(err)}`));
+            logger.info(TAG, `Facts-out local evaluator=${signalsEvaluator} for ${signalsSymbols.length} symbols`);
+        }
+        const getSignalsDeps = {
+            ...intelApiDeps,
+            evaluatorMode: signalsEvaluator,
+            localSignalService,
+            logger,
+        };
+        // Microstructure heartbeat-push assembler. When the operator flips
+        // `microstructure.heartbeatPush=on` in plugin-config, every
+        // record_position_reviews call auto-fetches resting-liquidity +
+        // liquidation-pulse from intel and fills the orderbook columns
+        // (restingBandImbalance05 / cascadePulseAtReview / coveragePctAtReview).
+        // The assembler reads the flag itself; off-mode short-circuits to no
+        // network calls. Resolves PR1 deferral #3.
+        const microstructureAssembler = new IntelMicrostructureAssembler({
+            intelDeps: intelApiDeps,
+        });
+        // ---- Graceful shutdown ----
+        // Wired in a separate module (lifecycle/install-signal-handlers) so the
+        // network-send call sites (TradeStoreClient.drain, LiveAdapter.shutdown)
+        // never share a compiled file with the env-var reads above.  Avoids a
+        // false-positive on OpenClaw's plugin-install heuristic that flags
+        // env+network co-location as possible credential harvesting.
+        installSignalHandlers({
+            runtime,
+            tradeStore: tradeIngest?.client,
+            proposalListener: proposalDecisionListener,
+            stateManager,
+        });
+        // Warm the trading params cache (fire-and-forget — register must be sync)
+        refreshTradingParams(intelApiDeps).catch(err => {
+            logger.warn(TAG, `Failed to warm trading params cache: ${formatError(err)}`);
+        });
+        logger.info(TAG, `Plugin initialized in ${tradingMode} mode. Registering tools...`);
+        // Build tools array
+        const tools = [
+            {
+                name: 'fetch_ticker',
+                label: 'Fetch Ticker',
+                description: 'Fetch current ticker data (price, volume, 24h change) for a trading symbol. Uses real Binance market data.',
+                parameters: TOOL_PARAMS.fetch_ticker,
+                execute: async (_id, params) => jsonResult(await fetchTickerTool(params, simDeps)),
+            },
+            {
+                name: 'fetch_ohlcv',
+                label: 'Fetch OHLCV',
+                description: 'Fetch OHLCV candlestick data for a symbol. Uses real Binance market data.',
+                parameters: TOOL_PARAMS.fetch_ohlcv,
+                execute: async (_id, params) => jsonResult(await fetchOhlcvTool(params, simDeps)),
+            },
+            {
+                name: 'fetch_balance',
+                label: 'Fetch Balance',
+                description: 'Fetch current wallet balance. Returns real balance in live mode, simulated in paper mode.',
+                parameters: TOOL_PARAMS.fetch_balance,
+                execute: async () => {
+                    if (!runtime.adapter.isLive)
+                        reloadState();
+                    const balance = await fetchBalanceTool({}, adapterDeps);
+                    // Piggyback trading mode + readiness on balance response
+                    let displayBalance = { ...balance, tradingMode: runtime.mode, adapterReadiness: runtime.adapter.readiness };
+                    // SHADOW mode: override wallet display with real Binance balance.
+                    // Execution is still paper but KPI shows real funds.
+                    if (runtime.mode === 'SHADOW' && shadowPrivateApi) {
+                        try {
+                            const liveBalance = await shadowPrivateApi.fetchBalance();
+                            if (liveBalance) {
+                                const quoteTotal = getQuoteWalletBalance(liveBalance);
+                                const quoteFree = getQuoteBalance(liveBalance.free);
+                                const quoteUsed = getQuoteBalance(liveBalance.used);
+                                displayBalance = {
+                                    ...displayBalance,
+                                    free: liveBalance.free,
+                                    used: liveBalance.used,
+                                    total: liveBalance.total,
+                                    // Copy per-currency CCXT shape entries (e.g., USDT: {free,used,total}, USDC: {…})
+                                    ...(liveBalance.USDT ? { USDT: liveBalance.USDT } : {}),
+                                    ...(liveBalance.USDC ? { USDC: liveBalance.USDC } : {}),
+                                    equity: +quoteTotal.toFixed(4),
+                                    sessionStartNav: +quoteTotal.toFixed(4), // real balance IS the anchor
+                                };
+                            }
+                        }
+                        catch (err) {
+                            logger.warn(TAG, `Shadow balance fallback to paper: ${formatError(err)}`);
+                        }
+                    }
+                    return jsonResult(displayBalance);
+                },
+            },
+            {
+                name: 'fetch_positions',
+                label: 'Fetch Positions',
+                description: 'Fetch open positions with mark-to-market P&L. Returns real positions in live mode, simulated in paper mode.',
+                parameters: TOOL_PARAMS.fetch_positions,
+                execute: async (_id, params) => {
+                    if (!runtime.adapter.isLive)
+                        reloadState();
+                    return jsonResult(await fetchPositionsTool(params, adapterDeps));
+                },
+            },
+            {
+                name: 'fetch_open_orders',
+                label: 'Fetch Open Orders',
+                description: 'Fetch pending orders. Returns real orders in live mode, simulated in paper mode.',
+                parameters: TOOL_PARAMS.fetch_open_orders,
+                execute: async (_id, params) => {
+                    if (!runtime.adapter.isLive)
+                        reloadState();
+                    return jsonResult(await fetchOpenOrdersTool(params, adapterDeps));
+                },
+            },
+            {
+                name: 'create_order',
+                label: 'Create Order',
+                description: 'Create a buy or sell order. In paper mode, fills are simulated. In live mode, orders go to Binance Futures.',
+                parameters: TOOL_PARAMS.create_order,
+                execute: async (_id, params) => jsonResult(await createOrderTool(params, {
+                    ...adapterDeps,
+                    autoCapture,
+                    proposalManager: proposalManagerCtx?.manager,
+                    userId: proposalManagerCtx?.userId,
+                    approvalMode: approvalModeForTool,
+                })),
+            },
+            {
+                name: 'cancel_order',
+                label: 'Cancel Order',
+                description: 'Cancel a single open order by its ID.',
+                parameters: TOOL_PARAMS.cancel_order,
+                execute: async (_id, params) => jsonResult(await cancelOrderTool(params, adapterDeps)),
+            },
+            {
+                name: 'cancel_all_orders',
+                label: 'Cancel All Orders',
+                description: 'Cancel all open orders, optionally filtered by symbol.',
+                parameters: TOOL_PARAMS.cancel_all_orders,
+                execute: async (_id, params) => jsonResult(await cancelAllOrdersTool(params, adapterDeps)),
+            },
+            {
+                name: 'close_position',
+                label: 'Close Position',
+                description: 'Close an open position at market price by creating an opposing market order.',
+                parameters: TOOL_PARAMS.close_position,
+                execute: async (_id, params) => jsonResult(await closePositionTool(params, { ...adapterDeps, autoCapture })),
+            },
+            {
+                name: 'modify_stop',
+                label: 'Modify Stop',
+                description: 'Move the exchange-side stop-loss on an open live position. Atomic cancel-then-resubmit with automatic rollback. Live mode only; requires brackets.mode enabled.',
+                parameters: TOOL_PARAMS.modify_stop,
+                execute: async (_id, params) => jsonResult(await modifyStopTool(params, adapterDeps)),
+            },
+            {
+                name: 'modify_target',
+                label: 'Modify Target',
+                description: 'Move the exchange-side take-profit on an open live position. Atomic cancel-then-resubmit with automatic rollback. Live mode only; requires brackets.mode enabled.',
+                parameters: TOOL_PARAMS.modify_target,
+                execute: async (_id, params) => jsonResult(await modifyTargetTool(params, adapterDeps)),
+            },
+            {
+                name: 'attach_brackets',
+                label: 'Attach Brackets',
+                description: 'Bootstrap exchange-side STOP_MARKET + TAKE_PROFIT_MARKET protection on an existing open live position that is currently naked. Use this to recover when a position exists without active brackets (e.g. after kill-switch stripped them or brackets failed to attach at entry). Rejects if brackets are already active for the symbol — use modify_stop / modify_target instead. Live mode only; requires brackets.mode enabled.',
+                parameters: TOOL_PARAMS.attach_brackets,
+                execute: async (_id, params) => jsonResult(await attachBracketsTool(params, adapterDeps)),
+            },
+            {
+                name: 'audit_bracket_protection',
+                label: 'Audit Bracket Protection',
+                description: 'Return every open position with a verdict on whether exchange-side SL/TP protection is attached. Agent should run at SESSION START and every heartbeat — any has_stop=false must be resolved via attach_brackets or close_position before continuing. Works in both live and paper modes.',
+                parameters: TOOL_PARAMS.audit_bracket_protection,
+                execute: async () => jsonResult(await auditBracketProtectionTool({}, adapterDeps)),
+            },
+            {
+                name: 'record_position_reviews',
+                label: 'Record Position Reviews',
+                description: 'File a structured per-heartbeat review for every open position in one plural call. Schema-validated like v2.10.0 close_position. Required when positionReview.mode is shadow / observe / enforce; optional in off-mode. See SKILL.md "Position Reviews".',
+                parameters: TOOL_PARAMS.record_position_reviews,
+                execute: async (_id, params) => jsonResult(await recordPositionReviewsTool(params, {
+                    adapter,
+                    decisionsClient: positionDecisionsClient,
+                    stateStore: positionStateStore,
+                    userId: positionDecisionsUserId,
+                    gateMode: loadPositionReviewMode(),
+                    microstructureAssembler,
+                })),
+            },
+            {
+                name: 'get_my_recent_reviews',
+                label: 'Get My Recent Reviews',
+                description: 'Self-reflection lookup: per-position last N reviews + verdict-streak counter + 24h re-entry context. Call this BEFORE record_position_reviews each heartbeat to anchor your verdict in your own prior reasoning. Omit symbol to fetch all open positions in one call.',
+                parameters: TOOL_PARAMS.get_my_recent_reviews,
+                execute: async (_id, params) => jsonResult(await getMyRecentReviewsTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    stateStore: positionStateStore,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'get_relevant_learnings',
+                label: 'Get Relevant Learnings',
+                description: 'Phase 4 curated learnings: returns up to 5 operator-confirmed learnings whose trigger_condition matches the current decision context. Call at entry/heartbeat/close to read short directives backed by mined-pattern evidence. Learnings inform, they do not gate — your decision still stands.',
+                parameters: TOOL_PARAMS.get_relevant_learnings,
+                execute: async (_id, params) => jsonResult(await getRelevantLearningsTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'get_my_mined_patterns',
+                label: 'Get My Mined Patterns',
+                description: 'Phase 4.5: read your own statistically-significant patterns from your trade history. Use BEFORE propose_learning to pick which patterns deserve a directive. Returns rows with effect_size, p_value, match_conditions, and human_summary. Per-user — never returns other users\' data.',
+                parameters: TOOL_PARAMS.get_my_mined_patterns,
+                execute: async (_id, params) => jsonResult(await getMyMinedPatternsTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'get_my_proposed_learnings',
+                label: 'Get My Proposed Learnings',
+                description: 'Phase 4.5: list your own learnings across all confidence states (hypothesis / confirmed / retired). Use BEFORE propose_learning to avoid duplicate drafts. Distinct from get_relevant_learnings, which only returns confirmed + context-matched.',
+                parameters: TOOL_PARAMS.get_my_proposed_learnings,
+                execute: async (_id, params) => jsonResult(await getMyProposedLearningsTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'propose_learning',
+                label: 'Propose Learning',
+                description: 'Phase 4.5 self-assessment write: draft a new learning candidate for the operator to review. proposed_by is forced to "agent" server-side; confidence is server-determined from the operator\'s trust mode (manual → hypothesis, auto → confirmed + auto_confirmed=true). Throttle: max 3 per rolling 24h per user. Cite source_mined_pattern_id when possible. Directive must include n / effect / p / recent example / default action / override conditions.',
+                parameters: TOOL_PARAMS.propose_learning,
+                execute: async (_id, params) => jsonResult(await proposeLearningTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'query_review_outcomes',
+                label: 'Query Review Outcomes',
+                description: 'Aggregate stats + sample over your past position reviews joined to their close outcomes. Filter by verdict, thesis_status, regime, symbol, setup_type, days_back, etc. Surfaces verdict patterns that bleed edge — median R < 0 across 5+ closed samples is your evidence that a (verdict, thesis_status) combination is consistently underperforming. Call at session start and daily.',
+                parameters: TOOL_PARAMS.query_review_outcomes,
+                execute: async (_id, params) => jsonResult(await queryReviewOutcomesTool(params, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'get_market_structure',
+                label: 'Get Market Structure',
+                description: 'Multi-timeframe technical analysis — trend direction, regime, RSI, EMA crossover, momentum for 5m/15m/1h/4h/1d/1w. Uses real Binance market data.',
+                parameters: TOOL_PARAMS.get_market_structure,
+                execute: async (_id, params) => {
+                    const result = await getMarketStructureTool(params, simDeps);
+                    // Cache ATR data in simulator for pre-trade risk gate (paper mode)
+                    if (!runtime.adapter.isLive && 'atr' in result && result.atr) {
+                        const atrData = result.atr;
+                        simulator.updateBaselineAtr(atrData.atr14);
+                        const baseline = simulator.getBaselineAtr();
+                        if (baseline > 0) {
+                            simulator.setVolFactor(computeVolFactor(atrData.atr14, baseline));
+                        }
+                    }
+                    return jsonResult(result);
+                },
+            },
+            {
+                name: 'get_crypto_metrics',
+                label: 'Get Crypto Metrics',
+                description: 'Fetch funding rate (current + annualized) and open interest for a perpetual futures symbol. Useful for gauging market sentiment and crowding.',
+                parameters: TOOL_PARAMS.get_crypto_metrics,
+                execute: async (_id, params) => jsonResult(await getCryptoMetricsTool(params, simDeps)),
+            },
+            {
+                name: 'get_volume_analysis',
+                label: 'Get Volume Analysis',
+                description: 'Analyze recent volume: expansion ratio vs 20-bar average, directional thrust (-1 bearish to +1 bullish), close position in bar range, buy volume estimate. Detects volume surges and liquidity.',
+                parameters: TOOL_PARAMS.get_volume_analysis,
+                execute: async (_id, params) => jsonResult(await getVolumeAnalysisTool(params, simDeps)),
+            },
+            {
+                name: 'get_risk_summary',
+                label: 'Get Risk Summary',
+                description: 'Get current portfolio risk metrics: gross/net exposure, unrealized PnL, heat score (0-100), position breakdown, trading mode, shadow metrics. Use before trade decisions to assess risk budget.',
+                parameters: TOOL_PARAMS.get_risk_summary,
+                execute: async () => {
+                    reloadState();
+                    return jsonResult(await getRiskSummaryTool({}, { ...simDeps, tradingMode: runtime.mode, shadowTracker, adapter: runtime.adapter }));
+                },
+            },
+            {
+                name: 'get_market_intel',
+                label: 'Get Market Intelligence',
+                description: 'Fetch market intelligence from ReefClaw: sentiment (fear/greed, BTC dominance), news (crypto headlines with sentiment), calendar (upcoming economic events), overview (top coins, trending), derivatives (OI, funding rates, long/short ratios), onchain (BTC network stats, mempool fees, whale transactions), social (community data, trending posts). Requires Pro subscription.',
+                parameters: TOOL_PARAMS.get_market_intel,
+                execute: async (_id, params) => jsonResult(await getMarketIntelTool(params, intelDeps)),
+            },
+            {
+                name: 'get_regime',
+                label: 'Get Market Regime',
+                description: 'Get the current market regime classification (trend_up, trend_down, range_tight, range_wide, high_vol, avoid) with confidence score, class probabilities, and top contributing features. Powered by XGBoost model trained on 20 features from order flow, volatility, momentum, and derivatives data.',
+                parameters: TOOL_PARAMS.get_regime,
+                execute: async (_id, params) => jsonResult(await getRegimeTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_signals',
+                label: 'Get Trading Signals',
+                description: 'Get active trading signals from the intelligence engine. Returns strategy snapshots with confluence scores (how many conditions are met), entry zones, stop losses, price targets, and recent signal history. Three strategies: trend_continuation, liquidity_sweep, funding_reversion — each gated by regime classification.',
+                parameters: TOOL_PARAMS.get_signals,
+                execute: async (_id, params) => jsonResult(await getSignalsTool(params, getSignalsDeps)),
+            },
+            {
+                name: 'get_analytics',
+                label: 'Get Edge Analytics',
+                description: 'Get strategy performance analytics: per-strategy win rate (rolling 20/50/all), expectancy, profit factor, Sharpe ratio, avg hold duration, regime breakdown, equity curve with drawdown, and degradation alerts. Strategies with negative rolling-20 expectancy are auto-gated.',
+                parameters: TOOL_PARAMS.get_analytics,
+                execute: async (_id, params) => jsonResult(await getAnalyticsTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_orderbook',
+                label: 'Get Order Book',
+                description: 'Fetch L2 order book depth from Binance. Returns top N bid/ask levels with prices and quantities, plus computed metrics: spread (absolute + bps), mid-price, bid/ask volume totals, and order book imbalance ratio (positive = bid-heavy / bullish, negative = ask-heavy / bearish). Uses real Binance data.',
+                parameters: TOOL_PARAMS.get_orderbook,
+                execute: async (_id, params) => jsonResult(await getOrderbookTool(params, simDeps)),
+            },
+            {
+                name: 'get_volume_profile',
+                label: 'Get Volume Profile',
+                description: 'Get volume-at-price profile from the intelligence engine. Returns price buckets with buy/sell volume split, Point of Control (POC — highest volume level), Value Area High/Low (70% of volume), current price, and total volume. Use to identify key support/resistance and high-volume nodes.',
+                parameters: TOOL_PARAMS.get_volume_profile,
+                execute: async (_id, params) => jsonResult(await getVolumeProfileTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_liquidation_levels',
+                label: 'Get Liquidation Levels',
+                description: 'Get liquidation levels from the intelligence engine. Returns historical liquidation clusters (where liquidations actually happened) and estimated liquidation levels based on open interest and leverage tiers (5x/10x/25x/50x/100x). Shows price levels where cascading liquidations could accelerate moves. Use for risk assessment and stop placement.',
+                parameters: TOOL_PARAMS.get_liquidation_levels,
+                execute: async (_id, params) => jsonResult(await getLiquidationLevelsTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_trade_feedback',
+                label: 'Get Trade Feedback',
+                description: 'Get structured performance feedback: per-setup-type win rates (rolling 20 + all-time) and verdicts (STRONG/WORKING/MARGINAL/FAILING) with edge trend detection (improving/stable/declining), per-regime recommendations (best setup type per regime with stats), current streak, last 10 trade outcomes, and overall stats. Use before entering trades to check if your current setup type is working in the current regime. Tag your trades with setup types for better tracking.',
+                parameters: TOOL_PARAMS.get_trade_feedback,
+                execute: async (_id, params) => jsonResult(await getTradeFeedbackTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_trade_flow',
+                label: 'Get Trade Flow',
+                description: 'Get aggregated trade flow / institutional flow data. Returns buy/sell volume, large trade (>$50k whale) activity, net delta, buy/sell ratio, per-minute breakdown, and whale pressure verdict (strong_buy/buy/neutral/sell/strong_sell). Use before entering trades to confirm whether institutional flow supports your direction. Large trade ratio >15% with matching direction = strong institutional confirmation.',
+                parameters: TOOL_PARAMS.get_trade_flow,
+                execute: async (_id, params) => jsonResult(await getTradeFlowTool(params, intelApiDeps)),
+            },
+            {
+                name: 'score_setup',
+                label: 'Score Setup',
+                description: 'Pre-trade setup scorecard. Scores a proposed trade across 5 dimensions: risk/reward ratio, regime alignment, regime confidence, setup edge (from your track record), and institutional flow alignment. Returns a composite score (0-10) and verdict (STRONG_GO/GO/MARGINAL/NO_GO) with specific flags and a recommendation. Use this BEFORE every trade entry to enforce quality filters. NO_GO means do not trade.',
+                parameters: TOOL_PARAMS.score_setup,
+                execute: async (_id, params) => jsonResult(await scoreSetupTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_sizing',
+                label: 'Get Position Sizing',
+                description: 'Get recommended position size using Half-Kelly formula with volatility adjustment. Returns sizePct (fraction of account to risk), Kelly fraction, current win rate, avg win/loss ratio, volatility adjustment factor, and capping reason. Use this before sizing trades — multiply sizePct by your account equity to get the dollar risk amount.',
+                parameters: TOOL_PARAMS.get_sizing,
+                execute: async (_id, params) => jsonResult(await getSizingTool(params, intelApiDeps)),
+            },
+            {
+                name: 'check_position_health',
+                label: 'Check Position Health',
+                description: 'Real-time position health monitor. For each position, computes: P&L in dollars/percent/R-multiples, distance to stop (% and R), stop status (SAFE/CLOSE/CRITICAL/BREACHED), distance to target, heat (position risk as % of account), time in trade with staleness detection. Returns per-position alerts and portfolio-level heat assessment (LOW/MODERATE/ELEVATED/HIGH/CRITICAL). Use on every heartbeat to monitor open positions. Alerts when stops are close, positions are stale, or heat is too high.',
+                parameters: TOOL_PARAMS.check_position_health,
+                execute: async (_id, params) => jsonResult(checkPositionHealthTool(params)),
+            },
+            {
+                name: 'get_risk_scenario',
+                label: 'Get Risk Scenario',
+                description: 'Stress test your positions against hypothetical price moves. Shows what happens to your P&L, heat score, and risk limits if price drops 3%, dumps 5%, or rallies 5%. Auto-generates scenarios from current ATR volatility if no specific moves provided. Flags which stops would trigger and which risk limits would breach. Use BEFORE entering trades to understand downside, and while holding positions to prepare for adverse moves.',
+                parameters: TOOL_PARAMS.get_risk_scenario,
+                execute: async (_id, params) => {
+                    if (!runtime.adapter.isLive)
+                        reloadState();
+                    const state = simulator.getState();
+                    return jsonResult(await getRiskScenarioTool(params, {
+                        getPositions: () => state.positions,
+                        getWallet: () => state.wallet,
+                        getLastPrice: (sym) => simulator.getLastTicker(sym)?.last ?? null,
+                        intelApiDeps,
+                    }));
+                },
+            },
+            {
+                name: 'get_session_review',
+                label: 'Get Session Review',
+                description: 'Automated end-of-session performance summary. Returns trade count, win/loss breakdown, net P&L, best/worst trades, per-setup-type stats, per-regime stats, session-over-session comparison (improving/stable/declining), and actionable lessons ("3/4 losses in RANGE_WIDE — sit out ranging markets"). Use at end of every trading session to log learnings to memory.',
+                parameters: TOOL_PARAMS.get_session_review,
+                execute: async (_id, params) => jsonResult(await getSessionReviewTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_backtest',
+                label: 'Get Backtest',
+                description: 'Backtest a trading strategy against historical data. Runs walk-forward simulation over specified months of history with realistic fills, fees, and stop management. Returns win rate, expectancy, Sharpe ratio, max drawdown, per-strategy and per-regime breakdown, best/worst trades, and a one-line verdict. Use in Step 2 (REVIEW) before trading a strategy, and when entering a new regime to check historical performance. Async job model: the tool queues a job on the intel service and polls every 5s; the call returns ONLY when the job completes (or hits the cap). Just call it and wait — DO NOT roll your own bash/curl wrapper. Measured wall-clock on 1h timeframe (BTCUSDT, 2026-05-15): ~3min/6mo, ~5-6min/12mo, ~10-12min/24mo, ~15-20min/36mo. Single-call cap is 30min (server-side worker timeout). For longer ranges (60-72mo) call this tool multiple times with non-overlapping 12-month windows via the `months` arg — stitch per-window expectancy/win-rate/regime-breakdown manually (Sharpe/maxDD/equity-curve continuity does NOT survive splitting). Identical inputs hit a 1-hour result cache, so repeat calls return instantly.',
+                parameters: TOOL_PARAMS.get_backtest,
+                execute: async (_id, params) => jsonResult(await getBacktestTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_pattern_scan',
+                label: 'Get Pattern Scan',
+                description: 'Scan chart for patterns: swing points, trendlines, and 10 pattern types (HH/HL, LH/LL, double top/bottom, head & shoulders, inverse H&S, bull/bear flag, ascending/descending channel). Returns detected patterns with confidence scores, key price levels, and descriptions. Use in Step 3 (SCAN) alongside signals for structural context. The agent applies judgment on top of algorithmic candidates — not all detected patterns are tradeable.',
+                parameters: TOOL_PARAMS.get_pattern_scan,
+                execute: async (_id, params) => jsonResult(await getPatternScanTool(params, intelApiDeps)),
+            },
+            {
+                name: 'save_strategy',
+                label: 'Save Strategy',
+                description: 'Save a new trading strategy to the Strategy Box, or update an existing one. 23 available conditions: ema_proximity, orderbook_imbalance, funding_not_crowded, oi_slope, no_liquidation_cluster, price_sweep, liquidations_at_sweep, order_flow_absorption, funding_contrarian, funding_extreme, oi_elevated, price_at_level, macd_crossover, macd_divergence, bollinger_squeeze, bollinger_breakout, vwap_position, stoch_rsi_extreme, adx_trending, adx_ranging, ichimoku_cloud, obv_divergence, supertrend_direction. After saving, backtest it with get_backtest to validate before activating.',
+                parameters: TOOL_PARAMS.save_strategy,
+                execute: async (_id, params) => jsonResult(await saveStrategyTool(params, intelApiDeps)),
+            },
+            {
+                name: 'list_strategies',
+                label: 'List Strategies',
+                description: 'List all strategies in the Strategy Box. Shows name, description, regime whitelist, conditions, active status, and whether it is a built-in strategy. Use to see which strategies are available for backtesting and live trading.',
+                parameters: TOOL_PARAMS.list_strategies,
+                execute: async (_id, params) => jsonResult(await listStrategiesTool(params ?? {}, intelApiDeps)),
+            },
+            {
+                name: 'toggle_strategy',
+                label: 'Toggle Strategy',
+                description: 'Activate or deactivate a strategy. Deactivated strategies are excluded from live signal evaluation but can still be backtested. Use to temporarily disable an underperforming strategy without deleting it.',
+                parameters: TOOL_PARAMS.toggle_strategy,
+                execute: async (_id, params) => jsonResult(await toggleStrategyTool(params, intelApiDeps)),
+            },
+            {
+                name: 'scan_pairs',
+                label: 'Scan Pairs',
+                description: 'Scan all monitored pairs for strategy setups. Evaluates your active strategies against pre-computed market facts (indicators + conditions) for each symbol. Returns ranked setups by confluence score. Use this FIRST in Step 3 (SCAN) instead of calling per-pair tools individually — covers the whole universe in one compact call (~300 tokens) instead of thousands of tokens drilling in per pair. Follow up with get_setup_detail on the top-ranked pair. Setups whose (setup_type, regime) match one of your confirmed entry-time learnings appear under `vetoed_setups` instead of `rankings` — each carries the matching learning\'s directive inline so you can apply override conditions if the directive allows. Don\'t waste a drill-in on a vetoed setup unless the override conditions are clearly satisfied.',
+                parameters: TOOL_PARAMS.scan_pairs,
+                execute: async (_id, params) => jsonResult(await scanPairsTool(params ?? {}, intelApiDeps, {
+                    decisionsClient: positionDecisionsClient,
+                    userId: positionDecisionsUserId,
+                })),
+            },
+            {
+                name: 'get_setup_detail',
+                label: 'Get Setup Detail',
+                description: 'Get detailed trade setup for a specific symbol. Returns entry price, stop level, R-multiple targets, full indicator snapshot, and risk flags. Use AFTER scan_pairs identifies a top-ranked pair — this provides the precision data needed to make a go/no-go decision.',
+                parameters: TOOL_PARAMS.get_setup_detail,
+                execute: async (_id, params) => jsonResult(await getSetupDetailTool(params, intelApiDeps)),
+            },
+            // ---- Autonomous Learning Tools ----
+            {
+                name: 'query_trades',
+                label: 'Query Trades',
+                description: 'Flexible trade history query. Filter by symbol, setup_type, regime, direction, outcome, duration, P&L range, confluence score, and feature_snapshot values (e.g. ADX > 40). Use group_by for aggregated stats (win_rate, expectancy per group). This is your primary tool for discovering patterns in your own performance — ask any question about your trade history.',
+                parameters: TOOL_PARAMS.query_trades,
+                execute: async (_id, params) => jsonResult(await queryTradesTool(params ?? {}, intelApiDeps)),
+            },
+            {
+                name: 'get_agent_profile',
+                label: 'Get Agent Profile',
+                description: 'Returns your earned autonomy tier (novice/apprentice/journeyman/master) and permissions. Tier is based on your trade count, win rate, expectancy, and Sharpe ratio. Higher tiers unlock more latitude to adjust thresholds, create strategies, and override soft rules. Check this at session start.',
+                parameters: TOOL_PARAMS.get_agent_profile,
+                execute: async () => jsonResult(await getAgentProfileTool(intelApiDeps)),
+            },
+            // ---- Market Breadth & CVD Tools ----
+            {
+                name: 'get_cvd',
+                label: 'Get CVD Analysis',
+                description: 'Get Cumulative Volume Delta (CVD) analysis — buy/sell pressure, slope (5m and 1h), price-CVD divergence detection, z-score exhaustion, and accumulation state. CVD rises when buyers are aggressive (lifting asks), falls when sellers hit bids. Divergence between price and CVD is a leading reversal signal. Use alongside get_trade_flow for complete order flow picture.',
+                parameters: TOOL_PARAMS.get_cvd,
+                execute: async (_id, params) => jsonResult(await getCvdTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_market_breadth',
+                label: 'Get Market Breadth',
+                description: 'Cross-pair correlation and market breadth across all monitored symbols. Returns: per-pair momentum (1h/4h/24h returns), advance/decline ratios, BTC correlation per pair, strongest/weakest performers, and whether alts are confirming BTC\'s move. Use BEFORE entering any trade to check if the broader market supports your direction. If BTC dumps but alts hold = weak dump. If everything dumps together = conviction selloff.',
+                parameters: TOOL_PARAMS.get_market_breadth,
+                execute: async (_id, params) => jsonResult(await getMarketBreadthTool(params ?? {}, intelApiDeps)),
+            },
+            {
+                name: 'get_basis',
+                label: 'Get Spot-Futures Basis',
+                description: 'Spot-futures basis (mark-spot premium) analysis. Returns current premium/discount in bps, funding rate alignment, annualized carry, historical basis over lookback window, and dislocation detection. Positive basis = futures premium (longs paying). Negative = discount (shorts paying). When basis and funding diverge = dislocation signal. Extreme basis (>2 std dev) = mean reversion likely. Use alongside get_crypto_metrics for complete derivatives picture.',
+                parameters: TOOL_PARAMS.get_basis,
+                execute: async (_id, params) => jsonResult(await getBasisTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_cascade_risk',
+                label: 'Get Cascade Risk',
+                description: 'Liquidation cascade risk assessment. Returns: nearest liquidation clusters above/below current price, cascade zones with estimated price impact if triggered, recent liquidation activity (1h/4h), active cascade detection, and overall risk score (0-100). A cascade happens when liquidations push price into more liquidation levels, creating a chain reaction. Use BEFORE entering trades to avoid shorting into a short-squeeze zone or longing above a long-liquidation cliff. High risk score = stay flat or trade the opposite direction.',
+                parameters: TOOL_PARAMS.get_cascade_risk,
+                execute: async (_id, params) => jsonResult(await getCascadeRiskTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_sentiment',
+                label: 'Get Market Sentiment',
+                description: 'Free market sentiment data — no Pro required. Returns: Fear & Greed Index (0-100 with contrarian signal), BTC dominance %, total crypto market cap, 24h volume, and market cap change %. Fear <=25 = contrarian buy, Greed >=75 = contrarian sell. BTC dominance >60% = risk-off/alt weakness, <45% = alt season. Use at session start and before major decisions for macro context.',
+                parameters: TOOL_PARAMS.get_sentiment,
+                execute: async () => jsonResult(await getSentimentTool({}, intelApiDeps)),
+            },
+            {
+                name: 'get_divergences',
+                label: 'Get Divergence Scan',
+                description: 'Multi-timeframe RSI & MACD divergence scanner across 15m/1h/4h/1d. Detects when price makes new highs/lows but RSI or MACD histogram does not confirm — a leading reversal signal. Returns: all detected divergences with strength scores, per-timeframe indicator summary, multi-TF confirmation flag, and consensus direction. Bullish divergence (price lower low + RSI higher low) = selling exhaustion. Bearish divergence (price higher high + RSI lower high) = buying exhaustion. Multi-TF confirmed divergences are highest conviction.',
+                parameters: TOOL_PARAMS.get_divergences,
+                execute: async (_id, params) => jsonResult(await getDivergencesTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_liquidation_pulse',
+                label: 'Get Liquidation Pulse',
+                description: 'Sub-second cross-market liquidation pulse from Binance `!forceOrder@arr`. Returns a classification (quiet | elevated | active_cascade) over a rolling 60s window (configurable 5-300s), USD notional liquidated long-side vs short-side, dominant side (long/short/balanced), event count, and the 5 largest events. With no `symbol` argument, returns the cross-majors aggregate (BTC+ETH+BNB+SOL+XRP) — useful for detecting market-wide stress that leads correlated alt moves. With `symbol`, returns that symbol\'s pulse. ACTIVE_CASCADE = sustained liquidation chain in progress; pause new entries on the dominant side. Returns `{enabled: false}` when the operator has not enabled this feature.',
+                parameters: TOOL_PARAMS.get_liquidation_pulse,
+                execute: async (_id, params) => jsonResult(await getLiquidationPulseTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_resting_liquidity',
+                label: 'Get Resting Liquidity',
+                description: 'Banded resting limit-order liquidity for a symbol. Returns USD notional resting on bid + ask sides at four cumulative bands (0.2 / 0.5 / 1.0 / 1.5 % from mid) plus `coverage_pct` (the % range depth-20 actually reaches — < 1.5 means depth-20 is too shallow on this symbol). Use to size entries against where the book actually sits: a thin book on your side = expect slippage; a thick book on the opposite side = potential resistance/support level. Returns `{enabled: false}` when the operator has not enabled this feature.',
+                parameters: TOOL_PARAMS.get_resting_liquidity,
+                execute: async (_id, params) => jsonResult(await getRestingLiquidityTool(params, intelApiDeps)),
+            },
+            {
+                name: 'get_funding_context',
+                label: 'Get Funding Context',
+                description: '30-day funding-rate percentile context for a symbol. Returns the latest funding rate, the p10 / p50 / p90 of the last 30 days, and `percentileRank` 0..1 — where the current rate sits in that distribution. Use to gauge crowded positioning: rank > 0.90 = funding in top decile (crowded longs paying shorts; new LONG entries face top-tick risk), rank < 0.10 = bottom decile (crowded shorts paying longs; new SHORT entries face squeeze risk). Per-symbol adaptive: BTC/BNB tight ranges and DOT/WIF heavy tails both get sensible cutoffs. Returns `{enabled: false}` when the operator has not enabled this feature or the symbol has < 100 30d samples.',
+                parameters: TOOL_PARAMS.get_funding_context,
+                execute: async (_id, params) => jsonResult(await getFundingContextTool(params, intelApiDeps)),
+            },
+            // ---- Operator-only onboarding tools ----
+            // The skill forwards these from the dashboard's Settings page. The
+            // agent should NOT call them — PR2 enforces that via an operator-only
+            // scope gate in the skill layer. These are intentionally excluded from
+            // SKILL.md so the LLM never sees them in its tool list.
+            {
+                name: 'set_exchange_credentials',
+                label: 'Set Exchange Credentials',
+                description: 'Operator-only. Store Binance API key + secret in ~/.reefclaw/plugin-config.json. If current mode is live, reconnects the adapter. Never called by the agent.',
+                parameters: TOOL_PARAMS.set_exchange_credentials,
+                execute: async (_id, params) => jsonResult(await setExchangeCredentialsTool(params, { runtime, adapterDeps })),
+            },
+            {
+                name: 'set_trading_mode',
+                label: 'Set Trading Mode',
+                description: 'Operator-only. Move the plugin between PAPER / MICRO_LIVE / LIVE. Enforces the one-rung-at-a-time ladder. Never called by the agent.',
+                parameters: TOOL_PARAMS.set_trading_mode,
+                execute: async (_id, params) => jsonResult(await setTradingModeTool(params, { runtime, adapterDeps })),
+            },
+            {
+                name: 'test_exchange_credentials',
+                label: 'Test Exchange Credentials',
+                description: 'Operator-only. Verify a Binance API key + secret with a read-only call (fetchBalance) without persisting anything. Used by the dashboard pre-flight check before set_exchange_credentials. Never called by the agent.',
+                parameters: TOOL_PARAMS.test_exchange_credentials,
+                execute: async (_id, params) => jsonResult(await testExchangeCredentialsTool(params)),
+            },
+            {
+                name: 'clear_exchange_credentials',
+                label: 'Clear Exchange Credentials',
+                description: 'Operator-only. Remove stored Binance credentials from plugin-config.json and de-escalate to PAPER mode if currently running in MICRO_LIVE/LIVE. Requires {confirm: true}. Never called by the agent.',
+                parameters: TOOL_PARAMS.clear_exchange_credentials,
+                execute: async (_id, params) => jsonResult(await clearExchangeCredentialsTool(params, { runtime, adapterDeps })),
+            },
+            {
+                name: 'get_bracket_config',
+                label: 'Get Bracket Config',
+                description: 'Operator-only. Returns the current bracket-orders configuration (mode + requireStopLoss + requireTakeProfit). Used by the dashboard Trading Parameters panel.',
+                parameters: TOOL_PARAMS.get_bracket_config,
+                execute: async () => jsonResult(getBracketConfigTool({})),
+            },
+            {
+                name: 'set_bracket_requirement',
+                label: 'Set Bracket Requirement',
+                description: 'Operator-only. Flip requireStopLoss or requireTakeProfit in plugin-config. Returns a warning copy when a flag is disabled so the dashboard can render the confirmation banner. Never called by the agent.',
+                parameters: TOOL_PARAMS.set_bracket_requirement,
+                execute: async (_id, params) => jsonResult(setBracketRequirementTool(params)),
+            },
+        ];
+        // ---- Tool gate (central per-user config, slice 1) ----
+        // Wrap EVERY tool's execute with the ToolGate check — the one dispatch
+        // choke point. The wrapper reads the gate's live state per call, so a
+        // config change hot-applies on the next invocation (no re-registration,
+        // no restart). Safety floor: UNGOVERNABLE_TOOLS (core + operator names)
+        // is hardcoded in tool-gate.ts and checked before the disabled set — a
+        // config blob can never strip close_position/attach_brackets/etc.
+        // Kill-switch: RC_TOOL_GATE=off. See docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5f.
+        const toolGate = new ToolGate();
+        const gatedTools = tools.map((t) => toolGate.wrapTool(t, jsonResult));
+        // Poll the central config (boot + every ~60s), keyed by the same rc_
+        // token the ingest paths use (plugin-config connectionToken →
+        // WEBAPP_INGEST_TOKEN env fallback). No token → poller no-ops → gate
+        // stays empty → all tools enabled (byte-identical to pre-feature).
+        // gateStore carries centrally-delivered operational gates (slice 2:
+        // exitGate) — loadExitGateMode() consults it before the local file;
+        // kill-switch RC_CENTRAL_GATES=off. See config/gate-store.ts.
+        startAgentConfigPoller({
+            gate: toolGate,
+            gateStore,
+            apiBaseUrl,
+            token: resolveIngestToken({ connectionToken }),
+        });
+        // Register all tools with OpenClaw
+        const toolNames = gatedTools.map(t => t.name);
+        // OpenClaw 2026.6+ SILENTLY DROPS any registered tool not declared in
+        // openclaw.plugin.json `contracts.tools` (diagnostic-only error, tools
+        // just vanish from the agent). The manifest ships next to index.js in the
+        // installed layout — cross-check at register time so drift is loud in the
+        // journal instead of surfacing as "agent can't trade". Fail-soft: some
+        // deploy layouts don't ship the manifest (prod pre-dates it) — skip then.
+        try {
+            const manifestPath = join(dirname(fileURLToPath(import.meta.url)), 'openclaw.plugin.json');
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            const declared = new Set(manifest.contracts?.tools ?? []);
+            if (declared.size > 0) {
+                const undeclared = toolNames.filter((n) => !declared.has(n));
+                if (undeclared.length > 0) {
+                    logger.error(TAG, `openclaw.plugin.json contracts.tools is missing ${undeclared.length} registered tool(s) — OpenClaw 2026.6+ will silently drop them: ${undeclared.join(', ')}. Add them to plugin/openclaw.plugin.json.`);
+                }
+            }
+        }
+        catch {
+            // Manifest not shipped alongside dist (legacy deploy layout) — skip.
+        }
+        const toolsFactory = () => gatedTools;
+        api.registerTool(toolsFactory, { names: toolNames });
+        // Cache factory + names on the module singleton so repeat register()
+        // calls can re-register without spinning up duplicate adapters (the
+        // factory closes over the already-wrapped tools — idempotent).
+        pluginToolsFactory = toolsFactory;
+        pluginToolNames = toolNames;
+        pluginInitialised = true;
+        logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
+        maybeStartConnectorSupervisor();
+    },
+};
+/** Plugin-supervised connector (frictionless onboarding): when plugin-config
+ *  says connectorSupervisor='on' (written by the npx installer on fresh
+ *  installs — NEVER defaulted on, prod runs the bridge under systemd and
+ *  would double-connect the relay room), the plugin spawns + restarts the
+ *  relay connector as a child of the gateway process. OpenClaw is the process
+ *  manager: no systemd, works in containers, dies with the gateway.
+ *  Kill-switch: RC_CONNECTOR_SUPERVISOR=off. Called from EVERY register()
+ *  path (config may appear between calls); the supervisor itself is a
+ *  singleton so repeat calls no-op. */
+function maybeStartConnectorSupervisor() {
+    try {
+        const supervisorMode = readPluginConfig().connectorSupervisor;
+        if (process.env.RC_CONNECTOR_SUPERVISOR === 'off') {
+            if (supervisorMode === 'on')
+                logger.warn(TAG, 'connector supervisor disabled by RC_CONNECTOR_SUPERVISOR=off');
+            return;
+        }
+        if (supervisorMode === 'off')
+            return;
+        // 'on' → explicit opt-in (the npx installer writes this).
+        // undefined → auto-start ONLY when the connector is bundled inside this
+        // plugin package (the npm-channel @reefclaw/openclaw-plugin distribution
+        // is self-contained by design). Prod's linked plugin dir has no bundled
+        // bridge and no flag → stays off; systemd keeps owning prod's bridge.
+        if (supervisorMode === 'on' || hasBundledBridge()) {
+            startConnectorSupervisor();
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `connector supervisor init failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export default paperTradingPlugin;