@echomem/mcp 1.4.14 → 1.4.15

package/dist/hud/diagnostics.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { echoConfigDir, KeyStore } from "../keystore.js";
+const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+const EVENTS_TAIL_LINES = 400;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function briefError(error) {
+    const message = error instanceof Error ? error.message : String(error || "Connection failed");
+    return message
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [redacted]")
+        .replace(/ec_[A-Za-z0-9._-]+/g, "ec_[redacted]")
+        .replace(/\s+/g, " ")
+        .slice(0, 180);
+}
+function normalizePlan(value) {
+    const plan = text(value)?.toLowerCase();
+    return plan && ["free", "pro", "power", "team", "enterprise"].includes(plan) ? plan : undefined;
+}
+/** Parse the account bootstrap contract without importing app-only code into the npm package. */
+export function accountDiagnosticsFromBootstrap(payload) {
+    const root = record(payload) ?? {};
+    const entitlements = record(root.entitlements) ?? {};
+    const usage = record(root.usage) ?? {};
+    const activation = record(root.activation) ?? {};
+    const limit = number(entitlements.deepSearchPerMonth);
+    const searchesThisMonth = number(activation.memorySearchMonthToDateCount);
+    const searchesRemaining = limit === undefined || searchesThisMonth === undefined
+        ? undefined
+        : limit < 0
+            ? null
+            : Math.max(0, limit - searchesThisMonth);
+    return {
+        plan: normalizePlan(root.plan),
+        deepSearchPerMonth: limit,
+        searchesThisMonth,
+        searchesRemaining,
+        memoryCount: number(usage.memories),
+        sourceCount: number(usage.sources),
+    };
+}
+/** Read only the latest memory-search trace; never return a query, token, or memory content. */
+export function latestSearchTraceFromEvents(lines) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+            const event = record(JSON.parse(lines[index] || ""));
+            if (!event || event.type !== "tool_call" || event.tool !== "search_memories")
+                continue;
+            const at = text(event.ts);
+            if (!at)
+                continue;
+            return {
+                at,
+                ok: typeof event.ok === "boolean" ? event.ok : undefined,
+                requestId: text(event.request_id),
+                endpoint: text(event.endpoint),
+                httpStatus: number(event.http_status),
+                errorCode: text(event.error_code),
+                errorKind: text(event.error_kind),
+                latencyMs: number(event.latency_ms),
+            };
+        }
+        catch {
+            // A concurrently appended partial line or old malformed record is safely ignored.
+        }
+    }
+    return undefined;
+}
+function loadLatestSearchTrace() {
+    try {
+        const file = path.join(echoConfigDir(), "events.jsonl");
+        return latestSearchTraceFromEvents(fs.readFileSync(file, "utf8").split("\n").slice(-EVENTS_TAIL_LINES));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read-only, local HUD diagnostics. Credentials are used only in the Authorization header to
+ * EchoMem's authenticated account endpoint; this never sends transcripts, queries, or memories.
+ */
+export async function loadHudDiagnostics() {
+    const updatedAt = new Date().toISOString();
+    const lastSearch = loadLatestSearchTrace();
+    const token = new KeyStore().getToken();
+    if (!token) {
+        return { updatedAt, account: { state: "not_logged_in" }, accountRequest: {}, lastSearch };
+    }
+    const requestId = `hud-account-${randomUUID()}`;
+    const startedAt = Date.now();
+    try {
+        const response = await fetch(`${API_BASE}/api/extension/account/bootstrap`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "X-EchoMem-Request-Id": requestId,
+            },
+        });
+        const payload = await response.json().catch(() => ({}));
+        const telemetry = record(payload)?.telemetry;
+        const echoedRequestId = text(record(telemetry)?.requestId) ?? requestId;
+        const accountRequest = {
+            requestId: echoedRequestId,
+            httpStatus: response.status,
+            elapsedMs: Date.now() - startedAt,
+        };
+        if (!response.ok) {
+            return {
+                updatedAt,
+                account: { state: "error", error: `Account check returned HTTP ${response.status}` },
+                accountRequest,
+                lastSearch,
+            };
+        }
+        return {
+            updatedAt,
+            account: { state: "connected", ...accountDiagnosticsFromBootstrap(payload) },
+            accountRequest,
+            lastSearch,
+        };
+    }
+    catch (error) {
+        return {
+            updatedAt,
+            account: { state: "error", error: briefError(error) },
+            accountRequest: { requestId, elapsedMs: Date.now() - startedAt },
+            lastSearch,
+        };
+    }
+}

package/dist/hud/server.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { HudMonitor } from "./monitor.js";
 import { HUD_HTML } from "./web.js";
 import { buildCapsuleText } from "./capsule.js";
+import { loadHudDiagnostics } from "./diagnostics.js";
 import { homePath, newestFile, walkFiles } from "./fs.js";
 import { KeyStore } from "../keystore.js";
 import { assembleCodex, assembleClaude } from "../migrate.js";
@@ -42,6 +43,24 @@ export async function createHudServer(opts = {}) {
             res.end(JSON.stringify(latest, null, 2));
             return;
         }
