@coinrithm/mcp-trading 0.7.2 → 0.7.4

package/dist/agent/mechanical.js

@@ -0,0 +1,286 @@
+// Mechanical BENCHMARK baseline agents — the living reference line the Arena
+// measures skill against (sol-audit #7 baselines).
+//
+// These are NOT LLM agents. There is no model, no prompt, and no inference cost.
+// Each cycle the runner short-circuits the provider and computes a decision
+// deterministically from the observation, so a benchmark's forecast is fully
+// reproducible from (market, date) alone. Three strategies, ALL mechanical:
+//
+//   • market-implied — submits a forecast EXACTLY equal to the market's own
+//     probability at decision time. This is the definition of the baseline the
+//     forecast-skill scorecard measures against, and the ONLY agent for which an
+//     echo of the market price is correct BY DESIGN. Its description says
+//     BENCHMARK so the runner's anti-echo log is never read as a defect.
+//   • base-rate     — submits an uninformative 50 for every market. We do NOT
+//     invent per-category historical base rates: the observation carries no
+//     calibrated category prior, so the honest baseline is the uninformative
+//     prior. If a cheap calibrated base rate is ever surfaced in the
+//     observation, swap it in here (documented, never fabricated).
+//   • random        — submits a deterministic pseudo-random forecast in [20,80]
+//     seeded from (market key, UTC date), so a run is reproducible and a "null"
+//     forecaster's noise floor is a fair, stable comparison.
+//
+// The market PICK rule is identical across all three (highest-volume eligible
+// market that carries a usable probability and is not already held), so the
+// three benchmarks bet the SAME markets and differ ONLY in the forecast — which
+// is exactly what a clean baseline comparison needs.
+import { SPEC_VERSION, } from "./types.js";
+import { dayKey } from "./util.js";
+// ───────────────────────── Strategy vocabulary ──────────────────────────────
+export const BENCHMARK_STRATEGIES = [
+    "market-implied",
+    "base-rate",
+    "random",
+];
+export function isBenchmarkStrategy(s) {
+    return BENCHMARK_STRATEGIES.includes(s);
+}
+// The uninformative prior the base-rate benchmark submits. Documented, NOT an
+// invented per-category historical rate: the observation carries no calibrated
+// category prior to read, so 50 (maximum entropy for a binary) is the honest,
+// non-fabricated baseline. See the module header.
+export const BASE_RATE_UNINFORMATIVE = 50;
+// Tiny fixed stake (mUSD). Equal to the server's PM minimum so a benchmark bets
+// the smallest honest ticket — it exists to record forecasts, not to size risk.
+export const BENCHMARK_STAKE_MUSD = 10;
+// The random/null benchmark's forecast range (inclusive), kept away from the
+// [1,99] extremes so a "no-information" forecaster never masquerades as confident.
+export const RANDOM_FORECAST_MIN = 20;
+export const RANDOM_FORECAST_MAX = 80;
+// ───────────────────────── Deterministic helpers ────────────────────────────
+// A market's stable identity: the canonical triple, lower-cased. Doubles as the
+// dedupe key against held positions and the seed component for the random RNG.
+export function marketKey(m) {
+    return `${m.source.toLowerCase()}|${m.slug.toLowerCase()}|${m.outcomeExternalMarketId}`;
+}
+// FNV-1a 32-bit string hash — small, dependency-free, and deterministic across
+// platforms. Used only to derive the reproducible random-benchmark forecast.
+function fnv1a32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        // h *= 16777619, kept in 32-bit unsigned space via Math.imul.
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+// Deterministic pseudo-random forecast in [RANDOM_FORECAST_MIN,
+// RANDOM_FORECAST_MAX], one-decimal, seeded from (marketKey, dateKey). Same seed
+// ⇒ same value, so a re-run of the same cycle reproduces exactly.
+export function seededRandomForecast(seed) {
+    const span = RANDOM_FORECAST_MAX - RANDOM_FORECAST_MIN;
+    // 0..1 from the hash, then map into the span at one-decimal precision.
+    const unit = fnv1a32(seed) / 0xffffffff;
+    const raw = RANDOM_FORECAST_MIN + unit * span;
+    return Math.round(raw * 10) / 10;
+}
+// Clamp any probability-percentage to the backend's exclusive (0,100) rail as a
+// one-decimal value in [1,99] — the same rail the runner enforces on model
+// forecasts. Non-finite input returns undefined.
+function clampForecast(pct) {
+    if (!Number.isFinite(pct))
+        return undefined;
+    const clamped = Math.min(99, Math.max(1, pct));
+    return Math.round(clamped * 10) / 10;
+}
+// A market is a usable benchmark candidate iff it carries a real probability
+// (needed for the market-implied echo) AND a canonical triple. Keeping the SAME
+// gate for all three strategies is what makes them bet identical markets.
+function hasUsableProbability(m) {
+    return (typeof m.probability === "number" &&
+        Number.isFinite(m.probability) &&
+        !!m.source &&
+        !!m.slug &&
+        !!m.outcomeExternalMarketId);
+}
+// Deterministic pick: among eligible (usable-probability), not-already-held
+// candidates, the highest-volume market wins; ties break on the market key
+// ascending so the choice is fully reproducible. `volumeUsd` absent ⇒ treated as
+// 0, so an older backend that omits volume falls back to a pure key-ordered pick
+// (still deterministic). observe() already excludes held markets and eligibility
+// -false outcomes, so this is a belt-and-suspenders re-filter.
+export function pickBenchmarkMarket(markets, heldKeys = new Set()) {
+    const candidates = markets
+        .filter(hasUsableProbability)
+        .filter((m) => !heldKeys.has(marketKey(m)));
+    if (candidates.length === 0)
+        return undefined;
+    return candidates.reduce((best, m) => {
+        const bv = best.volumeUsd ?? 0;
+        const mv = m.volumeUsd ?? 0;
+        if (mv !== bv)
+            return mv > bv ? m : best;
+        return marketKey(m) < marketKey(best) ? m : best;
+    });
+}
+// The per-strategy forecast (1..99) for a chosen market on a given UTC date.
+// Returns undefined only if a market-implied echo can't be sized (non-finite
+// probability) — the caller then skips rather than fabricating a value.
+export function benchmarkForecast(strategy, market, dateKey) {
+    switch (strategy) {
+        case "market-implied":
+            // Echo the market's own probability (0..1 ⇒ percentage). BY DESIGN — this
+            // agent IS the market-implied baseline definition.
+            return clampForecast(Math.round((market.probability ?? NaN) * 100));
+        case "base-rate":
+            return BASE_RATE_UNINFORMATIVE;
+        case "random":
+            return clampForecast(seededRandomForecast(`${marketKey(market)}|${dateKey}`));
+    }
+}
+const heldKeysOf = (positions) => new Set(positions
+    .filter((p) => (p.status ?? "open") === "open")
+    .map((p) => marketKey({
+    source: p.source ?? "",
+    slug: p.slug ?? "",
+    outcomeExternalMarketId: p.outcomeExternalMarketId ?? "",
+})));
+// Compute one benchmark cycle's decision directly from the observation — no
+// model call. Skips (never throws) when the strategy is unknown or no eligible
+// market is available; otherwise emits a single pm_open carrying the strategy's
+// forecast. Confidence is fixed at 1 (a benchmark never abstains on confidence).
+export function decideMechanical(input) {
+    const log = [];
+    const strategy = input.strategy;
+    if (!isBenchmarkStrategy(strategy)) {
+        log.push(`mechanical: unknown benchmark strategy "${strategy}" — skipping`);
+        return {
+            decision: { decision: "skip", reason: "unknown_strategy", actions: [] },
+            log,
+        };
+    }
+    const dateKey = input.dateKey ?? dayKey();
+    const stakeMusd = input.stakeMusd ?? BENCHMARK_STAKE_MUSD;
+    const held = heldKeysOf(input.observation.pmPositions);
+    const market = pickBenchmarkMarket(input.observation.pmMarkets, held);
+    if (!market) {
+        log.push(`mechanical(${strategy}): no eligible PM market to benchmark this cycle — skipping`);
+        return {
+            decision: { decision: "skip", reason: "no_eligible_market", actions: [] },
+            log,
+        };
+    }
+    const forecast = benchmarkForecast(strategy, market, dateKey);
+    if (forecast == null) {
+        log.push(`mechanical(${strategy}): could not size a forecast for ${market.slug} — skipping`);
+        return {
+            decision: { decision: "skip", reason: "unsizable_forecast", actions: [] },
+            log,
+        };
+    }
+    const marketPct = typeof market.probability === "number"
+        ? Math.round(market.probability * 100)
+        : undefined;
+    const rationale = strategy === "market-implied"
+        ? `BENCHMARK market-implied: forecast ${forecast}% = market probability${marketPct != null ? ` ${marketPct}%` : ""} on ${market.source}/${market.slug} (echo is the baseline definition, not a defect).`
+        : strategy === "base-rate"
+            ? `BENCHMARK base-rate: uninformative ${forecast}% prior on ${market.source}/${market.slug} (no invented per-category base rate).`
+            : `BENCHMARK random: seeded pseudo-random ${forecast}% on ${market.source}/${market.slug} (reproducible from market+date).`;
+    const action = {
+        type: "pm_open",
+        ref: market.ref,
+        source: market.source,
+        slug: market.slug,
+        outcomeExternalMarketId: market.outcomeExternalMarketId,
+        stakeMusd,
+        confidence: 1,
+        forecastProbability: forecast,
+        rationaleSummary: rationale,
+    };
+    log.push(`mechanical(${strategy}): bet ${stakeMusd}mUSD on ${market.source}/${market.slug} @ forecast ${forecast}% (market ${marketPct ?? "?"}%, vol ${market.volumeUsd ?? 0})`);
+    return {
+        decision: {
+            decision: "act",
+            confidence: 1,
+            rationale,
+            actions: [action],
+        },
+        log,
+    };
+}
+// A complete, valid AgentSpec for a mechanical benchmark. The strategy travels
+// in model.name (provider "mechanical"); the runner reads it there. Caps are set
+// so a benchmark NEVER self-disables (all kill-switches off — it is a permanent
+// reference line) and never abstains on confidence (minConfidence 0). PM-only,
+// tiny fixed stake, always-fire trigger policy (mechanical is free, so there is
+// no reason to gate a cycle).
+function benchmarkSpec(strategy, cadenceSeconds) {
+    const label = LABELS[strategy];
+    return {
+        name: `bench-${strategy}`,
+        description: `BENCHMARK (${label}) — a mechanical, non-LLM baseline reference agent. ${DESCRIPTIONS[strategy]} It is NOT a skill agent; it exists so the Arena can show real agents beating (or not) a fixed, deterministic baseline. Paper-only, zero inference cost.`,
+        spec: SPEC_VERSION,
+        trigger: { cadence: `${Math.round(cadenceSeconds / 60)}m` },
+        model: { provider: "mechanical", name: strategy },
+        venues: ["pm"],
+        risk: {
+            maxLeverage: 1,
+            perTradeMarginMusd: BENCHMARK_STAKE_MUSD, // per-trade stake cap = the tiny fixed stake
+            maxConcurrentPositions: 1000, // PM opens aren't capped by this; kept generous
+            requireStopLoss: false,
+            // Discovery needs a query coin; PM-only agents still seed discover from the
+            // watchlist. Majors give the broadest, most-liquid crypto board to benchmark.
+            watchlist: ["BTC", "ETH", "SOL"],
+        },
+        limits: {
+            maxTradesPerDay: 0, // 0 = unlimited: a benchmark records as many markets as it sees
+            maxWritesPerCycle: 1, // one benchmarked market per cycle
+            maxDailyLossMusd: 0, // disabled — a reference line never risk-stops
+            maxOpenMarginMusd: 100000,
+        },
+        abstention: {
+            onStaleData: false,
+            onWeakSignal: false,
+            onMissingQuote: false,
+            onInsufficientBalance: false,
+            minConfidence: 0, // a benchmark never abstains on confidence
+        },
+        sync: { requirePollBeforeWrite: false },
+        killSwitch: {
+            maxDrawdownMusd: 0,
+            maxConsecutiveRejects: 0,
+            maxConsecutiveModelFailures: 0,
+            onRateLimitPressure: false,
+        },
+        objective: {
+            primary: "calibration",
+            secondary: ["benchmark", strategy],
+            horizon: "all",
+        },
+        capabilities: [],
+        triggerPolicy: {
+            mode: "always", // mechanical = free; always evaluate, never gate a cycle
+            skipLlmWhenNoTrigger: false,
+            alwaysManageOpenPositions: true,
+            maxLlmCallsPerHour: 0,
+            debounceMinutes: 0,
+            pmEvalCooldownMinutes: 0,
+        },
+    };
+}
+const LABELS = {
+    "market-implied": "market-implied",
+    "base-rate": "base-rate",
+    random: "random/null",
+};
+const DESCRIPTIONS = {
+    "market-implied": "Each cycle it picks the highest-volume eligible market and submits a forecast EXACTLY equal to the market's own probability — the market-implied baseline every skill claim is measured against.",
+    "base-rate": "It submits an uninformative 50% prior on every market (no fabricated per-category base rate).",
+    random: "It submits a deterministic pseudo-random forecast in [20,80] seeded from the market and date, giving a reproducible no-information noise floor.",
+};
+// Human-readable prose stored on the row. NEVER fed to a model (mechanical agents
+// don't reason) — it exists so the Arena/terminal can describe the agent honestly.
+function benchmarkProse(strategy) {
+    return `# Benchmark: ${LABELS[strategy]}\n\nThis is a MECHANICAL BENCHMARK baseline, not a skill agent. ${DESCRIPTIONS[strategy]}\n\nIt calls no language model, has zero inference cost, and is fully deterministic and reproducible. It exists purely as a public reference line: the Arena compares real agents' calibration against these baselines. Paper-only.`;
+}
+// Default cadence: hourly. Frequent enough to accumulate a steady benchmark
+// record, slow enough that the three benchmarks don't churn the discovered board.
+const DEFAULT_BENCHMARK_CADENCE_SECONDS = 3600;
+export const BENCHMARK_AGENTS = BENCHMARK_STRATEGIES.map((strategy) => ({
+    handle: `bench-${strategy}`,
+    displayName: `Benchmark: ${LABELS[strategy]}`,
+    strategy,
+    cadenceSeconds: DEFAULT_BENCHMARK_CADENCE_SECONDS,
+    spec: benchmarkSpec(strategy, DEFAULT_BENCHMARK_CADENCE_SECONDS),
+    prose: benchmarkProse(strategy),
+}));

