@coinrithm/mcp-trading 0.7.2 → 0.7.3

package/dist/agent/gate.js

@@ -64,9 +64,17 @@ export function evaluateGate(observation, state, policy, nowMs) {
         if (pmAvailable &&
             policy.pmEvalCooldownMinutes > 0 &&
             sinceLastCall >= policy.pmEvalCooldownMinutes * 60_000) {
-            return { fire: true, codes: ["PM_PERIODIC"], reason: "PM periodic eval (quiet price tape)" };
+            return {
+                fire: true,
+                codes: ["PM_PERIODIC"],
+                reason: "PM periodic eval (quiet price tape)",
+            };
         }
-        return { fire: false, codes: [], reason: "no trigger (flat tape, no open position)" };
+        return {
+            fire: false,
+            codes: [],
+            reason: "no trigger (flat tape, no open position)",
+        };
     }
     // A real trigger exists. Open positions are NEVER starved by budget/debounce
     // (managing a live position is always allowed); the caps below only throttle
@@ -75,7 +83,11 @@ export function evaluateGate(observation, state, policy, nowMs) {
         if (policy.maxLlmCallsPerHour > 0) {
             const recent = (state.llmCallTimestamps ?? []).filter((t) => nowMs - t < 3_600_000);
             if (recent.length >= policy.maxLlmCallsPerHour) {
-                return { fire: false, codes: codeList, reason: `hourly LLM budget ${policy.maxLlmCallsPerHour} reached` };
+                return {
+                    fire: false,
+                    codes: codeList,
+                    reason: `hourly LLM budget ${policy.maxLlmCallsPerHour} reached`,
+                };
             }
         }
         if (policy.debounceMinutes > 0) {
@@ -83,11 +95,19 @@ export function evaluateGate(observation, state, policy, nowMs) {
             if (state.lastTriggerFingerprint === fp &&
                 state.lastLlmCallAt != null &&
                 nowMs - state.lastLlmCallAt < policy.debounceMinutes * 60_000) {
-                return { fire: false, codes: codeList, reason: `debounced (same triggers within ${policy.debounceMinutes}m)` };
+                return {
+                    fire: false,
+                    codes: codeList,
+                    reason: `debounced (same triggers within ${policy.debounceMinutes}m)`,
+                };
             }
         }
     }
-    return { fire: true, codes: codeList, reason: `triggers: ${codeList.join(",")}` };
+    return {
+        fire: true,
+        codes: codeList,
+        reason: `triggers: ${codeList.join(",")}`,
+    };
 }
 // Record that this cycle spent an LLM call — feeds the budget + debounce next
 // cycle. Mutates state; the caller persists it.

package/dist/agent/index.js

@@ -4,7 +4,6 @@ import { main } from "./cli.js";
 main(process.argv.slice(2))
     .then((code) => process.exit(code))
     .catch((err) => {
-    // eslint-disable-next-line no-console
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
 });

package/dist/agent/indicators.js

@@ -133,14 +133,16 @@ export function computeIndicators(candles, opts = {}) {
         const f = Math.pow(10, figs - Math.ceil(Math.log10(Math.abs(n))));
         return Math.round(n * f) / f;
     };
-    const sigN = (n, figs = 6) => (n == null ? null : sig(n, figs));
+    const sigN = (n, figs = 6) => n == null ? null : sig(n, figs);
     return {
         asOfClose: sig(close),
         rsi14: rsi14 == null ? null : Math.round(rsi14 * 10) / 10,
         ema20: sigN(ema20),
         ema50: sigN(ema50),
         atr14: sigN(atr14),
-        bollinger: bb == null ? null : { upper: sig(bb.upper), mid: sig(bb.mid), lower: sig(bb.lower) },
+        bollinger: bb == null
+            ? null
+            : { upper: sig(bb.upper), mid: sig(bb.mid), lower: sig(bb.lower) },
         recent20: r20 == null ? null : { high: sig(r20.high), low: sig(r20.low) },
         aboveEma20: ema20 == null ? null : close > ema20,
         ema20AboveEma50: ema20 == null || ema50 == null ? null : ema20 > ema50,

package/dist/agent/manifest.js

@@ -5,7 +5,7 @@
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { sha256, stableStringify, toPosix } from "./util.js";
-import { RESOLVER_VERSION, RUNNER_VERSION, MANIFEST_SCHEMA } from "./version.js";
+import { RESOLVER_VERSION, RUNNER_VERSION, MANIFEST_SCHEMA, } from "./version.js";
 export function buildManifest(resolved, spec) {
     // configHash binds the RESOLVED spec to the resolver + schema version, so a
     // run reproduces only against the same compile (not just the same files).

package/dist/agent/mechanical.d.ts

@@ -0,0 +1,36 @@
+import { AgentSpec, Decision, Observation, PmMarket } from "./types.js";
+export declare const BENCHMARK_STRATEGIES: readonly ["market-implied", "base-rate", "random"];
+export type BenchmarkStrategy = (typeof BENCHMARK_STRATEGIES)[number];
+export declare function isBenchmarkStrategy(s: string): s is BenchmarkStrategy;
+export declare const BASE_RATE_UNINFORMATIVE = 50;
+export declare const BENCHMARK_STAKE_MUSD = 10;
+export declare const RANDOM_FORECAST_MIN = 20;
+export declare const RANDOM_FORECAST_MAX = 80;
+export declare function marketKey(m: {
+    source: string;
+    slug: string;
+    outcomeExternalMarketId: string;
+}): string;
+export declare function seededRandomForecast(seed: string): number;
+export declare function pickBenchmarkMarket(markets: PmMarket[], heldKeys?: Set<string>): PmMarket | undefined;
+export declare function benchmarkForecast(strategy: BenchmarkStrategy, market: PmMarket, dateKey: string): number | undefined;
+export interface MechanicalDecideInput {
+    strategy: string;
+    observation: Observation;
+    dateKey?: string;
+    stakeMusd?: number;
+}
+export interface MechanicalDecideResult {
+    decision: Decision;
+    log: string[];
+}
+export declare function decideMechanical(input: MechanicalDecideInput): MechanicalDecideResult;
+export interface BenchmarkAgentDefinition {
+    handle: string;
+    displayName: string;
+    strategy: BenchmarkStrategy;
+    cadenceSeconds: number;
+    spec: AgentSpec;
+    prose: string;
+}
+export declare const BENCHMARK_AGENTS: BenchmarkAgentDefinition[];

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.js

@@ -54,6 +54,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(),
@@ -296,12 +363,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 +375,59 @@ 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);
+            // ── 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}`));
+                    const secRows = expandPmMarkets(secR.data, heldPmKeys)
+                        .filter((m) => titleMentionsCoin(m.title, topAnalyzed))
+                        .filter((m) => !primaryEventKeys.has(`${m.source}|${m.slug}`))
+                        .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;