@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/ingest/readiness-reporter.js

@@ -0,0 +1,163 @@
+// Agent-readiness reporter — runs connect-phase health checks ON the trader's
+// host and POSTs a self-describing report to the webapp, so a silently-broken
+// agent (geo-blocked by Binance, clock-skewed, no tools) surfaces a plain-English
+// dashboard alert instead of a false green. Advisory only: it NEVER blocks
+// trading or the safety floor. See docs/AGENT_READINESS_GATE_PLAN.md (Phase 1).
+//
+// No token → no-op (nothing to authenticate; matches the config poller). A
+// module-level singleton guard mirrors `pluginInitialised` in index.ts — OpenClaw
+// calls register() multiple times per process and we must never spawn a second
+// timer. The interval is unref()'d so it never holds the process open.
+import { makeReadinessCheck, deriveOverallReadiness, } from '@reefclaw/shared';
+import { logger, formatError } from '../logger.js';
+const TAG = 'readiness';
+const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
+const MIN_INTERVAL_MS = 60_000;
+/** Best-effort display fact; kept in sync with the register() banner in index.ts. */
+const PLUGIN_VERSION = '3.8.0';
+function resolveIntervalMs(explicit) {
+    if (explicit && explicit > 0)
+        return Math.max(MIN_INTERVAL_MS, explicit);
+    const raw = Number(process.env.RC_READINESS_INTERVAL_MS);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_INTERVAL_MS;
+    return Math.max(MIN_INTERVAL_MS, raw);
+}
+/** 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 async function collectReadiness(opts, bootWarmup = false) {
+    const now = Date.now();
+    const checks = [];
+    // The venue decides which reachability check this report carries; the copy
+    // for both ids lives in shared/src/readiness.ts. Clock drift comes from the
+    // same probe on both venues (Binance fapi serverTime / Hyperliquid
+    // exchangeStatus.time — live-verified 2026-07-11).
+    const reachId = opts.venue === 'hyperliquid' ? 'hyperliquid_reachable' : 'binance_reachable';
+    // plugin_loaded — trivially true (this code runs inside the loaded plugin),
+    // but a positive row is what proves the report path is alive at all.
+    checks.push(makeReadinessCheck('plugin_loaded', 'pass', { checkedAt: now }));
+    // tools_registered
+    checks.push(makeReadinessCheck('tools_registered', opts.toolCount > 0 ? 'pass' : 'fail', {
+        detail: `${opts.toolCount} tools`,
+        checkedAt: now,
+    }));
+    // venue reachability (+ clock drift from the same probe response)
+    const probe = await opts.publicApi.probeReachability();
+    if (probe.outcome === 'reachable') {
+        checks.push(makeReadinessCheck(reachId, 'pass', { checkedAt: now }));
+        const drift = probe.driftMs;
+        if (drift == null) {
+            checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+        }
+        else {
+            const abs = Math.abs(drift);
+            const rawStatus = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
+            // Boot warm-up: a non-pass reading on the first cycle is untrustworthy
+            // (event-loop congestion inflates the measured drift) — report 'unknown'
+            // and let the next cycle confirm, rather than flash the banner amber/red.
+            const status = bootWarmup && rawStatus !== 'pass' ? 'unknown' : rawStatus;
+            checks.push(makeReadinessCheck('clock_in_sync', status, {
+                detail: bootWarmup && rawStatus !== 'pass'
+                    ? `drift ${Math.round(drift)}ms (boot warm-up — rechecking)`
+                    : `drift ${Math.round(drift)}ms`,
+                checkedAt: now,
+            }));
+        }
+    }
+    else if (probe.outcome === 'geo_blocked') {
+        checks.push(makeReadinessCheck(reachId, 'fail', {
+            detail: opts.venue === 'binance' ? 'HTTP 451' : 'blocked (HTTP 451/403)',
+            checkedAt: now,
+        }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else if (probe.outcome === 'unreachable') {
+        // Network/DNS/timeout — could be transient, so warn (amber) rather than
+        // asserting a definitive failure. A persistent problem stays amber across
+        // re-checks; only the geo-block is a hard red.
+        checks.push(makeReadinessCheck(reachId, 'warn', { detail: 'unreachable', checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else {
+        // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
+        checks.push(makeReadinessCheck(reachId, 'unknown', { checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    return {
+        schemaVersion: 1,
+        generatedAt: now,
+        overall: deriveOverallReadiness(checks),
+        checks,
+        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount, venue: opts.venue },
+    };
+}
+async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/agent-readiness`;
+    const ac = new AbortController();
+    const tid = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(report),
+            signal: ac.signal,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            logger.warn(TAG, `POST ${url} → ${res.status}`);
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `readiness POST failed: ${formatError(err)}`);
+    }
+    finally {
+        clearTimeout(tid);
+    }
+}
+let reporterStarted = false;
+/** Test-only — reset the singleton guard between unit tests. */
+export function __resetReadinessReporterForTests() {
+    reporterStarted = false;
+}
+/** Fire the readiness report once at boot then on an unref'd interval. */
+export function startReadinessReporter(opts) {
+    if (reporterStarted)
+        return;
+    if (!opts.token || !opts.token.trim()) {
+        logger.info(TAG, 'no connection token — readiness reporting disabled');
+        return;
+    }
+    reporterStarted = true;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const intervalMs = resolveIntervalMs(opts.intervalMs);
+    const timeoutMs = opts.requestTimeoutMs ?? 10_000;
+    const cycle = async (bootWarmup) => {
+        try {
+            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup);
+            await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
+            if (report.overall === 'fail') {
+                const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');
+                logger.warn(TAG, `readiness FAIL: ${failing}`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `readiness cycle failed: ${formatError(err)}`);
+        }
+    };
+    // First fire is the boot cycle (warm-up); the interval cycles are steady-state.
+    void cycle(true);
+    const timer = setInterval(() => void cycle(false), intervalMs);
+    timer.unref();
+    logger.info(TAG, `readiness reporter started (interval ${Math.round(intervalMs / 1000)}s)`);
+}

package/assets/plugin/ingest/reconcile-db-vs-exchange.d.ts

@@ -0,0 +1,51 @@
+import type { PositionDecisionsClient } from './position-decisions-client.js';
+export interface DbVsExchangeContext {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+    /** Active trading book. Scopes the DB read so open rows from the INACTIVE
+     *  book — which can never appear in this adapter's snapshot — are not
+     *  misread as orphans and synthetically closed (cross-book corruption after
+     *  a set_trading_mode switch with positions open). Absent → unscoped
+     *  (legacy callers). */
+    resolveMode?: () => 'paper' | 'live';
+    /** Active venue (issue #209 item 5) — the same orphan-misread class on the
+     *  exchange axis: a tenant running two venues has open rows the OTHER
+     *  venue's snapshot can never contain. Absent → unscoped (legacy). */
+    resolveExchange?: () => 'binance' | 'hyperliquid';
+}
+/**
+ * Close webapp `positions` rows that are status='open' but absent from the
+ * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
+ *
+ * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
+ *        !== null). Pass only when the fetch genuinely succeeded.
+ */
+export interface DbReconcileOptions {
+    /** Provenance tag written into closeAssessment.source (default boot sweep). */
+    source?: string;
+    /** Attribution hook (issue #203): given an orphaned symbol, return a short
+     *  human-readable description of what the execution engine last knew about
+     *  it (e.g. the simulator's last trade). Logged with the synthetic close so
+     *  chronic capture misses can be classified instead of perpetually healed. */
+    describeLastExit?: (symbol: string) => string | undefined;
+}
+export declare function reconcileDbOpenVsExchange(ctx: DbVsExchangeContext, exchangeSymbols: Iterable<string>, nowMs?: number, opts?: DbReconcileOptions): Promise<number>;
+export declare const DEFAULT_DB_RECONCILE_INTERVAL_MS = 300000;
+export interface PeriodicDbReconcileDeps extends DbVsExchangeContext {
+    /** Resolve the ACTIVE adapter each tick (follows runtime reconnects). */
+    resolveAdapter: () => {
+        getPositionsOrNull(symbol?: string): Promise<Array<{
+            symbol: string;
+        }> | null>;
+    } | undefined;
+    describeLastExit?: (symbol: string) => string | undefined;
+}
+export interface PeriodicDbReconcileHandle {
+    stop(): void;
+    /** One sweep cycle — exposed for tests (no setInterval). */
+    runOnce(): Promise<number>;
+}
+/** Resolve the sweep interval from RC_DB_RECONCILE_INTERVAL_MS.
+ *  'off' or '0' disables (returns null); values are clamped to ≥60s. */
+export declare function resolveDbReconcileIntervalMs(raw?: string | undefined): number | null;
+export declare function startPeriodicDbReconcile(deps: PeriodicDbReconcileDeps, intervalMs?: number | null): PeriodicDbReconcileHandle | null;

