@reefclaw/openclaw-plugin 0.1.23 → 0.1.25

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/portfolio/directional-scoreboard.d.ts

@@ -0,0 +1,17 @@
+import type { ReentryExitRecord } from './reentry-tracker.js';
+export interface ScoreboardInputs {
+    /** Tracked open positions on the current book (state store, not exchange). */
+    openPositions: Array<{
+        side: 'long' | 'short';
+    }>;
+    /** Tracker exit records, oldest first (as stored). */
+    exitRecords: readonly ReentryExitRecord[];
+    book: 'paper' | 'live';
+    /** e.g. "BTC 4h −2.4% (−2.3×ATR)" — from the leader fact's changeOfCharacter. */
+    tapeLine?: string;
+    /** How many recent closes to summarize. */
+    lastN?: number;
+}
+/** Build the scoreboard line, or undefined when there is nothing to show
+ *  (no open positions AND no recent closes on this book). */
+export declare function buildDirectionalScoreboard(inputs: ScoreboardInputs): string | undefined;

package/portfolio/directional-scoreboard.js

@@ -0,0 +1,71 @@
+// Directional scoreboard — WS2 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// One compact line of counter-evidence attached to the entry funnel
+// (scan_pairs): the book's current directional tilt, how the last N closes
+// per direction actually went, and what the market-leader tape did — the
+// three facts an anchored agent never sees together. Pure indication: it
+// never blocks or vetoes anything (that is the refuted-ledger's territory).
+//
+// Data sources are all local + free: the PositionStateStore (tracked open
+// positions — no exchange round-trip, so no HL address-budget cost) and the
+// ReentryTracker exit records (persisted; realizedR/realizedPnl where a
+// source had them). The tape line comes from the market leader's
+// change-of-character block on the intel facts the caller already fetched.
+const emptyStats = () => ({
+    wins: 0, losses: 0, unknown: 0, pnl: 0, pnlKnown: false, rSum: 0, rKnown: false,
+});
+function fmtDir(label, s) {
+    const n = s.wins + s.losses + s.unknown;
+    if (n === 0)
+        return undefined;
+    let out = `${label} ${s.wins}W/${s.losses}L${s.unknown > 0 ? `/${s.unknown}?` : ''}`;
+    if (s.rKnown)
+        out += ` ${s.rSum >= 0 ? '+' : ''}${Math.round(s.rSum * 100) / 100}R`;
+    else if (s.pnlKnown) {
+        const abs = Math.round(Math.abs(s.pnl) * 100) / 100;
+        out += ` ${s.pnl >= 0 ? '+' : '-'}$${abs}`;
+    }
+    return out;
+}
+/** Build the scoreboard line, or undefined when there is nothing to show
+ *  (no open positions AND no recent closes on this book). */
+export function buildDirectionalScoreboard(inputs) {
+    const lastN = inputs.lastN ?? 8;
+    const longs = inputs.openPositions.filter((p) => p.side === 'long').length;
+    const shorts = inputs.openPositions.filter((p) => p.side === 'short').length;
+    // Newest-first walk over this book's records (legacy untagged match either).
+    const recent = [];
+    for (let i = inputs.exitRecords.length - 1; i >= 0 && recent.length < lastN; i--) {
+        const r = inputs.exitRecords[i];
+        if (r.mode && r.mode !== inputs.book)
+            continue;
+        recent.push(r);
+    }
+    if (longs + shorts === 0 && recent.length === 0)
+        return undefined;
+    const stats = { long: emptyStats(), short: emptyStats() };
+    for (const r of recent) {
+        const s = stats[r.side];
+        if (r.wasLoss === true)
+            s.losses++;
+        else if (r.wasLoss === false)
+            s.wins++;
+        else
+            s.unknown++;
+        if (typeof r.realizedPnl === 'number' && Number.isFinite(r.realizedPnl)) {
+            s.pnl += r.realizedPnl;
+            s.pnlKnown = true;
+        }
+        if (typeof r.realizedR === 'number' && Number.isFinite(r.realizedR)) {
+            s.rSum += r.realizedR;
+            s.rKnown = true;
+        }
+    }
+    const parts = [`book: ${longs}L/${shorts}S open`];
+    const closeBits = [fmtDir('longs', stats.long), fmtDir('shorts', stats.short)].filter((v) => v !== undefined);
+    if (closeBits.length > 0)
+        parts.push(`last ${recent.length} closes: ${closeBits.join(', ')}`);
+    if (inputs.tapeLine)
+        parts.push(`tape: ${inputs.tapeLine}`);
+    return parts.join(' · ');
+}

package/portfolio/reentry-tracker.d.ts

@@ -4,8 +4,24 @@ export interface ReentryExitRecord {
     /** 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). */
+    /** Whether the closed trade realized a loss (drives the stronger caution
+     *  and arms the reentryCooldown gate). */
     wasLoss?: boolean;
+    /** Where the wasLoss sign came from, for auditing sign-accuracy before the
+     *  cooldown gate is promoted past shadow: engine-exact ('paper_engine',
+     *  'ws_fill') vs the agent's own close assessment ('assessment_r'). */
+    lossSource?: 'paper_engine' | 'assessment_r' | 'ws_fill';
+    /** Trading book at close time. The cooldown gate filters to the current
+     *  book so a paper loss can't cool down a live entry after a mode flip.
+     *  Legacy records (absent) match either book — they age out of any
+     *  realistic cooldown window within the hour anyway. */
+    mode?: 'paper' | 'live';
+    /** Realized R at close where a source had it (agent assessment on live
+     *  tool-closes). Feeds the WS2 directional scoreboard. */
+    realizedR?: number;
+    /** Realized net PnL (quote ccy) where engine/exchange-exact (paper engine,
+     *  WS bracket fills). Feeds the WS2 directional scoreboard. */
+    realizedPnl?: number;
     closedAtMs: number;
 }
 /** Signal-bar duration for a strategy/setup name. Name-suffix inference:
@@ -26,6 +42,27 @@ export declare class ReentryTracker {
     /** 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;
+    /** Most recent LOSSY exit for `symbol` within `windowMs`, or undefined.
+     *  Feeds the reentryCooldown gate (evidence 2026-09-02: 58 re-entries within
+     *  60m of a same-symbol losing close ran −0.077R mean vs +0.090R baseline).
+     *  Any direction, any setup — the measured pathology is symbol churn, not
+     *  setup churn. `mode` filters to the current trading book; records without
+     *  a mode tag (pre-upgrade) match either book. */
+    lastLossyExit(symbol: string, windowMs: number, opts?: {
+        mode?: 'paper' | 'live';
+        nowMs?: number;
+    }): ReentryExitRecord | undefined;
+    /** Trailing consecutive LOSSY closes on `book`, newest first, across ALL
+     *  symbols — the live feed for the graduated loss-streak sizing brake in
+     *  preTradeRiskCheck (WS1, docs/MARKET_ADAPTIVITY_PLAN.md §3; live was fed a
+     *  hardcoded 0 since the beginning while paper computed it from engine
+     *  history). Semantics: a WIN breaks the streak, and so does an
+     *  UNKNOWN-outcome record (wasLoss undefined) — unknown is never counted as
+     *  a loss, and stopping there under-counts, which only makes the brake
+     *  gentler. Records from the OTHER book are skipped entirely (a paper loss
+     *  neither extends nor breaks a live streak); legacy untagged records match
+     *  either book, same as lastLossyExit. */
+    consecutiveLosses(book: 'paper' | 'live'): number;
     /** 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. */

package/portfolio/reentry-tracker.js

@@ -98,6 +98,55 @@ export class ReentryTracker {
         }
         return bySetup ?? bySymbol;
     }
+    /** Most recent LOSSY exit for `symbol` within `windowMs`, or undefined.
+     *  Feeds the reentryCooldown gate (evidence 2026-09-02: 58 re-entries within
+     *  60m of a same-symbol losing close ran −0.077R mean vs +0.090R baseline).
+     *  Any direction, any setup — the measured pathology is symbol churn, not
+     *  setup churn. `mode` filters to the current trading book; records without
+     *  a mode tag (pre-upgrade) match either book. */
+    lastLossyExit(symbol, windowMs, opts) {
+        const key = normalizeBracketSymbol(symbol);
+        const now = opts?.nowMs ?? Date.now();
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.symbol !== key)
+                continue;
+            if (r.wasLoss !== true)
+                continue;
+            if (opts?.mode && r.mode && r.mode !== opts.mode)
+                continue;
+            const ageMs = now - r.closedAtMs;
+            // Tolerate small clock skew on exchange timestamps (up to 60s in the
+            // future still counts as "just closed").
+            if (ageMs >= -60_000 && ageMs <= windowMs)
+                return r;
+        }
+        return undefined;
+    }
+    /** Trailing consecutive LOSSY closes on `book`, newest first, across ALL
+     *  symbols — the live feed for the graduated loss-streak sizing brake in
+     *  preTradeRiskCheck (WS1, docs/MARKET_ADAPTIVITY_PLAN.md §3; live was fed a
+     *  hardcoded 0 since the beginning while paper computed it from engine
+     *  history). Semantics: a WIN breaks the streak, and so does an
+     *  UNKNOWN-outcome record (wasLoss undefined) — unknown is never counted as
+     *  a loss, and stopping there under-counts, which only makes the brake
+     *  gentler. Records from the OTHER book are skipped entirely (a paper loss
+     *  neither extends nor breaks a live streak); legacy untagged records match
+     *  either book, same as lastLossyExit. */
+    consecutiveLosses(book) {
+        let n = 0;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.mode && r.mode !== book)
+                continue;
+            if (r.wasLoss === true) {
+                n++;
+                continue;
+            }
+            break; // win or unknown outcome ends the trailing streak
+        }
+        return n;
+    }
     /** 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. */

