@reefclaw/openclaw-plugin 0.1.23 → 0.1.24

package/http/keepalive-fetch.js

@@ -0,0 +1,50 @@
+// Keep-alive HTTP for the plugin's intel/webapp clients.
+//
+// Node's built-in fetch closes idle sockets after undici's 4s default, and the
+// gap between two agent tool calls is LLM think-time (seconds to tens of
+// seconds) — so every intel/webapp call was paying a fresh TCP+TLS handshake
+// (~2 RTTs) before any server work started. A dedicated undici Agent with a
+// 60s idle timeout holds the connection across those gaps.
+//
+// undici loads via createRequire (same rule as CCXT — see
+// docs/CLAUDE/plugin-integration.md) and the whole module FAILS OPEN to the
+// global fetch: dist-only overlay deploys land on boxes whose node_modules
+// predate this dependency, and a missing package must degrade to today's
+// behaviour, never crash the connector.
+import { createRequire } from 'node:module';
+// Captured at module load. When someone REPLACES globalThis.fetch later
+// (vitest fetch mocks, tracing wrappers), keepAliveFetch honors the
+// replacement instead of undici — otherwise every fetch-stubbing test (and
+// any legitimate instrumentation) would be silently bypassed onto the real
+// network.
+const nativeFetch = globalThis.fetch;
+let cached;
+function build() {
+    try {
+        const req = createRequire(import.meta.url);
+        const undici = req('undici');
+        const dispatcher = new undici.Agent({
+            keepAliveTimeout: 60_000,
+            keepAliveMaxTimeout: 300_000,
+            connections: 16,
+        });
+        // undici's own fetch + Agent are used together: passing an npm-undici
+        // dispatcher to Node's built-in fetch can fail an instanceof check against
+        // the internal undici copy.
+        return (url, init) => undici.fetch(url, { ...init, dispatcher });
+    }
+    catch {
+        return (url, init) => fetch(url, init);
+    }
+}
+/** Drop-in fetch with connection keep-alive; falls back to global fetch when
+ *  undici is unavailable, and defers to globalThis.fetch whenever it has been
+ *  replaced (mocks/instrumentation). */
+export function keepAliveFetch(url, init) {
+    if (globalThis.fetch !== nativeFetch) {
+        return globalThis.fetch(url, init);
+    }
+    if (!cached)
+        cached = build();
+    return cached(url, init);
+}

package/index.js

