@plur-ai/mcp 0.10.1 → 0.12.0

package/README.md

@@ -52,6 +52,7 @@ Your agent gets these tools automatically:
 |------|-------------|
 | `plur_session_start` | Start a session — injects relevant engrams for your task |
 | `plur_learn` | Store a memory — correction, preference, convention, or decision |
+| `plur_learn_batch` | Store many memories in one call — same dedup + policy as `plur_learn`, with per-item failure isolation |
 | `plur_recall_hybrid` | **Best default** — BM25 + embeddings merged via RRF. Zero cost. |
 | `plur_recall` | Keyword search (BM25 only, instant) |
 | `plur_inject_hybrid` | Load relevant memories for the current task |

package/dist/index.js

@@ -5,7 +5,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSy
 import { join } from "path";
 import { fileURLToPath } from "url";
 import { homedir, platform } from "os";
-var VERSION = "0.10.1";
+var VERSION = "0.12.0";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -65,6 +65,12 @@ var PLUR_HOOKS = {
     matcher: "auto|manual",
     hooks: [{ type: "command", command: `${CLI} hook-inject --rehydrate`, timeout: 15 }]
   }],
+  // Auto-close the memory lifecycle at session end (Claude Code SessionEnd,
+  // shipped v1.0.85) — captures a closing episode and cleans up the session
+  // checkpoint even if the agent forgot to call plur_session_end (#217).
+  SessionEnd: [{
+    hooks: [{ type: "command", command: `${CLI} hook-session-end`, timeout: 5 }]
+  }],
   // --- Contextual injection ---
   PreToolUse: [
     { matcher: "EnterPlanMode", hooks: [{ type: "command", command: `${CLI} hook-inject --event plan_mode`, timeout: 10 }] },
@@ -98,7 +104,7 @@ Hooks inject engrams automatically on every first message \u2014 you do not need
 2. **Learn**: When corrected or discovering something new, call \`plur_learn\` immediately
 3. **Recall**: Before answering factual questions, call \`plur_recall_hybrid\` \u2014 check memory first
 4. **Feedback**: Rate injected engrams with \`plur_feedback\` (positive/negative) \u2014 trains relevance
-5. **End**: Call \`plur_session_end\` with summary + engram_suggestions
+5. **End**: Call \`plur_session_end\` with summary + engram_suggestions \u2014 a SessionEnd hook auto-closes the lifecycle if you forget, but calling it yourself captures higher-quality learnings
 
 Do not ask permission to use these tools \u2014 they are your memory system.
 
@@ -279,7 +285,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-XG6IEACO.js");
+  const { runStdio } = await import("./server-6CNGJXSW.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-XG6IEACO.js → server-6CNGJXSW.js}

@@ -17,7 +17,7 @@ import { Plur as Plur2, checkForUpdate } from "@plur-ai/core";
 import { existsSync, unlinkSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName } from "@plur-ai/core";
 
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
@@ -31,9 +31,10 @@ function recordTelemetry(event) {
 }
 
 // src/version.ts
-var VERSION = "0.10.1";
+var VERSION = "0.12.0";
 
 // src/tools.ts
+import { z } from "zod";
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
   return async (prompt) => {
     const response = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
@@ -55,6 +56,73 @@ function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
     return data.choices?.[0]?.message?.content ?? "";
   };
 }
+function jsonSchemaPropToZod(prop) {
+  if (!prop || typeof prop !== "object") return z.unknown();
+  const variants = prop.anyOf ?? prop.oneOf;
+  if (Array.isArray(variants) && variants.length > 0) {
+    const zodVariants = variants.map(jsonSchemaPropToZod);
+    if (zodVariants.length === 1) return zodVariants[0];
+    return z.union(zodVariants);
+  }
+  if (prop.type === "string") return prop.enum ? z.enum(prop.enum) : z.string();
+  if (prop.type === "number" || prop.type === "integer") return z.number();
+  if (prop.type === "boolean") return z.boolean();
+  if (prop.type === "array") {
+    const itemSchema = prop.items ? jsonSchemaPropToZod(prop.items) : z.unknown();
+    return z.preprocess((val) => {
+      if (typeof val !== "string") return val;
+      const trimmed = val.trim();
+      if (trimmed.startsWith("[")) {
+        try {
+          const parsed = JSON.parse(trimmed);
+          return Array.isArray(parsed) ? parsed : val;
+        } catch {
+          return val;
+        }
+      }
+      if (prop.items?.type === "string") {
+        return trimmed.length === 0 ? [] : trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      }
+      return val;
+    }, z.array(itemSchema));
+  }
+  if (prop.type === "object" && prop.properties) {
+    const shape = {};
+    for (const [k, p] of Object.entries(prop.properties)) {
+      const field = jsonSchemaPropToZod(p);
+      shape[k] = prop.required?.includes(k) ? field : field.optional();
+    }
+    return z.object(shape).passthrough();
+  }
+  return z.unknown();
+}
+function validateToolArgs(tool, rawArgs) {
+  const schema = tool.inputSchema;
+  if (!schema?.properties) return { ok: true, data: rawArgs };
+  const shape = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    const field = jsonSchemaPropToZod(prop);
+    shape[key] = schema.required?.includes(key) ? field : field.optional();
+  }
+  const parsed = z.object(shape).passthrough().safeParse(rawArgs);
+  if (!parsed.success) {
+    const receivedFields = Object.keys(rawArgs);
+    const details = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join(", ");
+    const hasArrayParam = Object.values(schema.properties ?? {}).some((p) => p?.type === "array");
+    const arrayBugHint = receivedFields.length === 0 && hasArrayParam ? ' Known client-side bug (plur-ai/plur#297): some MCP clients drop the entire arguments payload when an array-typed parameter is included. Retry passing array parameters as a JSON string (e.g. tags: "[\\"a\\",\\"b\\"]") or a comma-separated string (tags: "a, b") \u2014 the server coerces both back into arrays.' : "";
+    const receivedNote = receivedFields.length > 0 ? `Received fields: [${receivedFields.join(", ")}].` : "Received no fields (the arguments object was empty).";
+    return {
+      ok: false,
+      errorPayload: {
+        error: `Invalid arguments: ${details}. ${receivedNote} The call reached the server \u2014 this is a malformed-arguments error, not a transport failure. Fix the field(s) named above and retry; do not abandon the call.` + arrayBugHint,
+        success: false,
+        received_fields: receivedFields,
+        _isError: true
+      }
+    };
+  }
+  return { ok: true, data: parsed.data };
+}
 var PLUR_GUIDE_EMPTY = `## PLUR \u2014 Empty Store
 
 You have **0 engrams**. This session's learnings will be lost unless you store them.
@@ -111,7 +179,67 @@ mcpCanary.expect({
   description: "Learning from corrections",
   fix: "Call plur_learn when corrected. If using hooks, verify they are installed."
 });
-function getToolDefinitions() {
+var CURSOR_CORE_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "plur_session_start",
+  "plur_session_end",
+  "plur_learn",
+  "plur_recall_hybrid",
+  "plur_feedback",
+  "plur_forget",
+  "plur_status",
+  "plur_doctor",
+  "plur_packs_uninstall",
+  "plur_tensions_purge"
+]);
+function buildAdminDispatchTool(all) {
+  const byName = new Map(all.map((t) => [t.name, t]));
+  const adminActions = all.map((t) => t.name).filter((n) => !CURSOR_CORE_TOOL_NAMES.has(n)).sort();
+  return {
+    name: "plur_admin",
+    description: `Dispatch for less-common PLUR operations (packs, sync, tensions, stores, timeline, ingest, and more), collapsed into one tool so Cursor's ~40-tool-per-workspace limit is not exhausted by PLUR alone. Set "action" to the underlying tool name and "args" to that tool's normal arguments. Valid actions: ${adminActions.join(", ")}.`,
+    annotations: { title: "Admin dispatch", readOnlyHint: false },
+    inputSchema: {
+      type: "object",
+      properties: {
+        // No `enum` here — an invalid action must reach the handler's custom
+        // Unknown-action message with the full valid-actions list, not fail
+        // at top-level schema validation with a generic "Invalid arguments"
+        // error. If `enum: adminActions` were set, the top-level
+        // CallToolRequestSchema handler's Zod validation would reject
+        // unknown actions before this handler's `if (!target)` branch ever
+        // ran.
+        action: { type: "string", description: "Which underlying plur_* tool to invoke" },
+        args: { type: "object", description: "Arguments for the chosen action, matching that tool's normal input schema", additionalProperties: true }
+      },
+      required: ["action"]
+    },
+    handler: async (args, plur) => {
+      const action = args.action;
+      const target = byName.get(action);
+      if (!target) {
+        return { error: `Unknown action "${action}". Valid actions: ${adminActions.join(", ")}`, success: false, _isError: true };
+      }
+      const innerArgs = args.args ?? {};
+      const validated = validateToolArgs(target, innerArgs);
+      if (!validated.ok) {
+        return { ...validated.errorPayload, error: `${action}: ${validated.errorPayload.error}` };
+      }
+      try {
+        return await target.handler(validated.data, plur);
+      } catch (err) {
+        const message = err?.message ?? String(err);
+        throw new Error(`${action}: ${message}`);
+      }
+    }
+  };
+}
+function getToolDefinitions(profile = "full") {
+  const all = getAllToolDefinitions();
+  if (profile !== "cursor") return all;
+  const core = all.filter((t) => CURSOR_CORE_TOOL_NAMES.has(t.name));
+  return [...core, buildAdminDispatchTool(all)];
+}
+function getAllToolDefinitions() {
   return [
     {
       name: "plur_learn",
@@ -133,7 +261,10 @@ function getToolDefinitions() {
           source: { type: "string", description: "Origin of this knowledge (URL, conversation ref, etc.)" },
           pinned: { type: "boolean", description: "Always-load flag. If true, this engram bypasses the keyword-relevance gate at injection time. Use sparingly: meta-rules, safety conventions, core operating principles only." },
           commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked"], description: "How firmly the user has committed to this belief (default: leaning)" },
-          locked_reason: { type: "string", description: "Why this engram is locked (only meaningful when commitment=locked)" }
+          locked_reason: { type: "string", description: "Why this engram is locked (only meaningful when commitment=locked)" },
+          valid_from: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge becomes valid \u2014 inject/recall skip the engram before this date (#347)" },
+          valid_until: { type: "string", description: 'ISO date (YYYY-MM-DD) the knowledge expires \u2014 inject/recall skip the engram after this date. Set this for any time-bound fact (offers, deadlines, temporary endpoints). When omitted, an explicit expiry phrase in the statement ("valid until 31 May 2026") is auto-parsed and echoed back (#347)' },
+          supersedes: { type: "array", items: { type: "string" }, description: "Engram IDs this statement intentionally replaces (#240). Writes relations.supersedes on the new engram and the reverse superseded_by edge on each local target. Supersedes-linked pairs are skipped by tension scans \u2014 an intentional update is not a contradiction. Use when updating a standing fact (new version, changed rule) rather than contradicting it." }
         },
         required: ["statement"]
       },
@@ -149,6 +280,9 @@ function getToolDefinitions() {
           commitment: args.commitment,
           locked_reason: args.locked_reason,
           pinned: args.pinned,
+          valid_from: args.valid_from,
+          valid_until: args.valid_until,
+          supersedes: args.supersedes,
           llm
         };
         const explicitScope = typeof args.scope === "string" && args.scope.length > 0;
@@ -164,6 +298,14 @@ function getToolDefinitions() {
           const scopes = remote.map((s) => `"${s.scope}"`).join(", ");
           return { scope_hint: `Stored at "${engramScope}" because no scope was passed, but a team store is configured (${scopes}). If this is team/engineering knowledge, re-learn it with an explicit scope so it reaches the shared store; keep genuinely personal notes at the default scope.` };
         };
+        const temporalEcho = (engram) => {
+          const extracted = engram.structured_data?._expiry_extracted;
+          return {
+            ...engram.temporal?.valid_from ? { valid_from: engram.temporal.valid_from } : {},
+            ...engram.temporal?.valid_until ? { valid_until: engram.temporal.valid_until } : {},
+            ...extracted ? { expiry_note: `Parsed expiry phrase "${extracted.phrase}" from the statement \u2192 temporal.valid_until=${extracted.valid_until}. The engram stops injecting/recalling after that date. If this is wrong, re-learn with an explicit valid_until.` } : {}
+          };
+        };
         const statement = sanitizeStatement(args.statement);
         try {
           const engram = await plur.learnRouted(statement, context);
@@ -179,6 +321,7 @@ function getToolDefinitions() {
             type: engram.type,
             pinned: engram.pinned === true,
             decision: "ADD",
+            ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routed),
             ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {},
             ...demoted ? { demoted: true, requested_scope: demoted.from, warning: `Sensitive content (${demoted.patterns}) detected \u2014 stored at "${demoted.to}"/private instead of the requested shared scope "${demoted.from}". If this is a false positive, re-scope deliberately.` } : {},
@@ -196,6 +339,7 @@ function getToolDefinitions() {
             scope: engram.scope,
             type: engram.type,
             decision: "ADD",
+            ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routedFallback),
             ...isOutbox ? { outbox: true } : {},
             warning: `Remote write failed (${err.message}); engram queued for retry.`
@@ -203,6 +347,82 @@ function getToolDefinitions() {
         }
       }
     },
+    {
+      name: "plur_learn_batch",
+      description: "Create many engrams in one call \u2014 the batch form of plur_learn. Accepts an array of engram objects and writes them sequentially through the SAME dedup + policy pipeline as plur_learn (content-hash NOOP \u2192 semantic recall \u2192 LLM ADD/UPDATE/MERGE decision). Dedup also applies WITHIN the batch: a statement duplicating an earlier item in the same array resolves to NOOP against it. Returns the created/affected engram ids in input order, the per-item decisions, aggregate stats, and any per-item failures \u2014 a single bad item does not abort the batch. Use this when an orchestration fans out and wants to persist consolidated findings without N separate calls. LLM dedup calls are capped (default 50, override with max_llm_calls) to bound bulk-import cost. Note: unlike plur_learn, batch items take the LOCAL learn path \u2014 remote-scope auto-routing (learnRouted) is not applied per item, so for shared/remote-store writes prefer plur_learn or pass an explicit local scope. See plur-ai/plur#281.",
+      annotations: { title: "Learn (batch)", destructiveHint: false, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          engrams: {
+            type: "array",
+            description: "Engram objects to persist. Each requires `statement`; the other fields mirror plur_learn.",
+            items: {
+              type: "object",
+              properties: {
+                statement: { type: "string", description: "The knowledge assertion to store" },
+                type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"], description: "Category of the engram" },
+                scope: { type: "string", description: "Namespace, e.g. global, project:myapp" },
+                domain: { type: "string", description: "Domain tag, e.g. software.deployment" },
+                tags: { type: "array", items: { type: "string" }, description: "Searchable keyword tags \u2014 contribute to BM25/embedding recall" },
+                rationale: { type: "string", description: "Why this knowledge matters \u2014 also enters the search corpus" },
+                source: { type: "string", description: "Origin of this knowledge (URL, conversation ref, etc.)" },
+                pinned: { type: "boolean", description: "Always-load flag. Use sparingly: meta-rules, safety conventions, core principles." },
+                commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked"], description: "How firmly the user has committed (default: leaning)" },
+                valid_from: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge becomes valid" },
+                valid_until: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge expires" }
+              },
+              required: ["statement"]
+            }
+          },
+          max_llm_calls: { type: "number", description: "Max LLM dedup calls across the whole batch (default 50). Once spent, remaining items use the cheap hash/cosine path. Pass a large number to opt out." }
+        },
+        required: ["engrams"]
+      },
+      handler: async (args, plur) => {
+        const llm = getLlmFunction();
+        const raw = Array.isArray(args.engrams) ? args.engrams : [];
+        if (raw.length === 0) {
+          return { ids: [], results: [], stats: { added: 0, updated: 0, merged: 0, noops: 0, failed: 0 }, failures: [], warning: "No engrams provided \u2014 pass a non-empty `engrams` array." };
+        }
+        const items = raw.map((e) => ({
+          statement: sanitizeStatement(e.statement),
+          context: {
+            type: e.type,
+            scope: e.scope,
+            domain: e.domain,
+            source: e.source,
+            tags: e.tags,
+            rationale: e.rationale,
+            commitment: e.commitment,
+            pinned: e.pinned,
+            valid_from: e.valid_from,
+            valid_until: e.valid_until
+          }
+        }));
+        const maxLlmCalls = typeof args.max_llm_calls === "number" ? args.max_llm_calls : void 0;
+        const { results, stats, failures } = await plur.learnBatch(
+          items,
+          llm,
+          maxLlmCalls !== void 0 ? { maxLlmCalls } : void 0
+        );
+        mcpCanary.signal("learn_activity");
+        recordTelemetry("learn");
+        return {
+          ids: results.map((r) => r.engram.id),
+          results: results.map((r) => ({
+            id: r.engram.id,
+            statement: r.engram.statement,
+            scope: r.engram.scope,
+            type: r.engram.type,
+            decision: r.decision,
+            ...r.existing_id ? { existing_id: r.existing_id } : {}
+          })),
+          stats,
+          ...failures.length > 0 ? { failures, warning: `${failures.length} of ${raw.length} engram(s) failed to persist; the rest were written.` } : {}
+        };
+      }
+    },
     {
       name: "plur_recall",
       description: "Query engrams by BM25 keyword matching \u2014 use plur_recall_hybrid for semantic similarity. Note: a project-scope filter also returns personal-family engrams (local, global, user:*, agent:*); an explicit scope=global recall returns ALL personal-family engrams \u2014 wider than scope=global INJECT, which is targeted to the global namespace only.",
@@ -226,14 +446,18 @@ function getToolDefinitions() {
           limit: args.limit
         });
         return {
-          results: results.map((e) => ({
-            id: e.id,
-            statement: e.statement,
-            type: e.type,
-            scope: e.scope,
-            domain: e.domain,
-            retrieval_strength: e.activation.retrieval_strength
-          })),
+          results: results.map((e) => {
+            const supersededBy = e.relations?.superseded_by;
+            const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
+            return {
+              id: e.id,
+              statement: e.statement + annotation,
+              type: e.type,
+              scope: e.scope,
+              domain: e.domain,
+              retrieval_strength: e.activation.retrieval_strength
+            };
+          }),
           count: results.length
         };
       }
