@echomem/mcp 1.4.48 → 1.4.50

package/dist/durable-entry.js

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation } from "./headless-runtime.js";
+import { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION } from "./package-metadata.js";
+/**
+ * Resolving a DURABLE path to this package's own files.
+ *
+ * Anything we write into another program's config — an MCP server entry, a lifecycle hook command —
+ * outlives the process that wrote it. Pinning such a path to the npx cache (`…/_npx/<hash>/…`) works
+ * until npm garbage-collects that directory, after which the entry silently points at nothing. So
+ * prefer, in order: the managed runtime under ~/.echomem, the running copy when it is not itself
+ * ephemeral, then a global install.
+ */
+/** True when a resolved entry lives inside npx's throwaway cache (`…/_npx/<hash>/…`). */
+export function isEphemeralNpxPath(entry) {
+    return entry.split(path.sep).includes("_npx");
+}
+/**
+ * Locate a DURABLE global install of the bridge (the one `npm i -g @echomem/mcp` creates). Global
+ * modules sit next to the running node — `<node>/../lib/node_modules` (nvm/unix) or `<node>/node_modules`
+ * (Windows). Returns the realpath'd dist entry, or null when the package isn't globally installed.
+ */
+export function resolveGlobalEntry() {
+    const nodeDir = path.dirname(process.execPath);
+    const pkgParts = MCP_PACKAGE_NAME.split("/"); // ["@echomem", "mcp"]
+    const candidates = [
+        path.join(nodeDir, "..", "lib", "node_modules", ...pkgParts, "dist", "index.js"),
+        path.join(nodeDir, "node_modules", ...pkgParts, "dist", "index.js"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(candidate))
+                return fs.realpathSync(candidate);
+        }
+        catch {
+            /* keep trying */
+        }
+    }
+    return null;
+}
+/** The dist directory this module was loaded from. */
+function runningDistDir() {
+    return fileURLToPath(new URL("./", import.meta.url));
+}
+/**
+ * Absolute path to `dist/<relative>` from the most durable copy of this package available.
+ *
+ * `ephemeral` in the result flags the last-resort case: no durable copy exists, so the caller is
+ * about to persist a path that npm may collect. A working hook now beats no hook at all, but the
+ * caller should say so rather than fail silently.
+ */
+export function resolveDurableDistPath(relative) {
+    const managed = readHeadlessRuntimeInstallation();
+    if (managed?.entry) {
+        const candidate = path.join(path.dirname(managed.entry), relative);
+        if (fs.existsSync(candidate))
+            return { path: candidate, ephemeral: false };
+    }
+    const local = path.join(runningDistDir(), relative);
+    const localIsEphemeral = isEphemeralNpxPath(local);
+    if (!localIsEphemeral && fs.existsSync(local))
+        return { path: local, ephemeral: false };
+    const globalEntry = resolveGlobalEntry();
+    if (globalEntry) {
+        const candidate = path.join(path.dirname(globalEntry), relative);
+        if (fs.existsSync(candidate))
+            return { path: candidate, ephemeral: false };
+    }
+    return { path: local, ephemeral: localIsEphemeral };
+}
+/** Set on the child so a re-exec can never recurse. */
+const REEXEC_GUARD = "ECHO_DURABLE_REEXEC";
+/**
+ * Hand a config-writing command over to the durable runtime before it writes anything.
+ *
+ * `npx @echomem/mcp init` runs from `_npx/<hash>`, a directory npm garbage-collects. Every path such
+ * a process persists into someone else's config — hook commands, MCP entries — inherits that
+ * lifetime. Re-executing from `~/.echomem/mcp-runtime` first makes those writes durable by
+ * construction, instead of relying on each call site to remember.
+ *
+ * Version skew is resolved by upgrading rather than skipping: the durable copy is installed at the
+ * invoking package's version before control passes to it, so a newer `npx` never hands off to an
+ * older runtime. Installation is idempotent, so the child re-verifying costs nothing.
+ *
+ * Returns the child's exit status when it ran (the caller should exit with it), or null when the
+ * command should proceed in this process. Every failure path returns null: a re-exec that cannot
+ * happen must degrade to the old behaviour, never dead-end.
+ */
+export function reexecFromDurableRuntime(argv) {
+    if (process.env[REEXEC_GUARD] === "1")
+        return null;
+    if (process.env.ECHO_DISABLE_RUNTIME_BOOTSTRAP === "1")
+        return null;
+    if (!isEphemeralNpxPath(runningDistDir()))
+        return null;
+    // Version comes from the package.json beside dist/. If that could not be read we would ask the
+    // registry for a version that does not exist, so stay in-process rather than spend the round trip.
+    if (MCP_PACKAGE_VERSION === "0.0.0")
+        return null;
+    let installation = readHeadlessRuntimeInstallation();
+    if (installation?.version !== MCP_PACKAGE_VERSION) {
+        try {
+            installation = installHeadlessRuntimeSync(MCP_PACKAGE_VERSION);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!installation?.entry || !fs.existsSync(installation.entry))
+        return null;
+    console.log(`Running from the durable ${MCP_PACKAGE_NAME}@${installation.version} runtime so configured paths outlive the npx cache.`);
+    const result = spawnSync(process.execPath, [installation.entry, ...argv], {
+        stdio: "inherit",
+        env: { ...process.env, [REEXEC_GUARD]: "1" },
+        windowsHide: true,
+    });
+    if (result.error)
+        return null;
+    return result.status ?? 0;
+}

package/dist/hud/hooks.js

@@ -1,7 +1,20 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveDurableDistPath } from "../durable-entry.js";
+/**
+ * Hook commands are persisted into another program's settings and must keep working long after this
+ * process exits. Resolving them from `import.meta.url` pins them to whatever copy happens to be
+ * running — under `npx` that is the `_npx/<hash>` cache, which npm garbage-collects, leaving a hook
+ * that points at nothing. Always resolve through the durable-entry helper instead.
+ */
+function hookCommandFor(distRelative, subcommand) {
+    const cli = resolveDurableDistPath(distRelative);
+    if (cli.ephemeral) {
+        console.warn(`⚠️  EchoMem hooks are being pinned to a temporary npx path (${cli.path}). They will stop working once npm clears its cache — install the durable runtime or a global package to make them permanent.`);
+    }
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(cli.path)} ${subcommand}`;
+}
 export function installHooks(mode) {
     const written = [];
     if (mode === "codex" || mode === "both" || mode === "auto") {
@@ -36,7 +49,7 @@ function installCodexHooks() {
     const dir = path.join(os.homedir(), ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
-    const hookCommand = `${JSON.stringify(process.execPath)} ${JSON.stringify(process.argv[1])} summary --client codex --json`;
+    const hookCommand = hookCommandFor("index.js", "summary --client codex --json");
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
@@ -46,12 +59,10 @@ function installCodexHooks() {
     return file;
 }
 function saveCheckpointCommand() {
-    const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
-    return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} save-checkpoint`;
+    return hookCommandFor(path.join("hud", "cli.js"), "save-checkpoint");
 }
 function sourceSessionCommand() {
-    const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
-    return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} bind-source-session`;
+    return hookCommandFor(path.join("hud", "cli.js"), "bind-source-session");
 }
 function installCodexSourceSessionHook() {
     const dir = path.join(os.homedir(), ".codex");

package/dist/local-data-paths.js

@@ -85,41 +85,80 @@ export function resolveClaudeProjectsDir(opts = {}) {
     const root = configuredRoot("CLAUDE_CONFIG_DIR", ".claude", opts);
     return resolveReadableDirectory(root ? path.join(root, "projects") : null);
 }
-/**
- * Resolve Claude Desktop's local Cowork sandbox root.
- *
- * Cowork does not write into the normal `~/.claude/projects` profile. Claude Desktop creates an
- * OS-specific support directory and stores each local-agent session below
- * `local-agent-mode-sessions/<org>/<conversation>/local_<id>/`. The actual transcript is nested
- * again under that sandbox's `.claude/projects` directory.
- */
-export function resolveClaudeCoworkSessionsDir(opts = {}) {
+/** Resolve every readable Claude Desktop support directory, including Windows Store/MSIX data. */
+export function resolveClaudeDesktopSupportRoots(opts = {}) {
     const homeDir = normalizedHomeDir(opts.homeDir ?? os.homedir());
     if (!homeDir)
-        return null;
+        return [];
     const env = opts.env ?? process.env;
     const configured = env.CLAUDE_DESKTOP_SUPPORT_DIR;
-    let supportRoot = null;
+    const platform = opts.platform ?? process.platform;
+    const candidates = [];
     if (typeof configured === "string" && configured.trim()) {
-        supportRoot = expandCurrentUserHome(configured, homeDir);
+        candidates.push(expandCurrentUserHome(configured, homeDir));
     }
-    else {
-        const platform = opts.platform ?? process.platform;
-        if (platform === "darwin") {
-            supportRoot = path.join(homeDir, "Library", "Application Support", "Claude");
-        }
-        else if (platform === "win32") {
-            const appData = typeof env.APPDATA === "string" && env.APPDATA.trim()
-                ? expandCurrentUserHome(env.APPDATA, homeDir)
-                : path.join(homeDir, "AppData", "Roaming");
-            supportRoot = appData ? path.join(appData, "Claude") : null;
-        }
-        else {
-            const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
-                ? expandCurrentUserHome(env.XDG_CONFIG_HOME, homeDir)
-                : path.join(homeDir, ".config");
-            supportRoot = configHome ? path.join(configHome, "Claude") : null;
+    else if (platform === "darwin") {
+        candidates.push(path.join(homeDir, "Library", "Application Support", "Claude"));
+    }
+    else if (platform === "win32") {
+        const appData = typeof env.APPDATA === "string" && env.APPDATA.trim()
+            ? expandCurrentUserHome(env.APPDATA, homeDir)
+            : path.join(homeDir, "AppData", "Roaming");
+        if (appData)
+            candidates.push(path.join(appData, "Claude"));
+        const localAppData = typeof env.LOCALAPPDATA === "string" && env.LOCALAPPDATA.trim()
+            ? expandCurrentUserHome(env.LOCALAPPDATA, homeDir)
+            : path.join(homeDir, "AppData", "Local");
+        if (localAppData) {
+            const packagesRoot = path.join(localAppData, "Packages");
+            try {
+                for (const entry of fs.readdirSync(packagesRoot, { withFileTypes: true })) {
+                    if (!entry.isDirectory() || !/^Claude_/i.test(entry.name))
+                        continue;
+                    candidates.push(path.join(packagesRoot, entry.name, "LocalCache", "Roaming", "Claude"));
+                }
+            }
+            catch {
+                /* A non-Store install has no Packages directory. */
+            }
         }
     }
-    return resolveReadableDirectory(supportRoot ? path.join(supportRoot, "local-agent-mode-sessions") : null);
+    else {
+        const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+            ? expandCurrentUserHome(env.XDG_CONFIG_HOME, homeDir)
+            : path.join(homeDir, ".config");
+        if (configHome)
+            candidates.push(path.join(configHome, "Claude"));
+    }
+    const roots = [];
+    const seenRealpaths = new Set();
+    for (const candidate of candidates) {
+        const resolved = resolveReadableDirectory(candidate);
+        if (!resolved || seenRealpaths.has(resolved))
+            continue;
+        seenRealpaths.add(resolved);
+        roots.push(resolved);
+    }
+    return roots;
+}
+/**
+ * Resolve every Claude Desktop Cowork sandbox root. Cowork transcripts live below
+ * `local-agent-mode-sessions/<org>/<conversation>/local_<id>/.claude/projects`; Windows Store
+ * installs can have several private Claude package containers below `Packages`.
+ */
+export function resolveClaudeCoworkSessionRoots(opts = {}) {
+    const roots = [];
+    const seenRealpaths = new Set();
+    for (const supportRoot of resolveClaudeDesktopSupportRoots(opts)) {
+        const resolved = resolveReadableDirectory(path.join(supportRoot, "local-agent-mode-sessions"));
+        if (!resolved || seenRealpaths.has(resolved))
+            continue;
+        seenRealpaths.add(resolved);
+        roots.push(resolved);
+    }
+    return roots;
+}
+/** Backward-compatible first-root resolver. New discovery code should scan every returned root. */
+export function resolveClaudeCoworkSessionsDir(opts = {}) {
+    return resolveClaudeCoworkSessionRoots(opts)[0] ?? null;
 }

package/dist/migrate.js

@@ -29,7 +29,7 @@ import axios from "axios";
 import { KeyStore, echoConfigDir } from "./keystore.js";
 import { fetchEncryptionConfig } from "./encryption.js";
 import { discoverCodexSessionFiles } from "./codex-session-files.js";
-import { resolveClaudeCoworkSessionsDir, resolveClaudeProjectsDir } from "./local-data-paths.js";
+import { resolveClaudeCoworkSessionRoots, resolveClaudeProjectsDir } from "./local-data-paths.js";
 import { eachJsonLine, walkLocalFiles } from "./local-jsonl.js";
 const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const RATE_MAX = 28; // stay under the import-jobs /run limit of 30 / 60s
@@ -232,10 +232,7 @@ function claudeSessionCandidates(opts = {}) {
     // Supplying an explicit Claude root is an isolated discovery request (tests, diagnostics, or a
     // moved profile). Callers can still add Cowork roots explicitly. Normal onboarding supplies no
     // roots, so the platform-default Cowork directory is included automatically.
-    const defaultCoworkRoot = opts.claudeRoot === undefined
-        ? resolveClaudeCoworkSessionsDir()
-        : null;
-    const coworkRoots = opts.coworkRoots ?? (defaultCoworkRoot ? [defaultCoworkRoot] : []);
+    const coworkRoots = opts.coworkRoots ?? (opts.claudeRoot === undefined ? resolveClaudeCoworkSessionRoots() : []);
     for (const root of coworkRoots) {
         for (const filePath of userCreatedClaudeFiles(root)) {
             const conversationId = coworkConversationId(filePath, root);
@@ -323,16 +320,49 @@ function hasClaudeText(content) {
         return false;
     return content.some((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0);
 }
+/**
+ * True when this turn opens the conversation rather than continuing one.
+ *
+ * `parentUuid === null` is the common case, but a session started by dropping in a file opens with
+ * an `attachment` record and parents its first real turn to that — requiring a null parent silently
+ * discarded those whole transcripts. Walk the chain instead: a turn opens the conversation when
+ * nothing conversational precedes it in this file. A parent the file does not contain means the
+ * thread continues from somewhere else, which is not a user-created session.
+ */
+function startsConversation(obj, byUuid) {
+    let parentUuid = obj.parentUuid;
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (parentUuid === null || parentUuid === undefined)
+            return true;
+        if (typeof parentUuid !== "string")
+            return false;
+        const parent = byUuid.get(parentUuid);
+        if (!parent)
+            return false;
+        if (parent.type === "user" || parent.type === "assistant")
+            return false;
+        parentUuid = parent.parentUuid;
+    }
+    return false; // pathological chain; treat as not session-initiating rather than loop
+}
 function isUserCreatedClaudeSessionFile(file) {
-    return initialJsonObjects(file).some((obj) => {
-        if (!isRecord(obj) || obj.type !== "user")
+    const objects = initialJsonObjects(file).filter(isRecord);
+    const byUuid = new Map();
+    for (const obj of objects) {
+        if (typeof obj.uuid === "string" && obj.uuid)
+            byUuid.set(obj.uuid, obj);
+    }
+    return objects.some((obj) => {
+        if (obj.type !== "user")
             return false;
-        if (obj.userType !== "external" || obj.isSidechain !== false || obj.parentUuid !== null)
+        if (obj.userType !== "external" || obj.isSidechain !== false)
             return false;
         if (obj.isMeta === true || obj.isCompactSummary === true)
             return false;
         if (typeof obj.agentId === "string" && obj.agentId.trim())
             return false;
+        if (!startsConversation(obj, byUuid))
+            return false;
         const message = isRecord(obj.message) ? obj.message : {};
         return hasClaudeText(message.content);
     });

package/dist/setup.js

@@ -26,10 +26,12 @@ import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, setupNewEncryptionKey, verifyKeyB64 } from "./encryption.js";
 import { buildOnboardingStatsPayload } from "./onboarding-stats.js";
-import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableSessions, discoverPendingSessionsTargeted, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, MIGRATE_CONCURRENCY, } from "./migrate.js";
+import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableSessions, discoverPendingSessionsTargeted, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, discoverSessions, dedupeSessionsByConversation, MIGRATE_CONCURRENCY, } from "./migrate.js";
 import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
+import { resolveClaudeCoworkSessionRoots, resolveClaudeDesktopSupportRoots, resolveClaudeProjectsDir, resolveCodexSessionRoots, } from "./local-data-paths.js";
+import { isEphemeralNpxPath, reexecFromDurableRuntime, resolveDurableDistPath, resolveGlobalEntry } from "./durable-entry.js";
 import { installSaveCheckpointHooks, installSourceSessionHooks } 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";
@@ -215,28 +217,76 @@ function runtimeModuleUrl(name) {
     }
     return jsUrl.href;
 }
+function claudeDesktopRootHasBundledCode(supportRoot, platform) {
+    return versionedClaudeCodeExecutables(path.join(supportRoot, "claude-code"), platform === "win32" ? "claude.exe" : "claude", 1).length > 0;
+}
+/**
+ * Config targeting needs installation evidence; history discovery intentionally does not.
+ * A stale support directory can still contain importable Cowork history, but must not make setup
+ * claim that Claude Desktop is installed. An explicit support-root override is itself evidence.
+ */
+export function claudeDesktopConfigRoots(defaultRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? os.homedir();
+    const supportRoots = resolveClaudeDesktopSupportRoots(options);
+    if (env.CLAUDE_DESKTOP_SUPPORT_DIR?.trim())
+        return supportRoots;
+    if (platform === "darwin") {
+        const installed = [
+            "/Applications/Claude.app",
+            path.join(homeDir, "Applications", "Claude.app"),
+        ].some((appPath) => fs.existsSync(appPath));
+        if (!installed)
+            return [];
+        return supportRoots.length > 0 ? supportRoots : [defaultRoot];
+    }
+    return supportRoots.filter((supportRoot) => claudeDesktopRootHasBundledCode(supportRoot, platform));
+}
 /** Known clients and where their MCP server map lives. */
 export function knownClients() {
     const appSupport = process.platform === "darwin"
         ? home("Library", "Application Support")
         : process.env.APPDATA || home(".config");
+    const defaultClaudeDesktopRoot = path.join(appSupport, "Claude");
+    const claudeDesktopRoots = claudeDesktopConfigRoots(defaultClaudeDesktopRoot);
+    const claudeDesktopClients = (claudeDesktopRoots.length > 0 ? claudeDesktopRoots : [defaultClaudeDesktopRoot]).map((supportRoot) => ({
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        kind: "json",
+        configPath: path.join(supportRoot, "claude_desktop_config.json"),
+        detected: claudeDesktopRoots.length > 0,
+    }));
     return [
         { id: "cursor", label: "Cursor", kind: "json", configPath: home(".cursor", "mcp.json") },
         { id: "windsurf", label: "Windsurf", kind: "json", configPath: home(".codeium", "windsurf", "mcp_config.json") },
-        { id: "claude-desktop", label: "Claude Desktop", kind: "json", configPath: path.join(appSupport, "Claude", "claude_desktop_config.json") },
+        ...claudeDesktopClients,
         { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json -s user echomem '<entry>'  (or add to .mcp.json)" },
         { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
 /** A client is "present" if its config dir already exists — a cheap, side-effect-free heuristic. */
+/**
+ * Claude Code is present when its CLI runs OR when it has left a profile behind.
+ *
+ * The CLI probe alone misses a Store-packaged Claude Desktop, whose bundled binary never reaches
+ * PATH; a profile alone used to mean "detected but unconfigurable". Now that writeClaudeCodeConfig
+ * can merge the user entry into ~/.claude.json without a CLI, a profile is enough to act on.
+ */
+export function claudeCodeInstalled() {
+    return fs.existsSync(home(".claude")) || fs.existsSync(home(".claude.json")) || claudeCodeCliAvailable();
+}
 export function detectClients() {
     return knownClients().filter((c) => {
-        if (c.kind === "json")
+        if (c.kind === "json") {
+            if (c.id === "claude-desktop")
+                return c.detected === true;
             return fs.existsSync(path.dirname(c.configPath));
+        }
         if (c.kind === "command")
             return fs.existsSync(c.detectDir);
         if (c.id === "claude-code")
-            return fs.existsSync(home(".claude"));
+            return claudeCodeInstalled();
         return false;
     });
 }
@@ -278,33 +328,6 @@ export function buildServerEntry(opts = {}) {
     // Fallback (unresolved local install): at least drop `-y` so npx doesn't auto-INSTALL on every start.
     return { command: "npx", args: ["@echomem/mcp"] };
 }
-/** True when a resolved entry lives inside npx's throwaway cache (`…/_npx/<hash>/…`). */
-function isEphemeralNpxPath(entry) {
-    return entry.split(path.sep).includes("_npx");
-}
-/**
- * Locate a DURABLE global install of the bridge (the one `npm i -g @echomem/mcp` creates). Global
- * modules sit next to the running node — `<node>/../lib/node_modules` (nvm/unix) or `<node>/node_modules`
- * (Windows). Returns the realpath'd dist entry, or null when the package isn't globally installed.
- */
-function resolveGlobalEntry() {
-    const nodeDir = path.dirname(process.execPath);
-    const pkgParts = MCP_PACKAGE_NAME.split("/"); // ["@echomem", "mcp"]
-    const candidates = [
-        path.join(nodeDir, "..", "lib", "node_modules", ...pkgParts, "dist", "index.js"),
-        path.join(nodeDir, "node_modules", ...pkgParts, "dist", "index.js"),
-    ];
-    for (const candidate of candidates) {
-        try {
-            if (fs.existsSync(candidate))
-                return fs.realpathSync(candidate);
-        }
-        catch {
-            /* keep trying */
-        }
-    }
-    return null;
-}
 function installDurableHeadlessRuntime() {
     if (process.env.ECHO_DISABLE_RUNTIME_BOOTSTRAP === "1")
         return;
@@ -543,7 +566,7 @@ function claudeCodeLocalEchoMemProjects(configPath) {
         .map(([projectPath]) => projectPath)
         .sort();
 }
-function versionedClaudeCodeExecutables(root, executable) {
+function versionedClaudeCodeExecutables(root, executable, limit = Number.POSITIVE_INFINITY) {
     let versions;
     try {
         versions = fs.readdirSync(root, { withFileTypes: true });
@@ -555,7 +578,8 @@ function versionedClaudeCodeExecutables(root, executable) {
         .filter((entry) => entry.isDirectory())
         .sort((left, right) => right.name.localeCompare(left.name, undefined, { numeric: true }))
         .map((entry) => path.join(root, entry.name, executable))
-        .filter((candidate) => fs.existsSync(candidate));
+        .filter((candidate) => fs.existsSync(candidate))
+        .slice(0, limit);
 }
 /**
  * Return every safe Claude Code launcher location worth trying. Claude Desktop bundles the CLI,
@@ -574,13 +598,13 @@ export function claudeCodeCommandCandidates(options = {}) {
     if (platform === "win32") {
         const appData = env.APPDATA?.trim() || path.join(homeDir, "AppData", "Roaming");
         const localAppData = env.LOCALAPPDATA?.trim() || path.join(homeDir, "AppData", "Local");
-        candidates.push(...versionedClaudeCodeExecutables(path.join(appData, "Claude", "claude-code"), "claude.exe"), ...versionedClaudeCodeExecutables(path.join(localAppData, "Claude", "claude-code"), "claude.exe"));
+        candidates.push(...versionedClaudeCodeExecutables(path.join(appData, "Claude", "claude-code"), "claude.exe", 1), ...versionedClaudeCodeExecutables(path.join(localAppData, "Claude", "claude-code"), "claude.exe", 1));
         const packagesRoot = path.join(localAppData, "Packages");
         try {
             for (const entry of fs.readdirSync(packagesRoot, { withFileTypes: true })) {
                 if (!entry.isDirectory() || !/^Claude_/i.test(entry.name))
                     continue;
-                candidates.push(...versionedClaudeCodeExecutables(path.join(packagesRoot, entry.name, "LocalCache", "Roaming", "Claude", "claude-code"), "claude.exe"));
+                candidates.push(...versionedClaudeCodeExecutables(path.join(packagesRoot, entry.name, "LocalCache", "Roaming", "Claude", "claude-code"), "claude.exe", 1));
             }
         }
         catch {
@@ -613,53 +637,118 @@ function escapeWindowsCmdArgument(value) {
     escaped = `"${escaped}"`;
     return escaped.replace(/([()\][%!^"`<>&|;, *?])/g, "^$1");
 }
-function execClaudeCodeSync(args, options, commandCandidates) {
+function execClaudeCodeCommandSync(command, args, options) {
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
+        const shellCommand = [escapeWindowsCmdCommand(command), ...args.map(escapeWindowsCmdArgument)].join(" ");
+        const spawnOptions = {
+            ...options,
+            windowsHide: true,
+            windowsVerbatimArguments: true,
+        };
+        const result = spawnSync(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", `"${shellCommand}"`], spawnOptions);
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0) {
+            throw new Error(result.stderr?.trim() || `Claude Code exited with status ${result.status ?? "unknown"}.`);
+        }
+        return result.stdout || "";
+    }
+    return execFileSync(command, args, process.platform === "win32" ? { ...options, windowsHide: true } : options);
+}
+function claudeCodeCommandsOnPath(timeout) {
+    if (process.platform !== "win32" || timeout <= 0)
+        return [];
+    try {
+        return execFileSync("where.exe", ["claude"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout,
+            windowsHide: true,
+        }).split(/\r?\n/).map((candidate) => candidate.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+let cachedClaudeCodeCommand = null;
+function resolveRunnableClaudeCodeCommand(commandCandidates, deadline = Date.now() + 3000) {
+    if (!commandCandidates && cachedClaudeCodeCommand)
+        return cachedClaudeCodeCommand;
     let candidates = commandCandidates ? [...commandCandidates] : claudeCodeCommandCandidates();
-    if (process.platform === "win32" && !commandCandidates) {
+    if (!commandCandidates) {
+        const remainingForPath = Math.max(1, Math.min(1000, deadline - Date.now()));
+        candidates = [...new Set([...claudeCodeCommandsOnPath(remainingForPath), ...candidates])];
+    }
+    for (const command of candidates) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
         try {
-            const pathMatches = execFileSync("where.exe", ["claude"], {
+            execClaudeCodeCommandSync(command, ["--version"], {
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "ignore"],
-                timeout: 3000,
-                windowsHide: true,
-            }).split(/\r?\n/).map((candidate) => candidate.trim()).filter(Boolean);
-            candidates = [...new Set([...pathMatches, ...candidates])];
+                timeout: remaining,
+            });
+            if (!commandCandidates)
+                cachedClaudeCodeCommand = command;
+            return command;
         }
         catch {
-            /* The bundled Desktop candidates below remain available. */
+            /* Keep trying only while the shared deadline has time left. */
         }
     }
-    let lastError = new Error("Claude Code CLI was not found.");
-    for (const command of candidates) {
-        try {
-            if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
-                const shellCommand = [escapeWindowsCmdCommand(command), ...args.map(escapeWindowsCmdArgument)].join(" ");
-                const spawnOptions = {
-                    ...options,
-                    windowsHide: true,
-                    windowsVerbatimArguments: true,
-                };
-                const result = spawnSync(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", `"${shellCommand}"`], spawnOptions);
-                if (result.error)
-                    throw result.error;
-                if (result.status !== 0) {
-                    throw new Error(result.stderr?.trim() || `Claude Code exited with status ${result.status ?? "unknown"}.`);
-                }
-                return result.stdout || "";
-            }
-            return execFileSync(command, args, process.platform === "win32" ? { ...options, windowsHide: true } : options);
-        }
-        catch (error) {
-            lastError = error;
-        }
+    return null;
+}
+function execClaudeCodeSync(args, options, commandCandidates) {
+    const probeBudget = typeof options.timeout === "number" ? Math.min(options.timeout, 3000) : 3000;
+    const command = resolveRunnableClaudeCodeCommand(commandCandidates, Date.now() + probeBudget);
+    if (!command)
+        throw new Error("Claude Code CLI was not found within the setup time budget.");
+    return execClaudeCodeCommandSync(command, args, options);
+}
+export function claudeCodeCliAvailable() {
+    return resolveRunnableClaudeCodeCommand(undefined, Date.now() + 3000) !== null;
+}
+/**
+ * Merge the user-scope EchoMem entry straight into ~/.claude.json.
+ *
+ * Reserved for machines where NO Claude Code CLI can be executed at all — a Store-packaged Claude
+ * Desktop whose bundled binary never lands on PATH, an npm shim in a stripped environment. Without
+ * this, such a machine can never be configured, even though the file is trivial to update.
+ *
+ * Deliberately narrow: read immediately before write, touch only `mcpServers.echomem`, preserve
+ * every other key (this file also holds Claude account and session state), and swap it in via a
+ * same-directory temp file so a crash cannot truncate it. Project-local entries are still left to
+ * the CLI — removing those means knowing which project a scope belongs to.
+ */
+function writeUserEntryDirectly(configPath, entry) {
+    try {
+        const raw = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8").trim() : "";
+        const parsed = raw ? JSON.parse(raw) : {};
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return false;
+        const config = parsed;
+        const existing = config.mcpServers;
+        const servers = typeof existing === "object" && existing !== null && !Array.isArray(existing)
+            ? existing
+            : {};
+        servers.echomem = entry;
+        config.mcpServers = servers;
+        const tmp = `${configPath}.echomem-${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`);
+        fs.renameSync(tmp, configPath);
+        return true;
+    }
+    catch {
+        return false;
     }
-    throw lastError;
 }
 export function writeClaudeCodeConfig(entry, options = {}) {
     // EchoMem belongs at user scope so every Claude Code project resolves the same durable runtime.
     // Older CLI versions wrote local/project entries, which take precedence over user scope and can
     // keep launching a deleted npm cache or stale runtime. Migrate those only after user scope is safe.
     const configPath = options.configPath ?? home(".claude.json");
+    const configurationDeadline = Date.now() + 5000;
     let failureReason;
     const emptyResult = () => ({
         state: "unavailable",
@@ -670,14 +759,27 @@ export function writeClaudeCodeConfig(entry, options = {}) {
         preservedDesktopManaged: false,
         failureReason,
     });
+    let runnableCommand;
+    const cliCommand = () => {
+        if (runnableCommand === undefined) {
+            runnableCommand = resolveRunnableClaudeCodeCommand(options.claudeCommands, configurationDeadline);
+        }
+        return runnableCommand;
+    };
     const runClaude = (args, cwd) => {
+        const command = cliCommand();
+        const remaining = configurationDeadline - Date.now();
+        if (!command || remaining <= 0) {
+            failureReason = "Claude Code CLI was unavailable within the onboarding time budget.";
+            return false;
+        }
         try {
-            execClaudeCodeSync(args, {
+            execClaudeCodeCommandSync(command, args, {
                 cwd,
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "pipe"],
-                timeout: 10000,
-            }, options.claudeCommands);
+                timeout: Math.min(remaining, 5000),
+            });
             failureReason = undefined;
             return true;
         }
@@ -696,16 +798,31 @@ export function writeClaudeCodeConfig(entry, options = {}) {
         && validDesktopManagedEntry(previousUserEntry);
     const desiredUserEntry = preservedDesktopManaged ? previousUserEntry : entry;
     let restoredPreviousUserEntry = false;
+    let usedDirectWrite = false;
+    const fallbackWrite = () => {
+        // A working CLI that refuses is a real failure; masking it would hide a genuine problem.
+        if (cliCommand())
+            return false;
+        if (!writeUserEntryDirectly(configPath, desiredUserEntry))
+            return false;
+        usedDirectWrite = true;
+        failureReason = undefined;
+        return true;
+    };
     // Avoid interrupting active/new sessions when the correct global entry is already installed.
     if (!claudeEntriesMatch(previousUserEntry, desiredUserEntry)) {
-        if (previousUserEntry && !removeUser())
-            return emptyResult();
-        if (!addUser(desiredUserEntry)) {
-            const addFailureReason = failureReason;
-            if (previousUserEntry)
-                restoredPreviousUserEntry = addUser(previousUserEntry);
-            failureReason = addFailureReason;
-            return { ...emptyResult(), restoredPreviousUserEntry };
+        if (previousUserEntry && !removeUser()) {
+            if (!fallbackWrite())
+                return emptyResult();
+        }
+        else if (!addUser(desiredUserEntry)) {
+            if (!fallbackWrite()) {
+                const addFailureReason = failureReason;
+                if (previousUserEntry)
+                    restoredPreviousUserEntry = addUser(previousUserEntry);
+                failureReason = addFailureReason;
+                return { ...emptyResult(), restoredPreviousUserEntry };
+            }
         }
     }
     const installedUserEntry = echoMemEntryFromServers(readClaudeCodeConfigFile(configPath).mcpServers);
@@ -746,6 +863,7 @@ export function writeClaudeCodeConfig(entry, options = {}) {
         failedLocalProjects: unresolved,
         restoredPreviousUserEntry,
         preservedDesktopManaged,
+        usedDirectWrite,
     };
 }
 function readJsonClientEntry(configPath) {
@@ -2589,6 +2707,11 @@ function parseFlags(argv) {
     }
     return flags;
 }
+/**
+ * Configure MCP clients without starting local-history HTML onboarding. Echo Desktop on macOS owns
+ * its native onboarding and invokes this setup surface with --skip-login; only CLI `init` below owns
+ * the browser flow used by Windows/headless users.
+ */
 async function cmdSetup(flags) {
     if (!flags.dev && !flags["skip-runtime-install"]) {
         try {
@@ -2641,6 +2764,9 @@ async function cmdSetup(flags) {
                         if (result.preservedDesktopManaged) {
                             console.log(`✅ Kept the valid externally managed EchoMem user entry for ${c.label}.`);
                         }
+                        else if (result.usedDirectWrite) {
+                            console.log(`✅ Wrote EchoMem MCP entry to ${c.label} directly (no runnable \`claude\` CLI was found) — start a new Claude Code session to load it.`);
+                        }
                         else {
                             console.log(`✅ Wrote EchoMem MCP entry to ${c.label} via \`claude mcp add-json\` — start a new Claude Code session to load it.`);
                         }
@@ -2711,7 +2837,8 @@ async function cmdSetup(flags) {
     }
 }
 /**
- * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
+ * `echomem-mcp init` — the CLI-owned one-command install used by Windows/headless users. Configures
+ * EVERY coding agent installed on this
  * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), installs EchoMem's
  * Codex skills and writes the AGENTS.md memory guidance. One browser
  * bridge then runs permission → login → plan if needed → extraction in that order.
@@ -2813,11 +2940,14 @@ async function cmdUpdate(flags) {
 function selectSetupTargets(requested, all) {
     if (all || requested === "all") {
         return knownClients().filter((client) => {
-            if (client.kind === "json")
+            if (client.kind === "json") {
+                if (client.id === "claude-desktop")
+                    return client.detected === true;
                 return fs.existsSync(path.dirname(client.configPath));
+            }
             if (client.kind === "command")
                 return fs.existsSync(client.detectDir);
-            return client.id === "claude-code" && fs.existsSync(home(".claude"));
+            return client.id === "claude-code" && claudeCodeInstalled();
         });
     }
     return requested ? knownClients().filter((client) => client.id === requested) : detectClients();
@@ -3618,6 +3748,60 @@ async function cmdStatus(flags = {}) {
         }
     }
 }
+/**
+ * Where this install lives and what it can actually see.
+ *
+ * `status` answers "who am I logged in as". This answers "why is EchoMem not finding my sessions",
+ * which is the question that needs a command — a bare zero cannot distinguish "no store here" from
+ * "store found, nothing in it". Local only, so it still works with no network and no account.
+ */
+export function doctorReportLines() {
+    const lines = ["Environment:"];
+    const entry = resolveDurableDistPath("index.js");
+    const runtime = readHeadlessRuntimeInstallation();
+    lines.push(`  package         ${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`);
+    lines.push(`  entry point     ${entry.path}${entry.ephemeral ? "   [temporary npx cache — npm can delete this]" : ""}`);
+    lines.push(`  durable runtime ${runtime ? `${runtime.version} at ${runtime.entry}` : "not installed"}`);
+    const candidates = claudeCodeCommandCandidates();
+    lines.push(`  claude CLI      ${claudeCodeCliAvailable() ? "runnable" : `not runnable (${candidates.length} candidate${candidates.length === 1 ? "" : "s"} tried)`}`);
+    const supportRoots = resolveClaudeDesktopSupportRoots();
+    const containerised = supportRoots.some((root) => /[\\/]Packages[\\/]Claude_/i.test(root));
+    lines.push(`  Claude Desktop  ${supportRoots.length === 0
+        ? "not detected"
+        : `${containerised ? "Store/MSIX container" : "unpackaged install"} (${supportRoots.length} support root${supportRoots.length === 1 ? "" : "s"})`}`);
+    const claudeRoot = resolveClaudeProjectsDir();
+    const codexRoot = resolveCodexSessionRoots()[0]?.path;
+    const coworkRoots = resolveClaudeCoworkSessionRoots();
+    // Dedupe as the import path does: inside an MSIX container the plain and LocalCache support roots
+    // expose the same files, and realpath does not collapse that, so raw discovery counts them twice.
+    const sessions = dedupeSessionsByConversation(discoverSessions({ claudeRoot: claudeRoot ?? undefined, coworkRoots, codexRoot }));
+    const row = (label, source, root) => {
+        const found = sessions.filter((session) => session.source === source).length;
+        if (found > 0)
+            return `  ${label.padEnd(15)} ${found}  ${root ?? ""}`.trimEnd();
+        // A zero must say which zero it is.
+        return `  ${label.padEnd(15)} 0  ${root ? `store found at ${root}, nothing importable in it` : "no store on this machine"}`;
+    };
+    lines.push("", "Local sessions:");
+    lines.push(row("Claude Code", "claude-code", claudeRoot ?? undefined));
+    lines.push(row("Codex", "codex", codexRoot));
+    lines.push(row("Cowork", "claude-desktop", coworkRoots[0]));
+    return lines;
+}
+function cmdDoctor() {
+    console.log(`EchoMem doctor — ${MCP_PACKAGE_LABEL}\n`);
+    for (const line of doctorReportLines())
+        console.log(line);
+    const reports = inspectClientConfigs(MCP_PACKAGE_VERSION);
+    if (reports.length) {
+        console.log("\nClient MCP configs:");
+        for (const report of reports) {
+            for (const line of formatClientConfigReport(report))
+                console.log(line);
+        }
+    }
+    console.log("\nAccount, credentials and update checks: `status`.");
+}
 function cmdLogout() {
     const store = new KeyStore();
     try {
@@ -3666,9 +3850,18 @@ Manual / headless:
 Current bridge version: ${MCP_PACKAGE_VERSION}
 `;
 /** Returns true if argv was a recognized subcommand (and was handled). */
+/** Commands that persist paths into other programs' configs, and so must run from a durable copy. */
+const CONFIG_WRITING_COMMANDS = new Set(["init", "setup", "update"]);
 export async function runCli(argv) {
     const cmd = argv[0];
     const flags = parseFlags(argv.slice(1));
+    if (cmd && CONFIG_WRITING_COMMANDS.has(cmd)) {
+        const status = reexecFromDurableRuntime(argv);
+        if (status !== null) {
+            process.exitCode = status;
+            return true;
+        }
+    }
     switch (cmd) {
         case "init":
             await cmdInit(flags);
@@ -3692,7 +3885,7 @@ export async function runCli(argv) {
             await cmdStatus(flags);
             return true;
         case "doctor":
-            await cmdStatus(flags);
+            cmdDoctor();
             return true;
         case "logout":
             cmdLogout();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.48",
+  "version": "1.4.50",
   "description": "EchoMem MCP bridge for cross-agent memory, local history import, and recall",
   "main": "dist/index.js",
   "type": "module",
@@ -31,7 +31,7 @@
     "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/source-session.test.mjs && node test/source-session-hook.test.mjs && 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/canonical-golden.test.mjs && node test/tools.test.mjs && node test/workspace-selector.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.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",
+    "test": "npm run build && node test/source-session.test.mjs && node test/source-session-hook.test.mjs && 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/canonical-golden.test.mjs && node test/tools.test.mjs && node test/workspace-selector.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.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 && node test/durable-entry.test.mjs && node test/durable-reexec.test.mjs && node test/doctor.test.mjs && node test/environment-matrix.test.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {