@reefclaw/connect 0.1.36 → 0.1.38

package/assets/bridge/shock-wake.js

@@ -0,0 +1,291 @@
+// Shock-wake poller — WS3 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// The agent thinks on a 15–30 min heartbeat; an announcement lands mid-cycle
+// and isn't reconsidered until the next one — the adaptivity investigation's
+// core latency gap. This poller watches intel's /api/shocks (the WS2
+// change-of-character flags, computed each fact pass) and, when the market
+// genuinely changes character, delivers ONE out-of-band agent turn through
+// the same gateway path operator chat uses (provider.handleChat — the
+// precedent is the trade-mission presenter).
+//
+// Guardrails (every one deliberately boring):
+//   - Central gate `agent_config.gates.shockWake`: off (default) → shadow
+//     (logs WOULD WAKE, delivers nothing) → on. Polled from the webapp
+//     every ~5 min; absent/garbage/outage → off. No local file fallback —
+//     this gate is central-only.
+//   - Wake-worthy = a market LEADER (BTC/ETH) flagged 'shock', OR a broad
+//     correlated move: ≥5 distinct coins shocked (env RC_SHOCK_WAKE_MIN_BROAD),
+//     or ≥3 when a MAJOR (BTC/ETH/BNB/SOL/XRP) is among them. Disagreement-only
+//     flags never wake — they are slow-moving and already ride scan_pairs
+//     indication. (Broad bar raised from a flat ≥3 on 2026-09-06: the first
+//     live night delivered 7 wakes on rotating 3-coin mid-cap alt clusters —
+//     routine alt volatility, not announcements. Replayed against the new
+//     rule, those 7 become 1.)
+//   - Stale shocks (fact older than 10 min) are ignored.
+//   - Global cooldown 60 min between wakes + daily cap 8 (UTC), armed in
+//     shadow too so the shadow soak counts exactly what 'on' would deliver.
+//     A FAILED delivery does not arm the cooldown (retry next tick).
+//     (Cooldown default raised 30→60 min 2026-09-05: the shadow soak showed a
+//     single sustained 09-03 event re-firing 4 would-wakes in 95 min — one
+//     re-ping per hour during a long move is the intended cadence.)
+//   - The wake is INDICATION: it mandates re-evaluation, never an action.
+//   - DELIVERY CONFIRMATION (2026-09-06): the gateway acks the RPC even when
+//     the main-session lane silently swallows the turn (the 2026-07-22
+//     OpenClaw class — 7 of the first night's 9 wakes died this way). The
+//     bridge wires provider `chatMessageStart` into noteAssistantActivity();
+//     if no agent turn STARTS within RC_SHOCK_WAKE_REPLY_TIMEOUT_MS (10 min)
+//     of a delivered wake, a WARN names the swallow suspicion (dashboard chat
+//     is likely dead too) and a counter increments. Observability only — no
+//     auto-retry into a wedged lane.
+//
+// Env overrides: RC_SHOCK_WAKE_POLL_MS (60s), RC_SHOCK_WAKE_GATE_POLL_MS
+// (5 min), RC_SHOCK_WAKE_COOLDOWN_MS (30 min), RC_SHOCK_WAKE_DAILY_CAP (8).
+import { logger, formatError } from './logger.js';
+const TAG = 'shock-wake';
+/** Leaders whose lone shock is wake-worthy, as base coins (venue-stripped). */
+const LEADER_COINS = new Set(['BTC', 'ETH']);
+/** Majors (the platform's liquidation-pulse majors group): their participation
+ *  lowers the broad-shock coin bar from 5 to 3 — a SOL-led cluster is market
+ *  information; three rotating meme-alts are Tuesday. */
+const MAJOR_COINS = new Set(['BTC', 'ETH', 'BNB', 'SOL', 'XRP']);
+const STALE_SHOCK_MS = 10 * 60_000;
+function envInt(name, fallback) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+/** 'BTCUSDT' / 'HL_BTC' / 'BTC/USDC' → 'BTC'. Best-effort market vocabulary
+ *  for the wake message — never used to address an order. */
+export function coinOf(intelSymbol) {
+    return intelSymbol
+        .replace(/^HL_/, '')
+        .replace(/\/.*$/, '')
+        .replace(/(USDT|USDC|BUSD)$/i, '')
+        .toUpperCase();
+}
+/** Parse gates.shockWake off the raw /api/internal/config payload. Central-only
+ *  gate — absent/garbage → 'off'. */
+export function parseShockWakeGate(raw) {
+    if (!raw || typeof raw !== 'object')
+        return 'off';
+    const gates = raw.gates;
+    if (!gates || typeof gates !== 'object')
+        return 'off';
+    const v = gates.shockWake;
+    return v === 'shadow' || v === 'on' ? v : 'off';
+}
+/** Pure wake-worthiness rule. `nowMs` gates staleness. Broad rule (2026-09-06):
+ *  ≥`minBroadCount` distinct coins shocked, OR ≥3 when a major participates. */
+export function assessWakeWorthiness(shocks, nowMs, minBroadCount = 5) {
+    const fresh = shocks.filter((s) => {
+        const t = Date.parse(s.time);
+        return Number.isFinite(t) && nowMs - t <= STALE_SHOCK_MS;
+    });
+    const shocked = fresh.filter((s) => s.flags.includes('shock'));
+    // One coin can appear per-venue (BTCUSDT + HL_BTC) — count coins, not rows.
+    const coins = new Set(shocked.map((s) => coinOf(s.symbol)));
+    const leader = shocked.find((s) => LEADER_COINS.has(coinOf(s.symbol)));
+    if (leader)
+        return { wake: true, reason: 'leader_shock', shocked };
+    const hasMajor = [...coins].some((c) => MAJOR_COINS.has(c));
+    if (coins.size >= minBroadCount || (hasMajor && coins.size >= 3)) {
+        return { wake: true, reason: 'broad_shock', shocked };
+    }
+    return { wake: false, shocked };
+}
+/** The out-of-band agent turn. Clearly machine-labeled (never impersonates the
+ *  operator), mandates re-evaluation, orders nothing. */
+export function buildWakeMessage(a) {
+    const seen = new Set();
+    const lines = [];
+    for (const s of a.shocked) {
+        const coin = coinOf(s.symbol);
+        if (seen.has(coin))
+            continue;
+        seen.add(coin);
+        const sign = (v) => (v >= 0 ? '+' : '');
+        lines.push(`- ${coin}: 30m ${Math.max(s.shock30mAtr, s.range30mAtr).toFixed(1)}×ATR, ` +
+            `1h ${sign(s.return1hPct)}${s.return1hPct}%, 4h ${sign(s.return4hPct)}${s.return4hPct}% ` +
+            `(regime label: ${s.regime})`);
+        if (lines.length >= 6)
+            break;
+    }
+    return [
+        '[AUTOMATED MARKET-SHIFT ALERT — from the ReefClaw system, NOT the operator]',
+        '',
+        a.reason === 'leader_shock'
+            ? 'A market leader just moved sharply — the market may have changed character:'
+            : 'Multiple symbols moved sharply together — the market may have changed character:',
+        ...lines,
+        '',
+        'Do this NOW, ahead of your scheduled heartbeat:',
+        '1. Re-derive your directional bias from FRESH data (scan_pairs, get_regime) — do NOT lean on theses formed before this move; regime labels may LAG it (see market_shift_caution in scan results).',
+        '2. For EVERY open position: check the pinned invalidation FIRST. If price is through it, act on your own plan.',
+        '3. Hold off on new entries until the re-derived bias and the tape agree.',
+        '',
+        'This alert is indication only — it does not order you to close anything. Reply with a brief assessment so the operator sees your read.',
+    ].join('\n');
+}
+export class ShockWakePoller {
+    opts;
+    mode = 'off';
+    pollTimer = null;
+    gateTimer = null;
+    lastWakeAtMs = 0;
+    wakesToday = 0;
+    wakeDayUtc = '';
+    polling = false;
+    pollMs = envInt('RC_SHOCK_WAKE_POLL_MS', 60_000);
+    gatePollMs = envInt('RC_SHOCK_WAKE_GATE_POLL_MS', 5 * 60_000);
+    cooldownMs = envInt('RC_SHOCK_WAKE_COOLDOWN_MS', 60 * 60_000);
+    dailyCap = envInt('RC_SHOCK_WAKE_DAILY_CAP', 8);
+    minBroad = envInt('RC_SHOCK_WAKE_MIN_BROAD', 5);
+    replyTimeoutMs = envInt('RC_SHOCK_WAKE_REPLY_TIMEOUT_MS', 10 * 60_000);
+    // Delivery confirmation (see header): a wake is only proven delivered when
+    // an agent turn STARTS after it. lastAssistantAtMs is fed by the bridge's
+    // chatMessageStart wiring; awaitingSince/deadline track one in-flight wake
+    // (the 60-min cooldown guarantees no overlap with the 10-min timeout).
+    lastAssistantAtMs = 0;
+    awaitingSinceMs = null;
+    awaitingDeadlineMs = 0;
+    suspectedSwallows = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        if (this.pollTimer)
+            return;
+        const refresh = () => { void this.refreshGate(); };
+        refresh();
+        this.gateTimer = setInterval(refresh, this.gatePollMs);
+        this.gateTimer.unref?.();
+        this.pollTimer = setInterval(() => { void this.tick(); }, this.pollMs);
+        this.pollTimer.unref?.();
+        logger.info(TAG, `started (poll ${this.pollMs / 1000}s, cooldown ${this.cooldownMs / 60000}m, cap ${this.dailyCap}/day, gate polled ${this.gatePollMs / 60000}m)`);
+    }
+    stop() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        if (this.gateTimer)
+            clearInterval(this.gateTimer);
+        this.pollTimer = null;
+        this.gateTimer = null;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /** Fed by the bridge from provider `chatMessageStart` — any agent turn
+     *  beginning counts (the wake's reply, or an operator chat's; either proves
+     *  the lane is alive, which is what the swallow check needs). */
+    noteAssistantActivity(atMs) {
+        const t = atMs ?? this.opts.now?.() ?? Date.now();
+        this.lastAssistantAtMs = t;
+        if (this.awaitingSinceMs !== null && t >= this.awaitingSinceMs) {
+            logger.info(TAG, `wake reply confirmed — agent turn started ${Math.round((t - this.awaitingSinceMs) / 1000)}s after delivery`);
+            this.awaitingSinceMs = null;
+        }
+    }
+    /** Suspected-swallow count this process (test/telemetry seam). */
+    getSuspectedSwallows() {
+        return this.suspectedSwallows;
+    }
+    checkPendingReply(nowMs) {
+        if (this.awaitingSinceMs === null || nowMs <= this.awaitingDeadlineMs)
+            return;
+        this.suspectedSwallows++;
+        logger.warn(TAG, `wake delivered at ${new Date(this.awaitingSinceMs).toISOString()} but NO agent turn started ` +
+            `within ${Math.round(this.replyTimeoutMs / 60_000)}m — the main-session lane may be silently ` +
+            `swallowing turns (known OpenClaw class, 2026-07-22; dashboard chat is likely affected too). ` +
+            `Suspected swallows this process: ${this.suspectedSwallows}`);
+        this.awaitingSinceMs = null;
+    }
+    async refreshGate() {
+        const base = (this.opts.webappUrl ?? process.env.REEFCLAW_API_URL ?? 'https://www.reefclaw.com').replace(/\/$/, '');
+        try {
+            const doFetch = this.opts.fetchImpl ?? fetch;
+            const res = await doFetch(`${base}/api/internal/config`, {
+                headers: { Authorization: `Bearer ${this.opts.token}` },
+            });
+            if (!res.ok)
+                return; // keep last-known mode on outage (fail toward inert)
+            const next = parseShockWakeGate(await res.json());
+            if (next !== this.mode) {
+                logger.info(TAG, `gate: shockWake ${this.mode} → ${next}`);
+                this.mode = next;
+            }
+        }
+        catch (err) {
+            logger.debug(TAG, `gate poll failed (keeping ${this.mode}): ${formatError(err)}`);
+        }
+    }
+    /** One poll cycle. Exposed for tests. */
+    async tick() {
+        const tickNowMs = this.opts.now?.() ?? Date.now();
+        // Runs even when the gate is off — a wake delivered just before an
+        // operator rollback still deserves its confirmation verdict.
+        this.checkPendingReply(tickNowMs);
+        if (this.mode === 'off' || this.polling)
+            return;
+        this.polling = true;
+        try {
+            const nowMs = tickNowMs;
+            const doFetch = this.opts.fetchImpl ?? fetch;
+            const base = this.opts.intelligenceUrl.replace(/\/$/, '');
+            const res = await doFetch(`${base}/api/shocks`, {
+                headers: { Authorization: `Bearer ${this.opts.token}` },
+            });
+            if (!res.ok)
+                return;
+            const body = (await res.json());
+            if (!Array.isArray(body?.shocks))
+                return;
+            const a = assessWakeWorthiness(body.shocks, nowMs, this.minBroad);
+            if (!a.wake)
+                return;
+            // Rate limits — checked only for wake-worthy ticks so quiet markets
+            // never touch the counters.
+            const day = new Date(nowMs).toISOString().slice(0, 10);
+            if (day !== this.wakeDayUtc) {
+                this.wakeDayUtc = day;
+                this.wakesToday = 0;
+            }
+            if (nowMs - this.lastWakeAtMs < this.cooldownMs)
+                return;
+            if (this.wakesToday >= this.dailyCap) {
+                logger.warn(TAG, `daily cap ${this.dailyCap} reached — suppressing further wakes today`);
+                return;
+            }
+            const coins = [...new Set(a.shocked.map((s) => coinOf(s.symbol)))].join(', ');
+            if (this.mode === 'shadow') {
+                this.lastWakeAtMs = nowMs;
+                this.wakesToday++;
+                logger.warn(TAG, `WOULD WAKE (shadow): ${a.reason} — ${coins} (${this.wakesToday}/${this.dailyCap} today)`);
+                return;
+            }
+            const message = buildWakeMessage(a);
+            const out = await this.opts.provider.handleChat(message);
+            if (out.received) {
+                this.lastWakeAtMs = nowMs;
+                this.wakesToday++;
+                // Arm the delivery-confirmation window (see checkPendingReply).
+                this.awaitingSinceMs = nowMs;
+                this.awaitingDeadlineMs = nowMs + this.replyTimeoutMs;
+                logger.warn(TAG, `WAKE delivered: ${a.reason} — ${coins} (${this.wakesToday}/${this.dailyCap} today)`);
+            }
+            else {
+                // Delivery failed (gateway not connected etc.) — no cooldown, retry
+                // on the next tick while the shock is still fresh.
+                logger.warn(TAG, `wake delivery FAILED (${out.error ?? 'unknown'}) — will retry next tick`);
+            }
+        }
+        catch (err) {
+            logger.debug(TAG, `tick failed: ${formatError(err)}`);
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /** Test seam. */
+    __setModeForTest(mode) {
+        this.mode = mode;
+    }
+}

package/assets/bridge/types.d.ts

@@ -133,10 +133,51 @@ export interface AgentStateData {
                 /** Last run outcome, e.g. "ok" | "error". */
                 lastRunStatus?: string;
             };
+            /** Compact summary of the last recorded heartbeat run (flight recorder,
+             *  skill/src/heartbeat-runs.ts). Absent until the first beat is
+             *  recorded after start — byte-identical to pre-feature until then. */
+            lastHeartbeat?: LastHeartbeatSummary;
+            /** Is the LLM behind the agent answering? Derived skill-side from the
+             *  cron job's FailoverReason + the last recorded beat
+             *  (skill/src/model-health.ts). Absent until first derived. */
+            modelHealth?: ModelHealthSummary;
         };
     };
     timestamp: string;
 }
+/** Dashboard-facing summary of one heartbeat run (the full record lives in
+ *  the webapp's heartbeat_runs table). Token counts are RAW COUNTS — never
+ *  translated to a currency here or downstream. */
+export interface LastHeartbeatSummary {
+    runId: string;
+    startedAtMs: number;
+    endedAtMs: number | null;
+    durationMs: number | null;
+    status: 'ok' | 'error' | 'incomplete' | 'unknown';
+    toolCallCount: number;
+    toolErrorCount: number;
+    tokensTotal: number | null;
+    tokensInput: number | null;
+    tokensOutput: number | null;
+    model: string | null;
+}
+export interface ModelHealthSummary {
+    level: 'ok' | 'degraded' | 'error';
+    reason: string | null;
+    detail: string | null;
+    atMs: number;
+    model: string | null;
+}
+/** An agent turn's lifecycle as the gateway reports it, WITH the session key
+ *  (an isolated cron beat runs under `agent:main:cron:<jobId>:run:<sid>`),
+ *  so consumers can tell a heartbeat turn from a chat turn. */
+export interface AgentRunLifecycleData {
+    runId: string;
+    phase: 'start' | 'end' | 'error';
+    sessionKey?: string;
+    sessionId?: string;
+    at: number;
+}
 export interface RiskLimits {
     position: {
         maxPositionSize: number;

package/assets/plugin/config/agent-config-client.d.ts

@@ -6,12 +6,14 @@
  *  `positionReviewMode` (slice 3, the Position Decision Journal
  *  heartbeat-mandate + superset gate, file key `positionReview.mode`) →
  *  `approvalMode` (slice 4, per-trade operator approval, file key
- *  `approval.mode`). The first two ride the same four-stage
+ *  `approval.mode`) → `reentryCooldown` (create_order re-entry cooldown, file
+ *  key `reentryCooldown.mode`). All but approvalMode ride the same four-stage
  *  `off → shadow → observe → enforce` ladder; approvalMode has its own. */
 export interface AgentGates {
     exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
     positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
     approvalMode?: 'off' | 'per_trade';
+    reentryCooldown?: 'off' | 'shadow' | 'observe' | 'enforce';
 }
 /** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
  *  from the users row and delivered on the config channel). The plugin NEVER

package/assets/plugin/config/agent-config-client.js

@@ -125,6 +125,10 @@ function validateGates(raw) {
     if (typeof approvalMode === 'string' && APPROVAL_MODE_VALUES.has(approvalMode)) {
         gates.approvalMode = approvalMode;
     }
+    const reentryCooldown = obj.reentryCooldown;
+    if (typeof reentryCooldown === 'string' && MODE_LADDER_VALUES.has(reentryCooldown)) {
+        gates.reentryCooldown = reentryCooldown;
+    }
     return gates;
 }
 /** Version-monotonic acceptance (basic rollback/replay protection): a fetched

package/assets/plugin/config/gate-store.d.ts

@@ -18,6 +18,9 @@ declare class GateStore {
      *  is the pre-existing autonomous behaviour, so neither value can leave a
      *  position unprotected. */
     getApprovalMode(): AgentGates['approvalMode'] | null;
+    /** The central reentryCooldown mode, or null when central has no value (or
+     *  the kill-switch is on) — null tells the reader to fall back to the file. */
+    getReentryCooldown(): AgentGates['reentryCooldown'] | null;
     /** Test-only. */
     __reset(): void;
 }

