@echomem/mcp 1.4.34 → 1.4.35

package/README.md

@@ -37,38 +37,26 @@ legacy EchoMem-synthesized recall answer.
 
 ## Quick start (recommended)
 
-```bash
-# One command, everything: download the bridge + HUD, configure every coding agent you have
-# installed (Codex, Claude Code, Claude Desktop, Cursor, Windsurf…), log in, and launch the HUD.
-npm i -g @echomem/mcp@latest && echomem-mcp init
-```
+Install Echo Desktop, sign in once, then open **Connect MCP** and choose **Connect Echo**. The app
+ships and installs the MCP runtime, configures the detected Codex and Claude hosts, mirrors the same
+device credential used by the desktop app, and verifies the MCP handshake. No terminal login is
+required.
+
+The standalone HUD has been retired; Echo Desktop is the persistent setup and status surface. The
+bridge still reads local agent logs for on-demand context-health tools, but it no longer publishes or
+auto-launches an Electron overlay.
 
-A global install (not `npx`) is recommended because it wires each editor to a **stable** path: a bare
-`npx` run resolves the bridge into a throwaway `_npx/<hash>` cache dir that npm later garbage-collects,
-which would break the MCP server after the fact (`setup` now refuses to pin such a path and falls back
-to the global install, but installing globally avoids the issue entirely). The context HUD's
-launch-at-login also runs from the installed path. `init` is the flagship one-liner — it wraps `setup --all --with-hud`: it writes each
-installed agent's MCP config (with **no secret** in it — credentials live in
-`~/.echomem/credentials.json`, mode 0600), adds the EchoMem memory guidance to their global
-`AGENTS.md` / `CLAUDE.md`, installs first-party `echomem-search`, `echomem-save`,
-`echomem-forget`, and `echomem-login` skills for Codex, opens the browser to approve the device
-(and unlock the vault for encrypted accounts), then launches the context HUD. EchoMem updates only
-its own skill folders; other memory-provider skills are detected and reported but never modified.
-Reload your editors and you're done.
-
-Prefer to keep it minimal? `echomem-mcp setup` configures only the auto-detected editor and skips the
-HUD; the granular commands below still work.
+For headless systems and development, the granular CLI commands remain available:
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp init` | **Everything in one command** — all installed agents + HUD + login |
+| `npm i -g @echomem/mcp@latest && echomem-mcp init` | Legacy/headless setup for installed agents + login |
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
 | `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config without opening the browser or changing credentials |
 | `npx -y @echomem/mcp@latest update --all` | One-shot update: install the latest bridge durably and repoint detected client configs, with no browser login |
 | `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
-| `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Privately unlock the vault on this trusted device |
 | `echomem-mcp lock` | Remove the local vault key while keeping the device login |
@@ -82,29 +70,8 @@ checks npm for a newer published bridge using a cached, non-blocking check. Agen
 `npx -y @echomem/mcp@latest update --all` if the user agrees. The bridge does not auto-update on
 every MCP startup.
 
-## EchoMem Context HUD
-
-The package also ships `echomem-hud`, a local context-health sidecar for Codex and Claude. It reads
-local agent logs, computes a tracked lower-bound "clean vs dirty" context score, and renders a small
-HUD without adding tokens to the agent conversation.
-
-```bash
-echomem-hud app                 # Electron floating HUD
-echomem-hud serve               # Browser fallback at http://127.0.0.1:17377
-echomem-hud summary --json      # Machine-readable current score
-echomem-hud status              # Show detected Codex/Claude sources
-```
-
-Supported local sources:
-- Codex: `~/.codex/sessions/**/rollout-*.jsonl`
-- Claude Code: `~/.claude/echo-ctx/*.json` first, then local transcripts when present
-- Claude desktop agent/Cowork: local agent-mode transcripts under Application Support
-
-The v1 metric counts `range_redundant` reads only and reports pollution as `tracked dead-weight ≥`
-because exact context composition and provider eviction are not observable.
-
-MCP fallback: agents can call `echo_context_health` to get the same score as markdown in-chat. This
-is on-demand; the passive HUD remains a separate local process.
+Agents can still call `echo_context_health` for an on-demand local context-health report. It reads
+the local Codex/Claude logs and does not require a separate process or desktop overlay.
 
 ## Agent Doctor — local workspace forensics (new in 1.4.9)
 

package/dist/context-analysis/claude-native-canonical.js

@@ -7,6 +7,14 @@ import { walk } from "../report.js";
 import { isStrongPositiveFeedback, } from "./workspace-report.js";
 const OUTPUT_TOKEN_CAP = 12_000;
 const IMAGE_TOKENS = 4_000;
