@reefclaw/openclaw-plugin 0.1.12 → 0.1.13

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/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/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;
@@ -274,6 +290,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 +328,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

package/bridge/providers/gateway.js

@@ -11,7 +11,8 @@ import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
 import { discoverTools } from '../gateway/tool-discovery.js';
 import { EventParser, mapCcxtBalance, mapCcxtOrder, extractLiquidationFields, extractBracketField, extractPlannedLevels, } from '../gateway/event-parser.js';
 import { Poller } from '../gateway/poller.js';
-import { ensureHeartbeatCron } from '../gateway/heartbeat-cron.js';
+import { ensureHeartbeatCron, isHeartbeatLikeName } from '../gateway/heartbeat-cron.js';
+import { parseIdentityName } from '../utils/identity-name.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, } from './onboarding-commands.js';
@@ -130,6 +131,8 @@ function saveSessionStartNav(nav) {
 }
 // ---- Agent state emission interval ----
 const AGENT_STATE_INTERVAL_MS = 5_000;
+/** How often IDENTITY.md is re-read for the agent's display name (local file read). */
+const AGENT_NAME_TTL_MS = 60_000;
 // ---- GatewayProvider ----
 export class GatewayProvider {
     config;
@@ -154,12 +157,21 @@ export class GatewayProvider {
     agentIdentity = {};
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     loggedAgentIdentityProbe = false;
+    /** Last IDENTITY.md read (epoch ms) — TTL gate for the display-name re-read. */
+    agentNameReadAtMs = 0;
     /** One-shot latch for the boot-time heartbeat-cron ensure (re-armed on failure). */
     heartbeatCronEnsureStarted = false;
     /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
     heartbeatSeconds;
     heartbeatReadAtMs = 0;
     loggedHeartbeat = false;
+    /** 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). */
+    heartbeatHealth;
+    heartbeatHealthReadAtMs = 0;
+    heartbeatHealthRefreshing = false;
     lastTicker = null;
     positions = [];
     balance = { currency: 'USDT', total: 0, available: 0, locked: 0 };
@@ -230,6 +242,13 @@ export class GatewayProvider {
     // ---- Trade tracking ----
     /** Timestamp of the most recent trade (fill event) — used in buildAgentState */
     lastTradeTs = null;
+    /** 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. */
+    lastFillAt = 0;
     /** 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? } */
     openTradeEntries = new Map();
@@ -1152,6 +1171,10 @@ export class GatewayProvider {
                 // Track last trade timestamp for agent state
                 if (data.status === 'FILLED') {
                     this.lastTradeTs = data.timestamp ?? new Date().toISOString();
+                    // A fill debits the paper wallet immediately; `positions` catches up
+                    // on its own poll. Record when, so the RED-zone guard can tell a torn
+                    // wallet/positions snapshot from a real drawdown (issue #248).
+                    this.lastFillAt = Date.now();
                 }
             }
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1423,6 +1446,10 @@ export class GatewayProvider {
         };
         logger.info(TAG, `Synthetic fill: ${side} ${quantity} ${pos.symbol} @ ${fillPrice} (from position poll)`);
         this.lastTradeTs = now;
+        // Same reasoning as the orderUpdate path (issue #248) — this one is derived
+        // FROM a positions poll, so the snapshot already covers it and the guard
+        // clears on the next refresh rather than latching.
+        this.lastFillAt = Date.now();
         this.fire('orderUpdate', payload);
         // Track open entries for trade result reporting
         const tradeSide = pos.side === 'short' ? 'short' : 'long';
@@ -1799,6 +1826,70 @@ export class GatewayProvider {
             this.emitAgentState();
         }
     }
+    /**
+     * 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.
+     */
+    async refreshHeartbeatHealth() {
+        const ws = this.wsClient;
+        if (!ws)
+            return;
+        this.heartbeatHealthRefreshing = true;
+        try {
+            const resp = await ws.sendRpc('cron.list', { includeDisabled: true });
+            const jobs = resp?.jobs;
+            if (!Array.isArray(jobs))
+                return; // unknown shape — leave last-known
+            const hb = jobs.find((j) => isHeartbeatLikeName(j?.name));
+            const state = hb?.state;
+            if (!state || typeof state !== 'object')
+                return;
+            const s = state;
+            const next = {
+                consecutiveErrors: typeof s.consecutiveErrors === 'number' && s.consecutiveErrors >= 0 ? s.consecutiveErrors : 0,
+                lastRunAtMs: typeof s.lastRunAtMs === 'number' ? s.lastRunAtMs : undefined,
+                lastRunStatus: typeof s.lastRunStatus === 'string' ? s.lastRunStatus : undefined,
+            };
+            const prev = this.heartbeatHealth;
+            const changed = !prev ||
+                prev.consecutiveErrors !== next.consecutiveErrors ||
+                prev.lastRunAtMs !== next.lastRunAtMs ||
+                prev.lastRunStatus !== next.lastRunStatus;
+            this.heartbeatHealth = next;
+            this.heartbeatHealthReadAtMs = Date.now();
+            if (changed) {
+                if (next.consecutiveErrors > 0) {
+                    logger.warn(TAG, `Heartbeat health: ${next.consecutiveErrors} consecutive error(s), lastStatus=${next.lastRunStatus ?? 'unknown'}`);
+                }
+                this.emitAgentState();
+            }
+        }
+        catch {
+            /* cron.list unavailable (version/scope) — fail open, keep last-known */
+        }
+        finally {
+            this.heartbeatHealthRefreshing = false;
+        }
+    }
+    /** 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. */
+    maybeRefreshHeartbeatHealth() {
+        if (this.heartbeatHealthRefreshing)
+            return;
+        if (Date.now() - this.heartbeatHealthReadAtMs < 120_000)
+            return;
+        void this.refreshHeartbeatHealth();
+    }
     /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
     mergeAgentIdentity(found) {
         let changed = false;
@@ -1856,15 +1947,9 @@ export class GatewayProvider {
         ].filter((p) => !!p);
         for (const p of candidates) {
             try {
-                const txt = readFileSync(p, 'utf8');
-                const m = txt.match(/\*\*\s*Name\s*:?\s*\*\*\s*:?\s*(.+)/i);
-                let name = m?.[1]?.trim();
-                if (!name)
-                    continue;
-                name = name.replace(/^[_*`]+|[_*`]+$/g, '').trim(); // strip stray markdown emphasis
-                if (!name || /^\d+$/.test(name) || /\btbd\b|fill this in/i.test(name))
-                    continue;
-                return name;
+                const name = parseIdentityName(readFileSync(p, 'utf8'));
+                if (name)
+                    return name;
             }
             catch {
                 /* not found / unreadable — try the next candidate */
@@ -1872,6 +1957,31 @@ export class GatewayProvider {
         }
         return undefined;
     }
+    /**
+     * 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.
+     */
+    maybeRefreshAgentName() {
+        const now = Date.now();
+        if (now - this.agentNameReadAtMs < AGENT_NAME_TTL_MS)
+            return;
+        this.agentNameReadAtMs = now;
+        const name = this.resolveAgentNameFromIdentity();
+        // Fail-open: an unreadable/placeholder file keeps the last known good name.
+        if (name && this.mergeAgentIdentity({ name })) {
+            logger.info(TAG, `Agent identity updated: name=${name} (IDENTITY.md re-read)`);
+        }
+    }
     /**
      * Live heartbeat cadence in seconds — the agent's TRUE beat interval, read
      * from the OpenClaw cron store (`~/.openclaw/cron/jobs.json` → the enabled
@@ -1934,6 +2044,11 @@ export class GatewayProvider {
     }
     /** Build agent state from internal fields (used by both emitAgentState and getSnapshot). */
     buildAgentState() {
+        // Lazily keep the heartbeat-failure signal fresh (fire-and-forget, 120s).
+        this.maybeRefreshHeartbeatHealth();
+        // Lazily re-read IDENTITY.md (60s) so a name filled in after connect shows up.
+        this.maybeRefreshAgentName();
+        const hb = this.heartbeatHealth;
         return {
             mode: this.agentMode,
             strategy: this.lastKnownStrategy,
@@ -1948,6 +2063,18 @@ export class GatewayProvider {
                 errorRate: this.eventParser?.getErrorRate() ?? 0,
                 thinkingInterval: this.resolveHeartbeatSeconds() ?? 1800,
                 gatewayWs: this.wsClient?.getState() ?? 'disconnected',
+                // Conditional spread: absent until cron.list resolves the beat's state,
+                // so the payload stays byte-identical to the pre-feature shape when the
+                // gateway/version doesn't expose it.
+                ...(hb
+                    ? {
+                        heartbeatHealth: {
+                            consecutiveErrors: hb.consecutiveErrors,
+                            ...(hb.lastRunAtMs !== undefined ? { lastRunAtMs: hb.lastRunAtMs } : {}),
+                            ...(hb.lastRunStatus !== undefined ? { lastRunStatus: hb.lastRunStatus } : {}),
+                        },
+                    }
+                    : {}),
             },
         };
     }
@@ -1994,12 +2121,34 @@ export class GatewayProvider {
         const IMPOSSIBLE_DRAWDOWN = -0.5;
         const REQUIRED_RED_STREAK = 3;
         const MIN_RED_PERSISTENCE_MS = 25_000;
+        /** Ceiling on the issue #248 torn-snapshot deferral — see below. */
+        const MAX_TORN_SNAPSHOT_DEFER_MS = 5 * 60_000;
         if (metrics.drawdownZone === 'RED' && this.agentMode === 'ACTIVE') {
             if (this.redZoneStreak === 0)
                 this.redZoneSince = Date.now();
             this.redZoneStreak++;
             const redForMs = Date.now() - this.redZoneSince;
             const survivedPositionsRefresh = this.positionsUpdatedAt > this.redZoneSince;
+            // ★ issue #248: `survivedPositionsRefresh` proves a refresh HAPPENED, not
+            // that it INCORPORATED the fill that debited the wallet. When a fill has
+            // landed since the last positions refresh the snapshot is torn BY
+            // DEFINITION — paper deducts full notional at open, so equity is
+            // understated by exactly that notional and any entry >2.5% of NAV reads
+            // as RED. Measured on a live box: entries of 8.25% / 8.11% of NAV
+            // produced -8.09% / -7.93% verdicts 4s after each fill, on an account
+            // that was UP on the day. This condition can only ever WIDEN deferral —
+            // it never licenses a flatten the old code would have refused.
+            const positionsCoverLatestFill = this.lastFillAt === 0 || this.positionsUpdatedAt > this.lastFillAt;
+            // ...but BOUND that deferral. The tear resolves within one positions poll
+            // (~10s), so a RED verdict still standing after MAX_TORN_SNAPSHOT_DEFER_MS
+            // is not a snapshot artifact and must be honoured. Without a ceiling, a
+            // flapping synthetic-fill detector would keep `lastFillAt` ahead of every
+            // refresh and disarm the auto-flatten INDEFINITELY — and that detector is
+            // known to fabricate (it invented a duplicate fill 8s after a real one on
+            // 2026-07-25). Disarming a safety control on the word of an unreliable
+            // component is the worse failure direction, so the tear only ever BUYS
+            // TIME; past the ceiling the ordinary #213 debounce governs again.
+            const tornSnapshotBlocks = !positionsCoverLatestFill && redForMs < MAX_TORN_SNAPSHOT_DEFER_MS;
             if (uptimeMs < STARTUP_GRACE_PERIOD_MS) {
                 logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) but within startup grace period (${Math.round(uptimeMs / 1000)}s) — skipping auto-flatten`);
             }
@@ -2011,8 +2160,9 @@ export class GatewayProvider {
             }
             else if (this.redZoneStreak < REQUIRED_RED_STREAK ||
                 redForMs < MIN_RED_PERSISTENCE_MS ||
-                !survivedPositionsRefresh) {
-                logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) — deferring auto-flatten until the verdict persists (streak ${this.redZoneStreak}/${REQUIRED_RED_STREAK}, ${Math.round(redForMs / 1000)}s/${MIN_RED_PERSISTENCE_MS / 1000}s, survivedPositionsRefresh=${survivedPositionsRefresh}). A fresh entry's notional reads as phantom drawdown until the position snapshot catches up (issue #213); a real drawdown will persist and flatten on a later evaluation.`);
+                !survivedPositionsRefresh ||
+                tornSnapshotBlocks) {
+                logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) — deferring auto-flatten until the verdict persists (streak ${this.redZoneStreak}/${REQUIRED_RED_STREAK}, ${Math.round(redForMs / 1000)}s/${MIN_RED_PERSISTENCE_MS / 1000}s, survivedPositionsRefresh=${survivedPositionsRefresh}, positionsCoverLatestFill=${positionsCoverLatestFill}, tornSnapshotBlocks=${tornSnapshotBlocks}). A fresh entry's notional reads as phantom drawdown until the position snapshot catches up (issues #213/#248); a real drawdown will persist and flatten on a later evaluation.`);
             }
             else {
                 logger.warn(TAG, `RED zone drawdown detected (${metrics.drawdownZoneMessage}) — auto-flattening all positions`);

package/bridge/types.d.ts

@@ -54,6 +54,25 @@ export interface OrderData {
      * paper / legacy paths (treated as a working order → cancellable).
      */
     protective?: boolean;
+    /** Limit price. Undefined for market and trigger-only orders. */
+    price?: number;
+    /**
+     * Trigger price for a stop / take-profit order — Binance `stopPrice`,
+     * Hyperliquid `triggerPx`.
+     *
+     * ★ Without this the dashboard cannot see a resting protective leg AT ALL:
+     * `type` is collapsed to MARKET|LIMIT here, so a STOP_MARKET is
+     * indistinguishable from a market order on the wire. That is what left an HL
+     * micro-live book — every position bracketed on the exchange — drawing an
+     * entry line and nothing else, under a false "NO STOP" alarm.
+     */
+    stopPrice?: number;
+    /**
+     * Which protective leg this order IS, normalised at the venue boundary so no
+     * consumer has to parse venue type strings ('STOP_MARKET' on Binance,
+     * 'Stop Market' on Hyperliquid). Undefined for working entry orders.
+     */
+    protectiveRole?: 'stop' | 'target';
 }
 export interface FillData {
     id: string;
@@ -103,6 +122,17 @@ export interface AgentStateData {
             thinkingInterval: number;
             /** Gateway WebSocket state — helps diagnose chat delivery failures */
             gatewayWs?: string;
+            /** Heartbeat-cron health from `cron.list`. Absent on gateway versions
+             *  that don't expose cron state (byte-identical to pre-feature). Lets the
+             *  dashboard surface a failing/stale beat instead of a silent gap. */
+            heartbeatHealth?: {
+                /** Consecutive failed runs; >0 means the beat isn't delivering. */
+                consecutiveErrors: number;
+                /** Epoch ms of the last run start (any outcome). */
+                lastRunAtMs?: number;
+                /** Last run outcome, e.g. "ok" | "error". */
+                lastRunStatus?: string;
+            };
         };
     };
     timestamp: string;

package/bridge/utils/identity-name.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Parse the agent's display name out of an OpenClaw workspace `IDENTITY.md`.
+ *
+ * Extracted from GatewayProvider so the placeholder rules are unit-testable
+ * against the real template text — a placeholder that slips through is shown
+ * to the user AS the agent's name, which is exactly the bug this guards
+ * (2026-07-26: a dashboard header read `(pick something you like)` while the
+ * file said `Rook`). See docs/CLAUDE/agent-runtime.md §6.
+ */
+/**
+ * Extract `- **Name:** <X>` from IDENTITY.md markdown.
+ *
+ * Returns `undefined` when the file has no name, the value is an unfilled
+ * template placeholder, or it looks like an id rather than a name — callers
+ * fail open to their own UI placeholder.
+ *
+ * The value may sit on the line BELOW the label (the template's own layout):
+ *
+ *     - **Name:**
+ *       Rook
+ *
+ * which the `\s*` between `**` and the capture spans.
+ */
+export declare function parseIdentityName(markdown: string): string | undefined;

package/bridge/utils/identity-name.js

@@ -0,0 +1,54 @@
+/**
+ * Parse the agent's display name out of an OpenClaw workspace `IDENTITY.md`.
+ *
+ * Extracted from GatewayProvider so the placeholder rules are unit-testable
+ * against the real template text — a placeholder that slips through is shown
+ * to the user AS the agent's name, which is exactly the bug this guards
+ * (2026-07-26: a dashboard header read `(pick something you like)` while the
+ * file said `Rook`). See docs/CLAUDE/agent-runtime.md §6.
+ */
+/**
+ * Values the template ships (or a half-filled file leaves behind) that must
+ * never reach the UI. Matched AFTER markdown emphasis is stripped.
+ */
+const PLACEHOLDER_PATTERNS = [
+    /\btbd\b/i,
+    /fill this in/i,
+    // OpenClaw's own template values are parenthesised prompts, e.g.
+    //   _(pick something you like)_
+    //   _(AI? robot? familiar? ghost in the machine? something weirder?)_
+    //   _(your signature — pick one that feels right)_
+    // Any value that is ENTIRELY a bracketed aside is a prompt, not a name.
+    /^\(.*\)$/s,
+    /^\[.*\]$/s,
+    /^<.*>$/s,
+];
+/**
+ * Extract `- **Name:** <X>` from IDENTITY.md markdown.
+ *
+ * Returns `undefined` when the file has no name, the value is an unfilled
+ * template placeholder, or it looks like an id rather than a name — callers
+ * fail open to their own UI placeholder.
+ *
+ * The value may sit on the line BELOW the label (the template's own layout):
+ *
+ *     - **Name:**
+ *       Rook
+ *
+ * which the `\s*` between `**` and the capture spans.
+ */
+export function parseIdentityName(markdown) {
+    const m = markdown.match(/\*\*\s*Name\s*:?\s*\*\*\s*:?\s*(.+)/i);
+    let name = m?.[1]?.trim();
+    if (!name)
+        return undefined;
+    // Strip stray markdown emphasis (the template wraps placeholders in `_`).
+    name = name.replace(/^[_*`]+|[_*`]+$/g, '').trim();
+    if (!name)
+        return undefined;
+    if (/^\d+$/.test(name))
+        return undefined; // an id, not a name
+    if (PLACEHOLDER_PATTERNS.some((re) => re.test(name)))
+        return undefined;
+    return name;
+}

package/ccxt/binance-public.d.ts

@@ -18,8 +18,10 @@ export declare class BinancePublicApi implements PublicMarketDataApi {
     fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
     /** Probe Binance USD-M FUTURES reachability from this host — the readiness
      *  gate's core signal. Calls the futures-explicit implicit method so it hits
-     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
-     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  `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: