@reefclaw/openclaw-plugin 0.1.6 → 0.1.7

package/tools/attach-brackets.js

@@ -22,6 +22,9 @@
 import { generateBracketId, buildBracketCid } from '../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../live/bracket-params.js';
 import { formatError, logger } from '../logger.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+import { isTerminalBracketState } from '../venues/hyperliquid/hl-bracket-coordinator.js';
+import { buildHlBracketCloid } from '../venues/hyperliquid/hl-cloid.js';
 const TAG = 'attach-brackets';
 export async function attachBracketsTool(args, deps) {
     // ---- 1. Argument validation ----
@@ -77,6 +80,12 @@ async function attachBracketsLive(args, deps) {
             };
         }
     }
+    // Venue dispatch (issue #209): the HL arm drives the HlBracketCoordinator —
+    // the Binance-shaped path below would silently no-op ("not enabled") on HL,
+    // which is exactly the recovery gap the boot guard existed for.
+    if (deps.adapter instanceof HyperliquidLiveAdapter) {
+        return attachBracketsHl(args, deps.adapter);
+    }
     const live = deps.adapter;
     const mgr = live.getBracketManager?.();
     const ledger = live.getBracketLedger?.();
@@ -267,6 +276,162 @@ async function attachBracketsLive(args, deps) {
         attempts: attachResult.attempts,
     };
 }
