@reefclaw/openclaw-plugin 0.1.2 → 0.1.4

package/bridge/bridge.js

@@ -6,7 +6,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { logger } from './logger.js';
 import { Connector } from './connector.js';
-import { readLocalSkillVersion, validateSkillContent, compareSemver } from './utils/skill-version.js';
+import { readLocalSkillVersion, readAgentVisibleSkillVersions, validateSkillContent, compareSemver } from './utils/skill-version.js';
 import { verifySkillSignature, signatureRequired, readLastAppliedSignedAtMs, recordAppliedSignedAt, } from './utils/skill-signing.js';
 import { isTradingMode, validateModeTransition, redactTokens } from '@reefclaw/shared';
 import { OPERATOR_WRITE_METHODS } from './types.js';
@@ -837,6 +837,37 @@ export class Bridge {
                     logger.warn(TAG, `Failed to update workspace skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
                 }
             }
+            // 2d. Also write to the plugin-extension bundled skill directory — the
+            // chat-channel install layout (`/plugins install clawhub:...`) loads the
+            // agent-visible skill from ~/.openclaw/extensions/<plugin>/skills/, and a
+            // plugin (re)install resets that copy to the bundled bootstrap while the
+            // workspace copy above (our version tracker) survives. Without this
+            // write the agent stays on the bootstrap forever while the pull reports
+            // "already up to date" (observed live 2026-07-11).
+            const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+            if (existsSync(extensionsDir)) {
+                try {
+                    for (const ext of readdirSync(extensionsDir, { withFileTypes: true })) {
+                        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+                            continue;
+                        const extSkillsDir = join(extensionsDir, ext.name, 'skills');
+                        if (!existsSync(extSkillsDir))
+                            continue;
+                        for (const skillEntry of readdirSync(extSkillsDir, { withFileTypes: true })) {
+                            if (!skillEntry.isDirectory() || !skillEntry.name.includes('reefclaw'))
+                                continue;
+                            const extSkillMd = join(extSkillsDir, skillEntry.name, 'SKILL.md');
+                            if (existsSync(extSkillMd)) {
+                                writeFileSync(extSkillMd, content, 'utf-8');
+                                logger.info(TAG, `Updated extension skill SKILL.md: ${extSkillMd}`);
+                            }
+                        }
+                    }
+                }
+                catch (scanErr) {
+                    logger.warn(TAG, `Failed to update extension skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+                }
+            }
             // 3. Invalidate skillsSnapshot cache WITHOUT wiping sessions.json
             // Previously we wrote '{}' to sessions.json which destroyed OpenClaw chat history.
             // Now we surgically remove only the skillsSnapshot key from each session entry,
@@ -979,12 +1010,24 @@ export class Bridge {
                 return;
             }
             this.currentSkillVersion = readLocalSkillVersion();
