opentel-mcp 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.9.0
+
+**⚠️ Fixed, with a fingerprint behavior change — read this before the
+feature below.** The `auth` failure classifier
+(`src/fingerprint/classify/auth.js`) missed "permission denied" and
+"access denied" — the standard phrasing from Unix, git, AWS IAM, and GCP
+for a permission/authorization failure. It only recognized
+HTTP-status-derived wording (`unauthorized`, `forbidden`,
+`authenticat(e|ion)`) plus 401/403 status codes and a handful of known
+auth-library error names. Messages using the OS/CLI phrasing above fell
+through every classifier and landed in the `internal` catch-all instead.
+Found by running realistic error text through this project's own UI demo
+(`packages/ui/demo/populate.js`) and checking what `DEFAULT_CLASSIFIERS`
+actually returned for it — not assumed. Now also matches "not authorized",
+"permission(s) denied", "access denied", "insufficient permission(s)", and
+Node's own `EACCES`/`EPERM` error codes; still does not match bare
+"authorized" or "permission" alone (see the classifier's own docblock for
+the false-positive cases this deliberately excludes, e.g. "user denied the
+permission request").
+
+**This changes fingerprints for affected messages.** `category` is one of
+the hashed inputs `computeFingerprint()` combines into
+`mcp.failure.fingerprint` (see ADR 006). A permission-denied failure that
+previously classified as `internal` now classifies as `auth` — the fields
+feeding the hash change, so the fingerprint itself changes for anyone whose
+tool emits this wording. This does **not** amend the closed 8-category
+taxonomy ADR 006 established (`validation | timeout | network | auth |
+dependency | serialization | internal | unknown`) — `auth` already existed;
+this is a pattern-coverage fix to when the existing category fires, not a
+new category. If you alert or dashboard on a specific `mcp.failure.fingerprint`
+value for a permission error, expect a new value after upgrading.
+
+### Added — `instanceKey`: sharing tracker state across `instrumentMcpServer()` calls
+
+`instanceKey` (a string option on `instrumentMcpServer()`, or the
+`OTEL_MCP_INSTANCE_KEY` env var — lower precedence than the option) lets
+repeated `instrumentMcpServer()` calls that pass the same key share Agent
+Thrash Detection, budget tracking, schema drift detection, and the
+`ToolOutcome` counter's state, instead of each call constructing all four
+fresh and discarding them. Fixes the gap documented in the README's
+"In-memory tracker state is scoped to one `instrumentMcpServer()` call"
+section and `docs/known-gaps.md` entry 6, under a "stateless" Streamable
+HTTP deployment shape (a fresh `Server`/`McpServer` re-instrumented on
+every incoming request). Full design: ADR 012
+(`docs/adr/012-tracker-lifecycle-and-shared-state.md`).
+
+Backed by an internal, bounded, TTL-evicting registry (1000 distinct keys
+per process, 24h TTL renewed on every use — both ADR 012's proposed
+defaults) — fully internal, no new public type. Omit `instanceKey` (the
+default) for behavior byte-identical to every prior version: trackers are
+constructed fresh on every call, and the registry is never touched.
+
+**⚠️ Composition requirement: `instanceKey` alone does not fix Agent
+Thrash Detection.** `ThrashDetector` looks episodes up by `(sessionId,
+toolName, fingerprint)` — `instanceKey` shares the tracker object, but
+without a real, transport-provided `extra.sessionId` on every call, each
+`instrumentMcpServer()` call still generates its own random per-connection
+fallback session id, fresh, regardless of `instanceKey`. Sharing the
+tracker doesn't help if the lookup key inside it differs every call —
+each request lands as its own one-off episode instead of contributing to
+one shared loop. Real Streamable HTTP transports provide a real session id
+automatically, so the common case works with `instanceKey` alone — but a
+custom `Transport`, `assumeSingleSession: true`, or anything else on the
+generated-fallback path will set `instanceKey`, see nothing happen, and
+have every reason to think the fix is broken. Same silent-inertness shape
+as the original gap, one layer deeper. See the README's new "instanceKey"
+section for the full explanation and what to do about it — this is not a
+footnote there either.
+
+**⚠️ Does not help across process boundaries.** `instanceKey`'s registry
+is one process's in-memory state. On Lambda, Cloud Run, or any
+horizontally-scaled deployment, concurrent/recycled instances each hold
+their own independent registry — passing the identical `instanceKey`
+string everywhere does not change that. Counters remain instance-local and
+best-effort by design; this is a structural limitation, not a
+configuration gap, and this library deliberately does not add an external
+store (Redis/DynamoDB) to close it — see ADR 012's Update section for the
+full reasoning.
+
+**Documentation:** the "Metrics" section now covers wiring the Prometheus
+exporter specifically (`@opentelemetry/exporter-prometheus`), not just the
+OTLP example that was already there. Its pull-based text exposition format
+does not attach resource attributes (including `service.name`) to
+individual metric points by default — only to a separate `target_info`
+series — which is invisible with one service but means every series looks
+identical the moment you're scraping more than one instrumented server
+into the same Prometheus. Documents the fix
+(`withResourceConstantLabels: /^service\.name$/`) with a worked example.
+No code change; this behavior was always there, just undocumented. Found
+building `dashboards/grafana-mcp-health.json`'s verification harness.
+
 ## 0.8.0
 
 Three features. **Tool schema drift detection**: a server that silently

package/README.md

@@ -234,6 +234,49 @@ opentel-mcp doesn't bundle them (see `package.json`'s `peerDependencies`).
 are already runtime dependencies of opentel-mcp itself (its `setupNodeSdk:
 true` dev path uses them), so no extra install is needed for those two.
 
+#### Using the Prometheus exporter instead of OTLP — `service.name` needs an extra option
+
+If you scrape metrics with `@opentelemetry/exporter-prometheus` (pull-based)
+rather than exporting over OTLP (push-based, the example above), be aware
+that the Prometheus exporter does **not** attach resource attributes —
+including `service.name` — to every metric point by default. It only
+exposes them on a separate `target_info` series, which most PromQL you'd
+actually write (`rate(mcp_tool_calls_total[5m])`, grouped `sum by
+(gen_ai_tool_name)`, etc.) never joins against. In a single-service setup
+this is invisible; the moment you're scraping more than one instrumented
+server into the same Prometheus and need to tell their metrics apart —
+which is exactly what a `service.name` filter/template variable is for —
+every series looks identical without it.
+
+Fix: pass `withResourceConstantLabels`, a regex matching the resource
+attribute(s) you want flattened onto every point:
+
+```js
+import { metrics } from '@opentelemetry/api';
+import { MeterProvider } from '@opentelemetry/sdk-metrics';
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+
+const meterProvider = new MeterProvider({
+  resource: resourceFromAttributes({ 'service.name': 'my-mcp-server' }),
+  readers: [
+    new PrometheusExporter({
+      port: 9464,
+      withResourceConstantLabels: /^service\.name$/,
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+```
+
+With this set, `mcp_tool_calls_total{...}` (and every other `mcp.tool.*`
+series) carries a `service_name` label directly, so
+`mcp_tool_calls_total{service_name="my-mcp-server"}` and a Grafana
+`service.name` template variable both work without a `target_info` join.
+See `dashboards/grafana-mcp-health.json` and `dashboards/dev/` in the repo
+for a full worked example (dashboard JSON + a script that exercises this
+exact setup end to end).
+
 ## Failure Fingerprinting (v0.4.0+)
 
 Groups logically identical failures under one stable identifier, even