package/dist/agent/observe.d.ts

@@ -4,4 +4,8 @@ export interface ObserveOutput {
     observation: Observation;
     skip?: string;
 }
+export declare function isCalibrationChurnMarket(market: {
+    slug?: string;
+    title?: string;
+}): boolean;
 export declare function observe(client: CoinRithmClient, spec: AgentSpec, state: RunState, trace?: AgentTrace): Promise<ObserveOutput>;

package/dist/agent/observe.js

@@ -28,6 +28,16 @@ const PM_COIN_NAMES = {
     UNI: "Uniswap",
     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.
+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 ?? ""}`);
+}
 // Fetch candles for one coin and reduce them to a compact indicator bundle.
 // Tolerant by design: any failure (HTTP error, malformed/sparse candles) returns
 // null so the cycle proceeds with price-only context rather than skipping.
@@ -54,6 +64,73 @@ function freshnessOf(block) {
     const status = asStr(fr.status);
     return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
 }
+// Does a market title reference the given watchlist coin? Matches on the PM coin
+// NAME ("Bitcoin") or the ticker ("BTC"), case-insensitively — the discover `q`
+// is a phrase match so a q=Bitcoin result reliably carries "Bitcoin"/"BTC" in the
+// title. Used both to decide whether the primary board already covers the coin the
+// agent analysed and to keep the secondary (crypto-targeted) fetch on-topic.
+function titleMentionsCoin(title, symbol) {
+    const t = (title ?? "").toLowerCase();
+    if (!t)
+        return false;
+    const name = (PM_COIN_NAMES[symbol] ?? symbol).toLowerCase();
+    const sym = symbol.toLowerCase();
+    return t.includes(name) || t.includes(sym);
+}
+// Expand one raw /api/agent/pm/discover payload into per-outcome PmMarket rows
+// (WITHOUT a ref — refs are stamped once over the final merged+sliced list so they
+// stay contiguous pm1..pmN). One row per quoteable outcome; drops outcomes the
+// 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) {
+    const dd = asObj(discData);
+    return (asArr(dd.data ?? dd.markets ?? dd.results)
+        .map(asObj)
+        .flatMap((ev) => {
+        const source = (asStr(ev.source) ?? "").toLowerCase();
+        const slug = (asStr(ev.slug) ?? "").toLowerCase();
+        // Keep titles SHORT: the model only needs to recognise the market.
+        // Untrimmed titles, one per outcome across many events, ballooned the
+        // prompt to ~69k tokens (413s on small-context free models).
+        const title = (asStr(ev.title) ?? asStr(ev.question) ?? "").slice(0, 80);
+        const freshness = freshnessOf(ev); // freshness is event-level
+        // Event-level 24h volume (the discover payload's `volume24h`, USD). Feeds
+        // 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;
+        // 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
+        // model never bets a market that would fail the binary entry gate at
+        // quote. Back-compat: an older backend omits `eligible` (undefined) ->
+        // the outcome is kept (current behaviour).
+        const outcomes = asArr(ev.outcomes)
+            .map(asObj)
+            .filter((o) => o.eligible !== false)
+            .slice(0, 3);
+        // A market with no outcomes array still round-trips a flat fallback row.
+        const rows = outcomes.length > 0 ? outcomes : [ev];
+        return rows.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 ? undefined : p > 1 ? p / 100 : p))(asNum(o.probability)),
+            title,
+            freshness,
+            volumeUsd,
+        }));
+    })
+        .filter((m) => m.source && m.slug && m.outcomeExternalMarketId)
+        // Drop already-held markets so the model only sees markets it can actually
+        // open — done BEFORE any slice so held positions don't consume candidate slots.
+        .filter((m) => !heldPmKeys.has(`${m.source.toLowerCase()}|${m.slug.toLowerCase()}|${m.outcomeExternalMarketId}`)));
+}
 function emptyObservation(state, scopes = []) {
     return {
         asOf: state.cursor ?? new Date().toISOString(),
@@ -222,6 +299,9 @@ export async function observe(client, spec, state, trace) {
     let pmResolutions = [];
     let pmMarkets = [];
     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
@@ -232,7 +312,7 @@ export async function observe(client, spec, state, trace) {
         const pmQuery = PM_COIN_NAMES[topCoin] ?? spec.risk.watchlist[0] ?? "Bitcoin";
         const [pmPosR, pmDiscFirst] = await Promise.all([
             client.pmPositions(undefined, trace),
-            client.discoverPmMarkets({ q: pmQuery, limit: 12 }, trace),
+            client.discoverPmMarkets({ q: pmQuery, limit: primaryDiscoveryLimit }, trace),
         ]);
         let pmDiscR = pmDiscFirst;
         const firstCount = pmDiscR.ok
@@ -296,12 +376,11 @@ export async function observe(client, spec, state, trace) {
                 .slice(0, 25);
         }
         if (pmDiscR.ok) {
-            const dd = asObj(pmDiscR.data);
             // Anti-churn: exclude markets the agent ALREADY holds an open position in
             // from the candidate list BEFORE it reaches the prompt — so the model never
             // sees (and re-picks) a held market only to have the runner/server reject it
             // as a duplicate, burning a whole cycle. Keyed source|slug|outcomeExternalMarketId
-            // (lower-cased to match the discover rows below). The runner preflight guard
+            // (lower-cased to match the discover rows). The runner preflight guard
             // (duplicate_intent) + server dedup (duplicate_open) remain the backstops.
             // Side-agnostic = no re-bet/hedge on a held outcome, matching the runner policy.
             const heldPmKeys = new Set(pmPositions
@@ -309,57 +388,65 @@ export async function observe(client, spec, state, trace) {
                 .map((p) => `${(p.source ?? "").toLowerCase()}|${(p.slug ?? "").toLowerCase()}|${p.outcomeExternalMarketId ?? ""}`));
             // Real /api/agent/pm/discover payload: { data: [event], pagination, meta }.
             // Each EVENT carries source/slug/title/freshness at the top level and the
-            // quoteable id NESTED at outcomes[].externalMarketId — so expand one
-            // PmMarket per quoteable outcome. (Tolerant `markets`/`results` and flat
-            // `outcomeExternalMarketId` fallbacks kept for older/mocked shapes.)
-            pmMarkets = asArr(dd.data ?? dd.markets ?? dd.results)
-                .map(asObj)
-                .flatMap((ev) => {
-                const source = (asStr(ev.source) ?? "").toLowerCase();
-                const slug = (asStr(ev.slug) ?? "").toLowerCase();
-                // Keep titles SHORT: the model only needs to recognise the market.
-                // Untrimmed titles, one per outcome across many events, ballooned the
-                // prompt to ~69k tokens (413s on small-context free models).
-                const title = (asStr(ev.title) ?? asStr(ev.question) ?? "").slice(0, 80);
-                const freshness = freshnessOf(ev); // freshness is event-level
-                // 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
-                // model never bets a market that would fail the binary entry gate at
-                // quote. Back-compat: an older backend omits `eligible` (undefined) →
-                // the outcome is kept (current behaviour).
-                const outcomes = asArr(ev.outcomes)
-                    .map(asObj)
-                    .filter((o) => o.eligible !== false)
-                    .slice(0, 3);
-                // A market with no outcomes array still round-trips a flat fallback row.
-                const rows = outcomes.length > 0 ? outcomes : [ev];
-                return rows.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 (was stripped).
-                    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 ? undefined : p > 1 ? p / 100 : p))(asNum(o.probability)),
-                    title,
-                    freshness,
-                }));
-            })
-                .filter((m) => m.source && m.slug && m.outcomeExternalMarketId)
-                // Drop already-held markets (see heldPmKeys above) so the model only sees
-                // markets it can actually open — done BEFORE the slice so held positions
-                // don't consume the limited candidate slots.
-                .filter((m) => !heldPmKeys.has(`${m.source.toLowerCase()}|${m.slug.toLowerCase()}|${m.outcomeExternalMarketId}`))
-                // Hard cap the PM block: a handful of fresh markets is plenty to pick from.
+            // 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) {
+                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 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
+            // (→ pm_ref_unknown, wasted cycle). When the top ANALYSED coin (its sharpest
+            // edge) has no market in the primary board, fire ONE extra discover for that
+            // coin and MERGE it in — giving the model a real ref to bet instead of a
+            // hallucinated one. Budget: at most a single additional CoinRithm data-API
+            // read, and only on cycles where the top coin is actually missing; the shared
+            // free-tier model-call RateBudget (scheduler) is untouched — this is a read,
+            // not an LLM call, and the client already backs off on 429.
+            const analyzedCoins = watch
+                .filter((w) => w.coinId)
+                .map((w) => w.symbol.toUpperCase());
+            const topAnalyzed = analyzedCoins[0];
+            const primaryCoversTop = !topAnalyzed ||
+                mergedRows.some((m) => titleMentionsCoin(m.title, topAnalyzed));
+            if (topAnalyzed && !primaryCoversTop) {
+                const targetName = PM_COIN_NAMES[topAnalyzed] ?? topAnalyzed;
+                // limit 6 (not ~5): the eligible/held/dedupe filters shave the list, and we
+                // then cap the merged contribution to 4 targeted rows below.
+                const secR = await client.discoverPmMarkets({ q: targetName, limit: 6 }, trace);
+                if (secR.ok) {
+                    // Dedupe the secondary rows against the primary list by source+slug (event
+                    // key) so a market already on the board is never shown twice, and keep only
+                    // rows that actually reference the targeted coin (a fuzzy backend match
+                    // can't dilute the board with off-topic events).
+                    const primaryEventKeys = new Set(mergedRows.map((m) => `${m.source}|${m.slug}`));
+                    let secRows = expandPmMarkets(secR.data, heldPmKeys)
+                        .filter((m) => titleMentionsCoin(m.title, topAnalyzed))
+                        .filter((m) => !primaryEventKeys.has(`${m.source}|${m.slug}`));
+                    if (curatedCalibrationBoard) {
+                        secRows = secRows.filter((market) => !isCalibrationChurnMarket(market));
+                    }
+                    secRows = secRows.slice(0, 4);
+                    // Reserve slots for the targeted rows so the 12-cap can't slice off the
+                    // very markets the secondary fetch exists to surface. Primary rows keep
+                    // priority; the targeted rows are appended.
+                    if (secRows.length > 0) {
+                        const primaryBudget = Math.max(0, 12 - secRows.length);
+                        mergedRows = [...mergedRows.slice(0, primaryBudget), ...secRows];
+                    }
+                }
+            }
+            // Hard cap the PM block (a handful of fresh markets is plenty) and stamp a
+            // short, stable per-cycle ref (pm1…pmN) the model copies instead of the long
+            // outcomeExternalMarketId. Refs are assigned AFTER the merge + slice so they
+            // are a contiguous 1..N matching exactly what the prompt shows.
+            pmMarkets = mergedRows
                 .slice(0, 12)
-                // Stamp a short, stable per-cycle ref (pm1…pmN) the model copies instead of
-                // the long outcomeExternalMarketId. Assigned AFTER the slice so refs are a
-                // contiguous 1..N matching exactly what the prompt shows.
                 .map((m, i) => ({ ...m, ref: `pm${i + 1}` }));
         }
     }

package/dist/agent/prompt.d.ts

@@ -1,6 +1,8 @@
 import { AgentSpec, Observation, PmResolution } from "./types.js";
 export declare function formatPmResolutions(resolutions: PmResolution[]): string[];
-export declare function buildSystemPrompt(spec: AgentSpec, mergedProse: string): string;
+export declare function buildSystemPrompt(spec: AgentSpec, mergedProse: string, opts?: {
+    includeForecast?: boolean;
+}): string;
 export declare function buildUserPrompt(obs: Observation, journal?: Array<{
     at: string;
     did: string;

package/dist/agent/prompt.js

@@ -33,18 +33,24 @@ export function formatPmResolutions(resolutions) {
         `Resolved since last cycle: ${items.join("; ")}.`,
     ];
 }
-export function buildSystemPrompt(spec, mergedProse) {
+export function buildSystemPrompt(spec, mergedProse, 
+// includeForecast (default OFF here; the runner passes the house-agent flag):
+// when true, pm_open asks the model for its OWN independent forecastProbability
+// (1..99) — its probability the backed side wins, judged from the question, NOT
+// echoed from the market price. This feeds the agent's public calibration record.
+opts = {}) {
     const r = spec.risk;
     const v = spec.venues;
+    const includeForecast = opts.includeForecast === true;
     const actions = [];
     if (v.includes("futures")) {
-        actions.push('{"type":"futures_open","symbol","side":"long"|"short","leverage","marginMusd","stopLossPrice","takeProfitPrice","confidence":0..1}', '{"type":"futures_close","positionId","fraction"}', '{"type":"futures_set_sltp","positionId","stopLossPrice","takeProfitPrice"}', 'FUTURES TRIGGER RULES (the server rejects the WHOLE open otherwise): a LONG\'s takeProfitPrice must be ABOVE the current mark and stopLossPrice BELOW it (and above liquidationPrice); a SHORT is inverted (TP below mark, SL above). Every open position in observation.openPositions shows entryPrice, markPrice, liquidationPrice, stopLossPrice, takeProfitPrice — read them and place triggers on the correct side. NEVER attach stopLossPrice/takeProfitPrice to a futures_open for a symbol you ALREADY hold (the server treats it as an add and rejects it) — adjust that position with futures_set_sltp on its positionId instead.');
+        actions.push('{"type":"futures_open","symbol","side":"long"|"short","leverage","marginMusd","stopLossPrice","takeProfitPrice","confidence":0..1}', '{"type":"futures_close","positionId","fraction"}', '{"type":"futures_set_sltp","positionId","stopLossPrice","takeProfitPrice"}', "FUTURES TRIGGER RULES (the server rejects the WHOLE open otherwise): a LONG's takeProfitPrice must be ABOVE the current mark and stopLossPrice BELOW it (and above liquidationPrice); a SHORT is inverted (TP below mark, SL above). Every open position in observation.openPositions shows entryPrice, markPrice, liquidationPrice, stopLossPrice, takeProfitPrice — read them and place triggers on the correct side. NEVER attach stopLossPrice/takeProfitPrice to a futures_open for a symbol you ALREADY hold (the server treats it as an add and rejects it) — adjust that position with futures_set_sltp on its positionId instead.");
     }
     if (v.includes("spot")) {
         actions.push('{"type":"spot_order","symbol","side":"buy"|"sell","orderType":"market"|"limit"|"stop","quantity","limitPrice","stopPrice","confidence":0..1}', '{"type":"spot_cancel","orderId"}');
     }
     if (v.includes("pm")) {
-        actions.push('{"type":"pm_open","ref":"pmN","stakeMusd","confidence":0..1}  (set "ref" to the `ref` of the ONE observation.pmMarkets entry you are betting — e.g. "pm3" — copied EXACTLY; stakeMusd >= 10)');
+        actions.push(`{"type":"pm_open","ref":"pmN","stakeMusd","confidence":0..1${includeForecast ? ',"forecastProbability":1..99' : ""}}  (set "ref" to one of the refs listed THIS cycle (pm1..pmN) — the \`ref\` of the ONE observation.pmMarkets entry you are betting, e.g. "pm3", copied EXACTLY; a ref NOT in this cycle's list is rejected as pm_ref_unknown and wastes the cycle; stakeMusd >= 10${includeForecast ? '; set "forecastProbability" to YOUR OWN probability 1-99 that this outcome wins — see the forecast rule below' : ""})`);
     }
     return [
         "You operate a CoinRithm PAPER-TRADING agent (simulated 50,000 mUSD; not real money, not financial advice).",
@@ -65,7 +71,12 @@ export function buildSystemPrompt(spec, mergedProse) {
             : []),
         "- prediction markets are a FIRST-CLASS venue for you — a pm_open is as real a trade as a futures/spot open, not an afterthought. Each observation.pmMarkets entry carries a short `ref` (pm1, pm2, …), an `outcome` label, and `prob` (0..1, the market's CURRENT odds). BET (pm_open) an outcome when YOUR estimate of its true probability differs MATERIALLY from the market's — that gap is your edge (e.g. prob 0.35 but you think it's really ~0.55 -> buy). Skip only markets pinned near 0 or 1 (no edge left). Every entry in observation.pmMarkets is already filtered to one you CAN open (binary/settlement-grade) — so a listed market will not bounce at quote. Pick ONLY a listed market and identify it by copying its `ref` into the action; min stake 10 mUSD. Do NOT re-bet a market+outcome you ALREADY hold (check observation.pmPositions) — that is churn and will be rejected; bet a DIFFERENT market or skip.",
         "- PM stake is a SEPARATE budget from your futures margin: the futures margin cap (maxOpenMarginMusd) does NOT limit pm_open. So when your futures are at the margin/position cap — you hold the max, or a futures_open keeps getting REJECTED with open_margin_exceeds_cap — prediction markets are STILL fully open to you. PIVOT to pm_open on a mispriced market instead of re-proposing a futures_open that will just be rejected: a rejected open wastes the entire cycle, an eligible PM bet does not.",
-        "- YOUR SHARPEST PM EDGE is the crypto price view you JUST formed: crypto PM markets resolve on the very prices you analyse, so you have a genuine information edge there that you do NOT have on coin futures alone. EVERY cycle you reach a price conviction, it is REQUIRED that you scan observation.pmMarkets for a crypto market that same view prices wrong and, if one is materially mispriced, open it with pm_open — treat that mispricing exactly like a flagged coin setup (an ACT, not a skip). If you are bearish BTC, a 'BTC above $X by <date>' priced high is a NO; if bullish ETH, an 'ETH above $Y' priced low is a YES. Leaving a clearly mispriced crypto market untraded is the same mistake as ignoring a flagged setup. (For non-crypto events you have no special edge; skip unless the odds are obviously off.)",
+        "- YOUR SHARPEST PM EDGE is the crypto price view you JUST formed: crypto PM markets resolve on the very prices you analyse, so you have a genuine information edge there that you do NOT have on coin futures alone. EVERY cycle you reach a price conviction, it is REQUIRED that you scan observation.pmMarkets for a LISTED crypto market that same view prices wrong and, if one is materially mispriced, open it with pm_open by its `ref` — treat that mispricing exactly like a flagged coin setup (an ACT, not a skip). If you are bearish BTC, a 'BTC above $X by <date>' priced high is a NO; if bullish ETH, an 'ETH above $Y' priced low is a YES. ESCAPE HATCH — only the markets actually listed in observation.pmMarkets THIS cycle (pm1..pmN) are bettable: if NONE of them matches the coin or view you formed, that is a legitimate SKIP for PM (say so in one clause and move on) — do NOT invent, guess, or increment a ref for a market you wish existed, because a made-up ref is rejected (pm_ref_unknown) and wastes the whole cycle exactly like a rejected open. The mistake to avoid is leaving a LISTED, clearly mispriced crypto market untraded — a mispricing that is NOT on this cycle's board is simply not actionable now, not a miss. (For non-crypto events you have no special edge; skip unless the odds are obviously off.)",
+        ...(includeForecast
+            ? [
+                "- FORECAST RULE (pm_open forecastProbability): before you look at what the market is pricing, decide YOUR OWN probability the outcome you are backing actually WINS — reason ONLY from the question, its resolution criteria, and the deadline. Put that number (1-99, whole or one decimal) in `forecastProbability`. This is graded against reality as your PUBLIC calibration record, so it must be YOUR judgement, NOT the market's: do NOT copy, round, or anchor it to the observation.pmMarkets `prob`. It is FINE if your honest forecast happens to land on the market's number — but reaching that by echoing the price defeats the point. If you genuinely cannot form an independent view, OMIT the field rather than parroting the market (an absent forecast is better than a fake one, and it never blocks the bet).",
+            ]
+            : []),
         `- abstention.minConfidence ${spec.abstention.minConfidence}: opens below this are rejected, so act with genuine conviction — but routine caution is no reason to sit out a clear setup`,
         ...(spec.capabilities.includes("indicators")
             ? [
@@ -95,14 +106,14 @@ export function buildSystemPrompt(spec, mergedProse) {
         "",
         "## How to act — a decisive trader in character, not a bystander",
         "You ARE the character in the strategy above; trade like it. When you have a clear read — even a moderate-confidence one — TAKE THE POSITION, sized within your caps and protected with a stop. You wake every cycle and people watch you live: an agent that watches forever and never commits is useless to them and to itself.",
-        'Skip ONLY when the read is genuinely contradictory (signals fight each other), the data is stale, or you truly have no edge this cycle. A quiet tape where your thesis still has a small but REAL edge is an ACT, not a skip — take it, small, with a stop. Do not confuse caution with paralysis.',
+        "Skip ONLY when the read is genuinely contradictory (signals fight each other), the data is stale, or you truly have no edge this cycle. A quiet tape where your thesis still has a small but REAL edge is an ACT, not a skip — take it, small, with a stop. Do not confuse caution with paralysis.",
         'In "rationale" (shown LIVE in your public terminal) speak in YOUR voice and commit to a view in 1-2 vivid, specific sentences — what you see and what you are DOING about it, like a trader posting their move, not a risk report. Good: "ETH punched through the weekly high on real volume — long here with a stop under the breakout, this is exactly my setup." Weak: "conditions are mixed, waiting for clarity." Keep "reason" a short label.',
         "",
         "## Flagged setups this cycle — your wake-up list (observation.setups)",
         "A deterministic scan already checked every watchlist coin and put the ones with real, tradeable structure RIGHT NOW into observation.setups — each has symbol, kind, bias, strength, and a factual note (trend / RSI / breakout / ATR reads). This is your shortlist; you do NOT need to re-derive whether a setup exists.",
         '- If observation.setups is NON-EMPTY: act on the strongest one that fits YOUR strategy. The `bias` is the trend-following read; if you are a contrarian / mean-reversion trader, FADE it with the same facts (e.g. a downtrend that is also "RSI oversold" is YOUR long). Skipping a flagged setup needs a SPECIFIC reason tied to your thesis — "no clear setup" is NOT a valid skip when setups are listed.',
         "- If observation.setups is EMPTY: no coin has a flagged structure right now — but BEFORE you skip, check observation.pmMarkets for a crypto market your current read prices wrong (a PM mispricing is a valid ACT even with zero coin setups). Only then, if nothing is mispriced, skip new entries and just manage any open positions.",
-        '- A setup tagged `held` (held: long|short) is a position you ALREADY hold. Do NOT propose a new open on it — that only hits the margin cap and wastes the cycle. MANAGE it instead: trail the stop toward your target, ADD only if you have margin room AND fresh conviction, or cut if the thesis broke.',
+        "- A setup tagged `held` (held: long|short) is a position you ALREADY hold. Do NOT propose a new open on it — that only hits the margin cap and wastes the cycle. MANAGE it instead: trail the stop toward your target, ADD only if you have margin room AND fresh conviction, or cut if the thesis broke.",
         "",
         "## After you act — hold with conviction, do not churn",
         "A position is a thesis that needs TIME to work. Once you are in WITH a stop, let the stop or your target close it: do NOT bail on the next cycle over a small adverse tick, and do NOT manually close a fresh position unless the thesis is structurally invalidated (the level broke, the trend flipped) — not merely because price wiggled against you. A trade opened and closed minutes later just donates the round-trip fee + spread to noise.",