@reefclaw/openclaw-plugin 0.1.25 → 0.1.27

package/paper-adapter.js

@@ -25,17 +25,25 @@ export class PaperAdapter {
     async closePosition(symbol, closeReason) {
         return this.simulator.closePosition(symbol, closeReason);
     }
+    // Reads pull a newer state.json first (ExchangeSimulator.refreshState —
+    // no-op without a hook). Out-of-tool readers (DB-vs-exchange sweep,
+    // stop-watcher) otherwise see a stale book in the process that did not
+    // execute the entry and post false synthetic closes / phantom stop fills.
     async getBalance() {
+        this.simulator.refreshState();
         return this.simulator.getBalance();
     }
     async getPositions(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getPositions(symbol);
     }
     /** Paper has no exchange fetch to fail — position state is always known. */
     async getPositionsOrNull(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getPositions(symbol);
     }
     async getOpenOrders(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getOpenOrders(symbol);
     }
     async fetchOrder(orderId, _symbol) {

package/signals/types.js

@@ -1,6 +1,6 @@
 // Re-export shim for the plugin-side strategy evaluator (facts-out).
 //
-// The generated eval-core copies (registry, strategy-adapter, direction/entry/
+// The generated evaluator-core copies (registry, strategy-adapter, direction/entry/
 // stop-rules) import their types from `./types.js`. The canonical definitions
 // live in @reefclaw/shared (type-only → erased at runtime), so this shim makes
 // those relative imports resolve inside the plugin tree without pulling any

package/simulator/exchange-simulator.d.ts

@@ -63,6 +63,13 @@ export declare class ExchangeSimulator extends EventEmitter {
      *  on open and is released on close, so we must add it back here. */
     computeEquity(): number;
     private getQuoteCurrency;
+    private stateRefresher;
+    /** Install the "reload state.json if it changed" hook (index.ts reloadState). */
+    setStateRefresher(fn: (() => void) | null): void;
+    /** Pull a newer on-disk snapshot before an out-of-tool read. No-op when no
+     *  hook is installed (tests / single-process). Never throws — a failed
+     *  reload leaves the current in-memory book in place. */
+    refreshState(): void;
     getBalance(): CcxtBalance;
     getPositions(symbol?: string): CcxtPosition[];
     getOpenOrders(symbol?: string): CcxtOrder[];

package/simulator/exchange-simulator.js

@@ -153,6 +153,36 @@ export class ExchangeSimulator extends EventEmitter {
     getQuoteCurrency() {
         return this.state.config?.quoteCurrency ?? 'USDT';
     }
+    // ---- Cross-process refresh (two-process architecture) ----
+    //
+    // The agent and gateway processes each hold their own ExchangeSimulator and
+    // share state through state.json. Every paper TOOL path calls index.ts
+    // reloadState() before reading, but out-of-tool readers (the periodic
+    // DB-vs-exchange sweep, the stop-watcher's 3s poll) read the adapter
+    // directly — and a process that did NOT execute the entry then sees a
+    // stale in-memory book. On 2026-09-14 that posted a synthetic
+    // `reconciler_observed_flat` close 5–100s after EVERY entry on a paying
+    // tenant's box while the engine kept the position alive for hours. The
+    // hook lives on the simulator (not the adapter) so every PaperAdapter ever
+    // built from it — boot or any reconnect path — inherits it.
+    stateRefresher = null;
+    /** Install the "reload state.json if it changed" hook (index.ts reloadState). */
+    setStateRefresher(fn) {
+        this.stateRefresher = fn;
+    }
+    /** Pull a newer on-disk snapshot before an out-of-tool read. No-op when no
+     *  hook is installed (tests / single-process). Never throws — a failed
+     *  reload leaves the current in-memory book in place. */
+    refreshState() {
+        if (!this.stateRefresher)
+            return;
+        try {
+            this.stateRefresher();
+        }
+        catch (err) {
+            logger.warn(TAG, `state refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // ---- Read operations (for tools) ----
     getBalance() {
         const free = {};

package/simulator/types.d.ts

@@ -150,7 +150,7 @@ export interface PositionMetadata {
     /** The agent's stated profit-realization plan, pinned at entry (indication,
      *  not an enforced mechanic). */
     realizationRule?: RealizationRule;
-    /** Re-entry cooldown gate eval, present ONLY when the gate TRIGGERED on this
+    /** Re-entry cooldown gate evaluation, present ONLY when the gate TRIGGERED on this
      *  entry (a same-symbol loss within the window) and the order fired anyway
      *  (shadow/observe). Journaled to position_entries.metadata.reentry_cooldown
      *  so the shadow soak can measure the would-block cohort's forward outcomes

package/tools/create-order.js

@@ -1113,7 +1113,7 @@ export async function createOrderTool(args, deps) {
             const n = num(v);
             return n != null ? Math.max(min, Math.min(max, n)) : undefined;
         };
-        // Journal-tag a TRIGGERED cooldown eval (shadow/observe fire-anyway cohort —
+        // Journal-tag a TRIGGERED cooldown evaluation (shadow/observe fire-anyway cohort —
         // the measurement rows the promote-to-enforce decision reads).
         const reentryCooldownTag = reentryCooldownEval?.triggered
             ? {

package/tools/reentry-cooldown.js

@@ -22,8 +22,8 @@
 // Mode semantics mirror the exit gate (docs/CLAUDE/exit-gate.md):
 //   off     — not evaluated; byte-identical to the pre-gate path.
 //   shadow  — evaluated + logged + journal-tagged; never affects the order.
-//   observe — as shadow, but a triggered eval logs at WARN (operator-visible).
-//   enforce — a triggered eval hard-rejects create_order with a recovery hint.
+//   observe — as shadow, but a triggered evaluation logs at WARN (operator-visible).
+//   enforce — a triggered evaluation hard-rejects create_order with a recovery hint.
 export function evaluateReentryCooldown(inputs) {
     const base = {
         mode: inputs.mode,