@reefclaw/openclaw-plugin 0.1.0

package/ccxt/binance-public.d.ts

@@ -0,0 +1,18 @@
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+export declare class BinancePublicApi {
+    private exchange;
+    constructor();
+    /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
+    fetchTickerRaw(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch current ticker for a symbol. Returns null on error. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    /** Fetch funding rate for a perpetual futures symbol. Returns null on error. */
+    fetchFundingRate(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch open interest for a perpetual futures symbol. Returns null on error. */
+    fetchOpenInterest(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch order book depth. Returns null on error. */
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    /** Fetch OHLCV candles. Returns null on error. */
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+}

package/ccxt/binance-public.js

@@ -0,0 +1,147 @@
+// Thin wrapper around CCXT for Binance public API endpoints.
+// No API keys required — only uses public market data.
+import { createRequire } from 'node:module';
+import { logger } from '../logger.js';
+import { assertNotBanned, noteBinanceError, noteSuccess } from './binance-ban-gate.js';
+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
+let ccxtCjs;
+try {
+    const _require = createRequire(import.meta.url);
+    ccxtCjs = _require('ccxt');
+}
+catch {
+    // Fallback: try global require (available in OpenClaw's loader context)
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ccxtCjs = require('ccxt');
+}
+export class BinancePublicApi {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    exchange;
+    constructor() {
+        const BinanceClass = ccxtCjs.binance ?? ccxtCjs.default?.binance;
+        if (!BinanceClass) {
+            throw new Error('CCXT binance class not found — check ccxt version');
+        }
+        this.exchange = new BinanceClass({
+            enableRateLimit: true,
+        });
+        logger.info(TAG, 'Binance public API initialized (no auth)');
+    }
+    /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchTickerRaw(symbol) {
+        try {
+            assertNotBanned('fetchTickerRaw');
+            const r = await this.exchange.fetchTicker(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTickerRaw(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch current ticker for a symbol. Returns null on error. */
+    async fetchTicker(symbol) {
+        try {
+            assertNotBanned('fetchTicker');
+            const raw = await this.exchange.fetchTicker(symbol);
+            noteSuccess();
+            return {
+                symbol: raw.symbol,
+                last: raw.last ?? 0,
+                bid: raw.bid ?? 0,
+                ask: raw.ask ?? 0,
+                baseVolume: raw.baseVolume ?? 0,
+                quoteVolume: raw.quoteVolume ?? 0,
+                change: raw.change ?? 0,
+                percentage: raw.percentage ?? 0,
+                timestamp: raw.timestamp ?? Date.now(),
+                datetime: raw.datetime ?? new Date().toISOString(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTicker(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch funding rate for a perpetual futures symbol. Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchFundingRate(symbol) {
+        try {
+            assertNotBanned('fetchFundingRate');
+            const r = await this.exchange.fetchFundingRate(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchFundingRate(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch open interest for a perpetual futures symbol. Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchOpenInterest(symbol) {
+        try {
+            assertNotBanned('fetchOpenInterest');
+            const r = await this.exchange.fetchOpenInterest(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOpenInterest(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch order book depth. Returns null on error. */
+    async fetchOrderBook(symbol, limit = 20) {
+        try {
+            assertNotBanned('fetchOrderBook');
+            const raw = await this.exchange.fetchOrderBook(symbol, limit);
+            noteSuccess();
+            return {
+                bids: (raw.bids ?? []).map((l) => [l[0], l[1]]),
+                asks: (raw.asks ?? []).map((l) => [l[0], l[1]]),
+                timestamp: raw.timestamp ?? Date.now(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOrderBook(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch OHLCV candles. Returns null on error. */
+    async fetchOHLCV(symbol, timeframe = '1h', limit = 100) {
+        try {
+            assertNotBanned('fetchOHLCV');
+            const raw = await this.exchange.fetchOHLCV(symbol, timeframe, undefined, limit);
+            noteSuccess();
+            // Validate each candle has 6 numeric values
+            const valid = [];
+            for (const candle of raw) {
+                if (candle.length >= 6 &&
+                    typeof candle[0] === 'number' &&
+                    typeof candle[1] === 'number' &&
+                    typeof candle[2] === 'number' &&
+                    typeof candle[3] === 'number' &&
+                    typeof candle[4] === 'number' &&
+                    typeof candle[5] === 'number') {
+                    valid.push(candle);
+                }
+            }
+            return valid;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOHLCV(${symbol}, ${timeframe}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,55 @@
+/** Central operational-gate values. Each gate is validated against its own enum
+ *  PLUGIN-SIDE (§5b: central can never express a value the plugin doesn't
+ *  already consider safe); an invalid field is dropped — field-level fallback,
+ *  never whole-payload rejection. Gates are added one at a time
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3): `exitGate` (slice 2) →
+ *  `positionReviewMode` (slice 3, the Position Decision Journal
+ *  heartbeat-mandate + superset gate, file key `positionReview.mode`). Both
+ *  ride the same four-stage `off → shadow → observe → enforce` ladder. */
+export interface AgentGates {
+    exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
+    positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+}
+/** The slice of /api/internal/config the plugin consumes today. `limits`
+ *  arrives in the payload but is deliberately not modeled yet. */
+export interface AgentConfig {
+    version: number;
+    tools: {
+        disabled: string[];
+    };
+    gates: AgentGates;
+}
+/** Hardcoded safe default — identical to pre-central behavior (nothing
+ *  disabled, no central gate values → local file / defaults rule). */
+export declare function defaultAgentConfig(): AgentConfig;
+/**
+ * Validate an untrusted payload (network response OR cache file) into an
+ * AgentConfig. Returns null when the payload as a whole is malformed —
+ * partial application is never allowed (§5b: central cannot express a value
+ * the plugin doesn't already consider safe).
+ */
+export declare function validateAgentConfig(raw: unknown): AgentConfig | null;
+/** Version-monotonic acceptance (basic rollback/replay protection): a fetched
+ *  config older than what we already applied is rejected. Equal versions are
+ *  acceptable (idempotent re-apply is a no-op for the gate). */
+export declare function isAcceptableVersion(fetched: AgentConfig, current: AgentConfig | null): boolean;
+export interface FetchAgentConfigOptions {
+    apiBaseUrl: string;
+    token: string;
+    /** Injectable for unit tests + observability shims. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Fetch the central config. Returns a VALIDATED AgentConfig, or null on any
+ * failure (network, non-200, non-JSON, invalid shape). Never throws.
+ */
+export declare function fetchAgentConfig(opts: FetchAgentConfigOptions): Promise<AgentConfig | null>;
+export declare function defaultCachePath(): string;
+/** Read + validate the cached config. Missing/corrupt/invalid → null (the
+ *  caller falls through to safe defaults). Never throws. */
+export declare function readCachedConfig(path?: string): AgentConfig | null;
+/** Atomically persist the last-known-good config (tmp + rename, 0o600 — the
+ *  plugin-config-io convention). Failures are logged, never thrown: cache
+ *  persistence is an optimization, not a correctness requirement. */
+export declare function writeCachedConfig(config: AgentConfig, path?: string): void;

package/config/agent-config-client.js

@@ -0,0 +1,145 @@
+// Central per-user agent config — fetch + validate + last-known-good cache.
+//
+// Slice 1 of docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5: the plugin PULLS
+// `GET /api/internal/config` (webapp, rc_ token → tenant) and applies the
+// tool-enablement OFF-list through the ToolGate. The critical contract (§5b):
+// only a successful, authenticated, VALIDATED, version-acceptable response
+// ever changes behavior. A network error, 5xx, 401, garbage payload, or
+// corrupt cache file can NEVER change what the agent does — the caller keeps
+// the last-known-good config, or the hardcoded safe default (nothing
+// disabled).
+//
+// The cache file lives next to plugin-config.json (`~/.reefclaw/
+// agent-config-cache.json`) and follows the same atomic write convention
+// (tmp + rename, mode 0o600 — see plugin-config-io.ts). It is validated on
+// read with the same validator as the network path: a poisoned cache is as
+// untrusted as a poisoned response.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { logger, formatError } from '../logger.js';
+const TAG = 'agent-config';
+/** Shared four-stage ladder for the gates migrated so far. Kept as one set
+ *  because exitGate + positionReviewMode use identical values; a future gate
+ *  with a different enum gets its own constant. */
+const MODE_LADDER_VALUES = new Set(['off', 'shadow', 'observe', 'enforce']);
+/** Hardcoded safe default — identical to pre-central behavior (nothing
+ *  disabled, no central gate values → local file / defaults rule). */
+export function defaultAgentConfig() {
+    return { version: 0, tools: { disabled: [] }, gates: {} };
+}
+/** Tool names must look like tool names. Anything else is dropped — central
+ *  can never smuggle a weird value into the gate's set. */
+const TOOL_NAME_RE = /^[a-z0-9_]{1,64}$/;
+/**
+ * Validate an untrusted payload (network response OR cache file) into an
+ * AgentConfig. Returns null when the payload as a whole is malformed —
+ * partial application is never allowed (§5b: central cannot express a value
+ * the plugin doesn't already consider safe).
+ */
+export function validateAgentConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const version = obj.version;
+    if (typeof version !== 'number' || !Number.isFinite(version) || version < 0)
+        return null;
+    const tools = obj.tools;
+    if (!tools || typeof tools !== 'object' || Array.isArray(tools))
+        return null;
+    const disabledRaw = tools.disabled;
+    if (!Array.isArray(disabledRaw))
+        return null;
+    const disabled = disabledRaw.filter((v) => typeof v === 'string' && TOOL_NAME_RE.test(v));
+    return { version, tools: { disabled }, gates: validateGates(obj.gates) };
+}
+/** Per-field gate validation (§5b): a structurally-absent/garbage `gates`
+ *  becomes `{}` (no central values → local config rules); each known gate is
+ *  kept only when its value is in that gate's enum. Unknown keys are dropped. */
+function validateGates(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const obj = raw;
+    const gates = {};
+    const exitGate = obj.exitGate;
+    if (typeof exitGate === 'string' && MODE_LADDER_VALUES.has(exitGate)) {
+        gates.exitGate = exitGate;
+    }
+    const positionReviewMode = obj.positionReviewMode;
+    if (typeof positionReviewMode === 'string' && MODE_LADDER_VALUES.has(positionReviewMode)) {
+        gates.positionReviewMode = positionReviewMode;
+    }
+    return gates;
+}
+/** Version-monotonic acceptance (basic rollback/replay protection): a fetched
+ *  config older than what we already applied is rejected. Equal versions are
+ *  acceptable (idempotent re-apply is a no-op for the gate). */
+export function isAcceptableVersion(fetched, current) {
+    if (!current)
+        return true;
+    return fetched.version >= current.version;
+}
+/**
+ * Fetch the central config. Returns a VALIDATED AgentConfig, or null on any
+ * failure (network, non-200, non-JSON, invalid shape). Never throws.
+ */
+export async function fetchAgentConfig(opts) {
+    const { apiBaseUrl, token, fetchImpl = fetch, timeoutMs = 10_000 } = opts;
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/config`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            logger.debug(TAG, `config fetch non-200: ${res.status}`);
+            return null;
+        }
+        const body = (await res.json());
+        const validated = validateAgentConfig(body);
+        if (!validated)
+            logger.warn(TAG, 'config fetch returned an invalid payload — ignored');
+        return validated;
+    }
+    catch (err) {
+        logger.debug(TAG, `config fetch failed: ${formatError(err)}`);
+        return null;
+    }
+}
+// ---- last-known-good cache file ---------------------------------------------
+export function defaultCachePath() {
+    return join(homedir(), '.reefclaw', 'agent-config-cache.json');
+}
+/** Read + validate the cached config. Missing/corrupt/invalid → null (the
+ *  caller falls through to safe defaults). Never throws. */
+export function readCachedConfig(path = defaultCachePath()) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, 'utf-8');
+        return validateAgentConfig(JSON.parse(raw));
+    }
+    catch (err) {
+        logger.warn(TAG, `config cache unreadable (${formatError(err)}) — using safe defaults`);
+        return null;
+    }
+}
+/** Atomically persist the last-known-good config (tmp + rename, 0o600 — the
+ *  plugin-config-io convention). Failures are logged, never thrown: cache
+ *  persistence is an optimization, not a correctness requirement. */
+export function writeCachedConfig(config, path = defaultCachePath()) {
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const tmpPath = `${path}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n', {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        logger.warn(TAG, `config cache write failed: ${formatError(err)}`);
+    }
+}

package/config/agent-config-poller.d.ts

@@ -0,0 +1,25 @@
+import { type AgentConfig, type AgentGates } from './agent-config-client.js';
+import type { ToolGate } from './tool-gate.js';
+export declare function resolvePollIntervalMs(): number;
+export interface AgentConfigPollerOptions {
+    gate: ToolGate;
+    /** Central operational-gates consumer (slice 2 — exitGate). Optional so the
+     *  tool-allowlist path stands alone; wired from index.ts with the module
+     *  singleton `gateStore`. */
+    gateStore?: {
+        apply(gates: AgentGates): void;
+    };
+    apiBaseUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    intervalMs?: number;
+    cachePath?: string;
+}
+export interface AgentConfigPollerHandle {
+    stop(): void;
+    /** Exposed for tests/diagnostics — the currently applied config. */
+    getCurrent(): AgentConfig;
+}
+/** Test-only — allows the singleton guard to be reset between unit tests. */
+export declare function __resetPollerSingleton(): void;
+export declare function startAgentConfigPoller(opts: AgentConfigPollerOptions): AgentConfigPollerHandle;

package/config/agent-config-poller.js

@@ -0,0 +1,100 @@
+// Agent-config poller — boots the ToolGate from central config and keeps it
+// fresh (docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5b).
+//
+// Boot:    fetch → valid + version-acceptable → apply + write cache
+//          fetch fails → last-known-good cache file → apply
+//          nothing     → hardcoded safe default (nothing disabled)
+// Runtime: re-poll every RC_AGENT_CONFIG_POLL_MS (default 60s). Every failed
+//          poll is a keep-last-known-good no-op. Version-lower responses are
+//          rejected (rollback guard). The interval is unref()'d so it never
+//          holds the process open at shutdown.
+//
+// No token → the poller does not start at all: the gate stays empty (all
+// tools on), byte-identical to pre-feature behavior. A module-level singleton
+// guard mirrors `pluginInitialised` in index.ts — OpenClaw calls register()
+// multiple times per process and we must never spawn a second timer.
+import { defaultAgentConfig, fetchAgentConfig, isAcceptableVersion, readCachedConfig, writeCachedConfig, } from './agent-config-client.js';
+import { logger } from '../logger.js';
+const TAG = 'agent-config';
+const DEFAULT_POLL_MS = 60_000;
+const MIN_POLL_MS = 5_000;
+export function resolvePollIntervalMs() {
+    const raw = Number(process.env.RC_AGENT_CONFIG_POLL_MS);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_POLL_MS;
+    return Math.max(MIN_POLL_MS, raw);
+}
+let pollerStarted = false;
+/** Test-only — allows the singleton guard to be reset between unit tests. */
+export function __resetPollerSingleton() {
+    pollerStarted = false;
+}
+export function startAgentConfigPoller(opts) {
+    const noop = {
+        stop: () => { },
+        getCurrent: () => defaultAgentConfig(),
+    };
+    if (pollerStarted) {
+        logger.warn(TAG, 'poller already started — ignoring duplicate start');
+        return noop;
+    }
+    if (!opts.token || !opts.token.trim()) {
+        logger.info(TAG, 'no connection token — central tool config disabled, all tools enabled (safe default)');
+        return noop;
+    }
+    pollerStarted = true;
+    const intervalMs = opts.intervalMs ?? resolvePollIntervalMs();
+    let current = defaultAgentConfig();
+    let loggedFetchFailure = false;
+    const applyIfAcceptable = (fetched, source) => {
+        if (!isAcceptableVersion(fetched, current)) {
+            logger.warn(TAG, `rejected ${source} config v${fetched.version} < applied v${current.version} (rollback guard)`);
+            return false;
+        }
+        current = fetched;
+        opts.gate.apply(fetched);
+        opts.gateStore?.apply(fetched.gates);
+        return true;
+    };
+    const poll = async (isBoot) => {
+        const fetched = await fetchAgentConfig({
+            apiBaseUrl: opts.apiBaseUrl,
+            token: opts.token,
+            fetchImpl: opts.fetchImpl,
+        });
+        if (fetched) {
+            loggedFetchFailure = false;
+            if (applyIfAcceptable(fetched, 'network')) {
+                writeCachedConfig(fetched, opts.cachePath);
+            }
+            return;
+        }
+        if (isBoot) {
+            // Network unavailable at boot — fall back to the last-known-good cache.
+            const cached = readCachedConfig(opts.cachePath);
+            if (cached) {
+                logger.info(TAG, `boot fetch failed — applying last-known-good cache v${cached.version}`);
+                applyIfAcceptable(cached, 'cache');
+            }
+            else {
+                logger.info(TAG, 'boot fetch failed, no cache — safe defaults (all tools enabled)');
+            }
+            return;
+        }
+        // Runtime failure: keep last-known-good silently (log once per outage).
+        if (!loggedFetchFailure) {
+            loggedFetchFailure = true;
+            logger.warn(TAG, `config poll failed — keeping last-known-good v${current.version}`);
+        }
+    };
+    void poll(true);
+    const timer = setInterval(() => {
+        void poll(false);
+    }, intervalMs);
+    timer.unref();
+    logger.info(TAG, `poller started (interval ${Math.round(intervalMs / 1000)}s)`);
+    return {
+        stop: () => clearInterval(timer),
+        getCurrent: () => current,
+    };
+}

package/config/brackets-config.d.ts

@@ -0,0 +1,22 @@
+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'. */
+export declare function getBracketMode(config?: PluginConfigFile, remoteOverride?: BracketMode): BracketMode;
+/** Convenience: load from disk and return the effective mode. */
+export declare function loadBracketMode(): BracketMode;
+/** Is the feature enabled at all (observe or enforce)? */
+export declare function bracketsEnabled(mode: BracketMode): boolean;
+/** Should the stop-watcher still run alongside brackets? Only 'enforce' turns it off for live. */
+export declare function stopWatcherActiveInLive(mode: BracketMode): boolean;
+/** Per-side requirement flags. Default both true — operator can untick
+ *  individually from the Trading Parameters panel to accept the documented
+ *  risk. Read alongside the bracket mode so a single config read covers
+ *  everything the pre-trade gate needs. */
+export interface BracketRequirements {
+    requireStopLoss: boolean;
+    requireTakeProfit: boolean;
+}
+export declare function getBracketRequirements(config?: PluginConfigFile): BracketRequirements;
+/** Convenience loader. Returns defaults on a missing/corrupt file — same
+ *  policy as loadBracketMode: don't gate trading on a corrupt flag read. */
+export declare function loadBracketRequirements(): BracketRequirements;

package/config/brackets-config.js

@@ -0,0 +1,58 @@
+// Feature flag reader for the bracket-orders system.
+//
+// Ordering of sources (first hit wins):
+//   1. Remote override from intelligence (set via admin dashboard OTA) — stored
+//      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).
+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'. */
+export function getBracketMode(config, remoteOverride) {
+    if (remoteOverride && VALID.has(remoteOverride))
+        return remoteOverride;
+    const raw = config?.brackets?.mode;
+    if (typeof raw === 'string' && VALID.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Convenience: load from disk and return the effective mode. */
+export function loadBracketMode() {
+    try {
+        return getBracketMode(readPluginConfig());
+    }
+    catch {
+        // If plugin-config.json is malformed, we deliberately default to 'off'
+        // rather than throw — other subsystems will alert; trading should not
+        // be gated on bracket-mode reading a corrupt file.
+        return 'off';
+    }
+}
+/** Is the feature enabled at all (observe or enforce)? */
+export function bracketsEnabled(mode) {
+    return mode !== 'off';
+}
+/** Should the stop-watcher still run alongside brackets? Only 'enforce' turns it off for live. */
+export function stopWatcherActiveInLive(mode) {
+    return mode !== 'enforce';
+}
+export function getBracketRequirements(config) {
+    const b = config?.brackets;
+    return {
+        // Explicit `false` turns off; anything else (undefined, true, junk) stays on.
+        requireStopLoss: b?.requireStopLoss !== false,
+        requireTakeProfit: b?.requireTakeProfit !== false,
+    };
+}
+/** Convenience loader. Returns defaults on a missing/corrupt file — same
+ *  policy as loadBracketMode: don't gate trading on a corrupt flag read. */
+export function loadBracketRequirements() {
+    try {
+        return getBracketRequirements(readPluginConfig());
+    }
+    catch {
+        return { requireStopLoss: true, requireTakeProfit: true };
+    }
+}

package/config/gate-store.d.ts

@@ -0,0 +1,18 @@
+import type { AgentGates } from './agent-config-client.js';
+declare class GateStore {
+    private gates;
+    /** Apply a validated gates object (poller path). Logs only on change. */
+    apply(gates: AgentGates): void;
+    /** The central exitGate mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getExitGate(): AgentGates['exitGate'] | null;
+    /** The central positionReview.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getPositionReviewMode(): AgentGates['positionReviewMode'] | null;
+    /** Test-only. */
+    __reset(): void;
+}
+/** Module singleton — one store per plugin process, shared by the poller
+ *  (writer) and the config readers (consumers). */
+export declare const gateStore: GateStore;
+export {};

package/config/gate-store.js

@@ -0,0 +1,61 @@
+// GateStore — the plugin-side holder for centrally-delivered operational-gate
+// values (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3; slice 2 = exitGate,
+// slice 3 = positionReviewMode).
+//
+// The agent-config poller applies each validated config's `gates` here; the
+// per-feature config readers (position-review-config.ts loadExitGateMode +
+// loadPositionReviewMode) consult the store FIRST and fall back to the local
+// plugin-config.json when no central value is present:
+//
+//     central (this store) → ~/.reefclaw/plugin-config.json → hardcoded default
+//
+// Values in the store have already passed the plugin-side enum validation in
+// agent-config-client.ts (validateGates) — central can never deliver a value
+// outside a gate's enum (§5b). A config-server outage never lands here either:
+// the poller keeps last-known-good, and with no applied config the store is
+// empty → the local file rules, byte-identical to pre-central behavior.
+//
+// Kill-switch: RC_CENTRAL_GATES=off makes the store report no central values
+// (local file rules again) without a redeploy — same convention as
+// RC_TOOL_GATE for the tool allowlist.
+import { logger } from '../logger.js';
+const TAG = 'gate-store';
+function centralGatesEnabled() {
+    return (process.env.RC_CENTRAL_GATES ?? '').toLowerCase() !== 'off';
+}
+const UNSET = '(unset — local config rules)';
+class GateStore {
+    gates = {};
+    /** Apply a validated gates object (poller path). Logs only on change. */
+    apply(gates) {
+        const next = gates ?? {};
+        const changed = next.exitGate !== this.gates.exitGate ||
+            next.positionReviewMode !== this.gates.positionReviewMode;
+        this.gates = { ...next };
+        if (changed) {
+            logger.info(TAG, `applied central gates: exitGate=${next.exitGate ?? UNSET} ` +
+                `positionReviewMode=${next.positionReviewMode ?? UNSET}`);
+        }
+    }
+    /** The central exitGate mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getExitGate() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.exitGate ?? null;
+    }
+    /** The central positionReview.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getPositionReviewMode() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.positionReviewMode ?? null;
+    }
+    /** Test-only. */
+    __reset() {
+        this.gates = {};
+    }
+}
+/** Module singleton — one store per plugin process, shared by the poller
+ *  (writer) and the config readers (consumers). */
+export const gateStore = new GateStore();