@reefclaw/openclaw-plugin 0.1.6 → 0.1.7

package/onboarding/runtime.js

@@ -15,6 +15,7 @@ import { PaperAdapter } from '../paper-adapter.js';
 import { LiveAdapter } from '../live/live-adapter.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
 import { loadBracketMode } from '../config/brackets-config.js';
+import { loadStopWatcherIntervalMs } from '../config/plugin-config-io.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'plugin-runtime';
 /** Pure-ish factory: builds an adapter for the requested mode.
@@ -57,6 +58,11 @@ export class PluginRuntime {
     _marketFeed;
     operationLock;
     wave9LiveLifecycleHooks;
+    /** Observer applied to EVERY stop-watcher this runtime creates (reconnects
+     *  included). index.ts uses it to attach the journal auto-capture listener
+     *  for watcher closes (issue #199) — without it, a live<->paper reconnect
+     *  would silently shed the capture wiring. */
+    onWatcherCreated;
     /** 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;
@@ -67,6 +73,7 @@ export class PluginRuntime {
         this._stopWatcher = initial.stopWatcher ?? null;
         this._marketFeed = initial.marketFeed ?? null;
         this.operationLock = initial.operationLock;
+        this.onWatcherCreated = initial.onWatcherCreated;
     }
     get adapter() { return this._adapter; }
     get mode() { return this._mode; }
@@ -152,9 +159,13 @@ export class PluginRuntime {
         this._adapter = fresh;
         this._mode = next.mode;
         deps.adapterDeps.adapter = fresh;
-        // 6. Start a new stop-watcher bound to the new adapter.
-        const watcher = new PositionWatcher(fresh, undefined, this.operationLock);
+        // 6. Start a new stop-watcher bound to the new adapter. Re-read the
+        //    operator's cadence override — building with `undefined` here
+        //    silently reverted plugin-config `stopWatcher.intervalMs` to the
+        //    default on every reconnect.
+        const watcher = new PositionWatcher(fresh, loadStopWatcherIntervalMs(), this.operationLock);
         this.wave9LiveLifecycleHooks?.configurePositionWatcher?.(watcher, fresh);
+        this.onWatcherCreated?.(watcher);
         watcher.start();
         this._stopWatcher = watcher;
         // 7. Paper market feed follows the mode: run it when the new adapter is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "ReefClaw trading plugin for OpenClaw \u2014 paper trading with real Binance market data, plus the ReefClaw dashboard connector (supervised by OpenClaw, no service manager needed). Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",
@@ -22,7 +22,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@reefclaw/shared": "0.1.1",
+    "@reefclaw/shared": "0.1.2",
     "ccxt": "4.5.37",
     "json5": "2.2.3",
     "ws": "8.19.0"

package/portfolio/reentry-tracker.d.ts

@@ -0,0 +1,36 @@
+export interface ReentryExitRecord {
+    /** Canonical symbol (no settle suffix). */
+    symbol: string;
+    /** setup_type / strategy name from the entry metadata, when known. */
+    setupType?: string;
+    side: 'long' | 'short';
+    /** Whether the closed trade realized a loss (drives the stronger caution). */
+    wasLoss?: boolean;
+    closedAtMs: number;
+}
+/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
+ *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
+ *  shapes default to 60min so short-TF strategies are never over-warned. */
+export declare function strategyBarMinutes(name: string | undefined): number;
+export declare class ReentryTracker {
+    private records;
+    private readonly filePath;
+    private readonly dir;
+    constructor(pluginId?: string, opts?: {
+        basePath?: string;
+    });
+    /** Record a position exit. Never throws (best-effort persistence). */
+    recordExit(record: Omit<ReentryExitRecord, 'symbol'> & {
+        symbol: string;
+    }): void;
+    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
+     *  a symbol-only match so multi-strategy books get precise cautions. */
+    lastExit(symbol: string, setupType?: string): ReentryExitRecord | undefined;
+    /** Structured caution when (symbol, strategy) was already traded within the
+     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
+     *  the agent decides; nothing here blocks an order. */
+    cautionFor(symbol: string, strategy: string | undefined, nowMs?: number): string | undefined;
+    /** Test seam. */
+    getRecords(): readonly ReentryExitRecord[];
+    private persist;
+}

package/portfolio/reentry-tracker.js