@@ -1401,7 +1444,8 @@ Attribution's budget totals, Tool schema drift detection's per-tool schema
 history, and the Two-axis observation contract's `toolOutcome` counts.
 **All four live inside the object `instrumentMcpServer()` constructs for
 one call — they do not survive past it, and nothing shares state between
-two separate calls.**
+two separate calls, unless you set `instanceKey` (v0.9.0+ — see the
+section immediately below).**
 
 This is invisible, and correct, for the deployment shape every one of
 these features was designed against: one `Server`/`McpServer` instance,
@@ -1411,23 +1455,160 @@ instance around across many sessions. It becomes a real problem under a
 different, also-common shape: **"stateless" Streamable HTTP, where a fresh
 `Server` is constructed — and re-instrumented — on every incoming POST.**
 Under that topology, every one of these four trackers is discarded and
-rebuilt from empty before it ever sees a second data point. Nothing
-accumulates, nothing crosses a threshold, and today nothing warns that
-this is happening — the affected feature is silently inert.
-
-**This is a confirmed, currently-unfixed gap, not a hypothetical.**
-Reproduced directly in `test/integration/thrash-stateless-http-lifecycle.test.js`
-(`describe.skip` — a living reproduction, not a working fix): it drives 5
-identical tool failures across 5 separate `instrumentMcpServer()` calls and
-confirms `mcp.tool.loop.detected` never fires, even past the default
-`threshold: 3`, purely because of this lifecycle mismatch. Full
-investigation, root cause across all four trackers, and the design under
-consideration to fix it: ADR 012
+rebuilt from empty before it ever sees a second data point, unless
+`instanceKey` is set — and, for Agent Thrash Detection specifically, a
+real session id is also available on every call. Without both, nothing
+accumulates, nothing crosses a threshold, and nothing warns that this is
+happening — the affected feature is silently inert.
+
+**Confirmed, not a hypothetical, and now has a partial fix.** Reproduced
+directly in `test/integration/thrash-stateless-http-lifecycle.test.js`:
+without `instanceKey`, it still drives 5 identical tool failures across 5
+separate `instrumentMcpServer()` calls and confirms `mcp.tool.loop.detected`
+never fires, even past the default `threshold: 3` — that remains the
+default, unchanged behavior when you don't opt in. With a shared
+`instanceKey` *and* a real session id on every call, the same file's other
+test confirms it now does. Full investigation, root cause across all four
+trackers, and the `instanceKey` design: ADR 012
 (`docs/adr/012-tracker-lifecycle-and-shared-state.md`). Tracked in
 `docs/known-gaps.md`.
 
