@echomem/mcp 1.4.36 → 1.4.38

package/README.md

@@ -55,7 +55,7 @@ For headless systems and development, the granular CLI commands remain available
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
 | `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config without opening the browser or changing credentials |
-| `npx -y @echomem/mcp@latest update --all` | One-shot update: install the latest bridge durably and repoint detected client configs, with no browser login |
+| `npx -y @echomem/mcp@latest update --all` | Bootstrap or repair the durable per-user runtime and repoint detected client configs, with no browser login |
 | `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Privately unlock the vault on this trusted device |
@@ -65,10 +65,11 @@ For headless systems and development, the granular CLI commands remain available
 | `echomem-mcp logout` | Remove stored credentials |
 
 The bridge reports its package version in MCP server instructions and in tool descriptions. It also
-checks npm for a newer published bridge using a cached, non-blocking check. Agents can call
-`echomem_update_status` to show the user whether an update exists and then run
-`npx -y @echomem/mcp@latest update --all` if the user agrees. The bridge does not auto-update on
-every MCP startup.
+checks npm for a newer published bridge using a cached, non-blocking check. Standalone installations
+stage compatible updates in the background under `~/.echomem/mcp-runtime` and atomically activate
+them for the next MCP session; the current handshake never waits for npm. Agents can call
+`echomem_update_status` to inspect progress. `ECHO_DISABLE_AUTO_UPDATE=1` disables automatic
+installation, and `npx -y @echomem/mcp@latest update --all` remains the bootstrap and repair command.
 
 Agents can still call `echo_context_health` for an on-demand local context-health report. It reads
 the local Codex/Claude logs and does not require a separate process or desktop overlay.
@@ -189,14 +190,9 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
 * **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 * **`delete_memory`**: Delete a single personal memory through a two-step confirmation flow. First call with `memoryId` only to preview the target and receive `confirmationToken`; after the user explicitly confirms, call again with `confirmed: true` and that exact token. This deletes the memory row only and preserves raw `source_of_truth` conversation records.
-* **`echomem_update_status`**: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and returns the update command to show the user when a newer bridge exists.
+* **`echomem_update_status`**: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and reports automatic installation state plus a fallback repair command.
 * **`echo_context_health`**: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.
 
-Legacy aliases are preserved for compatibility:
-
-* `search_memories_by_description_semantic` -> `search_memories`
-* `search_memories_by_time_range` -> `get_memories_by_time_range`
-
 Contract reference:
 
 * `docs/PUBLIC_API_CONTRACT_V1.md`

package/dist/headless-runtime.js

@@ -0,0 +1,254 @@
+import { execFile, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { echoConfigDir } from "./keystore.js";
+import { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION } from "./package-metadata.js";
+const execFileAsync = promisify(execFile);
+const RUNTIME_LAYOUT = 1;
+const UPDATE_LOCK_STALE_MS = 15 * 60 * 1000;
+export function headlessRuntimeRoot() {
+    return path.join(echoConfigDir(), "mcp-runtime");
+}
+function versionsRoot() {
+    return path.join(headlessRuntimeRoot(), "versions");
+}
+function activeRuntimePath() {
+    return path.join(headlessRuntimeRoot(), "active.json");
+}
+export function headlessLauncherPath() {
+    return path.join(headlessRuntimeRoot(), "launcher.mjs");
+}
+function packageEntryForPrefix(prefix) {
+    return path.join(prefix, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "dist", "index.js");
+}
+function packageJsonForPrefix(prefix) {
+    return path.join(prefix, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "package.json");
+}
+function safeVersion(value) {
+    const version = value.trim();
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`Invalid EchoMem MCP version: ${value}`);
+    }
+    return version;
+}
+function relativeEntryForVersion(version) {
+    return path.join("versions", version, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "dist", "index.js");
+}
+function atomicWriteJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2), { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        /* Best effort on platforms without POSIX permissions. */
+    }
+}
+function ensureLauncher() {
+    const root = headlessRuntimeRoot();
+    const launcher = headlessLauncherPath();
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const source = [
+        "#!/usr/bin/env node",
+        'import fs from "node:fs";',
+        'import path from "node:path";',
+        'import { fileURLToPath, pathToFileURL } from "node:url";',
+        "const root = path.dirname(fileURLToPath(import.meta.url));",
+        'const active = JSON.parse(fs.readFileSync(path.join(root, "active.json"), "utf8"));',
+        'if (active.layout !== 1 || typeof active.entry !== "string" || path.isAbsolute(active.entry) || active.entry.split(/[\\\\/]/).includes("..")) {',
+        '  throw new Error("EchoMem MCP runtime pointer is invalid; run `npx -y @echomem/mcp@latest update --all`.");',
+        "}",
+        "const entry = path.resolve(root, active.entry);",
+        'if (!fs.existsSync(entry)) throw new Error("EchoMem MCP runtime is missing; run `npx -y @echomem/mcp@latest update --all`.");',
+        "await import(pathToFileURL(entry).href);",
+        "",
+    ].join("\n");
+    let current = "";
+    try {
+        current = fs.readFileSync(launcher, "utf8");
+    }
+    catch {
+        /* Create it below. */
+    }
+    if (current !== source)
+        fs.writeFileSync(launcher, source, { mode: 0o700 });
+    try {
+        fs.chmodSync(launcher, 0o700);
+    }
+    catch {
+        /* Best effort on platforms without POSIX permissions. */
+    }
+    return launcher;
+}
+function readPackageVersion(prefix) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonForPrefix(prefix), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readHeadlessRuntimeInstallation() {
+    try {
+        const active = JSON.parse(fs.readFileSync(activeRuntimePath(), "utf8"));
+        if (active.layout !== RUNTIME_LAYOUT || typeof active.version !== "string" || typeof active.entry !== "string") {
+            return undefined;
+        }
+        if (path.isAbsolute(active.entry) || active.entry.split(/[\\/]/).includes(".."))
+            return undefined;
+        const entry = path.resolve(headlessRuntimeRoot(), active.entry);
+        const expectedRoot = `${path.resolve(headlessRuntimeRoot())}${path.sep}`;
+        if (!entry.startsWith(expectedRoot) || !fs.existsSync(entry))
+            return undefined;
+        const prefix = path.join(versionsRoot(), active.version);
+        if (readPackageVersion(prefix) !== active.version)
+            return undefined;
+        return { version: active.version, launcher: ensureLauncher(), entry };
+    }
+    catch {
+        return undefined;
+    }
+}
+function activateRuntime(prefix, version) {
+    const entry = packageEntryForPrefix(prefix);
+    if (!fs.existsSync(entry) || readPackageVersion(prefix) !== version) {
+        throw new Error(`${MCP_PACKAGE_NAME}@${version} did not install a valid MCP entry point`);
+    }
+    const launcher = ensureLauncher();
+    atomicWriteJson(activeRuntimePath(), {
+        layout: RUNTIME_LAYOUT,
+        version,
+        entry: relativeEntryForVersion(version),
+        activatedAt: new Date().toISOString(),
+    });
+    return { version, launcher, entry };
+}
+function resolveNpmInvocation() {
+    const candidates = [
+        process.env.npm_execpath,
+        path.resolve(path.dirname(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        path.resolve(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+    ].filter((candidate) => Boolean(candidate));
+    for (const npmCli of candidates) {
+        try {
+            if (fs.existsSync(npmCli))
+                return { command: process.execPath, prefixArgs: [npmCli] };
+        }
+        catch {
+            /* Keep looking. */
+        }
+    }
+    return { command: process.platform === "win32" ? "npm.cmd" : "npm", prefixArgs: [] };
+}
+function npmInstallArguments(prefix, version) {
+    return [
+        "install",
+        "--ignore-scripts",
+        "--omit=dev",
+        "--no-audit",
+        "--no-fund",
+        "--no-package-lock",
+        "--prefix",
+        prefix,
+        `${MCP_PACKAGE_NAME}@${version}`,
+    ];
+}
+function prepareStaging(version) {
+    const destination = path.join(versionsRoot(), version);
+    fs.mkdirSync(versionsRoot(), { recursive: true, mode: 0o700 });
+    const staging = path.join(versionsRoot(), `.${version}-${process.pid}-${Date.now()}`);
+    fs.rmSync(staging, { recursive: true, force: true });
+    return { destination, staging };
+}
+function finishStaging(staging, destination, version) {
+    if (readPackageVersion(staging) !== version || !fs.existsSync(packageEntryForPrefix(staging))) {
+        throw new Error(`npm installed an invalid ${MCP_PACKAGE_NAME}@${version} runtime`);
+    }
+    if (fs.existsSync(destination))
+        fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staging, destination);
+    return activateRuntime(destination, version);
+}
+export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION) {
+    const version = safeVersion(targetVersion);
+    const existing = readHeadlessRuntimeInstallation();
+    if (existing?.version === version)
+        return existing;
+    const destination = path.join(versionsRoot(), version);
+    if (readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
+        return activateRuntime(destination, version);
+    }
+    const { staging } = prepareStaging(version);
+    const npm = resolveNpmInvocation();
+    try {
+        execFileSync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
+            stdio: "inherit",
+            windowsHide: true,
+        });
+        return finishStaging(staging, destination, version);
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw new Error(`Could not stage ${MCP_PACKAGE_NAME}@${version}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function acquireUpdateLock() {
+    const lock = path.join(headlessRuntimeRoot(), "update.lock");
+    fs.mkdirSync(headlessRuntimeRoot(), { recursive: true, mode: 0o700 });
+    try {
+        const descriptor = fs.openSync(lock, "wx", 0o600);
+        fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        fs.closeSync(descriptor);
+    }
+    catch {
+        try {
+            const age = Date.now() - fs.statSync(lock).mtimeMs;
+            if (age <= UPDATE_LOCK_STALE_MS)
+                return undefined;
+            fs.rmSync(lock, { force: true });
+            return acquireUpdateLock();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return () => fs.rmSync(lock, { force: true });
+}
+export async function autoUpdateHeadlessRuntime(targetVersion) {
+    if (process.env.ECHO_DISABLE_AUTO_UPDATE === "1")
+        return { state: "disabled" };
+    let version;
+    try {
+        version = safeVersion(targetVersion);
+    }
+    catch (error) {
+        return { state: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    if (readHeadlessRuntimeInstallation()?.version === version)
+        return { state: "already-installed" };
+    const releaseLock = acquireUpdateLock();
+    if (!releaseLock)
+        return { state: "busy" };
+    const { destination, staging } = prepareStaging(version);
+    const npm = resolveNpmInvocation();
+    try {
+        await execFileAsync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
+            timeout: 120_000,
+            windowsHide: true,
+            maxBuffer: 1024 * 1024,
+        });
+        const installation = finishStaging(staging, destination, version);
+        return { state: "installed", installation };
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        return { state: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        releaseLock();
+    }
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { runCli } from "./setup.js";
 import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, } from "./package-metadata.js";
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
 import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
+import { autoUpdateHeadlessRuntime } from "./headless-runtime.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
 const ECHO_PRICING_URL = process.env.ECHO_PRICING_URL || "https://echoknows.com/account";
 const ECHO_MEMORY_WEB_URL = (process.env.ECHO_MEMORY_WEB_URL || "https://echoknows.com/memory").replace(/\/$/, "");
@@ -1216,7 +1217,7 @@ class EchoMemMCPServer {
         this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
         if (!DESKTOP_MANAGED) {
             startBackgroundUpdateCheck((status) => {
-                this.updateStatus = status;
+                this.handleUpdateStatus(status);
             });
         }
         this.setupToolHandlers();
@@ -1226,6 +1227,33 @@ class EchoMemMCPServer {
             process.exit(0);
         });
     }
+    handleUpdateStatus(status) {
+        this.updateStatus = status;
+        if (!status.updateAvailable || !status.latestVersion)
+            return;
+        this.updateStatus = { ...status, autoUpdateState: "installing" };
+        void autoUpdateHeadlessRuntime(status.latestVersion).then((result) => {
+            if (result.state === "installed" || result.state === "already-installed") {
+                this.updateStatus = { ...status, autoUpdateState: "ready" };
+            }
+            else if (result.state === "busy") {
+                this.updateStatus = { ...status, autoUpdateState: "installing" };
+            }
+            else {
+                this.updateStatus = {
+                    ...status,
+                    autoUpdateState: "failed",
+                    error: result.state === "failed" ? result.error : "automatic updates are disabled",
+                };
+            }
+        }).catch((error) => {
+            this.updateStatus = {
+                ...status,
+                autoUpdateState: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        });
+    }
     getMcpClientAnalytics() {
         const hostPlatform = normalizeMcpHostPlatform(this.mcpClientName)
             ?? detectMcpHostFromEnv()
@@ -1320,8 +1348,8 @@ class EchoMemMCPServer {
                     }
                     const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
                     const status = await checkLatestUpdateStatus({ force });
-                    this.updateStatus = status;
-                    return { content: [{ type: "text", text: formatUpdateStatusText(status) }] };
+                    this.handleUpdateStatus(status);
+                    return { content: [{ type: "text", text: formatUpdateStatusText(this.updateStatus ?? status) }] };
                 }
                 if (canonicalName === canonicalToolNames.contextHealth) {
                     const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
@@ -2319,10 +2347,7 @@ Details: ${m.details || "N/A"}`;
             return {
                 content: [{
                         type: "text",
-                        text: [
-                            scopeText,
-                            `No sharing decision was recorded for ${groupName}. The checkpoint remains private. Ask again at a later qualifying checkpoint; never interpret decline or cancel as No.`,
-                        ].filter(Boolean).join("\n\n"),
+                        text: this.sharingFallbackText(scopeText, groupName),
                     }],
             };
         }

package/dist/package-metadata.js

@@ -28,13 +28,13 @@ export const MCP_VAULT_UNLOCK_INSTRUCTION = MCP_DESKTOP_MANAGED
     ? "open Echo Desktop and unlock the vault there"
     : "run `echomem-mcp unlock` locally";
 const MCP_UPDATE_INSTRUCTION = MCP_DESKTOP_MANAGED
-    ? "Echo Desktop manages this MCP runtime; install an Echo Desktop update when one is offered"
-    : `update once with \`${MCP_UPDATE_ALL_COMMAND}\``;
+    ? "Echo Desktop auto-installs compatible MCP updates"
+    : `updates auto-install in the background; on failure run \`${MCP_UPDATE_ALL_COMMAND}\``;
 export const MEMORY_CITATION_INSTRUCTION = 'If the user-facing answer materially relies on one or more EchoMem memories, end it with a compact "EchoMem sources:" list containing only the memories actually used. For memories owned by teammates or accepted friends, call record_memory_citations immediately before the final answer with those exact Memory IDs. Do not cite memories that were merely retrieved. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. Omit the sources section and citation receipt when no memory informed the answer.';
 export const SAVED_MEMORY_RECEIPT_INSTRUCTION = 'After save_conversation succeeds and returns one or more saved memory IDs, make the save visible in the final user-facing answer with a compact "EchoMem saved:" list containing every memory created by that call. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. This save receipt is separate from "EchoMem sources:" and does not imply that the newly saved memories informed the answer.';
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
-    `If this bridge is stale, ${MCP_UPDATE_INSTRUCTION} and start a new MCP session; never auto-update at startup.`,
+    `If stale, ${MCP_UPDATE_INSTRUCTION}; restart the MCP session afterward. Updates never delay startup.`,
     "Before re-deriving prior decisions or preferences, use search_memories.",
     `Before the final response for a durable decision, implementation, fix, commit, passing verification, release, or milestone, call save_conversation. Skip secrets and trivial work. If the encrypted vault is locked, tell the user to ${MCP_VAULT_UNLOCK_INSTRUCTION}.`,
     "After a successful save, show every memory created by that call in a compact EchoMem saved: list with canonical links; this is separate from \"EchoMem sources:\".",
@@ -45,5 +45,5 @@ export const MCP_SERVER_INSTRUCTIONS = [
     "Group profiles, conversation sharing, publication, sensitive-memory flags, and deletion require explicit user confirmation. Never store or log an echo_grp_ invite code.",
 ].join(" ");
 export function withMcpVersion(description) {
-    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, ${MCP_UPDATE_INSTRUCTION}, then start a new MCP session. Do not run updates repeatedly or on every startup.`;
+    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, ${MCP_UPDATE_INSTRUCTION}, then start a new MCP session. Do not run manual updates repeatedly.`;
 }

package/dist/setup.js

@@ -34,6 +34,7 @@ import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
 import { installSaveCheckpointHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } 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(/\/$/, "");
@@ -239,6 +240,10 @@ export function buildServerEntry(opts = {}) {
     if (opts.devEntryPath) {
         return { command: "node", args: [opts.devEntryPath] };
     }
+    const managed = readHeadlessRuntimeInstallation();
+    if (managed) {
+        return { command: process.execPath, args: [managed.launcher] };
+    }
     // Spawn the ALREADY-INSTALLED bridge directly (this node + this script's real path) instead of
     // `npx -y @echomem/mcp`. `npx -y` re-resolves and, on a cache miss, NETWORK-fetches from the npm
     // registry on EVERY client start — on a slow/flaky network that delays the MCP handshake past the
@@ -291,51 +296,12 @@ function resolveGlobalEntry() {
     }
     return null;
 }
-export function needsDurableGlobalUpdate(runningEntry, durableEntry, targetVersion = MCP_PACKAGE_VERSION) {
-    if (!isEphemeralNpxPath(runningEntry))
-        return false;
-    const installedVersion = durableEntry
-        ? packageVersionFromPath(durableEntry)?.version
-        : undefined;
-    return installedVersion !== targetVersion;
-}
-function installDurableGlobalUpdate() {
-    const runningEntry = (() => {
-        try {
-            return fs.realpathSync(process.argv[1] || "");
-        }
-        catch {
-            return process.argv[1] || "";
-        }
-    })();
-    const currentGlobalEntry = resolveGlobalEntry();
-    if (!needsDurableGlobalUpdate(runningEntry, currentGlobalEntry))
+function installDurableHeadlessRuntime() {
+    if (process.env.ECHO_DISABLE_RUNTIME_BOOTSTRAP === "1")
         return;
-    const packageSpec = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
-    console.log(`Installing durable ${packageSpec} before updating client configs…`);
-    const npmExecPath = process.env.npm_execpath;
-    try {
-        if (npmExecPath && fs.existsSync(npmExecPath)) {
-            execFileSync(process.execPath, [npmExecPath, "install", "-g", packageSpec], {
-                stdio: "inherit",
-            });
-        }
-        else {
-            execFileSync(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "-g", packageSpec], {
-                stdio: "inherit",
-            });
-        }
-    }
-    catch (error) {
-        throw new Error(`Could not install ${packageSpec} globally: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    const installedEntry = resolveGlobalEntry();
-    const installedVersion = installedEntry
-        ? packageVersionFromPath(installedEntry)?.version
-        : undefined;
-    if (installedVersion !== MCP_PACKAGE_VERSION) {
-        throw new Error(`Global EchoMem bridge is ${installedVersion || "missing"} after update; expected ${MCP_PACKAGE_VERSION}.`);
-    }
+    console.log(`Staging durable per-user ${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION} runtime…`);
+    const installation = installHeadlessRuntimeSync();
+    console.log(`✅ Activated ${MCP_PACKAGE_NAME}@${installation.version} for new MCP sessions.`);
 }
 /** The TOML block EchoMem adds to ~/.codex/config.toml. No secret — the bridge reads the keystore. */
 export function codexTomlBlock(entry) {
@@ -450,8 +416,30 @@ export function writeJsonClientConfig(configPath, entry) {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
 export function writeClaudeCodeConfig(entry) {
+    const addArguments = ["mcp", "add-json", "-s", "local", "echomem", JSON.stringify(entry)];
     try {
-        execFileSync("claude", ["mcp", "add-json", "echomem", JSON.stringify(entry)], {
+        execFileSync("claude", addArguments, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        return "wrote";
+    }
+    catch (error) {
+        const stderr = error.stderr;
+        const detail = Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? "");
+        if (!detail.includes("already exists"))
+            return "unavailable";
+    }
+    // Claude Code's CLI will not replace a same-name local server. Once the replacement entry is
+    // fully constructed, remove only EchoMem and immediately re-add it; sibling MCP servers remain.
+    try {
+        execFileSync("claude", ["mcp", "remove", "echomem", "-s", "local"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        execFileSync("claude", addArguments, {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 10000,
@@ -2652,6 +2640,14 @@ function parseFlags(argv) {
     return flags;
 }
 async function cmdSetup(flags) {
+    if (!flags.dev && !flags["skip-runtime-install"]) {
+        try {
+            installDurableHeadlessRuntime();
+        }
+        catch (error) {
+            console.log(`ℹ️  Automatic runtime staging was unavailable; keeping the existing bridge (${error instanceof Error ? error.message : String(error)}).`);
+        }
+    }
     const entry = buildServerEntry({ devEntryPath: typeof flags.dev === "string" ? flags.dev : undefined });
     const requested = typeof flags.client === "string" ? flags.client : undefined;
     const targets = selectSetupTargets(requested, Boolean(flags.all));
@@ -2800,8 +2796,8 @@ function writeSaveCheckpointHooksForTargets(targets) {
 }
 async function cmdUpdate(flags) {
     if (!flags.dev)
-        installDurableGlobalUpdate();
-    await cmdSetup({ ...flags, "skip-login": true });
+        installDurableHeadlessRuntime();
+    await cmdSetup({ ...flags, "skip-login": true, "skip-runtime-install": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
 }
 function selectSetupTargets(requested, all) {

package/dist/update-check.js

@@ -107,10 +107,18 @@ export function startBackgroundUpdateCheck(onStatus) {
 export function formatUpdateNotice(status) {
     if (!status?.updateAvailable || !status.latestVersion)
         return undefined;
+    if (status.autoUpdateState === "ready") {
+        return `EchoMem ${status.latestVersion} was installed automatically. Start a new agent/MCP session to use it.`;
+    }
+    if (status.autoUpdateState === "installing") {
+        return `EchoMem ${status.latestVersion} is downloading automatically in the background. The next agent/MCP session will use it.`;
+    }
+    if (status.autoUpdateState === "failed") {
+        return `EchoMem ${status.latestVersion} could not be installed automatically. Run \`${status.command}\`, then start a new agent/MCP session.`;
+    }
     return [
         `EchoMem update available: installed ${status.currentVersion}, latest ${status.latestVersion}.`,
-        `Offer to update, then run \`${status.command}\` if the user agrees.`,
-        "After updating, start a new agent/MCP session.",
+        "It will install automatically in the background for the next agent/MCP session.",
     ].join(" ");
 }
 export function formatUpdateStatusText(status) {
@@ -120,8 +128,14 @@ export function formatUpdateStatusText(status) {
         `Update available: ${status.updateAvailable ? "yes" : "no"}`,
     ];
     if (status.updateAvailable) {
-        lines.push(`Update command: ${status.command}`);
-        lines.push("After updating, start a new agent/MCP session.");
+        if (status.autoUpdateState === "ready")
+            lines.push("Automatic update: installed for the next agent/MCP session");
+        else if (status.autoUpdateState === "installing")
+            lines.push("Automatic update: installing in the background");
+        else if (status.autoUpdateState === "failed")
+            lines.push(`Automatic update: failed; fallback command: ${status.command}`);
+        else
+            lines.push("Automatic update: scheduled in the background");
     }
     if (status.checkedAt)
         lines.push(`Checked at: ${status.checkedAt} (${status.source})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.36",
+  "version": "1.4.38",
   "description": "EchoMem MCP bridge: cloud-first memory tools and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -33,7 +33,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/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/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",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {