@echomem/mcp 1.4.49 → 1.4.51

package/dist/setup.js

@@ -26,15 +26,19 @@ 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 { resolveClaudeDesktopSupportRoots } from "./local-data-paths.js";
-import { installSaveCheckpointHooks, installSourceSessionHooks } from "./hud/hooks.js";
+import { resolveClaudeCoworkSessionRoots, resolveClaudeDesktopSupportRoots, resolveClaudeProjectsDir, resolveCodexSessionRoots, } from "./local-data-paths.js";
+import { isEphemeralNpxPath, reexecFromDurableRuntime, resolveDurableDistPath, resolveGlobalEntry } from "./durable-entry.js";
+import { installSaveCheckpointHooks, installSourceSessionHooks, removeLifecycleHooks } from "./hud/hooks.js";
+import { atomicWriteJsonObject, atomicWriteTextFile, readJsonObjectFile } from "./config-files.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";
-import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } from "./headless-runtime.js";
+import { startMcpControlServer } from "./mcp-control.js";
+import { loadHudDiagnostics } from "./hud/diagnostics.js";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, removeHeadlessRuntime, } from "./headless-runtime.js";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
 // localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
@@ -216,18 +220,45 @@ 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 = resolveClaudeDesktopSupportRoots();
+    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") },
@@ -238,14 +269,27 @@ export function knownClients() {
     ];
 }
 /** 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 claudeCodeCliAvailable();
+            return claudeCodeInstalled();
         return false;
     });
 }
@@ -287,33 +331,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;
@@ -394,13 +411,38 @@ export function writeCodexConfig(configPath, entry, options = {}) {
         if (lines.slice(start, end).join("\n").trimEnd() === block)
             return "exists"; // already correct
         const next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end)];
-        fs.writeFileSync(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
+        atomicWriteTextFile(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
         return "wrote"; // replaced a stale entry → caller tells the user to restart Codex
     }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(configPath, sep + block + "\n");
+    atomicWriteTextFile(configPath, content + sep + block + "\n");
     return "wrote";
 }
+/** Remove only EchoMem's TOML section and preserve every other Codex setting. */
+export function removeCodexConfig(configPath) {
+    let content;
+    try {
+        content = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.echomem\]\s*$/.test(line));
+    if (start < 0)
+        return false;
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end += 1;
+    const next = [...lines.slice(0, start), ...lines.slice(end)]
+        .join("\n")
+        .replace(/^\n+/, "")
+        .replace(/\n{3,}/g, "\n\n");
+    atomicWriteTextFile(configPath, next);
+    return true;
+}
 /**
  * Write the EchoMem guidance block into the agent's GLOBAL memory file (~/.codex/AGENTS.md,
  * ~/.claude/CLAUDE.md) so the agent treats EchoMem as its core memory tool without the tool
@@ -455,13 +497,35 @@ export function writeAgentsMemoryGuidance(filePath) {
         const current = content.slice(start, end + AGENTS_MD_END.length);
         if (current === block)
             return "exists";
-        fs.writeFileSync(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
+        atomicWriteTextFile(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
         return "updated";
     }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(filePath, sep + block + "\n");
+    atomicWriteTextFile(filePath, content + sep + block + "\n");
     return "wrote";
 }
+/** Remove EchoMem's marker-owned guidance block without touching user-authored content. */
+export function removeAgentsMemoryGuidance(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    const start = content.indexOf(AGENTS_MD_BEGIN);
+    const end = content.indexOf(AGENTS_MD_END);
+    if (start < 0 || end <= start)
+        return false;
+    const next = (content.slice(0, start) + content.slice(end + AGENTS_MD_END.length))
+        .replace(/^\s*\n/, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd();
+    atomicWriteTextFile(filePath, next ? `${next}\n` : "");
+    return true;
+}
 /**
  * Refresh marker-owned guidance for users upgrading an existing standalone MCP install.
  * This intentionally does not create global memory files: setup owns first installation,
@@ -493,32 +557,30 @@ export function refreshInstalledMemoryGuidance() {
 }
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
 export function writeJsonClientConfig(configPath, entry, options = {}) {
-    let config = {};
-    try {
-        config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    }
-    catch {
-        /* fresh config */
-    }
-    config.mcpServers = config.mcpServers || {};
-    if (!options.forceHeadless && validDesktopManagedEntry(config.mcpServers.echomem)) {
+    const config = readJsonObjectFile(configPath, "MCP client configuration");
+    const servers = objectRecord(config.mcpServers) ?? {};
+    config.mcpServers = servers;
+    if (!options.forceHeadless && validDesktopManagedEntry(servers.echomem)) {
         return "desktop-managed";
     }
-    config.mcpServers.echomem = entry;
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    servers.echomem = entry;
+    atomicWriteJsonObject(configPath, config);
     return "wrote";
 }
