@plur-ai/mcp 0.20.1 → 0.21.1

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

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-445S5QNU.js";
+} from "./chunk-O2NJFMNP.js";
 
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
@@ -15,9 +15,29 @@ function recordTelemetry(event) {
 
 // src/tools.ts
 import { existsSync, unlinkSync } from "fs";
-import { join } from "path";
+import { join, dirname, resolve } from "path";
 import { homedir } from "os";
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName, SUGGEST_DISPLAY_MIN_CONFIDENCE, mcpRemoteWarningLine, doctorRemoteRemediation, normalizeEndpointUrl, REMOTE_STATUS_TTL_MS, PROBE_CLEARABLE_STATES, bareEngramId, summariseProvenance, renderProvenanceSummary } 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) => {
@@ -79,8 +99,11 @@ 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.
-      session: _resolveInjectionSession(args)
+      // 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. #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) => {
@@ -90,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,
@@ -124,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.
-    session: _resolveInjectionSession(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;
@@ -154,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,
@@ -216,10 +245,12 @@ function jsonSchemaPropToZod(prop) {
       }
       const items = prop.items;
       const itemVariants = items?.anyOf ?? items?.oneOf;
-      const itemsAcceptString = items?.type === "string" || Array.isArray(itemVariants) && itemVariants.some((v) => v?.type === "string");
-      if (itemsAcceptString) {
+      if (items?.type === "string") {
         return trimmed.length === 0 ? [] : trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
       }
+      if (Array.isArray(itemVariants) && itemVariants.some((v) => v?.type === "string")) {
+        return trimmed.length === 0 ? [] : [trimmed];
+      }
       return val;
     }, z.array(itemSchema));
   }
