@echomem/mcp 1.4.50 → 1.4.51

package/README.md

@@ -54,7 +54,7 @@ npx -y @echomem/mcp@latest init
 Windows PowerShell:
 
 ```powershell
-npx.cmd -y @echomem/mcp@latest init
+npx.cmd -y @echomem/mcp@latest connect
 ```
 
 The one-off `npx` command is the recommended install path; it stages a durable per-user runtime
@@ -63,7 +63,9 @@ Node if `npx.cmd` is not found.
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp init` | Legacy/headless setup for installed agents + login |
+| `npx -y @echomem/mcp@latest connect` | Open Connect Echo for account readiness, per-host setup, Doctor, repair, and uninstall (use `npx.cmd` in Windows PowerShell) |
+| `npx -y @echomem/mcp@latest init` | One-command setup for installed agents + login (use `npx.cmd` in Windows PowerShell) |
+| `npm i -g @echomem/mcp@latest`, then `echomem-mcp init` | Optional global install for a persistent CLI command |
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
@@ -75,8 +77,31 @@ Node if `npx.cmd` is not found.
 | `echomem-mcp lock` | Remove the local vault key while keeping the device login |
 | `echomem-mcp status` | Show token / key / detected clients, configured bridge versions, and update guidance |
 | `echomem-mcp doctor [--no-network]` | Diagnose configured client bridge versions |
+| `echomem-mcp control` / `manage` | Compatibility aliases for the returning-user Connect Echo page |
+| `echomem-mcp reconnect` | Clean-reinstall EchoMem's managed runtime, clear inactive runtime cache, and repair detected host entries |
+| `echomem-mcp uninstall --confirm` | Remove EchoMem MCP host entries/runtime while preserving login, vault credentials, and cloud memories |
 | `echomem-mcp logout` | Remove stored credentials |
 
+### Windows Connect Echo (no desktop app required)
+
+If you installed the optional global CLI, run this from PowerShell:
+
+```powershell
+echomem-mcp connect
+```
+
+For the recommended one-off install, launch the same local control page with:
+
+```powershell
+npx.cmd -y @echomem/mcp@latest connect
+```
+
+The page binds only to `127.0.0.1` and uses a per-launch nonce. It validates account/vault state,
+shows each detected MCP host independently, and provides Connect, Repair, Disconnect, Doctor, and
+clean Reconnect actions. **Uninstall MCP** stays under Advanced controls and removes only EchoMem-owned
+host entries, hooks, guidance, skills, and managed runtime files; it does not remove the local
+EchoMem credential store or any cloud memory. Restart each agent after configuration changes.
+
 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. Standalone installations
 stage compatible updates in the background under `~/.echomem/mcp-runtime` and atomically activate

package/dist/config-files.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function isErrno(error, code) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === code;
+}
+/**
+ * Read a user-owned JSON configuration without treating corruption as an empty file.
+ * Setup must fail closed here: replacing malformed JSON would destroy unrelated client settings.
+ */
+export function readJsonObjectFile(file, label = "configuration") {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return {};
+        throw new Error(`Could not read ${label} at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing JSON root is not an object.`);
+    }
+    return parsed;
+}
+/** Write beside the destination and rename only after the complete replacement is durable locally. */
+export function atomicWriteTextFile(file, content) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    let mode;
+    try {
+        mode = fs.statSync(file).mode;
+    }
+    catch {
+        /* A fresh file uses the process default mode. */
+    }
+    try {
+        fs.writeFileSync(temporary, content, mode === undefined ? undefined : { mode });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch {
+            /* Preserve the original error. */
+        }
+        throw error;
+    }
+}
+export function atomicWriteJsonObject(file, value) {
+    atomicWriteTextFile(file, JSON.stringify(value, null, 2));
+}

package/dist/headless-runtime.js

@@ -173,28 +173,79 @@ function finishStaging(staging, destination, version) {
     fs.renameSync(staging, destination);
     return activateRuntime(destination, version);
 }
-export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION) {
+function pruneInactiveRuntimeVersions(activeVersion) {
+    const removed = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync(versionsRoot(), { withFileTypes: true });
+    }
+    catch {
+        return removed;
+    }
+    for (const entry of entries) {
+        // A dot-prefixed directory is another install's staging area. Never prune in-flight work.
+        if (entry.name === activeVersion || entry.name.startsWith("."))
+            continue;
+        try {
+            safeVersion(entry.name);
+        }
+        catch {
+            continue;
+        }
+        const target = path.join(versionsRoot(), entry.name);
+        try {
+            fs.rmSync(target, { recursive: true, force: true });
+            removed.push(entry.name);
+        }
+        catch {
+            /* Cache pruning is best effort; the active clean runtime is already safe. */
+        }
+    }
+    return removed;
+}
+export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION, options = {}) {
     const version = safeVersion(targetVersion);
     const existing = readHeadlessRuntimeInstallation();
-    if (existing?.version === version)
+    if (!options.force && existing?.version === version)
         return existing;
     const destination = path.join(versionsRoot(), version);
-    if (readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
-        return activateRuntime(destination, version);
+    if (!options.force && readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
+        const installation = activateRuntime(destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
-    const { staging } = prepareStaging(version);
-    const npm = resolveNpmInvocation();
+    const releaseLock = acquireUpdateLock();
+    if (!releaseLock)
+        throw new Error("Another EchoMem runtime update is already in progress. Retry reconnect in a moment.");
+    let staging = "";
     try {
+        staging = prepareStaging(version).staging;
+        const npm = resolveNpmInvocation();
         execFileSync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
             stdio: "inherit",
             windowsHide: true,
         });
-        return finishStaging(staging, destination, version);
+        const installation = finishStaging(staging, destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
     catch (error) {
-        fs.rmSync(staging, { recursive: true, force: true });
+        if (staging)
+            fs.rmSync(staging, { recursive: true, force: true });
         throw new Error(`Could not stage ${MCP_PACKAGE_NAME}@${version}: ${error instanceof Error ? error.message : String(error)}`);
     }
+    finally {
+        releaseLock();
+    }
+}
+/** Remove only EchoMem's staged standalone runtime. Credentials and cloud data live elsewhere. */
+export function removeHeadlessRuntime() {
+    const root = headlessRuntimeRoot();
+    const removed = fs.existsSync(root);
+    fs.rmSync(root, { recursive: true, force: true });
+    return { removed, path: root };
 }
 function acquireUpdateLock() {
     const lock = path.join(headlessRuntimeRoot(), "update.lock");

package/dist/hud/hooks.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { atomicWriteJsonObject, readJsonObjectFile } from "../config-files.js";
 import { resolveDurableDistPath } from "../durable-entry.js";
 /**
  * Hook commands are persisted into another program's settings and must keep working long after this
@@ -45,17 +46,59 @@ export function installSourceSessionHooks(mode) {
     }
     return written;
 }
+/** Remove only EchoMem-owned lifecycle hook groups and preserve every unrelated user hook. */
+export function removeLifecycleHooks(mode) {
+    const files = [];
+    let removedGroups = 0;
+    const targets = [];
+    if (mode === "codex" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CODEX_HOME", ".codex"), "hooks.json"));
+    }
+    if (mode === "claude-code" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "settings.json"));
+    }
+    for (const file of targets) {
+        if (!fs.existsSync(file))
+            continue;
+        const content = readHooksFile(file);
+        const hooks = content.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+            continue;
+        let changed = false;
+        for (const [event, value] of Object.entries(hooks)) {
+            if (!Array.isArray(value))
+                continue;
+            const kept = value.filter((group) => !isEchoLifecycleGroup(group));
+            const removed = value.length - kept.length;
+            if (removed === 0)
+                continue;
+            removedGroups += removed;
+            changed = true;
+            if (kept.length > 0)
+                hooks[event] = kept;
+            else
+                delete hooks[event];
+        }
+        if (!changed)
+            continue;
+        if (Object.keys(hooks).length === 0)
+            delete content.hooks;
+        atomicWriteJsonObject(file, content);
+        files.push(file);
+    }
+    return { files, removedGroups };
+}
 function installCodexHooks() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     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 }] });
-    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [codexCommandHook(hookCommand, 5)] });
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function saveCheckpointCommand() {
@@ -65,24 +108,19 @@ function sourceSessionCommand() {
     return hookCommandFor(path.join("hud", "cli.js"), "bind-source-session");
 }
 function installCodexSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.SessionStart = mergeSourceSessionGroup(content.hooks.SessionStart, {
-        hooks: [{
-                type: "command",
-                command: sourceSessionCommand(),
-                timeout: 5,
-                statusMessage: "Binding EchoMem to this conversation",
-            }],
+        hooks: [codexCommandHook(sourceSessionCommand(), 5, "Binding EchoMem to this conversation")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -95,28 +133,23 @@ function installClaudeCodeSourceSessionHook() {
                 statusMessage: "Binding EchoMem to this conversation",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installCodexSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.Stop = mergeSaveCheckpointGroup(content.hooks.Stop, {
-        hooks: [{
-                type: "command",
-                command: saveCheckpointCommand(),
-                timeout: 10,
-                statusMessage: "Checking whether completed work should be remembered",
-            }],
+        hooks: [codexCommandHook(saveCheckpointCommand(), 10, "Checking whether completed work should be remembered")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -129,22 +162,40 @@ function installClaudeCodeSaveCheckpointHook() {
                 statusMessage: "Checking whether completed work should be remembered",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSnippet() {
-    const dir = path.join(os.homedir(), ".claude", "echo-ctx");
+    const dir = path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "echo-ctx");
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
 function readHooksFile(file) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    return readJsonObjectFile(file, "agent hooks");
+}
+function profileDirectory(envKey, fallbackName) {
+    const home = os.homedir();
+    const configured = process.env[envKey]?.trim();
+    if (!configured)
+        return path.join(home, fallbackName);
+    if (configured === "~")
+        return home;
+    if (configured.startsWith("~/") || configured.startsWith("~\\")) {
+        return path.join(home, configured.slice(2));
     }
-    catch {
-        return {};
+    if (!path.isAbsolute(configured)) {
+        throw new Error(`${envKey} must be an absolute path or start with ~/`);
     }
+    return path.normalize(configured);
+}
+function codexCommandHook(command, timeout, statusMessage) {
+    return {
+        type: "command",
+        command,
+        commandWindows: command,
+        timeout,
+        ...(statusMessage ? { statusMessage } : {}),
+    };
 }
 function mergeHookGroup(existing, group) {
     const groups = Array.isArray(existing) ? existing.filter((item) => !isEchoHudGroup(item)) : [];
@@ -176,3 +227,6 @@ function isEchoSaveCheckpointGroup(value) {
         return false;
     return JSON.stringify(value).includes("save-checkpoint");
 }
+function isEchoLifecycleGroup(value) {
+    return isEchoHudGroup(value) || isEchoSourceSessionGroup(value) || isEchoSaveCheckpointGroup(value);
+}

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { bindSourceSessionSchema, canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
+import { bindSourceSessionSchema, canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, linkWorkspaceTicketSessionSchema, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
@@ -16,7 +16,7 @@ import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS, MEMORY_CITATION_INSTRUCTI
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
 import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
 import { autoUpdateHeadlessRuntime } from "./headless-runtime.js";
-import { resolveSourceSessionFromMcpContext, resolveSourceSessionFromBindingToken, } from "./source-session.js";
+import { resolveSourceSessionRequestContext, resolveSourceSessionFromBindingToken, } from "./source-session.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(/\/$/, "");
@@ -582,6 +582,14 @@ function inputAnalyticsForTool(canonicalName, args) {
                 receipt_id_hash: receiptId ? hashText(receiptId) : undefined,
             };
         }
+        case canonicalToolNames.linkWorkspaceTicketSession: {
+            const ticketId = readString(a, "ticketId");
+            const workspaceId = readString(a, "workspaceId");
+            return {
+                ticket_id_hash: ticketId ? hashText(ticketId) : undefined,
+                workspace_id_hash: workspaceId ? hashText(workspaceId) : undefined,
+            };
+        }
         case canonicalToolNames.flagPublicationAttention: {
             const memoryIds = Array.isArray(a.memoryIds) ? a.memoryIds.filter((id) => typeof id === "string") : [];
             return {
@@ -609,13 +617,22 @@ function inputAnalyticsForTool(canonicalName, args) {
 function toolEventName(canonicalName, status) {
     return `[MCP] ${canonicalName} ${status}`;
 }
+const SUBAGENT_DURABLE_WRITE_MESSAGE = [
+    "Codex subagents cannot save EchoMem memories or manage conversation sharing.",
+    "Return durable findings to the root agent; the root agent must consolidate them and call save_conversation once.",
+].join(" ");
+const SUBAGENT_ROOT_ONLY_TOOLS = new Set([
+    canonicalToolNames.save,
+    canonicalToolNames.requestGroupSessionSharing,
+    canonicalToolNames.setGroupSessionSharing,
+]);
 class EchoMemApiClient {
     store;
     axios;
     activeToken;
     accountGeneration = 0;
     boundSourceSession = null;
-    requestSourceSession = new AsyncLocalStorage();
+    requestContext = new AsyncLocalStorage();
     sourceSessionsByCanonicalKey = new Map();
     whoamiCache = null;
     /** One id per bridge process — groups all saves from this coding session under a single EchoMem context. */
@@ -677,10 +694,20 @@ class EchoMemApiClient {
     }
     getBoundSourceSession() {
         this.synchronizeAccountContext();
-        return this.requestSourceSession.getStore() ?? this.boundSourceSession;
+        const requestContext = this.requestContext.getStore();
+        return requestContext === undefined ? this.boundSourceSession : requestContext.sourceSession;
+    }
+    getRequestVerifiedSourceSession() {
+        const requestContext = this.requestContext.getStore();
+        if (!requestContext || requestContext.lineageStatus === "unbound")
+            return null;
+        return requestContext.sourceSession;
     }
-    async withSourceSession(sourceSession, operation) {
-        return sourceSession ? this.requestSourceSession.run(sourceSession, operation) : operation();
+    isSubagentRequest() {
+        return this.requestContext.getStore()?.isSubagent === true;
+    }
+    async withRequestContext(requestContext, operation) {
+        return this.requestContext.run(requestContext, operation);
     }
     async bindSourceSession(verified, persistForBridge = true) {
         this.synchronizeAccountContext();
@@ -714,6 +741,21 @@ class EchoMemApiClient {
             created: response.data?.created === true,
         };
     }
+    async linkWorkspaceTicketSession(args) {
+        const parsed = linkWorkspaceTicketSessionSchema.parse(args ?? {});
+        // A bridge-level compatibility binding can outlive a conversation in
+        // long-running hosts. Ticket links are therefore allowed to take the fast
+        // path only from identity verified for this exact request; otherwise the
+        // Desktop transcript watcher completes the link from local evidence.
+        const sourceSession = this.getRequestVerifiedSourceSession();
+        if (!sourceSession)
+            return null;
+        const response = await this.axios.post(`/api/extension/workspace-tickets/${encodeURIComponent(parsed.ticketId)}/sessions`, {
+            contextId: sourceSession.contextId,
+            workspaceId: parsed.workspaceId,
+        });
+        return response.data;
+    }
     async trackMcpAnalyticsEvent(eventType, eventProperties, insertId) {
         if (!this.hasToken())
             return;
@@ -966,6 +1008,9 @@ class EchoMemApiClient {
         return data;
     }
     async saveConversation(args) {
+        if (this.isSubagentRequest()) {
+            throw new Error(SUBAGENT_DURABLE_WRITE_MESSAGE);
+        }
         const parsed = saveConversationSchema.parse(args ?? {});
         const groupSharingScopeId = parsed.groupSharingScopeId ?? randomUUID();
         let rawData = parsed.conversation?.trim() || "";
@@ -984,6 +1029,7 @@ class EchoMemApiClient {
         const config = {
             headers: {
                 "X-EchoMem-Request-Id": randomUUID(),
+                "X-EchoMem-Origin-Channel": "local_mcp",
                 ...(enc.enabled && enc.key ? { "X-Encryption-Key": enc.key } : {}),
             },
         };
@@ -1429,21 +1475,32 @@ class EchoMemMCPServer {
             const clientVersion = this.server.getClientVersion();
             this.mcpClientName = clientVersion?.name ?? this.mcpClientName;
             this.mcpClientVersion = clientVersion?.version ?? this.mcpClientVersion;
-            let requestSourceSession = this.client.getBoundSourceSession();
-            let inferred = null;
+            let sourceResolution = {
+                sourceSession: null,
+                isSubagent: false,
+                lineageStatus: "unbound",
+            };
             try {
-                inferred = resolveSourceSessionFromMcpContext(extra._meta, { hostPlatform: this.getMcpClientAnalytics().host_platform });
+                sourceResolution = resolveSourceSessionRequestContext(extra._meta, { hostPlatform: this.getMcpClientAnalytics().host_platform });
             }
             catch {
                 // Malformed host metadata is not model input. Ignore it and retain the explicit fallback.
             }
+            // A child request starts fail-closed. Resolved children bind to the originating root; unresolved
+            // children carry an explicit null so AsyncLocalStorage cannot fall through to a global binding.
+            let requestSourceSession = sourceResolution.isSubagent
+                ? null
+                : this.client.getBoundSourceSession();
             // Verified request metadata always wins over a bridge-level compatibility fallback. The
             // startup hook performs the eager write; this path attaches the exact context to the current
             // request and retries the backend write if startup raced login.
-            if (inferred && this.client.hasToken()) {
-                requestSourceSession = await this.client.bindSourceSession(inferred, false);
+            if (sourceResolution.sourceSession && this.client.hasToken()) {
+                requestSourceSession = await this.client.bindSourceSession(sourceResolution.sourceSession, false);
             }
-            return this.client.withSourceSession(requestSourceSession, async () => {
+            return this.client.withRequestContext({
+                ...sourceResolution,
+                sourceSession: requestSourceSession,
+            }, async () => {
                 const t0 = Date.now();
                 const analyticsBase = {
                     surface: "mcp",
@@ -1454,6 +1511,18 @@ class EchoMemMCPServer {
                     codex_session_id: this.client.getBoundSourceSession()?.canonicalKey ?? this.client.getSessionId(),
                     conversation_id: this.client.getBoundSourceSession()?.canonicalKey ?? this.client.getSessionId(),
                     context_id: this.client.getBoundSourceSession()?.contextId,
+                    agent_is_subagent: sourceResolution.isSubagent,
+                    agent_lineage_status: sourceResolution.lineageStatus,
+                    agent_depth: sourceResolution.agentDepth,
+                    agent_thread_id_hash: sourceResolution.agentThreadId
+                        ? hashText(sourceResolution.agentThreadId)
+                        : undefined,
+                    agent_parent_thread_id_hash: sourceResolution.parentThreadId
+                        ? hashText(sourceResolution.parentThreadId)
+                        : undefined,
+                    agent_root_thread_id_hash: sourceResolution.rootThreadId
+                        ? hashText(sourceResolution.rootThreadId)
+                        : undefined,
                     tool_name: request.params.name,
                     canonical_tool_name: canonicalName,
                     ...triggerAnalyticsForTool(canonicalName, toolArgs),
@@ -1471,6 +1540,13 @@ class EchoMemMCPServer {
                     if (recallRoute.error) {
                         throw new McpError(ErrorCode.InvalidParams, recallRoute.error);
                     }
+                    if (sourceResolution.isSubagent && SUBAGENT_ROOT_ONLY_TOOLS.has(canonicalName)) {
+                        rec.error_kind = "invalid_args";
+                        return {
+                            content: [{ type: "text", text: SUBAGENT_DURABLE_WRITE_MESSAGE }],
+                            isError: true,
+                        };
+                    }
                     if (canonicalName === canonicalToolNames.updateStatus) {
                         if (DESKTOP_MANAGED) {
                             return {
@@ -1502,6 +1578,14 @@ class EchoMemMCPServer {
                             ? client
                             : "auto";
                         const capsuleText = await recomposeCapsuleMarkdown(mode);
+                        if (this.client.isSubagentRequest()) {
+                            return {
+                                content: [{
+                                        type: "text",
+                                        text: `${capsuleText}\n\n---\nNot persisted: ${SUBAGENT_DURABLE_WRITE_MESSAGE}`,
+                                    }],
+                            };
+                        }
                         // If logged in, persist the capsule via passthrough so it's retrievable by contextId.
                         if (this.client.hasToken()) {
                             try {
@@ -1536,6 +1620,8 @@ class EchoMemMCPServer {
                     switch (canonicalName) {
                         case canonicalToolNames.bindSourceSession:
                             return await this.handleBindSourceSession(request.params.arguments);
+                        case canonicalToolNames.linkWorkspaceTicketSession:
+                            return await this.handleLinkWorkspaceTicketSession(request.params.arguments);
                         case canonicalToolNames.search:
                             return await this.handleSearch(toolArgs, rec);
                         case canonicalToolNames.save:
@@ -1925,6 +2011,37 @@ Details: ${m.details || "N/A"}`)
                 }],
         };
     }
