@reefclaw/openclaw-plugin 0.1.1 → 0.1.3

package/config/entitlement-gate.js

@@ -0,0 +1,137 @@
+// EntitlementGate — the plugin-side enforcement point for account-level
+// (billing) restrictions: when the server-resolved entitlement says the user
+// has no paid access (trial expired past its end, subscription lapsed past
+// the 7-day grace), NEW ENTRIES pause. Everything else keeps working.
+//
+// ★ SAFETY ANALYSIS (why this can never add risk to an existing book):
+// the gate blocks ONLY the names in ENTITLEMENT_GATED_TOOLS — today exactly
+// `create_order`, the one tool that ADDS risk and the one thing our servers
+// cannot 403 (it goes plugin → Binance directly). Every risk-REDUCING and
+// safety path (close_position, modify_stop, attach_brackets,
+// audit_bracket_protection, record_position_reviews, the operator-control
+// tools, kill/flatten/pause via the skill) is untouched by construction: it
+// is not in the gated set, and a pin test asserts the set can never grow into
+// the safety floor. This mirrors what an auto-pause on loss limits already
+// does (no new entries, existing positions fully manageable) — an operation
+// the product already considers safe.
+//
+// ★ THREAT MODEL HONESTY: the plugin runs on the trader's own hardware, so
+// this gate is the COURTESY layer — it makes the agent stop cleanly with an
+// actionable message instead of burning failed calls. The HARD enforcement is
+// server-side: webapp Pro routes and the intelligence API both 403 on
+// paidAccess=false, which removes the data the agent trades on.
+//
+// Fail direction: no entitlement data (older webapp, outage, garbage payload,
+// no token) → ALLOW. Billing enforcement must never brick a paying customer
+// because our config channel hiccuped; last-known-good semantics come from
+// the agent-config cache like every other centrally-delivered value.
+//
+// Kill-switch: RC_ENTITLEMENT_GATE=off (never blocks) | shadow (log-only)
+// | default enforce — same convention as RC_TOOL_GATE / RC_CENTRAL_GATES.
+import { logger } from '../logger.js';
+const TAG = 'entitlement-gate';
+/** The ONLY tools an expired entitlement may pause. Deliberately a denylist
+ *  (not "everything except safety"): a tool added tomorrow is un-gated by
+ *  default, which is the conservative failure mode in a trading product.
+ *  Intel/data tools are NOT here — the intelligence service and webapp 403
+ *  those server-side with the same actionable message. */
+export const ENTITLEMENT_GATED_TOOLS = new Set(['create_order']);
+export function resolveEntitlementGateMode() {
+    const raw = (process.env.RC_ENTITLEMENT_GATE ?? '').toLowerCase();
+    if (raw === 'off')
+        return 'off';
+    if (raw === 'shadow')
+        return 'shadow';
+    return 'enforce';
+}
+/** Structured, agent-visible result for a blocked call. Worded so the agent
+ *  stops cleanly (no retry loop), keeps managing the existing book, and tells
+ *  the operator exactly how to restore service. */
+export function entitlementBlockedResult(name) {
+    return {
+        ok: false,
+        error: 'entitlement_expired',
+        tool: name,
+        message: `New entries are paused: the ReefClaw subscription for this connection has expired ` +
+            `(trial ended or payment lapsed). Do not retry this call. Existing positions remain fully ` +
+            `manageable — close_position, modify_stop, attach_brackets, and all emergency/operator ` +
+            `controls work normally, and protective brackets stay enforced by the exchange. ` +
+            `Tell your operator to renew at https://reefclaw.com (Settings → Billing) to resume trading.`,
+    };
+}
+export class EntitlementGate {
+    mode;
+    entitlement;
+    /** Avoids log spam: one line per state transition, not per blocked call. */
+    lastLoggedKey = '';
+    constructor(mode = resolveEntitlementGateMode()) {
+        this.mode = mode;
+        if (mode !== 'enforce')
+            logger.info(TAG, `mode=${mode}`);
+    }
+    getMode() {
+        return this.mode;
+    }
+    getEntitlement() {
+        return this.entitlement;
+    }
+    /** Apply the entitlement slice of a validated config (poller path).
+     *  `undefined` (server omitted it / validation dropped it) CLEARS the held
+     *  verdict — the gate then fails open rather than enforcing a stale one
+     *  the server no longer asserts. */
+    apply(entitlement) {
+        const key = entitlement ? `${entitlement.state}:${entitlement.paidAccess}` : '(none)';
+        if (key !== this.lastLoggedKey) {
+            this.lastLoggedKey = key;
+            logger.info(TAG, entitlement
+                ? `entitlement: state=${entitlement.state} paidAccess=${entitlement.paidAccess}` +
+                    (entitlement.graceUntil ? ` graceUntil=${entitlement.graceUntil}` : '')
+                : 'entitlement: no server verdict — gate inactive (fail-open)');
+        }
+        this.entitlement = entitlement;
+    }
+    /** Should this call be blocked? Non-gated names short-circuit FIRST (the
+     *  safety set can never be touched, in any mode, with any payload); then
+     *  only an explicit server verdict of paidAccess=false blocks. */
+    isBlocked(name) {
+        if (this.mode === 'off')
+            return false;
+        if (!ENTITLEMENT_GATED_TOOLS.has(name))
+            return false;
+        if (!this.entitlement)
+            return false; // unknown → allow
+        if (this.entitlement.paidAccess !== false)
+            return false;
+        if (this.mode === 'shadow') {
+            logger.info(TAG, `SHADOW: would block ${name} (state=${this.entitlement.state})`);
+            return false;
+        }
+        return true;
+    }
+    /** Wrap a tool's execute with the gate check — same hot-apply pattern as
+     *  ToolGate.wrapTool (state is consulted per call, not at registration). */
+    wrapTool(tool, jsonResult) {
+        if (!ENTITLEMENT_GATED_TOOLS.has(tool.name))
+            return tool;
+        const originalExecute = tool.execute.bind(tool);
+        return {
+            ...tool,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            execute: (...args) => {
+                if (this.isBlocked(tool.name)) {
+                    logger.info(TAG, `blocked ${tool.name} (entitlement state=${this.entitlement?.state ?? 'unknown'})`);
+                    return Promise.resolve(jsonResult(entitlementBlockedResult(tool.name)));
+                }
+                return originalExecute(...args);
+            },
+        };
+    }
+    /** Test-only. */
+    __reset() {
+        this.entitlement = undefined;
+        this.lastLoggedKey = '';
+    }
+}
+/** Module singleton — one gate per plugin process, shared by the poller
+ *  (writer) and the tool-wrap in index.ts (consumer), mirroring gateStore. */
+export const entitlementGate = new EntitlementGate();

