@reefclaw/openclaw-plugin 0.1.13 → 0.1.15

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/ccxt/binance-public.d.ts

@@ -1,3 +1,4 @@
+import { type VenueReachabilityResult } from '@reefclaw/shared';
 import type { CcxtTicker, CcxtOHLCV } from '../types.js';
 import type { OrderBookDepth } from '../simulator/types.js';
 import type { PublicMarketDataApi } from './public-market-data-api.js';
@@ -28,9 +29,20 @@ export declare class BinancePublicApi implements PublicMarketDataApi {
      *   - 'reachable'   clean response (driftMs = serverTime − localTime)
      *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
      *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
-     *   - 'unreachable' network / DNS / timeout / other error */
-    probeReachability(): Promise<{
-        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
-        driftMs: number | null;
-    }>;
+     *   - 'stalled'     THIS process was starved — we learned nothing (issue #265)
+     *   - 'unreachable' network / DNS / timeout / other error
+     *
+     *  ★ Self-stall detection: an error is evidence about BINANCE only if it
+     *  arrived on schedule. When the host starves the process the loop stops
+     *  running, ccxt's own timeout lands minutes late, and the old code blamed the
+     *  network — producing a confident "you are geo-blocked / check your firewall"
+     *  banner while the agent was in fact trading normally. Past
+     *  REACHABILITY_STALL_FACTOR× the request budget we report `stalled` and the
+     *  reporter renders it `unknown`. A 451 still wins: the server ANSWERED, so
+     *  that classification stands however late we noticed it. */
+    probeReachability(): Promise<VenueReachabilityResult>;
+    /** The request budget the stall yardstick is measured against. ccxt owns the
+     *  actual timeout, so read it from the instance rather than hardcoding a
+     *  second copy that could silently drift from it. */
+    private probeTimeoutMs;
 }

package/ccxt/binance-public.js

@@ -33,6 +33,7 @@
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
 import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
+import { REACHABILITY_STALL_FACTOR } from '@reefclaw/shared';
 const TAG = 'binance-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -190,8 +191,19 @@ export class BinancePublicApi {
      *   - 'reachable'   clean response (driftMs = serverTime − localTime)
      *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
      *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
-     *   - 'unreachable' network / DNS / timeout / other error */
+     *   - 'stalled'     THIS process was starved — we learned nothing (issue #265)
+     *   - 'unreachable' network / DNS / timeout / other error
+     *
+     *  ★ Self-stall detection: an error is evidence about BINANCE only if it
+     *  arrived on schedule. When the host starves the process the loop stops
+     *  running, ccxt's own timeout lands minutes late, and the old code blamed the
+     *  network — producing a confident "you are geo-blocked / check your firewall"
+     *  banner while the agent was in fact trading normally. Past
+     *  REACHABILITY_STALL_FACTOR× the request budget we report `stalled` and the
+     *  reporter renders it `unknown`. A 451 still wins: the server ANSWERED, so
+     *  that classification stands however late we noticed it. */
     async probeReachability() {
+        const startedAt = Date.now();
         try {
             assertNotBanned('reachabilityProbe');
             const r = await this.exchange.fapiPublicGetTime({});
@@ -209,8 +221,24 @@ export class BinancePublicApi {
             }
             const msg = err instanceof Error ? err.message : String(err);
             const geo = msg.includes('451');
-            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
-            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+            if (geo) {
+                logger.warn(TAG, `probeReachability failed (HTTP 451 geo-block): ${msg}`);
+                return { outcome: 'geo_blocked', driftMs: null };
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs > this.probeTimeoutMs() * REACHABILITY_STALL_FACTOR) {
+                logger.warn(TAG, `probeReachability inconclusive: this process was starved — a ${this.probeTimeoutMs()}ms probe took ${Math.round(elapsedMs / 1000)}s (${msg}). Reporting reachability as unknown, NOT as a Binance failure.`);
+                return { outcome: 'stalled', driftMs: null, stallMs: elapsedMs };
+            }
+            logger.warn(TAG, `probeReachability failed: ${msg}`);
+            return { outcome: 'unreachable', driftMs: null };
         }
     }
+    /** The request budget the stall yardstick is measured against. ccxt owns the
+     *  actual timeout, so read it from the instance rather than hardcoding a
+     *  second copy that could silently drift from it. */
+    probeTimeoutMs() {
+        const t = Number(this.exchange?.timeout);
+        return Number.isFinite(t) && t > 0 ? t : 10_000;
+    }
 }

package/config/operator-provenance.d.ts

@@ -0,0 +1,6 @@
+export interface ProvenanceVerdict {
+    ok: boolean;
+    /** Agent-legible refusal — returned verbatim as the tool error. */
+    error?: string;
+}
+export declare function verifyOperatorProvenance(provided: unknown, configPath?: string): ProvenanceVerdict;

package/config/operator-provenance.js

@@ -0,0 +1,50 @@
+// Operator-provenance gate for the state-mutating operator tools
+// (audit 2026-07-26 F12).
+//
+// "Operator-only. Never called by the agent." was PROSE in four tool
+// descriptions — nothing enforced it, and `acknowledged:true` is
+// caller-supplied, so a tool-capable agent could walk the PAPER→LIVE ladder,
+// clear the exchange credentials, or disable the stop-loss requirement with
+// one impulsive call. The dashboard path (browser → relay → skill bridge →
+// gateway) now proves provenance: the bridge injects the rc_* connection
+// token it already authenticates with, and the plugin compares it against
+// its own copy. The chat redaction guards keep rc_* tokens OUT of the
+// agent's context, so the agent cannot produce one conversationally.
+//
+// THREAT-MODEL HONESTY: the agent runs on the operator's own box and could
+// read plugin-config with exec tools — this gate defends against one-call
+// LLM impulsivity (the realistic failure mode), not a deliberately
+// adversarial agent, which owns the box and could edit the config directly.
+//
+// Fail direction: OPEN when no connection token is configured (a pure-local
+// dev box has no dashboard to inject provenance — same
+// infrastructure-absent ⇒ allow direction as the entitlement gate);
+// CLOSED on a missing or mismatched token when one IS configured.
+// Read per call (no restart needed after a token rotation — F10 philosophy).
+import { timingSafeEqual } from 'node:crypto';
+import { readPluginConfig } from './plugin-config-io.js';
+import { resolveIngestToken } from './user-data-stream-config.js';
+const REFUSAL = 'operator_only: this tool changes safety-critical operator settings and accepts requests ' +
+    'ONLY from the ReefClaw dashboard (operator provenance token missing or invalid). Do not ' +
+    'retry and do not attempt to obtain the token — if this change is wanted, the OPERATOR ' +
+    'makes it from the dashboard Settings panel.';
+export function verifyOperatorProvenance(provided, configPath) {
+    let expected;
+    try {
+        expected = resolveIngestToken(readPluginConfig(configPath))?.trim() || undefined;
+    }
+    catch {
+        expected = undefined;
+    }
+    if (!expected)
+        return { ok: true }; // unconfigured box — nothing to prove against
+    const given = typeof provided === 'string' ? provided.trim() : '';
+    if (given.length === 0)
+        return { ok: false, error: REFUSAL };
+    const a = Buffer.from(given, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, error: REFUSAL };
+    }
+    return { ok: true };
+}

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

