@echomem/mcp 1.4.33 → 1.4.35

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
+import { canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
@@ -18,6 +18,13 @@ import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, st
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
 const ECHO_PRICING_URL = process.env.ECHO_PRICING_URL || "https://echoknows.com/account";
 const ECHO_MEMORY_WEB_URL = (process.env.ECHO_MEMORY_WEB_URL || "https://echoknows.com/memory").replace(/\/$/, "");
+const DESKTOP_MANAGED = process.env.ECHO_DESKTOP_MANAGED === "1";
+const CONNECT_DEVICE_INSTRUCTION = DESKTOP_MANAGED
+    ? "Open Echo Desktop, sign in, and choose Connect MCP, then retry this action."
+    : "Run `echomem-mcp login` in a terminal to reconnect this device, then retry this action.";
+const UNLOCK_VAULT_INSTRUCTION = DESKTOP_MANAGED
+    ? "Open Echo Desktop and unlock the vault there. Keep the passphrase out of chat."
+    : "Open Terminal and run `echomem-mcp unlock` yourself. Do not have the agent run this interactive command and do not send your passphrase in chat.";
 function memoryWebUrl(memoryId) {
     return `${ECHO_MEMORY_WEB_URL}/${encodeURIComponent(memoryId)}`;
 }
@@ -156,7 +163,7 @@ function formatReconnectRequiredResult(error) {
         return null;
     return [
         "🔌 EchoMem's saved login is no longer accepted (Unauthorized, HTTP 401).",
-        "Action required from the user: run `echomem-mcp login` in a terminal to reconnect this device, then retry this action.",
+        `Action required from the user: ${CONNECT_DEVICE_INSTRUCTION}`,
         "No editor restart is needed. Keep all credentials out of chat.",
     ].join("\n");
 }
@@ -1013,7 +1020,12 @@ class EchoMemApiClient {
     async recordMemoryCitations(args) {
         const parsed = recordMemoryCitationsSchema.parse(args ?? {});
         try {
-            const response = await this.axios.post("/api/extension/social/memory-citations", { ...parsed, sessionKey: this.sessionId });
+            const response = await this.axios.post("/api/extension/social/memory-citations", 
+            // A citation receipt belongs to one planned answer, not to the lifetime of the MCP stdio
+            // process. Deriving the legacy API's sessionKey from the required per-answer receipt keeps
+            // retries idempotent while avoiding the same process-vs-conversation coupling that broke
+            // group sharing in long-lived Claude hosts.
+            { ...parsed, sessionKey: `answer:${parsed.receiptId}` });
             return response.data;
         }
         catch (error) {
@@ -1152,9 +1164,11 @@ class EchoMemMCPServer {
         });
         this.client = new EchoMemApiClient(store);
         this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
-        startBackgroundUpdateCheck((status) => {
-            this.updateStatus = status;
-        });
+        if (!DESKTOP_MANAGED) {
+            startBackgroundUpdateCheck((status) => {
+                this.updateStatus = status;
+            });
+        }
         this.setupToolHandlers();
         this.server.onerror = (error) => console.error("[MCP Error]", error);
         process.on("SIGINT", async () => {
@@ -1202,7 +1216,7 @@ class EchoMemMCPServer {
             ]);
             this.mapInjected = !!map;
             this.groupMapInjected = !!groupMap;
-            const updateNotice = formatUpdateNotice(this.updateStatus);
+            const updateNotice = DESKTOP_MANAGED ? undefined : formatUpdateNotice(this.updateStatus);
             return { tools: listToolSpecs({ map, groupMap, updateNotice }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1238,6 +1252,14 @@ class EchoMemMCPServer {
                     return { content: [{ type: "text", text: await buildReportText(false) }] };
                 }
                 if (canonicalName === canonicalToolNames.updateStatus) {
+                    if (DESKTOP_MANAGED) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Echo Desktop manages this MCP runtime (${MCP_PACKAGE_VERSION}). Install app updates from Echo Desktop, then start a new agent session.`,
+                                }],
+                        };
+                    }
                     const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
                     const status = await checkLatestUpdateStatus({ force });
                     this.updateStatus = status;
@@ -1320,6 +1342,8 @@ class EchoMemMCPServer {
                         return await this.handleGroupContext(request.params.arguments);
                     case canonicalToolNames.getGroupSessionSharing:
                         return await this.handleGetGroupSessionSharing(request.params.arguments);
+                    case canonicalToolNames.requestGroupSessionSharing:
+                        return await this.handleRequestGroupSessionSharing(request.params.arguments);
                     case canonicalToolNames.setGroupSessionSharing:
                         return await this.handleSetGroupSessionSharing(request.params.arguments);
                     case canonicalToolNames.createGroup:
@@ -1354,7 +1378,7 @@ class EchoMemMCPServer {
                         content: [
                             {
                                 type: "text",
-                                text: "🔌 EchoMem isn't connected yet. Run `echomem-mcp login` in a terminal to connect this device, then retry — no editor restart needed.",
+                                text: `🔌 EchoMem isn't connected yet. ${CONNECT_DEVICE_INSTRUCTION} No editor restart is needed.`,
                             },
                         ],
                     };
@@ -1368,8 +1392,10 @@ class EchoMemMCPServer {
                                 text: [
                                     "🔒 EchoMem vault is locked.",
                                     "This encrypted account has no usable local decryption key. Once unlocked, this trusted device stays unlocked until you explicitly lock it or log out.",
-                                    "Action required from the user: open Terminal and run `echomem-mcp unlock` yourself. Do not have the agent run this interactive command and do not send your passphrase in chat.",
-                                    "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                    `Action required from the user: ${UNLOCK_VAULT_INSTRUCTION}`,
+                                    ...(DESKTOP_MANAGED ? [] : [
+                                        "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                    ]),
                                     "After the success message, retry this EchoMem action in the current session — no editor restart is needed.",
                                 ].join("\n"),
                             },
@@ -1607,7 +1633,7 @@ Details: ${m.details || "N/A"}`)
                     syncedGroupNames.length
                         ? `Saved privately first and synced to approved groups: ${syncedGroupNames.join(", ")}.`
                         : "Saved to your private memory.",
-                    `This user has multiple groups: ${availableGroups.map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`).join(", ")}. Call get_group_session_sharing with this conversation scope and one groupId at a time; obtain a separate explicit Yes/No decision for each group.`,
+                    `This user has multiple groups: ${availableGroups.map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`).join(", ")}. Call request_group_session_sharing with this conversation scope and one groupId at a time so supported hosts render a separate sharing choice for each group.`,
                     failedSyncs.length
                         ? `${failedSyncs.length} approved group sync(s) failed; private memories were preserved.`
                         : "",
@@ -1616,7 +1642,7 @@ Details: ${m.details || "N/A"}`)
                         : "",
                 ].filter(Boolean).join(" ")
                 : sharing?.decision === null || sharing?.decision === undefined
-                    ? `Saved to your private memory. Ask: “Share memories saved from this conversation with ${readString(sharingGroup, "name") ?? "your current group"}?” Silence leaves the state unset, so ask again at a later qualifying checkpoint until the user explicitly answers Yes or No; do not repeat the prompt in the same response.`
+                    ? `Saved to your private memory. Call request_group_session_sharing with this conversation scope${readString(sharingGroup, "id") ? ` and groupId ${readString(sharingGroup, "id")}` : ""} so a supported host can show the sharing choice for ${readString(sharingGroup, "name") ?? "your current group"}. If the client cannot render it, relay that tool's fallback question. Decline, cancel, or silence leaves the state unset.`
                     : sharing.decision === "private"
                         ? "Saved to your private memory."
                         : syncedGroupNames.length
@@ -1646,7 +1672,7 @@ Details: ${m.details || "N/A"}`)
             `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.`,
             receipt,
             typeof groupSharingScopeId === "string" && groupSharingScopeId
-                ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only for get_group_session_sharing, set_group_session_sharing, and save_conversation calls in this conversation. Never reuse it in another conversation or save it as memory.`
+                ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only for get_group_session_sharing, request_group_session_sharing, set_group_session_sharing, and save_conversation calls in this conversation. Never reuse it in another conversation or save it as memory.`
                 : "",
             typeof memoriesDiscarded === "number" && memoriesDiscarded > 0
                 ? `${memoriesDiscarded} additional memories were not stored because your active-memory limit was reached.`
@@ -2090,7 +2116,7 @@ Details: ${m.details || "N/A"}`;
             return {
                 content: [{
                         type: "text",
-                        text: `${scopeText}\n\nThis user belongs to multiple groups: ${choices}. Reuse this same conversation scope and call get_group_session_sharing once per groupId. Ask for a separate explicit Yes/No sharing decision for each selected group.`,
+                        text: `${scopeText}\n\nThis user belongs to multiple groups: ${choices}. Reuse this same conversation scope and call request_group_session_sharing once per groupId so supported hosts render a separate sharing choice for each group.`,
                     }],
             };
         }
@@ -2100,7 +2126,7 @@ Details: ${m.details || "N/A"}`;
             return {
                 content: [{
                         type: "text",
-                        text: `${scopeText}\n\nNo sharing decision exists for this conversation. Ask: “Share memories saved from this conversation with ${readString(group, "name") ?? "your group"}?” Silence is not a No: leave the state unset and ask again at a later qualifying checkpoint until the user explicitly answers Yes or No, without repeating the prompt in the same response. Then call set_group_session_sharing with that explicit answer and the scope above; an explicit No stops later prompts for this conversation.`,
+                        text: `${scopeText}\n\nNo sharing decision exists for this conversation. Call request_group_session_sharing with the scope above${readString(group, "id") ? ` and groupId ${readString(group, "id")}` : ""}. Supported hosts will show a native Share with team / Keep private choice. If the client cannot render it, relay that tool's fallback question. Decline, cancel, or silence is not a No and leaves the state unset.`,
                     }],
             };
         }
@@ -2116,13 +2142,23 @@ Details: ${m.details || "N/A"}`;
                 }],
         };
     }
-    async handleSetGroupSessionSharing(args) {
-        const parsed = setGroupSessionSharingSchema.parse(args ?? {});
-        const payload = await this.client.setGroupSessionSharing(parsed);
-        const sync = isRecord(payload?.sync) ? payload.sync : null;
+    sharingScopeText(groupSharingScopeId) {
+        return groupSharingScopeId
+            ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only in this conversation for later get/request/set/save calls. Never persist it as memory.`
+            : "";
+    }
+    sharingFallbackText(scopeText, groupName) {
+        return [
+            scopeText,
+            `This client cannot show EchoMem's sharing choice UI. Ask: “Share eligible memories saved from this conversation with ${groupName}?” Only an explicit Yes or No may be passed to set_group_session_sharing. Decline, cancel, or silence leaves the state unset.`,
+        ].filter(Boolean).join("\n\n");
+    }
+    formatGroupSessionSharingUpdate(share, payload, scopeText = "") {
+        const data = isRecord(payload) ? payload : {};
+        const sync = isRecord(data.sync) ? data.sync : null;
         const protectedIds = Array.isArray(sync?.protectedMemoryIds) ? sync.protectedMemoryIds : [];
-        const group = isRecord(payload?.group) ? payload.group : {};
-        const receipt = parsed.share
+        const group = isRecord(data.group) ? data.group : {};
+        const receipt = share
             ? sync?.synced === false
                 ? "Conversation sharing is enabled, but the initial group sync failed. Private memories were preserved; retry before claiming publication."
                 : `Conversation sharing is enabled for ${readString(group, "name") ?? "the current group"}. Existing eligible memories in this scope were synced and later saves carrying the same scope will sync automatically.`
@@ -2130,10 +2166,127 @@ Details: ${m.details || "N/A"}`;
         return {
             content: [{
                     type: "text",
-                    text: `${receipt}${protectedIds.length ? ` ${protectedIds.length} flagged ${protectedIds.length === 1 ? "memory was" : "memories were"} protected and kept private.` : ""}`,
+                    text: [
+                        scopeText,
+                        `${receipt}${protectedIds.length ? ` ${protectedIds.length} flagged ${protectedIds.length === 1 ? "memory was" : "memories were"} protected and kept private.` : ""}`,
+                    ].filter(Boolean).join("\n\n"),
                 }],
         };
     }
+    async handleRequestGroupSessionSharing(args) {
+        const parsed = requestGroupSessionSharingSchema.parse(args ?? {});
+        const payload = await this.client.getGroupSessionSharing(parsed);
+        const groupSharingScopeId = readString(payload ?? {}, "groupSharingScopeId");
+        const scopeText = this.sharingScopeText(groupSharingScopeId);
+        if (!groupSharingScopeId) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "EchoMem could not establish a conversation sharing scope, so no decision was recorded and the checkpoint remains private. Retry request_group_session_sharing before offering team sharing.",
+                    }],
+            };
+        }
+        if (payload?.hasGroup !== true) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "No company group is configured for this user. Saves remain private; do not ask about conversation sharing.",
+                    }],
+            };
+        }
+        if (payload?.requiresGroupSelection === true) {
+            const availableGroups = Array.isArray(payload?.availableGroups)
+                ? payload.availableGroups.filter(isRecord)
+                : [];
+            const choices = availableGroups
+                .map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `${scopeText}\n\nChoose one group and call request_group_session_sharing again with the same scope and its groupId: ${choices}. Each group has an independent decision.`,
+                    }],
+            };
+        }
+        const group = isRecord(payload?.group) ? payload.group : {};
+        const groupName = readString(group, "name") ?? "your group";
+        const existingDecision = typeof payload?.decision === "string" ? payload.decision : null;
+        if (existingDecision === "share" || existingDecision === "private") {
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            scopeText,
+                            existingDecision === "share"
+                                ? `This conversation is already approved for ${groupName}. Eligible memories sync automatically; flagged memories stay private.`
+                                : `This conversation is already private for ${groupName}. No sharing prompt was shown.`,
+                        ].filter(Boolean).join("\n\n"),
+                    }],
+            };
+        }
+        const formElicitation = this.server.getClientCapabilities()?.elicitation?.form;
+        if (!formElicitation) {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        let elicitation;
+        try {
+            elicitation = await this.server.elicitInput({
+                mode: "form",
+                message: `EchoMem saved this checkpoint privately. Choose whether eligible memories from this conversation should also be shared with ${groupName}. Flagged memories always remain private.`,
+                requestedSchema: {
+                    type: "object",
+                    properties: {
+                        sharingDecision: {
+                            type: "string",
+                            title: "Team sharing",
+                            description: `Choose whether eligible conversation memories may be shared with ${groupName}.`,
+                            oneOf: [
+                                { const: "share", title: "Share with team" },
+                                { const: "private", title: "Keep private" },
+                            ],
+                        },
+                    },
+                    required: ["sharingDecision"],
+                },
+            });
+        }
+        catch {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        if (elicitation.action !== "accept") {
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            scopeText,
+                            `No sharing decision was recorded for ${groupName}. The checkpoint remains private. Ask again at a later qualifying checkpoint; never interpret decline or cancel as No.`,
+                        ].filter(Boolean).join("\n\n"),
+                    }],
+            };
+        }
+        const sharingDecision = readString(elicitation.content ?? {}, "sharingDecision");
+        if (sharingDecision !== "share" && sharingDecision !== "private") {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        const updatePayload = await this.client.setGroupSessionSharing({
+            ...parsed,
+            groupSharingScopeId,
+            share: sharingDecision === "share",
+            confirmed: true,
+        });
+        return this.formatGroupSessionSharingUpdate(sharingDecision === "share", updatePayload, scopeText);
+    }
+    async handleSetGroupSessionSharing(args) {
+        const parsed = setGroupSessionSharingSchema.parse(args ?? {});
+        const payload = await this.client.setGroupSessionSharing(parsed);
+        return this.formatGroupSessionSharingUpdate(parsed.share, payload);
+    }
     async handlePublishToGroup(args) {
         const parsed = publishToGroupSchema.parse(args ?? {});
         const payload = await this.client.publishMemoryToGroup(args);
@@ -2182,8 +2335,8 @@ Details: ${m.details || "N/A"}`;
             content: [{
                     type: "text",
                     text: payload?.alreadyMember
-                        ? `You are already a member of ${payload?.group?.name ?? "this group"}. No memories were published. Use prepare_group_publication to review memories and propose any missing title or responsibility fields, then call get_group_session_sharing and, if unset, ask again at later qualifying checkpoints until the user explicitly answers Yes or No.`
-                        : `Joined ${payload?.group?.name ?? "the company group"}. No memories were published. Next use prepare_group_publication to review candidates, infer a proposed title and responsibility summary, and ask the user to confirm that profile together with the publication preview. Also call get_group_session_sharing without a scope to mint one for this conversation; if unset, ask whether memories saved from this conversation should be shared and ask again at a later qualifying checkpoint after silence until an explicit Yes or No.`,
+                        ? `You are already a member of ${payload?.group?.name ?? "this group"}. No memories were published. Use prepare_group_publication to review memories and propose any missing title or responsibility fields, then call request_group_session_sharing so supported hosts render the native sharing choice. Decline or cancel stays unset for a later checkpoint.`
+                        : `Joined ${payload?.group?.name ?? "the company group"}. No memories were published. Next use prepare_group_publication to review candidates, infer a proposed title and responsibility summary, and ask the user to confirm that profile together with the publication preview. Also call request_group_session_sharing without a scope so supported hosts show the native team-sharing choice. Decline or cancel leaves consent unset for a later checkpoint.`,
                 }],
         };
     }