+/**
+ * Hyperliquid recovery attach (issue #209). Same safety contract as the
+ * Binance path — null ≠ empty, positive-evidence-only destructive decisions,
+ * idempotent no-op on a live matching bracket — expressed against the
+ * HlBracketCoordinator. Classification is the d59e51b floor: a stored cid
+ * positively present in a successful getOpenOrders is 'live'; a NON-EMPTY set
+ * lacking every stored cid is 'stale'; an EMPTY set or a thrown fetch is
+ * 'unknown' (empty is never positive disconfirmation).
+ */
+async function attachBracketsHl(args, adapter) {
+    const coordinator = adapter.getHlBracketCoordinator();
+    const ledger = coordinator.getLedger();
+    // ---- Position must exist (null ≠ empty) ----
+    const positions = await adapter.getPositionsOrNull(args.symbol);
+    if (positions === null) {
+        return {
+            error: `Exchange data unavailable for ${args.symbol} (Hyperliquid fetch failed / rate-gated) — ` +
+                `position state UNKNOWN. NOT treating this as "no position"; bracket attach skipped ` +
+                `this cycle. Retry on next heartbeat.`,
+        };
+    }
+    const base = args.symbol.split(':')[0];
+    const position = positions.find(p => p.symbol?.startsWith(base)) ?? positions[0];
+    const contracts = Math.abs(Number(position?.contracts ?? 0));
+    if (!position || contracts <= 0) {
+        return { error: `No open position for ${args.symbol}.` };
+    }
+    const entrySide = position.side === 'long' ? 'buy' : 'sell';
+    // ---- Direction sanity vs entry price ----
+    const refPrice = position.entryPrice > 0 ? position.entryPrice : await adapter.getLastPrice(position.symbol);
+    if (refPrice != null && refPrice > 0) {
+        if (args.stop_price !== undefined) {
+            const msg = validateStopDirection(entrySide, refPrice, args.stop_price);
+            if (msg)
+                return { error: msg };
+        }
+        if (args.target_price !== undefined) {
+            const msg = validateTargetDirection(entrySide, refPrice, args.target_price);
+            if (msg)
+                return { error: msg };
+        }
+    }
+    // ---- Existing ledger row: classify against the exchange ----
+    const existing = ledger.getBySymbol(position.symbol);
+    let clearedStaleLedgerRow = false;
+    if (existing && !isTerminalBracketState(existing.state)) {
+        let cls = 'unknown';
+        const hasCids = Boolean(existing.slCid || existing.tpCid);
+        if (hasCids) {
+            try {
+                const open = await adapter.getOpenOrders(position.symbol);
+                const liveCids = new Set(open.map(o => o.clientOrderId).filter(Boolean));
+                if ((existing.slCid && liveCids.has(existing.slCid)) || (existing.tpCid && liveCids.has(existing.tpCid))) {
+                    cls = 'live';
+                }
+                else if (open.length > 0) {
+                    cls = 'stale'; // non-empty set positively lacking our cids
+                } // empty set → 'unknown' (d59e51b: empty is never disconfirmation)
+            }
+            catch {
+                cls = 'unknown';
+            }
+        }
+        if (cls === 'unknown') {
+            return {
+                error: `Cannot confirm whether ${position.symbol} brackets are live on Hyperliquid ` +
+                    `(open-orders unavailable, the set came back empty, or the row is in-flight with no ` +
+                    `cids yet). NOT assuming protected and NOT reattaching this cycle. Retry next ` +
+                    `heartbeat; if this persists treat the position as potentially NAKED and verify on ` +
+                    `the exchange. Do NOT record a hold/protected review on the basis of this call.`,
+            };
+        }
+        if (cls === 'live') {
+            if (pricesMatch(args.stop_price, existing.stopPrice)
+                && pricesMatch(args.target_price, existing.targetPrice)) {
+                return {
+                    ok: true,
+                    symbol: position.symbol,
+                    bracket_id: existing.bracketId,
+                    entry_side: entrySide,
+                    stop_price: existing.stopPrice,
+                    target_price: existing.targetPrice,
+                    sl_cid: existing.slCid,
+                    tp_cid: existing.tpCid,
+                    attach_latency_ms: 0,
+                    cancelled_stale_bracket_orders: 0,
+                    cleared_stale_ledger_row: false,
+                    attempts: 0,
+                    idempotent_no_op: true,
+                    note: `Bracket already ${existing.state} on exchange with matching prices — no-op.`,
+                };
+            }
+            return {
+                error: `Bracket already ${existing.state} for ${position.symbol} at ` +
+                    `stop=${existing.stopPrice ?? 'none'} target=${existing.targetPrice ?? 'none'}. ` +
+                    `Use modify_stop / modify_target to change levels, or close_position to exit.`,
+            };
+        }
+        logger.warn(TAG, `HL ledger row for ${position.symbol} is stale (state=${existing.state}; stored cloids not ` +
+            `on exchange, non-empty order set) — forcing terminal to re-attach`);
+        ledger.markState(position.symbol, 'cancelled', {
+            closeReason: 'cancelled_auto',
+            lastError: 'stale_ledger_detected_by_attach_brackets',
+        });
+        clearedStaleLedgerRow = true;
+    }
+    // ---- Orphan cleanup (best-effort; protection beats hygiene) ----
+    let cancelledOrphans = 0;
+    try {
+        cancelledOrphans = await adapter.cancelSymbolBracketLegs(position.symbol);
+    }
+    catch (err) {
+        logger.warn(TAG, `HL orphan cleanup failed for ${position.symbol}: ${formatError(err)}`);
+    }
+    // ---- Register + attach ----
+    const bracketId = generateBracketId();
+    try {
+        coordinator.registerEntry({
+            symbol: position.symbol,
+            side: entrySide,
+            stopPrice: args.stop_price,
+            targetPrice: args.target_price,
+        }, bracketId, buildHlBracketCloid(bracketId, 'entry'));
+    }
+    catch (err) {
+        return { error: `registerEntry failed: ${formatError(err)}` };
+    }
+    let attachResult;
+    try {
+        attachResult = await coordinator.attachOnFill(position.symbol, contracts);
+    }
+    catch (err) {
+        return { error: `attach failed: ${formatError(err)}` };
+    }
+    if (!attachResult.ok) {
+        return {
+            error: `Bracket attach failed after ${attachResult.attempts} attempt(s): ` +
+                `${attachResult.error ?? 'unknown error'}. Position remains open. Try again with ` +
+                `adjusted levels, or close_position to exit.`,
+        };
+    }
+    return {
+        ok: true,
+        symbol: position.symbol,
+        bracket_id: bracketId,
+        entry_side: entrySide,
+        stop_price: args.stop_price,
+        target_price: args.target_price,
+        sl_cid: attachResult.slCid,
+        tp_cid: attachResult.tpCid,
+        attach_latency_ms: attachResult.latencyMs,
+        cancelled_stale_bracket_orders: cancelledOrphans,
+        cleared_stale_ledger_row: clearedStaleLedgerRow,
+        attempts: attachResult.attempts,
+    };
+}
 // Non-terminal bracket states — a row in any of these means brackets are
 // either in-flight or fully live; attach_brackets refuses to clobber them
 // UNLESS the ledger cids don't match any live exchange order (stale row).

package/tools/audit-bracket-protection.js

@@ -17,6 +17,10 @@
 import { parseBracketCid } from '../live/bracket-id.js';
 import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
 import { formatError, logger } from '../logger.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+import { isTerminalBracketState } from '../venues/hyperliquid/hl-bracket-coordinator.js';
+import { parseHlBracketCloid } from '../venues/hyperliquid/hl-cloid.js';
+import { isProtectiveHlOrder } from '../venues/hyperliquid/hl-brackets.js';
 const TAG = 'audit-bracket-protection';
 // Per-symbol verdict history for flicker detection. When audit verdicts
 // transition protected→unprotected→protected repeatedly inside a short
@@ -73,7 +77,12 @@ export async function auditBracketProtectionTool(_args, deps) {
                 positions: entries,
             };
         }
-        // Live mode.
+        // Live mode — venue dispatch (issue #209). The Binance-shaped path below
+        // reads algo-order fields HL doesn't have; on HL it produced permanent
+        // false "unprotected" verdicts (the spiral seed).
+        if (deps.adapter instanceof HyperliquidLiveAdapter) {
+            return auditHlLive(deps.adapter);
+        }
         const live = deps.adapter;
         const ledger = live.getBracketLedger?.() ?? null;
         const bracketsEnabled = ledger !== null;
@@ -525,3 +534,150 @@ function extractTriggerPrice(o) {
     }
     return undefined;
 }
+/**
+ * Hyperliquid live audit (issue #209). Same contracts as the Binance path:
+ * null ≠ empty ({error} on an unavailable read — the agent skips the cycle and
+ * MUST NOT act), and an EMPTY open-orders set against a non-terminal ledger row
+ * WITH cids is unverifiable, never "unprotected" (HL has no zero-weight per-leg
+ * resolver, so the honest floor is the whole-audit {error}). External trigger
+ * legs count as protection (`manual_order_protecting`) via the HL order shape
+ * (isTrigger/reduceOnly/orderType — T-7 fields), mirroring the Binance rule
+ * that a manually-placed stop must never be reported as naked.
+ */
+async function auditHlLive(adapter) {
+    const ledger = adapter.getHlBracketCoordinator().getLedger();
+    const positionsOrNull = await adapter.getPositionsOrNull();
+    if (positionsOrNull === null) {
+        return {
+            error: 'Exchange data unavailable (Hyperliquid fetch failed / rate-gated). Skipping audit ' +
+                'this cycle — bracket state on the exchange is unchanged. Retry on next heartbeat.',
+        };
+    }
+    const activePositions = positionsOrNull.filter(p => Math.abs(Number(p.contracts ?? 0)) > 0);
+    if (activePositions.length === 0) {
+        return {
+            ok: true,
+            mode: 'live',
+            brackets_enabled: true,
+            total_positions: 0,
+            protected_count: 0,
+            unprotected_count: 0,
+            positions: [],
+        };
+    }
+    const entries = [];
+    for (const p of activePositions) {
+        let symbolOrders;
+        try {
+            symbolOrders = await adapter.getOpenOrders(p.symbol);
+        }
+        catch (err) {
+            const m = formatError(err);
+            logger.warn(TAG, `HL audit skipped — open orders unavailable for ${p.symbol}: ${m}`);
+            return {
+                error: `Exchange data unavailable for ${p.symbol} (Hyperliquid open-orders fetch failed). ` +
+                    `Skipping audit this cycle — do NOT run attach_brackets or ` +
+                    `close_position(reason='bracket_integrity') on the basis of this call. Underlying: ${m}`,
+            };
+        }
+        const ledgerRow = ledger.getBySymbol(p.symbol) ?? null;
+        const rowNonTerminalWithCids = !!ledgerRow && !isTerminalBracketState(ledgerRow.state) && Boolean(ledgerRow.slCid || ledgerRow.tpCid);
+        if (symbolOrders.length === 0 && rowNonTerminalWithCids) {
+            // Untrusted-empty contradiction (the SOL/INJ lesson, HL edition): the
+            // ledger says legs are live but the successful fetch shows nothing.
+            // Empty is NOT positive disconfirmation — refuse honestly.
+            return {
+                error: `Cannot confirm bracket protection for ${p.symbol} — the exchange returned an empty ` +
+                    `open-orders set while the ledger row is ${ledgerRow.state} with stored cloids. ` +
+                    `Empty ≠ "brackets gone". Skipping audit this cycle; do NOT run attach_brackets or ` +
+                    `close_position(reason='bracket_integrity'). Retry next heartbeat.`,
+            };
+        }
+        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 ? parseHlBracketCloid(o.clientOrderId) : null;
+            const triggerPrice = extractTriggerPrice(o);
+            const info = o.info ?? {};
+            if (parsed?.role === 'stop') {
+                hasBracketStop = true;
+                stopPrice = triggerPrice ?? stopPrice;
+            }
+            else if (parsed?.role === 'target') {
+                hasBracketTarget = true;
+                targetPrice = triggerPrice ?? targetPrice;
+            }
+            else if (isProtectiveHlOrder(info)) {
+                const t = String(info.orderType ?? o.type ?? '').toLowerCase();
+                if (t.includes('take profit') || t.includes('tp') || t.includes('take_profit')) {
+                    hasManualTarget = true;
+                    targetPrice = triggerPrice ?? targetPrice;
+                }
+                else {
+                    hasManualStop = true;
+                    stopPrice = triggerPrice ?? stopPrice;
+                }
+            }
+        }
+        const hasStop = hasBracketStop || hasManualStop;
+        const hasTarget = hasBracketTarget || hasManualTarget;
+        if (ledgerRow?.stopPrice !== undefined)
+            stopPrice = ledgerRow.stopPrice;
+        if (ledgerRow?.targetPrice !== undefined)
+            targetPrice = ledgerRow.targetPrice;
+        let reason;
+        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 && isTerminalBracketState(ledgerRow.state)) {
+            reason = 'ledger_terminal_no_order';
+        }
+        else {
+            reason = 'no_protective_order';
+        }
+        // ★ T-2 under-coverage: a stop can exist AND still leave scaled-in size
+        // naked (fixed-size legs). Surface it in logs; the adapter's 60s
+        // truth-check sweep auto-resizes.
+        const contracts = Math.abs(Number(p.contracts ?? 0));
+        if (hasBracketStop && ledgerRow?.qty !== undefined && ledgerRow.qty + 1e-8 < contracts) {
+            logger.warn(TAG, `HL audit: ${p.symbol} stop leg sized ${ledgerRow.qty} vs position ${contracts} — ` +
+                'under-covered (T-2); the truth-check sweep will resize');
+        }
+        entries.push({
+            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: ledgerRow?.state ?? 'no_ledger_row',
+            reason,
+            recommended_action: hasStop ? 'none' : 'attach_brackets',
+        });
+    }
+    const nowTs = Date.now();
+    for (const e of entries) {
+        recordVerdictAndCheckFlicker(normalizeBracketSymbol(e.symbol), e.has_stop, nowTs);
+    }
+    const unprotected = entries.filter(e => !e.has_stop).length;
+    return {
+        ok: true,
+        mode: 'live',
+        brackets_enabled: true,
+        total_positions: entries.length,
+        protected_count: entries.length - unprotected,
+        unprotected_count: unprotected,
+        positions: entries,
+    };
+}

