@reefclaw/openclaw-plugin 0.1.0

package/live/bracket-reconciler.js

@@ -0,0 +1,573 @@
+// BracketReconciler — periodic drift check between the local bracket ledger
+// and the exchange state. Runs every 60s by default.
+//
+// Reconciliation matrix (key = {position exists, SL on exchange, TP on exchange}):
+//
+//   pos:Y sl:Y tp:Y  → healthy, no-op
+//   pos:Y sl:Y tp:N  → partial (TP missing) — ALERT (manual cancel or trigger race)
+//   pos:Y sl:N tp:Y  → partial (SL missing) — ALERT (position unprotected!)
+//   pos:Y sl:N tp:N  → brackets gone, position alive → ALERT (unprotected)
+//   pos:N sl:Y tp:Y  → position closed, brackets orphaned → AUTO-CANCEL, mark ledger
+//   pos:N sl:Y tp:N  → position closed, one orphan → AUTO-CANCEL, mark ledger
+//   pos:N sl:N tp:Y  → position closed, one orphan → AUTO-CANCEL, mark ledger
+//   pos:N sl:N tp:N  → position closed cleanly → mark ledger (triggered or cancelled)
+//
+// Unknown orphans (bracket-tagged clientOrderIds on exchange with no ledger
+// entry) are auto-cancelled — they represent either a crash before ledger
+// persist or a leftover from a previous plugin install.
+import { EventEmitter } from 'node:events';
+import { normalizeBracketSymbol } from './bracket-ledger.js';
+import { parseBracketCid } from './bracket-id.js';
+import { logger, formatError } from '../logger.js';
+const TAG = 'bracket-reconciler';
+const DEFAULT_INTERVAL_MS = 60_000;
+/** Grace window for the unknown-bracket orphan sweep (2026-05-16 SOL
+ *  incident). A bracket-tagged `rc-*` order with no active ledger row is
+ *  NOT necessarily junk: in the seconds right after an entry fill the
+ *  post-entry auto-attach places SL/TP on the exchange while (a) the ledger
+ *  row is still being persisted and (b) the reconciler's positions snapshot
+ *  has not yet propagated the brand-new position — so BOTH the "active
+ *  ledger entry" check AND the "live position exists" guard miss it, and the
+ *  sweep cancels the freshly-placed protection (prod: SOL bracket cancelled
+ *  ~8 s after entry, naked spiral). A bracket the reconciler is seeing for
+ *  the first time, or whose exchange order is younger than this window, is
+ *  too young to be a crash/old-plugin leftover (those are minutes-to-hours
+ *  old) — delaying their cleanup by a minute is harmless; cancelling a
+ *  live position's only protection is not. Env-overridable; clamp 10s–10m. */
+const ORPHAN_GRACE_MS = (() => {
+    const raw = Number(process.env.RC_BRACKET_ORPHAN_GRACE_MS);
+    return Number.isFinite(raw) && raw >= 10_000 && raw <= 600_000 ? raw : 60_000;
+})();
+/** Max multiplier applied to interval under sustained back-pressure (e.g.
+ *  binance 429 storm where `getOpenOrders` keeps throwing). 5× → 5 min cap.
+ *  Matches the upper end of Binance's documented per-IP rate-limit window. */
+const MAX_BACKOFF_MULTIPLIER = 5;
+/** Error-message substrings that indicate transient exchange unavailability
+ *  (rate-limit or null-collapse from `LiveAdapter.getOpenOrders`). When
+ *  matched, the reconciler doubles its tick interval (up to the cap) so it
+ *  stops piling onto an already-throttled IP. The match is intentionally
+ *  loose — better to over-back-off on a misclassified network error than
+ *  to keep hammering during a real 429. */
+const TRANSIENT_UNAVAILABLE_MARKERS = [
+    '429',
+    'Too Many Requests',
+    'fetchOpenOrders returned null',
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'getaddrinfo',
+];
+export class BracketReconciler extends EventEmitter {
+    adapter;
+    ledger;
+    manager;
+    api;
+    baseIntervalMs;
+    now;
+    handle = null;
+    /** Distinct from `handle` because we need to know "did stop() get called
+     *  while a pass was in flight" — at that moment `handle` is still the
+     *  in-flight setTimeout token but `started` has flipped to false. The
+     *  finally-block consults `started` (not `handle`) to decide whether to
+     *  schedule another tick. */
+    started = false;
+    running = false;
+    /** Current multiplier applied to baseIntervalMs. Doubles on each
+     *  transient-unavailable error, capped at MAX_BACKOFF_MULTIPLIER. Resets to
+     *  1 on a successful pass. Persisted across pass invocations as the
+     *  observed back-pressure state. */
+    backoffMultiplier = 1;
+    /** bracketId → epoch-ms the orphan sweep first observed it as an
+     *  unmatched (no-active-ledger-row) bracket. Drives the ORPHAN_GRACE_MS
+     *  youth guard: a bracket seen for the first time is, by construction,
+     *  ≤ one pass old from our side — never cancel it that pass. Pruned each
+     *  pass to bracketIds still unmatched on the exchange (bounded). */
+    firstSeenOrphanAt = new Map();
+    constructor(adapter, ledger, manager, api, opts = {}) {
+        super();
+        this.adapter = adapter;
+        this.ledger = ledger;
+        this.manager = manager;
+        this.api = api;
+        this.baseIntervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Begin periodic reconciliation. Safe to call if already started. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.scheduleNextPass();
+        logger.info(TAG, `Started (interval=${this.baseIntervalMs}ms)`);
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        if (this.handle) {
+            clearTimeout(this.handle);
+            this.handle = null;
+        }
+        logger.info(TAG, 'Stopped');
+    }
+    /** Self-rescheduling tick. Replaces the old `setInterval` because the
+     *  next interval is dynamic — we slow down under back-pressure, speed back
+     *  up after a clean pass. The old approach kept hitting Binance at full
+     *  60 s cadence during a 429 storm, amplifying it. */
+    scheduleNextPass() {
+        if (!this.started)
+            return;
+        const delay = this.baseIntervalMs * this.backoffMultiplier;
+        this.handle = setTimeout(() => {
+            this.handle = null;
+            void this.runPass()
+                .then(() => {
+                if (this.backoffMultiplier > 1) {
+                    logger.info(TAG, `clean pass — backoff multiplier reset (was ${this.backoffMultiplier}×)`);
+                    this.backoffMultiplier = 1;
+                }
+            })
+                .catch((err) => {
+                const msg = formatError(err);
+                logger.error(TAG, `reconcile pass failed: ${msg}`);
+                const transient = TRANSIENT_UNAVAILABLE_MARKERS.some((m) => msg.includes(m));
+                if (transient) {
+                    const prev = this.backoffMultiplier;
+                    this.backoffMultiplier = Math.min(prev * 2, MAX_BACKOFF_MULTIPLIER);
+                    if (this.backoffMultiplier !== prev) {
+                        logger.warn(TAG, `transient exchange unavailability — backing off ` +
+                            `${prev}× → ${this.backoffMultiplier}× (next pass in ` +
+                            `${(this.baseIntervalMs * this.backoffMultiplier) / 1000}s)`);
+                    }
+                }
+            })
+                .finally(() => {
+                // Schedule next tick unless stop() was called while this pass was
+                // in flight. `started` is the authoritative signal — `handle` was
+                // cleared at top of this callback above.
+                if (this.started)
+                    this.scheduleNextPass();
+            });
+        }, delay);
+    }
+    /** One reconciliation pass. Exposed for unit tests + startup recovery. */
+    async runPass() {
+        if (this.running) {
+            // Skip re-entrant pass — last one still in flight
+            return { startedAt: new Date(this.now()).toISOString(), drifts: [], positionsChecked: 0, ordersChecked: 0 };
+        }
+        this.running = true;
+        const startedAt = new Date(this.now()).toISOString();
+        const drifts = [];
+        try {
+            const [positionsRaw, openOrders] = await Promise.all([
+                this.adapter.getPositionsOrNull
+                    ? this.adapter.getPositionsOrNull()
+                    : this.adapter.getPositions(),
+                this.adapter.getOpenOrders(),
+            ]);
+            // `null` = positions fetch FAILED (429 / weight-paced / transient) —
+            // state UNKNOWN, NOT "flat". Under this snapshot we must take ZERO
+            // destructive action: an empty/failed positions list must never read as
+            // "no live position → safe to cancel these orphan brackets". 2026-05-15
+            // XRP strip loop: positions kept collapsing, the Section-2 orphan sweep
+            // cancelled the live position's bracket legs every pass.
+            const positionsUntrusted = positionsRaw === null;
+            const positions = positionsRaw ?? [];
+            // Key by normalized symbol so `entry.symbol` (canonical un-suffixed
+            // form stored by BracketLedger) matches CCXT position.symbol (which
+            // arrives suffixed as `BTC/USDT:USDT`). Without this, every active
+            // bracket entry would look "position gone" and the reconciler would
+            // auto-cancel live protection. See bracket-ledger.ts
+            // `normalizeBracketSymbol` for the rationale.
+            const positionBySymbol = new Map();
+            for (const p of positions)
+                positionBySymbol.set(normalizeBracketSymbol(p.symbol), p);
+            // ROOT-CAUSE FIX 2026-05-16 (belt-and-suspenders to the attach-time
+            // disable): proactively neutralise Binance's per-symbol
+            // countdownCancelAll dead-man's-switch on every symbol that currently
+            // has a live position. An externally-armed countdown (nothing in our
+            // stack arms it — verified) purges ALL orders for the symbol
+            // server-side ~tens of seconds after they're placed; that was the
+            // months-long naked-position spiral. Disabling it each pass means a
+            // re-armed switch is cleared within one reconciler cycle instead of
+            // silently stripping protection. Best-effort: never let it break the
+            // pass; the method itself is idempotent + swallows its own errors.
+            if (this.api.disableCountdownCancelAll) {
+                for (const sym of new Set(positions.map(p => p.symbol))) {
+                    try {
+                        await this.api.disableCountdownCancelAll(sym);
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `periodic disableCountdownCancelAll(${sym}) ignored: ${formatError(err)}`);
+                    }
+                }
+            }
+            // Bucket open orders by bracketId + role
+            const ordersByBracket = new Map();
+            for (const o of openOrders) {
+                const cid = o.clientOrderId;
+                if (!cid)
+                    continue;
+                const parsed = parseBracketCid(cid);
+                if (!parsed)
+                    continue;
+                const bucket = ordersByBracket.get(parsed.bracketId) ?? {};
+                bucket[parsed.role] = o;
+                ordersByBracket.set(parsed.bracketId, bucket);
+            }
+            // ---- 1. Walk active ledger entries ----
+            for (const entry of this.ledger.getActive()) {
+                const onExchange = ordersByBracket.get(entry.bracketId) ?? {};
+                const position = positionBySymbol.get(entry.symbol);
+                const slExpected = entry.stopPrice !== undefined;
+                const tpExpected = entry.targetPrice !== undefined;
+                const slLive = !!onExchange.stop;
+                const tpLive = !!onExchange.target;
+                if (position) {
+                    // Position alive — brackets SHOULD be present as expected
+                    const missingSl = slExpected && !slLive;
+                    const missingTp = tpExpected && !tpLive;
+                    if (missingSl || missingTp) {
+                        drifts.push({
+                            kind: 'position_unprotected',
+                            symbol: entry.symbol,
+                            bracketId: entry.bracketId,
+                            details: `missing: ${[missingSl && 'stop', missingTp && 'target'].filter(Boolean).join('+')}`,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                    }
+                    else {
+                        drifts.push({
+                            kind: 'healthy',
+                            symbol: entry.symbol,
+                            bracketId: entry.bracketId,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                    }
+                }
+                else if (positionsUntrusted) {
+                    // Positions fetch FAILED — "position gone" is unverifiable. Never
+                    // mark the ledger terminal or cancel on an untrusted snapshot;
+                    // brackets (if any) stay, ledger stays, re-evaluate next pass.
+                    drifts.push({
+                        kind: 'untrusted_snapshot_skip',
+                        symbol: entry.symbol,
+                        bracketId: entry.bracketId,
+                        details: `positions fetch returned null (429 / weight-paced / transient) — ` +
+                            `cannot verify ${entry.symbol} is gone. NO ledger mutation, NO cancel. ` +
+                            `Re-evaluating next pass.`,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    logger.warn(TAG, `Untrusted positions snapshot — skipping "position gone" handling for ` +
+                        `${entry.symbol} (bracketId=${entry.bracketId}); NOT mutating ledger or cancelling.`);
+                }
+                else {
+                    // Position gone (per getPositions) — but is that trustworthy?
+                    //
+                    // 2026-05-15 bracket-spiral root cause: `getPositions()` collapses a
+                    // 429 / transient `fetchPositions` failure to `[]` (live-adapter.ts
+                    // `positions ?? []`), unlike `getOpenOrders()` which throws on null
+                    // since the 2026-05-14 fix. `fetchPositions` and `fetchOpenOrders`
+                    // are independent HTTP calls with independent rate-limit windows —
+                    // under a 429 storm one succeeds while the other fails. When
+                    // positions 429-collapses to empty but openOrders SUCCEEDS and shows
+                    // the bracket legs live, this branch fired `cancelBrackets` and
+                    // stripped protection off a still-open live position. The position
+                    // then "reappeared" next snapshot, now naked. Confirmed via prod
+                    // ALGO_UPDATE sniffer: SL+TP placed, then CANCELED ~46-60s later
+                    // (= one reconciler cycle) with no Binance reason — i.e. an explicit
+                    // cancelOrder from us, not an exchange-side action.
+                    //
+                    // The discriminator: Binance auto-cancels reduce-only STOP/TP orders
+                    // within ~10s of a position reaching zero. So if `getOpenOrders`
+                    // (trustworthy — it throws rather than lying on 429) STILL shows the
+                    // bracket legs live, the position almost certainly still exists and
+                    // the empty positions list is a failed fetch. Live brackets + zero
+                    // positions is a logical contradiction, not a closed position.
+                    // Refuse the destructive cancel; let the next pass (Patch C backs
+                    // the cadence off under this exact pressure) re-evaluate with good
+                    // data. Cost of waiting: ~nothing (Binance auto-cancels genuine
+                    // reduce-only orphans anyway). Cost of acting on the bad snapshot:
+                    // a naked live position. See
+                    // `memory/feedback_getopenorders_null_collapse_naked_loop.md`.
+                    if (slLive || tpLive) {
+                        drifts.push({
+                            kind: 'untrusted_snapshot_skip',
+                            symbol: entry.symbol,
+                            bracketId: entry.bracketId,
+                            details: `getPositions() returned no position for ${entry.symbol} but ` +
+                                `getOpenOrders() shows live ${[slLive && 'stop', tpLive && 'target'].filter(Boolean).join('+')} ` +
+                                `(bracketId=${entry.bracketId}). Live reduce-only brackets cannot ` +
+                                `coexist with a closed position on Binance — treating the empty ` +
+                                `positions snapshot as a failed fetch and SKIPPING cancel. ` +
+                                `Re-evaluating next pass.`,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                        logger.warn(TAG, `REFUSING destructive cancel for ${entry.symbol}: positions=empty but ` +
+                            `brackets live on exchange (bracketId=${entry.bracketId}). ` +
+                            `Bad positions snapshot — NOT cancelling live protection.`);
+                    }
+                    else {
+                        // Position gone, no brackets open — clean terminal state.
+                        // We don't know which side triggered (SL vs TP) without fill history,
+                        // so log as 'cancelled' unless ledger already resolved via the
+                        // trigger-handler path (future wiring).
+                        drifts.push({
+                            kind: 'terminal_clean',
+                            symbol: entry.symbol,
+                            bracketId: entry.bracketId,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                        try {
+                            this.ledger.markState(entry.symbol, 'cancelled', { closeReason: 'cancelled_auto' });
+                        }
+                        catch { /* already terminal */ }
+                    }
+                }
+            }
+            // ---- 2. Walk exchange orders for unknown-bracket orphans ----
+            const activeBracketIds = new Set(this.ledger.getActive().map(e => e.bracketId));
+            // Prune the first-seen map to bracketIds still present + unmatched on
+            // the exchange this pass (resolved/gone ones can't spiral). Keeps it
+            // bounded and means a bracketId that disappears then reappears is
+            // correctly treated as young again.
+            for (const id of [...this.firstSeenOrphanAt.keys()]) {
+                if (!ordersByBracket.has(id) || activeBracketIds.has(id)) {
+                    this.firstSeenOrphanAt.delete(id);
+                }
+            }
+            for (const [bracketId, bucket] of ordersByBracket) {
+                if (activeBracketIds.has(bracketId))
+                    continue; // already handled
+                // Bracket-tagged cids on exchange with no ACTIVE ledger entry.
+                // Possible causes: crashed before ledger persist; leftover from old
+                // plugin; OR — the 2026-05-16 SOL incident — a bracket just placed
+                // by the post-entry auto-attach whose ledger row / position snapshot
+                // hasn't propagated yet. NOT always safe to cancel; gated below.
+                const samples = [bucket.stop, bucket.target, bucket.entry].filter(Boolean);
+                if (samples.length === 0)
+                    continue;
+                const symbol = samples[0].symbol;
+                // Record the first pass that ever saw this bracketId unmatched, so
+                // the grace clock (below) starts at true first sighting regardless
+                // of which guard fires this pass. Pruned above once it resolves.
+                const nowMs = this.now();
+                if (!this.firstSeenOrphanAt.has(bracketId)) {
+                    this.firstSeenOrphanAt.set(bracketId, nowMs);
+                }
+                // ---- PRIMARY POSITIVE-CONFIRMATION GATE (2026-05-16 SOL) --------
+                // The authoritative, zero-weight source of per-leg liveness is the
+                // trusted user-data WS ALGO_UPDATE map — the SAME signal
+                // audit_bracket_protection used to (correctly) report SOL's stop
+                // leg LIVE at 08:36:10.167, 271 ms before this sweep cancelled it
+                // off a stale REST positions snapshot. Ask it FIRST. If any of the
+                // exact orders we are about to cancel is positively WS-confirmed
+                // live, it is reduce-only protection on a real position (Binance
+                // auto-cancels true reduce-only orphans within ~10 s, so a still-
+                // live leg ⇒ a position exists) — NEVER cancel it, regardless of
+                // ledger/snapshot state. Absence from `liveCids` is NOT proof a leg
+                // is dead (never-recorded ≠ cancelled — same contract as
+                // resolveBracketLegLiveness): the WS can only POSITIVELY protect
+                // here; it never licenses a cancel. When the WS has no usable
+                // opinion (untrusted/silent) we fall through to the snapshot guards
+                // and the grace backstop unchanged.
+                const wsLive = this.adapter.findTrustedLiveBracketCidsForSymbol?.(symbol);
+                if (wsLive?.trusted && wsLive.liveCids.length > 0) {
+                    const liveSet = new Set(wsLive.liveCids);
+                    const liveLegCids = samples
+                        .map(o => o.clientOrderId)
+                        .filter((c) => !!c && liveSet.has(c));
+                    if (liveLegCids.length > 0) {
+                        drifts.push({
+                            kind: 'unknown_orphan_skip_ws_live',
+                            symbol,
+                            bracketId,
+                            details: `no active ledger row for bracketId=${bracketId} but the trusted ` +
+                                `user-data WS POSITIVELY confirms leg(s) [${liveLegCids.join(', ')}] ` +
+                                `LIVE for ${symbol} — authoritative reduce-only protection on a ` +
+                                `real position. REFUSING to cancel (zero-weight positive proof, ` +
+                                `independent of the unreliable ledger row / stale positions ` +
+                                `snapshot). Investigate why the ledger row is missing.`,
+                            ts: new Date(nowMs).toISOString(),
+                        });
+                        logger.warn(TAG, `REFUSING orphan cancel for ${symbol} (bracketId=${bracketId}): ` +
+                            `trusted WS confirms leg(s) [${liveLegCids.join(', ')}] LIVE — ` +
+                            `these are protecting a live position. Keeping them. Ledger row ` +
+                            `missing/non-active for an open position — root cause to fix.`);
+                        continue;
+                    }
+                }
+                // CRITICAL money-safety guard (2026-05-15 XRP strip loop). A
+                // bracket-tagged order with no ACTIVE ledger entry is NOT
+                // automatically a safe orphan: if a live position exists for this
+                // symbol, these legs are the ONLY exchange protection on a real open
+                // position whose ledger row we lost (stale/terminal/restart/the
+                // ledger-goes-non-active root cause under investigation). Cancelling
+                // them strips a live position naked; attach re-adds, the ledger goes
+                // stale again, next pass strips again → infinite naked loop. Losing
+                // the ledger row must NEVER strip exchange protection off a live
+                // position. Only a TRUE orphan — positions snapshot TRUSTED *and* no
+                // live position for the symbol — is safe to cancel.
+                if (positionsUntrusted) {
+                    drifts.push({
+                        kind: 'untrusted_snapshot_skip',
+                        symbol,
+                        bracketId,
+                        details: `unknown-bracket cids on exchange for ${symbol} but positions ` +
+                            `snapshot is untrusted (null fetch) — cannot prove these are true ` +
+                            `orphans vs protection on a live position. SKIPPING cancel.`,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    logger.warn(TAG, `REFUSING orphan cancel for ${symbol} (bracketId=${bracketId}): ` +
+                        `positions snapshot untrusted — NOT cancelling, could be live protection.`);
+                    continue;
+                }
+                if (positionBySymbol.has(normalizeBracketSymbol(symbol))) {
+                    drifts.push({
+                        kind: 'unknown_orphan_skip_live_position',
+                        symbol,
+                        bracketId,
+                        details: `no active ledger entry for bracketId=${bracketId} but a LIVE ` +
+                            `position exists for ${symbol} — these bracket legs are protecting ` +
+                            `it (lost/stale ledger row). REFUSING to cancel; brackets stay. ` +
+                            `Investigate why the ledger row went non-active.`,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    logger.warn(TAG, `REFUSING orphan cancel for ${symbol} (bracketId=${bracketId}): ` +
+                        `live position present — these legs are its protection. Keeping them. ` +
+                        `Ledger row lost/non-active for an open position — root cause to investigate.`);
+                    continue;
+                }
+                // ---- GRACE GUARD (TERTIARY backstop, 2026-05-16 SOL incident) ----
+                // Reached only when: the trusted-WS positive gate above had NO
+                // usable opinion (WS untrusted/silent, or no live record for these
+                // cids) AND trusted snapshot AND no live position for the symbol AND
+                // no active ledger row. The authoritative fix is the WS gate above;
+                // this remains purely as a safety net for the WS-blind path. Same
+                // false-positive the SOL spiral exploited — a bracket placed seconds
+                // ago by the post-entry auto-attach, before the ledger row persisted
+                // and before the brand-new position propagated into the positions
+                // snapshot. A genuine crash/old-plugin orphan is minutes-to-hours
+                // old; a real leftover is never seconds old. Two independent youth
+                // signals; if EITHER says "young", REFUSE the cancel (positive-
+                // safety: only act when positively proven stale, never on a maybe):
+                //   - reconciler first-seen: first unmatched sighting ⇒ ≤ one pass
+                //     old from our side ⇒ young by construction.
+                //   - exchange order age: youngest plausible sample timestamp (algo
+                //     orders may omit it — then unused, never assumed old).
+                const seenAgeMs = nowMs - (this.firstSeenOrphanAt.get(bracketId) ?? nowMs);
+                let exchangeAgeMs = Number.POSITIVE_INFINITY;
+                for (const o of samples) {
+                    const ts = o.timestamp;
+                    if (typeof ts === 'number' && ts > 0 && ts <= nowMs + 5_000) {
+                        exchangeAgeMs = Math.min(exchangeAgeMs, nowMs - ts);
+                    }
+                }
+                const apparentAgeMs = Math.min(seenAgeMs, exchangeAgeMs);
+                if (apparentAgeMs < ORPHAN_GRACE_MS) {
+                    drifts.push({
+                        kind: 'unknown_orphan_grace_skip',
+                        symbol,
+                        bracketId,
+                        details: `bracket-tagged cids for ${symbol} have no active ledger row and ` +
+                            `no live position in the snapshot, but are only ~${Math.round(apparentAgeMs / 1000)}s old (grace ${Math.round(ORPHAN_GRACE_MS / 1000)}s) — too ` +
+                            `young to be a crash/old-plugin leftover; treating as a freshly-` +
+                            `attached bracket racing ledger-persist + position propagation. ` +
+                            `NOT cancelling this pass.`,
+                        ts: new Date(nowMs).toISOString(),
+                    });
+                    logger.warn(TAG, `REFUSING orphan cancel for ${symbol} (bracketId=${bracketId}): ` +
+                        `only ~${Math.round(apparentAgeMs / 1000)}s old (< ${Math.round(ORPHAN_GRACE_MS / 1000)}s grace) — freshly-placed bracket, ledger/position not yet ` +
+                        `propagated. Keeping it; re-evaluate next pass.`);
+                    continue;
+                }
+                // ---- AUTHORITATIVE POSITIVE-TERMINAL GATE — THE Section-2 root fix
+                // (2026-05-16 SOL recurring naked-position spiral) ------------------
+                // Reaching here means: WS positive-live gate had no opinion, the
+                // positions snapshot is non-null and does NOT contain this symbol,
+                // and the orphan is past the grace window. PRE-FIX that conjunction
+                // alone licensed the cancel — Section-2 inferred "orphan" purely
+                // from the symbol's ABSENCE in the positions snapshot. That
+                // inference is structurally unsound for rc-* legs: every rc-*-{s,t}
+                // is a reduce-only STOP/TP, and Binance auto-cancels a reduce-only
+                // order within ~10 s of the position reaching zero. A reduce-only
+                // rc-* leg still LIVE on the exchange well past the grace window
+                // (60 s ≫ 10 s) is therefore POSITIVE PROOF the position is still
+                // OPEN and the empty / weight-paced / eventually-consistent
+                // positions snapshot is a bad read — the exact null≠empty hole
+                // Section-1 already refuses (the "live brackets + empty positions =
+                // logical contradiction" branch above) and the precise mechanism
+                // every prior guard (WS / live-position / grace) was routed around
+                // because each only narrowed, never removed, the
+                // positions-absence→cancel path.
+                //
+                // The invariant, applied symmetrically here: ONLY positive per-leg
+                // terminal proof — NEVER positions-absence — may license a
+                // destructive bracket cancel. resolveBracketLegLiveness is the same
+                // authoritative signal classifyLedgerVsExchange uses (trusted-WS →
+                // weight-1 REST → 'unknown' floor). ALL legs positively 'terminal'
+                // ⇒ the legs really are dead ⇒ the cancel is a harmless idempotent
+                // cleanup (Binance had likely auto-cancelled them already). ANY leg
+                // 'live' or 'unknown' ⇒ REFUSE and re-evaluate next pass; a genuine
+                // crash orphan stays caught (Binance reduce-only auto-cancel, or a
+                // later pass once a leg goes positively terminal / positions read
+                // trustworthy). The resolver is optional only for narrow unit mocks;
+                // the real LiveAdapter always implements it, so the production path
+                // is unconditionally gated and the spiral is structurally impossible.
+                if (this.adapter.resolveBracketLegLiveness) {
+                    const cids = samples
+                        .map(o => o.clientOrderId)
+                        .filter((c) => !!c);
+                    const verdicts = await Promise.all(cids.map(c => this.adapter.resolveBracketLegLiveness(c)));
+                    const allTerminal = verdicts.length > 0 && verdicts.every(v => v === 'terminal');
+                    if (!allTerminal) {
+                        drifts.push({
+                            kind: 'unknown_orphan_skip_legs_not_terminal',
+                            symbol,
+                            bracketId,
+                            details: `no ledger row + positions snapshot reports ${symbol} flat, but ` +
+                                `the authoritative per-leg resolver did NOT positively confirm ` +
+                                `ALL legs terminal (verdicts=${JSON.stringify(verdicts)}). A ` +
+                                `reduce-only rc-* leg still live past the ${Math.round(ORPHAN_GRACE_MS / 1000)}s grace implies an OPEN position (Binance auto-cancels ` +
+                                `reduce-only orphans in ~10s) — the empty positions snapshot ` +
+                                `is a bad read. REFUSING the cancel; only positive terminal ` +
+                                `proof licenses it. Re-evaluating next pass.`,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                        logger.warn(TAG, `REFUSING orphan cancel for ${symbol} (bracketId=${bracketId}): ` +
+                            `per-leg resolver verdicts=${JSON.stringify(verdicts)} (not all ` +
+                            `'terminal'). A live reduce-only rc-* leg past grace means the ` +
+                            `position is OPEN — positions-absence is NOT proof of ` +
+                            `orphan-hood. Keeping protection. (Section-2 positive-terminal ` +
+                            `gate — the 2026-05-16 SOL spiral root fix.)`);
+                        continue;
+                    }
+                }
+                drifts.push({
+                    kind: 'unknown_orphan',
+                    symbol,
+                    bracketId,
+                    details: `no ledger entry for bracketId=${bracketId}, no live position for ${symbol}, all legs POSITIVELY terminal, ~${Math.round((nowMs - (this.firstSeenOrphanAt.get(bracketId) ?? nowMs)) / 1000)}s observed (> grace); cancelling ${samples.length} orphan order(s)`,
+                    ts: new Date(this.now()).toISOString(),
+                });
+                for (const o of samples) {
+                    if (!o.clientOrderId)
+                        continue;
+                    try {
+                        await this.api.cancelOrderByClientId(o.clientOrderId, o.symbol);
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `orphan cancel failed for cid ${o.clientOrderId}: ${formatError(err)}`);
+                    }
+                }
+            }
+            // Emit every drift so listeners (telemetry, admin dashboard) see them all.
+            for (const d of drifts)
+                this.emit('drift', d);
+            return { startedAt, drifts, positionsChecked: positions.length, ordersChecked: openOrders.length };
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}