@coinrithm/mcp-trading 0.7.15 → 0.7.17

package/dist/agent/observe.js

@@ -1,6 +1,8 @@
 // Observe phase: read CoinRithm state into one Observation. Sync-polls /trades
 // before any write (polledBeforeWrite=true only after that succeeds). If a
 // required read fails, or no watchlist symbol resolves, the cycle SKIPS writes.
+import { INDICATOR_RANGES, indicatorRangeOf, signalThresholdsOf, } from "./signals.js";
+import { filterUniverseRows, scansUniverse, universeQuery, universeQueryParams, universeResolveTop, universeSectorsOf, UNIVERSE_MAX_SCAN_LIMIT, } from "./universe.js";
 import { futuresEntryEligibilityOf } from "./futuresEligibility.js";
 import { asObj, asArr, asNum, asStr } from "./extract.js";
 import { computeIndicators } from "./indicators.js";
@@ -369,10 +371,9 @@ export async function readPmCalibration(client, trace, nowMs = Date.now()) {
         return undefined;
     }
 }
-// The 1D endpoint nominally returns 288 five-minute bars. Timestamps and gaps
-// are checked separately; requesting this range does not establish freshness.
-const INDICATOR_RANGE = "1D";
-const INDICATOR_INTERVAL_SECONDS = 300;
+// The candle range is the agent's data diet (spec.data.indicatorRange, default
+// 1D = 288 five-minute bars; 1W = 15m, 1M = 1h, 3M = 4h). Timestamps and gaps
+// are checked separately; requesting a range does not establish freshness.
 // `universe_scan` bounds: how many top movers to pull, and how many of those
 // to fully resolve into tradable watch entries (each resolved row costs a
 // resolve + market [+ candles] call).
@@ -449,7 +450,7 @@ function candleTimestamp(value) {
         ? value
         : undefined;
 }