package/tools/bracket-control.d.ts

@@ -0,0 +1,12 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { BracketLedger } from '../live/bracket-ledger.js';
+export interface BracketControl {
+    venue: 'binance' | 'hyperliquid';
+    ledger: BracketLedger;
+    modifyStop(symbol: string, newStopPrice: number): Promise<void>;
+    modifyTarget(symbol: string, newTargetPrice: number): Promise<void>;
+}
+/** Resolve the venue's bracket-mutation surface, or null when brackets are
+ *  not enabled (Binance with brackets.mode=off; never null on HL live —
+ *  exchange-side legs are HL live's ONLY protection, so they are always on). */
+export declare function resolveBracketControl(adapter: IExchangeAdapter): BracketControl | null;

package/tools/bracket-control.js

@@ -0,0 +1,35 @@
+// Venue dispatch for the bracket-mutating tools (issue #209).
+//
+// modify_stop / modify_target need one seam: "give me the thing that can move
+// a leg, plus the ledger that knows the current geometry". On Binance that is
+// BracketManager (+ LiveAdapter's ledger); on Hyperliquid it is the
+// HlBracketCoordinator (which owns its own venue-distinct ledger). The tools
+// must never know which venue they are on beyond this resolver — the
+// hard-cast-to-LiveAdapter pattern is exactly what left the HL arm returning
+// "Bracket orders are not enabled" on every call (the #209 recovery gap).
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+/** Resolve the venue's bracket-mutation surface, or null when brackets are
+ *  not enabled (Binance with brackets.mode=off; never null on HL live —
+ *  exchange-side legs are HL live's ONLY protection, so they are always on). */
+export function resolveBracketControl(adapter) {
+    if (adapter instanceof HyperliquidLiveAdapter) {
+        const coordinator = adapter.getHlBracketCoordinator();
+        return {
+            venue: 'hyperliquid',
+            ledger: coordinator.getLedger(),
+            modifyStop: (symbol, px) => coordinator.modifyStop(symbol, px),
+            modifyTarget: (symbol, px) => coordinator.modifyTarget(symbol, px),
+        };
+    }
+    const live = adapter;
+    const mgr = live.getBracketManager?.();
+    const ledger = live.getBracketLedger?.();
+    if (!mgr || !ledger)
+        return null;
+    return {
+        venue: 'binance',
+        ledger,
+        modifyStop: (symbol, px) => mgr.modifyStop(symbol, px),
+        modifyTarget: (symbol, px) => mgr.modifyTarget(symbol, px),
+    };
+}

package/tools/create-order.js

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import { formatError } from '../logger.js';
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
 import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
-import { validateCreateOrder, sanitizeRealizationRule } from './assessment-validation.js';
+import { validateCreateOrder, sanitizeRealizationRule, validateProtectiveGeometry } from './assessment-validation.js';
 import { preTradeRiskCheck, getDefaultPreTradeLimits, computeConsecutiveLosses } from '../risk/pre-trade-check.js';
 import { bracketsEnabled, loadBracketMode, loadBracketRequirements } from '../config/brackets-config.js';
 import { onCreateOrderFilled } from '../ingest/position-auto-capture.js';
