@reefclaw/connect 0.1.5 → 0.1.7

package/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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.

package/assets/plugin/signals/strategy-adapter.js

@@ -9,6 +9,7 @@ import { evaluateConditions } from './conditions/registry.js';
 import { resolveDirection } from './direction-rules.js';
 import { computeEntry } from './entry-rules.js';
 import { computeStop } from './stop-rules.js';
+import { computeATR } from '../shared/indicators.js';
 /**
  * Higher-timeframe tick gating state, keyed by
  * `${gateNamespace}\x1f${strategyName}:${symbol}`.
@@ -41,6 +42,73 @@ function pickTimeframeBars(ctx, tf) {
         return ctx.ohlcv4h ?? [];
     return ctx.ohlcv1h;
 }
+const TF_MS = {
+    '1h': 3_600_000,
+    '4h': 4 * 3_600_000,
+    '1d': 24 * 3_600_000,
+};
+/** Median spacing of the last few bars — robust bar-cadence probe. */
+function barSpacingMs(bars) {
+    const n = bars.length;
+    if (n < 2)
+        return 0;
+    const deltas = [];
+    for (let i = Math.max(1, n - 4); i < n; i++) {
+        deltas.push(bars[i].time.getTime() - bars[i - 1].time.getTime());
+    }
+    deltas.sort((a, b) => a - b);
+    return deltas[Math.floor(deltas.length / 2)];
+}
+/**
+ * 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 function resolvePrimaryContext(ctx, tf, tfBars) {
+    if (tf === '1h')
+        return ctx;
+    const spacing = barSpacingMs(ctx.ohlcv1h);
+    if (spacing === 0 || spacing >= TF_MS[tf] * 0.9)
+        return ctx; // already primary (backtest) or undecidable
+    if (tfBars.length < 50)
+        return null; // live warm-up parity with the backtest engine
+    const highs = tfBars.map(b => b.high);
+    const lows = tfBars.map(b => b.low);
+    const closes = tfBars.map(b => b.close);
+    const atr14 = computeATR(highs, lows, closes, 14);
+    return {
+        ...ctx,
+        ohlcv1h: tfBars,
+        atr14: Number.isFinite(atr14) && atr14 > 0 ? atr14 : ctx.atr14,
+    };
+}
 /** Empty no-signal evaluation — used when gating skips a strategy. */
 const SKIPPED = { direction: null, conditions: [], trade: undefined };
 /**
@@ -80,40 +148,49 @@ export function adaptStrategy(config, gateNamespace) {
                 return SKIPPED;
             }
             lastEvaluatedBarTime.set(gateKey, latestBarTime);
+            // ─── Higher-timeframe live parity ──────────────────────────────
+            // Evaluate against a context whose implicit-1h slot carries
+            // primary-timeframe bars — see resolvePrimaryContext. Backtest
+            // contexts pass through untouched; only live contexts for 4h/1d
+            // strategies are adapted, and a live context below the backtest's
+            // 50-bar warm-up resolves to null → skip.
+            const ectx = resolvePrimaryContext(ctx, tf, tfBars);
+            if (ectx === null)
+                return SKIPPED;
             // ─── SkipIf gates ──────────────────────────────────────────────
             // Portfolio-wide / cross-symbol filters. If any are met the
             // strategy is skipped this tick. Evaluated before main conditions
             // so the bulk of the work is short-circuited.
             if (config.skipIf && config.skipIf.length > 0) {
-                const { conditions: skipResults } = evaluateConditions(config.skipIf, ctx, null);
+                const { conditions: skipResults } = evaluateConditions(config.skipIf, ectx, null);
                 if (skipResults.some(c => c.met))
                     return SKIPPED;
             }
             // Pass 1: evaluate conditions with direction = null
-            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ctx, null);
+            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ectx, null);
             // Determine direction
-            const direction = resolveDirection(config.directionRule, ctx, condCtx);
+            const direction = resolveDirection(config.directionRule, ectx, condCtx);
             // Pass 2: re-evaluate direction-sensitive conditions now that we know direction
             // (orderbook_imbalance and funding_contrarian behave differently per direction)
             const directionSensitive = new Set(['orderbook_imbalance', 'funding_contrarian', 'funding_extreme_skip', 'funding_position_ok', 'return_momentum']);
             const hasDirSensitive = config.conditions.some(c => directionSensitive.has(c.type));
             let finalConditions = pass1;
             if (direction && hasDirSensitive) {
-                const { conditions: pass2 } = evaluateConditions(config.conditions, ctx, direction);
+                const { conditions: pass2 } = evaluateConditions(config.conditions, ectx, direction);
                 // Merge: use pass2 results for direction-sensitive, pass1 for others
                 finalConditions = pass1.map((c, i) => directionSensitive.has(config.conditions[i].type) ? pass2[i] : c);
             }
             const allMet = finalConditions.every(c => c.met);
             let trade;
             if (allMet && direction) {
-                const entryZone = computeEntry(config.entryRule, ctx, direction, condCtx);
-                const stopLevel = computeStop(config.stopRule, ctx, direction, condCtx);
+                const entryZone = computeEntry(config.entryRule, ectx, direction, condCtx);
+                const stopLevel = computeStop(config.stopRule, ectx, direction, condCtx);
                 const risk = direction === 'LONG'
-                    ? ctx.currentPrice - stopLevel
-                    : stopLevel - ctx.currentPrice;
+                    ? ectx.currentPrice - stopLevel
+                    : stopLevel - ectx.currentPrice;
                 const targets = config.targetRMultiples.map(rm => direction === 'LONG'
-                    ? ctx.currentPrice + risk * rm
-                    : ctx.currentPrice - risk * rm);
+                    ? ectx.currentPrice + risk * rm
+                    : ectx.currentPrice - risk * rm);
                 trade = { entryZone, stopLevel, targets };
             }
             return { direction, conditions: finalConditions, trade };

package/assets/plugin/tools/create-order.js

@@ -1,5 +1,6 @@
 // Tool: create_order — order execution with real price data + pre-trade risk gate
 // Readiness gate: BLOCKED unless adapter.readiness === 'READY'.
+import { randomUUID } from 'node:crypto';
 import { formatError } from '../logger.js';
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
 import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
@@ -293,32 +294,37 @@ export async function createOrderTool(args, deps) {
         }
     }
     try {
-        const order = await deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata);
+        // Stash the metadata BEFORE submission, keyed by a pre-generated
+        // clientOrderId (fixed 2026-07-07; supersedes the 2026-07-05 post-return
+        // stash). For market orders the user-data WS fill routinely arrives
+        // BEFORE the REST ack resolves — observed on prod (FIL 2026-07-06
+        // 20:28:17: WS capture consumed nothing and journaled metadata=none while
+        // the post-return stash landed milliseconds later). The WS
+        // ORDER_TRADE_UPDATE carries the clientOrderId (`o.c`), so
+        // onWsFillObserved falls back to it when the exchange orderId lookup
+        // misses; promote() below adds the exchange-orderId alias once the REST
+        // ack returns for the normal (WS-after-REST) ordering. If the submission
+        // throws, the unused stash entry simply expires (24h TTL, pruned).
+        let stashCid;
+        if (deps.autoCapture?.pendingEntries && metadata) {
+            stashCid = randomUUID();
+            deps.autoCapture.pendingEntries.put({
+                orderId: stashCid,
+                clientOrderId: stashCid,
+                symbol: args.symbol,
+                side: side,
+                metadata,
+            });
+        }
+        const order = await deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata, stashCid ? { clientOrderId: stashCid } : undefined);
         // Auto-capture entry to the Position Decision Journal — fail-open, never
         // block the trading hot path on a webapp ingest blip.
         if (deps.autoCapture) {
-            // ALWAYS stash the metadata first (fixed 2026-07-05). Binance futures
-            // market orders routinely come back filled>0 but with NO average price
-            // in the immediate REST response — the synchronous capture below then
-            // bails ("missing fill price; skipping capture") and, before this fix,
-            // the metadata was dropped on the floor because the stash only ran in
-            // the not-filled branch. The WS-driven onWsFillObserved captured those
-            // entries seconds later with metadata=none → the live journal filled
-            // with '(no thesis recorded)' / setup_type='unknown' rows (majority of
-            // 2026-07 live entries) even though the agent supplied full v2.10.0
-            // metadata every time. When the synchronous capture DOES succeed, the
-            // WS dedup (openedFromExchangeTradeId === orderId) skips the duplicate
-            // and the unused stash entry simply expires (24h TTL, pruned).
-            if (metadata &&
+            if (stashCid &&
                 deps.autoCapture.pendingEntries &&
                 typeof order.id === 'string' &&
                 order.id.length > 0) {
-                deps.autoCapture.pendingEntries.put({
-                    orderId: order.id,
-                    symbol: args.symbol,
-                    side: side,
-                    metadata,
-                });
+                deps.autoCapture.pendingEntries.promote(stashCid, order.id);
             }
             const filledNow = typeof order.filled === 'number' && order.filled > 0;
             if (filledNow) {

package/assets/shared/index.d.ts

@@ -8,3 +8,5 @@ export type { FillEvent, FillSource } from './fills.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
 export type { Direction, OhlcvBar, TradeFlowBucket, GlobalMarketContext, MarketContext, SignalCondition, StrategyEvaluation, StrategyDefinition, SignalEvent, StrategyState, SignalSnapshot, } from './signals/types.js';
 export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, EntryRuleConfig, StopRuleConfig, DirectionRule, PrimaryTimeframe, StrategyConfig, } from './signals/conditions/types.js';
+export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, } from './readiness.js';
+export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/index.js

@@ -3,3 +3,4 @@ export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from './protocol.js';
 export { logger, setLogLevel, formatError } from './logger.js';
 export { VALID_TRADING_MODES, isTradingMode, validateModeTransition, modeRequiresCredentials, } from './trading-mode.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
+export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/readiness.d.ts

@@ -0,0 +1,50 @@
+export type ReadinessStatus = 'pass' | 'warn' | 'fail' | 'unknown';
+/** Which lifecycle phase a check belongs to. `connect` runs with NO Binance API
+ *  keys (covers paper trading too); `golive` needs keys (Phase 2). */
+export type ReadinessPhase = 'connect' | 'golive';
+export type ReadinessCheckId = 'binance_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered';
+export interface ReadinessCheck {
+    /** Stable machine id. Widened to string so the webapp can render checks from a
+     *  newer plugin it doesn't have the union for. */
+    id: ReadinessCheckId | string;
+    label: string;
+    status: ReadinessStatus;
+    phase: ReadinessPhase;
+    /** Short machine/human detail, e.g. "HTTP 451" or "drift 1200ms". */
+    detail?: string;
+    /** Plain-English fix, present only when the status is warn/fail. */
+    fixHint?: string;
+    /** epoch ms when this check ran. */
+    checkedAt: number;
+}
+export interface ReadinessReport {
+    /** Bumped only if the payload shape changes incompatibly. */
+    schemaVersion: 1;
+    generatedAt: number;
+    overall: ReadinessStatus;
+    checks: ReadinessCheck[];
+    /** Best-effort agent facts for display. */
+    agent?: {
+        pluginVersion?: string;
+        toolCount?: number;
+    };
+}
+interface CheckCopy {
+    label: string;
+    phase: ReadinessPhase;
+    fixHint: string;
+}
+/** The canonical connect-phase checks + their plain-English fixes. Single source
+ *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
+export declare const READINESS_CHECK_COPY: Record<ReadinessCheckId, CheckCopy>;
+/** Build a self-describing check, pulling label/phase/fixHint from the copy map.
+ *  fixHint is attached only when there is something to fix (warn/fail). */
+export declare function makeReadinessCheck(id: ReadinessCheckId, status: ReadinessStatus, opts?: {
+    detail?: string;
+    checkedAt?: number;
+}): ReadinessCheck;
+/** Worst status across the checks: fail > warn > unknown > pass. An all-unknown
+ *  (or empty) set is 'unknown', so a report that couldn't run anything doesn't
+ *  masquerade as a clean pass. */
+export declare function deriveOverallReadiness(checks: ReadinessCheck[]): ReadinessStatus;
+export {};