@@ -0,0 +1,127 @@
+// Re-entry tracker — records recent position exits per (symbol, setup) so the
+// entry funnel (scan_pairs / get_signals) can flag setups the agent already
+// traded within the current signal bar (issue #204).
+//
+// WHY: the validated backtests for the 4h/1d templates have one-trade-per-
+// signal semantics — a signal bar produces at most one trade. Live, the 4h
+// condition stays true for hours, so after every exit the next heartbeat
+// re-entered the same setup: measured 19× the backtest cadence with 79-minute
+// median holds, including 22 same-direction re-entries within one bar of a
+// LOSING close (2026-07-14 → 07-20 HL soak). Per the tools-not-mandates
+// doctrine this ships as STRUCTURED INDICATION — the annotation tells the
+// agent the setup was already traded this bar; it never blocks the order.
+//
+// Persistence: small JSON in the plugins base dir (same pattern as
+// position-state-store) so restarts don't blind the indication. Best-effort —
+// a persistence failure degrades to in-memory-only, never throws into the
+// trading path.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'reentry-tracker';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const STATE_FILENAME = 'reentry-log.json';
+const MAX_RECORDS = 300;
+/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
+ *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
+ *  shapes default to 60min so short-TF strategies are never over-warned. */
+export function strategyBarMinutes(name) {
+    if (!name)
+        return 60;
+    const lower = name.toLowerCase();
+    const hourMatch = lower.match(/_(\d{1,2})h\b|_(\d{1,2})h_|_(\d{1,2})h$/);
+    if (hourMatch) {
+        const h = Number(hourMatch[1] ?? hourMatch[2] ?? hourMatch[3]);
+        if (Number.isFinite(h) && h > 0)
+            return h * 60;
+    }
+    if (/_1d\b|_1d_|_1d$|daily/.test(lower))
+        return 1440;
+    return 60;
+}
+export class ReentryTracker {
+    records = [];
+    filePath;
+    dir;
+    constructor(pluginId, opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        this.dir = join(base, pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, STATE_FILENAME);
+        try {
+            if (!existsSync(this.dir))
+                mkdirSync(this.dir, { recursive: true });
+            if (existsSync(this.filePath)) {
+                const parsed = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+                if (Array.isArray(parsed?.records)) {
+                    this.records = parsed.records.filter((r) => typeof r?.symbol === 'string' && Number.isFinite(r?.closedAtMs));
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `load failed (${formatError(err)}) — starting empty`);
+            this.records = [];
+        }
+    }
+    /** Record a position exit. Never throws (best-effort persistence). */
+    recordExit(record) {
+        try {
+            this.records.push({ ...record, symbol: normalizeBracketSymbol(record.symbol) });
+            if (this.records.length > MAX_RECORDS) {
+                this.records = this.records.slice(-MAX_RECORDS);
+            }
+            this.persist();
+        }
+        catch (err) {
+            logger.warn(TAG, `recordExit failed: ${formatError(err)}`);
+        }
+    }
+    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
+     *  a symbol-only match so multi-strategy books get precise cautions. */
+    lastExit(symbol, setupType) {
+        const key = normalizeBracketSymbol(symbol);
+        let bySetup;
+        let bySymbol;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.symbol !== key)
+                continue;
+            if (!bySymbol)
+                bySymbol = r;
+            if (setupType && r.setupType === setupType) {
+                bySetup = r;
+                break;
+            }
+            if (!setupType)
+                break;
+        }
+        return bySetup ?? bySymbol;
+    }
+    /** Structured caution when (symbol, strategy) was already traded within the
+     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
+     *  the agent decides; nothing here blocks an order. */
+    cautionFor(symbol, strategy, nowMs = Date.now()) {
+        const last = this.lastExit(symbol, strategy);
+        if (!last)
+            return undefined;
+        const barMin = strategyBarMinutes(strategy ?? last.setupType);
+        const agoMin = Math.round((nowMs - last.closedAtMs) / 60_000);
+        if (agoMin < 0 || agoMin > barMin)
+            return undefined;
+        const lossNote = last.wasLoss ? ' at a LOSS' : '';
+        return (`already traded this signal bar: exited a ${last.side} on this setup ${agoMin}m ago${lossNote} ` +
+            `(bar=${barMin}m). The validated backtest takes ONE trade per signal bar — re-enter only if ` +
+            `you can name what NEW information arrived since that exit.`);
+    }
+    /** Test seam. */
+    getRecords() {
+        return this.records;
+    }
+    persist() {
+        const payload = { schemaVersion: 1, records: this.records };
+        const tmp = `${this.filePath}.tmp`;
+        writeFileSync(tmp, JSON.stringify(payload), 'utf-8');
+        renameSync(tmp, this.filePath);
+    }
+}