+/** Remove only the EchoMem server entry from a JSON MCP client configuration. */
+export function removeJsonClientConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return false;
+    const config = readJsonObjectFile(configPath, "MCP client configuration");
+    const servers = objectRecord(config.mcpServers);
+    if (!servers || !("echomem" in servers))
+        return false;
+    delete servers.echomem;
+    atomicWriteJsonObject(configPath, config);
+    return true;
+}
 function readClaudeCodeConfigFile(configPath) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : {};
-    }
-    catch {
-        return {};
-    }
+    return readJsonObjectFile(configPath, "Claude Code user configuration");
 }
 function echoMemEntryFromServers(value) {
     return objectRecord(objectRecord(value)?.echomem);
@@ -552,7 +614,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 });
@@ -564,7 +626,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,
@@ -583,13 +646,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 {
@@ -622,55 +685,106 @@ 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;
-        }
-    }
-    throw lastError;
+    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 {
-        execClaudeCodeSync(["--version"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: 3000,
-        });
+        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 {
@@ -682,6 +796,7 @@ export function writeClaudeCodeConfig(entry, options = {}) {
     // 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",
@@ -692,14 +807,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;
         }
@@ -718,16 +846,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);
@@ -768,8 +911,39 @@ export function writeClaudeCodeConfig(entry, options = {}) {
         failedLocalProjects: unresolved,
         restoredPreviousUserEntry,
         preservedDesktopManaged,
+        usedDirectWrite,
     };
 }
+/** Remove EchoMem at Claude Code user/project scope while preserving account and sibling config. */
+export function removeClaudeCodeConfig(configPath = home(".claude.json")) {
+    if (!fs.existsSync(configPath))
+        return { removedUserEntry: false, removedProjectEntries: [] };
+    const config = readClaudeCodeConfigFile(configPath);
+    let changed = false;
+    let removedUserEntry = false;
+    const userServers = objectRecord(config.mcpServers);
+    if (userServers && "echomem" in userServers) {
+        delete userServers.echomem;
+        removedUserEntry = true;
+        changed = true;
+    }
+    const removedProjectEntries = [];
+    const projects = objectRecord(config.projects);
+    if (projects) {
+        for (const [projectPath, value] of Object.entries(projects)) {
+            const project = objectRecord(value);
+            const servers = objectRecord(project?.mcpServers);
+            if (!servers || !("echomem" in servers))
+                continue;
+            delete servers.echomem;
+            removedProjectEntries.push(projectPath);
+            changed = true;
+        }
+    }
+    if (changed)
+        atomicWriteJsonObject(configPath, config);
+    return { removedUserEntry, removedProjectEntries };
+}
 function readJsonClientEntry(configPath) {
     try {
         const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
@@ -2611,6 +2785,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 {
@@ -2663,6 +2842,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.`);
                         }
@@ -2733,7 +2915,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.
@@ -2835,11 +3018,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" && claudeCodeCliAvailable();
+            return client.id === "claude-code" && claudeCodeInstalled();
         });
     }
     return requested ? knownClients().filter((client) => client.id === requested) : detectClients();
@@ -3587,6 +3773,293 @@ function cmdLock() {
     store.clearKey();
     console.log("🔒 EchoMem vault locked on this device. Your login remains connected.");
 }
+export async function collectMcpDoctorReport(options = {}) {
+    const updateStatus = options.noNetwork
+        ? readCachedUpdateStatus()
+        : await checkLatestUpdateStatus({ force: true });
+    const desiredVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    const runtime = readHeadlessRuntimeInstallation();
+    const store = new KeyStore();
+    const token = store.getToken();
+    const key = store.getKey();
+    let account = token
+        ? { state: options.noNetwork ? "not_checked" : "unreachable", detail: options.noNetwork ? "Account validation skipped." : "Account validation did not finish." }
+        : { state: "not_connected", detail: "Connect this Windows profile to an Echo account." };
+    let vault = key
+        ? { state: options.noNetwork ? "not_checked" : "unknown", detail: options.noNetwork ? "Vault validation skipped." : "Checking the saved vault key." }
+        : { state: token ? "unknown" : "locked", detail: token ? "Vault state has not been checked." : "Connect the account before checking the vault." };
+    let lastSearch;
+    if (token && !options.noNetwork) {
+        const diagnostics = await loadHudDiagnostics();
+        if (diagnostics.account.state === "connected") {
+            account = {
+                state: "connected",
+                plan: diagnostics.account.plan,
+                detail: diagnostics.account.plan
+                    ? `${diagnostics.account.plan} account verified.`
+                    : "Echo account verified.",
+            };
+        }
+        else if (diagnostics.accountRequest.httpStatus === 401 || diagnostics.accountRequest.httpStatus === 403) {
+            account = { state: "invalid", detail: "The saved Echo credential is no longer valid. Reconnect the account." };
+        }
+        else {
+            account = { state: "unreachable", detail: diagnostics.account.error || "Echo account validation is temporarily unavailable." };
+        }
+        if (diagnostics.lastSearch) {
+            lastSearch = {
+                at: diagnostics.lastSearch.at,
+                ok: diagnostics.lastSearch.ok,
+                httpStatus: diagnostics.lastSearch.httpStatus,
+                latencyMs: diagnostics.lastSearch.latencyMs,
+            };
+        }
+        if (account.state === "connected") {
+            try {
+                const encryption = await fetchEncryptionConfig(authedAxios(token));
+                if (!encryption.enabled) {
+                    vault = { state: "unencrypted", detail: "This account does not require a local vault key." };
+                }
+                else if (!key) {
+                    vault = { state: "locked", detail: "The encrypted vault is locked on this Windows profile." };
+                }
+                else if (await verifyKeyB64(key, encryption)) {
+                    vault = { state: "unlocked", detail: "The local vault key is valid." };
+                }
+                else {
+                    vault = { state: "invalid", detail: "The saved vault key does not match this account. Reconnect and unlock again." };
+                }
+            }
+            catch (error) {
+                vault = { state: "unknown", detail: `Vault validation unavailable: ${formatVerificationError(error)}` };
+            }
+        }
+        else if (!key) {
+            vault = { state: "unknown", detail: "Vault state cannot be verified until the account reconnects." };
+        }
+    }
+    const wsl = process.platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+    const clients = inspectClientConfigs(desiredVersion).map((client) => {
+        const health = !client.configured
+            ? "not_configured"
+            : client.state === "ok" || client.state === "newer"
+                ? "ready"
+                : client.state === "stale" || client.state === "missing"
+                    ? "repair"
+                    : "attention";
+        return {
+            ...client,
+            detected: true,
+            health,
+            recommendedAction: health === "not_configured" ? "connect" : health === "repair" || health === "attention" ? "repair" : "none",
+        };
+    });
+    return {
+        packageVersion: MCP_PACKAGE_VERSION,
+        publishedLatest: updateStatus?.latestVersion,
+        platform: process.platform,
+        credentialsPresent: Boolean(token),
+        vaultKeyPresent: Boolean(key),
+        runtime: runtime ? { version: runtime.version, launcher: runtime.launcher } : undefined,
+        account,
+        vault,
+        environment: {
+            windowsNative: process.platform === "win32",
+            wsl,
+            detail: wsl
+                ? "This is WSL. Native Windows agents use a separate EchoMem installation and configuration."
+                : process.platform === "win32"
+                    ? "Native Windows profile. WSL installations are managed separately."
+                    : "This Connect Echo page is running outside native Windows.",
+        },
+        lastSearch,
+        clients,
+    };
+}
+/**
+ * Remove standalone EchoMem MCP integration without deleting login/vault credentials or cloud data.
+ * Every user-owned config is edited narrowly and atomically; malformed files fail closed.
+ */
+export function uninstallStandaloneMcp() {
+    const store = new KeyStore();
+    const report = {
+        removedClients: [],
+        removedGuidance: [],
+        removedSkills: [],
+        removedHookGroups: 0,
+        removedRuntime: false,
+        credentialsPreserved: Boolean(store.getToken() || store.getKey()),
+        errors: [],
+    };
+    for (const client of knownClients()) {
+        try {
+            if (client.kind === "json") {
+                if (removeJsonClientConfig(client.configPath))
+                    report.removedClients.push(client.label);
+            }
+            else if (client.kind === "command") {
+                if (removeCodexConfig(client.configPath))
+                    report.removedClients.push(client.label);
+            }
+            else {
+                const removed = removeClaudeCodeConfig();
+                if (removed.removedUserEntry || removed.removedProjectEntries.length > 0)
+                    report.removedClients.push(client.label);
+            }
+        }
+        catch (error) {
+            report.errors.push(`${client.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        const hooks = removeLifecycleHooks("both");
+        report.removedHookGroups = hooks.removedGroups;
+    }
+    catch (error) {
+        report.errors.push(`Lifecycle hooks: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const file of [path.join(codexHome(), "AGENTS.md"), path.join(claudeConfigHome(), "CLAUDE.md")]) {
+        try {
+            if (removeAgentsMemoryGuidance(file))
+                report.removedGuidance.push(file);
+        }
+        catch (error) {
+            report.errors.push(`Guidance ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    for (const skillName of CODEX_SKILL_NAMES) {
+        const directory = path.join(codexHome(), "skills", skillName);
+        try {
+            if (!fs.existsSync(directory))
+                continue;
+            fs.rmSync(directory, { recursive: true, force: true });
+            report.removedSkills.push(skillName);
+        }
+        catch (error) {
+            report.errors.push(`Codex skill ${skillName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        report.removedRuntime = removeHeadlessRuntime().removed;
+    }
+    catch (error) {
+        report.errors.push(`Managed runtime: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return report;
+}
+function requireClient(clientId) {
+    const client = knownClients().find((candidate) => candidate.id === clientId);
+    if (!client)
+        throw new Error(`Unsupported MCP host: ${clientId}`);
+    return client;
+}
+export async function connectStandaloneMcpHost(clientId, options = {}) {
+    requireClient(clientId);
+    const updateStatus = await checkLatestUpdateStatus({ force: true });
+    const targetVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    installHeadlessRuntimeSync(targetVersion, {
+        force: options.repair === true,
+        prune: options.repair === true,
+    });
+    await cmdSetup({
+        client: clientId,
+        "skip-login": true,
+        "skip-runtime-install": true,
+        "continue-on-client-error": true,
+    });
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+export async function disconnectStandaloneMcpHost(clientId) {
+    const client = requireClient(clientId);
+    if (client.kind === "json") {
+        removeJsonClientConfig(client.configPath);
+    }
+    else if (client.kind === "command") {
+        removeCodexConfig(client.configPath);
+    }
+    else {
+        removeClaudeCodeConfig();
+    }
+    if (client.id === "codex") {
+        removeLifecycleHooks("codex");
+        removeAgentsMemoryGuidance(path.join(codexHome(), "AGENTS.md"));
+        for (const skillName of CODEX_SKILL_NAMES) {
+            fs.rmSync(path.join(codexHome(), "skills", skillName), { recursive: true, force: true });
+        }
+    }
+    if (client.id === "claude-code")
+        removeLifecycleHooks("claude-code");
+    if (client.id === "claude-code" || client.id === "claude-desktop") {
+        const otherId = client.id === "claude-code" ? "claude-desktop" : "claude-code";
+        const other = requireClient(otherId);
+        const otherReport = inspectClientConfig(other, MCP_PACKAGE_VERSION);
+        if (!otherReport?.configured)
+            removeAgentsMemoryGuidance(path.join(claudeConfigHome(), "CLAUDE.md"));
+    }
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+async function cleanReconnectStandaloneMcp() {
+    const updateStatus = await checkLatestUpdateStatus({ force: true });
+    const targetVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    console.log(`Installing a clean ${MCP_PACKAGE_NAME}@${targetVersion} runtime…`);
+    installHeadlessRuntimeSync(targetVersion, { force: true, prune: true });
+    await cmdSetup({
+        all: true,
+        "skip-login": true,
+        "skip-runtime-install": true,
+        "continue-on-client-error": true,
+    });
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+async function cmdControl() {
+    const control = await startMcpControlServer({
+        doctor: () => collectMcpDoctorReport(),
+        connectHost: (clientId, repair) => connectStandaloneMcpHost(clientId, { repair }),
+        disconnectHost: (clientId) => disconnectStandaloneMcpHost(clientId),
+        reconnect: () => cleanReconnectStandaloneMcp(),
+        uninstall: () => uninstallStandaloneMcp(),
+    });
+    console.log("Connect Echo is running locally.");
+    console.log(control.url);
+    console.log("Close this terminal or press Ctrl+C when you are finished.");
+    openBrowser(control.url);
+}
+async function cmdConnect(flags) {
+    if (flags["skip-login"] !== true) {
+        const current = await collectMcpDoctorReport();
+        const accountNeedsLogin = current.account.state === "not_connected" || current.account.state === "invalid";
+        const vaultNeedsUnlock = current.account.state === "connected"
+            && (current.vault.state === "locked" || current.vault.state === "invalid");
+        if (accountNeedsLogin || vaultNeedsUnlock) {
+            const connected = await cmdLogin({ ...flags, force: true });
+            if (!connected)
+                return;
+        }
+    }
+    await cmdControl();
+}
+async function cmdReconnect(flags) {
+    const report = await cleanReconnectStandaloneMcp();
+    const configured = report.clients.filter((client) => client.configured).length;
+    console.log(`Clean reconnect complete: ${configured} MCP host${configured === 1 ? "" : "s"} configured.`);
+    console.log("Start a new session in each MCP host to load the clean runtime.");
+}
+function cmdUninstall(flags) {
+    if (flags.confirm !== true) {
+        console.error("Uninstall requires explicit confirmation: echomem-mcp uninstall --confirm");
+        console.error("This preserves EchoMem login, vault credentials, and cloud memories.");
+        process.exitCode = 1;
+        return;
+    }
+    const report = uninstallStandaloneMcp();
+    console.log(`Removed EchoMem MCP from ${report.removedClients.length} host configuration${report.removedClients.length === 1 ? "" : "s"}.`);
+    console.log(`Managed runtime: ${report.removedRuntime ? "removed" : "not installed"}.`);
+    console.log("EchoMem login, vault credentials, and cloud memories were preserved.");
+    if (report.errors.length > 0) {
+        console.error(`Some components could not be removed:\n${report.errors.map((error) => `- ${error}`).join("\n")}`);
+        process.exitCode = 1;
+    }
+}
 async function cmdStatus(flags = {}) {
     const store = new KeyStore();
     const token = store.getToken();
@@ -3640,6 +4113,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 {
@@ -3653,6 +4180,7 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
+  echomem-mcp connect               Open Connect Echo; authenticate if needed, then manage MCP hosts
   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
@@ -3667,6 +4195,9 @@ Usage:
   echomem-mcp lock                  Remove the local vault key while keeping the device login
   echomem-mcp status                Show token/key/clients
   echomem-mcp doctor [--no-network] Diagnose configured client bridge versions
+  echomem-mcp control               Alias for the returning-user Connect Echo control page
+  echomem-mcp reconnect             Clean-reinstall the managed runtime and repair detected hosts
+  echomem-mcp uninstall --confirm   Remove MCP integration but preserve credentials and cloud memories
   echomem-mcp logout                Remove stored credentials
   echomem-mcp migrate [--since D]   Import your existing Codex/Claude history into your memory
   echomem-mcp migrate --estimate    Estimate migration size/time metadata without uploading transcripts
@@ -3688,10 +4219,22 @@ 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 "connect":
+            await cmdConnect(flags);
+            return true;
         case "init":
             await cmdInit(flags);
             return true;
@@ -3714,7 +4257,18 @@ export async function runCli(argv) {
             await cmdStatus(flags);
             return true;
         case "doctor":
-            await cmdStatus(flags);
+            cmdDoctor();
+            return true;
+        case "control":
+        case "manage":
+            await cmdControl();
+            return true;
+        case "reconnect":
+        case "repair":
+            await cmdReconnect(flags);
+            return true;
+        case "uninstall":
+            cmdUninstall(flags);
             return true;
         case "logout":
             cmdLogout();