@reefclaw/openclaw-plugin 0.1.12 → 0.1.13

package/ccxt/binance-public.js

@@ -1,5 +1,35 @@
 // Thin wrapper around CCXT for Binance public API endpoints.
 // No API keys required — only uses public market data.
+//
+// ★ USD-M FUTURES, NOT SPOT. ReefClaw trades Binance USD-M perpetuals, so every
+// price this client serves must come from `fapi.binance.com`. `ccxt.binance` is
+// the combined spot+futures class and defaults to SPOT, so without an explicit
+// `defaultType: 'future'` the symbol-resolving reads (fetchTicker / fetchOHLCV /
+// fetchOrderBook) silently resolved to the spot market. That was wrong in two
+// ways at once:
+//   1. SILENT: every pair with a spot twin (BTC/USDT, ETH/USDT, …) returned
+//      SPOT prices on a perp product — charts, paper marks and paper fills all
+//      priced off the wrong book, diverging from the perp by the basis.
+//   2. LOUD: the 17 futures-ONLY contracts (1000FLOKI, 1000PEPE, 1000SHIB,
+//      1000BONK, 1000SATS, 1000RATS, 1000LUNC, 1000XEC, 1000CAT, …) have no
+//      spot market, so every fetch threw `binance does not have market symbol`.
+//      A user holding one got a dead feed: 100% ticker failure, marks frozen at
+//      entry, unrealized stuck at 0, and the frozen NAV then fed a phantom
+//      RED-zone drawdown -> auto-flatten. Observed on a live customer box
+//      2026-07-25 (1000FLOKI/USDT, 120/120 failed polls).
+// `fetchFundingRate` / `fetchOpenInterest` were always futures-correct (ccxt
+// routes them to fapi regardless) and `probeReachability` calls the futures
+// endpoint explicitly, so only the three symbol-resolving reads change.
+//
+// Weights are unchanged and already futures-calibrated in binance-ban-gate.ts
+// (ceiling 2000/2400 = the USD-M IP cap). Doc-verified against
+// https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api
+// (2026-07-25): host `fapi.binance.com`; /fapi/v1/ticker/24hr weight 1 for a
+// single symbol (gate charges 2), /fapi/v1/klines weight 1-10 by limit (gate
+// charges 2), /fapi/v1/depth weight 2-20 by limit (gate charges 5) — the gate
+// stays conservative on all three, so this never under-counts. It does mean the
+// calls now genuinely consume the futures budget the gate was already charging
+// them against (spot and futures have separate IP weight pools).
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
 import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
@@ -26,8 +56,12 @@ export class BinancePublicApi {
         }
         this.exchange = new BinanceClass({
             enableRateLimit: true,
+            // ★ Load-bearing — see the file header. Without this ccxt.binance serves
+            // SPOT, which mispriced every perp read and hard-failed the futures-only
+            // 1000x contracts. Pinned by binance-public.test.ts.
+            options: { defaultType: 'future' },
         });
-        logger.info(TAG, 'Binance public API initialized (no auth)');
+        logger.info(TAG, 'Binance public API initialized (no auth, USD-M futures)');
     }
     /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -146,8 +180,10 @@ export class BinancePublicApi {
     }
     /** 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').
+     *  `fapi.binance.com` regardless of how the instance is configured. Keep it
+     *  explicit even though the client now sets `defaultType: 'future'`: this
+     *  probe must detect a futures-specific 451 geo-block, and it must not start
+     *  silently probing spot if that option is ever changed.
      *  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:

package/live/proposal-decision-listener.d.ts

@@ -35,6 +35,9 @@ export interface ProposalDecisionListenerHealth {
     running: boolean;
     ticksTotal: number;
     ticksWithFires: number;
+    claimsAcquired: number;
+    claimConflicts: number;
+    claimFailures: number;
     firesAttempted: number;
     firesSucceeded: number;
     firesAbandonedDrift: number;
@@ -53,6 +56,21 @@ export declare class ProposalDecisionListener {
      *  that finds ≥1 pending. */
     private currentIntervalMs;
     private health;
