@echomem/mcp 1.4.39 → 1.4.41

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-page/client-extraction.js

@@ -1285,10 +1285,12 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         var slot = document.getElementById("setupPlan");
         if (!slot) return;
         var readySettings = slot.closest ? slot.closest(".readySettings") : null;
+        var planGateDecision = slot.closest ? slot.closest(".planGateDecision") : null;
         if (!canExtract) {
           slot.innerHTML = "";
           slot.classList.add("is-hidden");
           if (readySettings) readySettings.classList.remove("is-plan-open", "is-checkout-pending");
+          if (planGateDecision) planGateDecision.classList.remove("is-checkout-pending");
           renderBillingCommitment("");
           return;
         }
@@ -1303,6 +1305,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
             return;
           }
           if (readySettings) readySettings.classList.remove("is-plan-open", "is-checkout-pending");
+          if (planGateDecision) planGateDecision.classList.remove("is-checkout-pending");
           rememberSetupPlanChoice("");
           setupPlanChoice = "paid";
           var planLabel = plan.charAt(0).toUpperCase() + plan.slice(1);
@@ -1329,6 +1332,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         }
         if (setupPlanChoice === "free") {
           if (readySettings) readySettings.classList.remove("is-plan-open", "is-checkout-pending");
+          if (planGateDecision) planGateDecision.classList.remove("is-checkout-pending");
           slot.innerHTML = '<div class="setupPlanConfirmed"><span class="setupPlanConfirmedIcon" aria-hidden="true">' + setupIcon("check") + '</span><span class="setupPlanConfirmedCopy"><strong>Original Echo</strong><span>100 coding sessions and 100 memory recalls each week.</span></span><button type="button" class="textButton" id="changeSetupPlan">Change</button></div>';
           renderBillingCommitment("");
           var changeBtn = document.getElementById("changeSetupPlan");
@@ -1352,6 +1356,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
             readySettings.classList.remove("is-plan-open");
             readySettings.classList.add("is-checkout-pending");
           }
+          if (planGateDecision) planGateDecision.classList.add("is-checkout-pending");
           var selectedPaidPlan = pendingPaidPlan === "power" ? "Power" : "Pro";
           var pendingHasTrial = !billingStatus || billingStatus.trialAvailable !== false;
           var pendingPrice = pendingPaidPlan === "power" ? "$100" : "$20";
@@ -1361,15 +1366,15 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
             : "Checking automatically every few seconds");
           slot.innerHTML =
             '<section class="setupPlanChoice setupPlanCheckout" aria-labelledby="setupPlanHeading">' +
-              '<div class="setupPlanIntro"><h3 id="setupPlanHeading">' + esc(pendingHasTrial ? selectedPaidPlan + " trial — $0 today" : selectedPaidPlan + " subscription") + '</h3><p>Finish in Stripe. This page updates automatically.</p></div>' +
+              '<div class="setupPlanIntro"><h3 id="setupPlanHeading">' + esc(pendingHasTrial ? selectedPaidPlan + " trial — $0 today" : selectedPaidPlan + " subscription") + '</h3><p>Complete checkout in Stripe, then return here. This page updates automatically.</p></div>' +
               '<dl class="checkoutCommitment">' +
                 '<div><dt>Today</dt><dd>' + esc(pendingHasTrial ? "$0" : pendingPrice) + '</dd></div>' +
                 '<div><dt>History import</dt><dd>' + esc(pendingLimit) + ' sessions</dd></div>' +
                 '<div><dt>' + esc(pendingHasTrial ? "First charge" : "Billing") + '</dt><dd>' + esc(pendingHasTrial ? pendingPrice + " on " + trialChargeDateText() : pendingPrice + "/month now") + '</dd></div>' +
               '</dl>' +
