@reefclaw/openclaw-plugin 0.1.12 → 0.1.14

package/bridge/gateway/event-parser.d.ts

@@ -67,6 +67,25 @@ export declare function mapCcxtType(ccxtType: string): 'MARKET' | 'LIMIT';
  * real protective signals; a plain LIMIT/MARKET entry has none → false.
  */
 export declare function isProtectiveOrder(ccxt: CcxtOrder): boolean;
+/**
+ * The trigger price of a stop / take-profit order, wherever the venue put it.
+ *
+ * Verified against live payloads: Binance USD-M Futures uses unified
+ * `stopPrice` (raw `info.stopPrice`); Hyperliquid's `frontendOpenOrders` rows
+ * carry `info.triggerPx` alongside `isTrigger: true` and
+ * `orderType: 'Stop Market' | 'Take Profit Market'`, which ccxt surfaces as
+ * `triggerPrice`.
+ */
+export declare function extractTriggerPrice(ccxt: CcxtOrder): number | undefined;
+/**
+ * Which protective leg an order is, or undefined when it is a working order.
+ *
+ * Venue type strings differ ('STOP_MARKET' / 'TAKE_PROFIT_MARKET' on Binance,
+ * 'Stop Market' / 'Take Profit Market' on Hyperliquid), so normalise here and
+ * let every consumer read one enum. Take-profit is tested FIRST because
+ * 'TAKE_PROFIT_MARKET' must never fall into a substring test for 'STOP'.
+ */
+export declare function classifyProtectiveRole(ccxt: CcxtOrder): 'stop' | 'target' | undefined;
 export declare function mapCcxtOrder(ccxt: CcxtOrder): OrderData | null;
 /**
  * Build a FillData from a CCXT order (when the order has fills).

package/bridge/gateway/event-parser.js

@@ -52,6 +52,49 @@ export function isProtectiveOrder(ccxt) {
         return true;
     return false;
 }
+/** Positive finite number from a unified field or a raw string (venues send both). */
+function positiveNum(v) {
+    const n = typeof v === 'string' ? Number(v) : v;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/**
+ * The trigger price of a stop / take-profit order, wherever the venue put it.
+ *
+ * Verified against live payloads: Binance USD-M Futures uses unified
+ * `stopPrice` (raw `info.stopPrice`); Hyperliquid's `frontendOpenOrders` rows
+ * carry `info.triggerPx` alongside `isTrigger: true` and
+ * `orderType: 'Stop Market' | 'Take Profit Market'`, which ccxt surfaces as
+ * `triggerPrice`.
+ */
+export function extractTriggerPrice(ccxt) {
+    const o = ccxt;
+    return (positiveNum(o.stopPrice) ??
+        positiveNum(o.triggerPrice) ??
+        positiveNum(o.info?.stopPrice) ??
+        positiveNum(o.info?.triggerPx));
+}
+/**
+ * Which protective leg an order is, or undefined when it is a working order.
+ *
+ * Venue type strings differ ('STOP_MARKET' / 'TAKE_PROFIT_MARKET' on Binance,
+ * 'Stop Market' / 'Take Profit Market' on Hyperliquid), so normalise here and
+ * let every consumer read one enum. Take-profit is tested FIRST because
+ * 'TAKE_PROFIT_MARKET' must never fall into a substring test for 'STOP'.
+ */
+export function classifyProtectiveRole(ccxt) {
+    if (!isProtectiveOrder(ccxt))
+        return undefined;
+    const o = ccxt;
+    const rawType = String(o.info?.origType ?? o.info?.orderType ?? o.info?.type ?? o.type ?? '').toUpperCase();
+    if (rawType.includes('TAKE_PROFIT') || rawType.includes('TAKE PROFIT'))
+        return 'target';
+    if (rawType.includes('STOP'))
+        return 'stop';
+    // A resting reduce-only LIMIT with no trigger is a take-profit (split-TP legs).
+    if (String(o.type ?? '').toLowerCase() === 'limit')
+        return 'target';
+    return undefined;
+}
 export function mapCcxtOrder(ccxt) {
     if (!ccxt.id || typeof ccxt.id !== 'string') {
         logger.warn(TAG, `CCXT order missing valid ID: ${JSON.stringify(ccxt.id)}`);
@@ -68,6 +111,9 @@ export function mapCcxtOrder(ccxt) {
     const now = new Date().toISOString();
     const ts = ccxt.datetime ?? (ccxt.timestamp ? new Date(ccxt.timestamp).toISOString() : now);
     const protective = isProtectiveOrder(ccxt);
+    const price = positiveNum(ccxt.price);
+    const stopPrice = extractTriggerPrice(ccxt);
+    const protectiveRole = classifyProtectiveRole(ccxt);
     return {
         id: ccxt.id,
         symbol: ccxt.symbol,
@@ -81,6 +127,12 @@ export function mapCcxtOrder(ccxt) {
         createdAt: ts,
         updatedAt: ts,
         ...(protective && { protective: true }),
+        // Prices the dashboard draws its stop/target lines from. A resting leg is
+        // exchange truth and exists on every venue, so it is the source that
+        // survives a missing ledger row or a venue with no metadata map.
+        ...(price !== undefined && { price }),
+        ...(stopPrice !== undefined && { stopPrice }),
+        ...(protectiveRole && { protectiveRole }),
     };
 }
 /**

package/bridge/gateway/gateway-config.d.ts

@@ -1,3 +1,4 @@
+import { type VenueId } from '@reefclaw/shared';
 export interface GatewayConfig {
     /** Full gateway URL, e.g. "http://localhost:18789" */
     gatewayUrl: string;
@@ -5,10 +6,16 @@ export interface GatewayConfig {
     gatewayToken: string;
     /** Trading symbol, e.g. "BTC/USDT" */
     symbol: string;
-    /** Intelligence service URL (optional — regime classification) */
+    /** Intelligence service URL (regime classification + trade-result reporting) */
     intelligenceUrl?: string;
     /** Connection token for intelligence service auth */
     connectionToken?: string;
+    /** Trading venue this box is configured for. Decides how a canonical symbol
+     *  is spelled in the intel DB ('BTC/USDT' → 'BTCUSDT' vs 'BTC/USDC' →
+     *  'HL_BTC'), so every skill↔intel symbol crossing depends on it.
+     *  Optional so a hand-built config (tests, embedders) stays valid; every
+     *  consumer treats absent as 'binance', the historical behaviour. */
+    venue?: VenueId;
 }
 /** CLI args specific to gateway provider */
 export interface GatewayCliArgs {
@@ -20,17 +27,21 @@ export interface GatewayCliArgs {
 /**
  * Resolve gateway connection config with priority:
  * 1. CLI args (--gateway-url, --gateway-token, --symbol)
- * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
- * 3. OpenClaw config file (~/.openclaw/openclaw.json)
- * 4. Defaults (localhost:18789, BTC/USDT)
+ * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL,
+ *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE)
+ * 3. Config files (~/.openclaw/openclaw.json, ~/.reefclaw/plugin-config.json)
+ * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com)
  *
  * Returns null for gatewayToken if it can't be resolved (caller must handle).
+ * `intelligenceUrl` is never null — see DEFAULT_INTELLIGENCE_URL for why that
+ * matters.
  */
 export declare function resolveGatewayConfig(args: GatewayCliArgs): {
     gatewayUrl: string;
     gatewayToken: string | null;
     symbol: string;
-    intelligenceUrl: string | null;
+    intelligenceUrl: string;
+    venue: VenueId;
 };
 /**
  * Validate that the resolved config has all required fields.

package/bridge/gateway/gateway-config.js

@@ -5,11 +5,27 @@ import { readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import JSON5 from 'json5';
+import { parseVenue, VENUE_DEFAULT_SYMBOL } from '@reefclaw/shared';
 import { logger } from '../logger.js';
 const TAG = 'gateway-config';
 const DEFAULT_GATEWAY_PORT = 18789;
 const DEFAULT_GATEWAY_HOST = 'localhost';
-const DEFAULT_SYMBOL = 'BTC/USDT';
+/**
+ * Same default the plugin hardcodes (plugin/src/index.ts) so the two processes
+ * agree on the intel service without any operator configuration.
+ *
+ * ★ Before 2026-07-27 the skill had NO default and NO config-file fallback:
+ * `intelligenceUrl` came only from `--intelligence-url` or
+ * `REEFCLAW_INTELLIGENCE_URL`, and NOTHING in the repo ever set either one —
+ * not the installer, not a systemd unit, not a deploy script. The skill is the
+ * ONLY writer of intel's `trade_results` table, so on every default install
+ * every closed trade was dropped at debug level inside `reportTradeResult`.
+ * Downstream that meant `tradeCount` never reached `minTradesForKelly`, Kelly
+ * sizing was pinned at `cappedReason: 'insufficient_history'` forever, and
+ * `get_agent_profile` reported tier `novice` / 0 trades no matter how much the
+ * agent traded. Reads had a default; the write did not.
+ */
+const DEFAULT_INTELLIGENCE_URL = 'https://intel.reefclaw.com';
 // ---- Read OpenClaw config file ----
 function getConfigPath() {
     return process.env.OPENCLAW_CONFIG_PATH
@@ -28,18 +44,48 @@ function readOpenClawJson() {
         return null;
     }
 }
+// ---- Read the plugin's own config file ----
+function getPluginConfigPath() {
+    return process.env.REEFCLAW_PLUGIN_CONFIG_PATH
+        || join(homedir(), '.reefclaw', 'plugin-config.json');
+}
+/**
+ * Best-effort read of ~/.reefclaw/plugin-config.json — the file that already
+ * carries `intelligenceUrl` and `exchange.venue` for the plugin. Reading the
+ * same file here makes the two processes agree by construction rather than by
+ * convention (the skill previously had no way at all to learn either value).
+ * Fail-soft: null on a missing/unreadable/malformed file, which is the common
+ * case on a chat-install box that never writes this file.
+ */
+function readPluginConfig() {
+    const path = getPluginConfigPath();
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        logger.debug(TAG, `Could not read plugin config from ${path}`);
+        return null;
+    }
+}
 // ---- Resolve gateway config ----
 /**
  * Resolve gateway connection config with priority:
  * 1. CLI args (--gateway-url, --gateway-token, --symbol)
- * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
- * 3. OpenClaw config file (~/.openclaw/openclaw.json)
- * 4. Defaults (localhost:18789, BTC/USDT)
+ * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL,
+ *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE)
+ * 3. Config files (~/.openclaw/openclaw.json, ~/.reefclaw/plugin-config.json)
+ * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com)
  *
  * Returns null for gatewayToken if it can't be resolved (caller must handle).
+ * `intelligenceUrl` is never null — see DEFAULT_INTELLIGENCE_URL for why that
+ * matters.
  */
 export function resolveGatewayConfig(args) {
     const ocConfig = readOpenClawJson();
+    const pluginConfig = readPluginConfig();
     // --- Gateway URL ---
     // CLI > env > construct from openclaw.json port > default
     const port = ocConfig?.gateway?.port ?? DEFAULT_GATEWAY_PORT;
@@ -56,24 +102,34 @@ export function resolveGatewayConfig(args) {
     if (fileToken && !args.gatewayToken && !process.env.OPENCLAW_GATEWAY_TOKEN) {
         logger.info(TAG, 'Using gateway token from OpenClaw config');
     }
+    // --- Venue ---
+    // env > plugin-config.json exchange.venue > binance. Resolved BEFORE the
+    // symbol because it decides both the symbol default and the intel spelling.
+    // parseVenue surfaces a mis-spelled value instead of silently coercing it.
+    const { venue, unrecognized } = parseVenue(process.env.REEFCLAW_VENUE ?? pluginConfig?.exchange?.venue);
+    if (unrecognized) {
+        logger.warn(TAG, `Unrecognized venue '${unrecognized}' — falling back to binance`);
+    }
     // --- Symbol ---
-    // CLI > env > default
+    // CLI > env > the VENUE's default. A venue-blind 'BTC/USDT' default on a
+    // hyperliquid box is a symbol that venue rejects everywhere it's consumed
+    // (the issue-#174 class of bug).
     const symbol = args.symbol
         || process.env.REEFCLAW_SYMBOL
-        || DEFAULT_SYMBOL;
+        || VENUE_DEFAULT_SYMBOL[venue];
     if (!gatewayToken) {
         logger.warn(TAG, 'Gateway token not found in CLI args, env vars, or OpenClaw config');
     }
     // --- Intelligence URL ---
-    // CLI > env > default
+    // CLI > env > plugin-config.json > default. A default is mandatory: this URL
+    // gates the ONLY writer of intel's trade_results (see the constant).
     const intelligenceUrl = args.intelligenceUrl
         || process.env.REEFCLAW_INTELLIGENCE_URL
-        || null;
-    if (intelligenceUrl) {
-        logger.info(TAG, `Intelligence service: ${intelligenceUrl}`);
-    }
+        || pluginConfig?.intelligenceUrl
+        || DEFAULT_INTELLIGENCE_URL;
+    logger.info(TAG, `Intelligence service: ${intelligenceUrl} (venue=${venue})`);
     logger.debug(TAG, `Resolved: url=${gatewayUrl}, token=${gatewayToken ? '***' : '(none)'}, symbol=${symbol}`);
-    return { gatewayUrl, gatewayToken, symbol, intelligenceUrl };
+    return { gatewayUrl, gatewayToken, symbol, intelligenceUrl, venue };
 }
 /**
  * Validate that the resolved config has all required fields.

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

@@ -1,5 +1,6 @@
 export declare const HEARTBEAT_CRON_NAME = "reefclaw-heartbeat";
 export declare const HEARTBEAT_EVERY_MS: number;
+export declare const HEARTBEAT_TIMEOUT_SECONDS = 780;
 export declare const HEARTBEAT_MESSAGE: string;
 export interface CronRpcClient {
     sendRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;

package/bridge/gateway/heartbeat-cron.js

@@ -16,7 +16,18 @@
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { dirname } from 'path';
 export const HEARTBEAT_CRON_NAME = 'reefclaw-heartbeat';
+// 15m is the default. A disciplined beat (early-exit on no-trade + trading
+// tools only — see SKILL.md) finishes in a couple of minutes even on small
+// models, so 15m is comfortable; the 2026-07-24 timeouts were caused by the
+// agent's "coding" tool profile making it WANDER (a 9-min beat), not by the
+// cadence — the funnel + tool discipline are the fix, not a slower schedule.
+// Existing installs keep their cadence (once-per-install marker); operators
+// change it any time via `openclaw cron edit <id> --every <duration>`.
 export const HEARTBEAT_EVERY_MS = 15 * 60 * 1000;
+// Explicit per-run cap. The server does NOT default payload.timeoutSeconds
+// (verified empirically on 2026.7.1-2: a cron.add without it stores none) —
+// 780s is the field-proven value from the 2026-07-22 small-box mitigations.
+export const HEARTBEAT_TIMEOUT_SECONDS = 780;
 // 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. ' +
@@ -74,7 +85,17 @@ export async function ensureHeartbeatCron(opts) {
             schedule: { kind: 'every', everyMs: HEARTBEAT_EVERY_MS },
             sessionTarget: 'isolated',
             wakeMode: 'now',
-            payload: { kind: 'agentTurn', message: HEARTBEAT_MESSAGE },
+            // payload.timeoutSeconds is the stored shape (verified via the CLI's own
+            // cron.add on 2026.7.1-2). No toolsAllow: absent = all-tools-allowed,
+            // which is future-proof — an explicit allowlist freezes at creation and
+            // silently excludes every plugin tool shipped later. Beat tool
+            // discipline (no subagents/web/media during heartbeats) lives in
+            // SKILL.md, which updates on every bridge start.
+            payload: {
+                kind: 'agentTurn',
+                message: HEARTBEAT_MESSAGE,
+                timeoutSeconds: HEARTBEAT_TIMEOUT_SECONDS,
+            },
         };
         let delivery = 'announce';
         try {

package/bridge/gateway/poller.js

@@ -356,8 +356,14 @@ export class Poller {
         const tool = this.toolMap.fetch_positions;
         // Fetch ALL positions (no symbol filter) so multi-symbol trades are visible
         const result = await this.http.invoke(tool, {});
-        const positions = Array.isArray(result.data) ? result.data : [];
-        this.callbacks.onPositions(positions);
+        if (!Array.isArray(result.data)) {
+            // null ≠ empty: this cache is the emergency-Flatten fallback. Collapsing
+            // a garbage response to [] would let a later failed fresh read report
+            // "No positions to close" off poisoned data (audit 2026-07-26 F6).
+            logger.warn(TAG, `fetch_positions returned non-array (${typeof result.data}) — keeping last known positions`);
+            return;
+        }
+        this.callbacks.onPositions(result.data);
     }
     async pollBalance() {
         const tool = this.toolMap.fetch_balance;
@@ -370,13 +376,17 @@ export class Poller {
         // Fetch ALL open orders (no symbol filter) — this cache is the fallback
         // for the portfolio-wide Kill + reconcile snapshot (see interval comment).
         const result = await this.http.invoke(tool, {});
+        if (!Array.isArray(result.data)) {
+            // null ≠ empty: same reasoning as pollPositions — a garbage response
+            // must not overwrite the Kill fallback cache with a confirmed-empty [].
+            logger.warn(TAG, `fetch_open_orders returned non-array (${typeof result.data}) — keeping last known orders`);
+            return;
+        }
         const orders = [];
-        if (Array.isArray(result.data)) {
-            for (const ccxt of result.data) {
-                const mapped = mapCcxtOrder(ccxt);
-                if (mapped)
-                    orders.push(mapped);
-            }
+        for (const ccxt of result.data) {
+            const mapped = mapCcxtOrder(ccxt);
+            if (mapped)
+                orders.push(mapped);
         }
         this.callbacks.onOpenOrders(orders);
     }

package/bridge/providers/emergency-commands.d.ts

@@ -29,8 +29,16 @@ export interface EmergencyContext {
  *
  * Caller must set agentMode = 'STOPPED' after this returns, and should pass a
  * FRESH all-symbols order snapshot (see the gateway wrapper).
+ *
+ * ★ null ≠ empty (audit 2026-07-26 F6): `freshOrders === null` means the fresh
+ * fetch FAILED — order state is unknown. A stale (≤60s) cache that happens to
+ * be empty is NOT proof of zero working orders, and reporting executed:true
+ * from it is exactly the false-green the 2026-06-19 fix exists to prevent. On
+ * a failed fresh read Kill still halts the agent and best-effort cancels the
+ * cached-known working set, but ALWAYS reports executed:false with the
+ * unverified-coverage reason.
  */
-export declare function executeKill(ctx: EmergencyContext, openOrders: OrderData[]): Promise<EmergencyResult>;
+export declare function executeKill(ctx: EmergencyContext, freshOrders: OrderData[] | null, cachedOrders?: OrderData[]): Promise<EmergencyResult>;
 /**
  * Flatten: close all open positions at market.
  * Caller must set agentMode = 'STOPPED' after this returns.

package/bridge/providers/emergency-commands.js

@@ -30,11 +30,21 @@ function rejectionReasons(results, max = 3) {
  *
  * Caller must set agentMode = 'STOPPED' after this returns, and should pass a
  * FRESH all-symbols order snapshot (see the gateway wrapper).
+ *
+ * ★ null ≠ empty (audit 2026-07-26 F6): `freshOrders === null` means the fresh
+ * fetch FAILED — order state is unknown. A stale (≤60s) cache that happens to
+ * be empty is NOT proof of zero working orders, and reporting executed:true
+ * from it is exactly the false-green the 2026-06-19 fix exists to prevent. On
+ * a failed fresh read Kill still halts the agent and best-effort cancels the
+ * cached-known working set, but ALWAYS reports executed:false with the
+ * unverified-coverage reason.
  */
-export async function executeKill(ctx, openOrders) {
+export async function executeKill(ctx, freshOrders, cachedOrders = []) {
     if (!ctx.http) {
         return { action: 'kill', executed: false, timestamp: new Date().toISOString(), details: 'HTTP client not initialized' };
     }
+    const fresh = freshOrders !== null;
+    const openOrders = freshOrders ?? cachedOrders;
     // Protective = a stop/TP bracket (reduceOnly OR closePosition OR stop-type;
     // see mapCcxtOrder/isProtectiveOrder). Working = everything else (entries /
     // adds). Preserve protective so an open position is never left naked.
@@ -95,6 +105,15 @@ export async function executeKill(ctx, openOrders) {
             logger.warn(TAG, details);
         }
     }
+    if (!fresh) {
+        // Coverage is unverifiable: whatever the cached list said, orders placed
+        // in the last ≤60s are invisible to it. Never render a green "Killed".
+        executed = false;
+        details = working.length === 0
+            ? `Agent halted, but order state is UNVERIFIED — fresh order fetch failed and the cached snapshot shows no working orders; verify on the exchange${preservedNote}`
+            : `${details} — STALE snapshot (fresh order fetch failed); full coverage unverified`;
+        logger.error(TAG, details);
+    }
     return { action: 'kill', executed, timestamp: new Date().toISOString(), details };
 }
 /**
@@ -110,13 +129,19 @@ export async function executeFlatten(ctx, cachedPositions) {
     // ctx.symbol here narrowed the result to a single symbol, so positions on
     // every other symbol were silently skipped and never closed. The cached
     // fallback (this.positions) is already all-symbols.
+    // ★ null ≠ empty (audit 2026-07-26 F6): `fresh` records whether the list is
+    // exchange-confirmed. A stale cache that happens to be empty must NEVER
+    // produce a green "Flattened" — a position opened in the last ≤60s would be
+    // invisible to it and left running behind a STOPPED agent.
     let positions = cachedPositions;
+    let fresh = false;
     const fetchTool = ctx.toolMap.fetch_positions;
     if (fetchTool) {
         try {
             const result = await ctx.http.invokeEmergency(fetchTool, {});
             if (Array.isArray(result.data)) {
                 positions = result.data;
+                fresh = true;
             }
             else {
                 // Mirror gateway.ts fetchFreshPositions: a non-array response must
@@ -132,6 +157,11 @@ export async function executeFlatten(ctx, cachedPositions) {
     // Filter to non-zero positions
     const openPositions = positions.filter((p) => (p.contracts ?? 0) !== 0);
     if (openPositions.length === 0) {
+        if (!fresh) {
+            const details = 'Position state UNVERIFIED — fresh position fetch failed and the cached snapshot shows none; nothing was closed, verify on the exchange';
+            logger.error(TAG, details);
+            return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details };
+        }
         return { action: 'flatten', executed: true, timestamp: new Date().toISOString(), details: 'No positions to close' };
     }
     // Close each position
@@ -179,6 +209,13 @@ export async function executeFlatten(ctx, cachedPositions) {
         logger.error(TAG, details);
         return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details };
     }
+    if (!fresh) {
+        // Every cached-known position closed, but positions opened in the last
+        // ≤60s are invisible to a stale snapshot — coverage is unverifiable.
+        const details = `Closed ${succeeded}/${openPositions.length} positions from a STALE snapshot (fresh position fetch failed) — full coverage unverified, verify on the exchange`;
+        logger.error(TAG, details);
+        return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details };
+    }
     const details = `Closed ${succeeded}/${openPositions.length} positions`;
     return { action: 'flatten', executed: true, timestamp: new Date().toISOString(), details };
 }

package/bridge/providers/gateway.d.ts

@@ -40,12 +40,21 @@ export declare class GatewayProvider implements OpenClawProvider {
     private agentIdentity;
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     private loggedAgentIdentityProbe;
+    /** Last IDENTITY.md read (epoch ms) — TTL gate for the display-name re-read. */
+    private agentNameReadAtMs;
     /** 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;
     private loggedHeartbeat;
+    /** Heartbeat-job health read from `cron.list` (RPC — the filesystem jobs.json
+     *  is absent on 2026.7.x). Surfaced so the dashboard shows a failing/stale
+     *  beat instead of a silent gap (a beat failed 10× over ~2 days undetected,
+     *  2026-07-24). undefined until first resolved; refreshed lazily (120s). */
+    private heartbeatHealth?;
+    private heartbeatHealthReadAtMs;
+    private heartbeatHealthRefreshing;
     private lastTicker;
     private positions;
     private balance;
@@ -107,6 +116,13 @@ export declare class GatewayProvider implements OpenClawProvider {
     private currentRegime;
     /** Timestamp of the most recent trade (fill event) — used in buildAgentState */
     private lastTradeTs;
+    /** Epoch ms of the most recent LIVE fill observed this process (issue #248).
+     *  Deliberately separate from `lastTradeTs`: that one is a display string and
+     *  is also seeded from the historical trades ledger at startup, which must
+     *  NOT count here — this field exists solely to prove whether the current
+     *  `positions` snapshot predates a fill, and a historical seed would make an
+     *  untorn snapshot look torn forever. 0 = no fill seen yet this process. */
+    private lastFillAt;
     /** Tracks open position entries for computing trade results on close.
      *  Key: `symbol:side` (e.g. "BTC/USDT:long"), Value: { entryPrice, quantity, side, entryTime, missionId?, setupType?, regime?, confluenceScore? } */
     private openTradeEntries;
@@ -227,6 +243,20 @@ export declare class GatewayProvider implements OpenClawProvider {
      *  the WS store; under weight pressure isStoreTrusted() flickers between
      *  the two, so the raw symbol alternates poll-to-poll. */
     private canonicalSymbol;
+    /** Canonical symbol → the intel DB symbol for this box's venue.
+     *  binance: 'BTC/USDT' → 'BTCUSDT'; hyperliquid: 'BTC/USDC' → 'HL_BTC'.
+     *
+     *  ★ The old venue-blind `.replace('/','')` produced 'BTCUSDC' on a
+     *  hyperliquid box — a symbol no intel row has ever carried (intel
+     *  namespaces every HL row under the 'HL_' prefix). That silently broke the
+     *  regime/signal/mission/analytics pollers AND wrote every trade result to a
+     *  symbol Kelly sizing would never read back, so a hyperliquid box stayed at
+     *  `insufficient_history` even once the reporting path itself worked.
+     *
+     *  FAILS OPEN: an unmappable symbol falls back to the legacy concatenation
+     *  so intel answers "no data for <echo>" — honest and debuggable — rather
+     *  than the caller throwing and dropping the report entirely. */
+    private toIntelSymbol;
     private onPollerPositions;
     /**
      * Compare previous and current positions from polling.
@@ -263,6 +293,14 @@ export declare class GatewayProvider implements OpenClawProvider {
     private lastMarketStructure;
     private fetchFreshPositions;
     private fetchFreshBalance;
+    /** Strict fresh read — null on ANY failure (missing tool, thrown fetch,
+     *  non-array garbage). Callers whose verdict claims order-state coverage
+     *  (Kill) MUST distinguish "confirmed list" from "unknown"; collapsing a
+     *  failed read into the ≤60s cache here was how a stale-empty cache became
+     *  a green "No open orders to cancel" (audit 2026-07-26 F6). */
+    private fetchFreshOpenOrdersOrNull;
+    /** Cached-fallback wrapper for DISPLAY surfaces (the reconcile snapshot):
+     *  stale data beats a blank panel there. Never use for emergency verdicts. */
     private fetchFreshOpenOrders;
     private fetchAgentHealth;
     /**
@@ -274,6 +312,24 @@ export declare class GatewayProvider implements OpenClawProvider {
      * so the dashboard updates without waiting for the next periodic tick.
      */
     private refreshAgentIdentity;
+    /**
+     * Read the heartbeat cron job's health from `cron.list` (RPC — the
+     * filesystem `jobs.json` the cadence reader uses is absent on 2026.7.x).
+     * Extracts `state.consecutiveErrors` + last-run info from the heartbeat-like
+     * job and caches it. Best-effort, fail-open (a version/scope that hides
+     * cron.list simply leaves health undefined → the dashboard shows nothing new,
+     * byte-identical to before). Re-emits agent_state when the value changes so a
+     * newly-failing beat surfaces without waiting for the next tick.
+     *
+     * Why this matters: on 2026-07-24 a customer's beat failed 10× over ~2 days
+     * (bad delivery target, then a heap crash-loop) and NOTHING surfaced it —
+     * `consecutiveErrors` was sitting right here in the cron state the whole time.
+     */
+    private refreshHeartbeatHealth;
+    /** Kick a lazy heartbeat-health refresh when the cache is stale and no
+     *  refresh is in flight. Fire-and-forget: the RPC completion re-emits
+     *  agent_state, so callers stay synchronous. */
+    private maybeRefreshHeartbeatHealth;
     /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
     private mergeAgentIdentity;
     /**
@@ -294,6 +350,21 @@ export declare class GatewayProvider implements OpenClawProvider {
      * unfilled placeholder, or the value looks like an id rather than a name.
      */
     private resolveAgentNameFromIdentity;
+    /**
+     * Keep the display name fresh WITHOUT waiting for a reconnect.
+     *
+     * Naming the agent is a first-conversation ritual, so IDENTITY.md is usually
+     * written minutes-to-days AFTER the bridge connected. Resolving only on
+     * (re)connect meant the header served the unfilled template for the whole
+     * onboarding session (2026-07-26: rig showed `(pick something you like)` for
+     * ~24h after the agent wrote `Rook`). This is a small local file read, so a
+     * 60s TTL keeps it honest at negligible cost — unlike the model, which needs
+     * an RPC and legitimately only changes across a gateway restart.
+     *
+     * Called from buildAgentState(), so a newly-resolved name rides the payload
+     * being built right now — no extra emit needed.
+     */
+    private maybeRefreshAgentName;
     /**
      * Live heartbeat cadence in seconds — the agent's TRUE beat interval, read
      * from the OpenClaw cron store (`~/.openclaw/cron/jobs.json` → the enabled
@@ -338,7 +409,7 @@ export declare class GatewayProvider implements OpenClawProvider {
      * truthful-unknown beats confidently-wrong.
      */
     private seedLastTradeTs;
-    /** Symbol formatted for intelligence API (BTC/USDT → BTCUSDT). */
+    /** The configured symbol as the intel DB spells it. */
     private get intelligenceSymbol();
     /** Shared intelligence poller with circuit-breaker (exponential backoff on errors). */
     private startIntelligencePoller;