@@ -46,8 +46,12 @@ export interface PluginConfigFile {
     hl?: {
         marketSlippagePct?: number;
     };
+    /** MICRO_LIVE per-order notional cap in quote-USD (USDT on Binance, USDC on
+     *  Hyperliquid). Default 50 when the mode is MICRO_LIVE and no value is set.
+     *  `sizeCapPercent` used to be accepted here but was NEVER enforced by any
+     *  adapter (dead config implying protection it didn't provide) — it is no
+     *  longer read; loadMicroLiveConfig warns when it is present. */
     microLive?: {
-        sizeCapPercent?: number;
         maxPositionUSDT?: number;
     };
     /** Exchange-native bracket orders (STOP_MARKET + TAKE_PROFIT_MARKET).
@@ -202,6 +206,16 @@ export declare function defaultConfigPath(): string;
  *  the override to the default (same read-at-build-time pattern as
  *  loadBracketMode). */
 export declare function loadStopWatcherIntervalMs(path?: string): number | undefined;
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export declare function loadMicroLiveConfig(path?: string): {
+    maxPositionUSDT?: number;
+} | undefined;
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */

package/config/plugin-config-io.js

@@ -5,9 +5,15 @@
 // 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';
+import { logger } from '../logger.js';
 /** The connection the AGENT saves during onboarding lives in OpenClaw's own
  *  config (`skills.entries.reefclaw.config` in ~/.openclaw/openclaw.json) —
  *  the connector reads it there, and since the chat-install flow never writes
@@ -53,6 +59,29 @@ export function loadStopWatcherIntervalMs(path) {
     catch { /* best-effort — default applies */ }
     return undefined;
 }
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export function loadMicroLiveConfig(path) {
+    try {
+        const ml = readPluginConfig(path).microLive;
+        if (!ml || typeof ml !== 'object')
+            return undefined;
+        if (ml.sizeCapPercent !== undefined) {
+            logger.warn('plugin-config', 'microLive.sizeCapPercent is set but has NEVER been enforced by any adapter — it has no effect. ' +
+                'Remove it; microLive.maxPositionUSDT is the enforced per-order notional cap.');
+        }
+        const cap = ml.maxPositionUSDT;
+        if (typeof cap === 'number' && Number.isFinite(cap) && cap > 0)
+            return { maxPositionUSDT: cap };
+    }
+    catch { /* best-effort — adapter default applies */ }
+    return undefined;
+}
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */

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[]>;