@echomem/mcp 1.4.40 → 1.4.42

package/dist/package-metadata.js

@@ -35,10 +35,11 @@ export const SAVED_MEMORY_RECEIPT_INSTRUCTION = 'After save_conversation succeed
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
     `If stale, ${MCP_UPDATE_INSTRUCTION}; restart the MCP session afterward. Updates never delay startup.`,
+    "A local SessionStart hook binds supported conversations to their real provider sessions; use bind_source_session only as fallback.",
     "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:\".",
-    "For company groups, call request_group_session_sharing near conversation start or after a qualifying save, relay its exact text question, and call set_group_session_sharing only after an explicit Yes or No. Omit groupSharingScopeId only on the first call, then reuse the returned scope only in this conversation. Each group needs an explicit choice; silence stays unset. Never infer consent. Flagged memories stay private.",
+    "For company groups, request sharing near conversation start or after a save; relay its exact question and set only after explicit Yes or No. Reuse the returned scope only in this conversation. Each group needs its own choice; silence means unset. Flagged memories stay private.",
     "EchoMem credential identity is authoritative over Claude profiles, host accounts, git identity, or inference. Use get_group_context before group-orientation answers and never re-filter owners returned by search_others_memories.",
     "When a final answer materially uses teammate or friend memories, call record_memory_citations with only the exact used Memory IDs and a unique per-answer receiptId.",
     "End memory-informed answers with a compact EchoMem sources: list. Use each memory key as the label and https://echoknows.com/memory/<memory-id> as its canonical link.",

package/dist/setup.js

@@ -31,7 +31,7 @@ import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
 import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
-import { installSaveCheckpointHooks } from "./hud/hooks.js";
+import { installSaveCheckpointHooks, installSourceSessionHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
 import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } from "./headless-runtime.js";