@@ -664,8 +664,14 @@ function buildPortfolioSnapshotFromSimulator(simulator) {
 }
 /** Build a PortfolioSnapshot from adapter (live mode). */
 async function buildPortfolioSnapshotFromAdapter(adapter) {
+    // Null-honest balance read where the adapter offers one (LiveAdapter) —
+    // getBalance() collapses a FAILED fetch to a phantom-zero object, which
+    // reads as walletTotal=0 against the real sessionStartNav → ~−100%
+    // drawdown → RED zone rejects the entry for the wrong reason (and sizing
+    // runs against walletAvailable=0).
+    const balanceRead = adapter.getBalanceOrNull?.() ?? adapter.getBalance();
     const [balance, positions] = await Promise.all([
-        adapter.getBalance(),
+        balanceRead,
         adapter.getPositionsOrNull(),
     ]);
     // null = positions fetch FAILED (429 / weight-paced / transient). If we
@@ -678,6 +684,11 @@ async function buildPortfolioSnapshotFromAdapter(adapter) {
         throw new Error('Cannot build portfolio snapshot — position fetch failed (exchange data ' +
             'unavailable, likely Binance 429 or transient). Order NOT placed; retry next heartbeat.');
     }
+    // Same contract for the balance leg: null = fetch failed, NOT a zero wallet.
+    if (balance === null) {
+        throw new Error('Cannot build portfolio snapshot — balance fetch failed (exchange data ' +
+            'unavailable, likely Binance 429 or transient). Order NOT placed; retry next heartbeat.');
+    }
     const walletTotal = getQuoteWalletBalance(balance);
     // Use the session-start NAV captured once at initialization, not the current balance.
     // If not available (shouldn't happen after init), fall back to current balance.
@@ -925,6 +936,23 @@ export async function createOrderTool(args, deps) {
                 return rejectWave9Divergence(`stopPrice is on the wrong side of entry ${orderPrice} for a ${side} order.`, 'actual_market_stop_geometry_diverged');
             }
         }
+        // ---- Generic-path protective geometry gate (issue #200) ----
+        // The wrong-side check above ran ONLY for wave9 orders; a generic entry with
+        // its stop/invalidation on the profit side passed validation and was closed
+        // by the stop-watcher seconds later (7 sub-5-minute kills on the 2026-07 HL
+        // soak — one spawned the −$117.86 journal fabrication of issue #199).
+        if (!wave9Claimed) {
+            const geometryError = validateProtectiveGeometry({
+                side: side,
+                refPrice: orderPrice,
+                stopPrice: args.stopPrice,
+                invalidationPrice: args.invalidation_price,
+                targetPrice: args.target_price,
+            });
+            if (geometryError) {
+                return { error: `create_order rejected (protective geometry): ${geometryError}` };
+            }
+        }
         const proposed = {
             symbol: args.symbol,
             side: side,

package/tools/get-setup-detail.js

@@ -307,5 +307,16 @@ function computeStop(strategy, atr, entryPrice, direction) {
     }
 }
 function roundPrice(p) {
-    return Math.round(p * 100) / 100;
+    // 2 decimals for $1+ prices; below that, 6 significant digits — a flat
+    // 2-decimal round collapses entry/stop/targets onto the same value for the
+    // sub-cent class (1000PEPE/1000SHIB/…, ATR below the $0.01 granularity),
+    // tripping the zero-risk guard and refusing every setup on those symbols.
+    if (!Number.isFinite(p) || p === 0)
+        return p;
+    const abs = Math.abs(p);
+    if (abs >= 1)
+        return Math.round(p * 100) / 100;
+    const decimals = 5 - Math.floor(Math.log10(abs));
+    const f = Math.pow(10, decimals);
+    return Math.round(p * f) / f;
 }

package/tools/modify-stop.js

@@ -5,6 +5,7 @@
 // Paper mode: moves the position's metadata.stopPrice in place (the paper
 // stop-watcher reads it), so BE/trail works without a close+reopen round-trip.
 // Live mode without brackets enabled: error asking operator to enable.
+import { resolveBracketControl } from './bracket-control.js';
 import { validateStopDirection } from '../live/bracket-params.js';
 import { formatError } from '../logger.js';
 import { isWave9ManagedPosition } from '../wave9/paper-admission-guard.js';
@@ -43,12 +44,11 @@ export async function modifyStopTool(args, deps) {
                 };
             }
         }
