pattern-mcp 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,26 +2,39 @@
 /**
  * Pattern
  *
- * MCP server exposing two tools. `recommend_component` judges whether a UI
+ * MCP server exposing tools built around one judgment: whether a UI
  * component need should be met with an existing shadcn/ui, 21st.dev, or
  * ReUI (reui.io) component, or requires a custom build guided by a
- * real-app reference from Mobbin. `record_component_decision` appends a
- * confirmed decision to local per-project memory (see MEMORY_PATH below),
- * which recommend_component can optionally read back (via project_id) as
- * consistency context for a future call -- never as a cached verdict;
- * coverage is still scored fresh every time.
+ * real-app reference from Mobbin.
  *
- * The judgment logic (extract requirements -> search -> score real code ->
- * threshold into a verdict) is delegated to a single Anthropic API call
- * with the server-side web_search tool enabled, so the same reasoning
+ * Two separate local stores back this, with two different rules:
+ *  - `record_component_decision` appends a confirmed decision to local
+ *    per-project memory (see MEMORY_PATH below), which recommend_component
+ *    can optionally read back (via project_id) as consistency context for
+ *    a future call -- never as a cached verdict; coverage is still scored
+ *    fresh every time. Unchanged, still true.
+ *  - Every recommend_component call that reaches the API instead appends
+ *    to a per-project ledger (see LEDGER_PATH below). Unlike memory.json,
+ *    a high-confidence ledger entry CAN be served directly on a later,
+ *    matching call instead of a fresh search+score -- the one deliberate
+ *    exception to "always fresh," bounded by exact component_need/domain/
+ *    framework/conventions match and a staleness TTL, and always flagged
+ *    via `served_from_ledger: true` in the response so nothing is silently
+ *    passed off as freshly verified. See findLedgerCacheHit.
+ *
+ * The judgment logic itself (extract requirements -> search -> score real
+ * code -> threshold into a verdict) is delegated to a single Anthropic API
+ * call with the server-side web_search tool enabled, so the same reasoning
  * this project validated by hand in conversation is what runs here.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { captureApiError, captureRecommendation, printTelemetryNoticeOnce, shutdownTelemetry, } from "./telemetry.js";
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Configurable so Sonnet vs. Haiku can be A/B tested without a code change.
 // Defaults to Sonnet 5. Try MODEL=claude-haiku-4-5-20251001 to test the
@@ -100,6 +113,30 @@ const LOG_PATH = process.env.PATTERN_LOG_PATH ?? join(homedir(), ".pattern", "ca
 // of what's in this file (see README's "no verdict caching" rule).
 const MEMORY_PATH = process.env.PATTERN_MEMORY_PATH ?? join(homedir(), ".pattern", "memory.json");
 const MAX_DECISIONS_PER_PROJECT = 50;
+// Per-project judgment ledger -- distinct from both LOG_PATH and
+// MEMORY_PATH above. Every recommend_component call that reaches the API
+// with a project_id and lands on reason "scored" or "no_candidates_found"
+// appends one line here (see appendLedgerEntry), unlike MEMORY_PATH which
+// only gains an entry when record_component_decision is explicitly called.
+// Unlike MEMORY_PATH, this file's entries CAN produce a cached verdict on a
+// later call (see findLedgerCacheHit) -- the one deliberate exception to
+// this project's "coverage is scored fresh every time" rule, bounded by
+// exact component_need/domain/framework/conventions match, confidence
+// "high", and LEDGER_TTL_DAYS staleness, and always flagged in the
+// response via served_from_ledger so nothing is silently passed off as
+// fresh. Same homedir/project_id-keyed convention as LOG_PATH/MEMORY_PATH,
+// not a repo-root file -- this server has no concept of "which repo" a
+// call is about, only the caller-supplied project_id string.
+const LEDGER_PATH = process.env.PATTERN_LEDGER_PATH ?? join(homedir(), ".pattern", "ledger.jsonl");
+const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
+// Kill switch for the cache-hit short-circuit specifically -- does NOT
+// disable the ledger itself. Entries still get written and read_ledger
+// still works either way; this only controls whether judgeComponent is
+// allowed to skip a fresh search+score on a matching entry. Set
+// PATTERN_NO_LEDGER_CACHE_HIT (any truthy value) to revert to "every
+// recommend_component call always scores fresh" without removing any
+// ledger code -- flip it back off (unset the var) to re-enable.
+const LEDGER_CACHE_HIT_ENABLED = !process.env.PATTERN_NO_LEDGER_CACHE_HIT;
 // $/1M tokens, checked against the Anthropic pricing page rather than
 // recalled from training data (rates drift). Both current and legacy
 // Haiku 4.5 model-id spellings are listed since PATTERN_MODEL is
@@ -191,12 +228,16 @@ export function computeBreakdownMs(t) {
     };
 }
 function buildMeta(timings, usage) {
+    const fresh = usage.input_tokens ?? 0;
+    const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+    const cacheRead = usage.cache_read_input_tokens ?? 0;
     return {
         total_ms: timings.scoreEndMs - timings.requestStartMs,
         breakdown_ms: computeBreakdownMs(timings),
         tokens_used: {
-            input: (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0),
+            input: fresh + cacheWrite + cacheRead,
             output: usage.output_tokens ?? 0,
+            input_breakdown: { fresh, cache_write: cacheWrite, cache_read: cacheRead },
         },
         estimated_cost_usd: estimateCostUsd(usage, MODEL),
     };
@@ -338,6 +379,9 @@ async function streamAnthropicMessage(body) {
 const TOOL_NAME = "recommend_component";
 const RECORD_DECISION_TOOL_NAME = "record_component_decision";
 const EXTRACT_REQUIREMENTS_TOOL_NAME = "extract_requirements";
+const READ_LEDGER_TOOL_NAME = "read_ledger";
+const REPORT_BUILD_COST_TOOL_NAME = "report_build_cost";
+const REPORT_OUTCOME_PROXY_TOOL_NAME = "report_outcome_proxy";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -367,8 +411,14 @@ const INPUT_SCHEMA = {
                 "belongs to. When provided, past decisions confirmed via " +
                 "record_component_decision for this same project_id are surfaced to " +
                 "the model as a consistency signal (never a rule -- a genuinely " +
-                "better match found in this search still wins). Omit to skip memory " +
-                "lookup entirely; this never falls back to a shared/global bucket.",
+                "better match found in this search still wins). Separately, this call " +
+                "may also be served directly from a recent, high-confidence prior " +
+                "recommend_component judgment for this same project_id/component_need/" +
+                "domain/framework/existing_stack, skipping search+score entirely -- " +
+                "check the response for served_from_ledger: true, which is always set " +
+                "when this happens; see read_ledger to inspect what's stored. Omit " +
+                "project_id to skip both lookups entirely; neither ever falls back to " +
+                "a shared/global bucket.",
         },
         checklist: {
             type: "array",
@@ -381,6 +431,16 @@ const INPUT_SCHEMA = {
                 "today's default behavior: recommend_component extracts its own " +
                 "checklist internally, unchanged.",
         },
+        feature_id: {
+            type: "string",
+            description: "Optional. A stable identifier for the feature this component need " +
+                "belongs to (e.g. a ticket id or branch name), used to roll up this " +
+                "call's cost with a later report_build_cost call for the same " +
+                "feature. Omit to have one derived deterministically from " +
+                "project_id+component_need -- repeat calls for the same feature " +
+                "then land under the same id automatically, with no coordination " +
+                "needed between calls. Only meaningful together with project_id.",
+        },
     },
     required: ["component_need", "domain", "framework"],
 };
@@ -428,9 +488,110 @@ const RECORD_DECISION_INPUT_SCHEMA = {
             type: "string",
             description: "Optional. ISO 8601 timestamp of the decision. Defaults to the current time if omitted.",
         },
+        time_saved_minutes: {
+            type: "number",
+            description: "Optional. Your own estimate, in minutes, of the time this decision saved you by having " +
+                "Pattern's verdict instead of researching candidates and judging fit yourself from scratch. " +
+                "This is self-reported by the calling agent -- Pattern has no way to measure a counterfactual, " +
+                "so it never computes this itself (unlike _meta, which is Pattern's own real cost/latency). " +
+                "Omit if you don't have a meaningful estimate; never guess a number just to fill the field.",
+        },
     },
     required: ["project_id", "component_need", "action", "source"],
 };
+const READ_LEDGER_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in prior recommend_component calls whose ledger entries you want to inspect.",
+        },
+        component_need: {
+            type: "string",
+            description: "Optional. Filters entries by simple keyword match against their component_need. Omit to list all entries for the project.",
+        },
+        limit: {
+            type: "number",
+            description: "Optional. Maximum number of entries to return, most recent first. Defaults to 20.",
+        },
+        feature_id: {
+            type: "string",
+            description: "Optional. Instead of the usual keyword listing, returns the full " +
+                "cost rollup for this one feature_id -- every verdict-time ledger " +
+                "entry (fresh judgments and $0 ledger cache hits) plus every " +
+                "report_build_cost record for it, with a summed total_cost_usd. " +
+                "When provided, component_need and limit are ignored.",
+        },
+    },
+    required: ["project_id"],
+};
+const REPORT_BUILD_COST_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        feature_id: {
+            type: "string",
+            description: "The feature_id this build belongs to -- either one you explicitly " +
+                "passed to an earlier recommend_component call for this feature, " +
+                "or (if you didn't) the same value recommend_component would " +
+                "derive on its own: sha256(project_id + '::' + component_need, " +
+                "lowercased/trimmed) truncated to 8 hex chars. When in doubt, call " +
+                "read_ledger with just project_id and copy the feature_id off the " +
+                "relevant entry rather than re-deriving it by hand.",
+        },
+        project_id: {
+            type: "string",
+            description: "Optional but recommended. The same project_id used in the recommend_component call(s) for this feature, so read_ledger's feature_id rollup can find this record.",
+        },
+        tokens_used: {
+            type: "number",
+            description: "Optional. Total tokens spent building this feature, if you have a real number (e.g. from your own session accounting).",
+        },
+        cost_usd: {
+            type: "number",
+            description: "Total real spend, in USD, for building this feature end to end -- your own best number, not Pattern's (Pattern has no visibility past the verdict it returned).",
+        },
+        outcome: {
+            type: "string",
+            enum: ["shipped", "abandoned", "replaced_with_existing"],
+            description: "What actually happened to this build: 'shipped' it went out, " +
+                "'abandoned' the build was dropped before shipping, " +
+                "'replaced_with_existing' you started a custom build but swapped " +
+                "in an existing component instead (or vice versa).",
+        },
+    },
+    required: ["feature_id", "cost_usd", "outcome"],
+};
+const REPORT_OUTCOME_PROXY_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        feature_id: {
+            type: "string",
+            description: "The feature_id this outcome data belongs to -- same value used in the feature's recommend_component/report_build_cost calls.",
+        },
+        project_id: {
+            type: "string",
+            description: "Optional but recommended. The same project_id used in this feature's other calls, so read_ledger's feature_id rollup can find this record.",
+        },
+        reworked: {
+            type: "boolean",
+            description: "Whether any of the files this feature's build touched have been modified again since the original merge -- computed by you from your own repo's git history (e.g. `git log --follow` against the file list), never guessed. Re-report this on a later check if the answer changes.",
+        },
+        days_to_rework: {
+            type: "number",
+            description: "Optional. Days between the original merge and the first rework commit, if reworked is true and you have a real date to compute from.",
+        },
+        time_to_merge_hours: {
+            type: "number",
+            description: "Hours between the first commit touching this feature's files and the commit/PR that merged it, computed from your own repo's git metadata.",
+        },
+        status_at_30d: {
+            type: "string",
+            enum: ["kept", "replaced", "removed"],
+            description: "At a ~30-day horizon post-merge: whether the component Pattern recommended still exists in the codebase, unchanged in kind ('kept'), was swapped for a different approach ('replaced'), or was deleted entirely ('removed'). Only report this once the horizon has actually passed.",
+        },
+    },
+    required: ["feature_id"],
+};
 // Shared between buildSystemPrompt's own step 2 and
 // buildExtractionSystemPrompt (the extract_requirements tool's standalone
 // prompt) -- the extraction *instructions* are one piece of text reused
@@ -466,13 +627,34 @@ Search shadcn/ui, 21st.dev, and ReUI (reui.io) for components matching the need,
 If search returns zero real candidates -- not just weak matches, but nothing relevant at all (e.g. only vendor policy pages, unrelated components) -- stop here and return verdict "custom_build" with reason "no_candidates_found". Do not fabricate a coverage score in this case; omit requirements_checked and coverage entirely.
 
 4. SCORE COVERAGE AGAINST THE CHECKLIST
-For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate. Base this only on your web_search results from step 3 -- do not use the web_fetch tool here or anywhere in steps 2-5; it is reserved entirely for step 6's reference deep-link check below, and using it earlier can starve that reserved budget.
+For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate.
+
+Before finalizing that coverage score, fetch the best-fitting candidate's own real docs/source page ONCE with the web_fetch tool -- a reserved slot exists for exactly this, separate from step 6's reference-verification budget below, so using it here will not starve that reserved budget. Re-check every requirement against what that fetched page actually says, not just the web_search snippet/description you started with -- a search result can describe functionality a component doesn't actually have, or omit a real prop/feature it does have, and only the fetched page is real evidence either way. Only fetch a URL that a real search result in step 3 actually returned -- never construct or guess one. If the fetch fails, or there's no confirmed URL to fetch, score from the web_search evidence alone and say so in the affected items' evidence text. This one candidate-verification fetch is the only exception to "no web_fetch in steps 2-5" -- it remains reserved for step 6's reference deep-link check otherwise.
 
 5. APPLY VERDICT THRESHOLDS
 coverage >= 80% -> verdict "use_existing", confidence "high"
 coverage 40-79% -> verdict "use_existing", confidence "low" (list the missing fields)
 coverage < 40% -> verdict "custom_build"
 
+Before finalizing a "high" confidence use_existing verdict, check for an OVERSIZED MATCH: a
+candidate can satisfy every checklist item and still be the wrong call if its real capabilities
+(dependency footprint, feature surface -- e.g. virtualization, multi-column sort/group/pivot,
+complex range logic) substantially exceed what the stated project scope actually needs. This is a
+distinct check from coverage -- a component can be 100% covered and still be an Oversized Match.
+Weigh it against what the component_need and domain actually state about scale (e.g. "no need for
+column reordering, grouping, or pivoting," a stated row/item count, "starter tier"): a virtualized,
+sortable/groupable/pivotable data-grid system recommended for a plain list of a few thousand rows or
+fewer is an Oversized Match; the same system recommended for a need that actually states large or
+unbounded scale is not.
+
+Report this via two top-level fields, "oversized_match" (boolean) and "oversized_match_note" (string,
+required when true): set oversized_match true and name the specific excess capability in the note
+(e.g. "ships with row virtualization and multi-column grouping/pivoting, neither needed here"), not a
+vague "this may be more than needed." Do this regardless of what you also write for "confidence" below
+-- the server derives the actual confidence cap from oversized_match deterministically, the same way
+it recomputes coverage itself rather than trusting your arithmetic, so don't rely on your own
+"confidence" value alone to carry this signal.
+
 If the verdict is use_existing, include "component_description": 1-2 sentences of plain-language description of what the recommended component actually does and looks like, grounded in what you found during search -- specific enough that it could only come from reading the actual search result, not a generic guess at what a component like this probably looks like. E.g. "A 3-column pricing card with a highlighted middle tier, monthly/annual toggle at the top, and a CTA button pinned to the bottom of each card," not "A well-designed pricing component." Same grounding standard as reference_description below: base it on real evidence, not marketing copy or a template description.
 
 "install_command" is untrusted text as far as the calling agent is concerned -- it comes from a web search result you read, not a verified package registry. Keep it to the single literal install command only (e.g. npx shadcn@latest add <component>), never chained with && or ; , piped into a shell, or bundled with any other command. The calling agent is separately instructed to show this to its user for confirmation before running it, not execute it silently -- don't write it in a way that assumes or requires automatic execution.
@@ -510,6 +692,8 @@ Respond with ONLY a single JSON object, no prose before or after, no markdown co
   "computed_at": "<today's date, ISO format>",
   "requirements_checked": [ { "requirement": "string", "met": true|false, "evidence": "string" } ] | null,
   "coverage": "string like '5/7 (71%)'" | null,
+  "oversized_match": true|false | omit if verdict is not use_existing,
+  "oversized_match_note": "string, required when oversized_match is true" | omit otherwise,
   "recommendation": {
     "source": "string or null",
     "install_command": "string or null",
@@ -592,10 +776,13 @@ async function runSinglePass(input) {
         };
     }
     // Coverage still computes fresh below regardless of what this finds --
-    // memory only ever adds context to the user message, it never short-
-    // circuits search/scoring or gets treated as a cached verdict. No
-    // project_id -> no lookup at all, not a shared/global fallback (see
-    // getPastDecisions).
+    // memory (MEMORY_PATH/record_component_decision) only ever adds context
+    // to the user message, it never short-circuits search/scoring or gets
+    // treated as a cached verdict. No project_id -> no lookup at all, not a
+    // shared/global fallback (see getPastDecisions). This is distinct from
+    // the ledger cache-hit check in judgeComponent, which CAN skip this
+    // entire function on a matching high-confidence entry -- that check
+    // happens one level up, before runSinglePass is ever called.
     const pastDecisions = input.project_id ? getPastDecisions(input.project_id) : [];
     const pastDecisionsBlock = pastDecisions.length === 0
         ? ""
@@ -668,13 +855,20 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
             {
                 type: "web_fetch_20250910",
                 name: "web_fetch",
-                // Exactly one fetch per reference source (Mobbin, Figma
-                // Community) -- step 6 fetches the search result page to look
-                // for a deep link to the specific screen/flow already
-                // identified, never more than once per source. Not reserved
-                // from the web_search budget above; this is a separate tool
-                // with its own separate cap.
-                max_uses: 2,
+                // 3 reserved slots, same "reserve, don't let an earlier step
+                // starve a later one's budget" pattern as web_search's
+                // SEARCH_BUDGET + 2 above: 1 for step 4's single candidate-
+                // verification fetch (re-checking the best-fitting candidate's
+                // real docs against the checklist, added to catch evidence
+                // errors search-snippet-only scoring was producing -- confirmed
+                // live: an invented feature claim and a missed real one, both on
+                // the same case, both from trusting search snippets over the
+                // actual page), and 2 for step 6's Mobbin + Figma Community
+                // deep-link checks (exactly one fetch per reference source,
+                // never more than once per source). Not reserved from the
+                // web_search budget above; this is a separate tool with its own
+                // separate cap.
+                max_uses: 3,
                 // Category/browse pages can be large, and all we need from them
                 // is a permalink, not the full page -- caps token cost of a
                 // fetch that turns out not to have a deep link after all.
@@ -804,6 +998,7 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
     // other enforce* functions above.
     parsed.checklist_source = checklistSource;
     parsed._meta = buildMeta(data.timings, data.usage);
+    parsed._meta.scoring_fetch = findScoringFetch(fetchCallDetails);
     // Same "server-side, not just prompt instruction" policy as the rest of
     // this file: a past_decision_signal is only trusted when this call
     // actually had past-decision context to consider. Strips a fabricated
@@ -1007,6 +1202,12 @@ function recordDecision(input) {
         action: input.action,
         source: input.source,
         timestamp: input.timestamp ?? new Date().toISOString(),
+        // Finite-number guard only -- no range/sanity clamp, since a caller's
+        // own estimate isn't Pattern's to second-guess. NaN/Infinity would
+        // corrupt memory.json's JSON on write, so those alone are rejected.
+        time_saved_minutes: typeof input.time_saved_minutes === "number" && Number.isFinite(input.time_saved_minutes)
+            ? input.time_saved_minutes
+            : undefined,
     };
     const memory = readMemory();
     const existing = memory[input.project_id] ?? [];
@@ -1022,6 +1223,269 @@ export function getPastDecisions(projectId) {
     const memory = readMemory();
     return memory[projectId] ?? [];
 }
+function hashConventions(existingStack) {
+    if (!existingStack)
+        return null;
+    return createHash("sha256").update(existingStack).digest("hex").slice(0, 16);
+}
+// Stable id for rolling up cost across recommend_component (verdict) and
+// report_build_cost (build) records for the "same" feature. A
+// caller-supplied id always wins (their own tracking -- a ticket id,
+// branch name, whatever is stable on their side); otherwise derive
+// deterministically from project_id+component_need so repeat calls for the
+// same feature land under the same key across sessions with no
+// coordination required between recommend_component and report_build_cost.
+function deriveFeatureId(componentNeed, projectId, provided) {
+    if (provided && provided.trim())
+        return provided.trim();
+    return createHash("sha256")
+        .update(`${projectId}::${componentNeed.trim().toLowerCase()}`)
+        .digest("hex")
+        .slice(0, 8);
+}
+// Same "missing/malformed collapses to empty" philosophy as readMemory,
+// but line-oriented (JSONL) rather than whole-file JSON -- a single
+// corrupted line (e.g. a hand-edited file, or a write that got cut off)
+// is skipped rather than failing the whole read.
+function readLedgerEntries(projectId) {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.project_id === projectId) {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return entries;
+}
+// The only entry point that writes ledger.jsonl. Validates every
+// candidate against the DistilledCandidate boundary before it ever touches
+// disk -- a raw object reaching here throws rather than silently
+// persisting (see assertDistilledCandidateShape).
+function appendLedgerEntry(entry) {
+    for (const candidate of entry.candidates_evaluated) {
+        assertDistilledCandidateShape(candidate);
+    }
+    mkdirSync(dirname(LEDGER_PATH), { recursive: true });
+    appendFileSync(LEDGER_PATH, JSON.stringify(entry) + "\n", "utf8");
+}
+// Verdict-serving match: deliberately stricter than findLedgerMatches
+// below (exact component_need/domain/framework, not keyword overlap)
+// since this decides whether a fresh API call gets skipped entirely, not
+// just what gets listed back to a caller browsing history.
+function findLedgerCacheHit(input, entries) {
+    const snapshot = hashConventions(input.existing_stack);
+    const needLower = input.component_need.trim().toLowerCase();
+    const ttlMs = LEDGER_TTL_DAYS * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const eligible = entries.filter((e) => {
+        if (e.component_need.trim().toLowerCase() !== needLower)
+            return false;
+        if (e.domain !== input.domain)
+            return false;
+        if (e.framework !== input.framework)
+            return false;
+        if (e.project_conventions_snapshot !== snapshot)
+            return false;
+        if (e.confidence !== "high")
+            return false;
+        if (e.reason !== "scored" && e.reason !== "no_candidates_found")
+            return false;
+        const age = now - new Date(e.timestamp).getTime();
+        if (!Number.isFinite(age) || age > ttlMs)
+            return false;
+        return true;
+    });
+    if (eligible.length === 0)
+        return null;
+    return eligible.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0];
+}
+// Broader listing for the read_ledger tool itself -- simple keyword match
+// on component_need (no embeddings, per the build plan's explicit v1
+// scope), not the strict exact match findLedgerCacheHit needs.
+function findLedgerMatches(projectId, componentNeed, limit = 20) {
+    let entries = readLedgerEntries(projectId);
+    if (componentNeed && componentNeed.trim()) {
+        const needle = componentNeed.trim().toLowerCase();
+        entries = entries.filter((e) => e.component_need.toLowerCase().includes(needle));
+    }
+    entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return entries.slice(0, limit);
+}
+// report_build_cost (cost-attribution build plan, 1.3) -- self-reported
+// build cost, cheapest option first, since Pattern has no visibility into
+// what happens after judgeComponent returns a verdict (1.4's
+// session-correlation fallback is a research spike only, not built here).
+// Stored as a second, separate JSONL file rather than mixed into
+// ledger.jsonl's LedgerEntry shape -- a BuildRecord has none of
+// LedgerEntry's verdict/coverage/candidate fields, and keeping the file
+// single-shape keeps read_ledger's existing output stable. Joined to
+// verdict records purely by feature_id, per the build plan's data model.
+const BUILD_LEDGER_PATH = process.env.PATTERN_BUILD_LEDGER_PATH ?? join(homedir(), ".pattern", "build_ledger.jsonl");
+function appendBuildRecord(record) {
+    mkdirSync(dirname(BUILD_LEDGER_PATH), { recursive: true });
+    appendFileSync(BUILD_LEDGER_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+// Same "missing/malformed collapses to empty, one bad line skipped not
+// fatal" philosophy as readLedgerEntries.
+function readBuildRecords(featureId) {
+    let raw;
+    try {
+        raw = readFileSync(BUILD_LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.feature_id === featureId) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return records;
+}
+function recordBuildCost(input) {
+    const record = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        project_id: input.project_id,
+        feature_id: input.feature_id,
+        tokens_used: typeof input.tokens_used === "number" && Number.isFinite(input.tokens_used) ? input.tokens_used : null,
+        cost_usd: input.cost_usd,
+        outcome: input.outcome,
+    };
+    appendBuildRecord(record);
+    return record;
+}
+// The "total cost per feature is queryable" rollup task 1.5 validates
+// against a hand total: every verdict-time ledger entry for this
+// project_id+feature_id (fresh judgments and $0 cache hits alike) plus
+// every self-reported build record for the same feature_id. project_id is
+// required, same as every other read here, so this never falls back to a
+// shared/global bucket across projects.
+// report_outcome_proxy (cost-attribution build plan Phase 2, 2.1-2.3) --
+// self-reported, same reasoning as report_build_cost: rework-rate and
+// time-to-merge both require real git history, and Pattern has no
+// process.cwd()/repo-path concept and no filesystem access to a caller's
+// repo at all (see project judgment ledger's own design notes) -- rather
+// than giving Pattern a new git-shelling-out capability, the calling
+// agent (which already has real repo access) computes these off its own
+// `git log`/`git blame` and reports the result here. This also makes
+// 2.4's exclusion check true by construction: nothing on this path ever
+// reads coverage_pct, confidence, or any other Pattern-produced field --
+// there simply isn't a code path from a verdict into an outcome proxy.
+// Append-only like every other record here: a feature can get multiple
+// proxy reports over time (time_to_merge_hours right after merge,
+// reworked/days_to_rework on a later re-check, status_at_30d once the
+// horizon passes) -- readers take the latest report per field via
+// latestOutcomeProxy below, not a running mutation of one row.
+const OUTCOME_PROXY_PATH = process.env.PATTERN_OUTCOME_PROXY_PATH ?? join(homedir(), ".pattern", "outcome_proxies.jsonl");
+function appendOutcomeProxyRecord(record) {
+    mkdirSync(dirname(OUTCOME_PROXY_PATH), { recursive: true });
+    appendFileSync(OUTCOME_PROXY_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+function readOutcomeProxyRecords(featureId) {
+    let raw;
+    try {
+        raw = readFileSync(OUTCOME_PROXY_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.feature_id === featureId) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return records;
+}
+// Merges every report for a feature into one view, most recent value per
+// field wins (not most recent record wins) -- so a status_at_30d reported
+// today doesn't get lost behind an unrelated reworked update reported
+// yesterday, and vice versa. history is still returned in full for anyone
+// who wants the raw timeline rather than just the merged snapshot.
+function latestOutcomeProxy(featureId) {
+    const records = readOutcomeProxyRecords(featureId).sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    if (records.length === 0)
+        return { merged: null, history: records };
+    const merged = {};
+    for (const r of records) {
+        if (r.reworked !== undefined)
+            merged.reworked = r.reworked;
+        if (r.days_to_rework !== undefined)
+            merged.days_to_rework = r.days_to_rework;
+        if (r.time_to_merge_hours !== undefined)
+            merged.time_to_merge_hours = r.time_to_merge_hours;
+        if (r.status_at_30d !== undefined)
+            merged.status_at_30d = r.status_at_30d;
+    }
+    return { merged, history: records };
+}
+function recordOutcomeProxy(input) {
+    if (input.reworked === undefined &&
+        input.days_to_rework === undefined &&
+        input.time_to_merge_hours === undefined &&
+        input.status_at_30d === undefined) {
+        throw new Error("report_outcome_proxy requires at least one of reworked, days_to_rework, time_to_merge_hours, or status_at_30d.");
+    }
+    const record = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        project_id: input.project_id,
+        feature_id: input.feature_id,
+        ...(input.reworked !== undefined ? { reworked: input.reworked } : {}),
+        ...(input.days_to_rework !== undefined ? { days_to_rework: input.days_to_rework } : {}),
+        ...(input.time_to_merge_hours !== undefined ? { time_to_merge_hours: input.time_to_merge_hours } : {}),
+        ...(input.status_at_30d !== undefined ? { status_at_30d: input.status_at_30d } : {}),
+    };
+    appendOutcomeProxyRecord(record);
+    return record;
+}
+function totalFeatureCost(projectId, featureId) {
+    const verdictEntries = readLedgerEntries(projectId).filter((e) => e.feature_id === featureId);
+    const buildRecords = readBuildRecords(featureId).filter((r) => !r.project_id || r.project_id === projectId);
+    const total = verdictEntries.reduce((sum, e) => sum + (e.cost_usd ?? 0), 0) +
+        buildRecords.reduce((sum, r) => sum + (r.cost_usd ?? 0), 0);
+    const { merged, history } = latestOutcomeProxy(featureId);
+    return {
+        feature_id: featureId,
+        verdict_entries: verdictEntries,
+        build_records: buildRecords,
+        total_cost_usd: Math.round(total * 10000) / 10000,
+        outcome_proxy: merged,
+        outcome_proxy_history: history,
+    };
+}
 // Orchestrates the ensemble: run once, and only pay for 2 more full
 // pipeline passes when the single-run result landed close enough to a
 // verdict threshold that a single item's judgment swinging could flip
@@ -1049,11 +1513,120 @@ function aggregateMeta(passes) {
         tokens_used: {
             input: metas.reduce((sum, m) => sum + m.tokens_used.input, 0),
             output: metas.reduce((sum, m) => sum + m.tokens_used.output, 0),
+            // Only present if every pass has it -- all passes go through the same
+            // buildMeta call site in practice, so a mix would mean something else
+            // changed; safer to omit than to silently sum a partial set.
+            ...(metas.every((m) => m.tokens_used.input_breakdown)
+                ? {
+                    input_breakdown: {
+                        fresh: metas.reduce((sum, m) => sum + (m.tokens_used.input_breakdown?.fresh ?? 0), 0),
+                        cache_write: metas.reduce((sum, m) => sum + (m.tokens_used.input_breakdown?.cache_write ?? 0), 0),
+                        cache_read: metas.reduce((sum, m) => sum + (m.tokens_used.input_breakdown?.cache_read ?? 0), 0),
+                    },
+                }
+                : {}),
         },
         estimated_cost_usd: Math.round(metas.reduce((sum, m) => sum + m.estimated_cost_usd, 0) * 10000) / 10000,
     };
 }
+// Builds the LedgerEntry appended after a judgment -- fresh (non-cache-hit)
+// or a ledger cache hit, distinguished by opts.cacheHit/opts.costUsd (a
+// cache hit is always real $0, a fresh call carries its own
+// _meta.estimated_cost_usd; callers pass that in rather than this function
+// reaching into result._meta itself, since the cache-hit path's synthetic
+// _meta shouldn't be treated as equivalent to a real one).
+// checklist/checklist_source come from the result itself, not input.checklist
+// -- that field captures what was actually scored regardless of whether the
+// caller pre-supplied it or this call extracted it internally.
+function buildLedgerEntry(input, projectId, result, opts) {
+    const candidate = distillCandidate(result);
+    const checklist = Array.isArray(result.requirements_checked)
+        ? result.requirements_checked.map((r) => r.requirement).filter((r) => !!r)
+        : [];
+    return {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        project_id: projectId,
+        feature_id: deriveFeatureId(input.component_need, projectId, opts.featureId ?? input.feature_id),
+        component_need: input.component_need,
+        domain: input.domain,
+        framework: input.framework,
+        checklist,
+        checklist_source: result.checklist_source ?? "extracted",
+        candidates_evaluated: candidate ? [candidate] : [],
+        verdict: result.verdict,
+        chosen_candidate: candidate?.name ?? null,
+        confidence: result.confidence,
+        reason: result.reason,
+        coverage: result.coverage ?? null,
+        cost_usd: opts.costUsd,
+        cache_hit: opts.cacheHit,
+        project_conventions_snapshot: hashConventions(input.existing_stack),
+    };
+}
 async function judgeComponent(input) {
+    // The one deliberate exception to "coverage is scored fresh every time"
+    // (see file header and runSinglePass's memory-lookup comment) -- bounded
+    // by exact component_need/domain/framework/conventions match, confidence
+    // "high", and LEDGER_TTL_DAYS staleness. Checked before the skip-list
+    // fast-path so a skip-list primitive never bothers with a ledger read.
+    // Gated by LEDGER_CACHE_HIT_ENABLED (PATTERN_NO_LEDGER_CACHE_HIT) so the
+    // "always fresh" behavior can be restored without removing this code.
+    const ledgerCacheHit = LEDGER_CACHE_HIT_ENABLED && !isSkipListMatch(input.component_need) && input.project_id
+        ? findLedgerCacheHit(input, readLedgerEntries(input.project_id))
+        : null;
+    if (ledgerCacheHit) {
+        console.error(JSON.stringify({
+            diagnostic: "ledger_cache_hit",
+            project_id: input.project_id,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_timestamp: ledgerCacheHit.timestamp,
+        }));
+        const candidate = ledgerCacheHit.candidates_evaluated[0] ?? null;
+        const result = {
+            verdict: ledgerCacheHit.verdict,
+            confidence: ledgerCacheHit.confidence,
+            reason: "ledger_cache_hit",
+            coverage: ledgerCacheHit.coverage,
+            requirements_checked: null,
+            recommendation: candidate
+                ? { source: candidate.source, install_command: null, component_description: candidate.name, reference: null }
+                : null,
+            ensemble: { triggered: false },
+            checklist_source: ledgerCacheHit.checklist_source,
+            served_from_ledger: true,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_verdict_timestamp: ledgerCacheHit.timestamp,
+            _meta: {
+                total_ms: 1,
+                breakdown_ms: { extract: 1, search: 0, score: 0 },
+                tokens_used: { input: 0, output: 0 },
+                estimated_cost_usd: 0,
+            },
+        };
+        captureRecommendation({
+            projectId: input.project_id,
+            verdict: result.verdict,
+            confidence: result.confidence,
+            reason: result.reason,
+            ensembleTriggered: false,
+            estimatedCostUsd: 0,
+            servedFromLedger: true,
+        });
+        // Cost-attribution build plan, 1.1: log feature_id on every ledger
+        // write, cache hit included -- not just fresh judgments -- so a
+        // feature's total cost rolls up correctly even when most of its later
+        // calls cost $0 via this exact short-circuit. Inherits the matched
+        // entry's feature_id unless this call explicitly supplies its own.
+        if (input.project_id) {
+            appendLedgerEntry(buildLedgerEntry(input, input.project_id, result, {
+                costUsd: 0,
+                cacheHit: true,
+                featureId: input.feature_id ?? ledgerCacheHit.feature_id,
+            }));
+        }
+        return JSON.stringify(result);
+    }
     // Session cap and local logging both apply only to calls that actually
     // reach the API -- skip-list hits never do, so both are excluded here
     // on the same condition rather than counted/logged and refunded.
@@ -1075,6 +1648,23 @@ async function judgeComponent(input) {
         first.result.ensemble = { triggered: false };
         if (reachesApi)
             logCall(input, first.result);
+        if (reachesApi && input.project_id && (first.result.reason === "scored" || first.result.reason === "no_candidates_found")) {
+            appendLedgerEntry(buildLedgerEntry(input, input.project_id, first.result, {
+                costUsd: first.result._meta?.estimated_cost_usd ?? 0,
+                cacheHit: false,
+            }));
+        }
+        if (reachesApi) {
+            captureRecommendation({
+                projectId: input.project_id,
+                verdict: first.result.verdict,
+                confidence: first.result.confidence,
+                reason: first.result.reason,
+                ensembleTriggered: false,
+                estimatedCostUsd: first.result._meta?.estimated_cost_usd ?? null,
+                servedFromLedger: false,
+            });
+        }
         return JSON.stringify(first.result);
     }
     console.error(JSON.stringify({
@@ -1082,13 +1672,37 @@ async function judgeComponent(input) {
         reason: first.result.reason,
         coverage: first.result.coverage,
     }));
-    const [second, third] = await Promise.all([runSinglePass(input), runSinglePass(input)]);
-    const passes = [first, second, third].filter((p) => p.ok);
-    const verdicts = passes.map((p) => p.result.verdict);
-    const counts = new Map();
+    // Adaptive escalation: run only a 2nd pass first. A binary verdict
+    // (use_existing | custom_build) can only tie at 2 passes, never at 3 --
+    // so we escalate to a 3rd pass ONLY on that 1/1 tie, which is exactly
+    // the case that actually needs a tie-break. When the 2nd pass agrees
+    // with the 1st, that agreement is itself the answer and a 3rd pass
+    // would just spend real API cost confirming what's already settled.
+    // This does not touch the correctness guarantee for genuine
+    // disagreement -- it still always resolves via an odd-numbered
+    // majority vote, same as the flat 3-run version this replaces.
+    const second = await runSinglePass(input);
+    let passes = [first, second].filter((p) => p.ok);
+    let verdicts = passes.map((p) => p.result.verdict);
+    let counts = new Map();
     for (const v of verdicts)
         counts.set(v, (counts.get(v) ?? 0) + 1);
-    const [majorityVerdict, majorityCount] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    let sortedCounts = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    const isTwoWayTie = passes.length === 2 && sortedCounts.length === 2 && sortedCounts[0][1] === sortedCounts[1][1];
+    if (isTwoWayTie) {
+        console.error(JSON.stringify({
+            diagnostic: "ensemble_tie_escalated",
+            runs: verdicts,
+        }));
+        const third = await runSinglePass(input);
+        passes = [first, second, third].filter((p) => p.ok);
+        verdicts = passes.map((p) => p.result.verdict);
+        counts = new Map();
+        for (const v of verdicts)
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+        sortedCounts = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    }
+    const [majorityVerdict, majorityCount] = sortedCounts[0];
     const agreement = `${majorityCount}/${passes.length}`;
     // Use a pass whose own verdict already matches the majority as the base
     // for everything else in the response (recommendation, coverage,
@@ -1111,7 +1725,16 @@ async function judgeComponent(input) {
     if (majorityCount < passes.length)
         base.confidence = "low";
     base.ensemble = { triggered: true, runs: verdicts, agreement };
+    // Captured before aggregateMeta overwrites base._meta (same object as
+    // winningPass.result._meta) with a fresh summed-across-passes object --
+    // scoring_fetch isn't summed like cost/tokens, it describes whichever
+    // single pass's evidence actually became requirements_checked/
+    // recommendation below, so it must come from the winning pass
+    // specifically, not be dropped by aggregateMeta not knowing about it.
+    const winningScoringFetch = winningPass.result._meta?.scoring_fetch;
     base._meta = aggregateMeta(passes) ?? base._meta;
+    if (base._meta)
+        base._meta.scoring_fetch = winningScoringFetch;
     console.error(JSON.stringify({
         diagnostic: "ensemble_decision",
         runs: verdicts,
@@ -1123,6 +1746,21 @@ async function judgeComponent(input) {
     // reachable for calls that passed the skip-list check above -- always
     // reachesApi === true here, no guard needed.
     logCall(input, base);
+    if (input.project_id && (base.reason === "scored" || base.reason === "no_candidates_found")) {
+        appendLedgerEntry(buildLedgerEntry(input, input.project_id, base, {
+            costUsd: base._meta?.estimated_cost_usd ?? 0,
+            cacheHit: false,
+        }));
+    }
+    captureRecommendation({
+        projectId: input.project_id,
+        verdict: base.verdict,
+        confidence: base.confidence,
+        reason: base.reason,
+        ensembleTriggered: true,
+        estimatedCostUsd: base._meta?.estimated_cost_usd ?? null,
+        servedFromLedger: false,
+    });
     return JSON.stringify(base);
 }
 // The model's stated `coverage` string doesn't always match its own
@@ -1177,6 +1815,38 @@ export function parseCoveragePercent(coverage) {
     }
     return null;
 }
+const ALLOWED_DISTILLED_CANDIDATE_KEYS = new Set(["source", "name", "url", "coverage_pct"]);
+// Throws rather than silently stripping unknown keys -- a raw object
+// reaching this function is a bug (some caller skipped distillCandidate),
+// and failing loudly is what makes "Pattern never persists scraped source"
+// a checkable claim rather than a hopeful one.
+export function assertDistilledCandidateShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("DistilledCandidate must be a plain object");
+    }
+    const keys = Object.keys(value);
+    const extra = keys.filter((k) => !ALLOWED_DISTILLED_CANDIDATE_KEYS.has(k));
+    if (extra.length > 0) {
+        throw new Error(`DistilledCandidate has disallowed key(s): ${extra.join(", ")}`);
+    }
+}
+// Only ever called for verdict "use_existing" with a populated
+// recommendation -- custom_build has no existing candidate to distill, so
+// candidates_evaluated/chosen_candidate stay empty/null in the ledger for
+// those. `url` reuses the already fetch-verified scoring_fetch URL
+// (see JudgmentResult._meta.scoring_fetch) rather than inventing a second
+// notion of "the candidate's real page" -- if that fetch didn't happen or
+// failed, url is null rather than falling back to an unverified guess.
+export function distillCandidate(result) {
+    if (result.verdict !== "use_existing" || !result.recommendation)
+        return null;
+    return {
+        source: result.recommendation.source ?? null,
+        name: result.recommendation.component_description ?? null,
+        url: result._meta?.scoring_fetch?.succeeded ? result._meta.scoring_fetch.url ?? null : null,
+        coverage_pct: parseCoveragePercent(result.coverage),
+    };
+}
 export function enforceVerdictThreshold(parsed) {
     if (parsed.reason !== "scored")
         return;
@@ -1187,7 +1857,26 @@ export function enforceVerdictThreshold(parsed) {
     let correctConfidence;
     if (pct >= 80) {
         correctVerdict = "use_existing";
-        correctConfidence = "high";
+        // Oversized Match overrides the coverage-only threshold -- a candidate
+        // can satisfy every requirement and still be the wrong call if it's
+        // disproportionate to the stated scope (see step 5's Oversized Match
+        // check and the JudgmentResult.oversized_match comment). Deliberately
+        // keyed off the model's own oversized_match flag, not its "confidence"
+        // field -- confirmed live that the model can correctly reason through
+        // an Oversized Match in oversized_match_note and still leave
+        // "confidence": "high" unchanged, so that field alone can't be trusted
+        // to carry this signal.
+        if (parsed.oversized_match === true) {
+            correctConfidence = "low";
+            console.error(JSON.stringify({
+                diagnostic: "oversized_match_confidence_capped",
+                coverage: parsed.coverage,
+                note: parsed.oversized_match_note ?? null,
+            }));
+        }
+        else {
+            correctConfidence = "high";
+        }
     }
     else if (pct >= 40) {
         correctVerdict = "use_existing";
@@ -1275,6 +1964,20 @@ export const DOMAIN_FOR_SOURCE_KEYWORD = {
     mobbin: "mobbin.com",
     figma: "figma.com",
 };
+// Distinguishes step 4's single candidate-verification fetch from step 6's
+// Mobbin/Figma reference fetches -- both use the same web_fetch tool and
+// the same reserved budget's underlying diagnostics, so this identifies
+// step 4's fetch as whichever call (if any) targets a domain that ISN'T a
+// reference source. Diagnostic only, feeding _meta.scoring_fetch -- never
+// used to correct or invalidate individual requirement judgments (see that
+// field's own comment for why there's no safe fallback to correct to).
+export function findScoringFetch(fetchCallDetails) {
+    const referenceDomains = Object.values(DOMAIN_FOR_SOURCE_KEYWORD);
+    const candidateFetch = fetchCallDetails.find((d) => d.url && !referenceDomains.some((domain) => d.url.includes(domain)));
+    if (!candidateFetch)
+        return { attempted: false, succeeded: false, url: null };
+    return { attempted: true, succeeded: candidateFetch.succeeded, url: candidateFetch.url ?? null };
+}
 // Figma Community's own URL structure makes a "/community/file/<id>/<slug>"
 // URL inherently specific to one file -- unlike Mobbin's "/explore/..."
 // category pages, there's no browse-vs-specific gap to resolve here.
@@ -1438,7 +2141,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "Omit it to keep today's default behavior unchanged. The response " +
                 "always includes checklist_source ('extracted' | 'provided') and " +
                 "an internal _meta block (timing/token/cost accounting) -- neither " +
-                "affects the verdict itself.",
+                "affects the verdict itself. Surface _meta.estimated_cost_usd to " +
+                "the user after the call (e.g. 'that judgment cost ~$0.12'), the " +
+                "same way install_command is shown before running -- it's real " +
+                "spend against the user's own API key, not internal bookkeeping " +
+                "to keep from them.",
             inputSchema: INPUT_SCHEMA,
         },
         {
@@ -1454,7 +2161,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "heuristic based on how specific component_need is, not a " +
                 "calibrated signal -- treat 'low' as a hint to reread the input, " +
                 "not a hard error. Cheaper and faster than recommend_component " +
-                "since it makes no search calls at all.",
+                "since it makes no search calls at all. Also returns an internal " +
+                "_meta block -- surface _meta.estimated_cost_usd to the user " +
+                "after the call, same as recommend_component.",
             inputSchema: EXTRACT_REQUIREMENTS_INPUT_SCHEMA,
         },
         {
@@ -1467,9 +2176,60 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "calls with the same project_id will see this decision as a " +
                 "consistency signal, not a binding rule. Use a stable project_id " +
                 "(e.g. the project's directory path or name) so decisions are " +
-                "grouped correctly and never mixed with another project's.",
+                "grouped correctly and never mixed with another project's. Pass " +
+                "time_saved_minutes (optional) if you have a genuine estimate of how " +
+                "much time this decision saved you -- this is your own self-reported " +
+                "number, never computed or verified by Pattern.",
             inputSchema: RECORD_DECISION_INPUT_SCHEMA,
         },
+        {
+            name: READ_LEDGER_TOOL_NAME,
+            description: "Lists past recommend_component judgment entries for a project_id -- " +
+                "every call that reached the API and produced a verdict, not just " +
+                "ones you explicitly confirmed via record_component_decision. Each " +
+                "entry holds only distilled fields (verdict, confidence, coverage, " +
+                "chosen candidate's source/name/url) -- never the original " +
+                "per-requirement evidence text. Useful for auditing what Pattern has " +
+                "already judged for a project, or for understanding why a later " +
+                "call came back with served_from_ledger: true (see recommend_component " +
+                "-- a high-confidence entry here, matching on component_need/domain/" +
+                "framework/existing_stack and recent enough, can be served directly " +
+                "instead of a fresh search+score).",
+            inputSchema: READ_LEDGER_INPUT_SCHEMA,
+        },
+        {
+            name: REPORT_BUILD_COST_TOOL_NAME,
+            description: "Self-reports the end-to-end build cost for one feature -- call this " +
+                "once when the build a recommend_component verdict fed into is " +
+                "actually complete (shipped, abandoned, or replaced), not on every " +
+                "verdict. Pattern only ever sees the cost of judging what to use; " +
+                "everything past that -- the actual scaffold, install, or custom " +
+                "build -- happens outside Pattern entirely, so this is the only way " +
+                "that cost gets attributed back to the feature. Pass the same " +
+                "feature_id you used (or that recommend_component derived) for this " +
+                "feature's judgment call(s), so read_ledger's feature_id rollup can " +
+                "join this record to them. This only appends a local record; it " +
+                "never re-runs any judgment and never calls the Anthropic API.",
+            inputSchema: REPORT_BUILD_COST_INPUT_SCHEMA,
+        },
+        {
+            name: REPORT_OUTCOME_PROXY_TOOL_NAME,
+            description: "Self-reports a value signal for one feature that is deliberately " +
+                "independent of Pattern's own verdict -- never derive any of these " +
+                "fields from coverage_pct, confidence, or anything else Pattern " +
+                "returned; they only mean something if they could contradict the " +
+                "verdict. Compute reworked/days_to_rework and time_to_merge_hours " +
+                "from your own repo's real git history (e.g. `git log --follow` " +
+                "against the files this feature's build touched) -- never guess " +
+                "them. Report status_at_30d only once a real ~30-day-post-merge " +
+                "horizon has actually passed. Safe to call more than once for the " +
+                "same feature_id as more signal becomes available over time (e.g. " +
+                "time_to_merge_hours right after merge, reworked on a later check, " +
+                "status_at_30d at the 30-day mark) -- read_ledger's feature_id " +
+                "rollup merges every report into one latest-value-per-field view. " +
+                "This only appends a local record; it never calls the Anthropic API.",
+            inputSchema: REPORT_OUTCOME_PROXY_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1483,6 +2243,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            if (/Anthropic API error \d+/.test(message)) {
+                captureApiError({ tool: TOOL_NAME, message, projectId: args.project_id });
+            }
             return {
                 content: [{ type: "text", text: `Error: ${message}` }],
                 isError: true,
@@ -1511,6 +2274,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            if (/Anthropic API error \d+/.test(message)) {
+                captureApiError({ tool: EXTRACT_REQUIREMENTS_TOOL_NAME, message });
+            }
             return {
                 content: [{ type: "text", text: `Error: ${message}` }],
                 isError: true,
@@ -1538,13 +2304,84 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === READ_LEDGER_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            if (args.feature_id) {
+                const rollup = totalFeatureCost(args.project_id, args.feature_id);
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, ...rollup }) }],
+                };
+            }
+            const entries = findLedgerMatches(args.project_id, args.component_need, args.limit);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, entries }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === REPORT_BUILD_COST_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const record = recordBuildCost(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ status: "recorded", record }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === REPORT_OUTCOME_PROXY_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const record = recordOutcomeProxy(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ status: "recorded", record }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {
+    printTelemetryNoticeOnce();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Best-effort telemetry drain on clean shutdown -- no-op when telemetry
+    // was never enabled (see src/telemetry.ts).
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, async () => {
+            await shutdownTelemetry();
+            process.exit(0);
+        });
+    }
+}
+// Guard exists so verification scripts (e.g. verify-ledger-boundary.mjs)
+// can import this module's exported pure functions (distillCandidate,
+// assertDistilledCandidateShape, parseCoveragePercent, etc.) without also
+// spinning up a stdio server that blocks on stdin. Real usage (the bin
+// entry point, `npx pattern-mcp`) never sets this, so autostart is
+// unaffected.
+if (!process.env.PATTERN_NO_AUTOSTART) {
+    main().catch((err) => {
+        console.error("Fatal error starting pattern-mcp:", err);
+        process.exit(1);
+    });
 }
-main().catch((err) => {
-    console.error("Fatal error starting pattern-mcp:", err);
-    process.exit(1);
-});