@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/ingest/position-auto-capture.js

@@ -0,0 +1,709 @@
+// Auto-capture helper for the Position Decision Journal.
+//
+// Wires create_order / close_position / fill events into the webapp ingest:
+//
+//   ENTRY  — onCreateOrderFilled() upserts the parent positions row, gets back
+//             the UUID, persists it locally for restart-survival, then posts the
+//             entry decision row.
+//   CLOSE  — onClosePositionFilled() looks up the cached position UUID and posts
+//             the close decision row. Local position-state is dropped after the
+//             dispatch so the symbol can re-enter cleanly.
+//
+// Auto-capture is mode-agnostic — it runs whenever the decisions client is
+// configured (env vars present), regardless of trading mode (PAPER vs LIVE) or
+// positionReview.mode. Fail-open: a network blip on a webapp POST does not
+// block the trading hot path.
+//
+// PR 1 scope: market orders (immediate fill detection from CcxtOrder.filled).
+// Limit-order fill capture and scale-in detection are deferred to a follow-up
+// that hooks into the WS-ingest pipeline (see POSITION_DECISION_JOURNAL_PLAN
+// §5.1 for the longer-term design).
+import { logger } from '../logger.js';
+import { isBracketCid } from '../live/bracket-id.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+import { fillPriceFromOrder } from '../live/fill-price.js';
+const TAG = 'position-auto-capture';
+/** Flatness tolerance for remaining-contracts tracking. Reduce-only fills sum
+ *  exactly to the position size on Binance, so any residual below this is noise
+ *  / float rounding and means the position is flat. */
+const FLAT_EPSILON = 1e-6;
+/** Extract the simulator's engine-exact trade economics from a close order,
+ *  with strict numeric guards (absent on live orders → undefined). */
+export function extractPaperTrade(order) {
+    const raw = order?.info?.['paperTrade'];
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    const gross = num(raw['grossRealizedPnl']);
+    const net = num(raw['netRealizedPnl']);
+    if (gross === undefined || net === undefined)
+        return undefined;
+    return {
+        grossRealizedPnl: gross,
+        netRealizedPnl: net,
+        openFee: num(raw['openFee']) ?? 0,
+        closeFee: num(raw['closeFee']) ?? 0,
+        setupType: typeof raw['setupType'] === 'string' ? raw['setupType'] : undefined,
+    };
+}
+/** Stale-state probe: does the exchange position for `symbol` consist entirely
+ *  of the just-filled quantity? 'stale' → the tracked prior exposure no longer
+ *  exists (closed outside the journal); 'active' → genuine scale-in;
+ *  'unknown' → cannot tell (null fetch etc.) — callers keep legacy behaviour. */
+async function probeStaleStateEntry(ctx, symbol, filledQty) {
+    const adapter = ctx.resolveAdapter?.();
+    if (!adapter)
+        return 'unknown';
+    let positions;
+    try {
+        positions = await adapter.getPositionsOrNull(symbol);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (positions === null)
+        return 'unknown';
+    const key = normalizeBracketSymbol(symbol);
+    const pos = positions.find((p) => normalizeBracketSymbol(p.symbol) === key);
+    const contracts = Math.abs(Number(pos?.contracts));
+    if (!pos || !Number.isFinite(contracts) || contracts <= 0)
+        return 'unknown';
+    const tolerance = Math.max(1e-9, contracts * 0.001);
+    return Math.abs(contracts - filledQty) <= tolerance ? 'stale' : 'active';
+}
+/** Called after a successful adapter.createOrder().
+ *
+ *  For PR 1, we treat any non-zero `filled` quantity as an entry event and
+ *  upsert the parent position + post the entry decision row. Limit orders that
+ *  haven't filled yet are skipped (caller can call us again from the WS-ingest
+ *  pipeline once they fill — that wiring is the follow-up).
+ *
+ *  Always-fail-open: webapp errors are logged but never thrown.
+ */
+export async function onCreateOrderFilled(ctx, inputs, order) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
+        ? order.filled
+        : 0;
+    if (filledQty <= 0) {
+        // Limit order not yet filled — nothing to capture yet.
+        return;
+    }
+    // Resolve the ACTUAL average fill — never order.price (the limit). A
+    // marketable limit can fill percent-scale away from its limit, and the
+    // synchronous RESULT response sometimes omits avgPrice on a filled limit
+    // (issue #196: TAO journaled 202 vs a real 196.23 fill). The adapter
+    // re-queries to enrich order.average before we get here; if it's still
+    // unresolvable we SKIP rather than journal the wrong (limit) price — the
+    // WS-driven onWsFillObserved path re-captures the entry with the real fill.
+    const fillPrice = fillPriceFromOrder(order);
+    if (fillPrice === null) {
+        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: fill price unresolvable (avg=${order.average ?? 'null'} cost=${order.cost} filled=${order.filled}); skipping capture (WS fill path will re-capture with the real price)`);
+        return;
+    }
+    // Need v2.10.0 metadata to build a meaningful entry row. In paper mode the
+    // agent may omit them; we still capture an entry but mark missing fields.
+    const md = inputs.metadata;
+    if (!md) {
+        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: no metadata; skipping (paper without rationale)`);
+        return;
+    }
+    const positionSide = inputs.side === 'buy' ? 'long' : 'short';
+    const openedAtMs = Date.now();
+    // State-store already knows this symbol. Three cases (issue #199):
+    //   STALE   — the exchange position is exactly this fill, so the tracked
+    //             prior exposure was closed outside the journal (stop-watcher /
+    //             manual). Drop the stale mapping and journal a NEW position;
+    //             stitching onto it fabricates P&L against the old entry.
+    //   SCALE-IN (paper) — genuine add. Paper has no WS fill stream, so the old
+    //             "deferred to v2" early-return silently dropped every paper
+    //             scale-in; journal an is_scale_in entry row here instead.
+    //   SCALE-IN (live)  — keep deferring to onWsFillObserved (it captures
+    //             scale-ins with WS-exact data; capturing here would double-post).
+    const existing = ctx.stateStore.get(inputs.symbol);
+    if (existing) {
+        const probe = await probeStaleStateEntry(ctx, inputs.symbol, filledQty);
+        if (probe === 'stale') {
+            logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: state-store entry (openedAt=${existing.openedAt}) is STALE — ` +
+                `exchange position equals this fill (${filledQty}); prior exposure closed outside the journal. ` +
+                `Dropping stale mapping and journaling a NEW position (issue #199).`);
+            ctx.stateStore.remove(inputs.symbol);
+            // fall through to the new-position path below
+        }
+        else if (ctx.resolveMode?.() !== 'paper') {
+            logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: existing position in state-store (openedAt=${existing.openedAt}); scale-in captured by the WS fill path`);
+            return;
+        }
+        else if (existing.side !== positionSide) {
+            // Opposite-side paper fill on a tracked position = partial/soft flatten
+            // that bypassed close_position. Don't guess — the close paths + periodic
+            // sweep own this.
+            logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: opposite-side fill on tracked ${existing.side} position — skipping (use close_position)`);
+            return;
+        }
+        else {
+            if (!existing.webappPositionId) {
+                logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: paper scale-in but no webappPositionId yet — skipping entry row`);
+                return;
+            }
+            const entry = buildEntryPayload({
+                positionId: existing.webappPositionId,
+                isScaleIn: true,
+                ts: openedAtMs,
+                fillPrice,
+                fillSize: filledQty,
+                exchangeTradeId: typeof order.id === 'string' ? order.id : '',
+                metadata: md,
+            });
+            ctx.decisionsClient.postEntry(ctx.userId, entry);
+            ctx.stateStore.addOpenContracts(inputs.symbol, filledQty);
+            logger.info(TAG, `scale-in captured (paper) ${inputs.symbol} ${positionSide} ${filledQty} @ ${fillPrice} ` +
+                `(positionId=${existing.webappPositionId.slice(0, 8)}…)`);
+            return;
+        }
+    }
+    // Local state-store first — ensures restart-survival even if the webapp POST
+    // fails on the first attempt.
+    ctx.stateStore.upsert({
+        symbol: inputs.symbol,
+        openedAt: openedAtMs,
+        side: positionSide,
+        openedFromExchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+        setupType: md.setupType,
+    });
+    const upsert = {
+        symbol: inputs.symbol,
+        positionOpenAt: openedAtMs,
+        side: positionSide,
+        currentSize: filledQty,
+        avgEntryPrice: fillPrice,
+        mode: ctx.resolveMode?.(),
+        exchange: ctx.venue,
+    };
+    // postPosition is awaited — we need the UUID before posting the entry row.
+    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
+    if (!positionId) {
+        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: webapp position upsert returned no id; entry row will not be posted (will retry on next observation)`);
+        return;
+    }
+    ctx.stateStore.setWebappId(inputs.symbol, positionId);
+    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
+    ctx.stateStore.addOpenContracts(inputs.symbol, filledQty);
+    // Build entry decision payload from the v2.10.0 metadata.
+    // regime_confidence stored 0-100 in PositionMetadata (per validator), but the
+    // webapp schema expects 0-1. Normalize.
+    const regimeConfNormalized = typeof md.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
+        : 0.5;
+    const entry = {
+        positionId,
+        entryAt: openedAtMs,
+        isScaleIn: false,
+        thesis: md.thesis ?? '(no thesis recorded)',
+        setupType: md.setupType ?? 'unknown',
+        regime: md.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        scorecardVerdict: md.scorecardVerdict ?? 'GO',
+        confluenceScore: typeof md.confluenceScore === 'number' ? md.confluenceScore : 0,
+        fillPrice,
+        fillSize: filledQty,
+        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+        metadata: buildEntryPlanMetadata(md),
+    };
+    ctx.decisionsClient.postEntry(ctx.userId, entry);
+    logger.info(TAG, `entry captured ${inputs.symbol} ${positionSide} ${filledQty} @ ${fillPrice} (positionId=${positionId.slice(0, 8)}…)`);
+}
+/** Called after a successful adapter.closePosition() with the v2.10.0 reason +
+ *  assessment from close_position.ts. Looks up the cached position UUID, posts
+ *  the close decision row, and drops the local state entry. */
+export async function onClosePositionFilled(ctx, inputs, order) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    const stateEntry = ctx.stateStore.get(inputs.symbol);
+    if (!stateEntry || !stateEntry.webappPositionId) {
+        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: no cached webappPositionId; close row will not be posted (entry was not captured)`);
+        return;
+    }
+    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
+        ? order.filled
+        : 0;
+    // Actual average fill — never order.price (the limit); see fillPriceFromOrder (#196).
+    const fillPrice = fillPriceFromOrder(order);
+    if (filledQty <= 0 || fillPrice === null) {
+        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: missing fill quantity or price; skipping capture`);
+        return;
+    }
+    const closeAtMs = Date.now();
+    const regimeConfNormalized = typeof inputs.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, inputs.regimeConfidence / 100))
+        : 0.5;
+    // Engine-exact economics on paper (issue #201): the simulator attaches the
+    // trade's net P&L + both fee legs to the close order. Posting a non-zero
+    // realizedPnl means the webapp keeps it verbatim (its recompute only fires
+    // on the legacy all-zero path) — the journal stops being gross-of-fees.
+    const paperTrade = extractPaperTrade(order);
+    // Size-mismatch defense (issue #199): if the close fill is materially larger
+    // or smaller than the contracts tracked for THIS journal position, the close
+    // likely belongs to different exposure (state-store staleness). Flag it so
+    // the webapp close route refuses to fabricate price-based P&L/R from it.
+    const tracked = stateEntry.remainingContracts;
+    const sizeMismatch = typeof tracked === 'number' && Number.isFinite(tracked) && tracked > 0 &&
+        Math.abs(tracked - filledQty) / Math.max(tracked, filledQty) > 0.05
+        ? { tracked_contracts: tracked, close_fill_size: filledQty }
+        : undefined;
+    if (sizeMismatch) {
+        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: close fill ${filledQty} vs tracked ${tracked} contracts — ` +
+            `flagging size_mismatch (webapp will not derive price-based metrics from this close)`);
+    }
+    const closeAssessment = {
+        ...inputs.closeAssessment,
+        ...(paperTrade
+            ? {
+                pnl_source: 'paper_engine_net',
+                pnl_gross: paperTrade.grossRealizedPnl,
+                fees: { open: paperTrade.openFee, close: paperTrade.closeFee },
+            }
+            : {}),
+        ...(sizeMismatch ? { size_mismatch: sizeMismatch } : {}),
+    };
+    const close = {
+        positionId: stateEntry.webappPositionId,
+        closeAt: closeAtMs,
+        closeReason: inputs.closeReason,
+        closeAssessment,
+        scorecardVerdict: inputs.scorecardVerdict ?? 'NO_GO',
+        confluenceScore: typeof inputs.confluenceScore === 'number' ? inputs.confluenceScore : 0,
+        regime: inputs.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        fillPrice,
+        fillSize: filledQty,
+        realizedPnl: paperTrade?.netRealizedPnl ?? 0, // live: filled by ws-ingest / server
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    // Re-entry indication (issue #204) — record the exit so scan_pairs can flag
+    // same-bar re-entries on this (symbol, setup).
+    ctx.reentryTracker?.recordExit({
+        symbol: inputs.symbol,
+        setupType: stateEntry.setupType ?? paperTrade?.setupType,
+        side: stateEntry.side,
+        wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        closedAtMs: closeAtMs,
+    });
+    // Drop local state — symbol can re-enter as a new position.
+    ctx.stateStore.remove(inputs.symbol);
+    logger.info(TAG, `close captured ${inputs.symbol} reason=${inputs.closeReason} (positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** How long onAutoFlattenClose polls for the entry journal's webappPositionId
+ *  before giving up (the entry's WS fill can land a beat after the flatten).
+ *  6 × 750ms ≈ 4.5s upper bound; off the trading hot path (event-handler). */
+const AUTO_FLATTEN_LOOKUP_ATTEMPTS = 6;
+const AUTO_FLATTEN_LOOKUP_INTERVAL_MS = 750;
+/** Journal the close produced by an adapter-internal auto-flatten
+ *  (`bracket_attach_failed`). Those flattens call `adapter.closePosition`
+ *  directly, bypassing the close_position tool, so `onClosePositionFilled`
+ *  never runs and the position row orphaned as status='open' (issue #196:
+ *  LTC 2026-07-14, TAO 2026-07-15 — both showed 1 exchange position vs 2 in the
+ *  journal). Polls briefly for the entry journal's webappPositionId (the
+ *  entry's WS fill can arrive just after the flatten), then posts an idempotent
+ *  close row (UNIQUE on position_id) and drops the state-store entry. Fail-open;
+ *  the boot DB reconcile sweep is the backstop if the entry never journals. */
+export async function onAutoFlattenClose(ctx, inputs, lookup = {
+    attempts: AUTO_FLATTEN_LOOKUP_ATTEMPTS,
+    intervalMs: AUTO_FLATTEN_LOOKUP_INTERVAL_MS,
+}) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    if (!(inputs.fillPrice > 0) || !(inputs.fillSize > 0))
+        return;
+    // The entry may not be journaled yet: the auto-flatten fires the moment the
+    // bracket attach exhausts its retries, which can beat the entry's WS-fill
+    // capture. Poll a few times for the webappPositionId before giving up.
+    let webappPositionId;
+    for (let attempt = 0; attempt < lookup.attempts; attempt++) {
+        webappPositionId = ctx.stateStore.get(inputs.symbol)?.webappPositionId;
+        if (webappPositionId)
+            break;
+        if (attempt < lookup.attempts - 1)
+            await sleep(lookup.intervalMs);
+    }
+    if (!webappPositionId) {
+        logger.warn(TAG, `onAutoFlattenClose ${inputs.symbol}: no webappPositionId after ${lookup.attempts} attempts — ` +
+            `DB row may stay status='open' until the boot reconcile sweep (entry likely not journaled)`);
+        return;
+    }
+    const close = {
+        positionId: webappPositionId,
+        closeAt: inputs.observedAtMs ?? Date.now(),
+        closeReason: 'bracket_attach_failed',
+        closeAssessment: {
+            note: 'Position auto-flattened because exchange-native bracket protection could not be ' +
+                'attached (bracket_attach_failed). Journaled from the flatten fill — no close_position ' +
+                'call (auto-flatten bypass, issue #196).',
+            observedFrom: 'auto_flatten',
+        },
+        scorecardVerdict: 'NO_GO',
+        confluenceScore: 0,
+        regime: 'unknown',
+        regimeConfidence: 0.5,
+        fillPrice: inputs.fillPrice,
+        fillSize: Math.abs(inputs.fillSize),
+        // Real close (we have the flatten fill) — not synthetic. Zeros are filled
+        // in per-metric by the webapp close route (price-based R from the pinned
+        // invalidation_price); a scratch resolves to ≈0R, honestly.
+        realizedPnl: 0,
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        ...(inputs.exchangeTradeId ? { exchangeTradeId: inputs.exchangeTradeId } : {}),
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    const flattenState = ctx.stateStore.get(inputs.symbol);
+    ctx.reentryTracker?.recordExit({
+        symbol: inputs.symbol,
+        setupType: flattenState?.setupType,
+        side: flattenState?.side ?? 'long',
+        closedAtMs: inputs.observedAtMs ?? Date.now(),
+    });
+    ctx.stateStore.remove(inputs.symbol);
+    logger.info(TAG, `auto-flatten close captured ${inputs.symbol} @ ${inputs.fillPrice} ` +
+        `(positionId=${webappPositionId.slice(0, 8)}…)`);
+}
+/** Journal a stop-watcher auto-close (issue #199).
+ *
+ *  The watcher calls `adapter.closePosition(symbol, 'stop_watcher')` directly —
+ *  it never goes through the close_position tool, and paper has no WS fill
+ *  stream, so before this hook every watcher close left the journal position
+ *  (and the state-store mapping) alive: the next trade on the symbol was then
+ *  silently dropped or stitched onto the stale position, fabricating P&L
+ *  (measured 14/69 corrupted closes on the 2026-07 HL soak; worst single
+ *  fabrication −$117.86 vs a real −$10.63).
+ *
+ *  Contract: the engine exposure is DEFINITIVELY gone when this runs (the
+ *  watcher's close resolved), so the state-store entry is always dropped —
+ *  even when we can't post a close row (the periodic DB sweep then heals the
+ *  orphaned DB row instead of a later close being mis-stitched). Fail-open. */
+export async function onStopWatcherClose(ctx, inputs) {
+    if (!ctx.stateStore)
+        return;
+    const stateEntry = ctx.stateStore.get(inputs.symbol);
+    const paperTrade = extractPaperTrade(inputs.order);
+    const closeAtMs = Date.now();
+    // Record the exit for re-entry indication regardless of journal linkage —
+    // the engine trade happened even if the journal never knew the position.
+    ctx.reentryTracker?.recordExit({
+        symbol: inputs.symbol,
+        setupType: stateEntry?.setupType ?? paperTrade?.setupType,
+        side: stateEntry?.side ?? 'long',
+        wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        closedAtMs: closeAtMs,
+    });
+    const dropState = () => { ctx.stateStore?.remove(inputs.symbol); };
+    if (!ctx.decisionsClient || !ctx.userId) {
+        dropState();
+        return;
+    }
+    if (!stateEntry?.webappPositionId) {
+        logger.warn(TAG, `onStopWatcherClose ${inputs.symbol}: no cached webappPositionId — dropping state; ` +
+            `periodic DB sweep will close any orphaned journal row`);
+        dropState();
+        return;
+    }
+    const order = inputs.order;
+    const fillPrice = (order ? fillPriceFromOrder(order) : null)
+        ?? (Number.isFinite(inputs.markPrice) && inputs.markPrice > 0 ? inputs.markPrice : null);
+    const filledQty = typeof order?.filled === 'number' && Number.isFinite(order.filled) && order.filled > 0
+        ? order.filled
+        : (typeof stateEntry.remainingContracts === 'number' && stateEntry.remainingContracts > 0
+            ? stateEntry.remainingContracts
+            : null);
+    if (fillPrice === null || filledQty === null) {
+        logger.warn(TAG, `onStopWatcherClose ${inputs.symbol}: fill data unresolvable — dropping state; ` +
+            `periodic DB sweep will close the journal row`);
+        dropState();
+        return;
+    }
+    const close = {
+        positionId: stateEntry.webappPositionId,
+        closeAt: closeAtMs,
+        closeReason: 'stop_watcher',
+        closeAssessment: {
+            note: 'Position auto-closed by the stop-watcher: mark crossed the pinned stopPrice. ' +
+                'Journaled from the watcher close fill — no close_position call (issue #199).',
+            observedFrom: 'stop_watcher',
+            stop_price: inputs.stopPrice,
+            mark_price: inputs.markPrice,
+            ...(paperTrade
+                ? {
+                    pnl_source: 'paper_engine_net',
+                    pnl_gross: paperTrade.grossRealizedPnl,
+                    fees: { open: paperTrade.openFee, close: paperTrade.closeFee },
+                }
+                : {}),
+        },
+        scorecardVerdict: 'NO_GO',
+        confluenceScore: 0,
+        regime: 'unknown',
+        regimeConfidence: 0.5,
+        fillPrice,
+        fillSize: Math.abs(filledQty),
+        realizedPnl: paperTrade?.netRealizedPnl ?? 0,
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        ...(typeof order?.id === 'string' && order.id.length > 0 ? { exchangeTradeId: order.id } : {}),
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    dropState();
+    logger.info(TAG, `stop-watcher close captured ${inputs.symbol} @ ${fillPrice} ` +
+        `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…, ` +
+        `pnl=${paperTrade ? paperTrade.netRealizedPnl.toFixed(4) : 'server-side'})`);
+}
+/** Look up the metadata create_order stashed for this fill. Primary key is
+ *  the exchange orderId (post-REST-ack `promote()`); the clientOrderId
+ *  fallback covers the routine market-order race where the WS fill arrives
+ *  BEFORE the REST response, i.e. before the promote — the pre-submission
+ *  stash is keyed by the cid, which the WS event carries (`o.c`). */
+function consumePendingEntry(ctx, fill) {
+    if (!ctx.pendingEntries)
+        return undefined;
+    return (ctx.pendingEntries.consume(fill.exchangeOrderId) ??
+        (fill.clientOrderId ? ctx.pendingEntries.consume(fill.clientOrderId) : undefined));
+}
+export async function onWsFillObserved(ctx, fill) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    if (fill.fillPrice <= 0 || fill.fillSize <= 0)
+        return;
+    // Reduce-only fills are exit-side. close_position tool exits are journaled by
+    // onClosePositionFilled; bracket SL/TP fills and other reduce-only closes
+    // bypass that path entirely and used to leave the journal position open
+    // forever (close-bypass class). When closeOnReduceOnlyFill is enabled, detect
+    // the position going flat from the fill(s) and journal an exact close.
+    if (fill.reduceOnly) {
+        await handleReduceOnlyExit(ctx, fill);
+        return;
+    }
+    const stateEntry = ctx.stateStore.get(fill.symbol);
+    const fillSide = fill.side === 'buy' ? 'long' : 'short';
+    const ts = fill.exchangeTimeMs ?? Date.now();
+    if (stateEntry) {
+        // Dedup: if the synchronous create_order path already captured this
+        // exact order (orderId match), the WS event is the same fill — skip.
+        if (stateEntry.openedFromExchangeTradeId === fill.exchangeOrderId) {
+            return;
+        }
+        if (stateEntry.side !== fillSide) {
+            // Opposite-side fill on an existing position. Almost certainly a manual
+            // flatten that bypassed close_position. Don't journal here — the
+            // operator should use close_position with reason+assessment instead.
+            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: opposite-side fill on existing ${stateEntry.side} position; skipping (use close_position for rationale capture)`);
+            return;
+        }
+        // SCALE-IN: same symbol, same side, fresh fill.
+        if (!stateEntry.webappPositionId) {
+            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: scale-in observed but no webappPositionId yet — skipping (parent upsert may have failed; will retry next fill)`);
+            return;
+        }
+        const pending = consumePendingEntry(ctx, fill);
+        const entry = buildEntryPayload({
+            positionId: stateEntry.webappPositionId,
+            isScaleIn: true,
+            ts,
+            fillPrice: fill.fillPrice,
+            fillSize: fill.fillSize,
+            exchangeTradeId: fill.exchangeTradeId,
+            metadata: pending?.metadata,
+        });
+        ctx.decisionsClient.postEntry(ctx.userId, entry);
+        // Grow tracked size so a later reduce-only exit detects flat correctly.
+        ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
+        logger.info(TAG, `scale-in captured ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
+            `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+        return;
+    }
+    // No state-store entry → NEW position via WS-driven fill. Replicates the
+    // synchronous-market-order path but pulls metadata from the pending cache
+    // (which create_order populated BEFORE submitting the order).
+    const pending = consumePendingEntry(ctx, fill);
+    ctx.stateStore.upsert({
+        symbol: fill.symbol,
+        openedAt: ts,
+        side: fillSide,
+        openedFromExchangeTradeId: fill.exchangeOrderId,
+        setupType: pending?.metadata?.setupType,
+    });
+    const upsert = {
+        symbol: fill.symbol,
+        positionOpenAt: ts,
+        side: fillSide,
+        currentSize: fill.fillSize,
+        avgEntryPrice: fill.fillPrice,
+        mode: ctx.resolveMode?.(),
+        exchange: ctx.venue,
+    };
+    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
+    if (!positionId) {
+        logger.warn(TAG, `onWsFillObserved ${fill.symbol}: webapp position upsert returned no id; entry row will not be posted`);
+        return;
+    }
+    ctx.stateStore.setWebappId(fill.symbol, positionId);
+    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
+    ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
+    const entry = buildEntryPayload({
+        positionId,
+        isScaleIn: false,
+        ts,
+        fillPrice: fill.fillPrice,
+        fillSize: fill.fillSize,
+        exchangeTradeId: fill.exchangeTradeId,
+        metadata: pending?.metadata,
+    });
+    ctx.decisionsClient.postEntry(ctx.userId, entry);
+    logger.info(TAG, `entry captured (ws) ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
+        `(positionId=${positionId.slice(0, 8)}…, metadata=${pending ? 'cached' : 'none'})`);
+}
+/** Reduce-only exit fill handler — the close-bypass fix. When enabled, sums the
+ *  fill's realised PnL into the tracked position and, once remaining size hits
+ *  flat, posts an exact close decision row (Binance-exact realised PnL, real
+ *  exit price) and drops the local state entry. Idempotent at the webapp
+ *  (position_closes UNIQUE on position_id); fail-open. */
+async function handleReduceOnlyExit(ctx, fill) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    // Gated: when off, preserve the legacy behaviour (reduce-only fills ignored).
+    if (!ctx.closeOnReduceOnlyFill)
+        return;
+    const stateEntry = ctx.stateStore.get(fill.symbol);
+    // No tracked entry (already cleaned, or never journaled) → nothing to close.
+    if (!stateEntry || !stateEntry.webappPositionId)
+        return;
+    const updated = ctx.stateStore.applyExitContracts(fill.symbol, fill.fillSize, fill.realizedPnl ?? 0);
+    if (!updated) {
+        // Size unknown for this entry (opened before tracking existed and not yet
+        // seeded). Can't decide flatness from fills — leave the reconciler/ALGO
+        // close-bypass path as the backstop.
+        logger.info(TAG, `reduce-only fill ${fill.symbol}: size untracked; deferring close to reconciler/ALGO backstop`);
+        return;
+    }
+    const remaining = updated.remainingContracts ?? 0;
+    if (remaining > FLAT_EPSILON) {
+        logger.info(TAG, `partial exit ${fill.symbol}: ${fill.fillSize} reduce-only fill, ${remaining} contracts remaining`);
+        return; // not flat yet — keep accumulating
+    }
+    // FLAT. Auto-journal an exact close ONLY for exchange-native bracket fills
+    // (the cid is one of our bracket legs). Non-bracket reduce-only flats are
+    // either close_position's own order (its WS fill can race ahead of
+    // onClosePositionFilled) or a manual/external close — both are handled by
+    // their own paths (close_position's rich reason+assessment, or the reconciler
+    // backstop). Closing here would clobber the agent's close reasoning, so defer.
+    const isBracket = fill.clientOrderId ? isBracketCid(fill.clientOrderId) : false;
+    if (!isBracket) {
+        logger.info(TAG, `${fill.symbol} flat via non-bracket reduce-only fill (cid=${fill.clientOrderId ?? 'none'}) — ` +
+            `deferring close to close_position / reconciler backstop (no clobber)`);
+        return; // do NOT remove — onClosePositionFilled / backstop owns this close
+    }
+    const realizedPnl = updated.realizedPnlAccum ?? 0;
+    const close = {
+        positionId: stateEntry.webappPositionId,
+        closeAt: fill.exchangeTimeMs ?? Date.now(),
+        closeReason: 'bracket_fill',
+        closeAssessment: {
+            note: 'Position closed by an exchange-native bracket SL/TP fill (reduce-only). ' +
+                'Auto-journaled from the WS fill — no close_position call (close-bypass path).',
+            observedFrom: 'ws_reduce_only_fill',
+            clientOrderId: fill.clientOrderId,
+        },
+        scorecardVerdict: 'NO_GO',
+        confluenceScore: 0,
+        regime: 'unknown',
+        regimeConfidence: 0.5,
+        fillPrice: fill.fillPrice,
+        fillSize: Math.abs(fill.fillSize),
+        // realizedPnl is Binance-exact (summed across exit fills); the zeros below
+        // are filled in PER-METRIC by the webapp close route (price-based R from
+        // the pinned invalidation_price, mfe/give-back from the last review — see
+        // webapp lib/api/close-metrics.ts). The route's old all-four-zero gate
+        // meant this non-zero PnL used to suppress that fill-in entirely, persisting
+        // realized_r=0 on every bracket_fill close (the 2026-07-11 zero-hole).
+        realizedPnl,
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        exchangeTradeId: fill.exchangeTradeId,
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    ctx.reentryTracker?.recordExit({
+        symbol: fill.symbol,
+        setupType: stateEntry.setupType,
+        side: stateEntry.side,
+        wasLoss: realizedPnl < 0,
+        closedAtMs: fill.exchangeTimeMs ?? Date.now(),
+    });
+    ctx.stateStore.remove(fill.symbol);
+    logger.info(TAG, `close captured (ws bracket fill) ${fill.symbol} pnl=${realizedPnl.toFixed(4)} ` +
+        `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+}
+/** Internal helper — builds the PositionEntryPayload from a fill, applying the
+ *  same regimeConfidence normalisation (0-100 → 0-1) as the synchronous path. */
+function buildEntryPayload(args) {
+    const md = args.metadata;
+    const regimeConfNormalized = typeof md?.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
+        : 0.5;
+    return {
+        positionId: args.positionId,
+        entryAt: args.ts,
+        isScaleIn: args.isScaleIn,
+        thesis: md?.thesis ?? '(no thesis recorded)',
+        setupType: md?.setupType ?? 'unknown',
+        regime: md?.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        scorecardVerdict: md?.scorecardVerdict ?? 'GO',
+        confluenceScore: typeof md?.confluenceScore === 'number' ? md.confluenceScore : 0,
+        fillPrice: args.fillPrice,
+        fillSize: args.fillSize,
+        exchangeTradeId: args.exchangeTradeId,
+        metadata: buildEntryPlanMetadata(md),
+    };
+}
+/** Pinned-plan subset persisted to position_entries.metadata (free-form JSONB).
+ *  Keys are snake_case per the canonical-JSONB-key rule (CLAUDE.md learning-loop:
+ *  a camelCase mismatch previously broke learning matching). Returns undefined
+ *  when neither field is present so we never write an empty object. */
+export function buildEntryPlanMetadata(md) {
+    if (!md)
+        return undefined;
+    const out = {};
+    if (typeof md.invalidationPrice === 'number' && Number.isFinite(md.invalidationPrice)) {
+        out.invalidation_price = md.invalidationPrice;
+    }
+    // Pin the planned profit target too — it's the agent's stated target (and the
+    // bracket TP in live), surfaced on the dashboard pinned-plan view. Distinct
+    // from realization_rule (which is mostly omitted); without this the target is
+    // blank on the journal/Trade-card pinned-plan surfaces in the common case.
+    if (typeof md.targetPrice === 'number' && Number.isFinite(md.targetPrice)) {
+        out.target_price = md.targetPrice;
+    }
+    const rr = md.realizationRule;
+    if (rr) {
+        const j = { type: rr.type };
+        if (rr.targetPrice != null)
+            j.target_price = rr.targetPrice;
+        if (rr.trailAfterR != null)
+            j.trail_after_r = rr.trailAfterR;
+        if (rr.trailDistanceR != null)
+            j.trail_distance_r = rr.trailDistanceR;
+        if (rr.scale)
+            j.scale = rr.scale.map((s) => ({ at_r: s.atR, fraction: s.fraction }));
+        if (rr.note)
+            j.note = rr.note;
+        out.realization_rule = j;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}