@reefclaw/openclaw-plugin 0.1.14 → 0.1.16

package/bridge/providers/risk-calculator.js

@@ -43,11 +43,62 @@ export function applyRegimeAdjustment(baseLimits, regime) {
     };
 }
 // ---- Drawdown zone thresholds ----
+/** Fallback zone boundaries, used only until the tenant's trading params load.
+ *  The AUTHORITATIVE values are the operator's `drawdownYellow/Orange/Red`
+ *  trading params — the same numbers the plugin's pre-trade gate rejects on.
+ *  Keeping a second hardcoded ladder here is how the skill ended up
+ *  auto-flattening at -2.5% on an account configured to -4%. */
 export const DRAWDOWN_ZONE_THRESHOLDS = {
     YELLOW: -0.01, // -1%
     ORANGE: -0.02, // -2%
     RED: -0.025, // -2.5%
 };
+// ---- Hardcoded bounds on tenant-supplied risk params ----
+//
+// CLAUDE.md load-bearing rule: central config may move knobs only WITHIN
+// hardcoded bounds — it must never be able to disable a safety mechanism.
+// The RED threshold drives the auto-flatten, so without a floor a single
+// careless dashboard edit (drawdownRed = -0.5) would silently switch the
+// auto-flatten off. Out-of-band values are REJECTED (keep last-good), not
+// clamped — we never invent a threshold the operator didn't set.
+/** The auto-flatten trigger can never be configured looser than −10%. */
+export const AUTO_FLATTEN_RED_FLOOR = -0.10;
+/** Sanity bands for tenant limit fields. Values outside → field ignored,
+ *  previous value kept. Wide on purpose: these reject nonsense, not policy. */
+export const TENANT_LIMIT_BOUNDS = {
+    maxPositionSize: { min: 1, max: 1e9 },
+    maxOpenPositions: { min: 1, max: 100 },
+    maxGrossExposure: { min: 0.01, max: 20 },
+    maxPerTradeLoss: { min: 0.01, max: 1e7 }, // magnitude; sign applied by caller
+};
+/** Finite number within [min, max], else null. */
+export function boundedNum(v, min, max) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return null;
+    return v >= min && v <= max ? v : null;
+}
+/**
+ * Validate a tenant drawdown-zone ladder. Returns null when acceptable, else
+ * a human-readable reason. Requirements: all finite; YELLOW ≤ 0 (zones are
+ * losses); strictly monotonic YELLOW > ORANGE > RED (a scrambled ladder would
+ * put the book straight into RED and auto-flatten it); RED no looser than
+ * AUTO_FLATTEN_RED_FLOOR.
+ */
+export function validateDrawdownLadder(t) {
+    for (const [k, v] of Object.entries(t)) {
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            return `${k} is not a finite number`;
+    }
+    if (t.YELLOW > 0)
+        return `YELLOW ${t.YELLOW} must be ≤ 0`;
+    if (!(t.YELLOW > t.ORANGE && t.ORANGE > t.RED)) {
+        return `not monotonic (need YELLOW > ORANGE > RED, got ${t.YELLOW} / ${t.ORANGE} / ${t.RED})`;
+    }
+    if (t.RED < AUTO_FLATTEN_RED_FLOOR) {
+        return `RED ${t.RED} is looser than the hardcoded auto-flatten floor ${AUTO_FLATTEN_RED_FLOOR}`;
+    }
+    return null;
+}
 // ---- Rate tracking window ----
 const RATE_WINDOW_MS = 60_000; // 1 minute
 // ---- Volatility + drawdown pure functions ----
@@ -73,12 +124,12 @@ export function applyVolatilityAdjustment(baseLimits, volFactor) {
     };
 }
 /** Determine drawdown zone from drawdown ratio (e.g. -0.015 = -1.5%). */
