@reefclaw/openclaw-plugin 0.1.13 → 0.1.15

package/live/approval-lifecycle.js

@@ -0,0 +1,80 @@
+// Approval-listener lifecycle — follows adapter swaps instead of boot state
+// (audit 2026-07-26 F10).
+//
+// The ProposalDecisionListener used to start ONCE at boot, only when the
+// process booted live with approval.mode='per_trade'. Every real trader
+// onboards in PAPER and goes live later from the dashboard, so on their box
+// the listener never existed — approvals would sit unfired. Worse, the
+// listener held the adapter it was CONSTRUCTED with: a live→PAPER flip left
+// it wired to the orphaned live adapter (an operator approval would fire a
+// real exchange order while the dashboard said PAPER), and a credential swap
+// left it firing through the stopped old adapter.
+//
+// This class owns exactly one listener at a time and is driven by
+// PluginRuntime.onAdapterSwapped (boot calls it once with the boot adapter):
+//   - live adapter + approval.mode='per_trade' (re-read at swap time) → a
+//     fresh listener bound to THAT adapter;
+//   - anything else → no listener (stopping any previous one first, awaiting
+//     its in-flight tick so a fire's result PATCH lands before teardown).
+//
+// Swaps are serialized through a promise chain: a second swap arriving while
+// the first is still draining queues behind it, so two listeners can never
+// run concurrently (the DB fire-claim makes a double-fire impossible anyway —
+// this keeps the process tidy, not the money safe).
+import { logger, formatError } from '../logger.js';
+const TAG = 'approval-lifecycle';
+export class ApprovalListenerLifecycle {
+    deps;
+    listener;
+    chain = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get active() {
+        return this.listener !== undefined;
+    }
+    /** Apply the lifecycle for a freshly published adapter. Serialized. */
+    onAdapterSwapped(adapter) {
+        this.chain = this.chain
+            .then(() => this.apply(adapter))
+            .catch((err) => {
+            logger.error(TAG, `listener swap failed: ${formatError(err)}`);
+        });
+        return this.chain;
+    }
+    /** Terminal stop (shutdown drain) — also serialized behind pending swaps. */
+    stop() {
+        this.chain = this.chain
+            .then(() => this.stopCurrent())
+            .catch((err) => {
+            logger.warn(TAG, `listener stop failed: ${formatError(err)}`);
+        });
+        return this.chain;
+    }
+    async apply(adapter) {
+        // Always tear down the previous listener first — it is bound to the OLD
+        // adapter and must never fire through it again.
+        await this.stopCurrent();
+        if (!adapter.isLive)
+            return;
+        const mode = this.deps.resolveApprovalMode();
+        if (mode !== 'per_trade')
+            return;
+        if (!this.deps.hasWiring()) {
+            logger.warn(TAG, "approval.mode='per_trade' but ingest credentials/proposal manager missing — listener NOT started; approvals will not fire");
+            return;
+        }
+        const fresh = this.deps.buildListener(adapter);
+        fresh.start();
+        this.listener = fresh;
+        logger.info(TAG, 'ProposalDecisionListener started (bound to the current adapter)');
+    }
+    async stopCurrent() {
+        if (!this.listener)
+            return;
+        const old = this.listener;
+        this.listener = undefined;
+        await old.stop();
+        logger.info(TAG, 'ProposalDecisionListener stopped');
+    }
+}

package/live/bracket-types.d.ts

