@coinrithm/mcp-trading 0.7.14 → 0.7.15

package/dist/agent/observe.js

@@ -1,11 +1,374 @@
 // 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 { futuresEntryEligibilityOf } from "./futuresEligibility.js";
 import { asObj, asArr, asNum, asStr } from "./extract.js";
 import { computeIndicators } from "./indicators.js";
 import { scanSetups } from "./setups.js";
-import { freshnessOf, pmQualityOf, pmDecisionSupportOf } from "./pmContext.js";
+import { freshnessOf, pmQualityOf, pmDecisionSupportOf, pmConsensusOf, pmCalibrationOf, pmSettlementRuleOf, pmOutcomeRuleOf, } from "./pmContext.js";
 import { deriveCapitalBook, usesCapitalSizing } from "./capitalSizing.js";
+function contextTimestamp(value) {
+    const text = asStr(value);
+    return text &&
+        text.length <= 40 &&
+        /^\d{4}-\d{2}-\d{2}T/.test(text) &&
+        Number.isFinite(Date.parse(text))
+        ? text
+        : undefined;
+}
+/** Keep sentiment's sample and dates together on both watchlist paths. */
+function sentimentContextOf(market) {
+    const sentiment = asObj(market.sentiment);
+    const votes = asNum(sentiment.totalVotes);
+    return {
+        sentimentBullishPct: asNum(sentiment.bullishPct),
+        sentimentTotalVotes: votes !== undefined && Number.isSafeInteger(votes) && votes >= 0
+            ? votes
+            : undefined,
+        sentimentDayUtc: contextTimestamp(sentiment.dayUtc),
+        sentimentUpdatedAt: contextTimestamp(sentiment.updatedAt),
+    };
+}
+const WHALE_READ_TIMEOUT_MS = 5_000;
+const MAX_WHALE_TRADES = 10;
+const MAX_WHALE_WALLETS = 2;
+const MAX_WALLET_DAILY = 30;
+const MAX_WALLET_FILLS = 6;
+const MAX_EVENT_SLUG_LENGTH = 240;
+const MAX_TIMESTAMP_LENGTH = 40;
+const PUBLIC_WALLET_SOURCES = new Set(["polymarket", "limitless", "myriad"]);
+const FULL_EVM_ADDRESS = /^0x[a-fA-F0-9]{40}$/;
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+function whaleFailure(result) {
+    if (result.status === 0) {
+        return asObj(result.data).error === "timeout" ? "timeout" : "network_error";
+    }
+    return "http_error";
+}
+function compactWalletFill(value) {
+    const row = asObj(value);
+    const event = asObj(row.event);
+    const side = asStr(row.side);
+    if (!side)
+        return undefined;
+    return {
+        ...(asStr(event.slug)
+            ? { eventSlug: asStr(event.slug)?.slice(0, MAX_EVENT_SLUG_LENGTH) }
+            : {}),
+        ...(asStr(event.title)
+            ? { eventTitle: asStr(event.title)?.slice(0, 180) }
+            : {}),
+        ...(asStr(row.marketQuestion)
+            ? { marketQuestion: asStr(row.marketQuestion)?.slice(0, 240) }
+            : {}),
+        side: side.slice(0, 24),
+        ...(asStr(row.outcome)
+            ? { outcome: asStr(row.outcome)?.slice(0, 120) }
+            : {}),
+        ...(asNum(row.usdValue) !== undefined
+            ? { usdValue: asNum(row.usdValue) }
+            : {}),
+        ...(asNum(row.price) !== undefined ? { price: asNum(row.price) } : {}),
+        ...(asStr(row.evidenceType)
+            ? { evidenceType: asStr(row.evidenceType)?.slice(0, 48) }
+            : {}),
+        ...(asStr(row.tradedAt)
+            ? { tradedAt: asStr(row.tradedAt)?.slice(0, MAX_TIMESTAMP_LENGTH) }
+            : {}),
+        ...(asStr(row.sourceMarketRef)
+            ? { sourceMarketRef: asStr(row.sourceMarketRef)?.slice(0, 120) }
+            : {}),
+    };
+}
+function compactWallet(value, expectedSource, expectedAddress) {
+    const row = asObj(value);
+    const returnedSource = asStr(row.source)?.toLowerCase();
+    const returnedAddress = asStr(row.wallet) ?? asStr(row.address);
+    if (returnedSource !== expectedSource ||
+        !returnedAddress ||
+        returnedAddress.toLowerCase() !== expectedAddress) {
+        return undefined;
+    }
+    if (!row.summary30d ||
+        typeof row.summary30d !== "object" ||
+        Array.isArray(row.summary30d)) {
+        return undefined;
+    }
+    if (!Array.isArray(row.daily) || !Array.isArray(row.recentFills)) {
+        return undefined;
+    }
+    const summary = asObj(row.summary30d);
+    const daily = asArr(row.daily)
+        .filter((item) => ISO_DAY.test(asStr(asObj(item).day) ?? ""))
+        .map((item) => {
+        const day = asObj(item);
+        return {
+            ...(asStr(day.day) ? { day: asStr(day.day) } : {}),
+            ...(asNum(day.tradeCount) !== undefined
+                ? { tradeCount: asNum(day.tradeCount) }
+                : {}),
+            ...(asNum(day.buyCount) !== undefined
+                ? { buyCount: asNum(day.buyCount) }
+                : {}),
+            ...(asNum(day.sellCount) !== undefined
+                ? { sellCount: asNum(day.sellCount) }
+                : {}),
+            ...(asNum(day.notionalUsd) !== undefined
+                ? { notionalUsd: asNum(day.notionalUsd) }
+                : {}),
+        };
+    })
+        .sort((a, b) => (b.day ?? "").localeCompare(a.day ?? ""))
+        .slice(0, MAX_WALLET_DAILY);
+    const recentFills = asArr(row.recentFills)
+        .map(compactWalletFill)
+        .filter((item) => !!item)
+        .slice(0, MAX_WALLET_FILLS);
+    return {
+        source: expectedSource,
+        address: expectedAddress,
+        ...(asStr(row.asOf)
+            ? { asOf: asStr(row.asOf)?.slice(0, MAX_TIMESTAMP_LENGTH) }
+            : {}),
+        summary30d: {
+            ...(asStr(summary.basis)
+                ? { basis: asStr(summary.basis)?.slice(0, 48) }
+                : {}),
+            ...(asStr(summary.windowStart)
+                ? {
+                    windowStart: asStr(summary.windowStart)?.slice(0, MAX_TIMESTAMP_LENGTH),
+                }
+                : {}),
+            ...(asNum(summary.tradeCount) !== undefined
+                ? { tradeCount: asNum(summary.tradeCount) }
+                : {}),
+            ...(asNum(summary.notionalUsd) !== undefined
+                ? { notionalUsd: asNum(summary.notionalUsd) }
+                : {}),
+            ...(asNum(summary.buyNotionalUsd) !== undefined
+                ? { buyNotionalUsd: asNum(summary.buyNotionalUsd) }
+                : {}),
+            ...(asNum(summary.sellNotionalUsd) !== undefined
+                ? { sellNotionalUsd: asNum(summary.sellNotionalUsd) }
+                : {}),
+        },
+        rollup: {
+            ...(typeof asObj(row.rollup).available === "boolean"
+                ? { available: asObj(row.rollup).available }
+                : {}),
+            ...(asNum(asObj(row.rollup).coveredDays) !== undefined
+                ? { coveredDays: asNum(asObj(row.rollup).coveredDays) }
+                : {}),
+            ...(asStr(asObj(row.rollup).from)
+                ? {
+                    from: asStr(asObj(row.rollup).from)?.slice(0, MAX_TIMESTAMP_LENGTH),
+                }
+                : {}),
+            ...(asStr(asObj(row.rollup).to)
+                ? { to: asStr(asObj(row.rollup).to)?.slice(0, MAX_TIMESTAMP_LENGTH) }
+                : {}),
+            ...(asStr(asObj(row.rollup).computedAt)
+                ? {
+                    computedAt: asStr(asObj(row.rollup).computedAt)?.slice(0, MAX_TIMESTAMP_LENGTH),
+                }
+                : {}),
+        },
+        daily,
+        recentFills,
+    };
+}
+/**
+ * Add bounded public whale context after the deterministic gate. This is
+ * deliberately separate from observe(): a skipped or mechanical cycle never
+ * pays for the public reads, and this context cannot widen candidate selection.
+ */
+export async function enrichWhaleContext(client, observation) {
+    const fetchedAt = () => new Date().toISOString();
+    const relevant = new Set([...observation.pmMarkets, ...observation.pmPositions]
+        .map((item) => item.source && item.slug
+        ? `${item.source.toLowerCase()}|${item.slug.toLowerCase()}`
+        : undefined)
+        .filter((item) => !!item));
+    const unavailable = (reason) => ({
+        status: "unavailable",
+        fetchedAt: fetchedAt(),
+        coverage: "relevant_events",
+        trades: [],
+        wallets: [],
+        omitted: 0,
+        ...(reason ? { reason } : {}),
+    });
+    if (relevant.size === 0) {
+        return {
+            status: "available",
+            fetchedAt: fetchedAt(),
+            coverage: "no_relevant_events",
+            trades: [],
+            wallets: [],
+            omitted: 0,
+        };
+    }
+    const tape = await client.getPublicPmWhales({
+        limit: 50,
+        timeoutMs: WHALE_READ_TIMEOUT_MS,
+    });
+    if (!tape.ok)
+        return unavailable(whaleFailure(tape));
+    const root = asObj(tape.data);
+    if (!Array.isArray(root.trades))
+        return unavailable("invalid_payload");
+    let omitted = 0;
+    const trades = [];
+    const walletRequests = [];
+    for (const value of root.trades) {
+        const row = asObj(value);
+        const source = asStr(row.source)?.toLowerCase();
+        const eventSlug = asStr(row.eventSlug);
+        const side = asStr(row.side);
+        if (!source ||
+            !eventSlug ||
+            !side ||
+            !relevant.has(`${source}|${eventSlug.toLowerCase()}`)) {
+            omitted += 1;
+            continue;
+        }
+        const walletAddress = asStr(row.walletAddress)?.trim();
+        const validWalletAddress = walletAddress &&
+            PUBLIC_WALLET_SOURCES.has(source) &&
+            FULL_EVM_ADDRESS.test(walletAddress)
+            ? walletAddress.toLowerCase()
+            : undefined;
+        if (validWalletAddress &&
+            !walletRequests.some((item) => item.source === source && item.address === validWalletAddress)) {
+            walletRequests.push({ source, address: validWalletAddress });
+        }
+        if (trades.length >= MAX_WHALE_TRADES) {
+            omitted += 1;
+            continue;
+        }
+        const trade = {
+            source,
+            eventSlug: eventSlug.slice(0, MAX_EVENT_SLUG_LENGTH),
+            side: side.slice(0, 24),
+            ...(asStr(row.eventTitle)
+                ? { eventTitle: asStr(row.eventTitle)?.slice(0, 180) }
+                : {}),
+            ...(asStr(row.marketQuestion)
+                ? { marketQuestion: asStr(row.marketQuestion)?.slice(0, 240) }
+                : {}),
+            ...(asStr(row.outcome)
+                ? { outcome: asStr(row.outcome)?.slice(0, 120) }
+                : {}),
+            ...(asNum(row.usdValue) !== undefined
+                ? { usdValue: asNum(row.usdValue) }
+                : {}),
+            ...(asNum(row.price) !== undefined ? { price: asNum(row.price) } : {}),
+            ...(asStr(row.sourceMarketRef)
+                ? { sourceMarketRef: asStr(row.sourceMarketRef)?.slice(0, 120) }
+                : {}),
+            ...(asStr(row.valueBasis)
+                ? { valueBasis: asStr(row.valueBasis)?.slice(0, 64) }
+                : {}),
+            ...(asStr(row.evidenceType)
+                ? { evidenceType: asStr(row.evidenceType)?.slice(0, 48) }
+                : {}),
+            ...(asStr(row.evidenceRef)
+                ? { evidenceRef: asStr(row.evidenceRef)?.slice(0, 160) }
+                : {}),
+            ...(asNum(row.nativeValue) !== undefined
+                ? { nativeValue: asNum(row.nativeValue) }
+                : {}),
+            ...(asStr(row.nativeCurrency)
+                ? { nativeCurrency: asStr(row.nativeCurrency)?.slice(0, 24) }
+                : {}),
+            ...(asStr(row.availability) &&
+                ["live", "delayed", "unavailable"].includes(asStr(row.availability))
+                ? {
+                    availability: asStr(row.availability),
+                }
+                : {}),
+            ...(asStr(row.tradedAt)
+                ? { tradedAt: asStr(row.tradedAt)?.slice(0, MAX_TIMESTAMP_LENGTH) }
+                : {}),
+            ...(asStr(row.observedAt)
+                ? { observedAt: asStr(row.observedAt)?.slice(0, MAX_TIMESTAMP_LENGTH) }
+                : {}),
+            ...(asNum(row.latencySeconds) !== undefined
+                ? { latencySeconds: asNum(row.latencySeconds) }
+                : {}),
+            ...(validWalletAddress ? { walletAddress: validWalletAddress } : {}),
+        };
+        trades.push(trade);
+    }
+    const wallets = [];
+    let reason;
+    for (const request of walletRequests.slice(0, MAX_WHALE_WALLETS)) {
+        const detail = await client.getPublicPmWhaleWallet(request.source, request.address, { timeoutMs: WHALE_READ_TIMEOUT_MS });
+        if (!detail.ok) {
+            omitted += 1;
+            reason ??= whaleFailure(detail);
+            continue;
+        }
+        const wallet = compactWallet(detail.data, request.source, request.address);
+        if (!wallet) {
+            omitted += 1;
+            reason ??= "invalid_payload";
+            continue;
+        }
+        wallets.push(wallet);
+    }
+    return {
+        status: reason ? "partial" : "available",
+        fetchedAt: fetchedAt(),
+        coverage: "relevant_events",
+        trades,
+        wallets,
+        omitted,
+        ...(reason ? { reason } : {}),
+    };
+}
+// The agent's own settled PM forecast record changes only as bets settle, so
+// it is read at most once per PM_CALIBRATION_TTL_MS per credential. The cache
+// is module-level because the hosted scheduler builds a new client every
+// cycle; it is keyed by a hash of base URL + API key, never the key itself.
+// Every attempt (success, failure, or a backend without the field) is cached
+// for the full TTL, a read is never retried (no 429 retry either) and it has
+// its own short deadline, so it can neither block nor repeat within a cycle.
+const PM_CALIBRATION_TTL_MS = 30 * 60_000;
+const PM_CALIBRATION_READ_TIMEOUT_MS = 5_000;
+const PM_CALIBRATION_CACHE_MAX = 2_000;
+const pmCalibrationCache = new Map();
+export function clearPmCalibrationCache() {
+    pmCalibrationCache.clear();
+}
+export async function readPmCalibration(client, trace, nowMs = Date.now()) {
+    try {
+        const key = client.credentialFingerprint();
+        const hit = pmCalibrationCache.get(key);
+        if (hit && nowMs >= hit.at && nowMs - hit.at < PM_CALIBRATION_TTL_MS)
+            return await hit.value;
+        const value = client
+            .performance(trace, {
+            timeoutMs: PM_CALIBRATION_READ_TIMEOUT_MS,
+            maxRetries: 0,
+        })
+            .then((r) => r.ok ? pmCalibrationOf(asObj(r.data).pmCalibration) : undefined)
+            .catch(() => undefined);
+        // Re-insert so Map order tracks recency, then drop the oldest entries.
+        pmCalibrationCache.delete(key);
+        pmCalibrationCache.set(key, { at: nowMs, value });
+        for (const oldest of pmCalibrationCache.keys()) {
+            if (pmCalibrationCache.size <= PM_CALIBRATION_CACHE_MAX)
+                break;
+            pmCalibrationCache.delete(oldest);
+        }
+        return await value;
+    }
+    catch {
+        // A client without the read (or any synchronous failure) omits the block.
+        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";
@@ -64,11 +427,14 @@ const PM_COIN_NAMES = {
     SUI: "Sui",
 };
 // Repeated micro-contracts are useful for execution smoke tests but are a poor
-// calibration universe: outcomes overlap heavily, resolve too quickly to admit
-// meaningful independent research, and drown the public scorecard in Bitcoin
-// coin flips. Non-mechanical calibration agents receive a deeper discovery
-// page with these rows removed. Mechanical baselines intentionally keep the
-// unmodified universe so their reference contract remains reproducible.
+// forecasting universe: outcomes overlap heavily, resolve too quickly to admit
+// meaningful independent research, and are priced off the same public spot
+// prices the agent sees. In production (30 days to 2026-09-29) these churn rows
+// were 72% of all LLM PM decisions and drowned the public scorecard in Bitcoin
+// coin flips. Every non-mechanical agent (any objective, not only
+// calibration) therefore receives a deeper discovery page with these rows
+// removed. Mechanical baselines intentionally keep the unmodified universe so
+// their reference contract remains reproducible.
 const PM_CALIBRATION_CHURN_RE = /(updown|up-or-down|-5-?min|-5m-|-15m|15m(?:-|$)|(?:5|15)\s+min(?:ute)?s?|-1h-|hourly|-daily-|\bdaily\b|what-price-will[^\n]*(?:today|tomorrow)|-above-on-|-price-on-|this[ -]week|of[ -]the[ -]week|-weekly-)/i;
 export function isCalibrationChurnMarket(market) {
     return PM_CALIBRATION_CHURN_RE.test(`${market.slug ?? ""} ${market.title ?? ""}`);
@@ -296,6 +662,12 @@ function expandPmMarkets(discData, heldPmKeys) {
         // the mechanical BENCHMARK agents' deterministic highest-volume pick rule.
         // Same for every outcome of the event; undefined on an older backend.
         const volumeUsd = asNum(ev.volume24h) ?? undefined;
+        // Event-level cross-venue consensus, copied onto every outcome row of
+        // the event as-is (never mapped to or flipped for a specific outcome).
+        const consensus = pmConsensusOf(ev);
+        // Event-level settlement terms, likewise copied to every outcome row;
+        // the prompt prints them once per event.
+        const rules = pmSettlementRuleOf(ev);
         // At most a few outcomes per event so a wide multi-outcome market
         // (e.g. dozens of price buckets) can't explode the prompt. Drop
         // outcomes the backend flagged NOT openable (eligible === false) so the
@@ -312,26 +684,36 @@ function expandPmMarkets(discData, heldPmKeys) {
             .slice(0, 3);
         // Only an absent legacy outcomes field permits the flat fallback. A
         // present empty/malformed/all-rejected array must never resurrect ev.
-        return outcomes.map((o) => ({
-            source,
-            slug,
-            outcomeExternalMarketId: asStr(o.externalMarketId) ?? asStr(o.outcomeExternalMarketId) ?? "",
-            // Carry the odds through: the model needs the outcome label + current
-            // probability to spot a mispriced market and bet it.
-            outcomeName: asStr(o.name) ?? asStr(o.outcomeName) ?? undefined,
-            // Backend returns probability as 0..100 (percent) — normalise to 0..1
-            // to match the prompt's "0..1" framing (probed 2026-06-24).
-            probability: ((p) => p == null || p < 0 || p > 100 ? undefined : p / 100)(asNum(o.probability)),
-            title,
-            freshness,
-            quality,
-            decisionSupport,
-            volumeUsd,
-            // Event-level fundamentals from the same payload (slice 2): the
-            // resolution date and the venue-reported liquidity (USD).
-            endDate: asStr(ev.endDate) ?? undefined,
-            liquidityUsd: asNum(ev.liquidity) ?? undefined,
-        }));
+        return outcomes.map((o) => {
+            // This outcome's own rule for a per-outcome event (bound by market
+            // id at the API); undefined when the rule is not per-outcome.
+            const outcomeRule = pmOutcomeRuleOf(rules, o);
+            return {
+                source,
+                slug,
+                outcomeExternalMarketId: asStr(o.externalMarketId) ??
+                    asStr(o.outcomeExternalMarketId) ??
+                    "",
+                // Carry the odds through: the model needs the outcome label + current
+                // probability to spot a mispriced market and bet it.
+                outcomeName: asStr(o.name) ?? asStr(o.outcomeName) ?? undefined,
+                // Backend returns probability as 0..100 (percent) — normalise to 0..1
+                // to match the prompt's "0..1" framing (probed 2026-06-24).
+                probability: ((p) => p == null || p < 0 || p > 100 ? undefined : p / 100)(asNum(o.probability)),
+                title,
+                freshness,
+                quality,
+                decisionSupport,
+                volumeUsd,
+                // Event-level fundamentals from the same payload (slice 2): the
+                // resolution date and the venue-reported liquidity (USD).
+                endDate: asStr(ev.endDate) ?? undefined,
+                liquidityUsd: asNum(ev.liquidity) ?? undefined,
+                ...(consensus !== undefined ? { consensus } : {}),
+                ...(rules !== undefined ? { rules } : {}),
+                ...(outcomeRule ? { outcomeRule } : {}),
+            };
+        });
     })
         .filter((m) => m.source &&
         m.slug &&
@@ -475,9 +857,11 @@ export async function observe(client, spec, state, trace) {
             change24h: asNum(price.change24h),
             change7d: asNum(price.change7d),
             // Community sentiment (already in the /market context, was stripped).
-            sentimentBullishPct: asNum(asObj(m.sentiment).bullishPct) ?? undefined,
+            ...sentimentContextOf(m),
             // Freshness lives under the response's `observation` block.
             freshness: freshnessOf(asObj(m.observation)),
+            // Server futures-reference eligibility (undefined = unknown, older API).
+            futuresEntryEligibility: futuresEntryEligibilityOf(m),
             // Canonical slug (the news graph's key): from the resolve match, else
             // the market context's observation.dataset.coinSlug.
             slug: asStr(match.slug) ??
@@ -490,8 +874,13 @@ export async function observe(client, spec, state, trace) {
         if (!marketMood) {
             const fg = asObj(m.fearGreed);
             const v = asNum(fg.value);
+            const fetchedAt = contextTimestamp(fg.fetchedAt);
             if (v != null)
-                marketMood = { fearGreed: v, label: asStr(fg.label) ?? "" };
+                marketMood = {
+                    fearGreed: v,
+                    label: asStr(fg.label) ?? "",
+                    ...(fetchedAt ? { fetchedAt } : {}),
+                };
         }
         // `indicators` capability: enrich the observation with computed TA so the
         // model reasons over structure (trend/momentum/volatility/breakout) instead
@@ -560,8 +949,9 @@ export async function observe(client, spec, state, trace) {
                     change1h: asNum(price.change1h),
                     change24h: asNum(price.change24h) ?? row.change24hPct,
                     change7d: asNum(price.change7d),
-                    sentimentBullishPct: asNum(asObj(m.sentiment).bullishPct) ?? undefined,
+                    ...sentimentContextOf(m),
                     freshness: freshnessOf(asObj(m.observation)),
+                    futuresEntryEligibility: futuresEntryEligibilityOf(m),
                     discovered: true,
                     slug: row.slug ?? asStr(asObj(asObj(m.observation).dataset).coinSlug),
                 };
@@ -611,22 +1001,30 @@ export async function observe(client, spec, state, trace) {
     let capitalPmData;
     let pmResolutions = [];
     let pmMarkets = [];
+    let pmCalibration;
     if (wantPm) {
-        const curatedCalibrationBoard = spec.objective?.primary === "calibration" &&
-            spec.model?.provider !== "mechanical";
-        const primaryDiscoveryLimit = curatedCalibrationBoard ? 30 : 12;
-        // Bias PM discovery toward CRYPTO markets the agent has a price view on — the
-        // only PM edge a price agent reliably has (probed 2026-06-24: the default board
-        // is World Cup / elections / F1, which an agent has no edge on). The discover
+        // 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 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
+        // 2026-06-24: the default board is World Cup / elections / F1). The discover
         // `q` is an AND/phrase match, so query ONE coin — the agent's TOP watchlist coin,
         // where its price view is sharpest — never the joined list (matches ~nothing).
         // Fall back to Bitcoin (always plentiful) — NEVER the general non-crypto board.
         const topCoin = (spec.risk.watchlist[0] ?? "").toUpperCase();
         const pmQuery = PM_COIN_NAMES[topCoin] ?? spec.risk.watchlist[0] ?? "Bitcoin";
-        const [pmPosR, pmDiscFirst] = await Promise.all([
+        // The own-calibration read runs alongside the PM reads (cached, bounded,
+        // never fatal). Mechanical agents have no prompt, so they skip it.
+        const [pmPosR, pmDiscFirst, calibration] = await Promise.all([
             client.pmPositions(undefined, trace),
             client.discoverPmMarkets({ q: pmQuery, limit: primaryDiscoveryLimit }, trace),
+            curatedPmBoard
+                ? readPmCalibration(client, trace)
+                : Promise.resolve(undefined),
         ]);
+        pmCalibration = calibration;
         let pmDiscR = pmDiscFirst;
         const firstCount = pmDiscR.ok
             ? asArr(asObj(pmDiscR.data).data ??
@@ -634,7 +1032,9 @@ export async function observe(client, spec, state, trace) {
                 asObj(pmDiscR.data).results).length
             : 0;
         if (firstCount < 3 && pmQuery !== "Bitcoin") {
-            const fb = await client.discoverPmMarkets({ q: "Bitcoin", limit: 12 }, trace);
+            // Same page depth as the primary: the Bitcoin board is the most
+            // churn-heavy query, so a 12-row page could filter down to nothing.
+            const fb = await client.discoverPmMarkets({ q: "Bitcoin", limit: primaryDiscoveryLimit }, trace);
             if (fb.ok)
                 pmDiscR = fb;
         }
@@ -714,13 +1114,13 @@ export async function observe(client, spec, state, trace) {
             // quoteable id NESTED at outcomes[].externalMarketId — expandPmMarkets turns
             // that into one row per quoteable outcome (eligible + not-held filtered).
             let mergedRows = expandPmMarkets(pmDiscR.data, heldPmKeys);
-            if (curatedCalibrationBoard) {
+            if (curatedPmBoard) {
                 mergedRows = mergedRows.filter((market) => !isCalibrationChurnMarket(market));
             }
             // ── Crypto-targeted secondary discover (pm_ref hallucination fix) ────────
-            // The prompt tells the model its SHARPEST PM edge is the crypto price view it
-            // JUST formed — but that is only actionable if the board actually LISTS a
-            // market for the coin it analysed. The primary board is keyed to ONE query
+            // The prompt tells the model crypto price markets are where its price view
+            // is at least relevant, but that is only usable if the board actually LISTS
+            // a market for the coin it analysed. The primary board is keyed to ONE query
             // (the top watchlist coin, with a Bitcoin fallback when that coin is thin),
             // so an agent whose top coin got displaced by the Bitcoin fallback sees NO
             // market for the coin it has a view on and an 8B model invents a pmN ref
@@ -751,7 +1151,7 @@ export async function observe(client, spec, state, trace) {
                     let secRows = expandPmMarkets(secR.data, heldPmKeys)
                         .filter((m) => titleMentionsCoin(m.title, topAnalyzed))
                         .filter((m) => !primaryEventKeys.has(`${m.source}|${m.slug}`));
-                    if (curatedCalibrationBoard) {
+                    if (curatedPmBoard) {
                         secRows = secRows.filter((market) => !isCalibrationChurnMarket(market));
                     }
                     secRows = secRows.slice(0, 4);
@@ -827,6 +1227,7 @@ export async function observe(client, spec, state, trace) {
         pmPositions,
         pmResolutions,
         pmMarkets,
+        ...(pmCalibration ? { pmCalibration } : {}),
         watch,
         news,
         // Deterministic structure flags computed from the watch indicators — the

package/dist/agent/pmContext.d.ts

@@ -1,4 +1,4 @@
-import type { Freshness, PmDecisionSupport, PmQuality } from "./types.js";
+import type { Freshness, PmCalibration, PmConsensus, PmDecisionSupport, PmQuality, PmOutcomeRule, PmSettlementRule } from "./types.js";
 export declare const PM_BLOCK_REASONS: readonly ["structurally_invalid", "stale_freshness", "freshness_unknown", "unpriced", "quote_dead", "dead_zero", "not_open", "source_degraded", "settlement_limbo"];
 export declare const PM_WARNING_REASONS: readonly ["lagging_freshness", "unproven_no_activity", "untraded_default", "play_money", "anomaly_flagged", "source_time_unverified", "sum_atypical_independent"];
 export declare const PM_FLAGS: readonly ["thinMarket", "inactiveMarket", "highAmbiguity", "nearResolution", "staleData"];
@@ -10,4 +10,13 @@ export declare const knownCode: (value: unknown, allowed: readonly string[]) =>
 export declare function sourceTimestamp(value: unknown): string | undefined;
 export declare function freshnessOf(block: Record<string, unknown>): Freshness | undefined;
 export declare function pmQualityOf(value: unknown): PmQuality | undefined;
+export declare const PM_RULES_TEXT_MAX = 500;
+export declare function pmSettlementRuleOf(event: Record<string, unknown>): PmSettlementRule | null | undefined;
+export declare const PM_OUTCOME_PRIMARY_MAX = 400;
+export declare const PM_OUTCOME_SECONDARY_MAX = 300;
+export declare function pmOutcomeRuleOf(rules: PmSettlementRule | null | undefined, outcome: Record<string, unknown>): PmOutcomeRule | undefined;
+export declare const PM_CONSENSUS_KINDS: readonly ["binary", "leader"];
+export declare function pmConsensusOf(event: Record<string, unknown>): PmConsensus | null | undefined;
+export declare const PM_CALIBRATION_MIN_SETTLED = 20;
+export declare function pmCalibrationOf(value: unknown): PmCalibration | undefined;
 export declare function pmDecisionSupportOf(value: unknown): PmDecisionSupport | undefined;