pattern-mcp 0.3.0 → 0.5.0

package/dist/index.js

@@ -30,10 +30,12 @@
 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 { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } 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
@@ -128,6 +130,64 @@ const MAX_DECISIONS_PER_PROJECT = 50;
 // 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);
+// Ledger integrity + decision provenance
+// (pattern-ledger-integrity-and-provenance-spec.md). This deliberately
+// reverses the principle stated above report_outcome_proxy elsewhere in
+// this file ("Pattern has no process.cwd()/repo-path concept and no
+// filesystem access to a caller's repo at all") -- but narrowly: the only
+// two things this grants are (1) checking whether one caller-supplied
+// file_path still exists / still mentions a chosen_candidate
+// (checkFileLiveStatus) and (2) reading the current commit SHA via
+// `git rev-parse HEAD` (computeSnapshotRef). Both are read-only, both are
+// scoped to PROJECT_ROOT (see resolveWithinRoot's traversal guard), and
+// neither ever runs an arbitrary shell command. report_build_cost/
+// report_outcome_proxy remain self-reported by design -- rework rate and
+// time-to-merge need real git *history*, a materially bigger and more
+// failure-prone surface than "does this one file exist right now" or
+// "what commit is HEAD."
+//
+// Defaults to process.cwd() -- for a locally-run stdio MCP server, that's
+// normally the consuming repo's root, since MCP hosts typically launch
+// the server with the project directory as its working directory. When
+// that assumption doesn't hold (or for tests), override with
+// PATTERN_PROJECT_ROOT.
+const PROJECT_ROOT = process.env.PATTERN_PROJECT_ROOT ?? process.cwd();
+// Belt-and-suspenders guard against a file_path (ultimately caller-
+// supplied, see recommend_component's input schema) that's absolute or
+// escapes PROJECT_ROOT via "../" -- the calling agent already has real fs
+// access to its own machine regardless, but a stray path should degrade
+// to "unknown" rather than silently stat-ing something outside the
+// project. Returns null (never throws) on anything that doesn't resolve
+// cleanly inside root.
+function resolveWithinRoot(root, relPath) {
+    if (!relPath || isAbsolute(relPath))
+        return null;
+    const resolved = resolve(root, relPath);
+    const rel = relative(root, resolved);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return resolved;
+}
+// Feature 2 / Decision Provenance, P0: best-effort commit SHA at
+// ledger-write time. Never throws -- not being in a git repo, git not
+// being installed, or the call simply timing out all degrade to null
+// rather than failing the judgment call that triggered this write (see
+// buildLedgerEntry). Read-only: `git rev-parse HEAD` never touches repo
+// state.
+function computeSnapshotRef(root) {
+    try {
+        const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 // 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
@@ -227,12 +287,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),
     };
@@ -375,6 +439,9 @@ 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 CHECK_LEDGER_LIVENESS_TOOL_NAME = "check_ledger_liveness";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -424,6 +491,26 @@ 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.",
+        },
+        file_path: {
+            type: "string",
+            description: "Optional. Path (relative to the project root) where this component " +
+                "decision is expected to be implemented, if already known -- usually " +
+                "not known yet at this call, since the decision typically precedes " +
+                "the file existing. When provided, it's stored on the resulting " +
+                "ledger entry and check_ledger_liveness can later confirm the file " +
+                "still exists and still references chosen_candidate. Omit if unknown; " +
+                "it cannot currently be attached to an entry after the fact.",
+        },
     },
     required: ["component_need", "domain", "framework"],
 };
@@ -497,6 +584,96 @@ const READ_LEDGER_INPUT_SCHEMA = {
             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"],
+};
+const CHECK_LEDGER_LIVENESS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in the recommend_component call(s) whose ledger entries you want live-checked.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "Optional. Check just this one entry (its id, from read_ledger) " +
+                "instead of every entry for project_id that has a file_path set.",
+        },
     },
     required: ["project_id"],
 };
