@reefclaw/openclaw-plugin 0.1.13 → 0.1.15

package/bridge/providers/gateway.js

@@ -1,11 +1,12 @@
 // GatewayProvider — real OpenClaw gateway integration.
 // Connects to the OpenClaw gateway via HTTP and WebSocket,
 // streams live trading data, and emits ProviderEvents.
-import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { logger, formatError } from '../logger.js';
 import { isTradingMode } from '../types.js';
+import { toIntelSymbol } from '@reefclaw/shared';
 import { GatewayHttpClient } from '../gateway/gateway-http-client.js';
 import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
 import { discoverTools } from '../gateway/tool-discovery.js';
@@ -13,7 +14,7 @@ import { EventParser, mapCcxtBalance, mapCcxtOrder, extractLiquidationFields, ex
 import { Poller } from '../gateway/poller.js';
 import { ensureHeartbeatCron, isHeartbeatLikeName } from '../gateway/heartbeat-cron.js';
 import { parseIdentityName } from '../utils/identity-name.js';
-import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, } from './risk-calculator.js';
+import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, DRAWDOWN_ZONE_THRESHOLDS, TENANT_LIMIT_BOUNDS, boundedNum, validateDrawdownLadder, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, } from './onboarding-commands.js';
 const TAG = 'gateway';
@@ -219,6 +220,7 @@ export class GatewayProvider {
     agentStateInterval = null;
     toolRetryInterval = null;
     regimeInterval = null;
+    tradingParamsInterval = null;
     signalInterval = null;
     missionInterval = null;
     analyticsInterval = null;
@@ -239,6 +241,17 @@ export class GatewayProvider {
     atrSampleCount = 0;
     // ---- Current regime (Phase 9e: regime-conditional risk) ----
     currentRegime = 'UNKNOWN';
+    /** ★ The tenant's ENFORCED risk limits, mirrored from intel
+     *  `/api/trading-params` — the same row the plugin's `preTradeRiskCheck`
+     *  rejects orders against. Null until the first fetch lands (then
+     *  DEFAULT_RISK_LIMITS applies). Before this existed the dashboard's risk
+     *  banner ran on a hardcoded ladder that no enforcer used, so it could show
+     *  a red "Gate fail" for a limit nothing blocked on — and, in the other
+     *  direction, stay green while the plugin rejected every entry. */
+    riskLimits = null;
+    /** Tenant drawdown-zone boundaries. Drives the RED-zone auto-flatten, so a
+     *  stale/stricter local ladder here can flatten a live book early. */
+    drawdownThresholds = null;
     // ---- Trade tracking ----
     /** Timestamp of the most recent trade (fill event) — used in buildAgentState */
     lastTradeTs = null;
@@ -351,6 +364,10 @@ export class GatewayProvider {
             clearInterval(this.regimeInterval);
             this.regimeInterval = null;
         }
+        if (this.tradingParamsInterval) {
+            clearInterval(this.tradingParamsInterval);
+            this.tradingParamsInterval = null;
+        }
         if (this.signalInterval) {
             clearInterval(this.signalInterval);
             this.signalInterval = null;
@@ -572,10 +589,11 @@ export class GatewayProvider {
         const ctx = { http: this.http, toolMap: this.toolMap, symbol: this.config.symbol };
         // Pass a FRESH, all-symbols order snapshot so Kill cancels every working
         // order portfolio-wide and correctly identifies (and preserves) protective
-        // reduceOnly brackets. fetchFreshOpenOrders falls back to this.openOrders on
-        // any fetch error, so this never blocks the kill.
-        const freshOrders = await this.fetchFreshOpenOrders();
-        const result = await _executeKill(ctx, freshOrders);
+        // reduceOnly brackets. On a failed fresh read Kill still runs against the
+        // ≤60s cache (never blocked) but reports executed:false — a stale cache
+        // cannot verify coverage (audit 2026-07-26 F6).
+        const freshOrders = await this.fetchFreshOpenOrdersOrNull();
+        const result = await _executeKill(ctx, freshOrders, this.openOrders);
         this.agentMode = 'STOPPED';
         this.emitAgentState();
         return result;
@@ -660,16 +678,26 @@ export class GatewayProvider {
     // Thin wrappers — real logic lives in providers/onboarding-commands.ts
     // so unit tests can drive pure functions with a mocked HTTP client.
     async setTradingMode(mode, acknowledged) {
-        return executeSetTradingMode({ http: this.http, toolMap: this.toolMap }, mode, acknowledged);
+        return executeSetTradingMode(
+        // operatorToken = the rc_* connection token — the plugin refuses the
+        // four state-mutating operator tools without it (audit F12).
+        { http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, mode, acknowledged);
     }
     async setExchangeCredentials(apiKey, secret, testnet) {
-        return executeSetExchangeCredentials({ http: this.http, toolMap: this.toolMap }, apiKey, secret, testnet);
+        return executeSetExchangeCredentials({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, apiKey, secret, testnet);
     }
     async testExchangeCredentials(apiKey, secret, testnet) {
-        return executeTestExchangeCredentials({ http: this.http, toolMap: this.toolMap }, apiKey, secret, testnet);
+        return executeTestExchangeCredentials(
+        // operatorToken required since the SkillSpector hardening: the plugin
+        // refuses the credential-validation call without dashboard provenance.
+        { http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, apiKey, secret, testnet);
     }
     async clearExchangeCredentials() {
-        return executeClearExchangeCredentials({ http: this.http, toolMap: this.toolMap });
+        return executeClearExchangeCredentials({
+            http: this.http,
+            toolMap: this.toolMap,
+            operatorToken: this.config.connectionToken,
+        });
     }
     /** Operator-only. Read the current bracket-orders config from the plugin. */
     async getBracketConfig() {
@@ -677,7 +705,7 @@ export class GatewayProvider {
     }
     /** Operator-only. Flip requireStopLoss or requireTakeProfit. */
     async setBracketRequirement(flag, value) {
-        return executeSetBracketRequirement({ http: this.http, toolMap: this.toolMap }, flag, value);
+        return executeSetBracketRequirement({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, flag, value);
     }
     async getSnapshot() {
         logger.info(TAG, 'Reconciliation snapshot requested');
@@ -851,7 +879,13 @@ export class GatewayProvider {
         // Step 3: Create WS client and connect FIRST to obtain device token.
         // OpenClaw's REST API requires a device token from the WS handshake,
         // not the raw gateway auth token. Tool discovery must wait for this.
-        this.wsClient = new GatewayWsClient(this.config);
+        // Least privilege: operator.admin (cron management) is requested only
+        // while the once-per-install heartbeat-cron ensure is still owed — after
+        // the marker exists, every session runs on operator.read/write alone.
+        this.wsClient = new GatewayWsClient({
+            ...this.config,
+            requestAdminScope: !existsSync(join(homedir(), '.openclaw', 'workspace', 'heartbeat-cron-ensured.json')),
+        });
         this.wireWsEvents();
         // Wait for WS handshake to complete (or fail)
         const deviceToken = await this.waitForDeviceToken();
@@ -916,6 +950,9 @@ export class GatewayProvider {
         }
         // Step 6: Start regime poller if intelligence service is configured
         this.startRegimePoller();
+        // Step 6b: Mirror the tenant's ENFORCED risk limits. A safety input, so it
+        // runs even when the intel display pollers are shed.
+        this.startTradingParamsPoller();
         // Step 7: Start signal poller if intelligence service is configured
         this.startSignalPoller();
         // Step 8: Start mission poller if intelligence service is configured
@@ -1195,6 +1232,28 @@ export class GatewayProvider {
     canonicalSymbol(s) {
         return typeof s === 'string' ? s.replace(/:[A-Z]+$/, '') : s;
     }
+    /** Canonical symbol → the intel DB symbol for this box's venue.
+     *  binance: 'BTC/USDT' → 'BTCUSDT'; hyperliquid: 'BTC/USDC' → 'HL_BTC'.
+     *
+     *  ★ The old venue-blind `.replace('/','')` produced 'BTCUSDC' on a
+     *  hyperliquid box — a symbol no intel row has ever carried (intel
+     *  namespaces every HL row under the 'HL_' prefix). That silently broke the
+     *  regime/signal/mission/analytics pollers AND wrote every trade result to a
+     *  symbol Kelly sizing would never read back, so a hyperliquid box stayed at
+     *  `insufficient_history` even once the reporting path itself worked.
+     *
+     *  FAILS OPEN: an unmappable symbol falls back to the legacy concatenation
+     *  so intel answers "no data for <echo>" — honest and debuggable — rather
+     *  than the caller throwing and dropping the report entirely. */
+    toIntelSymbol(symbol) {
+        const canonical = this.canonicalSymbol(symbol);
+        try {
+            return toIntelSymbol(this.config.venue ?? 'binance', canonical);
+        }
+        catch {
+            return canonical.replace('/', '');
+        }
+    }
     async onPollerPositions(positions) {
         // Canonicalize symbols at this single position-ingress chokepoint so
         // the ENTIRE skill (position-diff, openTradeEntries keys, snapshots,
@@ -1610,7 +1669,9 @@ export class GatewayProvider {
     /** Simple heat score (0–100) matching webapp's HeatGauge logic */
     computeHeatScoreSimple(metrics) {
         const { grossExposure, dailyDrawdown, ordersPerMinute, cancelsPerMinute } = metrics.utilization;
-        const limits = DEFAULT_RISK_LIMITS;
+        // Same enforced limits the breach detector uses — otherwise the heat gauge
+        // and the gate disagree about what "hot" means.
+        const limits = this.riskLimits ?? DEFAULT_RISK_LIMITS;
         const scores = [
             limits.position.maxGrossExposure > 0 ? (grossExposure / limits.position.maxGrossExposure) * 100 : 0,
             limits.loss.maxDailyDrawdown < 0 ? (dailyDrawdown / limits.loss.maxDailyDrawdown) * 100 : 0,
@@ -1737,10 +1798,15 @@ export class GatewayProvider {
             return this.balance;
         }
     }
-    async fetchFreshOpenOrders() {
+    /** Strict fresh read — null on ANY failure (missing tool, thrown fetch,
+     *  non-array garbage). Callers whose verdict claims order-state coverage
+     *  (Kill) MUST distinguish "confirmed list" from "unknown"; collapsing a
+     *  failed read into the ≤60s cache here was how a stale-empty cache became
+     *  a green "No open orders to cancel" (audit 2026-07-26 F6). */
+    async fetchFreshOpenOrdersOrNull() {
         const tool = this.toolMap.fetch_open_orders;
         if (!tool || !this.http)
-            return this.openOrders;
+            return null;
         try {
             // Fetch ALL open orders (no symbol filter). Multi-symbol orphan orders
             // submitted while the browser was disconnected must show up in the
@@ -1749,7 +1815,7 @@ export class GatewayProvider {
             const result = await this.http.invoke(tool, {});
             if (!Array.isArray(result.data)) {
                 logger.warn(TAG, `fetch_open_orders returned non-array: ${typeof result.data}`);
-                return this.openOrders;
+                return null;
             }
             const mapped = result.data
                 .map((o) => mapCcxtOrder(o))
@@ -1761,10 +1827,15 @@ export class GatewayProvider {
             return mapped;
         }
         catch (err) {
-            logger.warn(TAG, `Fresh open orders fetch failed, using cached: ${err instanceof Error ? err.message : String(err)}`);
-            return this.openOrders;
+            logger.warn(TAG, `Fresh open orders fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
         }
     }
+    /** Cached-fallback wrapper for DISPLAY surfaces (the reconcile snapshot):
+     *  stale data beats a blank panel there. Never use for emergency verdicts. */
+    async fetchFreshOpenOrders() {
+        return (await this.fetchFreshOpenOrdersOrNull()) ?? this.openOrders;
+    }
     async fetchAgentHealth() {
         const ws = this.wsClient;
         if (!ws)
@@ -2261,6 +2332,8 @@ export class GatewayProvider {
             atrData: this.atrData ?? undefined,
             regime: this.currentRegime,
             realizedPnlToday: this.realizedPnlToday ?? undefined,
+            baseLimits: this.riskLimits ?? undefined,
+            drawdownThresholds: this.drawdownThresholds ?? undefined,
         });
         // Store pruned timestamps back (non-mutating function returns new arrays)
         this.orderTimestamps = result.prunedOrderTimestamps;
@@ -2309,7 +2382,13 @@ export class GatewayProvider {
         const url = this.config.intelligenceUrl;
         const token = this.config.connectionToken;
         if (!url || !token) {
-            logger.debug(TAG, 'Intelligence not configured — skipping trade result report');
+            // NEVER debug-level. This is the only writer of intel's `trade_results`,
+            // and those rows are what `minTradesForKelly` counts and what
+            // `get_agent_profile` derives its tier from. Silently skipping here is
+            // indistinguishable from "the agent has never traded" — which is exactly
+            // how it read for months. See DEFAULT_INTELLIGENCE_URL in gateway-config.
+            logger.warn(TAG, `Intelligence not configured (url=${url ? 'set' : 'MISSING'}, token=${token ? 'set' : 'MISSING'}) — DROPPING trade result for ${symbol}. `
+                + 'Kelly sizing and the agent profile are computed from these rows and will stay pinned at their no-history defaults.');
             return;
         }
         const direction = entry.side === 'long' ? 'LONG' : 'SHORT';
@@ -2321,7 +2400,7 @@ export class GatewayProvider {
         const durationSeconds = Math.floor((Date.now() - new Date(entry.entryTime).getTime()) / 1000);
         const tradeResult = {
             missionId: entry.missionId ?? `trade-${Date.now()}`,
-            symbol: symbol.replace('/', ''), // BTC/USDT → BTCUSDT for Intelligence API
+            symbol: this.toIntelSymbol(symbol), // venue-aware: BTC/USDT → BTCUSDT, BTC/USDC → HL_BTC
             direction,
             strategy: this.lastKnownStrategy.name,
             regime: entry.regime ?? this.currentRegime,
@@ -2406,9 +2485,9 @@ export class GatewayProvider {
         }
     }
     // ---- Intelligence service polling ----
-    /** Symbol formatted for intelligence API (BTC/USDT → BTCUSDT). */
+    /** The configured symbol as the intel DB spells it. */
     get intelligenceSymbol() {
-        return this.config.symbol.replace('/', '');
+        return this.toIntelSymbol(this.config.symbol);
     }
     /** Shared intelligence poller with circuit-breaker (exponential backoff on errors). */
     startIntelligencePoller(name, endpoint, intervalMs, onData, intervalRef, delayFirstMs = 0) {
@@ -2420,6 +2499,21 @@ export class GatewayProvider {
             }
             return;
         }
+        // These five read-pollers (regime 60s, signals 10s, missions 10s,
+        // analytics 30s, decision-trace 30s ≈ 22 req/min per box) were dormant for
+        // as long as `intelligenceUrl` had no default. Giving it one turns them on
+        // everywhere, which is the intended behaviour — they feed the dashboard's
+        // regime/signals/missions panels — but it IS new load on an intel API with
+        // a known heap leak. Kill-switch so that load can be shed in one restart
+        // WITHOUT taking the trade_results writer down with it: the writer is what
+        // Kelly sizing and the agent tier are computed from, and it does not go
+        // through this function.
+        if (process.env.RC_SKILL_INTEL_POLL === 'off') {
+            if (name === 'regime') {
+                logger.warn(TAG, 'RC_SKILL_INTEL_POLL=off — intelligence read-polling disabled (trade-result reporting is unaffected)');
+            }
+            return;
+        }
         const symbol = this.intelligenceSymbol;
         const fullUrl = `${url}/api/${endpoint}/${symbol}`;
         logger.info(TAG, `Starting ${name} poller: ${fullUrl}`);
@@ -2474,6 +2568,99 @@ export class GatewayProvider {
             this.fire('regimeUpdate', { ...data, event: 'regime_update', symbol });
         }, 'regimeInterval');
     }
+    /**
+     * Mirror the tenant's trading params into the risk limits the dashboard
+     * banner and the RED-zone auto-flatten run on.
+     *
+     * Deliberately NOT routed through `startIntelligencePoller`: that helper
+     * appends `/${symbol}` and is gated by `RC_SKILL_INTEL_POLL=off`. These
+     * limits are a safety input, not a dashboard read — shedding intel display
+     * load must not silently revert the operator's configured limits to the
+     * fallback ladder.
+     *
+     * Fail-open by design: a failed fetch keeps the last good values (or the
+     * fallback constants on a cold start). We never tighten limits from a
+     * parse failure, and we never widen them past what the plugin enforces —
+     * the plugin re-reads the same row for the gate that actually blocks.
+     */
+    startTradingParamsPoller() {
+        const url = this.config.intelligenceUrl;
+        const token = this.config.connectionToken;
+        if (!url || !token)
+            return;
+        const fullUrl = `${url}/api/trading-params`;
+        logger.info(TAG, `Starting trading-params poller: ${fullUrl}`);
+        const poll = async () => {
+            if (!this.started)
+                return;
+            try {
+                const res = await fetch(fullUrl, {
+                    headers: { Authorization: `Bearer ${token}` },
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!res.ok) {
+                    this.trackIntelError('tradingParams', `HTTP ${res.status}`);
+                    return;
+                }
+                const body = (await res.json());
+                const p = body?.params;
+                if (!p)
+                    return;
+                // Every field is bounds-checked against hardcoded bands
+                // (TENANT_LIMIT_BOUNDS / validateDrawdownLadder) — CLAUDE.md
+                // load-bearing rule: central config moves knobs only WITHIN hardcoded
+                // bounds; it must never be able to disable a safety mechanism.
+                // Out-of-band → field ignored, previous value kept.
+                const B = TENANT_LIMIT_BOUNDS;
+                const maxPositionSize = boundedNum(p.maxPositionSize, B.maxPositionSize.min, B.maxPositionSize.max);
+                const maxOpenPositions = boundedNum(p.maxOpenPositions, B.maxOpenPositions.min, B.maxOpenPositions.max);
+                const maxGrossExposure = boundedNum(p.maxGrossExposure, B.maxGrossExposure.min, B.maxGrossExposure.max);
+                const maxPerTradeLoss = boundedNum(p.maxPerTradeLoss, B.maxPerTradeLoss.min, B.maxPerTradeLoss.max);
+                // Validate the zone ladder FIRST — the loss limit below reads from the
+                // ACCEPTED ladder, so a rejected row can't leak its RED into
+                // maxDailyDrawdown (which drives the dailyDrawdown AUTO_PAUSE breach).
+                const base = this.drawdownThresholds ?? DRAWDOWN_ZONE_THRESHOLDS;
+                const next = {
+                    YELLOW: boundedNum(p.drawdownYellow, -1, 0) ?? base.YELLOW,
+                    ORANGE: boundedNum(p.drawdownOrange, -1, 0) ?? base.ORANGE,
+                    RED: boundedNum(p.drawdownRed, -1, 0) ?? base.RED,
+                };
+                const ladderError = validateDrawdownLadder(next);
+                if (ladderError === null) {
+                    this.drawdownThresholds = next;
+                }
+                else {
+                    logger.warn(TAG, `Ignoring drawdown zones from trading params: ${ladderError}`);
+                }
+                const prev = this.riskLimits ?? DEFAULT_RISK_LIMITS;
+                const acceptedRed = this.drawdownThresholds?.RED;
+                this.riskLimits = {
+                    position: {
+                        maxPositionSize: maxPositionSize ?? prev.position.maxPositionSize,
+                        maxOpenPositions: maxOpenPositions ?? prev.position.maxOpenPositions,
+                        maxGrossExposure: maxGrossExposure ?? prev.position.maxGrossExposure,
+                        // Intel has no separate net-tilt param; the gross cap bounds it
+                        // (|net| ≤ gross always, so this can never fire before gross).
+                        maxNetExposure: maxGrossExposure ?? prev.position.maxNetExposure,
+                    },
+                    loss: {
+                        // Drawdown limit tracks the operator's RED boundary rather than a
+                        // third independent number.
+                        maxDailyDrawdown: acceptedRed ?? prev.loss.maxDailyDrawdown,
+                        maxPerTradeLoss: maxPerTradeLoss != null ? -Math.abs(maxPerTradeLoss) : prev.loss.maxPerTradeLoss,
+                        maxDailyLoss: prev.loss.maxDailyLoss,
+                    },
+                    rate: prev.rate,
+                };
+                this.intelErrors.tradingParams = 0;
+            }
+            catch (err) {
+                this.trackIntelError('tradingParams', formatError(err));
+            }
+        };
+        void poll();
+        this.tradingParamsInterval = setInterval(() => { void poll(); }, 60_000);
+    }
     startSignalPoller() {
         this.startIntelligencePoller('signals', 'signals', 10_000, (raw) => {
             const data = raw;

package/bridge/providers/onboarding-commands.d.ts

@@ -38,6 +38,17 @@ export interface ClearExchangeCredentialsOutcome {
 export interface OnboardingContext {
     http: GatewayHttpClient | null;
     toolMap: ToolMap;
+    /** rc_* connection token, injected as `operator_token` on the operator-only
+     *  tools: the four state-MUTATING ones (set_trading_mode /
+     *  set_exchange_credentials / clear_exchange_credentials /
+     *  set_bracket_requirement, audit 2026-07-26 F12) plus
+     *  test_exchange_credentials (read-only, but a live authenticated exchange
+     *  call with caller-supplied keys — without the gate it would hand a
+     *  prompt-injected agent a credential-validation oracle). The plugin refuses
+     *  these calls without it — the operator-provenance proof that the request
+     *  came through the dashboard path, which the agent cannot forge
+     *  conversationally (chat redaction strips rc_* tokens). */
+    operatorToken?: string;
 }
 export type BracketMode = 'off' | 'observe' | 'enforce';
 export type BracketRequirementFlag = 'requireStopLoss' | 'requireTakeProfit';

package/bridge/providers/onboarding-commands.js

@@ -23,7 +23,7 @@ export async function executeSetTradingMode(ctx, mode, acknowledged) {
         };
     }
     try {
-        const result = await ctx.http.invoke(tool, { mode, acknowledged });
+        const result = await ctx.http.invoke(tool, { mode, acknowledged, operator_token: ctx.operatorToken });
         return result.data;
     }
     catch (err) {
@@ -57,7 +57,7 @@ export async function executeTestExchangeCredentials(ctx, apiKey, secret, testne
         };
     }
     try {
-        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet });
+        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet, operator_token: ctx.operatorToken });
         return result.data;
     }
     catch (err) {
@@ -93,7 +93,7 @@ export async function executeClearExchangeCredentials(ctx) {
         };
     }
     try {
-        const result = await ctx.http.invoke(tool, { confirm: true });
+        const result = await ctx.http.invoke(tool, { confirm: true, operator_token: ctx.operatorToken });
         return result.data;
     }
     catch (err) {
@@ -162,7 +162,7 @@ export async function executeSetBracketRequirement(ctx, flag, value) {
         };
     }
     try {
-        const result = await ctx.http.invoke(tool, { flag, value });
+        const result = await ctx.http.invoke(tool, { flag, value, operator_token: ctx.operatorToken });
         return result.data;
     }
     catch (err) {
@@ -194,7 +194,7 @@ export async function executeSetExchangeCredentials(ctx, apiKey, secret, testnet
         };
     }
     try {
-        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet });
+        const result = await ctx.http.invoke(tool, { apiKey, secret, testnet, operator_token: ctx.operatorToken });
         return result.data;
     }
     catch (err) {

package/bridge/providers/risk-calculator.d.ts

@@ -10,11 +10,53 @@ export declare const REGIME_LIMIT_PROFILES: Record<string, Partial<{
 }>>;
 /** Apply regime-conditional adjustments to limits. */
 export declare function applyRegimeAdjustment(baseLimits: RiskLimits, regime: string): RiskLimits;
+/** 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 declare const DRAWDOWN_ZONE_THRESHOLDS: {
     readonly YELLOW: -0.01;
     readonly ORANGE: -0.02;
     readonly RED: -0.025;
 };
+export interface DrawdownThresholds {
+    YELLOW: number;
+    ORANGE: number;
+    RED: number;
+}
+/** The auto-flatten trigger can never be configured looser than −10%. */
+export declare const AUTO_FLATTEN_RED_FLOOR = -0.1;
+/** Sanity bands for tenant limit fields. Values outside → field ignored,
+ *  previous value kept. Wide on purpose: these reject nonsense, not policy. */
+export declare const TENANT_LIMIT_BOUNDS: {
+    readonly maxPositionSize: {
+        readonly min: 1;
+        readonly max: 1000000000;
+    };
+    readonly maxOpenPositions: {
+        readonly min: 1;
+        readonly max: 100;
+    };
+    readonly maxGrossExposure: {
+        readonly min: 0.01;
+        readonly max: 20;
+    };
+    readonly maxPerTradeLoss: {
+        readonly min: 0.01;
+        readonly max: 10000000;
+    };
+};
+/** Finite number within [min, max], else null. */
+export declare function boundedNum(v: unknown, min: number, max: number): number | 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 declare function validateDrawdownLadder(t: DrawdownThresholds): string | null;
 export type DrawdownZone = 'GREEN' | 'YELLOW' | 'ORANGE' | 'RED';
 /** State snapshot needed to compute equity. */
 export interface EquityState {
@@ -36,6 +78,12 @@ export interface RiskState {
     };
     regime?: string;
     realizedPnlToday?: number;
+    /** The tenant's configured limits (from intel `/api/trading-params`) — the
+     *  SAME numbers the plugin's pre-trade gate enforces. Omitted until the
+     *  first fetch lands, in which case DEFAULT_RISK_LIMITS applies. */
+    baseLimits?: RiskLimits;
+    /** The tenant's configured drawdown-zone boundaries. Omitted → fallback. */
+    drawdownThresholds?: DrawdownThresholds;
 }
 /** Result of computeRiskMetrics including pruned timestamp arrays. */
 export interface RiskMetricsResult {
@@ -51,7 +99,7 @@ export declare function computeVolFactor(state: {
 /** Apply volatility adjustment to base limits. Tightens position/exposure, leaves loss/rate unchanged. */
 export declare function applyVolatilityAdjustment(baseLimits: RiskLimits, volFactor: number): RiskLimits;
 /** Determine drawdown zone from drawdown ratio (e.g. -0.015 = -1.5%). */
-export declare function getDrawdownZone(drawdownRatio: number): DrawdownZone;
+export declare function getDrawdownZone(drawdownRatio: number, thresholds?: DrawdownThresholds): DrawdownZone;
 /** Human-readable message for a drawdown zone. */
 export declare function getDrawdownZoneMessage(zone: DrawdownZone, ratio: number): string;
 /**
@@ -80,6 +128,17 @@ export declare function countRecentEvents(timestamps: number[]): {
 };
 /**
  * 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 declare function detectBreaches(metrics: {
     grossExposure: number;
@@ -88,7 +147,7 @@ export declare function detectBreaches(metrics: {
     dailyLoss?: number;
     ordersPerMinute: number;
     cancelsPerMinute: number;
-}, limits: RiskLimits): RiskBreach[];
+}, limits: RiskLimits, advisoryLimits?: RiskLimits): RiskBreach[];
 /**
  * Compute full risk metrics from a state snapshot.
  * Returns metrics + pruned timestamp arrays for the caller to store.