package/assets/plugin/config/gate-store.js

@@ -31,12 +31,14 @@ class GateStore {
         const next = gates ?? {};
         const changed = next.exitGate !== this.gates.exitGate ||
             next.positionReviewMode !== this.gates.positionReviewMode ||
-            next.approvalMode !== this.gates.approvalMode;
+            next.approvalMode !== this.gates.approvalMode ||
+            next.reentryCooldown !== this.gates.reentryCooldown;
         this.gates = { ...next };
         if (changed) {
             logger.info(TAG, `applied central gates: exitGate=${next.exitGate ?? UNSET} ` +
                 `positionReviewMode=${next.positionReviewMode ?? UNSET} ` +
-                `approvalMode=${next.approvalMode ?? UNSET}`);
+                `approvalMode=${next.approvalMode ?? UNSET} ` +
+                `reentryCooldown=${next.reentryCooldown ?? UNSET}`);
         }
     }
     /** The central exitGate mode, or null when central has no value (or the
@@ -66,6 +68,13 @@ class GateStore {
             return null;
         return this.gates.approvalMode ?? null;
     }
+    /** The central reentryCooldown mode, or null when central has no value (or
+     *  the kill-switch is on) — null tells the reader to fall back to the file. */
+    getReentryCooldown() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.reentryCooldown ?? null;
+    }
     /** Test-only. */
     __reset() {
         this.gates = {};

package/assets/plugin/config/loss-streak-config.d.ts

@@ -0,0 +1,2 @@
+export type LossStreakSizingMode = 'off' | 'log' | 'enforce';
+export declare function resolveLossStreakSizingMode(): LossStreakSizingMode;

package/assets/plugin/config/loss-streak-config.js

@@ -0,0 +1,33 @@
+// WS1 (docs/MARKET_ADAPTIVITY_PLAN.md §3) — mode resolver for the LIVE
+// loss-streak sizing brake feed.
+//
+// preTradeRiskCheck has always had a graduated loss-streak brake (0.5× /
+// 0.25× position size at the operator-tunable lossStreakHalfSize /
+// lossStreakQuarterSize thresholds — never a hard block), but live fed it a
+// hardcoded consecutiveLosses=0 ("would come from intelligence DB — use 0
+// for now"). The real feed now comes from the ReentryTracker exit records
+// (wasLoss + book tag, persisted).
+//
+// Env RC_LOSS_STREAK_SIZING:
+//   'enforce' (DEFAULT since 2026-09-05) — feed the real streak to the risk
+//                          check; the graduated size reduction applies on
+//                          live exactly as it always has on paper. Promoted
+//                          from 'log' after the pre-registered soak: 3 days
+//                          of clean streak logs (1→3 tracked + reset
+//                          correctly) and an 18/18 loss-sign agreement audit
+//                          between the agent's r_multiple_at_close and DB
+//                          realized_r.
+//   'log'               — compute + log on entries; sizing UNAFFECTED
+//                          (riskCheck still sees 0). The rollout soak mode.
+//   'off'               — no compute, no log; byte-identical to the
+//                          pre-WS1 path (kill-switch).
+//
+// Deliberately env-based (not the central gate channel): it is a
+// live/paper-parity bug fix on a risk-reduction mechanism, not a new policy
+// ladder — and its only enforce-direction effect is SMALLER size.
+export function resolveLossStreakSizingMode() {
+    const raw = (process.env.RC_LOSS_STREAK_SIZING ?? '').toLowerCase();
+    if (raw === 'off' || raw === 'log')
+        return raw;
+    return 'enforce';
+}

package/assets/plugin/config/plugin-config-io.d.ts

@@ -197,6 +197,25 @@ export interface PluginConfigFile {
     stopWatcher?: {
         intervalMs?: number;
     };
+    /** Re-entry cooldown gate — blocks (mode-laddered) a NEW create_order entry
+     *  on a symbol whose last close within `minutes` was a LOSS. See
+     *  plugin/src/tools/reentry-cooldown.ts for the evidence + semantics.
+     *
+     *  mode='off' (default)  — gate never runs; behaviour identical to today.
+     *  mode='shadow'         — gate runs; verdict logged + tagged into
+     *                           position_entries.metadata.reentry_cooldown;
+     *                           the order always fires.
+     *  mode='observe'        — as shadow, but a triggered verdict logs at WARN.
+     *  mode='enforce'        — triggered verdict hard-rejects create_order.
+     *
+     *  `mode` here is the LOCAL fallback — once the central gate
+     *  (agent_config.gates.reentryCooldown) is set, central rules (kill-switch
+     *  RC_CENTRAL_GATES=off). `minutes` is local-only (default 60, clamped
+     *  5–1440). */
+    reentryCooldown?: {
+        mode?: 'off' | 'shadow' | 'observe' | 'enforce';
+        minutes?: number;
+    };
     [extra: string]: unknown;
 }
 export declare function defaultConfigPath(): string;

package/assets/plugin/config/reentry-cooldown-config.d.ts

@@ -0,0 +1,7 @@
+import { type PluginConfigFile } from './plugin-config-io.js';
+import type { ReentryCooldownMode } from '../tools/reentry-cooldown.js';
+export declare const DEFAULT_REENTRY_COOLDOWN_MINUTES = 60;
+export declare function getReentryCooldownMode(config?: PluginConfigFile): ReentryCooldownMode;
+export declare function loadReentryCooldownMode(): ReentryCooldownMode;
+export declare function getReentryCooldownMinutes(config?: PluginConfigFile): number;
+export declare function loadReentryCooldownMinutes(): number;

package/assets/plugin/config/reentry-cooldown-config.js

@@ -0,0 +1,59 @@
+// Feature-flag readers for the re-entry cooldown gate (create_order).
+//
+// Mode default 'off' so the gate ships dead-code; the cooldown window default
+// (60 min) matches the 2026-09-02 measurement window that motivated the gate.
+// Mode resolution follows the exitGate pattern (config-service slice 2):
+//
+//     central (agent_config.gates.reentryCooldown via gate-store)
+//       → plugin-config.json reentryCooldown.mode
+//       → 'off'
+//
+// create_order reads the mode PER CALL, so a dashboard/API flip via
+// scripts/enable-reentry-cooldown.py hot-applies within one config poll —
+// no restart. Kill-switch RC_CENTRAL_GATES=off hands control back to the
+// local file. The minutes knob is LOCAL-only (mechanism tunable, not a
+// ladder) — central carries only the mode.
+import { readPluginConfig } from './plugin-config-io.js';
+import { gateStore } from './gate-store.js';
+const VALID_MODES = new Set([
+    'off',
+    'shadow',
+    'observe',
+    'enforce',
+]);
+export const DEFAULT_REENTRY_COOLDOWN_MINUTES = 60;
+const MIN_COOLDOWN_MINUTES = 5;
+const MAX_COOLDOWN_MINUTES = 1440;
+export function getReentryCooldownMode(config) {
+    const raw = config?.reentryCooldown?.mode;
+    if (typeof raw === 'string' && VALID_MODES.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+export function loadReentryCooldownMode() {
+    const central = gateStore.getReentryCooldown();
+    if (central)
+        return central;
+    try {
+        return getReentryCooldownMode(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+export function getReentryCooldownMinutes(config) {
+    const raw = config?.reentryCooldown?.minutes;
+    if (typeof raw === 'number' && Number.isFinite(raw)) {
+        return Math.max(MIN_COOLDOWN_MINUTES, Math.min(MAX_COOLDOWN_MINUTES, raw));
+    }
+    return DEFAULT_REENTRY_COOLDOWN_MINUTES;
+}
+export function loadReentryCooldownMinutes() {
+    try {
+        return getReentryCooldownMinutes(readPluginConfig());
+    }
+    catch {
+        return DEFAULT_REENTRY_COOLDOWN_MINUTES;
+    }
+}

package/assets/plugin/index.js

@@ -2637,6 +2637,11 @@ const paperTradingPlugin = {
                     decisionsClient: positionDecisionsClient,
                     userId: positionDecisionsUserId,
                     reentryTracker,
+                    // WS2 directional scoreboard (docs/MARKET_ADAPTIVITY_PLAN.md §3):
+                    // tracked positions from the state store (no exchange round-trip)
+                    // + book resolved per call so a paper↔live flip follows.
+                    openPositions: () => positionStateStore.getAll().map((e) => ({ side: e.side })),
+                    book: () => (runtime.adapter.isLive ? 'live' : 'paper'),
                 })),
             },
             {

package/assets/plugin/ingest/position-auto-capture.js

@@ -306,12 +306,27 @@ export async function onClosePositionFilled(ctx, inputs, order) {
     };
     ctx.decisionsClient.postClose(ctx.userId, close);
     // Re-entry indication (issue #204) — record the exit so scan_pairs can flag
-    // same-bar re-entries on this (symbol, setup).
+    // same-bar re-entries on this (symbol, setup), and so the reentryCooldown
+    // gate can see recent losses. Live agent-closes have no engine trade record
+    // here (exchange-exact PnL arrives later on the WS fill, racing this path),
+    // so the loss sign falls back to the agent's own r_multiple_at_close — the
+    // same validator-checked field the exit gate trusts. lossSource lets the
+    // shadow soak audit that sign against the DB before enforce.
+    const rRaw = inputs.closeAssessment?.['r_multiple_at_close'];
+    const rAtClose = typeof rRaw === 'number' && Number.isFinite(rRaw) ? rRaw : undefined;
     ctx.reentryTracker?.recordExit({
         symbol: inputs.symbol,
         setupType: stateEntry.setupType ?? paperTrade?.setupType,
         side: stateEntry.side,
-        wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        wasLoss: paperTrade
+            ? paperTrade.netRealizedPnl < 0
+            : rAtClose != null
+                ? rAtClose < 0
+                : undefined,
+        lossSource: paperTrade ? 'paper_engine' : rAtClose != null ? 'assessment_r' : undefined,
+        mode: ctx.resolveMode?.(),
+        realizedR: rAtClose,
+        realizedPnl: paperTrade?.netRealizedPnl,
         closedAtMs: closeAtMs,
     });
     // Drop local state — symbol can re-enter as a new position.
@@ -388,6 +403,7 @@ export async function onAutoFlattenClose(ctx, inputs, lookup = {
         symbol: inputs.symbol,
         setupType: flattenState?.setupType,
         side: flattenState?.side ?? 'long',
+        mode: ctx.resolveMode?.(),
         closedAtMs: inputs.observedAtMs ?? Date.now(),
     });
     ctx.stateStore.remove(inputs.symbol);
@@ -421,6 +437,9 @@ export async function onStopWatcherClose(ctx, inputs) {
         setupType: stateEntry?.setupType ?? paperTrade?.setupType,
         side: stateEntry?.side ?? 'long',
         wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        lossSource: paperTrade ? 'paper_engine' : undefined,
+        mode: ctx.resolveMode?.(),
+        realizedPnl: paperTrade?.netRealizedPnl,
         closedAtMs: closeAtMs,
     });
     const dropState = () => { ctx.stateStore?.remove(inputs.symbol); };
@@ -680,6 +699,9 @@ async function handleReduceOnlyExit(ctx, fill) {
         setupType: stateEntry.setupType,
         side: stateEntry.side,
         wasLoss: realizedPnl < 0,
+        lossSource: 'ws_fill',
+        mode: ctx.resolveMode?.(),
+        realizedPnl,
         closedAtMs: fill.exchangeTimeMs ?? Date.now(),
     });
     ctx.stateStore.remove(fill.symbol);
@@ -745,5 +767,16 @@ export function buildEntryPlanMetadata(md) {
             j.note = rr.note;
         out.realization_rule = j;
     }
+    // Cooldown-gate measurement tag (snake_case per the canonical JSONB key
+    // rule) — present only when the gate triggered and the entry fired anyway.
+    const rc = md.reentryCooldown;
+    if (rc) {
+        out.reentry_cooldown = {
+            mode: rc.mode,
+            minutes_since_loss: rc.minutesSinceLoss,
+            cooldown_minutes: rc.cooldownMinutes,
+            would_block: rc.wouldBlock,
+        };
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 }

package/assets/plugin/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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": {