@@ -215,7 +215,7 @@ export function knownClients() {
         { id: "cursor", label: "Cursor", kind: "json", configPath: home(".cursor", "mcp.json") },
         { id: "windsurf", label: "Windsurf", kind: "json", configPath: home(".codeium", "windsurf", "mcp_config.json") },
         { id: "claude-desktop", label: "Claude Desktop", kind: "json", configPath: path.join(appSupport, "Claude", "claude_desktop_config.json") },
-        { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json echomem '<entry>'  (or add to .mcp.json)" },
+        { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json -s user echomem '<entry>'  (or add to .mcp.json)" },
         { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
@@ -356,6 +356,7 @@ function echomemGuidanceBlock() {
         "## Memory (EchoMem)",
         "EchoMem is your long-term memory across all coding sessions and tools.",
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
+        "- EchoMem's local SessionStart hook automatically binds each new Codex or Claude Code conversation to its real source-session ID. Use `bind_source_session` with a fresh UUID only as a compatibility fallback when the hook is unavailable or reports that the session is unbound.",
         "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
         '- If the final user-facing answer materially relies on one or more EchoMem memories, end it with a compact `EchoMem sources:` list containing only the memories actually used. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories that were merely retrieved, and omit the section when no memory informed the answer.',
         "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip it.",
@@ -415,13 +416,70 @@ export function writeJsonClientConfig(configPath, entry) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
-export function writeClaudeCodeConfig(entry) {
-    // EchoMem is a memory server that should load in EVERY Claude Code project, so it belongs at
-    // `user` scope (~/.claude.json, all projects) rather than `local` scope (the current project only).
-    const addArguments = ["mcp", "add-json", "-s", "user", "echomem", JSON.stringify(entry)];
-    const removeFromScope = (scope) => {
+function readClaudeCodeConfigFile(configPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function echoMemEntryFromServers(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entry = value.echomem;
+    return entry && typeof entry === "object" && !Array.isArray(entry)
+        ? entry
+        : undefined;
+}
+function claudeEntriesMatch(actual, expected) {
+    if (!actual || actual.command !== expected.command)
+        return false;
+    const actualArgs = Array.isArray(actual.args) ? actual.args : [];
+    const expectedArgs = Array.isArray(expected.args) ? expected.args : [];
+    if (actualArgs.length !== expectedArgs.length || actualArgs.some((value, index) => value !== expectedArgs[index])) {
+        return false;
+    }
+    const expectedEnv = expected.env;
+    if (!expectedEnv || typeof expectedEnv !== "object" || Array.isArray(expectedEnv))
+        return true;
+    const actualEnv = actual.env;
+    if (!actualEnv || typeof actualEnv !== "object" || Array.isArray(actualEnv))
+        return false;
+    return Object.entries(expectedEnv).every(([key, value]) => actualEnv[key] === value);
+}
+function claudeCodeLocalEchoMemProjects(configPath) {
+    const projects = readClaudeCodeConfigFile(configPath).projects;
+    if (!projects || typeof projects !== "object" || Array.isArray(projects))
+        return [];
+    return Object.entries(projects)
+        .filter(([, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        return Boolean(echoMemEntryFromServers(value.mcpServers));
+    })
+        .map(([projectPath]) => projectPath)
+        .sort();
+}
+export function writeClaudeCodeConfig(entry, options = {}) {
+    // EchoMem belongs at user scope so every Claude Code project resolves the same durable runtime.
+    // Older CLI versions wrote local/project entries, which take precedence over user scope and can
+    // keep launching a deleted npm cache or stale runtime. Migrate those only after user scope is safe.
+    const configPath = options.configPath ?? home(".claude.json");
+    const emptyResult = () => ({
+        state: "unavailable",
+        removedLocalProjects: [],
+        skippedLocalProjects: [],
+        failedLocalProjects: [],
+        restoredPreviousUserEntry: false,
+    });
+    const runClaude = (args, cwd) => {
         try {
-            execFileSync("claude", ["mcp", "remove", "echomem", "-s", scope], {
+            execFileSync("claude", args, {
+                cwd,
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "pipe"],
                 timeout: 10000,
@@ -432,39 +490,61 @@ export function writeClaudeCodeConfig(entry) {
             return false;
         }
     };
-    // Older builds installed EchoMem at `local` scope. Left in place it would shadow the user-scoped
-    // entry and keep launching the stale command, so drop it first. Best-effort: `local` is per-project,
-    // so this only clears the directory setup runs from — a no-op (ignored) when nothing is there.
-    removeFromScope("local");
-    try {
-        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 server. Once the replacement entry is fully
-    // constructed, remove only EchoMem and immediately re-add it; sibling MCP servers remain.
-    try {
-        if (!removeFromScope("user"))
-            return "unavailable";
-        execFileSync("claude", addArguments, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: 10000,
-        });
-        return "wrote";
+    const addUser = (value) => runClaude([
+        "mcp", "add-json", "-s", "user", "echomem", JSON.stringify(value),
+    ]);
+    const removeUser = () => runClaude(["mcp", "remove", "echomem", "-s", "user"]);
+    const before = readClaudeCodeConfigFile(configPath);
+    const previousUserEntry = echoMemEntryFromServers(before.mcpServers);
+    let restoredPreviousUserEntry = false;
+    // Avoid interrupting active/new sessions when the correct global entry is already installed.
+    if (!claudeEntriesMatch(previousUserEntry, entry)) {
+        if (previousUserEntry && !removeUser())
+            return emptyResult();
+        if (!addUser(entry)) {
+            if (previousUserEntry)
+                restoredPreviousUserEntry = addUser(previousUserEntry);
+            return { ...emptyResult(), restoredPreviousUserEntry };
+        }
     }
-    catch {
-        return "unavailable";
+    const installedUserEntry = echoMemEntryFromServers(readClaudeCodeConfigFile(configPath).mcpServers);
+    if (!claudeEntriesMatch(installedUserEntry, entry)) {
+        return { ...emptyResult(), restoredPreviousUserEntry };
+    }
+    const removedLocalProjects = [];
+    const skippedLocalProjects = [];
+    const failedLocalProjects = [];
+    for (const projectPath of claudeCodeLocalEchoMemProjects(configPath)) {
+        // A deleted directory cannot currently shadow user scope. Do not recreate it or hand-edit
+        // ~/.claude.json, which also contains Claude account/session state.
+        if (!fs.existsSync(projectPath)) {
+            skippedLocalProjects.push(projectPath);
+            continue;
+        }
+        let projectCwd = projectPath;
+        try {
+            projectCwd = fs.realpathSync(projectPath);
+        }
+        catch {
+            /* The existence check above already established the safe fallback path. */
+        }
+        if (runClaude(["mcp", "remove", "echomem", "-s", "local"], projectCwd)) {
+            removedLocalProjects.push(projectPath);
+        }
+        else {
+            failedLocalProjects.push(projectPath);
+        }
     }
+    const remainingActiveProjects = claudeCodeLocalEchoMemProjects(configPath)
+        .filter((projectPath) => fs.existsSync(projectPath));
+    const unresolved = [...new Set([...failedLocalProjects, ...remainingActiveProjects])].sort();
+    return {
+        state: unresolved.length > 0 ? "needs-repair" : "wrote",
+        removedLocalProjects,
+        skippedLocalProjects,
+        failedLocalProjects: unresolved,
+        restoredPreviousUserEntry,
+    };
 }
 function readJsonClientEntry(configPath) {
     try {
@@ -2667,6 +2747,7 @@ async function cmdSetup(flags) {
     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));
+    const configurationFailures = [];
     if (targets.length === 0) {
         console.log("No client auto-detected. Add this MCP server entry manually:\n");
         console.log(JSON.stringify({ echomem: entry }, null, 2));
@@ -2687,23 +2768,39 @@ async function cmdSetup(flags) {
             }
             else {
                 const result = c.id === "claude-code" ? writeClaudeCodeConfig(entry) : "unavailable";
-                if (result === "wrote") {
+                if (result !== "unavailable" && result.state === "wrote") {
                     console.log(`✅ Wrote EchoMem MCP entry to ${c.label} via \`claude mcp add-json\` — start a new Claude Code session to load it.`);
+                    if (result.removedLocalProjects.length > 0) {
+                        console.log(`✅ Removed ${result.removedLocalProjects.length} stale Claude Code project-local EchoMem ${result.removedLocalProjects.length === 1 ? "entry" : "entries"}.`);
+                    }
+                    if (result.skippedLocalProjects.length > 0) {
+                        console.log(`ℹ️  Ignored ${result.skippedLocalProjects.length} EchoMem local ${result.skippedLocalProjects.length === 1 ? "entry" : "entries"} for deleted project directories; they cannot shadow the user entry.`);
+                    }
                 }
                 else {
-                    console.log(`ℹ️  ${c.label}: ${c.note}\n   entry: ${JSON.stringify(entry)}`);
+                    const failedProjects = result === "unavailable" ? [] : result.failedLocalProjects;
+                    configurationFailures.push(failedProjects.length > 0
+                        ? `${c.label} still has project-local EchoMem overrides in: ${failedProjects.join(", ")}`
+                        : `${c.label} user-scoped EchoMem entry could not be verified`);
                 }
             }
         }
     }
+    if (configurationFailures.length > 0) {
+        throw new Error([
+            "EchoMem MCP configuration is incomplete; onboarding was stopped before login/import.",
+            ...configurationFailures.map((failure) => `- ${failure}`),
+            `Retry with: ${MCP_UPDATE_COMMAND} --client claude-code`,
+        ].join("\n"));
+    }
     if (!flags["no-agents-md"]) {
         writeMemoryGuidanceForTargets(targets);
     }
     if (!flags["no-codex-skills"]) {
         writeCodexSkillsForTargets(targets);
     }
-    if (flags["install-save-hooks"]) {
-        writeSaveCheckpointHooksForTargets(targets);
+    if (flags["no-save-hooks"] !== true) {
+        writeLifecycleHooksForTargets(targets);
     }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
@@ -2793,7 +2890,7 @@ function writeCodexSkillsForTargets(targets) {
         console.log(`ℹ️  Could not install EchoMem Codex skills: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function writeSaveCheckpointHooksForTargets(targets) {
+function writeLifecycleHooksForTargets(targets) {
     const clients = new Set();
     if (targets.some((target) => target.id === "codex"))
         clients.add("codex");
@@ -2804,8 +2901,10 @@ function writeSaveCheckpointHooksForTargets(targets) {
         return;
     }
     const mode = clients.size === 2 ? "both" : [...clients][0];
-    const paths = installSaveCheckpointHooks(mode);
-    console.log(`✅ Installed EchoMem private-save checkpoint hooks:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
+    const sourcePaths = installSourceSessionHooks(mode);
+    const savePaths = installSaveCheckpointHooks(mode);
+    const paths = [...new Set([...sourcePaths, ...savePaths])];
+    console.log(`✅ Installed EchoMem source-session and private-save hooks:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
     if (clients.has("codex")) {
         console.log("   Codex: start a new session and run /hooks once to review and trust the hook.");
     }
@@ -3810,7 +3909,7 @@ Manual / headless:
   ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
   ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
-  echomem-mcp setup --install-save-hooks --all  Install proactive private-save completion checks
+  echomem-mcp setup --install-save-hooks --all  Install source-session + private-save lifecycle hooks
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 
 Current bridge version: ${MCP_PACKAGE_VERSION}

package/dist/source-session-hook.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import axios from "axios";
+import { KeyStore } from "./keystore.js";
+import { SOURCE_SESSION_HOOK_EVIDENCE, verifiedSourceSession, } from "./source-session.js";
+const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+const MAX_HEAD_BYTES = 256 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function transcriptHead(file) {
+    const descriptor = fs.openSync(file, "r");
+    try {
+        const size = Math.min(fs.fstatSync(descriptor).size, MAX_HEAD_BYTES);
+        const buffer = Buffer.allocUnsafe(size);
+        const read = fs.readSync(descriptor, buffer, 0, size, 0);
+        return buffer.toString("utf8", 0, read);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function codexSessionFromTranscript(file) {
+    for (const line of transcriptHead(file).split(/\r?\n/)) {
+        try {
+            const row = JSON.parse(line);
+            if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
+                continue;
+            const id = typeof row.payload.id === "string" ? row.payload.id : "";
+            if (!id)
+                return null;
+            const source = row.payload.source;
+            const isSubagent = typeof row.payload.parent_thread_id === "string"
+                || (isRecord(source) && Object.hasOwn(source, "subagent"));
+            return { id, isSubagent };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function coworkSessionFromPath(file) {
+    return file.split(path.sep).find((part) => /^local_[A-Za-z0-9_-]{1,194}$/.test(part)) ?? null;
+}
+export function resolveSourceSessionFromHookPayload(payload) {
+    const requestedSessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path.trim() : "";
+    if (!requestedSessionId || !transcriptPath || !path.isAbsolute(transcriptPath))
+        return null;
+    let file;
+    try {
+        file = fs.realpathSync(transcriptPath);
+        if (!fs.statSync(file).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const coworkSession = coworkSessionFromPath(file);
+    if (coworkSession) {
+        return verifiedSourceSession("cowork", coworkSession, SOURCE_SESSION_HOOK_EVIDENCE);
+    }
+    const codexSession = codexSessionFromTranscript(file);
+    if (codexSession) {
+        if (codexSession.isSubagent || codexSession.id.toLowerCase() !== requestedSessionId.toLowerCase()) {
+            return null;
+        }
+        return verifiedSourceSession("codex", codexSession.id, SOURCE_SESSION_HOOK_EVIDENCE);
+    }
+    const filenameSession = path.basename(file, path.extname(file));
+    if (filenameSession !== requestedSessionId)
+        return null;
+    return verifiedSourceSession("claude-code", filenameSession, SOURCE_SESSION_HOOK_EVIDENCE);
+}
+async function bindSourceSession(identity) {
+    const token = new KeyStore().getToken();
+    if (!token)
+        return;
+    await axios.post(`${API_BASE}/api/extension/source-sessions/bind`, {
+        provider: identity.provider,
+        providerSessionId: identity.providerSessionId,
+        evidence: identity.evidence,
+    }, {
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        timeout: 3_500,
+    });
+}
+/** SessionStart must never prevent the host conversation from opening. The first MCP call retries. */
+export async function runSourceSessionStartHook(input) {
+    try {
+        const parsed = JSON.parse(input);
+        if (!isRecord(parsed))
+            return JSON.stringify({ continue: true });
+        const identity = resolveSourceSessionFromHookPayload(parsed);
+        if (identity)
+            await bindSourceSession(identity);
+    }
+    catch {
+        // Startup binding is best-effort locally; MCP request metadata provides an exact retry path.
+    }
+    return JSON.stringify({ continue: true });
+}

package/dist/source-session.js

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveClaudeProjectsDir, resolveCodexSessionRoots } from "./local-data-paths.js";
+export const SOURCE_SESSION_BINDING_EVIDENCE = "local_jsonl_tool_call";
+export const SOURCE_SESSION_HOOK_EVIDENCE = "local_session_start_hook";
+export const SOURCE_SESSION_MCP_METADATA_EVIDENCE = "local_mcp_session_metadata";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_IN_TEXT_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const MAX_TAIL_BYTES = 512 * 1024;
+const DEFAULT_MAX_AGE_MS = 15 * 60 * 1000;
+const MAX_RECENT_FILES_PER_PROVIDER = 24;
+function normalizedProviderSessionId(provider, value) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 200 || /\s/.test(normalized)) {
+        throw new Error("source-session ID must contain 1-200 non-whitespace characters");
+    }
+    if (provider === "codex" && !UUID_RE.test(normalized)) {
+        throw new Error("Codex source-session ID must be a UUID");
+    }
+    if (provider === "cowork" && !/^local_[A-Za-z0-9_-]{1,194}$/.test(normalized)) {
+        throw new Error("Cowork source-session ID must use the local_ host session identifier");
+    }
+    return UUID_RE.test(normalized) ? normalized.toLowerCase() : normalized;
+}
+export function verifiedSourceSession(provider, providerSessionId, evidence) {
+    const normalized = normalizedProviderSessionId(provider, providerSessionId);
+    return {
+        provider,
+        providerSessionId: normalized,
+        canonicalKey: `${provider}:${normalized}`,
+        evidence,
+    };
+}
+/**
+ * Resolve identity from host-owned MCP metadata. Unlike tool arguments, these values are attached by
+ * Codex/Claude outside the model-controlled input. The SessionStart hook performs the eager bind;
+ * this resolver lets the MCP process independently attach the same identity on its first real call.
+ */
+export function resolveSourceSessionFromMcpContext(metadata, options = {}) {
+    const host = options.hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
+    const env = options.env ?? process.env;
+    if (host.includes("codex")) {
+        const root = isRecord(metadata) ? metadata : {};
+        const turn = isRecord(root["x-codex-turn-metadata"])
+            ? root["x-codex-turn-metadata"]
+            : {};
+        const candidate = typeof turn.thread_id === "string"
+            ? turn.thread_id
+            : typeof turn.session_id === "string"
+                ? turn.session_id
+                : typeof root.threadId === "string"
+                    ? root.threadId
+                    : "";
+        return candidate
+            ? verifiedSourceSession("codex", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    if (host.includes("claude_desktop") || host === "claude" || host.includes("cowork")) {
+        const candidate = env.CLAUDE_CODE_HOST_SESSION_ID?.trim() ?? "";
+        return candidate
+            ? verifiedSourceSession("cowork", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    if (host.includes("claude_code")) {
+        const candidate = env.CLAUDE_CODE_SESSION_ID?.trim() ?? "";
+        return candidate
+            ? verifiedSourceSession("claude-code", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readableDirectory(candidate) {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function coworkRoot() {
+    const supportRoot = process.env.CLAUDE_DESKTOP_SUPPORT_DIR?.trim()
+        || path.join(os.homedir(), "Library", "Application Support", "Claude");
+    return path.join(supportRoot, "local-agent-mode-sessions");
+}
+function defaultRoots() {
+    const claudeProjects = resolveClaudeProjectsDir();
+    const desktopRoot = coworkRoot();
+    return {
+        codex: resolveCodexSessionRoots().map((root) => root.path),
+        claudeCode: claudeProjects ? [claudeProjects] : [],
+        cowork: readableDirectory(desktopRoot) ? [desktopRoot] : [],
+    };
+}
+function walkJsonlFiles(roots) {
+    const files = [];
+    const pending = roots.filter(readableDirectory);
+    while (pending.length) {
+        const directory = pending.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const target = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "subagents" || entry.name === "workflows")
+                    continue;
+                pending.push(target);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                files.push(target);
+            }
+        }
+    }
+    return files;
+}
+function recentFiles(roots, nowMs, maxAgeMs) {
+    return walkJsonlFiles(roots)
+        .map((file) => {
+        try {
+            return { file, mtimeMs: fs.statSync(file).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((item) => item !== null && item.mtimeMs >= nowMs - maxAgeMs && item.mtimeMs <= nowMs + 5_000)
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, MAX_RECENT_FILES_PER_PROVIDER)
+        .map((item) => item.file);
+}
+function tailContainsBinding(file, bindingToken) {
+    let descriptor = null;
+    try {
+        const stat = fs.statSync(file);
+        const bytes = Math.min(stat.size, MAX_TAIL_BYTES);
+        if (bytes <= 0)
+            return false;
+        descriptor = fs.openSync(file, "r");
+        const buffer = Buffer.allocUnsafe(bytes);
+        fs.readSync(descriptor, buffer, 0, bytes, stat.size - bytes);
+        const tail = buffer.toString("utf8");
+        return tail.includes(bindingToken) && tail.includes("bind_source_session");
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
+    }
+}
+function codexSessionId(file) {
+    let descriptor = null;
+    try {
+        descriptor = fs.openSync(file, "r");
+        const stat = fs.fstatSync(descriptor);
+        const bytes = Math.min(stat.size, 128 * 1024);
+        const buffer = Buffer.allocUnsafe(bytes);
+        fs.readSync(descriptor, buffer, 0, bytes, 0);
+        for (const line of buffer.toString("utf8").split(/\r?\n/)) {
+            if (!line.includes("session_meta"))
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
+                    continue;
+                if (typeof row.payload.parent_thread_id === "string" && row.payload.parent_thread_id)
+                    return null;
+                const raw = typeof row.payload.id === "string"
+                    ? row.payload.id
+                    : typeof row.payload.session_id === "string"
+                        ? row.payload.session_id
+                        : "";
+                return UUID_RE.test(raw) ? raw.toLowerCase() : null;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
+    }
+    return path.basename(file).match(UUID_IN_TEXT_RE)?.[0]?.toLowerCase() ?? null;
+}
+function claudeCodeSessionId(file) {
+    const value = path.basename(file, ".jsonl").trim();
+    return value && value.length <= 200 ? value : null;
+}
+function coworkSessionId(file) {
+    const value = file.split(path.sep).find((part) => /^local_[A-Za-z0-9_-]{1,194}$/.test(part));
+    return value ?? null;
+}
+function enabledProviders(hostPlatform) {
+    const normalized = hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
+    if (normalized.includes("codex"))
+        return ["codex"];
+    if (normalized.includes("claude_code"))
+        return ["claude-code"];
+    if (normalized.includes("claude_desktop") || normalized === "claude") {
+        return ["cowork", "claude-code"];
+    }
+    return ["codex", "claude-code", "cowork"];
+}
+export function resolveSourceSessionFromBindingToken(bindingToken, options = {}) {
+    const normalizedToken = bindingToken.trim().toLowerCase();
+    if (!UUID_RE.test(normalizedToken)) {
+        throw new Error("bindingToken must be a UUID generated fresh for this tool call");
+    }
+    const needsDefaults = options.roots?.codex === undefined
+        || options.roots?.claudeCode === undefined
+        || options.roots?.cowork === undefined;
+    const defaults = needsDefaults ? defaultRoots() : { codex: [], claudeCode: [], cowork: [] };
+    const roots = {
+        codex: options.roots?.codex ?? defaults.codex,
+        claudeCode: options.roots?.claudeCode ?? defaults.claudeCode,
+        cowork: options.roots?.cowork ?? defaults.cowork,
+    };
+    const nowMs = options.nowMs ?? Date.now();
+    const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const matches = [];
+    for (const provider of enabledProviders(options.hostPlatform)) {
+        const providerRoots = provider === "codex"
+            ? roots.codex
+            : provider === "claude-code"
+                ? roots.claudeCode
+                : roots.cowork;
+        for (const file of recentFiles(providerRoots, nowMs, maxAgeMs)) {
+            if (!tailContainsBinding(file, normalizedToken))
+                continue;
+            const providerSessionId = provider === "codex"
+                ? codexSessionId(file)
+                : provider === "claude-code"
+                    ? claudeCodeSessionId(file)
+                    : coworkSessionId(file);
+            if (providerSessionId)
+                matches.push({ provider, providerSessionId });
+        }
+    }
+    const unique = new Map(matches.map((match) => [`${match.provider}:${match.providerSessionId}`, match]));
+    if (unique.size === 0) {
+        throw new Error("Could not verify this binding token in a recent local host JSONL. Retry bind_source_session with a new UUID after the host has recorded the tool call.");
+    }
+    if (unique.size !== 1) {
+        throw new Error("The binding token appeared in multiple source sessions; retry with a fresh UUID");
+    }
+    const verified = [...unique.values()][0];
+    return verifiedSourceSession(verified.provider, verified.providerSessionId, SOURCE_SESSION_BINDING_EVIDENCE);
+}