@reticlehq/server 2.2.1 → 2.3.0

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isToonable, resultToToon } from '@reticlehq/core';
 import { TOOLS } from './tools/tools.js';
@@ -10,6 +11,8 @@ import { buildErrorPayload } from './tools/error-recovery.js';
 import { log } from './log.js';
 import { SERVER_VERSION } from './server-version.js';
 import { MCP_SERVER_NAME } from './init/mcp.js';
+import { setMcpClientNameHook } from './telemetry/feedback-context.js';
+import { getSessionMetrics } from './telemetry/session-metrics.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -25,10 +28,31 @@ const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
-function firstSentence(description) {
+/**
+ * Append the tool's example call to whatever description survived trimming.
+ *
+ * Costs a handful of tokens per turn and buys back the failed round trips an agent spends guessing
+ * how the fields compose — which is a far worse trade in the other direction.
+ */
+function withExample(description, example) {
+    return example === undefined ? description : `${description} e.g. ${JSON.stringify(example)}`;
+}
+/**
+ * Abbreviations whose internal period is NOT a sentence end.
+ *
+ * The splitter looked for the first `". "`, which "e.g. " satisfies — so every lean-profile
+ * description containing one was cut off mid-abbreviation. `reticle_act`'s ref parameter reached the
+ * agent as "Element ref from reticle_snapshot or reticle_query (e.g." and stopped: the example gone,
+ * and any contract stated after it gone too. Silent, and it degraded the DEFAULT profile only, which
+ * is the one nobody reads the raw strings for.
+ */
+const ABBREVIATIONS = ['e.g.', 'i.e.', 'etc.', 'vs.', 'cf.'];
+export function firstSentence(description) {
     const nl = description.indexOf('\n');
     const base = nl >= 0 ? description.slice(0, nl) : description;
-    const dot = base.search(/\.\s/);
+    // Mask abbreviations with an equal-length filler so offsets stay valid in the original string.
+    const masked = ABBREVIATIONS.reduce((text, abbr) => text.split(abbr).join('\u0000'.repeat(abbr.length)), base);
+    const dot = masked.search(/\.\s/);
     const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
     return sentence.length > 160 ? `${sentence.slice(0, 159)}…` : sentence;
 }
@@ -52,9 +76,34 @@ const PREDICATE_PARAMS = new Set(['predicate', 'until']);
  * grammar up front versus letting the agent fetch it from `reticle_tools` when it needs a variant it
  * has not used before.
  */
-const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
-    'animation | signal | state | settled | allOf | anyOf | not. Call reticle_tools for the full ' +
-    'field grammar of a kind.';
+/**
+ * The kind list — the part an agent needs to WRITE a predicate. Carried on every predicate parameter.
+ *
+ * An earlier version put this on one tool and pointed the other five at it ("same grammar as
+ * reticle_act_and_wait's"), which saved 790 B/turn. It was the wrong trade: it made writing a
+ * predicate require joining two tool descriptions, and accuracy is worth more here than the bytes.
+ * Only the "where to get field details" sentence is stated once now — that one IS a pointer, so
+ * making it a pointer costs nothing.
+ */
+const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
+    'animation | signal | state | settled | allOf | anyOf | not.';
+/**
+ * Said once per turn: the bug-catching options, and where to get the rest of the field grammar.
+ *
+ * `net.count`, `console.absent` and `absent` are the three predicate options that catch a class of
+ * bug rather than confirm an expectation — a double-submit, an action that "worked" while logging a
+ * caught error, something that should have disappeared and did not. They sat behind a
+ * `reticle_tools` round trip, so an agent only found them if it already knew to look, which is the
+ * wrong way round for the checks most likely to catch what nobody suspected.
+ *
+ * Anchored to one tool rather than repeated on all six: these are ADDITIONAL capability, not what
+ * makes a basic predicate correct, so one mention per turn is enough to make them reachable without
+ * paying for six.
+ */
+const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
+    'console.absent:true (action completed with a CLEAN console), absent:true on element/text ' +
+    '(it should be gone). Call reticle_tools for the full field grammar of a kind.';
+const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
  * Lean copy of a tool's zod input shape for lean profiles: each parameter's description is
  * truncated to its first sentence via zod's own `.describe` (which returns a new schema, so the
@@ -62,11 +111,14 @@ const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. ki
  * schema cost; the first clause keeps each param's purpose and any enum hints. Params without a
  * description pass through unchanged. Predicate params are replaced wholesale — see above.
  */
-function leanZodShape(shape) {
+function leanZodShape(shape, predicateAnchor) {
     const out = {};
     for (const [key, schema] of Object.entries(shape)) {
         if (PREDICATE_PARAMS.has(key)) {
-            const compact = z.record(z.unknown()).describe(COMPACT_PREDICATE_DESCRIPTION);
+            // Every tool keeps the kinds; only the navigation hint is anchored to one.
+            const compact = z
+                .record(z.unknown())
+                .describe(predicateAnchor === undefined ? COMPACT_PREDICATE_DESCRIPTION : PREDICATE_KINDS);
             out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
@@ -112,9 +164,84 @@ export function advertisedTools(profile) {
     const base = filterTools(TOOLS, profile === TOOL_PROFILE.HYBRID ? TOOL_PROFILE.CORE : profile);
     return [...base, ...buildDynamicTools(TOOLS)];
 }
+/**
+ * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
+ * and (non-lean only) the output schema.
+ *
+ * Exported so tests assert on the REAL advertised text rather than on the tool definitions, which
+ * are trimmed later and would make a guard that cannot fail — a mistake already made once here, with
+ * an abbreviation test that read raw defs and would have passed with the bug fully present.
+ */
+export function advertisedConfig(tool, advertised, profile) {
+    const terse = profile === TOOL_PROFILE.CORE ||
+        profile === TOOL_PROFILE.STANDARD ||
+        profile === TOOL_PROFILE.HYBRID;
+    // The first advertised tool carrying a predicate spells the grammar out; the rest point at it.
+    const anchor = advertised.find((t) => Object.keys(t.inputSchema).some((k) => PREDICATE_PARAMS.has(k)))?.name;
+    const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
+    return {
+        description: withExample(terse ? firstSentence(tool.description) : tool.description, tool.example),
+        inputSchema: terse
+            ? leanZodShape(tool.inputSchema, tool.name === anchor ? undefined : anchor)
+            : tool.inputSchema,
+        ...(outputSchema !== undefined ? { outputSchema } : {}),
+    };
+}
+/** Argument keys the tool never declared. Empty when the tool's shape is unknown to us. */
+function unknownKeys(args, allowed) {
+    if (allowed === undefined || typeof args !== 'object' || args === null)
+        return [];
+    return Object.keys(args).filter((key) => !allowed.has(key));
+}
+export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
+    const target = server;
+    const original = target.validateToolInput;
+    if (typeof original !== 'function')
+        return;
+    target.validateToolInput = async (tool, args, toolName) => {
+        // An UNKNOWN key is the failure zod cannot catch, because object schemas are non-strict: the key
+        // is silently dropped and the tool answers as if it had not been asked. Measured live —
+        // `reticle_clock { action: "freeze" }` returned `{"frozen":false}`, which reads as a fact about
+        // the app ("the clock is not frozen") when it means "you named the parameter wrong". That is a
+        // false NEGATIVE the caller cannot detect from the reply, in every tool at once.
+        const unknown = unknownKeys(args, allowedKeys.get(toolName));
+        if (unknown.length > 0) {
+            const example = examples.get(toolName);
+            throw new McpError(ErrorCode.InvalidParams, `Unknown ${unknown.length === 1 ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
+                `They were NOT applied — a result computed without them would look like an answer. ` +
+                (example === undefined
+                    ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                    : `A valid call looks like: ${toolName} ${example}`));
+        }
+        try {
+            return await original.call(server, tool, args, toolName);
+        }
+        catch (error) {
+            // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
+            const raw = error instanceof Error ? error.message : String(error);
+            const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            const example = examples.get(toolName);
+            const help = example === undefined
+                ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                : ` A valid call looks like: ${toolName} ${example}`;
+            throw new McpError(ErrorCode.InvalidParams, `${detail}${help}`);
+        }
+    };
+}
 export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     const server = new McpServer(SERVER_INFO);
+    // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
+    // hook rather than read here: the handshake has not happened yet at construction time, and a
+    // feedback report filed twenty tool calls later is exactly when we want the answer.
+    setMcpClientNameHook(() => {
+        const info = server.server.getClientVersion();
+        // Record it as a side effect of the first read so the session summary can report WHICH agents
+        // drove this daemon — the multi-agent story, visible without a second plumbing path.
+        if (info?.name !== undefined)
+            getSessionMetrics().recordClient(info.name);
+        return info === undefined ? undefined : { name: info.name, version: info.version };
+    });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.
     const registerTool = server.registerTool.bind(server);
     // `dynamic` advertises only the 2 meta-tools (reticle_tools + reticle_run); real tools load on demand.
@@ -126,9 +253,12 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
     const advertised = advertisedTools(profile);
-    const terse = profile === TOOL_PROFILE.CORE ||
-        profile === TOOL_PROFILE.STANDARD ||
-        profile === TOOL_PROFILE.HYBRID;
+    installFriendlyArgErrors(server, new Map(advertised
+        .filter((tool) => tool.example !== undefined)
+        .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
+    // Every tool in TOOLS, not just the advertised ones: reticle_run dispatches to the full table,
+    // so an unadvertised tool reached through the hatch must be just as strict.
+    new Map(TOOLS.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.
@@ -150,12 +280,7 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
         // handler below is unchanged, so `full`/`dynamic` (non-terse) keep the schema for validating
         // clients. This removes the single largest remaining slice of the per-request tax (~36% of the
         // hybrid payload) with no loss the agent can observe.
-        const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
-        const config = {
-            description: terse ? firstSentence(tool.description) : tool.description,
-            inputSchema: terse ? leanZodShape(tool.inputSchema) : tool.inputSchema,
-            ...(outputSchema !== undefined ? { outputSchema } : {}),
-        };
+        const config = advertisedConfig(tool, advertised, profile);
         registerTool(tool.name, config, async (args) => {
             try {
                 const result = await runTool(tool, deps, args);
@@ -171,6 +296,10 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 log('tool_error', { tool: tool.name, error: message });
+                // Counted by FINGERPRINT, never by message — see error-fingerprint.ts. This is the single
+                // boundary every agent-visible tool failure crosses, so it is the one place "which error is
+                // hurting people most" can be answered without instrumenting every handler.
+                getSessionMetrics().recordToolError(message, tool.name);
                 // Every error the agent hits should answer "what next?", not just "what broke".
                 return {
                     isError: true,
@@ -181,4 +310,3 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     }
     return server;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/oracles/flow-instrument-gaps.d.ts

@@ -16,4 +16,3 @@ export declare function lastSource(steps: readonly FlowStep[]): {
  * source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
  */
 export declare function instrumentationGapsForFlows(unassertedFlows: readonly string[], flowStepsByName: ReadonlyMap<string, readonly FlowStep[]>): InstrumentationGap[];
-//# sourceMappingURL=flow-instrument-gaps.d.ts.map

package/dist/oracles/flow-instrument-gaps.js

@@ -42,4 +42,3 @@ export function instrumentationGapsForFlows(unassertedFlows, flowStepsByName) {
     }
     return gaps;
 }
-//# sourceMappingURL=flow-instrument-gaps.js.map

package/dist/oracles/propose-consequences.d.ts

@@ -19,4 +19,3 @@ export interface ProposedConsequence {
 }
 /** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
 export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
-//# sourceMappingURL=propose-consequences.d.ts.map

package/dist/oracles/propose-consequences.js

@@ -90,4 +90,3 @@ export function proposeConsequences(events) {
     }
     return proposals.sort((a, b) => a.tier - b.tier);
 }
-//# sourceMappingURL=propose-consequences.js.map

package/dist/oracles/self-instrument.d.ts

@@ -29,4 +29,3 @@ export interface InstrumentationProposal {
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export declare function proposeInstrumentation(gaps: readonly InstrumentationGap[]): InstrumentationProposal[];
-//# sourceMappingURL=self-instrument.d.ts.map

package/dist/oracles/self-instrument.js

@@ -41,4 +41,3 @@ export function proposeInstrumentation(gaps) {
         rationale: rationaleFor(gap),
     }));
 }
-//# sourceMappingURL=self-instrument.js.map

package/dist/pairing-token.d.ts

@@ -25,4 +25,3 @@ export declare function nodePairingTokenDeps(): PairingTokenDeps;
  * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
  */
 export declare function readOrCreatePairingToken(dir: string, deps: PairingTokenDeps): Promise<string | undefined>;
-//# sourceMappingURL=pairing-token.d.ts.map

package/dist/pairing-token.js

@@ -59,4 +59,3 @@ export async function readOrCreatePairingToken(dir, deps) {
         return undefined;
     }
 }
-//# sourceMappingURL=pairing-token.js.map

package/dist/phenomena/phenomena.d.ts

@@ -24,4 +24,3 @@ export declare function detectPreHydrationClicks(events: readonly ReticleEvent[]
 export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
 /** Run every journal-only matcher over a session's events + actions. */
 export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-//# sourceMappingURL=phenomena.d.ts.map

package/dist/phenomena/phenomena.js

@@ -99,4 +99,3 @@ export function detectPhenomena(events, actions) {
         ...detectSwallowedErrors(events),
     ];
 }
-//# sourceMappingURL=phenomena.js.map

package/dist/pool/browser-pool.d.ts

@@ -89,4 +89,3 @@ export declare class BrowserPool {
     shutdown(): Promise<void>;
 }
 export {};
-//# sourceMappingURL=browser-pool.d.ts.map

package/dist/pool/browser-pool.js

@@ -236,4 +236,3 @@ export class BrowserPool {
             waiter(); // let them re-claim + relaunch
     }
 }
-//# sourceMappingURL=browser-pool.js.map

package/dist/pool/lease-reaper.d.ts

@@ -13,4 +13,3 @@ export declare class LeaseReaper {
     start(): void;
     stop(): void;
 }
-//# sourceMappingURL=lease-reaper.d.ts.map

package/dist/pool/lease-reaper.js

@@ -38,4 +38,3 @@ export class LeaseReaper {
         this.#timer = undefined;
     }
 }
-//# sourceMappingURL=lease-reaper.js.map

package/dist/pool/playwright-launcher.d.ts

@@ -18,4 +18,3 @@ export declare function playwrightLauncher(opts?: {
  * Pure (env value + cpu count passed in) so it's testable.
  */
 export declare function resolveMaxContexts(envValue: string | undefined, cpuCount: number): number;
-//# sourceMappingURL=playwright-launcher.d.ts.map

package/dist/pool/playwright-launcher.js

@@ -5,6 +5,9 @@
  *
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
+import { BrowserLaunchKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
@@ -38,10 +41,16 @@ export function playwrightLauncher(opts = {}) {
     // (where it's meaningful) instead of at import-time (where it kills unrelated features).
     return async () => {
         const { chromium } = await import('playwright');
+        // A pooled launch serves N parallel leases, so this counts BROWSERS, not contexts — which is the
+        // number that actually costs memory and the one that explains a slow machine.
+        const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            return wrapBrowser(await chromium.launch({ headless }));
+            const browser = wrapBrowser(await chromium.launch({ headless }));
+            settle();
+            return browser;
         }
         catch (err) {
+            settle(classifyConnectFailure(err));
             // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
             const msg = err instanceof Error ? err.message : String(err);
             if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
@@ -74,4 +83,3 @@ export function resolveMaxContexts(envValue, cpuCount) {
     const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
     return Math.min(MAX_CONTEXTS_CEILING, byCpu);
 }
-//# sourceMappingURL=playwright-launcher.js.map

package/dist/project/baselines.d.ts

@@ -19,4 +19,3 @@ export declare class BaselineStore {
     list(): string[];
 }
 export {};
-//# sourceMappingURL=baselines.d.ts.map

package/dist/project/baselines.js

@@ -44,4 +44,3 @@ export class BaselineStore {
         return [...this.#map.keys()];
     }
 }
-//# sourceMappingURL=baselines.js.map

package/dist/project/file-lock.d.ts

@@ -1,2 +1,3 @@
 export declare function withFileLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=file-lock.d.ts.map
+/** Exposed for testing — returns the number of active chain entries. */
+export declare function chainSize(): number;

package/dist/project/file-lock.js

@@ -18,7 +18,17 @@ export function withFileLock(path, fn) {
     // Run after the previous holder settles, regardless of whether it resolved or rejected.
     const run = prev.then(fn, fn);
     // Keep the chain alive but swallow the outcome so one task's rejection never rejects the next waiter.
-    chains.set(path, run.then(() => undefined, () => undefined));
+    const settled = run.then(() => undefined, () => undefined);
+    chains.set(path, settled);
+    // Reclaim the entry once settled IF no successor queued behind us (the Map still points to our
+    // promise). Without this, every unique path leaks a Map slot for the daemon's lifetime.
+    void settled.then(() => {
+        if (chains.get(path) === settled)
+            chains.delete(path);
+    });
     return run;
 }
-//# sourceMappingURL=file-lock.js.map
+/** Exposed for testing — returns the number of active chain entries. */
+export function chainSize() {
+    return chains.size;
+}

package/dist/project/fs-port.d.ts

@@ -42,4 +42,3 @@ export interface FileSystemPort {
 }
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export declare function createNodeFileSystem(): FileSystemPort;
-//# sourceMappingURL=fs-port.d.ts.map

package/dist/project/fs-port.js

@@ -51,4 +51,3 @@ export function createNodeFileSystem() {
         isNotFound: (error) => error?.code === 'ENOENT',
     };
 }
-//# sourceMappingURL=fs-port.js.map

package/dist/project/project-store.d.ts

@@ -29,4 +29,3 @@ export declare class ProjectStore {
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }
-//# sourceMappingURL=project-store.d.ts.map

package/dist/project/project-store.js

@@ -142,4 +142,3 @@ function truncate(runs) {
     }
     return runs.filter((_, i) => kept.has(i));
 }
-//# sourceMappingURL=project-store.js.map

package/dist/project/project-tools.d.ts

@@ -1,3 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
 export declare const PROJECT_TOOLS: ToolDef[];
-//# sourceMappingURL=project-tools.d.ts.map

package/dist/project/project-tools.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
-import { asString } from '../tools/tools-helpers.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 import { fetchProjectRegressionFromCloud, resolveCloudConfig } from '../cloud/cloud-sync.js';
 import { RunStore } from '../runs/run-store.js';
 import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
@@ -49,6 +49,8 @@ async function cloudRegression(deps, sessionId) {
     return report ?? undefined;
 }
 /** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
+/** Runs returned when the caller does not ask for a specific count. */
+const DEFAULT_RUN_LIMIT = 25;
 function lastTwoFor(runs, name) {
     const matching = runs.filter((r) => r.name === name);
     const n = matching.length;
@@ -85,10 +87,18 @@ export const PROJECT_TOOLS = [
         description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle Cloud, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
         inputSchema: {
             name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
+            limit: z
+                .number()
+                .optional()
+                .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
             ...sessionIdShape,
         },
         outputSchema: {
             runs: z.array(z.unknown()),
+            totalRuns: z
+                .number()
+                .optional()
+                .describe('How many runs exist in total. Compare against runs.length to see if it was capped.'),
             diff: z.unknown().optional(),
             runDiff: z.unknown().optional(),
             cloud: z.unknown().optional(),
@@ -106,8 +116,22 @@ export const PROJECT_TOOLS = [
                 });
             }
             const name = asString(args['name']);
+            // The most recent N, in the order they happened. The history is append-only and unbounded —
+            // measured at ~20KB (~5,000 tokens) across 176 runs on this repo — and an agent asking "how
+            // did this behave before" wants the recent past, not every run ever recorded. `totalRuns`
+            // travels with it so the cap is never silent, per the repo's no-silent-caps rule.
+            //
+            // Order is left alone deliberately. Reversing to newest-first was tried and reverted: it read
+            // better but broke an existing contract for no reason the bound required, and a caller relying
+            // on chronological order would have been silently handed the reverse.
+            const cap = asNumber(args['limit']) ?? DEFAULT_RUN_LIMIT;
+            const recent = (runs) => runs.slice(-cap);
             if (name === undefined) {
-                return withCloud({ runs: read.file.runs, learned: read.file.learned });
+                return withCloud({
+                    runs: recent(read.file.runs),
+                    totalRuns: read.file.runs.length,
+                    learned: read.file.learned,
+                });
             }
             const lastRun = await deps.project.lastRun(name);
             const pair = lastTwoFor(read.file.runs, name);
@@ -117,8 +141,10 @@ export const PROJECT_TOOLS = [
             // last time?" from project.json, while `runDiff` answers "what changed between the last two full
             // verification runs?" from .reticle/runs. Best-effort: no artifacts simply means no runDiff.
             const runDiff = await lastTwoRunArtifacts(deps);
+            const forName = read.file.runs.filter((r) => r.name === name);
             return withCloud({
-                runs: read.file.runs.filter((r) => r.name === name),
+                runs: recent(forName),
+                totalRuns: forName.length,
                 learned: read.file.learned,
                 lastRun,
                 ...(pair !== undefined ? { diff: diffRuns(pair[0], pair[1]) } : {}),
@@ -156,4 +182,3 @@ export const PROJECT_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=project-tools.js.map

package/dist/project/reticle-dir.d.ts

@@ -83,4 +83,3 @@ export type ReadContractResult = {
 };
 /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. */
 export declare function readContract(fs: FileSystemPort, root: string): Promise<ReadContractResult>;
-//# sourceMappingURL=reticle-dir.d.ts.map

package/dist/project/reticle-dir.js

@@ -167,4 +167,3 @@ export async function readContract(fs, root) {
         return { ok: false, reason: ContractReadError.MALFORMED };
     return { ok: true, capabilities: result.data.capabilities, generatedAt: result.data.generatedAt };
 }
-//# sourceMappingURL=reticle-dir.js.map

package/dist/runs/build-verification-run.d.ts

@@ -27,4 +27,3 @@ export declare function computeVerdict(input: VerificationRunInput): RunVerdict;
  * input can never escape as an "artifact".
  */
 export declare function buildVerificationRun(input: VerificationRunInput, now: () => number): ReticleVerificationRun;
-//# sourceMappingURL=build-verification-run.d.ts.map

package/dist/runs/build-verification-run.js

@@ -68,4 +68,3 @@ export function buildVerificationRun(input, now) {
     };
     return redactForProfile(ReticleVerificationRunSchema.parse(run));
 }
-//# sourceMappingURL=build-verification-run.js.map

package/dist/runs/profile-redact.d.ts

@@ -13,4 +13,3 @@ export declare const REDACTED = "[redacted:prod-preview]";
  * the repair block (source-naming) is dropped and stateAssertion values are redacted.
  */
 export declare function redactForProfile(run: ReticleVerificationRun): ReticleVerificationRun;
-//# sourceMappingURL=profile-redact.d.ts.map

package/dist/runs/profile-redact.js

@@ -29,4 +29,3 @@ export function redactForProfile(run) {
     void repair; // intentionally dropped — fix instructions name source files
     return { ...rest, evidence };
 }
-//# sourceMappingURL=profile-redact.js.map

package/dist/runs/render-report.d.ts

@@ -6,4 +6,3 @@
 import { type ReticleVerificationRun } from '@reticlehq/core';
 /** Render the run as a plain-text report. Sections with no content are omitted. */
 export declare function renderRunReport(run: ReticleVerificationRun): string;
-//# sourceMappingURL=render-report.d.ts.map

package/dist/runs/render-report.js

@@ -67,4 +67,3 @@ export function renderRunReport(run) {
     }
     return out.join('\n');
 }
-//# sourceMappingURL=render-report.js.map

package/dist/runs/repair-prompt.d.ts

@@ -14,4 +14,3 @@ export declare function deviationHeadline(deviation: unknown): string | undefine
 export declare function buildRepairPacket(replay: FlowReplayResult): RepairPacket | undefined;
 /** Build the repair packets for a set of replays (failed ones only). */
 export declare function buildRepairPackets(replays: ReadonlyArray<FlowReplayResult>): RepairPacket[];
-//# sourceMappingURL=repair-prompt.d.ts.map

package/dist/runs/repair-prompt.js

@@ -69,4 +69,3 @@ export function buildRepairPacket(replay) {
 export function buildRepairPackets(replays) {
     return replays.map(buildRepairPacket).filter((p) => p !== undefined);
 }
-//# sourceMappingURL=repair-prompt.js.map

package/dist/runs/replay-mapping.d.ts

@@ -9,4 +9,3 @@ import { ReplayStatus, RunFlowStatus, type FlowReplayResult, type RunFlowResult
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number): RunFlowResult;
-//# sourceMappingURL=replay-mapping.d.ts.map

package/dist/runs/replay-mapping.js

@@ -32,4 +32,3 @@ export function mapReplayToFlowResult(replay, durationMs) {
         ...(failureReason !== undefined ? { failureReason } : {}),
     };
 }
-//# sourceMappingURL=replay-mapping.js.map

package/dist/runs/reticle-runner.d.ts

@@ -45,4 +45,3 @@ export declare class ReticleRunner {
      */
     verify(opts: VerifyOptions): Promise<ReticleVerificationRun>;
 }
-//# sourceMappingURL=reticle-runner.d.ts.map

package/dist/runs/reticle-runner.js

@@ -9,6 +9,7 @@
  * top of this — the orchestration and the verdict live here so the MCP path and the API produce the
  * same artifact byte-for-byte.
  */
+import { reportRunTelemetry } from '../telemetry/run-telemetry.js';
 import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { buildRepairPackets } from './repair-prompt.js';
@@ -50,7 +51,8 @@ export class ReticleRunner {
             evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
             ...(failurePackets.length > 0 ? { repair: { failurePackets } } : {}),
         };
-        return buildVerificationRun(input, () => this.#port.now());
+        const run = buildVerificationRun(input, () => this.#port.now());
+        reportRunTelemetry(run);
+        return run;
     }
 }
-//# sourceMappingURL=reticle-runner.js.map

package/dist/runs/risk-classify.d.ts

@@ -24,4 +24,3 @@ export declare function classifyChangedFiles(files: ReadonlyArray<ChangedFileInp
  * severity and a gated flag driven by the policy. This is what the verdict counts as blocking.
  */
 export declare function buildRisks(changedFiles: ReadonlyArray<RunChangedFile>, policy?: RiskPolicy): RunRisk[];
-//# sourceMappingURL=risk-classify.d.ts.map

package/dist/runs/risk-classify.js

@@ -73,4 +73,3 @@ export function buildRisks(changedFiles, policy = {}) {
     }
     return risks;
 }
-//# sourceMappingURL=risk-classify.js.map

package/dist/runs/run-diff.d.ts

@@ -31,4 +31,3 @@ export declare const DEFAULT_NOISE_FLOOR_PCT = 10;
  * console diffs land once runs persist per-step detail.
  */
 export declare function diffRuns(before: ReticleVerificationRun, after: ReticleVerificationRun, noiseFloorPct?: number): RunDiff;
-//# sourceMappingURL=run-diff.d.ts.map