@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/simulator/exchange-simulator.js

@@ -205,6 +205,11 @@ export class ExchangeSimulator extends EventEmitter {
                 // Surface entry metadata (if available)
                 ...(p.metadata && {
                     setupType: p.metadata.setupType,
+                    missionId: p.metadata.missionId,
+                    candidateId: p.metadata.candidateId,
+                    strategy: p.metadata.strategy,
+                    accruedFundingUsd: p.metadata.accruedFundingUsd,
+                    fundingThroughTime: p.metadata.fundingThroughTime,
                     thesis: p.metadata.thesis,
                     stopPrice: p.metadata.stopPrice,
                     targetPrice: p.metadata.targetPrice,
@@ -281,11 +286,18 @@ export class ExchangeSimulator extends EventEmitter {
             if (!ticker) {
                 throw new Error(`No ticker data for ${symbol}. Call updateTicker() first.`);
             }
+            // Stale-quote guard (issue #202): a market fill priced off an aged quote
+            // books phantom P&L the moment a fresh price arrives (measured up to
+            // ~0.6% off on the HL paper book — a real −$22.99 in 4 seconds). Reject
+            // instead; the agent refreshes via fetch_ticker and retries.
+            this.assertQuoteFresh(symbol, ticker);
             return this.executeMarketFill(order, ticker.last, metadata);
         }
-        // Limit order — check if it crosses the current price
+        // Limit order — check if it crosses the current price. A stale quote must
+        // not price an immediate cross-fill (same hazard as market fills); the
+        // order RESTS instead and fills on the next fresh tick via updateTicker.
         const ticker = this.lastTicker.get(symbol);
-        if (ticker && this.shouldFillLimit(order, ticker.last)) {
+        if (ticker && this.quoteAgeMs(ticker) <= this.maxQuoteAgeMs() && this.shouldFillLimit(order, ticker.last)) {
             return this.executeLimitFill(order, ticker.last, metadata);
         }
         // Limit order doesn't cross — add to open orders. Pin the entry metadata
@@ -543,6 +555,45 @@ export class ExchangeSimulator extends EventEmitter {
         };
     }
     // ---- Private helpers ----
+    /** Default max quote age a NEW-exposure fill may price against (issue #202).
+     *  Generous vs the 5s paper feed cadence; env RC_PAPER_MAX_QUOTE_AGE_MS
+     *  overrides. */
+    static DEFAULT_MAX_QUOTE_AGE_MS = 45_000;
+    maxQuoteAgeMs() {
+        const raw = Number(process.env.RC_PAPER_MAX_QUOTE_AGE_MS);
+        return Number.isFinite(raw) && raw > 0 ? raw : ExchangeSimulator.DEFAULT_MAX_QUOTE_AGE_MS;
+    }
+    /** Quote age from the ticker's own timestamp. A missing/invalid timestamp
+     *  reads as age 0 (fail-open — the guard cannot fire on it). */
+    quoteAgeMs(ticker) {
+        const ts = ticker.timestamp;
+        if (!Number.isFinite(ts) || ts <= 0)
+            return 0;
+        return Math.max(0, Date.now() - ts);
+    }
+    /** Reject fills that would OPEN or GROW exposure on a stale quote. Risk-
+     *  reducing fills (closes/partials against an existing position) are always
+     *  allowed — blocking a close on a broken feed compounds the risk. */
+    assertQuoteFresh(symbol, ticker) {
+        const age = this.quoteAgeMs(ticker);
+        const max = this.maxQuoteAgeMs();
+        if (age <= max)
+            return;
+        const pos = this.state.positions.find(p => p.symbol === symbol);
+        // The order side reaching here is the one being filled — derive reduce vs
+        // grow from the position side at the call site instead? The market path
+        // calls this before fill with the order side unavailable; use position
+        // presence: any existing position keeps closes flowing, and a stale-quote
+        // scale-in on an open position is bounded by the feed refreshing open
+        // symbols every 5s (only NEW symbols go minutes without a tick).
+        if (pos) {
+            logger.warn(TAG, `Stale quote for ${symbol} (${Math.round(age / 1000)}s old) — allowing fill because an open ` +
+                `position exists (risk-reducing paths are never blocked)`);
+            return;
+        }
+        throw new Error(`Order rejected: market data for ${symbol} is stale (${Math.round(age / 1000)}s old, ` +
+            `max ${Math.round(max / 1000)}s). Refresh the price (fetch_ticker) and retry.`);
+    }
     shouldFillLimit(order, currentPrice) {
         if (order.price === null)
             return false;
@@ -562,6 +613,12 @@ export class ExchangeSimulator extends EventEmitter {
             metadata,
         };
         const result = fillMarketOrder(order, currentPrice, this.state.wallet, position, realistic);
+        // Observability for issue #202: stamp the quote's age onto the fill's
+        // execution-quality record so staleness is visible in trade history.
+        const tickerAtFill = this.lastTicker.get(order.symbol);
+        if (result.executionQuality && tickerAtFill) {
+            result.executionQuality.quoteAgeMs = this.quoteAgeMs(tickerAtFill);
+        }
         const ccxtOrder = this.applyFillResult(result);
         const eq = result.executionQuality;
         if (eq) {
@@ -608,7 +665,25 @@ export class ExchangeSimulator extends EventEmitter {
             fillPrice: result.order.average ?? 0,
             fee: result.order.fee.cost,
         });
-        return this.toCcxtOrder(result.order);
+        const ccxtOrder = this.toCcxtOrder(result.order);
+        // Reducing fills carry a Trade record — attach its engine-exact economics
+        // (net-of-fee P&L + both fee legs) so the journal close capture records
+        // NET, matching the live book's convention (issue #201). The wallet/NAV
+        // was already net; only the journal was blind to fees.
+        if (result.trade) {
+            const t = result.trade;
+            ccxtOrder.info = {
+                ...(ccxtOrder.info ?? {}),
+                paperTrade: {
+                    grossRealizedPnl: t.realizedPnl,
+                    netRealizedPnl: t.realizedPnl - (t.fee + (t.openFee ?? 0)),
+                    openFee: t.openFee ?? 0,
+                    closeFee: t.fee,
+                    ...(typeof t.metadata?.setupType === 'string' ? { setupType: t.metadata.setupType } : {}),
+                },
+            };
+        }
+        return ccxtOrder;
     }
     updatePosition(symbol, newPosition) {
         const idx = this.state.positions.findIndex(p => p.symbol === symbol);

package/simulator/fill-engine.js

@@ -53,7 +53,11 @@ export function parseSymbol(symbol) {
     if (parts.length !== 2) {
         throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE`);
     }
-    return { base: parts[0], quote: parts[1] };
+    const [quote, settle, ...extra] = parts[1].split(':');
+    if (!quote || extra.length > 0 || (settle !== undefined && settle !== quote)) {
+        throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE or BASE/QUOTE:QUOTE`);
+    }
+    return { base: parts[0], quote };
 }
 /**
  * Ensure a currency exists in the wallet with at least zero balance.

package/simulator/types.d.ts

@@ -38,6 +38,10 @@ export interface ExecutionQuality {
     feePaid: number;
     bookLevelsConsumed: number;
     bookDepthAvailable: boolean;
+    /** Age of the quote the fill priced against (fill time − ticker.timestamp).
+     *  Surfaces feed staleness (issue #202); absent on records from before the
+     *  field existed or when the ticker carried no usable timestamp. */
+    quoteAgeMs?: number;
 }
 export interface SimulatorState {
     version: string;
@@ -83,7 +87,7 @@ export interface CurrencyBalance {
  *  - `exchange_stop` / `exchange_target`: exchange-native STOP_MARKET / TAKE_PROFIT_MARKET triggered on Binance
  *  - `cancelled_auto`: bracket reconciler cleaned up after detecting the position closed externally
  *  - `operator` / `agent` / `emergency`: explicit initiator */
-export type CloseReason = 'agent' | 'stop_watcher' | 'emergency' | 'operator' | 'bracket_attach_failed' | 'exchange_stop' | 'exchange_target' | 'cancelled_auto';
+export type CloseReason = 'agent' | 'stop_watcher' | 'emergency' | 'operator' | 'bracket_attach_failed' | 'exchange_stop' | 'exchange_target' | 'cancelled_auto' | 'wave9_signal_reversal' | 'liquidated' | 'adl' | 'venue_delisted';
 /** The agent's stated profit-realization plan, pinned at entry. PURE DATA /
  *  indication — the plugin does NOT enforce it; it is surfaced back so the agent
  *  can hold to its own plan instead of re-litigating. The agent fills the parts
@@ -107,6 +111,11 @@ export interface RealizationRule {
  *  moment of close. */
 export interface PositionMetadata {
     setupType?: string;
+    missionId?: string;
+    candidateId?: string;
+    strategy?: 'tsmom_28d_long_flat_reversal_1d' | 'tsmom_28d_short_flat_reversal_1d';
+    accruedFundingUsd?: number;
+    fundingThroughTime?: string;
     thesis?: string;
     stopPrice?: number;
     targetPrice?: number;

package/skills/reefclaw/SKILL.md

@@ -80,6 +80,8 @@ OpenClaw can install the ReefClaw plugin through its own owner chat command —
 2. Tell the user to type `/restart` in this chat.
 3. Then the user types: `/plugins install clawhub:@reefclaw/openclaw-plugin` — the install restarts OpenClaw automatically; the bundled connector starts by itself and the dashboard flips to Connected.
 
+If that install is **cancelled asking for a ClawHub risk acknowledgement** (OpenClaw 2026.7+ does this; older versions never ask and reject the flag), rerun the identical command with the acknowledgement appended: `/plugins install clawhub:@reefclaw/openclaw-plugin --acknowledge-clawhub-risk`. If it is still refused, use the `npx @reefclaw/connect` fallback — it does not go through ClawHub.
+
 Only fall back to `npx @reefclaw/connect` (below) when the chat install is unavailable.
 
 ## If you cannot run the installer (elevated exec disabled)

package/strategy/evaluator.d.ts

@@ -27,6 +27,8 @@ export interface StrategyConfig {
         params: Record<string, number>;
     };
     targetRMultiples: number[];
+    /** Dedicated portfolio catalog rows are not declarative generic strategies. */
+    executionModel?: string;
 }
 export interface StrategyRow {
     id: number;
@@ -55,6 +57,7 @@ export interface StrategyEvalResult {
     regime_confidence: number;
     summary: string;
 }
+export declare function isDeclarativeStrategyConfig(strategy: StrategyConfig): boolean;
 /**
  * Evaluate a strategy against a symbol's fact object.
  * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.

package/strategy/evaluator.js

@@ -4,12 +4,17 @@
 // and optionally checks threshold-based conditions against indicator values.
 import { CONDITION_EVALUATORS } from './condition-registry.js';
 import { getCachedTradingParams } from '../trading-params-cache.js';
+export function isDeclarativeStrategyConfig(strategy) {
+    return strategy.executionModel === undefined || strategy.executionModel === 'declarative';
+}
 // ─── Evaluator ──────────────────────────────────────────────────────────
 /**
  * Evaluate a strategy against a symbol's fact object.
  * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.
  */
 export function evaluateStrategy(strategy, fact) {
+    if (!isDeclarativeStrategyConfig(strategy))
+        return null;
     // Check regime gate
     if (strategy.regimeWhitelist.length > 0) {
         const matchesRegime = strategy.regimeWhitelist.some(r => r === fact.regime || r === 'ANY');

package/tools/assessment-validation.d.ts

@@ -1,4 +1,25 @@
 import type { RealizationRule } from '../simulator/types.js';
+/** Minimum pre-entry stop distance in basis points (the SKILL v2.10.0
+ *  discipline floor's fixed component; the ATR component is enforced by the
+ *  live bracket path where ATR is authoritative). */
+export declare const MIN_STOP_DISTANCE_BPS = 30;
+export interface ProtectiveGeometryArgs {
+    side: 'buy' | 'sell';
+    /** Reference entry price: the limit price, or last trade for market orders. */
+    refPrice: number;
+    stopPrice?: number;
+    invalidationPrice?: number;
+    targetPrice?: number;
+}
+/** Validate stop / invalidation / target geometry against the entry side.
+ *
+ *  Before this existed the wrong-side check ran ONLY on the wave9 path
+ *  (create-order.ts) — a generic short entered with its stop BELOW entry
+ *  passed validation and was closed by the stop-watcher seconds later
+ *  (7 sub-5-minute kills on the 2026-07 HL soak, issue #200). Returns an
+ *  error string, or null when the geometry is sound. Fields left undefined
+ *  are not judged (stop-required policy stays with the caller). */
+export declare function validateProtectiveGeometry(args: ProtectiveGeometryArgs): string | null;
 /** The five legitimate reasons to manually close an otherwise-bracketed
  *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other
  *  value is rejected. */
@@ -31,6 +52,8 @@ export interface ClosePositionArgs {
     symbol: string;
     reason?: string;
     assessment?: CloseAssessment;
+    candidate_id?: string;
+    wave9_exit_token?: string;
 }
 export interface ValidationResult {
     ok: boolean;

package/tools/assessment-validation.js

@@ -13,6 +13,64 @@
 //                           live mode.
 // Tested in: assessment-validation.test.ts.
 import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+// ---- protective geometry (create_order, issue #200) ----
+/** Minimum pre-entry stop distance in basis points (the SKILL v2.10.0
+ *  discipline floor's fixed component; the ATR component is enforced by the
+ *  live bracket path where ATR is authoritative). */
+export const MIN_STOP_DISTANCE_BPS = 30;
+/** Validate stop / invalidation / target geometry against the entry side.
+ *
+ *  Before this existed the wrong-side check ran ONLY on the wave9 path
+ *  (create-order.ts) — a generic short entered with its stop BELOW entry
+ *  passed validation and was closed by the stop-watcher seconds later
+ *  (7 sub-5-minute kills on the 2026-07 HL soak, issue #200). Returns an
+ *  error string, or null when the geometry is sound. Fields left undefined
+ *  are not judged (stop-required policy stays with the caller). */
+export function validateProtectiveGeometry(args) {
+    const { side, refPrice } = args;
+    if (!Number.isFinite(refPrice) || refPrice <= 0)
+        return null; // no reference — cannot judge
+    const dirWord = side === 'buy' ? 'long' : 'short';
+    if (args.stopPrice !== undefined) {
+        const stop = args.stopPrice;
+        if (!Number.isFinite(stop) || stop <= 0) {
+            return 'stopPrice must be a positive finite number.';
+        }
+        if ((side === 'buy' && stop >= refPrice) || (side === 'sell' && stop <= refPrice)) {
+            return (`stopPrice ${stop} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: a ${dirWord}'s ` +
+                `protective stop must be ${side === 'buy' ? 'below' : 'above'} entry. A wrong-side stop is ` +
+                `instantly "breached" and the stop-watcher closes the position seconds after entry.`);
+        }
+        const distanceBps = (Math.abs(refPrice - stop) / refPrice) * 10_000;
+        if (distanceBps < MIN_STOP_DISTANCE_BPS) {
+            return (`stopPrice ${stop} is only ${distanceBps.toFixed(1)}bps from entry ${refPrice} — below the ` +
+                `${MIN_STOP_DISTANCE_BPS}bps discipline floor. Place the stop at a structural level ` +
+                `(≥ max(0.3×ATR, ${MIN_STOP_DISTANCE_BPS}bps) from entry).`);
+        }
+    }
+    if (args.invalidationPrice !== undefined) {
+        const inv = args.invalidationPrice;
+        if (!Number.isFinite(inv) || inv <= 0) {
+            return 'invalidation_price must be a positive finite number.';
+        }
+        if ((side === 'buy' && inv >= refPrice) || (side === 'sell' && inv <= refPrice)) {
+            return (`invalidation_price ${inv} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
+                `invalidation must be ${side === 'buy' ? 'below' : 'above'} entry (it marks where the thesis ` +
+                `is WRONG, not where it profits). Fix the pinned plan before entering.`);
+        }
+    }
+    if (args.targetPrice !== undefined) {
+        const target = args.targetPrice;
+        if (!Number.isFinite(target) || target <= 0) {
+            return 'target_price must be a positive finite number.';
+        }
+        if ((side === 'buy' && target <= refPrice) || (side === 'sell' && target >= refPrice)) {
+            return (`target_price ${target} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
+                `the profit target must be ${side === 'buy' ? 'above' : 'below'} entry.`);
+        }
+    }
+    return null;
+}
 // ---- close_position ----
 /** The five legitimate reasons to manually close an otherwise-bracketed
  *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other

package/tools/attach-brackets.d.ts

@@ -1,4 +1,6 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
 interface AttachBracketsArgs {
     symbol: string;
     stop_price?: number;
@@ -26,9 +28,12 @@ interface AttachBracketsSuccess {
     idempotent_no_op?: boolean;
     note?: string;
 }
-export declare function attachBracketsTool(args: AttachBracketsArgs, deps: {
+interface AttachBracketsDeps {
     adapter: IExchangeAdapter;
-}): Promise<AttachBracketsSuccess | {
+    operationLock?: TradingOperationLock;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+}
+export declare function attachBracketsTool(args: AttachBracketsArgs, deps: AttachBracketsDeps): Promise<AttachBracketsSuccess | {
     error: string;
 }>;
 export {};

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 ----
@@ -41,6 +44,48 @@ export async function attachBracketsTool(args, deps) {
     if (!deps.adapter.isLive) {
         return { error: 'attach_brackets is live-mode only (it places exchange-side STOP/TP orders). In paper mode, use modify_stop / modify_target to set or move the position\'s protective levels in place — the paper stop-watcher enforces metadata.stopPrice.' };
     }
+    if (deps.checkWave9LiveSymbolOwnership && !deps.operationLock) {
+        return {
+            error: 'Live attach_brackets refused: the shared trading operation lock is required ' +
+                'while Wave 9 LIVE ownership checks are enabled.',
+        };
+    }
+    const attachLive = () => attachBracketsLive(args, deps);
+    try {
+        return deps.operationLock
+            ? await deps.operationLock.withAccountLock(`generic-attach-brackets-final:${args.symbol}`, attachLive)
+            : await attachLive();
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}
+async function attachBracketsLive(args, deps) {
+    if (deps.checkWave9LiveSymbolOwnership) {
+        let ownership;
+        try {
+            ownership = await deps.checkWave9LiveSymbolOwnership(args.symbol);
+        }
+        catch (err) {
+            return {
+                error: `attach_brackets refused at mutation boundary: Wave 9 LIVE ownership check failed ` +
+                    `for ${args.symbol} (${formatError(err)}).`,
+            };
+        }
+        if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+            return {
+                error: `attach_brackets refused at mutation boundary: ${args.symbol} has ` +
+                    `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                    'Wave 9 protection is candidate-bound and cannot be replaced by the generic bracket tool.',
+            };
+        }
+    }
+    // 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?.();
@@ -231,6 +276,162 @@ export async function attachBracketsTool(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).