package/signals/change-of-character.d.ts

@@ -0,0 +1,38 @@
+/** 30m move ≥ this ×ATR(1h) ⇒ 'shock'. */
+export declare const SHOCK_ATR_MULT_30M = 2;
+/** 4h tape opposing a directional regime label by ≥ this ×ATR(1h) ⇒ 'regime_tape_disagreement'. */
+export declare const DISAGREEMENT_ATR_MULT_4H = 2;
+export type ChangeOfCharacterFlag = 'shock' | 'regime_tape_disagreement';
+export interface ChangeOfCharacter {
+    /** |price now − close ~30m ago| ÷ ATR(1h). */
+    shock30mAtr: number;
+    /** (max high − min low) over the last ~30m ÷ ATR(1h) — catches a spike-and-revert the close-to-close move misses. */
+    range30mAtr: number;
+    /** % return vs the close ~1h ago. */
+    return1hPct: number;
+    /** % return vs the close ~4h ago. */
+    return4hPct: number;
+    /** Signed (price now − close ~4h ago) ÷ ATR(1h) — the tape the regime label must answer to. */
+    tape4hAtr: number;
+    /** ATR(1h) as % of price — the volatility yardstick the multiples are in. */
+    atrPct: number;
+    flags: ChangeOfCharacterFlag[];
+    /** Agent-facing one-liner. Present ONLY when a flag fired — silence stays silent. */
+    summary?: string;
+}
+interface BarLike {
+    high: number;
+    low: number;
+    close: number;
+}
+export interface ChangeOfCharacterInputs {
+    /** 5m bars, oldest first (≥7 required). */
+    ohlcv5m: BarLike[];
+    /** 1h bars, oldest first (≥5 required). */
+    ohlcv1h: BarLike[];
+    atr14: number;
+    currentPrice: number;
+    regime: string;
+}
+export declare function computeChangeOfCharacter(inputs: ChangeOfCharacterInputs): ChangeOfCharacter | undefined;
+export {};

package/signals/change-of-character.js

