@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/ingest/position-decisions-client.d.ts

@@ -0,0 +1,327 @@
+export interface PositionDecisionsClientOptions {
+    baseUrl: string;
+    ingestToken: string;
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+    maxAttempts?: number;
+    baseBackoffMs?: number;
+    backoffCapMs?: number;
+}
+export interface PositionUpsertPayload {
+    symbol: string;
+    positionOpenAt: number;
+    side: 'long' | 'short';
+    currentSize: number;
+    avgEntryPrice: number;
+    /** Trading mode the position was opened in ('paper' | 'live'). Tags the
+     *  journal row so paper and live positions can be segregated. Omitted only
+     *  if the active adapter can't be resolved (treated as legacy/NULL). */
+    mode?: 'paper' | 'live';
+    /** Venue the position was opened on ('binance' | 'hyperliquid') — journal /
+     *  analytics segmentation (fees + funding cadence differ per venue).
+     *  Absent → NULL (legacy binance), mirroring `mode`. Migration 0058. */
+    exchange?: string;
+}
+export interface PositionEntryPayload {
+    positionId: string;
+    entryAt: number;
+    isScaleIn?: boolean;
+    thesis: string;
+    setupType: string;
+    regime: string;
+    regimeConfidence: number;
+    scorecardVerdict: string;
+    confluenceScore: number;
+    confluenceComponents?: Record<string, unknown>;
+    fillPrice: number;
+    fillSize: number;
+    exchangeTradeId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PositionReviewPayload {
+    positionId: string;
+    reviewAt?: number;
+    verdict: 'hold' | 'add_on' | 'close_recommended';
+    thesisStatus: 'intact' | 'weakening' | 'invalidated' | 'evolving';
+    entryScore: number;
+    currentScore: number;
+    scoreDelta: number;
+    confluenceComponents: Record<string, unknown>;
+    regimeEntry: string;
+    regimeCurrent: string;
+    regimeConfidence: number;
+    rMultiple: number;
+    distanceToStopBps: number;
+    distanceToTargetBps?: number | null;
+    timeInPositionMinutes: number;
+    mfeR: number;
+    giveBackPct: number;
+    whatChanged: string;
+    invalidationTrigger: string;
+    restingBandImbalance05?: number | null;
+    cascadePulseAtReview?: 'quiet' | 'elevated' | 'active_cascade' | null;
+    coveragePctAtReview?: number | null;
+    imbalanceDeltaSinceEntry?: number | null;
+    metadata?: Record<string, unknown>;
+}
+export interface PositionClosePayload {
+    positionId: string;
+    closeAt: number;
+    closeReason: string;
+    closeAssessment: Record<string, unknown>;
+    scorecardVerdict: string;
+    confluenceScore: number;
+    regime: string;
+    regimeConfidence: number;
+    fillPrice: number;
+    fillSize: number;
+    realizedPnl: number;
+    realizedR: number;
+    mfeRAtClose: number;
+    giveBackPctAtClose: number;
+    exchangeTradeId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Row shape from GET /api/internal/positions?status=open (DB-vs-exchange
+ *  reconcile). Keyed off the DB row id so a wiped state-store can't hide it. */
+export interface OpenPositionRow {
+    id: string;
+    symbol: string;
+    side: 'long' | 'short';
+    remainingSize: number;
+    entryPrice: number;
+    openedAt: number;
+}
+export interface OpenPositionsResponse {
+    positions: OpenPositionRow[];
+}
+export interface PositionDecisionsClientHealth {
+    inFlight: number;
+    totalPosted: number;
+    totalSucceeded: number;
+    totalDroppedTerminal: number;
+    totalDroppedRetriesExhausted: number;
+}
+export interface PriorReview {
+    reviewAt: number;
+    verdict: 'hold' | 'add_on' | 'close_recommended';
+    thesisStatus: 'intact' | 'weakening' | 'invalidated' | 'evolving';
+    scoreDelta: number;
+    currentScore: number;
+    rMultiple: number;
+    regimeCurrent: string;
+    whatChanged: string;
+}
+export interface VerdictStreak {
+    verdict: 'hold' | 'add_on' | 'close_recommended';
+    consecutiveCount: number;
+    thesisProgression: ('intact' | 'weakening' | 'invalidated' | 'evolving')[];
+    truncated: boolean;
+}
+export interface ReentryContext {
+    recentOpenedCount: number;
+    recentClosedCount: number;
+    recentClosedRealizedR: number[];
+    minutesSinceLastClose: number | null;
+}
+export interface PositionReviewContext {
+    positionId: string;
+    symbol: string;
+    side: 'long' | 'short';
+    openedAt: number;
+    reviews: PriorReview[];
+    verdictStreak: VerdictStreak | null;
+    reentryContext: ReentryContext | null;
+}
+export interface RecentReviewsResponse {
+    positions: PositionReviewContext[];
+}
+export interface ReviewOutcomesFilters {
+    verdict?: 'hold' | 'add_on' | 'close_recommended';
+    thesisStatus?: 'intact' | 'weakening' | 'invalidated' | 'evolving';
+    regimeCurrent?: string;
+    symbol?: string;
+    side?: 'long' | 'short';
+    setupType?: string;
+    daysBack?: number;
+    minScoreDelta?: number;
+    maxScoreDelta?: number;
+    closedOnly?: boolean;
+    sampleLimit?: number;
+}
+export interface ReviewOutcomesStats {
+    nTotal: number;
+    nClosed: number;
+    winRate: number | null;
+    medianR: number | null;
+    meanR: number | null;
+    medianGiveBack: number | null;
+    p25R: number | null;
+    p75R: number | null;
+    outcomeCounts: Record<string, number>;
+}
+export interface ReviewOutcomeSample {
+    reviewId: string;
+    positionId: string;
+    reviewAt: string;
+    symbol: string;
+    side: 'long' | 'short';
+    verdict: string;
+    thesisStatus: string;
+    regimeCurrent: string;
+    setupType: string | null;
+    scoreDelta: number;
+    rAtReview: number;
+    mfeAtReview: number;
+    whatChanged: string;
+    positionStatus: 'open' | 'closed';
+    closeAt: string | null;
+    finalRealizedR: number | null;
+    finalCloseReason: string | null;
+    minutesReviewToClose: number | null;
+}
+export interface ReviewOutcomesResponse {
+    filters: Record<string, unknown>;
+    stats: ReviewOutcomesStats;
+    sample: ReviewOutcomeSample[];
+}
+export interface RelevantLearning {
+    id: string;
+    title: string;
+    directive: string;
+    triggerCondition: Record<string, unknown> | null;
+    evidence: Record<string, unknown> | null;
+    lastValidatedAt: string | null;
+    updatedAt: string;
+}
+export interface RelevantLearningsResponse {
+    learnings: RelevantLearning[];
+    appliesAt: 'entry' | 'heartbeat' | 'close';
+    totalCandidates: number;
+    returnedCount: number;
+}
+export interface RelevantLearningsFilters {
+    appliesAt: 'entry' | 'heartbeat' | 'close';
+    setupType?: string;
+    regime?: string;
+    verdict?: 'hold' | 'add_on' | 'close_recommended';
+}
+export interface MyMinedPattern {
+    id: string;
+    patternType: string;
+    matchConditions: Record<string, unknown>;
+    sampleSize: number;
+    baselineValue: number | null;
+    observedValue: number | null;
+    effectSize: number;
+    pValue: number;
+    humanSummary: string;
+    minedAt: string;
+    dateRangeEnd: string | null;
+    promotedToLearningId: string | null;
+}
+export interface MyMinedPatternsResponse {
+    patterns: MyMinedPattern[];
+    totalReturned: number;
+}
+export interface MyMinedPatternsFilters {
+    withinDays?: number;
+    minSampleSize?: number;
+    maxPValue?: number;
+    includePromoted?: boolean;
+}
+export interface MyProposedLearning {
+    id: string;
+    confidence: 'hypothesis' | 'confirmed' | 'retired';
+    appliesAt: 'entry' | 'heartbeat' | 'close';
+    title: string;
+    directive: string;
+    triggerCondition: Record<string, unknown> | null;
+    evidence: Record<string, unknown> | null;
+    sourceMinedPatternId: string | null;
+    proposedBy: 'operator' | 'agent';
+    autoConfirmed: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MyProposedLearningsResponse {
+    learnings: MyProposedLearning[];
+    totalReturned: number;
+}
+export interface MyProposedLearningsFilters {
+    includeHypothesis?: boolean;
+    includeConfirmed?: boolean;
+    includeRetired?: boolean;
+    proposedBy?: 'agent' | 'operator';
+}
+export interface ProposeLearningPayload {
+    appliesAt: 'entry' | 'heartbeat' | 'close';
+    title: string;
+    directive: string;
+    sourceMinedPatternId?: string;
+    triggerCondition?: Record<string, unknown>;
+    evidence?: Record<string, unknown>;
+}
+export interface ProposeLearningResponse {
+    id: string;
+    confidence: 'hypothesis' | 'confirmed';
+    autoConfirmed: boolean;
+    trustMode: 'manual' | 'auto';
+    proposalsUsed: number;
+    proposalsLimit: number;
+}
+export declare class PositionDecisionsClient {
+    private readonly opts;
+    private inFlight;
+    private totalPosted;
+    private totalSucceeded;
+    private totalDroppedTerminal;
+    private totalDroppedRetriesExhausted;
+    constructor(options: PositionDecisionsClientOptions);
+    /** Awaited — the auto-capture pipeline needs the returned positionId before
+     *  posting children. Returns null on terminal failure (caller logs + drops). */
+    postPosition(userId: string, payload: PositionUpsertPayload): Promise<string | null>;
+    /** Fire-and-forget. */
+    postEntry(userId: string, payload: PositionEntryPayload): void;
+    /** Fire-and-forget. */
+    postReview(userId: string, payload: PositionReviewPayload): void;
+    /** Fire-and-forget. */
+    postClose(userId: string, payload: PositionClosePayload): void;
+    /** DB-vs-exchange reconcile read: this tenant's open positions. Awaited.
+     *  Returns null on terminal/retry-exhausted failure — the caller MUST treat
+     *  null as UNKNOWN (never as "no open rows"), else a failed fetch would
+     *  false-close the whole book. Pass `mode` to scope the read to the ACTIVE
+     *  book (paper strict / live incl. legacy NULL rows) and `exchange` to scope
+     *  it to the ACTIVE venue (hyperliquid strict / binance incl. legacy NULL
+     *  rows) — the sweep diffs against one adapter's snapshot, so an unscoped
+     *  read misreads the inactive book's/venue's rows as orphans (issue #209
+     *  item 5: the same corruption class on the venue axis). */
+    getOpenPositions(userId: string, mode?: 'paper' | 'live', exchange?: 'binance' | 'hyperliquid'): Promise<OpenPositionsResponse | null>;
+    /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
+     *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
+    getRecentReviews(userId: string, positionIds: string[], reviewLimit?: number): Promise<RecentReviewsResponse | null>;
+    /** Phase 2 outcome-attribution read. Aggregate stats + sample over the
+     *  position_review_outcomes view filtered by the provided criteria. */
+    queryReviewOutcomes(userId: string, filters: ReviewOutcomesFilters): Promise<ReviewOutcomesResponse | null>;
+    /** Phase 4 — curated learnings read. The agent calls this at decision
+     *  time (entry/heartbeat/close) to fetch confirmed learnings whose
+     *  trigger_condition matches the current decision context. Returns null
+     *  on terminal/retry-exhausted failure (caller logs + degrades to empty). */
+    getRelevantLearnings(userId: string, filters: RelevantLearningsFilters): Promise<RelevantLearningsResponse | null>;
+    /** Phase 4.5 — agent self-assessment: read this user's own unpromoted
+     *  mined_patterns so the agent can pick candidates to propose. */
+    getMyMinedPatterns(userId: string, filters: MyMinedPatternsFilters): Promise<MyMinedPatternsResponse | null>;
+    /** Phase 4.5 — read this user's own learnings across confidence states, so
+     *  the agent can dedup before proposing a fresh hypothesis. */
+    getMyProposedLearnings(userId: string, filters: MyProposedLearningsFilters): Promise<MyProposedLearningsResponse | null>;
+    /** Phase 4.5 — POST a new hypothesis (or auto-confirmed) learning. Confidence
+     *  is server-determined by user trust mode; we cannot set it from here. */
+    proposeLearning(userId: string, payload: ProposeLearningPayload): Promise<ProposeLearningResponse | null>;
+    drain(): Promise<void>;
+    getHealth(): PositionDecisionsClientHealth;
+    private fireAndForget;
+    private run;
+    private runReturning;
+    private runGetReturning;
+    private sleepBackoff;
+}

package/assets/plugin/ingest/position-decisions-client.js

@@ -0,0 +1,306 @@
+// HTTP client for the webapp's /api/internal/position-{positions,entries,reviews,closes}
+// ingest endpoints.
+//
+// Mirrors trade-store-client.ts retry semantics:
+//   - 2xx              : success.
+//   - 4xx              : terminal — drop + log loudly (caller bug or duplicate).
+//   - 5xx / network    : retry with exponential backoff up to maxAttempts.
+//
+// Two callable surfaces:
+//   - postPosition()  is awaited (returns the parent UUID); the auto-capture
+//                      pipeline needs the id before posting children.
+//   - postEntry/Review/Close are fire-and-forget (don't block the WS hot path).
+//
+// All four routes accept the same auth: Bearer + X-User-Id headers.
+import { logger, formatError } from '../logger.js';
+const TAG = 'position-decisions-client';
+export class PositionDecisionsClient {
+    opts;
+    inFlight = new Set();
+    totalPosted = 0;
+    totalSucceeded = 0;
+    totalDroppedTerminal = 0;
+    totalDroppedRetriesExhausted = 0;
+    constructor(options) {
+        this.opts = {
+            baseUrl: options.baseUrl.replace(/\/+$/, ''),
+            ingestToken: options.ingestToken,
+            fetchImpl: options.fetchImpl ?? fetch,
+            requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+            maxAttempts: options.maxAttempts ?? 4,
+            baseBackoffMs: options.baseBackoffMs ?? 250,
+            backoffCapMs: options.backoffCapMs ?? 5_000,
+        };
+    }
+    /** Awaited — the auto-capture pipeline needs the returned positionId before
+     *  posting children. Returns null on terminal failure (caller logs + drops). */
+    async postPosition(userId, payload) {
+        const result = await this.runReturning(userId, '/api/internal/positions', payload);
+        return result?.positionId ?? null;
+    }
+    /** Fire-and-forget. */
+    postEntry(userId, payload) {
+        this.fireAndForget(userId, '/api/internal/position-entries', payload);
+    }
+    /** Fire-and-forget. */
+    postReview(userId, payload) {
+        this.fireAndForget(userId, '/api/internal/position-reviews', payload);
+    }
+    /** Fire-and-forget. */
+    postClose(userId, payload) {
+        this.fireAndForget(userId, '/api/internal/position-closes', payload);
+    }
+    /** DB-vs-exchange reconcile read: this tenant's open positions. Awaited.
+     *  Returns null on terminal/retry-exhausted failure — the caller MUST treat
+     *  null as UNKNOWN (never as "no open rows"), else a failed fetch would
+     *  false-close the whole book. Pass `mode` to scope the read to the ACTIVE
+     *  book (paper strict / live incl. legacy NULL rows) and `exchange` to scope
+     *  it to the ACTIVE venue (hyperliquid strict / binance incl. legacy NULL
+     *  rows) — the sweep diffs against one adapter's snapshot, so an unscoped
+     *  read misreads the inactive book's/venue's rows as orphans (issue #209
+     *  item 5: the same corruption class on the venue axis). */
+    async getOpenPositions(userId, mode, exchange) {
+        const qs = new URLSearchParams({ status: 'open' });
+        if (mode)
+            qs.set('mode', mode);
+        if (exchange)
+            qs.set('exchange', exchange);
+        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`);
+    }
+    /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
+     *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
+    async getRecentReviews(userId, positionIds, reviewLimit) {
+        if (positionIds.length === 0)
+            return { positions: [] };
+        const qs = new URLSearchParams();
+        qs.set('positionIds', positionIds.join(','));
+        if (reviewLimit && reviewLimit > 0)
+            qs.set('reviewLimit', String(reviewLimit));
+        const path = `/api/internal/position-reviews/recent?${qs.toString()}`;
+        return this.runGetReturning(userId, path);
+    }
+    /** Phase 2 outcome-attribution read. Aggregate stats + sample over the
+     *  position_review_outcomes view filtered by the provided criteria. */
+    async queryReviewOutcomes(userId, filters) {
+        const qs = new URLSearchParams();
+        if (filters.verdict)
+            qs.set('verdict', filters.verdict);
+        if (filters.thesisStatus)
+            qs.set('thesis_status', filters.thesisStatus);
+        if (filters.regimeCurrent)
+            qs.set('regime_current', filters.regimeCurrent);
+        if (filters.symbol)
+            qs.set('symbol', filters.symbol);
+        if (filters.side)
+            qs.set('side', filters.side);
+        if (filters.setupType)
+            qs.set('setup_type', filters.setupType);
+        if (filters.daysBack !== undefined)
+            qs.set('days_back', String(filters.daysBack));
+        if (filters.minScoreDelta !== undefined) {
+            qs.set('min_score_delta', String(filters.minScoreDelta));
+        }
+        if (filters.maxScoreDelta !== undefined) {
+            qs.set('max_score_delta', String(filters.maxScoreDelta));
+        }
+        if (filters.closedOnly)
+            qs.set('closed_only', '1');
+        if (filters.sampleLimit !== undefined)
+            qs.set('sample_limit', String(filters.sampleLimit));
+        const path = `/api/internal/positions/reviews/with-outcomes${qs.toString() ? `?${qs.toString()}` : ''}`;
+        return this.runGetReturning(userId, path);
+    }
+    /** Phase 4 — curated learnings read. The agent calls this at decision
+     *  time (entry/heartbeat/close) to fetch confirmed learnings whose
+     *  trigger_condition matches the current decision context. Returns null
+     *  on terminal/retry-exhausted failure (caller logs + degrades to empty). */
+    async getRelevantLearnings(userId, filters) {
+        const qs = new URLSearchParams();
+        qs.set('applies_at', filters.appliesAt);
+        if (filters.setupType)
+            qs.set('setup_type', filters.setupType);
+        if (filters.regime)
+            qs.set('regime', filters.regime);
+        if (filters.verdict)
+            qs.set('verdict', filters.verdict);
+        const path = `/api/internal/learnings?${qs.toString()}`;
+        return this.runGetReturning(userId, path);
+    }
+    /** Phase 4.5 — agent self-assessment: read this user's own unpromoted
+     *  mined_patterns so the agent can pick candidates to propose. */
+    async getMyMinedPatterns(userId, filters) {
+        const qs = new URLSearchParams();
+        if (filters.withinDays !== undefined)
+            qs.set('within_days', String(filters.withinDays));
+        if (filters.minSampleSize !== undefined)
+            qs.set('min_sample_size', String(filters.minSampleSize));
+        if (filters.maxPValue !== undefined)
+            qs.set('max_p_value', String(filters.maxPValue));
+        if (filters.includePromoted)
+            qs.set('include_promoted', '1');
+        const q = qs.toString();
+        const path = `/api/internal/learnings/my-patterns${q ? `?${q}` : ''}`;
+        return this.runGetReturning(userId, path);
+    }
+    /** Phase 4.5 — read this user's own learnings across confidence states, so
+     *  the agent can dedup before proposing a fresh hypothesis. */
+    async getMyProposedLearnings(userId, filters) {
+        const qs = new URLSearchParams();
+        if (filters.includeHypothesis === false)
+            qs.set('include_hypothesis', '0');
+        if (filters.includeConfirmed === false)
+            qs.set('include_confirmed', '0');
+        if (filters.includeRetired)
+            qs.set('include_retired', '1');
+        if (filters.proposedBy)
+            qs.set('proposed_by', filters.proposedBy);
+        const q = qs.toString();
+        const path = `/api/internal/learnings/my-proposals${q ? `?${q}` : ''}`;
+        return this.runGetReturning(userId, path);
+    }
+    /** Phase 4.5 — POST a new hypothesis (or auto-confirmed) learning. Confidence
+     *  is server-determined by user trust mode; we cannot set it from here. */
+    async proposeLearning(userId, payload) {
+        return this.runReturning(userId, '/api/internal/learnings/propose', payload);
+    }
+    async drain() {
+        if (this.inFlight.size === 0)
+            return;
+        logger.info(TAG, `Draining ${this.inFlight.size} in-flight decision post(s)...`);
+        await Promise.allSettled(Array.from(this.inFlight));
+    }
+    getHealth() {
+        return {
+            inFlight: this.inFlight.size,
+            totalPosted: this.totalPosted,
+            totalSucceeded: this.totalSucceeded,
+            totalDroppedTerminal: this.totalDroppedTerminal,
+            totalDroppedRetriesExhausted: this.totalDroppedRetriesExhausted,
+        };
+    }
+    // ---- Internals ----
+    fireAndForget(userId, path, body) {
+        this.totalPosted++;
+        const promise = this.run(userId, path, body).finally(() => {
+            this.inFlight.delete(promise);
+        });
+        this.inFlight.add(promise);
+    }
+    async run(userId, path, body) {
+        await this.runReturning(userId, path, body);
+    }
+    async runReturning(userId, path, body) {
+        const url = `${this.opts.baseUrl}${path}`;
+        const json = JSON.stringify(body);
+        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+            try {
+                const ac = new AbortController();
+                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                let res;
+                try {
+                    res = await this.opts.fetchImpl(url, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${this.opts.ingestToken}`,
+                            'x-user-id': userId,
+                        },
+                        body: json,
+                        signal: ac.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(tid);
+                }
+                if (res.status >= 200 && res.status < 300) {
+                    this.totalSucceeded++;
+                    try {
+                        return (await res.json());
+                    }
+                    catch {
+                        return null;
+                    }
+                }
+                if (res.status >= 400 && res.status < 500) {
+                    this.totalDroppedTerminal++;
+                    let errBody = '';
+                    try {
+                        errBody = await res.text();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    logger.warn(TAG, `POST ${url} → ${res.status} (terminal, dropped). userId=${userId} body=${errBody.slice(0, 200)}`);
+                    return null;
+                }
+                logger.warn(TAG, `POST ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+            }
+            catch (err) {
+                logger.warn(TAG, `POST ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+            }
+            if (attempt < this.opts.maxAttempts) {
+                await this.sleepBackoff(attempt);
+            }
+        }
+        this.totalDroppedRetriesExhausted++;
+        logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
+        return null;
+    }
+    async runGetReturning(userId, path) {
+        const url = `${this.opts.baseUrl}${path}`;
+        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+            try {
+                const ac = new AbortController();
+                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                let res;
+                try {
+                    res = await this.opts.fetchImpl(url, {
+                        method: 'GET',
+                        headers: {
+                            authorization: `Bearer ${this.opts.ingestToken}`,
+                            'x-user-id': userId,
+                        },
+                        signal: ac.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(tid);
+                }
+                if (res.status >= 200 && res.status < 300) {
+                    try {
+                        return (await res.json());
+                    }
+                    catch {
+                        return null;
+                    }
+                }
+                if (res.status >= 400 && res.status < 500) {
+                    let errBody = '';
+                    try {
+                        errBody = await res.text();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    logger.warn(TAG, `GET ${url} → ${res.status} (terminal, dropped). userId=${userId} body=${errBody.slice(0, 200)}`);
+                    return null;
+                }
+                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+            }
+            catch (err) {
+                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+            }
+            if (attempt < this.opts.maxAttempts) {
+                await this.sleepBackoff(attempt);
+            }
+        }
+        logger.error(TAG, `GET ${url} failed after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
+        return null;
+    }
+    async sleepBackoff(attempt) {
+        const exp = Math.min(this.opts.baseBackoffMs * 2 ** (attempt - 1), this.opts.backoffCapMs);
+        const jitter = exp * 0.2 * (Math.random() * 2 - 1);
+        const delay = Math.max(0, Math.round(exp + jitter));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}

package/assets/plugin/ingest/readiness-reporter.d.ts

@@ -0,0 +1,42 @@
+import { type ReadinessReport, type VenueId } from '@reefclaw/shared';
+/** Venue-agnostic reachability probe — BinancePublicApi.probeReachability and
+ *  HyperliquidPublicApi.probeReachability both return exactly this shape. */
+export interface VenueReachabilityProbe {
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
+}
+export interface ReadinessReporterOptions {
+    apiBaseUrl: string;
+    token: string;
+    /** Which venue this agent trades — decides the reachability check id
+     *  (binance_reachable vs hyperliquid_reachable) and which host `publicApi`
+     *  probes. The reporter probes ONLY the configured venue: on a
+     *  Binance-451-blocked host trading Hyperliquid, a Binance probe would be
+     *  a permanent false alarm (plan §5.11). */
+    venue: VenueId;
+    /** Public API of the CONFIGURED venue (probe only). */
+    publicApi: VenueReachabilityProbe;
+    /** Number of trading tools registered (a health signal). */
+    toolCount: number;
+    fetchImpl?: typeof fetch;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+}
+/** Run every connect-phase check once and assemble the report. Exported for
+ *  unit tests.
+ *
+ *  `bootWarmup` marks the FIRST cycle, which fires during gateway boot while
+ *  the event loop is congested (WS start, snapshot, seed all racing). That
+ *  delay between the probe's server-time response and the local `Date.now()`
+ *  read inflates the apparent clock drift — observed −4112ms at boot
+ *  self-correcting to −108ms on the next 5-min cycle. During warm-up a
+ *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
+ *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
+ *  skewed clock still surfaces on cycle 2. */
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount'>, bootWarmup?: boolean): Promise<ReadinessReport>;
+/** Test-only — reset the singleton guard between unit tests. */
+export declare function __resetReadinessReporterForTests(): void;
+/** Fire the readiness report once at boot then on an unref'd interval. */
+export declare function startReadinessReporter(opts: ReadinessReporterOptions): void;