+        if (url.pathname === "/diagnostics") {
+            loadHudDiagnostics().then((diagnostics) => {
+                if (res.writableEnded)
+                    return;
+                res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+                res.end(JSON.stringify(diagnostics));
+            }).catch(() => {
+                if (res.writableEnded)
+                    return;
+                res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+                res.end(JSON.stringify({
+                    updatedAt: new Date().toISOString(),
+                    account: { state: "error", error: "Diagnostics unavailable" },
+                    accountRequest: {},
+                }));
+            });
+            return;
+        }
         if (url.pathname === "/select") {
             const id = url.searchParams.get("id");
             monitor.pin(id && id !== "auto" ? id : null);

package/dist/hud/web.js

@@ -217,6 +217,32 @@ export const HUD_HTML = String.raw `<!doctype html>
         cursor: grab;
       }
       #hud.open .details { display: block; }
+      .diagnostics {
+        margin: 10px 0 0;
+        padding: 10px 11px;
+        border: 1px solid rgba(26, 58, 143, 0.18);
+        border-radius: 10px;
+        background: rgba(255, 255, 255, 0.72);
+      }
+      .diagnostics-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+      .diagnostics-title { font-size: 10px; font-weight: 820; letter-spacing: .02em; color: var(--blue); }
+      .diagnostics-refresh {
+        border: 0;
+        padding: 0;
+        background: transparent;
+        color: var(--faint);
+        font-family: inherit;
+        font-size: 10px;
+        font-weight: 730;
+        cursor: pointer;
+      }
+      .diagnostics-refresh:hover { color: var(--blue); }
+      .diagnostics-body { display: grid; gap: 5px; margin-top: 7px; }
+      .diagnostics-line { display: flex; align-items: baseline; justify-content: space-between; gap: 10px; font-size: 10px; line-height: 1.25; }
+      .diagnostics-k { flex: 0 0 auto; color: var(--faint); font-weight: 650; }
+      .diagnostics-v { min-width: 0; overflow: hidden; text-align: right; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-family: "JetBrains Mono", ui-monospace, monospace; font-size: 9.5px; font-weight: 650; }
+      .diagnostics-v.bad { color: var(--brick); }
+      .diagnostics-v.wrap { white-space: normal; overflow-wrap: anywhere; }
       /* The current session is the one object every number and action belongs to — one card. */
       .now-card {
         border: 1px solid rgba(26, 58, 143, 0.24);
@@ -690,6 +716,10 @@ export const HUD_HTML = String.raw `<!doctype html>
             </div>
           </div>
         </div>
+        <section class="diagnostics" aria-label="Memory access diagnostics">
+          <div class="diagnostics-head"><span class="diagnostics-title">Memory access</span><button class="diagnostics-refresh" id="diagnosticsrefresh" type="button">Refresh</button></div>
+          <div class="diagnostics-body" id="diagnosticsbody"><span class="diagnostics-v">Open this panel to check account status.</span></div>
+        </section>
         <div class="tabs" id="tabs"></div>
         <div class="meta-row"><span class="meta-line" id="metaline"></span><button class="switchbtn agent-switch" id="switchbtn" title="Switch agent" style="display:none" type="button"></button></div>
         <div class="path" id="path"></div>
@@ -730,6 +760,8 @@ export const HUD_HTML = String.raw `<!doctype html>
       const switchBtn = document.getElementById("switchbtn");
       const revealEl = document.getElementById("reveal");
       const missing = document.getElementById("missing");
+      const diagnosticsBody = document.getElementById("diagnosticsbody");
+      const diagnosticsRefresh = document.getElementById("diagnosticsrefresh");
       let prevTurnState = null;
       let lastCapsule = "";
       let renewResultSessionKey = "";
@@ -741,6 +773,8 @@ export const HUD_HTML = String.raw `<!doctype html>
       let renewStartMs = 0;
       let renewEta = null;
       let renewEstimateSeq = 0;
+      let diagnosticsLoaded = false;
+      let diagnosticsInFlight = false;
       const CHECKPOINT_CACHE_KEY = "echomemHudCheckpointCacheV2";
       const CHECKPOINT_CACHE_LIMIT = 24;
       const CHECKPOINT_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
@@ -753,6 +787,85 @@ export const HUD_HTML = String.raw `<!doctype html>
       // viewing", so the user can always point the HUD at the right session. Flip false to show the viewer.
       const DEMO_CLEAN = true;
 
+      function diagnosticsLine(label, value, bad, wrap) {
+        return '<span class="diagnostics-line"><span class="diagnostics-k">' + esc(label) + '</span><span class="diagnostics-v' + (bad ? ' bad' : '') + (wrap ? ' wrap' : '') + '">' + esc(value) + '</span></span>';
+      }
+
+      function requestLabel(requestId) {
+        return requestId ? requestId : "not available";
+      }
+
+      function planLabel(plan) {
+        if (!plan) return "connected";
+        return plan.slice(0, 1).toUpperCase() + plan.slice(1);
+      }
+
+      function renderDiagnostics(data) {
+        if (!diagnosticsBody) return;
+        const account = (data && data.account) || {};
+        const accountRequest = (data && data.accountRequest) || {};
+        const lines = [];
+        if (account.state === "connected") {
+          lines.push(diagnosticsLine("account", planLabel(account.plan) + " · authenticated"));
+          if (typeof account.searchesThisMonth === "number" && typeof account.deepSearchPerMonth === "number") {
+            const limit = account.deepSearchPerMonth < 0 ? "Unlimited" : String(account.deepSearchPerMonth);
+            const remaining = account.searchesRemaining === null ? "" : (typeof account.searchesRemaining === "number" ? " · " + account.searchesRemaining + " left" : "");
+            lines.push(diagnosticsLine("searches", account.searchesThisMonth + " / " + limit + " UTC month" + remaining));
+          } else {
+            lines.push(diagnosticsLine("searches", "month-to-date not reported"));
+          }
+        } else if (account.state === "not_logged_in") {
+          lines.push(diagnosticsLine("account", "not logged in", true));
+        } else {
+          lines.push(diagnosticsLine("account", account.error || "unavailable", true));
+        }
+        const accountStatus = typeof accountRequest.httpStatus === "number"
+          ? "HTTP " + accountRequest.httpStatus + (typeof accountRequest.elapsedMs === "number" ? " · " + accountRequest.elapsedMs + "ms" : "")
+          : "not sent";
+        lines.push(diagnosticsLine("account check", accountStatus, account.state === "error"));
+        if (accountRequest.requestId) lines.push(diagnosticsLine("account request", requestLabel(accountRequest.requestId), false, true));
+
+        const last = data && data.lastSearch;
+        if (!last) {
+          lines.push(diagnosticsLine("last search", "no local trace yet"));
+        } else {
+          const outcome = last.ok === false ? "failed" : last.ok === true ? "succeeded" : "recorded";
+          const status = typeof last.httpStatus === "number" ? "HTTP " + last.httpStatus : outcome;
+          const errorLabel = last.errorCode || (last.errorKind && last.errorKind !== "none" ? last.errorKind : "");
+          const detail = [status, errorLabel].filter(Boolean).join(" · ");
+          lines.push(diagnosticsLine("last search", detail || outcome, last.ok === false));
+          if (last.requestId) lines.push(diagnosticsLine("search request", requestLabel(last.requestId), last.ok === false, true));
+        }
+        diagnosticsBody.innerHTML = lines.join("");
+        diagnosticsLoaded = true;
+        syncHeight();
+      }
+
+      async function refreshDiagnostics() {
+        if (!diagnosticsBody || diagnosticsInFlight) return;
+        diagnosticsInFlight = true;
+        diagnosticsBody.innerHTML = diagnosticsLine("memory access", "checking…");
+        if (diagnosticsRefresh) diagnosticsRefresh.disabled = true;
+        try {
+          const response = await fetch("/diagnostics");
+          renderDiagnostics(await response.json());
+        } catch (_) {
+          renderDiagnostics({ account: { state: "error", error: "local diagnostic fetch failed" }, accountRequest: {} });
+        } finally {
+          diagnosticsInFlight = false;
+          if (diagnosticsRefresh) diagnosticsRefresh.disabled = false;
+        }
+      }
+
+      function maybeLoadDiagnostics() {
+        if (!diagnosticsLoaded && !diagnosticsInFlight) refreshDiagnostics();
+      }
+
+      if (diagnosticsRefresh) diagnosticsRefresh.addEventListener("click", (event) => {
+        event.stopPropagation();
+        refreshDiagnostics();
+      });
+
       // Mini mode: resting state is a small pill; opening the panel shows the full layout, closing
       // returns to the pill. Preference persists (localStorage here, window size in main's bounds file).
       const miniBtn = document.getElementById("minibtn");
@@ -889,6 +1002,7 @@ export const HUD_HTML = String.raw `<!doctype html>
         }
         if (event.target instanceof HTMLElement && (event.target.closest(".switchbtn") || event.target.closest(".cornerbtn"))) return;
         hud.classList.toggle("open");
