@reefclaw/openclaw-plugin 0.1.22 → 0.1.24

package/simulator/exchange-simulator.js

@@ -12,6 +12,34 @@ import { fillMarketOrder, fillLimitOrder, parseSymbol } from './fill-engine.js';
 import { updateMfe } from '../mfe.js';
 import { computeInvalidationHit } from '../pinned-plan.js';
 const TAG = 'simulator';
+/** Canonical key for the per-symbol quote/orderbook caches and for matching a
+ *  ticker against stored positions/orders.
+ *
+ *  CCXT echoes the VENUE-UNIFIED symbol back from fetchTicker: ask Binance USDM
+ *  for 'ETH/USDT' and the ticker returns as 'ETH/USDT:USDT'. Positions and
+ *  orders, however, are stored under whatever form the caller opened them with,
+ *  so `lastTicker.get(position.symbol)` silently missed for every position held
+ *  in the un-suffixed form. The consequences were all silent:
+ *    - getPositions()/computeEquity() fell back to entryPrice, so the mark was
+ *      FROZEN at entry — the stop-watcher compared a frozen mark, never saw a
+ *      breach, and the position ran unprotected past its stop indefinitely;
+ *    - createOrder() threw 'No ticker data for X' on the market leg, so the
+ *      agent could not close by hand either (both automatic and manual exits
+ *      were dead at once);
+ *    - MFE, take-profit legs and resting-limit fills never advanced.
+ *  Keying both sides through this normalizer makes the caches format-agnostic,
+ *  which also repairs books already persisted with a mix of both forms.
+ *
+ *  Same regex as webapp/src/lib/symbols.ts normalizeSymbol and
+ *  plugin/src/venues/symbols.ts stripSettleSuffix — kept inline so the
+ *  simulator keeps its zero-import-for-hot-path shape. */
+export function tickerKey(symbol) {
+    return symbol.replace(/:[A-Z]+$/, '');
+}
+/** True when two symbols denote the same market regardless of settle suffix. */
+function sameMarket(a, b) {
+    return tickerKey(a) === tickerKey(b);
+}
 export class ExchangeSimulator extends EventEmitter {
     state;
     lastTicker = new Map();
@@ -112,7 +140,7 @@ export class ExchangeSimulator extends EventEmitter {
         const walletTotal = this.state.wallet[quote]?.total ?? 0;
         let positionEquity = 0;
         for (const pos of this.state.positions) {
-            const ticker = this.lastTicker.get(pos.symbol);
+            const ticker = this.lastTicker.get(tickerKey(pos.symbol));
             const mark = ticker?.last ?? pos.entryPrice;
             const entryNotional = pos.entryPrice * pos.quantity;
             const unrealized = pos.side === 'long'
@@ -182,10 +210,16 @@ export class ExchangeSimulator extends EventEmitter {
     }
     getPositions(symbol) {
         const positions = symbol
-            ? this.state.positions.filter(p => p.symbol === symbol)
+            ? this.state.positions.filter(p => sameMarket(p.symbol, symbol))
             : this.state.positions;
         return positions.map(p => {
-            const ticker = this.lastTicker.get(p.symbol);
+            const ticker = this.lastTicker.get(tickerKey(p.symbol));
+            // No quote for this symbol means we CANNOT mark this position. Falling
+            // back to entryPrice fabricates "flat since entry", which reads as a
+            // perfectly healthy position to every consumer — that is how a stop
+            // breach stayed invisible for 35h. Keep the fallback (callers need a
+            // number) but flag it so the stop-watcher can alarm instead of skipping.
+            const markPriceStale = ticker === undefined;
             const markPrice = ticker?.last ?? p.entryPrice;
             const notional = p.quantity * markPrice;
             const pnlMultiplier = p.side === 'long' ? 1 : -1;
@@ -200,6 +234,7 @@ export class ExchangeSimulator extends EventEmitter {
                 contractSize: 1,
                 entryPrice: p.entryPrice,
                 markPrice,
+                markPriceStale,
                 notional,
                 unrealizedPnl,
                 percentage,
@@ -233,7 +268,7 @@ export class ExchangeSimulator extends EventEmitter {
     }
     getOpenOrders(symbol) {
         const orders = symbol
-            ? this.state.openOrders.filter(o => o.symbol === symbol)
+            ? this.state.openOrders.filter(o => sameMarket(o.symbol, symbol))
             : this.state.openOrders;
         return orders.map(o => this.toCcxtOrder(o));
     }
@@ -244,10 +279,10 @@ export class ExchangeSimulator extends EventEmitter {
     // ---- Order book ----
     /** Cache the latest order book snapshot for a symbol. */
     updateOrderBook(symbol, orderbook) {
-        this.lastOrderBook.set(symbol, orderbook);
+        this.lastOrderBook.set(tickerKey(symbol), orderbook);
     }
     getLastOrderBook(symbol) {
-        return this.lastOrderBook.get(symbol);
+        return this.lastOrderBook.get(tickerKey(symbol));
     }
     // ---- Write operations (for tools) ----
     createOrder(symbol, side, type, amount, price, metadata, 
@@ -294,7 +329,7 @@ export class ExchangeSimulator extends EventEmitter {
                 return this.executeMarketFill(order, referencePrice, metadata);
             }
             // Market orders fill immediately at current price
-            const ticker = this.lastTicker.get(symbol);
+            const ticker = this.lastTicker.get(tickerKey(symbol));
             if (!ticker) {
                 throw new Error(`No ticker data for ${symbol}. Call updateTicker() first.`);
             }
@@ -308,7 +343,7 @@ export class ExchangeSimulator extends EventEmitter {
         // Limit order — check if it crosses the current price. A stale quote must
         // not price an immediate cross-fill (same hazard as market fills); the
         // order RESTS instead and fills on the next fresh tick via updateTicker.
-        const ticker = this.lastTicker.get(symbol);
+        const ticker = this.lastTicker.get(tickerKey(symbol));
         if (ticker && this.quoteAgeMs(ticker) <= this.maxQuoteAgeMs() && this.shouldFillLimit(order, ticker.last)) {
             return this.executeLimitFill(order, ticker.last, metadata);
         }
@@ -341,7 +376,7 @@ export class ExchangeSimulator extends EventEmitter {
         const cancelled = [];
         const remaining = [];
         for (const order of this.state.openOrders) {
-            if (!symbol || order.symbol === symbol) {
+            if (!symbol || sameMarket(order.symbol, symbol)) {
                 order.status = 'canceled';
                 cancelled.push(order);
                 this.pendingOrderMetadata.delete(order.id);
@@ -364,7 +399,7 @@ export class ExchangeSimulator extends EventEmitter {
      *   else, which keeps the normal market-close path byte-identical.
      */
     closePosition(symbol, closeReason, referencePrice) {
-        const position = this.state.positions.find(p => p.symbol === symbol);
+        const position = this.state.positions.find(p => sameMarket(p.symbol, symbol));
         if (!position) {
             throw new Error(`No open position for ${symbol}`);
         }
@@ -387,7 +422,7 @@ export class ExchangeSimulator extends EventEmitter {
      *  and getPositions both read metadata.stopPrice, so a moved stop takes
      *  effect on the next watcher tick. Throws if there is no open position. (M9) */
     updatePositionMetadata(symbol, patch) {
-        const pos = this.state.positions.find(p => p.symbol === symbol);
+        const pos = this.state.positions.find(p => sameMarket(p.symbol, symbol));
         if (!pos) {
             throw new Error(`No open position for ${symbol}`);
         }
@@ -401,7 +436,7 @@ export class ExchangeSimulator extends EventEmitter {
     }
     // ---- Ticker updates (checks pending limit fills) ----
     updateTicker(ticker) {
-        this.lastTicker.set(ticker.symbol, ticker);
+        this.lastTicker.set(tickerKey(ticker.symbol), ticker);
         this.refreshMfeForSymbol(ticker.symbol, ticker.last);
         // MFE is refreshed FIRST so the peak this tick reached is recorded before a
         // target close reads it — otherwise every TP exit would understate its own
@@ -411,7 +446,7 @@ export class ExchangeSimulator extends EventEmitter {
         const toFill = [];
         const remaining = [];
         for (const order of this.state.openOrders) {
-            if (order.symbol === ticker.symbol && this.shouldFillLimit(order, ticker.last)) {
+            if (sameMarket(order.symbol, ticker.symbol) && this.shouldFillLimit(order, ticker.last)) {
                 toFill.push(order);
             }
             else {
@@ -449,7 +484,7 @@ export class ExchangeSimulator extends EventEmitter {
         }
     }
     getLastTicker(symbol) {
-        return this.lastTicker.get(symbol);
+        return this.lastTicker.get(tickerKey(symbol));
     }
     /**
      * Take-profit legs — the paper analog of the exchange-native
@@ -483,7 +518,7 @@ export class ExchangeSimulator extends EventEmitter {
         if (!Number.isFinite(price) || price <= 0)
             return;
         // Snapshot: closing mutates state.positions mid-iteration.
-        const candidates = this.state.positions.filter((p) => p.symbol === symbol);
+        const candidates = this.state.positions.filter((p) => sameMarket(p.symbol, symbol));
         for (const position of candidates) {
             const target = position.metadata?.targetPrice;
             if (target === undefined || !Number.isFinite(target) || target <= 0)
@@ -492,17 +527,20 @@ export class ExchangeSimulator extends EventEmitter {
             if (!breached)
                 continue;
             // Guard against a re-entrant tick firing a second close on the same
-            // symbol while the first is still settling.
-            if (this.takeProfitPending.has(symbol))
+            // symbol while the first is still settling. Keyed canonically so the
+            // guard still holds when the tick and the position disagree on suffix.
+            const pendingKey = tickerKey(position.symbol);
+            if (this.takeProfitPending.has(pendingKey))
                 continue;
-            this.takeProfitPending.add(symbol);
+            this.takeProfitPending.add(pendingKey);
             try {
-                logger.info(TAG, `TARGET REACHED: ${symbol} ${position.side} price=${price} target=${target} — closing (exchange_target)`);
+                logger.info(TAG, `TARGET REACHED: ${position.symbol} ${position.side} price=${price} target=${target} — closing (exchange_target)`);
                 // Target = decision price; the fill engine adds realistic adverse
-                // slippage on top (see the fill-convention note above).
-                const order = this.closePosition(symbol, 'exchange_target', target);
+                // slippage on top (see the fill-convention note above). Address the
+                // close with the POSITION's own symbol, never the ticker's form.
+                const order = this.closePosition(position.symbol, 'exchange_target', target);
                 this.emit('target_closed', {
-                    symbol,
+                    symbol: position.symbol,
                     side: position.side,
                     targetPrice: target,
                     markPrice: price,
@@ -514,10 +552,10 @@ export class ExchangeSimulator extends EventEmitter {
             catch (err) {
                 // Never let a failed protective close kill the tick loop — the next
                 // tick retries, and the position is still visible to the agent.
-                logger.error(TAG, `Target close failed for ${symbol}: ${formatError(err)}`);
+                logger.error(TAG, `Target close failed for ${position.symbol}: ${formatError(err)}`);
             }
             finally {
-                this.takeProfitPending.delete(symbol);
+                this.takeProfitPending.delete(pendingKey);
             }
         }
     }
@@ -530,7 +568,7 @@ export class ExchangeSimulator extends EventEmitter {
             return;
         let peakAdvanced = false;
         for (const p of this.state.positions) {
-            if (p.symbol !== symbol)
+            if (!sameMarket(p.symbol, symbol))
                 continue;
             const meta = { ...(p.metadata ?? {}) };
             const priorPeak = meta.mfePeakPrice;
@@ -602,7 +640,7 @@ export class ExchangeSimulator extends EventEmitter {
             const keptPeak = diskPeak === undefined
                 ? priorPeak
                 : (p.side === 'long' ? Math.max(priorPeak, diskPeak) : Math.min(priorPeak, diskPeak));
-            const mark = this.lastTicker.get(p.symbol)?.last ?? meta.originalEntryPrice ?? p.entryPrice;
+            const mark = this.lastTicker.get(tickerKey(p.symbol))?.last ?? meta.originalEntryPrice ?? p.entryPrice;
             const out = updateMfe({
                 side: p.side,
                 entryPrice: meta.originalEntryPrice ?? p.entryPrice,
@@ -671,7 +709,7 @@ export class ExchangeSimulator extends EventEmitter {
         const max = this.maxQuoteAgeMs();
         if (age <= max)
             return;
-        const pos = this.state.positions.find(p => p.symbol === symbol);
+        const pos = this.state.positions.find(p => sameMarket(p.symbol, symbol));
         // The order side reaching here is the one being filled — derive reduce vs
         // grow from the position side at the call site instead? The market path
         // calls this before fill with the order side unavailable; use position
@@ -696,8 +734,10 @@ export class ExchangeSimulator extends EventEmitter {
             : currentPrice >= order.price;
     }
     executeMarketFill(order, currentPrice, metadata) {
-        const position = this.state.positions.find(p => p.symbol === order.symbol) ?? null;
-        const orderbook = this.lastOrderBook.get(order.symbol) ?? null;
+        // Match canonically: a miss here would hand fillMarketOrder position=null,
+        // turning a CLOSE into a brand-new opposing position.
+        const position = this.state.positions.find(p => sameMarket(p.symbol, order.symbol)) ?? null;
+        const orderbook = this.lastOrderBook.get(tickerKey(order.symbol)) ?? null;
         const realistic = {
             orderbook,
             config: this.simulationConfig,
@@ -707,7 +747,7 @@ export class ExchangeSimulator extends EventEmitter {
         const result = fillMarketOrder(order, currentPrice, this.state.wallet, position, realistic);
         // Observability for issue #202: stamp the quote's age onto the fill's
         // execution-quality record so staleness is visible in trade history.
-        const tickerAtFill = this.lastTicker.get(order.symbol);
+        const tickerAtFill = this.lastTicker.get(tickerKey(order.symbol));
         if (result.executionQuality && tickerAtFill) {
             result.executionQuality.quoteAgeMs = this.quoteAgeMs(tickerAtFill);
         }
@@ -725,7 +765,7 @@ export class ExchangeSimulator extends EventEmitter {
         return ccxtOrder;
     }
     executeLimitFill(order, decisionPrice, metadata) {
-        const position = this.state.positions.find(p => p.symbol === order.symbol) ?? null;
+        const position = this.state.positions.find(p => sameMarket(p.symbol, order.symbol)) ?? null;
         const result = fillLimitOrder(order, this.state.wallet, position, this.simulationConfig, decisionPrice, metadata);
         const ccxtOrder = this.applyFillResult(result);
         const eq = result.executionQuality;
@@ -778,7 +818,9 @@ export class ExchangeSimulator extends EventEmitter {
         return ccxtOrder;
     }
     updatePosition(symbol, newPosition) {
-        const idx = this.state.positions.findIndex(p => p.symbol === symbol);
+        // Canonical match: an exact-compare miss here would append a DUPLICATE
+        // position row instead of replacing/removing the existing one.
+        const idx = this.state.positions.findIndex(p => sameMarket(p.symbol, symbol));
         if (newPosition) {
             if (idx >= 0) {
                 this.state.positions[idx] = newPosition;

package/tools/audit-bracket-protection.js

@@ -566,13 +566,16 @@ async function auditHlLive(adapter) {
         };
     }
     const entries = [];
-    for (const p of activePositions) {
-        let symbolOrders;
-        try {
-            symbolOrders = await adapter.getOpenOrders(p.symbol);
-        }
-        catch (err) {
-            const m = formatError(err);
+    // Fan the per-symbol open-orders reads out (HL has no batched read; the
+    // serial loop cost N round-trips per heartbeat), then walk the results in
+    // the ORIGINAL position order — the first failing symbol still produces
+    // the identical error return, and no verdict logic changes.
+    const orderFetches = await Promise.allSettled(activePositions.map((pos) => adapter.getOpenOrders(pos.symbol)));
+    for (let i = 0; i < activePositions.length; i++) {
+        const p = activePositions[i];
+        const fetched = orderFetches[i];
+        if (fetched.status === 'rejected') {
+            const m = formatError(fetched.reason);
             logger.warn(TAG, `HL audit skipped — open orders unavailable for ${p.symbol}: ${m}`);
             return {
                 error: `Exchange data unavailable for ${p.symbol} (Hyperliquid open-orders fetch failed). ` +
@@ -580,6 +583,7 @@ async function auditHlLive(adapter) {
                     `close_position(reason='bracket_integrity') on the basis of this call. Underlying: ${m}`,
             };
         }
+        const symbolOrders = fetched.value;
         const ledgerRow = ledger.getBySymbol(p.symbol) ?? null;
         const rowNonTerminalWithCids = !!ledgerRow && !isTerminalBracketState(ledgerRow.state) && Boolean(ledgerRow.slCid || ledgerRow.tpCid);
         if (symbolOrders.length === 0 && rowNonTerminalWithCids) {

package/tools/create-order.js

@@ -1,7 +1,7 @@
 // Tool: create_order — order execution with real price data + pre-trade risk gate
 // Readiness gate: BLOCKED unless adapter.readiness === 'READY'.
 import { createHash, randomUUID } from 'node:crypto';
-import { formatError } from '../logger.js';
+import { formatError, logger } from '../logger.js';
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
 import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
 import { validateCreateOrder, sanitizeRealizationRule, validateProtectiveGeometry } from './assessment-validation.js';
@@ -875,6 +875,7 @@ export async function createOrderTool(args, deps) {
     }
     // In paper mode, fetch latest ticker + order book for realistic fills
     let ticker = null;
+    let livePortfolioPromise;
     if (!deps.adapter.isLive) {
         const paperDeps = { binanceApi: deps.binanceApi, simulator: deps.adapter.getSimulator() };
         const [priceResult] = await Promise.all([
@@ -886,7 +887,14 @@ export async function createOrderTool(args, deps) {
         ticker = priceResult;
     }
     else {
-        // Live mode: fetch ticker for risk check reference price
+        // Live mode: the risk-gate portfolio snapshot (balance + positions) has
+        // no dependency on the ticker — start it here so the two exchange
+        // round-trips overlap; awaited at the risk check below. The catch-keeper
+        // only silences the unhandled rejection an early return would otherwise
+        // leave floating; the later await still surfaces the real error.
+        livePortfolioPromise = buildPortfolioSnapshotFromAdapter(deps.adapter);
+        livePortfolioPromise.catch(() => { });
+        // Fetch ticker for risk check reference price
         const lastPrice = await deps.adapter.getLastPrice(args.symbol);
         if (lastPrice != null) {
             ticker = {
@@ -1003,7 +1011,7 @@ export async function createOrderTool(args, deps) {
             consecutiveLosses = computeConsecutiveLosses(simulator.getState().tradeHistory);
         }
         else {
-            portfolio = await buildPortfolioSnapshotFromAdapter(deps.adapter);
+            portfolio = await (livePortfolioPromise ?? buildPortfolioSnapshotFromAdapter(deps.adapter));
             // In live mode, consecutive losses would come from intelligence DB — use 0 for now
         }
         // Bracket enforcement only applies in live mode when the feature is enabled.
@@ -1083,14 +1091,48 @@ export async function createOrderTool(args, deps) {
             typeof args.confluence_score === 'number');
         const proposalPathWired = !!(deps.proposalManager && deps.userId);
         const approvalMode = deps.approvalMode ?? 'off';
+        // per_trade + proposal path unwired: FAIL CLOSED.
+        //
+        // The operator asked for a human gate on every entry. If we can't deliver
+        // the proposal (no ingest token / no REEFCLAW_USER_ID), the honest failure
+        // is "no trade", not "trade without the gate". This branch previously fell
+        // through to the normal fire path so the agent was never trapped in an
+        // unfireable state — but that turned a misconfiguration into a live order
+        // the operator never approved, silently, with only a boot-time warning as
+        // the signal. A silent bypass of an explicitly-requested safety gate is the
+        // one outcome this feature exists to prevent (Locked Decision #2: never
+        // silent fire). Credentials drift for ordinary reasons — token rotation
+        // touches four files (docs/CLAUDE/token-rotation.md), and a freshly
+        // provisioned box can boot before they land — so this is a reachable state,
+        // not a theoretical one.
+        //
+        // Halting entries is the safe direction: exits, closes, stops and every
+        // operator emergency control are unaffected (they don't route through the
+        // approval branch), so a mis-wired box can still protect and unwind an open
+        // book — it just can't open new risk without the gate the operator asked
+        // for. Logged at ERROR on EVERY occurrence, not once at boot, so the signal
+        // is present at the time the trade is refused.
+        if (approvalMode === 'per_trade' && !proposalPathWired) {
+            logger.error('create-order', `approval.mode=per_trade but the proposal path is not wired — REFUSING to fire ` +
+                `${args.symbol} ${side} (fail-closed). Missing plugin connectionToken/WEBAPP_INGEST_TOKEN ` +
+                `and/or REEFCLAW_USER_ID. Restore the credentials, or set approval.mode=off to trade ` +
+                `autonomously again.`);
+            return {
+                error: 'Order refused: approval mode is per_trade but this box cannot deliver the proposal ' +
+                    'to the operator (missing connection token and/or REEFCLAW_USER_ID), so there is no ' +
+                    'way for the operator to approve it. Refusing to fire un-approved — this is fail-closed ' +
+                    'by design, not a transient error. Tell the operator: either restore the plugin ' +
+                    'connection credentials, or set approval.mode=off to resume autonomous trading. ' +
+                    'Do not retry until they confirm one of those. Closing positions, stops and brackets ' +
+                    'are unaffected.',
+            };
+        }
         // per_trade mode: propose and EARLY-RETURN. The agent's call doesn't fire;
         // the operator approves and ProposalDecisionListener fires via this same
         // tool with proposalManager omitted (which takes the real path below).
         //
-        // If proposalManager isn't wired (operator set approval.mode=per_trade in
-        // config but ingest creds aren't present), we fall through to the normal
-        // fire path — the startup warning is the operator's signal. We never trap
-        // the agent inside an unfireable per_trade branch.
+        // NOTE the listener's own fire passes NO approvalMode (defaults to 'off')
+        // and no proposalManager, so it never re-enters this branch.
         if (approvalMode === 'per_trade' && proposalPathWired) {
             if (!argsMetadataComplete) {
                 return {

package/tools/get-funding-context.js

@@ -12,5 +12,10 @@
 // FUNDING_OVERLAY flag is off or the symbol has < 100 30d samples.
 import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
 export async function getFundingContextTool(args, deps) {
-    return fetchIntelApi(`/api/funding/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+    // Server-side percentile context already has a 15-min TTL — 60s here just
+    // collapses same-heartbeat repeats.
+    return fetchIntelApi(`/api/funding/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps, {
+        cacheTtlMs: 60_000,
+        timeoutMs: 10_000,
+    });
 }

package/tools/get-liquidation-levels.js

@@ -3,5 +3,9 @@
 import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
 export async function getLiquidationLevelsTool(args, deps) {
     const hours = args.hours ?? 24;
-    return fetchIntelApi(`/api/liquidation-levels/${enc(resolveIntelSymbol(deps, args.symbol))}?hours=${hours}`, deps);
+    // Historical clusters move slowly — 30s TTL collapses per-position repeats.
+    return fetchIntelApi(`/api/liquidation-levels/${enc(resolveIntelSymbol(deps, args.symbol))}?hours=${hours}`, deps, {
+        cacheTtlMs: 30_000,
+        timeoutMs: 10_000,
+    });
 }

package/tools/get-liquidation-pulse.js

@@ -13,7 +13,13 @@ export async function getLiquidationPulseTool(args, deps) {
         params.set('symbol', resolveIntelSymbol(deps, args.symbol));
     const windowSeconds = clamp(args.window_seconds ?? 60, 5, 300);
     params.set('window_seconds', String(windowSeconds));
-    return fetchIntelApi(`/api/liquidation-pulse?${params.toString()}`, deps);
+    // 10s TTL: short enough that an active_cascade classification is never
+    // stale-read into the override decision (cascades persist 60-180s), long
+    // enough to collapse the per-position repeats within one heartbeat.
+    return fetchIntelApi(`/api/liquidation-pulse?${params.toString()}`, deps, {
+        cacheTtlMs: 10_000,
+        timeoutMs: 10_000,
+    });
 }
 function clamp(n, lo, hi) {
     if (!Number.isFinite(n))

package/tools/get-market-intel.js

@@ -12,6 +12,7 @@
 // unchanged. This bounds the threat — it can't make the agent place a naked
 // order (the create_order gate still applies) — and makes injected directives
 // far less likely to be followed.
+import { keepAliveFetch } from '../http/keepalive-fetch.js';
 /** Categories whose payloads contain attacker-influenceable free text. */
 const UNTRUSTED_TEXT_CATEGORIES = new Set(['news', 'social', 'calendar']);
 const MAX_TEXT_LEN = 2000;
@@ -88,7 +89,7 @@ export async function getMarketIntelTool(args, deps) {
         url.searchParams.set('symbols', symbols.join(','));
     }
     try {
-        const res = await fetch(url.toString(), {
+        const res = await keepAliveFetch(url.toString(), {
             headers: { Authorization: `Bearer ${connectionToken}` },
             signal: AbortSignal.timeout(10_000),
         });

package/tools/get-relevant-learnings.js

@@ -15,6 +15,13 @@
 import { logger, formatError } from '../logger.js';
 const TAG = 'get-relevant-learnings';
 const VALID_APPLIES_AT = new Set(['entry', 'heartbeat', 'close']);
+// Curated learnings change on operator-curation timescales, but the agent is
+// instructed to read them at several points per heartbeat — and a looping
+// model can spam identical calls (observed live 2026-08-04: ~230 identical
+// calls in one beat drove a 272k-token context overflow). A short TTL keyed
+// on the exact query bounds both.
+const CACHE_TTL_MS = 30_000;
+const cache = new Map();
 export async function getRelevantLearningsTool(args, deps) {
     if (!deps.decisionsClient || !deps.userId) {
         // Ingest not wired — return empty, callable. Same shape as
@@ -32,6 +39,11 @@ export async function getRelevantLearningsTool(args, deps) {
             error: "applies_at is required and must be one of: 'entry', 'heartbeat', 'close'.",
         };
     }
+    const cacheKey = `${deps.userId}:${args.applies_at}:${args.setup_type ?? ''}:${args.regime ?? ''}:${args.verdict ?? ''}`;
+    const hit = cache.get(cacheKey);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS) {
+        return structuredClone(hit.result);
+    }
     let response;
     try {
         response = await deps.decisionsClient.getRelevantLearnings(deps.userId, {
@@ -56,10 +68,17 @@ export async function getRelevantLearningsTool(args, deps) {
             note: 'Webapp /api/internal/learnings returned no result; proceeding without curated learnings.',
         };
     }
-    return {
+    const result = {
         ok: true,
         learnings: response.learnings,
         total_candidates: response.totalCandidates,
         returned_count: response.returnedCount,
     };
+    cache.set(cacheKey, { at: Date.now(), result });
+    if (cache.size > 64) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+    return structuredClone(result);
 }

package/tools/get-resting-liquidity.js

@@ -7,5 +7,10 @@
 // `microstructure.bandedLiquidity` flag is off (= columns are NULL).
 import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
 export async function getRestingLiquidityTool(args, deps) {
-    return fetchIntelApi(`/api/resting-liquidity/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+    // Cached: the microstructure assembler hits the same endpoint on the review
+    // path each heartbeat; advisory read, so a short TTL + tight timeout.
+    return fetchIntelApi(`/api/resting-liquidity/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps, {
+        cacheTtlMs: 15_000,
+        timeoutMs: 10_000,
+    });
 }

package/tools/get-wave9-status.js

@@ -695,6 +695,23 @@ export async function getWave9StatusTool(deps) {
             const reversalDue = position
                 ? (position.side === 'long' ? daily.exitLong : daily.exitShort)
                 : false;
+            // Quiet-row compaction: no candidate and no held position — the evidence
+            // numerics (returns / ATR / reference close) are ~740B per symbol the
+            // agent never acts on; × 8 symbols × every heartbeat this was ~68% of
+            // the whole status payload. Rows with entries or a position keep the
+            // full shape unchanged. Deliberately NOT gated on daily.exitLong/
+            // exitShort: those flags are set for most symbols on any
+            // negative-momentum day, and with no held position there is nothing to
+            // exit — the first shipped version kept them and saved nothing
+            // (verified live 2026-08-04: 72 currentReturn mentions per beat).
+            if (entries.length === 0 && !position) {
+                return {
+                    symbol,
+                    capDecision: { status: 'not_candidate', reason: 'no_completed_daily_zero_cross' },
+                    entries: [],
+                    reversal: { due: false, timing: 'not_due' },
+                };
+            }
             return {
                 symbol,
                 currentReturn: daily.currentReturn,

package/tools/hl-provision-agent-wallet.js

@@ -96,6 +96,24 @@ export async function hlProvisionAgentWalletTool(args, deps) {
         const derived = await deriveAddressFromPrivateKey(existingKey);
         if (derived.ok) {
             const masterMatches = existingMaster != null && existingMaster.toLowerCase() === walletAddress.toLowerCase();
+            // ★ Honour a CHANGED network on the resume path. The same keypair is
+            // valid on both Hyperliquid networks, so switching mainnet<->testnet
+            // must not require regenerating the wallet — but the stored flag has to
+            // follow, or the box boots against the network the operator did NOT
+            // pick. Before this, unticking "Use Hyperliquid testnet" after
+            // provisioning silently kept testnet:true, and the approval was signed
+            // for Testnet while the operator believed they were on mainnet
+            // (observed live 2026-08-03).
+            if (masterMatches && existingTestnet !== testnet) {
+                try {
+                    updatePluginConfig({ exchange: buildVenueExchangeConfig(existingExchange, 'hyperliquid', {}, testnet) }, deps.configPath);
+                    existingTestnet = testnet;
+                    logger.info(TAG, `network switched to ${testnet ? 'TESTNET' : 'MAINNET'} (same agent wallet)`);
+                }
+                catch (err) {
+                    logger.warn(TAG, `could not persist network change: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             return {
                 ok: true,
                 message: masterMatches

package/tools/hl-submit-agent-approval.d.ts

@@ -0,0 +1,27 @@
+export interface HlSubmitAgentApprovalArgs {
+    /** The approveAgent action, byte-identical to what the wallet signed. */
+    action?: Record<string, unknown>;
+    /** Outer nonce — for user-signed actions it must equal action.nonce. */
+    nonce?: number;
+    signature?: {
+        r?: unknown;
+        s?: unknown;
+        v?: unknown;
+    };
+    /** Tool-discovery probe — returns immediately, no config or network. */
+    probe?: boolean;
+}
+export interface HlSubmitAgentApprovalResult {
+    ok: boolean;
+    message: string;
+    /** Hyperliquid's own status string when it answered ('ok' | 'err'). */
+    hlStatus?: string;
+    /** Which network the SIGNED action targeted. */
+    chain?: 'Mainnet' | 'Testnet';
+    agentAddress?: string;
+}
+export interface HlSubmitAgentApprovalDeps {
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function hlSubmitAgentApprovalTool(args: HlSubmitAgentApprovalArgs, deps?: HlSubmitAgentApprovalDeps): Promise<HlSubmitAgentApprovalResult>;