@reefclaw/openclaw-plugin 0.1.1 → 0.1.2

package/index.js

@@ -43,6 +43,7 @@ import { readPluginConfig, readOpenClawConnection } from './config/plugin-config
 import { startConnectorSupervisor, hasBundledBridge } from './connector-supervisor.js';
 import { ToolGate } from './config/tool-gate.js';
 import { gateStore } from './config/gate-store.js';
+import { entitlementGate } from './config/entitlement-gate.js';
 import { startAgentConfigPoller } from './config/agent-config-poller.js';
 import { PositionWatcher } from './live/stop-watcher.js';
 import { PaperMarketFeed } from './simulator/paper-market-feed.js';
@@ -1273,31 +1274,39 @@ const paperTradingPlugin = {
                         // weight). getPositionsOrNull() returns null on a failed/weight-paced
                         // fetch; getPositions() would collapse that to [] (null≠empty trap).
                         const trusted = await liveAdapter.getPositionsOrNull();
-                        const positions = trusted ?? [];
-                        await reconcileStateStoreOnStartup({
-                            decisionsClient: positionDecisionsClient,
-                            stateStore: positionStateStore,
-                            userId: positionDecisionsUserId,
-                            lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
-                        }, positions.map((p) => p.symbol));
-                        // Seed remaining-contracts for positions still open on the exchange
-                        // so the reduce-only-fill close handler can detect flat for entries
-                        // that opened before this plugin instance started (or before the
-                        // size-tracking field existed). seedRemainingContracts never clobbers
-                        // live fill-tracked state.
-                        for (const p of positions) {
-                            const contracts = Math.abs(Number(p.contracts));
-                            if (Number.isFinite(contracts) && contracts > 0) {
-                                positionStateStore.seedRemainingContracts(p.symbol, contracts);
-                            }
-                        }
-                        // DB-authoritative orphan close: close webapp `positions` rows that
-                        // are status='open' but absent from the exchange (closed on-exchange
-                        // while down / state-store wiped). ONLY on a TRUSTED snapshot — a
-                        // null (failed) fetch must never be read as "flat" and close the book.
                         if (trusted !== null) {
+                            // State-store sweep ONLY on a TRUSTED snapshot: this call treats
+                            // every state-store symbol absent from the list as closed and
+                            // removes it (incl. its webappPositionId journal linkage), so
+                            // collapsing a null (failed) fetch to [] would wipe the store
+                            // for every open position on a transient boot-time 429/paced
+                            // read — the null≠empty trap, with no self-healing retry.
+                            await reconcileStateStoreOnStartup({
+                                decisionsClient: positionDecisionsClient,
+                                stateStore: positionStateStore,
+                                userId: positionDecisionsUserId,
+                                lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
+                            }, trusted.map((p) => p.symbol));
+                            // Seed remaining-contracts for positions still open on the exchange
+                            // so the reduce-only-fill close handler can detect flat for entries
+                            // that opened before this plugin instance started (or before the
+                            // size-tracking field existed). seedRemainingContracts never clobbers
+                            // live fill-tracked state.
+                            for (const p of trusted) {
+                                const contracts = Math.abs(Number(p.contracts));
+                                if (Number.isFinite(contracts) && contracts > 0) {
+                                    positionStateStore.seedRemainingContracts(p.symbol, contracts);
+                                }
+                            }
+                            // DB-authoritative orphan close: close webapp `positions` rows that
+                            // are status='open' but absent from the exchange (closed on-exchange
+                            // while down / state-store wiped). Same trusted-snapshot-only rule —
+                            // a null fetch must never be read as "flat" and close the book.
                             await reconcileDbOpenVsExchange({ decisionsClient: positionDecisionsClient, userId: positionDecisionsUserId }, trusted.map((p) => p.symbol));
                         }
+                        else {
+                            logger.warn(TAG, 'Startup reconciliation skipped — positions fetch untrusted (null); state-store left untouched. Runtime drift_detected + periodic reconcilers cover the gap.');
+                        }
                     }
                     catch (err) {
                         logger.warn(TAG, `Startup state-store reconciliation failed: ${formatError(err)}`);
@@ -1958,7 +1967,13 @@ const paperTradingPlugin = {
         // config blob can never strip close_position/attach_brackets/etc.
         // Kill-switch: RC_TOOL_GATE=off. See docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5f.
         const toolGate = new ToolGate();
-        const gatedTools = tools.map((t) => toolGate.wrapTool(t, jsonResult));
+        // Entitlement gate (account-level enforcement): wraps OUTSIDE the
+        // ToolGate so an expired subscription's message wins over an operator
+        // OFF-list message. It touches ONLY ENTITLEMENT_GATED_TOOLS (exactly
+        // create_order — new risk); closes/stops/brackets/emergency are not in
+        // the set by construction. No server verdict → fail-open. Kill-switch:
+        // RC_ENTITLEMENT_GATE=off. See config/entitlement-gate.ts.
+        const gatedTools = tools.map((t) => entitlementGate.wrapTool(toolGate.wrapTool(t, jsonResult), jsonResult));
         // Poll the central config (boot + every ~60s), keyed by the same rc_
         // token the ingest paths use (plugin-config connectionToken →
         // WEBAPP_INGEST_TOKEN env fallback). No token → poller no-ops → gate
@@ -1966,9 +1981,11 @@ const paperTradingPlugin = {
         // gateStore carries centrally-delivered operational gates (slice 2:
         // exitGate) — loadExitGateMode() consults it before the local file;
         // kill-switch RC_CENTRAL_GATES=off. See config/gate-store.ts.
+        // entitlementGate receives the server-resolved billing verdict.
         startAgentConfigPoller({
             gate: toolGate,
             gateStore,
+            entitlementGate,
             apiBaseUrl,
             token: resolveIngestToken({ connectionToken }),
         });

package/ingest/pending-entry-metadata.d.ts

@@ -1,7 +1,13 @@
 import type { PositionMetadata } from '../simulator/types.js';
 export interface PendingEntry {
-    /** Exchange-issued orderId — the lookup key when the WS fill arrives. */
+    /** Primary lookup key. Initially the client order id (the stash happens
+     *  BEFORE submission, when no exchange orderId exists yet); promote()
+     *  re-keys it to the exchange-issued orderId once the REST ack returns. */
     orderId: string;
+    /** Client order id (idempotency key) — secondary lookup key. The WS
+     *  ORDER_TRADE_UPDATE carries it (`o.c`), so a fill that arrives BEFORE
+     *  the REST response (routine for market orders) still finds the stash. */
+    clientOrderId?: string;
     /** Canonical (un-suffixed) symbol. */
     symbol: string;
     /** Side the agent intended at create_order time. */
@@ -24,25 +30,41 @@ export declare class PendingEntryStore {
     private readonly now;
     private readonly ttlMs;
     private entries;
+    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
+     *  REST ack (no exchange orderId known yet) find the stash by cid. */
+    private cidIndex;
     constructor(opts?: PendingEntryStoreOptions);
-    /** Stash metadata until the WS fill for this orderId arrives. */
+    /** Stash metadata until the WS fill for this order arrives. Keyed by
+     *  `orderId`; when `clientOrderId` is provided the entry is also findable
+     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
     put(input: {
         orderId: string;
+        clientOrderId?: string;
         symbol: string;
         side: 'buy' | 'sell';
         metadata: PositionMetadata;
     }): void;
-    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
-     *  callers should call `consume(orderId)` to remove on first match, since
-     *  multiple partial fills on the same limit order all share one orderId
-     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
-     *  registered position (state-store branch handles those). */
+    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
+     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
+     *  working. No-op when the entry is gone (already consumed by a WS fill
+     *  that beat the REST response, or expired). */
+    promote(fromKey: string, exchangeOrderId: string): void;
+    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
+     *  Does NOT remove the entry — callers should call `consume(orderId)` to
+     *  remove on first match, since multiple partial fills on the same limit
+     *  order all share one orderId and the FIRST fill is the entry; subsequent
+     *  are scale-ins of an already-registered position (state-store branch
+     *  handles those). */
     get(orderId: string): PendingEntry | undefined;
-    /** Atomic get + remove. Use this when you've already consumed the metadata
-     *  to post an entry row and don't want it picked up again. */
+    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
+     *  you've already consumed the metadata to post an entry row and don't
+     *  want it picked up again. */
     consume(orderId: string): PendingEntry | undefined;
     /** Remove an entry without retrieval (e.g. on cancel). */
     drop(orderId: string): boolean;
+    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
+    private resolveKey;
+    private deleteEntry;
     size(): number;
     getFilePath(): string;
     private pruneExpired;

package/ingest/pending-entry-metadata.js

@@ -33,6 +33,9 @@ export class PendingEntryStore {
     now;
     ttlMs;
     entries = new Map();
+    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
+     *  REST ack (no exchange orderId known yet) find the stash by cid. */
+    cidIndex = new Map();
     constructor(opts) {
         const base = resolvePluginsBaseDir(opts?.basePath);
         this.dir = join(base, opts?.pluginId ?? DEFAULT_PLUGIN_ID);
@@ -43,45 +46,91 @@ export class PendingEntryStore {
             mkdirSync(this.dir, { recursive: true });
         this.loadOrInit();
     }
-    /** Stash metadata until the WS fill for this orderId arrives. */
+    /** Stash metadata until the WS fill for this order arrives. Keyed by
+     *  `orderId`; when `clientOrderId` is provided the entry is also findable
+     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
     put(input) {
         const ts = this.now();
         this.entries.set(input.orderId, {
             orderId: input.orderId,
+            ...(input.clientOrderId ? { clientOrderId: input.clientOrderId } : {}),
             symbol: input.symbol,
             side: input.side,
             metadata: input.metadata,
             createdAt: ts,
             expiresAt: ts + this.ttlMs,
         });
+        if (input.clientOrderId)
+            this.cidIndex.set(input.clientOrderId, input.orderId);
         this.persist();
     }
-    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
-     *  callers should call `consume(orderId)` to remove on first match, since
-     *  multiple partial fills on the same limit order all share one orderId
-     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
-     *  registered position (state-store branch handles those). */
+    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
+     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
+     *  working. No-op when the entry is gone (already consumed by a WS fill
+     *  that beat the REST response, or expired). */
+    promote(fromKey, exchangeOrderId) {
+        const key = this.resolveKey(fromKey);
+        if (key === undefined || key === exchangeOrderId)
+            return;
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        entry.orderId = exchangeOrderId;
+        this.entries.set(exchangeOrderId, entry);
+        if (entry.clientOrderId)
+            this.cidIndex.set(entry.clientOrderId, exchangeOrderId);
+        this.persist();
+    }
+    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
+     *  Does NOT remove the entry — callers should call `consume(orderId)` to
+     *  remove on first match, since multiple partial fills on the same limit
+     *  order all share one orderId and the FIRST fill is the entry; subsequent
+     *  are scale-ins of an already-registered position (state-store branch
+     *  handles those). */
     get(orderId) {
         this.pruneExpired();
-        return this.entries.get(orderId);
+        const key = this.resolveKey(orderId);
+        return key === undefined ? undefined : this.entries.get(key);
     }
-    /** Atomic get + remove. Use this when you've already consumed the metadata
-     *  to post an entry row and don't want it picked up again. */
+    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
+     *  you've already consumed the metadata to post an entry row and don't
+     *  want it picked up again. */
     consume(orderId) {
         this.pruneExpired();
-        const entry = this.entries.get(orderId);
+        const key = this.resolveKey(orderId);
+        if (key === undefined)
+            return undefined;
+        const entry = this.entries.get(key);
         if (!entry)
             return undefined;
-        this.entries.delete(orderId);
+        this.deleteEntry(key, entry);
         this.persist();
         return entry;
     }
     /** Remove an entry without retrieval (e.g. on cancel). */
     drop(orderId) {
-        const existed = this.entries.delete(orderId);
-        if (existed)
-            this.persist();
-        return existed;
+        const key = this.resolveKey(orderId);
+        if (key === undefined)
+            return false;
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        this.deleteEntry(key, entry);
+        this.persist();
+        return true;
+    }
+    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
+    resolveKey(k) {
+        if (this.entries.has(k))
+            return k;
+        const viaCid = this.cidIndex.get(k);
+        return viaCid !== undefined && this.entries.has(viaCid) ? viaCid : undefined;
+    }
+    deleteEntry(key, entry) {
+        this.entries.delete(key);
+        if (entry.clientOrderId)
+            this.cidIndex.delete(entry.clientOrderId);
     }
     size() {
         return this.entries.size;
@@ -95,7 +144,7 @@ export class PendingEntryStore {
         let pruned = false;
         for (const [orderId, entry] of this.entries) {
             if (entry.expiresAt <= ts) {
-                this.entries.delete(orderId);
+                this.deleteEntry(orderId, entry);
                 pruned = true;
             }
         }
@@ -128,6 +177,8 @@ export class PendingEntryStore {
         for (const entry of file.entries) {
             if (entry.expiresAt > ts) {
                 this.entries.set(entry.orderId, entry);
+                if (entry.clientOrderId)
+                    this.cidIndex.set(entry.clientOrderId, entry.orderId);
                 kept++;
             }
             else {
@@ -163,6 +214,9 @@ export class PendingEntryStore {
             if (typeof e.orderId !== 'string' || e.orderId.length === 0) {
                 throw new Error('pending-entry-metadata: entry missing orderId');
             }
+            if (e.clientOrderId !== undefined && (typeof e.clientOrderId !== 'string' || e.clientOrderId.length === 0)) {
+                throw new Error('pending-entry-metadata: invalid clientOrderId');
+            }
             if (typeof e.symbol !== 'string' || e.symbol.length === 0) {
                 throw new Error('pending-entry-metadata: entry missing symbol');
             }

package/ingest/position-auto-capture.js

@@ -173,6 +173,17 @@ export async function onClosePositionFilled(ctx, inputs, order) {
     ctx.stateStore.remove(inputs.symbol);
     logger.info(TAG, `close captured ${inputs.symbol} reason=${inputs.closeReason} (positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
 }
+/** Look up the metadata create_order stashed for this fill. Primary key is
+ *  the exchange orderId (post-REST-ack `promote()`); the clientOrderId
+ *  fallback covers the routine market-order race where the WS fill arrives
+ *  BEFORE the REST response, i.e. before the promote — the pre-submission
+ *  stash is keyed by the cid, which the WS event carries (`o.c`). */
+function consumePendingEntry(ctx, fill) {
+    if (!ctx.pendingEntries)
+        return undefined;
+    return (ctx.pendingEntries.consume(fill.exchangeOrderId) ??
+        (fill.clientOrderId ? ctx.pendingEntries.consume(fill.clientOrderId) : undefined));
+}
 export async function onWsFillObserved(ctx, fill) {
     if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
         return;
@@ -208,7 +219,7 @@ export async function onWsFillObserved(ctx, fill) {
             logger.warn(TAG, `onWsFillObserved ${fill.symbol}: scale-in observed but no webappPositionId yet — skipping (parent upsert may have failed; will retry next fill)`);
             return;
         }
-        const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+        const pending = consumePendingEntry(ctx, fill);
         const entry = buildEntryPayload({
             positionId: stateEntry.webappPositionId,
             isScaleIn: true,
@@ -227,8 +238,8 @@ export async function onWsFillObserved(ctx, fill) {
     }
     // No state-store entry → NEW position via WS-driven fill. Replicates the
     // synchronous-market-order path but pulls metadata from the pending cache
-    // (which create_order populated when the limit was placed).
-    const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+    // (which create_order populated BEFORE submitting the order).
+    const pending = consumePendingEntry(ctx, fill);
     ctx.stateStore.upsert({
         symbol: fill.symbol,
         openedAt: ts,

package/ingest/readiness-reporter.d.ts

@@ -0,0 +1,19 @@
+import { type ReadinessReport } from '@reefclaw/shared';
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+export interface ReadinessReporterOptions {
+    apiBaseUrl: string;
+    token: string;
+    binanceApi: Pick<BinancePublicApi, 'probeReachability'>;
+    /** Number of trading tools registered (a health signal). */
+    toolCount: number;
+    fetchImpl?: typeof fetch;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+}
+/** Run every connect-phase check once and assemble the report. Exported for
+ *  unit tests. */
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'binanceApi' | 'toolCount'>): Promise<ReadinessReport>;
+/** Test-only — reset the singleton guard between unit tests. */
+export declare function __resetReadinessReporterForTests(): void;
+/** Fire the readiness report once at boot then on an unref'd interval. */
+export declare function startReadinessReporter(opts: ReadinessReporterOptions): void;

package/ingest/readiness-reporter.js

@@ -0,0 +1,142 @@
+// Agent-readiness reporter — runs connect-phase health checks ON the trader's
+// host and POSTs a self-describing report to the webapp, so a silently-broken
+// agent (geo-blocked by Binance, clock-skewed, no tools) surfaces a plain-English
+// dashboard alert instead of a false green. Advisory only: it NEVER blocks
+// trading or the safety floor. See docs/AGENT_READINESS_GATE_PLAN.md (Phase 1).
+//
+// No token → no-op (nothing to authenticate; matches the config poller). 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. The interval is unref()'d so it never holds the process open.
+import { makeReadinessCheck, deriveOverallReadiness, } from '@reefclaw/shared';
+import { logger, formatError } from '../logger.js';
+const TAG = 'readiness';
+const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
+const MIN_INTERVAL_MS = 60_000;
+/** Best-effort display fact; kept in sync with the register() banner in index.ts. */
+const PLUGIN_VERSION = '3.8.0';
+function resolveIntervalMs(explicit) {
+    if (explicit && explicit > 0)
+        return Math.max(MIN_INTERVAL_MS, explicit);
+    const raw = Number(process.env.RC_READINESS_INTERVAL_MS);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_INTERVAL_MS;
+    return Math.max(MIN_INTERVAL_MS, raw);
+}
+/** Run every connect-phase check once and assemble the report. Exported for
+ *  unit tests. */
+export async function collectReadiness(opts) {
+    const now = Date.now();
+    const checks = [];
+    // plugin_loaded — trivially true (this code runs inside the loaded plugin),
+    // but a positive row is what proves the report path is alive at all.
+    checks.push(makeReadinessCheck('plugin_loaded', 'pass', { checkedAt: now }));
+    // tools_registered
+    checks.push(makeReadinessCheck('tools_registered', opts.toolCount > 0 ? 'pass' : 'fail', {
+        detail: `${opts.toolCount} tools`,
+        checkedAt: now,
+    }));
+    // binance_reachable (+ clock drift from the same probe response)
+    const probe = await opts.binanceApi.probeReachability();
+    if (probe.outcome === 'reachable') {
+        checks.push(makeReadinessCheck('binance_reachable', 'pass', { checkedAt: now }));
+        const drift = probe.driftMs;
+        if (drift == null) {
+            checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+        }
+        else {
+            const abs = Math.abs(drift);
+            const status = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
+            checks.push(makeReadinessCheck('clock_in_sync', status, {
+                detail: `drift ${Math.round(drift)}ms`,
+                checkedAt: now,
+            }));
+        }
+    }
+    else if (probe.outcome === 'geo_blocked') {
+        checks.push(makeReadinessCheck('binance_reachable', 'fail', { detail: 'HTTP 451', checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else if (probe.outcome === 'unreachable') {
+        // Network/DNS/timeout — could be transient, so warn (amber) rather than
+        // asserting a definitive failure. A persistent problem stays amber across
+        // re-checks; only the 451 geo-block is a hard red.
+        checks.push(makeReadinessCheck('binance_reachable', 'warn', { detail: 'unreachable', checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else {
+        // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
+        checks.push(makeReadinessCheck('binance_reachable', 'unknown', { checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    return {
+        schemaVersion: 1,
+        generatedAt: now,
+        overall: deriveOverallReadiness(checks),
+        checks,
+        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount },
+    };
+}
+async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/agent-readiness`;
+    const ac = new AbortController();
+    const tid = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(report),
+            signal: ac.signal,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            logger.warn(TAG, `POST ${url} → ${res.status}`);
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `readiness POST failed: ${formatError(err)}`);
+    }
+    finally {
+        clearTimeout(tid);
+    }
+}
+let reporterStarted = false;
+/** Test-only — reset the singleton guard between unit tests. */
+export function __resetReadinessReporterForTests() {
+    reporterStarted = false;
+}
+/** Fire the readiness report once at boot then on an unref'd interval. */
+export function startReadinessReporter(opts) {
+    if (reporterStarted)
+        return;
+    if (!opts.token || !opts.token.trim()) {
+        logger.info(TAG, 'no connection token — readiness reporting disabled');
+        return;
+    }
+    reporterStarted = true;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const intervalMs = resolveIntervalMs(opts.intervalMs);
+    const timeoutMs = opts.requestTimeoutMs ?? 10_000;
+    const cycle = async () => {
+        try {
+            const report = await collectReadiness({
+                binanceApi: opts.binanceApi,
+                toolCount: opts.toolCount,
+            });
+            await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
+            if (report.overall === 'fail') {
+                const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');
+                logger.warn(TAG, `readiness FAIL: ${failing}`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `readiness cycle failed: ${formatError(err)}`);
+        }
+    };
+    void cycle();
+    const timer = setInterval(() => void cycle(), intervalMs);
+    timer.unref();
+    logger.info(TAG, `readiness reporter started (interval ${Math.round(intervalMs / 1000)}s)`);
+}

package/live/exchange-info-cache.d.ts

@@ -23,7 +23,9 @@ export declare class ExchangeInfoCache {
     private rules;
     /** Set of all known symbols for normalization lookups. */
     private knownSymbols;
-    /** Load market info from CCXT exchange instance. */
+    /** Load market info from CCXT exchange instance. Throws on failure (incl.
+     *  an active ban — the gate short-circuits with zero network so a boot
+     *  during a 418 can't extend it); callers treat a throw as init failure. */
     load(exchange: any): Promise<void>;
     /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
     getRules(symbol: string): SymbolRules | undefined;

package/live/exchange-info-cache.js

@@ -1,6 +1,7 @@
 // Exchange info cache — caches per-symbol trading rules (min notional, lot sizes, tick sizes).
 // Loaded once on startup from CCXT loadMarkets(), used to validate and round orders before submission.
 import { logger } from '../logger.js';
+import { assertNotBanned, noteBinanceError, noteSuccess } from '../ccxt/binance-ban-gate.js';
 const TAG = 'exchange-info';
 /**
  * Normalize symbol format for consistent lookups.
@@ -26,10 +27,24 @@ export class ExchangeInfoCache {
     rules = new Map();
     /** Set of all known symbols for normalization lookups. */
     knownSymbols = new Set();
-    /** Load market info from CCXT exchange instance. */
+    /** Load market info from CCXT exchange instance. Throws on failure (incl.
+     *  an active ban — the gate short-circuits with zero network so a boot
+     *  during a 418 can't extend it); callers treat a throw as init failure. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async load(exchange) {
-        const info = await exchange.loadMarkets(true); // force refresh
+        let info;
+        try {
+            // GET /fapi/v1/exchangeInfo via ccxt loadMarkets — IP weight 1
+            // (doc-verified). Ban-gated but never weight-paced (NEVER_PACE):
+            // once-per-boot and required for order validation + emergency close.
+            assertNotBanned('loadMarkets');
+            info = await exchange.loadMarkets(true); // force refresh
+            noteSuccess();
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
         for (const [symbol, market] of Object.entries(info)) {
             const m = market;
             // Only cache futures (swap) markets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "ReefClaw trading plugin for OpenClaw \u2014 paper trading with real Binance market data, plus the ReefClaw dashboard connector (supervised by OpenClaw, no service manager needed). Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",

package/signals/strategy-adapter.d.ts

@@ -1,6 +1,39 @@
-import type { StrategyDefinition } from './types.js';
-import type { StrategyConfig } from './conditions/types.js';
+import type { StrategyDefinition, MarketContext, OhlcvBar } from './types.js';
+import type { StrategyConfig, PrimaryTimeframe } from './conditions/types.js';
 export declare function clearStrategyGatingState(): void;
+/**
+ * Live parity for higher-timeframe strategies (the tfHours-aware-stops fix,
+ * 2026-07 — see docs/STRATEGY_RESEARCH_2026-07.md §6.4 / CLAUDE.md ★).
+ *
+ * Every implicit bar read in this engine — stop rules
+ * (`findSwingPoints(ctx.ohlcv1h.slice(-48))`), entry rules
+ * (`computeEMA(ctx.ohlcv1h…)`), conditions without a `tfHours` param
+ * (ema_proximity, stoch_rsi_extreme, adx_*, …) and `ctx.atr14` — targets the
+ * `ohlcv1h` slot. The backtest engine feeds MAIN-timeframe bars into that
+ * slot (and computes atr14 from them), so a 4h/1d strategy backtests against
+ * primary-timeframe geometry. LIVE contexts put real 1h bars there, so the
+ * same strategy would compute stops/EMAs/ATR from 1h data — a 1d ATR is ~8×
+ * the 1h ATR, so live stops came out ~8× too tight. This helper gives the
+ * evaluation the exact context shape the backtest validated: primary bars in
+ * the `ohlcv1h` slot, atr14 recomputed from them (same computeATR the
+ * backtest and live context builders use).
+ *
+ * Detection, not configuration: when the `ohlcv1h` slot already carries
+ * primary-cadence bars (median spacing ≥ 90% of the primary bar duration —
+ * i.e. a backtest context), the context is returned UNTOUCHED, so backtest
+ * behaviour is byte-identical by construction (including warm-up: the
+ * backtest engine already refuses to build a context below 50 main bars).
+ * A live 1h series can only look primary-spaced through a data gap, in
+ * which case we fall back to the untouched context (pre-fix behaviour)
+ * rather than guessing.
+ *
+ * Returns null for a LIVE context whose primary-timeframe history is below
+ * the backtest's 50-bar warm-up — the caller skips evaluation, mirroring
+ * the backtest's null-context warm-up window.
+ *
+ * Exported for tests.
+ */
+export declare function resolvePrimaryContext(ctx: MarketContext, tf: PrimaryTimeframe, tfBars: OhlcvBar[]): MarketContext | null;
 /**
  * Convert a declarative StrategyConfig into a StrategyDefinition
  * that the signal engine and backtest engine can evaluate.