@@ -989,7 +989,10 @@ const paperTradingPlugin = {
         // gateway process must reload it before serving HTTP API calls.
         const reloadState = () => {
             try {
-                const fresh = stateManager.loadSync();
+                // Skips the full read+parse (and replaceState) when the on-disk file
+                // hasn't changed since the last load — this runs on every paper-mode
+                // tool call and the file grows with trade history.
+                const fresh = stateManager.loadSyncIfChanged();
                 if (fresh) {
                     simulator.replaceState(fresh);
                 }
@@ -1293,11 +1296,32 @@ const paperTradingPlugin = {
         // rows while collecting real ones). See docs/APPROVAL_MODE_DESIGN.md §12.
         const approvalShadowEnabled = (process.env.APPROVAL_SHADOW_MODE ?? '').trim() === '1';
         const resolveApprovalMode = () => {
-            try {
-                if (readPluginConfig().approval?.mode === 'per_trade')
-                    return 'per_trade';
+            // Precedence (config-service slice 4, mirrors loadExitGateMode /
+            // loadPositionReviewMode):
+            //
+            //   central (agent_config.gates.approvalMode) → plugin-config.json →
+            //   APPROVAL_SHADOW_MODE env → 'off'
+            //
+            // Central is enum-validated plugin-side (agent-config-client
+            // validateGates) and can only ever say 'off' | 'per_trade' — it cannot
+            // enable shadow telemetry and cannot weaken the safety floor. Kill-switch
+            // RC_CENTRAL_GATES=off makes the store report null and the file rules
+            // again. Read per call, so a dashboard flip applies within one poll
+            // (~60 s) with no restart.
+            const central = gateStore.getApprovalMode();
+            if (central === 'per_trade')
+                return 'per_trade';
+            if (central !== 'off') {
+                // No central value — fall back to the local file.
+                try {
+                    if (readPluginConfig().approval?.mode === 'per_trade')
+                        return 'per_trade';
+                }
+                catch { /* config unreadable — env-only fallback below */ }
             }
-            catch { /* config unreadable — env-only fallback below */ }
+            // Central 'off' still permits local shadow telemetry: shadow does not
+            // change trading behaviour (the order fires either way), it only writes
+            // an extra row, and the env flag is the operator's own local choice.
             return approvalShadowEnabled ? 'shadow' : 'off';
         };
         // Proposal manager + listener credentials: built whenever ingest
@@ -1327,8 +1351,18 @@ const paperTradingPlugin = {
                     logger.info(TAG, `Approval wiring active (mode=${bootApprovalMode}) → ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
                 }
             }
+            else if (bootApprovalMode === 'per_trade') {
+                // FAIL-CLOSED state: create_order will REFUSE every new entry until the
+                // credentials are restored or approval.mode is set back to off. Loud at
+                // boot AND at each refusal (create-order.ts) — a boot-only signal is how
+                // this used to go unnoticed while orders fired without the gate.
+                logger.error(TAG, `approval mode=per_trade but ingest token / REEFCLAW_USER_ID missing — proposals CANNOT ` +
+                    `reach the operator, so create_order will REFUSE every new entry (fail-closed). ` +
+                    `Restore the plugin connectionToken/WEBAPP_INGEST_TOKEN + REEFCLAW_USER_ID, or set ` +
+                    `approval.mode=off. Exits, stops, brackets and operator controls are unaffected.`);
+            }
             else if (bootApprovalMode !== 'off') {
-                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — proposal path disabled (orders fire directly)`);
+                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — shadow telemetry disabled (orders fire directly, as in off mode)`);
             }
         }
         // ---- Create exchange adapter based on trading mode ----
@@ -1887,6 +1921,14 @@ const paperTradingPlugin = {
                     pollIntervalMs: approvalCfg?.pollIntervalMs ?? 3_000,
                 });
             },
+            // The approval path just went away (mode flipped off, or live→PAPER).
+            // Anything still pending is now un-fireable but still shows an Approve
+            // button — cancel it rather than leave the operator a dead control.
+            onApprovalPathDisabled: async () => {
+                if (!proposalManagerCtx)
+                    return;
+                await proposalManagerCtx.manager.cancelAll(proposalManagerCtx.userId, 'mode_disabled');
+            },
         });
         runtime.setOnAdapterSwapped((a) => { void approvalLifecycle.onAdapterSwapped(a); });
         // Boot application — the same path every later swap takes.

package/ingest/position-decisions-client.d.ts

@@ -322,6 +322,12 @@ export declare class PositionDecisionsClient {
     private fireAndForget;
     private run;
     private runReturning;
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    private static readonly READ_MAX_ATTEMPTS;
+    private static readonly READ_DEADLINE_MS;
     private runGetReturning;
     private sleepBackoff;
 }

package/ingest/position-decisions-client.js

@@ -12,6 +12,7 @@
 //   - postEntry/Review/Close are fire-and-forget (don't block the WS hot path).
 //
 // All four routes accept the same auth: Bearer + X-User-Id headers.
+import { keepAliveFetch } from '../http/keepalive-fetch.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'position-decisions-client';
 export class PositionDecisionsClient {
@@ -25,7 +26,7 @@ export class PositionDecisionsClient {
         this.opts = {
             baseUrl: options.baseUrl.replace(/\/+$/, ''),
             ingestToken: options.ingestToken,
-            fetchImpl: options.fetchImpl ?? fetch,
+            fetchImpl: options.fetchImpl ?? keepAliveFetch,
             requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
             maxAttempts: options.maxAttempts ?? 4,
             baseBackoffMs: options.baseBackoffMs ?? 250,
@@ -65,7 +66,12 @@ export class PositionDecisionsClient {
             qs.set('mode', mode);
         if (exchange)
             qs.set('exchange', exchange);
-        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`);
+        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`, {
+            // Reconcile-sweep read, NOT on the agent decision path — keep the
+            // write-grade retry budget: a null here skips a whole reconcile pass.
+            maxAttempts: this.opts.maxAttempts,
+            deadlineMs: Number.POSITIVE_INFINITY,
+        });
     }
     /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
      *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
@@ -246,12 +252,24 @@ export class PositionDecisionsClient {
         logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
         return null;
     }
-    async runGetReturning(userId, path) {
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    static READ_MAX_ATTEMPTS = 2;
+    static READ_DEADLINE_MS = 8_000;
+    async runGetReturning(userId, path, budget) {
         const url = `${this.opts.baseUrl}${path}`;
-        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+        const maxAttempts = budget?.maxAttempts ??
+            Math.min(this.opts.maxAttempts, PositionDecisionsClient.READ_MAX_ATTEMPTS);
+        const deadlineAt = Date.now() + (budget?.deadlineMs ?? PositionDecisionsClient.READ_DEADLINE_MS);
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const remainingMs = deadlineAt - Date.now();
+            if (remainingMs <= 0)
+                break;
             try {
                 const ac = new AbortController();
-                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                const tid = setTimeout(() => ac.abort(), Math.min(this.opts.requestTimeoutMs, remainingMs));
                 let res;
                 try {
                     res = await this.opts.fetchImpl(url, {
@@ -285,16 +303,16 @@ export class PositionDecisionsClient {
                     logger.warn(TAG, `GET ${url} → ${res.status} (terminal, dropped). userId=${userId} body=${errBody.slice(0, 200)}`);
                     return null;
                 }
-                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${maxAttempts}).`);
             }
             catch (err) {
-                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${maxAttempts}): ${formatError(err)}`);
             }
-            if (attempt < this.opts.maxAttempts) {
+            if (attempt < maxAttempts && Date.now() < deadlineAt) {
                 await this.sleepBackoff(attempt);
             }
         }
-        logger.error(TAG, `GET ${url} failed after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
+        logger.error(TAG, `GET ${url} failed after ${maxAttempts} attempt(s)/deadline. userId=${userId}.`);
         return null;
     }
     async sleepBackoff(attempt) {

package/live/approval-lifecycle.d.ts

@@ -14,6 +14,16 @@ export interface ApprovalLifecycleDeps {
     hasWiring: () => boolean;
     /** Build a listener bound to THIS adapter. Called only when starting. */
     buildListener: (adapter: IExchangeAdapter) => StartableListener;
+    /** Called when a RUNNING listener was torn down and no replacement started —
+     *  i.e. the approval path was deliberately disabled (mode flipped away from
+     *  per_trade, or the live adapter went away). Any proposal still pending is
+     *  now un-fireable but still approvable on the dashboard, so the caller
+     *  cancels them (design doc §10 row 12).
+     *
+     *  Deliberately NOT called from stop() — a shutdown drain is a restart, not a
+     *  disable, and cancelling the operator's live proposals on every plugin
+     *  restart would be both wrong and obnoxious. */
+    onApprovalPathDisabled?: () => void | Promise<void>;
 }
 export declare class ApprovalListenerLifecycle {
     private readonly deps;

package/live/approval-lifecycle.js

@@ -52,14 +52,28 @@ export class ApprovalListenerLifecycle {
         return this.chain;
     }
     async apply(adapter) {
+        // A listener was running before this swap? Then if we end up NOT starting a
+        // replacement, whatever is still pending has been orphaned.
+        const hadListener = this.listener !== undefined;
         // Always tear down the previous listener first — it is bound to the OLD
         // adapter and must never fire through it again.
         await this.stopCurrent();
+        const orphaned = async (why) => {
+            if (!hadListener || !this.deps.onApprovalPathDisabled)
+                return;
+            logger.info(TAG, `approval path disabled (${why}) — cancelling any pending proposals`);
+            try {
+                await this.deps.onApprovalPathDisabled();
+            }
+            catch (err) {
+                logger.warn(TAG, `pending-proposal cancel failed: ${formatError(err)}`);
+            }
+        };
         if (!adapter.isLive)
-            return;
+            return orphaned('adapter is no longer live');
         const mode = this.deps.resolveApprovalMode();
         if (mode !== 'per_trade')
-            return;
+            return orphaned(`approval.mode=${mode}`);
         if (!this.deps.hasWiring()) {
             logger.warn(TAG, "approval.mode='per_trade' but ingest credentials/proposal manager missing — listener NOT started; approvals will not fire");
             return;

package/live/microstructure-assembler.js

@@ -66,9 +66,18 @@ export class IntelMicrostructureAssembler {
             return cached.block;
         // Map canonical "BTC/USDT" → intel "BTCUSDT".
         const intelSymbol = canonical.replace('/', '');
+        // cacheTtlMs mirrors the agent-facing tools (get_resting_liquidity /
+        // get_liquidation_pulse) so the assembler and the agent's own calls share
+        // one round-trip per heartbeat instead of duplicate-fetching.
         const [restingResult, pulseResult] = await Promise.allSettled([
-            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps),
-            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps),
+            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps, {
+                cacheTtlMs: 15_000,
+                timeoutMs: 10_000,
+            }),
+            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps, {
+                cacheTtlMs: 10_000,
+                timeoutMs: 10_000,
+            }),
         ]);
         const block = { symbol: canonical, updatedAt: ts };
         let anySignal = false;

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

@@ -44,6 +44,9 @@ export interface ProposalDecisionListenerHealth {
     firesFailedTrading: number;
     patchFailures: number;
     pollFailures: number;
+    /** Distinct proposals seen holding a claim with no result — each one is an
+     *  operator-actionable reconciliation, not a retryable error. */
+    strandedObserved: number;
     lastTickAt: string | null;
 }
 export declare class ProposalDecisionListener {
@@ -56,6 +59,11 @@ export declare class ProposalDecisionListener {
      *  that finds ≥1 pending. */
     private currentIntervalMs;
     private health;
+    /** Stranded rows already reported by THIS process — the poll re-reports them
+     *  every tick (they never clear themselves), so dedupe the ERROR log. A
+     *  restart deliberately re-reports: if it's still stranded, it still needs
+     *  reconciling. */
+    private readonly strandedReported;
     /** Claim tokens are process-local by design. A new process must never steal
      *  an old process's durable claim, because it cannot know whether the
      *  exchange accepted an order just before the crash. */
@@ -82,6 +90,19 @@ export declare class ProposalDecisionListener {
     private scheduleNextTick;
     private runTick;
     private tick;
+    /** Report claims that outlived any plausible fire attempt.
+     *
+     *  These are proposals a listener (usually a previous incarnation of this
+     *  process) claimed and then died before reporting an outcome. Claims never
+     *  expire and the work queue skips claimed rows, so nothing retries them —
+     *  before this, the operator's approval simply produced no position and no
+     *  message. We can't safely re-fire (the order may already be live), so the
+     *  actionable thing is the deterministic client-order id: it answers "did
+     *  this ever reach the exchange?" definitively.
+     *
+     *  Logged at ERROR once per row per process so a restart re-surfaces it,
+     *  without spamming every 3 s tick. */
+    private reportStranded;
     private fetchPending;
     private claimPending;
     private forgetClaim;

package/live/proposal-decision-listener.js

@@ -51,8 +51,14 @@ export class ProposalDecisionListener {
         firesFailedTrading: 0,
         patchFailures: 0,
         pollFailures: 0,
+        strandedObserved: 0,
         lastTickAt: null,
     };
+    /** Stranded rows already reported by THIS process — the poll re-reports them
+     *  every tick (they never clear themselves), so dedupe the ERROR log. A
+     *  restart deliberately re-reports: if it's still stranded, it still needs
+     *  reconciling. */
+    strandedReported = new Set();
     /** Claim tokens are process-local by design. A new process must never steal
      *  an old process's durable claim, because it cannot know whether the
      *  exchange accepted an order just before the crash. */
@@ -171,6 +177,36 @@ export class ProposalDecisionListener {
             }
         }
     }
+    /** Report claims that outlived any plausible fire attempt.
+     *
+     *  These are proposals a listener (usually a previous incarnation of this
+     *  process) claimed and then died before reporting an outcome. Claims never
+     *  expire and the work queue skips claimed rows, so nothing retries them —
+     *  before this, the operator's approval simply produced no position and no
+     *  message. We can't safely re-fire (the order may already be live), so the
+     *  actionable thing is the deterministic client-order id: it answers "did
+     *  this ever reach the exchange?" definitively.
+     *
+     *  Logged at ERROR once per row per process so a restart re-surfaces it,
+     *  without spamming every 3 s tick. */
+    reportStranded(rows) {
+        for (const row of rows) {
+            if (this.strandedReported.has(row.id))
+                continue;
+            this.strandedReported.add(row.id);
+            this.health.strandedObserved++;
+            let cid = '(unavailable)';
+            try {
+                cid = proposalEntryClientOrderId(this.opts.adapter, row.proposalUuid);
+            }
+            catch { /* CID derivation is best-effort — the report still goes out */ }
+            logger.error(TAG, `STRANDED approved proposal ${row.id} (${row.symbol} ${row.side}) — claimed at ` +
+                `${row.claimedAt ?? 'unknown'} and never reported a result, so no listener will ` +
+                `retry it. The order may or may not have reached the exchange. Reconcile by ` +
+                `clientOrderId=${cid}: if present on the exchange the entry is live (attach/verify ` +
+                `its brackets); if absent, nothing was submitted and the proposal can be re-made.`);
+        }
+    }
     async fetchPending() {
         const url = `${this.opts.baseUrl}/api/internal/proposed_orders/pending-decisions`;
         try {
@@ -197,6 +233,9 @@ export class ProposalDecisionListener {
                 return [];
             }
             const body = await res.json();
+            if (Array.isArray(body.stranded) && body.stranded.length > 0) {
+                this.reportStranded(body.stranded);
+            }
             return Array.isArray(body.proposals) ? body.proposals : [];
         }
         catch (err) {

package/live/proposal-manager.d.ts

@@ -68,6 +68,18 @@ export declare class ProposalManager {
      *  + hard expiry synchronously; the actual POST runs in the background.
      *  Caller may correlate via the returned proposalUuid before the post lands. */
     propose(userId: string, req: ProposalRequest): ProposeResult;
+    /** Cancel every outstanding proposal for this tenant because the approval
+     *  path is being disabled (mode flipped off, or the live adapter went away).
+     *
+     *  Without this, flipping `per_trade` → `off` — or a live→PAPER swap — leaves
+     *  rows the operator can still see and approve while no listener exists to
+     *  fire them: the card sits there, Approve "works", and nothing ever happens
+     *  (design doc §10 row 12). The webapp refuses to cancel rows a listener has
+     *  already claimed, so this can never disown an order that may be live.
+     *
+     *  Best-effort by design: awaited by the caller only for logging. A failure
+     *  is bounded by hard expiry (≤4 min) and must never block an adapter swap. */
+    cancelAll(userId: string, reason: 'mode_disabled'): Promise<void>;
     /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
     drain(): Promise<void>;
     getHealth(): ProposalManagerHealth;

package/live/proposal-manager.js

@@ -50,6 +50,53 @@ export class ProposalManager {
         this.inFlight.add(promise);
         return { proposalUuid, setupBucket, hardExpiresAt };
     }
+    /** Cancel every outstanding proposal for this tenant because the approval
+     *  path is being disabled (mode flipped off, or the live adapter went away).
+     *
+     *  Without this, flipping `per_trade` → `off` — or a live→PAPER swap — leaves
+     *  rows the operator can still see and approve while no listener exists to
+     *  fire them: the card sits there, Approve "works", and nothing ever happens
+     *  (design doc §10 row 12). The webapp refuses to cancel rows a listener has
+     *  already claimed, so this can never disown an order that may be live.
+     *
+     *  Best-effort by design: awaited by the caller only for logging. A failure
+     *  is bounded by hard expiry (≤4 min) and must never block an adapter swap. */
+    async cancelAll(userId, reason) {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders/cancel-all`;
+        try {
+            const ac = new AbortController();
+            const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+            let res;
+            try {
+                res = await this.opts.fetchImpl(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.opts.ingestToken}`,
+                        'x-user-id': userId,
+                    },
+                    body: JSON.stringify({ reason }),
+                    signal: ac.signal,
+                });
+            }
+            finally {
+                clearTimeout(tid);
+            }
+            if (res.status < 200 || res.status >= 300) {
+                logger.warn(TAG, `cancel-all (${reason}) returned HTTP ${res.status}`);
+                return;
+            }
+            const body = (await res.json().catch(() => ({})));
+            const cancelled = typeof body.cancelled === 'number' ? body.cancelled : 0;
+            const inFlight = Array.isArray(body.inFlight) ? body.inFlight.length : 0;
+            if (cancelled > 0 || inFlight > 0) {
+                logger.info(TAG, `cancel-all (${reason}): cancelled=${cancelled} inFlight-uncancellable=${inFlight}`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `cancel-all (${reason}) failed: ${formatError(err)}`);
+        }
+    }
     /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
     async drain() {
         if (this.inFlight.size === 0)

package/live/stop-watcher.d.ts

@@ -37,8 +37,20 @@ export interface Wave9StopCloseLifecycle {
     resolveCandidateId(position: CcxtPosition): Promise<string | undefined> | string | undefined;
     settleAfterClose(candidateId: string, symbol: string): Promise<Wave9StopCloseOutcome>;
 }
+/** True when this position carries a protective stop we are supposed to be
+ *  enforcing. Used to decide whether an unusable mark is an ALARM (a stop we
+ *  cannot evaluate) or simply uninteresting (no stop set). */
+export declare function hasEnforceableStop(position: CcxtPosition): boolean;
+/** True when the mark cannot be trusted for a protective decision — either the
+ *  venue gave us nothing usable, or (paper) it is the fabricated entryPrice
+ *  fallback. Both mean "we do not know where price is", NOT "price is fine". */
+export declare function isMarkUnusable(position: CcxtPosition): boolean;
 /** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
+ *  Exported for direct unit-testing without spinning up a watcher loop.
+ *
+ *  NOTE: a `false` here means "not breached OR not knowable". Callers that care
+ *  about the difference must check isMarkUnusable() — see tick(), which alarms
+ *  on an unknowable mark rather than treating it as safe. */
 export declare function isStopBreached(position: CcxtPosition): boolean;
 export declare class PositionWatcher extends EventEmitter {
     private interval;
@@ -53,6 +65,9 @@ export declare class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     private notifiedBreach;
+    /** Symbols already alarmed for an unusable mark, so the ERROR fires once per
+     *  episode rather than every tick. Cleared as soon as a usable mark returns. */
+    private notifiedUnusableMark;
     constructor(adapter: IExchangeAdapter, intervalMs?: number, operationLock?: TradingOperationLock);
     /** Configure this after the durable execution ledger is ready. Runtime
      *  lifecycle hooks reapply it to every watcher after reconnect. */

package/live/stop-watcher.js

@@ -28,18 +28,35 @@ const TAG = 'stop-watcher';
 // revert with zero deploy via plugin-config.json `stopWatcher.intervalMs`.
 // See docs/EFFICIENCY_QUICK_WINS_PLAN.md + the Binance ban-gate context.
 export const DEFAULT_INTERVAL_MS = 10_000;
+/** True when this position carries a protective stop we are supposed to be
+ *  enforcing. Used to decide whether an unusable mark is an ALARM (a stop we
+ *  cannot evaluate) or simply uninteresting (no stop set). */
+export function hasEnforceableStop(position) {
+    const stop = position.stopPrice;
+    return stop !== undefined && stop !== null && Number.isFinite(stop) && stop > 0;
+}
+/** True when the mark cannot be trusted for a protective decision — either the
+ *  venue gave us nothing usable, or (paper) it is the fabricated entryPrice
+ *  fallback. Both mean "we do not know where price is", NOT "price is fine". */
+export function isMarkUnusable(position) {
+    if (position.markPriceStale === true)
+        return true;
+    const mark = position.markPrice;
+    return !Number.isFinite(mark) || mark <= 0;
+}
 /** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
+ *  Exported for direct unit-testing without spinning up a watcher loop.
+ *
+ *  NOTE: a `false` here means "not breached OR not knowable". Callers that care
+ *  about the difference must check isMarkUnusable() — see tick(), which alarms
+ *  on an unknowable mark rather than treating it as safe. */
 export function isStopBreached(position) {
-    const stop = position.stopPrice;
-    if (stop === undefined || stop === null || !Number.isFinite(stop) || stop <= 0) {
+    if (!hasEnforceableStop(position))
         return false;
-    }
-    const mark = position.markPrice;
-    if (!Number.isFinite(mark) || mark <= 0) {
+    if (isMarkUnusable(position))
         return false;
-    }
-    return position.side === 'long' ? mark <= stop : mark >= stop;
+    const stop = position.stopPrice;
+    return position.side === 'long' ? position.markPrice <= stop : position.markPrice >= stop;
 }
 export class PositionWatcher extends EventEmitter {
     interval = null;
@@ -54,6 +71,9 @@ export class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     notifiedBreach = new Set();
+    /** Symbols already alarmed for an unusable mark, so the ERROR fires once per
+     *  episode rather than every tick. Cleared as soon as a usable mark returns. */
+    notifiedUnusableMark = new Set();
     constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS, operationLock) {
         super();
         this.adapter = adapter;
@@ -82,6 +102,7 @@ export class PositionWatcher extends EventEmitter {
         }
         this.closePending.clear();
         this.notifiedBreach.clear();
+        this.notifiedUnusableMark.clear();
         logger.info(TAG, 'Stopped');
     }
     /** Run one check cycle. Exposed for tests (skip setInterval). */
@@ -115,7 +136,26 @@ export class PositionWatcher extends EventEmitter {
             if (!openSymbols.has(sym))
                 this.closePending.delete(sym);
         }
+        for (const sym of this.notifiedUnusableMark) {
+            if (!openSymbols.has(sym))
+                this.notifiedUnusableMark.delete(sym);
+        }
         for (const position of positions) {
+            // A position with a stop we CANNOT evaluate is unprotected, not healthy.
+            // Silence here is what let a breached stop run for 35h: the mark was a
+            // fabricated entryPrice fallback, isStopBreached read false, and the
+            // watcher skipped it every tick without ever saying so. Alarm instead.
+            if (hasEnforceableStop(position) && isMarkUnusable(position)) {
+                if (!this.notifiedUnusableMark.has(position.symbol)) {
+                    logger.error(TAG, `STOP UNENFORCEABLE: ${position.symbol} ${position.side} has stop=${position.stopPrice} ` +
+                        `but no usable mark (markPrice=${position.markPrice}` +
+                        `${position.markPriceStale ? ', stale/fabricated' : ''}). The position is running ` +
+                        'UNPROTECTED — the watcher cannot evaluate the breach. Check the quote feed for this symbol.');
+                    this.notifiedUnusableMark.add(position.symbol);
+                }
+                continue;
+            }
+            this.notifiedUnusableMark.delete(position.symbol);
             if (!isStopBreached(position))
                 continue;
             if (this.closePending.has(position.symbol))

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {