@coinrithm/mcp-trading 0.7.4 → 0.7.6

package/dist/agent/cli.js

@@ -7,7 +7,7 @@
 import { mkdirSync, writeFileSync, existsSync, statSync, readFileSync, openSync, closeSync, unlinkSync, } from "node:fs";
 import { resolve as resolvePath, dirname, join, basename } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { resolveAgent, ResolveError, mergeProseParts, isSkillProseSource, } from "./resolve.js";
+import { resolveAgent, ResolveError, mergeProseParts, isSkillProseSource, hostedProseBudget, HOSTED_PROSE_MAX_CHARS, } from "./resolve.js";
 import { buildSpec, loadAgent } from "./skill.js";
 import { validateSkill } from "./skillValidator.js";
 import { strictLint } from "./strictLint.js";
@@ -101,6 +101,27 @@ export function cmdValidate(path, mode = "self-host") {
     const spec = buildSpec(raw);
     const lint = [...strictLint(raw), ...checkCapabilityDrift(resolved, spec)];
     const v = validateSkill({ spec, body: resolved.mergedProse, raw }, mode);
+    // Hosted-only: the managed deploy/edit API caps the merged strategy prose at
+    // HOSTED_PROSE_MAX_CHARS and REVERTS the save when it is exceeded, so a
+    // bundle that resolves and lints perfectly can still be undeployable through
+    // the Studio. Measured 2026-08-19 after a user hit the wall: 4 of 9 example
+    // bundles were over (contrarian-carl 8,159, mia 8,175, olivia 8,587,
+    // pia-pump-fader 11,787) while the corpus README claimed they all pass
+    // `validate --hosted`. Checking it here is what makes that claim true and
+    // stops the corpus drifting back over the wall.
+    if (mode === "hosted") {
+        const budget = hostedProseBudget(resolved.mergedProse);
+        if (!budget.fits) {
+            lint.push({
+                code: "hosted_prose_too_long",
+                path: "character/*.md",
+                message: `merged strategy prose is ${budget.used} chars, ${budget.over} over the hosted ` +
+                    `limit of ${HOSTED_PROSE_MAX_CHARS} — the managed deploy would reject this and ` +
+                    `revert to the template. Self-host has no such cap. Note the count includes a ` +
+                    `"<!-- path -->" header per prose file, not just the bodies.`,
+            });
+        }
+    }
     const lintFatal = mode === "hosted";
     const lines = [];
     for (const i of lint) {

package/dist/agent/client.d.ts

@@ -37,6 +37,7 @@ export declare class CoinRithmClient {
         coinId?: string;
     }, trace?: AgentTrace): Promise<ApiResult>;
     resolve(q: string, trace?: AgentTrace): Promise<ApiResult>;
+    cryptoMovers(direction: "gainers" | "losers", limit: number, trace?: AgentTrace): Promise<ApiResult>;
     market(coinId: string, trace?: AgentTrace): Promise<ApiResult>;
     candles(coinId: string, range: string, trace?: AgentTrace): Promise<ApiResult>;
     trades(query?: {

package/dist/agent/client.js

@@ -18,6 +18,10 @@ function traceHeaders(trace) {
         h["X-CoinRithm-Strategy-Label"] = trace.strategyLabel;
     if (typeof trace.confidence === "number")
         h["X-CoinRithm-Confidence"] = String(trace.confidence);
+    if (trace.observationHash)
+        h["X-CoinRithm-Observation-Hash"] = trace.observationHash;
+    if (trace.indicatorVersion)
+        h["X-CoinRithm-Indicator-Version"] = trace.indicatorVersion;
     return h;
 }
 export class CoinRithmClient {
@@ -112,6 +116,13 @@ export class CoinRithmClient {
     resolve(q, trace) {
         return this.request("GET", "/api/agent/resolve", { query: { q }, trace });
     }
+    // Keyless public universe scan (top 24h movers). The Bearer header rides
+    // along harmlessly — the /api/coins routes are public and ignore it.
+    cryptoMovers(direction, limit, trace) {
+        return this.request("GET", direction === "losers"
+            ? "/api/coins/top-losers"
+            : "/api/coins/top-gainers", { query: { limit }, trace });
+    }
     market(coinId, trace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { trace });
     }

package/dist/agent/decision.d.ts

@@ -53,16 +53,22 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     positionId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
     stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
     takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
+    rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     type: "futures_set_sltp";
     stopLossPrice?: any;
     takeProfitPrice?: any;
     positionId?: any;
+    confidence?: any;
+    rationaleSummary?: string | undefined;
 }, {
     type: "futures_set_sltp";
     stopLossPrice?: unknown;
     takeProfitPrice?: unknown;
     positionId?: unknown;
+    confidence?: unknown;
+    rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_order">;
     symbol: z.ZodString;
@@ -96,11 +102,17 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_cancel">;
     orderId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
+    rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     type: "spot_cancel";
+    confidence?: any;
+    rationaleSummary?: string | undefined;
     orderId?: any;
 }, {
     type: "spot_cancel";
+    confidence?: unknown;
+    rationaleSummary?: string | undefined;
     orderId?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"pm_open">;

package/dist/agent/decision.js

@@ -59,6 +59,13 @@ const futuresSetSltp = z
     positionId: num(z.number()),
     stopLossPrice: num(z.number()).nullable().optional(),
     takeProfitPrice: num(z.number()).nullable().optional(),
+    // Accepted-and-unused: the output contract asks for per-action confidence,
+    // so models copy it onto EVERY action. The two schemas that lacked it were
+    // fail-closing whole decisions under .strict() (~180-200 discarded
+    // fleet-wide per day, live-measured 2026-08-19). Same tolerance the four
+    // trade actions already have.
+    confidence,
+    rationaleSummary: z.string().optional(),
 })
     .strict();
 const spotOrder = z
@@ -78,6 +85,9 @@ const spotCancel = z
     .object({
     type: z.literal("spot_cancel"),
     orderId: num(z.number()),
+    // Same accepted-and-unused tolerance as futures_set_sltp above.
+    confidence,
+    rationaleSummary: z.string().optional(),
 })
     .strict();
 // pm_open accepts EITHER a short ref (pm1…pmN, what the prompt now asks for) OR

package/dist/agent/indicators.d.ts

@@ -1,3 +1,4 @@
+export declare const INDICATOR_VERSION = "coinrithm.indicators.v1";
 export interface Candle {
     open: number;
     high: number;

package/dist/agent/indicators.js

@@ -10,6 +10,9 @@
 //
 // Every function returns null when there are too few candles, so callers can
 // omit an indicator from the observation rather than emit a misleading number.
+// Bump whenever indicator inputs, defaults, formulas, rounding, or output
+// semantics change. Stored beside each observation hash and in manifest.lock.
+export const INDICATOR_VERSION = "coinrithm.indicators.v1";
 const closesOf = (c) => c.map((x) => x.close);
 const finite = (n) => Number.isFinite(n);
 // Simple moving average of the last `period` values.

package/dist/agent/manifest.d.ts

@@ -4,6 +4,7 @@ export interface AgentManifest {
     spec: string;
     resolverVersion: string;
     runnerVersion: string;
+    indicatorVersion: string;
     resolvedConfig: Record<string, unknown>;
     resolvedSpec: AgentSpec;
     provenance: Provenance;

package/dist/agent/manifest.js

@@ -6,12 +6,14 @@ 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 { INDICATOR_VERSION } from "./indicators.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).
     const configHash = sha256(stableStringify({
         resolvedSpec: spec,
         resolverVersion: RESOLVER_VERSION,
+        indicatorVersion: INDICATOR_VERSION,
         schema: MANIFEST_SCHEMA,
     }));
     return {
@@ -19,6 +21,7 @@ export function buildManifest(resolved, spec) {
         spec: spec.spec || "coinrithm.agent.v1",
         resolverVersion: RESOLVER_VERSION,
         runnerVersion: RUNNER_VERSION,
+        indicatorVersion: INDICATOR_VERSION,
         resolvedConfig: resolved.rawFrontmatter,
         resolvedSpec: spec,
         provenance: resolved.provenance,

package/dist/agent/observationReceipt.d.ts

@@ -0,0 +1,6 @@
+import type { Observation } from "./types.js";
+export interface ObservationReceipt {
+    observationHash: string;
+    indicatorVersion: string;
+}
+export declare function buildObservationReceipt(observation: Observation): ObservationReceipt;

package/dist/agent/observationReceipt.js

@@ -0,0 +1,10 @@
+// A compact, privacy-safe receipt for the exact structured observation used by
+// one decision. We persist the digest, never the full prompt or model output.
+import { INDICATOR_VERSION } from "./indicators.js";
+import { sha256, stableStringify } from "./util.js";
+export function buildObservationReceipt(observation) {
+    return {
+        observationHash: sha256(stableStringify(observation)),
+        indicatorVersion: INDICATOR_VERSION,
+    };
+}

package/dist/agent/observe.js

@@ -8,6 +8,11 @@ import { scanSetups } from "./setups.js";
 // (~5-min fresh, ~288 bars — ample for EMA50/RSI14/Bollinger20), which suits the
 // short cadence the hosted house agents run on. Probe-verified 2026-06-17.
 const INDICATOR_RANGE = "1D";
+// `universe_scan` bounds: how many top movers to pull, and how many of those
+// to fully resolve into tradable watch entries (each resolved row costs a
+// resolve + market [+ candles] call).
+const UNIVERSE_SCAN_LIMIT = 15;
+const UNIVERSE_RESOLVE_TOP = 3;
 // Watchlist symbols -> the coin NAMES prediction-market titles use, so an agent
 // discovers PM markets about the coins it actually has a price view on.
 const PM_COIN_NAMES = {
@@ -42,7 +47,16 @@ export function isCalibrationChurnMarket(market) {
 // Tolerant by design: any failure (HTTP error, malformed/sparse candles) returns
 // null so the cycle proceeds with price-only context rather than skipping.
 async function fetchIndicators(client, coinId, trace) {
-    const cr = await client.candles(coinId, INDICATOR_RANGE, trace);
+    // The try honors the documented tolerance for SYNCHRONOUS throws too (an
+    // unexpected client error must degrade to price-only context, never kill
+    // the cycle).
+    let cr;
+    try {
+        cr = await client.candles(coinId, INDICATOR_RANGE, trace);
+    }
+    catch {
+        return null;
+    }
     if (!cr.ok)
         return null;
     // Endpoint shape: { candles: [{ t, o, h, l, c, v }] } ascending (oldest first).
@@ -272,6 +286,78 @@ export async function observe(client, spec, state, trace) {
         }
         watch.push(entry);
     }
+    // `universe_scan` capability (2026-08-18, direct user request): discover the
+    // top 24h movers across the whole tracked universe, resolve the strongest
+    // few into FULL watch entries (marked discovered) and pass the remainder as
+    // compact context. Bounds: one movers call + up to
+    // UNIVERSE_RESOLVE_TOP resolve/market(+candles) calls per cycle — the same
+    // per-symbol cost as ~3 extra watchlist rows, all against CoinRithm's own
+    // API (never the model quota). Failures degrade to "no universe section",
+    // never a skipped cycle. Watchlist + blocklist symbols are excluded up
+    // front so a discovered row can never duplicate or bypass the deny-list.
+    let universeMovers;
+    if (spec.capabilities.includes("universe_scan")) {
+        const mv = await client.cryptoMovers("gainers", UNIVERSE_SCAN_LIMIT, trace);
+        if (mv.ok && Array.isArray(mv.data)) {
+            const excluded = new Set([...spec.risk.watchlist, ...(spec.risk.blocklist ?? [])].map((s) => s.toUpperCase()));
+            const rows = mv.data
+                .map(asObj)
+                .map((r) => ({
+                symbol: (asStr(r.symbol) ?? "").toUpperCase(),
+                name: asStr(r.name),
+                change24hPct: asNum(r.change24h),
+                priceUsd: asNum(r.currentPrice),
+                // The movers row already carries the ucid, which IS the coinId every
+                // downstream call takes. Kept so the resolve round-trip below can be
+                // skipped — see the comment there.
+                coinId: asStr(r.ucid),
+            }))
+                .filter((r) => r.symbol && !excluded.has(r.symbol));
+            const resolveTop = rows.slice(0, UNIVERSE_RESOLVE_TOP);
+            for (const row of resolveTop) {
+                // Prefer the ucid the movers feed already gave us. Resolving the
+                // SYMBOL instead was both a wasted call per discovered mover and a
+                // correctness hazard: symbols collide across listings, so the resolver
+                // could hand back a different coin than the one that actually moved,
+                // and the agent would analyze (and trade) that other coin.
+                let coinId = row.coinId;
+                let resolvedName;
+                if (!coinId) {
+                    const rs = await client.resolve(row.symbol, trace);
+                    const match = asObj(asObj(rs.data).match);
+                    coinId =
+                        rs.ok && match.coinId != null ? String(match.coinId) : undefined;
+                    resolvedName = asStr(match.name);
+                }
+                if (!coinId)
+                    continue;
+                const mk = await client.market(coinId, trace);
+                const m = asObj(mk.data);
+                const price = asObj(m.price);
+                const entry = {
+                    symbol: row.symbol,
+                    coinId,
+                    name: resolvedName ?? row.name ?? undefined,
+                    priceUsd: asNum(price.usd) ?? row.priceUsd,
+                    change1h: asNum(price.change1h),
+                    change24h: asNum(price.change24h) ?? row.change24hPct,
+                    change7d: asNum(price.change7d),
+                    sentimentBullishPct: asNum(asObj(m.sentiment).bullishPct) ?? undefined,
+                    freshness: freshnessOf(asObj(m.observation)),
+                    discovered: true,
+                };
+                if (wantIndicators) {
+                    const ind = await fetchIndicators(client, coinId, trace);
+                    if (ind)
+                        entry.indicators = ind;
+                }
+                watch.push(entry);
+            }
+            const context = rows.slice(UNIVERSE_RESOLVE_TOP);
+            if (context.length > 0)
+                universeMovers = context;
+        }
+    }
     // Spot resting orders (for cancel + affordability) — only if spot is enabled.
     const wantSpot = spec.venues.includes("spot");
     const wantPm = spec.venues.includes("pm");
@@ -451,12 +537,19 @@ export async function observe(client, spec, state, trace) {
         }
     }
     // News context (only with the `news` capability): recent high-importance news
-    // for the watchlist coins, fed into the decide prompt as a market-catalyst
-    // layer the price chart can't show. One cached call; degrades to no news on
-    // failure (never blocks a cycle).
+    // for the coins the agent is actually LOOKING AT this cycle — the watch array,
+    // which includes any `universe_scan`-discovered movers. Keying this to the
+    // static watchlist alone (the old behavior) starved exactly the case news
+    // exists for: a discovered pump whose catalyst the agent is supposed to
+    // investigate before acting (the pump-fade pattern, 2026-08-19). One cached
+    // call; degrades to no news on failure (never blocks a cycle).
     let news;
-    if (wantNews && spec.risk.watchlist.length > 0) {
-        const nr = await client.agentNews({ coins: spec.risk.watchlist.join(","), limit: 8, hours: 48 }, trace);
+    const newsCoins = Array.from(new Set([
+        ...spec.risk.watchlist,
+        ...watch.map((w) => w.symbol.toUpperCase()),
+    ]));
+    if (wantNews && newsCoins.length > 0) {
+        const nr = await client.agentNews({ coins: newsCoins.join(","), limit: 8, hours: 48 }, trace);
         if (nr.ok) {
             news = asArr(asObj(nr.data).items)
                 .map(asObj)
@@ -495,6 +588,7 @@ export async function observe(client, spec, state, trace) {
         syncCursor,
         newClosedTrades,
         polledBeforeWrite,
+        universeMovers,
     };
     // Skip only when there is NOTHING actionable: no coin resolved (futures/spot)
     // AND no PM candidate (pm). A pm-only agent proceeds on its discovered markets.

package/dist/agent/prompt.js

@@ -63,7 +63,15 @@ opts = {}) {
         `- venues you may act in: ${v.join(", ")}`,
         `- perTradeMarginMusd ${r.perTradeMarginMusd} is the per-trade SIZE cap (futures margin / spot buy notional / PM stake)`,
         `- futures: maxLeverage ${r.maxLeverage}, maxConcurrentPositions ${r.maxConcurrentPositions}, requireStopLoss ${r.requireStopLoss} (long stop below entry, short stop above)`,
-        `- watchlist (spot + futures use ONLY these): ${r.watchlist.join(", ")}`,
+        // With universe_scan, the validator's gate is WATCH-membership (manual
+        // watchlist ∪ this cycle's discovered entries) — saying "ONLY these" here
+        // while the universe-scan section below calls discovered movers tradable
+        // made cap-obedient models refuse every discovered candidate (the caps
+        // header says proposing outside a cap wastes the cycle). Keep the two
+        // sections telling one story.
+        spec.capabilities.includes("universe_scan")
+            ? `- tradable symbols (spot + futures): your watchlist (${r.watchlist.join(", ")}) PLUS this cycle's watch entries marked \`discovered: true\` — nothing outside those`
+            : `- watchlist (spot + futures use ONLY these): ${r.watchlist.join(", ")}`,
         ...(r.blocklist && r.blocklist.length > 0
             ? [
                 `- deny-list (NEVER open these, even if on the watchlist): ${r.blocklist.join(", ")}`,
@@ -87,6 +95,15 @@ opts = {}) {
                 "- a null field = not enough data; ignore it. These INFORM your decision; they never widen a cap.",
             ]
             : []),
+        ...(spec.capabilities.includes("universe_scan")
+            ? [
+                "",
+                "## Universe scan (discovered movers) — candidates beyond your watchlist",
+                "Watch entries with `discovered: true` are today's strongest 24h movers across the WHOLE tracked universe, resolved with the same price/sentiment (and indicators) data as your watchlist. observation.universeMovers lists further movers as symbol + 24h change only (context — you cannot trade those directly this cycle).",
+                "- Treat a discovered candidate like any other symbol: analyze it for catalysts, exhaustion and reversal BEFORE acting. A big 24h pump is as often a top as a beginning — chasing green candles blind is how discovery loses money.",
+                "- All your normal risk rules apply unchanged: caps, stops, blocklist, confidence floor. Discovery widens what you can SEE, never what you may risk.",
+            ]
+            : []),
         ...(spec.capabilities.includes("news")
             ? [
                 "",
@@ -169,6 +186,7 @@ export function buildUserPrompt(obs, journal) {
         watch: obs.watch,
         setups: obs.setups,
         news: obs.news,
+        universeMovers: obs.universeMovers,
         marketMood: obs.marketMood,
         newClosedTrades: obs.newClosedTrades.slice(0, 20),
         polledBeforeWrite: obs.polledBeforeWrite,

package/dist/agent/resolve.d.ts

@@ -3,9 +3,21 @@ export declare class ResolveError extends Error {
     issues: ResolveIssue[];
     constructor(issues: ResolveIssue[]);
 }
+export declare const proseBody: (raw: string) => string;
+export declare const GUARDS_FILE = "character/guards.md";
+export declare const GUARDS_HEADER = "## HARD BEHAVIORAL GUARDS \u2014 never violate these";
+export declare const GUARDS_FOOTER = "(These guards override every other instruction in this strategy. When a guard conflicts with an opportunity, the guard wins and the correct output is a skip that names the guard.)";
+export declare const wrapGuardsProse: (body: string) => string;
 export declare function isSkillProseSource(source: string): boolean;
 export declare function mergeProseParts(parts: Array<{
     source: string;
     text: string;
 }>): string;
 export declare function resolveAgent(inputPath: string): ResolvedAgent;
+export declare const HOSTED_PROSE_MAX_CHARS = 8000;
+/** PURE — exported for tests. Mirrors the backend's trim-then-measure. */
+export declare const hostedProseBudget: (mergedProse: string) => {
+    used: number;
+    over: number;
+    fits: boolean;
+};

package/dist/agent/resolve.js

@@ -47,6 +47,32 @@ const JOURNAL_MAX_LINES = 200;
 const JOURNAL_MAX_BYTES = 8_000;
 // Optional prose files (markdown the LLM reads), in assembly order.
 const PROSE_FILES = ["character/thesis.md", "character/persona.md"];
+// Prose files carry an OPTIONAL YAML frontmatter block (type/title/description/
+// tags) that is authoring metadata, not doctrine — the model gains nothing from
+// `tags: [agent, persona, mean-reversion]`. It was being merged verbatim into
+// the system prompt: pure noise, and on the hosted path it also consumed the
+// 8,000-char strategy budget (measured 2026-08-19: ~1.0k chars across a
+// decomposed bundle's thesis/persona/journal). Skill files already strip theirs
+// (their frontmatter is parsed for the cap patch), and guards.md strips too —
+// this brings the remaining prose files in line. Files WITHOUT frontmatter are
+// returned unchanged.
+export const proseBody = (raw) => {
+    const src = raw.replace(/\r\n/g, "\n");
+    const m = /^---\n[\s\S]*?\n---\n?([\s\S]*)$/.exec(src);
+    return (m ? m[1] : src).trim();
+};
+// First-class hard-guards file (2026-08-19, audit rank 7). User-authored
+// behavioral borders that machine caps cannot express ("never open a short
+// unless a qualifying pump preceded it") previously lived as an undocumented
+// "Hard borders" paragraph buried mid-persona — present in only 5 of 8
+// bundles and easy for a forker to miss. character/guards.md gets a dedicated
+// slot: loaded LAST so the block lands at the END of the strategy prose,
+// immediately adjacent to the system prompt's hard-caps section, wrapped in a
+// high-salience header plus an explicit guards-win-conflicts rule.
+export const GUARDS_FILE = "character/guards.md";
+export const GUARDS_HEADER = "## HARD BEHAVIORAL GUARDS — never violate these";
+export const GUARDS_FOOTER = "(These guards override every other instruction in this strategy. When a guard conflicts with an opportunity, the guard wins and the correct output is a skip that names the guard.)";
+export const wrapGuardsProse = (body) => `${GUARDS_HEADER}\n\n${body.trim()}\n\n${GUARDS_FOOTER}`;
 const FUNCTIONALITY_PIN = "functionality/coinrithm.yaml";
 // Enforced cap field names. sizing.yaml is SOFT guidance and must NOT contain
 // any of these (or a user could think a limit binds when it does not).
@@ -427,8 +453,9 @@ function resolveDirectory(dir) {
         const p = join(dir, pf);
         if (existsSync(p)) {
             const abs = safePath(ctx, pf, "prose");
-            if (abs)
-                proseParts.push({ source: pf, text: readHashed(ctx, abs) });
+            if (abs) {
+                proseParts.push({ source: pf, text: proseBody(readHashed(ctx, abs)) });
+            }
         }
     }
     proseParts.push(...skillProse);
@@ -437,13 +464,28 @@ function resolveDirectory(dir) {
     if (existsSync(journalPath)) {
         const abs = safePath(ctx, "journal/notes.md", "journal");
         if (abs) {
-            const full = readHashed(ctx, abs);
+            const full = proseBody(readHashed(ctx, abs));
             proseParts.push({
                 source: "journal/notes.md",
                 text: boundTail(full, JOURNAL_MAX_LINES, JOURNAL_MAX_BYTES),
             });
         }
     }
+    // Hard behavioral guards — see GUARDS_FILE above. Pushed AFTER the journal
+    // so the wrapped block is the final prose the model reads before the caps
+    // section. Frontmatter is optional and stripped (only the body is doctrine);
+    // an empty body contributes nothing.
+    const guardsAbsPath = join(dir, GUARDS_FILE);
+    if (existsSync(guardsAbsPath)) {
+        const abs = safePath(ctx, GUARDS_FILE, "guards");
+        if (abs) {
+            const raw = readHashed(ctx, abs);
+            const body = (raw.startsWith("---") ? parseFrontmatter(raw).body : raw).trim();
+            if (body) {
+                proseParts.push({ source: GUARDS_FILE, text: wrapGuardsProse(body) });
+            }
+        }
+    }
     // Optional API/tool contract pin. It is locked for reproducibility and stale
     // warnings, but it is not part of AgentSpec and is never sent to the model.
     const functionalityPath = join(dir, FUNCTIONALITY_PIN);
@@ -542,3 +584,21 @@ export function resolveAgent(inputPath) {
         { code: "input_invalid", message: "input must be a file or a directory" },
     ]);
 }
+// ── Hosted strategy-prose budget ───────────────────────────────────────────
+// The managed (Studio) deploy/edit API caps the merged strategy prose and
+// reverts the save past the cap; the self-host runner has NO such limit. The
+// cap is not arbitrary — the merged prose becomes the system prompt, and an
+// oversized prompt is what previously pushed small free-tier models to ~69k
+// tokens / 413s per cycle. Mirrored here (backend-v2
+// controllers/agentManage.ts sanitizeStrategyProse) so `validate --hosted`
+// can catch it before a user does.
+export const HOSTED_PROSE_MAX_CHARS = 8000;
+/** PURE — exported for tests. Mirrors the backend's trim-then-measure. */
+export const hostedProseBudget = (mergedProse) => {
+    const used = mergedProse.replace(/\r\n/g, "\n").trim().length;
+    return {
+        used,
+        over: Math.max(0, used - HOSTED_PROSE_MAX_CHARS),
+        fits: used <= HOSTED_PROSE_MAX_CHARS,
+    };
+};