+// Request-by-request retained-context scoring grows faster than the raw JSONL. Keep onboarding
+// predictable by analyzing a deterministic head/middle/tail sample from oversized sessions. The
+// source transcript is untouched and remains available to the separate import pipeline.
+const CLAUDE_MAX_TURNS_PER_SESSION = 1_000;
+const CLAUDE_HEAD_TURNS = 200;
+const CLAUDE_TAIL_TURNS = 500;
+const CLAUDE_MIDDLE_WINDOWS = 3;
+const CLAUDE_MIDDLE_WINDOW_TURNS = 100;
 const PROBLEM_META = {
     P01: { label: "Outdated Images & Screenshots", bucket: "dead", category: "Runtime Bug", confidence: "high" },
     P02: { label: "Ignored User Instructions", bucket: "refind", category: "Model Behavior", confidence: "medium" },
@@ -350,26 +358,31 @@ function resultItem(args) {
 }
 function scoreClaudeNativeSession(parsed) {
     classifyItems(parsed.items);
-    const requestRows = [];
+    const terminalRequestByTurn = new Map();
     for (const request of parsed.requests) {
         const rawBuckets = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
         const buckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
         const problemStats = new Map();
-        const occurrences = [];
-        const priorItems = parsed.items
-            .filter((item) => item.requestSeq < request.seq)
-            .flatMap((item) => {
+        // Episode rendering only needs totals by episode/problem/bucket. Aggregating here avoids
+        // retaining one occurrence for every prior item on every request (quadratic heap growth).
+        const occurrenceMap = new Map();
+        const priorItems = [];
+        let usefulItemTokens = 0;
+        let wasteItemTokens = 0;
+        for (const item of parsed.items) {
+            if (item.requestSeq >= request.seq)
+                continue;
             const classification = classForRequest(item, request);
-            return classification ? [{ item, classification }] : [];
-        });
+            if (!classification)
+                continue;
+            priorItems.push({ item, classification });
+            if (classification.kind === "useful")
+                usefulItemTokens += item.tokens;
+            else
+                wasteItemTokens += item.tokens;
+        }
         const overhead = Math.min(request.inputTokens, parsed.overheadTokens);
         const productBudget = Math.max(0, request.inputTokens - overhead);
-        const usefulItemTokens = priorItems
-            .filter(({ classification }) => classification.kind === "useful")
-            .reduce((sum, { item }) => sum + item.tokens, 0);
-        const wasteItemTokens = priorItems
-            .filter(({ classification }) => classification.kind === "waste")
-            .reduce((sum, { item }) => sum + item.tokens, 0);
         const totalObserved = usefulItemTokens + wasteItemTokens;
         const scale = totalObserved > productBudget && totalObserved > 0 ? productBudget / totalObserved : 1;
         const keepProd = usefulItemTokens * scale;
@@ -413,7 +426,7 @@ function scoreClaudeNativeSession(parsed) {
                 });
             }
             problemStats.set(classification.problemId, stat);
-            occurrences.push({
+            recordNativeOccurrence(occurrenceMap, {
                 episode: request.episode,
                 problemId: classification.problemId,
                 bucket: classification.bucket,
@@ -437,7 +450,7 @@ function scoreClaudeNativeSession(parsed) {
             problemStats,
             buckets,
             rawBuckets,
-            occurrences,
+            occurrences: occurrenceMap,
             requestUsefulTokens: rawUseful,
             requestWasteTokens: rawResidue,
         });
@@ -466,7 +479,7 @@ function scoreClaudeNativeSession(parsed) {
                     turnWasteTokens: Math.round(rawResidue),
                 }];
         }
-        requestRows.push({
+        terminalRequestByTurn.set(request.turn, {
             request,
             officialInputTokens: request.inputTokens,
             usefulTokens: rawUseful,
@@ -477,10 +490,11 @@ function scoreClaudeNativeSession(parsed) {
             buckets,
             rawBuckets,
             problems: problemStats,
-            occurrences,
+            occurrences: [...occurrenceMap.values()],
         });
     }
-    const selectedRows = selectTerminalRequestPerTurn(requestRows);
+    const selectedRows = [...terminalRequestByTurn.values()]
+        .sort((left, right) => left.request.turn - right.request.turn || left.request.seq - right.request.seq);
     const selected = mergeRequestAccountingRows(selectedRows);
     const zeroBuckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
     const zeroRawBuckets = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
@@ -537,7 +551,7 @@ function allocateResidualToProblemSignals(args) {
             });
         }
         args.problemStats.set(problemId, stat);
-        args.occurrences.push({
+        recordNativeOccurrence(args.occurrences, {
             episode: args.request.episode,
             problemId,
             bucket,
@@ -548,15 +562,15 @@ function allocateResidualToProblemSignals(args) {
     }
     return allocated;
 }
-function selectTerminalRequestPerTurn(rows) {
-    const byTurn = new Map();
-    for (const row of rows) {
-        const current = byTurn.get(row.request.turn);
-        if (!current || row.request.seq > current.request.seq) {
-            byTurn.set(row.request.turn, row);
-        }
+function recordNativeOccurrence(occurrences, occurrence) {
+    const key = `${occurrence.episode}:${occurrence.problemId}:${occurrence.bucket}`;
+    const existing = occurrences.get(key);
+    if (existing) {
+        existing.tokens += occurrence.tokens;
+        existing.turn = Math.max(existing.turn, occurrence.turn);
+        return;
     }
-    return [...byTurn.values()].sort((left, right) => left.request.turn - right.request.turn || left.request.seq - right.request.seq);
+    occurrences.set(key, { ...occurrence });
 }
 function mergeRequestAccountingRows(rows) {
     const buckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
@@ -1023,7 +1037,52 @@ function internalBucket(bucket) {
     return "opt_dead";
 }
 function readRows(file) {
+    const totalTurns = countClaudeNativeTurns(file);
+    const ranges = claudeTurnSampleRanges(totalTurns);
     const rows = [];
+    let turn = 0;
+    forEachJsonRow(file, (row) => {
+        if (stringValue(row.type) === "user" && !isClaudeToolResultUser(row))
+            turn += 1;
+        if (turn === 0 || turnInClaudeRanges(turn, ranges))
+            rows.push(row);
+    });
+    return rows;
+}
+function countClaudeNativeTurns(file) {
+    let turns = 0;
+    forEachJsonRow(file, (row) => {
+        if (stringValue(row.type) === "user" && !isClaudeToolResultUser(row))
+            turns += 1;
+    });
+    return turns;
+}
+export function claudeTurnSampleRanges(totalTurns) {
+    if (totalTurns <= CLAUDE_MAX_TURNS_PER_SESSION)
+        return totalTurns > 0 ? [[1, totalTurns]] : [];
+    const tailStart = totalTurns - CLAUDE_TAIL_TURNS + 1;
+    const ranges = [
+        [1, CLAUDE_HEAD_TURNS],
+        [tailStart, totalTurns],
+    ];
+    const middleStart = CLAUDE_HEAD_TURNS + 1;
+    const middleEnd = tailStart - 1;
+    const middleSpan = Math.max(0, middleEnd - middleStart + 1);
+    for (let index = 0; index < CLAUDE_MIDDLE_WINDOWS; index += 1) {
+        const segmentStart = middleStart + Math.floor((middleSpan * index) / CLAUDE_MIDDLE_WINDOWS);
+        const segmentEnd = middleStart + Math.floor((middleSpan * (index + 1)) / CLAUDE_MIDDLE_WINDOWS) - 1;
+        const segmentTurns = Math.max(0, segmentEnd - segmentStart + 1);
+        const windowTurns = Math.min(CLAUDE_MIDDLE_WINDOW_TURNS, segmentTurns);
+        const start = segmentStart + Math.floor((segmentTurns - windowTurns) / 2);
+        if (windowTurns > 0)
+            ranges.push([start, start + windowTurns - 1]);
+    }
+    return ranges.sort((left, right) => left[0] - right[0]);
+}
+function turnInClaudeRanges(turn, ranges) {
+    return ranges.some(([start, end]) => turn >= start && turn <= end);
+}
+function forEachJsonRow(file, visit) {
     const fd = fs.openSync(file, "r");
     const decoder = new StringDecoder("utf8");
     const buffer = Buffer.allocUnsafe(1 << 20);
@@ -1034,7 +1093,7 @@ function readRows(file) {
         try {
             const parsed = JSON.parse(line);
             if (isRecord(parsed))
-                rows.push(parsed);
+                visit(parsed);
         }
         catch {
             // Claude Code may leave an active final JSONL line partial.
@@ -1064,7 +1123,6 @@ function readRows(file) {
     finally {
         fs.closeSync(fd);
     }
-    return rows;
 }
 function isClaudeToolResultUser(record) {
     const content = recordValue(record.message).content;

package/dist/forensics.js

@@ -1158,9 +1158,9 @@ function invalidSetupReport(code, message) {
 /**
  * Fail-closed boundary between the local scanner and setup UI.
  *
- * The setup page must never infer that a fixture, partial scan, or internally inconsistent token
- * ledger is the user's report. This validator checks the provenance and the cross-ledger identities
- * the UI relies on before any absolute token number is rendered.
+ * The setup page must never infer that a fixture, unreconciled scan, or internally inconsistent
+ * token ledger is the user's report. This validator checks provenance and the cross-ledger
+ * identities the UI relies on before any absolute token number is rendered.
  */
 export function validateForensicReportForSetup(value) {
     const report = recordValue(value);
@@ -1268,6 +1268,7 @@ export function validateForensicReportForSetup(value) {
         return invalidSetupReport("REPORT_COST_INVALID", "Per-workspace costs do not reconcile with total spend.");
     }
     const diagnostics = canonical.diagnostics === undefined ? null : recordValue(canonical.diagnostics);
+    let skippedCanonicalSessions = 0;
     if (canonical.diagnostics !== undefined && !diagnostics) {
         return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
     }
@@ -1277,12 +1278,15 @@ export function validateForensicReportForSetup(value) {
         if (skippedSessions === null || !Array.isArray(errors)) {
             return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
         }
-        if (skippedSessions > 0 || errors.length > 0) {
-            return invalidSetupReport("REPORT_PARTIAL", "Some local sessions could not be analyzed; no partial report was shown.");
+        if (skippedSessions !== errors.length) {
+            return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics do not reconcile.");
         }
+        skippedCanonicalSessions = skippedSessions;
     }
-    if (sessionCount !== canonicalSessionCount) {
-        return invalidSetupReport("REPORT_COHORT_MISMATCH", "Provider and canonical ledgers cover different session cohorts.");
+    if (canonicalSessionCount > sessionCount ||
+        canonicalSessionCount + skippedCanonicalSessions !== sessionCount ||
+        (sessionCount > 0 && canonicalSessionCount === 0)) {
+        return invalidSetupReport("REPORT_COHORT_MISMATCH", "Canonical analysis did not retain a usable local-session cohort.");
     }
     if (canonicalUseful + canonicalWaste !== canonicalInput) {
         return invalidSetupReport("REPORT_CANONICAL_INVALID", "Canonical useful and waste totals do not reconcile.");
@@ -1517,8 +1521,7 @@ export async function buildForensicReport(opts) {
     }
     if (report.canonicalGoldenStandard &&
         !("error" in report.canonicalGoldenStandard) &&
-        (report.canonicalGoldenStandard.diagnostics?.skippedSessions ?? 0) === 0 &&
-        report.scale.sessionCount === report.canonicalGoldenStandard.summary.sessionsAnalyzed) {
+        report.canonicalGoldenStandard.summary.sessionsAnalyzed > 0) {
         const projection = projectCanonicalWasteToBilledInput(Number(report.scale.totalInputTokens || 0), report.canonicalGoldenStandard.summary);
         if (projection)
             report.billedWasteProjection = projection;

package/dist/index.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");
 }
@@ -1157,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 () => {
@@ -1207,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) => {
@@ -1243,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;
@@ -1361,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.`,
                             },
                         ],
                     };
@@ -1375,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"),
                             },

package/dist/package-metadata.js

@@ -21,15 +21,22 @@ 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 this bridge is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session; never auto-update at startup.`,
+    `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 run echomem-mcp unlock.",
+    `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.",
@@ -38,5 +45,5 @@ export const MCP_SERVER_INSTRUCTIONS = [
     "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

@@ -10,7 +10,7 @@ const CHECKPOINT_REASON = [
     "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,

package/dist/setup.js

@@ -31,7 +31,7 @@ import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
 import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
-import { installHooks, installSaveCheckpointHooks } from "./hud/hooks.js";
+import { installSaveCheckpointHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
@@ -392,7 +392,7 @@ function echomemGuidanceBlock() {
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
         "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
         '- If the final 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. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories that were merely retrieved, and omit the section when no memory informed the answer.',
-        "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip it.",
+        "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because 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 it.",
         '- 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. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. This save receipt is separate from `EchoMem sources:` and does not imply the newly saved memories informed the answer.',
         "- For a user with a company group, call `request_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/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; never infer an answer. Saves sync eligible memories to every approved group; a No keeps them private for that group.",
         "- If the user pastes a session carryover/checkpoint: it may reference `get_checkpoint_by_context` — use it to pull the checkpoint/decision trail when you need more than the snapshot.",
@@ -403,14 +403,12 @@ function echomemGuidanceBlock() {
         "- Group sharing is scoped to an opaque id carried only in the current conversation, not to the MCP transport session. Membership is rechecked for each sync. Flagged memories are withheld from automatic conversation sync and remain private.",
         "- If a user asks to create a group, call `create_memory_group`; if they ask for a code to share, call `create_group_invite` and return the secret invite code only to that user. Never save the invite code to memory or include it in logs, analytics, summaries, or unrelated output.",
         "- If a user supplies an `echo_grp_...` code and explicitly asks to join, call `join_memory_group`. Joining never authorizes publishing by itself and must not move a user out of another group. After joining, continue into the profile-and-publication preview instead of leaving title or responsibility blank.",
-        "- For requests such as “prepare my recent work memories,” “upload work from this ticket,” or “publish work since my last sync,” call `prepare_group_publication` first. This is a no-publication preview. For encrypted accounts, tell the user to run `echomem-mcp unlock` locally if the tool reports that the key is required.",
+        "- For requests such as “prepare my recent work memories,” “upload work from this ticket,” or “publish work since my last sync,” call `prepare_group_publication` first. This is a no-publication preview. For encrypted accounts, tell the user to open Echo Desktop and unlock the vault there if the tool reports that the key is required.",
         "- After preparing, select only exact candidate memory IDs that match the user's stated scope and exclude already-published or exact-content duplicates. Use the candidate evidence to draft a concise title and responsibility summary for the current member, but label both as proposals rather than facts.",
         "- Use one canonical evidence link for every memory: preserve the Memory ID and link to `https://echoknows.com/memory/<memory-id>`. The site resolves the authorized representation: an owner is sent to their private timeline, while current group/friend access opens an authorized publication snapshot or public memory. The visible Markdown label should use the memory key, not the raw URL or UUID.",
         "- If the user asks to flag memories about a sensitive topic, search their own memories first, show the exact matches with owner-only personal links, and ask them to confirm. Only then call `flag_memories_for_publication_attention`; flagging does not publish, decrypt, change visibility, or retract an existing group snapshot.",
         "- Present the proposed title/responsibility and the memory publication preview together and ask for explicit confirmation. Never save an inferred profile or publish memories before confirmation. If an unflagged candidate appears sensitive, proactively ask whether the user wants to mark its exact ID for publication attention first. Explain naturally: marking does not publish or change encryption; it means you will call it out and ask for detailed confirmation whenever a later publication includes it. Never auto-flag based on agent inference. Show already-flagged candidates in a separate warning, state that nothing has been published yet, and offer three choices: exclude them, review them separately, or first search for and mark similar sensitive owned memories for publication attention.",
         "- On confirmation, call `update_group_profile` with the confirmed title, responsibility summary, and `confirmed: true`, then call `complete_group_publication` with the exact `scanId`, selected memory IDs, and `confirmed: true`. If a flagged memory is selected, require separate explicit acknowledgement and pass its exact ID in `acknowledgedFlaggedMemoryIds`. If the user edits either proposal, use their wording. An explicit request to join and upload still requires this preview and confirmation.",
-        "- If the user asks to show, reopen, restart, or bring back the EchoMem HUD (the context-health overlay), run the shell command `echomem-hud app --client auto`.",
-        "- If the user wants the HUD to come back after a computer restart, run the shell command `echomem-hud autostart on --client auto`.",
         AGENTS_MD_END,
     ].join("\n");
 }
@@ -1312,20 +1310,99 @@ function forensicStageLabel(stage) {
 /** Build the local forensic "Context Doctor" report on a worker thread so the multi-file scan never
  * blocks the bridge's event loop (the freeze postmortem: any unbounded sync work on this path is risky). */
 export function buildForensicReportOffThread(onProgress, options = {}) {
+    let lastProgress = null;
+    const recordProgress = (progress) => {
+        lastProgress = progress;
+        onProgress?.(progress);
+    };
+    return runForensicReportWorker(recordProgress, options).catch(async (primaryError) => {
+        if (options.failOpen === false)
+            throw primaryError;
+        const failureCode = errorCode(primaryError) || "REPORT_BUILD_FAILED";
+        console.error(`[echomem] local scan degraded after ${failureCode}; continuing without local-history analysis`);
+        onProgress?.({
+            done: lastProgress?.done || 0,
+            total: lastProgress?.total || 0,
+            stage: "finalizing-report",
+            detail: "finishing setup without optional local-history analysis",
+            overall: 0.99,
+            stageDone: 0,
+            stageTotal: 0,
+        });
+        return runForensicReportWorker(undefined, {
+            timeoutMs: 30_000,
+            maxOldGenerationSizeMb: Math.max(64, options.maxOldGenerationSizeMb || 0),
+        }, [], failureCode);
+    });
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : "";
+}
+/** Turn an optional onboarding-stats failure into a terminal, non-polling payload.
+ *
+ * This must only be used for dashboard enrichment. Authentication, consent, vault access, and an
+ * import the user explicitly started retain their normal hard-failure behavior. The reason is a
+ * stable internal code rather than an exception message, so local paths or conversation details
+ * can never cross the localhost bridge by accident. */
+export function completeOptionalStatsPayload(payload, reason, countsTrusted) {
+    const fallback = {
+        schemaVersion: 1,
+        generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+        llmCallsUsed: 0,
+        transcriptsUploaded: false,
+        sessions: { total: 0, codex: 0, claudeCode: 0 },
+        migratable: { pending: 0, alreadyMigrated: 0 },
+        memoriesCaptured: null,
+    };
+    const completed = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? { ...payload }
+        : fallback;
+    delete completed.partial;
+    completed.optionalDiagnostics = {
+        degraded: true,
+        reason: /^[A-Z0-9_]+$/.test(reason) ? reason : "OPTIONAL_STATS_FAILED",
+        countsTrusted,
+    };
+    return completed;
+}
+function runForensicReportWorker(onProgress, options, sources, degradedReason) {
     const forensicsUrl = runtimeModuleUrl("forensics");
+    const serializedSources = sources === undefined ? "undefined" : JSON.stringify(sources);
+    const serializedDegradedReason = JSON.stringify(degradedReason || "");
     const code = `
     import { parentPort } from "node:worker_threads";
-    import { buildForensicReport } from ${JSON.stringify(forensicsUrl)};
+    import { buildForensicReport, validateForensicReportForSetup } from ${JSON.stringify(forensicsUrl)};
     try {
       const report = await buildForensicReport({
+        sources: ${serializedSources},
         includeLegacyGoldenStandard: false,
         onProgress: (done, total, stage, detail, overall, stageDone, stageTotal) => parentPort?.postMessage({
           progress: { done, total, stage, detail, overall, stageDone, stageTotal },
         }),
       });
+      const degradedReason = ${serializedDegradedReason};
+      if (degradedReason) {
+        report.scanDiagnostics = {
+          degraded: true,
+          reason: degradedReason,
+          skippedSources: ["codex", "claude"],
+        };
+      }
+      const validation = validateForensicReportForSetup(report);
+      if (!validation.ok) {
+        const error = new Error(validation.message);
+        error.code = validation.code;
+        throw error;
+      }
       parentPort?.postMessage({ ok: true, report });
     } catch (error) {
-      parentPort?.postMessage({ ok: false, message: error instanceof Error ? error.message : String(error) });
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        code: error && typeof error === "object" && "code" in error ? String(error.code || "") : "",
+      });
     }
   `;
     const requestedHeapMb = options.maxOldGenerationSizeMb;
@@ -1369,7 +1446,10 @@ export function buildForensicReportOffThread(onProgress, options = {}) {
                 finish({ ok: true, report: msg.report });
                 return;
             }
-            finish({ ok: false, error: new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed") });
+            const error = new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed");
+            if (typeof msg.code === "string" && msg.code)
+                error.code = msg.code;
+            finish({ ok: false, error });
         });
         worker.once("error", (error) => {
             finish({ ok: false, error });
@@ -2622,19 +2702,20 @@ async function cmdSetup(flags) {
     else {
         await cmdLogin(flags);
     }
-    if (flags["with-hud"])
-        await cmdSetupHud(flags);
+    if (flags["with-hud"]) {
+        console.log("ℹ️  The standalone EchoMem HUD has been retired. Echo Desktop now owns setup and status.");
+    }
 }
 /**
  * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
  * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), installs EchoMem's
- * Codex skills, writes the AGENTS.md memory guidance, and launches the context HUD. One browser
+ * Codex skills and writes the AGENTS.md memory guidance. One browser
  * bridge then runs permission → report → login → plan if needed → extraction in that order.
  * `setup`/`login`/`update` remain granular primitives; init picks the full product defaults.
  */
 async function cmdInit(flags) {
-    console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
-    // 1. Configure every installed agent + write AGENTS.md. Hold login + HUD so we control ordering.
+    console.log("Setting up EchoMem — shared memory for all your coding agents.\n");
+    // 1. Configure every installed agent + write AGENTS.md. Hold login so we control ordering.
     await cmdSetup({
         ...flags,
         all: true,
@@ -2643,10 +2724,7 @@ async function cmdInit(flags) {
         "init-quiet": true,
         "install-save-hooks": flags["no-save-hooks"] !== true,
     });
-    // 2. Bring the HUD up NOW (non-blocking) so everything is already running while onboarding proceeds.
-    if (!flags["no-hud"])
-        await cmdSetupHud(flags);
-    // 3. Start one ordered onboarding bridge. A fresh device logs in only after consent + report.
+    // 2. Start one ordered onboarding bridge. A fresh device logs in only after consent + report.
     console.log("");
     if (!flags["skip-login"] && !flags["no-login"] && !await cmdOnboarding(flags)) {
         console.log("\nEchoMem is configured, but onboarding did not finish. Run `echomem-mcp init` again when you are ready.");
@@ -2655,13 +2733,7 @@ async function cmdInit(flags) {
     console.log("");
     console.log("🎉 EchoMem is ready.");
     console.log("   • MCP memory is configured for every coding agent installed on this machine.");
-    if (!flags["no-hud"]) {
-        console.log('   • The context HUD is running (top-right). Right-click it → "Show after restart" to keep it,');
-        console.log('     or just tell your agent "open the EchoMem HUD" anytime (it runs: echomem-hud app).');
-    }
-    else {
-        console.log('   • Start the context HUD anytime with: echomem-hud app');
-    }
+    console.log("   • Echo Desktop shows connection status and manages this device credential.");
     console.log('   • Try it now: ask your agent — "search my EchoMem for what I\'ve been working on and recap it."');
 }
 /**
@@ -2744,55 +2816,6 @@ function selectSetupTargets(requested, all) {
     }
     return requested ? knownClients().filter((client) => client.id === requested) : detectClients();
 }
-async function cmdSetupHud(flags) {
-    const client = parseHudClient(flags["hud-client"] || "auto");
-    const hudCli = resolveHudCliPath();
-    console.log("");
-    console.log(`✅ EchoMem HUD available: ${process.execPath} ${hudCli}`);
-    if (flags["install-hud-hooks"]) {
-        const paths = installHooks(client === "claude-desktop" ? "auto" : client);
-        console.log(`✅ Installed EchoMem HUD hook support:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
-        console.log("   Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
-    }
-    else {
-        console.log("ℹ️  HUD hooks not installed. Add --install-hud-hooks if you want lifecycle wakeups.");
-    }
-    if (!flags["no-launch-hud"]) {
-        try {
-            spawn(process.execPath, [hudCli, "app", "--client", client], { stdio: "ignore", detached: true }).unref();
-            console.log("✅ Launched EchoMem HUD app.");
-        }
-        catch {
-            console.log(`ℹ️  Could not auto-launch HUD. Run: echomem-hud app --client ${client}`);
-        }
-    }
-    else {
-        console.log(`Run the HUD later with: echomem-hud app --client ${client}`);
-    }
-}
-function resolveHudCliPath() {
-    const entry = fs.realpathSync(process.argv[1] || "");
-    const compiledEntry = compiledDistPathForSource(entry);
-    if (compiledEntry) {
-        const compiledHud = path.join(path.dirname(compiledEntry), "hud", "cli.js");
-        if (fs.existsSync(compiledHud))
-            return compiledHud;
-    }
-    const base = path.dirname(entry);
-    const candidate = path.join(base, "hud", "cli.js");
-    if (fs.existsSync(candidate))
-        return candidate;
-    const sourceCandidate = path.join(base, "hud", "cli.ts");
-    if (fs.existsSync(sourceCandidate)) {
-        throw new Error("The local HUD CLI is not built. Run npm --prefix packages/mcp-server run build and retry.");
-    }
-    return candidate;
-}
-function parseHudClient(value) {
-    return value === "codex" || value === "claude-code" || value === "claude-desktop" || value === "both" || value === "auto"
-        ? value
-        : "auto";
-}
 function localBridgeOptions(flags) {
     const port = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
     if (port !== undefined && (!Number.isInteger(port) || port < 1024 || port > 65535)) {
@@ -3065,7 +3088,23 @@ async function cmdOnboarding(flags) {
             extracted: 0,
         });
     };
-    const refreshLocalStatsForToken = async (activeToken) => {
+    const publishOptionalStatsFallback = (generation, reason, countsTrusted) => {
+        if (generation !== refreshGeneration)
+            return;
+        stats = completeOptionalStatsPayload(stats, reason, countsTrusted);
+        srv.setStats(stats);
+        const pending = countsTrusted ? latestPendingEstimate : 0;
+        srv.setProgress({
+            status: "idle",
+            total: pending,
+            completed: 0,
+            running: 0,
+            queued: pending,
+            failed: 0,
+            extracted: 0,
+        });
+    };
+    const refreshLocalStatsForTokenCore = async (activeToken) => {
         const generation = ++refreshGeneration;
         lastProcessedImportKeys = null; // shared with /migrate so it can assemble only the pending sessions
         let importStatusUnavailable = false;
@@ -3270,15 +3309,31 @@ async function cmdOnboarding(flags) {
                     return;
                 stats = fullPayload;
                 srv.setStats(fullPayload);
-            })();
+            })().catch((e) => {
+                if (generation !== refreshGeneration)
+                    return;
+                console.error(`[echomem] optional full local-history stats unavailable; continuing (${errorCode(e) || "FULL_STATS_FAILED"})`);
+                publishOptionalStatsFallback(generation, "FULL_STATS_FAILED", true);
+            });
             return initialExact;
         }).catch((e) => {
             if (generation === refreshGeneration) {
-                console.error(`Could not finish exact local extraction estimate: ${e instanceof Error ? e.message : String(e)}`);
+                console.error(`[echomem] optional exact local-history discovery unavailable; continuing (${errorCode(e) || "EXACT_DISCOVERY_FAILED"})`);
+                publishOptionalStatsFallback(generation, "EXACT_DISCOVERY_FAILED", false);
             }
             return disc;
         });
     };
+    const refreshLocalStatsForToken = async (activeToken) => {
+        const expectedGeneration = refreshGeneration + 1;
+        try {
+            await refreshLocalStatsForTokenCore(activeToken);
+        }
+        catch (e) {
+            console.error(`[echomem] optional local-history stats unavailable; continuing (${errorCode(e) || "OPTIONAL_STATS_FAILED"})`);
+            publishOptionalStatsFallback(expectedGeneration, "OPTIONAL_STATS_FAILED", false);
+        }
+    };
     srv.setLogoutHandler(resetLocalLoginState);
     srv.setTokenRefreshHandler(async ({ token: nextToken, key: nextKey }) => {
         if (!await verifyAndPrint({ token: nextToken, key: nextKey }))
@@ -3714,14 +3769,13 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
-  echomem-mcp init                  One command: configure agents + HUD + login + local-history onboarding
+  echomem-mcp init                  Legacy/headless setup: configure agents + login + local-history onboarding
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then connect this device
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
   echomem-mcp setup --no-codex-skills  Skip installing the bundled EchoMem Codex skills
   echomem-mcp update --all          Install this bridge durably + repoint detected clients; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser
-  echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
   echomem-mcp login                 Connect this device only; never scans or imports local history
   echomem-mcp login --force         Reconnect this device with a different account
   echomem-mcp unlock                Privately unlock the vault on this trusted device
@@ -3744,7 +3798,6 @@ Manual / headless:
   ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
   ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
-  echomem-mcp setup --with-hud --install-hud-hooks --install-save-hooks --client codex [--hud-client auto]
   echomem-mcp setup --install-save-hooks --all  Install proactive private-save completion checks
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 

package/dist/v1-contract.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
+import { MCP_DESKTOP_MANAGED, MCP_VAULT_UNLOCK_INSTRUCTION, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
 export const canonicalToolNames = {
     search: "search_memories",
     save: "save_conversation",
@@ -388,7 +388,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to run \`echomem-mcp unlock\` and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing, request_group_session_sharing, or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, call request_group_session_sharing so supported hosts render a choice UI; its fallback tells you when a text Yes/No prompt is required. Silence leaves consent unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
+            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to ${MCP_VAULT_UNLOCK_INSTRUCTION} and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing, request_group_session_sharing, or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, call request_group_session_sharing so supported hosts render a choice UI; its fallback tells you when a text Yes/No prompt is required. Silence leaves consent unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -909,11 +909,11 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
-            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} 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. ${memoryCitationInstruction} Current time: ${currentTime}.`),
+            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} Use this when the user or EchoMem returns 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. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {
-                    contextId: { type: "string", description: "The EchoMem contextId shown by the HUD or returned by save_conversation / Renew session." },
+                    contextId: { type: "string", description: "The EchoMem contextId returned by save_conversation or Renew session." },
                     limit: { type: "number", default: 100 },
                     triggerMessage: {
                         type: "string",
@@ -931,7 +931,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.updateStatus,
-            description: `Check whether this installed EchoMem MCP bridge is behind the latest published npm version. Works without login, uploads no user transcript, and normal background checks are cached so EchoMem does not hit npm on every startup. If it reports an update, tell the user and offer to run the returned update command; after updating, the user must start a new agent/MCP session.${updateSection}`,
+            description: `Check whether this installed EchoMem MCP bridge is behind the latest version. Works without login, uploads no user transcript, and normal background checks are cached. ${MCP_DESKTOP_MANAGED ? "Echo Desktop owns updates for this runtime; direct the user back to the desktop app." : "If it reports an update, tell the user and offer to run the returned update command."} After updating, the user must start a new agent/MCP session.${updateSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -945,7 +945,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.contextHealth,
-            description: "Show the current local Codex/Claude context-health score as markdown: clean percentage, tracked lower-bound dead-weight, redundant reads, source client, and token-count source. Use when the user asks about the context HUD, dirty context, context pollution, whether cleanup is worth it, or wants an in-chat fallback to the passive HUD. This reads local agent logs only and needs no login.",
+            description: "Show the current local Codex/Claude context-health score as markdown: clean percentage, tracked lower-bound dead-weight, redundant reads, source client, and token-count source. Use when the user asks about dirty context, context pollution, or whether cleanup is worth it. This on-demand tool reads local agent logs only and needs no login.",
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.34",
-  "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
+  "version": "1.4.35",
+  "description": "EchoMem MCP bridge: cloud-first memory tools and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
+  "echoDesktop": {
+    "minimumVersion": "1.0.0",
+    "runtimeLayout": 1
+  },
   "bin": {
     "mcp": "dist/index.js",
-    "echomem-mcp": "dist/index.js",
-    "echomem-hud": "dist/hud/cli.js"
+    "echomem-mcp": "dist/index.js"
   },
   "files": [
     "dist",
@@ -23,22 +26,24 @@
     "smoke": "node smoke.mjs",
     "preview:extraction": "npm run build && node scripts/preview-extraction.mjs",
     "stress:long-history": "npm run build && node scripts/stress-long-history.mjs",
+    "stress:long-claude-history": "npm run build && node scripts/stress-long-claude-history.mjs",
     "test:artifact": "npm run build && node test/package-artifact.test.mjs",
     "test:registry": "node test/registry-artifact.test.mjs",
     "test:registry-ui": "npm run build && node test/registry-ui.test.mjs",
     "test:ui": "npm run build && node test/setup-ui.test.mjs",
+    "test:onboarding-resilience": "npm run build && node test/onboarding-resilience.test.mjs",
     "test:billing-ui": "npm run build && node test/setup-ui.test.mjs billing",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/hud.test.mjs && node test/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
     "axios": "^1.6.8",
-    "electron": "41.7.1",
     "zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
+    "electron": "41.7.1",
     "tsx": "^4.22.4",
     "typescript": "^5.3.3"
   }