package/signals/conditions/registry.js

@@ -160,11 +160,20 @@ register('price_sweep', (ctx, params, _dir, condCtx) => {
             sweepLevel = nearestHigh;
         }
     }
-    // Store in shared context for entry/stop rules and direction
+    // Store in shared context for entry/stop rules and direction.
+    // sweptDirection is written non-destructively, like the funding_extreme /
+    // cvd_divergence setters: only when a sweep actually resolved a side. An
+    // unconditional write (including null on a no-sweep bar) clobbered a
+    // direction set by an earlier condition in the same evaluation, so a
+    // from_sweep/from_funding strategy listing price_sweep AFTER another
+    // setter could never fire.
     condCtx.sweepLevel = sweepLevel;
     condCtx.recentLow = recentLow;
     condCtx.recentHigh = recentHigh;
-    condCtx.sweptDirection = sweptLow ? 'LONG' : sweptHigh ? 'SHORT' : null;
+    if (sweptLow)
+        condCtx.sweptDirection = 'LONG';
+    else if (sweptHigh)
+        condCtx.sweptDirection = 'SHORT';
     const met = sweptLow || sweptHigh;
     return {
         met,

package/signals/strategy-adapter.js

@@ -170,15 +170,25 @@ export function adaptStrategy(config, gateNamespace) {
             const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ectx, null);
             // Determine direction
             const direction = resolveDirection(config.directionRule, ectx, condCtx);
-            // Pass 2: re-evaluate direction-sensitive conditions now that we know direction
-            // (orderbook_imbalance and funding_contrarian behave differently per direction)
-            const directionSensitive = new Set(['orderbook_imbalance', 'funding_contrarian', 'funding_extreme_skip', 'funding_position_ok', 'return_momentum']);
-            const hasDirSensitive = config.conditions.some(c => directionSensitive.has(c.type));
+            // Pass 2: once the direction is known, re-evaluate the FULL condition
+            // array with it. Many registry conditions branch on `direction`
+            // (orderbook_imbalance, funding_contrarian, macd_crossover,
+            // bollinger_breakout, vwap_position, stoch_rsi_extreme, ichimoku_cloud,
+            // supertrend_direction, …) and their pass-1 result was computed against
+            // direction=null — typically the permissive either-side branch. A
+            // hand-curated allowlist here (the pre-fix 5-type set) silently drifted
+            // out of sync with the registry, so non-listed direction-dependent
+            // conditions kept their permissive pass-1 result forever (e.g. a
+            // fixed_long strategy's macd_crossover accepted a BEARISH crossover).
+            // Pass 2 always evaluated the whole array anyway — use it wholesale.
+            // Direction-insensitive conditions are pure functions of (ctx, params)
+            // and return identical results in both passes; entry/stop computation
+            // below deliberately keeps pass 1's condCtx (setter values don't depend
+            // on direction).
             let finalConditions = pass1;
-            if (direction && hasDirSensitive) {
+            if (direction) {
                 const { conditions: pass2 } = evaluateConditions(config.conditions, ectx, direction);
-                // Merge: use pass2 results for direction-sensitive, pass1 for others
-                finalConditions = pass1.map((c, i) => directionSensitive.has(config.conditions[i].type) ? pass2[i] : c);
+                finalConditions = pass2;
             }
             const allMet = finalConditions.every(c => c.met);
             let trade;

package/simulator/exchange-simulator.d.ts

@@ -79,6 +79,18 @@ export declare class ExchangeSimulator extends EventEmitter {
      *  reload never regresses the agent's give-back signal. */
     replaceState(newState: SimulatorState): void;
     getState(): SimulatorState;
+    /** Default max quote age a NEW-exposure fill may price against (issue #202).
+     *  Generous vs the 5s paper feed cadence; env RC_PAPER_MAX_QUOTE_AGE_MS
+     *  overrides. */
+    static readonly DEFAULT_MAX_QUOTE_AGE_MS = 45000;
+    private maxQuoteAgeMs;
+    /** Quote age from the ticker's own timestamp. A missing/invalid timestamp
+     *  reads as age 0 (fail-open — the guard cannot fire on it). */
+    private quoteAgeMs;
+    /** Reject fills that would OPEN or GROW exposure on a stale quote. Risk-
+     *  reducing fills (closes/partials against an existing position) are always
+     *  allowed — blocking a close on a broken feed compounds the risk. */
+    private assertQuoteFresh;
     private shouldFillLimit;
     private executeMarketFill;
     private executeLimitFill;

package/simulator/exchange-simulator.js

@@ -286,11 +286,18 @@ export class ExchangeSimulator extends EventEmitter {
             if (!ticker) {
                 throw new Error(`No ticker data for ${symbol}. Call updateTicker() first.`);
             }
+            // Stale-quote guard (issue #202): a market fill priced off an aged quote
+            // books phantom P&L the moment a fresh price arrives (measured up to
+            // ~0.6% off on the HL paper book — a real −$22.99 in 4 seconds). Reject
+            // instead; the agent refreshes via fetch_ticker and retries.
+            this.assertQuoteFresh(symbol, ticker);
             return this.executeMarketFill(order, ticker.last, metadata);
         }
-        // Limit order — check if it crosses the current price
+        // Limit order — check if it crosses the current price. A stale quote must
+        // not price an immediate cross-fill (same hazard as market fills); the
+        // order RESTS instead and fills on the next fresh tick via updateTicker.
         const ticker = this.lastTicker.get(symbol);
-        if (ticker && this.shouldFillLimit(order, ticker.last)) {
+        if (ticker && this.quoteAgeMs(ticker) <= this.maxQuoteAgeMs() && this.shouldFillLimit(order, ticker.last)) {
             return this.executeLimitFill(order, ticker.last, metadata);
         }
         // Limit order doesn't cross — add to open orders. Pin the entry metadata
@@ -548,6 +555,45 @@ export class ExchangeSimulator extends EventEmitter {
         };
     }
     // ---- Private helpers ----
+    /** Default max quote age a NEW-exposure fill may price against (issue #202).
+     *  Generous vs the 5s paper feed cadence; env RC_PAPER_MAX_QUOTE_AGE_MS
+     *  overrides. */
+    static DEFAULT_MAX_QUOTE_AGE_MS = 45_000;
+    maxQuoteAgeMs() {
+        const raw = Number(process.env.RC_PAPER_MAX_QUOTE_AGE_MS);
+        return Number.isFinite(raw) && raw > 0 ? raw : ExchangeSimulator.DEFAULT_MAX_QUOTE_AGE_MS;
+    }
+    /** Quote age from the ticker's own timestamp. A missing/invalid timestamp
+     *  reads as age 0 (fail-open — the guard cannot fire on it). */
+    quoteAgeMs(ticker) {
+        const ts = ticker.timestamp;
+        if (!Number.isFinite(ts) || ts <= 0)
+            return 0;
+        return Math.max(0, Date.now() - ts);
+    }
+    /** Reject fills that would OPEN or GROW exposure on a stale quote. Risk-
+     *  reducing fills (closes/partials against an existing position) are always
+     *  allowed — blocking a close on a broken feed compounds the risk. */
+    assertQuoteFresh(symbol, ticker) {
+        const age = this.quoteAgeMs(ticker);
+        const max = this.maxQuoteAgeMs();
+        if (age <= max)
+            return;
+        const pos = this.state.positions.find(p => p.symbol === symbol);
+        // The order side reaching here is the one being filled — derive reduce vs
+        // grow from the position side at the call site instead? The market path
+        // calls this before fill with the order side unavailable; use position
+        // presence: any existing position keeps closes flowing, and a stale-quote
+        // scale-in on an open position is bounded by the feed refreshing open
+        // symbols every 5s (only NEW symbols go minutes without a tick).
+        if (pos) {
+            logger.warn(TAG, `Stale quote for ${symbol} (${Math.round(age / 1000)}s old) — allowing fill because an open ` +
+                `position exists (risk-reducing paths are never blocked)`);
+            return;
+        }
+        throw new Error(`Order rejected: market data for ${symbol} is stale (${Math.round(age / 1000)}s old, ` +
+            `max ${Math.round(max / 1000)}s). Refresh the price (fetch_ticker) and retry.`);
+    }
     shouldFillLimit(order, currentPrice) {
         if (order.price === null)
             return false;
@@ -567,6 +613,12 @@ export class ExchangeSimulator extends EventEmitter {
             metadata,
         };
         const result = fillMarketOrder(order, currentPrice, this.state.wallet, position, realistic);
+        // Observability for issue #202: stamp the quote's age onto the fill's
+        // execution-quality record so staleness is visible in trade history.
+        const tickerAtFill = this.lastTicker.get(order.symbol);
+        if (result.executionQuality && tickerAtFill) {
+            result.executionQuality.quoteAgeMs = this.quoteAgeMs(tickerAtFill);
+        }
         const ccxtOrder = this.applyFillResult(result);
         const eq = result.executionQuality;
         if (eq) {
@@ -613,7 +665,25 @@ export class ExchangeSimulator extends EventEmitter {
             fillPrice: result.order.average ?? 0,
             fee: result.order.fee.cost,
         });
-        return this.toCcxtOrder(result.order);
+        const ccxtOrder = this.toCcxtOrder(result.order);
+        // Reducing fills carry a Trade record — attach its engine-exact economics
+        // (net-of-fee P&L + both fee legs) so the journal close capture records
+        // NET, matching the live book's convention (issue #201). The wallet/NAV
+        // was already net; only the journal was blind to fees.
+        if (result.trade) {
+            const t = result.trade;
+            ccxtOrder.info = {
+                ...(ccxtOrder.info ?? {}),
+                paperTrade: {
+                    grossRealizedPnl: t.realizedPnl,
+                    netRealizedPnl: t.realizedPnl - (t.fee + (t.openFee ?? 0)),
+                    openFee: t.openFee ?? 0,
+                    closeFee: t.fee,
+                    ...(typeof t.metadata?.setupType === 'string' ? { setupType: t.metadata.setupType } : {}),
+                },
+            };
+        }
+        return ccxtOrder;
     }
     updatePosition(symbol, newPosition) {
         const idx = this.state.positions.findIndex(p => p.symbol === symbol);

package/simulator/types.d.ts

@@ -38,6 +38,10 @@ export interface ExecutionQuality {
     feePaid: number;
     bookLevelsConsumed: number;
     bookDepthAvailable: boolean;
+    /** Age of the quote the fill priced against (fill time − ticker.timestamp).
+     *  Surfaces feed staleness (issue #202); absent on records from before the
+     *  field existed or when the ticker carried no usable timestamp. */
+    quoteAgeMs?: number;
 }
 export interface SimulatorState {
     version: string;

package/skills/reefclaw/SKILL.md

@@ -80,6 +80,8 @@ OpenClaw can install the ReefClaw plugin through its own owner chat command —
 2. Tell the user to type `/restart` in this chat.
 3. Then the user types: `/plugins install clawhub:@reefclaw/openclaw-plugin` — the install restarts OpenClaw automatically; the bundled connector starts by itself and the dashboard flips to Connected.
 
+If that install is **cancelled asking for a ClawHub risk acknowledgement** (OpenClaw 2026.7+ does this; older versions never ask and reject the flag), rerun the identical command with the acknowledgement appended: `/plugins install clawhub:@reefclaw/openclaw-plugin --acknowledge-clawhub-risk`. If it is still refused, use the `npx @reefclaw/connect` fallback — it does not go through ClawHub.
+
 Only fall back to `npx @reefclaw/connect` (below) when the chat install is unavailable.
 
 ## If you cannot run the installer (elevated exec disabled)

package/tools/assessment-validation.d.ts

@@ -1,4 +1,25 @@
 import type { RealizationRule } from '../simulator/types.js';
+/** Minimum pre-entry stop distance in basis points (the SKILL v2.10.0
+ *  discipline floor's fixed component; the ATR component is enforced by the
+ *  live bracket path where ATR is authoritative). */
+export declare const MIN_STOP_DISTANCE_BPS = 30;
+export interface ProtectiveGeometryArgs {
+    side: 'buy' | 'sell';
+    /** Reference entry price: the limit price, or last trade for market orders. */
+    refPrice: number;
+    stopPrice?: number;
+    invalidationPrice?: number;
+    targetPrice?: number;
+}
+/** Validate stop / invalidation / target geometry against the entry side.
+ *
+ *  Before this existed the wrong-side check ran ONLY on the wave9 path
+ *  (create-order.ts) — a generic short entered with its stop BELOW entry
+ *  passed validation and was closed by the stop-watcher seconds later
+ *  (7 sub-5-minute kills on the 2026-07 HL soak, issue #200). Returns an
+ *  error string, or null when the geometry is sound. Fields left undefined
+ *  are not judged (stop-required policy stays with the caller). */
+export declare function validateProtectiveGeometry(args: ProtectiveGeometryArgs): string | null;
 /** The five legitimate reasons to manually close an otherwise-bracketed
  *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other
  *  value is rejected. */

package/tools/assessment-validation.js

@@ -13,6 +13,64 @@
 //                           live mode.
 // Tested in: assessment-validation.test.ts.
 import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+// ---- protective geometry (create_order, issue #200) ----
+/** Minimum pre-entry stop distance in basis points (the SKILL v2.10.0
+ *  discipline floor's fixed component; the ATR component is enforced by the
+ *  live bracket path where ATR is authoritative). */
+export const MIN_STOP_DISTANCE_BPS = 30;
+/** Validate stop / invalidation / target geometry against the entry side.
+ *
+ *  Before this existed the wrong-side check ran ONLY on the wave9 path
+ *  (create-order.ts) — a generic short entered with its stop BELOW entry
+ *  passed validation and was closed by the stop-watcher seconds later
+ *  (7 sub-5-minute kills on the 2026-07 HL soak, issue #200). Returns an
+ *  error string, or null when the geometry is sound. Fields left undefined
+ *  are not judged (stop-required policy stays with the caller). */
+export function validateProtectiveGeometry(args) {
+    const { side, refPrice } = args;
+    if (!Number.isFinite(refPrice) || refPrice <= 0)
+        return null; // no reference — cannot judge
+    const dirWord = side === 'buy' ? 'long' : 'short';
+    if (args.stopPrice !== undefined) {
+        const stop = args.stopPrice;
+        if (!Number.isFinite(stop) || stop <= 0) {
+            return 'stopPrice must be a positive finite number.';
+        }
+        if ((side === 'buy' && stop >= refPrice) || (side === 'sell' && stop <= refPrice)) {
+            return (`stopPrice ${stop} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: a ${dirWord}'s ` +
+                `protective stop must be ${side === 'buy' ? 'below' : 'above'} entry. A wrong-side stop is ` +
+                `instantly "breached" and the stop-watcher closes the position seconds after entry.`);
+        }
+        const distanceBps = (Math.abs(refPrice - stop) / refPrice) * 10_000;
+        if (distanceBps < MIN_STOP_DISTANCE_BPS) {
+            return (`stopPrice ${stop} is only ${distanceBps.toFixed(1)}bps from entry ${refPrice} — below the ` +
+                `${MIN_STOP_DISTANCE_BPS}bps discipline floor. Place the stop at a structural level ` +
+                `(≥ max(0.3×ATR, ${MIN_STOP_DISTANCE_BPS}bps) from entry).`);
+        }
+    }
+    if (args.invalidationPrice !== undefined) {
+        const inv = args.invalidationPrice;
+        if (!Number.isFinite(inv) || inv <= 0) {
+            return 'invalidation_price must be a positive finite number.';
+        }
+        if ((side === 'buy' && inv >= refPrice) || (side === 'sell' && inv <= refPrice)) {
+            return (`invalidation_price ${inv} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
+                `invalidation must be ${side === 'buy' ? 'below' : 'above'} entry (it marks where the thesis ` +
+                `is WRONG, not where it profits). Fix the pinned plan before entering.`);
+        }
+    }
+    if (args.targetPrice !== undefined) {
+        const target = args.targetPrice;
+        if (!Number.isFinite(target) || target <= 0) {
+            return 'target_price must be a positive finite number.';
+        }
+        if ((side === 'buy' && target <= refPrice) || (side === 'sell' && target >= refPrice)) {
+            return (`target_price ${target} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
+                `the profit target must be ${side === 'buy' ? 'above' : 'below'} entry.`);
+        }
+    }
+    return null;
+}
 // ---- close_position ----
 /** The five legitimate reasons to manually close an otherwise-bracketed
  *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other