@@ -253,9 +284,9 @@ function validateToolArgs(tool, rawArgs) {
     const arrayShapedDrop = partialDrop && missingArrayParams.length > 0;
     let dropHint = "";
     if (wholePayloadDrop) {
-      dropHint = " Known intermittent client-side issue (plur-ai/plur#772, refines #297): some MCP clients transiently drop the ENTIRE arguments payload \u2014 most often when several tool calls are batched into a single message. Nothing was stored or evaluated. Retry the IDENTICAL call with the full payload, as the ONLY tool call in that message \u2014 identical retries typically succeed. If two identical retries fail the same way, the arguments really are absent from your call \u2014 re-issue it with the intended fields." + (hasArrayParam ? ' If retries keep failing specifically on array parameters, pass them 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.' : "");
+      dropHint = " Known intermittent client-side issue (plur-ai/plur#772, refines #297): some MCP clients transiently drop the ENTIRE arguments payload \u2014 most often when several tool calls are batched into a single message. Nothing was stored or evaluated. Retry the IDENTICAL call with the full payload, as the ONLY tool call in that message \u2014 identical retries typically succeed. If two identical retries fail the same way, the arguments really are absent from your call \u2014 re-issue it with the intended fields." + (hasArrayParam ? ' If retries keep failing specifically on array parameters, pass them 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. (A list of free-text statements such as engram_suggestions is not comma-split: send it as a JSON string; a bare string is one item.)' : "");
     } else if (arrayShapedDrop) {
-      dropHint = ` Known client-side bug (plur-ai/plur#297): some MCP clients drop array-typed parameters from a large arguments payload while keeping the earlier fields (here: ${missingArrayParams.join(", ")}). This is size-sensitive \u2014 the same call often succeeds with a shorter payload, so shrink the other fields (e.g. a briefer summary) as well. 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.`;
+      dropHint = ` Known client-side bug (plur-ai/plur#297): some MCP clients drop array-typed parameters from a large arguments payload while keeping the earlier fields (here: ${missingArrayParams.join(", ")}). This is size-sensitive \u2014 the same call often succeeds with a shorter payload, so shrink the other fields (e.g. a briefer summary) as well. 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. (A list of free-text statements such as engram_suggestions is not comma-split: send it as a JSON string; a bare string is one item.)`;
     }
     const receivedNote = receivedFields.length > 0 ? `Received fields: [${receivedFields.join(", ")}].` : "Received no fields (the arguments object was empty).";
     const disposition = wholePayloadDrop ? "The request reached the server but its arguments did not \u2014 do not abandon the call, and do not rewrite the payload: it was never evaluated. Retry the IDENTICAL call; it usually succeeds. If you issued several tool calls in one message, send them one per message \u2014 batching is the strongest correlate of this drop (#772)." : "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.";
@@ -362,16 +393,23 @@ mcpCanary.expect({
 });
 var _sessionTelemetry = /* @__PURE__ */ new Map();
 var SESSION_TTL_MS = 8 * 60 * 60 * 1e3;
+var _pendingScopeEvictions = /* @__PURE__ */ new Set();
 function _cleanExpiredSessions(plur) {
   const cutoff = Date.now() - SESSION_TTL_MS;
   for (const [id, state] of _sessionTelemetry) {
     if (new Date(state.started_at).getTime() < cutoff) {
       _sessionTelemetry.delete(id);
+      _pendingScopeEvictions.add(id);
+    }
+  }
+  if (plur) {
+    for (const id of _pendingScopeEvictions) {
       try {
-        plur?.clearSessionScope({ session: id });
+        plur.clearSessionScope({ session: id });
       } catch {
       }
     }
+    _pendingScopeEvictions.clear();
   }
 }
 function _implicitSessionId() {
@@ -379,11 +417,165 @@ function _implicitSessionId() {
   if (_sessionTelemetry.size !== 1) return void 0;
   return _sessionTelemetry.keys().next().value;
 }
+function learnDecision(engram) {
+  return (engram.write_count ?? 1) > 1 ? { decision: "NOOP", existing_id: engram.id } : { decision: "ADD" };
+}
+var _warnedUntrustedConfigs = /* @__PURE__ */ new Set();
+function _estimatePinnedCost(statement, ctx) {
+  const id = "ENG-0000-0000-000";
+  const text = String(statement ?? "");
+  const commitment = typeof ctx.commitment === "string" ? ctx.commitment : void 0;
+  let rendered = 0;
+  try {
+    rendered = formatLayer3({ id, statement: text, domain: ctx.domain, rationale: ctx.rationale, commitment, confidence_score: 0 }).length + 1;
+  } catch {
+  }
+  const fieldSum = id.length + 4 + text.length + (ctx.rationale ? 15 + ctx.rationale.length : 0) + (ctx.domain ? ctx.domain.length + 10 : 0) + (commitment ? commitment.length + 14 : 0) + 23;
+  return Math.ceil(Math.max(rendered, fieldSum) / 4);
+}
+function _shellWord(s, platform = process.platform) {
+  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/.test(s)) return null;
+  if (/^[A-Za-z0-9_@+=:,./~-]+$/.test(s)) return s;
+  if (platform === "win32") {
+    if (/[$`%!"\u201c\u201d\u201e]/.test(s) || s.endsWith("\\")) return null;
+    return `"${s}"`;
+  }
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function trustCommand(dir, storageRoot, platform = process.platform) {
+  const target = dir === null ? "<dir>" : _shellWord(dir, platform);
+  if (target === null) return null;
+  if (!storageRoot || resolve(storageRoot) === resolve(join(homedir(), ".plur"))) return `plur trust ${target}`;
+  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);
+  if (!raw.scope && !raw.domain) return {};
+  const configDir = configPath ? dirname(configPath) : null;
+  let trusted = false;
+  try {
+    trusted = configDir !== null && trust.isDirectoryTrusted(configDir);
+  } catch {
+    trusted = false;
+  }
+  if (trusted) return { scope: raw.scope, domain: raw.domain };
+  const declared = [
+    raw.scope ? UNTRUSTED_SCOPE_GRAMMAR.test(raw.scope) ? `scope ${_escapedText(raw.scope)}` : "an invalid scope" : null,
+    raw.domain ? UNTRUSTED_DOMAIN_GRAMMAR.test(raw.domain) ? `domain ${_escapedText(raw.domain)}` : "an invalid domain" : null
+  ].filter(Boolean).join(" / ");
+  const cmd = configDir !== null && _UNSAFE_PATH_CHARS.test(configDir) ? null : trustCommand(configDir, trust.storageRoot);
+  const warning = `${configPath ? _escapedText(configPath) : ".plur.yaml"} declares ${declared}, but ${configDir ? _escapedText(configDir) : "its directory"} is not a trusted directory \u2014 ignoring it and using the local default scope instead. If this project is yours, ` + (cmd !== null ? `run: ${cmd}` : "run `plur trust` for that directory from a terminal.");
+  if (configPath && !_warnedUntrustedConfigs.has(configPath)) {
+    _warnedUntrustedConfigs.add(configPath);
+    try {
+      process.stderr.write(`[plur] ${warning}
+`);
+    } catch {
+    }
+  }
+  return { warning };
+}
+function describeRefusedRoute(scope) {
+  return isSharedScope(scope) ? { kind: "shared", what: `the shared scope "${scope}"`, rule: "unscoped writes are never auto-routed into a shared store" } : {
+    kind: "remote-personal",
+    what: `"${scope}", a personal scope on a remote store that is not verified as your own namespace (its /me identity is unknown or belongs to another user)`,
+    rule: "unscoped writes are never auto-routed into a remote personal namespace that is not verifiably yours"
+  };
+}
 function _resolveInjectionSession(args) {
   const explicit = args.session_id;
   if (typeof explicit === "string" && explicit.length > 0) return explicit;
   return _implicitSessionId();
 }
+var NO_SESSION_SLOT_WARNING = "No session is open, so this is the process-default slot. An id-less plur_learn / plur_inject / plur_recall uses NO session default unless exactly one session is open, so this slot governs neither writes nor the recall dialing context. Call plur_session_start (then plur_session_scope with its session_id) to scope a session.";
+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) {
@@ -415,7 +607,9 @@ var CURSOR_CORE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "plur_receipt",
   "plur_doctor",
   "plur_packs_uninstall",
-  "plur_tensions_purge"
+  "plur_tensions_purge",
+  "plur_tensions",
+  "plur_validate_meta"
 ]);
 function summarizeToolDescription(description) {
   const line = description.split("\n", 1)[0].trim();
@@ -493,13 +687,16 @@ function buildAdminDispatchTool(all) {
       const innerArgs = args.args ?? {};
       const validated = validateToolArgs(target, innerArgs);
       if (!validated.ok) {
-        return { ...validated.errorPayload, error: `${action}: ${validated.errorPayload.error}` };
+        const inner = String(validated.errorPayload.error);
+        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(`${action}: ${message}`);
+        throw new Error(message.startsWith(`${action}:`) ? message : `${action}: ${message}`);
       }
     }
   };
@@ -567,7 +764,7 @@ function getAllToolDefinitions() {
           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." },
-          session_id: { type: "string", description: "Session this write belongs to (from plur_session_start). Resolves the session default scope (incl. mid-session plur_session_scope changes) when no explicit scope is passed. Optional when one session is open; pass it when several are (#243)." },
+          session_id: { type: "string", description: "Session this write belongs to (from plur_session_start). Resolves the session default scope (incl. mid-session plur_session_scope changes) when no explicit scope is passed. Optional when one session is open. With none or several open and no session_id, NO session default applies: the write takes the unscoped path (#243, E7)." },
           measured_under: {
             type: "object",
             description: "Measurement context for numeric or benchmark-derived claims (#869). Records the conditions under which the asserted value was measured \u2014 model, source_type, hardware, dataset, date. When present, the tension scanner does not treat two measurements from the same store taken under different configurations as a contradiction (the skipped pair is reported in the scan result). Omit for non-numeric engrams.",
@@ -630,7 +827,7 @@ function getAllToolDefinitions() {
           visibility: {
             type: "string",
             enum: ["private", "public", "template"],
-            description: 'Whether this memory may leave this machine. Defaults to "private", which means it is EXCLUDED from every exported pack. Set "public" only when the user has said this is shareable with others \u2014 it is their decision, not yours. Without this an agent cannot mark anything shareable at all, so every memory it writes is private forever and any pack built from them is empty.'
+            description: 'Who this memory is shared with beyond its scope. Defaults to "private": EXCLUDED from every exported pack and from shared git sync. The default does NOT keep a team-scope write on this machine \u2014 with visibility omitted, a write whose scope is a team store (e.g. group:acme/eng) still goes to that team store. Only an EXPLICIT "private" keeps such a write local (stored here with a warning, never sent to the team store). Set "public" only when the user has said this is shareable with others \u2014 it is their decision, not yours. Without "public" nothing an agent writes can appear in a pack.'
           }
         },
         required: ["statement"]
@@ -647,7 +844,7 @@ function getAllToolDefinitions() {
           // hierarchy segment as a FULL term hit, double the weight of a
           // statement word, so a missing domain forfeits the strongest
           // retrieval signal an author has. Explicit argument always wins.
-          domain: args.domain ?? readProjectConfig().domain ?? void 0,
+          domain: args.domain ?? readTrustedProjectConfig(plur).domain ?? void 0,
           source: args.source,
           tags: args.tags,
           rationale: args.rationale,
@@ -671,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: _resolveInjectionSession(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();
@@ -685,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.` };
         };
@@ -725,12 +925,14 @@ function getAllToolDefinitions() {
         }
         try {
           const engram = await plur.learnRouted(statement, context);
+          const delivered = plur.deliveryOf(engram, context?.scope);
           const isOutbox = !!engram.structured_data?._outbox;
           const demoted = engram.structured_data?._demoted;
           const routed = engram.structured_data?._routed;
+          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;
@@ -759,7 +961,18 @@ function getAllToolDefinitions() {
             pinned: engram.pinned === true,
             // See the note on recall results: same fact, not same record.
             content_hash: engram.content_hash,
-            decision: "ADD",
+            // An absorbed duplicate (content-hash or cross-scope recurrence)
+            // hands back the EXISTING engram with write_count bumped; reporting
+            // it as 'ADD' told the caller a new memory exists when none was
+            // written. Same vocabulary as plur_learn_batch (formal Adapters #1).
+            ...learnDecision(engram),
+            // #1264: always present. The warning sits BEFORE the others so a
+            // 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 } : {},
             ...(() => {
@@ -767,14 +980,24 @@ 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.` } : {}
+            ...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,
+            // as a `warning`, because the old `info` string for the opposite
+            // outcome proved easy to miss in a long session — and this one
+            // changes what the caller should do next, rather than merely
+            // reporting where the write went.
+            ...routeRefused ? (() => {
+              const why = describeRefusedRoute(routeRefused.scope);
+              return { route_refused: { scope: routeRefused.scope, confidence: routeRefused.confidence, reason: routeRefused.reason, kind: why.kind }, warning: `No scope was provided. This content matched ${why.what} (confidence ${routeRefused.confidence}), but ${why.rule} \u2014 it was stored at "${engram.scope}" instead. If it belongs there, pass scope: "${routeRefused.scope}" explicitly, or move it with plur_rescope.` };
+            })() : {}
           };
         } catch (err) {
           const engram = await plur.learn(statement, context);
+          const delivered = plur.deliveryOf(engram, context?.scope);
           const isOutbox = !!engram.structured_data?._outbox;
           const routedFallback = engram.structured_data?._routed;
           mcpCanary.signal("learn_activity");
@@ -788,19 +1011,26 @@ function getAllToolDefinitions() {
             statement: engram.statement,
             scope: engram.scope,
             type: engram.type,
-            decision: "ADD",
+            ...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 } : {},
-            warning: `Remote write failed (${err.message}); engram queued for retry.`
+            // The routed write can fail for reasons that have nothing to do
+            // with a remote (a local lock, a store error), and learn() only
+            // queues when the scope is remote-backed. Say what actually
+            // happened (formal Adapters #1).
+            warning: isOutbox ? `Remote write failed (${err.message}); engram queued for retry.` : `Routed write failed (${err.message}); stored through the local learn() fallback at "${engram.scope}".`
           };
         }
       }
     },
     {
       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, or local cosine REPORTING when no LLM is configured). Exact-hash dedup also applies WITHIN the batch: a statement duplicating an earlier item in the same array resolves to NOOP against it. Similarity never suppresses a write \u2014 each result carries `dedup.mode` (llm | cosine | hash-only) and, when similarity ran, `dedup.near_duplicates`. Read dedup.mode before trusting an ADD: hash-only means "not identical", NOT "not a duplicate". Returns `ids` aligned 1:1 with the input array (ids[i] is the engram id for input i, or null if input i failed), the per-item decisions (each carrying its input_index), aggregate stats, and any per-item failures (each with its input index) \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.',
+      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, or local cosine REPORTING when no LLM is configured). Exact-hash dedup also applies WITHIN the batch: a statement duplicating an earlier item in the same array resolves to NOOP against it. Similarity never suppresses a write \u2014 each result carries `dedup.mode` (llm | cosine | hash-only) and, when similarity ran, `dedup.near_duplicates`. Read dedup.mode before trusting an ADD: hash-only means "not identical", NOT "not a duplicate". Returns `ids` aligned 1:1 with the input array (ids[i] is the engram id for input i, or null if input i failed), the per-item decisions (each carrying its input_index), aggregate stats, and any per-item failures (each with its input index) \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. Each item is written through the same routed path as plur_learn (learnRouted, #930), resolves the same session default scope (pass `session_id` when several sessions are open) and the same .plur.yaml domain default, and a `pinned` item is refused with pinned_quota_exceeded when the pinned set has no room \u2014 reported in `failures`, the rest of the batch still written. Items take no `visibility`: each gets the default ("private" \u2014 excluded from packs and shared git sync), and an item whose scope is a team store still goes to that team store; to keep a team-scope memory local, use plur_learn with an explicit visibility: "private". See plur-ai/plur#281.',
       annotations: { title: "Learn (batch)", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
@@ -837,7 +1067,8 @@ function getAllToolDefinitions() {
               required: ["statement"]
             }
           },
-          max_llm_calls: { type: "number", description: "Max LLM dedup calls across the whole batch (default 50). Once spent, remaining items fall back to the local cosine path (no API cost); the dedup.mode on each result says which ran. Pass a large number to opt out." }
+          max_llm_calls: { type: "number", description: "Max LLM dedup calls across the whole batch (default 50). Once spent, remaining items fall back to the local cosine path (no API cost); the dedup.mode on each result says which ran. Pass a large number to opt out." },
+          session_id: { type: "string", description: "Session these writes belong to (from plur_session_start). Resolves the session default scope for items without an explicit scope, exactly as plur_learn does. Optional when one session is open. With none or several open and no session_id, NO session default applies: the write takes the unscoped path (#243, E7)." }
         },
         required: ["engrams"]
       },
@@ -847,12 +1078,15 @@ 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 = await _writeSession(args, plur);
+        const projectDomain = readTrustedProjectConfig(plur).domain ?? void 0;
         const items = raw.map((e) => ({
           statement: sanitizeStatement(e.statement),
           context: {
             type: e.type,
             scope: e.scope,
-            domain: e.domain,
+            domain: e.domain ?? projectDomain,
+            session: batchSession,
             source: e.source,
             tags: e.tags,
             rationale: e.rationale,
@@ -864,11 +1098,44 @@ function getAllToolDefinitions() {
           }
         }));
         const maxLlmCalls = typeof args.max_llm_calls === "number" ? args.max_llm_calls : void 0;
-        const { results, stats, failures } = await plur.learnBatch(
-          items,
+        const gateFailures = [];
+        let admitted = items.map((_, i) => i);
+        if (items.some((it) => it.context.pinned === true)) {
+          const q = await plur.pinnedQuota();
+          let free = q.free;
+          admitted = [];
+          items.forEach((it, i) => {
+            if (it.context.pinned !== true) {
+              admitted.push(i);
+              return;
+            }
+            if (free <= 0) {
+              const claimed = q.free - free;
+              gateFailures.push({
+                index: i,
+                statement: String(it.statement ?? "").slice(0, 80),
+                error: `pinned_quota_exceeded: the pinned set has no room (quota ${q.quota}, used ${q.used}${claimed > 0 ? `, plus ~${claimed} claimed by earlier pinned items in this batch` : ""}); this item was NOT stored \u2014 learn it unpinned or unpin something first (plur_pin {list:true}).`
+              });
+              return;
+            }
+            admitted.push(i);
+            free -= _estimatePinnedCost(it.statement, it.context);
+          });
+        }
+        const batchOut = admitted.length === 0 ? { results: [], stats: { added: 0, updated: 0, merged: 0, noops: 0, failed: 0 }, failures: [] } : await plur.learnBatch(
+          admitted.map((i) => items[i]),
           llm,
           maxLlmCalls !== void 0 ? { maxLlmCalls } : void 0
         );
+        const results = batchOut.results.map((r) => ({
+          ...r,
+          input_index: r.input_index !== void 0 ? admitted[r.input_index] : void 0
+        }));
+        const failures = [
+          ...batchOut.failures.map((f) => ({ ...f, index: admitted[f.index] ?? f.index })),
+          ...gateFailures
+        ].sort((a, b) => a.index - b.index);
+        const stats = { ...batchOut.stats, failed: (batchOut.stats.failed ?? 0) + gateFailures.length };
         mcpCanary.signal("learn_activity");
         recordTelemetry("learn");
         const ids = raw.map(() => null);
@@ -894,13 +1161,31 @@ function getAllToolDefinitions() {
           } catch {
           }
         }
+        const refusedScopes = [...new Set(results.map((r) => r.engram.structured_data?._routeRefused?.scope).filter((sc) => typeof sc === "string"))];
+        const refusedCount = results.filter((r) => r.engram.structured_data?._routeRefused !== void 0).length;
+        const warnings = [];
+        if (failures.length > 0) {
+          warnings.push(`${failures.length} of ${raw.length} engram(s) failed to persist; the rest were written.`);
+        }
+        if (refusedCount > 0) {
+          warnings.push(
+            `${refusedCount} of ${raw.length} engram(s) had no scope and matched ${refusedScopes.map((sc) => describeRefusedRoute(sc).what).join("; ")} \u2014 unscoped writes are never auto-routed into a shared store or into a remote personal namespace that is not verifiably yours, so they were stored at the local default instead. Pass an explicit scope on those items if they belong there, or move them with plur_rescope.`
+          );
+        }
         return {
           ids,
           results: results.map((r) => {
             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,
@@ -909,18 +1194,21 @@ function getAllToolDefinitions() {
               // #856 audit: `dedup` was computed and then dropped here, so the
               // reporting it exists for reached no caller — "anything below the
               // bar is still reported" was not observable anywhere.
-              ...r.dedup ? { dedup: r.dedup } : {}
+              ...r.dedup ? { dedup: r.dedup } : {},
+              ...routed ? { routed: { scope: routed.scope, confidence: routed.confidence, reason: routed.reason } } : {},
+              ...routeRefused ? { route_refused: { scope: routeRefused.scope, confidence: routeRefused.confidence, reason: routeRefused.reason } } : {}
             };
           }),
           stats,
           ...batchDomainHint,
-          ...failures.length > 0 ? { failures, warning: `${failures.length} of ${raw.length} engram(s) failed to persist; the rest were written.` } : {}
+          ...failures.length > 0 ? { failures } : {},
+          ...warnings.length > 0 ? { warning: warnings.join(" ") } : {}
         };
       }
     },
     {
       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",
@@ -939,7 +1227,7 @@ function getAllToolDefinitions() {
           budget: { type: "object", description: 'Budget constraints for sub-agents. Hybrid mode only \u2014 ignored when mode:"keyword".', properties: { max_tokens: { type: "number" }, max_results: { type: "number" } } },
           caller_session_id: { type: "string", description: 'Session ID of calling agent for budget enforcement. Hybrid mode only \u2014 ignored when mode:"keyword".' },
           include_episodes: { type: "boolean", description: 'If true, include linked episode summaries for each engram (SP2 episodic anchoring). Hybrid mode only \u2014 ignored when mode:"keyword".' },
-          session_id: { type: "string", description: "Session this recall belongs to (from plur_session_start). Its default scope (incl. mid-session plur_session_scope changes) sets the remote dialing context when no explicit scope filter is passed. Optional when one session is open (#243)." }
+          session_id: { type: "string", description: "Session this recall belongs to (from plur_session_start). Its default scope (incl. mid-session plur_session_scope changes) sets the remote dialing context when no explicit scope filter is passed. Optional when one session is open (#243); with none or several open and no session_id, no session default applies." }
         },
         required: ["query"]
       },
@@ -947,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",
@@ -959,7 +1247,7 @@ function getAllToolDefinitions() {
           budget: { type: "object", description: "Budget constraints for sub-agents", properties: { max_tokens: { type: "number" }, max_results: { type: "number" } } },
           caller_session_id: { type: "string", description: "Session ID of calling agent for budget enforcement" },
           include_episodes: { type: "boolean", description: "If true, include linked episode summaries for each engram (SP2 episodic anchoring)" },
-          session_id: { type: "string", description: "Session this recall belongs to (from plur_session_start). Its default scope sets the remote dialing context when no explicit scope filter is passed (#243)." }
+          session_id: { type: "string", description: "Session this recall belongs to (from plur_session_start). Its default scope sets the remote dialing context when no explicit scope filter is passed (#243). Optional when one session is open; with none or several open and no session_id, no session default applies." }
         },
         required: ["query"]
       },
@@ -981,12 +1269,12 @@ function getAllToolDefinitions() {
           task: { type: "string", description: "The task description to inject context for" },
           budget: { type: "number", description: "Token budget for injection (default 2000)" },
           scope: { type: "string", description: "Scope filter for engram selection" },
-          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open; required for correct attribution when several are." }
+          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open. With none or several open and no session_id, no session default applies (E7) and the injection is not attributed to any session." }
         },
         required: ["task"]
       },
       handler: async (args, plur) => {
-        const session_id = _resolveInjectionSession(args);
+        const session_id = _resolveWriteSession(args);
         const result = await plur.inject(args.task, {
           budget: args.budget,
           scope: args.scope,
@@ -1019,17 +1307,21 @@ function getAllToolDefinitions() {
           task: { type: "string", description: "The task description to inject context for" },
           budget: { type: "number", description: "Token budget for injection (default 2000)" },
           scope: { type: "string", description: "Scope filter for engram selection" },
-          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open; required for correct attribution when several are." }
+          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open. With none or several open and no session_id, no session default applies (E7) and the injection is not attributed to any session." }
         },
         required: ["task"]
       },
       handler: async (args, plur) => {
-        const session_id = _resolveInjectionSession(args);
+        const session_id = _resolveWriteSession(args);
         const result = await plur.injectHybrid(args.task, {
           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 = {
@@ -1098,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." };
@@ -1117,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) => {
@@ -1134,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 = [];
@@ -1159,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,
@@ -1190,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,
@@ -1404,6 +1697,13 @@ function getAllToolDefinitions() {
             // field has, so a caller reading only that cannot distinguish a
             // clean pack from one whose baseline was destroyed.
             integrity_status: p.integrity_status,
+            // 'carried-from-v1' when the v2 baseline was carried from a v1 row
+            // without re-verification (§5.5): `ok` then means "unchanged since
+            // the migration", not "matches what was installed".
+            ...p.baseline ? { baseline: p.baseline } : {},
+            // true when the pack's only registry row is a legacy row another
+            // same-name pack could own; integrity_status is then 'unverified'.
+            ...p.registry_ambiguous ? { registry_ambiguous: true } : {},
             installed_at: p.installed_at,
             source: p.source
           })),
@@ -1489,7 +1789,7 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_outbox",
-      description: "Inspect the remote-write outbox \u2014 team-scoped writes queued locally because their remote store was unreachable. Read-only by default; pass flush:true to retry them now. Entries never include the target URL or token.",
+      description: "Inspect the remote-write outbox \u2014 team-scoped writes queued locally because their remote store was unreachable, plus any other queued remote operation core lists (e.g. a retirement still to be applied on the remote). Read-only by default; pass flush:true to retry them now. Entries never include the target URL or token.",
       annotations: { title: "Outbox", readOnlyHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
@@ -1500,11 +1800,21 @@ function getAllToolDefinitions() {
       handler: async (args, plur) => {
         const before = await plur.listOutbox();
         if (args.flush !== true) {
-          return { pending: before.length, entries: before };
+          const summary = summarizeOutbox(before);
+          return {
+            pending: before.length,
+            retrying: summary.retrying,
+            needs_action: summary.needs_action,
+            ...summary.needs_action > 0 ? { needs_action_scopes: summary.scopes } : {},
+            entries: before
+          };
         }
-        const result = await plur.flushOutbox();
+        const result = await plur.flushOutbox({ force: true });
         return {
-          pending: await plur.outboxCount(),
+          // Counted from the same list the entries come from (formal R2): a
+          // separate counter can miss an entry kind the list shows (e.g. a
+          // queued remote retirement), and report 0 while one is stuck.
+          pending: (await plur.listOutbox()).length,
           flushed: result.flushed,
           failed: result.failed,
           ...result.expired_warnings.length > 0 ? { expired_warnings: result.expired_warnings } : {},
@@ -1632,8 +1942,13 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_validate_meta",
-      description: "Test a meta-engram template against engrams from a new domain \u2014 updates confidence and domain_coverage",
-      annotations: { title: "Validate meta-engram", destructiveHint: false, idempotentHint: false },
+      description: "Test a meta-engram template against engrams from a new domain \u2014 updates confidence and domain_coverage. A meta-engram that fails validation in a third domain is demoted (top \u2192 mop) or, below top level, RETIRED.",
+      // Destructive (owner decision I_tensions_resolve, formal R2): the third
+      // failed validation retires a non-top meta-engram (core
+      // meta/validation.ts) and the handler persists it. A removal needs an
+      // explicit, gated act, so plur_admin refuses this tool and it is a direct
+      // tool in every profile (CURSOR_CORE_TOOL_NAMES).
+      annotations: { title: "Validate meta-engram", destructiveHint: true, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -1658,9 +1973,15 @@ function getAllToolDefinitions() {
           args.llm_api_key,
           args.llm_model
         );
+        const wasRetired = meta.status === "retired";
         const result = await validateMetaEngram(meta, testEngrams, testDomain, llm);
+        const retiredNow = !wasRetired && meta.status === "retired";
         await plur.updateEngram(meta);
         return {
+          ...retiredNow ? {
+            retired: true,
+            note: `Meta-engram ${result.meta_engram_id} was retired: its prediction failed in a third domain. It no longer injects; its history records the retirement.`
+          } : {},
           meta_engram_id: result.meta_engram_id,
           test_domain: result.test_domain,
           prediction_held: result.prediction_held,
@@ -1704,6 +2025,9 @@ function getAllToolDefinitions() {
           tension_count: status.tension_count,
           versioned_engram_count: status.versioned_engram_count ?? 0,
           outbox_count: status.outbox_count ?? 0,
+          // #1299: queued writes a retry cannot deliver, per scope.
+          outbox_needs_action: status.outbox_needs_action ?? 0,
+          ...status.outbox_attention ? { outbox_attention: status.outbox_attention } : {},
           // Injection-provenance event/label counts (#452) — #202's volume gate.
           history_events: status.history_events ?? {
             co_injection: 0,
@@ -1716,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)
@@ -1727,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)
         };
       }
     },
@@ -2010,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.`);
@@ -2055,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
@@ -2071,7 +2411,11 @@ function getAllToolDefinitions() {
     {
       name: "plur_session_start",
       description: "Start a session \u2014 inject relevant engrams for your task. Call at the beginning of every session.",
-      annotations: { title: "Session Start", readOnlyHint: true, idempotentHint: false },
+      // Not read-only (formal R2, mcp-integrations#6): start registers the
+      // session's scope, flushes the remote-write outbox (pushes to remote
+      // stores) and writes telemetry. It only replays writes already asked for,
+      // so it is not destructive.
+      annotations: { title: "Session Start", readOnlyHint: false, destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -2101,6 +2445,12 @@ function getAllToolDefinitions() {
         } catch (err) {
           outbox_error = err.message;
         }
+        let outbox_needs;
+        try {
+          const summary = await plur.outboxSummary();
+          if (summary.needs_action > 0) outbox_needs = summary;
+        } catch {
+        }
         const remote_scopes = plur.getWritableRemoteScopes().map((s) => {
           const md = plur.getScopeMetadata(s.scope);
           return {
@@ -2109,18 +2459,32 @@ function getAllToolDefinitions() {
             ...md?.covers && md.covers.length > 0 ? { covers: md.covers } : {}
           };
         });
-        const projectConfig = readProjectConfig();
+        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);
@@ -2129,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;
@@ -2201,7 +2565,16 @@ ${guide}`;
             version_warning = `Update available: PLUR v${versionCheck.current} \u2192 v${versionCheck.latest}. Run: npm i -g @plur-ai/cli@latest && plur init (configs pin versions)`;
           }
         }
-        if (scope_source === "project-config") {
+        if (projectConfig.warning) {
+          guide = `\u26A0\uFE0F ${projectConfig.warning}
+
+${guide}`;
+        }
+        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).`;
@@ -2261,6 +2634,11 @@ Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: wh
           } catch {
           }
         }
+        if (outbox_needs) {
+          guide += `
+
+\u26A0\uFE0F OUTBOX: ${outbox_needs.needs_action} queued team write(s) cannot be delivered by retrying. ` + describeNeedsAction(outbox_needs).join(" ") + " Tell the user; nothing is dropped automatically. `plur outbox` lists them.";
+        }
         const session_tool_profile = activeToolProfile();
         if (session_tool_profile !== "full") {
           guide += `
@@ -2277,6 +2655,7 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
           ...remote_scopes.length > 0 ? { remote_scopes } : {},
           ...default_scope ? { default_scope, scope_source } : {},
           ...default_domain ? { default_domain, domain_source: "project-config" } : {},
+          ...projectConfig.warning ? { project_config_warning: projectConfig.warning } : {},
           // 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
@@ -2293,6 +2672,10 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
             outbox_error,
             outbox_warning: `The outbox flush failed \u2014 ${outbox_error}. Engrams routed to a remote store are still queued locally and were NOT pushed. They retry on the next session_start or plur_sync.`
           } : {},
+          // #1299: writes a retry cannot deliver — count, scope, reason, next step.
+          ...outbox_needs ? {
+            outbox_needs_action: { count: outbox_needs.needs_action, scopes: outbox_needs.scopes }
+          } : {},
           // Version staleness warning (issue #151)
           ...version_warning ? { version_warning, version: VERSION } : {}
         };
@@ -2302,7 +2685,7 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
     },
     {
       name: "plur_session_scope",
-      description: `Adjust or inspect the session default write scope MID-session \u2014 narrow, expand, or switch context without restarting the session (#243). op:"set" replaces the default scope used by unscoped plur_learn calls for the rest of the session AND the org context that decides which enterprise hosts plur_recall dials; op:"show" reports the effective scope and how it was derived (project config, session_start default, or a mid-session set); op:"clear" reverts to the scope the session started with. Use when the conversation genuinely pivots \u2014 a focused bug fix surfacing a team-wide architecture insight, or switching to another org's project. Do NOT oscillate scope call-by-call: for a one-off write to a different scope, pass scope explicitly on that plur_learn instead (explicit per-call scope always beats the session default). Every change is logged as a session_scope_changed history event.`,
+      description: `Adjust or inspect the session default write scope MID-session \u2014 narrow, expand, or switch context without restarting the session (#243). op:"set" replaces the default scope used by unscoped plur_learn calls for the rest of the session AND the org context that decides which enterprise hosts plur_recall dials (it needs an open session: with none open it refuses, since no id-less call reads a session-less slot); op:"show" reports the effective scope and how it was derived (project config, session_start default, or a mid-session set); op:"clear" reverts to the scope the session started with. Use when the conversation genuinely pivots \u2014 a focused bug fix surfacing a team-wide architecture insight, or switching to another org's project. Do NOT oscillate scope call-by-call: for a one-off write to a different scope, pass scope explicitly on that plur_learn instead (explicit per-call scope always beats the session default). Every change is logged as a session_scope_changed history event.`,
       annotations: { title: "Session scope", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -2335,6 +2718,7 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
         const reason = args.reason;
         const { session, ambiguous, open } = _resolveScopeSession(args);
         const record = session ? _sessionTelemetry.get(session) : void 0;
+        const noSessionSlot = session === void 0 && open === 0;
         const remote_scopes = plur.getWritableRemoteScopes();
         const withCommon = (body) => ({
           op,
@@ -2350,7 +2734,7 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
             source,
             ...ambiguous ? {
               warning: `${open} sessions are open \u2014 this is the process-default slot, not a specific session's scope. Pass session_id (from plur_session_start) to inspect one.`
-            } : {},
+            } : noSessionSlot && scope != null ? { warning: NO_SESSION_SLOT_WARNING } : {},
             guide: scope == null ? "No session default scope is set: unscoped plur_learn writes auto-route on a confident covers match or land at the unscoped default. Explicit per-call scope always wins." : `Unscoped plur_learn calls this session default to "${scope}"; recall dialing follows the same org context. Explicit per-call scope always wins.`
           });
         }
@@ -2360,6 +2744,11 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
           );
         }
         if (op === "set") {
+          if (noSessionSlot) {
+            throw new Error(
+              "plur_session_scope: no session is open, so there is no session scope to set \u2014 an id-less plur_learn / plur_inject / plur_recall uses no session default unless exactly one session is open. Call plur_session_start first (then pass its session_id here), or pass scope explicitly on each plur_learn."
+            );
+          }
           const scope = args.scope;
           if (typeof scope !== "string" || scope.trim().length === 0) {
             throw new Error('plur_session_scope: op:"set" requires a non-empty string "scope" (use op:"clear" to revert to the session-start default)');
@@ -2370,7 +2759,8 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
           const { previous: previous2, next: next2 } = plur.adjustSessionScope(scope, { session, reason, trigger: "set" });
           if (record) record.scope_adjusted = true;
           const remoteEntry = remote_scopes.find((s) => s.scope === scope);
-          const warning = isSharedScope(scope) ? remoteEntry ? `"${scope}" routes to the shared remote store at ${remoteEntry.url}: every unscoped plur_learn for the rest of this session defaults there, visible to everyone with read access to that scope. The per-write secrets/sensitivity guard still scans each write (offending content is demoted to local), but relevance is your call \u2014 clear or narrow the scope when the conversation leaves team context.` : `"${scope}" is a shared-family scope but matches no configured remote store scope, so writes stay on this machine under that namespace. The write-time sensitivity guard treats it as shared (scans + demotes offending content). If you expected a team store, check the remote_scopes list.` : void 0;
+          const sharedWarning = isSharedScope(scope) ? remoteEntry ? `"${scope}" routes to the shared remote store at ${remoteEntry.url}: every unscoped plur_learn for the rest of this session defaults there, visible to everyone with read access to that scope. The per-write secrets/sensitivity guard still scans each write (offending content is demoted to local), but relevance is your call \u2014 clear or narrow the scope when the conversation leaves team context.` : `"${scope}" is a shared-family scope but matches no configured remote store scope, so writes stay on this machine under that namespace. The write-time sensitivity guard treats it as shared (scans + demotes offending content). If you expected a team store, check the remote_scopes list.` : void 0;
+          const warning = sharedWarning;
           return withCommon({
             previous_scope: previous2,
             new_scope: next2,
@@ -2378,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 : readProjectConfig().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;
@@ -2424,7 +2815,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
                 }
               ]
             },
-            description: 'Learnings from this session. Preferred shape is {statement: "...", type?: "..."}; bare strings are also accepted and treated as the statement. Review the conversation for corrections, preferences, patterns, and technical facts before calling.'
+            description: 'Learnings from this session. Preferred shape is {statement: "...", type?: "..."}; bare strings are also accepted and treated as the statement. If the whole parameter arrives as one plain string it is ONE suggestion (never split on commas); send several as a JSON array. Review the conversation for corrections, preferences, patterns, and technical facts before calling.'
           }
         },
         required: ["summary", "engram_suggestions"]
@@ -2457,13 +2848,19 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           session_id,
           channel: "mcp"
         });
+        const endSession = _resolveInjectionSession(args);
+        const projectDomain = readTrustedProjectConfig(plur).domain ?? void 0;
         let engrams_created = 0;
         const engrams_failed = [];
         for (let i = 0; i < items.length; i++) {
           const { statement, type } = items[i];
           try {
-            await plur.learn(statement, {
+            await plur.learnRouted(sanitizeStatement(statement), {
               type,
+              // 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,
               // An end-of-session summary is the model's reading of what
@@ -2475,20 +2872,23 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             engrams_failed.push({ index: i, statement: statement.slice(0, 80), error: err.message });
           }
         }
-        const telemetry = session_id ? _sessionTelemetry.get(session_id) : void 0;
+        const telemetry = endSession ? _sessionTelemetry.get(endSession) : void 0;
         const injection_summary = telemetry && telemetry.injection_calls > 0 ? {
           pack_counts: { ...telemetry.pack_counts },
           total_injections: telemetry.injection_calls,
           session_duration_ms: Date.now() - new Date(telemetry.started_at).getTime()
         } : void 0;
-        if (session_id) {
-          _sessionTelemetry.delete(session_id);
-          plur.clearSessionScope({ session: session_id });
+        if (endSession) {
+          _sessionTelemetry.delete(endSession);
+          plur.clearSessionScope({ session: endSession });
         }
         try {
-          const plurDir = process.env.PLUR_PATH ?? join(homedir(), ".plur");
+          const plurDir = process.env.PLUR_PATH || join(homedir(), ".plur");
           const sessionsDir = join(plurDir, "sessions");
-          const keys = [session_id, process.env.CLAUDE_SESSION_ID, String(process.ppid)].filter(Boolean).map((k) => k.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64));
+          const keys = [session_id, process.env.CLAUDE_SESSION_ID, String(process.ppid)].filter(Boolean).flatMap((k) => [
+            (k.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown").slice(0, 64),
+            k.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64)
+          ]).filter(Boolean);
           for (const key of keys) {
             const cp = join(sessionsDir, `${key}.checkpoint.json`);
             if (existsSync(cp)) {
@@ -2595,12 +2995,24 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const raw = args.min_confidence;
         const explicit = typeof raw === "number" && Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : void 0;
         const minConfidence = explicit ?? plur.getScopeRoutingConfig().min_confidence ?? SUGGEST_DISPLAY_MIN_CONFIDENCE;
-        const candidates = await plur.suggestScope({
+        const signals = {
           statement: args.statement,
           domain: args.domain,
           tags: args.tags
-        }, { minConfidence });
-        return { candidates, count: candidates.length, min_confidence: minConfidence };
+        };
+        const candidates = await plur.suggestScope(signals, { minConfidence });
+        const decision = plur.previewAutoRoute(signals);
+        const would_route = decision.action === "route" && decision.scope ? { scope: decision.scope, note: "An unscoped write of these signals would be auto-routed here." } : decision.action === "refuse-shared" && decision.refusedShared ? (() => {
+          const why = describeRefusedRoute(decision.refusedShared.scope);
+          return {
+            scope: null,
+            // Field name kept for compatibility; `refused_kind` says which kind it is.
+            refused_shared: decision.refusedShared.scope,
+            refused_kind: why.kind,
+            note: `The best match is ${why.what}, and ${why.rule}. An unscoped write would land at the local default instead. Pass that scope explicitly if the engram belongs there.`
+          };
+        })() : { scope: null, note: "An unscoped write of these signals would land at the local default \u2014 nothing matched confidently enough to route." };
+        return { candidates, count: candidates.length, min_confidence: minConfidence, would_route };
       }
     },
     {
@@ -2691,6 +3103,14 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     {
       name: "plur_rescope",
       description: "Move existing engram(s) to a different scope (#676) \u2014 e.g. promote a personal/local engram into a team scope so it reaches the shared store. Bypasses the content-hash dedup that makes a plur_learn re-emit a silent no-op: rescope matches by id and moves the engram. Remote targets (a configured writable store scope): a copy is pushed via the routed write path (the server assigns the id, provenance is kept in the copy's source field) and the local original is soft-retired with a superseded_by link \u2014 set keep_local:true to keep it active. Local targets (local, global, project:*): the scope is rewritten in place, preserving id and activation. The target must be local/global/project:* or a scope with a configured writable store \u2014 anything else fails early (typo protection). Content is re-scanned for secrets/sensitive material before any shared/remote target and a hit blocks the move. Batch via ids; dry_run:true previews every decision without mutating anything. NOT candidate activation \u2014 that is plur_promote.",
+      // NOT destructive (owner decision I_tensions_resolve, formal R2): a
+      // rescope never removes content. A local target rewrites the scope in
+      // place (same id, same activation); a remote target retires the local
+      // original only after the copy was pushed, and links it to that copy
+      // with `superseded_by`. A copy always remains, so this is a move, not a
+      // removal — it stays dispatchable through plur_admin
+      // (rescope-tool.test.ts). Contrast plur_tensions resolve, which retires
+      // the loser with no copy and is therefore destructive.
       annotations: { title: "Rescope", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -2720,7 +3140,14 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     {
       name: "plur_tensions",
       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 },
+      // Not idempotent (formal R2, mcp-integrations#6): scan persists each NEW
+      // detection, and an LLM judge can find new pairs on a repeat call.
+      // Destructive (owner decision I_tensions_resolve, formal R2): action
+      // "resolve" retires the losing engram with no copy left — exactly
+      // plur_forget's effect. A removal needs an explicit, gated act, so
+      // plur_admin refuses this tool and it is a direct tool in every profile
+      // (CURSOR_CORE_TOOL_NAMES), where the client sees this annotation.
+      annotations: { title: "Tensions", readOnlyHint: false, destructiveHint: true, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -2866,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
         });
@@ -3096,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,