@@ -544,6 +721,25 @@ 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.
@@ -581,6 +777,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",
@@ -1115,6 +1313,140 @@ function hashConventions(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);
+}
+// Overlay store for live-check results, same "append-only, latest-value-
+// per-key wins at read time, never mutate the source-of-truth line"
+// convention as outcome_proxies.jsonl/latestOutcomeProxy above -- a check
+// is a new observation, not a correction of the original ledger entry, so
+// ledger.jsonl itself stays untouched by it.
+const LEDGER_LIVENESS_PATH = process.env.PATTERN_LEDGER_LIVENESS_PATH ?? join(homedir(), ".pattern", "ledger_liveness.jsonl");
+function appendLedgerLivenessRecord(record) {
+    mkdirSync(dirname(LEDGER_LIVENESS_PATH), { recursive: true });
+    appendFileSync(LEDGER_LIVENESS_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+function readLedgerLivenessRecords(ledgerEntryId) {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_LIVENESS_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.ledger_entry_id === ledgerEntryId) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return records;
+}
+function latestLiveness(ledgerEntryId) {
+    const records = readLedgerLivenessRecords(ledgerEntryId).sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return records[0] ?? null;
+}
+function withLatestLiveness(entry) {
+    const latest = latestLiveness(entry.id);
+    if (!latest)
+        return entry;
+    return { ...entry, live_status: latest.live_status, last_verified_live: latest.timestamp };
+}
+// Feature 1 / Referential Integrity, P1: the single-entry live-check.
+// Orphaned when file_path is set but the file no longer exists; live when
+// the file exists and (best-effort) still mentions chosen_candidate;
+// unknown when file_path was never supplied, escapes PROJECT_ROOT (see
+// resolveWithinRoot), or exists but the candidate name can't be confirmed
+// in its content -- conservative on purpose, per the spec's own risk
+// mitigation (a false "orphaned" is worse than a lingering "unknown").
+// "dangling" (an entry only cross-referenced by other ledger entries, no
+// live anchor anywhere) is graph-level analysis across the whole ledger,
+// not a single-entry check -- Feature 1 P3, not built here.
+function checkFileLiveStatus(entry) {
+    if (!entry.file_path)
+        return "unknown";
+    const abs = resolveWithinRoot(PROJECT_ROOT, entry.file_path);
+    if (!abs)
+        return "unknown";
+    if (!existsSync(abs))
+        return "orphaned";
+    if (!entry.chosen_candidate)
+        return "live";
+    try {
+        const content = readFileSync(abs, "utf8");
+        return content.toLowerCase().includes(entry.chosen_candidate.toLowerCase()) ? "live" : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function checkLedgerEntryLiveness(entry) {
+    const record = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        ledger_entry_id: entry.id,
+        project_id: entry.project_id,
+        live_status: checkFileLiveStatus(entry),
+        checked_file_path: entry.file_path,
+    };
+    appendLedgerLivenessRecord(record);
+    return record;
+}
+// check_ledger_liveness tool: on-demand invocation of the live-check above
+// (the design's "on demand via an MCP call" case -- a scheduled/batch
+// sweep is Feature 1 P2, not built here). Entries with no file_path are
+// reported but never checked/recorded -- their status is permanently
+// "unknown" by construction, so re-checking them on every call would only
+// grow ledger_liveness.jsonl without ever learning anything new.
+function checkLedgerLiveness(input) {
+    const entries = readLedgerEntries(input.project_id).filter((e) => !input.ledger_entry_id || e.id === input.ledger_entry_id);
+    const results = entries.map((e) => {
+        if (!e.file_path) {
+            return {
+                ledger_entry_id: e.id,
+                component_need: e.component_need,
+                file_path: null,
+                live_status: "unknown",
+                checked_at: null,
+                note: "no file_path recorded on this entry -- nothing to check",
+            };
+        }
+        const record = checkLedgerEntryLiveness(e);
+        return {
+            ledger_entry_id: e.id,
+            component_need: e.component_need,
+            file_path: e.file_path,
+            live_status: record.live_status,
+            checked_at: record.timestamp,
+            note: null,
+        };
+    });
+    return {
+        checked: results.filter((r) => r.checked_at !== null).length,
+        total_entries: results.length,
+        results,
+    };
+}
 // 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)
@@ -1134,7 +1466,19 @@ function readLedgerEntries(projectId) {
         try {
             const parsed = JSON.parse(line);
             if (parsed && typeof parsed === "object" && parsed.project_id === projectId) {
-                entries.push(parsed);
+                // Backward-compatible defaults for entries written before the
+                // ledger integrity/provenance fields existed -- a missing key
+                // (not merely a null one) falls back to these rather than
+                // `undefined` leaking into the returned shape.
+                const rawEntry = parsed;
+                const normalized = {
+                    ...rawEntry,
+                    file_path: rawEntry.file_path ?? null,
+                    snapshot_ref: rawEntry.snapshot_ref ?? null,
+                    last_verified_live: rawEntry.last_verified_live ?? null,
+                    live_status: rawEntry.live_status ?? "unknown",
+                };
+                entries.push(withLatestLiveness(normalized));
             }
         }
         catch {
@@ -1197,6 +1541,167 @@ function findLedgerMatches(projectId, componentNeed, limit = 20) {
     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
@@ -1224,15 +1729,32 @@ 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 fresh (non-cache-hit) judgment.
+// 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) {
+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)
@@ -1241,6 +1763,7 @@ function buildLedgerEntry(input, projectId, result) {
         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,
@@ -1252,7 +1775,22 @@ function buildLedgerEntry(input, projectId, result) {
         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),
+        // Feature 2 P0: captured fresh for every entry (cache hits included),
+        // not inherited from a matched ledger_cache_hit -- this reflects the
+        // codebase state at the moment *this line* was written, not the
+        // moment the original judgment ran (see PROJECT_ROOT above).
+        snapshot_ref: computeSnapshotRef(PROJECT_ROOT),
+        // Feature 1 P0: caller-supplied at write time (recommend_component's
+        // optional file_path), null when not yet known -- typically the case,
+        // since the decision is usually made before the file exists. Always
+        // starts "unknown"/unchecked; check_ledger_liveness fills these in
+        // later via the ledger_liveness.jsonl overlay (see withLatestLiveness).
+        file_path: input.file_path ?? null,
+        last_verified_live: null,
+        live_status: "unknown",
     };
 }
 async function judgeComponent(input) {
@@ -1295,6 +1833,27 @@ async function judgeComponent(input) {
                 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
@@ -1319,7 +1878,21 @@ async function judgeComponent(input) {
         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));
+            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);
     }
@@ -1328,13 +1901,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,
@@ -1379,8 +1976,20 @@ async function judgeComponent(input) {
     // 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));
+        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
@@ -1477,7 +2086,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";
@@ -1798,6 +2426,57 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "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,
+        },
+        {
+            name: CHECK_LEDGER_LIVENESS_TOOL_NAME,
+            description: "Checks whether recommend_component ledger entries for a project_id " +
+                "are still 'live' -- the file_path recorded on the entry (if any) " +
+                "still exists and still mentions chosen_candidate. Requires real, " +
+                "read-only filesystem access to PROJECT_ROOT (defaults to this " +
+                "server's working directory; override with PATTERN_PROJECT_ROOT) -- " +
+                "this is the one exception to Pattern otherwise having no " +
+                "filesystem access to a caller's repo (see report_build_cost/" +
+                "report_outcome_proxy above). Entries with no file_path are listed " +
+                "but not checked -- their status is permanently 'unknown' since " +
+                "there's nothing to check. Never writes to your repo, never runs " +
+                "an arbitrary git/shell command beyond `git rev-parse HEAD` " +
+                "elsewhere in this server. Results are also layered onto " +
+                "read_ledger's live_status/last_verified_live fields for the same " +
+                "entries afterward.",
+            inputSchema: CHECK_LEDGER_LIVENESS_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1811,6 +2490,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,
@@ -1839,6 +2521,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,
@@ -1869,6 +2554,12 @@ 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 }) }],
@@ -1882,11 +2573,68 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    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,
+            };
+        }
+    }
+    if (request.params.name === CHECK_LEDGER_LIVENESS_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = checkLedgerLiveness(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, ...result }) }],
+            };
+        }
+        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,