@plur-ai/mcp 0.21.0 → 0.21.1

package/README.md

@@ -69,6 +69,37 @@ Less commonly needed tools (`plur_recall_hybrid`, `plur_inject_hybrid`, `plur_le
 
 A `plur_*` name missing from `tools/list` means it moved behind the gateway, not that the server is down. `plur_admin { action: "help" }` returns every action with a one-line description and its argument schema; `plur_doctor` reports the same inventory as `tool_surface`.
 
+## Folders where PLUR is off
+
+Your folder map (`~/.plur/folders.yaml`, changed by `plur folders set` from a terminal) can turn PLUR off for a folder. The editor hooks already go silent there; the MCP server's memory tools do too.
+
+**What is gated.** 33 tools — every tool that reads or writes engrams or episodes or returns their text: `plur_learn`, `plur_learn_batch`, `plur_recall`, `plur_recall_hybrid`, `plur_inject`, `plur_inject_hybrid`, `plur_session_start`, `plur_session_end`, `plur_capture`, `plur_timeline`, `plur_feedback`, `plur_pin`, `plur_forget`, `plur_ingest`, `plur_promote`, `plur_rescope`, `plur_episode_to_engram`, `plur_report_failure`, `plur_extract_meta`, `plur_meta_engrams`, `plur_validate_meta`, `plur_tensions`, `plur_tensions_purge`, `plur_similarity_search`, `plur_history`, `plur_provenance`, `plur_profile`, `plur_receipt`, `plur_packs_install`, `plur_packs_uninstall`, `plur_packs_export`, `plur_sync`, `plur_outbox` — called directly or through `plur_admin`. In an `off` folder they read and write no store, local or remote (no outbox row either), and return a normal, non-error answer:
+
+```json
+{ "success": true, "plur": "off", "folder": "/work/secret", "message": "PLUR is off for this folder … plur folders set /work/secret --on" }
+```
+
+The message names every folder-map entry that turns the folder off (a parent folder or a glob can), with the command for each.
+
+**What is not gated.** The admin and diagnostic tools keep working: `plur_status`, `plur_doctor`, `plur_stores_list`, `plur_stores_add`, `plur_sync_status`, `plur_packs_list`, `plur_packs_discover`, `plur_packs_preview`, `plur_scopes_discover`, `plur_suggest_scope`, `plur_session_scope`. Some of them still read stores — status, doctor and stores_list load them to count or probe them, and doctor runs a recall probe. What they can return: counts, health and configuration; A store that cannot be parsed is reported by the error's first line only (what went wrong, line and column) — in `plur_status` and in the error any tool returns — never by the file's lines. One exception: `plur_packs_preview` previews any pack directory the agent names, including an installed pack under your PLUR home, and then returns that pack's statements. Server startup is not gated yet: starting the server in an `off` folder can still register a `.plur/` store found there ([#1523](https://github.com/plur-ai/plur/issues/1523)).
+
+**Which folder.** The editor's workspace: each root the client lists over MCP `roots/list`, plus the folder the server was started in. If any of them is `off`, the memory tools are off. The folder map is read on every call, so a change takes effect on the next one. Calls made while the roots are being fetched wait for them. If fetching them fails or times out, or a root does not resolve to a folder on this machine (`file://otherhost/…`, an encoded slash), that call does nothing (it answers `"reason": "workspace-unknown"`, not an error) and the next call asks again; it never falls back to the start folder alone. If the client's roots keep failing, memory stays off until they work. The roots answer is cached, and shared between calls made at the same time, only when the client declares `roots.listChanged`; otherwise every call sends its own roots request. A client that declares no roots capability at all, and was started outside the workspace, cannot be checked against it.
+
+**A broken folder map fails safe.** If `folders.yaml` exists but cannot be read or parsed — including a dangling symlink, a symlink loop, an empty or comments-only file, and an unknown top-level key such as a misspelled `folder:` — the gated tools do nothing and answer with `"reason": "folder-map-unreadable"`, naming the file, the line and column, and the problem in plain words — quoting at most the key on that line, never a value (#1526). A misspelled `plur:` or `path:` key (`plru:`, `pth:`) counts as broken too. When `plur folders repair` can fix it, the answer carries `repair_summary` (what the repair changes, to show the user first) and `repair_command` (`plur folders repair --yes`, with `--path` for a non-default store) and tells the agent to run it only after the user agrees; otherwise it says the line must be fixed by hand. A repair adds no `on` to the map; folders with their own trusted `.plur.yaml` or project MCP config are on again, as before the map broke. `plur_status` and `plur_doctor` report the same problem as `folder_map` (and `plur_doctor` fails its `folder map` check). No `folders.yaml` at all (nothing at that path) means no decisions yet: every folder is undecided and gets the question below. A broken map offers no folder-question command and issues no nonce (only the repair command, when the repair can fix it). On first read, an old `trust.yaml` is imported into a new `folders.yaml` (a one-time core migration); otherwise the server never writes the map.
+
+**An undecided folder gets the folder question** ([#1525](https://github.com/plur-ai/plur/issues/1525)). In a folder you have not decided about (folder map `ask`: no entry and no project marker, or a repo `.plur.yaml` asking for settings you have not trusted), the gated tools read and write no memory and answer, without an error, with the same question the editor hooks ask:
+
+```json
+{ "success": true, "plur": "ask", "folder": "/work/app", "question": "[PLUR Memory — no decision for this folder yet …] …",
+  "answers": [
+    { "label": "Yes, with the team scope group:acme/eng", "command": "plur folders set /work/app --scope group:acme/eng --nonce … --session mcp-…" },
+    { "label": "Yes, without a team scope", "command": "plur folders set /work/app --on --nonce … --session mcp-…" },
+    { "label": "Not now", "command": "plur folders set /work/app --not-now --nonce … --session mcp-…" },
+    { "label": "Never here", "command": "plur folders set /work/app --off --nonce … --session mcp-…" } ] }
+```
+
+The agent asks you and runs the command for your answer (or you run it in a terminal). Each command carries its own single-use nonce, bound to that folder, that answer and this MCP session: a command from another session, or one that drops `--session`, is refused. Every memory call returns the same question, with the same nonces, until you answer; the next call after an answer follows it. **Yes** turns memory on, and the answer's team scope becomes this session's default write scope: an unscoped `plur_learn` or `plur_learn_batch` goes there, with or without `plur_session_start` (which also uses the folder map's scope for its default when you pass none). An unscoped `plur_recall` (either mode), `plur_recall_hybrid` or `plur_inject_hybrid` searches that team's store too, again with or without `plur_session_start`. An explicit scope still wins. With several workspace folders, a folder scope is used only when every folder (none left out, each through its real path) has the same one; the home folder, a folder above it or `/` as a workspace folder means no folder scope. A `plur_session_start` default holds only while the workspace folders, and the scope they resolve to, are the ones the session started with. **Never here** turns it off. **Not now** writes nothing to the folder map: memory stays off for the rest of this MCP session, without the question; the folder stays undecided, so the next session asks again. The server never writes the map itself. The session's unanswered nonces are deleted as soon as the session closes (stdin ends, or SIGTERM / SIGINT); the server then exits once the tool calls already running have answered (after stdin ends, however long they take; on a signal, within 2 s); a server killed outright leaves its nonce file, which the next server removes once the nonces have expired (24 h). Precedence across the workspace folders is off, then ask, then on. `off` is checked on every workspace folder, the server's start folder included. The question is never asked about your home folder, a filesystem root or a folder above home, whether it is a root the client sends or the start folder: a yes or a never-here there would cover every folder under it, so memory there runs as before. Otherwise it is asked about the client's roots when it sends any — the start folder is wherever the client happened to launch the server — and, when it sends none (or only such folders), about the start folder. "Not now" stops the question, not the other answers: the yes and never-here commands of the same question keep working for that session, as with the editor hooks.
+
 ## Sync across machines
 
 Your agent can sync memory to any git remote:

package/dist/{chunk-WA3JKTZ7.js → chunk-O2NJFMNP.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.21.0";
+var VERSION = "0.21.1";
 
 export {
   VERSION

package/dist/{chunk-UINIIUBY.js → chunk-OETJSRYE.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-WA3JKTZ7.js";
+} from "./chunk-O2NJFMNP.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 } 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) => {
@@ -81,8 +101,9 @@ var recallHandler = async (args, plur) => {
       // 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 response2 = {
       results: results.map((e) => {
@@ -92,7 +113,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,
@@ -126,8 +151,9 @@ var recallHandler = async (args, plur) => {
     // MCP recall remote budget (#776)
     // #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 +182,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,
@@ -422,12 +449,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 +538,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 +691,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 +868,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 +884,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 +932,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 +970,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 +980,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 +1013,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 +1078,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 +1178,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 +1208,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 +1235,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",
@@ -1200,7 +1317,11 @@ function getAllToolDefinitions() {
           budget: args.budget,
           scope: args.scope,
           source: "inject",
-          session_id
+          session_id,
+          // #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 = {
@@ -1269,8 +1390,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 +1409,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 +1427,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 +1452,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 +1483,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 +2040,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 +2051,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 +2338,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 +2386,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
@@ -2323,16 +2461,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,7 +2493,7 @@ 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;
@@ -2418,7 +2570,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).`;
@@ -2612,7 +2768,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 +2857,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 +3293,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 +3526,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,

package/dist/index.d.ts

@@ -48,6 +48,13 @@ interface HookEntry {
         async?: boolean;
     }>;
 }
+/**
+ * Write the PLUR section into CLAUDE.md with core's `upsertInstructionSection`
+ * — the same logic as `plur init`: only a section PLUR shipped is replaced,
+ * one the user wrote or edited is kept and the new one added beside it, and a
+ * timestamped backup precedes any change to an existing file.
+ */
+declare function installClaudeMd(claudeMdPath?: string): Promise<string>;
 /**
  * Merge PLUR hooks into Claude Code settings (#1279). No I/O apart from
  * reading plur-hook.meta.json for the exec-form check.
@@ -72,4 +79,4 @@ declare function applyPlurHooks(settings: Settings, hooksMap: Record<string, Hoo
     status: 'installed' | 'healed' | 'already';
 };
 
-export { type HookEntry, type Settings, applyPlurHooks, buildPlurHooks, compareSemver, extractManifestVersion };
+export { type HookEntry, type Settings, applyPlurHooks, buildPlurHooks, compareSemver, extractManifestVersion, installClaudeMd };