@reefclaw/connect 0.1.20 → 0.1.22

package/assets/plugin/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;
@@ -25,11 +38,22 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     private _coordinator;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    readonly bracketsAlwaysEnforced = true;
     private userStream;
     private truthCheckTimer;
     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
@@ -132,6 +156,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;
@@ -147,6 +175,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/assets/plugin/venues/hyperliquid/hl-live-adapter.js

@@ -38,6 +38,7 @@ import { generateBracketId } from '../../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.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
@@ -65,11 +66,22 @@ export class HyperliquidLiveAdapter extends EventEmitter {
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     _coordinator = null;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    bracketsAlwaysEnforced = true;
     userStream = null;
     truthCheckTimer = null;
     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 +93,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 +138,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 +165,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 +217,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 +242,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 +352,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);
             }
@@ -709,14 +765,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));

package/assets/plugin/venues/hyperliquid/hl-public.d.ts

@@ -1,6 +1,7 @@
 import type { CcxtTicker, CcxtOHLCV } from '../../types.js';
 import type { OrderBookDepth } from '../../simulator/types.js';
 import type { PublicMarketDataApi } from '../../ccxt/public-market-data-api.js';
+import { type VenueReachabilityResult } from '@reefclaw/shared';
 export interface HyperliquidPublicApiOptions {
     testnet?: boolean;
     /** Test seam — injected ccxt exchange instance. */
@@ -60,11 +61,17 @@ export declare class HyperliquidPublicApi implements PublicMarketDataApi {
      *  (verified live 2026-07-11: `{"specialStatuses":null,"time":…}`) doubles
      *  as the clock-drift source. Geo classification is best-effort — HL's
      *  API-level geo behavior is UNVERIFIED (plan §3.9); a 403/451 maps to
-     *  geo_blocked, anything else non-2xx/network maps to unreachable. */
-    probeReachability(): Promise<{
-        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
-        driftMs: number | null;
-    }>;
+     *  geo_blocked, anything else non-2xx/network maps to unreachable.
+     *
+     *  ★ Self-stall detection (issue #265): the failure path is wall-clock timed.
+     *  A throw is only evidence about the VENUE if our own abort timer fired
+     *  roughly when it was set for. On a starved host the loop stops running —
+     *  observed live on the HL rig: this 10s timer landed 86s late while the
+     *  agent was trading on HL perfectly well — and blaming the network then
+     *  produces a confident, wrong "check DNS/firewall/region" banner. Past
+     *  STALL_FACTOR× the budget we report `stalled`, which the reporter renders
+     *  as `unknown`: we genuinely did not learn whether HL is reachable. */
+    probeReachability(): Promise<VenueReachabilityResult>;
     /** `meta` — the asset universe (szDecimals, maxLeverage, positional assetIndex).
      *  Keyless info read, weight 20. Feeds HyperliquidInfoCache. Returns null on any
      *  failure (never a partial universe — a half-loaded rules table would silently

package/assets/plugin/venues/hyperliquid/hl-public.js

@@ -32,6 +32,7 @@
 // on this venue — logged clearly, null returned (never silently translated).
 import { createRequire } from 'node:module';
 import { logger } from '../../logger.js';
+import { REACHABILITY_STALL_FACTOR } from '@reefclaw/shared';
 import { toCcxtSymbol, toHyperliquidCoin } from '../symbols.js';
 const TAG = 'hl-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
@@ -55,6 +56,10 @@ const DEFAULT_TICKER_TTL_MS = 4_000;
  *  snapshot's ccxt call re-runs the whole fetchMarkets pipeline (weight ~60,
  *  ~13s on a slow host) and nothing price-critical reads these fields. */
 const FULL_SNAPSHOT_REFRESH_MS = 300_000;
+/** Reachability-probe request budget. Also the yardstick for self-stall
+ *  detection — see probeReachability. */
+const PROBE_TIMEOUT_MS = 10_000;
+const STALL_FACTOR = REACHABILITY_STALL_FACTOR;
 function resolveTickerTtlMs() {
     const raw = Number(process.env.RC_HL_TICKER_TTL_MS);
     if (!Number.isFinite(raw) || raw < 500)
@@ -343,10 +348,20 @@ export class HyperliquidPublicApi {
      *  (verified live 2026-07-11: `{"specialStatuses":null,"time":…}`) doubles
      *  as the clock-drift source. Geo classification is best-effort — HL's
      *  API-level geo behavior is UNVERIFIED (plan §3.9); a 403/451 maps to
-     *  geo_blocked, anything else non-2xx/network maps to unreachable. */
+     *  geo_blocked, anything else non-2xx/network maps to unreachable.
+     *
+     *  ★ Self-stall detection (issue #265): the failure path is wall-clock timed.
+     *  A throw is only evidence about the VENUE if our own abort timer fired
+     *  roughly when it was set for. On a starved host the loop stops running —
+     *  observed live on the HL rig: this 10s timer landed 86s late while the
+     *  agent was trading on HL perfectly well — and blaming the network then
+     *  produces a confident, wrong "check DNS/firewall/region" banner. Past
+     *  STALL_FACTOR× the budget we report `stalled`, which the reporter renders
+     *  as `unknown`: we genuinely did not learn whether HL is reachable. */
     async probeReachability() {
         const ac = new AbortController();
-        const tid = setTimeout(() => ac.abort(), 10_000);
+        const tid = setTimeout(() => ac.abort(), PROBE_TIMEOUT_MS);
+        const startedAt = Date.now();
         try {
             const res = await this.fetchImpl(`${this.baseUrl()}/info`, {
                 method: 'POST',
@@ -368,7 +383,13 @@ export class HyperliquidPublicApi {
             return { outcome: 'reachable', driftMs };
         }
         catch (err) {
-            logger.warn(TAG, `probeReachability failed: ${err instanceof Error ? err.message : String(err)}`);
+            const elapsedMs = Date.now() - startedAt;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (elapsedMs > PROBE_TIMEOUT_MS * STALL_FACTOR) {
+                logger.warn(TAG, `probeReachability inconclusive: this process was starved — a ${PROBE_TIMEOUT_MS}ms probe took ${Math.round(elapsedMs / 1000)}s (${msg}). Reporting reachability as unknown, NOT as a Hyperliquid failure.`);
+                return { outcome: 'stalled', driftMs: null, stallMs: elapsedMs };
+            }
+            logger.warn(TAG, `probeReachability failed: ${msg}`);
             return { outcome: 'unreachable', driftMs: null };
         }
         finally {

package/assets/plugin/venues/hyperliquid/hl-user-stream.d.ts

@@ -41,7 +41,19 @@ export interface HlOrderUpdateEvent {
     statusTimestamp: number;
 }
 export interface HlUserStreamCallbacks {
-    onFill: (fill: HlFillEvent) => void;
+    /** ★ `meta.isSnapshot` marks a fill from the subscription SNAPSHOT — the batch
+     *  of recent history HL sends on every (re)subscribe — not a live execution.
+     *
+     *  Do NOT confuse this with the T-5 gap rule below: HL not replaying the fills
+     *  you MISSED while disconnected is true and unrelated. It still ships a
+     *  snapshot of recent history on subscribe, and consumers must tell them apart.
+     *  Idempotent consumers (the audit-trail ingest, keyed on exchange trade id)
+     *  should take snapshot fills; state MUTATORS (bracket resize/attach) must not
+     *  — replaying an old fill's `startPosition + sz` resizes live protective legs
+     *  to a stale historical size (audit 2026-07-27 F44). */
+    onFill: (fill: HlFillEvent, meta: {
+        isSnapshot: boolean;
+    }) => void;
     onOrderUpdate: (update: HlOrderUpdateEvent) => void;
     /** userEvents: liquidation / funding / non-user-cancel — the close-bypass feed. */
     onUserEvent: (event: Record<string, unknown>) => void;

package/assets/plugin/venues/hyperliquid/hl-user-stream.js

@@ -137,9 +137,12 @@ export class HyperliquidUserStream {
         switch (channel) {
             case 'userFills': {
                 const payload = data;
+                // `isSnapshot` was typed here from the start but never read — so every
+                // (re)connect replayed recent history as if it were live (F44).
+                const isSnapshot = payload?.isSnapshot === true;
                 for (const fill of payload?.fills ?? []) {
                     this.lastEventAt = Math.max(this.lastEventAt, fill.time ?? Date.now());
-                    this.opts.callbacks.onFill(fill);
+                    this.opts.callbacks.onFill(fill, { isSnapshot });
                 }
                 break;
             }

package/assets/plugin/venues/registry.js

@@ -1,12 +1,13 @@
 // Venue registry — the single seam where a trading venue's LIVE adapter is
-// constructed (Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
+// constructed (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
 //
-// Phase 0 scope: Binance is the ONLY venue this build can trade live;
-// 'hyperliquid' is a recognised-but-unsupported config value that boot handles
-// by falling back to PAPER (never by crashing register() — OpenClaw treats a
-// throwing register as "ignored" and the agent silently loses every tool).
-// Phase 3 adds the HyperliquidLiveAdapter arm HERE and nowhere else, so the
-// boot path never grows a second venue branch.
+// This build trades live on BOTH supported venues: Binance (LiveAdapter) and
+// Hyperliquid (HyperliquidLiveAdapter, Phase 3 — brackets always enforced by
+// HlBracketCoordinator). A venue with missing/invalid credentials falls back
+// to PAPER at boot (never by crashing register() — OpenClaw treats a throwing
+// register as "ignored" and the agent silently loses every tool). Any future
+// venue adds its arm HERE and nowhere else, so the boot path never grows a
+// second venue branch.
 //
 // Venue is LOCAL mechanism (TOOL_DISTRIBUTION_ARCHITECTURE.md §2 decision
 // rule: it holds keys + is part of the safety floor) — it is read from

package/assets/plugin/wave9/paper-admission-guard.d.ts

@@ -1,7 +1,18 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 /** One catalog toggle represents both frozen Wave 9 strategy legs. */
 export declare const WAVE9_BUNDLE_SETUP_TYPE = "wave9_28d_momentum_reversal";
+/** TOOL-level close reason: what close_position args + beginExit redemption
+ *  requests must carry. The `wave9_` namespace keeps it from colliding with
+ *  generic CloseReason values. */
 export declare const WAVE9_MECHANICAL_EXIT_REASON = "wave9_signal_reversal";
+/** DECISION-level exit cause: what the authorization decision
+ *  (Wave9PaperExitTokenDecision.reason) records at issuance. Deliberately a
+ *  DIFFERENT string from WAVE9_MECHANICAL_EXIT_REASON — the decision names
+ *  WHY the strategy exits (its only exit cause is a signal reversal), the
+ *  tool reason names WHICH namespaced close path redeems it. issueExitBatch
+ *  validates this constant; beginExit validates the tool constant. Two fields
+ *  on two layers, each checked against its own value — not an asymmetry. */
+export declare const WAVE9_EXIT_DECISION_REASON = "signal_reversal";
 export type Wave9ExecutionMode = 'PAPER' | 'LIVE';
 /** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
 export declare function isWave9ManagedPosition(position: {
@@ -93,7 +104,7 @@ export interface Wave9PaperExitTokenDecision {
     missionId: string;
     symbol: string;
     positionSide: 'long' | 'short';
-    reason: 'signal_reversal';
+    reason: typeof WAVE9_EXIT_DECISION_REASON;
     notBeforeMs: number;
     deadlineMs: number;
     positionFingerprint: string;

package/assets/plugin/wave9/paper-admission-guard.js

@@ -2,7 +2,18 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { WAVE9_SYMBOL_PRIORITY } from '../portfolio/wave9-policy.js';
 /** One catalog toggle represents both frozen Wave 9 strategy legs. */
 export const WAVE9_BUNDLE_SETUP_TYPE = 'wave9_28d_momentum_reversal';
+/** TOOL-level close reason: what close_position args + beginExit redemption
+ *  requests must carry. The `wave9_` namespace keeps it from colliding with
+ *  generic CloseReason values. */
 export const WAVE9_MECHANICAL_EXIT_REASON = 'wave9_signal_reversal';
+/** DECISION-level exit cause: what the authorization decision
+ *  (Wave9PaperExitTokenDecision.reason) records at issuance. Deliberately a
+ *  DIFFERENT string from WAVE9_MECHANICAL_EXIT_REASON — the decision names
+ *  WHY the strategy exits (its only exit cause is a signal reversal), the
+ *  tool reason names WHICH namespaced close path redeems it. issueExitBatch
+ *  validates this constant; beginExit validates the tool constant. Two fields
+ *  on two layers, each checked against its own value — not an asymmetry. */
+export const WAVE9_EXIT_DECISION_REASON = 'signal_reversal';
 /** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
 export function isWave9ManagedPosition(position) {
     return position.setupType === WAVE9_BUNDLE_SETUP_TYPE
@@ -615,7 +626,7 @@ export class Wave9PaperAdmissionGuard {
         exactText(decision.candidateId, 'exit candidateId');
         exactText(decision.missionId, 'missionId');
         requireExecutionMode(decision.tradingMode);
-        if (decision.reason !== 'signal_reversal')
+        if (decision.reason !== WAVE9_EXIT_DECISION_REASON)
             throw new Wave9PaperAdmissionGuardError('Wave 9 exit reason must be signal_reversal');
         if (!WAVE9_SYMBOL_PRIORITY.includes(decision.symbol)) {
             throw new Wave9PaperAdmissionGuardError(`unsupported Wave 9 symbol ${decision.symbol}`);

package/assets/shared/index.d.ts

@@ -9,6 +9,6 @@ export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js
 export type { Direction, OhlcvBar, TradeFlowBucket, GlobalMarketContext, MarketContext, SignalCondition, StrategyEvaluation, StrategyDefinition, SignalEvent, StrategyState, SignalSnapshot, } from './signals/types.js';
 export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, EntryRuleConfig, StopRuleConfig, DirectionRule, PrimaryTimeframe, StrategyConfig, } from './signals/conditions/types.js';
 export type { VenueId } from './venues/symbols.js';
-export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
-export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, } from './readiness.js';
-export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, VenueReachabilityOutcome, VenueReachabilityResult, } from './readiness.js';
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, HOST_STALL_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/index.js

@@ -3,5 +3,9 @@ export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from './protocol.js';
 export { logger, setLogLevel, formatError } from './logger.js';
 export { VALID_TRADING_MODES, isTradingMode, validateModeTransition, modeRequiresCredentials, } from './trading-mode.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
-export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
-export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+// ★ VALUES, not types — a symbol missing from this list type-checks fine at the
+// import site and is `undefined` at runtime (the shared-registry drift class).
+// Adding a const to readiness.ts is only half the job; it must be re-exported
+// here AND the shared dist rebuilt before the plugin can see it.
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, HOST_STALL_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/readiness.d.ts

@@ -2,7 +2,30 @@ export type ReadinessStatus = 'pass' | 'warn' | 'fail' | 'unknown';
 /** Which lifecycle phase a check belongs to. `connect` runs with NO Binance API
  *  keys (covers paper trading too); `golive` needs keys (Phase 2). */
 export type ReadinessPhase = 'connect' | 'golive';
-export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered';
+export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered' | 'host_responsive';
+/** What a venue reachability probe concluded.
+ *
+ *  ★ `stalled` is the one that is NOT about the venue: it means the probe's own
+ *  abort timer fired far later than it was set for, which can only happen when
+ *  this process was starved of CPU — so the request never got a fair chance and
+ *  we learned NOTHING about the venue. Before it existed, a frozen host fell
+ *  into the same catch as a real network failure and the dashboard confidently
+ *  told the operator to check their DNS/firewall/region (issue #265).
+ *  `unknown` = we deliberately didn't probe (ban/weight gate paused us). */
+export type VenueReachabilityOutcome = 'reachable' | 'geo_blocked' | 'unreachable' | 'stalled' | 'unknown';
+export interface VenueReachabilityResult {
+    outcome: VenueReachabilityOutcome;
+    driftMs: number | null;
+    /** Wall-clock the probe actually took, set only when `outcome === 'stalled'`
+     *  — it IS the evidence (a 10s timer that returned after 86s). */
+    stallMs?: number;
+}
+/** A failed probe is read as a venue failure only while it finished within
+ *  this multiple of its own timeout budget; past it, the clock says the
+ *  process — not the network — is what broke. 2× leaves generous room for
+ *  ordinary scheduling jitter and TLS/DNS slack while sitting far below the
+ *  8×-and-worse overshoots a real freeze produces. */
+export declare const REACHABILITY_STALL_FACTOR = 2;
 export interface ReadinessCheck {
     /** Stable machine id. Widened to string so the webapp can render checks from a
      *  newer plugin it doesn't have the union for. */
@@ -42,11 +65,31 @@ interface CheckCopy {
 /** The canonical connect-phase checks + their plain-English fixes. Single source
  *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
 export declare const READINESS_CHECK_COPY: Record<ReadinessCheckId, CheckCopy>;
+/** Assertive copy for a stall we COULD attribute, passed explicitly as the
+ *  `fixHint` override — the same "only name a cause you measured" rule that
+ *  governs GEO_BLOCK_FIX_HINT. The discriminator is the kernel's own runqueue
+ *  wait for this process (/proc/self/schedstat): time spent runnable but denied
+ *  a CPU. Large ⇒ the host really is the problem; ~0 across a multi-second
+ *  freeze ⇒ the process blocked itself and no amount of extra hardware helps. */
+export declare const HOST_STALL_FIX_HINT: Record<'host_starved' | 'self_inflicted', string>;
+/** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
+ *  override. This is the one case where naming the cause is honest: the server
+ *  answered 451/403, so we are reporting what it told us — not an inference from
+ *  a request that never completed. */
+export declare const GEO_BLOCK_FIX_HINT: Record<'binance' | 'hyperliquid', string>;
 /** Build a self-describing check, pulling label/phase/fixHint from the copy map.
- *  fixHint is attached only when there is something to fix (warn/fail). */
+ *  fixHint is attached only when there is something to fix (warn/fail).
+ *
+ *  `fixHint` in opts OVERRIDES the copy-map default. The static copy asserts one
+ *  cause per check id, which is right for a definitive signal (a 451 IS a geo
+ *  block) but wrong when the same id fires on an inference: a reachability warn
+ *  sent the operator hunting a firewall that was never the problem (issue #265).
+ *  Callers that know the status was inferred pass a hint that describes the
+ *  possibilities instead of asserting one. */
 export declare function makeReadinessCheck(id: ReadinessCheckId, status: ReadinessStatus, opts?: {
     detail?: string;
     checkedAt?: number;
+    fixHint?: string;
 }): ReadinessCheck;
 /** Worst status across the checks: fail > warn > unknown > pass. An all-unknown
  *  (or empty) set is 'unknown', so a report that couldn't run anything doesn't