-**If you instrument a fresh `Server`/`McpServer` per request, assume none
-of these four features work as documented until ADR 012's fix ships.**
+**If you instrument a fresh `Server`/`McpServer` per request: set
+`instanceKey`.** Read the section immediately below in full before relying
+on it — it has one required companion for thrash detection specifically
+(a real session id, not the generated fallback), and it does not help at
+all across multiple processes or containers (Lambda, Cloud Run, or any
+horizontally-scaled deployment). Both are easy to miss and produce the
+exact same silent-inertness symptom as this section describes.
+
+## instanceKey: sharing tracker state across instrumentMcpServer() calls (v0.9.0+)
+
+`instanceKey` (a string option on `instrumentMcpServer()`, or the
+`OTEL_MCP_INSTANCE_KEY` environment variable) lets repeated
+`instrumentMcpServer()` calls that pass the same key share the four
+trackers described above instead of each one resetting to empty. Full
+design: ADR 012 (`docs/adr/012-tracker-lifecycle-and-shared-state.md`).
+
+### When to set it
+
+Set it when `instrumentMcpServer()` runs more than once per process for
+what is logically **one** service — the case the previous section
+describes: a fresh `Server`/`McpServer` constructed and re-instrumented on
+every incoming request, on an otherwise long-lived process. "Stateless"
+Streamable HTTP — a fresh `McpServer` per POST, the process itself kept
+alive — is the common real example. Pick one stable string per logical
+service and pass the same one on every call:
+
+```js
+instrumentMcpServer(server, { instanceKey: 'my-mcp-server' });
+```
+
+(`serviceName` deliberately omitted here — it only has an effect when
+`setupNodeSdk: true`, see "Two modes" below; passing it without that logs
+a one-time `diag.warn` and is unrelated to `instanceKey`, which is
+orthogonal to how spans/metrics get exported.)
+
+Omit it (the default) for the normal case — one `Server`/`McpServer`
+instrumented once and kept alive for the process's life (stdio, or an
+HTTP server that keeps one instrumented instance around across many
+sessions). Behavior is byte-identical to every version before v0.9.0:
+trackers are constructed fresh on every call, and the internal registry is
+never looked up or written to.
+
+### ⚠️ instanceKey alone does not fix thrash detection — read this before relying on it
+
+> **`instanceKey` shares the tracker OBJECT. Agent Thrash Detection also
+> needs a real, transport-provided session id on every call — without
+> both, thrash detection stays silently inert even with `instanceKey`
+> set.** This is the exact same silent-inertness shape as the original
+> gap, now hiding behind what looks like a fix. It was found writing this
+> feature's own regression test, not anticipated in the original design.
+
+Why: `ThrashDetector` — the tracker `instanceKey` shares — looks up
+episodes by `(sessionId, toolName, fingerprint)`, not just fingerprint
+alone (see "Session id resolution" above). Without a real
+`extra.sessionId`, `instrumentMcpServer()` generates its own random
+per-connection fallback session id — and it does this **fresh, on every
+single call**, regardless of `instanceKey`. Sharing the tracker instance
+doesn't change that: five stateless-HTTP requests sharing one
+`instanceKey` still each get recorded under a different, unrelated
+fallback id, so the same shared `ThrashDetector` sees five separate
+one-off episodes instead of one five-long loop. Nothing ever accumulates
+past 1, and nothing warns you.
+
+**Both of these are required together, not either/or:**
+
+1. `instanceKey`, so the tracker itself is shared across calls, **and**
+2. a real `extra.sessionId` on every call, so the lookup key inside that
+   shared tracker is stable across calls too.
+
+Real Streamable HTTP transports give you (2) automatically — the SDK
+threads a real client session id through `extra.sessionId` on every
+request regardless of whether the `Server` object handling it was just
+constructed, so the common "stateless Streamable HTTP" case works with
+`instanceKey` alone, no extra effort. **You will NOT get (2) for free —
+and thrash detection will stay silently inert despite `instanceKey` being
+set — if:** you're using a custom `Transport` implementation that never
+exposes a `sessionId`, you've set `assumeSingleSession: true` (which
+exists specifically to opt into the generated fallback), or anything else
+lands on the fallback path described in "Session id resolution" above. If
+you're in any of those cases, you need your own mechanism for threading a
+stable, real session identity into each call — `instanceKey` cannot
+manufacture one for you, and there is no configuration of it that will.
+
+This composition requirement is specific to Agent Thrash Detection's
+per-session lookup key. Schema drift detection and the `ToolOutcome`
+counter have no session-id dependency at all — `instanceKey` alone is
+sufficient for both. Budget tracking's `perToolUsd` scope is also
+session-independent; its `perSessionUsd` scope inherits the identical
+requirement, for the identical reason.
+
+### Registry bounds, and what eviction means
+
+The internal registry `instanceKey` looks trackers up in is bounded, not
+unbounded (ADR 012's proposed defaults):
+
+- **Cap:** 1000 distinct `instanceKey` values per process. Normal usage —
+  one stable key per logical service, reused across arbitrarily many
+  calls — should never approach this.
+- **TTL:** 24 hours, renewed on every use. Every `instrumentMcpServer()`
+  call under a given key resets that key's 24-hour clock, so a busy
+  service's entry never expires from age alone as long as it keeps being
+  used.
+
+**Eviction mid-use silently resets that key's accumulated state.** Cap
+pressure (more than 1000 distinct keys in active use) or a key genuinely
+going quiet for the full 24-hour TTL both mean the *next* call under that
+key finds nothing and builds fresh trackers — exactly the original bug's
+own behavior, just now gated behind a much narrower condition than "the
+next request arrived." Nothing warns when this happens.
+
+### Does NOT help across process boundaries — Lambda, Cloud Run, or any recycled/horizontally-scaled deployment
+
+**Counters are instance-local and best-effort. The registry is an
+optimization for one process fielding many `instrumentMcpServer()` calls
+— it is not, and will not become, a distributed-counting mechanism.**
+`instanceKey`'s registry lives in one process's memory. On Lambda, Cloud
+Run, or any horizontally-scaled container fleet, concurrent requests are
+routed across concurrently-running instances, and instances themselves get
+recycled — passing the identical `instanceKey` string everywhere does
+**not** change this: each process loads its own copy of the registry and
+only ever sees the calls actually routed to it. A retry loop of N requests
+landing on N different instances still resets to empty on every one of
+them — the same silent inertness this whole feature exists to fix,
+reached through a different door. There is no `instanceKey` configuration
+that closes this gap; it is a structural limitation of an in-process
+registry, not a tuning problem. Full reasoning — including why this
+library deliberately does not add an external store (Redis, DynamoDB, or
+similar) to solve it, consistent with its dependency-free posture
+elsewhere — is in ADR 012's Update section.
+
+### Configuration
+
+`instanceKey?: string` on `instrumentMcpServer()`'s options. Also settable
+via the `OTEL_MCP_INSTANCE_KEY` environment variable (lower precedence
+than the option itself). An empty or whitespace-only value from either
+source is treated the same as omitting it entirely.
 
 ## Two modes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -9,7 +9,8 @@
     ".": {
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -25,6 +26,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
+    "build": "node -e \"console.log('opentel-mcp: no build step — plain JS shipped as-is')\"",
     "verify:tarball": "node scripts/verify-tarball.js",
     "bench": "vitest bench --run",
     "prepack": "node scripts/strip-workspaces.js",

package/src/config.js

@@ -76,6 +76,30 @@ import { resolveSchemaDriftConfig } from './schema-drift/config.js';
  *   `enabled: false` (or the default when this option is omitted) is a true no-op: tools/list is not
  *   wrapped at all, unlike thrashDetection/costTracking whose disabled state still wraps tools/call for
  *   other reasons and merely skips inner logic.
+ * @property {string} [instanceKey] - Host-supplied stable identifier for one logical service (ADR 012,
+ *   docs/adr/012-tracker-lifecycle-and-shared-state.md, Option C — Phase 2: this option and its wiring).
+ *   When provided, the four in-memory trackers this library keeps per instrumented server — budget
+ *   (src/cost/budget.js), Agent Thrash Detection (src/thrash/detector.js), the ToolOutcome counter
+ *   (src/observation/tool-outcome-counter.js), and schema drift (src/schema-drift/detector.js) — are looked
+ *   up from an internal, bounded, TTL-evicting registry (src/registry/instance-registry.js) keyed by this
+ *   string, instead of being constructed fresh on every instrumentMcpServer() call. Repeated calls that pass
+ *   the SAME instanceKey therefore share accumulated tracker state — fixing the gap ADR 012 documents under
+ *   a "fresh Server per request" deployment shape, where every tracker previously reset to empty before ever
+ *   accumulating anything.
+ *
+ *   Omit (the default, `undefined`) for behavior byte-identical to pre-v0.9.0: trackers are constructed
+ *   fresh on every call exactly as before, the registry is never looked up or written to, and no extra
+ *   allocation happens beyond the trackers themselves.
+ *
+ *   Also settable via the `OTEL_MCP_INSTANCE_KEY` environment variable (lower precedence than this option;
+ *   an empty or whitespace-only value from either source is treated as omitted, matching this codebase's
+ *   `serviceName` validation). Distinct instanceKey values never share state with each other or with calls
+ *   that omit the option — each is its own independent registry entry.
+ *
+ *   Passing an unstable value (e.g. a per-request id) silently defeats the whole point while looking
+ *   configured — see ADR 012's Option C "Against" for why this is a real footgun, not a hypothetical one.
+ *   Registry bounds (cap, TTL) and known limitations (single-process only — no cross-instance/serverless
+ *   sharing) are documented in ADR 012, not repeated here.
  */
 
 // Guards the "serviceName has no effect" diagnostic below so it fires once
@@ -89,6 +113,36 @@ export function __resetServiceNameWarnedForTests() {
   warnedServiceNameIgnored = false;
 }
 
+// ADR 012, Phase 2: the first env var this codebase reads for a bare
+// top-level InstrumentOptions field, not one nested inside a feature's own
+// sub-config (contrast OTEL_MCP_THRASH_*/OTEL_MCP_SCHEMA_DRIFT_*, both
+// scoped to their feature's own resolve*Config() module — thrash/config.js's
+// own docblock: "No precedent for env-var-driven config exists elsewhere in
+// this codebase [outside thrash/schema-drift]"). instanceKey has no feature
+// namespace of its own to nest under, so it takes the bare OTEL_MCP_ prefix
+// directly, the same base namespace those two already share.
+const ENV_INSTANCE_KEY = 'OTEL_MCP_INSTANCE_KEY';
+
+/**
+ * Resolves `instanceKey`: the explicit option wins if it's a non-empty
+ * (post-trim) string, else the env var if IT is, else `undefined` — no
+ * fallback default beyond that, per ADR 012 ("omit for behavior
+ * byte-identical to pre-v0.9.0"). An invalid value from either source
+ * (non-string, empty, or whitespace-only) is silently treated as absent,
+ * matching this file's own `hasServiceName` validation and this codebase's
+ * general "invalid input degrades to the next source, never throws" env-var
+ * discipline (thrash/config.js, schema-drift/config.js).
+ *
+ * @param {unknown} optionValue
+ * @param {string | undefined} envValue
+ * @returns {string | undefined}
+ */
+function resolveInstanceKey(optionValue, envValue) {
+  if (typeof optionValue === 'string' && optionValue.trim() !== '') return optionValue;
+  if (typeof envValue === 'string' && envValue.trim() !== '') return envValue;
+  return undefined;
+}
+
 /**
  * Validates and applies defaults to raw instrumentMcpServer() options.
  *
@@ -133,5 +187,6 @@ export function resolveOptions(options) {
     },
     thrashDetection: resolveThrashConfig(opts.thrashDetection),
     schemaDrift: resolveSchemaDriftConfig(opts.schemaDrift),
+    instanceKey: resolveInstanceKey(opts.instanceKey, process.env[ENV_INSTANCE_KEY]),
   };
 }

package/src/fingerprint/classify/auth.js

@@ -2,15 +2,50 @@
  * @module fingerprint/classify/auth
  *
  * Classifies authn/authz failures: 401/403 status codes, known
- * auth-related error names, and generic "unauthorized" / "forbidden" /
- * "authenticat(e|ion)" wording.
+ * auth-related error names, Node's own OS-level permission error codes,
+ * and message wording covering both HTTP-style ("unauthorized",
+ * "forbidden") and OS/CLI-style ("permission denied", "access denied")
+ * phrasing — the latter verified against real tool output, not guessed:
+ *
+ * - Node's `fs` module: a permission-denied filesystem operation throws
+ *   with `err.code === 'EACCES'` and `err.message === "EACCES: permission
+ *   denied, <syscall> '<path>'"` (confirmed directly against the
+ *   installed Node runtime — `fs.writeFileSync()`/`readFileSync()` against
+ *   a path without permission). `EPERM` ("operation not permitted") is
+ *   Node's other OS-level permission error code, used e.g. when an
+ *   operation needs elevated privileges.
+ * - git: an SSH-auth failure prints OpenSSH's own literal wording,
+ *   `Permission denied (publickey)`; an HTTPS push without access prints
+ *   `remote: Permission to <owner>/<repo>.git denied to <user>.`.
+ * - AWS: IAM's standard explicit-deny message is "User: ... is *not
+ *   authorized to perform*: <action> on resource: ..."; S3 and many other
+ *   services instead return an `AccessDenied` error code/name with
+ *   message "Access Denied".
+ * - GCP: the standard gRPC/REST status is literally `PERMISSION_DENIED`,
+ *   with messages like "Permission '...' denied on resource ..." or
+ *   "The caller does not have permission".
+ *
+ * "insufficient permission(s)" is included as its own phrase — common,
+ * distinct wording (SQL Server, Salesforce, Windows UAC-style messages)
+ * that doesn't contain "denied" at all.
+ *
+ * DELIBERATELY NOT matching bare "authorized" or "permission" alone:
+ * both are common in non-error application text ("user is authorized to
+ * proceed", "permission granted", "user denied the permission request" —
+ * that last one is application semantics about a permission *prompt*,
+ * not an auth failure, and must NOT match here). Every message pattern
+ * below requires the specific denial phrase as a unit ("not authorized",
+ * "permission(s) denied", "access denied", "insufficient permission(s)"),
+ * not just the presence of an auth-adjacent word.
  */
 
 /** @typedef {import('../types.d.ts').Classifier} Classifier */
 
 const KNOWN_STATUSES = new Set([401, 403]);
 const KNOWN_NAMES = new Set(['UnauthorizedError', 'ForbiddenError', 'AuthError']);
-const MESSAGE_RE = /\bunauthorized\b|\bforbidden\b|\bauthenticat/i;
+const KNOWN_CODES = new Set(['EACCES', 'EPERM']);
+const MESSAGE_RE =
+  /\bunauthorized\b|\bforbidden\b|\bauthenticat|\bnot authorized\b|\bpermissions? denied\b|\baccess denied\b|\binsufficient permissions?\b/i;
 
 /** @type {Classifier} */
 export default {
@@ -21,6 +56,9 @@ export default {
     const name = err?.name;
     if (typeof name === 'string' && KNOWN_NAMES.has(name)) return 'auth';
 
+    const code = err?.code;
+    if (typeof code === 'string' && KNOWN_CODES.has(code)) return 'auth';
+
     const message = err?.message ?? '';
     if (typeof message === 'string' && MESSAGE_RE.test(message)) return 'auth';
 

package/src/fingerprint/classify/validation-paths.js

@@ -3,26 +3,57 @@
  *
  * Extracts which schema field(s) a Zod validation failure named, per ADR
  * 009 (docs/adr/009-field-level-convergence.md). The MCP TypeScript SDK's
- * `getParseErrorMessage()` (server/zod-compat.js) falls back to a
- * ZodError's own `.message` getter, which — confirmed against the
- * installed `zod` package — is the full JSON-serialized issues array
- * (`JSON.stringify(this.issues, ..., 2)`), embedding each failing issue's
- * `path`. That JSON survives verbatim into the thrown McpError's message,
- * and — same mechanism `classifyFailureChannel()` relies on
+ * `getParseErrorMessage()` (server/zod-compat.js) renders a ZodError into
+ * a message string that survives verbatim into the thrown McpError's
+ * message, and — same mechanism `classifyFailureChannel()` relies on
  * (fingerprint/classify/channel.js) — verbatim again into McpServer's
- * `isError: true` disguise of it.
+ * `isError: true` disguise of it. This module parses that rendered text,
+ * not a live ZodError: by the time a failure reaches this instrumentation,
+ * the structured object is gone (see ADR 009's Q2) — only ever the
+ * rendered text remains.
  *
- * This is best-effort, string-parsing extraction, not access to a live
- * ZodError: by the time a failure reaches this instrumentation, the
- * structured object is gone (see ADR 009's Q2) — only ever the rendered
- * text remains. Pure, synchronous, no OTel, never throws: any input that
- * doesn't confidently look like a Zod issues array resolves to an empty
- * array rather than a wrong or partial guess.
+ * TWO rendering formats are parsed, because the SDK has changed this
+ * rendering once already (confirmed empirically going from
+ * @modelcontextprotocol/sdk@1.29.0 to 1.30.0 — see ADR 009's addendum):
+ *
+ *   1. JSON issues array — `JSON.stringify(error.issues, ..., 2)`, the
+ *      whole-array-with-`path`-fields shape `getParseErrorMessage()` used
+ *      through SDK 1.29.0 (and still what you get if a low-level `Server`
+ *      author throws a raw, unrendered `ZodError` directly — nothing
+ *      guarantees they've upgraded, or ever rendered it through the SDK's
+ *      helper at all).
+ *   2. Rendered "`<message> at <dotPath>`" lines, one per issue, joined by
+ *      `\n` — what `getParseErrorMessage()` produces as of SDK 1.30.0.
+ *      Root-level issues (empty `path`) render as just `<message>`, no
+ *      " at " suffix at all.
+ *
+ * JSON is tried first (it's self-validating — a successful, Zod-issue-
+ * shaped parse is strong evidence either way — see `parseZodIssuesArray`)
+ * and unconditionally preferred when it confidently matches. The rendered
+ * form is tried only as a fallback, and only within a message that already
+ * confirms it's SDK-validation-shaped text (see `extractRenderedPaths`) —
+ * unlike the JSON path, a bare "<x> at <y>" line is not self-validating,
+ * so this format leans on the same INPUT/OUTPUT_VALIDATION marker
+ * `classify/channel.js` already trusts (ADR 007) rather than pattern-
+ * matching arbitrary text.
+ *
+ * This is best-effort, string-parsing extraction. Pure, synchronous, no
+ * OTel, never throws: any input that doesn't confidently look like either
+ * known rendering resolves to an empty array rather than a wrong or
+ * partial guess.
  *
  * Standalone, like channel.js: not wired into computeFingerprint() (the
  * path text is already implicit in the hashed normalized message — see
  * ADR 009's "Where would extraction belong" — so hashing it again would
  * be redundant, not more correct) and not re-exported from src/index.js.
+ *
+ * FRAGILITY, stated plainly: this is now coupled to TWO independent SDK
+ * rendering formats instead of one. A third format in a future SDK
+ * version breaks this again, exactly the way 1.30.0 broke the
+ * JSON-only version — and the failure mode is silent: `[]`, not an
+ * exception, not a warning. `test/fingerprint/classify.validation-paths.test.js`'s
+ * SDK-version pin exists specifically so that a future SDK bump fails a
+ * test loudly instead of only degrading data quality unnoticed.
  */
 
 /**
@@ -133,6 +164,85 @@ function parseZodIssuesArray(jsonText) {
   return paths;
 }
 
+// Same literal markers classify/channel.js already trusts (ADR 007) as the
+// SDK's own convention for distinguishing input- vs output-validation
+// -32602 failures from every other condition sharing that code. Reused
+// here as the precondition for attempting rendered-format extraction at
+// all: extractRenderedPaths() only ever runs on text that already
+// contains one of these, never on arbitrary business-logic text (e.g. a
+// tool's own "please look at docs" message), since a bare "<x> at <y>"
+// line is not self-validating the way a Zod-issue-shaped JSON array is.
+const INPUT_VALIDATION_MARKER = 'Input validation error:';
+const OUTPUT_VALIDATION_MARKER = 'Output validation error:';
+
+// A dotPath segment as SDK 1.30.0's getDotPath() renders it: an
+// identifier-like key, or `[digits]` for an array index, chained with `.`
+// or `[...]`. Deliberately excludes whitespace and punctuation other than
+// `.`/`_`/`$`/brackets, so a suffix like "least 5" (the tail of a
+// root-level message that happens to contain the substring " at ", e.g.
+// "Number must be at least 5") fails this pattern and is correctly not
+// mistaken for a path -- see this function's docblock for the residual
+// risk that remains even with this restriction.
+const RENDERED_DOT_PATH_RE = /^[\w$]+(?:\.[\w$]+|\[\d+\])*$/;
+
+/**
+ * Normalizes a rendered dotPath's `[digit]` array-index segments to `.digit`,
+ * matching parseZodIssuesArray()'s `path.join('.')` output. Chosen over
+ * leaving brackets as-is so both extraction paths (JSON and rendered) agree
+ * on canonical form for the same logical field -- callers/operators
+ * comparing `mcp.failure.validation_paths` values across SDK versions (or
+ * across the low-level Server's JSON-rendered path and McpServer's
+ * SDK-rendered path in the same fleet) should never see "items[3]" from one
+ * and "items.3" from the other for what is, semantically, the same path.
+ *
+ * @param {string} dotPath
+ * @returns {string}
+ */
+function normalizeRenderedDotPath(dotPath) {
+  return dotPath.replace(/\[(\d+)\]/g, '.$1');
+}
+
+/**
+ * Parses SDK 1.30.0+'s rendered `"<message> at <dotPath>"` format: one
+ * issue per line, joined by `\n`, root-level issues (empty `path`)
+ * rendering as just `<message>` with no " at " suffix at all.
+ *
+ * Only attempted when `text` contains the SDK's own input/output
+ * validation marker (see INPUT_VALIDATION_MARKER above) -- this format,
+ * unlike the JSON array, is not self-validating on its own (any English
+ * sentence ending in "at <word>" would otherwise look plausible), so this
+ * gate is the load-bearing precondition that keeps this from firing on
+ * unrelated business-logic failure text.
+ *
+ * Per-line, best-effort: a line with no confidently-path-shaped " at "
+ * suffix (root-level issues; a message whose own text happens to contain
+ * " at " followed by more prose) is silently skipped, not treated as
+ * disqualifying the whole message -- unlike parseZodIssuesArray()'s
+ * all-or-nothing JSON handling, a real Zod validation failure routinely
+ * mixes root-level and field-level issues in the same result, so a
+ * per-line miss here is expected, not a sign of corruption.
+ *
+ * @param {string} text
+ * @returns {readonly string[]}
+ */
+function extractRenderedPaths(text) {
+  if (!text.includes(INPUT_VALIDATION_MARKER) && !text.includes(OUTPUT_VALIDATION_MARKER)) {
+    return [];
+  }
+
+  const paths = [];
+  for (const line of text.split('\n')) {
+    const atIndex = line.lastIndexOf(' at ');
+    if (atIndex === -1) continue;
+
+    const suffix = line.slice(atIndex + 4);
+    if (!RENDERED_DOT_PATH_RE.test(suffix)) continue;
+
+    paths.push(normalizeRenderedDotPath(suffix));
+  }
+  return paths;
+}
+
 /**
  * Extracts which schema field(s) a validation failure named, from
  * whichever shape the caller has in hand: a CallToolResult with
@@ -140,10 +250,14 @@ function parseZodIssuesArray(jsonText) {
  * McpServer's disguised protocol failures live, see this module's
  * docblock), or an error-like object with a string `.message`.
  *
+ * Tries the JSON issues array first (SDK <=1.29.0, and any low-level
+ * `Server` author who throws a raw, unrendered `ZodError`); falls back to
+ * the SDK 1.30.0+ rendered "<message> at <path>" format only when no
+ * confident JSON match was found. See this module's docblock for why both
+ * exist and the fragility of depending on either.
+ *
  * Never throws, never guesses: returns `[]` — not a partial or
- * best-guess result — whenever the message is missing, doesn't contain a
- * balanced JSON array, or that array doesn't confidently look like a Zod
- * issues array.
+ * best-guess result — whenever neither format confidently matches.
  *
  * @param {unknown} failure
  * @returns {readonly string[]} One dot-joined path per failing issue
@@ -157,9 +271,12 @@ export function extractValidationPaths(failure) {
     if (typeof text !== 'string') return [];
 
     const jsonSubstring = extractJsonArraySubstring(text);
-    if (jsonSubstring === null) return [];
+    if (jsonSubstring !== null) {
+      const jsonPaths = parseZodIssuesArray(jsonSubstring);
+      if (jsonPaths !== null) return jsonPaths;
+    }
 
-    return parseZodIssuesArray(jsonSubstring) ?? [];
+    return extractRenderedPaths(text);
   } catch {
     return [];
   }

package/src/index.d.ts

@@ -114,6 +114,34 @@ export interface InstrumentOptions {
    * (`src/schema-drift/types.d.ts`) for the full field list and defaults.
    */
   schemaDrift?: Partial<SchemaDriftConfig>;
+
+  /**
+   * Host-supplied stable identifier for one logical service (ADR 012,
+   * `docs/adr/012-tracker-lifecycle-and-shared-state.md`, Option C). When provided, the four in-memory
+   * trackers this library keeps per instrumented server — the budget tracker, Agent Thrash Detection, the
+   * `ToolOutcome` counter, and schema drift detection — are looked up from an internal, bounded,
+   * TTL-evicting registry keyed by this string instead of being constructed fresh on every
+   * {@link instrumentMcpServer} call. Repeated calls that pass the SAME `instanceKey` therefore share
+   * accumulated tracker state — fixing the gap ADR 012 documents under a "fresh Server per request"
+   * deployment shape, where every tracker previously reset to empty before ever accumulating anything.
+   *
+   * Omit (the default, `undefined`) for behavior byte-identical to pre-v0.9.0: trackers are constructed
+   * fresh on every call exactly as before, and the registry is never looked up or written to.
+   *
+   * Also settable via the `OTEL_MCP_INSTANCE_KEY` environment variable (lower precedence than this option;
+   * an empty or whitespace-only value from either source is treated as omitted). Distinct `instanceKey`
+   * values never share state with each other or with calls that omit the option.
+   *
+   * The registry itself (`src/registry/instance-registry.js`) stays fully internal — there is no public
+   * type for it, and none is needed: nothing in this package's public API accepts or returns a registry
+   * instance, so a consumer only ever interacts with this feature through this one string field.
+   *
+   * Passing an unstable value (e.g. a per-request id) silently defeats the whole point while looking
+   * configured — see ADR 012's Option C "Against" for why this is a real footgun, not a hypothetical one.
+   * Registry bounds (cap, TTL) and known limitations (single-process only — no cross-instance/serverless
+   * sharing) are documented in ADR 012, not repeated here.
+   */
+  instanceKey?: string;
 }
 
 /**

package/src/instrument.js

@@ -25,6 +25,7 @@ import { SchemaDriftDetector } from './schema-drift/detector.js';
 import { createSchemaDriftEmitter } from './schema-drift/emitter.js';
 import { ToolOutcomeCounter } from './observation/tool-outcome-counter.js';
 import { detectObservationIntegrity } from './observation/integrity.js';
+import { InstanceRegistry } from './registry/instance-registry.js';
 import {
   ATTR_MCP_METHOD_NAME,
   ATTR_GEN_AI_TOOL_NAME,
@@ -79,6 +80,82 @@ const SCHEMA_DRIFT_SCOPE = 'server';
 // (e.g. monorepos with dedup issues), not just within one module instance.
 const kInstrumented = Symbol.for('opentel-mcp/instrumented');
 
+// ADR 012, Phase 2 (docs/adr/012-tracker-lifecycle-and-shared-state.md,
+// Option C): one registry for the whole process, constructed once here at
+// module load. This is the only architecture under which repeated
+// instrumentMcpServer() calls that share an instanceKey can actually share
+// tracker state — a per-call local variable couldn't be looked up again by
+// a later, unrelated call, and there is no other persistent scope this
+// library could reach for that doesn't require the host to hold and pass a
+// reference itself (ADR 012's Option B, rejected). Confirmed with the ADR's
+// author before implementing: the original Decision text never states this
+// explicitly (only the REJECTED Option A is described as "module-level"),
+// so this is a deliberate implementation choice filling a gap the ADR left
+// open, not a restatement of something it already said.
+//
+// Constructing this costs one empty BoundedTtlMap — negligible, and
+// unconditional regardless of whether any call ever supplies instanceKey,
+// since the registry must already exist the first time one does. This is
+// NOT the same thing as the "no allocation when instanceKey is unset"
+// guarantee instrumentMcpServer() makes below — that guarantee is about
+// PER-CALL allocation of registry entries/trackers, which getOrCreateTracker()
+// (below) skips entirely when instanceKey is undefined; a one-time,
+// process-lifetime empty Map is unrelated to and unaffected by that.
+const instanceRegistry = new InstanceRegistry();
+
+// Test-only: lets tests get a clean registry regardless of what earlier
+// tests in the same file already populated it with (the singleton above is
+// shared for the lifetime of this module instance — see its own comment).
+// Not part of the public API.
+export function __resetInstanceRegistryForTests() {
+  instanceRegistry.clear();
+}
+
+// Test-only: exposes the singleton's current size so tests can assert
+// "instanceKey omitted -> the registry is never touched" directly, rather
+// than only inferring it from tracker identity. Not part of the public API.
+export function __getInstanceRegistrySizeForTests() {
+  return instanceRegistry.size;
+}
+
+/**
+ * Looks up (or constructs) one of the four ADR-012 trackers. When
+ * `instanceKey` is `undefined`, calls `factory()` directly and never
+ * touches `registry` at all — this is what keeps the default (instanceKey
+ * omitted) path byte-identical to pre-v0.9.0 behavior: no registry lookup,
+ * no registry write, no allocation beyond the tracker itself, exactly as
+ * before this phase existed.
+ *
+ * The key is namespaced per tracker type (`${instanceKey}:${trackerSuffix}`)
+ * rather than using the raw `instanceKey` directly for all four. ADR 012's
+ * Decision text never addresses this: it describes "instrument.js looks up
+ * or creates each of the four trackers in an internal, bounded registry
+ * keyed by that string" without saying whether that means one shared entry
+ * per key (bundling all four trackers into one cached value) or one entry
+ * per (key, tracker type) pair. Left as a genuine, unaddressed gap. Chosen
+ * here: per-tracker-type namespacing, on ONE shared InstanceRegistry
+ * instance — the four tracker types can never collide on the same registry
+ * entry (a `ThrashDetector` can never be handed back where a budget tracker
+ * was expected, or vice versa), at the cost of all four trackers, across
+ * every instanceKey a process uses, sharing one bounded cap/TTL rather than
+ * each tracker type getting its own independent bound. Flagged explicitly
+ * as a choice, not a rediscovery of something the ADR already decided —
+ * four separate InstanceRegistry instances (one per tracker type) would
+ * have achieved the same non-collision guarantee structurally, without
+ * relying on string-namespace hygiene, and remains a reasonable alternative
+ * if independent per-tracker-type bounds turn out to matter in practice.
+ *
+ * @template V
+ * @param {string | undefined} instanceKey
+ * @param {string} trackerSuffix - e.g. 'thrash', 'budget', 'tool-outcome', 'schema-drift'.
+ * @param {() => V} factory
+ * @returns {V}
+ */
+function getOrCreateTracker(instanceKey, trackerSuffix, factory) {
+  if (instanceKey === undefined) return factory();
+  return instanceRegistry.getOrCreate(`${instanceKey}:${trackerSuffix}`, factory);
+}
+
 const UNSUPPORTED_INPUT_ERROR =
   'opentel-mcp: instrumentMcpServer() expects either a low-level Server ' +
   'instance (from @modelcontextprotocol/sdk/server/index.js) or a ' +
@@ -191,13 +268,23 @@ export function instrumentMcpServer(input, options) {
   // One tracker per instrumented server, not per call — session/tool cost
   // must accumulate across the server's whole lifetime (see
   // src/cost/budget.js). A no-op tracker when costTracking.budget is unset.
-  const budgetTracker = createBudgetTracker(resolved.costTracking.budget);
+  //
+  // ADR 012, Phase 2: when resolved.instanceKey is set, this is looked up
+  // from (or, on first use, created in) the process-wide instanceRegistry
+  // instead of constructed fresh — see getOrCreateTracker()'s own docblock.
+  // When instanceKey is undefined (the default), this line behaves exactly
+  // as it did before this phase existed: factory() runs unconditionally,
+  // the registry is never touched.
+  const budgetTracker = getOrCreateTracker(resolved.instanceKey, 'budget', () =>
+    createBudgetTracker(resolved.costTracking.budget),
+  );
   // Same one-per-server lifetime as budgetTracker above — thrash episodes
   // accumulate across calls, not within one (see src/thrash/detector.js).
   // Constructed unconditionally, same as budgetTracker: resolved.thrashDetection.enabled
   // gates per-call work (applyThrashDetection/applyThrashSuccessClear
-  // below), not this one-time setup.
-  const thrashDetector = new ThrashDetector(resolved.thrashDetection);
+  // below), not this one-time setup. Same ADR-012/instanceKey wiring as
+  // budgetTracker above.
+  const thrashDetector = getOrCreateTracker(resolved.instanceKey, 'thrash', () => new ThrashDetector(resolved.thrashDetection));
   const thrashEmitter = resolved.enableMetrics ? createThrashEmitter(PACKAGE_VERSION) : null;
   // MCP sessions have a transport-provided id (extra.sessionId below) for
   // session-oriented transports, but stdio has none — there's exactly one
@@ -241,8 +328,9 @@ export function instrumentMcpServer(input, options) {
   // optional sub-feature. Deliberately NOT gated on fingerprinting,
   // thrashDetection, or enableMetrics — see ToolOutcomeCounter's own
   // docblock for why (Finding 3: those flags gate OTHER bookkeeping this
-  // counter must stay independent of).
-  const toolOutcomeCounter = new ToolOutcomeCounter();
+  // counter must stay independent of). Same ADR-012/instanceKey wiring as
+  // budgetTracker/thrashDetector above.
+  const toolOutcomeCounter = getOrCreateTracker(resolved.instanceKey, 'tool-outcome', () => new ToolOutcomeCounter());
   // Additive to instrumentMcpServer()'s existing return contract, same
   // pattern as getThrashSummary above: a getObservationState() method,
   // unconditional (not gated on setupNodeSdk), omitted entirely when
@@ -271,9 +359,17 @@ export function instrumentMcpServer(input, options) {
   // per-call use — is what actually delivers "no allocation when
   // disabled." schemaDriftEmitter is additionally gated on enableMetrics,
   // mirroring thrashEmitter exactly: detection/state-tracking is
-  // independent of metrics on/off, only emission is gated.
+  // independent of metrics on/off, only emission is gated. The
+  // instanceKey/registry lookup below only runs when schemaDrift.enabled —
+  // "no allocation when disabled" takes priority over the ADR-012 wiring,
+  // exactly as it already does over every other option here; there is
+  // nothing to share across calls for a feature that isn't running at all.
   const schemaDriftDetector = resolved.schemaDrift.enabled
-    ? new SchemaDriftDetector({ maxTrackedTools: resolved.schemaDrift.maxTrackedTools })
+    ? getOrCreateTracker(
+        resolved.instanceKey,
+        'schema-drift',
+        () => new SchemaDriftDetector({ maxTrackedTools: resolved.schemaDrift.maxTrackedTools }),
+      )
     : null;
   const schemaDriftEmitter =
     resolved.schemaDrift.enabled && resolved.enableMetrics ? createSchemaDriftEmitter(PACKAGE_VERSION) : null;

package/src/registry/instance-registry.js

@@ -0,0 +1,170 @@
+/**
+ * @module registry/instance-registry
+ *
+ * Phase 1 of the `instanceKey` design (ADR 012, Option C,
+ * docs/adr/012-tracker-lifecycle-and-shared-state.md — "Registry bounds:
+ * must be a BoundedTtlMap, not an unbounded global"). This module is the
+ * keyed lookup-or-create registry itself, in isolation: no wiring into
+ * `instrumentMcpServer()`, no `instanceKey` option, no config surface, no
+ * `diag.warn`. Those are later phases. What exists here is the generic
+ * mechanism a later phase will use to look up or construct the four
+ * ADR-012 trackers (`ThrashDetector`, the budget tracker,
+ * `ToolOutcomeCounter`, `SchemaDriftDetector`) by a host-supplied string
+ * key, instead of constructing them unconditionally as local variables —
+ * so repeated `instrumentMcpServer()` calls sharing a key can share their
+ * state.
+ *
+ * Deliberately generic over the cached value's shape (this module knows
+ * nothing about trackers) — same reasoning `src/thrash/store.js`'s own
+ * docblock already gives for keeping `BoundedTtlMap` itself free of any
+ * thrash-specific logic: this class exists purely to answer "have I
+ * already built something for this key, in this process?", which is a
+ * useful question independent of what "something" is.
+ *
+ * Built on `BoundedTtlMap` (`src/thrash/store.js`), reused as-is rather
+ * than duplicated — that module already is the bounded, lazily-expiring,
+ * no-timer store this needs, and ADR 012 explicitly rejected inventing a
+ * second one. Imported across the `thrash/` directory boundary the same
+ * way `src/thrash/emitter.js` already imports from `../fingerprint/attributes.js`
+ * and `src/schema-drift/emitter.js` imports from `../attributes.js` — this
+ * codebase already treats a specific, deliberately-generic module as
+ * reusable across feature directories, not as private to the directory it
+ * happens to live in.
+ *
+ * Defaults: `maxSize` 1000, `ttlMs` 86_400_000 (24h). ADR 012 proposes
+ * both explicitly, in the same range as `thrashDetection.maxTrackedKeys`/
+ * `schemaDrift.maxTrackedTools` (1000) for the cap, and a "day-scale
+ * default... a defensible starting point, explicitly a starting point
+ * pending real deployment feedback, not a value this design derives from
+ * first principles" for the TTL — carried over here verbatim, not
+ * re-decided. Both remain overridable via the constructor for whichever
+ * later phase adds a config surface.
+ */
+
+import { BoundedTtlMap } from '../thrash/store.js';
+
+/** @type {number} See module docblock — ADR 012's proposed default, same range as thrashDetection.maxTrackedKeys/schemaDrift.maxTrackedTools. */
+export const DEFAULT_MAX_INSTANCES = 1000;
+
+/** @type {number} 24 hours. See module docblock — ADR 012's proposed "day-scale... starting point" default. */
+export const DEFAULT_TTL_MS = 86_400_000;
+
+/**
+ * `V` must never be `undefined` — `getOrCreate()` uses `undefined` (the
+ * same convention `BoundedTtlMap.get()`/`Map.get()` already use) as its
+ * own "nothing here" signal, so a factory that legitimately produces
+ * `undefined` would be indistinguishable from a miss and get rebuilt on
+ * every call. Not enforced at runtime (matching this codebase's general
+ * preference for documented contracts over defensive runtime checks on
+ * internal-only modules); the four ADR-012 trackers a later phase will
+ * cache here are always plain objects/class instances, never `undefined`.
+ *
+ * @template V
+ */
+export class InstanceRegistry {
+  /** @type {BoundedTtlMap<string, V>} */
+  #store;
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.maxSize] - @default DEFAULT_MAX_INSTANCES
+   * @param {number} [options.ttlMs] - @default DEFAULT_TTL_MS
+   * @param {() => number} [options.clock] - Injectable for deterministic tests; forwarded to BoundedTtlMap, defaults to Date.now there.
+   */
+  constructor({ maxSize = DEFAULT_MAX_INSTANCES, ttlMs = DEFAULT_TTL_MS, clock } = {}) {
+    this.#store = clock !== undefined ? new BoundedTtlMap(maxSize, ttlMs, clock) : new BoundedTtlMap(maxSize, ttlMs);
+  }
+
+  /**
+   * Removes every entry. Not part of normal operation (nothing in this
+   * module's own logic ever calls it) — added for host/test code that
+   * needs to explicitly reset a registry instance (e.g. a module-level
+   * singleton reused across many tests in one file). Implemented via
+   * `entries()` + `delete()` rather than reaching into `BoundedTtlMap`
+   * directly, so this stays a pure consumer of that module's existing
+   * public surface, same as every other method here.
+   */
+  clear() {
+    for (const [key] of this.#store.entries()) {
+      this.#store.delete(key);
+    }
+  }
+
+  /** Current entry count. Forwards BoundedTtlMap's own caveat: may include not-yet-swept expired entries. */
+  get size() {
+    return this.#store.size;
+  }
+
+  /**
+   * Looks up `key`. If a live (non-expired) entry exists, its TTL is
+   * renewed — `.set()` is called again with the SAME value — and the
+   * existing value is returned, without calling `factory`. If absent or
+   * expired, `factory()` is called to construct a fresh value, which is
+   * then stored under `key` and returned.
+   *
+   * This re-`set()`-on-hit behavior is the point ADR 012 calls out by
+   * name as "the subtle correctness point": `BoundedTtlMap`'s own
+   * documented semantics are TTL-from-`set()`-time, `get()` alone
+   * refreshes LRU order but NOT expiry. Reused as a plain get-then-set,
+   * a busy, continuously-used key would still expire on a fixed schedule
+   * from its first `set()`, regardless of how often it's subsequently
+   * hit — exactly undermining the point of giving it a stable key. This
+   * method is the wiring ADR 012 specifies to fix that: the hit branch
+   * below calls `.set()` unconditionally, not only the miss branch,
+   * producing sliding-window "used it, so keep it" expiry at the call
+   * site without needing to modify `BoundedTtlMap` itself.
+   *
+   * Never throws due to this method's own lookup/renewal/insert
+   * bookkeeping — a failure in any of those steps (e.g. a broken
+   * `clock`) is treated as a cache miss and falls through to `factory()`,
+   * matching this codebase's fail-open discipline for every other
+   * tracker (see `src/cost/budget.js`'s `recordAndCheck()`, which applies
+   * the same standard to its own bookkeeping). `factory()` itself is
+   * deliberately NOT caught here: it is the caller's own construction
+   * logic, there is no safe substitute value this registry could invent
+   * in its place, and silently swallowing a broken factory would hide a
+   * real bug behind a misleadingly-plain `undefined` return instead of
+   * surfacing it. If `factory()` throws, that exception propagates to
+   * the caller unchanged.
+   *
+   * Eviction (LRU cap pressure, or the renewed TTL genuinely elapsing) is
+   * NOT distinguished from "never seen this key before" — both are a
+   * miss, and both silently construct fresh via `factory()`. This is
+   * ADR 012's own decision, not an oversight: "Whether the registry
+   * should also distinguish 'brand-new key' from 'key seen before but
+   * since evicted' (and warn differently for each) was considered and is
+   * deliberately left open... a considered enhancement for whoever
+   * implements this, not a requirement." An evicted-then-re-requested key
+   * losing its accumulated state is the original ADR-012 bug, in
+   * miniature — a real, accepted reduction in blast radius (it now
+   * requires actual TTL-scale idleness or cap pressure to trigger,
+   * instead of firing on every call), not a closure of the failure mode.
+   *
+   * @param {string} key
+   * @param {() => V} factory
+   * @returns {V}
+   */
+  getOrCreate(key, factory) {
+    try {
+      const existing = this.#store.get(key);
+      if (existing !== undefined) {
+        this.#store.set(key, existing); // renew TTL on hit — see method docblock
+        return existing;
+      }
+    } catch {
+      // Never throw due to this registry's own bookkeeping — treat as a
+      // miss and fall through to factory(). See method docblock.
+    }
+
+    const created = factory();
+
+    try {
+      this.#store.set(key, created);
+    } catch {
+      // Caching failed, but factory() already succeeded — still hand the
+      // caller a usable value rather than losing it to a store-layer bug.
+    }
+
+    return created;
+  }
+}

package/src/registry/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared type definitions for the `instanceKey` registry (ADR 012, Phase
+ * 1 — docs/adr/012-tracker-lifecycle-and-shared-state.md).
+ *
+ * Hand-written, not a compiled build artifact — this project ships plain
+ * JS with no TypeScript build step (see CONTRIBUTING.md). Exists purely
+ * so TypeScript consumers (and editors) get accurate types for
+ * `src/registry/instance-registry.js`, the same pattern
+ * `src/thrash/types.d.ts` and `src/fingerprint/types.d.ts` already use.
+ *
+ * Internal — this module is not re-exported from `src/index.js`/
+ * `src/index.d.ts`. Phase 1 only: no `instanceKey` option exists yet on
+ * `instrumentMcpServer()`, so there is no public-facing type here either.
+ */
+
+/**
+ * Constructor options for {@link InstanceRegistry}.
+ */
+export interface InstanceRegistryOptions {
+  /** Hard cap on distinct keys. Least-recently-used keys are evicted past this. @default 1000 */
+  maxSize?: number;
+  /** Time-to-live (ms) from the moment a key's entry is last (re-)set — see `getOrCreate()`'s renew-on-hit behavior. @default 86400000 (24h) */
+  ttlMs?: number;
+  /** Returns "now" in epoch ms. Injectable for deterministic tests; defaults to `Date.now`. */
+  clock?: () => number;
+}
+
+/**
+ * A bounded, TTL-evicting, lookup-or-create registry keyed by a
+ * host-supplied string (the future `instanceKey` option). Generic over
+ * the cached value's shape — see `src/registry/instance-registry.js`'s
+ * own docblock for why this module knows nothing about trackers.
+ *
+ * @template V - Must never be `undefined` — see the `.js` module's docblock.
+ */
+export declare class InstanceRegistry<V> {
+  constructor(options?: InstanceRegistryOptions);
+
+  /** Current entry count. May include not-yet-swept expired entries — same caveat as `BoundedTtlMap.size`. */
+  readonly size: number;
+
+  /**
+   * Looks up `key`; on a live hit, renews its TTL and returns the
+   * existing value without calling `factory`. On a miss (absent,
+   * expired, or evicted), calls `factory()`, stores the result under
+   * `key`, and returns it. Never throws due to this method's own
+   * lookup/renewal/insert bookkeeping; a throwing `factory` propagates
+   * unchanged. See the `.js` module's docblock for the full contract,
+   * including why evicted-vs-never-seen is deliberately undistinguished.
+   */
+  getOrCreate(key: string, factory: () => V): V;
+
+  /** Removes every entry. Not used by this module's own logic — for host/test code that needs an explicit reset. */
+  clear(): void;
+}

package/src/thrash/config.js

@@ -2,14 +2,20 @@
  * @module thrash/config
  * Options parsing and defaults for Agent Thrash Detection (v0.6.0).
  *
- * No precedent for env-var-driven config exists elsewhere in this
- * codebase (src/config.js's resolveOptions() only reads from its
- * `options` argument) — this module introduces the pattern for the first
- * time rather than following an established one. Precedence, highest to
- * lowest: explicit field on the `partial` argument, then the field's
- * `OTEL_MCP_THRASH_*` env var, then the hardcoded default. An invalid or
- * unparseable env value is treated exactly like an absent one — silent
- * fallback to the next source, never a throw.
+ * This module introduced env-var-driven config to this codebase first —
+ * at the time, src/config.js's resolveOptions() read only from its
+ * `options` argument, with no env var fallback anywhere. That's since
+ * changed: ADR 012 Phase 2 (docs/adr/012-tracker-lifecycle-and-shared-state.md)
+ * added `OTEL_MCP_INSTANCE_KEY`, resolved directly in src/config.js's
+ * resolveOptions() itself rather than a nested feature config module,
+ * since `instanceKey` is a bare top-level option with no feature-specific
+ * sub-config to belong to the way `thrashDetection`/`schemaDrift` do. The
+ * pattern this module established is otherwise unchanged and still the
+ * one every feature-scoped config follows: explicit field on the
+ * `partial` argument, then the field's `OTEL_MCP_THRASH_*` env var, then
+ * the hardcoded default. An invalid or unparseable env value is treated
+ * exactly like an absent one — silent fallback to the next source, never
+ * a throw.
  */
 
 /**