@@ -289,9 +513,11 @@ function getToolDefinitions() {
         const response = {
           results: boundedResults.map((e) => {
             const raw = e;
+            const supersededBy = e.relations?.superseded_by;
+            const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
             const base = {
               id: e.id,
-              statement: e.statement,
+              statement: e.statement + annotation,
               type: e.type,
               scope: e.scope,
               domain: e.domain,
@@ -310,6 +536,14 @@ function getToolDefinitions() {
         if (meta.mode === "hybrid-degraded") {
           response.warning = `Embedding layer unavailable \u2014 results are BM25-only. Run plur_doctor for diagnosis. Last error: ${meta.embedderError ?? "unknown"}`;
         }
+        if (resolveRerankerName() !== "off") {
+          response.reranked = meta.reranked ?? 0;
+          const rr = plur.rerankerStatus();
+          if (boundedResults.length > 0 && (meta.reranked ?? 0) === 0 && rr.lastError) {
+            const corruptNote = rr.lastErrorKind === "corrupt-cache" ? " The model cache looks corrupt (truncated download) \u2014 purge and re-download, see plur_doctor." : "";
+            response.reranker_warning = `PLUR_RERANKER is set but the reranker did not engage \u2014 results are RRF-only (fusion order, no cross-encoder rerank).${corruptNote} Last error: ${rr.lastError}. Run plur_doctor for diagnosis.`;
+          }
+        }
         return response;
       }
     },
@@ -336,7 +570,9 @@ function getToolDefinitions() {
           consider: result.consider,
           count: result.count,
           tokens_used: result.tokens_used,
-          injected_ids: result.injected_ids
+          injected_ids: result.injected_ids,
+          // #181: unresolved-tension warnings — flag contradicted context
+          ...result.warnings ? { warnings: result.warnings } : {}
         };
       }
     },
@@ -364,7 +600,9 @@ function getToolDefinitions() {
           count: result.count,
           tokens_used: result.tokens_used,
           injected_ids: result.injected_ids,
-          mode: "hybrid"
+          mode: "hybrid",
+          // #181: unresolved-tension warnings — flag contradicted context
+          ...result.warnings ? { warnings: result.warnings } : {}
         };
       }
     },