+    /** Claim tokens are process-local by design. A new process must never steal
+     *  an old process's durable claim, because it cannot know whether the
+     *  exchange accepted an order just before the crash. */
+    private readonly claimTokens;
+    /** In-memory work queue for claims whose POST or fire-result response was
+     *  lost. The DB poll excludes claimed rows, so only the original process can
+     *  retry its exact token/outcome; a restarted process cannot steal it. */
+    private readonly claimedCandidates;
+    private readonly acquiredClaims;
+    /** Once present, this process must never invoke createOrderTool for the
+     *  proposal again. Any subsequent work is result persistence only. */
+    private readonly mutationsStarted;
+    /** Completed outcomes awaiting a successful fire-result response. Retrying
+     *  this PATCH is safe; retrying the exchange mutation is not. */
+    private readonly pendingResults;
     constructor(options: ProposalDecisionListenerOptions);
     /** Begin the poll loop. Idempotent — subsequent calls are no-ops while
      *  the listener is already running. */
@@ -65,6 +83,8 @@ export declare class ProposalDecisionListener {
     private runTick;
     private tick;
     private fetchPending;
+    private claimPending;
+    private forgetClaim;
     private firePending;
     private patchResult;
 }

package/live/proposal-decision-listener.js

@@ -3,29 +3,31 @@
 //
 // Phase B implementation: polls GET /api/internal/proposed_orders/pending-decisions
 // at config.pollIntervalMs (default 3 sec). For each approved-but-unfired row:
-//   1. Drift abandon — if mark price has moved more than ±0.3 R from the
+//   1. POST /claim — atomically acquire non-transferable DB ownership before
+//      any exchange side effect. A second listener cannot acquire the row.
+//   2. Drift abandon — if mark price has moved more than ±0.3 R from the
 //      proposed entry since the proposal was created, fail with a transparent
 //      `fireError` rather than firing into a different setup.
-//   2. Fire via createOrderTool — same backend function the toggle-off path
-//      calls directly. Reuses the pre-trade risk gate, bracket attach, and
-//      auto-capture entry-row write.
-//   3. PATCH /fire-result with either firedOrderId or fireError. Fired-once
-//      idempotency lives in the DB constraint (status='approved' AND
-//      fired_order_id IS NULL filter).
+//   3. Fire via createOrderTool with a proposal-derived exchange CID — same
+//      backend function the toggle-off path calls directly. Once this boundary
+//      starts, only result persistence may retry.
+//   4. PATCH /fire-result with the claim token and either firedOrderId or
+//      fireError. An exact lost-response retry is idempotently acknowledged.
 //
 // Started by index.ts only when config.approval.mode === 'per_trade' AND
 // ingest credentials are present. Drained at shutdown so an in-flight fire
-// completes its PATCH before the process exits.
+// gets one final opportunity to complete its PATCH before the process exits.
 //
 // Why polling and not relay events: simpler — no skill <-> plugin event-bus
 // changes needed. 3-sec poll is well under the latency a human approval flow
 // tolerates. Refactor to SSE/relay-push only if measurement shows the poll
-// load is meaningful (very unlikely — ~3 req/s per user is negligible).
+// load is meaningful (very unlikely — ~0.33 req/s per active user is small).
 //
 // See docs/APPROVAL_MODE_DESIGN.md §2 (architecture) + §7.3 (re-validation) +
 // §10 failure matrix.
+import { randomUUID } from 'node:crypto';
 import { logger, formatError } from '../logger.js';