-export function getDrawdownZone(drawdownRatio) {
-    if (drawdownRatio <= DRAWDOWN_ZONE_THRESHOLDS.RED)
+export function getDrawdownZone(drawdownRatio, thresholds = DRAWDOWN_ZONE_THRESHOLDS) {
+    if (drawdownRatio <= thresholds.RED)
         return 'RED';
-    if (drawdownRatio <= DRAWDOWN_ZONE_THRESHOLDS.ORANGE)
+    if (drawdownRatio <= thresholds.ORANGE)
         return 'ORANGE';
-    if (drawdownRatio <= DRAWDOWN_ZONE_THRESHOLDS.YELLOW)
+    if (drawdownRatio <= thresholds.YELLOW)
         return 'YELLOW';
     return 'GREEN';
 }
@@ -143,10 +194,22 @@ export function countRecentEvents(timestamps) {
 }
 /**
  * Detect risk limit breaches from current metrics.
+ *
+ * ★ CRITICAL is reserved for the limits that are ACTUALLY ENFORCED — the
+ * tenant's trading params, which the plugin's `preTradeRiskCheck` rejects
+ * orders against (`plugin/src/risk/pre-trade-check.ts`). A red "Gate fail" on
+ * the dashboard must mean "the agent is being blocked right now".
+ *
+ * `advisoryLimits` carries the vol/regime-TIGHTENED view. Those multipliers
+ * live only in this file — no enforcer applies them — so they may raise a
+ * WARNING (amber, indication) but must never produce a CRITICAL. Conflating
+ * the two is what put a permanent red "Gate fail · Gross exposure 121%" on a
+ * live book whose 1.5x enforced limit was never even approached.
  */
-export function detectBreaches(metrics, limits) {
+export function detectBreaches(metrics, limits, advisoryLimits) {
     const breaches = [];
     const now = new Date().toISOString();
+    const advisory = advisoryLimits ?? limits;
     // Gross exposure
     if (metrics.grossExposure > limits.position.maxGrossExposure) {
         breaches.push({
@@ -158,10 +221,11 @@ export function detectBreaches(metrics, limits) {
             timestamp: now,
         });
     }
-    else if (metrics.grossExposure > limits.position.maxGrossExposure * 0.8) {
+    else if (metrics.grossExposure > advisory.position.maxGrossExposure ||
+        metrics.grossExposure > limits.position.maxGrossExposure * 0.8) {
         breaches.push({
             metric: 'grossExposure',
-            limit: limits.position.maxGrossExposure,
+            limit: Math.min(advisory.position.maxGrossExposure, limits.position.maxGrossExposure),
             current: metrics.grossExposure,
             level: 'WARNING',
             action: 'ALERT',
@@ -179,10 +243,11 @@ export function detectBreaches(metrics, limits) {
             timestamp: now,
         });
     }
-    else if (Math.abs(metrics.netExposure) > limits.position.maxNetExposure * 0.8) {
+    else if (Math.abs(metrics.netExposure) > advisory.position.maxNetExposure ||
+        Math.abs(metrics.netExposure) > limits.position.maxNetExposure * 0.8) {
         breaches.push({
             metric: 'netExposure',
-            limit: limits.position.maxNetExposure,
+            limit: Math.min(advisory.position.maxNetExposure, limits.position.maxNetExposure),
             current: metrics.netExposure,
             level: 'WARNING',
             action: 'ALERT',
@@ -270,8 +335,12 @@ export function computeRiskMetrics(state) {
     // Prune and count rate events (non-mutating)
     const orderResult = countRecentEvents(state.orderTimestamps);
     const cancelResult = countRecentEvents(state.cancelTimestamps);
+    // Enforced limits: the tenant's configured trading params when they've been
+    // fetched, else the fallback constants. These are what the plugin's
+    // pre-trade gate rejects on, so they — and only they — drive CRITICAL.
+    const enforcedLimits = state.baseLimits ?? DEFAULT_RISK_LIMITS;
     // Volatility adjustment (when ATR data is available)
-    let adjustedLimits = DEFAULT_RISK_LIMITS;
+    let adjustedLimits = enforcedLimits;
     let effectiveLimits;
     let volatilityInfo;
     let volFactor = 1.0;
@@ -279,7 +348,7 @@ export function computeRiskMetrics(state) {
         volFactor = computeVolFactor(state.atrData);
         const adjusted = volFactor > 1.0;
         if (adjusted) {
-            adjustedLimits = applyVolatilityAdjustment(DEFAULT_RISK_LIMITS, volFactor);
+            adjustedLimits = applyVolatilityAdjustment(enforcedLimits, volFactor);
         }
         volatilityInfo = {
             atr14: state.atrData.currentAtr,
@@ -305,14 +374,17 @@ export function computeRiskMetrics(state) {
             };
         }
     }
-    if (adjustedLimits !== DEFAULT_RISK_LIMITS) {
+    if (adjustedLimits !== enforcedLimits) {
         effectiveLimits = adjustedLimits;
     }
-    // Drawdown zone
-    const drawdownZone = getDrawdownZone(dailyDrawdown);
+    // Drawdown zone — boundaries come from the tenant's trading params so the
+    // skill's RED-zone auto-flatten fires at the operator's configured level,
+    // not a second hardcoded ladder that can be stricter than the plugin's.
+    const zoneThresholds = state.drawdownThresholds ?? DRAWDOWN_ZONE_THRESHOLDS;
+    const drawdownZone = getDrawdownZone(dailyDrawdown, zoneThresholds);
     const drawdownZoneMessage = getDrawdownZoneMessage(drawdownZone, dailyDrawdown);
-    // Detect breaches using effective limits (vol + regime adjusted) when available
-    const limitsForBreaches = effectiveLimits ?? DEFAULT_RISK_LIMITS;
+    // Breaches: CRITICAL against the ENFORCED limits, WARNING against the
+    // vol/regime-tightened advisory view (see detectBreaches).
     const dailyLoss = state.realizedPnlToday ?? 0;
     const breaches = detectBreaches({
         grossExposure: grossRatio,
@@ -321,12 +393,12 @@ export function computeRiskMetrics(state) {
         dailyLoss,
         ordersPerMinute: orderResult.count,
         cancelsPerMinute: cancelResult.count,
-    }, limitsForBreaches);
+    }, enforcedLimits, effectiveLimits);
     // Add zone-specific breaches
     if (drawdownZone === 'ORANGE' || drawdownZone === 'RED') {
         breaches.push({
             metric: 'drawdownZone',
-            limit: drawdownZone === 'RED' ? DRAWDOWN_ZONE_THRESHOLDS.RED : DRAWDOWN_ZONE_THRESHOLDS.ORANGE,
+            limit: drawdownZone === 'RED' ? zoneThresholds.RED : zoneThresholds.ORANGE,
             current: dailyDrawdown,
             level: 'CRITICAL',
             action: drawdownZone === 'RED' ? 'AUTO_PAUSE' : 'REJECT_ORDER',
@@ -336,7 +408,7 @@ export function computeRiskMetrics(state) {
     else if (drawdownZone === 'YELLOW') {
         breaches.push({
             metric: 'drawdownZone',
-            limit: DRAWDOWN_ZONE_THRESHOLDS.YELLOW,
+            limit: zoneThresholds.YELLOW,
             current: dailyDrawdown,
             level: 'WARNING',
             action: 'ALERT',
@@ -345,7 +417,7 @@ export function computeRiskMetrics(state) {
     }
     return {
         metrics: {
-            limits: DEFAULT_RISK_LIMITS,
+            limits: enforcedLimits,
             utilization: {
                 currentPositionSize: positionSizes,
                 openPositionCount: state.positions.filter((p) => computePositionNotional(p, state.lastTickerPrice) !== 0).length,

package/bridge/utils/skill-signing.js

@@ -14,9 +14,14 @@
 //      (gitignored — keep it offline; NEVER on the relay or any server)
 //   4. rebuild + redeploy the skill (deploy-skillmd-ota.py is already wired to sign)
 //
-// Until a key is pinned, OTA is FAIL-CLOSED (every push rejected) while
-// SKILL_OTA_REQUIRE_SIGNATURE is on (the default). Normal trading is unaffected
-// — only the OTA-update path gates on this.
+// ENFORCEMENT IS CURRENTLY DORMANT: SKILL_OTA_REQUIRE_SIGNATURE defaults OFF
+// and no key is pinned (C1 is ON HOLD pending the agent-update-mechanism
+// decision — see signatureRequired() below). While dormant, OTA updates apply
+// unsigned exactly as before this module existed; the authenticated webapp
+// pull channel (rc_ token) remains the trust boundary. When the flag is turned
+// ON: a pinned key verifies every update, and flag-on-without-a-key FAILS
+// CLOSED (every push rejected). Normal trading is unaffected either way —
+// only the OTA-update path gates on this.
 import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';

package/config/plugin-config-io.js

@@ -5,6 +5,11 @@
 // sets credentials or switches trading mode from the webapp. Writes must be
 // crash-safe (no half-written JSON) and must preserve keys we don't understand
 // (forwards compatibility — other tools may add fields we don't know about).
+//
+// Write authorization: every mutation path into this module is an
+// operator-only tool gated on dashboard provenance (verifyOperatorProvenance,
+// audit F12) — the agent cannot reach these writes conversationally. The file
+// is the plugin's OWN config store; nothing here touches OpenClaw's config.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';

package/exchange-adapter.d.ts

@@ -28,6 +28,19 @@ export interface OrderOptions {
  * Only create_order is blocked when readiness !== 'READY'.
  */
 export interface IExchangeAdapter {
+    /**
+     * ★ Venue capability: this adapter's exchange-side protective legs ARE the
+     * safety floor — there is no watcher fallback and no `brackets.mode=off`
+     * arm, so brackets are attached unconditionally (Hyperliquid live).
+     *
+     * Read it wherever `brackets.mode` is consulted. That flag is a
+     * BINANCE-ONLY lifecycle knob (it is only ever passed to `LiveAdapter`), so
+     * treating it as the global answer made an HL rig report "Brackets off" on
+     * the dashboard AND — worse — skipped the mandatory-stop pre-trade gate,
+     * because that gate was wired behind `bracketsEnabled(loadBracketMode())`.
+     * Omitted/false on Binance + paper: byte-identical to the old behaviour.
+     */
+    readonly bracketsAlwaysEnforced?: boolean;
     createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
     cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
     cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;

package/index.js

@@ -816,6 +816,7 @@ const TOOL_PARAMS = {
     test_exchange_credentials: {
         type: 'object',
         properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
             apiKey: { type: 'string', description: 'Binance API key to verify (not persisted)' },
             secret: { type: 'string', description: 'Binance API secret to verify (not persisted)' },
             testnet: { type: 'boolean', description: 'Test against Binance testnet' },
@@ -2650,7 +2651,7 @@ const paperTradingPlugin = {
             {
                 name: 'set_trading_mode',
                 label: 'Set Trading Mode',
-                description: 'Operator-only. Move the plugin between PAPER / MICRO_LIVE / LIVE. Enforces the one-rung-at-a-time ladder. Refused without dashboard operator provenance.',
+                description: 'Operator-only. Move the plugin between PAPER / MICRO_LIVE / LIVE. Enforces the one-rung-at-a-time ladder. Briefly reconnects the trading adapter (open positions keep their exchange-side protective brackets throughout). Refused without dashboard operator provenance.',
                 parameters: TOOL_PARAMS.set_trading_mode,
                 execute: async (_id, params) => {
                     const prov = verifyOperatorProvenance(params.operator_token);
@@ -2662,9 +2663,17 @@ const paperTradingPlugin = {
             {
                 name: 'test_exchange_credentials',
                 label: 'Test Exchange Credentials',
-                description: 'Operator-only. Verify a Binance API key + secret with a read-only call (fetchBalance) without persisting anything. Used by the dashboard pre-flight check before set_exchange_credentials. Never called by the agent.',
+                description: 'Operator-only. Verify a Binance API key + secret with a read-only call (fetchBalance) without persisting anything. Used by the dashboard pre-flight check before set_exchange_credentials. Refused without dashboard operator provenance.',
                 parameters: TOOL_PARAMS.test_exchange_credentials,
-                execute: async (_id, params) => jsonResult(await testExchangeCredentialsTool(params)),
+                // Read-only, but provenance-gated anyway: it makes a live authenticated
+                // exchange call with caller-supplied keys, which would otherwise hand a
+                // prompt-injected agent a credential-validation oracle.
+                execute: async (_id, params) => {
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await testExchangeCredentialsTool(params));
+                },
             },
             {
                 name: 'clear_exchange_credentials',
@@ -2683,7 +2692,9 @@ const paperTradingPlugin = {
                 label: 'Get Bracket Config',
                 description: 'Operator-only. Returns the current bracket-orders configuration (mode + requireStopLoss + requireTakeProfit). Used by the dashboard Trading Parameters panel.',
                 parameters: TOOL_PARAMS.get_bracket_config,
-                execute: async () => jsonResult(getBracketConfigTool({})),
+                // Adapter read at execute time (not registration) so a PAPER→HL-live
+                // swap changes the reported protection without a restart.
+                execute: async () => jsonResult(getBracketConfigTool({}, { adapter: runtime.adapter })),
             },
             {
                 name: 'set_bracket_requirement',

package/ingest/event-loop-monitor.d.ts

@@ -7,5 +7,16 @@ export declare function startEventLoopMonitor(): void;
  *  The histogram stores nanoseconds; `max` is Infinity-safe but can read as a
  *  sentinel before the first sample lands, so anything non-finite → null. */
 export declare function sampleEventLoopDelayMs(): number | null;
+/** Time (ms) this process spent waiting for a CPU since the previous call, then
+ *  re-baselines — so consecutive calls partition the timeline into the SAME
+ *  non-overlapping windows as `sampleEventLoopDelayMs`, and the two readings of
+ *  one cycle describe one window.
+ *
+ *  ★ Call this EVERY cycle, not only when a stall was observed: the counter is
+ *  cumulative since process start, so a first read taken at the moment of a
+ *  freeze would report hours of ordinary scheduling as if it were the freeze.
+ *
+ *  Returns null when unavailable or on the first (baseline-establishing) call. */
+export declare function sampleRunqueueWaitMs(): number | null;
 /** Test-only — drop the singleton so a fresh histogram is created. */
 export declare function __resetEventLoopMonitorForTests(): void;

package/ingest/event-loop-monitor.js

@@ -25,6 +25,7 @@
 // createRequire dance exists for that dependency's module shape, not for
 // builtins. See docs/CLAUDE/plugin-integration.md.
 import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { readFileSync } from 'node:fs';
 import { logger } from '../logger.js';
 const TAG = 'event-loop-monitor';
 /** Sampling resolution. 20ms is fine-grained enough to catch a real stall
@@ -99,6 +100,80 @@ export function sampleEventLoopDelayMs() {
         return null;
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Runqueue wait — the measurement that says WHO froze the loop.
+//
+// ★ Event-loop delay is a symptom with two very different causes: the host
+// descheduled us (co-tenant load, an oversubscribed VPS) or we blocked our own
+// loop (a synchronous burst — on a ReefClaw box, an LLM turn, which runs
+// EMBEDDED in this same process alongside order handling). The histogram above
+// cannot tell them apart, so the check used to assert the first and tell the
+// operator to buy more CPU. Verified wrong on prod 2026-07-29: a "froze 5.9s"
+// warn on a box at 0.05 load, 0 steal, 0 swap, whose cumulative runqueue wait
+// was 1.95s across the whole process lifetime. Resizing would have done nothing.
+//
+// /proc/self/schedstat field 2 is the kernel's own count of nanoseconds this
+// thread spent RUNNABLE but waiting for a CPU. It is exactly the discriminator:
+// large ⇒ the host really is starving us; ~0 while the loop froze ⇒ the freeze
+// came from inside. `/proc/self` is the thread-group leader = the main thread,
+// which is where the event loop runs, so this is the right thread to ask.
+//
+// Same evidence rule as everything else on this path (issue #265): unavailable
+// ⇒ null ⇒ 'unknown' attribution and the cautious copy — never a fabricated
+// zero, which would read as "definitely self-inflicted" and is the same
+// false-confidence bug pointed the other way.
+const SCHEDSTAT_PATH = '/proc/self/schedstat';
+/** Cumulative ns at the previous sample; null until the first read establishes
+ *  a baseline. A delta needs two points — the first call can only arm. */
+let lastRunqueueWaitNs = null;
+/** Latched after the first failed read: not Linux, or a kernel built without
+ *  CONFIG_SCHEDSTATS. Stops us re-reading a file that will never exist. */
+let schedstatUnavailable = false;
+/** Read the cumulative runqueue-wait counter (ns). Null when unreadable or
+ *  malformed — never a guess. */
+function readRunqueueWaitNs() {
+    if (schedstatUnavailable)
+        return null;
+    try {
+        // Three space-separated numbers: cpu_time_ns, runqueue_wait_ns, timeslices.
+        const parts = readFileSync(SCHEDSTAT_PATH, 'utf8').trim().split(/\s+/);
+        const ns = Number(parts[1]);
+        if (!Number.isFinite(ns) || ns < 0) {
+            schedstatUnavailable = true;
+            return null;
+        }
+        return ns;
+    }
+    catch {
+        schedstatUnavailable = true;
+        logger.info(TAG, 'runqueue-wait unavailable (not Linux, or kernel without CONFIG_SCHEDSTATS) — host-stall attribution will report unknown');
+        return null;
+    }
+}
+/** Time (ms) this process spent waiting for a CPU since the previous call, then
+ *  re-baselines — so consecutive calls partition the timeline into the SAME
+ *  non-overlapping windows as `sampleEventLoopDelayMs`, and the two readings of
+ *  one cycle describe one window.
+ *
+ *  ★ Call this EVERY cycle, not only when a stall was observed: the counter is
+ *  cumulative since process start, so a first read taken at the moment of a
+ *  freeze would report hours of ordinary scheduling as if it were the freeze.
+ *
+ *  Returns null when unavailable or on the first (baseline-establishing) call. */
+export function sampleRunqueueWaitMs() {
+    const ns = readRunqueueWaitNs();
+    if (ns == null)
+        return null;
+    const prev = lastRunqueueWaitNs;
+    lastRunqueueWaitNs = ns;
+    if (prev == null)
+        return null;
+    // Counters only climb; a decrease means we are not reading what we think we
+    // are (or it wrapped). Report unknown rather than a negative/garbage window.
+    if (ns < prev)
+        return null;
+    return (ns - prev) / 1e6;
+}
 /** Test-only — drop the singleton so a fresh histogram is created. */
 export function __resetEventLoopMonitorForTests() {
     try {
@@ -110,4 +185,6 @@ export function __resetEventLoopMonitorForTests() {
     histogram = null;
     initFailed = false;
     armed = false;
+    lastRunqueueWaitNs = null;
+    schedstatUnavailable = false;
 }

package/ingest/readiness-reporter.d.ts

@@ -1,4 +1,11 @@
 import { type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
+/** Who froze the loop. 'unknown' when the kernel counter is unreadable (not
+ *  Linux / no CONFIG_SCHEDSTATS / first cycle) — attribution is evidence, and
+ *  absent evidence stays absent rather than defaulting to a blame. */
+export type StallAttribution = 'host' | 'self' | 'unknown';
+/** Compare the freeze against the CPU the host actually denied us. Exported for
+ *  unit tests — this is the whole discrimination rule in one place. */
+export declare function attributeStall(stallMs: number, runqueueWaitMs: number | null): StallAttribution;
 /** Venue-agnostic reachability probe — BinancePublicApi.probeReachability and
  *  HyperliquidPublicApi.probeReachability both return exactly this shape. */
 export interface VenueReachabilityProbe {
@@ -46,6 +53,8 @@ export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'v
     state?: ReadinessCycleState;
     /** Injected for tests; production reads the real event-loop histogram. */
     sampleHostStallMs?: () => number | null;
+    /** Injected for tests; production reads /proc/self/schedstat. */
+    sampleRunqueueWaitMs?: () => number | null;
 }): Promise<ReadinessReport>;
 /** Test-only — reset the singleton guard between unit tests. */
 export declare function __resetReadinessReporterForTests(): void;

package/ingest/readiness-reporter.js

@@ -8,9 +8,9 @@
 // module-level singleton guard mirrors `pluginInitialised` in index.ts — OpenClaw
 // calls register() multiple times per process and we must never spawn a second
 // timer. The interval is unref()'d so it never holds the process open.
-import { makeReadinessCheck, deriveOverallReadiness, GEO_BLOCK_FIX_HINT, } from '@reefclaw/shared';
+import { makeReadinessCheck, deriveOverallReadiness, GEO_BLOCK_FIX_HINT, HOST_STALL_FIX_HINT, } from '@reefclaw/shared';
 import { logger, formatError } from '../logger.js';
-import { startEventLoopMonitor, sampleEventLoopDelayMs } from './event-loop-monitor.js';
+import { startEventLoopMonitor, sampleEventLoopDelayMs, sampleRunqueueWaitMs, } from './event-loop-monitor.js';
 const TAG = 'readiness';
 const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
 const MIN_INTERVAL_MS = 60_000;
@@ -25,6 +25,24 @@ const REACH_WARN_AFTER_FAILURES = 2;
  *  Well above ordinary GC/boot jitter (tens to low hundreds of ms) and far
  *  below the freezes worth alarming on — the live incident produced 89s-556s. */
 const HOST_STALL_WARN_MS = 5_000;
+/** How much of a freeze the kernel must attribute to runqueue wait before we
+ *  blame the HOST for it. Half is deliberately generous to the host-starved
+ *  reading: a host that froze us for N seconds necessarily made us wait most of
+ *  those N seconds, while a self-blocked loop accrues ~nothing (prod: 1.95s
+ *  across an entire process lifetime, against a 5.9s freeze in one cycle). */
+const HOST_WAIT_SHARE_OF_STALL = 0.5;
+/** Absolute floor under the share test. Sub-second waiting is ordinary
+ *  scheduling on any box and must never read as starvation, however short the
+ *  freeze it is compared against. */
+const HOST_WAIT_FLOOR_MS = 1_000;
+/** Compare the freeze against the CPU the host actually denied us. Exported for
+ *  unit tests — this is the whole discrimination rule in one place. */
+export function attributeStall(stallMs, runqueueWaitMs) {
+    if (runqueueWaitMs == null)
+        return 'unknown';
+    const hostThreshold = Math.max(HOST_WAIT_FLOOR_MS, stallMs * HOST_WAIT_SHARE_OF_STALL);
+    return runqueueWaitMs >= hostThreshold ? 'host' : 'self';
+}
 export function createReadinessCycleState() {
     return { consecutiveReachFailures: 0 };
 }
@@ -52,6 +70,7 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
     const checks = [];
     const state = deps.state ?? createReadinessCycleState();
     const sampleStall = deps.sampleHostStallMs ?? sampleEventLoopDelayMs;
+    const sampleWait = deps.sampleRunqueueWaitMs ?? sampleRunqueueWaitMs;
     // The venue decides which reachability check this report carries; the copy
     // for both ids lives in shared/src/readiness.ts. Clock drift comes from the
     // same probe on both venues (Binance fapi serverTime / Hyperliquid
@@ -77,6 +96,12 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
     // 'unknown', never a fabricated healthy zero — except that a probe which
     // measured its own overshoot IS a stall measurement, so it stands in.
     const stallMs = sampleStall() ?? (probe.outcome === 'stalled' ? (probe.stallMs ?? null) : null);
+    // ★ Sampled unconditionally, even on a passing cycle: the counter behind it is
+    // cumulative, so it must be re-baselined every cycle for its window to line up
+    // with the freeze window. Reading it only when a stall appeared would charge
+    // that one freeze with every millisecond of ordinary scheduling since boot and
+    // score a self-blocked loop as a starved host.
+    const runqueueWaitMs = sampleWait();
     if (stallMs == null) {
         checks.push(makeReadinessCheck('host_responsive', 'unknown', { checkedAt: now }));
     }
@@ -85,16 +110,40 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
         // Boot congestion (WS start, snapshot, seed all racing) legitimately stalls
         // the loop for seconds — same warm-up rule as the clock check below.
         const status = bootWarmup && rawStatus !== 'pass' ? 'unknown' : rawStatus;
+        // WHO froze it — computed only for a real freeze, since the whole question
+        // is what to tell the operator to go fix.
+        const attribution = rawStatus === 'pass' ? 'unknown' : attributeStall(stallMs, runqueueWaitMs);
+        const frozeSecs = (stallMs / 1000).toFixed(1);
+        const waitedSecs = runqueueWaitMs != null ? (runqueueWaitMs / 1000).toFixed(1) : null;
+        // The detail line carries the evidence, not just the verdict: an operator
+        // who disagrees with the attribution can see the number it rests on.
+        const stallDetail = attribution === 'host'
+            ? `froze ${frozeSecs}s (waited ${waitedSecs}s for CPU)`
+            : attribution === 'self'
+                ? `froze ${frozeSecs}s (host had CPU free — blocked inside the agent process)`
+                : `froze ${frozeSecs}s`;
         checks.push(makeReadinessCheck('host_responsive', status, {
             detail: rawStatus === 'pass'
                 ? `max loop delay ${Math.round(stallMs)}ms`
                 : bootWarmup
-                    ? `froze ${(stallMs / 1000).toFixed(1)}s (boot warm-up — rechecking)`
-                    : `froze ${(stallMs / 1000).toFixed(1)}s`,
+                    ? `froze ${frozeSecs}s (boot warm-up — rechecking)`
+                    : stallDetail,
+            // Only an attributed stall may name its cause; 'unknown' falls through to
+            // the cautious default in the copy map (issue #265 rule).
+            ...(attribution === 'host'
+                ? { fixHint: HOST_STALL_FIX_HINT.host_starved }
+                : attribution === 'self'
+                    ? { fixHint: HOST_STALL_FIX_HINT.self_inflicted }
+                    : {}),
             checkedAt: now,
         }));
         if (rawStatus !== 'pass' && !bootWarmup) {
-            logger.warn(TAG, `host starved: event loop froze ${(stallMs / 1000).toFixed(1)}s this cycle — order handling and bracket resync can lag by that much`);
+            const cause = attribution === 'host'
+                ? `host starved: waited ${waitedSecs}s for CPU`
+                : attribution === 'self'
+                    ? `blocked inside this process (host had CPU free — waited only ${waitedSecs}s)`
+                    : 'cause unattributable (runqueue wait unreadable)';
+            logger.warn(TAG, `event loop froze ${frozeSecs}s this cycle — order handling and bracket resync can lag by that much; ${cause}`);
         }
     }
     // venue reachability (+ clock drift from the same probe response)

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/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.14",
-  "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.16",
+  "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,19 +16,22 @@
     }
   },
   "files": [
-    "**/*"
+    "**/*",
+    "!scripts/**"
   ],
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
-    "@reefclaw/shared": "0.1.3",
+    "@reefclaw/shared": "0.1.4",
     "ccxt": "4.5.37",
     "json5": "2.2.3",
-    "ws": "8.19.0"
+    "ws": "8.21.1"
   },
   "scripts": {
-    "build": "node scripts/assemble.mjs"
+    "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"