@@ -20,6 +20,15 @@ export interface BracketLedgerEntry {
     symbol: string;
     entrySide: 'buy' | 'sell';
     entryCid: string;
+    /** Additional entry clientOrderIds submitted against this SAME bracket row —
+     *  a scale-in, or a second entry placed while the first is still resting.
+     *  Each order gets a fresh cloid but the row keeps the original `entryCid`,
+     *  so a fill matcher keyed on `entryCid` alone would ignore their fills
+     *  entirely (audit 2026-07-26 F5). HL-only today: Binance legs are
+     *  `closePosition:true` (whole-position, self-resizing), while HL legs are
+     *  FIXED SIZE — an unmatched scale-in fill there means NAKED contracts.
+     *  Bounded; oldest dropped. */
+    extraEntryCids?: string[];
     slCid?: string;
     tpCid?: string;
     stopPrice?: number;

package/live/live-adapter.d.ts

@@ -85,7 +85,6 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
     getSessionStartNav(): number | null;
     constructor(config: ExchangeConfig, mode: 'MICRO_LIVE' | 'LIVE', microLiveConfig?: {
-        sizeCapPercent?: number;
         maxPositionUSDT?: number;
     }, bracketMode?: BracketMode, userDataStreamMode?: UserDataStreamMode, userDataStreamTunables?: UserDataStreamTunables, 
     /** TRADE_AUDIT_TRAIL_PLAN Phase 1 — optional audit-trail wiring.  Wired

package/live/user-data-stream.js

@@ -297,8 +297,16 @@ export class UserDataStream extends EventEmitter {
                             // Capped to avoid flooding the journal under heavy bracket
                             // traffic. Operators read these first-N samples once after
                             // deploy to verify the parser matches Binance's actual shape.
-                            logger.info(TAG, `ALGO_UPDATE raw (${this.algoUpdateRawLogged + 1}/` +
-                                `${UserDataStream.ALGO_UPDATE_RAW_LOG_CAP}): ${JSON.stringify(obj)}`);
+                            // Raw account payloads (order ids, prices, quantities) only
+                            // reach the journal behind an explicit opt-in — by default we
+                            // log the parser-relevant SHAPE (field names), which is what
+                            // shape-drift verification actually needs.
+                            const raw = process.env.RC_LOG_RAW_WS === 'on';
+                            const shape = raw
+                                ? JSON.stringify(obj)
+                                : `keys=[${Object.keys(obj).join(',')}] event.keys=[${Object.keys(obj.o ?? {}).join(',')}]`;
+                            logger.info(TAG, `ALGO_UPDATE ${raw ? 'raw' : 'shape'} (${this.algoUpdateRawLogged + 1}/` +
+                                `${UserDataStream.ALGO_UPDATE_RAW_LOG_CAP}): ${shape}`);
                             this.algoUpdateRawLogged++;
                         }
                         this.emit('algoUpdate', ev);

package/onboarding/runtime.d.ts

@@ -3,14 +3,31 @@ import type { ExchangeConfig, TradingMode } from '../types.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { PaperMarketFeed } from '../simulator/paper-market-feed.js';
 import { LiveAdapter } from '../live/live-adapter.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
 import type { HlCredentials } from '../venues/hyperliquid/hl-private.js';
 import { type VenueId } from '../venues/registry.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
+import type { TradeStoreClient } from '../ingest/trade-store-client.js';
+import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
 import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export interface MicroLiveConfig {
-    sizeCapPercent?: number;
     maxPositionUSDT?: number;
 }
+/** Boot-constructed live wiring reapplied to EVERY adapter build (audit
+ *  2026-07-26 F9). Reconnects previously rebuilt adapters with only the
+ *  bracket mode — silently reverting WS authority to REST, dropping the
+ *  audit-trail ingest, and losing journal auto-capture until restart. The
+ *  clients live for the process lifetime (the SIGTERM drain holds them), so
+ *  rebuilds must REUSE them, never re-instantiate. */
+export interface LiveAdapterWiring {
+    /** Base of TradeIngestWiring — `exchange` is stamped per build from the
+     *  TARGET venue (fillExchangeId), because a venue flip changes it. */
+    tradeIngestBase?: {
+        client: TradeStoreClient;
+        userId: string;
+    };
+    autoCapture?: AutoCaptureContext;
+}
 export interface BuildAdapterInput {
     mode: TradingMode;
     exchange: ExchangeConfig | null;
@@ -24,6 +41,8 @@ export interface BuildAdapterInput {
     venue?: VenueId;
     /** Required for a live-mode build on the hyperliquid venue. */
     hlCredentials?: HlCredentials | null;
+    /** Boot wiring reapplied on every build — see LiveAdapterWiring (F9). */
+    wiring?: LiveAdapterWiring;
 }
 /** Wave 9 safety wiring is created only after its durable ledger is loaded.
  *  Runtime reapplies these hooks to both the bootstrap objects and every
@@ -62,6 +81,17 @@ export declare class PluginRuntime {
      *  for watcher closes (issue #199) — without it, a live<->paper reconnect
      *  would silently shed the capture wiring. */
     private readonly onWatcherCreated?;
+    /** Observer applied to EVERY live adapter this runtime creates (audit F9,
+     *  same pattern as onWatcherCreated). index.ts uses it to install the
+     *  drift_detected → journal close-bypass cleanup listener — previously
+     *  installed only on the BOOT adapter and lost on every reconnect. */
+    private readonly onAdapterCreated?;
+    /** Boot live wiring threaded into every buildAdapter call (audit F9). */
+    private readonly liveWiring?;
+    /** Fired after EVERY reconnect publishes its adapter (paper ones included) —
+     *  set post-construction because its consumer (the approval-listener
+     *  lifecycle, audit F10) is built after the runtime. */
+    private onAdapterSwapped?;
     /** Reconnect is serialized — a second caller waits for the first to finish
      *  so we never tear down an adapter that's mid-rebuild. */
     private reconnectInFlight;
@@ -73,11 +103,14 @@ export declare class PluginRuntime {
         marketFeed?: PaperMarketFeed | null;
         operationLock?: TradingOperationLock;
         onWatcherCreated?: (watcher: PositionWatcher) => void;
+        onAdapterCreated?: (adapter: LiveAdapter | HyperliquidLiveAdapter) => void;
+        liveWiring?: LiveAdapterWiring;
     });
     get adapter(): IExchangeAdapter;
     get mode(): TradingMode;
     get stopWatcher(): PositionWatcher | null;
     get marketFeed(): PaperMarketFeed | null;
+    setOnAdapterSwapped(cb?: (adapter: IExchangeAdapter) => void): void;
     setWave9LiveLifecycleHooks(hooks?: Wave9LiveLifecycleHooks): void;
     /**
      * Swap the current adapter for a new one built from `next`. The old

package/onboarding/runtime.js

@@ -14,10 +14,11 @@
 import { PaperAdapter } from '../paper-adapter.js';
 import { LiveAdapter } from '../live/live-adapter.js';
 import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
-import { createLiveAdapter } from '../venues/registry.js';
+import { createLiveAdapter, fillExchangeId } from '../venues/registry.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
 import { loadBracketMode } from '../config/brackets-config.js';
-import { loadStopWatcherIntervalMs, readPluginConfig } from '../config/plugin-config-io.js';
+import { loadMicroLiveConfig, loadStopWatcherIntervalMs, readPluginConfig } from '../config/plugin-config-io.js';
+import { loadUserDataStreamMode, loadUserDataStreamTunables } from '../config/user-data-stream-config.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'plugin-runtime';
 /** Pure-ish factory: builds an adapter for the requested mode.
@@ -25,12 +26,27 @@ const TAG = 'plugin-runtime';
  *  callers should pre-validate via `modeRequiresCredentials`, but this
  *  defense-in-depth prevents a crash if validation is bypassed. */
 export function buildAdapter(input) {
-    const { mode, exchange, microLive, simulator } = input;
+    const { mode, exchange, simulator } = input;
     if (mode === 'PAPER' || mode === 'SHADOW') {
         // Shadow mode uses a paper adapter for execution; the separate
         // ShadowTracker wraps a BinancePrivateApi for real-balance comparison.
         return new PaperAdapter(simulator);
     }
+    // Micro-live cap resolves from plugin-config at adapter build time when the
+    // caller didn't pass one — every reconnect path (mode flip, credential save)
+    // used to omit it, silently resetting an operator-raised OR -lowered cap
+    // back to the $50 default (audit 2026-07-26 F8).
+    const microLive = input.microLive ?? loadMicroLiveConfig();
+    // Audit-trail ingest (F9): reuse the boot-constructed client, stamp the
+    // exchange id from the TARGET venue (a venue flip changes it; the id is
+    // half of the trades idempotency key and must never be stale or minted).
+    const tradeIngest = input.wiring?.tradeIngestBase
+        ? {
+            client: input.wiring.tradeIngestBase.client,
+            userId: input.wiring.tradeIngestBase.userId,
+            exchange: fillExchangeId(input.venue ?? 'binance'),
+        }
+        : undefined;
     // Hyperliquid live (issue #217): mirror the boot path's construction —
     // per-venue credential shape, the SAME factory (createLiveAdapter), and
     // the same fall-back-to-paper defense when credentials are absent.
@@ -45,6 +61,8 @@ export function buildAdapter(input) {
                 credentials: input.hlCredentials,
                 mode: mode,
                 marketSlippagePct: readPluginConfig().hl?.marketSlippagePct,
+                microLive,
+                tradeIngest,
             },
         });
     }
