@reefclaw/openclaw-plugin 0.1.6 → 0.1.8

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/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

@@ -17,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
@@ -79,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. */
@@ -143,6 +144,27 @@ 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. */
@@ -259,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

package/live/live-adapter.js

@@ -22,9 +22,11 @@ import { BracketReconciler } from './bracket-reconciler.js';
 import { LiveBracketApi } from './live-bracket-api.js';
 import { generateBracketId, buildBracketCid, parseBracketCid } from './bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from './bracket-params.js';
+import { fillPriceFromOrder } from './fill-price.js';
 import { bracketsEnabled } from '../config/brackets-config.js';
 import { userDataStreamEnabled, userDataStreamAuthoritative, DEFAULT_TUNABLES as USER_DATA_STREAM_DEFAULT_TUNABLES, } from '../config/user-data-stream-config.js';
 import { UserDataStreamController } from './user-data-stream-controller.js';
+import { onAutoFlattenClose } from '../ingest/position-auto-capture.js';
 import { assertNotShuttingDown, registerOp } from '../lifecycle/shutdown-coordinator.js';
 import { updateMfe } from '../mfe.js';
 import { computeInvalidationHit } from '../pinned-plan.js';
@@ -171,6 +173,11 @@ export class LiveAdapter extends EventEmitter {
     // getPositions tick, dropped on closePosition or when a symbol vanishes from
     // the open-positions snapshot.
     liveMetadata = new Map();
+    // Position-decision auto-capture wiring (optional). Retained so the internal
+    // bracket_attach_failed auto-flatten can journal its close (issue #196): that
+    // flatten bypasses the close_position tool, so onClosePositionFilled never
+    // runs and the row would orphan as status='open'.
+    autoCapture;
     // Readiness state — mutable, starts INIT_PENDING
     _readiness = 'INIT_PENDING';
     get readiness() {
@@ -194,6 +201,11 @@ export class LiveAdapter extends EventEmitter {
         this.mode = mode;
         this.bracketMode = bracketMode;
         this.userDataStreamMode = userDataStreamMode;
+        // Retained for the auto-flatten journal close capture (issue #196): the
+        // adapter-internal `closePosition(…, 'bracket_attach_failed')` calls bypass
+        // the close_position tool, so onClosePositionFilled never runs for them —
+        // the row orphaned as status='open' until this capture existed.
+        this.autoCapture = autoCapture;
         this.api = new BinancePrivateApi(config);
         if (mode === 'MICRO_LIVE') {
             // sizeCapMultiplier is 1.0 — the agent already sizes for the real wallet.
@@ -742,6 +754,19 @@ export class LiveAdapter extends EventEmitter {
             }
             // ---- Post-submission bookkeeping ----
             this.intentJournal.updateIntent(clientOrderId, { status: 'confirmed', exchangeOrderId: order.id });
+            // ---- Fill-price enrichment (issue #196) ----
+            // For a marketable LIMIT order Binance's synchronous RESULT response can
+            // come back avgPrice=0 even though it filled (RESULT only guarantees the
+            // fill for MARKET / special-timeInForce LIMIT orders). Every downstream
+            // consumer — bracket direction validation, slippage, journal entry capture
+            // — MUST key off the real fill, never the limit price. Re-query by
+            // clientOrderId (weight 1) to patch order.average BEFORE any of them read
+            // it. Market orders report avgPrice reliably, so this fires only on the
+            // filled-limit edge; best-effort — a failed re-query leaves order.average
+            // as-is (consumers then use a mark price / skip, never the limit).
+            if (order.status === 'closed' && order.filled > 0 && fillPriceFromOrder(order) === null) {
+                await this.enrichFilledAvgPrice(order, clientOrderId, symbol);
+            }
             // Track slippage for market orders that filled immediately
             if (order.status === 'closed' && order.average != null && expectedPrice > 0) {
                 this.slippageTracker.recordFill({
@@ -781,60 +806,81 @@ export class LiveAdapter extends EventEmitter {
             // leg, register the bracket and (for market orders) attach immediately.
             // Limit orders defer attach to the poller's 'filled' event handler.
             if (this.bracketManager && this.bracketLedger && metadata && (metadata.stopPrice !== undefined || metadata.targetPrice !== undefined)) {
-                // Defense-in-depth: the pre-submission check above already rejected sign
-                // errors against the ref price, but re-check against the actual fill
-                // (order.average) in case the fill landed across the level. Crucially, a
-                // failure HERE is post-submission: bare-throwing would abandon a live
-                // position (filled market order) or a resting entry that fills naked
-                // (open limit). So clean up BEFORE throwing.
-                const refPrice = order.average ?? order.price ?? price ?? 0;
-                if (refPrice > 0) {
-                    let dirMsg = null;
+                // Defense-in-depth direction re-check. The pre-submission check above
+                // already rejected sign errors against the ref price; this re-checks once
+                // the order's outcome is known. Reference price by order state:
+                //   - FILLED (status=closed, filled>0): the ACTUAL average fill — NEVER
+                //     the limit price (issue #196). A marketable limit can fill percent-
+                //     scale away from its limit, so comparing the bracket to the limit
+                //     gives a FALSE invalid (needless auto-flatten — LTC 2026-07-14) or
+                //     lets a genuinely wrong stop through. If the fill price is
+                //     unresolvable, SKIP the check — the bracket attach (Binance -2021 on
+                //     a wrong-side stop) is the arbiter; validating against the limit
+                //     would resurrect the bug.
+                //   - still-OPEN resting limit: no fill yet, so the limit price IS the
+                //     correct reference (the order fills at/through its limit).
+                // A failure HERE is post-submission — clean up (flatten the filled
+                // position / cancel the resting order) BEFORE throwing.
+                let dirRef = null;
+                if (order.status === 'closed' && order.filled > 0) {
+                    dirRef = fillPriceFromOrder(order);
+                    if (dirRef === null) {
+                        logger.warn(TAG, `Post-fill bracket direction check skipped for ${symbol}: actual fill price unresolvable (avg=${order.average ?? 'null'} cost=${order.cost} filled=${order.filled}); NOT validating against the limit price — the bracket attach (Binance -2021) is the arbiter`);
+                    }
+                }
+                else if (order.status === 'open') {
+                    const lim = order.price ?? price ?? 0;
+                    dirRef = lim > 0 ? lim : null;
+                }
+                let dirMsg = null;
+                if (dirRef !== null && dirRef > 0) {
                     if (metadata.stopPrice !== undefined) {
-                        dirMsg = validateStopDirection(side, refPrice, metadata.stopPrice);
+                        dirMsg = validateStopDirection(side, dirRef, metadata.stopPrice);
                     }
                     if (!dirMsg && metadata.targetPrice !== undefined) {
-                        dirMsg = validateTargetDirection(side, refPrice, metadata.targetPrice);
+                        dirMsg = validateTargetDirection(side, dirRef, metadata.targetPrice);
                     }
-                    if (dirMsg) {
-                        if (order.status === 'closed' && order.filled > 0) {
-                            logger.error(TAG, `Post-fill bracket direction invalid for ${symbol} (${dirMsg}) — flattening the just-filled position to avoid a naked entry`);
-                            // We have HARD evidence the entry filled (status=closed, filled>0).
-                            // closePosition throws "No open position" when its attempt-1
-                            // fetchPositions returns a *confirmed-empty* snapshot — which, in
-                            // the moments right after a fill, is almost always Binance
-                            // position-state lagging the order response, NOT a real flat.
-                            // Accepting that single failure would fail open and leave the
-                            // position naked (the exact high-risk branch this cleanup exists
-                            // for). Retry across the lag window instead of trusting one snapshot.
-                            let flattened = false;
-                            for (let a = 1; a <= 4 && !flattened; a++) {
-                                try {
-                                    await this.closePosition(symbol, 'bracket_attach_failed');
-                                    flattened = true;
-                                }
-                                catch (err) {
-                                    logger.warn(TAG, `Post-fill flatten attempt ${a}/4 for ${symbol} failed: ${formatError(err)}`);
-                                    if (a < 4)
-                                        await sleep(1500);
-                                }
-                            }
-                            if (!flattened) {
-                                logger.error(TAG, `CRITICAL: post-fill flatten of ${symbol} FAILED after 4 attempts — position is NAKED, immediate operator intervention required`);
-                                this.emit('emergency_progress', { action: 'flatten', status: 'failed', symbol, message: `Naked ${symbol} after invalid bracket — manual close required` });
-                            }
-                        }
-                        else if (order.status === 'open') {
-                            logger.error(TAG, `Post-submit bracket direction invalid for ${symbol} (${dirMsg}) — cancelling the resting entry order so it can't fill unprotected`);
+                }
+                if (dirMsg) {
+                    if (order.status === 'closed' && order.filled > 0) {
+                        logger.error(TAG, `Post-fill bracket direction invalid for ${symbol} (${dirMsg}, fill=${dirRef}) — flattening the just-filled position to avoid a naked entry`);
+                        // We have HARD evidence the entry filled (status=closed, filled>0).
+                        // closePosition throws "No open position" when its attempt-1
+                        // fetchPositions returns a *confirmed-empty* snapshot — which, in
+                        // the moments right after a fill, is almost always Binance
+                        // position-state lagging the order response, NOT a real flat.
+                        // Accepting that single failure would fail open and leave the
+                        // position naked (the exact high-risk branch this cleanup exists
+                        // for). Retry across the lag window instead of trusting one snapshot.
+                        // closePosition journals the auto-flatten close itself (keyed on the
+                        // 'bracket_attach_failed' reason) so the row can't orphan (#196).
+                        let flattened = false;
+                        for (let a = 1; a <= 4 && !flattened; a++) {
                             try {
-                                await this.api.cancelOrderByClientId(clientOrderId, symbol);
+                                await this.closePosition(symbol, 'bracket_attach_failed');
+                                flattened = true;
                             }
                             catch (err) {
-                                logger.error(TAG, `Cancel of resting entry after invalid bracket failed for ${symbol}: ${formatError(err)}`);
+                                logger.warn(TAG, `Post-fill flatten attempt ${a}/4 for ${symbol} failed: ${formatError(err)}`);
+                                if (a < 4)
+                                    await sleep(1500);
                             }
                         }
-                        throw new Error(`Bracket rejected (post-submit): ${dirMsg}`);
+                        if (!flattened) {
+                            logger.error(TAG, `CRITICAL: post-fill flatten of ${symbol} FAILED after 4 attempts — position is NAKED, immediate operator intervention required`);
+                            this.emit('emergency_progress', { action: 'flatten', status: 'failed', symbol, message: `Naked ${symbol} after invalid bracket — manual close required` });
+                        }
                     }
+                    else if (order.status === 'open') {
+                        logger.error(TAG, `Post-submit bracket direction invalid for ${symbol} (${dirMsg}) — cancelling the resting entry order so it can't fill unprotected`);
+                        try {
+                            await this.api.cancelOrderByClientId(clientOrderId, symbol);
+                        }
+                        catch (err) {
+                            logger.error(TAG, `Cancel of resting entry after invalid bracket failed for ${symbol}: ${formatError(err)}`);
+                        }
+                    }
+                    throw new Error(`Bracket rejected (post-submit): ${dirMsg}`);
                 }
                 const bracketId = generateBracketId();
                 this.bracketManager.registerEntry({ symbol, side, stopPrice: metadata.stopPrice, targetPrice: metadata.targetPrice }, bracketId, clientOrderId);
@@ -866,7 +912,8 @@ export class LiveAdapter extends EventEmitter {
             const result = await this.bracketManager.attachBrackets(symbol, entryAmount);
             if (!result.ok) {
                 logger.error(TAG, `Bracket attach FAILED for ${symbol} after ${result.attempts} attempts: ${result.error}. Auto-flattening position.`);
-                // Best-effort emergency close. closePosition has its own retry logic.
+                // Best-effort emergency close. closePosition has its own retry logic +
+                // journals the auto-flatten close itself (keyed on the reason, #196).
                 try {
                     await this.closePosition(symbol, 'bracket_attach_failed');
                 }
@@ -880,6 +927,64 @@ export class LiveAdapter extends EventEmitter {
             logger.error(TAG, `attachBracketsAsync unexpected error for ${symbol}: ${formatError(err)}`);
         }
     }
+    /**
+     * 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.
+     */
+    async enrichFilledAvgPrice(order, clientOrderId, symbol) {
+        const rawAvg = order.average;
+        try {
+            const requeried = await this.api.fetchOrderByClientId(clientOrderId, symbol);
+            const resolved = requeried ? fillPriceFromOrder(requeried) : null;
+            if (resolved !== null && resolved > 0) {
+                order.average = resolved;
+                // Carry cumQuote across too, so cost-based consumers (VWAP, slippage)
+                // see the settled notional rather than 0.
+                if ((order.cost === 0 || order.cost == null) && requeried && requeried.cost > 0) {
+                    order.cost = requeried.cost;
+                }
+                logger.info(TAG, `Fill-price enriched for ${symbol}: avg ${rawAvg ?? 'null'} → ${resolved} (re-query by cid; limit price ${order.price ?? 'n/a'})`);
+                return;
+            }
+            logger.warn(TAG, `Fill-price enrichment for ${symbol} could not resolve an average (re-query avg=${requeried?.average ?? 'null'} cost=${requeried?.cost ?? 'null'} filled=${requeried?.filled ?? 'null'}); downstream uses mark price / skips capture, NOT the limit price ${order.price ?? 'n/a'}`);
+        }
+        catch (err) {
+            logger.warn(TAG, `Fill-price enrichment re-query for ${symbol} threw: ${formatError(err)}; leaving average as-is`);
+        }
+    }
+    /**
+     * 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.
+     */
+    captureAutoFlattenClose(symbol, closeOrder) {
+        if (!this.autoCapture)
+            return;
+        const fillPrice = fillPriceFromOrder(closeOrder);
+        // A synthetic "already flat" return (filled=0, avg=null) means another path
+        // (a bracket fill / external close) owns the real close — don't mislabel it
+        // as bracket_attach_failed and don't invent a price.
+        if (fillPrice === null || !(closeOrder.filled > 0))
+            return;
+        void onAutoFlattenClose(this.autoCapture, {
+            symbol,
+            fillPrice,
+            fillSize: Math.abs(closeOrder.filled),
+            ...(typeof closeOrder.id === 'string' && closeOrder.id.length > 0
+                ? { exchangeTradeId: closeOrder.id }
+                : {}),
+        }).catch((err) => logger.warn(TAG, `auto-flatten close capture for ${symbol} threw: ${formatError(err)}`));
+    }
     /** 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. */
@@ -1379,6 +1484,14 @@ export class LiveAdapter extends EventEmitter {
                     const order = await this.api.createOrder(symbol, closeSide, 'market', position.contracts, undefined, ccxtParams);
                     logger.info(TAG, `FLATTEN: ${symbol} close order ${order.id} status=${order.status}`);
                     this.emit('emergency_progress', { action: 'flatten', status: 'completed', symbol });
+                    // Auto-flatten (bracket_attach_failed) bypasses the close_position tool,
+                    // so onClosePositionFilled never journals its close and the position row
+                    // orphans as status='open' (issue #196). Journal it here from the real
+                    // close fill. Other reasons (operator_command, agent close_position) are
+                    // journaled by their own paths — don't double-capture.
+                    if (closeReason === 'bracket_attach_failed') {
+                        this.captureAutoFlattenClose(symbol, order);
+                    }
                     return order;
                 }
                 catch (err) {
@@ -1456,12 +1569,17 @@ export class LiveAdapter extends EventEmitter {
             emitUnprotected(`threw: ${formatError(err)}`);
         }
     }
-    async getBalance() {
+    /** 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. */
+    async getBalanceOrNull() {
         const balance = await this.api.fetchBalance();
         this.syncRateLimits();
         this.rateLimiter.recordQuery(ENDPOINT_WEIGHTS.fetchBalance ?? 5);
         if (!balance) {
-            return { free: {}, used: {}, total: {} };
+            return null;
         }
         // Binance USDⓈ-M quirk: `availableBalance` is only populated for the primary
         // margin asset (USDT). Secondary collaterals like USDC come back with
@@ -1499,6 +1617,17 @@ export class LiveAdapter extends EventEmitter {
         const cachedPositions = this.reconciler.getLastExchangePositions();
         return this.enricher.enrich(balance, cachedPositions);
     }
+    /** 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(). */
+    async getBalance() {
+        const balance = await this.getBalanceOrNull();
+        if (!balance) {
+            return { free: {}, used: {}, total: {} };
+        }
+        return balance;
+    }
     /** Re-anchor the realized-today seed + sessionStartNav from /fapi/v1/income.
      *  Throttled to {@link INCOME_REFRESH_MIN_INTERVAL_MS}; UTC date rollover
      *  forces an immediate refresh. Best-effort — failures are logged and

package/live/position-state-store.d.ts

@@ -10,6 +10,10 @@ export interface PositionStateEntry {
     webappPositionId?: string;
     /** exchangeTradeId of the opening fill (audit trail). */
     openedFromExchangeTradeId?: string;
+    /** setup_type from the entry metadata (e.g. 'pullback_trend_short_4h').
+     *  Carried so close paths can record the exit into the re-entry tracker
+     *  keyed by (symbol, setup) — issue #204. Optional; older entries lack it. */
+    setupType?: string;
     /** Last record_position_reviews call timestamp (epoch ms). Drives stale-gate. */
     lastReviewAt?: number;
     lastVerdict?: 'hold' | 'add_on' | 'close_recommended';

package/live/stop-watcher.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { CcxtPosition } from '../types.js';
+import type { CcxtOrder, CcxtPosition } from '../types.js';
 import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export declare const DEFAULT_INTERVAL_MS = 10000;
 export interface StopTriggeredEvent {
@@ -10,6 +10,13 @@ export interface StopTriggeredEvent {
     markPrice: number;
     quantity: number;
 }
+/** Emitted with 'stop_closed' — carries the executed close order so listeners
+ *  (the journal auto-capture wiring in index.ts) can record the close with the
+ *  real fill. Without this, watcher closes bypassed the Position Decision
+ *  Journal entirely and left phantom-open journal positions (issue #199). */
+export interface StopClosedEvent extends StopTriggeredEvent {
+    order?: CcxtOrder;
+}
 export type Wave9StopCloseOutcome = {
     status: 'flat';
     detail: string;

package/live/stop-watcher.js

@@ -138,6 +138,9 @@ export class PositionWatcher extends EventEmitter {
             quantity: position.contracts,
         };
         this.emit('stop_triggered', event);
+        // Captured close order for the 'stop_closed' event — set inside close()
+        // (which may run under the symbol lock) and read after it resolves.
+        let closeOrder;
         const close = async () => {
             let trustedPosition = position;
             // Re-read after acquiring the shared trading boundary. A Wave 9
@@ -169,7 +172,7 @@ export class PositionWatcher extends EventEmitter {
                 throw new Error(`Wave 9 ownership resolution failed before stop close submission: ${ownershipError}; ` +
                     'IMMEDIATE MANUAL INTERVENTION REQUIRED');
             }
-            await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher');
+            closeOrder = await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher');
             if (!candidateId || !this.wave9CloseLifecycle)
                 return 'closed';
             const outcome = await this.wave9CloseLifecycle.settleAfterClose(candidateId, trustedPosition.symbol);
@@ -190,7 +193,7 @@ export class PositionWatcher extends EventEmitter {
             if (result !== 'closed')
                 return;
             logger.info(TAG, `Auto-closed ${position.symbol} (reason=stop_watcher)`);
-            this.emit('stop_closed', event);
+            this.emit('stop_closed', { ...event, order: closeOrder });
         }
         catch (err) {
             const msg = formatError(err);

package/onboarding/runtime.d.ts

@@ -3,6 +3,8 @@ import type { ExchangeConfig, TradingMode } from '../types.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { PaperMarketFeed } from '../simulator/paper-market-feed.js';
 import { LiveAdapter } from '../live/live-adapter.js';
+import type { HlCredentials } from '../venues/hyperliquid/hl-private.js';
+import { type VenueId } from '../venues/registry.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
 import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export interface MicroLiveConfig {
@@ -14,6 +16,14 @@ export interface BuildAdapterInput {
     exchange: ExchangeConfig | null;
     microLive?: MicroLiveConfig;
     simulator: ExchangeSimulator;
+    /** Venue seam for the RUNTIME transition path (issue #217). Absent →
+     *  'binance' (every pre-venue caller byte-identical). The BOOT path got
+     *  this seam in Phase 3 (createLiveAdapter in index.ts); the runtime flip
+     *  — set_trading_mode, the product's go-live moment — missed it and
+     *  constructed a Binance LiveAdapter unconditionally. */
+    venue?: VenueId;
+    /** Required for a live-mode build on the hyperliquid venue. */
+    hlCredentials?: HlCredentials | null;
 }
 /** Wave 9 safety wiring is created only after its durable ledger is loaded.
  *  Runtime reapplies these hooks to both the bootstrap objects and every
@@ -47,6 +57,11 @@ export declare class PluginRuntime {
     private readonly _marketFeed;
     private readonly operationLock?;
     private wave9LiveLifecycleHooks?;
+    /** Observer applied to EVERY stop-watcher this runtime creates (reconnects
+     *  included). index.ts uses it to attach the journal auto-capture listener
+     *  for watcher closes (issue #199) — without it, a live<->paper reconnect
+     *  would silently shed the capture wiring. */
+    private readonly onWatcherCreated?;
     /** Reconnect is serialized — a second caller waits for the first to finish
      *  so we never tear down an adapter that's mid-rebuild. */
     private reconnectInFlight;
@@ -57,6 +72,7 @@ export declare class PluginRuntime {
         stopWatcher?: PositionWatcher | null;
         marketFeed?: PaperMarketFeed | null;
         operationLock?: TradingOperationLock;
+        onWatcherCreated?: (watcher: PositionWatcher) => void;
     });
     get adapter(): IExchangeAdapter;
     get mode(): TradingMode;
@@ -75,6 +91,8 @@ export declare class PluginRuntime {
         mode: TradingMode;
         exchange: ExchangeConfig | null;
         microLive?: MicroLiveConfig;
+        venue?: VenueId;
+        hlCredentials?: HlCredentials | null;
     }, deps: {
         adapterDeps: {
             adapter: IExchangeAdapter;