-import { createOrderTool } from '../tools/create-order.js';
+import { createOrderTool, proposalEntryClientOrderId, } from '../tools/create-order.js';
 const TAG = 'proposal-decision-listener';
 export class ProposalDecisionListener {
     opts;
@@ -40,6 +42,9 @@ export class ProposalDecisionListener {
         running: false,
         ticksTotal: 0,
         ticksWithFires: 0,
+        claimsAcquired: 0,
+        claimConflicts: 0,
+        claimFailures: 0,
         firesAttempted: 0,
         firesSucceeded: 0,
         firesAbandonedDrift: 0,
@@ -48,6 +53,21 @@ export class ProposalDecisionListener {
         pollFailures: 0,
         lastTickAt: null,
     };
+    /** Claim tokens are process-local by design. A new process must never steal
+     *  an old process's durable claim, because it cannot know whether the
+     *  exchange accepted an order just before the crash. */
+    claimTokens = new Map();
+    /** In-memory work queue for claims whose POST or fire-result response was
+     *  lost. The DB poll excludes claimed rows, so only the original process can
+     *  retry its exact token/outcome; a restarted process cannot steal it. */
+    claimedCandidates = new Map();
+    acquiredClaims = new Set();
+    /** Once present, this process must never invoke createOrderTool for the
+     *  proposal again. Any subsequent work is result persistence only. */
+    mutationsStarted = new Set();
+    /** Completed outcomes awaiting a successful fire-result response. Retrying
+     *  this PATCH is safe; retrying the exchange mutation is not. */
+    pendingResults = new Map();
     constructor(options) {
         this.opts = {
             baseUrl: options.baseUrl.replace(/\/+$/, ''),
@@ -119,7 +139,14 @@ export class ProposalDecisionListener {
     async tick() {
         this.health.ticksTotal++;
         this.health.lastTickAt = new Date().toISOString();
-        const pending = await this.fetchPending();
+        const fetched = await this.fetchPending();
+        // Claimed rows disappear from the DB poll. Keep only this process's exact
+        // token/candidate in a private queue so lost claim and result responses
+        // can be retried without making claims stealable after restart.
+        const pendingById = new Map(this.claimedCandidates);
+        for (const proposal of fetched)
+            pendingById.set(proposal.id, proposal);
+        const pending = [...pendingById.values()];
         if (pending.length === 0) {
             // Idle backoff — schedule next tick at the longer idle interval until
             // the queue becomes non-empty. This is the dominant cost-reduction lever
@@ -137,12 +164,10 @@ export class ProposalDecisionListener {
                 await this.firePending(p);
             }
             catch (err) {
-                // Defensive — firePending should already write a fireError PATCH on
-                // any failure path. If something escapes, surface it loudly so the
-                // operator can diagnose; the proposal will remain in approved state
-                // and be retried on the next tick (idempotent because firedOrderId
-                // is still NULL until a successful PATCH writes it).
-                logger.error(TAG, `Unhandled exception firing proposal ${p.id} (will retry next tick): ${formatError(err)}`);
+                // Before the mutation latch, the original token/candidate may retry.
+                // After the latch, firePending refuses another exchange call and the
+                // durable claim/CID require manual reconciliation if no result exists.
+                logger.error(TAG, `Unhandled exception processing claimed proposal ${p.id}: ${formatError(err)}`);
             }
         }
     }
@@ -158,6 +183,7 @@ export class ProposalDecisionListener {
                     headers: {
                         authorization: `Bearer ${this.opts.ingestToken}`,
                         'x-user-id': this.opts.userId,
+                        'x-reefclaw-proposal-claim-version': '1',
                     },
                     signal: ac.signal,
                 });
@@ -179,8 +205,97 @@ export class ProposalDecisionListener {
             return [];
         }
     }
+    async claimPending(proposalId, claimToken) {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders/${proposalId}/claim`;
+        try {
+            const ac = new AbortController();
+            const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+            let res;
+            try {
+                res = await this.opts.fetchImpl(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.opts.ingestToken}`,
+                        'x-user-id': this.opts.userId,
+                    },
+                    body: JSON.stringify({ claimToken }),
+                    signal: ac.signal,
+                });
+            }
+            finally {
+                clearTimeout(tid);
+            }
+            if (res.status === 409) {
+                this.health.claimConflicts++;
+                logger.info(TAG, `Proposal ${proposalId} was claimed by another listener`);
+                return 'conflict';
+            }
+            if (!res.ok) {
+                this.health.claimFailures++;
+                logger.warn(TAG, `POST ${url} returned ${res.status}`);
+                return 'unknown';
+            }
+            const body = await res.json();
+            if (body.ok !== true
+                || body.id !== proposalId
+                || body.claimToken !== claimToken) {
+                this.health.claimFailures++;
+                logger.warn(TAG, `POST ${url} returned a malformed claim acknowledgement`);
+                return 'unknown';
+            }
+            return 'acquired';
+        }
+        catch (err) {
+            this.health.claimFailures++;
+            logger.warn(TAG, `POST ${url} threw: ${formatError(err)}`);
+            return 'unknown';
+        }
+    }
+    forgetClaim(proposalId) {
+        this.claimTokens.delete(proposalId);
+        this.claimedCandidates.delete(proposalId);
+        this.acquiredClaims.delete(proposalId);
+        this.mutationsStarted.delete(proposalId);
+        this.pendingResults.delete(proposalId);
+    }
     async firePending(p) {
+        let claimToken = this.claimTokens.get(p.id);
+        if (!claimToken) {
+            claimToken = randomUUID();
+            this.claimTokens.set(p.id, claimToken);
+            this.claimedCandidates.set(p.id, p);
+        }
+        if (!this.acquiredClaims.has(p.id)) {
+            const claimStatus = await this.claimPending(p.id, claimToken);
+            if (claimStatus !== 'acquired') {
+                if (claimStatus === 'conflict')
+                    this.forgetClaim(p.id);
+                return;
+            }
+            this.acquiredClaims.add(p.id);
+            this.health.claimsAcquired++;
+        }
+        const awaitingPersistence = this.pendingResults.get(p.id);
+        if (awaitingPersistence) {
+            if (await this.patchResult(p.id, awaitingPersistence)
+                && awaitingPersistence.firedOrderId) {
+                this.health.firesSucceeded++;
+            }
+            return;
+        }
+        if (this.mutationsStarted.has(p.id)) {
+            logger.error(TAG, `Proposal ${p.id} has an ambiguous claimed mutation; refusing automatic re-fire`);
+            return;
+        }
         this.health.firesAttempted++;
+        if (Date.now() >= new Date(p.hardExpiresAt).getTime()) {
+            await this.patchResult(p.id, {
+                fireError: `hard_expired before fire (expired ${p.hardExpiresAt})`,
+            });
+            this.health.firesFailedTrading++;
+            return;
+        }
         // ---- 1. Drift abandon (Locked Decision #6) ----
         // Skip if we can't read a current price — better to let the trading path
         // surface the error than to silently abandon on a transient ticker miss.
@@ -198,35 +313,60 @@ export class ProposalDecisionListener {
                 }
             }
         }
+        // Validation can cross the hard-expiry boundary. Claim ownership alone is
+        // not authorization to submit after the deadline.
+        if (Date.now() >= new Date(p.hardExpiresAt).getTime()) {
+            await this.patchResult(p.id, {
+                fireError: `hard_expired before exchange mutation (expired ${p.hardExpiresAt})`,
+            });
+            this.health.firesFailedTrading++;
+            return;
+        }
         // ---- 2. Fire via createOrderTool (same path toggle-off mode uses) ----
         // CRITICAL: do NOT pass proposalManager + userId here. The listener IS the
         // consumer of approved proposals; passing proposalManager would recursively
         // dual-write another proposal row for the same intent. The agent's path
         // dual-writes; the listener's path fires the underlying order.
-        const result = await createOrderTool({
-            symbol: p.symbol,
-            side: p.side,
-            type: p.orderType,
-            amount: p.size,
-            // For limit orders we honour the original proposed entry. For market,
-            // the create_order tool reads the live ticker (per existing semantics).
-            price: p.orderType === 'limit' ? p.proposedEntry : undefined,
-            stopPrice: p.stopPrice,
-            target_price: p.targetPrice,
-            setup_type: p.setupType,
-            thesis: p.thesis,
-            regime: p.regime,
-            regime_confidence: p.regimeConfidence,
-            scorecard_verdict: p.scorecardVerdict,
-            confluence_score: p.confluenceScore,
-        }, {
-            binanceApi: this.opts.binanceApi,
-            adapter: this.opts.adapter,
-            autoCapture: this.opts.autoCapture,
-            operationLock: this.opts.operationLock,
-            checkWave9LiveSymbolOwnership: this.opts.checkWave9LiveSymbolOwnership,
-            // proposalManager + userId deliberately omitted — see above.
-        });
+        const entryClientOrderId = proposalEntryClientOrderId(this.opts.adapter, p.proposalUuid);
+        // This latch is set immediately before the function that can touch the
+        // exchange. No path clears it until fire-result is durably acknowledged.
+        this.mutationsStarted.add(p.id);
+        let result;
+        try {
+            result = await createOrderTool({
+                symbol: p.symbol,
+                side: p.side,
+                type: p.orderType,
+                amount: p.size,
+                // For limit orders we honour the original proposed entry. For market,
+                // the create_order tool reads the live ticker (per existing semantics).
+                price: p.orderType === 'limit' ? p.proposedEntry : undefined,
+                stopPrice: p.stopPrice,
+                target_price: p.targetPrice,
+                setup_type: p.setupType,
+                thesis: p.thesis,
+                regime: p.regime,
+                regime_confidence: p.regimeConfidence,
+                scorecard_verdict: p.scorecardVerdict,
+                confluence_score: p.confluenceScore,
+            }, {
+                binanceApi: this.opts.binanceApi,
+                adapter: this.opts.adapter,
+                autoCapture: this.opts.autoCapture,
+                operationLock: this.opts.operationLock,
+                checkWave9LiveSymbolOwnership: this.opts.checkWave9LiveSymbolOwnership,
+                entryClientOrderId,
+                // proposalManager + userId deliberately omitted — see above.
+            });
+        }
+        catch (err) {
+            await this.patchResult(p.id, {
+                fireError: `order_outcome_ambiguous: create_order threw after mutation boundary ` +
+                    `(clientOrderId=${entryClientOrderId}): ${formatError(err)}`,
+            });
+            this.health.firesFailedTrading++;
+            return;
+        }
         if ('error' in result) {
             // Trading-path rejection (risk gate, bracket attach failure, exchange
             // rejection, etc.). Surface to the operator via the proposal row.
@@ -246,12 +386,30 @@ export class ProposalDecisionListener {
             this.health.firesFailedTrading++;
             return;
         }
-        const firedOrderId = typeof result.id === 'string' ? result.id : `unknown-${Date.now()}`;
+        if (typeof result.id !== 'string' || result.id.length === 0) {
+            await this.patchResult(p.id, {
+                fireError: `order_outcome_ambiguous: exchange acknowledgement had no order id ` +
+                    `(clientOrderId=${entryClientOrderId})`,
+            });
+            this.health.firesFailedTrading++;
+            return;
+        }
+        const firedOrderId = result.id;
         logger.info(TAG, `Proposal ${p.id} fired → order ${firedOrderId}`);
-        await this.patchResult(p.id, { firedOrderId });
-        this.health.firesSucceeded++;
+        if (await this.patchResult(p.id, { firedOrderId })) {
+            this.health.firesSucceeded++;
+        }
     }
     async patchResult(proposalId, body) {
+        const claimToken = this.claimTokens.get(proposalId);
+        if (!claimToken) {
+            this.health.patchFailures++;
+            logger.error(TAG, `Refusing fire-result for unclaimed proposal ${proposalId}`);
+            return;
+        }
+        // Persist locally before the HTTP attempt. Any lost/failed response retries
+        // only this PATCH; createOrderTool is never invoked again.
+        this.pendingResults.set(proposalId, body);
         const url = `${this.opts.baseUrl}/api/internal/proposed_orders/${proposalId}/fire-result`;
         try {
             const ac = new AbortController();
@@ -265,7 +423,7 @@ export class ProposalDecisionListener {
                         authorization: `Bearer ${this.opts.ingestToken}`,
                         'x-user-id': this.opts.userId,
                     },
-                    body: JSON.stringify(body),
+                    body: JSON.stringify({ claimToken, ...body }),
                     signal: ac.signal,
                 });
             }