@@ -55,7 +73,12 @@ export function buildAdapter(input) {
     // Read bracket-mode from plugin-config at adapter build time so a config
     // flip + "Reconnect Exchange" pattern picks up the new mode on the next swap.
     const bracketMode = loadBracketMode();
-    return new LiveAdapter(exchange, mode, microLive, bracketMode);
+    // Same read-at-build-time rule for the user-data stream (F9): a rebuilt
+    // adapter wires its WS at construction, so passing nothing here reverted
+    // prod's `enforce` to REST-only polling on every dashboard reconnect.
+    const userDataStreamMode = loadUserDataStreamMode();
+    const userDataStreamTunables = loadUserDataStreamTunables();
+    return new LiveAdapter(exchange, mode, microLive, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, input.wiring?.autoCapture);
 }
 /**
  * Mutable runtime holder. Held once per plugin registration.
@@ -82,6 +105,17 @@ export class PluginRuntime {
      *  for watcher closes (issue #199) — without it, a live<->paper reconnect
      *  would silently shed the capture wiring. */
     onWatcherCreated;
+    /** Observer applied to EVERY live adapter this runtime creates (audit F9,
+     *  same pattern as onWatcherCreated). index.ts uses it to install the
+     *  drift_detected → journal close-bypass cleanup listener — previously
+     *  installed only on the BOOT adapter and lost on every reconnect. */
+    onAdapterCreated;
+    /** Boot live wiring threaded into every buildAdapter call (audit F9). */
+    liveWiring;
+    /** Fired after EVERY reconnect publishes its adapter (paper ones included) —
+     *  set post-construction because its consumer (the approval-listener
+     *  lifecycle, audit F10) is built after the runtime. */
+    onAdapterSwapped;
     /** Reconnect is serialized — a second caller waits for the first to finish
      *  so we never tear down an adapter that's mid-rebuild. */
     reconnectInFlight = null;