+        if (hud.classList.contains("open")) maybeLoadDiagnostics();
         syncHeight();
       });
 

package/dist/index.js

@@ -105,6 +105,11 @@ function readNumber(record, key) {
     const value = record[key];
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+function errorCodeFrom(value) {
+    if (!isRecord(value))
+        return undefined;
+    return readString(value, "code") || readString(value, "errorCode");
+}
 function compactOneLine(value, maxLength) {
     if (!value)
         return undefined;
@@ -569,30 +574,59 @@ class EchoMemApiClient {
             throw error;
         }
     }
-    async searchMemoriesRaw(query, opts, enc, retrievalOnly = false) {
-        const response = await this.axios.post("/api/extension/memories/search", {
-            query,
-            k: opts.limit,
-            similarityThreshold: opts.threshold,
-            timeFrameDays: opts.timeFrameDays,
-            requestId: opts.requestId,
-            sessionId: this.sessionId,
-        });
+    async searchMemoriesRaw(query, opts, enc, retrievalOnly = false, trace) {
+        const endpoint = "/api/extension/memories/search";
+        let response;
+        try {
+            response = await this.axios.post(endpoint, {
+                query,
+                k: opts.limit,
+                similarityThreshold: opts.threshold,
+                timeFrameDays: opts.timeFrameDays,
+                requestId: opts.requestId,
+                sessionId: this.sessionId,
+            });
+            trace?.({ requestId: opts.requestId, endpoint, httpStatus: response.status });
+        }
+        catch (error) {
+            trace?.({
+                requestId: opts.requestId,
+                endpoint,
+                httpStatus: axios.isAxiosError(error) ? error.response?.status : undefined,
+                errorCode: axios.isAxiosError(error) ? errorCodeFrom(error.response?.data) : undefined,
+            });
+            throw error;
+        }
         const data = enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
         return retrievalOnly && isRecord(data)
             ? { ...data, retrievalOnly: true, tuned: false }
             : data;
     }
-    async searchMemoriesRetrieved(query, opts, enc) {
-        const response = await this.axios.post("/api/extension/memories/deep-search/candidates", {
-            query,
-            requestId: opts.requestId,
-            logicalRequestId: opts.requestId,
-            sessionId: this.sessionId,
-            userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
-        });
+    async searchMemoriesRetrieved(query, opts, enc, trace) {
+        const endpoint = "/api/extension/memories/deep-search/candidates";
+        let response;
+        try {
+            response = await this.axios.post(endpoint, {
+                query,
+                requestId: opts.requestId,
+                logicalRequestId: opts.requestId,
+                sessionId: this.sessionId,
+                userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+            });
+            trace?.({ requestId: opts.requestId, endpoint, httpStatus: response.status });
+        }
+        catch (error) {
+            trace?.({
+                requestId: opts.requestId,
+                endpoint,
+                httpStatus: axios.isAxiosError(error) ? error.response?.status : undefined,
+                errorCode: axios.isAxiosError(error) ? errorCodeFrom(error.response?.data) : undefined,
+            });
+            throw error;
+        }
         const data = response.data ?? {};
         if (data.success === false) {
+            trace?.({ requestId: opts.requestId, endpoint, httpStatus: response.status, errorCode: errorCodeFrom(data) });
             throw new Error(`deep-search candidates proxy error: ${data.error || "unknown"}`);
         }
         const rawCandidates = Array.isArray(data.personalCandidates) ? data.personalCandidates : [];
@@ -648,16 +682,31 @@ class EchoMemApiClient {
     // never hits dg-web directly, so no new auth is needed and no other caller is
     // disrupted. NOTE: encrypted users still get server-side plaintext only; the
     // phase-1 + bridge-local-decrypt + phase-2 flow (spec §11) is the remaining work.
-    async searchMemoriesTuned(query, requestId) {
-        const response = await this.axios.post("/api/extension/memories/deep-search", {
-            query,
-            requestId,
-            logicalRequestId: requestId,
-            sessionId: this.sessionId,
-            userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
-        });
+    async searchMemoriesTuned(query, requestId, trace) {
+        const endpoint = "/api/extension/memories/deep-search";
+        let response;
+        try {
+            response = await this.axios.post(endpoint, {
+                query,
+                requestId,
+                logicalRequestId: requestId,
+                sessionId: this.sessionId,
+                userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+            });
+            trace?.({ requestId, endpoint, httpStatus: response.status });
+        }
+        catch (error) {
+            trace?.({
+                requestId,
+                endpoint,
+                httpStatus: axios.isAxiosError(error) ? error.response?.status : undefined,
+                errorCode: axios.isAxiosError(error) ? errorCodeFrom(error.response?.data) : undefined,
+            });
+            throw error;
+        }
         const data = response.data ?? {};
         if (data.success === false) {
+            trace?.({ requestId, endpoint, httpStatus: response.status, errorCode: errorCodeFrom(data) });
             throw new Error(`deep-search proxy error: ${data.error || "unknown"}`);
         }
         const primary = (data.retrievedMemorySnapshot?.primary ?? []);
@@ -669,7 +718,7 @@ class EchoMemApiClient {
         }));
         return { success: true, tuned: true, answer: String(data.answer || data.response || "").trim(), memories };
     }
-    async searchMemories(args) {
+    async searchMemories(args, trace) {
         const parsed = searchMemoriesSchema.parse(args ?? {});
         const query = parsed.query?.trim();
         const limit = parsed.limit ?? parsed.k ?? 10;
@@ -695,17 +744,17 @@ class EchoMemApiClient {
             requestId: randomUUID(),
         };
         if (!parsed.includeAnswer) {
-            return this.searchMemoriesRetrieved(query, searchOpts, enc);
+            return this.searchMemoriesRetrieved(query, searchOpts, enc, trace);
         }
         // Encrypted account: the server can't synthesize over plaintext it doesn't hold, so use the raw
         // retriever (returns ciphertext) and decrypt locally — zero-knowledge preserved end-to-end.
         if (enc.enabled) {
-            return await this.searchMemoriesRaw(query, searchOpts, enc);
+            return await this.searchMemoriesRaw(query, searchOpts, enc, false, trace);
         }
         // A synthesized answer is metered through the legacy route. Do not fall
         // back to raw retrieval after a ledger outage: that would return a result
         // without a durable usage fact.
-        return this.searchMemoriesTuned(query, searchOpts.requestId);
+        return this.searchMemoriesTuned(query, searchOpts.requestId, trace);
     }
     /** Decrypt the model-visible fields on a `{ memories: [...] }` response locally. */
     async decryptResult(data, key) {
@@ -1129,6 +1178,13 @@ class EchoMemMCPServer {
                         map_injected: rec.map_injected,
                         encrypted_user: rec.encrypted,
                         extracted_memory_count: rec.memories_extracted,
+                        // Preserve only the safe correlation fields needed to join a
+                        // bridge-local failure to the central operational trace. Query
+                        // text and upstream bodies never leave the local event stream.
+                        request_id: rec.request_id,
+                        endpoint: rec.endpoint,
+                        http_status: rec.http_status,
+                        error_code: rec.error_code ?? (rec.error_kind === "none" ? undefined : rec.error_kind),
                     };
                     void this.client.trackMcpAnalyticsEvent(rec.ok ? "[MCP] EchoMem Tool Succeeded" : "[MCP] EchoMem Tool Failed", finalAnalytics, `${analyticsCallId}:generic-completed`);
                     void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, rec.ok ? "Succeeded" : "Failed"), finalAnalytics, `${analyticsCallId}:completed`);
@@ -1142,7 +1198,14 @@ class EchoMemMCPServer {
             rec.query_len = query.length;
             rec.query_hash = hashText(query);
         }
-        const result = await this.client.searchMemories(args);
+        const result = await this.client.searchMemories(args, (trace) => {
+            if (!rec)
+                return;
+            rec.request_id = trace.requestId;
+            rec.endpoint = trace.endpoint;
+            rec.http_status = trace.httpStatus;
+            rec.error_code = trace.errorCode;
+        });
         if (rec) {
             // "Which memories were used": topic keys + delivered context size, for the comparison dataset.
             const mems = Array.isArray(result?.memories) ? result.memories : [];
@@ -1249,7 +1312,7 @@ Details: ${m.details || "N/A"}`)
                 typeof capsuleId === "string" && capsuleId ? `Capsule ID: ${capsuleId}` : "",
                 typeof contextId === "string" && contextId ? `Context: ${contextId}` : "",
                 "",
-                `To reload this capsule in a fresh session: get_memories_by_context({ contextId: "${contextId}" })`,
+                `To reload this capsule in a fresh session with Pro/Power recall: get_memories_by_context({ contextId: "${contextId}" })`,
             ].filter(Boolean).join("\n");
             return { content: [{ type: "text", text }] };
         }
@@ -1273,7 +1336,7 @@ Details: ${m.details || "N/A"}`)
             `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.`,
             list,
             saved.length
-                ? `Verify these captured the key facts. To re-fetch this exact batch later, search by the ids above${typeof contextId === "string" && contextId ? ` (context ${contextId})` : ""}.`
+                ? `Verify these captured the key facts. With Pro/Power recall, re-fetch this exact batch later by searching the ids above${typeof contextId === "string" && contextId ? ` (context ${contextId})` : ""}.`
                 : "",
         ].filter(Boolean).join("\n\n");
         return { content: [{ type: "text", text }] };

package/dist/setup-page/client-core.js

@@ -21,6 +21,8 @@ export const SETUP_PAGE_CLIENT_CORE = String.raw `      var params = new URLSear
       var reportMounted = false;    // report shell (city iframe) mounted once; loading is an overlay on it, not a separate page
       var authUrl = "";
       var workspacePath = "";
+      var billingStatus = null;
+      var recallGateSkipped = false;
       var authWindow = null;
       var connectionPollStarted = false;
       var statsPollStarted = false;

package/dist/setup-page/client-extraction.js

@@ -342,7 +342,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
                       '<div class="resultNumber"><strong>' + esc(number(extracted)) + '</strong><span>' + esc(memoryNoun) + '</span></div>') +
                 '</div>' +
               '</div>' +
-              (done ? tryItCard() : "") +
+              (done ? recallGateBlock() : "") +
               (done ? "" :
                 '<div class="memoryReceipt">' +
                   '<p class="receiptK">What just happened</p>' +
@@ -353,7 +353,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
                 '</div>') +
             '</div>' +
             (done ? hudTip() + doneCloseNote() : "");
-          wireTryButtons();
+          wireRecallGate();
           return;
         }
         setHead(preparing ? "Preparing" : "Extracting", preparing ? "Preparing" : "Extracting");
@@ -447,6 +447,82 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           setLaunchStatus(msg);
         }
       }
+      function paidRecallPlan(plan) {
+        return ["pro", "power", "team", "enterprise"].indexOf(String(plan || "").toLowerCase()) >= 0;
+      }
+      function recallPricingUrl() {
+        return (billingStatus && billingStatus.pricingUrl)
+          || "https://echoknows.com/pricing?source=mcp_onboarding";
+      }
+      function recallGateUnlocked() {
+        return recallGateSkipped || paidRecallPlan(billingStatus && billingStatus.plan);
+      }
+      function recallGateBlock() {
+        var unlocked = recallGateUnlocked();
+        return '<div class="recallGateBlock">' +
+          '<section class="recallGate' + (unlocked ? " is-hidden" : "") + '" id="recallGate">' +
+            '<p class="recallEyebrow">Memory saved. Recall is next.</p>' +
+            '<h3>Choose your 14-day trial plan for Codex and Claude recall.</h3>' +
+            '<p>Saving conversations and extracting memory stay included. Compare Pro and Power, then choose the plan that should unlock <code>search_memories</code>, project recall, and the prompt below.</p>' +
+            '<div class="recallGateActions">' +
+              '<button type="button" class="primary" id="recallStartTrial">Compare plans</button>' +
+              '<button type="button" class="secondary" id="recallSkip">Skip for now</button>' +
+            '</div>' +
+            '<p class="recallFine">Card required for trial. Cancel anytime.</p>' +
+            '<p class="launchStatus" id="recallGateStatus"></p>' +
+          '</section>' +
+          '<div id="recallTryWrap" class="recallTryWrap' + (unlocked ? "" : " is-hidden") + '">' +
+            '<p id="recallSkipNote" class="recallSkipNote' + (recallGateSkipped ? "" : " is-hidden") + '">Saving will keep working. Search and recall require Pro or Power when this prompt calls <code>search_memories</code>.</p>' +
+            tryItCard() +
+          '</div>' +
+        '</div>';
+      }
+      function setRecallGateStatus(message) {
+        var node = document.getElementById("recallGateStatus");
+        if (node) node.textContent = message || "";
+      }
+      function applyRecallGate() {
+        var gate = document.getElementById("recallGate");
+        var wrap = document.getElementById("recallTryWrap");
+        var skipNote = document.getElementById("recallSkipNote");
+        var unlocked = recallGateUnlocked();
+        if (gate) gate.classList.toggle("is-hidden", unlocked);
+        if (wrap) wrap.classList.toggle("is-hidden", !unlocked);
+        if (skipNote) skipNote.classList.toggle("is-hidden", !recallGateSkipped);
+      }
+      async function refreshBillingStatus() {
+        try {
+          billingStatus = await getJson("/billing-status");
+          applyRecallGate();
+          if (!recallGateUnlocked() && billingStatus && billingStatus.plan === "unknown") {
+            setRecallGateStatus("Could not check your plan. You can start the trial or skip and keep setup going.");
+          }
+        } catch (_) {
+          setRecallGateStatus("Could not check your plan. You can start the trial or skip and keep setup going.");
+        }
+      }
+      function openRecallPricing() {
+        var url = recallPricingUrl();
+        setRecallGateStatus("Opening pricing in a new tab...");
+        try {
+          var opened = window.open(url, "_blank", "noopener,noreferrer");
+          if (!opened) setRecallGateStatus("Your browser blocked the pricing tab. Allow pop-ups for this page, then click Compare plans again.");
+        } catch (_) {
+          setRecallGateStatus("Could not open a new tab. Allow pop-ups for this page, then click Compare plans again.");
+        }
+      }
+      function skipRecallGate() {
+        recallGateSkipped = true;
+        applyRecallGate();
+      }
+      function wireRecallGate() {
+        var trialBtn = document.getElementById("recallStartTrial");
+        if (trialBtn) trialBtn.addEventListener("click", openRecallPricing);
+        var skipBtn = document.getElementById("recallSkip");
+        if (skipBtn) skipBtn.addEventListener("click", skipRecallGate);
+        wireTryButtons();
+        void refreshBillingStatus();
+      }
       function tryItCard() {
         var prompt = recallPrompt();
         return '<div class="tryCard">' +
@@ -500,10 +576,10 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
             '<span class="seal">Skipped for now</span>' +
             '<h2>You can come back anytime.</h2>' +
             '<p>Echo saved what already finished. When you are ready, run <code>echomem-mcp init</code> again — it picks up right where it left off.</p>' +
-            tryItCard() +
+            recallGateBlock() +
             hudTip() +
           '</div>';
-        wireTryButtons();
+        wireRecallGate();
       }
       async function endExtraction() {
         if (extractionEnded) return;

package/dist/setup-page/client-lifecycle.js

@@ -1,5 +1,71 @@
 // Generated by splitting the previous inline setup page. Keep this source readable: it is emitted into one browser IIFE.
 export const SETUP_PAGE_CLIENT_LIFECYCLE = String.raw `      /* ---------- scan-first poll for the forensic report ---------- */
+      function renderLocalScanConsent() {
+        setScanMode(false);
+        setCityMode(false);
+        setExtractMode(false);
+        setReadyMode(false);
+        setHead("Local file access", "Consent");
+        app.className = "consentStage";
+        app.innerHTML =
+          '<section class="localConsent">' +
+            '<p class="consentEyebrow">Local visualization</p>' +
+            '<h2>Let Echo scan locally to build your Agent Doctor view?</h2>' +
+            '<p>Echo reads local Codex and Claude Code history on this machine only, then turns it into a private usage visualization. Nothing from this scan leaves your device.</p>' +
+            '<div class="consentActions">' +
+              '<button type="button" class="primary" id="allowLocalScan">Continue with local scan</button>' +
+              '<button type="button" class="textButton" id="declineLocalScan">Skip the insight for now</button>' +
+            '</div>' +
+            '<p class="consentFine" id="consentStatus"></p>' +
+          '</section>';
+        var allow = document.getElementById("allowLocalScan");
+        if (allow) allow.onclick = allowLocalScan;
+        var decline = document.getElementById("declineLocalScan");
+        if (decline) decline.onclick = declineLocalScan;
+      }
+      function setConsentStatus(message) {
+        var node = document.getElementById("consentStatus");
+        if (node) node.textContent = message || "";
+      }
+      async function allowLocalScan() {
+        setConsentStatus("Starting local scan...");
+        try {
+          await postJson("/report-consent", { allowed: true });
+          await showReport();
+        } catch (error) {
+          renderReportIssue("CONSENT_SAVE_FAILED", error && error.message ? error.message : "Could not start the local scan.");
+        }
+      }
+      async function declineLocalScan() {
+        setConsentStatus("Skipping Agent Doctor...");
+        try {
+          await postJson("/report-consent", { allowed: false });
+        } catch (_) {}
+        renderLocalScanSkipped();
+      }
+      function renderLocalScanSkipped() {
+        setScanMode(false);
+        setCityMode(false);
+        setExtractMode(false);
+        setReadyMode(true);
+        setHead("Agent Doctor skipped", connected ? "Signed in" : "Optional");
+        app.className = "consentStage";
+        app.innerHTML =
+          '<section class="localConsent">' +
+            '<p class="consentEyebrow">Visualization skipped</p>' +
+            '<h2>No problem. Echo can still set up memory.</h2>' +
+            '<p>We will skip Agent Doctor and continue with EchoMem setup.</p>' +
+            '<div class="consentActions">' +
+              '<button type="button" class="primary" data-connect-echo>' + (connected ? "Continue setup" : "Connect EchoMem") + '</button>' +
+              '<button type="button" class="textButton" id="changeConsent">Go back</button>' +
+            '</div>' +
+            '<p class="consentFine" data-signin-help></p>' +
+            '<a class="button secondary hidden" data-signin-fallback target="_blank" rel="noopener noreferrer">Open sign-in</a>' +
+          '</section>';
+        bindConnect();
+        var change = document.getElementById("changeConsent");
+        if (change) change.onclick = renderLocalScanConsent;
+      }
       async function showReport() {
         if (reportPollStarted) return;
         reportPollStarted = true;
@@ -103,14 +169,14 @@ export const SETUP_PAGE_CLIENT_LIFECYCLE = String.raw `      /* ---------- scan-
           }
           return;
         }
-        // Learn the auth URL + connection state, but don't block the local scan on it.
-        getJson("/config").then(function (cfg) {
+        // Learn the auth URL + connection state before asking for optional local file access.
+        try {
+          var cfg = await getJson("/config");
           authUrl = cfg.authUrl || authUrl;
           connected = !!cfg.connected;
           workspacePath = cfg.workspacePath || workspacePath;
-        }).catch(function () {});
-        // Scan-first: show the local forensic report before asking the user to connect.
-        await showReport();
+        } catch (_) {}
+        renderLocalScanConsent();
       }
       __ECHO_SETUP_STARTUP__;
 `;

package/dist/setup-page/document.js

@@ -11,7 +11,7 @@ const SETUP_PAGE_BODY = String.raw `
       </div>
       <div class="pill" id="status">Local</div>
     </header>
-    <section id="app" class="state">Starting local scan...</section>
+    <section id="app" class="state">Preparing setup...</section>
   </main>
   <dialog id="echo-note" class="echo-note-dlg">
     <button class="nclose" aria-label="Close">&times;</button>

package/dist/setup-page/styles-extraction.js

@@ -59,7 +59,73 @@ export const SETUP_PAGE_STYLES_EXTRACTION = String.raw `    /* ---- dashboard (p
     }
     .primary { background: var(--echo-ink-primary); color: #fff; }
     .secondary { background: #fff; color: var(--echo-ink-primary); }
+    .textButton {
+      min-height: 36px;
+      border-color: transparent;
+      background: transparent;
+      color: var(--echo-ink-faint);
+      padding: 0 8px;
+      font-size: 13px;
+      font-weight: 700;
+    }
+    .textButton:hover { color: var(--echo-ink-primary); background: transparent; }
     button:disabled { cursor: not-allowed; opacity: 0.55; }
+    .consentStage {
+      display: grid;
+      place-items: center;
+      min-height: min(620px, calc(100vh - 180px));
+    }
+    .localConsent {
+      width: min(680px, 100%);
+      border: 2px solid var(--echo-ink-primary);
+      border-radius: 8px;
+      background: var(--echo-paper-white);
+      padding: clamp(22px, 4vw, 34px);
+      box-shadow: 0 18px 38px -28px rgba(26,58,143,0.45);
+    }
+    .consentEyebrow {
+      margin: 0 0 10px;
+      font-family: var(--echo-font-mono);
+      font-size: 11px;
+      font-weight: 800;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--echo-ink-primary);
+    }
+    .localConsent h2 {
+      max-width: 620px;
+      margin: 0;
+      font-size: clamp(30px, 3.4vw, 42px);
+      line-height: 1.04;
+      color: var(--echo-ink-primary);
+    }
+    .localConsent > p:not(.consentEyebrow):not(.consentFine) {
+      max-width: 590px;
+      margin: 14px 0 0;
+      font-size: 16px;
+      line-height: 1.55;
+      color: var(--echo-ink-mute);
+    }
+    .consentActions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      align-items: center;
+      margin-top: 22px;
+    }
+    .consentActions button {
+      min-height: 48px;
+      padding: 0 18px;
+    }
+    .consentFine {
+      min-height: 18px;
+      margin: 10px 0 0;
+      font-family: var(--echo-font-mono);
+      font-size: 11px;
+      line-height: 1.45;
+      color: var(--echo-ink-faint);
+    }
+    .consentFine:empty { display: none; }
     .track { height: 12px; overflow: hidden; border-radius: 999px; background: #e8e8e1; margin: 16px 0 10px; }
     .fill { height: 100%; width: 0%; background: var(--echo-ink-primary); transition: width 180ms ease; }
     /* indeterminate "we're working on it" bar for the prep phase (before job counts move) */
@@ -93,6 +159,7 @@ export const SETUP_PAGE_STYLES_EXTRACTION = String.raw `    /* ---- dashboard (p
       .explainCopy h2 { font-size: 38px; }
       .explainCta .promiseActions { width: 100%; }
       .explainCta .primary, .explainCta .secondary { width: 100%; }
+      .consentActions .primary { width: 100%; }
       .cityHero { min-height: auto; }
       .cityShell {
         width: 100vw;
@@ -615,6 +682,81 @@ export const SETUP_PAGE_STYLES_EXTRACTION = String.raw `    /* ---- dashboard (p
     .exCountdown strong { color: var(--echo-ink-primary); font-weight: 700; }
     .exOverdue { margin: 0; max-width: 620px; border: 1px solid rgba(196, 148, 42, 0.45); background: rgba(233, 185, 73, 0.12); border-radius: 8px; padding: 12px 14px; font-size: 13px; line-height: 1.5; color: var(--echo-ink-text); }
     .exOverdue strong { display: block; margin-bottom: 4px; color: var(--echo-ink-primary); }
+    .is-hidden { display: none !important; }
+    .recallGateBlock { width: min(760px, 100%); margin: 2px auto 0; }
+    .recallGate {
+      width: 100%;
+      border: 2px solid var(--echo-ink-primary);
+      border-radius: 8px;
+      background: var(--echo-paper-white);
+      padding: clamp(18px, 3vw, 26px);
+      box-shadow: 0 18px 38px -28px rgba(26,58,143,0.45);
+      text-align: left;
+    }
+    .recallEyebrow {
+      margin: 0 0 10px;
+      font-family: var(--echo-font-mono);
+      font-size: 11px;
+      font-weight: 800;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--echo-ink-primary);
+    }
+    .recallGate h3 {
+      margin: 0;
+      max-width: 680px;
+      font-family: var(--echo-font-brand);
+      font-size: clamp(30px, 3.8vw, 48px);
+      line-height: 0.98;
+      font-weight: 900;
+      color: var(--echo-ink-primary);
+      letter-spacing: 0;
+    }
+    .recallGate p {
+      max-width: 620px;
+      margin: 14px 0 0;
+      font-size: 15px;
+      line-height: 1.55;
+      color: var(--echo-ink-mute);
+    }
+    .recallGate code,
+    .recallSkipNote code {
+      font-family: var(--echo-font-mono);
+      font-size: 0.92em;
+      background: var(--echo-paper-soft);
+      border: 1px solid var(--echo-line-soft);
+      border-radius: 5px;
+      padding: 1px 5px;
+      color: var(--echo-ink-primary);
+    }
+    .recallGateActions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      align-items: center;
+      margin-top: 22px;
+    }
+    .recallGateActions button {
+      min-height: 48px;
+      padding: 0 18px;
+    }
+    .recallGate .recallFine {
+      margin-top: 10px;
+      font-family: var(--echo-font-mono);
+      font-size: 11px;
+      color: var(--echo-ink-faint);
+    }
+    .recallTryWrap { width: 100%; }
+    .recallSkipNote {
+      margin: 0 0 12px;
+      border: 1px solid var(--echo-line-soft);
+      border-radius: 8px;
+      background: rgba(246,244,238,0.86);
+      padding: 10px 12px;
+      font-size: 13px;
+      line-height: 1.45;
+      color: var(--echo-ink-mute);
+    }
     .tryCard { margin-top: 2px; max-width: 760px; border: 2px solid var(--echo-ink-primary); border-radius: 8px; background: var(--echo-paper-white); padding: clamp(18px, 3vw, 26px); box-shadow: 0 18px 38px -28px rgba(26,58,143,0.45); }
     .tryCard .tryK { margin: 0 0 10px; font-family: var(--echo-font-mono); font-size: 12px; font-weight: 800; letter-spacing: 0.08em; text-transform: uppercase; color: var(--echo-ink-primary); }
     .tryCard .tryTitle {

package/dist/setup.js

@@ -38,6 +38,7 @@ import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "
 // device unless the user explicitly starts migration. Override the hosted auth origin with ECHO_WEB_URL.
 const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+const PRICING_URL = (process.env.ECHO_PRICING_URL || "https://echoknows.com/pricing").replace(/\/$/, "");
 function home(...p) {
     return path.join(os.homedir(), ...p);
 }
@@ -1250,6 +1251,29 @@ export function startCallbackServer(opts = {}) {
                     json(res, 200, payload);
                     return;
                 }
+                if (route === "/billing-status" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    const token = new KeyStore().getToken();
+                    const pricingUrl = `${PRICING_URL}?source=mcp_onboarding`;
+                    if (!token) {
+                        json(res, 200, { plan: "free", paid: false, pricingUrl });
+                        return;
+                    }
+                    try {
+                        const response = await authedAxios(token).get("/api/extension/account/bootstrap", { timeout: 6000 });
+                        const plan = (asString(response.data?.plan) || "free").toLowerCase();
+                        json(res, 200, {
+                            plan,
+                            paid: ["pro", "power", "team", "enterprise"].includes(plan),
+                            pricingUrl,
+                        });
+                    }
+                    catch {
+                        json(res, 200, { plan: "unknown", paid: false, pricingUrl });
+                    }
+                    return;
+                }
                 if (route === "/report" && req.method === "GET") {
                     // Local forensic "Context Doctor" report — computed locally, served BEFORE auth (scan-first).
                     res.setHeader("Cache-Control", "no-store");
@@ -1353,6 +1377,22 @@ export function startCallbackServer(opts = {}) {
                     json(res, 200, progress);
                     return;
                 }
+                if (route === "/report-consent" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    if (!checkNonce(asString(body.nonce)))
+                        return void text(res, 403, "bad nonce");
+                    const allowed = body.allowed === true;
+                    opts.onReportConsent?.(allowed);
+                    json(res, 200, { ok: true, allowed });
+                    return;
+                }
                 if (route === "/logout" && req.method === "POST") {
                     let body;
                     try {
@@ -1780,6 +1820,8 @@ async function cmdLogin(flags) {
     const nonce = devNonce || randomUUID();
     let stats = null;
     let forensicReport = null;
+    let forensicConsent = "pending";
+    let forensicScanStarted = false;
     const forensicStartedAt = Date.now();
     let forensicStageStartedAt = forensicStartedAt;
     let forensicStage = "starting";
@@ -1799,6 +1841,28 @@ async function cmdLogin(flags) {
         getStats: () => stats,
         getReport: () => forensicReport,
         getReportProgress: () => forensicProgress,
+        onReportConsent: (allowed) => {
+            if (!allowed) {
+                forensicConsent = "declined";
+                forensicProgress = {
+                    status: "failed",
+                    scanned: 0,
+                    total: 0,
+                    stage: "failed",
+                    label: "Local scan skipped",
+                    elapsedMs: Date.now() - forensicStartedAt,
+                    stageElapsedMs: Date.now() - forensicStageStartedAt,
+                    updatedAt: Date.now(),
+                    error: {
+                        code: "REPORT_SCAN_DECLINED",
+                        message: "Local file analysis was skipped. EchoMem can still connect, save conversations, and import memories.",
+                    },
+                };
+                return;
+            }
+            forensicConsent = "allowed";
+            startForensicScan();
+        },
     });
     const callbackUrl = `http://127.0.0.1:${srv.port}/callback`;
     const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
@@ -1812,46 +1876,50 @@ async function cmdLogin(flags) {
     openBrowser(localSetupUrl);
     console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
     console.log("Waiting for browser approval for up to 15 minutes…");
-    // Scan-first: build the local forensic "Context Doctor" report off-thread so the page shows it
-    // BEFORE the user connects an account (the scan is local-only; nothing leaves the machine).
-    buildForensicReportOffThread((progress) => {
-        const now = Date.now();
-        const nextStage = progress.stage || forensicStage;
-        if (nextStage !== forensicStage) {
-            forensicStage = nextStage;
-            forensicStageStartedAt = now;
-            console.log(`Local scan: ${forensicStageLabel(forensicStage)}…`);
-        }
-        forensicProgress = {
-            status: "running",
-            scanned: progress.done,
-            total: progress.total,
-            stage: forensicStage,
-            label: forensicStageLabel(forensicStage),
-            detail: progress.detail,
-            elapsedMs: now - forensicStartedAt,
-            stageElapsedMs: now - forensicStageStartedAt,
-            updatedAt: now,
-        };
-    })
-        .then((r) => {
-        forensicReport = r;
-    })
-        .catch((e) => {
-        const now = Date.now();
-        forensicProgress = {
-            status: "failed",
-            scanned: forensicProgress.scanned,
-            total: forensicProgress.total,
-            stage: "failed",
-            label: "Local scan failed",
-            elapsedMs: now - forensicStartedAt,
-            stageElapsedMs: now - forensicStageStartedAt,
-            updatedAt: now,
-            error: safeForensicError(e),
-        };
-        console.error(`Could not build the local report: ${e instanceof Error ? e.message : String(e)}`);
-    });
+    const startForensicScan = () => {
+        if (forensicScanStarted || forensicConsent !== "allowed")
+            return;
+        forensicScanStarted = true;
+        // Build the local forensic "Context Doctor" report off-thread only after explicit consent.
+        buildForensicReportOffThread((progress) => {
+            const now = Date.now();
+            const nextStage = progress.stage || forensicStage;
+            if (nextStage !== forensicStage) {
+                forensicStage = nextStage;
+                forensicStageStartedAt = now;
+                console.log(`Local scan: ${forensicStageLabel(forensicStage)}…`);
+            }
+            forensicProgress = {
+                status: "running",
+                scanned: progress.done,
+                total: progress.total,
+                stage: forensicStage,
+                label: forensicStageLabel(forensicStage),
+                detail: progress.detail,
+                elapsedMs: now - forensicStartedAt,
+                stageElapsedMs: now - forensicStageStartedAt,
+                updatedAt: now,
+            };
+        })
+            .then((r) => {
+            forensicReport = r;
+        })
+            .catch((e) => {
+            const now = Date.now();
+            forensicProgress = {
+                status: "failed",
+                scanned: forensicProgress.scanned,
+                total: forensicProgress.total,
+                stage: "failed",
+                label: "Local scan failed",
+                elapsedMs: now - forensicStartedAt,
+                stageElapsedMs: now - forensicStageStartedAt,
+                updatedAt: now,
+                error: safeForensicError(e),
+            };
+            console.error(`Could not build the local report: ${e instanceof Error ? e.message : String(e)}`);
+        });
+    };
     let token;
     let key;
     try {

package/dist/v1-contract.js

@@ -108,6 +108,7 @@ export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
     const map = opts.map?.trim();
     const updateNotice = opts.updateNotice?.trim();
+    const paidRecallNote = "Requires Echo Pro or Power; saving conversations and memory extraction remain included.";
     const updateSection = updateNotice ? `\n\nUPDATE NOTICE: ${updateNotice}` : "";
     const mapSection = map
         ? `\n\nThis user's EchoMem currently covers these topics (a relevance guide — recall when the task relates to one of them):\n${map}\n`
@@ -115,7 +116,7 @@ export function listToolSpecs(opts = {}) {
     return [
         {
             name: canonicalToolNames.search,
-            description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled.${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
+            description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled. ${paidRecallNote}${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -138,7 +139,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: "search_memories_by_description_semantic",
-            description: "Legacy alias for search_memories.",
+            description: `Legacy alias for search_memories. ${paidRecallNote}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -161,7 +162,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: "Save this conversation into EchoMem as long-term memory (durable memories are extracted automatically). passthrough=true stores the text verbatim as a session capsule instead — reload it later via get_memories_by_context.",
+            description: "Save this conversation into EchoMem as long-term memory (durable memories are extracted automatically). Saving is included. passthrough=true stores the text verbatim as a session capsule; reloading/searching saved memories requires Echo Pro or Power.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -194,7 +195,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.timeRange,
-            description: `Retrieve memories within a specific date range. Current time: ${currentTime}.`,
+            description: `Retrieve memories within a specific date range. ${paidRecallNote} Current time: ${currentTime}.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -212,7 +213,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.keywords,
-            description: "Search memories based on keywords in keys field.",
+            description: `Search memories based on keywords in keys field. ${paidRecallNote}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -369,7 +370,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.getByContext,
-            description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. Current time: ${currentTime}.`),
+            description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. ${paidRecallNote} save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -386,7 +387,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
-            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. Use this when the user or EchoMem HUD gives you a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. Current time: ${currentTime}.`),
+            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${paidRecallNote} Use this when the user or EchoMem HUD gives you a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.14",
+  "version": "1.4.15",
   "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",