-              '<div class="checkoutActions"><button type="button" class="primary" id="continueSelectedPaidPlan">Reopen Stripe checkout</button><button type="button" class="secondary" id="checkPaymentStatus">Check payment status</button></div>' +
+              '<div class="checkoutActions"><button type="button" class="primary" id="continueSelectedPaidPlan">Reopen Stripe checkout</button></div>' +
               '<p class="checkoutPollStatus" id="setupPlanStatus" role="status" aria-live="polite">' + esc(pendingStatus) + '</p>' +
-              '<div class="setupPlanFoot"><button type="button" class="textButton" id="changeSelectedPaidPlan">Choose another plan</button></div>' +
+              '<div class="setupPlanFoot"><button type="button" class="textButton" id="checkPaymentStatus">Check payment status</button><button type="button" class="textButton" id="changeSelectedPaidPlan">Choose another plan</button></div>' +
             '</section>';
           var checkPaid = document.getElementById("checkPaymentStatus");
           if (checkPaid) checkPaid.onclick = function () {
@@ -1395,6 +1400,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           readySettings.classList.remove("is-checkout-pending");
           readySettings.classList.add("is-plan-open");
         }
+        if (planGateDecision) planGateDecision.classList.remove("is-checkout-pending");
         slot.innerHTML = renderPlanHabitat();
         renderBillingCommitment("");
         bindPlanHabitat();

package/dist/setup-page/styles-mvp.js

@@ -667,6 +667,52 @@ export const SETUP_PAGE_STYLES_MVP = String.raw `
       color: var(--echo-ink-text);
       text-align: left;
     }
+    .planGateDecision.is-checkout-pending {
+      width: min(680px, 100%);
+    }
+    .planGateDecision.is-checkout-pending .setupPlanSlot {
+      margin-top: 8px;
+    }
+    .planGateDecision.is-checkout-pending .setupPlanCheckout {
+      display: grid;
+      gap: 16px;
+      margin: 0 auto;
+      overflow: visible;
+      border: 1px solid rgba(26,58,143,0.11);
+      border-radius: 20px;
+      background: rgba(255,255,255,0.78);
+      padding: clamp(22px, 4vw, 34px);
+      box-shadow: 0 22px 55px -42px rgba(20,36,84,0.5);
+      backdrop-filter: blur(10px);
+    }
+    .planGateDecision.is-checkout-pending .setupPlanIntro {
+      padding: 0;
+    }
+    .planGateDecision.is-checkout-pending .setupPlanIntro h3 {
+      font-size: clamp(25px, 3vw, 32px);
+      line-height: 1.2;
+    }
+    .planGateDecision.is-checkout-pending .setupPlanIntro p {
+      max-width: 620px;
+      margin-top: 7px;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+    .planGateDecision.is-checkout-pending .checkoutActions {
+      grid-template-columns: 1fr;
+    }
+    .planGateDecision.is-checkout-pending .setupPlanFoot {
+      justify-content: flex-start;
+      gap: 18px;
+      margin-top: 0;
+    }
+    .planGateDecision.is-checkout-pending .setupPlanFoot .textButton {
+      min-height: 0;
+      padding: 2px 0;
+      color: var(--echo-ink-mute);
+      font-size: 11px;
+      font-weight: 700;
+    }
     .mvpPricing {
       width: 100%;
     }

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.",
@@ -416,7 +417,26 @@ 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)];
+    // 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) => {
+        try {
+            execFileSync("claude", ["mcp", "remove", "echomem", "-s", scope], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 10000,
+            });
+            return true;
+        }
+        catch {
+            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",
@@ -431,14 +451,11 @@ export function writeClaudeCodeConfig(entry) {
         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.
+    // 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 {
-        execFileSync("claude", ["mcp", "remove", "echomem", "-s", "local"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: 10000,
-        });
+        if (!removeFromScope("user"))
+            return "unavailable";
         execFileSync("claude", addArguments, {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
@@ -2686,8 +2703,8 @@ async function cmdSetup(flags) {
     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"]) {
@@ -2777,7 +2794,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");
@@ -2788,8 +2805,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.");
     }
@@ -3794,7 +3813,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);
+}