@reefclaw/connect 0.1.9 → 0.1.10

package/assets/plugin/simulator/exchange-simulator.js

@@ -205,6 +205,11 @@ export class ExchangeSimulator extends EventEmitter {
                 // Surface entry metadata (if available)
                 ...(p.metadata && {
                     setupType: p.metadata.setupType,
+                    missionId: p.metadata.missionId,
+                    candidateId: p.metadata.candidateId,
+                    strategy: p.metadata.strategy,
+                    accruedFundingUsd: p.metadata.accruedFundingUsd,
+                    fundingThroughTime: p.metadata.fundingThroughTime,
                     thesis: p.metadata.thesis,
                     stopPrice: p.metadata.stopPrice,
                     targetPrice: p.metadata.targetPrice,

package/assets/plugin/simulator/fill-engine.js

@@ -53,7 +53,11 @@ export function parseSymbol(symbol) {
     if (parts.length !== 2) {
         throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE`);
     }
-    return { base: parts[0], quote: parts[1] };
+    const [quote, settle, ...extra] = parts[1].split(':');
+    if (!quote || extra.length > 0 || (settle !== undefined && settle !== quote)) {
+        throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE or BASE/QUOTE:QUOTE`);
+    }
+    return { base: parts[0], quote };
 }
 /**
  * Ensure a currency exists in the wallet with at least zero balance.

package/assets/plugin/simulator/types.d.ts

@@ -83,7 +83,7 @@ export interface CurrencyBalance {
  *  - `exchange_stop` / `exchange_target`: exchange-native STOP_MARKET / TAKE_PROFIT_MARKET triggered on Binance
  *  - `cancelled_auto`: bracket reconciler cleaned up after detecting the position closed externally
  *  - `operator` / `agent` / `emergency`: explicit initiator */
-export type CloseReason = 'agent' | 'stop_watcher' | 'emergency' | 'operator' | 'bracket_attach_failed' | 'exchange_stop' | 'exchange_target' | 'cancelled_auto';
+export type CloseReason = 'agent' | 'stop_watcher' | 'emergency' | 'operator' | 'bracket_attach_failed' | 'exchange_stop' | 'exchange_target' | 'cancelled_auto' | 'wave9_signal_reversal' | 'liquidated' | 'adl' | 'venue_delisted';
 /** The agent's stated profit-realization plan, pinned at entry. PURE DATA /
  *  indication — the plugin does NOT enforce it; it is surfaced back so the agent
  *  can hold to its own plan instead of re-litigating. The agent fills the parts
@@ -107,6 +107,11 @@ export interface RealizationRule {
  *  moment of close. */
 export interface PositionMetadata {
     setupType?: string;
+    missionId?: string;
+    candidateId?: string;
+    strategy?: 'tsmom_28d_long_flat_reversal_1d' | 'tsmom_28d_short_flat_reversal_1d';
+    accruedFundingUsd?: number;
+    fundingThroughTime?: string;
     thesis?: string;
     stopPrice?: number;
     targetPrice?: number;

package/assets/plugin/strategy/evaluator.d.ts

@@ -27,6 +27,8 @@ export interface StrategyConfig {
         params: Record<string, number>;
     };
     targetRMultiples: number[];
+    /** Dedicated portfolio catalog rows are not declarative generic strategies. */
+    executionModel?: string;
 }
 export interface StrategyRow {
     id: number;
@@ -55,6 +57,7 @@ export interface StrategyEvalResult {
     regime_confidence: number;
     summary: string;
 }
+export declare function isDeclarativeStrategyConfig(strategy: StrategyConfig): boolean;
 /**
  * Evaluate a strategy against a symbol's fact object.
  * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.

package/assets/plugin/strategy/evaluator.js

@@ -4,12 +4,17 @@
 // and optionally checks threshold-based conditions against indicator values.
 import { CONDITION_EVALUATORS } from './condition-registry.js';
 import { getCachedTradingParams } from '../trading-params-cache.js';
+export function isDeclarativeStrategyConfig(strategy) {
+    return strategy.executionModel === undefined || strategy.executionModel === 'declarative';
+}
 // ─── Evaluator ──────────────────────────────────────────────────────────
 /**
  * Evaluate a strategy against a symbol's fact object.
  * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.
  */
 export function evaluateStrategy(strategy, fact) {
+    if (!isDeclarativeStrategyConfig(strategy))
+        return null;
     // Check regime gate
     if (strategy.regimeWhitelist.length > 0) {
         const matchesRegime = strategy.regimeWhitelist.some(r => r === fact.regime || r === 'ANY');

package/assets/plugin/tools/assessment-validation.d.ts

@@ -31,6 +31,8 @@ export interface ClosePositionArgs {
     symbol: string;
     reason?: string;
     assessment?: CloseAssessment;
+    candidate_id?: string;
+    wave9_exit_token?: string;
 }
 export interface ValidationResult {
     ok: boolean;

package/assets/plugin/tools/attach-brackets.d.ts

@@ -1,4 +1,6 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
 interface AttachBracketsArgs {
     symbol: string;
     stop_price?: number;
@@ -26,9 +28,12 @@ interface AttachBracketsSuccess {
     idempotent_no_op?: boolean;
     note?: string;
 }
-export declare function attachBracketsTool(args: AttachBracketsArgs, deps: {
+interface AttachBracketsDeps {
     adapter: IExchangeAdapter;
-}): Promise<AttachBracketsSuccess | {
+    operationLock?: TradingOperationLock;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+}
+export declare function attachBracketsTool(args: AttachBracketsArgs, deps: AttachBracketsDeps): Promise<AttachBracketsSuccess | {
     error: string;
 }>;
 export {};

package/assets/plugin/tools/attach-brackets.js

@@ -41,6 +41,42 @@ export async function attachBracketsTool(args, deps) {
     if (!deps.adapter.isLive) {
         return { error: 'attach_brackets is live-mode only (it places exchange-side STOP/TP orders). In paper mode, use modify_stop / modify_target to set or move the position\'s protective levels in place — the paper stop-watcher enforces metadata.stopPrice.' };
     }
+    if (deps.checkWave9LiveSymbolOwnership && !deps.operationLock) {
+        return {
+            error: 'Live attach_brackets refused: the shared trading operation lock is required ' +
+                'while Wave 9 LIVE ownership checks are enabled.',
+        };
+    }
+    const attachLive = () => attachBracketsLive(args, deps);
+    try {
+        return deps.operationLock
+            ? await deps.operationLock.withAccountLock(`generic-attach-brackets-final:${args.symbol}`, attachLive)
+            : await attachLive();
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}
+async function attachBracketsLive(args, deps) {
+    if (deps.checkWave9LiveSymbolOwnership) {
+        let ownership;
+        try {
+            ownership = await deps.checkWave9LiveSymbolOwnership(args.symbol);
+        }
+        catch (err) {
+            return {
+                error: `attach_brackets refused at mutation boundary: Wave 9 LIVE ownership check failed ` +
+                    `for ${args.symbol} (${formatError(err)}).`,
+            };
+        }
+        if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+            return {
+                error: `attach_brackets refused at mutation boundary: ${args.symbol} has ` +
+                    `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                    'Wave 9 protection is candidate-bound and cannot be replaced by the generic bracket tool.',
+            };
+        }
+    }
     const live = deps.adapter;
     const mgr = live.getBracketManager?.();
     const ledger = live.getBracketLedger?.();

package/assets/plugin/tools/cancel-all-orders.d.ts

@@ -1,7 +1,9 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 import type { CcxtOrder } from '../types.js';
 export declare function cancelAllOrdersTool(args: {
     symbol?: string;
 }, deps: {
     adapter: IExchangeAdapter;
+    operationLock?: TradingOperationLock;
 }): Promise<CcxtOrder[]>;

package/assets/plugin/tools/cancel-all-orders.js

@@ -1,5 +1,8 @@
 // Tool: cancel_all_orders — cancel all open orders (paper or live)
 // NO readiness gate — emergency control (kill switch), must always work.
 export async function cancelAllOrdersTool(args, deps) {
-    return deps.adapter.cancelAllOrders(args.symbol);
+    const cancel = () => deps.adapter.cancelAllOrders(args.symbol);
+    return deps.adapter.isLive && deps.operationLock
+        ? deps.operationLock.withAccountLock(`generic-cancel-all-orders-final:${args.symbol ?? 'all'}`, cancel)
+        : cancel();
 }

package/assets/plugin/tools/cancel-order.d.ts

@@ -1,10 +1,14 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 import type { CcxtOrder } from '../types.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
 export declare function cancelOrderTool(args: {
     id: string;
     symbol?: string;
 }, deps: {
     adapter: IExchangeAdapter;
+    operationLock?: TradingOperationLock;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
 }): Promise<CcxtOrder | {
     error: string;
 }>;

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

@@ -1,12 +1,58 @@
-// Tool: cancel_order — cancel a single order (paper or live)
-// NO readiness gate — emergency control, must always work.
+// Tool: cancel_order — cancel a single order (paper or live).
+// There is no readiness gate, but LIVE cancellation cannot individually strip
+// candidate-bound Wave 9 protection. The emergency escape is an explicit
+// operator close, which reduces exposure instead of leaving it naked.
 import { formatError } from '../logger.js';
 export async function cancelOrderTool(args, deps) {
     if (!args.id) {
         return { error: 'Order ID is required.' };
     }
+    if (!deps.adapter.isLive) {
+        try {
+            return await deps.adapter.cancelOrder(args.id, args.symbol);
+        }
+        catch (err) {
+            return { error: formatError(err) };
+        }
+    }
+    if (deps.checkWave9LiveSymbolOwnership && !deps.operationLock) {
+        return {
+            error: 'Live cancel_order refused: the shared trading operation lock is required ' +
+                'while Wave 9 LIVE ownership checks are enabled.',
+        };
+    }
+    const cancelLive = async () => {
+        let symbol = args.symbol?.trim();
+        if (!symbol) {
+            const matches = (await deps.adapter.getOpenOrders())
+                .filter((order) => order.id === args.id);
+            if (matches.length !== 1 || !matches[0].symbol) {
+                throw new Error(`cancel_order refused: order ${args.id} could not be resolved to exactly one ` +
+                    `trusted open-order symbol (matches=${matches.length}).`);
+            }
+            symbol = matches[0].symbol;
+        }
+        if (deps.checkWave9LiveSymbolOwnership) {
+            let ownership;
+            try {
+                ownership = await deps.checkWave9LiveSymbolOwnership(symbol);
+            }
+            catch (err) {
+                throw new Error(`cancel_order refused at mutation boundary: Wave 9 LIVE ownership check failed ` +
+                    `for ${symbol} (${formatError(err)}).`);
+            }
+            if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+                throw new Error(`cancel_order refused at mutation boundary: ${symbol} has ` +
+                    `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                    'Use operator_command to close the position instead of stripping candidate-bound protection.');
+            }
+        }
+        return deps.adapter.cancelOrder(args.id, symbol);
+    };
     try {
-        return await deps.adapter.cancelOrder(args.id, args.symbol);
+        return deps.operationLock
+            ? await deps.operationLock.withAccountLock(`generic-cancel-order-final:${args.id}`, cancelLive)
+            : await cancelLive();
     }
     catch (err) {
         return { error: formatError(err) };

package/assets/plugin/tools/close-position.d.ts

@@ -4,6 +4,11 @@ import type { CcxtOrder } from '../types.js';
 import { type ClosePositionArgs } from './assessment-validation.js';
 import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
 import { type ExitGateMode } from '../config/position-review-config.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveExecutionLedger } from '../wave9/live-execution-ledger.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
+import { type Wave9LiveResidualProtectionResult } from '../wave9/live-residual-protection.js';
+import { type Wave9PaperAdmissionGuard } from '../wave9/paper-admission-guard.js';
 export declare function closePositionTool(args: ClosePositionArgs, deps: {
     binanceApi: PublicMarketDataApi;
     adapter: IExchangeAdapter;
@@ -11,6 +16,24 @@ export declare function closePositionTool(args: ClosePositionArgs, deps: {
     /** Override for tests — production reads from plugin-config.json on each
      *  call so the flag can be flipped without a restart. */
     exitGateMode?: ExitGateMode;
+    wave9AdmissionGuard?: Wave9PaperAdmissionGuard;
+    refreshPaperState?: () => void;
+    wave9TradingModeCheck?: () => string;
+    wave9VenueCheck?: () => string;
+    captureWave9PositionFingerprint?: (symbol: string) => Promise<{
+        fingerprint: string;
+        position: {
+            candidateId?: string;
+            missionId?: string;
+            setupType?: string;
+            side: 'long' | 'short';
+        };
+    }>;
+    wave9LiveLedger?: Wave9LiveExecutionLedger;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+    reprotectWave9LiveResidual?: (adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, candidateId: string, symbol: string) => Promise<Wave9LiveResidualProtectionResult>;
+    operationLock?: TradingOperationLock;
+    operationLockHeld?: boolean;
 }): Promise<CcxtOrder | {
     error: string;
 }>;

package/assets/plugin/tools/close-position.js

@@ -26,7 +26,18 @@ import { onClosePositionFilled } from '../ingest/position-auto-capture.js';
 import { evaluateExitGate, } from './exit-gate.js';
 import { getRecentAuditVerdictHistory } from './audit-bracket-protection.js';
 import { loadExitGateMode } from '../config/position-review-config.js';
+import { confirmWave9LivePositionFlat } from '../wave9/live-position-confirmation.js';
+import { reprotectWave9LiveResidual, } from '../wave9/live-residual-protection.js';
+import { captureWave9PaperPositionFingerprint, isWave9ManagedPosition, WAVE9_MECHANICAL_EXIT_REASON, } from '../wave9/paper-admission-guard.js';
 const TAG = 'close-position';
+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;
+}
 // Bracket-integrity circuit-breaker. Counts SUCCESSFUL close_position calls
 // with reason='bracket_integrity' in a rolling 60-min window. When the 3rd
 // such close is attempted, reject — repeated bracket-integrity flushes in
@@ -40,10 +51,131 @@ const BRACKET_INTEGRITY_LIMIT = 3;
 let bracketIntegrityCloses = []; // timestamps of successful closes
 export async function closePositionTool(args, deps) {
     // Schema gate FIRST — reject before touching the exchange.
-    const v = validateClosePosition(args);
-    if (!v.ok) {
-        logger.warn(TAG, `close_position rejected: ${v.error} (symbol=${args.symbol}, reason=${args.reason ?? 'missing'})`);
-        return { error: v.error ?? 'Invalid close_position arguments.' };
+    const wave9ExitClaimed = args.reason !== 'operator_command' && (args.reason === WAVE9_MECHANICAL_EXIT_REASON
+        || args.wave9_exit_token !== undefined
+        || args.candidate_id !== undefined);
+    if (wave9ExitClaimed && deps.wave9VenueCheck?.() !== 'binance') {
+        return { error: 'Wave 9 reversal close refused: execution is pinned to Binance USD-M futures.' };
+    }
+    if (wave9ExitClaimed && !deps.operationLock) {
+        return { error: 'Wave 9 reversal close refused: process-local trading operation lock is unavailable.' };
+    }
+    const initialWave9Mode = wave9ExitClaimed ? currentWave9ExecutionMode(deps) : null;
+    let wave9Lease;
+    if (wave9ExitClaimed) {
+        if (!initialWave9Mode) {
+            return {
+                error: 'Wave 9 reversal close refused: capability execution requires an exact PAPER/paper-adapter ' +
+                    'or LIVE/live-adapter runtime match.',
+            };
+        }
+        if (args.reason !== WAVE9_MECHANICAL_EXIT_REASON
+            || !args.wave9_exit_token
+            || !args.candidate_id
+            || !deps.wave9AdmissionGuard) {
+            return { error: 'Wave 9 reversal close requires its exact reason, candidate identity, and short-lived exit token.' };
+        }
+        const executionCanonical = args.symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+        if (!executionCanonical.endsWith('USDT') || executionCanonical.length <= 4) {
+            return { error: `Wave 9 reversal close refused: unsupported execution symbol ${args.symbol}.` };
+        }
+        if (initialWave9Mode === 'LIVE' && (!deps.captureWave9PositionFingerprint || !deps.wave9LiveLedger)) {
+            return {
+                error: 'Wave 9 live reversal close refused: authoritative live position capture and the durable ' +
+                    'execution ledger are required.',
+            };
+        }
+        args = { ...args, symbol: `${executionCanonical.slice(0, -4)}/USDT:USDT` };
+        try {
+            wave9Lease = await deps.operationLock.withAccountLock(`wave9-begin-close:${args.candidate_id ?? args.symbol}`, async () => {
+                if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                    throw new Error('adapter or trading mode changed before Wave 9 reversal began');
+                }
+                let position;
+                let positionFingerprint;
+                if (initialWave9Mode === 'LIVE') {
+                    const capture = await deps.captureWave9PositionFingerprint(args.symbol);
+                    position = capture.position;
+                    positionFingerprint = capture.fingerprint;
+                }
+                else {
+                    deps.refreshPaperState?.();
+                    const positions = await deps.adapter.getPositionsOrNull();
+                    if (positions === null)
+                        throw new Error('paper position snapshot unavailable');
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    const matches = positions.filter((candidate) => canonical(candidate.symbol) === canonical(args.symbol));
+                    if (matches.length !== 1)
+                        throw new Error('exactly one matching held position is required');
+                    position = matches[0];
+                    positionFingerprint = captureWave9PaperPositionFingerprint(deps.adapter, args.symbol).fingerprint;
+                }
+                if (!isWave9ManagedPosition(position)
+                    || position.candidateId !== args.candidate_id
+                    || !position.missionId) {
+                    throw new Error('held position lacks exact Wave 9 identity/geometry');
+                }
+                return deps.wave9AdmissionGuard.beginExit({
+                    token: args.wave9_exit_token,
+                    candidateId: args.candidate_id,
+                    missionId: position.missionId,
+                    symbol: args.symbol,
+                    positionSide: position.side,
+                    setupType: position.setupType,
+                    reason: args.reason,
+                    positionFingerprint,
+                    tradingMode: initialWave9Mode,
+                });
+            });
+        }
+        catch (err) {
+            return { error: `Wave 9 reversal close refused: ${formatError(err)}` };
+        }
+    }
+    else {
+        // Preserve the generic tool contract: malformed calls are rejected before
+        // any adapter read. Wave 9 classification is an additional check only for
+        // already-valid, non-operator risk-reducing closes.
+        const v = validateClosePosition(args);
+        if (!v.ok) {
+            logger.warn(TAG, `close_position rejected: ${v.error} (symbol=${args.symbol}, reason=${args.reason ?? 'missing'})`);
+            return { error: v.error ?? 'Invalid close_position arguments.' };
+        }
+        if (args.reason !== 'operator_command'
+            && deps.adapter.isLive
+            && deps.checkWave9LiveSymbolOwnership
+            && !deps.operationLock) {
+            return {
+                error: 'Generic live close_position refused: the shared trading operation lock is required ' +
+                    'while Wave 9 LIVE ownership checks are enabled.',
+            };
+        }
+        // When a trusted position snapshot is available, do not route a held
+        // Wave 9 position through a generic thesis/risk/bracket reason. Snapshot
+        // failure stays fail-open because an ordinary risk-reducing close must not
+        // be trapped by extra strategy-lifecycle I/O. Operator remains unconditional.
+        if (args.reason !== 'operator_command') {
+            try {
+                const getTrusted = deps.adapter.getPositionsOrNull?.bind(deps.adapter);
+                const held = getTrusted ? await getTrusted() : undefined;
+                if (held) {
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    if (held.some((position) => canonical(position.symbol) === canonical(args.symbol)
+                        && isWave9ManagedPosition(position))) {
+                        return {
+                            error: `Wave 9 position close refused: call get_wave9_status and use reason=${WAVE9_MECHANICAL_EXIT_REASON} ` +
+                                'with its single-use exit token. Only an explicit operator_command bypasses the strategy exit policy.',
+                        };
+                    }
+                }
+                else if (held === null) {
+                    logger.warn(TAG, 'Wave 9 generic-close classification unavailable; proceeding with legacy risk-reducing close semantics.');
+                }
+            }
+            catch (err) {
+                logger.warn(TAG, `Wave 9 generic-close classification failed (${formatError(err)}); proceeding with legacy risk-reducing close semantics.`);
+            }
+        }
     }
     // Exit-gate check — see docs/EXIT_GATE_DESIGN.md. The gate is orthogonal to
     // the bracket_integrity safeguard below; both can fire on the same call.
@@ -63,7 +195,7 @@ export async function closePositionTool(args, deps) {
     // snapshot was never constructed). See docs/EXIT_DISCIPLINE_BUILD_PLAN.md
     // Step 0a + docs/EXIT_GATE_DESIGN.md §5.
     let gateInputs = null;
-    if (gateMode !== 'off') {
+    if (!wave9ExitClaimed && gateMode !== 'off') {
         gateInputs = await buildExitGateInputs(args, deps);
         gateVerdict = evaluateExitGate(gateInputs);
         logger.info(TAG, `exit_gate mode=${gateMode} ${gateVerdict.outcome} tier=${gateVerdict.tier} code=${gateVerdict.code} (symbol=${args.symbol}, reason=${args.reason})`);
@@ -80,13 +212,30 @@ export async function closePositionTool(args, deps) {
     }
     // In paper mode, fetch latest ticker + order book for realistic fills
     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;
+        try {
+            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)) {
+                // The helper updates the simulator mark used by the actual close fill.
+            }
+            else {
+                if (wave9Lease) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'exit_market_data_unavailable', { retryable: true });
+                    wave9Lease = undefined;
+                }
+                return priceResult;
+            }
+        }
+        catch (err) {
+            if (wave9Lease) {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'exit_market_data_threw', { retryable: true });
+                wave9Lease = undefined;
+            }
+            return { error: `close_position market-data refresh failed: ${formatError(err)}` };
+        }
     }
     // Log the assessment so every agent close is auditable in the journal.
     // We log after validation (we've confirmed the shape is sound) and before
@@ -133,7 +282,127 @@ export async function closePositionTool(args, deps) {
         logger.info(TAG, `bracket_integrity safeguard: ${integrity.detail} — allowing close`);
     }
     try {
-        const order = await deps.adapter.closePosition(args.symbol);
+        const close = async () => {
+            if (!wave9ExitClaimed && !deps.adapter.isLive && reason !== 'operator_command') {
+                deps.refreshPaperState?.();
+                const positions = await deps.adapter.getPositionsOrNull();
+                if (positions === null) {
+                    // Preserve the existing risk-reduction contract: the extra
+                    // classification read cannot trap an ordinary close.
+                    logger.warn(TAG, 'Wave 9 final close classification unavailable; proceeding risk-reducing fail-open.');
+                }
+                else {
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    const target = positions.find((position) => canonical(position.symbol) === canonical(args.symbol));
+                    if (target && isWave9ManagedPosition(target)) {
+                        throw new Error(`Generic close_position refused at mutation boundary: ${args.symbol} is now held by Wave 9.`);
+                    }
+                }
+            }
+            if (!wave9ExitClaimed
+                && deps.adapter.isLive
+                && reason !== 'operator_command'
+                && deps.checkWave9LiveSymbolOwnership) {
+                let ownership;
+                try {
+                    ownership = await deps.checkWave9LiveSymbolOwnership(args.symbol);
+                }
+                catch (err) {
+                    throw new Error(`Generic close_position 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 close_position refused at mutation boundary: ${args.symbol} has ` +
+                        `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                        'Use get_wave9_status for a reversal authorization or operator_command for an emergency close.');
+                }
+            }
+            return wave9ExitClaimed
+                ? deps.adapter.closePosition(args.symbol, 'wave9_signal_reversal')
+                : deps.adapter.closePosition(args.symbol);
+        };
+        const closeWave9 = async () => {
+            if (!wave9Lease)
+                throw new Error('Wave 9 exit lease is unavailable at mutation boundary.');
+            if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'trading_mode_changed_before_exit_mutation', { retryable: true });
+                wave9Lease = undefined;
+                throw new Error('Wave 9 reversal close refused: adapter or trading mode changed before mutation.');
+            }
+            if (deps.wave9VenueCheck?.() !== 'binance') {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'execution_venue_changed_before_exit_mutation', { retryable: true });
+                wave9Lease = undefined;
+                throw new Error('Wave 9 reversal close refused: execution venue changed away from Binance before mutation.');
+            }
+            let currentFingerprint;
+            if (initialWave9Mode === 'LIVE') {
+                const capture = await deps.captureWave9PositionFingerprint(args.symbol);
+                if (!isWave9ManagedPosition(capture.position)
+                    || capture.position.candidateId !== args.candidate_id
+                    || !capture.position.missionId) {
+                    throw new Error('held live position no longer matches its exact Wave 9 identity');
+                }
+                currentFingerprint = capture.fingerprint;
+            }
+            else {
+                deps.refreshPaperState?.();
+                currentFingerprint = captureWave9PaperPositionFingerprint(deps.adapter, args.symbol).fingerprint;
+            }
+            deps.wave9AdmissionGuard.revalidate(wave9Lease, currentFingerprint);
+            let order;
+            let closeError;
+            try {
+                order = await close();
+            }
+            catch (err) {
+                if (initialWave9Mode !== 'LIVE')
+                    throw err;
+                closeError = formatError(err);
+            }
+            if (initialWave9Mode === 'LIVE') {
+                const flat = await confirmWave9LivePositionFlat(deps.adapter, args.symbol);
+                if (!flat.confirmed) {
+                    let protection;
+                    try {
+                        protection = await (deps.reprotectWave9LiveResidual ?? reprotectWave9LiveResidual)(deps.adapter, deps.wave9LiveLedger, args.candidate_id, args.symbol);
+                    }
+                    catch (err) {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_reprotection_threw:${formatError(err)}`, { retryable: true });
+                        wave9Lease = undefined;
+                        throw new Error(`CRITICAL: Wave 9 LIVE reversal is not stably flat (${flat.detail}), and residual ` +
+                            `re-protection threw (${formatError(err)}). Durable ownership remains OPEN. ` +
+                            'IMMEDIATE MANUAL INTERVENTION REQUIRED; a fresh exit authorization may retry.');
+                    }
+                    if (protection.status === 'protected') {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_reprotected:${protection.stopClientOrderId ?? 'exact_stop'}`, { retryable: true });
+                        wave9Lease = undefined;
+                        throw new Error(`Wave 9 LIVE reversal close${closeError ? ` threw (${closeError}) and` : ''} left ` +
+                            `${protection.residualQuantity ?? 'a'} residual ` +
+                            `contract position. Durable ownership remains OPEN and the exact frozen stop ` +
+                            `${protection.stopPrice} is proven live; refresh get_wave9_status and use the ` +
+                            'fresh exit authorization to retry the reduce-only close.');
+                    }
+                    deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_requires_manual_intervention:${protection.detail}`, { retryable: true });
+                    wave9Lease = undefined;
+                    throw new Error(`CRITICAL: Wave 9 LIVE reversal close${closeError ? ` threw (${closeError}) and` : ''} ` +
+                        `stable flat was not confirmed ` +
+                        `(${flat.detail}). Durable ownership remains OPEN. ${protection.detail}`);
+                }
+                await deps.wave9LiveLedger.markClosed(args.candidate_id);
+            }
+            deps.wave9AdmissionGuard.commit(wave9Lease);
+            wave9Lease = undefined;
+            if (closeError) {
+                throw new Error(`Wave 9 LIVE reversal close acknowledgement failed (${closeError}), but stable flat was ` +
+                    'proven and durable ownership is CLOSED. Do not retry this candidate.');
+            }
+            return order;
+        };
+        const order = wave9ExitClaimed
+            ? await deps.operationLock.withAccountLock(`wave9-close-final:${args.symbol}`, closeWave9)
+            : reason !== 'operator_command' && deps.operationLock
+                ? await deps.operationLock.withAccountLock(`generic-close-final:${args.symbol}`, close)
+                : await close();
         // Successful close — record the bracket_integrity timestamp so the
         // circuit-breaker can see the trend on the next attempt.
         if (reason === 'bracket_integrity' && deps.adapter.isLive) {
@@ -228,6 +497,10 @@ export async function closePositionTool(args, deps) {
         return order;
     }
     catch (err) {
+        if (wave9Lease) {
+            deps.wave9AdmissionGuard.abort(wave9Lease, `exit_execution_failed:${formatError(err)}`, { retryable: initialWave9Mode === 'LIVE' });
+            wave9Lease = undefined;
+        }
         return { error: formatError(err) };
     }
 }