@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/tools/attach-brackets.js

@@ -1,399 +0,0 @@
-// Tool: attach_brackets — bootstrap exchange-side protection on an existing
-// open live position that is currently naked (no STOP_MARKET / TAKE_PROFIT_MARKET
-// order). Complements modify_stop / modify_target, which can only MOVE an
-// already-active bracket — they can't attach one from nothing.
-//
-// Why this tool exists (2026-04-21 naked-position incident): kill-switch
-// sweeps were stripping bracket protective orders off open positions without
-// flattening them. The agent then had no recovery path because modify_*
-// requires state ∈ {active, partial}. This tool + the bracket-preserving
-// cancel filter in BinancePrivateApi together close the loop.
-//
-// Responsibilities:
-//   1. Validate inputs + mode (live only, brackets enabled).
-//   2. Confirm an open position exists with >0 contracts.
-//   3. Sanity-check stop / target direction vs the position side.
-//   4. Reject if a fresh bracket is already active (caller wants modify_*).
-//   5. Clear any stale bracket orders on the exchange for this symbol.
-//   6. Register a new bracket + attach it. Retries inherit BracketManager policy.
-//
-// Paper mode: rejected with an explanatory error (paper uses per-position
-// metadata + stop-watcher, not exchange orders).
-import { generateBracketId, buildBracketCid } from '../live/bracket-id.js';
-import { validateStopDirection, validateTargetDirection } from '../live/bracket-params.js';
-import { formatError, logger } from '../logger.js';
-const TAG = 'attach-brackets';
-export async function attachBracketsTool(args, deps) {
-    // ---- 1. Argument validation ----
-    if (!args.symbol || typeof args.symbol !== 'string') {
-        return { error: 'symbol is required.' };
-    }
-    if (args.stop_price === undefined && args.target_price === undefined) {
-        return { error: 'at least one of stop_price or target_price must be provided.' };
-    }
-    if (args.stop_price !== undefined && (!Number.isFinite(args.stop_price) || args.stop_price <= 0)) {
-        return { error: 'stop_price must be a positive finite number.' };
-    }
-    if (args.target_price !== undefined && (!Number.isFinite(args.target_price) || args.target_price <= 0)) {
-        return { error: 'target_price must be a positive finite number.' };
-    }
-    // ---- 2. Mode gate ----
-    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.',
-            };
-        }
-    }
-    const live = deps.adapter;
-    const mgr = live.getBracketManager?.();
-    const ledger = live.getBracketLedger?.();
-    if (!mgr || !ledger) {
-        return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
-    }
-    // ---- 3. Position must exist ----
-    // getPositionsOrNull() returns null when the fetch FAILED (429 / weight-
-    // paced / transient) — position state is UNKNOWN, NOT "no position". If
-    // we collapsed null→[] here, attach_brackets would tell the agent "No open
-    // position" for a position that is actually live and NAKED on Binance; the
-    // agent reads that as "nothing to protect", stops trying, and the naked
-    // position rides unprotected. Distinct error → agent retries next
-    // heartbeat. Same null≠empty contract as audit/closePosition/flatten.
-    const positions = await deps.adapter.getPositionsOrNull(args.symbol);
-    if (positions === null) {
-        return {
-            error: `Exchange data unavailable for ${args.symbol} (likely Binance 429 or transient ` +
-                `network) — position state UNKNOWN. NOT treating this as "no position"; ` +
-                `bracket attach skipped this cycle. Retry on next heartbeat.`,
-        };
-    }
-    const position = positions.find(p => p.symbol === args.symbol) ?? positions[0];
-    if (!position || position.contracts <= 0) {
-        return { error: `No open position for ${args.symbol}.` };
-    }
-    const entrySide = position.side === 'long' ? 'buy' : 'sell';
-    // ---- 4. Direction sanity check vs entry price ----
-    const refPrice = position.entryPrice > 0 ? position.entryPrice : await deps.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 };
-        }
-    }
-    // ---- 5. Handle existing ledger row ----
-    // If the ledger has a non-terminal row AND its stored SL/TP cids correspond
-    // to live exchange orders, a fresh bracket really is active. Two sub-cases:
-    //   (a) Caller passed the SAME prices the ledger already stores → idempotent
-    //       no-op success. This is the agent's defensive re-attach pattern: it
-    //       sees a flickery audit verdict, calls attach_brackets to "repair",
-    //       passes the same stop/target it remembers from the entry. Pre-fix
-    //       this returned an error, the agent escalated to close_position
-    //       (bracket_integrity), and we lost ~$3 of bracket-integrity flushes
-    //       on 2026-05-15. With idempotency, the defensive re-call costs
-    //       nothing and the position survives.
-    //   (b) Caller passed DIFFERENT prices → they want to change levels. Point
-    //       them at modify_stop / modify_target so we don't have two paths
-    //       that mutate the bracket geometry.
-    //
-    // If the ledger is non-terminal but the cids do NOT match any live exchange
-    // order, the row is stale (exchange brackets got cancelled out-of-band,
-    // plugin restart + lost attach, etc.). Force the row terminal so
-    // registerEntry below can seed a fresh pending_entry. Without this, stale
-    // rows deadlock recovery: audit reports has_stop=false (no exchange match),
-    // attach refuses (ledger says active), agent can't resolve. Incident:
-    // 2026-04-21 ADA death loop — 12 cycles panic-closed in 3 hours.
-    const existing = ledger.getBySymbol(position.symbol);
-    let clearedStaleLedgerRow = false;
-    if (existing && NON_TERMINAL_STATES.has(existing.state)) {
-        // Tri-state classification. `unknown` means we COULD NOT positively
-        // confirm the ledger's cids against live exchange orders — getOpenOrders
-        // threw (429 / weight-paced / sticky cooldown), OR the row has no cids to
-        // check (in-flight pending_entry/attaching). We must NOT collapse
-        // "unverifiable" into "live" — doing so makes attach_brackets return
-        // idempotent_no_op / "already active" for a position that is actually
-        // NAKED on the exchange, and the agent files a complacent hold/protected
-        // review on an unprotected live position. 2026-05-15 NEAR incident: a
-        // weight-paced getOpenOrders → verifyLedgerStale safe-defaulted to "not
-        // stale" → idempotent_no_op on an `attaching` row whose brackets were
-        // never placed. Same null≠empty / never-coerce-unverifiable-to-a-positive-
-        // safety-claim contract as getOpenOrders / getPositions / closePosition.
-        const cls = await classifyLedgerVsExchange(live, position.symbol, existing.slCid, existing.tpCid);
-        if (cls === 'unknown') {
-            logger.warn(TAG, `CANNOT CONFIRM bracket protection for ${position.symbol}: ledger row ` +
-                `state=${existing.state} (slCid=${existing.slCid ?? '-'}, tpCid=${existing.tpCid ?? '-'}) ` +
-                `but getOpenOrders unavailable or no cids to verify. Refusing to claim ` +
-                `protected; NOT clearing/reattaching (could race an in-flight attach).`);
-            return {
-                error: `Cannot confirm whether ${position.symbol} brackets are live on the exchange ` +
-                    `(getOpenOrders unavailable — Binance 429 / weight-paced / transient — or the ` +
-                    `ledger row is still in-flight with no cids yet). NOT assuming the position is ` +
-                    `protected and NOT reattaching this cycle. Retry on the next heartbeat. If this ` +
-                    `persists, treat the position as potentially NAKED: verify on the exchange and ` +
-                    `place a manual stop. Do NOT record a hold/protected review on the basis of this call.`,
-            };
-        }
-        if (cls === 'live') {
-            // Idempotency check: same protection levels = no-op success.
-            if (pricesMatch(args.stop_price, existing.stopPrice)
-                && pricesMatch(args.target_price, existing.targetPrice)) {
-                logger.info(TAG, `idempotent no-op for ${position.symbol}: bracket already ${existing.state} ` +
-                    `at stop=${existing.stopPrice ?? 'none'} target=${existing.targetPrice ?? 'none'} ` +
-                    `(slCid=${existing.slCid ?? '-'}, tpCid=${existing.tpCid ?? '-'})`);
-                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. If the audit reports has_stop=false anyway, suspect audit unreliability, not protection loss.`,
-                };
-            }
-            return {
-                error: `Bracket already ${existing.state} for ${position.symbol} ` +
-                    `at stop=${formatPrice(existing.stopPrice)} target=${formatPrice(existing.targetPrice)}. ` +
-                    `Use modify_stop / modify_target to change levels, or close_position to exit.`,
-            };
-        }
-        logger.warn(TAG, `Ledger row for ${position.symbol} is stale (state=${existing.state}, slCid=${existing.slCid}, tpCid=${existing.tpCid} not on exchange); forcing terminal to re-attach`);
-        try {
-            ledger.markState(position.symbol, 'cancelled', {
-                closeReason: 'cancelled_auto',
-                lastError: 'stale_ledger_detected_by_attach_brackets',
-            });
-            clearedStaleLedgerRow = true;
-        }
-        catch (err) {
-            return { error: `failed to clear stale ledger row: ${formatError(err)}` };
-        }
-    }
-    // ---- 6. Clear any stale bracket orders on the exchange for this symbol ----
-    // The ledger row (if any) is terminal at this point; its stored SL/TP cids
-    // may or may not still be live on the exchange. Orphan bracket orders not
-    // tracked by the ledger may also exist. Cancel all bracket-cid orders on
-    // this symbol so only our fresh pair remains after attach.
-    let cancelledOrphans = 0;
-    try {
-        cancelledOrphans = await live.cancelSymbolBracketOrders(position.symbol);
-    }
-    catch (err) {
-        logger.warn(TAG, `orphan cleanup failed for ${position.symbol}: ${formatError(err)}`);
-    }
-    // ---- 7. Register + attach ----
-    // BracketManager.registerEntry auto-clears terminal rows for the same symbol
-    // (see ledger-hygiene change landed alongside this tool).
-    const bracketId = generateBracketId();
-    try {
-        mgr.registerEntry({
-            symbol: position.symbol,
-            side: entrySide,
-            stopPrice: args.stop_price,
-            targetPrice: args.target_price,
-        }, bracketId, buildBracketCid(bracketId, 'entry'));
-    }
-    catch (err) {
-        return { error: `registerEntry failed: ${formatError(err)}` };
-    }
-    let attachResult;
-    try {
-        attachResult = await mgr.attachBrackets(position.symbol, position.contracts);
-    }
-    catch (err) {
-        return { error: `attachBrackets threw: ${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 || (!!existing && !NON_TERMINAL_STATES.has(existing.state)),
-        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).
-const NON_TERMINAL_STATES = new Set([
-    'pending_entry',
-    'attaching',
-    'active',
-    'partial',
-]);
-/** Classify a non-terminal ledger row against live exchange open orders.
- *
- *  - `'live'`    — getOpenOrders SUCCEEDED and at least one stored cid is
- *                  positively present in the live open orders. Only this
- *                  result may produce an idempotent_no_op / "already active"
- *                  reply: protection is PROVEN on the exchange.
- *  - `'stale'`   — getOpenOrders SUCCEEDED and NONE of the stored cids are
- *                  present. The exchange definitively does not have our
- *                  brackets → clear the row and re-attach.
- *  - `'unknown'` — we could NOT positively verify: getOpenOrders threw
- *                  (429 / weight-paced / sticky cooldown / transient), OR the
- *                  row has no cids to check (in-flight pending_entry/attaching
- *                  whose attach hasn't assigned cids yet). We must NOT treat
- *                  this as `live` (false "protected" on a possibly-naked
- *                  position — the 2026-05-15 NEAR incident) NOR as `stale`
- *                  (clearing + reattaching could race a genuine in-flight
- *                  attach and double up). The caller refuses honestly and
- *                  tells the agent to retry / verify manually.
- *
- *  Same null≠empty / never-coerce-unverifiable-into-a-positive-safety-claim
- *  contract as getOpenOrders / getPositions / closePosition / the reconciler. */
-async function classifyLedgerVsExchange(live, symbol, slCid, tpCid) {
-    if (!slCid && !tpCid)
-        return 'unknown';
-    // Cheap positive check first: a stored cid present in a SUCCESSFUL,
-    // non-empty getOpenOrders is immediate, zero-extra-weight proof of life.
-    // This keeps the common happy-path free. A throw or an empty set is NOT
-    // disconfirmation — fall through to the authoritative per-leg resolver.
-    try {
-        const openOrders = await live.getOpenOrders(symbol);
-        const liveCids = new Set();
-        for (const o of openOrders) {
-            if (o.clientOrderId)
-                liveCids.add(o.clientOrderId);
-        }
-        if ((slCid && liveCids.has(slCid)) || (tpCid && liveCids.has(tpCid))) {
-            return 'live';
-        }
-    }
-    catch (err) {
-        logger.warn(TAG, `classifyLedgerVsExchange: getOpenOrders(${symbol}) unavailable ` +
-            `(${formatError(err)}) — deferring to the per-leg liveness resolver, ` +
-            `NOT assuming protected or stale`);
-    }
-    // No positive snapshot match (empty, threw, or non-empty-without-our-cids).
-    // The SOL/INJ spiral root: a *successful* empty /fapi/v1/openAlgoOrders is
-    // NOT proof a leg is gone. Ask the authoritative per-leg resolver instead
-    // of inferring from absence — trusted-WS fast-path → weight-1 REST
-    // /fapi/v1/algoOrder → 'unknown' floor:
-    //   any leg 'live'                 → 'live'  (do NOT clobber)
-    //   ALL present legs 'terminal'    → 'stale' (POSITIVELY confirmed gone —
-    //                                    the only state that licenses repair)
-    //   otherwise (any 'unknown')      → 'unknown' (d59e51b safe floor)
-    const cids = [slCid, tpCid].filter((c) => !!c);
-    const verdicts = await Promise.all(cids.map(c => live.resolveBracketLegLiveness(c)));
-    if (verdicts.some(v => v === 'live'))
-        return 'live';
-    if (verdicts.length > 0 && verdicts.every(v => v === 'terminal')) {
-        // #2 — AUTHORITATIVE action-layer spiral guard (2026-05-16 INJ).
-        // The LEDGER's cids are positively terminal — but that is NOT proof the
-        // position is unprotected. A prior reattach's FRESH bracket may be live
-        // on the exchange under a NEW cid the ledger never caught up to.
-        // Returning 'stale' here licenses the clear+reattach that cancels that
-        // live bracket → naked → audit unprotected → attach → spiral. Before
-        // licensing repair, positively prove NO other rc-* leg for this symbol
-        // is live. Only positive evidence licenses the destructive action —
-        // same invariant as d59e51b / getOpenOrders / the reconciler.
-        const sweep = live.findTrustedLiveBracketCidsForSymbol(symbol);
-        if (sweep.trusted && sweep.liveCids.length > 0) {
-            logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} ledger cids (slCid=${slCid ?? '-'}, ` +
-                `tpCid=${tpCid ?? '-'}) are terminal BUT the trusted WS shows live ` +
-                `rc-* leg(s) under other cid(s) [${sweep.liveCids.join(', ')}] — a prior ` +
-                `reattach's fresh bracket is live and the ledger row lagged. Returning ` +
-                `'live' (NOT 'stale') to break the clear+reattach spiral; the position ` +
-                `IS protected on the exchange.`);
-            return 'live';
-        }
-        if (!sweep.trusted) {
-            // WS store untrusted → we cannot rule out a live fresh bracket under
-            // an untracked cid using the zero-weight signal, and the spiral REST
-            // is weight-paced. Refuse the destructive 'stale' (retry next cycle);
-            // a genuinely-naked position is still caught by the reconciler /
-            // ALGO_UPDATE / audit backstops. Worst case is a one-cycle delayed
-            // repair — far safer than cancelling a live bracket on a false 'stale'.
-            logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} ledger cids REST-confirmed terminal ` +
-                `but the WS store is UNTRUSTED — cannot positively rule out a live fresh ` +
-                `bracket under an untracked cid (weight-paced REST can't either). ` +
-                `Returning 'unknown' (NOT 'stale'); no force-reattach this cycle.`);
-            return 'unknown';
-        }
-        logger.info(TAG, `classifyLedgerVsExchange: ${symbol} legs POSITIVELY confirmed terminal ` +
-            `via per-leg resolver AND the trusted WS shows no other live rc-* leg ` +
-            `(slCid=${slCid ?? '-'}, tpCid=${tpCid ?? '-'}) — 'stale', safe to ` +
-            `clear+reattach.`);
-        return 'stale';
-    }
-    logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} bracket liveness UNVERIFIABLE ` +
-        `(slCid=${slCid ?? '-'}, tpCid=${tpCid ?? '-'}; verdicts=${JSON.stringify(verdicts)}) ` +
-        `— returning 'unknown', NOT 'stale'. No force-reattach this cycle.`);
-    return 'unknown';
-}
-/** Compare a requested price against the ledger's stored price for the same
- *  bracket leg. Match means: both undefined (caller didn't ask for that leg
- *  and ledger doesn't have it) OR both defined within 0.01% relative
- *  tolerance (covers exchange rounding of trigger prices vs the operator's
- *  request). Any other shape is a mismatch — interpret as the caller wanting
- *  to CHANGE the level, route to modify_*. */
-function pricesMatch(requested, stored) {
-    if (requested === undefined && stored === undefined)
-        return true;
-    if (requested === undefined || stored === undefined)
-        return false;
-    if (!Number.isFinite(requested) || !Number.isFinite(stored))
-        return false;
-    if (stored === 0)
-        return requested === 0;
-    return Math.abs(requested - stored) / Math.abs(stored) <= 1e-4;
-}
-function formatPrice(p) {
-    return p === undefined ? 'none' : String(p);
-}

package/assets/plugin/tools/audit-bracket-protection.d.ts

@@ -1,49 +0,0 @@
-import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { BracketState } from '../live/bracket-types.js';
-type ProtectionReason = 'bracket_active' | 'manual_order_protecting' | 'no_protective_order' | 'brackets_disabled' | 'stale_ledger_row' | 'ledger_terminal_no_order';
-interface PositionAuditEntry {
-    symbol: string;
-    side: 'long' | 'short';
-    contracts: number;
-    entry_price: number;
-    mark_price: number;
-    has_stop: boolean;
-    has_target: boolean;
-    stop_price?: number;
-    target_price?: number;
-    ledger_state: BracketState | 'no_ledger_row';
-    reason: ProtectionReason;
-    recommended_action: 'none' | 'attach_brackets' | 'close_position' | 'enable_brackets_mode';
-}
-interface AuditBracketProtectionResult {
-    ok: true;
-    mode: 'paper' | 'live';
-    brackets_enabled: boolean;
-    total_positions: number;
-    protected_count: number;
-    unprotected_count: number;
-    positions: PositionAuditEntry[];
-}
-export declare function auditBracketProtectionTool(_args: Record<string, never>, deps: {
-    adapter: IExchangeAdapter;
-}): Promise<AuditBracketProtectionResult | {
-    error: string;
-}>;
-/** Public getter — returns the recent audit verdict samples for a symbol so
- *  close_position can copy them into the position's close record for the
- *  dashboard Position Timeline drawer. Read-only snapshot; mutating the
- *  return value does not affect internal state. */
-export declare function getRecentAuditVerdictHistory(symbol: string): ReadonlyArray<{
-    ts: number;
-    protected: boolean;
-}>;
-/** Test seam — clears the in-memory flicker history between unit tests. */
-export declare const __testing__: {
-    resetFlickerHistory(): void;
-    /** Inspect current history for a symbol — used by tests to assert state. */
-    getHistory(symbol: string): ReadonlyArray<{
-        ts: number;
-        protected: boolean;
-    }>;
-};
-export {};