@@ -273,9 +431,12 @@ export class ProposalDecisionListener {
                 clearTimeout(tid);
             }
             if (res.status === 409) {
-                // Already-recorded race — listener double-fired but webapp's idempotency
-                // guard caught the duplicate. Not an error.
-                logger.info(TAG, `Proposal ${proposalId} fire-result already recorded (409, expected on retry)`);
+                this.health.patchFailures++;
+                logger.error(TAG, `Proposal ${proposalId} fire-result claim mismatch (409)`);
+                // Never retry the exchange mutation. Exact lost-response retries are
+                // 200; a 409 means this process cannot commit the result and the
+                // durable claim must be reconciled manually.
+                this.forgetClaim(proposalId);
                 return;
             }
             if (!res.ok) {
@@ -283,6 +444,8 @@ export class ProposalDecisionListener {
                 logger.warn(TAG, `PATCH ${url} → ${res.status}`);
                 return;
             }
+            this.forgetClaim(proposalId);
+            return true;
         }
         catch (err) {
             this.health.patchFailures++;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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",

package/tools/create-order.d.ts

@@ -17,6 +17,14 @@ type Wave9LiveResidualProtector = (adapter: IExchangeAdapter, ledger: Wave9LiveE
  *  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;
+/** Stable exchange idempotency key for one approved proposal.
+ *
+ * A listener can crash after exchange acceptance but before fire-result is
+ * persisted. Reconciliation must query the exact same client-order ID instead
+ * of submitting with a freshly generated one. Binance permits 36-character
+ * ASCII IDs; Hyperliquid requires exactly 128 bits of hex.
+ */
+export declare function proposalEntryClientOrderId(adapter: IExchangeAdapter, proposalUuid: string): string;
 export declare function createOrderTool(args: {
     symbol: string;
     side: string;
@@ -61,6 +69,9 @@ export declare function createOrderTool(args: {
     proposalManager?: ProposalManager;
     userId?: string;
     approvalMode?: 'off' | 'shadow' | 'per_trade';
+    /** Internal listener-only override. Keeps one approved proposal bound to a
+     * deterministic exchange idempotency key across reconciliation/restart. */
+    entryClientOrderId?: string;
     wave9AdmissionGuard?: Wave9PaperAdmissionGuard;
     wave9ActivationCheck?: () => Promise<{
         available: boolean;

package/tools/create-order.js

@@ -1,6 +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 { createHash, randomUUID } from 'node:crypto';
 import { formatError } from '../logger.js';
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
 import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
@@ -242,6 +242,27 @@ function candidateBoundFoundOrder(resolution, clientOrderId, symbol, side) {
 export function mintEntryStashCid(adapter) {
     return adapter instanceof HyperliquidLiveAdapter ? buildHlOrderCloid() : randomUUID();
 }
+/** Stable exchange idempotency key for one approved proposal.
+ *
+ * A listener can crash after exchange acceptance but before fire-result is
+ * persisted. Reconciliation must query the exact same client-order ID instead
+ * of submitting with a freshly generated one. Binance permits 36-character
+ * ASCII IDs; Hyperliquid requires exactly 128 bits of hex.
+ */
+export function proposalEntryClientOrderId(adapter, proposalUuid) {
+    const hex = proposalUuid.replace(/-/g, '').toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(hex)) {
+        throw new Error('proposalUuid must be a UUID');
+    }
+    if (adapter instanceof HyperliquidLiveAdapter) {
+        // Keep deterministic entries in the same 0x0d plain-order namespace as
+        // buildHlOrderCloid(). Using the UUID bytes directly could begin with
+        // bc7[e57] and be misclassified as a managed bracket leg.
+        const digest = createHash('sha256').update(hex).digest('hex');
+        return `0x0d${digest.slice(0, 30)}`;
+    }
+    return `rcp-${hex}`;
+}
 async function resolveWave9EntryCid(adapter, clientOrderId, symbol) {
     if (!adapter.resolveOrderByClientId) {
         return { status: 'unknown', detail: 'deterministic client-order resolver is unavailable' };
@@ -1142,7 +1163,7 @@ export async function createOrderTool(args, deps) {
             // throws, the unused stash entry simply expires (24h TTL, pruned).
             let stashCid = wave9Claimed && initialWave9Mode === 'LIVE'
                 ? wave9ClientOrderId(args.candidate_id)
-                : undefined;
+                : deps.entryClientOrderId;
             if (deps.autoCapture?.pendingEntries && metadata) {
                 stashCid ??= mintEntryStashCid(deps.adapter);
                 deps.autoCapture.pendingEntries.put({

package/tools/get-risk-summary.d.ts

@@ -41,6 +41,10 @@ export interface RiskSummaryResult {
         readyForUpgrade: boolean;
         upgradeBlockers: string[];
     };
+    /** Present only when an input field was missing/non-finite and a substitute
+     *  was used. Honest degradation: the numbers above still render, and the
+     *  agent is TOLD which ones are not straight from the exchange. */
+    dataWarnings?: string[];
     timestamp: string;
 }
 export declare function getRiskSummaryTool(_args: Record<string, never>, deps: {