@reefclaw/openclaw-plugin 0.1.12 → 0.1.14

package/venues/hyperliquid/hl-bracket-coordinator.js

@@ -32,6 +32,10 @@ import { parseHlBracketCloid } from './hl-cloid.js';
 const TAG = 'hl-bracket-coordinator';
 const DEFAULT_MAX_ATTEMPTS = 3;
 const DEFAULT_BACKOFF = (attempt) => (attempt === 1 ? 1_000 : 2_000);
+/** Cap on `extraEntryCids` so a position scaled many times cannot grow its
+ *  ledger row without bound. Oldest dropped — a cid that old has either filled
+ *  (row already resized) or been cancelled. */
+const MAX_EXTRA_ENTRY_CIDS = 20;
 const TERMINAL_STATES = new Set([
     'triggered_sl',
     'triggered_tp',
@@ -46,10 +50,10 @@ const TRIGGERED_STATUSES = new Set(['filled', 'triggered']);
 /** A batch item HL rejected. ccxt types status as open|closed|canceled, but a
  *  per-item rejection surfaces as an `error` entry in the raw batch response
  *  (`info.error`) — check both shapes rather than trust the narrow type. */
-function isRejectedOrder(o) {
+export function isRejectedOrder(o) {
     if (!o)
         return true;
-    if (String(o.status ?? '') === 'rejected')
+    if (String(o.status ?? '').toLowerCase() === 'rejected')
         return true;
     const info = o.info;
     return Boolean(info && info.error);
@@ -109,6 +113,12 @@ export class HlBracketCoordinator extends EventEmitter {
             logger.warn(TAG, `registerEntry(${req.symbol}): non-terminal row exists (state=${existing.state}, ` +
                 `bracketId=${existing.bracketId}) — duplicate fill signal, NOT clobbering ` +
                 `(anti-clobber contract; scale-ins go through resizeToPosition)`);
+            // ★ F5: not clobbering the row is right — DROPPING the new order's cloid
+            // was not. A duplicate signal carrying a DIFFERENT cid is a second order
+            // against the same position (a resting scale-in, or a second entry while
+            // the first is still pending); its fill has to find this row or nothing
+            // attaches/resizes for it.
+            this.registerAdditionalEntryCid(req.symbol, entryCid);
             return;
         }
         if (existing)
@@ -129,6 +139,49 @@ export class HlBracketCoordinator extends EventEmitter {
             ts: new Date(this.now()).toISOString(),
         });
     }
+    /** ★ Audit 2026-07-26 F5 — track a SECOND entry order placed against a live
+     *  bracket row (a scale-in, or another entry while the first still rests).
+     *
+     *  Each submission gets a fresh cloid, but the row keeps the ORIGINAL
+     *  `entryCid`. The user-stream fill handler matches fills to rows by cid, so
+     *  an unrecorded cid meant the later fill matched NOTHING: no attach, no
+     *  resize. On HL that is naked exposure, not cosmetic drift — legs are FIXED
+     *  SIZE (T-2), so the added contracts stayed unprotected until the 60s
+     *  truth-check sweep happened to catch them.
+     *
+     *  Idempotent; a terminal/absent row or a repeat of the primary cid is a
+     *  no-op. Recording is deliberately CHEAP and local — the sweep remains the
+     *  backstop, this just stops it being the only line of defence. */
+    registerAdditionalEntryCid(symbol, entryCid) {
+        if (!entryCid)
+            return;
+        const row = this.ledger.getBySymbol(symbol);
+        if (!row || isTerminalBracketState(row.state))
+            return;
+        if (row.entryCid === entryCid)
+            return;
+        const current = row.extraEntryCids ?? [];
+        if (current.includes(entryCid))
+            return;
+        this.ledger.upsert({
+            ...row,
+            extraEntryCids: [...current, entryCid].slice(-MAX_EXTRA_ENTRY_CIDS),
+        });
+        logger.info(TAG, `${row.symbol}: tracking additional entry cid ${entryCid} against bracket ` +
+            `${row.bracketId} (state=${row.state}) — its fill must drive attach/resize (T-2)`);
+    }
+    /** The bracket row a user-stream fill belongs to: the primary `entryCid` OR
+     *  any cid recorded by `registerAdditionalEntryCid`. Terminal rows never
+     *  match. Single home for the matching rule so the adapter's fill handler
+     *  and the ledger can never disagree about what "our entry" means. */
+    findRowByEntryCid(cloid) {
+        if (!cloid)
+            return undefined;
+        return this.ledger
+            .getAll()
+            .find((r) => !isTerminalBracketState(r.state) &&
+            (r.entryCid === cloid || r.extraEntryCids?.includes(cloid) === true));
+    }
     /** Attach both legs (ONE batched signed action) with retries. Idempotent on
      *  a non-pending row. On exhaustion: ledger 'failed' + attach_failed event —
      *  the ADAPTER escalates to auto-flatten (it owns closePosition). */
@@ -261,6 +314,10 @@ export class HlBracketCoordinator extends EventEmitter {
             symbol: entry.symbol,
             positionSide,
             positionSize: newPositionSize,
+            // F4: with the registered prices in hand, resize can REBUILD a leg that
+            // vanished entirely (e.g. a stripped stop) instead of no-oping while
+            // the coverage sweep warns forever.
+            registeredPrices: { stop: entry.stopPrice, target: entry.targetPrice },
         });
         if (res.resized) {
             this.ledger.markState(symbol, entry.state, {

package/venues/hyperliquid/hl-brackets.d.ts

@@ -87,6 +87,16 @@ export declare function planResize(args: {
     positionSide: 'long' | 'short';
     positionSize: number;
     liveLegs: LiveLeg[];
+    /** The prices REGISTERED at attach (the ledger row's stopPrice/targetPrice).
+     *  ★ Audit 2026-07-26 F4: a role whose leg vanished entirely used to be
+     *  "the attach path's job" — but no path owned it, so a stop-less position
+     *  never self-healed. With the registered price in hand, resize REBUILDS
+     *  the missing leg at the price the agent pinned; without one it cannot
+     *  invent a level and leaves the role to the coverage alarms. */
+    registeredPrices?: {
+        stop?: number;
+        target?: number;
+    };
 }): ResizePlan;
 /** Is this exchange order one of OUR protective legs?
  *

package/venues/hyperliquid/hl-brackets.js

@@ -84,6 +84,11 @@ export function bracketCoversPosition(args) {
         const legs = args.liveLegs.filter((l) => l.role === role);
         if (legs.length === 0) {
             missing.push(role);
+            // A role with no leg at all leaves the WHOLE position uncovered on that
+            // side — report the honest naked size. Leaving this at 0 was audit
+            // 2026-07-26 F4: the resize planner keyed on shortfall, saw zero, and
+            // no-oped forever while a stop-less position stayed naked.
+            shortfall[role] = args.positionSize;
             continue;
         }
         const coveredSize = legs.reduce((sum, l) => sum + l.size, 0);
@@ -91,12 +96,15 @@ export function bracketCoversPosition(args) {
         if (gap > COVERAGE_EPSILON)
             shortfall[role] = gap;
     }
-    const covered = shortfall.stop <= COVERAGE_EPSILON &&
-        shortfall.target <= COVERAGE_EPSILON &&
-        // A missing STOP is never "covered" — that is the naked-position case. A
-        // missing TARGET is a policy choice (requireTakeProfit can be off), so it is
-        // reported in `missing` but does not by itself fail coverage.
-        !missing.includes('stop');
+    const covered = 
+    // A missing STOP is never "covered" — that is the naked-position case
+    // (its shortfall is the full position size, so this arm also fails).
+    !missing.includes('stop') &&
+        shortfall.stop <= COVERAGE_EPSILON &&
+        // A missing TARGET is a policy choice (requireTakeProfit can be off): it
+        // is reported via `missing` + `shortfall` but does not by itself fail
+        // coverage. A PRESENT-but-undersized target still does.
+        (missing.includes('target') || shortfall.target <= COVERAGE_EPSILON);
     return { covered, shortfall, missing };
 }
 /** ★ Resize protective legs after a scale-in (or any position-size change).
@@ -120,20 +128,44 @@ export function planResize(args) {
         positionSize: args.positionSize,
         liveLegs: args.liveLegs,
     });
-    // Nothing to do when every present leg already covers the position exactly.
+    const healable = ['stop', 'target'].filter((role) => {
+        const price = args.registeredPrices?.[role];
+        return (coverage.missing.includes(role) &&
+            typeof price === 'number' && Number.isFinite(price) && price > 0);
+    });
+    // Nothing to do when every present leg already covers the position exactly
+    // and no vanished-but-registered leg needs rebuilding. (A missing role's
+    // shortfall is the full position size, so present-leg sizing is checked
+    // against the PRESENT legs only.)
+    const presentShortfall = ['stop', 'target'].some((role) => !coverage.missing.includes(role) && coverage.shortfall[role] > COVERAGE_EPSILON);
     const oversized = args.liveLegs.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
-    if (coverage.shortfall.stop <= COVERAGE_EPSILON &&
-        coverage.shortfall.target <= COVERAGE_EPSILON &&
-        !oversized) {
+    if (!presentShortfall && !oversized && healable.length === 0) {
         return { cancelCloids: [], submit: [], noop: true };
     }
-    // Rebuild every PRESENT role at the correct size, preserving its trigger price.
+    // Rebuild every PRESENT role at the correct size (preserving its trigger
+    // price), plus every HEALABLE missing role at its registered price.
     const legs = [];
     const cancelCloids = [];
     for (const role of ['stop', 'target']) {
         const existing = args.liveLegs.filter((l) => l.role === role);
-        if (existing.length === 0)
-            continue; // absent leg = attach path's job, not resize's
+        if (existing.length === 0) {
+            if (!healable.includes(role))
+                continue; // no leg, no registered price — coverage alarms own it
+            legs.push({
+                role,
+                triggerPrice: args.registeredPrices[role],
+                size: args.positionSize,
+                cloid: buildHlBracketCloid(args.bracketId, role),
+            });
+            continue;
+        }
+        // A present role that already covers exactly (and isn't oversized) is left
+        // untouched — a heal of the OTHER role must not churn a healthy leg.
+        const coveredSize = existing.reduce((sum, l) => sum + l.size, 0);
+        const roleHealthy = args.positionSize - coveredSize <= COVERAGE_EPSILON &&
+            !existing.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
+        if (roleHealthy)
+            continue;
         // Trigger price is preserved from the live leg (the agent's pinned plan) —
         // resizing must NEVER silently move a stop.
         const triggerPrice = existing[0].triggerPrice;

package/venues/hyperliquid/hl-fill-ingest.d.ts

@@ -0,0 +1,18 @@
+import type { FillEvent } from '@reefclaw/shared';
+import type { HlFillEvent } from './hl-user-stream.js';
+/** Inverse of shared `toHyperliquidCoin`: every HL perp is USDC-quoted, so the
+ *  canonical symbol is `<coin>/USDC` with the coin's case preserved (kPEPE). */
+export declare function hlCoinToCanonical(coin: string): string;
+/**
+ * Map one HL fill to the shared FillEvent contract.
+ *
+ * Returns null (with a warn) when the identity fields the audit trail's
+ * idempotency key needs are absent or garbled — a row we cannot key must be
+ * dropped, never fabricated. `exchange` MUST come from
+ * `fillExchangeId('hyperliquid')` (FILL_EXCHANGE_ID strings are frozen once
+ * rows exist) — this mapper trusts the wiring, it does not mint literals.
+ */
+export declare function hlFillToFillEvent(fill: Partial<HlFillEvent>, wiring: {
+    userId: string;
+    exchange: string;
+}, source: 'ws' | 'rest_reconcile'): FillEvent | null;

package/venues/hyperliquid/hl-fill-ingest.js

@@ -0,0 +1,69 @@
+// Per-fill audit-trail ingest for the Hyperliquid venue (audit 2026-07-26 F26).
+//
+// Binance fills reach the `trades` table via ws-ingest (ORDER_TRADE_UPDATE →
+// FillEvent → TradeStoreClient). HL's user stream had no equivalent: fills
+// drove bracket wiring and were then DROPPED — a live book and P&L with no
+// independent per-trade record, nothing to reconcile against when a number
+// looks wrong, and fills during a WS gap lost forever. This module is the HL
+// analog: a pure mapper from the WS fill shape (also satisfied by REST
+// `userFillsByTime` rows) to the shared FillEvent contract. The adapter calls
+// it from the WS hot path and from the reconnect gap backfill; idempotency is
+// the server-side (exchange, exchange_trade_id) upsert, so double-delivery
+// between the two paths is harmless by design.
+import { logger } from '../../logger.js';
+const TAG = 'hl-fill-ingest';
+/** Inverse of shared `toHyperliquidCoin`: every HL perp is USDC-quoted, so the
+ *  canonical symbol is `<coin>/USDC` with the coin's case preserved (kPEPE). */
+export function hlCoinToCanonical(coin) {
+    return `${coin}/USDC`;
+}
+const num = (v) => {
+    const n = typeof v === 'string' ? Number(v) : typeof v === 'number' ? v : Number.NaN;
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * Map one HL fill to the shared FillEvent contract.
+ *
+ * Returns null (with a warn) when the identity fields the audit trail's
+ * idempotency key needs are absent or garbled — a row we cannot key must be
+ * dropped, never fabricated. `exchange` MUST come from
+ * `fillExchangeId('hyperliquid')` (FILL_EXCHANGE_ID strings are frozen once
+ * rows exist) — this mapper trusts the wiring, it does not mint literals.
+ */
+export function hlFillToFillEvent(fill, wiring, source) {
+    const price = num(fill.px);
+    const quantity = num(fill.sz);
+    const time = num(fill.time);
+    if (typeof fill.tid !== 'number' || !Number.isFinite(fill.tid) ||
+        typeof fill.oid !== 'number' || !Number.isFinite(fill.oid) ||
+        typeof fill.coin !== 'string' || fill.coin.length === 0 ||
+        price === undefined || quantity === undefined || quantity <= 0 ||
+        time === undefined ||
+        (fill.side !== 'A' && fill.side !== 'B')) {
+        logger.warn(TAG, `Dropping unmappable HL fill (source=${source}): ${JSON.stringify(fill).slice(0, 200)}`);
+        return null;
+    }
+    return {
+        exchange: wiring.exchange,
+        exchangeTradeId: String(fill.tid),
+        exchangeOrderId: String(fill.oid),
+        clientOrderId: typeof fill.cloid === 'string' && fill.cloid.length > 0 ? fill.cloid : undefined,
+        source,
+        userId: wiring.userId,
+        symbol: hlCoinToCanonical(fill.coin),
+        side: fill.side === 'B' ? 'BUY' : 'SELL',
+        quantity,
+        price,
+        // HL `crossed` is the taker flag; maker is its inverse. Absent → unknown.
+        maker: typeof fill.crossed === 'boolean' ? !fill.crossed : undefined,
+        // `fee` is inclusive of builderFee, and we hard-disable the builder fee
+        // (options.builderFee:false, pinned by hl-private.test.ts) so this is the
+        // whole commission either way. HL fees settle in USDC unless feeToken says
+        // otherwise.
+        commission: num(fill.fee),
+        commissionAsset: typeof fill.feeToken === 'string' ? fill.feeToken : 'USDC',
+        realizedPnl: num(fill.closedPnl),
+        exchangeTime: time,
+        rawPayload: fill,
+    };
+}

package/venues/hyperliquid/hl-live-adapter.d.ts

@@ -6,10 +6,23 @@ import { type HlCredentials } from './hl-private.js';
 import type { BracketId } from '../../live/bracket-types.js';
 import { BracketLedger } from '../../live/bracket-ledger.js';
 import { HlBracketCoordinator } from './hl-bracket-coordinator.js';
+import type { TradeIngestWiring } from '../../live/live-adapter.js';
 export interface HlLiveAdapterOptions {
     credentials: HlCredentials;
     mode: TradingMode;
     marketSlippagePct?: number;
+    /** MICRO_LIVE per-order notional cap in quote-USD (USDC here). Defaults to
+     *  $50 in MICRO_LIVE — the same default Binance's LiveAdapter has enforced
+     *  since the mode existed. HL shipped Phase 3 without any cap, making
+     *  "micro" a label (audit 2026-07-26 F8). Ignored in LIVE. */
+    microLive?: {
+        maxPositionUSDT?: number;
+    };
+    /** Audit-trail wiring (audit 2026-07-26 F26): when present, every user-stream
+     *  fill is POSTed to /api/internal/trades and reconnect gaps are backfilled
+     *  via userFillsByTime. Same object boot passes the Binance adapter —
+     *  `exchange` MUST be fillExchangeId('hyperliquid'). */
+    tradeIngest?: TradeIngestWiring;
     /** Test seams. Production omits both. */
     bracketLedger?: BracketLedger;
     disableUserStream?: boolean;
@@ -30,6 +43,13 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
     private truthCheckRunning;
     private _readiness;
     private openOrdersUnavailableUntil;
+    /** MICRO_LIVE per-order notional cap (USD). null = LIVE, uncapped. */
+    private readonly maxPositionUsd;
+    /** Resolved audit-trail wiring (F26). undefined = ingest not configured. */
+    private readonly fillIngest?;
+    /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
+     *  low-water mark the reconnect gap backfill widens from. */
+    private lastFillIngestMs;
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -76,6 +96,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
      * against an unknown book could open a NEW position in the opposite direction);
      * a CONFIRMED-flat account is a benign no-op.
+     *
+     * ★ Success requires CONFIRMED flat: brackets/ledger are only cleaned up after
+     * a post-close position read shows zero — a rejected/partial IOC throws with
+     * protection left in place.
      */
     closePosition(symbol: string, _closeReason?: CloseReason): Promise<CcxtOrder>;
     getBalance(): Promise<CcxtBalance>;
@@ -128,6 +152,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
         symbol: string;
         positionSide: 'long' | 'short';
         positionSize: number;
+        registeredPrices?: {
+            stop?: number;
+            target?: number;
+        };
     }): Promise<{
         resized: boolean;
         slCid?: string;
@@ -143,6 +171,14 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  cleanup before a fresh attach). THROWS when order state is unknown —
      *  the caller logs and still attaches (protection beats hygiene). */
     cancelSymbolBracketLegs(symbol: string): Promise<number>;
+    /** Audit-trail ingest (F26): fire-and-forget POST of one fill. The client
+     *  never blocks the WS hot path; the server-side (exchange, trade id) upsert
+     *  makes WS/backfill double-delivery a no-op. */
+    private ingestFill;
+    /** Reconnect gap backfill (F26): the WS replays NOTHING (T-5), so fills that
+     *  landed while the socket was down exist ONLY via REST. Over-fetch with a
+     *  60s overlap is harmless (idempotent upsert); under-fetch loses audit rows. */
+    private backfillFillGap;
     /** Entry fills drive attach (resting limits) / resize (partial-fill growth).
      *  `startPosition` is the position BEFORE this fill — the WS-authoritative
      *  way to know the after-fill total without an extra REST read. */

package/venues/hyperliquid/hl-live-adapter.js

@@ -36,8 +36,9 @@ import { buildHlOrderCloid, parseHlBracketCloid } from './hl-cloid.js';
 import { BracketLedger } from '../../live/bracket-ledger.js';
 import { generateBracketId } from '../../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.js';
-import { HlBracketCoordinator, isTerminalBracketState } from './hl-bracket-coordinator.js';
+import { HlBracketCoordinator, isRejectedOrder, isTerminalBracketState, } from './hl-bracket-coordinator.js';
 import { HyperliquidUserStream } from './hl-user-stream.js';
+import { hlFillToFillEvent } from './hl-fill-ingest.js';
 import { formatError } from '../../logger.js';
 const TAG = 'hl-live-adapter';
 /** Venue-distinct ledger storage — a venue switch on the same box must never
@@ -70,6 +71,13 @@ export class HyperliquidLiveAdapter extends EventEmitter {
     truthCheckRunning = false;
     _readiness = 'INIT_PENDING';
     openOrdersUnavailableUntil = 0;
+    /** MICRO_LIVE per-order notional cap (USD). null = LIVE, uncapped. */
+    maxPositionUsd;
+    /** Resolved audit-trail wiring (F26). undefined = ingest not configured. */
+    fillIngest;
+    /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
+     *  low-water mark the reconnect gap backfill widens from. */
+    lastFillIngestMs = 0;
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -81,6 +89,23 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         this.api = new HyperliquidPrivateApi(opts.credentials);
         this.publicApi = new HyperliquidPublicApi({ testnet: opts.credentials.testnet });
         this.slippagePct = clampSlippage(opts.marketSlippagePct ?? DEFAULT_MARKET_SLIPPAGE);
+        this.maxPositionUsd =
+            opts.mode === 'MICRO_LIVE' ? opts.microLive?.maxPositionUSDT ?? 50 : null;
+        if (opts.tradeIngest) {
+            if (opts.tradeIngest.exchange) {
+                this.fillIngest = {
+                    client: opts.tradeIngest.client,
+                    userId: opts.tradeIngest.userId,
+                    exchange: opts.tradeIngest.exchange,
+                };
+                logger.info(TAG, 'Per-fill audit-trail ingest wired (WS + reconnect gap backfill)');
+            }
+            else {
+                // FILL_EXCHANGE_ID strings are frozen once rows exist — refusing beats
+                // minting rows under a guessed exchange id.
+                logger.warn(TAG, 'tradeIngest provided WITHOUT an exchange id — fill ingest disabled');
+            }
+        }
         this.infoCache = new HyperliquidInfoCache(async () => {
             // `meta` is a keyless info read — the public client owns it.
             return this.publicApi.fetchMeta();
@@ -109,7 +134,8 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         const rules = await this.infoCache.load();
         if (markets && rules && this.infoCache.size > 0) {
             this._readiness = 'READY';
-            logger.info(TAG, `HL live adapter READY (${this.infoCache.size} assets, mode=${this.opts.mode})`);
+            logger.info(TAG, `HL live adapter READY (${this.infoCache.size} assets, mode=${this.opts.mode}` +
+                `${this.maxPositionUsd != null ? `, micro cap $${this.maxPositionUsd}/order` : ''})`);
         }
         else {
             // DEGRADED, not BLOCKED: reads/exits still work; entries are refused
@@ -135,13 +161,17 @@ export class HyperliquidLiveAdapter extends EventEmitter {
                 walletAddress: this.opts.credentials.walletAddress,
                 testnet: this.opts.credentials.testnet,
                 callbacks: {
-                    onFill: (fill) => this.onUserFill(fill),
+                    onFill: (fill, meta) => this.onUserFill(fill, meta),
                     onOrderUpdate: (update) => this.onUserOrderUpdate(update),
                     onUserEvent: () => {
                         /* liquidation/funding — liquidation fills also arrive via onFill */
                     },
                     onResyncNeeded: (window) => {
                         void this.runTruthCheck(`ws_resync_blind_${Math.round(window.wasDisconnectedMs / 1000)}s`);
+                        // Fills that landed inside the blind window exist only via REST
+                        // (T-5: the WS replays nothing) — recover them for the audit
+                        // trail (F26). Bracket state is healed by the truth-check above.
+                        void this.backfillFillGap(window.sinceMs).catch((err) => logger.warn(TAG, `Fill gap backfill threw: ${msg(err)}`));
                     },
                 },
             });
@@ -183,6 +213,21 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             }
             referencePrice = mark;
         }
+        // ---- Micro-live notional cap (audit 2026-07-26 F8) ----
+        // Same semantics as Binance's LiveAdapter: clamp NEW exposure to the cap;
+        // never touch risk-reducing orders (blocking a close is worse than an
+        // uncapped close, and reduce-only cannot increase the position). A
+        // reference price is always in hand by this point — market orders fetched
+        // the mark above, limit orders carry their own price.
+        let effectiveAmount = amount;
+        if (this.maxPositionUsd != null && !options?.reduceOnly) {
+            const maxAmount = this.maxPositionUsd / referencePrice;
+            if (effectiveAmount > maxAmount) {
+                logger.info(TAG, `Micro-live cap: reducing ${symbol} amount ${effectiveAmount} → ${maxAmount} ` +
+                    `(max $${this.maxPositionUsd} notional at ref ${referencePrice})`);
+                effectiveAmount = maxAmount;
+            }
+        }
         const submitPrice = type === 'market'
             ? this.infoCache.marketPrice({
                 symbol,
@@ -193,7 +238,7 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             : this.infoCache.roundPrice(symbol, referencePrice, side === 'buy' ? 'down' : 'up');
         const check = this.infoCache.validate({
             symbol,
-            amount,
+            amount: effectiveAmount,
             side,
             price: type === 'limit' ? submitPrice : undefined,
             referencePrice,
@@ -303,6 +348,13 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         const ledger = this.getHlBracketCoordinator().getLedger();
         const existing = ledger.getBySymbol(symbol);
         if (existing && !isTerminalBracketState(existing.state) && existing.state !== 'pending_entry') {
+            // ★ F5: record THIS order's cloid against the live row FIRST. A scale-in
+            // submitted as a resting limit fills later, and `onUserFill` matches
+            // fills to rows by cid — without this its fill matched nothing, so no
+            // resize ever ran and the added contracts stayed NAKED (T-2: legs are
+            // fixed size) until the 60s truth-check sweep. Registered before the
+            // resize below so a fast fill can never race ahead of the bookkeeping.
+            this.getHlBracketCoordinator().registerAdditionalEntryCid(symbol, entryCloid);
             if (isFilled) {
                 void this.resizeAfterScaleInAsync(symbol);
             }
@@ -420,6 +472,10 @@ export class HyperliquidLiveAdapter extends EventEmitter {
      * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
      * against an unknown book could open a NEW position in the opposite direction);
      * a CONFIRMED-flat account is a benign no-op.
+     *
+     * ★ Success requires CONFIRMED flat: brackets/ledger are only cleaned up after
+     * a post-close position read shows zero — a rejected/partial IOC throws with
+     * protection left in place.
      */
     async closePosition(symbol, _closeReason) {
         const positions = await this.api.fetchPositions(symbol);
@@ -456,10 +512,34 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         });
         if (!order)
             throw new Error(`closePosition(${symbol}) returned no order`);
-        // Ledger hygiene: mark the bracket row terminal. T-1 auto-cancels the
-        // exchange legs when the position goes flat, so this is bookkeeping (plus
-        // a harmless defensive cancel), never load-bearing. Fire-and-forget — a
-        // close must never fail on ledger cleanup.
+        if (isRejectedOrder(order)) {
+            throw new Error(`closePosition(${symbol}): close order REJECTED by the exchange — position still open, ` +
+                'protection left in place. Retry the close.');
+        }
+        // ★ An IOC acknowledgement is NOT a fill: the slippage-bounded close can
+        // partially fill (or fill nothing) in a fast market. Confirm flat from
+        // exchange truth BEFORE touching protection — cancelling the brackets on a
+        // live residual would strip its only stop (no watcher fallback on HL live)
+        // AND terminalize the ledger row, hiding the residual from the truth-check
+        // sweep forever (audit 2026-07-26 F3).
+        const after = await this.api.fetchPositions(symbol);
+        if (after === null) {
+            logger.warn(TAG, `closePosition(${symbol}): post-close position read FAILED — flat UNCONFIRMED; leaving ` +
+                'protection + ledger row in place (T-1 auto-cancels legs on flat; the truth-check ' +
+                'sweep reconciles the row either way)');
+            return order;
+        }
+        const residualPos = after.find((p) => p.symbol?.startsWith(symbol.split(':')[0]));
+        const residual = Math.abs(Number(residualPos?.contracts ?? 0));
+        if (residual > 0) {
+            throw new Error(`closePosition(${symbol}): IOC close did NOT fully fill — residual ${residual} still open, ` +
+                'protection left in place (the truth-check sweep resizes the legs to the residual). ' +
+                'Retry the close.');
+        }
+        // Confirmed flat. Ledger hygiene: mark the bracket row terminal. T-1
+        // auto-cancels the exchange legs when the position goes flat, so this is
+        // bookkeeping (plus a harmless defensive cancel), never load-bearing.
+        // Fire-and-forget — a close must never fail on ledger cleanup.
         const row = this.getHlBracketCoordinator().getLedger().getBySymbol(symbol);
         if (row && !isTerminalBracketState(row.state)) {
             void this.getHlBracketCoordinator()
@@ -608,6 +688,16 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             // added size stays naked until the caller retries (truth-check sweep).
             throw new Error(`resizeBrackets(${args.symbol}): submission returned nothing — old legs left in place`);
         }
+        const rejected = submitted.filter((order) => isRejectedOrder(order));
+        if (submitted.length !== plan.submit.length || rejected.length > 0) {
+            // A batch-level acknowledgement does not mean every leg was accepted:
+            // Hyperliquid reports individual failures in each order's raw
+            // `info.error`. Keep every known-good old leg live and leave the ledger
+            // untouched so the truth-check sweep can retry with fresh cloids.
+            throw new Error(`resizeBrackets(${args.symbol}): batch returned ${submitted.length}/${plan.submit.length} legs` +
+                (rejected.length > 0 ? ` (${rejected.length} rejected)` : '') +
+                ' — old legs left in place');
+        }
         for (const cloid of plan.cancelCloids) {
             // Register BEFORE the request: the WS 'canceled' event can beat the
             // ledger update and must not read as stripped protection (canary).
@@ -671,14 +761,67 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         return cancelled;
     }
     // ---- User-stream handlers (issue #209 wiring) ----
+    /** Audit-trail ingest (F26): fire-and-forget POST of one fill. The client
+     *  never blocks the WS hot path; the server-side (exchange, trade id) upsert
+     *  makes WS/backfill double-delivery a no-op. */
+    ingestFill(fill, source) {
+        if (!this.fillIngest)
+            return false;
+        const event = hlFillToFillEvent(fill, this.fillIngest, source);
+        if (!event)
+            return false;
+        this.fillIngest.client.post(this.fillIngest.userId, event);
+        if (event.exchangeTime > this.lastFillIngestMs)
+            this.lastFillIngestMs = event.exchangeTime;
+        return true;
+    }
+    /** Reconnect gap backfill (F26): the WS replays NOTHING (T-5), so fills that
+     *  landed while the socket was down exist ONLY via REST. Over-fetch with a
+     *  60s overlap is harmless (idempotent upsert); under-fetch loses audit rows. */
+    async backfillFillGap(sinceMs) {
+        if (!this.fillIngest)
+            return;
+        const floor = Date.now() - 24 * 3600_000; // never sweep more than a day
+        const from = Math.max(floor, Math.min(sinceMs, this.lastFillIngestMs > 0 ? this.lastFillIngestMs : Number.POSITIVE_INFINITY) - 60_000);
+        const fills = await this.api.fetchFillsSince(from);
+        if (fills === null) {
+            // null ≠ empty: the fetch FAILED — the gap stays open, the next resync
+            // (or the periodic truth-check path) retries. Never treat as "no fills".
+            logger.warn(TAG, `Fill gap backfill fetch FAILED (since=${new Date(from).toISOString()}) — retried on next resync`);
+            return;
+        }
+        let posted = 0;
+        for (const f of fills) {
+            if (this.ingestFill(f, 'rest_reconcile'))
+                posted++;
+        }
+        if (fills.length > 0) {
+            logger.info(TAG, `Fill gap backfill: posted ${posted}/${fills.length} fill(s) since ${new Date(from).toISOString()}`);
+        }
+    }
     /** Entry fills drive attach (resting limits) / resize (partial-fill growth).
      *  `startPosition` is the position BEFORE this fill — the WS-authoritative
      *  way to know the after-fill total without an extra REST read. */
-    onUserFill(fill) {
+    onUserFill(fill, meta) {
+        // Audit trail first — bracket bookkeeping below must not gate the record.
+        // Snapshot fills ARE ingested on purpose: the ledger is idempotent on
+        // (exchange, exchange_trade_id), so replayed history upserts harmlessly and
+        // backfills rows we'd otherwise miss (F26).
+        this.ingestFill(fill, 'ws');
+        // ★ F44: but bracket bookkeeping is a STATE MUTATION, not an idempotent
+        // write. Every (re)subscribe ships a snapshot of recent fills, and acting on
+        // one recomputes the position as that old fill's `startPosition + sz` — a
+        // stale total — then resizes the LIVE protective legs down to it. Observed
+        // on the rig 2026-07-27: ETH legs cut 0.027 → 0.0231 thirteen seconds after
+        // a user-stream connect, leaving 0.0039 unprotected until the 60s sweep
+        // healed it, in a repeating flap. Exchange truth is the resync's job.
+        if (meta?.isSnapshot)
+            return;
         try {
-            const ledger = this.getHlBracketCoordinator().getLedger();
-            const rows = ledger.getAll().filter((r) => !isTerminalBracketState(r.state));
-            const row = rows.find((r) => r.entryCid && fill.cloid && r.entryCid === fill.cloid);
+            // Matches the primary entry cid OR any additional cid recorded for a
+            // scale-in / second resting entry (F5) — matching on `entryCid` alone
+            // silently dropped those fills.
+            const row = this.getHlBracketCoordinator().findRowByEntryCid(fill.cloid);
             if (!row)
                 return;
             const sz = Math.abs(Number(fill.sz ?? 0));