@@ -0,0 +1,93 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/change-of-character.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+// Change-of-character detection — WS2 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// The 2026-09 adaptivity investigation found the agent keeps trading a stale
+// directional view after event-driven regime flips because (a) the regime
+// label is computed from realized bars and lags a shock by hours, and (b) no
+// input ever shows it the contradiction. This module computes the two fast
+// counter-evidence facts from data the fact-computer already has in hand —
+// NO new DB queries (the intel hot-query chunk-exclusion rule is not in play):
+//
+//   - SHOCK: the last ~30 minutes moved a multiple of the hourly ATR. An
+//     hourly ATR is roughly "a typical hour's range", so 2×ATR inside 30m is
+//     ~4× the typical rate — announcement territory.
+//   - REGIME/TAPE DISAGREEMENT: the regime label says TREND_UP (or DOWN) but
+//     the realized 4h tape moved ≥2×ATR the other way — the label is lagging.
+//
+// Pure function, deterministic, fail-open: insufficient bars or a degenerate
+// ATR returns undefined and every consumer treats that as "no signal".
+// Thresholds are exported so the soak can be re-cut without archaeology.
+// Canonical copy lives in shared/src/signals/ and is synced to
+// intelligence/ + plugin/ via scripts/sync-shared-code.mjs (drift-tested).
+/** 30m move ≥ this ×ATR(1h) ⇒ 'shock'. */
+export const SHOCK_ATR_MULT_30M = 2.0;
+/** 4h tape opposing a directional regime label by ≥ this ×ATR(1h) ⇒ 'regime_tape_disagreement'. */
+export const DISAGREEMENT_ATR_MULT_4H = 2.0;
+const fin = (v) => Number.isFinite(v);
+const round2 = (v) => Math.round(v * 100) / 100;
+export function computeChangeOfCharacter(inputs) {
+    const { ohlcv5m, ohlcv1h, atr14, currentPrice, regime } = inputs;
+    if (!fin(atr14) || atr14 <= 0 || !fin(currentPrice) || currentPrice <= 0)
+        return undefined;
+    if (!Array.isArray(ohlcv5m) || ohlcv5m.length < 7)
+        return undefined;
+    if (!Array.isArray(ohlcv1h) || ohlcv1h.length < 5)
+        return undefined;
+    // ~30m window = last 6 closed 5m bars; the reference close sits just before it.
+    const last6 = ohlcv5m.slice(-6);
+    const ref30m = ohlcv5m[ohlcv5m.length - 7].close;
+    const ref1h = ohlcv1h[ohlcv1h.length - 2].close;
+    const ref4h = ohlcv1h[ohlcv1h.length - 5].close;
+    if (!fin(ref30m) || ref30m <= 0 || !fin(ref1h) || ref1h <= 0 || !fin(ref4h) || ref4h <= 0) {
+        return undefined;
+    }
+    const shock30mAtr = Math.abs(currentPrice - ref30m) / atr14;
+    const hi30 = Math.max(...last6.map((b) => b.high));
+    const lo30 = Math.min(...last6.map((b) => b.low));
+    const range30mAtr = fin(hi30) && fin(lo30) && hi30 >= lo30 ? (hi30 - lo30) / atr14 : 0;
+    const return1hPct = (currentPrice / ref1h - 1) * 100;
+    const return4hPct = (currentPrice / ref4h - 1) * 100;
+    const tape4hAtr = (currentPrice - ref4h) / atr14;
+    const atrPct = (atr14 / currentPrice) * 100;
+    const flags = [];
+    if (Math.max(shock30mAtr, range30mAtr) >= SHOCK_ATR_MULT_30M)
+        flags.push('shock');
+    const labelDir = regime === 'TREND_UP' ? 1 : regime === 'TREND_DOWN' ? -1 : 0;
+    const opposing = labelDir !== 0 && Math.sign(tape4hAtr) === -labelDir;
+    if (opposing && Math.abs(tape4hAtr) >= DISAGREEMENT_ATR_MULT_4H) {
+        flags.push('regime_tape_disagreement');
+    }
+    const out = {
+        shock30mAtr: round2(shock30mAtr),
+        range30mAtr: round2(range30mAtr),
+        return1hPct: round2(return1hPct),
+        return4hPct: round2(return4hPct),
+        tape4hAtr: round2(tape4hAtr),
+        atrPct: round2(atrPct),
+        flags,
+    };
+    if (flags.length > 0)
+        out.summary = buildSummary(out, regime);
+    return out;
+}
+function buildSummary(c, regime) {
+    const parts = [];
+    if (c.flags.includes('shock')) {
+        parts.push(`SHOCK: last 30m moved ${round2(Math.max(c.shock30mAtr, c.range30mAtr))}×ATR ` +
+            `(${c.return1hPct >= 0 ? '+' : ''}${c.return1hPct}% on the hour)`);
+    }
+    if (c.flags.includes('regime_tape_disagreement')) {
+        parts.push(`regime label '${regime}' contradicts the 4h tape ` +
+            `(${c.tape4hAtr >= 0 ? '+' : ''}${c.tape4hAtr}×ATR / ` +
+            `${c.return4hPct >= 0 ? '+' : ''}${c.return4hPct}%) — the label LAGS realized price`);
+    }
+    return (`MARKET SHIFT — ${parts.join('; ')}. Re-derive direction from fresh price data ` +
+        `before entering; on open positions, check the pinned invalidation FIRST and do not ` +
+        `lean on prior theses formed before this move.`);
+}

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;
@@ -54,7 +76,11 @@ export declare class ExchangeSimulator extends EventEmitter {
      *  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;
+    referencePrice?: number, 
+    /** Set ONLY by closePosition for mechanical/operator-initiated exits —
+     *  exempts them from the startup lockout. Never reachable from the
+     *  agent-facing create_order path. */
+    protectiveExit?: boolean): CcxtOrder;
     cancelOrder(orderId: string): CcxtOrder;
     cancelAllOrders(symbol?: string): CcxtOrder[];
     /**