@reefclaw/openclaw-plugin 0.1.22 → 0.1.24

package/live/microstructure-assembler.js

@@ -66,9 +66,18 @@ export class IntelMicrostructureAssembler {
             return cached.block;
         // Map canonical "BTC/USDT" → intel "BTCUSDT".
         const intelSymbol = canonical.replace('/', '');
+        // cacheTtlMs mirrors the agent-facing tools (get_resting_liquidity /
+        // get_liquidation_pulse) so the assembler and the agent's own calls share
+        // one round-trip per heartbeat instead of duplicate-fetching.
         const [restingResult, pulseResult] = await Promise.allSettled([
-            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps),
-            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps),
+            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps, {
+                cacheTtlMs: 15_000,
+                timeoutMs: 10_000,
+            }),
+            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps, {
+                cacheTtlMs: 10_000,
+                timeoutMs: 10_000,
+            }),
         ]);
         const block = { symbol: canonical, updatedAt: ts };
         let anySignal = false;

package/live/proposal-decision-listener.d.ts

@@ -44,6 +44,9 @@ export interface ProposalDecisionListenerHealth {
     firesFailedTrading: number;
     patchFailures: number;
     pollFailures: number;
+    /** Distinct proposals seen holding a claim with no result — each one is an
+     *  operator-actionable reconciliation, not a retryable error. */
+    strandedObserved: number;
     lastTickAt: string | null;
 }
 export declare class ProposalDecisionListener {
@@ -56,6 +59,11 @@ export declare class ProposalDecisionListener {
      *  that finds ≥1 pending. */
     private currentIntervalMs;
     private health;
+    /** Stranded rows already reported by THIS process — the poll re-reports them
+     *  every tick (they never clear themselves), so dedupe the ERROR log. A
+     *  restart deliberately re-reports: if it's still stranded, it still needs
+     *  reconciling. */
+    private readonly strandedReported;
     /** Claim tokens are process-local by design. A new process must never steal
      *  an old process's durable claim, because it cannot know whether the
      *  exchange accepted an order just before the crash. */
@@ -82,6 +90,19 @@ export declare class ProposalDecisionListener {
     private scheduleNextTick;
     private runTick;
     private tick;
+    /** Report claims that outlived any plausible fire attempt.
+     *
+     *  These are proposals a listener (usually a previous incarnation of this
+     *  process) claimed and then died before reporting an outcome. Claims never
+     *  expire and the work queue skips claimed rows, so nothing retries them —
+     *  before this, the operator's approval simply produced no position and no
+     *  message. We can't safely re-fire (the order may already be live), so the
+     *  actionable thing is the deterministic client-order id: it answers "did
+     *  this ever reach the exchange?" definitively.
+     *
+     *  Logged at ERROR once per row per process so a restart re-surfaces it,
+     *  without spamming every 3 s tick. */
+    private reportStranded;
     private fetchPending;
     private claimPending;
     private forgetClaim;

package/live/proposal-decision-listener.js

@@ -51,8 +51,14 @@ export class ProposalDecisionListener {
         firesFailedTrading: 0,
         patchFailures: 0,
         pollFailures: 0,
+        strandedObserved: 0,
         lastTickAt: null,
     };
+    /** Stranded rows already reported by THIS process — the poll re-reports them
+     *  every tick (they never clear themselves), so dedupe the ERROR log. A
+     *  restart deliberately re-reports: if it's still stranded, it still needs
+     *  reconciling. */
+    strandedReported = new Set();
     /** Claim tokens are process-local by design. A new process must never steal
      *  an old process's durable claim, because it cannot know whether the
      *  exchange accepted an order just before the crash. */
@@ -171,6 +177,36 @@ export class ProposalDecisionListener {
             }
         }
     }
+    /** Report claims that outlived any plausible fire attempt.
+     *
+     *  These are proposals a listener (usually a previous incarnation of this
+     *  process) claimed and then died before reporting an outcome. Claims never
+     *  expire and the work queue skips claimed rows, so nothing retries them —
+     *  before this, the operator's approval simply produced no position and no
+     *  message. We can't safely re-fire (the order may already be live), so the
+     *  actionable thing is the deterministic client-order id: it answers "did
+     *  this ever reach the exchange?" definitively.
+     *
+     *  Logged at ERROR once per row per process so a restart re-surfaces it,
+     *  without spamming every 3 s tick. */
+    reportStranded(rows) {
+        for (const row of rows) {
+            if (this.strandedReported.has(row.id))
+                continue;
+            this.strandedReported.add(row.id);
+            this.health.strandedObserved++;
+            let cid = '(unavailable)';
+            try {
+                cid = proposalEntryClientOrderId(this.opts.adapter, row.proposalUuid);
+            }
+            catch { /* CID derivation is best-effort — the report still goes out */ }
+            logger.error(TAG, `STRANDED approved proposal ${row.id} (${row.symbol} ${row.side}) — claimed at ` +
+                `${row.claimedAt ?? 'unknown'} and never reported a result, so no listener will ` +
+                `retry it. The order may or may not have reached the exchange. Reconcile by ` +
+                `clientOrderId=${cid}: if present on the exchange the entry is live (attach/verify ` +
+                `its brackets); if absent, nothing was submitted and the proposal can be re-made.`);
+        }
+    }
     async fetchPending() {
         const url = `${this.opts.baseUrl}/api/internal/proposed_orders/pending-decisions`;
         try {
@@ -197,6 +233,9 @@ export class ProposalDecisionListener {
                 return [];
             }
             const body = await res.json();
+            if (Array.isArray(body.stranded) && body.stranded.length > 0) {
+                this.reportStranded(body.stranded);
+            }
             return Array.isArray(body.proposals) ? body.proposals : [];
         }
         catch (err) {

package/live/proposal-manager.d.ts

@@ -68,6 +68,18 @@ export declare class ProposalManager {
      *  + hard expiry synchronously; the actual POST runs in the background.
      *  Caller may correlate via the returned proposalUuid before the post lands. */
     propose(userId: string, req: ProposalRequest): ProposeResult;
+    /** Cancel every outstanding proposal for this tenant because the approval
+     *  path is being disabled (mode flipped off, or the live adapter went away).
+     *
+     *  Without this, flipping `per_trade` → `off` — or a live→PAPER swap — leaves
+     *  rows the operator can still see and approve while no listener exists to
+     *  fire them: the card sits there, Approve "works", and nothing ever happens
+     *  (design doc §10 row 12). The webapp refuses to cancel rows a listener has
+     *  already claimed, so this can never disown an order that may be live.
+     *
+     *  Best-effort by design: awaited by the caller only for logging. A failure
+     *  is bounded by hard expiry (≤4 min) and must never block an adapter swap. */
+    cancelAll(userId: string, reason: 'mode_disabled'): Promise<void>;
     /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
     drain(): Promise<void>;
     getHealth(): ProposalManagerHealth;

package/live/proposal-manager.js

@@ -50,6 +50,53 @@ export class ProposalManager {
         this.inFlight.add(promise);
         return { proposalUuid, setupBucket, hardExpiresAt };
     }
+    /** Cancel every outstanding proposal for this tenant because the approval
+     *  path is being disabled (mode flipped off, or the live adapter went away).
+     *
+     *  Without this, flipping `per_trade` → `off` — or a live→PAPER swap — leaves
+     *  rows the operator can still see and approve while no listener exists to
+     *  fire them: the card sits there, Approve "works", and nothing ever happens
+     *  (design doc §10 row 12). The webapp refuses to cancel rows a listener has
+     *  already claimed, so this can never disown an order that may be live.
+     *
+     *  Best-effort by design: awaited by the caller only for logging. A failure
+     *  is bounded by hard expiry (≤4 min) and must never block an adapter swap. */
+    async cancelAll(userId, reason) {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders/cancel-all`;
+        try {
+            const ac = new AbortController();
+            const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+            let res;
+            try {
+                res = await this.opts.fetchImpl(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.opts.ingestToken}`,
+                        'x-user-id': userId,
+                    },
+                    body: JSON.stringify({ reason }),
+                    signal: ac.signal,
+                });
+            }
+            finally {
+                clearTimeout(tid);
+            }
+            if (res.status < 200 || res.status >= 300) {
+                logger.warn(TAG, `cancel-all (${reason}) returned HTTP ${res.status}`);
+                return;
+            }
+            const body = (await res.json().catch(() => ({})));
+            const cancelled = typeof body.cancelled === 'number' ? body.cancelled : 0;
+            const inFlight = Array.isArray(body.inFlight) ? body.inFlight.length : 0;
+            if (cancelled > 0 || inFlight > 0) {
+                logger.info(TAG, `cancel-all (${reason}): cancelled=${cancelled} inFlight-uncancellable=${inFlight}`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `cancel-all (${reason}) failed: ${formatError(err)}`);
+        }
+    }
     /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
     async drain() {
         if (this.inFlight.size === 0)

package/live/stop-watcher.d.ts

@@ -37,8 +37,20 @@ export interface Wave9StopCloseLifecycle {
     resolveCandidateId(position: CcxtPosition): Promise<string | undefined> | string | undefined;
     settleAfterClose(candidateId: string, symbol: string): Promise<Wave9StopCloseOutcome>;
 }
+/** True when this position carries a protective stop we are supposed to be
+ *  enforcing. Used to decide whether an unusable mark is an ALARM (a stop we
+ *  cannot evaluate) or simply uninteresting (no stop set). */
+export declare function hasEnforceableStop(position: CcxtPosition): boolean;
+/** True when the mark cannot be trusted for a protective decision — either the
+ *  venue gave us nothing usable, or (paper) it is the fabricated entryPrice
+ *  fallback. Both mean "we do not know where price is", NOT "price is fine". */
+export declare function isMarkUnusable(position: CcxtPosition): boolean;
 /** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
+ *  Exported for direct unit-testing without spinning up a watcher loop.
+ *
+ *  NOTE: a `false` here means "not breached OR not knowable". Callers that care
+ *  about the difference must check isMarkUnusable() — see tick(), which alarms
+ *  on an unknowable mark rather than treating it as safe. */
 export declare function isStopBreached(position: CcxtPosition): boolean;
 export declare class PositionWatcher extends EventEmitter {
     private interval;
@@ -53,6 +65,9 @@ export declare class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     private notifiedBreach;
+    /** Symbols already alarmed for an unusable mark, so the ERROR fires once per
+     *  episode rather than every tick. Cleared as soon as a usable mark returns. */
+    private notifiedUnusableMark;
     constructor(adapter: IExchangeAdapter, intervalMs?: number, operationLock?: TradingOperationLock);
     /** Configure this after the durable execution ledger is ready. Runtime
      *  lifecycle hooks reapply it to every watcher after reconnect. */

package/live/stop-watcher.js

@@ -28,18 +28,35 @@ const TAG = 'stop-watcher';
 // revert with zero deploy via plugin-config.json `stopWatcher.intervalMs`.
 // See docs/EFFICIENCY_QUICK_WINS_PLAN.md + the Binance ban-gate context.
 export const DEFAULT_INTERVAL_MS = 10_000;
+/** True when this position carries a protective stop we are supposed to be
+ *  enforcing. Used to decide whether an unusable mark is an ALARM (a stop we
+ *  cannot evaluate) or simply uninteresting (no stop set). */
+export function hasEnforceableStop(position) {
+    const stop = position.stopPrice;
+    return stop !== undefined && stop !== null && Number.isFinite(stop) && stop > 0;
+}
+/** True when the mark cannot be trusted for a protective decision — either the
+ *  venue gave us nothing usable, or (paper) it is the fabricated entryPrice
+ *  fallback. Both mean "we do not know where price is", NOT "price is fine". */
+export function isMarkUnusable(position) {
+    if (position.markPriceStale === true)
+        return true;
+    const mark = position.markPrice;
+    return !Number.isFinite(mark) || mark <= 0;
+}
 /** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
+ *  Exported for direct unit-testing without spinning up a watcher loop.
+ *
+ *  NOTE: a `false` here means "not breached OR not knowable". Callers that care
+ *  about the difference must check isMarkUnusable() — see tick(), which alarms
+ *  on an unknowable mark rather than treating it as safe. */
 export function isStopBreached(position) {
-    const stop = position.stopPrice;
-    if (stop === undefined || stop === null || !Number.isFinite(stop) || stop <= 0) {
+    if (!hasEnforceableStop(position))
         return false;
-    }
-    const mark = position.markPrice;
-    if (!Number.isFinite(mark) || mark <= 0) {
+    if (isMarkUnusable(position))
         return false;
-    }
-    return position.side === 'long' ? mark <= stop : mark >= stop;
+    const stop = position.stopPrice;
+    return position.side === 'long' ? position.markPrice <= stop : position.markPrice >= stop;
 }
 export class PositionWatcher extends EventEmitter {
     interval = null;
@@ -54,6 +71,9 @@ export class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     notifiedBreach = new Set();
+    /** Symbols already alarmed for an unusable mark, so the ERROR fires once per
+     *  episode rather than every tick. Cleared as soon as a usable mark returns. */
+    notifiedUnusableMark = new Set();
     constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS, operationLock) {
         super();
         this.adapter = adapter;
@@ -82,6 +102,7 @@ export class PositionWatcher extends EventEmitter {
         }
         this.closePending.clear();
         this.notifiedBreach.clear();
+        this.notifiedUnusableMark.clear();
         logger.info(TAG, 'Stopped');
     }
     /** Run one check cycle. Exposed for tests (skip setInterval). */
@@ -115,7 +136,26 @@ export class PositionWatcher extends EventEmitter {
             if (!openSymbols.has(sym))
                 this.closePending.delete(sym);
         }
+        for (const sym of this.notifiedUnusableMark) {
+            if (!openSymbols.has(sym))
+                this.notifiedUnusableMark.delete(sym);
+        }
         for (const position of positions) {
+            // A position with a stop we CANNOT evaluate is unprotected, not healthy.
+            // Silence here is what let a breached stop run for 35h: the mark was a
+            // fabricated entryPrice fallback, isStopBreached read false, and the
+            // watcher skipped it every tick without ever saying so. Alarm instead.
+            if (hasEnforceableStop(position) && isMarkUnusable(position)) {
+                if (!this.notifiedUnusableMark.has(position.symbol)) {
+                    logger.error(TAG, `STOP UNENFORCEABLE: ${position.symbol} ${position.side} has stop=${position.stopPrice} ` +
+                        `but no usable mark (markPrice=${position.markPrice}` +
+                        `${position.markPriceStale ? ', stale/fabricated' : ''}). The position is running ` +
+                        'UNPROTECTED — the watcher cannot evaluate the breach. Check the quote feed for this symbol.');
+                    this.notifiedUnusableMark.add(position.symbol);
+                }
+                continue;
+            }
+            this.notifiedUnusableMark.delete(position.symbol);
             if (!isStopBreached(position))
                 continue;
             if (this.closePending.has(position.symbol))

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {
@@ -72,6 +72,7 @@
       "clear_exchange_credentials",
       "hl_provision_agent_wallet",
       "hl_agent_wallet_status",
+      "hl_submit_agent_approval",
       "get_bracket_config",
       "set_bracket_requirement"
     ]

package/package.json

@@ -1,38 +1,38 @@
-{
-  "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.22",
-  "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode \u00e2\u20ac\u201d it cannot trade real funds until you supply exchange credentials and walk the PAPER\u00e2\u2020\u2019MICRO_LIVE\u00e2\u2020\u2019LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw \u00e2\u20ac\u201d a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
-  "type": "module",
-  "main": "index.js",
-  "openclaw": {
-    "extensions": [
-      "./index.js"
-    ],
-    "compat": {
-      "pluginApi": ">=2026.6.0"
-    },
-    "build": {
-      "openclawVersion": "2026.6.11"
-    }
-  },
-  "files": [
-    "**/*",
-    "!scripts/**"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@reefclaw/shared": "0.1.4",
-    "ccxt": "4.5.37",
-    "json5": "2.2.3",
-    "ws": "8.21.1"
-  },
-  "scripts": {
-    "build": "node scripts/assemble.mjs",
-    "verify": "node scripts/verify-shared-contract.mjs",
-    "prepublishOnly": "node scripts/verify-shared-contract.mjs"
-  },
-  "license": "MIT",
-  "homepage": "https://reefclaw.com"
-}
+{
+  "name": "@reefclaw/openclaw-plugin",
+  "version": "0.1.24",
+  "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode — it cannot trade real funds until you supply exchange credentials and walk the PAPER→MICRO_LIVE→LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw — a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
+  "type": "module",
+  "main": "index.js",
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.6.0"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11"
+    }
+  },
+  "files": [
+    "**/*",
+    "!scripts/**"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@reefclaw/shared": "0.1.4",
+    "ccxt": "4.5.37",
+    "json5": "2.2.3",
+    "ws": "8.21.1"
+  },
+  "scripts": {
+    "build": "node scripts/assemble.mjs",
+    "verify": "node scripts/verify-shared-contract.mjs",
+    "prepublishOnly": "node scripts/verify-shared-contract.mjs"
+  },
+  "license": "MIT",
+  "homepage": "https://reefclaw.com"
+}

package/persistence/state-manager.d.ts

@@ -1,6 +1,7 @@
 import type { SimulatorState } from '../simulator/types.js';
 export declare class StateManager {
     private readonly statePath;
+    private lastLoadedStat?;
     private saveTimer;
     private pendingState;
     constructor(pluginId: string, baseDir?: string);
@@ -37,6 +38,12 @@ export declare class StateManager {
      *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
      *  (preserved), never silently overwritten by the default the caller seeds. */
     loadSync(): SimulatorState | null;
+    /** loadSync that returns null when the file is unchanged since the last
+     *  loadSync. The reload exists for the two-process case (another process
+     *  wrote the file); an unchanged file means the caller's replaceState would
+     *  be a no-op re-parse of the whole trade history — which grows with the
+     *  account's age and was being paid on every paper-mode tool call. */
+    loadSyncIfChanged(): SimulatorState | null;
     /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
     loadOrDefaultSync(startingBalance: number, quoteCurrency: string): SimulatorState;
     private saveSyncSafe;

package/persistence/state-manager.js

@@ -2,7 +2,7 @@
 // Saves/loads state to ~/.openclaw/plugins/reefclaw-paper-trading/state.json
 // Uses atomic writes (temp file + rename) to prevent corruption.
 import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -11,6 +11,7 @@ import { createDefaultState } from '../simulator/types.js';
 const TAG = 'state-manager';
 export class StateManager {
     statePath;
+    lastLoadedStat;
     saveTimer = null;
     pendingState = null;
     constructor(pluginId, baseDir) {
@@ -131,8 +132,17 @@ export class StateManager {
             return null;
         }
         try {
+            // Stat BEFORE read: a write racing in between then causes one extra
+            // reload next time, never a skipped-but-needed one.
+            let stat;
+            try {
+                const s = statSync(this.statePath, { bigint: true });
+                stat = { mtimeNs: s.mtimeNs, size: s.size };
+            }
+            catch { /* stat raced a delete — plain read below decides */ }
             const raw = readFileSync(this.statePath, 'utf-8');
             const state = JSON.parse(raw);
+            this.lastLoadedStat = stat;
             logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
             return state;
         }
@@ -141,6 +151,23 @@ export class StateManager {
             return null;
         }
     }
+    /** loadSync that returns null when the file is unchanged since the last
+     *  loadSync. The reload exists for the two-process case (another process
+     *  wrote the file); an unchanged file means the caller's replaceState would
+     *  be a no-op re-parse of the whole trade history — which grows with the
+     *  account's age and was being paid on every paper-mode tool call. */
+    loadSyncIfChanged() {
+        try {
+            const s = statSync(this.statePath, { bigint: true });
+            if (this.lastLoadedStat &&
+                this.lastLoadedStat.mtimeNs === s.mtimeNs &&
+                this.lastLoadedStat.size === s.size) {
+                return null;
+            }
+        }
+        catch { /* missing/unstatable — loadSync handles + logs it */ }
+        return this.loadSync();
+    }
     /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
     loadOrDefaultSync(startingBalance, quoteCurrency) {
         const loaded = this.loadSync();

package/simulator/exchange-simulator.d.ts

@@ -1,6 +1,28 @@
 import { EventEmitter } from 'node:events';
 import type { SimulatorState, OrderBookDepth, SimulationConfig, ExecutionStats, PositionMetadata, CloseReason } from './types.js';
 import type { CcxtOrder, CcxtBalance, CcxtPosition, CcxtTicker } from '../types.js';
+/** Canonical key for the per-symbol quote/orderbook caches and for matching a
+ *  ticker against stored positions/orders.
+ *
+ *  CCXT echoes the VENUE-UNIFIED symbol back from fetchTicker: ask Binance USDM
+ *  for 'ETH/USDT' and the ticker returns as 'ETH/USDT:USDT'. Positions and
+ *  orders, however, are stored under whatever form the caller opened them with,
+ *  so `lastTicker.get(position.symbol)` silently missed for every position held
+ *  in the un-suffixed form. The consequences were all silent:
+ *    - getPositions()/computeEquity() fell back to entryPrice, so the mark was
+ *      FROZEN at entry — the stop-watcher compared a frozen mark, never saw a
+ *      breach, and the position ran unprotected past its stop indefinitely;
+ *    - createOrder() threw 'No ticker data for X' on the market leg, so the
+ *      agent could not close by hand either (both automatic and manual exits
+ *      were dead at once);
+ *    - MFE, take-profit legs and resting-limit fills never advanced.
+ *  Keying both sides through this normalizer makes the caches format-agnostic,
+ *  which also repairs books already persisted with a mix of both forms.
+ *
+ *  Same regex as webapp/src/lib/symbols.ts normalizeSymbol and
+ *  plugin/src/venues/symbols.ts stripSettleSuffix — kept inline so the
+ *  simulator keeps its zero-import-for-hot-path shape. */
+export declare function tickerKey(symbol: string): string;
 export declare class ExchangeSimulator extends EventEmitter {
     private state;
     private lastTicker;