package/dist/package-metadata.js

@@ -21,26 +21,29 @@ export const MCP_PACKAGE_NAME = stringOrFallback(packageJson.name, FALLBACK_PACK
 export const MCP_PACKAGE_VERSION = stringOrFallback(packageJson.version, FALLBACK_PACKAGE.version);
 export const MCP_PACKAGE_DESCRIPTION = stringOrFallback(packageJson.description, FALLBACK_PACKAGE.description);
 export const MCP_PACKAGE_LABEL = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
+export const MCP_DESKTOP_MANAGED = process.env.ECHO_DESKTOP_MANAGED === "1";
 export const MCP_UPDATE_COMMAND = `npx -y ${MCP_PACKAGE_NAME}@latest update`;
 export const MCP_UPDATE_ALL_COMMAND = `${MCP_UPDATE_COMMAND} --all`;
+export const MCP_VAULT_UNLOCK_INSTRUCTION = MCP_DESKTOP_MANAGED
+    ? "open Echo Desktop and unlock the vault there"
+    : "run `echomem-mcp unlock` locally";
+const MCP_UPDATE_INSTRUCTION = MCP_DESKTOP_MANAGED
+    ? "Echo Desktop manages this MCP runtime; install an Echo Desktop update when one is offered"
+    : `update once with \`${MCP_UPDATE_ALL_COMMAND}\``;
 export const MEMORY_CITATION_INSTRUCTION = 'If the user-facing answer materially relies on one or more EchoMem memories, end it with a compact "EchoMem sources:" list containing only the memories actually used. For memories owned by teammates or accepted friends, call record_memory_citations immediately before the final answer with those exact Memory IDs. Do not cite memories that were merely retrieved. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. Omit the sources section and citation receipt when no memory informed the answer.';
 export const SAVED_MEMORY_RECEIPT_INSTRUCTION = 'After save_conversation succeeds and returns one or more saved memory IDs, make the save visible in the final user-facing answer with a compact "EchoMem saved:" list containing every memory created by that call. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. This save receipt is separate from "EchoMem sources:" and does not imply that the newly saved memories informed the answer.';
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
-    `If the user or local config expects a newer EchoMem MCP version than ${MCP_PACKAGE_VERSION}, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session.`,
-    "Use echomem_update_status to check whether npm has a newer bridge; it is cached and non-blocking during normal tool listing.",
-    "Do not auto-update on every MCP startup; this bridge is intentionally stable between explicit updates.",
-    "Before the final response for work that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone, call save_conversation. This is a private checkpoint and does not require a separate user request. Skip secrets, incidental chatter, and trivial read-only work. If an encrypted vault is locked, tell the user to run echomem-mcp unlock rather than silently skipping the checkpoint.",
-    "For a user with a company group, call get_group_session_sharing near conversation start or after a qualifying private save. On the first call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one groupId at a time. Each group requires its own explicit Yes/No decision. Silence leaves that group's state unset; never infer an answer or repeat the prompt in the same response. Store only explicit answers with set_group_session_sharing, the same scope, and the selected groupId. Saves sync eligible memories to every approved group; a No keeps them private for that group. Flagged memories stay private.",
-    "For company-group sharing, use get_group_context for orientation; create_memory_group/create_group_invite/join_memory_group for membership; and prepare_group_publication as a no-publication preview.",
-    "After joining or when profile fields are missing, use candidate memory evidence to propose a title and responsibility summary. Ask the user to confirm that proposal together with the publication preview, then call update_group_profile and complete_group_publication.",
-    "Use one canonical https://echoknows.com/memory/<memory-id> link for private, group, and friend evidence. Label it with the memory key; the site resolves the authorized representation.",
-    "Each search result is one memory: preserve its Memory ID and canonical echoknows.com link when citing it.",
-    MEMORY_CITATION_INSTRUCTION,
-    SAVED_MEMORY_RECEIPT_INSTRUCTION,
-    "During a publication preview, if an unflagged candidate appears sensitive, proactively ask whether the user wants to mark its exact ID for publication attention first. Explain that marking does not publish or change encryption; it means the agent will call it out and ask for detailed confirmation whenever a later publication includes it. Never auto-flag inferred sensitivity. For sensitive-topic flags, search and preview exact owned memories before confirmed flag_memories_for_publication_attention. Separate already-flagged candidates, state that nothing has been published yet, and offer to exclude them, review them separately, or first search for and mark similar sensitive owned memories.",
-    "Never save an inferred group profile. Manual prepared publication requires explicit preview confirmation; flagged memories still require separate exact-memory confirmation. Never store or log an echo_grp_ invite code.",
+    `If this bridge is stale, ${MCP_UPDATE_INSTRUCTION} and start a new MCP session; never auto-update at startup.`,
+    "Before re-deriving prior decisions or preferences, use search_memories.",
+    `Before the final response for a durable decision, implementation, fix, commit, passing verification, release, or milestone, call save_conversation. Skip secrets and trivial work. If the encrypted vault is locked, tell the user to ${MCP_VAULT_UNLOCK_INSTRUCTION}.`,
+    "After a successful save, show every memory created by that call in a compact EchoMem saved: list with canonical links; this is separate from \"EchoMem sources:\".",
+    "For company groups, call request_group_session_sharing near conversation start or after a qualifying save. It renders a native choice on clients with MCP elicitation and returns a text fallback otherwise. Omit groupSharingScopeId only on the first call, then reuse the returned scope only in this conversation. Each group needs an explicit choice; decline, cancel, or silence stays unset. Never infer consent. Flagged memories stay private.",
+    "EchoMem credential identity is authoritative over Claude profiles, host accounts, git identity, or inference. Use get_group_context before group-orientation answers and never re-filter owners returned by search_others_memories.",
+    "When a final answer materially uses teammate or friend memories, call record_memory_citations with only the exact used Memory IDs and a unique per-answer receiptId.",
+    "End memory-informed answers with a compact EchoMem sources: list. Use each memory key as the label and https://echoknows.com/memory/<memory-id> as its canonical link.",
+    "Group profiles, conversation sharing, publication, sensitive-memory flags, and deletion require explicit user confirmation. Never store or log an echo_grp_ invite code.",
 ].join(" ");
 export function withMcpVersion(description) {
-    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` (or add \`--client cursor|windsurf|claude-desktop|claude-code|codex\` for a single client), then start a new MCP session. Do not run updates repeatedly or on every startup.`;
+    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, ${MCP_UPDATE_INSTRUCTION}, then start a new MCP session. Do not run updates repeatedly or on every startup.`;
 }

package/dist/save-checkpoint-hook.js

@@ -7,10 +7,10 @@ const CHECKPOINT_REASON = [
     "Run EchoMem's private completion checkpoint before finishing this turn.",
     "Review the work that just completed. If it produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone, call `save_conversation` now with a concise structured summary of the outcome, reasoning, relevant files, and constraints.",
     "Do not save secrets or incidental chatter. If the work was not durable, do not call the tool and finish normally.",
-    "Private persistence happens first. For a user with a company group, call `get_group_session_sharing` near conversation start or after a qualifying private save.",
-    "On the first get_group_session_sharing call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one groupId at a time. Each group needs its own explicit Yes/No decision. Silence leaves that group's state unset; do not infer an answer or repeat the prompt in the same response. A Yes decision syncs eligible memories from later saves carrying the same scope to that group; saves automatically sync to every approved group. A No decision keeps them private for that group.",
+    "Private persistence happens first. For a user with a company group, call `request_group_session_sharing` near conversation start or after a qualifying private save.",
+    "On the first request_group_session_sharing call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and call once per groupId. Supported clients render a native Share with team / Keep private choice; if the tool returns a text fallback, relay its exact question and call set_group_session_sharing only after an explicit Yes/No. Decline, cancel, or silence leaves that group's state unset. A Share decision syncs eligible memories from later saves carrying the same scope to that group; saves automatically sync to every approved group. Keep private keeps them private for that group.",
     "Flagged memories are withheld from automatic conversation sync and remain private.",
-    "If EchoMem reports that the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip a qualifying checkpoint.",
+    "If EchoMem reports that the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip a qualifying checkpoint.",
 ].join(" ");
 function currentTurnSlice(transcript) {
     const lines = transcript.split(/\r?\n/);

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

@@ -38,7 +38,13 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           }
           return envelope;
         }
-        if (!gs || !Number.isFinite(sessions) || sessions <= 0 || canonicalSessions !== sessions || canonicalInput <= 0 || skipped !== 0) {
+        if (
+          !gs ||
+          !Number.isFinite(sessions) || sessions <= 0 ||
+          !Number.isFinite(canonicalSessions) || canonicalSessions <= 0 || canonicalSessions > sessions ||
+          !Number.isFinite(skipped) || skipped < 0 || canonicalSessions + skipped !== sessions ||
+          !Number.isFinite(canonicalInput) || canonicalInput <= 0
+        ) {
           throw new Error("Canonical analysis is incomplete or does not match the provider session cohort.");
         }
         if (!Array.isArray(r.repos) || r.repos.length === 0) {
@@ -52,15 +58,19 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         report = null;
         reportEnvelope = null;
         resetReportSurface();
+        var canContinue = String(code || "").indexOf("REPORT_") === 0 || code === "RENDER_FAILED";
         setHead("We couldn't finish this scan", "Needs attention");
         app.className = "reportMessageStage";
         app.innerHTML =
           '<section class="reportMessage" data-report-state="failed">' +
             '<h2>We couldn’t finish this scan.</h2>' +
             '<p>Your coding history is unchanged.</p>' +
-            '<p>Close this tab and run <code>echomem-mcp init</code> again.</p>' +
+            (canContinue
+              ? '<p>This optional report can be retried later.</p><div class="actions"><button type="button" class="primary" data-connect-echo>Continue without report</button></div>'
+              : '<p>Close this tab and run <code>echomem-mcp init</code> again.</p>') +
             '<details class="reportTechnical"><summary>Technical details</summary><code>' + esc(code || "REPORT_FAILED") + '</code></details>' +
           '</section>';
+        if (canContinue) bindConnect();
       }
       function renderEmptyReport() {
         report = null;
@@ -71,8 +81,10 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         app.innerHTML =
           '<section class="reportMessage" data-report-state="empty">' +
             '<h2>No coding history found.</h2>' +
-            '<p>Start a Codex or Claude Code session, then run <code>echomem-mcp init</code> again.</p>' +
+            '<p>You can continue now and import local coding history later.</p>' +
+            '<div class="actions"><button type="button" class="primary" data-connect-echo>Continue setup</button></div>' +
           '</section>';
+        bindConnect();
       }
       function renderBridgeIssue() {
         renderReportIssue("BRIDGE_UNREACHABLE", "The local bridge stopped answering before your report was ready. Your terminal may have closed or the process may have stopped.");
@@ -203,6 +215,9 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         var hasPendingCount = typeof pending === "number";
         var discovery = stats && stats.discovery ? stats.discovery : {};
         var isPartial = !!(stats && stats.partial);
+        var optionalDiagnostics = stats && stats.optionalDiagnostics ? stats.optionalDiagnostics : {};
+        var optionalStatsDegraded = optionalDiagnostics.degraded === true;
+        var degradedWithoutCounts = optionalStatsDegraded && optionalDiagnostics.countsTrusted !== true;
         var localScanReady = !isPartial || discovery.phase === "exact" || discovery.phase === "full";
         var skippedActive = typeof migratable.skippedActive === "number" ? migratable.skippedActive : 0;
         var sessions = stats && stats.sessions ? stats.sessions : {};
@@ -210,8 +225,8 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         // already imported elsewhere, so it over-counts (e.g. 10). The count is only trustworthy after the
         // account check (phase "account"/"exact"/"full"), which corrects it (e.g. 3). Until then we show a
         // "counting" state with no number, so the user never sees the count jump down.
-        var pendingTrusted = hasPendingCount && !!discovery.phase && discovery.phase !== "quick";
-        var knownDone = pendingTrusted && pending === 0;
+        var pendingTrusted = !degradedWithoutCounts && hasPendingCount && !!discovery.phase && discovery.phase !== "quick";
+        var knownDone = pendingTrusted && pending === 0 && !optionalStatsDegraded;
         var canExtract = pendingTrusted && pending > 0;
         var pendN = hasPendingCount ? pending : 0;
         var pendingCodex = typeof migratable.pendingCodex === "number" ? migratable.pendingCodex : null;
@@ -227,15 +242,19 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         var currentPlanLabel = paidRecallPlan(currentPlan)
           ? currentPlan.charAt(0).toUpperCase() + currentPlan.slice(1) + " Echo"
           : "Original Echo";
-        setHead("Turn coding history into memory", pendingTrusted ? (knownDone ? "Done" : "Ready") : (localScanReady ? "Ready" : "Scanning"));
-        var headlineHtml = !pendingTrusted
+        setHead("Turn coding history into memory", degradedWithoutCounts ? "Ready" : (pendingTrusted ? (knownDone ? "Done" : "Ready") : (localScanReady ? "Ready" : "Scanning")));
+        var headlineHtml = degradedWithoutCounts
+          ? "Local history counting <strong>couldn’t finish.</strong>"
+          : !pendingTrusted
           ? "Counting your <strong>new conversations…</strong>"
           : (knownDone
               ? "You are <strong>all caught up.</strong>"
               : (planLimited
                   ? "<strong>" + esc(number(pendN)) + " sessions</strong> found."
                   : "<strong>" + esc(number(pendN)) + " sessions</strong> are ready to review."));
-        var sub = !pendingTrusted
+        var sub = degradedWithoutCounts
+          ? "You can finish setup now. Your conversations stay on this Mac, and you can retry the history import later."
+          : !pendingTrusted
           ? "Echo is matching your local history against what is already in memory."
             : (knownDone
             ? (skippedActive ? number(skippedActive) + " active conversation" + (skippedActive === 1 ? " is" : "s are") + " still changing, so Echo will pick them up later." : "Your history is already in EchoMem. Nothing new to extract.")
@@ -287,6 +306,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         }
         document.getElementById("exBanner").innerHTML =
           (statsSlow && !stats ? '<div class="warning">Local counts are taking longer than expected. You can still ask Echo to extract anything unprocessed.</div>' : '') +
+          (optionalStatsDegraded && !degradedWithoutCounts ? '<div class="warning">The optional usage summary was skipped. Your conversation list is still ready.</div>' : '') +
           (error ? '<div class="error">' + esc(error) + '</div>' : '');
         document.getElementById("exHeadline").innerHTML = headlineHtml;
         document.getElementById("exSub").textContent = sub;
@@ -297,7 +317,9 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           var asset = id === "claude-desktop" ? "claude" : "codex";
           return '<span class="pfIcon"><img src="/hud-assets/' + asset + '.svg" alt="" onerror="this.style.display=&quot;none&quot;;this.nextElementSibling.style.display=&quot;grid&quot;;" /><span class="pfFallback">' + fallback + '</span></span>';
         };
-        document.getElementById("exSources").innerHTML = !pendingTrusted
+        document.getElementById("exSources").innerHTML = degradedWithoutCounts
+          ? '<span class="pfNote">Optional local-history count skipped.</span>'
+          : !pendingTrusted
           ? '<span class="pfNote">Scanning local history&hellip;</span>'
           : (canExtract
               ? '<span class="pf">' + srcIcon("codex", "CX") + '<strong>' + esc(number(codexN)) + '</strong> Codex</span>' +
@@ -306,7 +328,9 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
                 '<span class="pfNote">found on this Mac</span>'
               : "");
         // Reassurances live at the moment of commitment — right under the button.
-        document.getElementById("exEta").innerHTML = pendingTrusted
+        document.getElementById("exEta").innerHTML = degradedWithoutCounts
+          ? 'Setup can continue without this optional count.'
+          : pendingTrusted
           ? (canExtract
               ? ''
               : 'Nothing new to extract right now.')
@@ -317,7 +341,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         // While still counting, hide the primary button entirely; the headline + source split
         // already say it is working, and the ready state should present one clear action.
         var migrateBtn = document.getElementById("migrate");
-        if (pendingTrusted) {
+        if (pendingTrusted || degradedWithoutCounts) {
           migrateBtn.style.display = "";
           var candidatesReady = !canExtract || candidateSessions().length > 0;
           if (canExtract && candidatesReady) ensureSessionSelection();

package/dist/setup-page.js

@@ -1,6 +1,6 @@
 import { renderSetupPageDocument } from "./setup-page/document.js";
 import { renderSetupPreviewBootstrap } from "./setup-preview.js";
-export { SETUP_PREVIEW_STATES } from "./setup-preview.js";
+export { SETUP_PREVIEW_REPORT, SETUP_PREVIEW_STATES } from "./setup-preview.js";
 /**
  * Setup page entry point. The implementation is split by product phase under ./setup-page/:
  * core utilities, local report, post-auth extraction, and lifecycle polling.

package/dist/setup-preview.js

@@ -3,8 +3,11 @@ export const SETUP_PREVIEW_STATES = [
     "consent-required",
     "scan",
     "scan-error",
+    "bridge-error",
     "report",
     "extract-counting",
+    "extract-degraded",
+    "extract-degraded-exact",
     "extract-ready",
     "extract-free-selected",
     "extract-free-trial-used",
@@ -35,7 +38,7 @@ export const SETUP_PREVIEW_STATES = [
 export function parseSetupPreviewState(value) {
     return SETUP_PREVIEW_STATES.includes(value) ? value : null;
 }
-const previewReport = {
+export const SETUP_PREVIEW_REPORT = {
     schemaVersion: 1,
     dataOrigin: "design-preview",
     generatedFrom: [],
@@ -307,8 +310,12 @@ export function renderSetupPreviewBootstrap(state) {
         return `${watermark}
         renderReportIssue("REPORT_CANONICAL_INVALID", "Preview-only canonical reconciliation failure.");`;
     }
+    if (state === "bridge-error") {
+        return `${watermark}
+        renderBridgeIssue();`;
+    }
     if (state === "report") {
-        const reportJson = JSON.stringify(previewReport);
+        const reportJson = JSON.stringify(SETUP_PREVIEW_REPORT);
         return `${watermark}
         localHistoryConsentGranted = true;
         report = ${reportJson};
@@ -320,6 +327,22 @@ export function renderSetupPreviewBootstrap(state) {
         stats = null;
         renderDashboard();`;
     }
+    if (state === "extract-degraded")
+        return `${watermark}${extractionPreviewBootstrap({
+            plan: "free", paid: false, trialAvailable: true, trialUsed: false,
+            quotaLimit: 100, quotaRemaining: 100, candidateCount: 7, selectFree: true,
+        })}
+        stats.discovery = { phase: "quick", exact: false };
+        stats.optionalDiagnostics = { degraded: true, reason: "EXACT_DISCOVERY_FAILED", countsTrusted: false };
+        renderDashboard();`;
+    if (state === "extract-degraded-exact")
+        return `${watermark}${extractionPreviewBootstrap({
+            plan: "free", paid: false, trialAvailable: true, trialUsed: false,
+            quotaLimit: 100, quotaRemaining: 100, candidateCount: 7, selectFree: true,
+        })}
+        stats.discovery = { phase: "exact", exact: true };
+        stats.optionalDiagnostics = { degraded: true, reason: "FULL_STATS_FAILED", countsTrusted: true };
+        renderDashboard();`;
     if (state === "extract-ready")
         return `${watermark}${extractionPreviewBootstrap({
             plan: "free", paid: false, trialAvailable: true, trialUsed: false,