@@ -709,6 +947,8 @@ function getToolDefinitions() {
       },
       handler: async (args, plur) => {
         const result = plur.sync(args.remote, { full: args.full === true });
+        await plur.waitForIndex();
+        const indexError = plur.lastIndexError();
         let outbox_result;
         try {
           outbox_result = await plur.flushOutbox();
@@ -716,6 +956,10 @@ function getToolDefinitions() {
         }
         return {
           ...result,
+          ...indexError ? {
+            index_error: indexError,
+            warning: `Index ${indexError.op} failed \u2014 ${indexError.message}. YAML is still the source of truth; run plur_sync with full=true to rebuild the index.`
+          } : {},
           ...outbox_result && (outbox_result.flushed > 0 || outbox_result.failed > 0) ? {
             outbox: {
               flushed: outbox_result.flushed,
@@ -907,6 +1151,15 @@ function getToolDefinitions() {
           tension_count: status.tension_count,
           versioned_engram_count: status.versioned_engram_count ?? 0,
           outbox_count: status.outbox_count ?? 0,
+          // Injection-provenance event/label counts (#452) — #202's volume gate.
+          history_events: status.history_events ?? {
+            co_injection: 0,
+            injection_outcome: 0,
+            outcome_positive: 0,
+            outcome_negative: 0
+          },
+          // Last background index/reembed failure (#272) — absent when healthy.
+          ...status.index_error ? { index_error: status.index_error } : {},
           // Version check (issue #151)
           ...versionCheck?.updateAvailable && versionCheck.latest ? {
             update_available: {
@@ -921,17 +1174,19 @@ function getToolDefinitions() {
     },
     {
       name: "plur_doctor",
-      description: 'Diagnose the PLUR install. Reports whether the embedding model loaded, whether hybrid search is fully operational, and \u2014 for any configured enterprise/remote store \u2014 whether its auth is valid (probes /api/v1/me and decodes token expiry), so a dead or soon-to-expire token surfaces instead of hiding behind a "healthy" report. Run this first when recall feels off or team engrams stop syncing.',
+      description: 'Diagnose the PLUR ENGINE (embedder, hybrid search, remote-store auth) \u2014 not hook/MCP wiring. Reports whether the embedding model loaded, whether hybrid search is fully operational, and \u2014 for any configured enterprise/remote store \u2014 whether its auth is valid (probes /api/v1/me and decodes token expiry), so a dead or soon-to-expire token surfaces instead of hiding behind a "healthy" report. Run this first when recall feels off or team engrams stop syncing. Does NOT check .cursor/mcp.json, .cursor/hooks.json, or the live MCP tool count \u2014 for that, run the `plur doctor` CLI command in a terminal (a different, more thorough check with the same name).',
       annotations: { title: "Doctor", readOnlyHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
-          retry: { type: "boolean", description: "If true, reset cached embedder failure state and retry the model load before reporting" }
+          retry: { type: "boolean", description: "If true, reset cached embedder failure state and retry the model load before reporting" },
+          rerank_eval: { type: "boolean", description: "If true and a reranker is configured (PLUR_RERANKER), run the per-store self-eval gate (#451): probes synthesized from this store's own engrams compare rerank-on vs RRF-only ordering. Verdict is cached in the store and advisory \u2014 it never auto-disables reranking. Costs one cross-encoder pass per probe (~20 probes)." }
         }
       },
       handler: async (args, plur) => {
         if (args.retry === true) {
           plur.resetEmbedder();
+          plur.resetReranker();
         }
         const status = plur.status();
         const before = plur.embedderStatus();
@@ -984,6 +1239,91 @@ function getToolDefinitions() {
             "  \u2022 Or opt out: set PLUR_DISABLE_EMBEDDINGS=1, or write `embeddings: { enabled: false }` to ~/.plur/config.yaml \u2014 hybrid search will run BM25-only"
           );
         }
+        const rerankerName = resolveRerankerName();
+        if (rerankerName !== "off") {
+          const adapter = getReranker(rerankerName);
+          let rerankerOk = false;
+          let rerankerDetail;
+          const probeStart = Date.now();
+          try {
+            const scores = await adapter.scoreBatch("plur doctor probe", ["probe document"]);
+            rerankerOk = scores.length === 1 && Number.isFinite(scores[0]);
+            const latencyNote = rerankerName === "bge-reranker-v2-m3" ? "seconds-scale per recall on CPU is expected \u2014 #220" : "ms-scale per recall on CPU is expected \u2014 #451";
+            rerankerDetail = rerankerOk ? `${rerankerName} loaded and scoring (probe ${Date.now() - probeStart}ms; ${latencyNote})` : `Probe returned malformed scores (${JSON.stringify(scores)}) \u2014 recall silently falls back to RRF-only`;
+          } catch (err) {
+            const message = err.message;
+            const kind = classifyRerankerFailure(message);
+            if (kind === "corrupt-cache") {
+              rerankerDetail = `Model cache looks corrupt (${message}) \u2014 recall silently falls back to RRF-only`;
+              remediation.push(
+                `Reranker model cache is corrupt \u2014 the classic symptom of a truncated download (#340). Delete ~/.cache/huggingface/hub/${hfCacheDirName(adapter.modelId)}/ and run plur_doctor with retry:true \u2014 the model will redownload via the classic (non-Xet) path.`
+              );
+            } else {
+              rerankerDetail = `Failed to load: ${message} \u2014 recall silently falls back to RRF-only`;
+              remediation.push(
+                `Reranker "${rerankerName}" is unavailable while PLUR_RERANKER requests it \u2014 recall degrades to RRF order without it. Check connectivity to huggingface.co (first-run download), or unset PLUR_RERANKER to opt out deliberately.`
+              );
+            }
+          }
+          checks.push({ check: "reranker available", ok: rerankerOk, detail: rerankerDetail });
+          if (rerankerOk) {
+            try {
+              const fitResult = await plur.checkRerankerFit({ rerankerName });
+              const sep = fitResult.separability.toFixed(3);
+              checks.push({
+                check: "reranker domain fit",
+                ok: fitResult.fit,
+                detail: fitResult.n_pairs === 0 ? "Not enough engrams to evaluate fit (< 2) \u2014 assuming fit" : fitResult.fit ? `Good fit \u2014 separability ${sep} on ${fitResult.n_pairs} pairs (threshold \u2265 0.05)` : `Poor fit \u2014 separability ${sep} on ${fitResult.n_pairs} pairs (threshold \u2265 0.05). Reranker may be net-negative on this store's domain mix.`
+              });
+              if (!fitResult.fit && fitResult.n_pairs > 0) {
+                remediation.push(
+                  `Reranker "${rerankerName}" shows poor separability (${sep}) on this store's engrams \u2014 it may be scoring irrelevant pairs higher than relevant ones. Consider unsetting PLUR_RERANKER or switching to a different tier. The fit check compares same-domain vs cross-domain pair scores; low separability means the model lacks signal on your content.`
+                );
+              }
+            } catch {
+            }
+          }
+          try {
+            let evalStatus;
+            let freshlyRun = false;
+            if (args.rerank_eval === true) {
+              const run = await plur.rerankerSelfEval();
+              evalStatus = { result: run.result, stale: false };
+              freshlyRun = !run.cached;
+            } else {
+              evalStatus = plur.rerankerEvalStatus(rerankerName);
+            }
+            if (!evalStatus) {
+              checks.push({
+                check: "reranker per-store eval",
+                ok: true,
+                detail: "Not yet evaluated on this store \u2014 cross-encoders can be net-negative out-of-domain (#451). Run plur_doctor with rerank_eval:true for the advisory self-check before trusting reranked order."
+              });
+            } else {
+              const r = evalStatus.result;
+              const harmful = r.verdict === "harmful";
+              const sign = r.delta_mrr >= 0 ? "+" : "";
+              const provenance = freshlyRun ? "measured now" : `cached ${r.evaluated_at}`;
+              const staleNote = evalStatus.stale ? " [STALE \u2014 store changed since; re-run with rerank_eval:true]" : "";
+              checks.push({
+                check: "reranker per-store eval",
+                ok: !harmful,
+                detail: `${r.verdict} on this store (${provenance}${staleNote}): \u0394MRR ${sign}${r.delta_mrr.toFixed(3)} vs RRF-only over ${r.scored_probes} probes (hit@1 ${(r.rrf_hit1 * 100).toFixed(0)}%\u2192${(r.rerank_hit1 * 100).toFixed(0)}%, ${r.promotions} promoted / ${r.demotions} demoted, ~${r.mean_rerank_ms.toFixed(0)}ms/probe)`
+              });
+              if (harmful) {
+                remediation.push(
+                  `Per-store self-eval measured reranker "${rerankerName}" as net-negative on THIS store (\u0394MRR ${r.delta_mrr.toFixed(3)}; it demoted known-relevant engrams in ${r.demotions}/${r.scored_probes} probes). This gate is advisory \u2014 reranking remains enabled. Unset PLUR_RERANKER to opt out for this store, or re-run plur_doctor with rerank_eval:true after the store grows/changes.`
+                );
+              }
+            }
+          } catch (err) {
+            checks.push({
+              check: "reranker per-store eval",
+              ok: false,
+              detail: `self-eval failed: ${err.message}`
+            });
+          }
+        }
         const canaryStatuses = mcpCanary.status();
         for (const cs of canaryStatuses) {
           if (!cs.healthy) {
@@ -1039,7 +1379,7 @@ function getToolDefinitions() {
         required: ["task"]
       },
       handler: async (args, plur) => {
-        mcpCanary.tick();
+        mcpCanary.reset();
         mcpCanary.signal("session_start_hook");
         const crypto = await import("crypto");
         const session_id = crypto.randomUUID();
@@ -1074,7 +1414,9 @@ function getToolDefinitions() {
         let engrams = null;
         try {
           const result = await plur.injectHybrid(task, {
-            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
+            session_id
+            // stamped on the co_injection provenance event (#452)
           });
           if (result.count > 0) {
             const lines = [];
@@ -1085,7 +1427,8 @@ function getToolDefinitions() {
           }
         } catch {
           const result = plur.inject(task, {
-            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
+            session_id
           });
           if (result.count > 0) {
             const lines = [];
@@ -1394,11 +1737,27 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         if (discoveries.length === 0) {
           return { discovered: [], note: "No remote stores configured. Register one scope first with plur_stores_add, then discover the rest." };
         }
+        const enrich = (d) => {
+          if (!d.ok) return d;
+          const byScope = new Map(d.metadata.map((m) => [m.scope, m]));
+          const registeredSet = new Set(d.registered);
+          const scopes = d.authorized.map((scope) => {
+            const m = byScope.get(scope);
+            return {
+              scope,
+              registered: registeredSet.has(scope),
+              ...m?.description ? { description: m.description } : {},
+              ...m && m.covers.length ? { covers: m.covers } : {}
+            };
+          });
+          return { ...d, scopes };
+        };
+        const discovered = discoveries.map(enrich);
         if (!register) {
-          return { discovered: discoveries };
+          return { discovered };
         }
         const registered = await plur.registerDiscoveredScopes({ url });
-        return { discovered: discoveries, registered };
+        return { discovered, registered };
       }
     },
     {
@@ -1443,22 +1802,48 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_tensions",
-      description: "List or scan for engram pairs that have conflicting knowledge. Without scan mode, shows previously detected conflicts. With scan:true, runs an active LLM-powered contradiction scan and returns only high-confidence tensions.",
-      annotations: { title: "Tensions", readOnlyHint: true, idempotentHint: true },
+      description: 'Tension lifecycle (#181). Default: list persisted tension records (unresolved first). scan:true runs an LLM contradiction scan, persists NEW detections as records, and skips already-recorded pairs. Lifecycle actions: action:"confirm" (real conflict), action:"dismiss" (false positive \u2014 pair suppressed from future scans), action:"resolve" + winner:<engram_id> (loser engram retired). Scan requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args.',
+      annotations: { title: "Tensions", readOnlyHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
           scope: { type: "string", description: "Filter by scope" },
           domain: { type: "string", description: "Filter by domain prefix" },
-          scan: { type: "boolean", description: "Run an active contradiction scan using an LLM judge. Requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args." },
+          scan: { type: "boolean", description: "Run an active contradiction scan using an LLM judge. New detections are persisted as tension records; recorded pairs (any status) are skipped. Requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args." },
+          persist: { type: "boolean", description: "Persist scan detections as tension records (default true). Set false for a dry-run scan that also ignores the recorded-pair suppress list." },
+          action: { type: "string", enum: ["confirm", "dismiss", "resolve"], description: "Lifecycle action on a persisted tension record (requires id). confirm: mark real. dismiss: false positive, suppress the pair. resolve: pick winner (requires winner), the losing engram is retired." },
+          id: { type: "string", description: "Tension record id (T-YYYY-MMDD-NNN) for action mode" },
+          winner: { type: "string", description: 'Engram id that wins the tension (action:"resolve" only). The other engram is retired.' },
+          status: { type: "string", enum: ["detected", "confirmed", "dismissed", "resolved", "all"], description: "List-mode status filter. Default: unresolved records (detected + confirmed)." },
           llm_base_url: { type: "string", description: "OpenAI-compatible API base URL for scan mode (e.g. https://api.openai.com/v1)" },
           llm_api_key: { type: "string", description: "API key for the LLM (scan mode)" },
           llm_model: { type: "string", description: "Model name for scan mode (default: gpt-4o-mini)" },
           min_confidence: { type: "number", description: "Minimum confidence threshold for scan mode (0\u20131, default: 0.7)" },
-          max_pairs: { type: "number", description: "Maximum candidate pairs to evaluate in scan mode (default: 50)" }
+          max_pairs: { type: "number", description: "Maximum candidate pairs to evaluate in scan mode (default: 50)" },
+          batch_size: { type: "number", description: "Pairs judged per LLM call in scan mode (default: 5). Set to 1 for sequential single-pair judging." },
+          temporal_discount: { type: "boolean", description: "Multiply judge confidence by a days-apart ladder (same day x1.0 ... 15+ days x0.3) in scan mode (#240). Overrides the config default (tensions.temporal_discount, off by default). The judge prompt already carries recorded dates; enable this only when date-aware judging alone leaves too many temporal-evolution false positives." }
         }
       },
       handler: async (args, plur) => {
+        if (args.action) {
+          const id = args.id;
+          if (!id) throw new Error(`action:"${args.action}" requires id (tension record id, e.g. T-2026-0703-001)`);
+          if (args.action === "confirm") {
+            const record = plur.confirmTension(id);
+            return { record, message: `Tension ${id} confirmed as a real conflict. Resolve it with action:"resolve" + winner:<engram_id>.` };
+          }
+          if (args.action === "dismiss") {
+            const record = plur.dismissTension(id);
+            return { record, message: `Tension ${id} dismissed \u2014 the pair is suppressed from future scans.` };
+          }
+          if (args.action === "resolve") {
+            const winner = args.winner;
+            if (!winner) throw new Error('action:"resolve" requires winner (the engram id to keep)');
+            const { record, retired_id } = plur.resolveTension(id, winner);
+            return { record, retired: retired_id, message: `Tension ${id} resolved: ${winner} wins, ${retired_id} retired.` };
+          }
+          throw new Error(`Unknown action: ${args.action}. Use confirm, dismiss, or resolve.`);
+        }
         const engrams = plur.list({
           scope: args.scope,
           domain: args.domain
@@ -1472,22 +1857,37 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
               count: 0
             };
           }
+          const tensionsConfig = plur.getTensionsConfig();
+          const persist = args.persist !== false;
           const result = await scanForTensions(engrams, llm, {
             min_confidence: args.min_confidence,
-            max_pairs: args.max_pairs
+            max_pairs: args.max_pairs,
+            batch_size: args.batch_size,
+            temporal_domains: tensionsConfig.temporal_domains,
+            snapshot_pairs: tensionsConfig.snapshot_pairs,
+            temporal_discount: args.temporal_discount ?? tensionsConfig.temporal_discount,
+            ...persist ? { exclude_pairs: new Set(plur.suppressedTensionPairKeys()) } : {}
           });
+          const persisted = persist && result.tensions.length > 0 ? plur.recordTensions(result.tensions) : void 0;
           return {
             pairs_checked: result.pairs_checked,
             count: result.new_tensions,
-            tensions: result.tensions.map((t) => ({
+            ...persisted ? { persisted_new: persisted.new_count } : {},
+            tensions: result.tensions.map((t, i) => ({
+              ...persisted ? { tension_id: persisted.records[i].id, category: persisted.records[i].category, status: persisted.records[i].status } : {},
               engram_a: { id: t.id_a, statement: t.statement_a },
               engram_b: { id: t.id_b, statement: t.statement_b },
               confidence: t.confidence,
-              reason: t.reason
-            }))
+              reason: t.reason,
+              ...t.days_apart !== void 0 ? { days_apart: t.days_apart } : {},
+              ...t.raw_confidence !== void 0 ? { raw_confidence: t.raw_confidence } : {}
+            })),
+            ...persisted && persisted.new_count > 0 ? { next_steps: 'Review each tension: action:"confirm" (real), action:"dismiss" (false positive), or action:"resolve" + winner:<engram_id> (retire the loser).' } : {}
           };
         }
-        const tensions = [];
+        const statusArg = args.status;
+        const records = statusArg === "all" ? plur.listTensions() : plur.listTensions({ status: statusArg ? [statusArg] : ["detected", "confirmed"] });
+        const legacy = [];
         const seen = /* @__PURE__ */ new Set();
         for (const engram of engrams) {
           if (!engram.relations?.conflicts?.length) continue;
@@ -1497,16 +1897,22 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             seen.add(pairKey);
             const other = engrams.find((e) => e.id === conflictId);
             if (!other) continue;
-            tensions.push({
+            legacy.push({
               engram_a: { id: engram.id, statement: engram.statement, type: engram.type },
               engram_b: { id: other.id, statement: other.statement, type: other.type },
-              detected_at: engram.activation.last_accessed,
-              purge_hint: "These conflicts are from the legacy detection system. Run plur_tensions_purge to clear them, then use scan:true for active contradiction detection."
+              detected_at: engram.activation.last_accessed
             });
           }
         }
-        const purge_hint = tensions.length > 0 ? "These are legacy conflict relations. Run plur_tensions_purge to clear them." : void 0;
-        return { tensions, count: tensions.length, ...purge_hint ? { purge_hint } : {} };
+        return {
+          tensions: records,
+          count: records.length,
+          ...legacy.length > 0 ? {
+            legacy_conflicts: legacy,
+            purge_hint: "legacy_conflicts are unvalidated relations.conflicts refs (importer heuristics or pre-#138 residue) \u2014 run scan:true to judge them, or plur_tensions_purge to clear them."
+          } : {},
+          ...records.length === 0 && legacy.length === 0 ? { hint: "No persisted tensions. Run scan:true to detect contradictions." } : {}
+        };
       }
     },
     {
@@ -1768,7 +2174,6 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
 }
 
 // src/server.ts
-import { z } from "zod";
 var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
 
 PLUR is a GLOBAL tool \u2014 one MCP server, one engram store (~/.plur/), available in every project. Multi-project scoping uses domain/scope fields on engrams, not separate installations.
@@ -1886,34 +2291,9 @@ Use \`scope\` to namespace engrams per project:
 
 Override with \`PLUR_PATH\` environment variable.
 `;
-function jsonSchemaPropToZod(prop) {
-  if (!prop || typeof prop !== "object") return z.unknown();
-  const variants = prop.anyOf ?? prop.oneOf;
-  if (Array.isArray(variants) && variants.length > 0) {
-    const zodVariants = variants.map(jsonSchemaPropToZod);
-    if (zodVariants.length === 1) return zodVariants[0];
-    return z.union(zodVariants);
-  }
-  if (prop.type === "string") return prop.enum ? z.enum(prop.enum) : z.string();
-  if (prop.type === "number" || prop.type === "integer") return z.number();
-  if (prop.type === "boolean") return z.boolean();
-  if (prop.type === "array") {
-    const itemSchema = prop.items ? jsonSchemaPropToZod(prop.items) : z.unknown();
-    return z.array(itemSchema);
-  }
-  if (prop.type === "object" && prop.properties) {
-    const shape = {};
-    for (const [k, p] of Object.entries(prop.properties)) {
-      const field = jsonSchemaPropToZod(p);
-      shape[k] = prop.required?.includes(k) ? field : field.optional();
-    }
-    return z.object(shape).passthrough();
-  }
-  return z.unknown();
-}
-async function createServer(plur) {
+async function createServer(plur, options) {
   const instance = plur ?? new Plur2();
-  const tools = getToolDefinitions();
+  const tools = getToolDefinitions(options?.profile ?? "full");
   checkForUpdate("@plur-ai/mcp", VERSION, (r) => {
     if (r.updateAvailable) {
       console.error(`[plur] Update available: ${r.current} \u2192 ${r.latest}. Run: npx @plur-ai/mcp@latest`);
@@ -1947,32 +2327,29 @@ async function createServer(plur) {
         isError: true
       };
     }
+    mcpCanary.tick();
     try {
-      const args = request.params.arguments ?? {};
-      const schema = tool.inputSchema;
-      if (schema?.properties) {
-        const shape = {};
-        for (const [key, prop] of Object.entries(schema.properties)) {
-          const field = jsonSchemaPropToZod(prop);
-          shape[key] = schema.required?.includes(key) ? field : field.optional();
-        }
-        const parsed = z.object(shape).passthrough().safeParse(args);
-        if (!parsed.success) {
-          const receivedFields = Object.keys(args);
-          const details = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join(", ");
-          const receivedNote = receivedFields.length > 0 ? `Received fields: [${receivedFields.join(", ")}].` : "Received no fields (the arguments object was empty).";
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              error: `Invalid arguments: ${details}. ${receivedNote} The call reached the server \u2014 this is a malformed-arguments error, not a transport failure. Fix the field(s) named above and retry; do not abandon the call.`,
-              success: false,
-              received_fields: receivedFields
-            }) }],
-            isError: true
-          };
-        }
+      let args = request.params.arguments ?? {};
+      const validated = validateToolArgs(tool, args);
+      if (!validated.ok) {
+        return {
+          content: [{ type: "text", text: JSON.stringify(validated.errorPayload) }],
+          isError: true
+        };
       }
+      args = validated.data;
       const result = await tool.handler(args, instance);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      let payload = result;
+      let resultIsError = false;
+      if (result && typeof result === "object" && result._isError === true) {
+        resultIsError = true;
+        const { _isError, ...rest } = result;
+        payload = rest;
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...resultIsError ? { isError: true } : {}
+      };
     } catch (err) {
       const message = err?.message ?? String(err);
       server.sendLoggingMessage({ level: "error", data: `Tool ${request.params.name} failed: ${message}` });
@@ -2001,11 +2378,16 @@ async function createServer(plur) {
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const uri = request.params.uri;
     if (uri === "plur://guide") {
+      const cursorNote = options?.profile === "cursor" ? `
+
+## Cursor tool profile
+
+Most tools above are NOT directly callable in this session \u2014 only ${[...CURSOR_CORE_TOOL_NAMES].join(", ")} are top-level tools here. Everything else in this guide is reachable through **plur_admin**: call it with \`{ action: "<tool name above>", args: {...} }\`.` : "";
       return {
         contents: [{
           uri: "plur://guide",
           mimeType: "text/markdown",
-          text: GUIDE_RESOURCE
+          text: GUIDE_RESOURCE + cursorNote
         }]
       };
     }
@@ -2093,7 +2475,8 @@ Please:
   return server;
 }
 async function runStdio() {
-  const server = await createServer();
+  const profile = process.env.PLUR_TOOL_PROFILE === "cursor" ? "cursor" : "full";
+  const server = await createServer(void 0, { profile });
   registerFlushOnExit({});
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plur-ai/mcp",
   "mcpName": "io.github.plur-ai/plur",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -14,7 +14,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.10.0"
+    "@plur-ai/core": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"