package/index.js

@@ -29,6 +29,7 @@ import { PositionStateStore } from './live/position-state-store.js';
 import { PendingEntryStore } from './ingest/pending-entry-metadata.js';
 import { onReconcilerObservedClose, reconcileStateStoreOnStartup } from './ingest/reconciler-cleanup.js';
 import { reconcileDbOpenVsExchange } from './ingest/reconcile-db-vs-exchange.js';
+import { startReadinessReporter } from './ingest/readiness-reporter.js';
 import { IntelMicrostructureAssembler } from './live/microstructure-assembler.js';
 import { recordPositionReviewsTool } from './tools/record-position-reviews.js';
 import { getMyRecentReviewsTool } from './tools/get-my-recent-reviews.js';
@@ -43,6 +44,7 @@ import { readPluginConfig, readOpenClawConnection } from './config/plugin-config
 import { startConnectorSupervisor, hasBundledBridge } from './connector-supervisor.js';
 import { ToolGate } from './config/tool-gate.js';
 import { gateStore } from './config/gate-store.js';
+import { entitlementGate } from './config/entitlement-gate.js';
 import { startAgentConfigPoller } from './config/agent-config-poller.js';
 import { PositionWatcher } from './live/stop-watcher.js';
 import { PaperMarketFeed } from './simulator/paper-market-feed.js';