-            if (compareSemver(body.version, this.currentSkillVersion) <= 0) {
+            // The workspace tracker alone is NOT proof the agent has the full skill:
+            // a plugin (re)install resets the agent-visible extension copy to the
+            // bundled bootstrap while the workspace copy survives (observed live
+            // 2026-07-11 — agent stranded on 0.0.5 with the tracker at 2.20.4). If
+            // ANY agent-visible copy is behind the webapp version, re-apply anyway;
+            // applySkillUpdate is idempotent across all copies.
+            const staleAgentCopies = readAgentVisibleSkillVersions().filter((v) => compareSemver(body.version, v) > 0);
+            if (compareSemver(body.version, this.currentSkillVersion) <= 0 && staleAgentCopies.length === 0) {
                 logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} already >= webapp v${body.version} — nothing to do`);
                 this.skillPullInFlight = false;
                 return;
             }
-            logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            if (staleAgentCopies.length > 0 && compareSemver(body.version, this.currentSkillVersion) <= 0) {
+                logger.info(TAG, `SKILL.md webapp pull: agent-visible skill copy at v${staleAgentCopies[0]} behind webapp v${body.version} (plugin reinstall reset it) — re-applying`);
+            }
+            else {
+                logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            }
             const result = await this.applySkillUpdate({ version: body.version, content: body.content });
             this.emit('agent_state', 'skill_update_applied', {
                 event: 'skill_update_applied',

package/bridge/utils/skill-version.d.ts

@@ -2,6 +2,15 @@
 export declare function parseSkillVersion(content: string): string | null;
 /** Read current SKILL.md version from disk */
 export declare function readLocalSkillVersion(): string | null;
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export declare function readAgentVisibleSkillVersions(): string[];
 /**
  * Compare two semver strings.
  * Returns 1 if a > b, -1 if a < b, 0 if equal.

package/bridge/utils/skill-version.js

@@ -1,5 +1,5 @@
 // SKILL.md version parsing utility for OTA updates
-import { readFileSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 const SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
@@ -18,6 +18,50 @@ export function readLocalSkillVersion() {
         return null;
     }
 }
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export function readAgentVisibleSkillVersions() {
+    const versions = [];
+    const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+    let extEntries;
+    try {
+        extEntries = readdirSync(extensionsDir, { withFileTypes: true });
+    }
+    catch {
+        return versions;
+    }
+    for (const ext of extEntries) {
+        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+            continue;
+        const skillsDir = join(extensionsDir, ext.name, 'skills');
+        let skillEntries;
+        try {
+            skillEntries = readdirSync(skillsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const s of skillEntries) {
+            if (!s.isDirectory() || !s.name.includes('reefclaw'))
+                continue;
+            try {
+                const v = parseSkillVersion(readFileSync(join(skillsDir, s.name, 'SKILL.md'), 'utf-8'));
+                if (v)
+                    versions.push(v);
+            }
+            catch {
+                // unreadable/absent copy — nothing to report for this entry
+            }
+        }
+    }
+    return versions;
+}
 // 120KB — the full SKILL.md crossed 100KB at v2.20.0 (103.7KB), which silently
 // broke every OTA apply against the old 100KB cap. Keep comfortably under the
 // 128KiB Cloudflare Durable-Object per-value hard limit the relay stores into.

package/ccxt/binance-ban-gate.js

@@ -128,6 +128,8 @@ const CONTEXT_WEIGHT = {
     fetchOHLCV: 2,
     fetchFundingRate: 1,
     fetchOpenInterest: 1,
+    // Readiness gate's host→Binance reachability probe (fapiPublicGetTime, wt 1).
+    reachabilityProbe: 1,
     // ExchangeInfoCache boot load — ccxt loadMarkets() → GET /fapi/v1/exchangeInfo,
     // IP weight 1 (doc-verified developers.binance.com 2026-07-10). Was the
     // known "ungated_ip" ccxt-internal call named in the window-summary comment.
@@ -200,7 +202,7 @@ const NEVER_PACE = new Set([
 const SHED_FIRST = new Set([
     'fetchTodayIncomeBreakdown', 'fetchTransfers', 'fetchRecentTradedSymbols',
     'fetchTicker', 'fetchTickerRaw', 'fetchOHLCV', 'fetchOrderBook',
-    'fetchFundingRate', 'fetchOpenInterest',
+    'fetchFundingRate', 'fetchOpenInterest', 'reachabilityProbe',
 ]);
 let weightWindowStart = 0;
 let weightUsed = 0;

package/ccxt/binance-public.d.ts

@@ -1,6 +1,7 @@
 import type { CcxtTicker, CcxtOHLCV } from '../types.js';
 import type { OrderBookDepth } from '../simulator/types.js';
-export declare class BinancePublicApi {
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+export declare class BinancePublicApi implements PublicMarketDataApi {
     private exchange;
     constructor();
     /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
@@ -15,4 +16,19 @@ export declare class BinancePublicApi {
     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>;
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
 }

package/ccxt/binance-public.js

@@ -2,7 +2,7 @@
 // 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';
+import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } 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
@@ -144,4 +144,37 @@ export class BinancePublicApi {
             return null;
         }
     }
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    async probeReachability() {
+        try {
+            assertNotBanned('reachabilityProbe');
+            const r = await this.exchange.fapiPublicGetTime({});
+            noteSuccess();
+            const serverTime = Number(r?.serverTime);
+            const driftMs = Number.isFinite(serverTime) ? serverTime - Date.now() : null;
+            return { outcome: 'reachable', driftMs };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            if (err instanceof BinanceBannedError) {
+                // Gate paused us (418/429 backoff or weight pacer) — we didn't actually
+                // reach the host, so the result is UNKNOWN, not a reachability failure.
+                return { outcome: 'unknown', driftMs: null };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            const geo = msg.includes('451');
+            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
+            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+        }
+    }
 }

package/ccxt/intel-public.d.ts

@@ -0,0 +1,25 @@
+import { type IntelApiDeps } from '../tools/intel-api.js';
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+type RawCcxt = Record<string, any>;
+export declare class IntelPublicApi implements PublicMarketDataApi {
+    private readonly deps;
+    constructor(deps: IntelApiDeps);
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    fetchTickerRaw(): Promise<RawCcxt | null>;
+    fetchFundingRate(): Promise<RawCcxt | null>;
+    fetchOpenInterest(): Promise<RawCcxt | null>;
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    fetchOrderBook(): Promise<OrderBookDepth | null>;
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    fetchOHLCV(): Promise<CcxtOHLCV[] | null>;
+}
+export {};

package/ccxt/intel-public.js

@@ -0,0 +1,80 @@
+// Intel-backed public market-data source for PAPER mode on hosts that Binance
+// geo-blocks (HTTP 451). Paper execution is fully simulated; it only needs a
+// price, which the intel service serves from its own (permitted-region) feeds
+// via GET /api/price/:symbol (latest 1m close, ≤~60s stale). See
+// docs/AGENT_READINESS_GATE_PLAN.md sibling + the wisekid 451 findings.
+//
+// Selected only when plugin-config `paperMarketDataSource: 'intel'` AND paper
+// mode (index.ts). Live trading NEVER uses this — live needs the real exchange.
+//
+// Increment 1 serves PRICE only (fetchTicker), which is the trading-critical
+// path: create_order / close_position price + the PaperMarketFeed mark loop.
+// Candles / order book / funding / OI have no intel HTTP route yet, so those
+// return null here — the SAME shape a 451 produces today (no regression), and
+// order-book absence is already handled by the fill engine's random-slippage
+// fallback. Candle/book/OI intel routes are a follow-up.
+import { logger } from '../logger.js';
+import { fetchIntelApi } from '../tools/intel-api.js';
+const TAG = 'intel-public';
+/** CCXT symbol (`BTC/USDT`, `BTC/USDT:USDT`) → intel format (`BTCUSDT`). */
+function toIntelSymbol(symbol) {
+    return symbol.replace('/', '').replace(/:.*$/, '');
+}
+export class IntelPublicApi {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        logger.info(TAG, 'Intel public market-data source active (paper mode, Binance reads routed to intel)');
+    }
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    async fetchTicker(symbol) {
+        const res = await fetchIntelApi(`/api/price/${toIntelSymbol(symbol)}`, this.deps);
+        if ('error' in res) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel failed: ${res.error}`);
+            return null;
+        }
+        const body = res;
+        const price = Number(body.price);
+        if (!Number.isFinite(price) || price <= 0) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel returned a bad price: ${body.price}`);
+            return null;
+        }
+        const timestamp = Number.isFinite(body.time) ? body.time : Date.now();
+        return {
+            // Key on the ORIGINAL ccxt symbol so the simulator's per-symbol maps line up.
+            symbol,
+            last: price,
+            bid: price,
+            ask: price,
+            baseVolume: 0,
+            quoteVolume: 0,
+            change: 0,
+            percentage: 0,
+            timestamp,
+            datetime: new Date(timestamp).toISOString(),
+        };
+    }
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    async fetchTickerRaw() {
+        return null;
+    }
+    async fetchFundingRate() {
+        return null;
+    }
+    async fetchOpenInterest() {
+        return null;
+    }
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    async fetchOrderBook() {
+        return null;
+    }
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    async fetchOHLCV() {
+        return null;
+    }
+}

package/ccxt/public-market-data-api.d.ts

@@ -0,0 +1,12 @@
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+type RawCcxt = Record<string, any>;
+export interface PublicMarketDataApi {
+    fetchTickerRaw(symbol: string): Promise<RawCcxt | null>;
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    fetchFundingRate(symbol: string): Promise<RawCcxt | null>;
+    fetchOpenInterest(symbol: string): Promise<RawCcxt | null>;
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+}
+export {};

package/ccxt/public-market-data-api.js

@@ -0,0 +1,9 @@
+// The public market-data surface paper mode reads (prices, candles, book,
+// funding, OI). Both BinancePublicApi (direct Binance) and IntelPublicApi
+// (via the intel service, for Binance-451-geo-blocked hosts) implement it, so
+// the paper wiring can select a source without any consumer knowing which.
+//
+// Deliberately EXCLUDES probeReachability: that is Binance-specific and only
+// the readiness reporter uses it — it must always probe the REAL Binance host
+// to detect the 451, so it keeps a concrete BinancePublicApi, never this.
+export {};

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

@@ -21,8 +21,23 @@ export interface PluginConfigFile {
      *  prod runs the bridge under systemd and a supervisor there would
      *  double-connect the relay room. Kill-switch: RC_CONNECTOR_SUPERVISOR=off. */
     connectorSupervisor?: 'on' | 'off';
+    /** Where PAPER mode reads market-data prices from. 'binance' (default) hits
+     *  Binance public endpoints directly; 'intel' routes them through the intel
+     *  service (GET /api/price/:symbol) so a host that Binance geo-blocks (HTTP
+     *  451) can still paper-trade. PAPER-ONLY + advisory: live trading always
+     *  uses the real exchange, and readiness still probes real Binance to detect
+     *  the 451. Kill-switch: RC_PAPER_MARKET_DATA=binance forces the default. */
+    paperMarketDataSource?: 'binance' | 'intel';
     apiBaseUrl?: string;
     intelligenceUrl?: string;
+    /** Exchange credentials + venue selection. `exchange.venue` picks the
+     *  trading venue ('binance' default | 'hyperliquid'); it is LOCAL mechanism
+     *  (never central-pushable) per docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.2.
+     *  Until Phase 3 ships the hyperliquid adapter, a non-PAPER mode on
+     *  venue='hyperliquid' falls back to PAPER at boot. NOTE: updatePluginConfig
+     *  replaces this block wholesale (the documented `exchange: null` clears
+     *  credentials), so any writer (set_exchange_credentials, SSH edits) must
+     *  carry `venue` through or it resets to the binance default. */
     exchange?: ExchangeConfig;
     tradingMode?: TradingMode;
     microLive?: {

package/index.js

@@ -11,6 +11,7 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { BinancePublicApi } from './ccxt/binance-public.js';
+import { IntelPublicApi } from './ccxt/intel-public.js';
 import { BinancePrivateApi } from './ccxt/binance-private.js';
 import { ExchangeSimulator } from './simulator/exchange-simulator.js';
 import { ShadowTracker } from './shadow/shadow-tracker.js';
@@ -18,7 +19,8 @@ import { StateManager } from './persistence/state-manager.js';
 import { logger, setLogLevel, formatError } from './logger.js';
 import { DEFAULT_CONFIG } from './types.js';
 import { PaperAdapter } from './paper-adapter.js';
-import { LiveAdapter } from './live/live-adapter.js';
+import { createLiveAdapter, fillExchangeId, isLiveVenueSupported, parseVenue, } from './venues/registry.js';
+import { HyperliquidPublicApi } from './venues/hyperliquid/hl-public.js';
 import { loadBracketMode } from './config/brackets-config.js';
 import { loadUserDataStreamMode, loadUserDataStreamTunables, loadUserDataStreamDbWrite, getUserDataStreamIngestBaseUrl, resolveIngestToken, resolveReefclawUserId, } from './config/user-data-stream-config.js';
 import { TradeStoreClient } from './ingest/trade-store-client.js';
@@ -29,6 +31,7 @@ import { PositionStateStore } from './live/position-state-store.js';
 import { PendingEntryStore } from './ingest/pending-entry-metadata.js';
 import { onReconcilerObservedClose, reconcileStateStoreOnStartup } from './ingest/reconciler-cleanup.js';
 import { reconcileDbOpenVsExchange } from './ingest/reconcile-db-vs-exchange.js';
+import { startReadinessReporter } from './ingest/readiness-reporter.js';
 import { IntelMicrostructureAssembler } from './live/microstructure-assembler.js';
 import { recordPositionReviewsTool } from './tools/record-position-reviews.js';
 import { getMyRecentReviewsTool } from './tools/get-my-recent-reviews.js';
@@ -911,6 +914,14 @@ const paperTradingPlugin = {
         let intelligenceUrl = 'https://intel.reefclaw.com';
         let exchangeConfig = null;
         let tradingMode = 'PAPER';
+        // Trading venue (multi-venue Phase 0 — docs/HYPERLIQUID_INTEGRATION_PLAN.md).
+        // Absent config field = 'binance', so every pre-venue install is untouched.
+        let venue = 'binance';
+        // exchange.testnet as written on disk — needed independently of
+        // exchangeConfig because the hyperliquid venue never builds a Binance
+        // credential config (Phase 0 gate) but its keyless public API still needs
+        // the mainnet/testnet routing.
+        let venueTestnet = false;
         let signalsEvaluator = 'central';
         let signalsSymbols = [];
         try {
@@ -927,9 +938,18 @@ const paperTradingPlugin = {
                 if (Array.isArray(rcConfig?.signals?.symbols)) {
                     signalsSymbols = rcConfig.signals.symbols.map((s) => String(s).toUpperCase());
                 }
-                // Read exchange credentials (Phase 9b)
+                // Read exchange credentials (Phase 9b) + venue (multi-venue Phase 0)
                 const exchange = rcConfig?.exchange;
-                if (exchange?.apiKey && exchange?.secret) {
+                const venueParse = parseVenue(exchange?.venue);
+                venue = venueParse.venue;
+                venueTestnet = exchange?.testnet === true;
+                if (venueParse.unrecognized) {
+                    logger.warn(TAG, `Unrecognized exchange.venue '${venueParse.unrecognized}' in plugin-config — treating as 'binance'`);
+                }
+                // apiKey/secret are a BINANCE credential pair; never build a Binance
+                // client config for another venue (a hyperliquid block carries
+                // walletAddress/agentPrivateKey instead — consumed from Phase 3 on).
+                if (venue === 'binance' && exchange?.apiKey && exchange?.secret) {
                     exchangeConfig = {
                         apiKey: exchange.apiKey,
                         secret: exchange.secret,
@@ -963,6 +983,14 @@ const paperTradingPlugin = {
         else {
             logger.warn(TAG, 'No connection token found — get_market_intel will return errors');
         }
+        // Venue support gate (multi-venue Phase 0). Checked BEFORE the credentials
+        // gate so a hyperliquid config gets the accurate diagnosis ("venue not
+        // supported yet"), not a misleading "missing API keys". Fallback-to-PAPER,
+        // never a throw — register() must stay non-crashing.
+        if (tradingMode !== 'PAPER' && !isLiveVenueSupported(venue)) {
+            logger.warn(TAG, `Trading mode ${tradingMode} on venue '${venue}' is not supported in this build — falling back to PAPER (live support arrives in Phase 3 of docs/HYPERLIQUID_INTEGRATION_PLAN.md)`);
+            tradingMode = 'PAPER';
+        }
         // Validate trading mode vs credentials
         if (tradingMode !== 'PAPER' && !exchangeConfig) {
             logger.warn(TAG, `Trading mode ${tradingMode} requires exchange API keys — falling back to PAPER`);
@@ -1062,6 +1090,9 @@ const paperTradingPlugin = {
             // closure — only invoked on a fill, long after `runtime` is built), so it
             // follows a live<->paper reconnect.
             resolveMode: () => (runtime.adapter.isLive ? 'live' : 'paper'),
+            // Venue tag (positions.exchange, migration 0058) — static per process;
+            // a venue change requires config edit + restart.
+            venue,
         };
         if (positionDecisionsClient) {
             logger.info(TAG, `Journal close-on-reduce-only-fill ${closeOnReduceOnlyFill ? 'ENABLED' : 'disabled'}`);
@@ -1145,6 +1176,11 @@ const paperTradingPlugin = {
                     tradeIngest = {
                         client: new TradeStoreClient({ baseUrl: ingestBaseUrl, ingestToken }),
                         userId: reefclawUserId,
+                        // Venue-derived FillEvent.exchange — 'binance_futures' for the
+                        // binance venue, i.e. byte-identical to the pre-venue literal
+                        // WsIngest defaulted to. Half of the (exchange, exchange_trade_id)
+                        // audit-trail idempotency key; never a fresh string literal.
+                        exchange: fillExchangeId(venue),
                     };
                     logger.info(TAG, `User-data stream dbWrite=on — WS audit-trail ingest wired to ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
                 }
