@reefclaw/openclaw-plugin 0.1.6 → 0.1.8

package/ingest/position-auto-capture.d.ts

@@ -1,8 +1,10 @@
 import type { PositionDecisionsClient } from './position-decisions-client.js';
 import type { PositionStateStore } from '../live/position-state-store.js';
 import type { CcxtOrder } from '../types.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { PositionMetadata } from '../simulator/types.js';
 import type { PendingEntryStore } from './pending-entry-metadata.js';
+import type { ReentryTracker } from '../portfolio/reentry-tracker.js';
 export interface AutoCaptureContext {
     decisionsClient?: PositionDecisionsClient;
     stateStore?: PositionStateStore;
@@ -26,7 +28,29 @@ export interface AutoCaptureContext {
      *  `resolveMode` this is a plain value, not a resolver. Tags journal rows
      *  (positions.exchange, migration 0058). */
     venue?: 'binance' | 'hyperliquid';
+    /** Resolve the ACTIVE adapter at capture time (follows a runtime reconnect,
+     *  same deferred-closure pattern as resolveMode). Used by the stale-state
+     *  defense in onCreateOrderFilled: when the state-store claims an open
+     *  position but the exchange position is exactly the just-filled quantity,
+     *  the prior exposure was closed outside the journal (watcher/manual) and
+     *  the mapping is STALE — stitching onto it fabricates P&L (issue #199). */
+    resolveAdapter?: () => IExchangeAdapter | undefined;
+    /** Re-entry tracker (issue #204) — every close path records the exit so
+     *  scan_pairs can flag setups already traded within the current signal bar. */
+    reentryTracker?: ReentryTracker;
 }
+/** Engine-exact paper fill economics attached by the simulator to close-order
+ *  results (`order.info.paperTrade`, issue #201). All numbers are quote-ccy. */
+export interface PaperTradeInfo {
+    grossRealizedPnl: number;
+    netRealizedPnl: number;
+    openFee: number;
+    closeFee: number;
+    setupType?: string;
+}
+/** Extract the simulator's engine-exact trade economics from a close order,
+ *  with strict numeric guards (absent on live orders → undefined). */
+export declare function extractPaperTrade(order: CcxtOrder | undefined): PaperTradeInfo | undefined;
 export interface CreateOrderInputs {
     symbol: string;
     side: 'buy' | 'sell';
@@ -56,6 +80,50 @@ export interface ClosePositionInputs {
  *  assessment from close_position.ts. Looks up the cached position UUID, posts
  *  the close decision row, and drops the local state entry. */
 export declare function onClosePositionFilled(ctx: AutoCaptureContext, inputs: ClosePositionInputs, order: CcxtOrder): Promise<void>;
+export interface AutoFlattenCloseInputs {
+    symbol: string;
+    /** Actual average fill price of the flatten close (resolved, never a limit). */
+    fillPrice: number;
+    fillSize: number;
+    exchangeTradeId?: string;
+    observedAtMs?: number;
+}
+/** 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 declare function onAutoFlattenClose(ctx: AutoCaptureContext, inputs: AutoFlattenCloseInputs, lookup?: {
+    attempts: number;
+    intervalMs: number;
+}): Promise<void>;
+export interface StopWatcherCloseInputs {
+    symbol: string;
+    stopPrice: number;
+    markPrice: number;
+    /** The executed close order from adapter.closePosition (may be absent if the
+     *  close resolved through a path that didn't surface it). */
+    order?: CcxtOrder;
+}
+/** 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 declare function onStopWatcherClose(ctx: AutoCaptureContext, inputs: StopWatcherCloseInputs): Promise<void>;
 /** WS-driven fill observed. Resolves the PR1 deferral that limit-order fills
  *  + scale-ins were silently dropped. Branches on three cases:
  *

package/ingest/position-auto-capture.js

@@ -20,11 +20,57 @@
 // §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
@@ -44,13 +90,16 @@ export async function onCreateOrderFilled(ctx, inputs, order) {
         // Limit order not yet filled — nothing to capture yet.
         return;
     }
-    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
-        ? order.average
-        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
-            ? order.price
-            : null;
+    // 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}: missing fill price; skipping capture`);
+        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
@@ -62,13 +111,57 @@ export async function onCreateOrderFilled(ctx, inputs, order) {
     }
     const positionSide = inputs.side === 'buy' ? 'long' : 'short';
     const openedAtMs = Date.now();
-    // Skip if state-store already knows about this position (scale-in / partial
-    // fill of an existing entry). PR 1 deferral: don't record additional entries.
-    // The follow-up that hooks WS-ingest will detect scale-ins explicitly.
+    // 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) {
-        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: existing position in state-store (openedAt=${existing.openedAt}); treating as scale-in (auto-capture deferred to v2)`);
-        return;
+        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.
@@ -77,6 +170,7 @@ export async function onCreateOrderFilled(ctx, inputs, order) {
         openedAt: openedAtMs,
         side: positionSide,
         openedFromExchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+        setupType: md.setupType,
     });
     const upsert = {
         symbol: inputs.symbol,
@@ -134,46 +228,242 @@ export async function onClosePositionFilled(ctx, inputs, order) {
     const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
         ? order.filled
         : 0;
-    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
-        ? order.average
-        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
-            ? order.price
-            : null;
+    // 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();
-    // Realized PnL + R-multiple require entry-side state we don't have here for
-    // PR 1. The skill-side computation already produces these for the webapp;
-    // this auto-capture just records what the close tool input told us. Default
-    // numeric fields to 0 — webapp accepts and the operator will see the close
-    // card with zeros until the v2 ws-ingest hook fills them properly.
     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: inputs.closeAssessment,
+        closeAssessment,
         scorecardVerdict: inputs.scorecardVerdict ?? 'NO_GO',
         confluenceScore: typeof inputs.confluenceScore === 'number' ? inputs.confluenceScore : 0,
         regime: inputs.regime ?? 'unknown',
         regimeConfidence: regimeConfNormalized,
         fillPrice,
         fillSize: filledQty,
-        realizedPnl: 0, // populated by v2 ws-ingest hook
+        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
@@ -246,6 +536,7 @@ export async function onWsFillObserved(ctx, fill) {
         openedAt: ts,
         side: fillSide,
         openedFromExchangeTradeId: fill.exchangeOrderId,
+        setupType: pending?.metadata?.setupType,
     });
     const upsert = {
         symbol: fill.symbol,
@@ -347,6 +638,13 @@ async function handleReduceOnlyExit(ctx, fill) {
         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)}…)`);

package/ingest/position-decisions-client.d.ts

@@ -290,8 +290,13 @@ export declare class PositionDecisionsClient {
     /** DB-vs-exchange reconcile read: this tenant's open positions. Awaited.
      *  Returns null on terminal/retry-exhausted failure — the caller MUST treat
      *  null as UNKNOWN (never as "no open rows"), else a failed fetch would
-     *  false-close the whole book. */
-    getOpenPositions(userId: string): Promise<OpenPositionsResponse | null>;
+     *  false-close the whole book. Pass `mode` to scope the read to the ACTIVE
+     *  book (paper strict / live incl. legacy NULL rows) and `exchange` to scope
+     *  it to the ACTIVE venue (hyperliquid strict / binance incl. legacy NULL
+     *  rows) — the sweep diffs against one adapter's snapshot, so an unscoped
+     *  read misreads the inactive book's/venue's rows as orphans (issue #209
+     *  item 5: the same corruption class on the venue axis). */
+    getOpenPositions(userId: string, mode?: 'paper' | 'live', exchange?: 'binance' | 'hyperliquid'): Promise<OpenPositionsResponse | null>;
     /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
      *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
     getRecentReviews(userId: string, positionIds: string[], reviewLimit?: number): Promise<RecentReviewsResponse | null>;

package/ingest/position-decisions-client.js

@@ -53,9 +53,19 @@ export class PositionDecisionsClient {
     /** DB-vs-exchange reconcile read: this tenant's open positions. Awaited.
      *  Returns null on terminal/retry-exhausted failure — the caller MUST treat
      *  null as UNKNOWN (never as "no open rows"), else a failed fetch would
-     *  false-close the whole book. */
-    async getOpenPositions(userId) {
-        return this.runGetReturning(userId, '/api/internal/positions?status=open');
+     *  false-close the whole book. Pass `mode` to scope the read to the ACTIVE
+     *  book (paper strict / live incl. legacy NULL rows) and `exchange` to scope
+     *  it to the ACTIVE venue (hyperliquid strict / binance incl. legacy NULL
+     *  rows) — the sweep diffs against one adapter's snapshot, so an unscoped
+     *  read misreads the inactive book's/venue's rows as orphans (issue #209
+     *  item 5: the same corruption class on the venue axis). */
+    async getOpenPositions(userId, mode, exchange) {
+        const qs = new URLSearchParams({ status: 'open' });
+        if (mode)
+            qs.set('mode', mode);
+        if (exchange)
+            qs.set('exchange', exchange);
+        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`);
     }
     /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
      *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */

package/ingest/reconcile-db-vs-exchange.d.ts

@@ -2,6 +2,16 @@ import type { PositionDecisionsClient } from './position-decisions-client.js';
 export interface DbVsExchangeContext {
     decisionsClient?: PositionDecisionsClient;
     userId?: string;
+    /** Active trading book. Scopes the DB read so open rows from the INACTIVE
+     *  book — which can never appear in this adapter's snapshot — are not
+     *  misread as orphans and synthetically closed (cross-book corruption after
+     *  a set_trading_mode switch with positions open). Absent → unscoped
+     *  (legacy callers). */
+    resolveMode?: () => 'paper' | 'live';
+    /** Active venue (issue #209 item 5) — the same orphan-misread class on the
+     *  exchange axis: a tenant running two venues has open rows the OTHER
+     *  venue's snapshot can never contain. Absent → unscoped (legacy). */
+    resolveExchange?: () => 'binance' | 'hyperliquid';
 }
 /**
  * Close webapp `positions` rows that are status='open' but absent from the
@@ -10,4 +20,32 @@ export interface DbVsExchangeContext {
  * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
  *        !== null). Pass only when the fetch genuinely succeeded.
  */
-export declare function reconcileDbOpenVsExchange(ctx: DbVsExchangeContext, exchangeSymbols: Iterable<string>, nowMs?: number): Promise<number>;
+export interface DbReconcileOptions {
+    /** Provenance tag written into closeAssessment.source (default boot sweep). */
+    source?: string;
+    /** Attribution hook (issue #203): given an orphaned symbol, return a short
+     *  human-readable description of what the execution engine last knew about
+     *  it (e.g. the simulator's last trade). Logged with the synthetic close so
+     *  chronic capture misses can be classified instead of perpetually healed. */
+    describeLastExit?: (symbol: string) => string | undefined;
+}
+export declare function reconcileDbOpenVsExchange(ctx: DbVsExchangeContext, exchangeSymbols: Iterable<string>, nowMs?: number, opts?: DbReconcileOptions): Promise<number>;
+export declare const DEFAULT_DB_RECONCILE_INTERVAL_MS = 300000;
+export interface PeriodicDbReconcileDeps extends DbVsExchangeContext {
+    /** Resolve the ACTIVE adapter each tick (follows runtime reconnects). */
+    resolveAdapter: () => {
+        getPositionsOrNull(symbol?: string): Promise<Array<{
+            symbol: string;
+        }> | null>;
+    } | undefined;
+    describeLastExit?: (symbol: string) => string | undefined;
+}
+export interface PeriodicDbReconcileHandle {
+    stop(): void;
+    /** One sweep cycle — exposed for tests (no setInterval). */
+    runOnce(): Promise<number>;
+}
+/** Resolve the sweep interval from RC_DB_RECONCILE_INTERVAL_MS.
+ *  'off' or '0' disables (returns null); values are clamped to ≥60s. */
+export declare function resolveDbReconcileIntervalMs(raw?: string | undefined): number | null;
+export declare function startPeriodicDbReconcile(deps: PeriodicDbReconcileDeps, intervalMs?: number | null): PeriodicDbReconcileHandle | null;