@@ -1273,31 +1275,39 @@ const paperTradingPlugin = {
                         // weight). getPositionsOrNull() returns null on a failed/weight-paced
                         // fetch; getPositions() would collapse that to [] (null≠empty trap).
                         const trusted = await liveAdapter.getPositionsOrNull();
-                        const positions = trusted ?? [];
-                        await reconcileStateStoreOnStartup({
-                            decisionsClient: positionDecisionsClient,
-                            stateStore: positionStateStore,
-                            userId: positionDecisionsUserId,
-                            lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
-                        }, positions.map((p) => p.symbol));
-                        // Seed remaining-contracts for positions still open on the exchange
-                        // so the reduce-only-fill close handler can detect flat for entries
-                        // that opened before this plugin instance started (or before the
-                        // size-tracking field existed). seedRemainingContracts never clobbers
-                        // live fill-tracked state.
-                        for (const p of positions) {
-                            const contracts = Math.abs(Number(p.contracts));
-                            if (Number.isFinite(contracts) && contracts > 0) {
-                                positionStateStore.seedRemainingContracts(p.symbol, contracts);
-                            }
-                        }
-                        // DB-authoritative orphan close: close webapp `positions` rows that
-                        // are status='open' but absent from the exchange (closed on-exchange
-                        // while down / state-store wiped). ONLY on a TRUSTED snapshot — a
-                        // null (failed) fetch must never be read as "flat" and close the book.
                         if (trusted !== null) {
+                            // State-store sweep ONLY on a TRUSTED snapshot: this call treats
+                            // every state-store symbol absent from the list as closed and
+                            // removes it (incl. its webappPositionId journal linkage), so
+                            // collapsing a null (failed) fetch to [] would wipe the store
+                            // for every open position on a transient boot-time 429/paced
+                            // read — the null≠empty trap, with no self-healing retry.
+                            await reconcileStateStoreOnStartup({
+                                decisionsClient: positionDecisionsClient,
+                                stateStore: positionStateStore,
+                                userId: positionDecisionsUserId,
+                                lastPriceFn: (sym) => liveAdapter.getLastPrice(sym),
+                            }, trusted.map((p) => p.symbol));
+                            // Seed remaining-contracts for positions still open on the exchange
+                            // so the reduce-only-fill close handler can detect flat for entries
+                            // that opened before this plugin instance started (or before the
+                            // size-tracking field existed). seedRemainingContracts never clobbers
+                            // live fill-tracked state.
+                            for (const p of trusted) {
+                                const contracts = Math.abs(Number(p.contracts));
+                                if (Number.isFinite(contracts) && contracts > 0) {
+                                    positionStateStore.seedRemainingContracts(p.symbol, contracts);
+                                }
+                            }
+                            // DB-authoritative orphan close: close webapp `positions` rows that
+                            // are status='open' but absent from the exchange (closed on-exchange
+                            // while down / state-store wiped). Same trusted-snapshot-only rule —
+                            // a null fetch must never be read as "flat" and close the book.
                             await reconcileDbOpenVsExchange({ decisionsClient: positionDecisionsClient, userId: positionDecisionsUserId }, trusted.map((p) => p.symbol));
                         }
+                        else {
+                            logger.warn(TAG, 'Startup reconciliation skipped — positions fetch untrusted (null); state-store left untouched. Runtime drift_detected + periodic reconcilers cover the gap.');
+                        }
                     }
                     catch (err) {
                         logger.warn(TAG, `Startup state-store reconciliation failed: ${formatError(err)}`);
@@ -1958,7 +1968,13 @@ const paperTradingPlugin = {
         // config blob can never strip close_position/attach_brackets/etc.
         // Kill-switch: RC_TOOL_GATE=off. See docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5f.
         const toolGate = new ToolGate();
-        const gatedTools = tools.map((t) => toolGate.wrapTool(t, jsonResult));
+        // Entitlement gate (account-level enforcement): wraps OUTSIDE the
+        // ToolGate so an expired subscription's message wins over an operator
+        // OFF-list message. It touches ONLY ENTITLEMENT_GATED_TOOLS (exactly
+        // create_order — new risk); closes/stops/brackets/emergency are not in
+        // the set by construction. No server verdict → fail-open. Kill-switch:
+        // RC_ENTITLEMENT_GATE=off. See config/entitlement-gate.ts.
+        const gatedTools = tools.map((t) => entitlementGate.wrapTool(toolGate.wrapTool(t, jsonResult), jsonResult));
         // Poll the central config (boot + every ~60s), keyed by the same rc_
         // token the ingest paths use (plugin-config connectionToken →
         // WEBAPP_INGEST_TOKEN env fallback). No token → poller no-ops → gate
@@ -1966,9 +1982,11 @@ const paperTradingPlugin = {
         // gateStore carries centrally-delivered operational gates (slice 2:
         // exitGate) — loadExitGateMode() consults it before the local file;
         // kill-switch RC_CENTRAL_GATES=off. See config/gate-store.ts.
+        // entitlementGate receives the server-resolved billing verdict.
         startAgentConfigPoller({
             gate: toolGate,
             gateStore,
+            entitlementGate,
             apiBaseUrl,
             token: resolveIngestToken({ connectionToken }),
         });
@@ -2003,6 +2021,19 @@ const paperTradingPlugin = {
         pluginToolNames = toolNames;
         pluginInitialised = true;
         logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
+        // Agent-readiness reporter (docs/AGENT_READINESS_GATE_PLAN.md Phase 1):
+        // probe host→Binance reachability (HTTP 451 geo-block) + clock drift on the
+        // host and POST a plain-English report to the webapp, so a silently-broken
+        // agent shows an actionable dashboard alert instead of a false green.
+        // Advisory + fire-and-forget; no token → no-op. Runs here once (guarded by
+        // the pluginInitialised early-return → once per process) + on an unref'd
+        // interval inside the reporter.
+        startReadinessReporter({
+            apiBaseUrl,
+            token: resolveIngestToken({ connectionToken }),
+            binanceApi,
+            toolCount: toolNames.length,
+        });
         maybeStartConnectorSupervisor();
     },
 };

package/ingest/pending-entry-metadata.d.ts

@@ -1,7 +1,13 @@
 import type { PositionMetadata } from '../simulator/types.js';
 export interface PendingEntry {
-    /** Exchange-issued orderId — the lookup key when the WS fill arrives. */
+    /** Primary lookup key. Initially the client order id (the stash happens
+     *  BEFORE submission, when no exchange orderId exists yet); promote()
+     *  re-keys it to the exchange-issued orderId once the REST ack returns. */
     orderId: string;
+    /** Client order id (idempotency key) — secondary lookup key. The WS
+     *  ORDER_TRADE_UPDATE carries it (`o.c`), so a fill that arrives BEFORE
+     *  the REST response (routine for market orders) still finds the stash. */
+    clientOrderId?: string;
     /** Canonical (un-suffixed) symbol. */
     symbol: string;
     /** Side the agent intended at create_order time. */
@@ -24,25 +30,41 @@ export declare class PendingEntryStore {
     private readonly now;
     private readonly ttlMs;
     private entries;
+    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
+     *  REST ack (no exchange orderId known yet) find the stash by cid. */
+    private cidIndex;
     constructor(opts?: PendingEntryStoreOptions);
-    /** Stash metadata until the WS fill for this orderId arrives. */
+    /** Stash metadata until the WS fill for this order arrives. Keyed by
+     *  `orderId`; when `clientOrderId` is provided the entry is also findable
+     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
     put(input: {
         orderId: string;
+        clientOrderId?: string;
         symbol: string;
         side: 'buy' | 'sell';
         metadata: PositionMetadata;
     }): void;
-    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
-     *  callers should call `consume(orderId)` to remove on first match, since
-     *  multiple partial fills on the same limit order all share one orderId
-     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
-     *  registered position (state-store branch handles those). */
+    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
+     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
+     *  working. No-op when the entry is gone (already consumed by a WS fill
+     *  that beat the REST response, or expired). */
+    promote(fromKey: string, exchangeOrderId: string): void;
+    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
+     *  Does NOT remove the entry — callers should call `consume(orderId)` to
+     *  remove on first match, since multiple partial fills on the same limit
+     *  order all share one orderId and the FIRST fill is the entry; subsequent
+     *  are scale-ins of an already-registered position (state-store branch
+     *  handles those). */
     get(orderId: string): PendingEntry | undefined;
-    /** Atomic get + remove. Use this when you've already consumed the metadata
-     *  to post an entry row and don't want it picked up again. */
+    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
+     *  you've already consumed the metadata to post an entry row and don't
+     *  want it picked up again. */
     consume(orderId: string): PendingEntry | undefined;
     /** Remove an entry without retrieval (e.g. on cancel). */
     drop(orderId: string): boolean;
+    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
+    private resolveKey;
+    private deleteEntry;
     size(): number;
     getFilePath(): string;
     private pruneExpired;

package/ingest/pending-entry-metadata.js

@@ -33,6 +33,9 @@ export class PendingEntryStore {
     now;
     ttlMs;
     entries = new Map();
+    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
+     *  REST ack (no exchange orderId known yet) find the stash by cid. */
+    cidIndex = new Map();
     constructor(opts) {
         const base = resolvePluginsBaseDir(opts?.basePath);
         this.dir = join(base, opts?.pluginId ?? DEFAULT_PLUGIN_ID);
@@ -43,45 +46,91 @@ export class PendingEntryStore {
             mkdirSync(this.dir, { recursive: true });
         this.loadOrInit();
     }
-    /** Stash metadata until the WS fill for this orderId arrives. */
+    /** Stash metadata until the WS fill for this order arrives. Keyed by
+     *  `orderId`; when `clientOrderId` is provided the entry is also findable
+     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
     put(input) {
         const ts = this.now();
         this.entries.set(input.orderId, {
             orderId: input.orderId,
+            ...(input.clientOrderId ? { clientOrderId: input.clientOrderId } : {}),
             symbol: input.symbol,
             side: input.side,
             metadata: input.metadata,
             createdAt: ts,
             expiresAt: ts + this.ttlMs,
         });
+        if (input.clientOrderId)
+            this.cidIndex.set(input.clientOrderId, input.orderId);
         this.persist();
     }
-    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
-     *  callers should call `consume(orderId)` to remove on first match, since
-     *  multiple partial fills on the same limit order all share one orderId
-     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
-     *  registered position (state-store branch handles those). */
+    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
+     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
+     *  working. No-op when the entry is gone (already consumed by a WS fill
+     *  that beat the REST response, or expired). */
+    promote(fromKey, exchangeOrderId) {
+        const key = this.resolveKey(fromKey);
+        if (key === undefined || key === exchangeOrderId)
+            return;
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        entry.orderId = exchangeOrderId;
+        this.entries.set(exchangeOrderId, entry);
+        if (entry.clientOrderId)
+            this.cidIndex.set(entry.clientOrderId, exchangeOrderId);
+        this.persist();
+    }
+    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
+     *  Does NOT remove the entry — callers should call `consume(orderId)` to
+     *  remove on first match, since multiple partial fills on the same limit
+     *  order all share one orderId and the FIRST fill is the entry; subsequent
+     *  are scale-ins of an already-registered position (state-store branch
+     *  handles those). */
     get(orderId) {
         this.pruneExpired();
-        return this.entries.get(orderId);
+        const key = this.resolveKey(orderId);
+        return key === undefined ? undefined : this.entries.get(key);
     }
-    /** Atomic get + remove. Use this when you've already consumed the metadata
-     *  to post an entry row and don't want it picked up again. */
+    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
+     *  you've already consumed the metadata to post an entry row and don't
+     *  want it picked up again. */
     consume(orderId) {
         this.pruneExpired();
-        const entry = this.entries.get(orderId);
+        const key = this.resolveKey(orderId);
+        if (key === undefined)
+            return undefined;
+        const entry = this.entries.get(key);
         if (!entry)
             return undefined;
-        this.entries.delete(orderId);
+        this.deleteEntry(key, entry);
         this.persist();
         return entry;
     }
     /** Remove an entry without retrieval (e.g. on cancel). */
     drop(orderId) {
-        const existed = this.entries.delete(orderId);
-        if (existed)
-            this.persist();
-        return existed;
+        const key = this.resolveKey(orderId);
+        if (key === undefined)
+            return false;
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        this.deleteEntry(key, entry);
+        this.persist();
+        return true;
+    }
+    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
+    resolveKey(k) {
+        if (this.entries.has(k))
+            return k;
+        const viaCid = this.cidIndex.get(k);
+        return viaCid !== undefined && this.entries.has(viaCid) ? viaCid : undefined;
+    }
+    deleteEntry(key, entry) {
+        this.entries.delete(key);
+        if (entry.clientOrderId)
+            this.cidIndex.delete(entry.clientOrderId);
     }
     size() {
         return this.entries.size;
@@ -95,7 +144,7 @@ export class PendingEntryStore {
         let pruned = false;
         for (const [orderId, entry] of this.entries) {
             if (entry.expiresAt <= ts) {
-                this.entries.delete(orderId);
+                this.deleteEntry(orderId, entry);
                 pruned = true;
             }
         }
@@ -128,6 +177,8 @@ export class PendingEntryStore {
         for (const entry of file.entries) {
             if (entry.expiresAt > ts) {
                 this.entries.set(entry.orderId, entry);
+                if (entry.clientOrderId)
+                    this.cidIndex.set(entry.clientOrderId, entry.orderId);
                 kept++;
             }
             else {
@@ -163,6 +214,9 @@ export class PendingEntryStore {
             if (typeof e.orderId !== 'string' || e.orderId.length === 0) {
                 throw new Error('pending-entry-metadata: entry missing orderId');
             }
+            if (e.clientOrderId !== undefined && (typeof e.clientOrderId !== 'string' || e.clientOrderId.length === 0)) {
+                throw new Error('pending-entry-metadata: invalid clientOrderId');
+            }
             if (typeof e.symbol !== 'string' || e.symbol.length === 0) {
                 throw new Error('pending-entry-metadata: entry missing symbol');
             }

package/ingest/position-auto-capture.js

@@ -173,6 +173,17 @@ export async function onClosePositionFilled(ctx, inputs, order) {
     ctx.stateStore.remove(inputs.symbol);
     logger.info(TAG, `close captured ${inputs.symbol} reason=${inputs.closeReason} (positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
 }
+/** Look up the metadata create_order stashed for this fill. Primary key is
+ *  the exchange orderId (post-REST-ack `promote()`); the clientOrderId
+ *  fallback covers the routine market-order race where the WS fill arrives
+ *  BEFORE the REST response, i.e. before the promote — the pre-submission
+ *  stash is keyed by the cid, which the WS event carries (`o.c`). */
+function consumePendingEntry(ctx, fill) {
+    if (!ctx.pendingEntries)
+        return undefined;
+    return (ctx.pendingEntries.consume(fill.exchangeOrderId) ??
+        (fill.clientOrderId ? ctx.pendingEntries.consume(fill.clientOrderId) : undefined));
+}
 export async function onWsFillObserved(ctx, fill) {
     if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
         return;
@@ -208,7 +219,7 @@ export async function onWsFillObserved(ctx, fill) {
             logger.warn(TAG, `onWsFillObserved ${fill.symbol}: scale-in observed but no webappPositionId yet — skipping (parent upsert may have failed; will retry next fill)`);
             return;
         }
-        const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+        const pending = consumePendingEntry(ctx, fill);
         const entry = buildEntryPayload({
             positionId: stateEntry.webappPositionId,
             isScaleIn: true,
@@ -227,8 +238,8 @@ export async function onWsFillObserved(ctx, fill) {
     }
     // No state-store entry → NEW position via WS-driven fill. Replicates the
     // synchronous-market-order path but pulls metadata from the pending cache
-    // (which create_order populated when the limit was placed).
-    const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+    // (which create_order populated BEFORE submitting the order).
+    const pending = consumePendingEntry(ctx, fill);
     ctx.stateStore.upsert({
         symbol: fill.symbol,
         openedAt: ts,

package/ingest/readiness-reporter.d.ts

@@ -0,0 +1,19 @@
+import { type ReadinessReport } from '@reefclaw/shared';
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+export interface ReadinessReporterOptions {
+    apiBaseUrl: string;
+    token: string;
+    binanceApi: Pick<BinancePublicApi, 'probeReachability'>;
+    /** 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. */
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'binanceApi' | 'toolCount'>): 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;