@plur-ai/mcp 0.21.0 → 0.21.2

package/dist/{chunk-UINIIUBY.js → chunk-22X2SQNV.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-WA3JKTZ7.js";
+} from "./chunk-OQDR6UF6.js";
 
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
@@ -17,7 +17,27 @@ function recordTelemetry(event) {
 import { existsSync, unlinkSync } from "fs";
 import { join, dirname, resolve } from "path";
 import { homedir } from "os";
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, NO_SESSION, findProjectConfigPath, readProjectConfigFromPath, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName, SUGGEST_DISPLAY_MIN_CONFIDENCE, mcpRemoteWarningLine, doctorRemoteRemediation, normalizeEndpointUrl, REMOTE_STATUS_TTL_MS, PROBE_CLEARABLE_STATES, bareEngramId, summariseProvenance, formatLayer3, renderProvenanceSummary, describeNeedsAction, summarizeOutbox } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, NO_SESSION, findProjectConfigPath, readProjectConfigFromPath, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName, SUGGEST_DISPLAY_MIN_CONFIDENCE, mcpRemoteWarningLine, doctorRemoteRemediation, normalizeEndpointUrl, REMOTE_STATUS_TTL_MS, PROBE_CLEARABLE_STATES, summariseProvenance, formatLayer3, renderProvenanceSummary, describeNeedsAction, summarizeOutbox, folderMapProblem, tokenEnvUnsetDetail, tokenEnvUnsetFix, resolveRecallDeadlineMs } from "@plur-ai/core";
+
+// src/folder-map-advice.ts
+import { folderRepairCommand } from "@plur-ai/core";
+function folderMapAdvice(problem, root) {
+  const command = problem.fixable ? folderRepairCommand(root) : null;
+  if (command) {
+    const summary = problem.repair_summary;
+    return {
+      command,
+      ...summary ? { summary } : {},
+      text: `PLUR can repair this${summary ? `; the repair changes ${summary}` : ""}. Show the user what is wrong and what the repair changes, and ask whether to repair the file (a backup is saved first; they can see the full change by running plur folders repair in a terminal). Only after the user agrees, run: ${command}`
+    };
+  }
+  if (problem.fixable) return { text: "The user can repair it by running plur folders repair in a terminal (it shows the change and asks first)." };
+  return {
+    text: problem.line !== void 0 ? `plur folders repair cannot fix this automatically: the user has to fix line ${problem.line} of that file by hand (plur folders repair then checks it).` : "plur folders repair cannot fix this automatically: the user has to fix or remove that file by hand."
+  };
+}
+
+// src/tools.ts
 import { z } from "zod";
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
   return async (prompt) => {
@@ -51,6 +71,22 @@ function formatAge(ageMs) {
   if (h < 24) return `${h}h ago`;
   return `${Math.floor(h / 24)}d ago`;
 }
+function attachRecallReport(response, meta) {
+  const remote = meta.remote ?? { state: "not_dialed", hosts: [] };
+  response.remote = remote;
+  response.results_complete = meta.results_complete ?? true;
+  const notes = [];
+  if (meta.local_complete === false) {
+    notes.push("Local search did not finish within the recall deadline \u2014 results are incomplete; retrying is fine.");
+  }
+  if (remote.hosts.some((h) => h.detail === "recall_deadline")) {
+    notes.push("The server did not answer within the recall deadline \u2014 results may be missing team engrams this call.");
+  }
+  if (notes.length > 0) {
+    const line = notes.join(" ");
+    response.warning = typeof response.warning === "string" && response.warning.length > 0 ? `${response.warning} ${line}` : line;
+  }
+}
 function attachRemoteStoreDegradation(response, plur) {
   let status;
   try {
@@ -69,21 +105,25 @@ function attachRemoteStoreDegradation(response, plur) {
   response.warning = typeof response.warning === "string" && response.warning.length > 0 ? `${response.warning} ${line}` : line;
 }
 var recallHandler = async (args, plur) => {
+  const deadline_at = Date.now() + resolveRecallDeadlineMs();
   const mode = args.mode ?? "hybrid";
   if (mode === "keyword") {
-    const results = await plur.recall(args.query, {
+    const kwMeta = await plur.recallWithMeta(args.query, {
       scope: args.scope,
       domain: args.domain,
       limit: args.limit,
       remote_timeout_ms: 2e3,
       // MCP recall remote budget (#776)
+      deadline_at,
       // #243: session default scope (incl. mid-session plur_session_scope
       // changes) establishes the remote dialing org context when no explicit
       // scope filter is passed. Same rule as writes (E7, formal R2): not
       // exactly one open session and no id → NO_SESSION, never the process
-      // slot the last-started session owns.
-      session: _resolveWriteSession(args)
+      // slot the last-started session owns. #1566: with no session default
+      // of its own, the workspace's scope — the one resolver writes use.
+      session: await _readSession(args, plur)
     });
+    const results = kwMeta.engrams;
     const response2 = {
       results: results.map((e) => {
         const supersededBy = e.relations?.superseded_by;
@@ -92,7 +132,11 @@ var recallHandler = async (args, plur) => {
         const measuredUnder = raw.measured_under;
         const measuredAnnotation = measuredUnder ? " [measured under: " + Object.entries(measuredUnder).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ") + "]" : "";
         return {
-          id: raw._originalId ?? bareEngramId(e.id),
+          // The id plur_learn returned for this engram (F3): a team row keeps
+          // its store prefix (`ENG-<PREFIX>-…`), so it never shares an id with
+          // a local engram minted the same day, and forget/feedback/pin route
+          // it to its store. A local engram's id has no prefix.
+          id: e.id,
           statement: e.statement + annotation + measuredAnnotation,
           type: e.type,
           scope: e.scope,
@@ -113,6 +157,7 @@ var recallHandler = async (args, plur) => {
       mode: "keyword"
     };
     attachRemoteStoreDegradation(response2, plur);
+    attachRecallReport(response2, kwMeta);
     return response2;
   }
   const budget = args.budget;
@@ -124,10 +169,12 @@ var recallHandler = async (args, plur) => {
     limit: fetchLimit,
     remote_timeout_ms: 2e3,
     // MCP recall remote budget (#776)
+    deadline_at,
     // #243: session default scope (incl. mid-session plur_session_scope
     // changes) establishes the remote dialing org context when no explicit
-    // scope filter is passed. Same rule as writes (E7, formal R2).
-    session: _resolveWriteSession(args)
+    // scope filter is passed. Same rule as writes (E7, formal R2), and the
+    // same workspace scope when the session has no default (#1566).
+    session: await _readSession(args, plur)
   });
   recordTelemetry("recall");
   const truncatedByCount = budget?.max_results != null && meta.engrams.length > cap;
@@ -156,7 +203,8 @@ var recallHandler = async (args, plur) => {
       const measuredUnder = raw.measured_under;
       const measuredAnnotation = measuredUnder ? " [measured under: " + Object.entries(measuredUnder).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ") + "]" : "";
       const base = {
-        id: raw._originalId ?? bareEngramId(e.id),
+        id: e.id,
+        // same id plur_learn returned — see the keyword branch (F3)
         statement: e.statement + annotation + measuredAnnotation,
         type: e.type,
         scope: e.scope,
@@ -178,8 +226,9 @@ var recallHandler = async (args, plur) => {
     mode: meta.mode
   };
   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"}`;
+    response.warning = meta.degraded_reason ? meta.embedderError ?? meta.degraded_reason : `Embedding layer unavailable \u2014 results are BM25-only. Run plur_doctor for diagnosis. Last error: ${meta.embedderError ?? "unknown"}`;
   }
+  if (meta.degraded_reason) response.degraded_reason = meta.degraded_reason;
   if (resolveRerankerName() !== "off") {
     response.reranked = meta.reranked ?? 0;
     const rr = plur.rerankerStatus();
@@ -189,6 +238,7 @@ var recallHandler = async (args, plur) => {
     }
   }
   attachRemoteStoreDegradation(response, plur);
+  attachRecallReport(response, meta);
   return response;
 };
 var RECALL_HYBRID_DEPRECATION = "plur_recall_hybrid is deprecated since 0.16 \u2014 use plur_recall (mode defaults to hybrid). This alias will be removed in 0.18.";
@@ -422,12 +472,51 @@ function trustCommand(dir, storageRoot, platform = process.platform) {
   const store = _shellWord(resolve(storageRoot), platform);
   return store === null ? null : `plur --path ${store} trust ${target}`;
 }
+function folderMapStatus(root) {
+  let p;
+  try {
+    p = folderMapProblem(root);
+  } catch {
+    return {};
+  }
+  if (!p) return {};
+  const advice = folderMapAdvice(p, root);
+  return {
+    folder_map: {
+      ok: false,
+      file: p.file,
+      problem: p.problem,
+      ...p.line !== void 0 ? { line: p.line } : {},
+      ...p.column !== void 0 ? { column: p.column } : {},
+      fixable: p.fixable,
+      ...advice.command ? { repair_command: advice.command } : {},
+      ...advice.summary ? { repair_summary: advice.summary } : {},
+      advice: `Memory tools are paused until it is fixed. ${advice.text}`
+    }
+  };
+}
+function folderOnCommand(entry, storageRoot, platform = process.platform) {
+  if (_UNSAFE_PATH_CHARS.test(entry)) return null;
+  const target = _shellWord(entry, platform);
+  if (target === null) return null;
+  if (!storageRoot || resolve(storageRoot) === resolve(join(homedir(), ".plur"))) return `plur folders set ${target} --on`;
+  const store = _shellWord(resolve(storageRoot), platform);
+  return store === null ? null : `plur --path ${store} folders set ${target} --on`;
+}
+function redactStoreErrors(errors) {
+  return Object.fromEntries(Object.entries(errors).map(([k, v]) => [k, String(v).split("\n", 1)[0].slice(0, 300)]));
+}
 var UNTRUSTED_SCOPE_GRAMMAR = /^(?:global|[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._@/:-]{0,199})$/;
 var UNTRUSTED_DOMAIN_GRAMMAR = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/;
 var _UNSAFE_PATH_CHARS = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/;
 function _escapedText(s) {
   return JSON.stringify(s.length > 1024 ? s.slice(0, 1024) + "\u2026" : s).replace(/[\u007f-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
+var FOLDER_SCOPE = /* @__PURE__ */ Symbol("plur.folderScope");
+function _folderContext(args) {
+  const c = args[FOLDER_SCOPE];
+  return c && typeof c === "object" && typeof c.resolve === "function" ? c : null;
+}
 function readTrustedProjectConfig(trust) {
   const configPath = findProjectConfigPath();
   const raw = readProjectConfigFromPath(configPath);
@@ -472,6 +561,44 @@ var NO_SESSION_SLOT_WARNING = "No session is open, so this is the process-defaul
 function _resolveWriteSession(args) {
   return _resolveInjectionSession(args) ?? NO_SESSION;
 }
+var FOLDER_SCOPE_SESSION_PREFIX = "\0plur:folder-scope:";
+function _knownSession(id, plur, viaServer) {
+  if (id.startsWith("\0")) return false;
+  if (_sessionTelemetry.has(id)) return true;
+  if (viaServer) return false;
+  try {
+    return plur.trackedSessionScopes().includes(id);
+  } catch {
+    return false;
+  }
+}
+async function _writeSession(args, plur, base, read = false) {
+  const explicit = typeof args.session_id === "string" && args.session_id.length > 0 ? args.session_id : void 0;
+  const chosen = base !== void 0 ? base : explicit ?? _implicitSessionId();
+  const ctx = _folderContext(args);
+  if (!ctx) return chosen ?? NO_SESSION;
+  const session = chosen !== void 0 && _knownSession(chosen, plur, true) ? chosen : NO_SESSION;
+  let ws = null;
+  try {
+    ws = read && ctx.admitted ? ctx.admitted() : await ctx.resolve();
+  } catch {
+    ws = null;
+  }
+  if (session !== NO_SESSION) {
+    const record = _sessionTelemetry.get(session);
+    const own = plur.getSessionScope({ session });
+    if (record?.scope_adjusted) return session;
+    if (record && own != null && ws !== null && record.workspace_key === ws.key && record.workspace_scope === ws.scope) return session;
+  }
+  const scope = ws?.scope ?? null;
+  if (scope === null) return NO_SESSION;
+  const key = FOLDER_SCOPE_SESSION_PREFIX + scope;
+  plur.setSessionScope(scope, { session: key });
+  return key;
+}
+function _readSession(args, plur) {
+  return _writeSession(args, plur, void 0, true);
+}
 function _resolveScopeSession(args) {
   const explicit = args.session_id;
   if (typeof explicit === "string" && explicit.length > 0) {
@@ -587,7 +714,9 @@ function buildAdminDispatchTool(all) {
         return { ...validated.errorPayload, error: inner.startsWith(`${action}:`) ? inner : `${action}: ${inner}` };
       }
       try {
-        return await target.handler(validated.data, plur);
+        const carried = args[FOLDER_SCOPE];
+        const data = carried !== void 0 ? { ...validated.data, [FOLDER_SCOPE]: carried } : validated.data;
+        return await target.handler(data, plur);
       } catch (err) {
         const message = err?.message ?? String(err);
         throw new Error(message.startsWith(`${action}:`) ? message : `${action}: ${message}`);
@@ -762,13 +891,15 @@ function getAllToolDefinitions() {
           // #243: resolve which session's default scope governs this write —
           // explicit session_id first, else the lone open session. Never
           // persisted on the engram (LearnContext.session selects a scope, it
-          // is not part of one).
-          session: _resolveWriteSession(args),
+          // is not part of one). The workspace's answer where the session
+          // gives none, or its roots changed (#1562, #1563 review round 2).
+          session: await _writeSession(args, plur),
           llm
         };
         const explicitScope = typeof args.scope === "string" && args.scope.length > 0;
-        const scopeHint = (engramScope, wasRouted) => {
+        const scopeHint = (engramScope, wasRouted, delivery) => {
           if (explicitScope || wasRouted || isSharedScope(engramScope)) return {};
+          if (delivery !== "local") return {};
           let remote = [];
           try {
             remote = plur.getWritableRemoteScopes();
@@ -776,6 +907,7 @@ function getAllToolDefinitions() {
             return {};
           }
           if (remote.length === 0) return {};
+          if (remote.some((s) => s.scope === engramScope)) return {};
           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.` };
         };
@@ -823,7 +955,7 @@ function getAllToolDefinitions() {
           const routeRefused = engram.structured_data?._routeRefused;
           mcpCanary.signal("learn_activity");
           recordTelemetry("learn");
-          const dedup = isOutbox ? void 0 : await plur.nearDuplicates(statement, context, engram.id);
+          const dedup = isOutbox ? void 0 : await plur.nearDuplicates(statement, context, plur.readIdFor(engram));
           const redraft = (() => {
             const ids = args.supersedes;
             if (!ids?.length) return void 0;
@@ -861,6 +993,8 @@ function getAllToolDefinitions() {
             // more specific `warning` below (outbox, demotion, refusal) still
             // wins that key; `delivery_warning` keeps this one either way.
             delivery: delivered.delivery,
+            // 0.21.1: why it was queued (rejected token vs unreachable server).
+            ...delivered.reason ? { delivery_reason: delivered.reason, delivery_reason_code: delivered.reason_code } : {},
             ...delivered.warning ? { delivery_warning: delivered.warning, warning: delivered.warning } : {},
             ...dedup?.near_duplicates?.length ? { dedup } : {},
             ...redraft ? { redraft } : {},
@@ -869,9 +1003,9 @@ function getAllToolDefinitions() {
               return c ? { composition: c } : {};
             })(),
             ...temporalEcho(engram),
-            ...scopeHint(engram.scope, !!routed),
+            ...scopeHint(engram.scope, !!routed, delivered.delivery),
             ...domainHint(!!routed),
-            ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {},
+            ...isOutbox ? { outbox: true, warning: delivered.reason ?? "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.` } : {},
             ...routed ? { routed: { scope: routed.scope, confidence: routed.confidence, reason: routed.reason }, info: `No scope was provided; auto-routed to "${routed.scope}" (confidence ${routed.confidence}) because its content matched that scope's covers. Pass an explicit scope to override.` } : {},
             // #1115: a shared scope matched but was NOT adopted. Said plainly,
@@ -902,9 +1036,10 @@ function getAllToolDefinitions() {
             type: engram.type,
             ...learnDecision(engram),
             delivery: delivered.delivery,
+            ...delivered.reason ? { delivery_reason: delivered.reason, delivery_reason_code: delivered.reason_code } : {},
             ...delivered.warning ? { delivery_warning: delivered.warning } : {},
             ...temporalEcho(engram),
-            ...scopeHint(engram.scope, !!routedFallback),
+            ...scopeHint(engram.scope, !!routedFallback, delivered.delivery),
             ...domainHint(!!routedFallback),
             ...isOutbox ? { outbox: true } : {},
             // The routed write can fail for reasons that have nothing to do
@@ -966,7 +1101,7 @@ function getAllToolDefinitions() {
         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 batchSession = _resolveWriteSession(args);
+        const batchSession = await _writeSession(args, plur);
         const projectDomain = readTrustedProjectConfig(plur).domain ?? void 0;
         const items = raw.map((e) => ({
           statement: sanitizeStatement(e.statement),
@@ -1066,9 +1201,14 @@ function getAllToolDefinitions() {
             const isOutbox = !!r.engram.structured_data?._outbox;
             const routed = r.engram.structured_data?._routed;
             const routeRefused = r.engram.structured_data?._routeRefused;
+            const requested = r.input_index !== void 0 ? raw[r.input_index]?.scope : void 0;
+            const delivered = plur.deliveryOf(r.engram, typeof requested === "string" ? requested : void 0);
             return {
               input_index: r.input_index,
               id: isOutbox ? r.engram.id : plur.readIdFor(r.engram),
+              delivery: delivered.delivery,
+              ...delivered.reason ? { delivery_reason: delivered.reason, delivery_reason_code: delivered.reason_code } : {},
+              ...delivered.warning ? { delivery_warning: delivered.warning } : {},
               statement: r.engram.statement,
               scope: r.engram.scope,
               type: r.engram.type,
@@ -1091,7 +1231,7 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_recall",
-      description: 'Search engrams by topic. Default mode is hybrid (BM25 + local embeddings via RRF) \u2014 set mode:"keyword" for BM25-only. Local search plus, when a configured enterprise store is part of the current project/work, one live timeout-bounded recall per remote host merged in (a `remote_stores` block + warning appears when a host is degraded; no host configured or implicated = fully local). 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.',
+      description: 'Search engrams by topic. Default mode is hybrid (BM25 + local embeddings via RRF) \u2014 set mode:"keyword" for BM25-only. Local search plus, when a configured enterprise store is part of the current project/work \u2014 or when the scope (or the default scope this session registered itself) is a personal user: scope and a remote store is configured with that same scope (exact match, case-insensitive; that rule adds only the matching store, though a store set to dial: always or a trusted project remote can still add others) \u2014 one live timeout-bounded recall per remote host merged in (a `remote_stores` block + warning appears when a host is degraded; no host configured or implicated = fully local). 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.',
       annotations: { title: "Recall", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -1118,7 +1258,7 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_recall_hybrid",
-      description: "[Deprecated since 0.16 \u2014 use plur_recall (mode defaults to hybrid). Alias kept for backwards compatibility; removal earliest 0.18.] Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion, plus the live enterprise-store recall leg when one is configured and project-relevant.",
+      description: "[Deprecated since 0.16 \u2014 use plur_recall (mode defaults to hybrid). Alias kept for backwards compatibility; removal earliest 0.18.] Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion, plus the live enterprise-store recall leg when one is configured and project-relevant, or when the scope is a personal user: scope matching the own scope of a configured remote store (exact, case-insensitive; adds only that store, while dial: always and a trusted project remote still apply).",
       annotations: { title: "Recall (hybrid) [deprecated alias]", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -1195,12 +1335,18 @@ function getAllToolDefinitions() {
         required: ["task"]
       },
       handler: async (args, plur) => {
+        const deadline_at = Date.now() + resolveRecallDeadlineMs();
         const session_id = _resolveWriteSession(args);
         const result = await plur.injectHybrid(args.task, {
           budget: args.budget,
           scope: args.scope,
           source: "inject",
-          session_id
+          session_id,
+          deadline_at,
+          // #1566: the dialing context follows the same rule as writes — the
+          // workspace's scope when the session has no default of its own.
+          // session_id above stays the caller's for attribution.
+          dial_session: await _readSession(args, plur)
         });
         _recordInjectionTelemetry(session_id, result.injected_packs);
         const response = {
@@ -1209,7 +1355,11 @@ function getAllToolDefinitions() {
           count: result.count,
           tokens_used: result.tokens_used,
           injected_ids: result.injected_ids,
-          mode: "hybrid",
+          // #1586 round 4: a degraded injection says so, instead of a fixed 'hybrid'.
+          // (Kept as 'hybrid' otherwise, as this reply always said.)
+          mode: result.mode === "hybrid-degraded" ? "hybrid-degraded" : "hybrid",
+          ...result.degraded_reason ? { degraded_reason: result.degraded_reason } : {},
+          ...(result.mode === "hybrid-degraded" || result.degraded_reason) && result.embedder_error ? { embedder_error: result.embedder_error } : {},
           // #181: unresolved-tension warnings — flag contradicted context
           ...result.warnings ? { warnings: result.warnings } : {},
           // #1142: pinned engrams that did not fit. `pinned: true` reads as a
@@ -1218,6 +1368,7 @@ function getAllToolDefinitions() {
           ...result.omitted_pinned?.length ? { omitted_pinned: result.omitted_pinned } : {}
         };
         attachRemoteStoreDegradation(response, plur);
+        attachRecallReport(response, result);
         return response;
       }
     },
@@ -1269,8 +1420,8 @@ function getAllToolDefinitions() {
           return { mode: "batch", results, summary };
         }
         try {
-          await plur.feedback(args.id, args.signal, args.scope);
-          return { success: true, id: args.id, signal: args.signal };
+          const { warnings } = await plur.feedback(args.id, args.signal, args.scope);
+          return { success: true, id: args.id, signal: args.signal, ...warnings.length > 0 ? { warnings } : {} };
         } catch (err) {
           if (err.message?.includes("readonly store")) {
             return { success: false, id: args.id, signal: args.signal, note: "Engram is in a readonly store. Feedback noted for this session but not persisted." };
@@ -1288,7 +1439,8 @@ function getAllToolDefinitions() {
         properties: {
           id: { type: "string", description: "Engram ID to pin or unpin" },
           pinned: { type: "boolean", description: "Target value (default true)" },
-          list: { type: "boolean", description: "If true, just return the current set of pinned engrams (no mutation)" }
+          list: { type: "boolean", description: "If true, just return the current set of pinned engrams (no mutation)" },
+          scope: { type: "string", description: `Which store holds it. Ids are minted per store, so one bare id can name a local engram and an unrelated remote one; such an id is refused. Pass "primary" for the local engram, or a remote store's scope (or the namespaced ENG-XXX-\u2026 id from recall) for the remote one.` }
         }
       },
       handler: async (args, plur) => {
@@ -1305,7 +1457,7 @@ function getAllToolDefinitions() {
         if (!args.id) throw new Error("Provide id (or list:true to list pinned)");
         const target = args.pinned ?? true;
         if (target === true) {
-          const q = await plur.pinnedQuota(args.id);
+          const q = await plur.pinnedQuota(args.id, args.scope ? { scope: args.scope } : void 0);
           if (q.candidate && !q.candidate.fits) {
             const deficit = q.candidate.would_be - q.quota;
             const covering = [];
@@ -1330,7 +1482,7 @@ function getAllToolDefinitions() {
             };
           }
         }
-        const updated = await plur.setPinnedAsync(args.id, target);
+        const updated = await plur.setPinnedAsync(args.id, target, args.scope ? { scope: args.scope } : void 0);
         if (!updated) throw new Error(`Engram not found: ${args.id}`);
         return {
           id: updated.id,
@@ -1361,18 +1513,18 @@ function getAllToolDefinitions() {
           const engram = scope ? void 0 : await plur.getById(args.id);
           if (engram) {
             if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
-            await plur.forget(args.id, args.reason, { force: true });
-            return { success: true, retired: { id: engram.id, statement: engram.statement } };
+            const { warnings: warnings2 } = await plur.forget(args.id, args.reason, { force: true });
+            return { success: true, retired: { id: engram.id, statement: engram.statement }, ...warnings2.length > 0 ? { warnings: warnings2 } : {} };
           }
-          await plur.forget(args.id, args.reason, { force: true, ...scope ? { scope } : {} });
-          return { success: true, retired: { id: args.id, ...scope ? { scope } : {} } };
+          const { warnings } = await plur.forget(args.id, args.reason, { force: true, ...scope ? { scope } : {} });
+          return { success: true, retired: { id: args.id, ...scope ? { scope } : {} }, ...warnings.length > 0 ? { warnings } : {} };
         }
         if (args.search) {
           const matches = await plur.recall(args.search, { limit: 100, remote: false });
           if (matches.length === 0) return { success: false, error: `No active engrams matching "${args.search}"` };
           if (matches.length === 1) {
-            await plur.forget(matches[0].id, args.reason, { force: true });
-            return { success: true, retired: { id: matches[0].id, statement: matches[0].statement } };
+            const { warnings } = await plur.forget(matches[0].id, args.reason, { force: true });
+            return { success: true, retired: { id: matches[0].id, statement: matches[0].statement }, ...warnings.length > 0 ? { warnings } : {} };
           }
           return {
             success: false,
@@ -1918,7 +2070,7 @@ function getAllToolDefinitions() {
           // Artifacts that could not be read (audit 2026-08-03, finding 14).
           // Core reports these; this hand-built response dropped them, so an
           // agent asking for status saw a healthy-looking `pack_count: 0`.
-          ...status.store_errors ? { store_errors: status.store_errors } : {},
+          ...status.store_errors ? { store_errors: redactStoreErrors(status.store_errors) } : {},
           // Spreading-activation drop counters — absent when both are zero.
           ...status.spread_drops ? { spread_drops: status.spread_drops } : {},
           // Version check (issue #151)
@@ -1929,7 +2081,11 @@ function getAllToolDefinitions() {
               behind: minorVersionsBehind(versionCheck.current, versionCheck.latest)
             }
           } : {},
-          capabilities: await mcpCanary.status()
+          capabilities: await mcpCanary.status(),
+          // #1526: a broken folders.yaml pauses every memory tool. Status is
+          // where an agent looks, so it names the line, the problem in plain
+          // words, and the repair (run only after the user agrees).
+          ...folderMapStatus(plur.storageRoot)
         };
       }
     },
@@ -2212,6 +2368,9 @@ function getAllToolDefinitions() {
                 detail: soon ? `Reachable, but token expires in ${h.tokenExpiresInDays}d \u2014 reauth soon` : `Reachable, auth valid${expiresNote}`
               });
               if (soon) remediation.push(`Remote ${h.url}: token expires in ${h.tokenExpiresInDays}d \u2014 mint a new token (<host>/me/api-keys), update ~/.plur/config.yaml, restart.`);
+            } else if (h.tokenEnvUnset) {
+              checks.push({ check: `remote store: ${h.url}`, ok: false, detail: tokenEnvUnsetDetail(h.tokenEnvUnset, h.scopes?.[0] ?? h.url) });
+              remediation.push(tokenEnvUnsetFix(h.url, h.tokenEnvUnset));
             } else if (h.status === "auth_expired") {
               checks.push({ check: `remote store: ${h.url}`, ok: false, detail: `AUTH FAILED${expiresNote} \u2014 team-scoped writes are queuing to the outbox, not syncing. (${h.reason ?? ""})` });
               remediation.push(`Remote ${h.url}: re-authenticate \u2014 open <host>/auth/github (or <host>/me/api-keys) in a browser, paste the token into ~/.plur/config.yaml, then restart Claude/MCP so it reloads. Queued engrams flush on next session_start.`);
@@ -2257,9 +2416,18 @@ function getAllToolDefinitions() {
         } catch {
         }
         const tool_surface = describeToolSurface();
+        const folderMap = folderMapStatus(plur.storageRoot);
+        if (folderMap.folder_map) {
+          const fm = folderMap.folder_map;
+          checks.push({ check: "folder map", ok: false, detail: `${fm.file} ${fm.problem}` });
+          remediation.push(`Folder map: ${fm.file} ${fm.problem}. ${fm.advice}`);
+        } else {
+          checks.push({ check: "folder map", ok: true, detail: "folders.yaml is readable (or absent: no decisions yet)" });
+        }
         return {
           ok: checks.every((c) => c.ok),
           checks,
+          ...folderMap,
           embedder: {
             before_probe: before,
             after_probe: after
@@ -2288,6 +2456,7 @@ function getAllToolDefinitions() {
         required: ["task"]
       },
       handler: async (args, plur) => {
+        const deadline_at = Date.now() + resolveRecallDeadlineMs();
         mcpCanary.reset();
         mcpCanary.signal("session_start_hook");
         const crypto = await import("crypto");
@@ -2323,16 +2492,30 @@ function getAllToolDefinitions() {
         });
         const projectConfig = readTrustedProjectConfig(plur);
         const explicit_default_scope = args.default_scope ?? null;
-        const default_scope = explicit_default_scope ?? projectConfig.scope ?? null;
-        const scope_source = explicit_default_scope ? "caller" : projectConfig.scope ? "project-config" : "none";
+        const folderCtx = _folderContext(args);
+        let workspace = null;
+        if (folderCtx) {
+          try {
+            workspace = await folderCtx.resolve();
+          } catch {
+            workspace = null;
+          }
+        }
+        const folder_scope = folderCtx ? workspace?.scope ?? null : null;
+        const default_scope = explicit_default_scope ?? (folderCtx ? folder_scope : projectConfig.scope ?? null) ?? null;
+        const scope_source = explicit_default_scope ? "caller" : folder_scope && folder_scope !== projectConfig.scope ? "folder-map" : default_scope ? "project-config" : "none";
         const default_domain = projectConfig.domain ?? null;
-        plur.setSessionScope(default_scope);
+        if (!folderCtx) plur.setSessionScope(default_scope);
         plur.setSessionScope(default_scope, { session: session_id });
         {
           const t = _sessionTelemetry.get(session_id);
           if (t) {
             t.default_scope = default_scope;
             t.default_scope_source = scope_source;
+            if (workspace) {
+              t.workspace_key = workspace.key;
+              t.workspace_scope = workspace.scope;
+            }
           }
         }
         const status = await plur.status().catch(() => null);
@@ -2341,19 +2524,27 @@ function getAllToolDefinitions() {
           episode_count: status?.episode_count ?? 0,
           pack_count: status?.pack_count ?? 0
         };
-        const store_errors = status?.store_errors;
+        const store_errors = status?.store_errors ? redactStoreErrors(status.store_errors) : void 0;
         await plur.warmRemoteCaches().catch(() => {
         });
         let engrams = null;
+        let injectionReport = {};
         try {
           const result = await plur.injectHybrid(task, {
             scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
             session_id,
             // stamped on the co_injection provenance event (#452)
             source: "session_start",
-            remote_timeout_ms: 5e3
+            remote_timeout_ms: 5e3,
             // session_start warm budget (#776)
+            deadline_at
           });
+          injectionReport = {
+            remote: result.remote,
+            results_complete: result.results_complete,
+            ...result.degraded_reason ? { degraded_reason: result.degraded_reason } : {},
+            ...(result.mode === "hybrid-degraded" || result.degraded_reason) && result.embedder_error ? { embedder_error: result.embedder_error } : {}
+          };
           _recordInjectionTelemetry(session_id, result.injected_packs);
           if (result.count > 0) {
             const lines = [];
@@ -2418,7 +2609,11 @@ ${guide}`;
 
 ${guide}`;
         }
-        if (scope_source === "project-config") {
+        if (scope_source === "folder-map") {
+          guide += `
+
+This folder's scope: "${default_scope}" (from your folder map, plur folders). plur_learn calls without an explicit scope will be tagged with this scope. Pass scope: "global" only for genuinely cross-project knowledge.`;
+        } else if (scope_source === "project-config") {
           guide += `
 
 Auto-detected project scope: "${default_scope}" (from .plur.yaml in the current project). plur_learn calls without an explicit scope will be tagged with this scope, keeping this project's knowledge separate from your other projects. Pass scope: "global" only for genuinely cross-project knowledge (general coding conventions, language gotchas, tool quirks).`;
@@ -2500,6 +2695,11 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
           ...default_scope ? { default_scope, scope_source } : {},
           ...default_domain ? { default_domain, domain_source: "project-config" } : {},
           ...projectConfig.warning ? { project_config_warning: projectConfig.warning } : {},
+          // #1586 audit L6: the injection's per-call remote report (added fields).
+          remote: injectionReport.remote ?? { state: "not_dialed", hosts: [] },
+          results_complete: injectionReport.results_complete ?? false,
+          ...injectionReport.degraded_reason ? { degraded_reason: injectionReport.degraded_reason } : {},
+          ...injectionReport.embedder_error ? { embedder_error: injectionReport.embedder_error } : {},
           // Ask LLM to check back — MCP can't push, but we can request a follow-up
           follow_up: store_stats.engram_count === 0 ? "This is a fresh store with 0 engrams. After your first exchange with the user, review what you learned and call plur_learn for any corrections, preferences, or patterns. Build the memory from this session." : void 0,
           // On fresh install, suggest hook setup for reliable injection
@@ -2612,7 +2812,8 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
             ...warning ? { warning } : {}
           });
         }
-        const restored = record !== void 0 ? record.default_scope ?? null : readTrustedProjectConfig(plur).scope ?? null;
+        const clearCtx = _folderContext(args);
+        const restored = record !== void 0 ? record.default_scope ?? null : clearCtx ? null : readTrustedProjectConfig(plur).scope ?? null;
         const restored_source = record !== void 0 ? record.default_scope_source === "caller" ? "session-start" : record.default_scope_source ?? "none" : restored != null ? "project-config" : "none";
         const { previous, next } = plur.adjustSessionScope(restored, { session, reason, trigger: "clear" });
         if (record) record.scope_adjusted = false;
@@ -2700,8 +2901,9 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           try {
             await plur.learnRouted(sanitizeStatement(statement), {
               type,
-              // E7: no resolvable session → no session default (NO_SESSION).
-              session: endSession ?? NO_SESSION,
+              // E7: no resolvable session → no session default; through the
+              // server, the workspace's answer (#1563 review round 2).
+              session: await _writeSession(args, plur, endSession),
               domain: projectDomain,
               // Link the engram back to the session that produced it (#960).
               session_episode_id: episode.id,
@@ -3135,6 +3337,9 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
       handler: async (args, plur) => {
         const engram = await plur.episodeToEngram(args.episode_id, {
           scope: args.scope,
+          // The same default as every other new write (#1563 review round 3,
+          // N1): never the process-wide slot.
+          session: await _writeSession(args, plur),
           domain: args.domain,
           tags: args.tags
         });
@@ -3365,9 +3570,12 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
 }
 
 export {
+  folderMapAdvice,
   registerFlushOnExit,
   validateToolArgs,
   mcpCanary,
+  folderOnCommand,
+  FOLDER_SCOPE,
   CURSOR_CORE_TOOL_NAMES,
   resolveToolProfile,
   setActiveToolProfile,