@reefclaw/openclaw-plugin 0.1.0

package/tools/audit-bracket-protection.js

@@ -0,0 +1,527 @@
+// Tool: audit_bracket_protection — returns every open live position with a
+// verdict on whether exchange-side SL / TP protection is currently attached.
+// Agent runs this at SESSION START and every heartbeat; any position with
+// `has_stop=false` or `has_target=false` must be resolved (attach_brackets
+// with new levels, or close_position).
+//
+// Cross-references three sources of truth to catch every failure mode:
+//   1. Live positions (adapter.getPositions)
+//   2. Open orders on the exchange (adapter.getOpenOrders) — ground truth
+//      for SL/TP orders currently live
+//   3. Bracket ledger (for state + stored price levels)
+//
+// Order checks are by clientOrderId prefix AND by symbol + type, so we catch
+// both (a) bracket orders with reefclaw-managed cids and (b) manually-placed
+// STOP_MARKET / TAKE_PROFIT_MARKET orders from the Binance UI that happen to
+// protect the position. Either is good enough for "position is protected".
+import { parseBracketCid } from '../live/bracket-id.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+import { formatError, logger } from '../logger.js';
+const TAG = 'audit-bracket-protection';
+// Per-symbol verdict history for flicker detection. When audit verdicts
+// transition protected→unprotected→protected repeatedly inside a short
+// window, the bracket subsystem itself is unreliable — protection on the
+// exchange isn't changing, our reading of it is. That's the signature of
+// the 2026-05-15 spiral (ATOM/LINK/NEAR all flushed via bracket_integrity
+// while their brackets were really still live). Emitting a structured warn
+// when we see it surfaces the bug to the operator BEFORE the agent
+// escalates to close_position.
+const FLICKER_WINDOW_MS = 5 * 60 * 1000;
+const FLICKER_THRESHOLD = 3; // 3 verdict flips in the window → warn
+// Retention bumped to 60 min so close_position can copy the last hour of
+// audit verdicts into position_closes.close_assessment.metadata.bracket_health_history
+// for post-mortem analysis on the dashboard's Position Timeline drawer.
+// 120 samples × ~120 bytes = ~15KB worst-case per symbol; trivial.
+const HISTORY_RETENTION_MS = 60 * 60 * 1000;
+const HISTORY_MAX_PER_SYMBOL = 120;
+const verdictHistory = new Map();
+let lastFlickerWarnedAt = new Map();
+const FLICKER_WARN_COOLDOWN_MS = 60 * 1000; // don't repeat the warn more than once a minute per symbol
+export async function auditBracketProtectionTool(_args, deps) {
+    try {
+        const isLive = deps.adapter.isLive;
+        // Paper mode: stop protection lives in position metadata + stop-watcher,
+        // not exchange orders. Report positions with their metadata for
+        // completeness, but mark them all protected (the stop-watcher model is
+        // the contract in paper).
+        if (!isLive) {
+            const positions = await deps.adapter.getPositions();
+            const entries = positions
+                .filter(p => p.contracts > 0)
+                .map(p => ({
+                symbol: p.symbol,
+                side: p.side,
+                contracts: p.contracts,
+                entry_price: p.entryPrice,
+                mark_price: p.markPrice,
+                has_stop: p.stopPrice !== undefined,
+                has_target: p.targetPrice !== undefined,
+                stop_price: p.stopPrice,
+                target_price: p.targetPrice,
+                ledger_state: 'no_ledger_row',
+                reason: p.stopPrice !== undefined ? 'manual_order_protecting' : 'no_protective_order',
+                recommended_action: p.stopPrice !== undefined ? 'none' : 'close_position',
+            }));
+            const unprotected = entries.filter(e => !e.has_stop).length;
+            return {
+                ok: true,
+                mode: 'paper',
+                brackets_enabled: false,
+                total_positions: entries.length,
+                protected_count: entries.length - unprotected,
+                unprotected_count: unprotected,
+                positions: entries,
+            };
+        }
+        // Live mode.
+        const live = deps.adapter;
+        const ledger = live.getBracketLedger?.() ?? null;
+        const bracketsEnabled = ledger !== null;
+        // Fetch positions + open orders. If `getOpenOrders` throws (it does so
+        // on null = fetch failure / 429 — see live-adapter.ts), we return a
+        // clear error instead of falling through with an empty list. The old
+        // behaviour was: null collapsed to []; audit said has_stop=false;
+        // agent ran attach_brackets; cancelSymbolBracketOrders no-op'd; new
+        // brackets piled up on top of orders Binance hadn't surfaced through
+        // the 429'd fetch. 2026-05-14 ATOM ran ~17 spurious re-attach cycles
+        // before the operator noticed. With this gate, a single 429 just
+        // delays the audit one heartbeat — far safer than fabricating
+        // "unprotected" verdicts.
+        // Weight discipline (2026-05-15, measured): the unscoped getOpenOrders
+        // sweep is 80 weight (40 regular + 40 algo). Pre-fix this ran on EVERY
+        // audit invocation — including when flat — and the agent's SKILL.md
+        // recovery loop (audit→attach) re-runs it every ~3s, so prod measured
+        // ~560-640 weight/min from this ONE call, ~40% of the pacer ceiling,
+        // which starved every other read and blinded the agent. Two cuts that
+        // do NOT change the audit verdict:
+        //   1. `openOrders` is consumed ONLY inside `activePositions.map(...)`,
+        //      so when there are no active positions it is provably unused —
+        //      skip the call entirely (return the trivial 0-position verdict).
+        //   2. When positions exist, fetch open orders SCOPED to those symbols
+        //      (1 regular + 1 algo = 2 weight each) instead of one 80-weight
+        //      unscoped sweep. Audit only ever inspects orders for symbols that
+        //      have a position; cross-symbol orphan detection is the bracket
+        //      reconciler's job (it keeps its 60s unscoped sweep — the
+        //      authoritative orphan/naked backstop, unchanged).
+        // The null-vs-empty {error} contract is preserved for the calls that
+        // matter (verifying real open positions have stops). When flat, the
+        // reconciler + user-data WS + ALGO_UPDATE remain the safety net.
+        let positions, openOrders;
+        try {
+            // null = positions fetch FAILED (429 / weight-paced / transient).
+            // getPositions() would collapse that to [] → activeSymbols=[] → this
+            // audit returns a trivial "0 positions, all protected" verdict during
+            // a rate-limit storm, masking a real naked position for a heartbeat.
+            // Treat it identically to the getOpenOrders-null case below: surface
+            // {error} so the agent skips this cycle and MUST NOT run attach_brackets
+            // (see CLAUDE.md audit-vs-action contract).
+            const positionsOrNull = await deps.adapter.getPositionsOrNull();
+            if (positionsOrNull === null) {
+                throw new Error('positions fetch returned null (exchange data unavailable)');
+            }
+            positions = positionsOrNull;
+            const activeSymbols = [
+                ...new Set(positions.filter(p => p.contracts > 0).map(p => p.symbol)),
+            ];
+            if (activeSymbols.length === 0) {
+                openOrders = [];
+            }
+            else {
+                const perSymbol = await Promise.all(activeSymbols.map(s => deps.adapter.getOpenOrders(s)));
+                openOrders = perSymbol.flat();
+            }
+        }
+        catch (err) {
+            const msg = formatError(err);
+            logger.warn(TAG, `audit skipped — exchange data unavailable: ${msg}`);
+            return {
+                error: `Exchange data unavailable (likely Binance 429 or transient network). ` +
+                    `Skipping audit this cycle — current bracket state on Binance is unchanged. ` +
+                    `Retry on next heartbeat. Underlying: ${msg}`,
+            };
+        }
+        const activePositions = positions.filter(p => p.contracts > 0);
+        // Group open orders by NORMALIZED symbol so position.symbol (may be
+        // `:USDT`-suffixed from CCXT fetchPositions) and order.symbol (same
+        // source but historically inconsistent across CCXT versions) always
+        // collide on the same key. Without this, a suffixed position would miss
+        // an un-suffixed order's brackets and audit would return has_stop=false
+        // despite the exchange-side stop being live.
+        const ordersBySymbol = new Map();
+        for (const o of openOrders) {
+            if (!o.symbol)
+                continue;
+            const key = normalizeBracketSymbol(o.symbol);
+            const list = ordersBySymbol.get(key) ?? [];
+            list.push(o);
+            ordersBySymbol.set(key, list);
+        }
+        // Untrusted-empty contradiction guard (2026-05-15 SOL/INJ spiral).
+        // A position whose ledger row is non-terminal WITH stored cids but whose
+        // scoped open-orders fetch came back EMPTY is NOT positive evidence the
+        // brackets are gone: under weight pressure Binance's algo-orders REST
+        // endpoint returns a *successful* [] while ALGO_UPDATE (the authoritative
+        // bracket-lifecycle signal) shows the legs still live and never
+        // terminated. Emitting a confident has_stop=false / attach_brackets
+        // verdict here is what drove the audit → attach → cancel-live-brackets
+        // loop AND the bracket_integrity escalation that flushed ATOM/LINK/NEAR.
+        // Same null≠empty / require-positive-disconfirmation contract as
+        // classifyLedgerVsExchange and the reconciler: surface {error} so the
+        // agent skips this cycle and MUST NOT run attach_brackets /
+        // close_position(reason='bracket_integrity') (CLAUDE.md audit-vs-action
+        // contract). The reconciler + ALGO_UPDATE remain the backstop for any
+        // genuinely-naked position on another symbol within one cycle — the
+        // file's own stated philosophy ("a single transient gap just delays the
+        // audit one heartbeat — far safer than fabricating verdicts").
+        const unverifiable = activePositions.filter(p => {
+            const normSym = normalizeBracketSymbol(p.symbol);
+            if ((ordersBySymbol.get(normSym) ?? []).length > 0)
+                return false;
+            const lr = ledger?.getBySymbol(p.symbol) ?? null;
+            return !!lr
+                && (lr.state === 'active' || lr.state === 'partial' || lr.state === 'attaching')
+                && (!!lr.slCid || !!lr.tpCid);
+        });
+        // Before declaring the audit blind, ask the ZERO-WEIGHT authoritative
+        // source we already built (Phase 1/2, deployed): the per-cid bracket-leg
+        // liveness resolver. `getOpenOrders` came back empty ONLY because the
+        // proactive weight pacer shed it (steady-state IP weight pins the soft
+        // ceiling 24/7 — the real disease). But ALGO_UPDATE has already pushed
+        // every leg's NEW/CANCELED/EXPIRED/TRIGGERED status into the in-memory
+        // per-cid map at zero Binance weight. `resolveBracketLegLiveness` reads
+        // that (Tier-1, only when the WS store is trusted), falling back to a
+        // weight-1 REST query, then to 'unknown'. Pre-fix this branch returned
+        // {error} unconditionally → the agent went blind on a live position for
+        // HOURS (prod 2026-05-16: INJ/USDT unverifiable every heartbeat 04:29→
+        // 05:54 straight) even though the WS knew the brackets were live the
+        // whole time. The Phase-2 resolver was dead code in the audit path.
+        //
+        //   stop leg 'live'     → position IS protected (positive verdict, w=0)
+        //   stop leg 'terminal' → positively confirmed naked → attach_brackets
+        //   'unknown'           → keep the d59e51b safe {error} floor for that
+        //                         symbol only (NEVER infer from absence)
+        const wsResolvedProtected = new Set(); // normSym → stop leg confirmed live
+        const stillBlind = [];
+        if (unverifiable.length > 0) {
+            await Promise.all(unverifiable.map(async (p) => {
+                const normSym = normalizeBracketSymbol(p.symbol);
+                const lr = ledger?.getBySymbol(p.symbol) ?? null;
+                // The stop leg is the protective one; resolve it. (A live SL is the
+                // bar for "protected"; TP-only is still has_stop=false downstream.)
+                let slState = 'unknown';
+                if (lr?.slCid) {
+                    try {
+                        slState = await live.resolveBracketLegLiveness(lr.slCid);
+                    }
+                    catch {
+                        slState = 'unknown';
+                    }
+                }
+                if (slState === 'live') {
+                    wsResolvedProtected.add(normSym);
+                }
+                else {
+                    // #1 (supporting) — the ledger's slCid may be positively terminal
+                    // while a PRIOR reattach's FRESH stop leg is live on the exchange
+                    // under a NEW cid the ledger never caught up to (the 2026-05-16 INJ
+                    // spiral). Declaring the position naked here drives the agent to
+                    // attach_brackets → clear+reattach → cancels the live leg → spiral.
+                    // Before that, ask whether ANY trusted-WS rc-*-s stop leg for this
+                    // symbol is live, not just the ledger's cid. (Authoritative break
+                    // is #2 in classifyLedgerVsExchange; this keeps the audit verdict
+                    // consistent so the agent isn't told to attach in the first place.)
+                    const sweep = live.findTrustedLiveBracketCidsForSymbol(p.symbol);
+                    const hasLiveStopLeg = sweep.trusted &&
+                        sweep.liveCids.some(c => parseBracketCid(c)?.role === 'stop');
+                    if (hasLiveStopLeg) {
+                        wsResolvedProtected.add(normSym);
+                    }
+                    else if (slState === 'terminal') {
+                        // Positively confirmed gone AND no other live stop leg — let the
+                        // normal entry builder produce has_stop=false → attach_brackets
+                        // (licensed: POSITIVE disconfirmation, not inference from absence).
+                    }
+                    else {
+                        stillBlind.push(p);
+                    }
+                }
+            }));
+        }
+        if (stillBlind.length > 0) {
+            const blindSyms = stillBlind.map(p => p.symbol).join(', ');
+            const seenLive = [...wsResolvedProtected].join(', ') || 'none';
+            logger.warn(TAG, `audit unverifiable for [${blindSyms}]: scoped getOpenOrders returned EMPTY ` +
+                `(weight-paced) AND the per-cid liveness resolver could not positively confirm ` +
+                `(WS untrusted/silent + weight-1 REST unavailable). Empty ≠ "brackets gone". ` +
+                `Returning {error} — agent must NOT run attach_brackets or ` +
+                `close_position(reason='bracket_integrity') this cycle. ` +
+                `(WS positively confirmed LIVE for: [${seenLive}].)`);
+            return {
+                error: `Cannot confirm bracket protection for [${blindSyms}] — the exchange returned ` +
+                    `an empty open-orders set (weight-paced) and the zero-weight per-leg liveness ` +
+                    `resolver could not positively confirm the bracket legs (WS store untrusted ` +
+                    `or silent on these cids, and the weight-1 REST query was unavailable). An ` +
+                    `empty result is NOT proof the brackets are gone. Skipping audit this cycle — ` +
+                    `bracket state on Binance is unchanged. Do NOT run attach_brackets or ` +
+                    `close_position(reason='bracket_integrity') on the basis of this call. ` +
+                    `Retry next heartbeat.`,
+            };
+        }
+        if (wsResolvedProtected.size > 0) {
+            logger.info(TAG, `per-leg liveness resolver: scoped getOpenOrders was weight-paced-empty but ` +
+                `the WS POSITIVELY confirmed the stop leg LIVE for ` +
+                `[${[...wsResolvedProtected].join(', ')}] at ZERO Binance weight — ` +
+                `reporting protected instead of going blind.`);
+        }
+        const entries = activePositions.map(p => {
+            const normSym = normalizeBracketSymbol(p.symbol);
+            const symbolOrders = ordersBySymbol.get(normSym) ?? [];
+            // BracketLedger applies normalization internally; pass p.symbol through.
+            const ledgerRow = ledger?.getBySymbol(p.symbol) ?? null;
+            // WS-confirmed-protected overlay: scoped getOpenOrders was weight-paced
+            // to empty for this symbol, so the order-based classification below
+            // would falsely report has_stop=false. But the zero-weight per-cid
+            // resolver POSITIVELY confirmed the stop leg is live on the exchange.
+            // Trust that (it's the authoritative ALGO_UPDATE signal, not inference
+            // from an absent REST result). stop_price from the ledger (our intent).
+            if (wsResolvedProtected.has(normSym)) {
+                return {
+                    symbol: p.symbol,
+                    side: p.side,
+                    contracts: p.contracts,
+                    entry_price: p.entryPrice,
+                    mark_price: p.markPrice,
+                    has_stop: true,
+                    has_target: ledgerRow?.targetPrice !== undefined,
+                    stop_price: ledgerRow?.stopPrice,
+                    target_price: ledgerRow?.targetPrice,
+                    ledger_state: ledgerRow?.state ?? 'no_ledger_row',
+                    reason: 'bracket_active',
+                    recommended_action: 'none',
+                };
+            }
+            // Classify each open order on the symbol: bracket SL, bracket TP,
+            // manual SL (non-bracket STOP_MARKET), manual TP (non-bracket TAKE_PROFIT_MARKET).
+            let hasBracketStop = false;
+            let hasBracketTarget = false;
+            let hasManualStop = false;
+            let hasManualTarget = false;
+            let stopPrice;
+            let targetPrice;
+            for (const o of symbolOrders) {
+                const parsed = o.clientOrderId ? parseBracketCid(o.clientOrderId) : null;
+                const triggerPrice = extractTriggerPrice(o);
+                if (parsed && parsed.role === 'stop') {
+                    hasBracketStop = true;
+                    stopPrice = triggerPrice ?? stopPrice;
+                }
+                else if (parsed && parsed.role === 'target') {
+                    hasBracketTarget = true;
+                    targetPrice = triggerPrice ?? targetPrice;
+                }
+                else {
+                    // Prefer Binance's authoritative `orderType` field on the algo
+                    // response (preserved in `info` by binance-private.ts). This
+                    // catches externally-placed stops — manual SL via Binance UI —
+                    // which parseBracketCid can't recognize since they have no
+                    // `rc-*-s/t` CID. The string heuristic on top-level `type`
+                    // remains as a secondary signal for legacy / non-algo paths
+                    // where `info` may be absent.
+                    // Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api/Current-All-Algo-Open-Orders
+                    const infoOrderType = String(o.info?.orderType ?? '').toUpperCase();
+                    const type = (o.type ?? '').toLowerCase();
+                    const isStopType = infoOrderType === 'STOP_MARKET' || infoOrderType === 'STOP' || infoOrderType === 'TRAILING_STOP_MARKET' ||
+                        (type.includes('stop') && !type.includes('take'));
+                    const isTargetType = infoOrderType === 'TAKE_PROFIT_MARKET' || infoOrderType === 'TAKE_PROFIT' ||
+                        type.includes('take_profit') || type.includes('take-profit') || type === 'take_profit_market';
+                    if (isStopType) {
+                        hasManualStop = true;
+                        stopPrice = triggerPrice ?? stopPrice;
+                    }
+                    else if (isTargetType) {
+                        hasManualTarget = true;
+                        targetPrice = triggerPrice ?? targetPrice;
+                    }
+                }
+            }
+            const hasStop = hasBracketStop || hasManualStop;
+            const hasTarget = hasBracketTarget || hasManualTarget;
+            // Prefer ledger price when available — it's our intent, not a re-derived
+            // exchange trigger value (which Binance may round).
+            if (ledgerRow?.stopPrice !== undefined)
+                stopPrice = ledgerRow.stopPrice;
+            if (ledgerRow?.targetPrice !== undefined)
+                targetPrice = ledgerRow.targetPrice;
+            const ledgerState = ledgerRow?.state ?? 'no_ledger_row';
+            let reason;
+            if (!bracketsEnabled) {
+                reason = 'brackets_disabled';
+            }
+            else if (hasStop || hasTarget) {
+                reason = hasBracketStop || hasBracketTarget ? 'bracket_active' : 'manual_order_protecting';
+            }
+            else if (ledgerRow && (ledgerRow.state === 'active' || ledgerRow.state === 'partial' || ledgerRow.state === 'attaching')) {
+                reason = 'stale_ledger_row';
+            }
+            else if (ledgerRow && isTerminalState(ledgerRow.state)) {
+                reason = 'ledger_terminal_no_order';
+            }
+            else {
+                reason = 'no_protective_order';
+            }
+            let recommended_action = 'none';
+            if (!bracketsEnabled)
+                recommended_action = 'enable_brackets_mode';
+            else if (!hasStop)
+                recommended_action = 'attach_brackets';
+            return {
+                symbol: p.symbol,
+                side: p.side,
+                contracts: p.contracts,
+                entry_price: p.entryPrice,
+                mark_price: p.markPrice,
+                has_stop: hasStop,
+                has_target: hasTarget,
+                stop_price: stopPrice,
+                target_price: targetPrice,
+                ledger_state: ledgerState,
+                reason,
+                recommended_action,
+            };
+        });
+        const unprotected = entries.filter(e => !e.has_stop).length;
+        // Flicker detection — runs after every audit pass. Cheap (a few map ops
+        // per open position) and only emits log when the threshold trips.
+        const nowTs = Date.now();
+        for (const e of entries) {
+            recordVerdictAndCheckFlicker(normalizeBracketSymbol(e.symbol), e.has_stop, nowTs);
+        }
+        // Diagnostic: when we conclude a live position is unprotected, dump the
+        // raw openOrders shape for that symbol so post-mortems can tell whether
+        // (a) exchange genuinely had no stop/TP, (b) CCXT returned them but the
+        // cid/type didn't parse, or (c) the orders came back under a different
+        // symbol key than the position. This is the other half of the bug the
+        // 2026-04-21 close_position safeguard catches — we want to see WHY the
+        // audit said false, not just catch the symptom.
+        for (const e of entries) {
+            if (e.has_stop)
+                continue;
+            const normSym = normalizeBracketSymbol(e.symbol);
+            const raw = ordersBySymbol.get(normSym) ?? [];
+            const orderSnapshot = raw.map(o => ({
+                id: o.id,
+                cid: o.clientOrderId ?? null,
+                type: o.type ?? null,
+                side: o.side ?? null,
+                reduceOnly: o.reduceOnly ?? null,
+                stopPrice: extractTriggerPrice(o) ?? null,
+                infoType: o.info
+                    ? (o.info.type ?? null)
+                    : null,
+                symbol: o.symbol ?? null,
+            }));
+            const allSymbols = Array.from(ordersBySymbol.keys());
+            logger.warn(TAG, `unprotected verdict for ${e.symbol} (norm=${normSym}): has_stop=${e.has_stop} ` +
+                `has_target=${e.has_target} reason=${e.reason} ledger=${e.ledger_state}. ` +
+                `openOrders keyed under ${normSym}: ${orderSnapshot.length} ` +
+                `(all symbol keys in map: ${JSON.stringify(allSymbols)}). ` +
+                `orders=${JSON.stringify(orderSnapshot)}`);
+        }
+        return {
+            ok: true,
+            mode: 'live',
+            brackets_enabled: bracketsEnabled,
+            total_positions: entries.length,
+            protected_count: entries.length - unprotected,
+            unprotected_count: unprotected,
+            positions: entries,
+        };
+    }
+    catch (err) {
+        logger.error(TAG, `audit failed: ${formatError(err)}`);
+        return { error: `audit_bracket_protection failed: ${formatError(err)}` };
+    }
+}
+function isTerminalState(s) {
+    return s === 'cancelled' || s === 'failed' || s === 'triggered_sl' || s === 'triggered_tp';
+}
+/** Append a verdict sample for the symbol and emit a flicker warn when the
+ *  recent history shows ≥ FLICKER_THRESHOLD verdict transitions (true↔false)
+ *  inside FLICKER_WINDOW_MS. Trims the history to retention bounds. */
+function recordVerdictAndCheckFlicker(symbol, isProtected, nowTs) {
+    const history = verdictHistory.get(symbol) ?? [];
+    history.push({ ts: nowTs, protected: isProtected });
+    // Trim by both age and length.
+    const cutoff = nowTs - HISTORY_RETENTION_MS;
+    while (history.length > 0 && history[0].ts < cutoff)
+        history.shift();
+    while (history.length > HISTORY_MAX_PER_SYMBOL)
+        history.shift();
+    verdictHistory.set(symbol, history);
+    // Count verdict transitions inside the flicker window.
+    const windowStart = nowTs - FLICKER_WINDOW_MS;
+    let transitions = 0;
+    let prev;
+    for (const sample of history) {
+        if (sample.ts < windowStart)
+            continue;
+        if (prev !== undefined && prev !== sample.protected)
+            transitions++;
+        prev = sample.protected;
+    }
+    if (transitions < FLICKER_THRESHOLD)
+        return;
+    const lastWarned = lastFlickerWarnedAt.get(symbol) ?? 0;
+    if (nowTs - lastWarned < FLICKER_WARN_COOLDOWN_MS)
+        return;
+    lastFlickerWarnedAt.set(symbol, nowTs);
+    logger.warn(TAG, `AUDIT FLICKER on ${symbol}: ${transitions} protected↔unprotected transitions ` +
+        `in the last ${FLICKER_WINDOW_MS / 60_000} min. ` +
+        `Bracket subsystem is reading exchange state inconsistently. ` +
+        `Suspect transient fetchOpenOrders gaps, attach_brackets re-entry races, or ` +
+        `CCXT symbol-form drift. Operator should investigate BEFORE the agent escalates ` +
+        `to close_position(reason='bracket_integrity'). ` +
+        `Recent samples: ${history.slice(-6).map(s => `${new Date(s.ts).toISOString().slice(11, 19)}:${s.protected ? 'P' : 'U'}`).join(' ')}`);
+}
+/** Public getter — returns the recent audit verdict samples for a symbol so
+ *  close_position can copy them into the position's close record for the
+ *  dashboard Position Timeline drawer. Read-only snapshot; mutating the
+ *  return value does not affect internal state. */
+export function getRecentAuditVerdictHistory(symbol) {
+    const history = verdictHistory.get(normalizeBracketSymbol(symbol)) ?? [];
+    // Defensive copy so callers can't mutate the live buffer.
+    return history.map(s => ({ ts: s.ts, protected: s.protected }));
+}
+/** Test seam — clears the in-memory flicker history between unit tests. */
+export const __testing__ = {
+    resetFlickerHistory() {
+        verdictHistory.clear();
+        lastFlickerWarnedAt = new Map();
+    },
+    /** Inspect current history for a symbol — used by tests to assert state. */
+    getHistory(symbol) {
+        return verdictHistory.get(normalizeBracketSymbol(symbol)) ?? [];
+    },
+};
+// CCXT returns STOP_MARKET / TAKE_PROFIT_MARKET trigger prices in one of a
+// few spots depending on version + exchange. Check the most common ones.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractTriggerPrice(o) {
+    const candidates = [
+        o?.stopPrice,
+        o?.triggerPrice,
+        o?.info?.stopPrice,
+        o?.info?.triggerPrice,
+        o?.params?.stopPrice,
+    ];
+    for (const c of candidates) {
+        if (typeof c === 'number' && Number.isFinite(c) && c > 0)
+            return c;
+        if (typeof c === 'string') {
+            const n = Number(c);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+    }
+    return undefined;
+}