@@ -93,11 +127,16 @@ export class PluginRuntime {
         this._marketFeed = initial.marketFeed ?? null;
         this.operationLock = initial.operationLock;
         this.onWatcherCreated = initial.onWatcherCreated;
+        this.onAdapterCreated = initial.onAdapterCreated;
+        this.liveWiring = initial.liveWiring;
     }
     get adapter() { return this._adapter; }
     get mode() { return this._mode; }
     get stopWatcher() { return this._stopWatcher; }
     get marketFeed() { return this._marketFeed; }
+    setOnAdapterSwapped(cb) {
+        this.onAdapterSwapped = cb;
+    }
     setWave9LiveLifecycleHooks(hooks) {
         this.wave9LiveLifecycleHooks = hooks;
         if (this._adapter instanceof LiveAdapter) {
@@ -160,7 +199,9 @@ export class PluginRuntime {
                 logger.warn(TAG, `old HL adapter stop failed: ${formatError(err)}`);
             }
         }
-        // 3. Build the new adapter.
+        // 3. Build the new adapter — with the boot live wiring, so a reconnect
+        //    can never silently shed WS authority / audit ingest / auto-capture
+        //    (audit F9).
         const fresh = buildAdapter({
             mode: next.mode,
             exchange: next.exchange,
@@ -168,12 +209,18 @@ export class PluginRuntime {
             simulator: this.simulator,
             venue: next.venue,
             hlCredentials: next.hlCredentials,
+            wiring: this.liveWiring,
         });
         // Install autonomous protection callbacks before initialization can emit
         // user-data or bracket-reconciler events.
         if (fresh instanceof LiveAdapter) {
             this.wave9LiveLifecycleHooks?.configureLiveAdapter?.(fresh);
         }
+        // Same before-init rule for the drift_detected journal cleanup (F9): the
+        // reconciler can emit on its first poll.
+        if (fresh instanceof LiveAdapter || fresh instanceof HyperliquidLiveAdapter) {
+            this.onAdapterCreated?.(fresh);
+        }
         // 4. Fire async init for live adapters (non-blocking — readiness flips
         //    INIT_PENDING → READY/DEGRADED/BLOCKED on its own).
         if (fresh instanceof LiveAdapter || fresh instanceof HyperliquidLiveAdapter) {
@@ -210,6 +257,10 @@ export class PluginRuntime {
                 this._marketFeed.start();
             }
         }
+        // 8. Notify swap observers (approval-listener lifecycle etc. — F10).
+        //    Fired for EVERY swap including paper, so a live→PAPER flip can tear
+        //    down consumers bound to the orphaned live adapter.
+        this.onAdapterSwapped?.(fresh);
         logger.info(TAG, `Reconnect complete: now in ${this._mode} mode (readiness=${fresh.readiness})`);
     }
 }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Supervised trading plugin for the ReefClaw dashboard: paper trading with real market data (no API keys required), and optional live trading on Binance or Hyperliquid behind explicit operator opt-in, exchange API credentials, and always-on protective stop brackets. Includes the dashboard connector bridge, heartbeat automation, and remote SKILL.md instruction updates from the ReefClaw webapp.",
   "author": "ReefClaw",
   "activation": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.13",
-  "description": "ReefClaw supervised trading plugin for OpenClaw \u2014 paper trading with real market data, optional live trading on Binance or Hyperliquid (operator opt-in, API keys, always-on protective brackets), plus the ReefClaw dashboard connector with heartbeat automation and remote SKILL.md updates from the ReefClaw webapp. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
+  "version": "0.1.15",
+  "description": "ReefClaw supervised trading plugin for OpenClaw — paper trading with real market data, optional live trading on Binance or Hyperliquid (operator opt-in, API keys, always-on protective brackets), plus the ReefClaw dashboard connector with heartbeat automation and remote SKILL.md updates from the ReefClaw webapp. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",
   "openclaw": {
@@ -16,16 +16,17 @@
     }
   },
   "files": [
-    "**/*"
+    "**/*",
+    "!scripts/**"
   ],
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
-    "@reefclaw/shared": "0.1.2",
+    "@reefclaw/shared": "0.1.3",
     "ccxt": "4.5.37",
     "json5": "2.2.3",
-    "ws": "8.19.0"
+    "ws": "8.21.1"
   },
   "scripts": {
     "build": "node scripts/assemble.mjs"

package/risk/pre-trade-check.js

@@ -57,9 +57,22 @@ export function adjustLimitByVol(defaultLimit, volFactor) {
         return defaultLimit;
     return defaultLimit / volFactor;
 }
+/** Strip a CCXT settle suffix ('AVAX/USDC:USDC' → 'AVAX/USDC') before any
+ *  same-symbol comparison. Live adapter positions carry SUFFIXED ccxt symbols
+ *  while the agent's order symbol is canonical/unsuffixed — an exact string
+ *  match therefore NEVER matched on live, so a close-shaped order was
+ *  misclassified as a fresh entry (entry-gated, breaking "exits always work"),
+ *  a flip was never netted, and a scale-in's existing leg was invisible to the
+ *  resulting-notional cap. Paper positions are unsuffixed, so paper was
+ *  unaffected — exactly the CLAUDE.md symbol-normalization trap. Inline copy
+ *  of venues/symbols.ts stripSettleSuffix (module-private there; this module
+ *  stays dependency-light like bracket-ledger.ts). */
+function canonSymbol(symbol) {
+    return symbol.replace(/:[A-Z]+$/, '');
+}
 /** Check if an order is closing an existing position (partial or full). */
 export function isClosingOrder(order, positions) {
-    const pos = positions.find(p => p.symbol === order.symbol);
+    const pos = positions.find(p => canonSymbol(p.symbol) === canonSymbol(order.symbol));
     if (!pos)
         return false;
     // Sell against a long = closing; buy against a short = closing
@@ -103,7 +116,7 @@ export function preTradeRiskCheck(order, portfolio, limits = DEFAULT_PRE_TRADE_L
     //     exposure — even in the RED zone (M6).
     //   - same-direction add (scale-in) / fresh entry → full entry checks (M5).
     // Emergency flatten bypasses this function entirely (EmergencyControls → adapter.createOrder).
-    const closingPos = portfolio.positions.find(p => p.symbol === order.symbol &&
+    const closingPos = portfolio.positions.find(p => canonSymbol(p.symbol) === canonSymbol(order.symbol) &&
         ((p.side === 'long' && order.side === 'sell') || (p.side === 'short' && order.side === 'buy')));
     const flipAmount = closingPos ? order.amount - closingPos.quantity : 0;
     const isFlip = closingPos != null && flipAmount > 1e-9 * Math.max(closingPos.quantity, 1);
@@ -211,7 +224,7 @@ export function preTradeRiskCheck(order, portfolio, limits = DEFAULT_PRE_TRADE_L
     //    is only the new opposite leg (the old leg is closed), so the existing
     //    notional is NOT added there.
     const entryNotional = entryOrder.amount * order.price;
-    const sameSymbolPos = portfolio.positions.find(p => p.symbol === order.symbol);
+    const sameSymbolPos = portfolio.positions.find(p => canonSymbol(p.symbol) === canonSymbol(order.symbol));
     const isScaleIn = sameSymbolPos != null &&
         ((sameSymbolPos.side === 'long' && order.side === 'buy') ||
             (sameSymbolPos.side === 'short' && order.side === 'sell'));
@@ -228,8 +241,8 @@ export function preTradeRiskCheck(order, portfolio, limits = DEFAULT_PRE_TRADE_L
         });
     }
     // 2. Open positions count (would a new symbol exceed limit?)
-    const existingSymbols = new Set(portfolio.positions.map(p => p.symbol));
-    if (!existingSymbols.has(order.symbol)) {
+    const existingSymbols = new Set(portfolio.positions.map(p => canonSymbol(p.symbol)));
+    if (!existingSymbols.has(canonSymbol(order.symbol))) {
         const newCount = existingSymbols.size + 1;
         if (newCount > limits.maxOpenPositions) {
             violations.push({

package/simulator/exchange-simulator.d.ts

@@ -4,6 +4,9 @@ import type { CcxtOrder, CcxtBalance, CcxtPosition, CcxtTicker } from '../types.
 export declare class ExchangeSimulator extends EventEmitter {
     private state;
     private lastTicker;
+    /** Symbols with a take-profit close in flight — suppresses a re-entrant
+     *  tick firing a second close on the same position. */
+    private takeProfitPending;
     private lastOrderBook;
     private simulationConfig;
     /** Metadata for pending limit orders, keyed by order ID. Cleaned up on fill/cancel. */
@@ -46,10 +49,21 @@ export declare class ExchangeSimulator extends EventEmitter {
     /** Cache the latest order book snapshot for a symbol. */
     updateOrderBook(symbol: string, orderbook: OrderBookDepth): void;
     getLastOrderBook(symbol: string): OrderBookDepth | undefined;
-    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata): CcxtOrder;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, 
+    /** Paper-only market-fill price override (take-profit leg). When set, the
+     *  market branch prices off THIS instead of the last tick, and skips the
+     *  stale-quote guard — the caller supplied the price, so quote age is
+     *  irrelevant, and a protective exit must never be blocked (issue #202). */
+    referencePrice?: number): CcxtOrder;
     cancelOrder(orderId: string): CcxtOrder;
     cancelAllOrders(symbol?: string): CcxtOrder[];
-    closePosition(symbol: string, closeReason?: CloseReason): CcxtOrder;
+    /**
+     * @param referencePrice Paper-only fill-price override. Used by the
+     *   take-profit leg to fill AT the target level instead of the (possibly
+     *   gapped-past) tick price — see `checkTakeProfitLegs`. Omitted everywhere
+     *   else, which keeps the normal market-close path byte-identical.
+     */
+    closePosition(symbol: string, closeReason?: CloseReason, referencePrice?: number): CcxtOrder;
     /** Paper-only: move an open position's MUTABLE protective levels (stopPrice /
      *  targetPrice) in place and persist, WITHOUT the close+reopen round-trip
      *  (which pays an extra taker fee and resets the R/MFE denominators). The
@@ -63,6 +77,35 @@ export declare class ExchangeSimulator extends EventEmitter {
     }): void;
     updateTicker(ticker: CcxtTicker): void;
     getLastTicker(symbol: string): CcxtTicker | undefined;
+    /**
+     * Take-profit legs — the paper analog of the exchange-native
+     * `TAKE_PROFIT_MARKET` order live attaches at entry.
+     *
+     * ★ Why this exists: paper STORED `metadata.targetPrice` and surfaced it
+     * (chart line, positions table) but nothing ever closed on it, so the TP was
+     * a drawing rather than an order. Every paper winner ran straight past its
+     * exit — observed live 2026-07-27 on an OP/USDT short that reached +2.07R
+     * against a 1.0R target. That made paper the odd one out of three: the
+     * BACKTEST exits at target (`backtest/engine.ts` exitReason 'target') and
+     * LIVE exits at target (Binance TP_MARKET leg / HL coordinator TP leg), so
+     * a strategy forward-validated on paper was being measured on a book that
+     * let every winner run.
+     *
+     * Fill convention: the TARGET LEVEL is the decision price, and the normal
+     * realistic-fill engine applies its own adverse slippage around it (book
+     * VWAP + vol factor + taker fee) — the same model every other paper fill
+     * uses, rather than a second hand-rolled slippage constant. When a tick gaps
+     * past the target we deliberately do NOT credit the gap: filling at the
+     * level is worse for us than filling at the gapped tick, so this stays
+     * conservative against both the backtest and a real TP_MARKET (which would
+     * fill at the gapped price).
+     *
+     * Stops stay with the PositionWatcher: it is the safety floor and re-homing
+     * it is a separate, riskier change. A single tick can only breach one leg
+     * (stop and target sit on opposite sides of entry), so there is no
+     * stop-vs-target ordering ambiguity to resolve here.
+     */
+    private checkTakeProfitLegs;
     /** Walk every position for `symbol` and refresh MFE / give-back from the
      *  latest mark. Idempotent — pure update of `metadata.mfePeakPrice` (only
      *  ratchets favourably) plus derived `mfeR` and `giveBackRatio`. Safe to