@reefclaw/openclaw-plugin 0.1.24 → 0.1.26

package/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/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;
@@ -602,6 +643,10 @@ export interface ConnectorConfig {
     relayUrl: string;
     userId: string;
     token: string;
+    /** Stable per-install id (non-secret), sent as `?instance=` so the relay's
+     *  skill-slot admission can tell "same box restarting" (instant takeover)
+     *  from "second box" (rejected 4011). See utils/instance-id.ts. */
+    instanceId?: string;
     reconnect?: {
         baseDelayMs?: number;
         maxDelayMs?: number;

package/bridge/utils/instance-id.d.ts

@@ -0,0 +1,3 @@
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export declare function resolveRelayInstanceId(baseDir?: string): string;

package/bridge/utils/instance-id.js

@@ -0,0 +1,48 @@
+// Stable per-install relay instance id (2026-08-25, skill-slot admission).
+//
+// The relay seats ONE skill connection per account and refuses newcomers —
+// EXCEPT a newcomer proving it is the same box restarting, which takes over
+// instantly (the graceful-restart property). "Same box" = this id, sent as a
+// non-secret `?instance=` query param on the relay URL. It must therefore
+// survive process restarts: persisted once per install at
+// `~/.reefclaw/relay-instance-id` and reused forever.
+//
+// Fail-open: when the filesystem refuses (read-only home, exotic container),
+// fall back to a per-process id. Takeover-after-crash then degrades to the
+// relay's liveness timeout instead of being instant — worse, never wrong.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logger } from '../logger.js';
+const TAG = 'instance-id';
+const ID_SHAPE = /^[A-Za-z0-9-]{8,64}$/;
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export function resolveRelayInstanceId(baseDir) {
+    // Operator escape hatch (e.g. two deliberate installs sharing one home dir).
+    const fromEnv = process.env.RC_RELAY_INSTANCE_ID?.trim();
+    if (fromEnv && ID_SHAPE.test(fromEnv))
+        return fromEnv;
+    const dir = baseDir ?? join(homedir(), '.reefclaw');
+    const file = join(dir, 'relay-instance-id');
+    try {
+        if (existsSync(file)) {
+            const existing = readFileSync(file, 'utf8').trim();
+            if (ID_SHAPE.test(existing))
+                return existing;
+            // Garbled file: fall through and rewrite — a fresh id only costs one
+            // liveness-timeout takeover, a garbled param corrupts the admission key.
+        }
+        const fresh = randomUUID();
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, fresh + '\n', 'utf8');
+        return fresh;
+    }
+    catch (err) {
+        const perProcess = randomUUID();
+        logger.warn(TAG, `Could not persist relay instance id (${err.message}) — using per-process id; ` +
+            `crash takeover degrades to the relay liveness timeout`);
+        return perProcess;
+    }
+}

package/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/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/config/brackets-config.d.ts

@@ -1,6 +1,7 @@
 import { type PluginConfigFile } from './plugin-config-io.js';
 export type BracketMode = 'off' | 'observe' | 'enforce';
-/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+/** Read bracket mode from a config object. Invalid values fall back to the
+ *  context default ('enforce' on a live-Binance box, else 'off'). */
 export declare function getBracketMode(config?: PluginConfigFile, remoteOverride?: BracketMode): BracketMode;
 /** Convenience: load from disk and return the effective mode. */
 export declare function loadBracketMode(): BracketMode;

package/config/brackets-config.js

@@ -5,10 +5,32 @@
 //      in memory on the plugin after push; not persisted to plugin-config.json.
 //      Wired in Phase 2; for Phase 1 this is always undefined.
 //   2. Local plugin-config.json `brackets.mode` field.
-//   3. Default: 'off' (legacy stop-watcher remains authoritative).
+//   3. Default: CONTEXT-AWARE since 2026-08-25 (E2E audit #3, the last
+//      real-money item on the fresh-box list): a box whose persisted
+//      tradingMode is MICRO_LIVE/LIVE on the BINANCE venue defaults to
+//      'enforce' — the historical 'off' default meant a fresh npx install
+//      flipped to live traded with NO exchange-side stops AND no mandatory-
+//      stop pre-trade gate (the gate is wired behind bracketsEnabled), i.e.
+//      genuinely naked, with no in-product way to notice. Everything else
+//      (paper, shadow, hyperliquid — whose adapter enforces brackets
+//      unconditionally and ignores this Binance-only knob) keeps 'off'.
+//      An EXPLICIT 'off' in config is still honored (operator break-glass,
+//      behind the Settings type-to-confirm guard) — with the new default it
+//      can only ever be a deliberate choice.
 import { readPluginConfig } from './plugin-config-io.js';
 const VALID = new Set(['off', 'observe', 'enforce']);
-/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+/** Does this config describe a live-Binance box — the one context where an
+ *  unset bracket mode must NOT mean "no protection"? Reads the PERSISTED
+ *  trading mode (set_trading_mode persists BEFORE the adapter swap, so
+ *  construction-time and per-call reads agree). */
+function isLiveBinanceContext(config) {
+    const mode = config?.tradingMode;
+    if (mode !== 'MICRO_LIVE' && mode !== 'LIVE')
+        return false;
+    return config?.exchange?.venue !== 'hyperliquid';
+}
+/** Read bracket mode from a config object. Invalid values fall back to the
+ *  context default ('enforce' on a live-Binance box, else 'off'). */
 export function getBracketMode(config, remoteOverride) {
     if (remoteOverride && VALID.has(remoteOverride))
         return remoteOverride;
@@ -16,7 +38,7 @@ export function getBracketMode(config, remoteOverride) {
     if (typeof raw === 'string' && VALID.has(raw)) {
         return raw;
     }
-    return 'off';
+    return isLiveBinanceContext(config) ? 'enforce' : 'off';
 }
 /** Convenience: load from disk and return the effective mode. */
 export function loadBracketMode() {

package/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/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/config/loss-streak-config.d.ts

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

package/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/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/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;