-function candleIntervals(times) {
+function candleIntervals(times, intervalSeconds) {
     let timestampedBarCount = 0;
     let checkedIntervalCount = 0;
     let irregularIntervalCount = 0;
@@ -464,7 +465,7 @@ function candleIntervals(times) {
             continue;
         const gap = current - previous;
         checkedIntervalCount++;
-        if (gap !== INDICATOR_INTERVAL_SECONDS)
+        if (gap !== intervalSeconds)
             irregularIntervalCount++;
         maxGapSeconds = Math.max(maxGapSeconds ?? 0, gap);
     }
@@ -486,13 +487,14 @@ function candleIntervals(times) {
 // the 24h volume. Tolerant by design: any failure (HTTP error, malformed/sparse
 // candles) yields null indicators so the cycle proceeds with price-only context
 // rather than skipping.
-async function fetchCandleContext(client, coinId, trace) {
+async function fetchCandleContext(client, coinId, range, trace) {
+    const intervalSeconds = INDICATOR_RANGES[range];
     // The try honors the documented tolerance for SYNCHRONOUS throws too (an
     // unexpected client error must degrade to price-only context, never kill
     // the cycle).
     let cr;
     try {
-        cr = await client.candles(coinId, INDICATOR_RANGE, trace);
+        cr = await client.candles(coinId, range, trace);
     }
     catch {
         return { indicators: null };
@@ -526,13 +528,13 @@ async function fetchCandleContext(client, coinId, trace) {
                 : undefined;
     }
     const latestTime = times.at(-1);
-    const recent = candleIntervals(times.slice(-15));
+    const recent = candleIntervals(times.slice(-15), intervalSeconds);
     return {
         indicators: computeIndicators(candles),
         indicatorContext: {
-            range: INDICATOR_RANGE,
-            nominalIntervalSeconds: INDICATOR_INTERVAL_SECONDS,
-            ...candleIntervals(times),
+            range,
+            nominalIntervalSeconds: intervalSeconds,
+            ...candleIntervals(times, intervalSeconds),
             ...(latestTime === undefined
                 ? {}
                 : { asOf: new Date(latestTime * 1000).toISOString() }),
@@ -566,10 +568,320 @@ function coinFundamentalsOf(m) {
         out.marketCapUsd = marketCapUsd;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+// Perpetual open interest from the same /market context (no extra call).
+// Keep venue coverage with each delta: it need not cover the whole total.
+// A malformed or absent block is omitted; a real zero reading is valid.
+export function openInterestOf(m, nowMs = Date.now()) {
+    const oi = asObj(asObj(m.derivatives).openInterest);
+    const totalUsd = asNum(oi.totalUsd);
+    const asOf = asStr(oi.asOf);
+    const sourceMs = asOf ? Date.parse(asOf) : NaN;
+    if (totalUsd == null ||
+        totalUsd < 0 ||
+        !asOf ||
+        !Number.isFinite(sourceMs) ||
+        sourceMs > nowMs + 60_000)
+        return undefined;
+    const names = (v) => Array.isArray(v)
+        ? [
+            ...new Set(v.filter((x) => typeof x === "string" && x.length > 0)),
+        ].sort()
+        : [];
+    const change1hVenues = names(oi.change1hVenues);
+    const change24hVenues = names(oi.change24hVenues);
+    const pct = (v) => {
+        const n = asNum(v);
+        return n == null ? null : n;
+    };
+    return {
+        totalUsd,
+        venues: names(asArr(oi.venues).map((v) => asObj(v).venue)),
+        change1hPct: change1hVenues.length ? pct(oi.change1hPct) : null,
+        change1hVenues,
+        change24hPct: change24hVenues.length ? pct(oi.change24hPct) : null,
+        change24hVenues,
+        asOf,
+        stale: oi.stale !== false || nowMs - sourceMs > 45 * 60_000,
+    };
+}
+// A provider time we can show: parseable and not more than 60 s ahead.
+const shownTime = (v, nowMs) => {
+    const s = asStr(v);
+    if (!s)
+        return undefined;
+    const ms = Date.parse(s);
+    return Number.isFinite(ms) && ms <= nowMs + 60_000 ? s : undefined;
+};
+// A dated metric from the API's {value, asOf, stale}; omitted when malformed,
+// negative or dated in the future. A real zero is valid.
+const datedValueOf = (v, nowMs) => {
+    const o = asObj(v);
+    const value = asNum(o.value);
+    const asOf = shownTime(o.asOf, nowMs);
+    if (value == null || value < 0 || !asOf)
+        return undefined;
+    return { value, asOf, stale: o.stale !== false };
+};
+// Binance positioning ratios from the same /market context (no extra call).
+// Each metric keeps its own provider time; malformed metrics are dropped and
+// the block is omitted when none is usable.
+export function positioningOf(m, nowMs = Date.now()) {
+    const p = asObj(asObj(m.derivatives).positioning);
+    const venue = asStr(p.venue);
+    const symbol = asStr(p.symbol);
+    if (!venue || !symbol)
+        return undefined;
+    const out = { venue, symbol };
+    const a = datedValueOf(p.longShortAccountRatio, nowMs);
+    const l = datedValueOf(p.longAccountPct, nowMs);
+    const t = datedValueOf(p.topTraderPositionRatio, nowMs);
+    const k = datedValueOf(p.takerBuySellRatio, nowMs);
+    if (a)
+        out.longShortAccountRatio = a;
+    if (l && l.value <= 100)
+        out.longAccountPct = l;
+    if (t)
+        out.topTraderPositionRatio = t;
+    if (k)
+        out.takerBuySellRatio = k;
+    return Object.keys(out).length > 2 ? out : undefined;
+}
+const liquidationWindowOf = (v) => {
+    const w = asObj(v);
+    const longU = asNum(w.longLiquidatedUsdt);
+    const shortU = asNum(w.shortLiquidatedUsdt);
+    const events = asNum(w.events);
+    const captured = asNum(w.capturedPct);
+    if (longU == null ||
+        shortU == null ||
+        events == null ||
+        captured == null ||
+        longU < 0 ||
+        shortU < 0 ||
+        events < 0 ||
+        !Number.isInteger(events) ||
+        captured < 0 ||
+        captured > 100)
+        return undefined;
+    return {
+        longLiquidatedUsdt: longU,
+        shortLiquidatedUsdt: shortU,
+        events,
+        capturedPct: captured,
+    };
+};
+// OKX liquidations from the same /market context. Both windows must be well
+// formed; capturedPct travels with every sum (a lower bound of our capture
+// uptime, not exchange completeness). Event counts must be whole numbers.
+export function liquidationsOf(m, nowMs = Date.now()) {
+    const q = asObj(asObj(m.derivatives).liquidations);
+    const venue = asStr(q.venue);
+    const instId = asStr(q.instId);
+    const last1h = liquidationWindowOf(q.last1h);
+    const last24h = liquidationWindowOf(q.last24h);
+    if (!venue || !instId || !last1h || !last24h)
+        return undefined;
+    const lastEventAt = q.lastEventAt == null ? null : (shownTime(q.lastEventAt, nowMs) ?? null);
+    return { venue, instId, last1h, last24h, lastEventAt };
+}
+// Macro proxies from the /market context (same block for every coin). Quotes
+// that are malformed or future-dated are dropped; omitted when none remain.
+const optPct = (v) => {
+    const n = asNum(v);
+    return n == null ? null : n;
+};
+const depthSideOf = (v) => {
+    const o = asObj(v);
+    const usd = asNum(o.usd);
+    const reachPct = asNum(o.reachPct);
+    const levels = asNum(o.levels);
+    if (usd == null || usd < 0 || reachPct == null || reachPct < 0)
+        return null;
+    if (levels == null || !Number.isInteger(levels) || levels < 1 || levels > 20)
+        return null;
+    if (typeof o.complete !== "boolean")
+        return null;
+    if (o.complete && levels >= 20)
+        return null; // a full side is never whole
+    return { usd, reachPct, levels, complete: o.complete };
+};
+// Observed depth from the same /market context (no extra call). One venue's
+// visible book; omitted when malformed, future-dated or without any side.
+/**
+ * `{ coins }` from an additive `relatedCoins` array (direct coin slugs), or
+ * nothing: non-arrays and non-string/blank entries are dropped, duplicates
+ * merged. Every valid slug is kept: the API never truncates the list, and
+ * dropping a linked coin could let a bet bypass that coin's cap. An empty
+ * result adds no field.
+ */
+export function coinsField(value) {
+    if (!Array.isArray(value))
+        return {};
+    const coins = [
+        ...new Set(value
+            .filter((c) => typeof c === "string")
+            .map((c) => c.trim().toLowerCase())
+            .filter((c) => c.length > 0 && c.length <= 100)),
+    ];
+    return coins.length ? { coins } : {};
+}
+export function fundingByVenueOf(m, nowMs = Date.now()) {
+    const block = asObj(asObj(m.derivatives).fundingByVenue);
+    if (block.sameTime !== false ||
+        !Array.isArray(block.rates) ||
+        block.rates.length > 2)
+        return undefined;
+    const rates = [];
+    const venues = new Set();
+    for (const value of block.rates) {
+        const r = asObj(value);
+        const role = r.role, venue = asStr(r.venue), symbol = asStr(r.symbol);
+        const fetchedAt = shownTime(r.fetchedAt, nowMs), rateFraction = asNum(r.rateFraction);
+        if ((role !== "context_only" && role !== "settlement_reference") ||
+            !venue ||
+            !symbol ||
+            !fetchedAt ||
+            rateFraction === undefined ||
+            r.sourceAt !== null ||
+            r.freshnessBasis !== "collection_time")
+            continue;
+        const source = role === "context_only"
+            ? "hyperliquid_predicted_fundings"
+            : "paper_futures_reference";
+        if (r.source !== source ||
+            (role === "context_only" &&
+                (venue !== "hyperliquid" ||
+                    r.intervalHours !== 1 ||
+                    Math.abs(rateFraction) > 0.04)))
+            continue;
+        const intervalHours = typeof r.intervalHours === "number" &&
+            Number.isInteger(r.intervalHours) &&
+            r.intervalHours > 0 &&
+            r.intervalHours <= 24
+            ? r.intervalHours
+            : null;
+        const hourlyEquivalentFraction = intervalHours === null ? null : rateFraction / intervalHours;
+        if (hourlyEquivalentFraction !== null &&
+            !Number.isFinite(hourlyEquivalentFraction))
+            continue;
+        // A duplicate venue makes identity ambiguous; never pick the first silently.
+        if (venues.has(venue))
+            return undefined;
+        venues.add(venue);
+        const ageSeconds = Math.max(0, Math.floor((nowMs - Date.parse(fetchedAt)) / 1000));
+        const next = typeof r.nextFundingTime === "string"
+            ? Date.parse(r.nextFundingTime)
+            : NaN;
+        const nextFundingTime = Number.isFinite(next) &&
+            next > nowMs &&
+            next <=
+                Date.parse(fetchedAt) +
+                    (role === "context_only" ? 61 * 60_000 : 24 * 3_600_000)
+            ? new Date(next).toISOString()
+            : null;
+        rates.push({
+            role,
+            venue,
+            symbol,
+            source,
+            rateFraction,
+            intervalHours,
+            hourlyEquivalentFraction,
+            nextFundingTime,
+            fetchedAt,
+            sourceAt: null,
+            ageSeconds,
+            stale: r.stale !== false || ageSeconds > 1800,
+            freshnessBasis: "collection_time",
+        });
+    }
+    return rates.some((r) => r.role === "context_only")
+        ? { rates, sameTime: false }
+        : undefined;
+}
+export function depthOf(m, nowMs = Date.now()) {
+    const d = asObj(asObj(m.derivatives).depth);
+    const venue = asStr(d.venue);
+    const asOf = shownTime(d.asOf, nowMs);
+    if (!venue || !asOf)
+        return undefined;
+    const bid = depthSideOf(d.bid);
+    const ask = depthSideOf(d.ask);
+    if (!bid && !ask)
+        return undefined;
+    return { venue, bid, ask, asOf, stale: d.stale !== false };
+}
+// Chain TVL from the same /market context (no extra call). Omitted when the
+// coin has no verified chain association or the block is malformed. publishedAt is
+// response provenance, never the TVL's observation time (unknown, null); a
+// future-dated time is never shown and an unknown one stays stale.
+export function chainTvlOf(m, nowMs = Date.now()) {
+    const c = asObj(asObj(m.defi).chainTvl);
+    const chain = asStr(c.chain);
+    const tvl = asNum(c.tvlUsd);
+    if (!chain || tvl == null || tvl < 0)
+        return undefined;
+    const publishedAt = c.publishedAt == null ? null : (shownTime(c.publishedAt, nowMs) ?? null);
+    const fetchedAt = c.fetchedAt == null ? null : (shownTime(c.fetchedAt, nowMs) ?? null);
+    const dayAt = c.dayAt == null ? null : (shownTime(c.dayAt, nowMs) ?? null);
+    return {
+        chain,
+        tvlUsd: tvl,
+        publishedAt,
+        fetchedAt,
+        sourceObservedAt: null,
+        // Unknown publication OR collection time is never fresh (root 56890).
+        stale: publishedAt == null || fetchedAt == null || c.stale !== false,
+        dayAt,
+        change1dPct: dayAt ? optPct(c.change1dPct) : null,
+        change7dPct: dayAt ? optPct(c.change7dPct) : null,
+    };
+}
+// Market-wide stablecoin supply from the /market context (same for every coin).
+export function stablecoinSupplyOf(m, nowMs = Date.now()) {
+    const s = asObj(asObj(m.defi).stablecoinSupply);
+    const total = asNum(s.totalUsd);
+    const dayAt = shownTime(s.dayAt, nowMs);
+    if (total == null || total < 0 || !dayAt)
+        return undefined;
+    return {
+        totalUsd: total,
+        dayAt,
+        change1dPct: optPct(s.change1dPct),
+        change7dPct: optPct(s.change7dPct),
+        stale: s.stale !== false,
+    };
+}
+export function macroOf(m, nowMs = Date.now()) {
+    const mc = asObj(m.macro);
+    const note = asStr(mc.note);
+    const quotes = [];
+    for (const raw of asArr(mc.quotes)) {
+        const q = asObj(raw);
+        const symbol = asStr(q.symbol);
+        const label = asStr(q.label);
+        const kind = asStr(q.kind);
+        const price = asNum(q.price);
+        const asOf = shownTime(q.asOf, nowMs);
+        if (!symbol || !label || !kind || price == null || price <= 0 || !asOf)
+            continue;
+        const change = asNum(q.change24hPct);
+        quotes.push({
+            symbol,
+            label,
+            kind,
+            price,
+            change24hPct: change == null ? null : change,
+            asOf,
+            stale: q.stale !== false,
+        });
+    }
+    return note && quotes.length > 0 ? { note, quotes } : undefined;
+}
 // Enrich a watch entry with what the candles fetch yields (indicators + 24h
 // volume) when the `indicators` capability is on. One call, both fields.
-async function enrichFromCandles(client, entry, coinId, trace) {
-    const cc = await fetchCandleContext(client, coinId, trace);
+async function enrichFromCandles(client, entry, coinId, range, trace) {
+    const cc = await fetchCandleContext(client, coinId, range, trace);
     if (cc.indicators)
         entry.indicators = cc.indicators;
     if (cc.indicatorContext)
@@ -588,6 +900,22 @@ async function enrichFromCandles(client, entry, coinId, trace) {
     }
 }
 const HEADLINES_PER_COIN = 3;
+const NEWS_URL_MAX_CHARS = 300;
+// A source link is kept only when it is a plain http(s) URL of bounded length;
+// anything else (javascript:, data:, oversized) is dropped, never rewritten.
+function newsUrl(raw) {
+    if (!raw || raw.length > NEWS_URL_MAX_CHARS)
+        return undefined;
+    try {
+        const url = new URL(raw);
+        return url.protocol === "https:" || url.protocol === "http:"
+            ? url.toString()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const HEADLINE_TITLE_CHARS = 110;
 const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 // Attribute the fetched news to the coins on watch: by the curated slug link
@@ -639,7 +967,7 @@ function titleMentionsCoin(title, symbol) {
 // backend flagged not-openable (eligible === false) and markets the agent already
 // holds (heldPmKeys). Shared by the primary board fetch and the crypto-targeted
 // secondary fetch so both go through the exact same filters.
-function expandPmMarkets(discData, heldPmKeys) {
+export function expandPmMarkets(discData, heldPmKeys) {
     const dd = asObj(discData);
     return (asArr(dd.data ?? dd.markets ?? dd.results)
         .map(asObj)
@@ -709,6 +1037,7 @@ function expandPmMarkets(discData, heldPmKeys) {
                 // resolution date and the venue-reported liquidity (USD).
                 endDate: asStr(ev.endDate) ?? undefined,
                 liquidityUsd: asNum(ev.liquidity) ?? undefined,
+                ...coinsField(ev.relatedCoins),
                 ...(consensus !== undefined ? { consensus } : {}),
                 ...(rules !== undefined ? { rules } : {}),
                 ...(outcomeRule ? { outcomeRule } : {}),
@@ -741,7 +1070,7 @@ function emptyObservation(state, scopes = []) {
         polledBeforeWrite: false,
     };
 }
-export async function observe(client, spec, state, trace) {
+export async function observe(client, spec, state, trace, options = {}) {
     const meR = await client.me(trace);
     if (!meR.ok)
         return {
@@ -834,6 +1163,8 @@ export async function observe(client, spec, state, trace) {
     // Bounded RAG: the market-wide Fear & Greed regime, captured once from the first
     // coin's /market context (it's market-wide, identical across coins).
     let marketMood;
+    let macro;
+    let stablecoinSupply;
     const wantIndicators = spec.capabilities.includes("indicators");
     const wantNews = spec.capabilities.includes("news");
     for (const symbol of spec.risk.watchlist) {
@@ -870,6 +1201,29 @@ export async function observe(client, spec, state, trace) {
         const fundamentals = coinFundamentalsOf(m);
         if (fundamentals)
             entry.fundamentals = fundamentals;
+        const openInterest = openInterestOf(m);
+        if (openInterest)
+            entry.openInterest = openInterest;
+        const positioning = positioningOf(m);
+        if (positioning)
+            entry.positioning = positioning;
+        const liquidations = liquidationsOf(m);
+        if (liquidations)
+            entry.liquidations = liquidations;
+        const chainTvl = chainTvlOf(m);
+        if (chainTvl)
+            entry.chainTvl = chainTvl;
+        const depth = depthOf(m);
+        if (depth)
+            entry.depth = depth;
+        const fundingByVenue = fundingByVenueOf(m);
+        if (fundingByVenue)
+            entry.fundingByVenue = fundingByVenue;
+        // Macro proxies are the same for every coin: keep the first usable block.
+        if (!macro)
+            macro = macroOf(m);
+        if (!stablecoinSupply)
+            stablecoinSupply = stablecoinSupplyOf(m);
         // Capture the market-wide Fear & Greed regime once (same across coins).
         if (!marketMood) {
             const fg = asObj(m.fearGreed);
@@ -886,7 +1240,7 @@ export async function observe(client, spec, state, trace) {
         // model reasons over structure (trend/momentum/volatility/breakout) instead
         // of price + %change alone. Backed by the candles endpoint's shared cache.
         if (wantIndicators)
-            await enrichFromCandles(client, entry, coinId, trace);
+            await enrichFromCandles(client, entry, coinId, indicatorRangeOf(spec), trace);
         watch.push(entry);
     }
     // `universe_scan` capability (2026-08-18, direct user request): discover the
@@ -899,79 +1253,159 @@ export async function observe(client, spec, state, trace) {
     // never a skipped cycle. Watchlist + blocklist symbols are excluded up
     // front so a discovered row can never duplicate or bypass the deny-list.
     let universeMovers;
-    if (spec.capabilities.includes("universe_scan")) {
-        const mv = await client.cryptoMovers("gainers", UNIVERSE_SCAN_LIMIT, trace);
-        if (mv.ok && Array.isArray(mv.data)) {
-            const excluded = new Set([...spec.risk.watchlist, ...(spec.risk.blocklist ?? [])].map((s) => s.toUpperCase()));
-            const rows = mv.data
-                .map(asObj)
-                .map((r) => ({
-                symbol: (asStr(r.symbol) ?? "").toUpperCase(),
-                name: asStr(r.name),
-                // Both serialize as decimal STRINGS on the live feed (openapi
-                // PublicCryptoMover; probed 2026-09-02: "72.34"), so the strict
-                // asNum read left them undefined. Parse the numeric string.
-                change24hPct: asNumLoose(r.change24h),
-                priceUsd: asNumLoose(r.currentPrice),
-                slug: asStr(r.slug),
-                // The movers row already carries the ucid, which IS the coinId every
-                // downstream call takes. Kept so the resolve round-trip below can be
-                // skipped — see the comment there.
-                coinId: asStr(r.ucid),
-            }))
-                .filter((r) => r.symbol && !excluded.has(r.symbol));
-            const resolveTop = rows.slice(0, UNIVERSE_RESOLVE_TOP);
-            for (const row of resolveTop) {
-                // Prefer the ucid the movers feed already gave us. Resolving the
-                // SYMBOL instead was both a wasted call per discovered mover and a
-                // correctness hazard: symbols collide across listings, so the resolver
-                // could hand back a different coin than the one that actually moved,
-                // and the agent would analyze (and trade) that other coin.
-                let coinId = row.coinId;
-                let resolvedName;
-                if (!coinId) {
-                    const rs = await client.resolve(row.symbol, trace);
-                    const match = asObj(asObj(rs.data).match);
-                    coinId =
-                        rs.ok && match.coinId != null ? String(match.coinId) : undefined;
-                    resolvedName = asStr(match.name);
-                }
-                if (!coinId)
-                    continue;
-                const mk = await client.market(coinId, trace);
-                const m = asObj(mk.data);
-                const price = asObj(m.price);
-                const entry = {
-                    symbol: row.symbol,
-                    coinId,
-                    name: resolvedName ?? row.name ?? undefined,
-                    priceUsd: asNum(price.usd) ?? row.priceUsd,
-                    change1h: asNum(price.change1h),
-                    change24h: asNum(price.change24h) ?? row.change24hPct,
-                    change7d: asNum(price.change7d),
-                    ...sentimentContextOf(m),
-                    freshness: freshnessOf(asObj(m.observation)),
-                    futuresEntryEligibility: futuresEntryEligibilityOf(m),
-                    discovered: true,
-                    slug: row.slug ?? asStr(asObj(asObj(m.observation).dataset).coinSlug),
+    if (scansUniverse(spec)) {
+        const excluded = new Set([...spec.risk.watchlist, ...(spec.risk.blocklist ?? [])].map((s) => s.toUpperCase()));
+        // Declared boundaries ask the screener; otherwise keep the original
+        // top-gainers scan exactly. Either way the rows share one resolve path.
+        let rows = [];
+        let resolveTopCount = UNIVERSE_RESOLVE_TOP;
+        if (spec.universe) {
+            const q = universeQuery(spec.universe);
+            resolveTopCount = universeResolveTop(spec.universe);
+            const ur = await client.agentUniverse(universeQueryParams(q), trace);
+            if (ur.ok) {
+                rows = filterUniverseRows(asArr(asObj(ur.data).rows)
+                    .map(asObj)
+                    .map((r) => ({
+                    symbol: (asStr(r.symbol) ?? "").toUpperCase(),
+                    name: asStr(r.name),
+                    slug: asStr(r.slug),
+                    coinId: asStr(r.ucid),
+                    marketCapRank: asNum(r.marketCapRank) ?? undefined,
+                    priceUsd: asNumLoose(r.priceUsd),
+                    change24h: asNumLoose(r.change24h),
+                    volume24hUsd: asNumLoose(r.volume24hUsd),
+                    // Missing stays missing: the filter must not read an absent
+                    // sector list as "no excluded sector".
+                    sectors: universeSectorsOf(r.sectors),
+                })), q);
+            }
+        }
+        else {
+            const mv = await client.cryptoMovers("gainers", UNIVERSE_SCAN_LIMIT, trace);
+            if (mv.ok && Array.isArray(mv.data)) {
+                rows = mv.data.map(asObj).map((r) => ({
+                    symbol: (asStr(r.symbol) ?? "").toUpperCase(),
+                    name: asStr(r.name),
+                    // Both serialize as decimal STRINGS on the live feed (openapi
+                    // PublicCryptoMover; probed 2026-09-02: "72.34"), so the strict
+                    // asNum read left them undefined. Parse the numeric string.
+                    change24h: asNumLoose(r.change24h),
+                    priceUsd: asNumLoose(r.currentPrice),
+                    slug: asStr(r.slug),
+                    // The movers row already carries the ucid, which IS the coinId every
+                    // downstream call takes. Kept so the resolve round-trip below can be
+                    // skipped — see the comment there.
+                    coinId: asStr(r.ucid),
+                }));
+            }
+        }
+        rows = rows.filter((r) => r.symbol && !excluded.has(r.symbol));
+        for (const row of rows.slice(0, resolveTopCount)) {
+            // Prefer the ucid the feed already gave us. Resolving the SYMBOL
+            // instead was both a wasted call per discovered mover and a correctness
+            // hazard: symbols collide across listings, so the resolver could hand
+            // back a different coin than the one that actually moved, and the
+            // agent would analyze (and trade) that other coin.
+            let coinId = row.coinId;
+            let resolvedName;
+            if (!coinId) {
+                const rs = await client.resolve(row.symbol, trace);
+                const match = asObj(asObj(rs.data).match);
+                coinId =
+                    rs.ok && match.coinId != null ? String(match.coinId) : undefined;
+                resolvedName = asStr(match.name);
+            }
+            if (!coinId)
+                continue;
+            const mk = await client.market(coinId, trace);
+            const m = asObj(mk.data);
+            const price = asObj(m.price);
+            const entry = {
+                symbol: row.symbol,
+                coinId,
+                name: resolvedName ?? row.name ?? undefined,
+                priceUsd: asNum(price.usd) ?? row.priceUsd,
+                change1h: asNum(price.change1h),
+                change24h: asNum(price.change24h) ?? row.change24h,
+                change7d: asNum(price.change7d),
+                ...sentimentContextOf(m),
+                freshness: freshnessOf(asObj(m.observation)),
+                futuresEntryEligibility: futuresEntryEligibilityOf(m),
+                discovered: true,
+                slug: row.slug ?? asStr(asObj(asObj(m.observation).dataset).coinSlug),
+            };
+            const fundamentals = coinFundamentalsOf(m);
+            if (fundamentals)
+                entry.fundamentals = fundamentals;
+            const openInterest = openInterestOf(m);
+            if (openInterest)
+                entry.openInterest = openInterest;
+            const positioning = positioningOf(m);
+            if (positioning)
+                entry.positioning = positioning;
+            const liquidations = liquidationsOf(m);
+            if (liquidations)
+                entry.liquidations = liquidations;
+            const chainTvl = chainTvlOf(m);
+            if (chainTvl)
+                entry.chainTvl = chainTvl;
+            const depth = depthOf(m);
+            if (depth)
+                entry.depth = depth;
+            const fundingByVenue = fundingByVenueOf(m);
+            if (fundingByVenue)
+                entry.fundingByVenue = fundingByVenue;
+            if (!macro)
+                macro = macroOf(m);
+            if (!stablecoinSupply)
+                stablecoinSupply = stablecoinSupplyOf(m);
+            if (wantIndicators)
+                await enrichFromCandles(client, entry, coinId, indicatorRangeOf(spec), trace);
+            watch.push(entry);
+        }
+        const context = rows
+            .slice(resolveTopCount)
+            .map(({ symbol, name, change24h, priceUsd }) => ({
+            symbol,
+            name,
+            change24hPct: change24h,
+            priceUsd,
+        }));
+        if (context.length > 0)
+            universeMovers = context;
+        // Watchlist coins must also prove they are inside declared boundaries
+        // before a new entry (universeEntryBlock). Bounded membership batches use
+        // the same filters; a failed batch leaves its coins unverified (no entries),
+        // never silently eligible. Held positions stay closable either way.
+        if (spec.universe) {
+            const toCheck = watch.filter((w) => !w.discovered && w.coinId);
+            const ids = [...new Set(toCheck.map((w) => w.coinId))];
+            for (let offset = 0; offset < ids.length; offset += UNIVERSE_MAX_SCAN_LIMIT) {
+                const batch = ids.slice(offset, offset + UNIVERSE_MAX_SCAN_LIMIT);
+                const q = {
+                    ...universeQuery(spec.universe),
+                    sort: "rank",
+                    limit: batch.length,
                 };
-                const fundamentals = coinFundamentalsOf(m);
-                if (fundamentals)
-                    entry.fundamentals = fundamentals;
-                if (wantIndicators)
-                    await enrichFromCandles(client, entry, coinId, trace);
-                watch.push(entry);
+                const mr = await client.agentUniverse(universeQueryParams(q, batch), trace);
+                if (mr.ok) {
+                    const inside = new Set(filterUniverseRows(asArr(asObj(mr.data).rows)
+                        .map(asObj)
+                        .map((r) => ({
+                        symbol: (asStr(r.symbol) ?? "").toUpperCase(),
+                        coinId: asStr(r.ucid),
+                        marketCapRank: asNum(r.marketCapRank) ?? undefined,
+                        volume24hUsd: asNumLoose(r.volume24hUsd),
+                        sectors: universeSectorsOf(r.sectors),
+                    })), q).map((r) => r.coinId));
+                    const checked = new Set(batch);
+                    for (const w of toCheck) {
+                        if (checked.has(w.coinId))
+                            w.withinBoundaries = inside.has(w.coinId);
+                    }
+                }
             }
-            const context = rows
-                .slice(UNIVERSE_RESOLVE_TOP)
-                .map(({ symbol, name, change24hPct, priceUsd }) => ({
-                symbol,
-                name,
-                change24hPct,
-                priceUsd,
-            }));
-            if (context.length > 0)
-                universeMovers = context;
         }
     }
     // Spot resting orders (for cancel + affordability) — only if spot is enabled.
@@ -1005,7 +1439,7 @@ export async function observe(client, spec, state, trace) {
     if (wantPm) {
         // Curated board for every non-mechanical agent: churn rows removed and a
         // deeper page so the filter does not empty it (see PM_CALIBRATION_CHURN_RE).
-        const curatedPmBoard = spec.model?.provider !== "mechanical";
+        const curatedPmBoard = options.curatedPmBoard ?? spec.model?.provider !== "mechanical";
         const primaryDiscoveryLimit = curatedPmBoard ? 30 : 12;
         // Bias PM discovery toward CRYPTO markets the agent has a price view on, the
         // only PM markets where a price agent's view is even relevant (probed
@@ -1070,6 +1504,8 @@ export async function observe(client, spec, state, trace) {
                 entryProbability: asNum(p.entryProbability),
                 currentProbability: asNum(p.currentProbability),
                 openedAt: asStr(p.openedAt),
+                ...coinsField(p.relatedCoins),
+                ...(asStr(p.eventEndDate) ? { endDate: asStr(p.eventEndDate) } : {}),
             }));
             // Settlement-feedback loop: the SAME /positions/pm response carries an
             // additive `recentlyResolved` array — the agent's OWN bets that settled
@@ -1200,6 +1636,8 @@ export async function observe(client, spec, state, trace) {
                 importance: asNum(it.importance) ?? undefined,
                 ageHours: ((a) => a == null ? undefined : Math.round((a / 60) * 10) / 10)(asNum(it.ageMinutes)),
                 publishedAt: asStr(it.publishedAt) ?? undefined,
+                url: newsUrl(asStr(it.url)),
+                category: asStr(it.category)?.slice(0, 40) ?? undefined,
                 coins: asArr(it.coins)
                     .map((c) => asStr(c))
                     .filter((c) => !!c),
@@ -1234,8 +1672,10 @@ export async function observe(client, spec, state, trace) {
         // model acts on these instead of re-deciding "is there a setup?" from scratch.
         // openPositions are passed so setups on a held symbol are tagged "manage,
         // don't re-open".
-        setups: scanSetups(watch, openPositions),
+        setups: scanSetups(watch, openPositions, signalThresholdsOf(spec)),
         marketMood,
+        ...(macro ? { macro } : {}),
+        ...(stablecoinSupply ? { stablecoinSupply } : {}),
         syncCursor,
         newClosedTrades,
         polledBeforeWrite,