package/tools/cancel-all-orders.d.ts

@@ -0,0 +1,7 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+export declare function cancelAllOrdersTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtOrder[]>;

package/tools/cancel-all-orders.js

@@ -0,0 +1,5 @@
+// Tool: cancel_all_orders — cancel all open orders (paper or live)
+// NO readiness gate — emergency control (kill switch), must always work.
+export async function cancelAllOrdersTool(args, deps) {
+    return deps.adapter.cancelAllOrders(args.symbol);
+}

package/tools/cancel-order.d.ts

@@ -0,0 +1,10 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+export declare function cancelOrderTool(args: {
+    id: string;
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtOrder | {
+    error: string;
+}>;

package/tools/cancel-order.js

@@ -0,0 +1,14 @@
+// Tool: cancel_order — cancel a single order (paper or live)
+// NO readiness gate — emergency control, must always work.
+import { formatError } from '../logger.js';
+export async function cancelOrderTool(args, deps) {
+    if (!args.id) {
+        return { error: 'Order ID is required.' };
+    }
+    try {
+        return await deps.adapter.cancelOrder(args.id, args.symbol);
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}

package/tools/check-position-health.d.ts

@@ -0,0 +1,46 @@
+interface PositionInput {
+    symbol: string;
+    side: 'LONG' | 'SHORT';
+    entry_price: number;
+    current_price: number;
+    stop_price: number;
+    target_price?: number;
+    quantity: number;
+    entry_time: string;
+}
+interface CheckHealthArgs {
+    positions: PositionInput[];
+    account_balance: number;
+}
+interface PositionHealth {
+    symbol: string;
+    side: string;
+    pnl: number;
+    pnlPercent: number;
+    pnlR: number;
+    distanceToStopPercent: number;
+    distanceToStopR: number;
+    stopStatus: 'SAFE' | 'CLOSE' | 'CRITICAL' | 'BREACHED';
+    distanceToTargetPercent: number | null;
+    distanceToTargetR: number | null;
+    targetReached: boolean;
+    heatPercent: number;
+    notionalPercent: number;
+    timeInTradeMinutes: number;
+    timeInTradeFormatted: string;
+    timeStatus: 'FRESH' | 'NORMAL' | 'EXTENDED' | 'STALE';
+    alerts: string[];
+}
+interface HealthSummary {
+    positions: PositionHealth[];
+    portfolio: {
+        totalHeat: number;
+        totalNotional: number;
+        totalPnl: number;
+        positionCount: number;
+        heatStatus: 'LOW' | 'MODERATE' | 'ELEVATED' | 'HIGH' | 'CRITICAL';
+        alerts: string[];
+    };
+}
+export declare function checkPositionHealthTool(args: CheckHealthArgs): HealthSummary;
+export {};