package/assets/shared/readiness.js

@@ -0,0 +1,58 @@
+// Agent readiness — the check-result contract shared by the plugin (which runs
+// the checks ON the trader's host) and the webapp (which stores + renders them).
+//
+// The plugin emits SELF-DESCRIBING checks (label + fixHint inline) so the webapp
+// renders generically without duplicating the copy. Advisory only: readiness
+// explains failures, it never blocks trading or the safety floor.
+// See docs/AGENT_READINESS_GATE_PLAN.md.
+/** The canonical connect-phase checks + their plain-English fixes. Single source
+ *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
+export const READINESS_CHECK_COPY = {
+    binance_reachable: {
+        label: 'Binance reachable',
+        phase: 'connect',
+        fixHint: 'Your agent host is geo-blocked by Binance (HTTP 451). Run OpenClaw from a Binance-permitted region — most EU / several Asia VPS regions work.',
+    },
+    clock_in_sync: {
+        label: 'Host clock in sync',
+        phase: 'connect',
+        fixHint: 'The host clock drifts from Binance server time. Enable NTP/chrony so signed orders are not rejected (-1021).',
+    },
+    plugin_loaded: {
+        label: 'ReefClaw plugin loaded',
+        phase: 'connect',
+        fixHint: 'The trading plugin did not load. Check the OpenClaw gateway logs for a plugin-load error.',
+    },
+    tools_registered: {
+        label: 'Trading tools registered',
+        phase: 'connect',
+        fixHint: 'No trading tools are registered. Ensure tools.alsoAllow includes "group:plugins", then restart the gateway.',
+    },
+};
+/** Build a self-describing check, pulling label/phase/fixHint from the copy map.
+ *  fixHint is attached only when there is something to fix (warn/fail). */
+export function makeReadinessCheck(id, status, opts = {}) {
+    const copy = READINESS_CHECK_COPY[id];
+    const needsFix = status === 'warn' || status === 'fail';
+    return {
+        id,
+        label: copy.label,
+        phase: copy.phase,
+        status,
+        ...(opts.detail !== undefined ? { detail: opts.detail } : {}),
+        ...(needsFix ? { fixHint: copy.fixHint } : {}),
+        checkedAt: opts.checkedAt ?? Date.now(),
+    };
+}
+/** Worst status across the checks: fail > warn > unknown > pass. An all-unknown
+ *  (or empty) set is 'unknown', so a report that couldn't run anything doesn't
+ *  masquerade as a clean pass. */
+export function deriveOverallReadiness(checks) {
+    if (checks.some((c) => c.status === 'fail'))
+        return 'fail';
+    if (checks.some((c) => c.status === 'warn'))
+        return 'warn';
+    if (checks.length === 0 || checks.every((c) => c.status === 'unknown'))
+        return 'unknown';
+    return 'pass';
+}

package/assets/shared/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.