-        const mgr = deps.adapter.getBracketManager?.();
-        const ledger = deps.adapter.getBracketLedger?.();
-        if (!mgr || !ledger) {
+        const control = resolveBracketControl(deps.adapter);
+        if (!control) {
             return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
         }
-        const entry = ledger.getBySymbol(args.symbol);
+        const entry = control.ledger.getBySymbol(args.symbol);
         if (!entry) {
             return { error: `No active bracket for ${args.symbol}.` };
         }
@@ -62,7 +62,7 @@ export async function modifyStopTool(args, deps) {
                 return { error: msg };
         }
         try {
-            await mgr.modifyStop(args.symbol, args.new_stop_price);
+            await control.modifyStop(args.symbol, args.new_stop_price);
             return {
                 ok: true,
                 symbol: args.symbol,

package/tools/modify-target.js

@@ -1,5 +1,6 @@
 // Tool: modify_target — move the exchange-side take-profit on an open live
 // position. Mirror of modify_stop; see that file for rationale.
+import { resolveBracketControl } from './bracket-control.js';
 import { validateTargetDirection } from '../live/bracket-params.js';
 import { formatError } from '../logger.js';
 import { isWave9ManagedPosition } from '../wave9/paper-admission-guard.js';
@@ -38,12 +39,11 @@ export async function modifyTargetTool(args, deps) {
                 };
             }
         }
-        const mgr = deps.adapter.getBracketManager?.();
-        const ledger = deps.adapter.getBracketLedger?.();
-        if (!mgr || !ledger) {
+        const control = resolveBracketControl(deps.adapter);
+        if (!control) {
             return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
         }
-        const entry = ledger.getBySymbol(args.symbol);
+        const entry = control.ledger.getBySymbol(args.symbol);
         if (!entry) {
             return { error: `No active bracket for ${args.symbol}.` };
         }
@@ -56,7 +56,7 @@ export async function modifyTargetTool(args, deps) {
                 return { error: msg };
         }
         try {
-            await mgr.modifyTarget(args.symbol, args.new_target_price);
+            await control.modifyTarget(args.symbol, args.new_target_price);
             return {
                 ok: true,
                 symbol: args.symbol,

package/tools/scan-pairs.d.ts

@@ -1,4 +1,5 @@
 import type { IntelApiDeps } from './intel-api.js';
+import type { ReentryTracker } from '../portfolio/reentry-tracker.js';
 import type { PositionDecisionsClient } from '../ingest/position-decisions-client.js';
 export interface ScanPairsArgs {
     /** Minimum confluence score (number of conditions met) to include in rankings. */
@@ -9,6 +10,9 @@ export interface ScanPairsArgs {
 export interface ScanPairsDecisionsDeps {
     decisionsClient?: PositionDecisionsClient;
     userId?: string;
+    /** Re-entry tracker (issue #204) — flags setups already traded within the
+     *  current signal bar. Indication only; nothing is filtered out. */
+    reentryTracker?: ReentryTracker;
 }
 export declare function scanPairsTool(args: ScanPairsArgs, deps: IntelApiDeps, decisionsDeps?: ScanPairsDecisionsDeps): Promise<Record<string, unknown> | {
     error: string;

package/tools/scan-pairs.js

@@ -182,15 +182,18 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
     const vetoed = [];
     for (const r of results) {
         const matches = entryLearnings.filter(l => learningMatches(l, r.strategy, r.regime));
+        const agentSymbol = presentIntelSymbol(deps, r.symbol);
+        const reentryCaution = decisionsDeps?.reentryTracker?.cautionFor(agentSymbol, r.strategy);
         const out = {
             // Agent-facing form: on hyperliquid the agent must see the symbol it
             // can hand straight to create_order ('BTC/USDC'), never 'HL_BTC'.
-            symbol: presentIntelSymbol(deps, r.symbol),
+            symbol: agentSymbol,
             score: r.score,
             regime: r.regime,
             strategy: r.strategy,
             conditions: `${r.conditionsMet}/${r.conditionsTotal} met: ${r.conditions.filter(c => c.met).map(c => c.name).join(', ')}`,
             summary: r.summary,
+            ...(reentryCaution ? { reentry_caution: reentryCaution } : {}),
         };
         if (matches.length === 0) {
             rankings.push(out);