@@ -1202,7 +1238,12 @@ const paperTradingPlugin = {
                     logger.warn(TAG, `approval mode=${approvalModeForTool} but WEBAPP_INGEST_TOKEN or REEFCLAW_USER_ID env missing — proposal path disabled`);
                     approvalModeForTool = 'off';
                 }
-                const liveAdapter = new LiveAdapter(exchangeConfig, tradingMode, microLiveConfig, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, autoCapture);
+                // Venue-dispatched construction (multi-venue Phase 0). For 'binance'
+                // this is a pure pass-through to `new LiveAdapter(...)` — identical
+                // args, identical behavior; the unsupported-venue arm is unreachable
+                // here because the isLiveVenueSupported() gate above already fell back
+                // to PAPER. Phase 3 adds the hyperliquid adapter inside the factory.
+                const liveAdapter = createLiveAdapter(venue, exchangeConfig, tradingMode, microLiveConfig, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, autoCapture);
                 adapter = liveAdapter;
                 // ---- Approval-mode Phase B — start ProposalDecisionListener ----
                 // Started only when approval.mode='per_trade' AND proposalManagerCtx
@@ -1319,11 +1360,64 @@ const paperTradingPlugin = {
         else {
             adapter = new PaperAdapter(simulator);
         }
+        // PAPER market-data source selection.
+        //
+        // Venue precedence (Hyperliquid Phase 1 — docs/HYPERLIQUID_INTEGRATION_PLAN.md):
+        // the configured VENUE decides which exchange prices paper mode, full stop.
+        // venue='hyperliquid' → every public read (PaperMarketFeed marks, the
+        // simulator's fill prices, fetch_ticker/fetch_ohlcv/get_orderbook tools)
+        // comes from Hyperliquid's keyless /info endpoints; the Binance-only
+        // `paperMarketDataSource:'intel'` escape hatch does not apply (intel has
+        // no HL rows until Phase 2 — silently serving Binance prices for a
+        // Hyperliquid book would be a lie, the exact class the symbol-translation
+        // rule forbids).
+        //
+        // Binance venue (default) is unchanged: a host Binance geo-blocks (HTTP
+        // 451) can route PRICE reads through the intel service by setting
+        // plugin-config `paperMarketDataSource:'intel'` (GET /api/price/:symbol).
+        // LIVE always uses the real exchange, and the readiness reporter probes
+        // the CONFIGURED venue. Kill-switch RC_PAPER_MARKET_DATA=binance forces
+        // the Binance-direct default (binance venue only).
+        //
+        // hlPublicApi is constructed once per process when the venue is
+        // hyperliquid — shared by the paper data path and the readiness probe.
+        const hlPublicApi = venue === 'hyperliquid' ? new HyperliquidPublicApi({ testnet: venueTestnet }) : null;
+        let configuredPaperSource;
+        try {
+            configuredPaperSource = readPluginConfig().paperMarketDataSource;
+        }
+        catch {
+            configuredPaperSource = undefined;
+        }
+        const paperDataSource = process.env.RC_PAPER_MARKET_DATA === 'binance'
+            ? 'binance'
+            : configuredPaperSource ?? 'binance';
+        const useIntelPaperData = venue === 'binance' &&
+            !adapter.isLive && paperDataSource === 'intel' && connectionToken.length > 0;
+        const marketDataApi = !adapter.isLive && hlPublicApi
+            ? hlPublicApi
+            : useIntelPaperData
+                ? new IntelPublicApi({ connectionToken, intelligenceUrl })
+                : binanceApi;
+        if (!adapter.isLive && hlPublicApi) {
+            logger.info(TAG, `PAPER market data sourced from Hyperliquid${venueTestnet ? ' TESTNET' : ''} (venue=hyperliquid) — use USDC pairs (e.g. BTC/USDC)`);
+            if (paperDataSource === 'intel') {
+                logger.warn(TAG, 'paperMarketDataSource=intel is a Binance-venue option — ignored on venue=hyperliquid (intel has no Hyperliquid rows until Phase 2)');
+            }
+        }
+        else if (useIntelPaperData) {
+            logger.warn(TAG, 'PAPER market data routed through intel (paperMarketDataSource=intel) — prices from GET /api/price; live + readiness still use Binance directly');
+        }
+        else if (venue === 'binance' && !adapter.isLive && paperDataSource === 'intel' && connectionToken.length === 0) {
+            logger.warn(TAG, 'paperMarketDataSource=intel requested but no connection token — falling back to Binance direct (which will 451 on a geo-blocked host)');
+        }
         // Build tool dependencies
         // `simDeps` for tools that need the simulator directly (ticker, market structure, risk scenario)
         // `adapterDeps` for the 7 adapter-based trading tools
-        const simDeps = { binanceApi, simulator };
-        const adapterDeps = { binanceApi, adapter };
+        // Both carry `marketDataApi` (Binance direct, or intel in paper mode) so
+        // every paper market-data read follows the selected source at once.
+        const simDeps = { binanceApi: marketDataApi, simulator };
+        const adapterDeps = { binanceApi: marketDataApi, adapter };
         // ---- Plugin runtime (mutable holder) ----
         // Owns the adapter + mode + stop-watcher and exposes `reconnect()` so the
         // operator can swap credentials / trading mode from the dashboard without
@@ -1356,7 +1450,7 @@ const paperTradingPlugin = {
         // resting limits fill. Paper-only — started here when the boot adapter is
         // paper; PluginRuntime.reconnect() stops it on a switch to live and
         // restarts it on a switch back to paper. Reuses the ban-gated fetchTicker.
-        const marketFeed = new PaperMarketFeed(binanceApi, simulator);
+        const marketFeed = new PaperMarketFeed(marketDataApi, simulator);
         if (!adapter.isLive) {
             marketFeed.start();
         }
@@ -2020,6 +2114,22 @@ const paperTradingPlugin = {
         pluginToolNames = toolNames;
         pluginInitialised = true;
         logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
+        // Agent-readiness reporter (docs/AGENT_READINESS_GATE_PLAN.md Phase 1):
+        // probe host→venue reachability (Binance HTTP 451 geo-block / Hyperliquid
+        // /info) + clock drift on the host and POST a plain-English report to the
+        // webapp, so a silently-broken agent shows an actionable dashboard alert
+        // instead of a false green. Probes ONLY the configured venue — on a
+        // Binance-451 host trading Hyperliquid a Binance probe would be a
+        // permanent false alarm. Advisory + fire-and-forget; no token → no-op.
+        // Runs here once (guarded by the pluginInitialised early-return → once per
+        // process) + on an unref'd interval inside the reporter.
+        startReadinessReporter({
+            apiBaseUrl,
+            token: resolveIngestToken({ connectionToken }),
+            venue,
+            publicApi: hlPublicApi ?? binanceApi,
+            toolCount: toolNames.length,
+        });
         maybeStartConnectorSupervisor();
     },
 };

package/ingest/position-auto-capture.d.ts

@@ -21,6 +21,11 @@ export interface AutoCaptureContext {
      *  from the current adapter (so it follows a runtime reconnect). Tags the
      *  journal position row so paper and live entries can be segregated. */
     resolveMode?: () => 'paper' | 'live';
+    /** Venue this gateway trades ('binance' | 'hyperliquid'). Static per process
+     *  — changing venue requires a config edit + restart (plan §5.2), so unlike
+     *  `resolveMode` this is a plain value, not a resolver. Tags journal rows
+     *  (positions.exchange, migration 0058). */
+    venue?: 'binance' | 'hyperliquid';
 }
 export interface CreateOrderInputs {
     symbol: string;