package/assets/plugin/ingest/reconcile-db-vs-exchange.js

@@ -0,0 +1,170 @@
+// DB-authoritative orphan close (Increment 0 of the durable orphan-position fix).
+//
+// The problem the existing backstops can't solve: a position closed on the
+// exchange (bracket SL/TP fill or manual close) while the gateway was DOWN, or
+// whose state-store entry was already wiped, leaves webapp `positions.status`
+// stuck 'open' forever. reconcileStateStoreOnStartup can't help — it iterates
+// only LOCAL state-store entries (a wiped entry is invisible) and passes
+// lastContracts:0 (which trips the fillSize>0 guard, so it never posts a close).
+//
+// This pass is DB-authoritative: it asks the webapp for the open set (keyed by
+// the DB row id, not local state), diffs against the EXCHANGE TRUTH snapshot,
+// and posts a synthetic close for any open DB row whose symbol is absent from
+// the exchange. Keying off the DB row id means a missing webappPositionId /
+// wiped state-store / untracked contracts can't defeat it for the common
+// one-row-per-symbol case.
+//
+// Known limitations (all fail SAFE — only false-negatives, never a wrong close):
+//   - Diff is symbol-membership only. If a symbol has BOTH a genuine orphan and
+//     a freshly re-opened live position (two open rows, same symbol, different
+//     positionOpenAt), the symbol is on the exchange so NEITHER is closed — the
+//     orphan persists until the next boot when that symbol is flat. A later
+//     increment can make this count-aware (close the M−N oldest-by-openedAt when
+//     the DB has M open rows but the exchange has N<M for the symbol).
+//   - First-writer-wins on position_closes UNIQUE(position_id): if a real
+//     close_position's journal POST is still retrying at boot, a synthetic close
+//     can land first and the accurate PnL becomes a no-op. Synthetic rows are
+//     tagged (metadata.synthetic) so a later increment could upgrade them.
+//   - closeAt is stamped at boot, not the real (earlier) exchange close time, so
+//     time-in-position analytics on these rows are approximate. Tagged synthetic.
+//
+// Safety (mandatory): the caller MUST pass a TRUSTED exchange snapshot
+// (getPositionsOrNull() !== null). A failed REST fetch collapses to [] in
+// getPositions(), which would make EVERY open row look orphaned — never run
+// this pass off an untrusted/empty-on-error snapshot.
+//
+// Idempotency: position_closes is UNIQUE(position_id) with onConflictDoNothing,
+// and the parent status flip is idempotent — a real close_position (exact PnL)
+// that lands first always wins the UNIQUE. closeReason='reconciler_observed_flat'
+// + metadata.synthetic=true tags these for KPI exclusion.
+import { logger } from '../logger.js';
+const TAG = 'reconcile-db-vs-exchange';
+/** Canonicalise a symbol to its settle-suffix-free form (BTC/USDT:USDT → BTC/USDT). */
+function canonical(symbol) {
+    return symbol.split(':')[0];
+}
+export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now(), opts = {}) {
+    if (!ctx.decisionsClient || !ctx.userId)
+        return 0;
+    const resp = await ctx.decisionsClient.getOpenPositions(ctx.userId, ctx.resolveMode?.(), ctx.resolveExchange?.());
+    if (!resp) {
+        // null = fetch failed (network / terminal). NEVER treat as "no open rows"
+        // (null≠empty) — skip; the next boot / periodic sweep retries.
+        logger.warn(TAG, 'DB open-positions fetch returned null — skipping reconcile (will retry)');
+        return 0;
+    }
+    if (resp.positions.length === 0)
+        return 0;
+    const exchangeSet = new Set();
+    for (const s of exchangeSymbols)
+        exchangeSet.add(canonical(s));
+    const orphans = resp.positions.filter((p) => !exchangeSet.has(canonical(p.symbol)));
+    if (orphans.length === 0) {
+        logger.info(TAG, `DB reconcile: all ${resp.positions.length} open row(s) present on exchange`);
+        return 0;
+    }
+    logger.warn(TAG, `DB reconcile: ${orphans.length} open DB row(s) absent from exchange — closing: ${orphans.map((o) => o.symbol).join(', ')}`);
+    let posted = 0;
+    for (const o of orphans) {
+        if (!(o.remainingSize > 0) || !(o.entryPrice > 0)) {
+            logger.warn(TAG, `${o.symbol}: bad size/price from DB (size=${o.remainingSize}, entry=${o.entryPrice}) — skipping close`);
+            continue;
+        }
+        const lastExitInfo = opts.describeLastExit?.(o.symbol);
+        if (lastExitInfo) {
+            logger.warn(TAG, `${o.symbol}: capture-miss attribution — ${lastExitInfo}`);
+        }
+        const close = {
+            positionId: o.id,
+            closeAt: nowMs,
+            closeReason: 'reconciler_observed_flat',
+            closeAssessment: {
+                source: opts.source ?? 'db_exchange_sweep_boot',
+                ...(lastExitInfo ? { last_engine_trade: lastExitInfo } : {}),
+                synthetic: true,
+                note: 'Position open in DB but absent from the exchange snapshot. It was ' +
+                    'closed on-exchange via a path that bypassed close_position (bracket ' +
+                    'SL/TP fill or manual close). Synthetic close; PnL/R/MFE recomputed ' +
+                    'server-side from the entry + last review.',
+                openedAtMs: o.openedAt,
+            },
+            // Synthetic-but-neutral context. Tagged so KPI aggregation can exclude it.
+            scorecardVerdict: 'unknown',
+            confluenceScore: 0,
+            regime: 'UNKNOWN',
+            regimeConfidence: 0,
+            // The true exit price wasn't captured; use the entry so the server-side
+            // recompute yields ~0 realized PnL (honest "unknown") rather than a
+            // fabricated number. R/MFE/give-back come from the last review row.
+            fillPrice: o.entryPrice,
+            fillSize: o.remainingSize,
+            realizedPnl: 0,
+            realizedR: 0,
+            mfeRAtClose: 0,
+            giveBackPctAtClose: 0,
+            metadata: { synthetic: true, source: 'boot_reconcile' },
+        };
+        ctx.decisionsClient.postClose(ctx.userId, close);
+        posted++;
+        logger.info(TAG, `synthetic close posted ${o.symbol} (positionId=${o.id.slice(0, 8)}…, size=${o.remainingSize})`);
+    }
+    return posted;
+}
+// ---- Periodic sweep (issues #199/#203) ----
+//
+// The boot-only sweep left phantoms alive for DAYS between restarts (paper:
+// the LTC phantom of issue #199 lived 26.5h; live: 38 of 85 closes in 14 days
+// were harvested only at the daily restart, issue #203). This interval runs
+// the same DB-authoritative pass continuously with the same trusted-snapshot
+// discipline: getPositionsOrNull() null → skip, never treat as flat.
+export const DEFAULT_DB_RECONCILE_INTERVAL_MS = 300_000;
+const MIN_DB_RECONCILE_INTERVAL_MS = 60_000;
+/** Resolve the sweep interval from RC_DB_RECONCILE_INTERVAL_MS.
+ *  'off' or '0' disables (returns null); values are clamped to ≥60s. */
+export function resolveDbReconcileIntervalMs(raw = process.env.RC_DB_RECONCILE_INTERVAL_MS) {
+    if (raw === 'off' || raw === '0')
+        return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_DB_RECONCILE_INTERVAL_MS;
+    return Math.max(MIN_DB_RECONCILE_INTERVAL_MS, n);
+}
+export function startPeriodicDbReconcile(deps, intervalMs = resolveDbReconcileIntervalMs()) {
+    if (intervalMs === null) {
+        logger.info(TAG, 'periodic sweep disabled (RC_DB_RECONCILE_INTERVAL_MS=off)');
+        return null;
+    }
+    let running = false;
+    const runOnce = async () => {
+        if (running)
+            return 0; // concurrency guard — a slow sweep never overlaps
+        running = true;
+        try {
+            const adapter = deps.resolveAdapter();
+            if (!adapter)
+                return 0;
+            const positions = await adapter.getPositionsOrNull();
+            if (positions === null) {
+                // Untrusted snapshot — NEVER read as flat (null≠empty).
+                logger.warn(TAG, 'periodic sweep skipped — positions fetch untrusted (null)');
+                return 0;
+            }
+            return await reconcileDbOpenVsExchange(deps, positions.map((p) => p.symbol), Date.now(), { source: 'db_exchange_sweep_periodic', describeLastExit: deps.describeLastExit });
+        }
+        catch (err) {
+            logger.warn(TAG, `periodic sweep failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => { void runOnce(); }, intervalMs);
+    // Never keep the process alive just for the sweep.
+    timer.unref?.();
+    logger.info(TAG, `periodic DB-vs-exchange sweep started (interval ${intervalMs}ms)`);
+    return {
+        stop: () => clearInterval(timer),
+        runOnce,
+    };
+}

package/assets/plugin/ingest/reconciler-cleanup.d.ts

@@ -0,0 +1,37 @@
+import type { PositionDecisionsClient } from './position-decisions-client.js';
+import type { PositionStateStore } from '../live/position-state-store.js';
+export interface ReconcilerCleanupContext {
+    decisionsClient?: PositionDecisionsClient;
+    stateStore?: PositionStateStore;
+    userId?: string;
+    /** Last-price fetcher. Plugin-side passes a closure over
+     *  `adapter.getLastPrice`. Tests inject a mock. Returning `null` skips
+     *  the webapp close post (state-store still cleaned). */
+    lastPriceFn?: (symbol: string) => Promise<number | null>;
+}
+export interface CloseObservedArgs {
+    /** Symbol observed flat. Either canonical (`BTC/USDT`) or settle-suffix
+     *  (`BTC/USDT:USDT`) form — state-store normalises internally. */
+    symbol: string;
+    /** Last contracts seen by reconciler before exchange showed flat. Used as
+     *  fillSize on the synthetic close payload. */
+    lastContracts: number;
+    /** Epoch ms — when reconciler observed the close. Defaults to Date.now(). */
+    observedAtMs?: number;
+}
+export declare function onReconcilerObservedClose(ctx: ReconcilerCleanupContext, args: CloseObservedArgs): Promise<void>;
+/** Startup-time reconciliation between state-store and exchange truth.
+ *
+ *  Why this exists: the in-memory reconciler only emits `closed` drifts on
+ *  the exact transition "was on exchange last poll, gone now". State-store
+ *  entries that persist across a close-bypass that happened BEFORE the plugin
+ *  started are invisible to that loop — they sit in `position-state.json`
+ *  forever and the next entry on the same symbol gets mistaken for a scale-in.
+ *
+ *  This pass runs once at boot, after the live adapter is initialised:
+ *  for every state-store entry, if the symbol isn't on the current exchange
+ *  snapshot, fire the same cleanup as the runtime hook would.
+ *
+ *  Returns the count of entries cleaned (for log + telemetry).
+ */
+export declare function reconcileStateStoreOnStartup(ctx: ReconcilerCleanupContext, exchangeSymbols: Iterable<string>): Promise<number>;

package/assets/plugin/ingest/reconciler-cleanup.js

@@ -0,0 +1,147 @@
+// Reconciler-driven cleanup for the close-bypass-leaks-state class-of-bug.
+//
+// Background: when a position closes via any path other than close_position()
+// — i.e., bracket SL/TP fill, opposite-side market order, or external close on
+// the exchange UI — onClosePositionFilled never runs. Two pieces of state leak:
+//
+//   1. webapp `positions.status` stays 'open' indefinitely (until a manual
+//      `scripts/reconcile-open-positions.py` sweep).
+//   2. `position-state.json` keeps the entry with its stale `webappPositionId`.
+//      The next entry on the same symbol is then mistaken for a scale-in and
+//      reviews silently drop because the cached id no longer maps to a live
+//      DB row.
+//
+// All three close-bypass paths converge on the same observable: the next
+// reconciler tick (60 s cadence) sees the symbol gone from `getPositions()`
+// and emits a `drift_detected` event with `type='closed'`. We hook there.
+//
+// Two-phase cleanup:
+//   Phase 1 — synthetic close to webapp (best-effort): if the state-store
+//             entry has a `webappPositionId` and we can fetch a last price,
+//             POST `/api/internal/position-closes` with a stub close payload
+//             tagged `closeReason='reconciler_observed_flat'`. Webapp
+//             recomputes realized PnL/R/MFE server-side from positionEntries +
+//             last review (the same path the close auto-capture uses).
+//   Phase 2 — state-store cleanup (unconditional): drop the entry. This is
+//             the more important half — it prevents the next entry on the
+//             same symbol from being mistaken for a scale-in.
+//
+// Idempotency:
+//   - webapp endpoint dedups via UNIQUE on position_id (onConflictDoNothing).
+//   - state-store remove is a no-op if the entry is already gone.
+// Re-firing on subsequent reconciler ticks is safe.
+//
+// Failure mode tradeoff: when no last-price is reachable, we skip the webapp
+// post but still clean state-store. The DB row stays 'open' until manual
+// reconcile (existing operator workflow). State-store cleanup alone closes
+// the next-entry-mistaken-for-scale-in failure mode, which is the harder one
+// to recover from.
+import { logger } from '../logger.js';
+const TAG = 'reconciler-cleanup';
+export async function onReconcilerObservedClose(ctx, args) {
+    if (!ctx.stateStore)
+        return;
+    const entry = ctx.stateStore.get(args.symbol);
+    if (!entry) {
+        // Already clean. Could happen if close_position fired between the WS
+        // close fill and this reconciler tick — onClosePositionFilled removed the
+        // entry first. Silent no-op.
+        return;
+    }
+    const webappPositionId = entry.webappPositionId;
+    const observedAtMs = args.observedAtMs ?? Date.now();
+    if (webappPositionId && ctx.decisionsClient && ctx.userId) {
+        let lastPrice = null;
+        if (ctx.lastPriceFn) {
+            try {
+                lastPrice = await ctx.lastPriceFn(args.symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `lastPriceFn(${args.symbol}) threw: ${err instanceof Error ? err.message : String(err)} — synthetic close will be skipped`);
+            }
+        }
+        const fillSize = Math.abs(args.lastContracts);
+        if (lastPrice !== null && lastPrice > 0 && fillSize > 0) {
+            const close = {
+                positionId: webappPositionId,
+                closeAt: observedAtMs,
+                closeReason: 'reconciler_observed_flat',
+                closeAssessment: {
+                    note: 'Position observed flat on exchange via reconciler. Close path ' +
+                        'bypassed close_position (likely bracket SL/TP fill, opposite-side ' +
+                        'market order, or external close). Synthetic close row.',
+                    observedAtMs,
+                    lastContracts: args.lastContracts,
+                },
+                scorecardVerdict: 'NO_GO',
+                confluenceScore: 0,
+                regime: 'unknown',
+                regimeConfidence: 0.5,
+                fillPrice: lastPrice,
+                fillSize,
+                // Webapp recomputes these server-side from positionEntries + last
+                // review when all four arrive as zero (same code path the close
+                // auto-capture uses).
+                realizedPnl: 0,
+                realizedR: 0,
+                mfeRAtClose: 0,
+                giveBackPctAtClose: 0,
+            };
+            ctx.decisionsClient.postClose(ctx.userId, close);
+            logger.info(TAG, `synthetic close posted ${args.symbol} ` +
+                `(positionId=${webappPositionId.slice(0, 8)}…, ` +
+                `price=${lastPrice}, size=${fillSize})`);
+        }
+        else {
+            logger.warn(TAG, `${args.symbol}: cannot post synthetic close ` +
+                `(lastPrice=${lastPrice ?? 'null'}, size=${fillSize}); ` +
+                `state-store entry will still be cleaned. DB row may stay ` +
+                `status='open' until reconcile-open-positions.py runs.`);
+        }
+    }
+    else if (!webappPositionId) {
+        logger.info(TAG, `${args.symbol}: orphan entry (no webappPositionId, parent row never created) — cleaning state-store only`);
+    }
+    ctx.stateStore.remove(args.symbol);
+}
+/** Startup-time reconciliation between state-store and exchange truth.
+ *
+ *  Why this exists: the in-memory reconciler only emits `closed` drifts on
+ *  the exact transition "was on exchange last poll, gone now". State-store
+ *  entries that persist across a close-bypass that happened BEFORE the plugin
+ *  started are invisible to that loop — they sit in `position-state.json`
+ *  forever and the next entry on the same symbol gets mistaken for a scale-in.
+ *
+ *  This pass runs once at boot, after the live adapter is initialised:
+ *  for every state-store entry, if the symbol isn't on the current exchange
+ *  snapshot, fire the same cleanup as the runtime hook would.
+ *
+ *  Returns the count of entries cleaned (for log + telemetry).
+ */
+export async function reconcileStateStoreOnStartup(ctx, exchangeSymbols) {
+    if (!ctx.stateStore)
+        return 0;
+    // Normalise the exchange symbol list — state-store stores canonical form.
+    const exchangeSet = new Set();
+    for (const sym of exchangeSymbols) {
+        exchangeSet.add(sym.split(':')[0]);
+    }
+    const stale = ctx.stateStore.getAll().filter((e) => !exchangeSet.has(e.symbol));
+    if (stale.length === 0) {
+        logger.info(TAG, `startup reconcile: state-store clean (${ctx.stateStore.size()} entries match exchange)`);
+        return 0;
+    }
+    logger.warn(TAG, `startup reconcile: ${stale.length} stale state-store entr${stale.length === 1 ? 'y' : 'ies'} ` +
+        `not on exchange — cleaning: ${stale.map((e) => e.symbol).join(', ')}`);
+    for (const entry of stale) {
+        await onReconcilerObservedClose(ctx, {
+            symbol: entry.symbol,
+            // We don't know the closing size — pass 0 so the synthetic close
+            // post is skipped (size validation in cleanup). State-store entry
+            // is still removed. Operator runs reconcile-open-positions.py to
+            // close any matching DB rows.
+            lastContracts: 0,
+        });
+    }
+    return stale.length;
+}