@reefclaw/openclaw-plugin 0.1.7 → 0.1.9

package/bridge/gateway/heartbeat-cron.d.ts

@@ -0,0 +1,27 @@
+export declare const HEARTBEAT_CRON_NAME = "reefclaw-heartbeat";
+export declare const HEARTBEAT_EVERY_MS: number;
+export declare const HEARTBEAT_MESSAGE: string;
+export interface CronRpcClient {
+    sendRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Whether an existing cron job counts as "the heartbeat already exists".
+ * Union of the two matchers already in the codebase: the old setup path
+ * matched /reefclaw/, while resolveHeartbeatSeconds() (the cadence reader that
+ * drives the dashboard header) matches /heart\s*beat/. A job satisfying either
+ * must suppress creation — prod/wisekid boxes carry heartbeat jobs whose names
+ * predate the reefclaw- prefix, and a duplicate 15m heartbeat would double the
+ * agent's token burn.
+ */
+export declare function isHeartbeatLikeName(name: unknown): boolean;
+export type EnsureHeartbeatOutcome = 'already_ensured' | 'found_existing' | 'created' | 'failed';
+/**
+ * Ensure a heartbeat cron exists. Non-fatal by contract: every failure path
+ * returns 'failed' rather than throwing, and only success writes the marker so
+ * a transient gateway error retries on the next boot.
+ */
+export declare function ensureHeartbeatCron(opts: {
+    rpc: CronRpcClient;
+    markerPath: string;
+    log: (msg: string) => void;
+}): Promise<EnsureHeartbeatOutcome>;

package/bridge/gateway/heartbeat-cron.js

@@ -0,0 +1,85 @@
+// Ensures the ReefClaw heartbeat cron job exists — once per install — via
+// gateway RPC (`cron.list` / `cron.add`).
+//
+// This replaces the old setup-time shell-out to the openclaw CLI. The CLI's
+// cron commands are themselves gateway RPC clients, so shelling out bought
+// nothing except a subprocess + PATH dependency — and it ran at
+// setup time, when the gateway is typically NOT up yet (setup's printed next
+// step is "Start your OpenClaw agent"), which is why creation silently
+// no-op'd on fresh installs without a running gateway. The bridge holds an
+// authenticated gateway WS by construction, so the ensure runs there instead.
+//
+// Once-per-install semantics: a marker file records that the ensure has run to
+// completion. Without it, a user who deliberately deleted their heartbeat cron
+// would get it resurrected on every bridge boot — the old setup-time path ran
+// once, and that operator-override behaviour must be preserved.
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+export const HEARTBEAT_CRON_NAME = 'reefclaw-heartbeat';
+export const HEARTBEAT_EVERY_MS = 15 * 60 * 1000;
+// Byte-identical to the message the setup-time CLI path created, so new jobs
+// match every existing install's job.
+export const HEARTBEAT_MESSAGE = 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. ' +
+    'Check tradingMode from fetch_balance — it is your source of truth for paper vs live. ' +
+    'Use tools in parallel where possible.';
+/**
+ * Whether an existing cron job counts as "the heartbeat already exists".
+ * Union of the two matchers already in the codebase: the old setup path
+ * matched /reefclaw/, while resolveHeartbeatSeconds() (the cadence reader that
+ * drives the dashboard header) matches /heart\s*beat/. A job satisfying either
+ * must suppress creation — prod/wisekid boxes carry heartbeat jobs whose names
+ * predate the reefclaw- prefix, and a duplicate 15m heartbeat would double the
+ * agent's token burn.
+ */
+export function isHeartbeatLikeName(name) {
+    return typeof name === 'string' && /reefclaw|heart\s*beat/i.test(name);
+}
+/**
+ * Ensure a heartbeat cron exists. Non-fatal by contract: every failure path
+ * returns 'failed' rather than throwing, and only success writes the marker so
+ * a transient gateway error retries on the next boot.
+ */
+export async function ensureHeartbeatCron(opts) {
+    const { rpc, markerPath, log } = opts;
+    try {
+        if (existsSync(markerPath))
+            return 'already_ensured';
+        // includeDisabled: a job the user disabled still means "exists" — re-adding
+        // a duplicate next to a deliberately-disabled one is worse than doing nothing.
+        const listResp = (await rpc.sendRpc('cron.list', { includeDisabled: true }));
+        const jobs = Array.isArray(listResp?.jobs) ? listResp.jobs : null;
+        if (!jobs) {
+            log('Heartbeat cron: skipped (cron.list returned no job list)');
+            return 'failed';
+        }
+        const existing = jobs.find((j) => isHeartbeatLikeName(j?.name));
+        if (existing) {
+            writeMarker(markerPath, { ensuredAt: new Date().toISOString(), found: String(existing.name) });
+            log(`Heartbeat cron: already exists (${String(existing.name)})`);
+            return 'found_existing';
+        }
+        // Parity with the params the CLI built for the old setup command
+        // (`openclaw cron add --name reefclaw-heartbeat --every 15m --session isolated --message ...`):
+        // isolated agentTurn defaults to delivery announce on the 'last' channel.
+        await rpc.sendRpc('cron.add', {
+            name: HEARTBEAT_CRON_NAME,
+            enabled: true,
+            schedule: { kind: 'every', everyMs: HEARTBEAT_EVERY_MS },
+            sessionTarget: 'isolated',
+            wakeMode: 'now',
+            payload: { kind: 'agentTurn', message: HEARTBEAT_MESSAGE },
+            delivery: { mode: 'announce', channel: 'last' },
+        });
+        writeMarker(markerPath, { ensuredAt: new Date().toISOString(), created: HEARTBEAT_CRON_NAME });
+        log(`Heartbeat cron: created (${HEARTBEAT_CRON_NAME}, every 15m)`);
+        return 'created';
+    }
+    catch (err) {
+        log(`Heartbeat cron: skipped (${err instanceof Error ? err.message.split('\n')[0] : String(err)})`);
+        return 'failed';
+    }
+}
+function writeMarker(markerPath, data) {
+    mkdirSync(dirname(markerPath), { recursive: true });
+    writeFileSync(markerPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

package/bridge/providers/gateway.d.ts

@@ -29,6 +29,8 @@ export declare class GatewayProvider implements OpenClawProvider {
     private agentIdentity;
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     private loggedAgentIdentityProbe;
+    /** One-shot latch for the boot-time heartbeat-cron ensure (re-armed on failure). */
+    private heartbeatCronEnsureStarted;
     /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
     private heartbeatSeconds?;
     private heartbeatReadAtMs;

package/bridge/providers/gateway.js

@@ -11,16 +11,26 @@ import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
 import { discoverTools } from '../gateway/tool-discovery.js';
 import { EventParser, mapCcxtBalance, mapCcxtOrder, extractLiquidationFields, extractBracketField, } from '../gateway/event-parser.js';
 import { Poller } from '../gateway/poller.js';
+import { ensureHeartbeatCron } from '../gateway/heartbeat-cron.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, } from './onboarding-commands.js';
 const TAG = 'gateway';
-// ---- Session NAV persistence ----
-// Persists sessionStartNav per date so Day P&L survives skill restarts.
-const SESSION_NAV_FILENAME = 'session-nav.json';
+// ---- Day-start NAV persistence ----
+// Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
+// survives skill restarts. The file was historically named session-nav.json;
+// renamed to day-start-nav.json 2026-07-22 — "session" was a misnomer (the
+// value anchors the trading DAY, not any auth/session state) and tripped
+// ClawHub's sensitive-file-read heuristic. Reads fall back to the legacy name
+// once, writes go to the new name only.
+const DAY_NAV_FILENAME = 'day-start-nav.json';
+const LEGACY_DAY_NAV_FILENAME = 'session-nav.json';
 const TRADING_MODE_FILENAME = 'trading-mode.json';
-function getSessionNavPath() {
-    return join(homedir(), '.openclaw', 'workspace', SESSION_NAV_FILENAME);
+function getDayNavPath() {
+    return join(homedir(), '.openclaw', 'workspace', DAY_NAV_FILENAME);
+}
+function getLegacyDayNavPath() {
+    return join(homedir(), '.openclaw', 'workspace', LEGACY_DAY_NAV_FILENAME);
 }
 function getTradingModePath() {
     return join(homedir(), '.openclaw', 'workspace', TRADING_MODE_FILENAME);
@@ -40,17 +50,20 @@ export function shouldAnchorSessionNav(args) {
     return args.mode === 'PAPER' && args.sessionDate !== args.today; // paper midnight rollover
 }
 function loadSessionStartNav() {
-    try {
-        const raw = readFileSync(getSessionNavPath(), 'utf-8');
-        const data = JSON.parse(raw);
-        if (data.date === todayDateStr() && typeof data.sessionStartNav === 'number' && data.sessionStartNav > 0) {
-            return data.sessionStartNav;
+    for (const path of [getDayNavPath(), getLegacyDayNavPath()]) {
+        try {
+            const raw = readFileSync(path, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data.date === todayDateStr() && typeof data.sessionStartNav === 'number' && data.sessionStartNav > 0) {
+                return data.sessionStartNav;
+            }
+            return null; // Different day or invalid — don't let a stale legacy file shadow it
+        }
+        catch {
+            /* missing or corrupt — try the legacy name */
         }
-        return null; // Different day or invalid
-    }
-    catch {
-        return null; // File doesn't exist or is corrupt
     }
+    return null;
 }
 /**
  * Persisted across skill restarts so the FIRST snapshot the gateway emits
@@ -90,7 +103,11 @@ function saveSessionStartNav(nav) {
         const dir = join(homedir(), '.openclaw', 'workspace');
         mkdirSync(dir, { recursive: true });
         const data = { date: todayDateStr(), sessionStartNav: nav };
-        writeFileSync(getSessionNavPath(), JSON.stringify(data, null, 2), 'utf-8');
+        writeFileSync(getDayNavPath(), JSON.stringify(data, null, 2), 'utf-8');
+        try {
+            unlinkSync(getLegacyDayNavPath());
+        }
+        catch { /* legacy file already gone */ }
     }
     catch (err) {
         logger.warn(TAG, `Failed to save session NAV: ${err instanceof Error ? err.message : String(err)}`);
@@ -122,6 +139,8 @@ export class GatewayProvider {
     agentIdentity = {};
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     loggedAgentIdentityProbe = false;
+    /** One-shot latch for the boot-time heartbeat-cron ensure (re-armed on failure). */
+    heartbeatCronEnsureStarted = false;
     /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
     heartbeatSeconds;
     heartbeatReadAtMs = 0;
@@ -1070,6 +1089,24 @@ export class GatewayProvider {
         // every (re)connect so a model swap — which restarts the gateway and drops
         // this socket — is reflected on the next handshake.
         void this.refreshAgentIdentity();
+        // Ensure the heartbeat cron exists — via gateway RPC, once per install
+        // (marker-file guarded; a deliberate operator delete is never resurrected).
+        // Lives here instead of setup because setup runs before the gateway is up.
+        if (!this.heartbeatCronEnsureStarted) {
+            this.heartbeatCronEnsureStarted = true;
+            const ws = this.wsClient;
+            if (ws) {
+                void ensureHeartbeatCron({
+                    rpc: ws,
+                    markerPath: join(homedir(), '.openclaw', 'workspace', 'heartbeat-cron-ensured.json'),
+                    log: (msg) => logger.info(TAG, msg),
+                }).then((outcome) => {
+                    // A transient failure retries on the next (re)connect, not just next boot.
+                    if (outcome === 'failed')
+                        this.heartbeatCronEnsureStarted = false;
+                });
+            }
+        }
         // Start periodic agent state emission (every 5s)
         if (!this.agentStateInterval) {
             this.agentStateInterval = setInterval(() => {
@@ -1589,7 +1626,11 @@ export class GatewayProvider {
                     this.hasReceivedPositions = false;
                     this.pendingEmptyPoll = false;
                     try {
-                        unlinkSync(getSessionNavPath());
+                        unlinkSync(getDayNavPath());
+                    }
+                    catch { /* ok if missing */ }
+                    try {
+                        unlinkSync(getLegacyDayNavPath());
                     }
                     catch { /* ok if missing */ }
                     logger.info(TAG, `Session start NAV reset on mode change (${prevMode} → ${this.tradingMode})`);

package/bridge/setup.js

@@ -1,7 +1,6 @@
 // Interactive setup helper for the ReefClaw skill.
 // Validates token format, tests relay connection, saves to OpenClaw config.
 import WebSocket from 'ws';
-import { execSync } from 'node:child_process';
 import { writeOpenClawConfig } from './config.js';
 import { logger } from './logger.js';
 const TAG = 'setup';
@@ -149,8 +148,12 @@ export async function runSetup(tokenOrBundle, userId, relayUrl) {
     }
     // Save to config
     writeOpenClawConfig(token, resolvedUserId, resolvedRelayUrl);
-    // Create heartbeat cron job if none exists
-    ensureHeartbeatCron();
+    // Heartbeat cron is ensured by the bridge at first gateway connect (via
+    // cron.list/cron.add RPC — see gateway/heartbeat-cron.ts). Setup can't do it:
+    // the gateway isn't running yet at this point, which is also why the old
+    // setup-time shell-out to the openclaw CLI silently no-op'd on fresh
+    // installs (the CLI's cron commands are gateway RPC clients too).
+    console.log('  Heartbeat cron: created automatically when the agent first connects (every 15m)');
     console.log('');
     console.log('  Setup complete! Token saved to ~/.openclaw/config.json');
     console.log('');
@@ -161,54 +164,6 @@ export async function runSetup(tokenOrBundle, userId, relayUrl) {
     console.log('    4. Your agent checks the market every 15 minutes (adjustable via chat)');
     console.log('');
 }
-// ---- Heartbeat cron ----
-/**
- * Ensures a heartbeat cron job exists for ReefClaw.
- * Checks `openclaw cron list` for an existing job with "reefclaw" in the name.
- * If none found, creates one with 15m default interval.
- * Non-fatal — if openclaw CLI isn't available or cron fails, setup still succeeds.
- */
-function ensureHeartbeatCron() {
-    try {
-        // Check if a reefclaw cron already exists
-        const listOutput = execSync('openclaw cron list --json 2>/dev/null', {
-            encoding: 'utf-8',
-            timeout: 15_000,
-        });
-        // Look for any job with "reefclaw" in the name
-        try {
-            const jobs = JSON.parse(listOutput);
-            const existing = (Array.isArray(jobs) ? jobs : []).find((j) => j.name?.toLowerCase().includes('reefclaw'));
-            if (existing) {
-                console.log(`  Heartbeat cron: already exists (${existing.name})`);
-                return;
-            }
-        }
-        catch {
-            // JSON parse failed — maybe not JSON output, check raw text
-            if (listOutput.toLowerCase().includes('reefclaw')) {
-                console.log('  Heartbeat cron: already exists');
-                return;
-            }
-        }
-        // No existing job — create one
-        console.log('  Creating heartbeat cron (every 15m)...');
-        execSync('openclaw cron add --name reefclaw-heartbeat --every 15m --session isolated ' +
-            "--message 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. Check tradingMode from fetch_balance — it is your source of truth for paper vs live. Use tools in parallel where possible.' 2>&1", { encoding: 'utf-8', timeout: 15_000 });
-        console.log('  Heartbeat cron: created (every 15 minutes)');
-        console.log('  Tip: Ask your agent "change heartbeat to 10 minutes" to adjust');
-    }
-    catch (err) {
-        // Non-fatal — user can create cron manually or agent can create it on first session
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes('not found') || msg.includes('ENOENT')) {
-            console.log('  Heartbeat cron: skipped (openclaw CLI not in PATH)');
-        }
-        else {
-            console.log(`  Heartbeat cron: skipped (${msg.split('\n')[0]})`);
-        }
-    }
-}
 function printSetupInstructions() {
     console.log('  To connect your OpenClaw agent to ReefClaw:');
     console.log('');

package/index.js

@@ -863,8 +863,8 @@ let pluginToolsFactory = null;
 let pluginToolNames = [];
 const paperTradingPlugin = {
     id: PLUGIN_ID,
-    name: 'ReefClaw Paper Trading',
-    description: 'Paper trading plugin with real Binance market data and simulated execution. No API keys required.',
+    name: 'ReefClaw Trading',
+    description: 'Supervised trading plugin for the ReefClaw dashboard: paper trading with real market data (no API keys required), and optional live trading on Binance or Hyperliquid behind explicit operator opt-in, exchange API credentials, and always-on protective stop brackets.',
     configSchema: {
         type: 'object',
         properties: {
@@ -1181,9 +1181,16 @@ const paperTradingPlugin = {
         // ingest credentials. See docs/APPROVAL_MODE_DESIGN.md §2 + §7.3.
         let proposalDecisionListener;
         if (tradingMode === 'MICRO_LIVE' || tradingMode === 'LIVE') {
-            if (!exchangeConfig) {
+            // Per-VENUE credential presence (rehearsal find #4): this safety check
+            // predated the venue seam and tested only the Binance shape, so a
+            // PERSISTED HL MICRO_LIVE (tradingMode written by the runtime flip)
+            // silently fell back to PAPER on every reboot — while the same config
+            // flipped live fine at runtime. The per-venue gate above is the real
+            // validation; this remains the defense-in-depth backstop.
+            const liveCredsPresent = venue === 'hyperliquid' ? hlCredentials !== null : exchangeConfig !== null;
+            if (!liveCredsPresent) {
                 // Already handled above (falls back to PAPER), but safety check
-                logger.error(TAG, `${tradingMode} mode requires exchange config — this should not happen`);
+                logger.error(TAG, `${tradingMode} mode requires ${venue} exchange credentials — this should not happen`);
                 adapter = new PaperAdapter(simulator);
                 tradingMode = 'PAPER';
             }

package/onboarding/runtime.d.ts

@@ -3,6 +3,8 @@ import type { ExchangeConfig, TradingMode } from '../types.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { PaperMarketFeed } from '../simulator/paper-market-feed.js';
 import { LiveAdapter } from '../live/live-adapter.js';
+import type { HlCredentials } from '../venues/hyperliquid/hl-private.js';
+import { type VenueId } from '../venues/registry.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
 import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export interface MicroLiveConfig {
@@ -14,6 +16,14 @@ export interface BuildAdapterInput {
     exchange: ExchangeConfig | null;
     microLive?: MicroLiveConfig;
     simulator: ExchangeSimulator;
+    /** Venue seam for the RUNTIME transition path (issue #217). Absent →
+     *  'binance' (every pre-venue caller byte-identical). The BOOT path got
+     *  this seam in Phase 3 (createLiveAdapter in index.ts); the runtime flip
+     *  — set_trading_mode, the product's go-live moment — missed it and
+     *  constructed a Binance LiveAdapter unconditionally. */
+    venue?: VenueId;
+    /** Required for a live-mode build on the hyperliquid venue. */
+    hlCredentials?: HlCredentials | null;
 }
 /** Wave 9 safety wiring is created only after its durable ledger is loaded.
  *  Runtime reapplies these hooks to both the bootstrap objects and every
@@ -81,6 +91,8 @@ export declare class PluginRuntime {
         mode: TradingMode;
         exchange: ExchangeConfig | null;
         microLive?: MicroLiveConfig;
+        venue?: VenueId;
+        hlCredentials?: HlCredentials | null;
     }, deps: {
         adapterDeps: {
             adapter: IExchangeAdapter;

package/onboarding/runtime.js

@@ -13,9 +13,11 @@
 // instant — no gateway restart required.
 import { PaperAdapter } from '../paper-adapter.js';
 import { LiveAdapter } from '../live/live-adapter.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+import { createLiveAdapter } from '../venues/registry.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
 import { loadBracketMode } from '../config/brackets-config.js';
-import { loadStopWatcherIntervalMs } from '../config/plugin-config-io.js';
+import { loadStopWatcherIntervalMs, readPluginConfig } from '../config/plugin-config-io.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'plugin-runtime';
 /** Pure-ish factory: builds an adapter for the requested mode.
@@ -29,6 +31,23 @@ export function buildAdapter(input) {
         // ShadowTracker wraps a BinancePrivateApi for real-balance comparison.
         return new PaperAdapter(simulator);
     }
+    // Hyperliquid live (issue #217): mirror the boot path's construction —
+    // per-venue credential shape, the SAME factory (createLiveAdapter), and
+    // the same fall-back-to-paper defense when credentials are absent.
+    if (input.venue === 'hyperliquid') {
+        if (!input.hlCredentials) {
+            logger.warn(TAG, `${mode} on hyperliquid requested without walletAddress+agentPrivateKey — falling back to PAPER`);
+            return new PaperAdapter(simulator);
+        }
+        return createLiveAdapter({
+            venue: 'hyperliquid',
+            args: {
+                credentials: input.hlCredentials,
+                mode: mode,
+                marketSlippagePct: readPluginConfig().hl?.marketSlippagePct,
+            },
+        });
+    }
     if (!exchange) {
         logger.warn(TAG, `${mode} requested without credentials — falling back to PAPER`);
         return new PaperAdapter(simulator);
@@ -131,12 +150,24 @@ export class PluginRuntime {
                 logger.warn(TAG, `old adapter shutdown failed: ${formatError(err)}`);
             }
         }
+        else if (old instanceof HyperliquidLiveAdapter) {
+            // Stops the HL user stream + the 60s REST truth-check timer — without
+            // this, a flip AWAY from HL live leaks both (issue #217).
+            try {
+                old.stop();
+            }
+            catch (err) {
+                logger.warn(TAG, `old HL adapter stop failed: ${formatError(err)}`);
+            }
+        }
         // 3. Build the new adapter.
         const fresh = buildAdapter({
             mode: next.mode,
             exchange: next.exchange,
             microLive: next.microLive,
             simulator: this.simulator,
+            venue: next.venue,
+            hlCredentials: next.hlCredentials,
         });
         // Install autonomous protection callbacks before initialization can emit
         // user-data or bracket-reconciler events.
@@ -145,7 +176,7 @@ export class PluginRuntime {
         }
         // 4. Fire async init for live adapters (non-blocking — readiness flips
         //    INIT_PENDING → READY/DEGRADED/BLOCKED on its own).
-        if (fresh instanceof LiveAdapter) {
+        if (fresh instanceof LiveAdapter || fresh instanceof HyperliquidLiveAdapter) {
             fresh.initialize().catch(err => {
                 logger.error(TAG, `New adapter init failed: ${formatError(err)}`);
             });

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "reefclaw-paper-trading",
-  "name": "ReefClaw Paper Trading",
-  "version": "0.1.0",
-  "description": "Paper trading plugin with real Binance market data and simulated execution. No API keys required.",
+  "name": "ReefClaw Trading",
+  "version": "0.1.9",
+  "description": "Supervised trading plugin for the ReefClaw dashboard: paper trading with real market data (no API keys required), and optional live trading on Binance or Hyperliquid behind explicit operator opt-in, exchange API credentials, and always-on protective stop brackets. Includes the dashboard connector bridge, heartbeat automation, and remote SKILL.md instruction updates from the ReefClaw webapp.",
   "author": "ReefClaw",
   "activation": {
     "onStartup": true

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.7",
-  "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",
+  "version": "0.1.9",
+  "description": "ReefClaw supervised trading plugin for OpenClaw \u2014 paper trading with real market data, optional live trading on Binance or Hyperliquid (operator opt-in, API keys, always-on protective brackets), plus the ReefClaw dashboard connector with heartbeat automation and remote SKILL.md updates from the ReefClaw webapp. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",
   "openclaw": {

package/scripts/assemble.mjs

@@ -66,16 +66,32 @@ if (!existsSync(pluginDist)) {
   console.log('[assemble] plugin/dist -> package root');
 }
 
-// 2. Manifest, with the `skills` declaration injected (npm package only).
+// 2. Manifest, with the `skills` declaration injected (npm package only) and the
+//    release version stamped from THIS package's package.json.
+//
+//    package.json#version is the authoritative release version — that is what
+//    ClawHub's `package-manifest-version-drift` rule compares against, and what
+//    OpenClaw's own `openclaw plugins build` writes into the manifest. The repo
+//    manifest (plugin/openclaw.plugin.json) carries a workspace-local version
+//    nobody bumps at release time, so copying it verbatim published
+//    manifest:0.1.0 against package:0.1.7 and tripped the validator. Deriving it
+//    here makes that drift structurally impossible instead of a bump to remember.
 const manifestSrc = join(repoRoot, 'plugin', 'openclaw.plugin.json');
+const pkgVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).version;
 if (!existsSync(manifestSrc)) {
   console.error('[assemble] missing plugin/openclaw.plugin.json.');
   missing += 1;
+} else if (typeof pkgVersion !== 'string' || pkgVersion.length === 0) {
+  console.error('[assemble] package.json has no version — cannot stamp the manifest.');
+  missing += 1;
 } else {
   const manifest = JSON.parse(readFileSync(manifestSrc, 'utf-8'));
+  manifest.version = pkgVersion;
   manifest.skills = ['./skills'];
   writeFileSync(join(pkgRoot, 'openclaw.plugin.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
-  console.log(`[assemble] manifest (+skills decl), ${manifest.contracts?.tools?.length ?? 0} contract tools`);
+  console.log(
+    `[assemble] manifest v${pkgVersion} (+skills decl), ${manifest.contracts?.tools?.length ?? 0} contract tools`,
+  );
 }
 
 // 3. The connector, bundled — this is what flips the supervisor's auto-start.

package/tools/create-order.d.ts

@@ -10,6 +10,13 @@ import { type Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownersh
 import { type Wave9LiveResidualProtectionResult } from '../wave9/live-residual-protection.js';
 import { type Wave9PaperAdmissionGuard } from '../wave9/paper-admission-guard.js';
 type Wave9LiveResidualProtector = (adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, candidateId: string, symbol: string) => Promise<Wave9LiveResidualProtectionResult>;
+/** Venue-aware idempotency cid for the live entry stash. HL client-order-ids
+ *  are 128-bit hex (0x + 32 hex chars) — a dashed randomUUID() fails
+ *  hl-private's cloid validation and the ENTRY IS REJECTED before reaching
+ *  the exchange (found live by the go-live rehearsal's first dust trade).
+ *  buildHlOrderCloid() mints the 0x0d… ORDER prefix, which the bracket parser
+ *  deliberately never recognises (cross-scheme cancels are destructive). */
+export declare function mintEntryStashCid(adapter: IExchangeAdapter): string;
 export declare function createOrderTool(args: {
     symbol: string;
     side: string;

package/tools/create-order.js

@@ -11,6 +11,8 @@ import { onCreateOrderFilled } from '../ingest/position-auto-capture.js';
 import { wave9ClientOrderId, } from '../wave9/live-execution-ledger.js';
 import { inspectWave9LiveSymbolOwnership, } from '../wave9/live-symbol-ownership.js';
 import { confirmWave9LivePositionFlat } from '../wave9/live-position-confirmation.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+import { buildHlOrderCloid } from '../venues/hyperliquid/hl-cloid.js';
 import { reprotectWave9LiveResidual, } from '../wave9/live-residual-protection.js';
 import { captureWave9PaperAccountSnapshot, isWave9ManagedPosition, WAVE9_BUNDLE_SETUP_TYPE, } from '../wave9/paper-admission-guard.js';
 function currentWave9ExecutionMode(deps) {
@@ -231,6 +233,15 @@ function candidateBoundFoundOrder(resolution, clientOrderId, symbol, side) {
         return undefined;
     return order;
 }
+/** Venue-aware idempotency cid for the live entry stash. HL client-order-ids
+ *  are 128-bit hex (0x + 32 hex chars) — a dashed randomUUID() fails
+ *  hl-private's cloid validation and the ENTRY IS REJECTED before reaching
+ *  the exchange (found live by the go-live rehearsal's first dust trade).
+ *  buildHlOrderCloid() mints the 0x0d… ORDER prefix, which the bracket parser
+ *  deliberately never recognises (cross-scheme cancels are destructive). */
+export function mintEntryStashCid(adapter) {
+    return adapter instanceof HyperliquidLiveAdapter ? buildHlOrderCloid() : randomUUID();
+}
 async function resolveWave9EntryCid(adapter, clientOrderId, symbol) {
     if (!adapter.resolveOrderByClientId) {
         return { status: 'unknown', detail: 'deterministic client-order resolver is unavailable' };
@@ -1133,7 +1144,7 @@ export async function createOrderTool(args, deps) {
                 ? wave9ClientOrderId(args.candidate_id)
                 : undefined;
             if (deps.autoCapture?.pendingEntries && metadata) {
-                stashCid ??= randomUUID();
+                stashCid ??= mintEntryStashCid(deps.adapter);
                 deps.autoCapture.pendingEntries.put({
                     orderId: stashCid,
                     clientOrderId: stashCid,

package/tools/set-trading-mode.js

@@ -9,6 +9,7 @@
 // because the caller chain is currently controlled end-to-end by the skill.
 import { readPluginConfig } from '../config/plugin-config-io.js';
 import { validateModeTransition, modeRequiresCredentials } from '../onboarding/mode-ladder.js';
+import { parseVenue } from '../venues/registry.js';
 import { logger } from '../logger.js';
 import { recordModeTransition } from '../audit/mode-transition-audit.js';
 const TAG = 'set-trading-mode';
@@ -49,12 +50,26 @@ export async function setTradingModeTool(args, deps) {
             readiness: deps.runtime.adapter.readiness,
         };
     }
-    // 3. Credential requirement check.
+    // 3. Credential requirement check — PER VENUE (issue #217: this gate was
+    //    Binance-only, so the go-live flip on the hyperliquid venue was rejected
+    //    despite valid walletAddress+agentPrivateKey in plugin-config).
     let exchange = null;
+    let hlCredentials = null;
+    let venue = 'binance';
     if (modeRequiresCredentials(target)) {
         try {
             const cfg = readPluginConfig(deps.configPath);
-            if (cfg.exchange?.apiKey && cfg.exchange?.secret) {
+            venue = parseVenue(cfg.exchange?.venue).venue;
+            if (venue === 'hyperliquid') {
+                if (cfg.exchange?.walletAddress && cfg.exchange?.agentPrivateKey) {
+                    hlCredentials = {
+                        walletAddress: String(cfg.exchange.walletAddress),
+                        agentPrivateKey: String(cfg.exchange.agentPrivateKey),
+                        testnet: cfg.exchange.testnet === true,
+                    };
+                }
+            }
+            else if (cfg.exchange?.apiKey && cfg.exchange?.secret) {
                 exchange = {
                     apiKey: cfg.exchange.apiKey,
                     secret: cfg.exchange.secret,
@@ -74,11 +89,13 @@ export async function setTradingModeTool(args, deps) {
                 reason: 'config_read_error',
             };
         }
-        if (!exchange) {
+        if (!exchange && !hlCredentials) {
             recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'missing_credentials' });
             return {
                 ok: false,
-                message: `${target} mode requires exchange credentials. Run set_exchange_credentials first.`,
+                message: venue === 'hyperliquid'
+                    ? `${target} mode on Hyperliquid requires exchange.walletAddress (master) + exchange.agentPrivateKey (agent wallet) in plugin-config.`
+                    : `${target} mode requires exchange credentials. Run set_exchange_credentials first.`,
                 previousMode,
                 mode: previousMode,
                 readiness: deps.runtime.adapter.readiness,
@@ -116,14 +133,14 @@ export async function setTradingModeTool(args, deps) {
         };
     }
     // 6. Swap the adapter.
-    await deps.runtime.reconnect({ mode: target, exchange }, { adapterDeps: deps.adapterDeps });
+    await deps.runtime.reconnect({ mode: target, exchange, venue, hlCredentials }, { adapterDeps: deps.adapterDeps });
     logger.info(TAG, `Transitioned ${previousMode} → ${target}`);
     recordModeTransition({
         previousMode,
         targetMode: target,
         acknowledged,
         ok: true,
-        testnet: exchange?.testnet,
+        testnet: exchange?.testnet ?? hlCredentials?.testnet,
     });
     return {
         ok: true,

package/types.js

@@ -1,4 +1,4 @@
-// Types for the ReefClaw Paper Trading plugin.
+// Types for the ReefClaw Trading plugin.
 // CCXT-compatible types that match what the GatewayProvider's event-parser expects.
 export const DEFAULT_CONFIG = {
     startingBalance: 10000,