+    async handleLinkWorkspaceTicketSession(args) {
+        const parsed = linkWorkspaceTicketSessionSchema.parse(args ?? {});
+        const result = await this.client.linkWorkspaceTicketSession(parsed);
+        if (!result) {
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Ticket ${parsed.ticketId} link is pending verified source-session discovery.`,
+                            "Echo Desktop can finish this link from the structured ticket marker or this exact local tool invocation.",
+                            "Do not guess a context ID or call bind_source_session on the user's behalf unless its documented compatibility fallback is actually needed.",
+                        ].join("\n"),
+                    }],
+            };
+        }
+        const ticket = isRecord(result.ticket) ? result.ticket : {};
+        const workspaceId = readString(ticket, "workspaceId") ?? parsed.workspaceId;
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        result.changed === true
+                            ? "Linked this verified source session to the Echo workspace ticket."
+                            : "This verified source session was already linked to the Echo workspace ticket.",
+                        `Ticket: ${parsed.ticketId}`,
+                        workspaceId ? `Workspace: ${workspaceId}` : "",
+                        "Retries are safe and do not create duplicate links or history events.",
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    }
     async handleTimeRange(args) {
         const parsed = timeRangeSchema.parse(args ?? {});
         const { success, memories, error } = await this.client.getMemoriesByTimeRange(args);