@reefclaw/openclaw-plugin 0.1.4 → 0.1.6

package/lifecycle/trading-operation-lock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Narrow process-local serialization boundary shared by guarded trading
+ * operations. Account and per-symbol operations intentionally use one queue:
+ * a Wave 9 portfolio transition must be atomic with respect to the legacy
+ * stop watcher, while callers gain no adapter/execution capability from the
+ * lock itself.
+ */
+export interface TradingOperationLock {
+    withAccountLock<T>(operation: string, run: () => Promise<T>): Promise<T>;
+    withSymbolLock<T>(symbol: string, operation: string, run: () => Promise<T>): Promise<T>;
+}
+export declare class SerialTradingOperationLock implements TradingOperationLock {
+    private tail;
+    private enqueue;
+    withAccountLock<T>(_operation: string, run: () => Promise<T>): Promise<T>;
+    withSymbolLock<T>(_symbol: string, _operation: string, run: () => Promise<T>): Promise<T>;
+}

package/lifecycle/trading-operation-lock.js

@@ -0,0 +1,14 @@
+export class SerialTradingOperationLock {
+    tail = Promise.resolve();
+    enqueue(run) {
+        const result = this.tail.then(run, run);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    withAccountLock(_operation, run) {
+        return this.enqueue(run);
+    }
+    withSymbolLock(_symbol, _operation, run) {
+        return this.enqueue(run);
+    }
+}

package/live/bracket-id.d.ts

@@ -1,5 +1,5 @@
-import type { VenueId } from '@reefclaw/shared';
 import type { BracketId, BracketRole } from './bracket-types.js';
+import type { VenueId } from '../venues/symbols.js';
 /** Generate a fresh 16-char hex bracketId. */
 export declare function generateBracketId(): BracketId;
 /** Build a clientOrderId for a given bracket + role. Emits the CURRENT
@@ -17,8 +17,7 @@ export declare function parseBracketCid(cid: string): {
 /** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
  *  — true for both the current and legacy schemes. */
 export declare function isBracketCid(cid: string): boolean;
-/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
- *  parser; other venues return null until their scheme ships. */
+/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
 export declare function parseBracketClientId(venue: VenueId, cid: string): {
     bracketId: BracketId;
     role: BracketRole;

package/live/bracket-id.js

@@ -35,6 +35,7 @@
 // alphanumeric) is well within it. Verified vs developers.binance.com
 // USDⓂ New-Order clientOrderId filter, 2026-05-16.
 import { randomBytes } from 'node:crypto';
+import { parseHlBracketCloid, isHlBracketCloid } from '../venues/hyperliquid/hl-cloid.js';
 // Emitted scheme (no `rc-`, no dashes).
 const CID_REGEX = /^bkt([0-9a-f]{16})([est])$/;
 // Legacy scheme — still parsed for backward compat, never emitted again.
@@ -83,17 +84,29 @@ export function isBracketCid(cid) {
 //
 // ALL bracket client-order-id recognition stays centralized in THIS module —
 // the brackets.md rule ("never hardcode an rc-/bkt regex elsewhere") extends
-// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid client order
-// ids are 128-bit hex cloids with a different scheme (hl-cloid.ts, Phase 3 of
-// docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.7) and will be dispatched from
-// here; until then the hyperliquid arm recognises nothing, which is correct —
-// this build never emits an HL bracket order.
-/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
- *  parser; other venues return null until their scheme ships. */
+// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid = 128-bit hex
+// cloids (`0xbc7…`, hl-cloid.ts §5.7 — a Binance-style ASCII cid is not even a
+// legal HL client id). Phase 3 wires that dispatch HERE, and nowhere else.
+//
+// ★ NEITHER VENUE MAY EVER RECOGNISE THE OTHER'S SCHEME. A false positive is
+//   destructive: `cancelAllOrders` preserves anything that parses as "ours", and
+//   the reconciler cancels/re-attaches on that basis. A foreign id that parsed as
+//   ours would be treated as a protective leg we own.
+/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
 export function parseBracketClientId(venue, cid) {
-    return venue === 'binance' ? parseBracketCid(cid) : null;
+    switch (venue) {
+        case 'binance':
+            return parseBracketCid(cid);
+        case 'hyperliquid':
+            return parseHlBracketCloid(cid);
+    }
 }
 /** Venue-aware isBracketCid. */
 export function isBracketClientId(venue, cid) {
-    return venue === 'binance' ? isBracketCid(cid) : false;
+    switch (venue) {
+        case 'binance':
+            return isBracketCid(cid);
+        case 'hyperliquid':
+            return isHlBracketCloid(cid);
+    }
 }

package/live/live-adapter.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
-import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from '../exchange-adapter.js';
+import type { IExchangeAdapter, AdapterReadiness, ClientOrderResolution, OrderOptions } from '../exchange-adapter.js';
 import { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { BinanceAlgoOrderProof } from '../ccxt/binance-private.js';
 import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode, ExchangeConfig } from '../types.js';
 import type { PositionMetadata, CloseReason } from '../simulator/types.js';
 import { ExchangeInfoCache } from './exchange-info-cache.js';
@@ -27,6 +28,16 @@ export interface TradeIngestWiring {
     userId: string;
     exchange?: string;
 }
+export interface Wave9ProtectionLossEvent {
+    source: 'algo_canceled' | 'algo_rejected' | 'reconciler_missing';
+    symbol: string;
+    bracketId: string;
+    entryClientOrderId: string;
+    entrySide: 'buy' | 'sell';
+    stopClientOrderId?: string;
+    detail: string;
+}
+export type Wave9ProtectionLossHandler = (event: Wave9ProtectionLossEvent) => Promise<void> | void;
 /**
  * Backfill `balance.free[cur] = total[cur]` for currencies where Binance's CCXT
  * response left the per-currency `free` and `used` at zero despite a non-zero
@@ -55,6 +66,10 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     private bracketLedger;
     private bracketManager;
     private bracketReconciler;
+    private wave9ProtectionLossHandler?;
+    private readonly wave9ProtectionLossInFlight;
+    private readonly pendingWave9ProtectionLossBySymbol;
+    private static readonly PENDING_WAVE9_PROTECTION_LOSS_CAP;
     private readonly userDataStreamMode;
     private userDataStream;
     private readonly wsAlgoStatusByCid;
@@ -128,6 +143,11 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
      * the subsequent flatten.
      */
     private attachBracketsAsync;
+    /** Install the Wave 9-only autonomous recovery bridge. With no handler,
+     *  every generic bracket lifecycle remains byte-for-byte behaviorally
+     *  unchanged. Runtime reapplies this setter after adapter reconnects. */
+    setWave9ProtectionLossHandler(handler?: Wave9ProtectionLossHandler): void;
+    private notifyWave9ProtectionLoss;
     /**
      * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
      *
@@ -194,6 +214,8 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
      *               fired (TRIGGERED/FINISHED) — only this licenses repair.
      *  'unknown'  = could not get an answer — safe-wait. */
     resolveBracketLegLiveness(cid: string): Promise<'live' | 'terminal' | 'unknown'>;
+    /** Immediate full-shape proof for one exact native conditional order. */
+    resolveBracketLegProof(cid: string): Promise<BinanceAlgoOrderProof | null>;
     /** Symbol-scoped generalization of the trusted-WS fast-path — the
      *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
      *
@@ -256,6 +278,7 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     private decoratePositionsWithMetadata;
     getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    resolveOrderByClientId(clientOrderId: string, symbol: string): Promise<ClientOrderResolution>;
     getLastPrice(symbol: string): Promise<number | null>;
     /** Sync rate limiter from exchange response headers after every private API call. */
     private syncRateLimits;

package/live/live-adapter.js

@@ -122,6 +122,10 @@ export class LiveAdapter extends EventEmitter {
     bracketLedger = null;
     bracketManager = null;
     bracketReconciler = null;
+    wave9ProtectionLossHandler;
+    wave9ProtectionLossInFlight = new Set();
+    pendingWave9ProtectionLossBySymbol = new Map();
+    static PENDING_WAVE9_PROTECTION_LOSS_CAP = 100;
     // User-data WebSocket stream — null when mode='off' (REST polling owns reads).
     // In Phase 1 this is dead code on prod (mode='off' is the default); the wiring
     // is in place so Phase 2 onwards only requires a flag flip. Read paths
@@ -216,7 +220,26 @@ export class LiveAdapter extends EventEmitter {
             this.bracketManager = new BracketManager(liveBracketApi, this.bracketLedger);
             this.bracketManager.on('event', (ev) => this.emit('bracket_event', ev));
             this.bracketReconciler = new BracketReconciler(this, this.bracketLedger, this.bracketManager, liveBracketApi);
-            this.bracketReconciler.on('drift', (d) => this.emit('bracket_drift', d));
+            this.bracketReconciler.on('drift', (d) => {
+                this.emit('bracket_drift', d);
+                if (d.kind !== 'position_unprotected'
+                    || !d.symbol
+                    || !d.bracketId
+                    || !d.details?.split(/[+:\s]+/).includes('stop'))
+                    return;
+                const row = this.bracketLedger?.getBySymbol(d.symbol);
+                if (!row || row.bracketId !== d.bracketId)
+                    return;
+                this.notifyWave9ProtectionLoss({
+                    source: 'reconciler_missing',
+                    symbol: normalizeBracketSymbol(d.symbol),
+                    bracketId: d.bracketId,
+                    entryClientOrderId: row.entryCid,
+                    entrySide: row.entrySide,
+                    ...(row.slCid ? { stopClientOrderId: row.slCid } : {}),
+                    detail: d.details,
+                });
+            });
             logger.info(TAG, `Bracket orders ENABLED in mode=${this.bracketMode}`);
         }
         // Forward poller events
@@ -814,7 +837,7 @@ export class LiveAdapter extends EventEmitter {
                     }
                 }
                 const bracketId = generateBracketId();
-                this.bracketManager.registerEntry({ symbol, side, stopPrice: metadata.stopPrice, targetPrice: metadata.targetPrice }, bracketId, buildBracketCid(bracketId, 'entry'));
+                this.bracketManager.registerEntry({ symbol, side, stopPrice: metadata.stopPrice, targetPrice: metadata.targetPrice }, bracketId, clientOrderId);
                 if (order.status === 'closed' && order.filled > 0) {
                     // Market order (or limit-that-filled-instantly) — attach now.
                     // We do NOT await: attach can take seconds and we don't want to block
@@ -857,6 +880,56 @@ export class LiveAdapter extends EventEmitter {
             logger.error(TAG, `attachBracketsAsync unexpected error for ${symbol}: ${formatError(err)}`);
         }
     }
+    /** Install the Wave 9-only autonomous recovery bridge. With no handler,
+     *  every generic bracket lifecycle remains byte-for-byte behaviorally
+     *  unchanged. Runtime reapplies this setter after adapter reconnects. */
+    setWave9ProtectionLossHandler(handler) {
+        this.wave9ProtectionLossHandler = handler;
+        if (!handler || this.pendingWave9ProtectionLossBySymbol.size === 0)
+            return;
+        const pending = [...this.pendingWave9ProtectionLossBySymbol.values()];
+        this.pendingWave9ProtectionLossBySymbol.clear();
+        for (const event of pending)
+            this.notifyWave9ProtectionLoss(event);
+    }
+    notifyWave9ProtectionLoss(event) {
+        const handler = this.wave9ProtectionLossHandler;
+        const key = normalizeBracketSymbol(event.symbol);
+        if (!handler || this.wave9ProtectionLossInFlight.has(key)) {
+            // initialize() may start the reconciler/user-data stream before the
+            // durable Wave 9 ledger is loaded by index.ts. Coalesce one latest loss
+            // per symbol and replay it when runtime installs the handler; never let
+            // that startup window silently discard a native-stop failure. The same
+            // queue catches a second loss while recovery is in flight — notably a
+            // freshly re-armed stop cancelled just before the first handler returns.
+            this.pendingWave9ProtectionLossBySymbol.set(key, event);
+            if (this.pendingWave9ProtectionLossBySymbol.size
+                > LiveAdapter.PENDING_WAVE9_PROTECTION_LOSS_CAP) {
+                const oldest = this.pendingWave9ProtectionLossBySymbol.keys().next().value;
+                if (oldest !== undefined) {
+                    this.pendingWave9ProtectionLossBySymbol.delete(oldest);
+                    logger.error(TAG, `Wave 9 protection-loss queue exceeded ${LiveAdapter.PENDING_WAVE9_PROTECTION_LOSS_CAP} ` +
+                        `symbols and evicted ${oldest}; IMMEDIATE MANUAL INTERVENTION REQUIRED`);
+                }
+            }
+            return;
+        }
+        this.wave9ProtectionLossInFlight.add(key);
+        void Promise.resolve()
+            .then(() => handler(event))
+            .catch((error) => {
+            logger.error(TAG, `Wave 9 protection-loss recovery failed for ${event.symbol}: ${formatError(error)}; ` +
+                'IMMEDIATE MANUAL INTERVENTION REQUIRED');
+        })
+            .finally(() => {
+            this.wave9ProtectionLossInFlight.delete(key);
+            const pending = this.pendingWave9ProtectionLossBySymbol.get(key);
+            if (pending) {
+                this.pendingWave9ProtectionLossBySymbol.delete(key);
+                this.notifyWave9ProtectionLoss(pending);
+            }
+        });
+    }
     /**
      * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
      *
@@ -896,6 +969,11 @@ export class LiveAdapter extends EventEmitter {
         const symbol = normalizeBracketSymbol(ev.symbol);
         const row = this.bracketLedger?.getBySymbol(symbol);
         const status = ev.status.toUpperCase();
+        const rowIsRecoverable = !!row
+            && (row.state === 'active' || row.state === 'partial' || row.state === 'attaching');
+        const isCurrentStop = parsed.role === 'stop'
+            && row?.bracketId === parsed.bracketId
+            && (!row.slCid || row.slCid === cid);
         // Record the authoritative per-leg WS status for the Tier-1 fast-path of
         // resolveBracketLegLiveness(). Every parsed rc-* lifecycle event, every
         // branch — including CANCELED, which the ledger deliberately does NOT
@@ -989,12 +1067,34 @@ export class LiveAdapter extends EventEmitter {
             else {
                 logger.info(TAG, `ALGO_UPDATE CANCELED on ${symbol} (${cid}) — ledger=${row?.state ?? 'none'} (benign: cancel of an already-terminal/absent bracket).`);
             }
+            if (rowIsRecoverable && isCurrentStop && row) {
+                this.notifyWave9ProtectionLoss({
+                    source: 'algo_canceled',
+                    symbol,
+                    bracketId: row.bracketId,
+                    entryClientOrderId: row.entryCid,
+                    entrySide: row.entrySide,
+                    stopClientOrderId: cid,
+                    detail: `exact native stop reported CANCELED (reason=${ev.reason ?? 'none'})`,
+                });
+            }
             return;
         }
         // NEW / TRIGGERING / REJECTED — informational. REJECTED is worth a WARN
         // (Binance refused the conditional order — e.g. margin check).
         if (status === 'REJECTED') {
             logger.warn(TAG, `ALGO_UPDATE REJECTED on ${symbol} (${cid}) reason=${ev.reason ?? 'none'} — bracket leg refused by Binance; position may be unprotected.`);
+            if (rowIsRecoverable && isCurrentStop && row) {
+                this.notifyWave9ProtectionLoss({
+                    source: 'algo_rejected',
+                    symbol,
+                    bracketId: row.bracketId,
+                    entryClientOrderId: row.entryCid,
+                    entrySide: row.entrySide,
+                    stopClientOrderId: cid,
+                    detail: `exact native stop reported REJECTED (reason=${ev.reason ?? 'none'})`,
+                });
+            }
         }
     }
     /** Expose the bracket manager for agent-facing tools (modify_stop, etc.).
@@ -1062,6 +1162,12 @@ export class LiveAdapter extends EventEmitter {
         // Tier 3 — no answer anywhere.
         return 'unknown';
     }
+    /** Immediate full-shape proof for one exact native conditional order. */
+    async resolveBracketLegProof(cid) {
+        if (!cid)
+            return null;
+        return this.api.queryAlgoOrderProof(cid);
+    }
     /** Symbol-scoped generalization of the trusted-WS fast-path — the
      *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
      *
@@ -1534,6 +1640,9 @@ export class LiveAdapter extends EventEmitter {
             out.push({
                 ...p,
                 setupType: p.setupType ?? freshMeta.setupType,
+                missionId: p.missionId ?? freshMeta.missionId,
+                candidateId: p.candidateId ?? freshMeta.candidateId,
+                strategy: p.strategy ?? freshMeta.strategy,
                 thesis: p.thesis ?? freshMeta.thesis,
                 stopPrice: p.stopPrice ?? freshMeta.stopPrice,
                 targetPrice: p.targetPrice ?? freshMeta.targetPrice,
@@ -1618,6 +1727,9 @@ export class LiveAdapter extends EventEmitter {
     async fetchOrder(orderId, symbol) {
         return this.api.fetchOrder(orderId, symbol);
     }
+    async resolveOrderByClientId(clientOrderId, symbol) {
+        return this.api.resolveOrderByClientId(clientOrderId, symbol);
+    }
     async getLastPrice(symbol) {
         const ticker = await this.api.fetchTicker(symbol);
         return ticker?.last ?? null;

package/live/local-signal-service.js

@@ -16,6 +16,9 @@ import { FactSubscriber } from './fact-subscriber.js';
 import { LocalStrategyEvaluator, DEFAULT_EVALUATOR_PARAMS } from './local-strategy-evaluator.js';
 const RECENT_RING = 50;
 const DEFAULT_FACT_STALENESS_MS = 60_000;
+function isDeclarativeConfig(config) {
+    return config.executionModel === undefined || config.executionModel === 'declarative';
+}
 export class LocalSignalService {
     opts;
     subscriber;
@@ -124,12 +127,14 @@ export class LocalSignalService {
             if (!resp.ok)
                 return;
             const body = (await resp.json());
-            const configs = (body.strategies ?? [])
+            if (!Array.isArray(body.strategies))
+                return;
+            const configs = body.strategies
                 .map((r) => r.config)
-                .filter((c) => !!c);
-            // Keep last-known strategies if the fetch returned an empty/garbage set.
-            if (configs.length > 0)
-                this.strategies = configs;
+                .filter((c) => !!c && isDeclarativeConfig(c));
+            // A valid empty list means all generic strategies are off (or only a
+            // dedicated portfolio bundle is active), so clear stale generic rows.
+            this.strategies = configs;
         }
         catch {
             /* keep last-known strategies — fail-open */
@@ -137,7 +142,7 @@ export class LocalSignalService {
     }
     /** Test seam — set strategies without an HTTP fetch. */
     __setStrategiesForTest(s) {
-        this.strategies = s;
+        this.strategies = s.filter((config) => isDeclarativeConfig(config));
     }
     /** Test seam — feed a raw SSE chunk to the subscriber. */
     __ingestForTest(chunk) {

package/live/local-strategy-evaluator.js

@@ -42,6 +42,10 @@ export class LocalStrategyEvaluator {
         const states = [];
         const signals = [];
         for (const config of strategies) {
+            const executionModel = config.executionModel;
+            if (executionModel !== undefined && executionModel !== 'declarative') {
+                continue;
+            }
             const def = adaptStrategy(config);
             // Regime gate (engine.ts): effective floor is the LOWER of the strategy's
             // own minConfidence and the user's regimeConfidenceFloor.

package/live/proposal-decision-listener.d.ts

@@ -1,6 +1,8 @@
 import type { BinancePublicApi } from '../ccxt/binance-public.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
 export interface ProposalDecisionListenerOptions {
     baseUrl: string;
     ingestToken: string;
@@ -8,6 +10,10 @@ export interface ProposalDecisionListenerOptions {
     adapter: IExchangeAdapter;
     binanceApi: BinancePublicApi;
     autoCapture?: AutoCaptureContext;
+    /** Shared mutation serialization and durable Wave 9 ownership check for
+     *  listener-side approved-order execution. */
+    operationLock?: TradingOperationLock;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
     /** Active poll interval — used while there are pending proposals (or the
      *  previous tick fetched any). Default 3 s. Keeps approval-to-fire latency
      *  low when the operator is actively working through proposals. */

package/live/proposal-decision-listener.js

@@ -56,6 +56,8 @@ export class ProposalDecisionListener {
             adapter: options.adapter,
             binanceApi: options.binanceApi,
             autoCapture: options.autoCapture,
+            operationLock: options.operationLock,
+            checkWave9LiveSymbolOwnership: options.checkWave9LiveSymbolOwnership,
             pollIntervalMs: options.pollIntervalMs ?? 3_000,
             pollIntervalIdleMs: options.pollIntervalIdleMs ?? 15_000,
             driftAbandonR: options.driftAbandonR ?? 0.3,
@@ -221,6 +223,8 @@ export class ProposalDecisionListener {
             binanceApi: this.opts.binanceApi,
             adapter: this.opts.adapter,
             autoCapture: this.opts.autoCapture,
+            operationLock: this.opts.operationLock,
+            checkWave9LiveSymbolOwnership: this.opts.checkWave9LiveSymbolOwnership,
             // proposalManager + userId deliberately omitted — see above.
         });
         if ('error' in result) {

package/live/stop-watcher.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { CcxtPosition } from '../types.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export declare const DEFAULT_INTERVAL_MS = 10000;
 export interface StopTriggeredEvent {
     symbol: string;
@@ -9,6 +10,26 @@ export interface StopTriggeredEvent {
     markPrice: number;
     quantity: number;
 }
+export type Wave9StopCloseOutcome = {
+    status: 'flat';
+    detail: string;
+    candidateId: string;
+    symbol: string;
+} | {
+    status: 'protected' | 'manual_intervention';
+    detail: string;
+    candidateId: string;
+    symbol: string;
+    stopPrice: number;
+    residualQuantity?: number;
+    stopClientOrderId?: string;
+};
+/** Optional durable Wave 9 lifecycle. Generic watcher behavior is unchanged
+ *  when this is absent or the current position has no owned candidate. */
+export interface Wave9StopCloseLifecycle {
+    resolveCandidateId(position: CcxtPosition): Promise<string | undefined> | string | undefined;
+    settleAfterClose(candidateId: string, symbol: string): Promise<Wave9StopCloseOutcome>;
+}
 /** Decide whether a position has crossed its stop.
  *  Exported for direct unit-testing without spinning up a watcher loop. */
 export declare function isStopBreached(position: CcxtPosition): boolean;
@@ -16,6 +37,8 @@ export declare class PositionWatcher extends EventEmitter {
     private interval;
     private intervalMs;
     private adapter;
+    private readonly operationLock?;
+    private wave9CloseLifecycle?;
     /** Symbols currently awaiting a close RPC — second trigger in the same tick
      *  is suppressed so the watcher cannot double-close. Cleared after the close
      *  call resolves (success or failure). */
@@ -23,7 +46,10 @@ export declare class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     private notifiedBreach;
-    constructor(adapter: IExchangeAdapter, intervalMs?: number);
+    constructor(adapter: IExchangeAdapter, intervalMs?: number, operationLock?: TradingOperationLock);
+    /** Configure this after the durable execution ledger is ready. Runtime
+     *  lifecycle hooks reapply it to every watcher after reconnect. */
+    setWave9CloseLifecycle(lifecycle?: Wave9StopCloseLifecycle): void;
     start(): void;
     stop(): void;
     /** Run one check cycle. Exposed for tests (skip setInterval). */

package/live/stop-watcher.js

@@ -45,6 +45,8 @@ export class PositionWatcher extends EventEmitter {
     interval = null;
     intervalMs;
     adapter;
+    operationLock;
+    wave9CloseLifecycle;
     /** Symbols currently awaiting a close RPC — second trigger in the same tick
      *  is suppressed so the watcher cannot double-close. Cleared after the close
      *  call resolves (success or failure). */
@@ -52,10 +54,16 @@ export class PositionWatcher extends EventEmitter {
     /** Symbols we've already logged a breach for this session, to avoid spamming
      *  the log every tick while the close is in flight. */
     notifiedBreach = new Set();
-    constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS) {
+    constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS, operationLock) {
         super();
         this.adapter = adapter;
         this.intervalMs = intervalMs;
+        this.operationLock = operationLock;
+    }
+    /** Configure this after the durable execution ledger is ready. Runtime
+     *  lifecycle hooks reapply it to every watcher after reconnect. */
+    setWave9CloseLifecycle(lifecycle) {
+        this.wave9CloseLifecycle = lifecycle;
     }
     start() {
         if (this.interval) {
@@ -130,8 +138,57 @@ export class PositionWatcher extends EventEmitter {
             quantity: position.contracts,
         };
         this.emit('stop_triggered', event);
+        const close = async () => {
+            let trustedPosition = position;
+            // Re-read after acquiring the shared trading boundary. A Wave 9
+            // reversal or another stop may have flattened the symbol while this
+            // watcher was queued.
+            if (this.operationLock) {
+                const current = await this.adapter.getPositionsOrNull(position.symbol);
+                if (current === null) {
+                    throw new Error('position recheck unavailable while holding trading operation lock');
+                }
+                const latest = current.find((candidate) => candidate.symbol === position.symbol);
+                if (!latest || !isStopBreached(latest)) {
+                    logger.info(TAG, `${position.symbol} no longer stop-triggered after locked recheck — skipping`);
+                    return 'skipped';
+                }
+                trustedPosition = latest;
+            }
+            let candidateId;
+            let ownershipError;
+            if (this.wave9CloseLifecycle) {
+                try {
+                    candidateId = await this.wave9CloseLifecycle.resolveCandidateId(trustedPosition);
+                }
+                catch (error) {
+                    ownershipError = formatError(error);
+                }
+            }
+            if (ownershipError) {
+                throw new Error(`Wave 9 ownership resolution failed before stop close submission: ${ownershipError}; ` +
+                    'IMMEDIATE MANUAL INTERVENTION REQUIRED');
+            }
+            await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher');
+            if (!candidateId || !this.wave9CloseLifecycle)
+                return 'closed';
+            const outcome = await this.wave9CloseLifecycle.settleAfterClose(candidateId, trustedPosition.symbol);
+            if (outcome.status === 'flat')
+                return 'closed';
+            if (outcome.status === 'protected') {
+                logger.warn(TAG, `Stop close left a Wave 9 residual on ${trustedPosition.symbol}; ` +
+                    `${outcome.detail}. The exact frozen stop is proven and the watcher will retry.`);
+                this.emit('stop_residual_protected', { ...event, ...outcome });
+                return 'residual_protected';
+            }
+            throw new Error(outcome.detail);
+        };
         try {
-            await this.adapter.closePosition(position.symbol, 'stop_watcher');
+            const result = this.operationLock
+                ? await this.operationLock.withSymbolLock(position.symbol, `stop_watcher:${position.symbol}`, close)
+                : await close();
+            if (result !== 'closed')
+                return;
             logger.info(TAG, `Auto-closed ${position.symbol} (reason=stop_watcher)`);
             this.emit('stop_closed', event);
         }

package/onboarding/runtime.d.ts

@@ -2,7 +2,9 @@ import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { ExchangeConfig, TradingMode } from '../types.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { PaperMarketFeed } from '../simulator/paper-market-feed.js';
+import { LiveAdapter } from '../live/live-adapter.js';
 import { PositionWatcher } from '../live/stop-watcher.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
 export interface MicroLiveConfig {
     sizeCapPercent?: number;
     maxPositionUSDT?: number;
@@ -13,6 +15,13 @@ export interface BuildAdapterInput {
     microLive?: MicroLiveConfig;
     simulator: ExchangeSimulator;
 }
+/** Wave 9 safety wiring is created only after its durable ledger is loaded.
+ *  Runtime reapplies these hooks to both the bootstrap objects and every
+ *  adapter/watcher built by a reconnect. */
+export interface Wave9LiveLifecycleHooks {
+    configureLiveAdapter?(adapter: LiveAdapter): void;
+    configurePositionWatcher?(watcher: PositionWatcher, adapter: IExchangeAdapter): void;
+}
 /** Pure-ish factory: builds an adapter for the requested mode.
  *  Falls back to PaperAdapter if a live mode is requested without credentials —
  *  callers should pre-validate via `modeRequiresCredentials`, but this
@@ -36,6 +45,8 @@ export declare class PluginRuntime {
      *  stops fire and NAV/uPnL stay live for non-dashboard symbols). Lives for
      *  the runtime's lifetime; started in paper, stopped in live. */
     private readonly _marketFeed;
+    private readonly operationLock?;
+    private wave9LiveLifecycleHooks?;
     /** Reconnect is serialized — a second caller waits for the first to finish
      *  so we never tear down an adapter that's mid-rebuild. */
     private reconnectInFlight;
@@ -45,11 +56,13 @@ export declare class PluginRuntime {
         simulator: ExchangeSimulator;
         stopWatcher?: PositionWatcher | null;
         marketFeed?: PaperMarketFeed | null;
+        operationLock?: TradingOperationLock;
     });
     get adapter(): IExchangeAdapter;
     get mode(): TradingMode;
     get stopWatcher(): PositionWatcher | null;
     get marketFeed(): PaperMarketFeed | null;
+    setWave9LiveLifecycleHooks(hooks?: Wave9LiveLifecycleHooks): void;
     /**
      * Swap the current adapter for a new one built from `next`. The old
      * adapter's background loops are stopped before the new one is wired in.