pattern-mcp 0.3.0 → 0.4.0

package/README.md

@@ -32,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes four tools:
+It exposes six tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -44,7 +44,16 @@ It exposes four tools:
   account.
 - `read_ledger` — lists past `recommend_component` judgments for a
   `project_id`, including any that were served from the ledger cache (see
-  [Per-project judgment ledger](#per-project-judgment-ledger)).
+  [Per-project judgment ledger](#per-project-judgment-ledger)); pass
+  `feature_id` instead of browsing by keyword to get a full cost rollup for
+  one feature (see [Tool: `report_build_cost`](#tool-report_build_cost)).
+- `report_build_cost` — self-reports the end-to-end build cost for one
+  feature, so cost incurred after Pattern's own verdict (the actual
+  scaffold/install/build) is still attributable back to it.
+- `report_outcome_proxy` — self-reports a value signal (rework, time to
+  merge, kept-vs-replaced) for one feature, deliberately independent of
+  Pattern's own verdict -- see [Outcome
+  proxies](#outcome-proxies).
 
 ## How it works
 
@@ -409,6 +418,16 @@ Leave `checklist` out to keep today's default behavior: `recommend_component`
 extracts its own checklist internally, exactly as before this option
 existed.
 
+#### `feature_id`
+
+`feature_id` is optional -- a stable identifier for the feature this
+component need belongs to (e.g. a ticket id or branch name). Its only use
+is joining this call's cost with a later
+[`report_build_cost`](#tool-report_build_cost) call for the same feature.
+Omit it to have one derived deterministically from `project_id` +
+`component_need`; only meaningful together with `project_id`. See
+[Feature cost attribution](#feature-cost-attribution).
+
 **Is the checklist actually skipped, not just re-derived?** Checked, not
 assumed. `breakdown_ms.extract` for a `checklist`-provided call is smaller
 than the default path's, but not near-zero -- which raised the question of
@@ -667,6 +686,10 @@ came back with `served_from_ledger: true`.
   match, no embeddings) against stored entries' `component_need`. Omit to
   list everything for the project.
 - `limit` is optional, defaults to 20. Most recent entries first.
+- `feature_id` is optional. When provided, `component_need` and `limit`
+  are ignored and the response is a full cost rollup for that one feature
+  instead of a keyword listing -- see [Feature cost
+  attribution](#feature-cost-attribution).
 
 ### Output
 
@@ -678,6 +701,7 @@ came back with `served_from_ledger: true`.
       "id": "a1b2c3d4-...",
       "timestamp": "2026-08-29T19:50:47.073Z",
       "project_id": "my-booking-app",
+      "feature_id": "3f9a21c0",
       "component_need": "cancellation policy display with refund tiers by date",
       "domain": "Airbnb-style rental marketplace",
       "framework": "React + Tailwind",
@@ -691,24 +715,210 @@ came back with `served_from_ledger: true`.
       "confidence": "low",
       "reason": "scored",
       "coverage": "5/8 (62.5%)",
+      "cost_usd": 0.087,
+      "cache_hit": false,
       "project_conventions_snapshot": "9f3a1c7e2b0d4f5a"
     }
   ]
 }
 ```
 
+Passing `feature_id` instead returns:
+
+```json
+{
+  "project_id": "my-booking-app",
+  "feature_id": "3f9a21c0",
+  "verdict_entries": [ "...same shape as above, filtered to this feature_id..." ],
+  "build_records": [
+    { "id": "...", "timestamp": "...", "project_id": "my-booking-app", "feature_id": "3f9a21c0", "tokens_used": 9000, "cost_usd": 1.25, "outcome": "shipped" }
+  ],
+  "total_cost_usd": 1.34,
+  "outcome_proxy": { "time_to_merge_hours": 3.5, "reworked": true, "days_to_rework": 12, "status_at_30d": "kept" },
+  "outcome_proxy_history": [ "...every raw report_outcome_proxy record for this feature_id, oldest first..." ]
+}
+```
+
+`outcome_proxy` is `null` (and `outcome_proxy_history` an empty array)
+when no `report_outcome_proxy` calls have been made for this feature yet
+-- see [Outcome proxies](#outcome-proxies).
+
 Each entry holds only distilled fields -- `candidates_evaluated` never
 contains raw HTML, full prop tables, or the per-requirement evidence text
 `recommend_component` itself returns. See
 [Data minimization](#data-minimization) below.
 
+## Tool: `report_build_cost`
+
+Self-reports the end-to-end build cost for one feature. Pattern only ever
+sees the cost of judging *what* to use (`recommend_component`'s own
+`_meta.estimated_cost_usd`); everything past that -- the actual scaffold,
+install, or custom build -- happens outside Pattern entirely and Pattern
+has no way to observe it. Call this once, after the calling agent's build
+for a feature is actually complete (shipped, abandoned, or replaced), not
+on every verdict.
+
+### Input
+
+```json
+{
+  "feature_id": "3f9a21c0",
+  "project_id": "my-booking-app",
+  "tokens_used": 9000,
+  "cost_usd": 1.25,
+  "outcome": "shipped"
+}
+```
+
+- `feature_id` is required -- either a value you explicitly passed to an
+  earlier `recommend_component` call for this feature, or (if you didn't)
+  the same value `recommend_component` derives on its own:
+  `sha256(project_id + "::" + component_need, lowercased/trimmed)`
+  truncated to 8 hex characters. 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` is optional but recommended -- without it, this record
+  still joins to a `recommend_component` entry by `feature_id` alone, but
+  `read_ledger`'s rollup can't scope it to one project.
+- `tokens_used` is optional.
+- `cost_usd` is required -- your own real number, not Pattern's.
+- `outcome` is required: `"shipped"`, `"abandoned"`, or
+  `"replaced_with_existing"`.
+
+### Output
+
+```json
+{
+  "status": "recorded",
+  "record": {
+    "id": "c5706b47-...",
+    "timestamp": "2026-09-02T01:25:29.653Z",
+    "project_id": "my-booking-app",
+    "feature_id": "3f9a21c0",
+    "tokens_used": 9000,
+    "cost_usd": 1.25,
+    "outcome": "shipped"
+  }
+}
+```
+
+This only appends a local record to `~/.pattern/build_ledger.jsonl`
+(override with `PATTERN_BUILD_LEDGER_PATH`) -- it never re-runs any
+judgment and never calls the Anthropic API.
+
+## Tool: `report_outcome_proxy`
+
+Self-reports a value signal for one feature, deliberately independent of
+Pattern's own verdict -- the whole point is a signal that could
+*contradict* the verdict, so nothing on this path ever reads
+`coverage_pct`, `confidence`, or any other Pattern-produced field. 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) -- Pattern has no `process.cwd()`/repo-path
+concept and no filesystem access to your repo at all, so it can't compute
+these itself. 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 re-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 (a later report only overwrites the specific
+fields it includes, never the others).
+
+### Input
+
+```json
+{
+  "feature_id": "3f9a21c0",
+  "project_id": "my-booking-app",
+  "reworked": true,
+  "days_to_rework": 12
+}
+```
+
+- `feature_id` is required.
+- `project_id` is optional but recommended, same reasoning as
+  `report_build_cost`.
+- `reworked`, `days_to_rework`, `time_to_merge_hours`, `status_at_30d` are
+  all individually optional, but **at least one is required** -- an empty
+  report is rejected rather than silently recording nothing.
+
+### Output
+
+```json
+{
+  "status": "recorded",
+  "record": {
+    "id": "8a2f1e0c-...",
+    "timestamp": "2026-09-16T18:04:12.881Z",
+    "project_id": "my-booking-app",
+    "feature_id": "3f9a21c0",
+    "reworked": true,
+    "days_to_rework": 12
+  }
+}
+```
+
+This only appends a local record to `~/.pattern/outcome_proxies.jsonl`
+(override with `PATTERN_OUTCOME_PROXY_PATH`) -- it never calls the
+Anthropic API.
+
+## Feature cost attribution
+
+Every `recommend_component` call that writes to the ledger -- a fresh
+judgment *or* a $0 [ledger cache hit](#the-cache-hit-exception) -- now
+carries a `feature_id`, plus its own `cost_usd` and `cache_hit`. Pair that
+with `report_build_cost`'s build-time record and `read_ledger`'s
+`feature_id` rollup, and total spend on a feature (judgment + build,
+across however many calls) is queryable end to end, not just the cost of
+one verdict call.
+
+`feature_id` defaults to a deterministic derivation --
+`sha256(project_id + "::" + component_need)` truncated to 8 hex chars --
+so repeat calls for the same feature land under the same id automatically,
+with no coordination needed between `recommend_component` and
+`report_build_cost` calls. Pass your own `feature_id` explicitly (e.g. a
+ticket id or branch name) if you'd rather key on something stable on your
+own side.
+
+## Outcome proxies
+
+Cost data alone (`feature cost attribution` above) can't answer whether a
+cheaper build was actually *worth it* -- comparing it against Pattern's
+own verdict/`coverage_pct` would be circular, since that's the very thing
+being evaluated. `report_outcome_proxy` attaches a cheap, non-circular
+value signal per `feature_id` instead:
+
+- **`reworked` / `days_to_rework`** (primary proxy) -- was any file this
+  feature's build touched modified again after the original merge, and if
+  so, how soon? Computed from real git history, not Pattern's own data.
+- **`time_to_merge_hours`** (secondary proxy) -- how long the feature
+  took from first commit to merge.
+- **`status_at_30d`** (tertiary, longer-horizon proxy) -- at a ~30-day
+  horizon, does the component Pattern recommended still exist in the
+  codebase, unchanged in kind (`"kept"`), was it swapped for a different
+  approach (`"replaced"`), or removed entirely (`"removed"`)?
+
+`read_ledger`'s `feature_id` rollup returns both `outcome_proxy` (the
+merged latest-value-per-field view) and `outcome_proxy_history` (every
+raw report, in case the timeline itself matters) alongside the cost
+figures from [Feature cost attribution](#feature-cost-attribution) above
+-- so "what did this feature cost end to end, and did it hold up?" is
+answerable from one `read_ledger` call.
+
 ## Per-project judgment ledger
 
 Distinct from [per-project decision memory](#per-project-decision-memory)
 below -- that file only gains an entry when `record_component_decision` is
 explicitly called. The ledger instead gains one entry automatically for
-**every** `recommend_component` call that reaches the API with a
-`project_id` and lands on reason `"scored"` or `"no_candidates_found"`.
+**every** `recommend_component` call with a `project_id` that lands on
+reason `"scored"` or `"no_candidates_found"` -- whether that's a fresh
+call that reached the API, or a $0 [ledger cache
+hit](#the-cache-hit-exception) served without one (`cache_hit: true`,
+`cost_usd: 0`), so a feature's total cost still rolls up correctly even
+once most of its later calls are free. See [Feature cost
+attribution](#feature-cost-attribution).
 
 Pattern stores it locally in:
 
@@ -837,9 +1047,75 @@ recommendations.
 Local project memory and the local call log are stored on the machine
 running Pattern. They are not sent anywhere by Pattern itself.
 
+The one exception is opt-in telemetry, off by default -- see
+[Telemetry](#telemetry) below for exactly what it sends and how to turn
+it on or off.
+
 Review [SECURITY.md](./SECURITY.md) before putting sensitive information
 into fields such as `component_need`, `domain`, or project IDs.
 
+## Telemetry
+
+Off by default. Nothing is sent anywhere for telemetry purposes unless
+you explicitly set:
+
+```
+PATTERN_TELEMETRY=1
+```
+
+**The one-time notice.** The first time you run this version of Pattern
+-- whether it's a brand-new install or an upgrade from a version before
+telemetry existed -- it prints a short notice to stderr explaining all of
+this and how to opt in. It prints exactly once, ever (tracked by a marker
+file at `~/.pattern/telemetry_notice_shown`), then never again, regardless
+of whether you act on it. There's no interactive y/n prompt: Pattern's
+stdin is the MCP JSON-RPC channel the client uses to talk to it, so
+blocking on stdin for a keypress would fight the protocol handshake
+instead of showing a dialog -- a stderr notice is the safe equivalent for
+a stdio MCP server.
+
+**Why it exists.** Two things about real usage can't be answered from
+this repo alone: whether people actually come back and use Pattern on a
+second or third project on their own, and how often a BYO Anthropic key
+actually hits a rate limit or runs out of credit in real sessions, not
+just the one time that happened during manual testing (see
+[Known limitations](#known-limitations)). Telemetry answers both without
+requiring anyone to fill out a survey.
+
+**What gets sent, when enabled:**
+
+- An anonymous, randomly generated install ID -- a UUID created once and
+  stored at `~/.pattern/install_id` (overridable via
+  `PATTERN_INSTALL_ID_PATH`), never derived from your machine, username,
+  or any other identifying information. This is the only thing that ties
+  two events together as "the same install."
+- A one-way SHA-256 hash of `project_id`, truncated to 16 hex characters
+  -- never the raw `project_id` string. The hash lets Pattern count how
+  many *distinct* projects one install has used, without ever seeing what
+  those projects are named.
+- On every `recommend_component` call that reaches the API or the ledger
+  cache-hit shortcut: `verdict`, `confidence`, `reason`,
+  `ensemble_triggered`, `estimated_cost_usd`, and `served_from_ledger` --
+  the same distilled shape already written to the
+  [local call log](#local-call-log), not new information.
+- On a failed Anthropic API call specifically: the HTTP status code and a
+  coarse classification (`rate_limit`, `insufficient_credit`, or `other`)
+  -- never the request or response body.
+
+**What never gets sent, telemetry on or off:** `component_need`,
+`domain`, `framework`, `existing_stack`, `requirements_checked` evidence,
+the raw `project_id`, or your Anthropic API key.
+
+**Where it goes.** Events go to Pattern's PostHog project via its public,
+write-only project key (safe to ship in source -- it can send events, it
+cannot read data back). Set `PATTERN_POSTHOG_KEY` /
+`PATTERN_POSTHOG_HOST` to point at a different project, e.g. for
+self-hosting.
+
+**Turning it off** is the default -- just don't set `PATTERN_TELEMETRY`.
+If you'd previously enabled it, unset the variable (or set it to `0`) to
+go back to fully local.
+
 ## Cost
 
 Pattern uses the Anthropic API, so `recommend_component` has a cost.

package/dist/index.js

@@ -34,6 +34,7 @@ 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
@@ -227,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),
     };
@@ -375,6 +380,8 @@ 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: {
@@ -424,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"],
 };
@@ -497,9 +514,84 @@ 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"],
+};
 // 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
@@ -544,6 +636,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 +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",
@@ -1115,6 +1228,21 @@ 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);
+}
 // 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)
@@ -1197,6 +1325,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 +1513,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 +1547,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,6 +1559,8 @@ 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),
     };
 }
@@ -1295,6 +1604,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 +1649,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 +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,
@@ -1379,8 +1747,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 +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";
@@ -1798,6 +2197,39 @@ 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,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1811,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,
@@ -1839,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,
@@ -1869,6 +2307,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 +2326,52 @@ 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,
+            };
+        }
+    }
     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,

