@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/tools/create-order.js

@@ -0,0 +1,1555 @@
+// Tool: create_order — order execution with real price data + pre-trade risk gate
+// Readiness gate: BLOCKED unless adapter.readiness === 'READY'.
+import { randomUUID } from 'node:crypto';
+import { formatError } from '../logger.js';
+import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
+import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
+import { validateCreateOrder, sanitizeRealizationRule, validateProtectiveGeometry } from './assessment-validation.js';
+import { preTradeRiskCheck, getDefaultPreTradeLimits, computeConsecutiveLosses } from '../risk/pre-trade-check.js';
+import { bracketsEnabled, loadBracketMode, loadBracketRequirements } from '../config/brackets-config.js';
+import { onCreateOrderFilled } from '../ingest/position-auto-capture.js';
+import { wave9ClientOrderId, } from '../wave9/live-execution-ledger.js';
+import { inspectWave9LiveSymbolOwnership, } from '../wave9/live-symbol-ownership.js';
+import { confirmWave9LivePositionFlat } from '../wave9/live-position-confirmation.js';
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+import { buildHlOrderCloid } from '../venues/hyperliquid/hl-cloid.js';
+import { reprotectWave9LiveResidual, } from '../wave9/live-residual-protection.js';
+import { captureWave9PaperAccountSnapshot, isWave9ManagedPosition, WAVE9_BUNDLE_SETUP_TYPE, } from '../wave9/paper-admission-guard.js';
+function currentWave9ExecutionMode(deps) {
+    const runtimeMode = deps.wave9TradingModeCheck?.() ?? deps.adapter.mode;
+    if (!deps.adapter.isLive && deps.adapter.mode === 'PAPER' && runtimeMode === 'PAPER')
+        return 'PAPER';
+    if (deps.adapter.isLive && deps.adapter.mode === 'LIVE' && runtimeMode === 'LIVE')
+        return 'LIVE';
+    return null;
+}
+function residualProtectionMessage(outcome) {
+    const protection = outcome.residualProtection;
+    if (!protection)
+        return ' Residual protection state is unavailable.';
+    return protection.status === 'protected'
+        ? ` The residual is protected by the proven frozen native stop ${protection.stopPrice}` +
+            `${protection.stopClientOrderId ? ` (${protection.stopClientOrderId})` : ''}.`
+        : ` ${protection.detail}`;
+}
+function confirmedWave9EntryPrice(order, side, stopPrice) {
+    const average = typeof order.average === 'number'
+        && Number.isFinite(order.average)
+        && order.average > 0
+        ? order.average
+        : undefined;
+    const limitPrice = typeof order.price === 'number'
+        && Number.isFinite(order.price)
+        && order.price > 0
+        ? order.price
+        : undefined;
+    const responsePrice = average ?? limitPrice;
+    if (responsePrice === undefined)
+        return undefined;
+    return side === 'buy'
+        ? (responsePrice > stopPrice ? responsePrice : undefined)
+        : (responsePrice < stopPrice ? responsePrice : undefined);
+}
+function confirmedWave9ExchangeOrderId(order) {
+    return typeof order.id === 'string'
+        && order.id.length > 0
+        && order.id.length <= 512
+        && order.id.trim() === order.id
+        ? order.id
+        : undefined;
+}
+async function flattenFailedWave9LiveEntry(adapter, ledger, symbol, candidateId, identity, residualProtector = reprotectWave9LiveResidual) {
+    let observation = await observeWave9LiveResidual(adapter, symbol, identity.side);
+    if (observation.status !== 'visible') {
+        const alreadyFlat = await confirmWave9LivePositionFlat(adapter, symbol);
+        if (alreadyFlat.confirmed) {
+            let terminalPersistenceError;
+            try {
+                await ledger.markClosed(candidateId);
+            }
+            catch (err) {
+                terminalPersistenceError = formatError(err);
+            }
+            return {
+                confirmedFlat: true,
+                confirmationDetail: alreadyFlat.detail,
+                closeAttempted: false,
+                ...(terminalPersistenceError ? { terminalPersistenceError } : {}),
+            };
+        }
+        // A terminal market fill can become visible during the stable-flat
+        // window. Re-read once as positive identity evidence; the failed flat
+        // proof itself never authorizes a symbol-wide mutation.
+        observation = await observeWave9LiveResidual(adapter, symbol, identity.side);
+    }
+    const residualQuantity = observation.status === 'visible'
+        ? observation.quantity
+        : undefined;
+    if (!Number.isFinite(identity.maximumQuantity)
+        || identity.maximumQuantity <= 0
+        || residualQuantity === undefined
+        || !Number.isFinite(residualQuantity)
+        || residualQuantity <= 0
+        || residualQuantity > identity.maximumQuantity) {
+        let stopPrice = 0;
+        try {
+            stopPrice = ledger.getByCandidateId(candidateId)?.initialStop ?? 0;
+        }
+        catch {
+            // Keep the identity refusal as the primary error.
+        }
+        return {
+            confirmedFlat: false,
+            confirmationDetail: `Wave 9 exposure identity fence refused symbol-wide flatten: ${observation.detail}; ` +
+                `maximum attributable quantity ${identity.maximumQuantity}`,
+            closeAttempted: false,
+            residualProtection: {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: refusing native-stop replacement or ` +
+                    `symbol-wide flatten because current exposure is not exactly candidate-bound ` +
+                    `(${observation.detail}; maximum ${identity.maximumQuantity})`,
+                candidateId,
+                symbol,
+                stopPrice,
+                ...(residualQuantity !== undefined ? { residualQuantity } : {}),
+            },
+        };
+    }
+    let flattenError;
+    try {
+        await adapter.closePosition(symbol, 'bracket_attach_failed');
+    }
+    catch (err) {
+        flattenError = formatError(err);
+    }
+    const confirmation = await confirmWave9LivePositionFlat(adapter, symbol);
+    const terminalSafeFlat = confirmation.confirmed && flattenError === undefined;
+    let terminalPersistenceError;
+    if (terminalSafeFlat) {
+        try {
+            await ledger.markClosed(candidateId);
+        }
+        catch (err) {
+            terminalPersistenceError = formatError(err);
+        }
+    }
+    let residualProtection;
+    if (!confirmation.confirmed) {
+        try {
+            residualProtection = await residualProtector(adapter, ledger, candidateId, symbol);
+        }
+        catch (err) {
+            let stopPrice = 0;
+            try {
+                stopPrice = ledger.getByCandidateId(candidateId)?.initialStop ?? 0;
+            }
+            catch {
+                // Preserve the original re-protection failure in the escalation.
+            }
+            residualProtection = {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: residual re-protection threw: ${formatError(err)}`,
+                candidateId,
+                symbol,
+                stopPrice,
+            };
+        }
+    }
+    return {
+        confirmedFlat: terminalSafeFlat,
+        confirmationDetail: confirmation.confirmed && flattenError
+            ? `trusted flat snapshots were observed, but the emergency close mutation was not acknowledged ` +
+                `(${flattenError}); positive-fill settlement may still be lagging`
+            : confirmation.detail,
+        closeAttempted: true,
+        ...(flattenError ? { flattenError } : {}),
+        ...(terminalPersistenceError ? { terminalPersistenceError } : {}),
+        ...(residualProtection ? { residualProtection } : {}),
+    };
+}
+function canonicalWave9Symbol(symbol) {
+    return symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+async function observeWave9LiveResidual(adapter, symbol, side) {
+    let positions;
+    try {
+        positions = await adapter.getPositionsOrNull(symbol);
+    }
+    catch (err) {
+        return { status: 'unknown', detail: `position read threw: ${formatError(err)}` };
+    }
+    if (positions === null || !Array.isArray(positions)) {
+        return { status: 'unknown', detail: 'position state is unknown' };
+    }
+    const target = canonicalWave9Symbol(symbol);
+    const expectedPositionSide = side === 'buy' ? 'long' : 'short';
+    const visible = [];
+    for (const position of positions) {
+        if (!position
+            || typeof position.symbol !== 'string'
+            || typeof position.contracts !== 'number'
+            || !Number.isFinite(position.contracts)
+            || position.contracts < 0) {
+            return { status: 'unknown', detail: 'position snapshot contained malformed rows' };
+        }
+        if (canonicalWave9Symbol(position.symbol) !== target || position.contracts === 0)
+            continue;
+        if (position.side !== expectedPositionSide) {
+            return {
+                status: 'unknown',
+                detail: `visible residual side ${position.side} does not match ${expectedPositionSide}`,
+            };
+        }
+        visible.push(position);
+    }
+    if (visible.length === 0)
+        return { status: 'flat', detail: 'one trusted snapshot is currently empty' };
+    if (visible.length !== 1) {
+        return { status: 'unknown', detail: 'multiple matching residual position rows were returned' };
+    }
+    return {
+        status: 'visible',
+        detail: `exchange reports ${visible[0].contracts} residual contracts`,
+        quantity: visible[0].contracts,
+    };
+}
+function candidateBoundFoundOrder(resolution, clientOrderId, symbol, side) {
+    if (resolution.status !== 'found')
+        return undefined;
+    const order = resolution.order;
+    if (order.clientOrderId !== clientOrderId
+        || canonicalWave9Symbol(order.symbol) !== canonicalWave9Symbol(symbol)
+        || order.side !== side
+        || order.type !== 'market'
+        || confirmedWave9ExchangeOrderId(order) === undefined
+        || (order.status !== 'open' && order.status !== 'closed' && order.status !== 'canceled')
+        || typeof order.amount !== 'number'
+        || !Number.isFinite(order.amount)
+        || order.amount <= 0
+        || typeof order.filled !== 'number'
+        || !Number.isFinite(order.filled)
+        || order.filled < 0
+        || order.filled > order.amount + 1e-9 * Math.max(1, order.amount))
+        return undefined;
+    return order;
+}
+/** Venue-aware idempotency cid for the live entry stash. HL client-order-ids
+ *  are 128-bit hex (0x + 32 hex chars) — a dashed randomUUID() fails
+ *  hl-private's cloid validation and the ENTRY IS REJECTED before reaching
+ *  the exchange (found live by the go-live rehearsal's first dust trade).
+ *  buildHlOrderCloid() mints the 0x0d… ORDER prefix, which the bracket parser
+ *  deliberately never recognises (cross-scheme cancels are destructive). */
+export function mintEntryStashCid(adapter) {
+    return adapter instanceof HyperliquidLiveAdapter ? buildHlOrderCloid() : randomUUID();
+}
+async function resolveWave9EntryCid(adapter, clientOrderId, symbol) {
+    if (!adapter.resolveOrderByClientId) {
+        return { status: 'unknown', detail: 'deterministic client-order resolver is unavailable' };
+    }
+    try {
+        return await adapter.resolveOrderByClientId(clientOrderId, symbol);
+    }
+    catch (err) {
+        return { status: 'unknown', detail: `client-order resolution threw: ${formatError(err)}` };
+    }
+}
+function flattenRecoveryOutcome(flatten, context, durableOpenEstablished) {
+    if (flatten.confirmedFlat && !flatten.terminalPersistenceError) {
+        return {
+            status: 'terminal',
+            detail: flatten.closeAttempted
+                ? `${context}; emergency close reached stable flat and durable ownership is CLOSED`
+                : `${context}; exchange was already stably flat and durable ownership is CLOSED`,
+        };
+    }
+    if (flatten.confirmedFlat) {
+        return {
+            status: 'manual_intervention',
+            detail: `${context}; stable flat was established, but durable CLOSED persistence failed: ` +
+                `${flatten.terminalPersistenceError}`,
+        };
+    }
+    if (flatten.residualProtection?.status === 'protected') {
+        if (!durableOpenEstablished) {
+            return {
+                status: 'manual_intervention',
+                detail: `${context}; the residual has a proven frozen native stop ` +
+                    `${flatten.residualProtection.stopPrice}, but durable OPEN ownership is unavailable. ` +
+                    'IMMEDIATE MANUAL INTERVENTION REQUIRED',
+            };
+        }
+        return {
+            status: 'protected',
+            detail: `${context}; emergency close left a residual, whose exact frozen native stop ` +
+                `${flatten.residualProtection.stopPrice} is proven live`,
+        };
+    }
+    return {
+        status: 'manual_intervention',
+        detail: `${context}; ${flatten.closeAttempted
+            ? 'emergency close did not establish stable flat'
+            : 'symbol-wide flatten was not authorized by the exposure identity fence'} ` +
+            `(${flatten.confirmationDetail}). ` +
+            `${flatten.residualProtection?.detail ?? 'IMMEDIATE MANUAL INTERVENTION REQUIRED'}`,
+    };
+}
+async function recoverWave9LiveSubmitThrow(input) {
+    const recoverCandidateExposure = async (foundOrder, recoveryQuantity, observation, context, entryTerminalProven) => {
+        if (!entryTerminalProven) {
+            let openPersistenceError;
+            try {
+                // Establish ownership without freezing an underreported fill while
+                // the entry order may still add to the position.
+                await input.ledger.markOpen(input.candidateId, {
+                    ...(foundOrder ? { exchangeOrderId: foundOrder.id } : {}),
+                });
+            }
+            catch (err) {
+                openPersistenceError = formatError(err);
+            }
+            let stopConfirmed = false;
+            try {
+                stopConfirmed = await input.confirmStop({
+                    candidateId: input.candidateId,
+                    symbol: input.symbol,
+                    entryClientOrderId: input.clientOrderId,
+                    entrySide: input.side,
+                    stopPrice: input.stopPrice,
+                    filledQuantity: recoveryQuantity,
+                });
+            }
+            catch {
+                stopConfirmed = false;
+            }
+            return {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: ${context}; the deterministic entry order ` +
+                    `is not proven terminal, so its final filled quantity is unknown and emergency flatten ` +
+                    `cannot safely claim CLOSED. ${stopConfirmed
+                        ? 'A candidate-bound close-all stop is currently proven live.'
+                        : 'Exact native stop protection is unconfirmed.'}` +
+                    `${openPersistenceError ? ` Durable OPEN persistence failed (${openPersistenceError}).` : ''}`,
+            };
+        }
+        const persistTerminalOpen = async () => {
+            if (recoveryQuantity > input.authorizedQuantity) {
+                return `final fill ${recoveryQuantity} exceeds authorized quantity ${input.authorizedQuantity}`;
+            }
+            const entryPrice = foundOrder
+                ? confirmedWave9EntryPrice(foundOrder, input.side, input.stopPrice)
+                : undefined;
+            try {
+                await input.ledger.markOpen(input.candidateId, {
+                    filledQuantity: recoveryQuantity,
+                    ...(foundOrder ? { exchangeOrderId: foundOrder.id } : {}),
+                    ...(entryPrice !== undefined ? { entryPrice } : {}),
+                });
+                return undefined;
+            }
+            catch (err) {
+                const markOpenError = formatError(err);
+                if (foundOrder
+                    && typeof input.ledger.reconcileOpenFillFromExactOrder === 'function') {
+                    try {
+                        await input.ledger.reconcileOpenFillFromExactOrder(input.candidateId, {
+                            filledQuantity: recoveryQuantity,
+                            exchangeOrderId: foundOrder.id,
+                            ...(entryPrice !== undefined ? { entryPrice } : {}),
+                        });
+                        return undefined;
+                    }
+                    catch (reconcileError) {
+                        return `${markOpenError}; exact terminal fill reconciliation failed: ${formatError(reconcileError)}`;
+                    }
+                }
+                return markOpenError;
+            }
+        };
+        const openPersistenceError = await persistTerminalOpen();
+        const maximumRecoverableQuantity = Math.min(recoveryQuantity, input.authorizedQuantity);
+        let currentObservation = observation;
+        if (currentObservation.status !== 'visible') {
+            const flat = await confirmWave9LivePositionFlat(input.adapter, input.symbol);
+            if (flat.confirmed) {
+                if (openPersistenceError) {
+                    return {
+                        status: 'manual_intervention',
+                        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: exact terminal fill and stable flatness ` +
+                            `were proven, but durable OPEN persistence failed (${openPersistenceError})`,
+                    };
+                }
+                try {
+                    await input.ledger.markClosed(input.candidateId);
+                    return {
+                        status: 'terminal',
+                        detail: `${context}; exact terminal fill is no longer present and exchange flatness ` +
+                            `remained stable (${flat.detail}); durable ownership is CLOSED`,
+                    };
+                }
+                catch (err) {
+                    return {
+                        status: 'manual_intervention',
+                        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: exact terminal fill and stable flatness ` +
+                            `were proven, but CLOSED persistence failed (${formatError(err)})`,
+                    };
+                }
+            }
+            // Visibility can lag the exact order lookup. Re-read only as positive
+            // identity evidence after the stable-flat window; never interpret a
+            // failed/unknown flat proof as permission to close a symbol.
+            currentObservation = await observeWave9LiveResidual(input.adapter, input.symbol, input.side);
+        }
+        const quantity = currentObservation.status === 'visible'
+            ? currentObservation.quantity
+            : undefined;
+        if (quantity === undefined
+            || !Number.isFinite(quantity)
+            || quantity <= 0
+            || quantity > maximumRecoverableQuantity) {
+            return {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: exact terminal entry fill is proven, but ` +
+                    `current same-symbol exposure is not safely candidate-bound (${currentObservation.detail}; ` +
+                    `maximum attributable quantity ${maximumRecoverableQuantity}). Refusing native-stop ` +
+                    `replacement or symbol-wide flatten.${openPersistenceError
+                        ? ` Durable OPEN persistence also failed (${openPersistenceError}).`
+                        : ' Durable ownership remains OPEN.'}`,
+            };
+        }
+        if (!openPersistenceError) {
+            let stopConfirmed = false;
+            try {
+                stopConfirmed = await input.confirmStop({
+                    candidateId: input.candidateId,
+                    symbol: input.symbol,
+                    entryClientOrderId: input.clientOrderId,
+                    entrySide: input.side,
+                    stopPrice: input.stopPrice,
+                    filledQuantity: recoveryQuantity,
+                });
+            }
+            catch {
+                stopConfirmed = false;
+            }
+            if (stopConfirmed) {
+                return {
+                    status: 'protected',
+                    detail: `${context}; the deterministic entry was recovered OPEN with an exact proven native stop`,
+                    ...(foundOrder ? { order: foundOrder } : {}),
+                };
+            }
+        }
+        // A positive exact fill establishes durable ownership, but does not by
+        // itself authorize a symbol-wide mutation. The helper re-observes current
+        // exposure and runs close/re-protection only when side and quantity still
+        // prove that the residual can belong to this candidate.
+        const flatten = await flattenFailedWave9LiveEntry(input.adapter, input.ledger, input.symbol, input.candidateId, {
+            side: input.side,
+            maximumQuantity: Math.min(recoveryQuantity, input.authorizedQuantity),
+        }, input.residualProtector);
+        const outcome = flattenRecoveryOutcome(flatten, openPersistenceError
+            ? `${context}; OPEN persistence failed (${openPersistenceError}); ${observation.detail}`
+            : `${context}; exact stop was unavailable; ${observation.detail}`, openPersistenceError === undefined);
+        return foundOrder && outcome.status === 'protected'
+            ? { ...outcome, order: foundOrder }
+            : outcome;
+    };
+    const exactStopProven = async (quantity) => {
+        let stopConfirmed = false;
+        try {
+            stopConfirmed = await input.confirmStop({
+                candidateId: input.candidateId,
+                symbol: input.symbol,
+                entryClientOrderId: input.clientOrderId,
+                entrySide: input.side,
+                stopPrice: input.stopPrice,
+                filledQuantity: quantity,
+            });
+        }
+        catch {
+            stopConfirmed = false;
+        }
+        return stopConfirmed;
+    };
+    const terminalizeOpenEntry = async (order) => {
+        try {
+            await input.adapter.cancelOrder(order.id, input.symbol);
+        }
+        catch (err) {
+            return { error: `exact open-entry cancellation failed: ${formatError(err)}` };
+        }
+        const afterCancel = await resolveWave9EntryCid(input.adapter, input.clientOrderId, input.symbol);
+        if (afterCancel.status === 'confirmed_absent') {
+            return order.filled === 0
+                ? { confirmedAbsent: true }
+                : { error: 'positive-fill entry disappeared after cancellation; final fill is unknown' };
+        }
+        const resolved = candidateBoundFoundOrder(afterCancel, input.clientOrderId, input.symbol, input.side);
+        if (!resolved) {
+            return {
+                error: afterCancel.status === 'unknown'
+                    ? `post-cancel entry state is unknown (${afterCancel.detail})`
+                    : 'post-cancel entry identity is mismatched',
+            };
+        }
+        return resolved.status === 'open'
+            ? { error: 'exact entry order remains open after cancellation' }
+            : { order: resolved };
+    };
+    const acknowledgedOrder = input.acknowledgedOrder
+        ? candidateBoundFoundOrder({ status: 'found', order: input.acknowledgedOrder }, input.clientOrderId, input.symbol, input.side)
+        : undefined;
+    let resolution = acknowledgedOrder
+        ? { status: 'found', order: acknowledgedOrder }
+        : await resolveWave9EntryCid(input.adapter, input.clientOrderId, input.symbol);
+    let foundOrder = candidateBoundFoundOrder(resolution, input.clientOrderId, input.symbol, input.side);
+    if (resolution.status === 'found' && !foundOrder) {
+        return {
+            status: 'manual_intervention',
+            detail: 'IMMEDIATE MANUAL INTERVENTION REQUIRED: client-order lookup returned mismatched candidate identity',
+        };
+    }
+    let residual = await observeWave9LiveResidual(input.adapter, input.symbol, input.side);
+    let foundFilled = foundOrder
+        && Number.isFinite(foundOrder.filled)
+        && foundOrder.filled > 0
+        ? foundOrder.filled
+        : undefined;
+    if (foundFilled !== undefined) {
+        if (foundOrder.status === 'open') {
+            const terminalized = await terminalizeOpenEntry(foundOrder);
+            if (!terminalized.order || terminalized.order.filled <= 0) {
+                try {
+                    await input.ledger.markOpen(input.candidateId, {
+                        exchangeOrderId: foundOrder.id,
+                    });
+                }
+                catch {
+                    // The manual outcome remains load-bearing even if persistence fails.
+                }
+                return {
+                    status: 'manual_intervention',
+                    detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: positive partial fill has an unproven ` +
+                        `final quantity (${terminalized.error ?? 'post-cancel identity unavailable'}); ` +
+                        'durable ownership remains OPEN without a frozen filled quantity',
+                };
+            }
+            foundOrder = terminalized.order;
+            foundFilled = terminalized.order.filled;
+        }
+        return recoverCandidateExposure(foundOrder, foundFilled, residual, `submit threw (${formatError(input.submitError)}) and the exact CID shows a positive fill`, true);
+    }
+    if (resolution.status === 'unknown' && residual.status === 'visible') {
+        return recoverCandidateExposure(undefined, residual.quantity, residual, `submit threw and CID resolution is unknown with a same-side residual`, false);
+    }
+    // A proven candidate-bound close-all stop is itself strong evidence that
+    // LiveAdapter progressed past submission even if position visibility lags.
+    if (resolution.status === 'unknown'
+        && await exactStopProven(input.authorizedQuantity)) {
+        return recoverCandidateExposure(undefined, input.authorizedQuantity, residual, 'submit acknowledgement is unknown, but its exact candidate-bound native stop is live', false);
+    }
+    if (foundOrder?.status === 'open' && foundOrder.filled === 0) {
+        const terminalized = await terminalizeOpenEntry(foundOrder);
+        if (terminalized.error) {
+            return {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: the deterministic zero-fill entry remains ` +
+                    `nonterminal (${terminalized.error})`,
+            };
+        }
+        if (terminalized.confirmedAbsent) {
+            resolution = { status: 'confirmed_absent' };
+            foundOrder = undefined;
+        }
+        else if (terminalized.order) {
+            resolution = { status: 'found', order: terminalized.order };
+            foundOrder = terminalized.order;
+        }
+    }
+    const flat = await confirmWave9LivePositionFlat(input.adapter, input.symbol);
+    let finalResolution = await resolveWave9EntryCid(input.adapter, input.clientOrderId, input.symbol);
+    let finalOrder = candidateBoundFoundOrder(finalResolution, input.clientOrderId, input.symbol, input.side);
+    if (finalResolution.status === 'found' && !finalOrder) {
+        return {
+            status: 'manual_intervention',
+            detail: 'IMMEDIATE MANUAL INTERVENTION REQUIRED: final client-order lookup returned mismatched candidate identity',
+        };
+    }
+    if (finalOrder?.status === 'open') {
+        const openOrder = finalOrder;
+        const terminalized = await terminalizeOpenEntry(openOrder);
+        if (terminalized.error || (!terminalized.order && !terminalized.confirmedAbsent)) {
+            if (openOrder.filled > 0) {
+                try {
+                    await input.ledger.markOpen(input.candidateId, {
+                        exchangeOrderId: openOrder.id,
+                    });
+                }
+                catch {
+                    // The explicit manual outcome below remains authoritative.
+                }
+            }
+            return {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: final exact entry order is nonterminal ` +
+                    `(${terminalized.error ?? 'post-cancel state unavailable'})`,
+            };
+        }
+        if (terminalized.confirmedAbsent) {
+            finalResolution = { status: 'confirmed_absent' };
+            finalOrder = undefined;
+        }
+        else {
+            finalOrder = terminalized.order;
+            finalResolution = { status: 'found', order: terminalized.order };
+        }
+    }
+    residual = await observeWave9LiveResidual(input.adapter, input.symbol, input.side);
+    if (finalOrder && Number.isFinite(finalOrder.filled) && finalOrder.filled > 0) {
+        return recoverCandidateExposure(finalOrder, finalOrder.filled, residual, 'the exact CID resolved to a positive fill after the settlement window', true);
+    }
+    if (finalResolution.status === 'unknown' && residual.status === 'visible') {
+        return recoverCandidateExposure(undefined, residual.quantity, residual, 'CID resolution remained unknown and a residual appeared during the settlement window', false);
+    }
+    if (finalResolution.status === 'unknown'
+        && await exactStopProven(input.authorizedQuantity)) {
+        return recoverCandidateExposure(undefined, input.authorizedQuantity, residual, 'CID resolution remained unknown, but an exact candidate-bound native stop appeared', false);
+    }
+    const terminalOrder = finalOrder?.status === 'canceled' && finalOrder.filled === 0;
+    let terminalFlat = flat;
+    if (finalResolution.status === 'confirmed_absent' || terminalOrder) {
+        // Bind terminalization to a fresh stable-flat window *after* exact CID
+        // terminal proof. The earlier settlement window can go stale while the
+        // final lookup/cancellation runs.
+        terminalFlat = await confirmWave9LivePositionFlat(input.adapter, input.symbol);
+    }
+    if (terminalFlat.confirmed
+        && (finalResolution.status === 'confirmed_absent' || terminalOrder)) {
+        try {
+            await input.ledger.markClosed(input.candidateId);
+            return {
+                status: 'terminal',
+                detail: `submit threw (${formatError(input.submitError)}), but the exact client order is ` +
+                    `${terminalOrder ? 'canceled with zero fill' : 'confirmed absent'} and the exchange ` +
+                    `remained stably flat`,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'manual_intervention',
+                detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: entry absence and stable flat were proven, ` +
+                    `but CLOSED persistence failed (${formatError(err)})`,
+            };
+        }
+    }
+    return {
+        status: 'manual_intervention',
+        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: submit outcome remains ambiguous; client-order ` +
+            `resolution is ${finalResolution.status} and stable flat is ${terminalFlat.confirmed
+                ? 'present but insufficient without deterministic absence'
+                : `unconfirmed (${terminalFlat.detail})`}. The entry capability is consumed and must not be retried`,
+    };
+}
+/** Build a PortfolioSnapshot from current simulator state (paper mode). */
+function buildPortfolioSnapshotFromSimulator(simulator) {
+    const state = simulator.getState();
+    const quoteCurrency = state.config.quoteCurrency;
+    const walletBal = state.wallet[quoteCurrency];
+    return {
+        positions: state.positions.map(p => {
+            const ticker = simulator.getLastTicker(p.symbol);
+            return {
+                symbol: p.symbol,
+                side: p.side,
+                quantity: p.quantity,
+                entryPrice: p.entryPrice,
+                markPrice: ticker?.last ?? p.entryPrice,
+            };
+        }),
+        walletTotal: walletBal?.total ?? 0,
+        walletAvailable: walletBal?.available ?? 0,
+        sessionStartNav: simulator.getSessionStartNav(),
+        equity: simulator.computeEquity(),
+        isLive: false,
+    };
+}
+/** Build a PortfolioSnapshot from adapter (live mode). */
+async function buildPortfolioSnapshotFromAdapter(adapter) {
+    // Null-honest balance read where the adapter offers one (LiveAdapter) —
+    // getBalance() collapses a FAILED fetch to a phantom-zero object, which
+    // reads as walletTotal=0 against the real sessionStartNav → ~−100%
+    // drawdown → RED zone rejects the entry for the wrong reason (and sizing
+    // runs against walletAvailable=0).
+    const balanceRead = adapter.getBalanceOrNull?.() ?? adapter.getBalance();
+    const [balance, positions] = await Promise.all([
+        balanceRead,
+        adapter.getPositionsOrNull(),
+    ]);
+    // null = positions fetch FAILED (429 / weight-paced / transient). If we
+    // collapsed that to [], existing open positions become invisible to the
+    // pre-trade risk check below — gross exposure / max-open-positions / net
+    // tilt would all be under-counted and a trade that should be blocked could
+    // pass. Refuse to size off a phantom-flat account; abort so the agent
+    // retries next heartbeat. Same null≠empty contract as the close/flatten path.
+    if (positions === null) {
+        throw new Error('Cannot build portfolio snapshot — position fetch failed (exchange data ' +
+            'unavailable, likely Binance 429 or transient). Order NOT placed; retry next heartbeat.');
+    }
+    // Same contract for the balance leg: null = fetch failed, NOT a zero wallet.
+    if (balance === null) {
+        throw new Error('Cannot build portfolio snapshot — balance fetch failed (exchange data ' +
+            'unavailable, likely Binance 429 or transient). Order NOT placed; retry next heartbeat.');
+    }
+    const walletTotal = getQuoteWalletBalance(balance);
+    // Use the session-start NAV captured once at initialization, not the current balance.
+    // If not available (shouldn't happen after init), fall back to current balance.
+    const sessionNav = adapter.getSessionStartNav?.() ?? walletTotal;
+    // Live Binance wallet already includes margin; equity = wallet + unrealized P&L.
+    let liveEquity = walletTotal;
+    for (const p of positions) {
+        const mark = p.markPrice ?? p.entryPrice;
+        const pnl = p.side === 'long'
+            ? (mark - p.entryPrice) * p.contracts
+            : (p.entryPrice - mark) * p.contracts;
+        liveEquity += pnl;
+    }
+    return {
+        positions: positions.map(p => ({
+            symbol: p.symbol,
+            side: p.side,
+            quantity: p.contracts,
+            entryPrice: p.entryPrice,
+            markPrice: p.markPrice,
+        })),
+        walletTotal,
+        walletAvailable: getQuoteBalance(balance.free),
+        sessionStartNav: sessionNav,
+        equity: liveEquity,
+        isLive: true,
+    };
+}
+export async function createOrderTool(args, deps) {
+    const wave9Claimed = isWave9ManagedPosition({
+        setupType: args.setup_type,
+        missionId: args.mission_id,
+    })
+        || args.wave9_admission_token !== undefined
+        || args.candidate_id !== undefined;
+    if (wave9Claimed && deps.wave9VenueCheck?.() !== 'binance') {
+        return { error: 'Wave 9 order refused: execution is pinned to Binance USD-M futures.' };
+    }
+    if (wave9Claimed && !deps.operationLock) {
+        return { error: 'Wave 9 order refused: process-local trading operation lock is unavailable.' };
+    }
+    const initialWave9Mode = wave9Claimed ? currentWave9ExecutionMode(deps) : null;
+    // Wave 9 is a dedicated targetless capability path. Never let a generic
+    // order impersonate it, and require the adapter + mutable runtime mode to
+    // agree exactly before accepting either PAPER or LIVE execution.
+    if (wave9Claimed) {
+        if (args.setup_type !== WAVE9_BUNDLE_SETUP_TYPE) {
+            return { error: `Wave 9 order refused: setup_type must be exactly ${WAVE9_BUNDLE_SETUP_TYPE}.` };
+        }
+        if (!initialWave9Mode) {
+            return {
+                error: 'Wave 9 order refused: capability execution requires an exact PAPER/paper-adapter ' +
+                    'or LIVE/live-adapter runtime match.',
+            };
+        }
+        if ((deps.approvalMode ?? 'off') !== 'off') {
+            return { error: 'Wave 9 order refused: approval mode must be off for immediate mechanical execution.' };
+        }
+        if (!deps.wave9AdmissionGuard || !args.wave9_admission_token || !args.candidate_id || !args.mission_id) {
+            return { error: 'Wave 9 order refused: a dedicated short-lived admission token and exact candidate/mission identity are required.' };
+        }
+        if (args.type.toLowerCase() !== 'market' || args.price !== undefined || args.target_price !== undefined) {
+            return { error: 'Wave 9 order refused: the frozen policy requires a targetless market order with no limit price.' };
+        }
+        const canonical = args.symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+        if (!canonical.endsWith('USDT') || canonical.length <= 4) {
+            return { error: `Wave 9 order refused: unsupported execution symbol ${args.symbol}.` };
+        }
+        if (args.stopPrice === undefined || !Number.isFinite(args.stopPrice) || args.stopPrice <= 0) {
+            return { error: 'Wave 9 order refused: a positive finite initial stop is required.' };
+        }
+        if (initialWave9Mode === 'LIVE') {
+            if (!deps.captureWave9AccountFingerprint
+                || !deps.confirmWave9LiveStop
+                || !deps.wave9LiveLedger) {
+                return {
+                    error: 'Wave 9 live order refused: authoritative live account capture, native-stop confirmation, ' +
+                        'and the durable execution ledger are required.',
+                };
+            }
+            if (!bracketsEnabled(loadBracketMode())) {
+                return { error: 'Wave 9 live order refused: exchange-native bracket protection is not enabled.' };
+            }
+        }
+        // Persist one unified USD-M key regardless of whether an older agent
+        // echoes BTCUSDT or BTC/USDT. Guard matching remains canonical.
+        args = { ...args, symbol: `${canonical.slice(0, -4)}/USDT:USDT` };
+    }
+    // ---- Readiness gate (live mode only) ----
+    if (deps.adapter.readiness !== 'READY') {
+        return { error: `Trading blocked: adapter is ${deps.adapter.readiness}. Wait for initialization to complete.` };
+    }
+    // ---- Assessment-schema gate (SKILL.md v2.10.0 — live mode only) ----
+    // In live mode the agent must include thesis + setup_type + regime +
+    // regime_confidence + scorecard_verdict + confluence_score.  This is the
+    // same data the heartbeat reassessment uses to detect scorecard reversal /
+    // regime flip — if the agent can't produce it at entry, it can't produce
+    // it mid-trade either.
+    const gateCheck = validateCreateOrder(args, deps.adapter.isLive && !wave9Claimed);
+    if (!gateCheck.ok) {
+        return { error: gateCheck.error ?? 'Invalid create_order arguments.' };
+    }
+    // Validate side
+    const side = args.side.toLowerCase();
+    if (side !== 'buy' && side !== 'sell') {
+        return { error: `Invalid side: ${args.side}. Must be 'buy' or 'sell'.` };
+    }
+    // Validate type
+    const type = args.type.toLowerCase();
+    if (type !== 'market' && type !== 'limit') {
+        return { error: `Invalid type: ${args.type}. Must be 'market' or 'limit'.` };
+    }
+    // Validate amount
+    if (!args.amount || args.amount <= 0) {
+        return { error: 'Amount must be a positive number.' };
+    }
+    // Validate price for limit orders
+    if (type === 'limit' && (!args.price || args.price <= 0)) {
+        return { error: 'Limit orders require a positive price.' };
+    }
+    if (args.mission_id !== undefined
+        && (typeof args.mission_id !== 'string'
+            || !/^[A-Za-z0-9_-]{1,128}$/.test(args.mission_id))) {
+        return { error: 'mission_id must be 1-128 letters, numbers, underscores, or hyphens.' };
+    }
+    if (!wave9Claimed
+        && deps.adapter.isLive
+        && deps.checkWave9LiveSymbolOwnership
+        && !deps.operationLock) {
+        return {
+            error: 'Generic live create_order refused: the shared trading operation lock is required ' +
+                'while Wave 9 LIVE ownership checks are enabled.',
+        };
+    }
+    if (!wave9Claimed && !deps.adapter.isLive) {
+        try {
+            deps.refreshPaperState?.();
+            const positions = await deps.adapter.getPositionsOrNull();
+            if (positions === null) {
+                return { error: 'create_order refused: paper position state unavailable for Wave 9 isolation check.' };
+            }
+            if (positions.some(isWave9ManagedPosition)) {
+                return {
+                    error: 'Generic create_order refused: the paper account contains an atomic Wave 9 position. ' +
+                        'The Wave 9 forward book must remain isolated until all of its positions are flat.',
+                };
+            }
+        }
+        catch (err) {
+            return { error: `create_order refused: Wave 9 isolation check failed (${formatError(err)}).` };
+        }
+    }
+    // In paper mode, fetch latest ticker + order book for realistic fills
+    let ticker = null;
+    if (!deps.adapter.isLive) {
+        const paperDeps = { binanceApi: deps.binanceApi, simulator: deps.adapter.getSimulator() };
+        const [priceResult] = await Promise.all([
+            fetchCurrentPrice(args.symbol, paperDeps),
+            fetchOrderBook(args.symbol, paperDeps),
+        ]);
+        if (isError(priceResult))
+            return priceResult;
+        ticker = priceResult;
+    }
+    else {
+        // Live mode: fetch ticker for risk check reference price
+        const lastPrice = await deps.adapter.getLastPrice(args.symbol);
+        if (lastPrice != null) {
+            ticker = {
+                symbol: args.symbol, last: lastPrice,
+                bid: lastPrice, ask: lastPrice, baseVolume: 0, quoteVolume: 0,
+                change: 0, percentage: 0, timestamp: Date.now(), datetime: new Date().toISOString(),
+            };
+        }
+    }
+    if (!ticker) {
+        return { error: `Failed to fetch current price for ${args.symbol}` };
+    }
+    // Once market data exists, consume the capability before any runtime
+    // geometry or generic-gate decision. A delayed stop that is now on the
+    // wrong side is an execution divergence and must latch the daily event.
+    let wave9Lease;
+    if (wave9Claimed) {
+        try {
+            wave9Lease = await deps.operationLock.withAccountLock(`wave9-begin-create:${args.candidate_id ?? args.symbol}`, async () => {
+                if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                    throw new Error('adapter or trading mode changed before Wave 9 admission began');
+                }
+                let accountFingerprint;
+                if (initialWave9Mode === 'LIVE') {
+                    const ownership = deps.checkWave9LiveSymbolOwnership
+                        ? await deps.checkWave9LiveSymbolOwnership(args.symbol)
+                        : await inspectWave9LiveSymbolOwnership(deps.adapter, deps.wave9LiveLedger, args.symbol);
+                    if (ownership.status !== 'unowned'
+                        || ownership.reason === 'authoritative_symbol_flat') {
+                        throw new Error(`candidate-symbol ownership must be refreshed after ` +
+                            `${ownership.status}:${ownership.reason}`);
+                    }
+                    accountFingerprint = (await deps.captureWave9AccountFingerprint()).fingerprint;
+                }
+                else {
+                    deps.refreshPaperState?.();
+                    deps.adapter.getSimulator().getSessionStartNav();
+                    accountFingerprint = captureWave9PaperAccountSnapshot(deps.adapter).fingerprint;
+                }
+                return deps.wave9AdmissionGuard.beginEntry({
+                    token: args.wave9_admission_token,
+                    candidateId: args.candidate_id,
+                    missionId: args.mission_id,
+                    symbol: args.symbol,
+                    side,
+                    type,
+                    quantity: args.amount,
+                    stopPrice: args.stopPrice,
+                    setupType: args.setup_type,
+                    accountFingerprint,
+                    tradingMode: initialWave9Mode,
+                });
+            });
+        }
+        catch (err) {
+            return { error: `Wave 9 admission refused: ${formatError(err)}` };
+        }
+    }
+    const rejectWave9Divergence = (message, code) => {
+        if (wave9Lease) {
+            deps.wave9AdmissionGuard.abort(wave9Lease, code);
+            wave9Lease = undefined;
+        }
+        return { error: `${wave9Claimed ? 'Wave 9 runtime divergence; daily event latched. ' : ''}${message}` };
+    };
+    // From beginEntry onward, every unexpected failure must release the
+    // in-flight capability. Explicit geometry/risk divergences still use the
+    // latching helper above; infrastructure/pure-computation throws are
+    // retryable because no exchange mutation has been attempted.
+    try {
+        // ---- Pre-trade risk gate ----
+        const orderPrice = type === 'limit' ? args.price : ticker.last;
+        if (wave9Claimed && args.stopPrice != null) {
+            if (!Number.isFinite(args.stopPrice) || args.stopPrice <= 0) {
+                return rejectWave9Divergence('stopPrice must be a positive finite number.', 'invalid_stop_price');
+            }
+            if ((side === 'buy' && args.stopPrice >= orderPrice) ||
+                (side === 'sell' && args.stopPrice <= orderPrice)) {
+                return rejectWave9Divergence(`stopPrice is on the wrong side of entry ${orderPrice} for a ${side} order.`, 'actual_market_stop_geometry_diverged');
+            }
+        }
+        // ---- Generic-path protective geometry gate (issue #200) ----
+        // The wrong-side check above ran ONLY for wave9 orders; a generic entry with
+        // its stop/invalidation on the profit side passed validation and was closed
+        // by the stop-watcher seconds later (7 sub-5-minute kills on the 2026-07 HL
+        // soak — one spawned the −$117.86 journal fabrication of issue #199).
+        if (!wave9Claimed) {
+            const geometryError = validateProtectiveGeometry({
+                side: side,
+                refPrice: orderPrice,
+                stopPrice: args.stopPrice,
+                invalidationPrice: args.invalidation_price,
+                targetPrice: args.target_price,
+            });
+            if (geometryError) {
+                return { error: `create_order rejected (protective geometry): ${geometryError}` };
+            }
+        }
+        const proposed = {
+            symbol: args.symbol,
+            side: side,
+            type: type,
+            amount: args.amount,
+            price: orderPrice,
+            stopPrice: args.stopPrice,
+            targetPrice: args.target_price,
+        };
+        // Build portfolio snapshot based on mode
+        let portfolio;
+        let consecutiveLosses = 0;
+        if (!deps.adapter.isLive) {
+            const simulator = deps.adapter.getSimulator();
+            portfolio = buildPortfolioSnapshotFromSimulator(simulator);
+            consecutiveLosses = computeConsecutiveLosses(simulator.getState().tradeHistory);
+        }
+        else {
+            portfolio = await buildPortfolioSnapshotFromAdapter(deps.adapter);
+            // In live mode, consecutive losses would come from intelligence DB — use 0 for now
+        }
+        // Bracket enforcement only applies in live mode when the feature is enabled.
+        // Paper mode uses the stop-watcher and doesn't care about these flags.
+        let bracketEnforcement;
+        if (deps.adapter.isLive && bracketsEnabled(loadBracketMode())) {
+            bracketEnforcement = wave9Claimed
+                ? { requireStopLoss: true, requireTakeProfit: false }
+                : loadBracketRequirements();
+        }
+        const riskCheck = preTradeRiskCheck(proposed, portfolio, getDefaultPreTradeLimits(), {
+            volFactor: !deps.adapter.isLive ? deps.adapter.getSimulator().getVolFactor() : 1.0,
+            consecutiveLosses,
+            bracketEnforcement,
+        });
+        if (!riskCheck.allowed) {
+            const reasons = riskCheck.violations.map(v => v.message).join('; ');
+            return rejectWave9Divergence(`Order REJECTED by risk gate [${riskCheck.drawdownZone} zone]: ${reasons}`, `generic_pretrade_divergence:${riskCheck.violations.map((v) => v.rule).join(',')}`);
+        }
+        // Build position metadata from optional args (only if any metadata provided)
+        // Sanitize numeric metadata — reject non-finite values, clamp ranges
+        const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+        const clamp = (v, min, max) => {
+            const n = num(v);
+            return n != null ? Math.max(min, Math.min(max, n)) : undefined;
+        };
+        const hasMetadata = args.mission_id || args.setup_type || args.thesis || args.target_price != null
+            || args.regime || args.scorecard_verdict || args.confluence_score != null
+            || args.invalidation_price != null || args.realization_rule != null;
+        const metadata = hasMetadata ? {
+            missionId: args.mission_id,
+            setupType: args.setup_type,
+            ...(wave9Claimed ? {
+                candidateId: args.candidate_id,
+                strategy: args.candidate_id.split('|')[2],
+                accruedFundingUsd: 0,
+                fundingThroughTime: args.candidate_id.split('|')[0],
+            } : {}),
+            thesis: args.thesis?.slice(0, 500), // Cap length
+            stopPrice: num(args.stopPrice),
+            targetPrice: num(args.target_price),
+            regime: args.regime,
+            regimeConfidence: clamp(args.regime_confidence, 0, 100),
+            scorecardVerdict: args.scorecard_verdict,
+            confluenceScore: clamp(args.confluence_score, 0, 10),
+            invalidationPrice: num(args.invalidation_price),
+            realizationRule: sanitizeRealizationRule(args.realization_rule),
+        } : undefined;
+        // ---- Approval-mode branches ----
+        // Both shadow and per_trade need full v2.10.0 metadata so the proposal is
+        // operator-meaningful. Metadata is the agent's responsibility; ingest creds
+        // are the operator's. Separate so the error messages can be precise.
+        const argsMetadataComplete = !!(args.thesis &&
+            args.setup_type &&
+            args.target_price != null &&
+            args.stopPrice != null &&
+            args.regime &&
+            typeof args.regime_confidence === 'number' &&
+            args.scorecard_verdict &&
+            typeof args.confluence_score === 'number');
+        const proposalPathWired = !!(deps.proposalManager && deps.userId);
+        const approvalMode = deps.approvalMode ?? 'off';
+        // per_trade mode: propose and EARLY-RETURN. The agent's call doesn't fire;
+        // the operator approves and ProposalDecisionListener fires via this same
+        // tool with proposalManager omitted (which takes the real path below).
+        //
+        // If proposalManager isn't wired (operator set approval.mode=per_trade in
+        // config but ingest creds aren't present), we fall through to the normal
+        // fire path — the startup warning is the operator's signal. We never trap
+        // the agent inside an unfireable per_trade branch.
+        if (approvalMode === 'per_trade' && proposalPathWired) {
+            if (!argsMetadataComplete) {
+                return {
+                    error: 'approval.mode=per_trade requires the full v2.10.0 metadata block on every create_order: ' +
+                        'thesis, setup_type, target_price, stopPrice, regime, regime_confidence, ' +
+                        'scorecard_verdict, confluence_score. The operator approves on this metadata.',
+                };
+            }
+            try {
+                const result = deps.proposalManager.propose(deps.userId, {
+                    symbol: args.symbol,
+                    side: side,
+                    orderType: type,
+                    size: args.amount,
+                    proposedEntry: orderPrice,
+                    stopPrice: args.stopPrice,
+                    targetPrice: args.target_price,
+                    riskUsd: Math.abs(orderPrice - args.stopPrice) * args.amount,
+                    thesis: args.thesis,
+                    setupType: args.setup_type,
+                    regime: args.regime,
+                    regimeConfidence: args.regime_confidence,
+                    scorecardVerdict: args.scorecard_verdict,
+                    confluenceScore: args.confluence_score,
+                    ...(args.supersedes_id ? { supersedesId: args.supersedes_id } : {}),
+                    // Real, operator-actionable. Default would also resolve to 'real' but
+                    // we set it explicitly so the intent reads at the call site.
+                    origin: 'real',
+                });
+                return {
+                    status: 'pending_approval',
+                    proposal_id: result.proposalUuid,
+                    hard_expires_at: result.hardExpiresAt.toISOString(),
+                    setup_bucket: result.setupBucket,
+                    message: `Order awaits operator approval (${result.setupBucket} bucket, expires ` +
+                        `${result.hardExpiresAt.toISOString()}). Do not call create_order again ` +
+                        `for this setup; the listener will fire on approval. If the operator ` +
+                        `requests modifications in chat, call create_order with supersedes_id=` +
+                        `<id from the chat-context header>.`,
+                };
+            }
+            catch (err) {
+                return { error: `Proposal submission failed: ${formatError(err)}` };
+            }
+        }
+        // shadow mode: dual-write a telemetry proposal AND continue to the real
+        // fire below. Never blocks the hot path on a propose() failure.
+        if (approvalMode === 'shadow' && proposalPathWired && argsMetadataComplete) {
+            try {
+                deps.proposalManager.propose(deps.userId, {
+                    symbol: args.symbol,
+                    side: side,
+                    orderType: type,
+                    size: args.amount,
+                    proposedEntry: orderPrice,
+                    stopPrice: args.stopPrice,
+                    targetPrice: args.target_price,
+                    riskUsd: Math.abs(orderPrice - args.stopPrice) * args.amount,
+                    thesis: args.thesis,
+                    setupType: args.setup_type,
+                    regime: args.regime,
+                    regimeConfidence: args.regime_confidence,
+                    scorecardVerdict: args.scorecard_verdict,
+                    confluenceScore: args.confluence_score,
+                    ...(args.supersedes_id ? { supersedesId: args.supersedes_id } : {}),
+                    // Phase A telemetry — agent's create_order ALSO fires the real order
+                    // synchronously below. Hidden from operator UI by origin='shadow'.
+                    origin: 'shadow',
+                });
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[approval-shadow] propose() threw: ${formatError(err)}`);
+            }
+        }
+        try {
+            // Stash the metadata BEFORE submission, keyed by a pre-generated
+            // clientOrderId (fixed 2026-07-07; supersedes the 2026-07-05 post-return
+            // stash). For market orders the user-data WS fill routinely arrives
+            // BEFORE the REST ack resolves — observed on prod (FIL 2026-07-06
+            // 20:28:17: WS capture consumed nothing and journaled metadata=none while
+            // the post-return stash landed milliseconds later). The WS
+            // ORDER_TRADE_UPDATE carries the clientOrderId (`o.c`), so
+            // onWsFillObserved falls back to it when the exchange orderId lookup
+            // misses; promote() below adds the exchange-orderId alias once the REST
+            // ack returns for the normal (WS-after-REST) ordering. If the submission
+            // throws, the unused stash entry simply expires (24h TTL, pruned).
+            let stashCid = wave9Claimed && initialWave9Mode === 'LIVE'
+                ? wave9ClientOrderId(args.candidate_id)
+                : undefined;
+            if (deps.autoCapture?.pendingEntries && metadata) {
+                stashCid ??= mintEntryStashCid(deps.adapter);
+                deps.autoCapture.pendingEntries.put({
+                    orderId: stashCid,
+                    clientOrderId: stashCid,
+                    symbol: args.symbol,
+                    side: side,
+                    metadata,
+                });
+            }
+            if (wave9Lease) {
+                if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'trading_mode_changed_before_mutation', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    return { error: 'Wave 9 order refused: adapter or trading mode changed before mutation.' };
+                }
+                if (deps.wave9VenueCheck?.() !== 'binance') {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'execution_venue_changed_before_mutation', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    return { error: 'Wave 9 order refused: execution venue changed away from Binance before mutation.' };
+                }
+                let activation;
+                try {
+                    activation = deps.wave9ActivationCheck
+                        ? await deps.wave9ActivationCheck()
+                        : { available: false, active: false };
+                }
+                catch {
+                    activation = { available: false, active: false };
+                }
+                if (!activation.available || !activation.active) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'activation_unavailable_or_inactive_before_mutation', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    return { error: 'Wave 9 order refused: strategy was toggled off or activation could not be re-verified.' };
+                }
+                if (deps.adapter.readiness !== 'READY') {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'adapter_not_ready_before_mutation', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    return { error: `Wave 9 order refused: adapter changed to ${deps.adapter.readiness} before mutation.` };
+                }
+                if (initialWave9Mode === 'LIVE' && !bracketsEnabled(loadBracketMode())) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'native_brackets_disabled_before_mutation', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    return { error: 'Wave 9 live order refused: native bracket protection was disabled before mutation.' };
+                }
+            }
+            const submit = async () => {
+                if (!wave9Claimed && !deps.adapter.isLive) {
+                    deps.refreshPaperState?.();
+                    const positions = await deps.adapter.getPositionsOrNull();
+                    if (positions === null) {
+                        throw new Error('generic create_order final isolation check could not read paper positions');
+                    }
+                    if (positions.some(isWave9ManagedPosition)) {
+                        throw new Error('Generic create_order refused at mutation boundary: the paper account now contains an atomic Wave 9 position.');
+                    }
+                }
+                if (!wave9Claimed && deps.adapter.isLive && deps.checkWave9LiveSymbolOwnership) {
+                    let ownership;
+                    try {
+                        ownership = await deps.checkWave9LiveSymbolOwnership(args.symbol);
+                    }
+                    catch (err) {
+                        throw new Error(`Generic create_order refused at mutation boundary: Wave 9 LIVE ownership ` +
+                            `check failed for ${args.symbol} (${formatError(err)}).`);
+                    }
+                    if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+                        throw new Error(`Generic create_order refused at mutation boundary: ${args.symbol} has ` +
+                            `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}).`);
+                    }
+                }
+                return deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata, stashCid ? { clientOrderId: stashCid } : undefined);
+            };
+            const submitWave9 = async () => {
+                if (!wave9Lease)
+                    throw new Error('Wave 9 admission lease is unavailable at mutation boundary.');
+                if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'trading_mode_changed_during_activation_check', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    throw new Error('Wave 9 order refused: adapter or trading mode changed during activation verification.');
+                }
+                if (deps.wave9VenueCheck?.() !== 'binance') {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'execution_venue_changed_at_mutation_boundary', { retryable: true, latchEvent: false });
+                    wave9Lease = undefined;
+                    throw new Error('Wave 9 order refused: execution venue changed away from Binance at mutation boundary.');
+                }
+                let currentFingerprint;
+                if (initialWave9Mode === 'LIVE') {
+                    const ownership = deps.checkWave9LiveSymbolOwnership
+                        ? await deps.checkWave9LiveSymbolOwnership(args.symbol)
+                        : await inspectWave9LiveSymbolOwnership(deps.adapter, deps.wave9LiveLedger, args.symbol);
+                    if (ownership.status !== 'unowned'
+                        || ownership.reason === 'authoritative_symbol_flat') {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_symbol_ownership_changed_before_mutation:${ownership.status}:${ownership.reason}`, { retryable: true, latchEvent: false });
+                        wave9Lease = undefined;
+                        throw new Error(`Wave 9 live order refused: candidate-symbol ownership changed before mutation ` +
+                            `(${ownership.status}:${ownership.reason}); refresh get_wave9_status.`);
+                    }
+                    currentFingerprint = (await deps.captureWave9AccountFingerprint()).fingerprint;
+                }
+                else {
+                    deps.refreshPaperState?.();
+                    currentFingerprint = captureWave9PaperAccountSnapshot(deps.adapter).fingerprint;
+                }
+                deps.wave9AdmissionGuard.revalidate(wave9Lease, currentFingerprint);
+                if (initialWave9Mode === 'LIVE') {
+                    const preEntryFlat = await confirmWave9LivePositionFlat(deps.adapter, args.symbol);
+                    if (!preEntryFlat.confirmed) {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_candidate_symbol_not_stably_flat_before_entry:${preEntryFlat.detail}`, { retryable: true, latchEvent: false });
+                        wave9Lease = undefined;
+                        throw new Error(`Wave 9 live order refused: candidate symbol was not authoritatively stably flat ` +
+                            `immediately before entry (${preEntryFlat.detail}). No order was submitted; refresh ` +
+                            'get_wave9_status.');
+                    }
+                    const refuseAfterFlatProof = (reason, detail) => {
+                        if (wave9Lease) {
+                            deps.wave9AdmissionGuard.abort(wave9Lease, reason, { retryable: true, latchEvent: false });
+                        }
+                        wave9Lease = undefined;
+                        throw new Error(`${detail} No order was submitted; refresh get_wave9_status.`);
+                    };
+                    let postFlatActivation;
+                    try {
+                        postFlatActivation = deps.wave9ActivationCheck
+                            ? await deps.wave9ActivationCheck()
+                            : { available: false, active: false };
+                    }
+                    catch {
+                        postFlatActivation = { available: false, active: false };
+                    }
+                    if (!postFlatActivation.available || !postFlatActivation.active) {
+                        refuseAfterFlatProof('activation_unavailable_or_inactive_after_flat_proof', 'Wave 9 live order refused: the strategy was toggled off or activation could not be re-verified after the stable-flat proof.');
+                    }
+                    if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                        refuseAfterFlatProof('trading_mode_changed_after_flat_proof', 'Wave 9 live order refused: adapter or trading mode changed after the stable-flat proof.');
+                    }
+                    if (deps.wave9VenueCheck?.() !== 'binance') {
+                        refuseAfterFlatProof('execution_venue_changed_after_flat_proof', 'Wave 9 live order refused: execution venue changed away from Binance after the stable-flat proof.');
+                    }
+                    if (deps.adapter.readiness !== 'READY') {
+                        refuseAfterFlatProof('adapter_not_ready_after_flat_proof', `Wave 9 live order refused: adapter changed to ${deps.adapter.readiness} after the stable-flat proof.`);
+                    }
+                    if (!bracketsEnabled(loadBracketMode())) {
+                        refuseAfterFlatProof('native_brackets_disabled_after_flat_proof', 'Wave 9 live order refused: native bracket protection was disabled after the stable-flat proof.');
+                    }
+                    let postFlatFingerprint;
+                    try {
+                        postFlatFingerprint = (await deps.captureWave9AccountFingerprint()).fingerprint;
+                    }
+                    catch (error) {
+                        refuseAfterFlatProof(`live_account_fingerprint_unavailable_after_flat_proof:${formatError(error)}`, `Wave 9 live order refused: the LIVE account fingerprint could not be refreshed ` +
+                            `after the stable-flat proof (${formatError(error)}).`);
+                    }
+                    try {
+                        deps.wave9AdmissionGuard.revalidate(wave9Lease, postFlatFingerprint);
+                    }
+                    catch (error) {
+                        refuseAfterFlatProof(`authorization_revalidation_failed_after_flat_proof:${formatError(error)}`, `Wave 9 live order refused: authorization or LIVE account identity changed during ` +
+                            `the stable-flat proof (${formatError(error)}).`);
+                    }
+                    const [eventTime, , strategy, direction] = args.candidate_id.split('|');
+                    await deps.wave9LiveLedger.recordAttempt({
+                        candidateId: args.candidate_id,
+                        missionId: args.mission_id,
+                        eventTime,
+                        symbol: args.symbol,
+                        strategy: strategy,
+                        direction: direction,
+                        side: side,
+                        quantity: args.amount,
+                        initialStop: args.stopPrice,
+                        clientOrderId: stashCid,
+                    });
+                }
+                const finishLiveEntryRecovery = (recovery, source) => {
+                    if (recovery.status === 'protected') {
+                        deps.wave9AdmissionGuard.commit(wave9Lease);
+                        wave9Lease = undefined;
+                        if (recovery.order)
+                            return recovery.order;
+                        throw new Error(`Wave 9 LIVE ${source}, but the entry was recovered OPEN and protected. ` +
+                            `Do not retry this candidate. ${recovery.detail}`);
+                    }
+                    deps.wave9AdmissionGuard.abort(wave9Lease, recovery.status === 'terminal'
+                        ? 'live_entry_recovery_confirmed_terminal'
+                        : 'live_entry_recovery_manual_intervention');
+                    wave9Lease = undefined;
+                    throw new Error(recovery.status === 'terminal'
+                        ? `Wave 9 LIVE ${source} resolved safely and is terminal. ${recovery.detail}`
+                        : `CRITICAL: ${recovery.detail}`);
+                };
+                let order;
+                try {
+                    order = await submit();
+                }
+                catch (submitError) {
+                    if (initialWave9Mode !== 'LIVE')
+                        throw submitError;
+                    const recovery = await recoverWave9LiveSubmitThrow({
+                        adapter: deps.adapter,
+                        ledger: deps.wave9LiveLedger,
+                        candidateId: args.candidate_id,
+                        clientOrderId: stashCid,
+                        symbol: args.symbol,
+                        side: side,
+                        stopPrice: args.stopPrice,
+                        authorizedQuantity: args.amount,
+                        submitError,
+                        confirmStop: deps.confirmWave9LiveStop,
+                        residualProtector: deps.reprotectWave9LiveResidual,
+                    });
+                    return finishLiveEntryRecovery(recovery, 'submit acknowledgement failed');
+                }
+                const filledQuantity = typeof order.filled === 'number'
+                    && Number.isFinite(order.filled)
+                    && order.filled > 0
+                    ? order.filled
+                    : undefined;
+                if (filledQuantity === undefined) {
+                    if (initialWave9Mode === 'LIVE') {
+                        const recovery = await recoverWave9LiveSubmitThrow({
+                            adapter: deps.adapter,
+                            ledger: deps.wave9LiveLedger,
+                            candidateId: args.candidate_id,
+                            clientOrderId: stashCid,
+                            symbol: args.symbol,
+                            side: side,
+                            stopPrice: args.stopPrice,
+                            authorizedQuantity: args.amount,
+                            submitError: new Error('market acknowledgement lacked a positive confirmed fill quantity'),
+                            acknowledgedOrder: order,
+                            confirmStop: deps.confirmWave9LiveStop,
+                            residualProtector: deps.reprotectWave9LiveResidual,
+                        });
+                        return finishLiveEntryRecovery(recovery, 'market acknowledgement lacked a positive confirmed fill quantity');
+                    }
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'market_order_not_filled');
+                    wave9Lease = undefined;
+                    throw new Error('Wave 9 market order lacks a positive confirmed fill quantity; admission batch latched.');
+                }
+                if (initialWave9Mode === 'LIVE'
+                    && !candidateBoundFoundOrder({ status: 'found', order }, stashCid, args.symbol, side)) {
+                    const recovery = await recoverWave9LiveSubmitThrow({
+                        adapter: deps.adapter,
+                        ledger: deps.wave9LiveLedger,
+                        candidateId: args.candidate_id,
+                        clientOrderId: stashCid,
+                        symbol: args.symbol,
+                        side: side,
+                        stopPrice: args.stopPrice,
+                        authorizedQuantity: args.amount,
+                        submitError: new Error('market acknowledgement had malformed or mismatched candidate identity'),
+                        confirmStop: deps.confirmWave9LiveStop,
+                        residualProtector: deps.reprotectWave9LiveResidual,
+                    });
+                    return finishLiveEntryRecovery(recovery, 'market acknowledgement had malformed or mismatched candidate identity');
+                }
+                if (initialWave9Mode === 'LIVE' && order.status === 'open') {
+                    const recovery = await recoverWave9LiveSubmitThrow({
+                        adapter: deps.adapter,
+                        ledger: deps.wave9LiveLedger,
+                        candidateId: args.candidate_id,
+                        clientOrderId: stashCid,
+                        symbol: args.symbol,
+                        side: side,
+                        stopPrice: args.stopPrice,
+                        authorizedQuantity: args.amount,
+                        submitError: new Error('market acknowledgement left an open entry remainder'),
+                        acknowledgedOrder: order,
+                        confirmStop: deps.confirmWave9LiveStop,
+                        residualProtector: deps.reprotectWave9LiveResidual,
+                    });
+                    return finishLiveEntryRecovery(recovery, 'market acknowledgement left an open entry remainder');
+                }
+                if (initialWave9Mode === 'LIVE') {
+                    const entryPrice = confirmedWave9EntryPrice(order, side, args.stopPrice);
+                    const exchangeOrderId = confirmedWave9ExchangeOrderId(order);
+                    let openPersistenceError;
+                    try {
+                        await deps.wave9LiveLedger.markOpen(args.candidate_id, {
+                            filledQuantity,
+                            ...(exchangeOrderId ? { exchangeOrderId } : {}),
+                            ...(entryPrice !== undefined ? { entryPrice } : {}),
+                        });
+                    }
+                    catch (err) {
+                        openPersistenceError = formatError(err);
+                    }
+                    if (openPersistenceError) {
+                        const flatten = await flattenFailedWave9LiveEntry(deps.adapter, deps.wave9LiveLedger, args.symbol, args.candidate_id, {
+                            side: side,
+                            maximumQuantity: Math.min(filledQuantity, args.amount),
+                        }, deps.reprotectWave9LiveResidual);
+                        deps.wave9AdmissionGuard.abort(wave9Lease, flatten.confirmedFlat
+                            ? 'live_open_persistence_failed_confirmed_flat'
+                            : 'live_open_persistence_failed_residual_exposure');
+                        wave9Lease = undefined;
+                        const flattenError = flatten.flattenError
+                            ? ` Close submission error: ${flatten.flattenError}.`
+                            : '';
+                        if (flatten.confirmedFlat && !flatten.terminalPersistenceError) {
+                            throw new Error(`Wave 9 confirmed fill could not be durably marked OPEN (${openPersistenceError}); ` +
+                                `${flatten.closeAttempted
+                                    ? 'the position was auto-flattened and confirmed flat'
+                                    : 'the exchange position was already confirmed stably flat'}, and its replay tombstone was ` +
+                                `persisted terminal.${flattenError}`);
+                        }
+                        if (flatten.confirmedFlat) {
+                            throw new Error(`Wave 9 confirmed fill could not be durably marked OPEN (${openPersistenceError}). ` +
+                                `The exchange is confirmed flat, but durable CLOSED persistence also failed ` +
+                                `(${flatten.terminalPersistenceError}).${flattenError}`);
+                        }
+                        throw new Error(`CRITICAL: Wave 9 confirmed fill could not be durably marked OPEN ` +
+                            `(${openPersistenceError}), and ${flatten.closeAttempted
+                                ? 'emergency flatten is not confirmed flat'
+                                : 'the exposure identity fence refused symbol-wide flatten'} ` +
+                            `(${flatten.confirmationDetail}). In-memory OPEN ownership was retained where possible; ` +
+                            `the entry capability is consumed and latched.${flattenError}${residualProtectionMessage(flatten)}`);
+                    }
+                    let stopConfirmed = false;
+                    try {
+                        stopConfirmed = await deps.confirmWave9LiveStop({
+                            candidateId: args.candidate_id,
+                            symbol: args.symbol,
+                            entryClientOrderId: stashCid,
+                            entrySide: side,
+                            stopPrice: args.stopPrice,
+                            filledQuantity,
+                        });
+                    }
+                    catch {
+                        stopConfirmed = false;
+                    }
+                    if (!stopConfirmed) {
+                        const flatten = await flattenFailedWave9LiveEntry(deps.adapter, deps.wave9LiveLedger, args.symbol, args.candidate_id, {
+                            side: side,
+                            maximumQuantity: Math.min(filledQuantity, args.amount),
+                        }, deps.reprotectWave9LiveResidual);
+                        deps.wave9AdmissionGuard.abort(wave9Lease, flatten.confirmedFlat
+                            ? 'live_stop_unconfirmed_confirmed_flat'
+                            : 'live_stop_unconfirmed_residual_exposure');
+                        wave9Lease = undefined;
+                        const flattenError = flatten.flattenError
+                            ? ` Close submission error: ${flatten.flattenError}.`
+                            : '';
+                        if (flatten.confirmedFlat && !flatten.terminalPersistenceError) {
+                            throw new Error(`Wave 9 live stop was not confirmed; ${flatten.closeAttempted
+                                ? 'the filled position was auto-flattened and confirmed flat'
+                                : 'the exchange position was already confirmed stably flat'}, and its durable ` +
+                                `execution row is terminal.${flattenError}`);
+                        }
+                        if (flatten.confirmedFlat) {
+                            throw new Error(`Wave 9 live stop was not confirmed. The exchange is confirmed flat, but durable ` +
+                                `CLOSED persistence failed (${flatten.terminalPersistenceError}).${flattenError}`);
+                        }
+                        throw new Error(`CRITICAL: Wave 9 live stop was not confirmed and ${flatten.closeAttempted
+                            ? 'emergency flatten is not confirmed flat'
+                            : 'the exposure identity fence refused symbol-wide flatten'} ` +
+                            `(${flatten.confirmationDetail}). Durable ownership remains OPEN; the entry ` +
+                            `capability is consumed and latched.${flattenError}${residualProtectionMessage(flatten)}`);
+                    }
+                }
+                deps.wave9AdmissionGuard.commit(wave9Lease);
+                wave9Lease = undefined;
+                return order;
+            };
+            const order = wave9Claimed
+                ? await deps.operationLock.withAccountLock(`wave9-create-final:${args.symbol}`, submitWave9)
+                : deps.operationLock
+                    ? await deps.operationLock.withAccountLock(`generic-create-final:${args.symbol}`, submit)
+                    : await submit();
+            // Auto-capture entry to the Position Decision Journal — fail-open, never
+            // block the trading hot path on a webapp ingest blip.
+            if (deps.autoCapture) {
+                if (stashCid &&
+                    deps.autoCapture.pendingEntries &&
+                    typeof order.id === 'string' &&
+                    order.id.length > 0) {
+                    deps.autoCapture.pendingEntries.promote(stashCid, order.id);
+                }
+                const filledNow = typeof order.filled === 'number' && order.filled > 0;
+                if (filledNow) {
+                    // Order filled at submit (market, or limit-that-crossed). Capture
+                    // synchronously — same as the original PR1 path.
+                    onCreateOrderFilled(deps.autoCapture, { symbol: args.symbol, side: side, metadata }, order).catch((err) => {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[position-auto-capture] entry capture threw: ${formatError(err)}`);
+                    });
+                }
+            }
+            return order;
+        }
+        catch (err) {
+            if (wave9Lease) {
+                deps.wave9AdmissionGuard.abort(wave9Lease, `order_execution_failed:${formatError(err)}`);
+                wave9Lease = undefined;
+            }
+            return { error: formatError(err) };
+        }
+    }
+    catch (err) {
+        if (!wave9Claimed)
+            throw err;
+        if (wave9Lease) {
+            deps.wave9AdmissionGuard.abort(wave9Lease, `pre_mutation_processing_failed:${formatError(err)}`, { retryable: true, latchEvent: false });
+            wave9Lease = undefined;
+        }
+        return { error: formatError(err) };
+    }
+}