@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/ingest/reconcile-db-vs-exchange.js

@@ -43,17 +43,10 @@ const TAG = 'reconcile-db-vs-exchange';
 function canonical(symbol) {
     return symbol.split(':')[0];
 }
-/**
- * Close webapp `positions` rows that are status='open' but absent from the
- * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
- *
- * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
- *        !== null). Pass only when the fetch genuinely succeeded.
- */
-export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now()) {
+export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now(), opts = {}) {
     if (!ctx.decisionsClient || !ctx.userId)
         return 0;
-    const resp = await ctx.decisionsClient.getOpenPositions(ctx.userId);
+    const resp = await ctx.decisionsClient.getOpenPositions(ctx.userId, ctx.resolveMode?.(), ctx.resolveExchange?.());
     if (!resp) {
         // null = fetch failed (network / terminal). NEVER treat as "no open rows"
         // (null≠empty) — skip; the next boot / periodic sweep retries.
@@ -77,12 +70,17 @@ export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Da
             logger.warn(TAG, `${o.symbol}: bad size/price from DB (size=${o.remainingSize}, entry=${o.entryPrice}) — skipping close`);
             continue;
         }
+        const lastExitInfo = opts.describeLastExit?.(o.symbol);
+        if (lastExitInfo) {
+            logger.warn(TAG, `${o.symbol}: capture-miss attribution — ${lastExitInfo}`);
+        }
         const close = {
             positionId: o.id,
             closeAt: nowMs,
             closeReason: 'reconciler_observed_flat',
             closeAssessment: {
-                source: 'db_exchange_sweep_boot',
+                source: opts.source ?? 'db_exchange_sweep_boot',
+                ...(lastExitInfo ? { last_engine_trade: lastExitInfo } : {}),
                 synthetic: true,
                 note: 'Position open in DB but absent from the exchange snapshot. It was ' +
                     'closed on-exchange via a path that bypassed close_position (bracket ' +
@@ -112,3 +110,61 @@ export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Da
     }
     return posted;
 }
+// ---- Periodic sweep (issues #199/#203) ----
+//
+// The boot-only sweep left phantoms alive for DAYS between restarts (paper:
+// the LTC phantom of issue #199 lived 26.5h; live: 38 of 85 closes in 14 days
+// were harvested only at the daily restart, issue #203). This interval runs
+// the same DB-authoritative pass continuously with the same trusted-snapshot
+// discipline: getPositionsOrNull() null → skip, never treat as flat.
+export const DEFAULT_DB_RECONCILE_INTERVAL_MS = 300_000;
+const MIN_DB_RECONCILE_INTERVAL_MS = 60_000;
+/** Resolve the sweep interval from RC_DB_RECONCILE_INTERVAL_MS.
+ *  'off' or '0' disables (returns null); values are clamped to ≥60s. */
+export function resolveDbReconcileIntervalMs(raw = process.env.RC_DB_RECONCILE_INTERVAL_MS) {
+    if (raw === 'off' || raw === '0')
+        return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_DB_RECONCILE_INTERVAL_MS;
+    return Math.max(MIN_DB_RECONCILE_INTERVAL_MS, n);
+}
+export function startPeriodicDbReconcile(deps, intervalMs = resolveDbReconcileIntervalMs()) {
+    if (intervalMs === null) {
+        logger.info(TAG, 'periodic sweep disabled (RC_DB_RECONCILE_INTERVAL_MS=off)');
+        return null;
+    }
+    let running = false;
+    const runOnce = async () => {
+        if (running)
+            return 0; // concurrency guard — a slow sweep never overlaps
+        running = true;
+        try {
+            const adapter = deps.resolveAdapter();
+            if (!adapter)
+                return 0;
+            const positions = await adapter.getPositionsOrNull();
+            if (positions === null) {
+                // Untrusted snapshot — NEVER read as flat (null≠empty).
+                logger.warn(TAG, 'periodic sweep skipped — positions fetch untrusted (null)');
+                return 0;
+            }
+            return await reconcileDbOpenVsExchange(deps, positions.map((p) => p.symbol), Date.now(), { source: 'db_exchange_sweep_periodic', describeLastExit: deps.describeLastExit });
+        }
+        catch (err) {
+            logger.warn(TAG, `periodic sweep failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => { void runOnce(); }, intervalMs);
+    // Never keep the process alive just for the sweep.
+    timer.unref?.();
+    logger.info(TAG, `periodic DB-vs-exchange sweep started (interval ${intervalMs}ms)`);
+    return {
+        stop: () => clearInterval(timer),
+        runOnce,
+    };
+}

package/lifecycle/trading-operation-lock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Narrow process-local serialization boundary shared by guarded trading
+ * operations. Account and per-symbol operations intentionally use one queue:
+ * a Wave 9 portfolio transition must be atomic with respect to the legacy
+ * stop watcher, while callers gain no adapter/execution capability from the
+ * lock itself.
+ */
+export interface TradingOperationLock {
+    withAccountLock<T>(operation: string, run: () => Promise<T>): Promise<T>;
+    withSymbolLock<T>(symbol: string, operation: string, run: () => Promise<T>): Promise<T>;
+}
+export declare class SerialTradingOperationLock implements TradingOperationLock {
+    private tail;
+    private enqueue;
+    withAccountLock<T>(_operation: string, run: () => Promise<T>): Promise<T>;
+    withSymbolLock<T>(_symbol: string, _operation: string, run: () => Promise<T>): Promise<T>;
+}

package/lifecycle/trading-operation-lock.js

@@ -0,0 +1,14 @@
+export class SerialTradingOperationLock {
+    tail = Promise.resolve();
+    enqueue(run) {
+        const result = this.tail.then(run, run);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    withAccountLock(_operation, run) {
+        return this.enqueue(run);
+    }
+    withSymbolLock(_symbol, _operation, run) {
+        return this.enqueue(run);
+    }
+}

package/live/bracket-id.d.ts

@@ -1,5 +1,5 @@
-import type { VenueId } from '@reefclaw/shared';
 import type { BracketId, BracketRole } from './bracket-types.js';
+import type { VenueId } from '../venues/symbols.js';
 /** Generate a fresh 16-char hex bracketId. */
 export declare function generateBracketId(): BracketId;
 /** Build a clientOrderId for a given bracket + role. Emits the CURRENT
@@ -17,8 +17,7 @@ export declare function parseBracketCid(cid: string): {
 /** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
  *  — true for both the current and legacy schemes. */
 export declare function isBracketCid(cid: string): boolean;
-/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
- *  parser; other venues return null until their scheme ships. */
+/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
 export declare function parseBracketClientId(venue: VenueId, cid: string): {
     bracketId: BracketId;
     role: BracketRole;

package/live/bracket-id.js

@@ -35,6 +35,7 @@
 // alphanumeric) is well within it. Verified vs developers.binance.com
 // USDⓂ New-Order clientOrderId filter, 2026-05-16.
 import { randomBytes } from 'node:crypto';
+import { parseHlBracketCloid, isHlBracketCloid } from '../venues/hyperliquid/hl-cloid.js';
 // Emitted scheme (no `rc-`, no dashes).
 const CID_REGEX = /^bkt([0-9a-f]{16})([est])$/;
 // Legacy scheme — still parsed for backward compat, never emitted again.
@@ -83,17 +84,29 @@ export function isBracketCid(cid) {
 //
 // ALL bracket client-order-id recognition stays centralized in THIS module —
 // the brackets.md rule ("never hardcode an rc-/bkt regex elsewhere") extends
-// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid client order
-// ids are 128-bit hex cloids with a different scheme (hl-cloid.ts, Phase 3 of
-// docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.7) and will be dispatched from
-// here; until then the hyperliquid arm recognises nothing, which is correct —
-// this build never emits an HL bracket order.
-/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
- *  parser; other venues return null until their scheme ships. */
+// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid = 128-bit hex
+// cloids (`0xbc7…`, hl-cloid.ts §5.7 — a Binance-style ASCII cid is not even a
+// legal HL client id). Phase 3 wires that dispatch HERE, and nowhere else.
+//
+// ★ NEITHER VENUE MAY EVER RECOGNISE THE OTHER'S SCHEME. A false positive is
+//   destructive: `cancelAllOrders` preserves anything that parses as "ours", and
+//   the reconciler cancels/re-attaches on that basis. A foreign id that parsed as
+//   ours would be treated as a protective leg we own.
+/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
 export function parseBracketClientId(venue, cid) {
-    return venue === 'binance' ? parseBracketCid(cid) : null;
+    switch (venue) {
+        case 'binance':
+            return parseBracketCid(cid);
+        case 'hyperliquid':
+            return parseHlBracketCloid(cid);
+    }
 }
 /** Venue-aware isBracketCid. */
 export function isBracketClientId(venue, cid) {
-    return venue === 'binance' ? isBracketCid(cid) : false;
+    switch (venue) {
+        case 'binance':
+            return isBracketCid(cid);
+        case 'hyperliquid':
+            return isHlBracketCloid(cid);
+    }
 }

package/live/fill-price.d.ts

@@ -0,0 +1,13 @@
+/** Minimal order shape needed to resolve a fill price. */
+export interface FillPriceOrder {
+    average: number | null;
+    filled: number;
+    cost: number;
+    /** Present only to make explicit that we deliberately DO NOT read it. */
+    price?: number | null;
+}
+/**
+ * The average price a filled order actually executed at, or null if it can't
+ * be determined from the response. Never returns the limit price.
+ */
+export declare function fillPriceFromOrder(order: FillPriceOrder): number | null;

package/live/fill-price.js

@@ -0,0 +1,37 @@
+// Resolve the ACTUAL average fill price of a (partially) filled order.
+//
+// Issue #196 (prod LTC/USDT 2026-07-14, TAO/USDT 2026-07-15): for marketable
+// LIMIT orders, Binance's synchronous USD-M order response
+// (newOrderRespType=RESULT) can carry avgPrice=0 even though executedQty>0 —
+// per the Binance doc, RESULT only guarantees the final fill for MARKET orders
+// and LIMIT orders with a special timeInForce, NOT a plain GTC LIMIT. Code that
+// then used `order.price` (the LIMIT price) as the entry proxy validated bracket
+// geometry / journaled the entry against a price the order never filled at —
+// several percent off for a marketable limit that crossed. That produced:
+//   - false "bracket direction invalid" auto-flattens (LTC: SELL limit 43 filled
+//     44.49, target 43.21 compared vs 43 → "must be BELOW 43" → needless scratch), and
+//   - wrong journal entry prices (TAO: BUY limit 202 filled ~196.23 → journaled 202).
+//
+// The LIMIT price is NEVER a valid substitute for the fill. This resolver
+// returns the true average fill from the response alone (no network), else null;
+// callers must re-query or fall back to a mark price, never to `order.price`.
+/**
+ * The average price a filled order actually executed at, or null if it can't
+ * be determined from the response. Never returns the limit price.
+ */
+export function fillPriceFromOrder(order) {
+    // 1. The exchange-reported average fill price, when present and positive.
+    if (typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0) {
+        return order.average;
+    }
+    // 2. VWAP from cost/filled. For USD-M futures ccxt maps cost = cumQuote =
+    //    Σ(price×qty), so cost/filled = Σ(price×qty)/Σqty = the exact avgPrice.
+    //    Covers the case where avgPrice=0 in the response but cumQuote settled.
+    if (typeof order.cost === 'number' && Number.isFinite(order.cost) && order.cost > 0 &&
+        typeof order.filled === 'number' && Number.isFinite(order.filled) && order.filled > 0) {
+        return order.cost / order.filled;
+    }
+    // 3. Unknown. The caller MUST NOT fall back to order.price (the limit) — that
+    //    is exactly the marketable-limit bug this helper exists to prevent.
+    return null;
+}

package/live/live-adapter.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
-import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from '../exchange-adapter.js';
+import type { IExchangeAdapter, AdapterReadiness, ClientOrderResolution, OrderOptions } from '../exchange-adapter.js';
 import { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { BinanceAlgoOrderProof } from '../ccxt/binance-private.js';
 import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode, ExchangeConfig } from '../types.js';
 import type { PositionMetadata, CloseReason } from '../simulator/types.js';
 import { ExchangeInfoCache } from './exchange-info-cache.js';
@@ -16,7 +17,7 @@ import { BracketManager } from './bracket-manager.js';
 import { type BracketMode } from '../config/brackets-config.js';
 import { type UserDataStreamMode, type UserDataStreamTunables } from '../config/user-data-stream-config.js';
 import { UserDataStreamController } from './user-data-stream-controller.js';
-import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
+import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
 import type { TradeStoreClient } from '../ingest/trade-store-client.js';
 /** Optional audit-trail wiring (TRADE_AUDIT_TRAIL_PLAN Phase 1).  Caller
  *  passes this only when userDataStream.dbWrite='on' AND the WEBAPP_INGEST_TOKEN
@@ -27,6 +28,16 @@ export interface TradeIngestWiring {
     userId: string;
     exchange?: string;
 }
+export interface Wave9ProtectionLossEvent {
+    source: 'algo_canceled' | 'algo_rejected' | 'reconciler_missing';
+    symbol: string;
+    bracketId: string;
+    entryClientOrderId: string;
+    entrySide: 'buy' | 'sell';
+    stopClientOrderId?: string;
+    detail: string;
+}
+export type Wave9ProtectionLossHandler = (event: Wave9ProtectionLossEvent) => Promise<void> | void;
 /**
  * Backfill `balance.free[cur] = total[cur]` for currencies where Binance's CCXT
  * response left the per-currency `free` and `used` at zero despite a non-zero
@@ -55,6 +66,10 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     private bracketLedger;
     private bracketManager;
     private bracketReconciler;
+    private wave9ProtectionLossHandler?;
+    private readonly wave9ProtectionLossInFlight;
+    private readonly pendingWave9ProtectionLossBySymbol;
+    private static readonly PENDING_WAVE9_PROTECTION_LOSS_CAP;
     private readonly userDataStreamMode;
     private userDataStream;
     private readonly wsAlgoStatusByCid;
@@ -64,6 +79,7 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     private lastIncomeRefreshMs;
     private incomeAnchorUtcDay;
     private liveMetadata;
+    private autoCapture?;
     private _readiness;
     get readiness(): AdapterReadiness;
     /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
@@ -128,6 +144,32 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
      * the subsequent flatten.
      */
     private attachBracketsAsync;
+    /**
+     * Patch `order.average` with the authoritative average fill price when a
+     * filled order came back without one (marketable-limit RESULT quirk, #196).
+     * Re-queries by clientOrderId (GET /fapi/v1/order, weight 1). Best-effort:
+     * on any failure or an unresolvable re-query the order is left as-is —
+     * downstream then falls back to a mark price / skips capture, NEVER to the
+     * limit price. Mutates `order` in place.
+     */
+    private enrichFilledAvgPrice;
+    /**
+     * Journal the close produced by an internal auto-flatten
+     * (`bracket_attach_failed`), so the position row can't orphan as
+     * status='open' (issue #196). These flattens go straight to
+     * `this.closePosition`, bypassing the close_position tool, so
+     * `onClosePositionFilled` never runs for them. Fire-and-forget + fail-open —
+     * never blocks or throws into the flatten path. The entry journal may not be
+     * ready at flatten time (the entry's WS fill can land ~1-2s later), so
+     * `onAutoFlattenClose` polls briefly for the webappPositionId; the boot DB
+     * reconcile sweep is the backstop if the entry never journals.
+     */
+    private captureAutoFlattenClose;
+    /** Install the Wave 9-only autonomous recovery bridge. With no handler,
+     *  every generic bracket lifecycle remains byte-for-byte behaviorally
+     *  unchanged. Runtime reapplies this setter after adapter reconnects. */
+    setWave9ProtectionLossHandler(handler?: Wave9ProtectionLossHandler): void;
+    private notifyWave9ProtectionLoss;
     /**
      * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
      *
@@ -194,6 +236,8 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
      *               fired (TRIGGERED/FINISHED) — only this licenses repair.
      *  'unknown'  = could not get an answer — safe-wait. */
     resolveBracketLegLiveness(cid: string): Promise<'live' | 'terminal' | 'unknown'>;
+    /** Immediate full-shape proof for one exact native conditional order. */
+    resolveBracketLegProof(cid: string): Promise<BinanceAlgoOrderProof | null>;
     /** Symbol-scoped generalization of the trusted-WS fast-path — the
      *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
      *
@@ -237,6 +281,16 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
      *  drift shape (re-emitted upstream as `bracket_drift`) plus a loud log so
      *  the operator knows re-protection is required. */
     private reattachBracketsAfterFailedClose;
+    /** Null-honest balance read: null = the fetch FAILED (429 / weight-paced /
+     *  banned) — the caller MUST treat it as UNKNOWN, never as a zero balance.
+     *  Same null≠empty contract as getPositionsOrNull. Decision paths (sizing,
+     *  pre-trade risk) must use this: the legacy getBalance() collapse below
+     *  reads as walletTotal=0 → ~−100% drawdown → RED zone. */
+    getBalanceOrNull(): Promise<CcxtBalance | null>;
+    /** Legacy display-path read. Collapses a FAILED fetch to an empty balance
+     *  object — acceptable for read-only surfaces (fetch_balance tool,
+     *  risk-summary display), a phantom-zero hazard for anything that decides.
+     *  Decision paths use getBalanceOrNull(). */
     getBalance(): Promise<CcxtBalance>;
     /** Re-anchor the realized-today seed + sessionStartNav from /fapi/v1/income.
      *  Throttled to {@link INCOME_REFRESH_MIN_INTERVAL_MS}; UTC date rollover
@@ -256,6 +310,7 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     private decoratePositionsWithMetadata;
     getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    resolveOrderByClientId(clientOrderId: string, symbol: string): Promise<ClientOrderResolution>;
     getLastPrice(symbol: string): Promise<number | null>;
     /** Sync rate limiter from exchange response headers after every private API call. */
     private syncRateLimits;