package/dist/telemetry.js

@@ -0,0 +1,222 @@
+/**
+ * Opt-in, anonymous product telemetry.
+ *
+ * Off by default. Enabling it (PATTERN_TELEMETRY=1) answers two questions
+ * the product can't answer any other way without asking users directly:
+ *
+ *  - Do people come back and use Pattern on a second or third project on
+ *    their own, unprompted? (tracked via distinct project hashes seen per
+ *    anonymous install, on every recommend_component call)
+ *  - How often does a BYO Anthropic key actually run dry or get rate
+ *    limited in real sessions, not just the one time it happened during
+ *    manual testing? (tracked via captureApiError)
+ *
+ * What gets sent, when enabled: an anonymous, randomly generated install
+ * ID (see installId() below); a one-way SHA-256 hash of project_id,
+ * truncated to 16 hex chars -- never the raw project_id string; the verdict
+ * shape already written to the local call log (verdict, confidence,
+ * ensemble_triggered, estimated cost); and, on a failed Anthropic API call,
+ * only the HTTP status and a coarse error classification (rate_limit /
+ * insufficient_credit / other) -- never the request or response body.
+ * component_need text, requirements_checked evidence, and the API key
+ * itself are never sent. See SECURITY.md and README.md for the full
+ * disclosure and the exact opt-in instructions.
+ *
+ * Reuses Pattern's existing PostHog project (the same one the marketing
+ * site sends browser events to) with its public, write-only project key --
+ * safe to embed in a distributed package the same way that key is already
+ * embedded in the site's client bundle. CLI events are namespaced with a
+ * "pattern_cli_" event prefix and source: "cli" so they're never confused
+ * with website traffic in queries or dashboards.
+ */
+import { PostHog } from "posthog-node";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// Opt-in, not opt-out -- deliberate, given who this tool is for. See
+// README's telemetry section: a local-first tool aimed at developers who
+// notice and care about silent tracking is exactly the audience §06 of the
+// product brief already flags as sensitive to "no paper trail" trust gaps.
+// Any of "1", "true", "yes" (case-insensitive) turns it on.
+const TELEMETRY_ENABLED = /^(1|true|yes)$/i.test(process.env.PATTERN_TELEMETRY ?? "");
+// One-time startup notice, printed to stderr -- the closest thing to an
+// opt-in prompt an MCP stdio server can safely show. stdin is the JSON-RPC
+// channel the client uses to talk to this process; blocking on it to read
+// a y/n keypress would fight the protocol handshake instead of showing a
+// dialog, so there's no safe way to do an interactive prompt here. This
+// prints once ever (gated by TELEMETRY_NOTICE_PATH, not by whether this is
+// a fresh install), so someone who installed Pattern before telemetry
+// existed sees it exactly once on their first run after upgrading, the
+// same as a brand-new install does on its first run ever. Call from
+// main() at startup -- never from inside a tool call, so it can't be
+// mistaken for a response to the calling agent.
+export function printTelemetryNoticeOnce() {
+    try {
+        readFileSync(TELEMETRY_NOTICE_PATH, "utf8");
+        return; // Already shown -- never repeat.
+    }
+    catch {
+        // No marker yet -- fall through and show it.
+    }
+    const status = TELEMETRY_ENABLED
+        ? "ON, because PATTERN_TELEMETRY is set"
+        : "OFF (the default -- nothing is sent unless you opt in)";
+    console.error([
+        "",
+        "Pattern -- one-time telemetry notice (this will not print again)",
+        `Anonymous usage telemetry is currently ${status}.`,
+        "",
+        "When enabled, Pattern sends an anonymous per-install ID, a one-way",
+        "hash of project_id (never the raw string), and the same verdict",
+        "summary already written to ~/.pattern/calls.log (verdict,",
+        "confidence, reason, estimated cost). component_need, domain,",
+        "framework, existing_stack, and your API key are never sent.",
+        "Full field list: https://github.com/donaldrichard19-LVD/pattern-mcp#telemetry",
+        "",
+        "To help improve Pattern by sharing anonymous usage data, opt in:",
+        "  PATTERN_TELEMETRY=1",
+        "Already on and want it off instead? Unset PATTERN_TELEMETRY (or set it to 0).",
+        "",
+    ].join("\n"));
+    try {
+        mkdirSync(dirname(TELEMETRY_NOTICE_PATH), { recursive: true });
+        writeFileSync(TELEMETRY_NOTICE_PATH, new Date().toISOString(), "utf8");
+    }
+    catch {
+        // Couldn't persist the marker -- worst case this prints again next
+        // run. Never blocks startup or a tool call over it.
+    }
+}
+// Public PostHog project API key (phc_...). Write-only: it can send events,
+// it cannot read or query data back, so it's safe to ship in source the
+// same way it's already shipped in the marketing site's client bundle.
+// Override for self-hosting or testing against a different project.
+const POSTHOG_KEY = process.env.PATTERN_POSTHOG_KEY ?? "phc_yUq5SpVfS9JxMm6QgFAYAfwzszAvbHQQsdN4xAqqJt3U";
+const POSTHOG_HOST = process.env.PATTERN_POSTHOG_HOST ?? "https://us.i.posthog.com";
+const INSTALL_ID_PATH = process.env.PATTERN_INSTALL_ID_PATH ?? join(homedir(), ".pattern", "install_id");
+// Marker for the one-time startup notice below -- deliberately a separate
+// file from install_id, not reused as an existence check. install_id gets
+// created the moment ANY telemetry function runs (including a disabled
+// no-op path in some future refactor); this marker exists purely to answer
+// "has this specific human seen the notice yet," so it's written only from
+// printTelemetryNoticeOnce itself.
+const TELEMETRY_NOTICE_PATH = process.env.PATTERN_TELEMETRY_NOTICE_PATH ?? join(homedir(), ".pattern", "telemetry_notice_shown");
+let cachedInstallId;
+// Stable per-install anonymous ID, generated once and persisted locally --
+// the distinct_id every telemetry event is keyed by. This is what makes
+// "same install, second project" observable at all; without it every event
+// would look like a brand-new anonymous user. Never derived from anything
+// that identifies a person or machine (no hostname, no MAC, no username) --
+// purely a random UUID with no way to reverse it to an identity.
+function installId() {
+    if (cachedInstallId)
+        return cachedInstallId;
+    try {
+        cachedInstallId = readFileSync(INSTALL_ID_PATH, "utf8").trim();
+        if (cachedInstallId)
+            return cachedInstallId;
+    }
+    catch {
+        // No file yet -- fall through and create one.
+    }
+    cachedInstallId = randomUUID();
+    try {
+        mkdirSync(dirname(INSTALL_ID_PATH), { recursive: true });
+        writeFileSync(INSTALL_ID_PATH, cachedInstallId, "utf8");
+    }
+    catch {
+        // Couldn't persist (e.g. read-only home dir) -- still usable for this
+        // process's lifetime, just won't be stable across restarts. Telemetry
+        // is best-effort by design; this never blocks a tool call.
+    }
+    return cachedInstallId;
+}
+// One-way hash so a project_id string (which may be a real repo/project
+// name someone doesn't want sent anywhere) never leaves the machine in
+// readable form, while still letting the same project produce the same
+// hash every time -- which is exactly what's needed to count distinct
+// projects per install without ever seeing what those projects are named.
+export function hashProjectId(projectId) {
+    return createHash("sha256").update(projectId).digest("hex").slice(0, 16);
+}
+// Classifies a thrown Anthropic API error by status code and the coarse
+// shape of the error body, without ever inspecting or forwarding the body
+// itself. Matches the two failure modes called out in the product brief's
+// Risks section (§06): a key that's out of money, and rate limiting.
+export function classifyApiError(message) {
+    const statusMatch = message.match(/Anthropic API error (\d+)/);
+    const status = statusMatch ? Number.parseInt(statusMatch[1], 10) : null;
+    if (status === 429)
+        return { type: "rate_limit", status };
+    if (status === 400 && /credit balance|insufficient/i.test(message)) {
+        return { type: "insufficient_credit", status };
+    }
+    return { type: "other", status };
+}
+let client;
+function getClient() {
+    if (!TELEMETRY_ENABLED || !POSTHOG_KEY)
+        return undefined;
+    if (!client) {
+        client = new PostHog(POSTHOG_KEY, {
+            host: POSTHOG_HOST,
+            // Low volume, long-lived process (an MCP server, not a batch job) --
+            // flush promptly rather than buffering, so an event isn't silently
+            // lost if the server process is killed shortly after a call.
+            flushAt: 1,
+            flushInterval: 0,
+        });
+    }
+    return client;
+}
+// Fire-and-forget by design: telemetry must never be able to slow down or
+// break a tool call. Every failure path here is swallowed, not surfaced --
+// including "telemetry is disabled," which is the common case.
+function capture(event, properties) {
+    const posthog = getClient();
+    if (!posthog)
+        return;
+    try {
+        posthog.capture({
+            distinctId: installId(),
+            event,
+            properties: { ...properties, source: "cli" },
+        });
+    }
+    catch {
+        // Never let a telemetry failure affect the tool call it's attached to.
+    }
+}
+export function captureRecommendation(args) {
+    capture("pattern_cli_recommend_component", {
+        project_hash: args.projectId ? hashProjectId(args.projectId) : null,
+        verdict: args.verdict ?? null,
+        confidence: args.confidence ?? null,
+        reason: args.reason ?? null,
+        ensemble_triggered: args.ensembleTriggered ?? false,
+        estimated_cost_usd: args.estimatedCostUsd ?? null,
+        served_from_ledger: args.servedFromLedger ?? false,
+    });
+}
+export function captureApiError(args) {
+    const { type, status } = classifyApiError(args.message);
+    capture("pattern_cli_api_error", {
+        tool: args.tool,
+        error_type: type,
+        status_code: status,
+        project_hash: args.projectId ? hashProjectId(args.projectId) : null,
+    });
+}
+// Best-effort drain on clean shutdown so the last event(s) of a session
+// aren't dropped. Safe to call even when telemetry was never enabled.
+export async function shutdownTelemetry() {
+    if (!client)
+        return;
+    try {
+        await client.shutdown();
+    }
+    catch {
+        // Ignore -- process is exiting either way.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/ui, 21st.dev, or ReUI component or requires a custom build, using field/requirement coverage scored against real component code.",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "posthog-node": "^5.51.4"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",