@echomem/mcp 1.3.0 → 1.3.2

package/dist/setup.js

@@ -15,6 +15,7 @@
 import http from "node:http";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
+import { Worker } from "node:worker_threads";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -22,10 +23,13 @@ import readline from "node:readline";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
-import { runReport, buildReportText } from "./report.js";
-import { cmdMigrate } from "./migrate.js";
-// The connect-device page lives on the main site (WebPageReactVersion → yeahecho.com), where the
-// user already has a session. It calls the EchoMem API cross-origin. Override with ECHO_WEB_URL.
+import { collect, runReport, buildStatsPayload } from "./report.js";
+import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableFastDiscovery, discoverMigratableSessions, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, MIGRATE_CONCURRENCY, } from "./migrate.js";
+import { syncCodexUsage } from "./codex-sync.js";
+import { renderSetupPage } from "./setup-page.js";
+// The hosted connect-device page is now only the account-auth/token courier. The dashboard itself is
+// served by this localhost bridge, where local logs and processed/unprocessed counts never leave the
+// device unless the user explicitly starts migration. Override the hosted auth origin with ECHO_WEB_URL.
 const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 function home(...p) {
@@ -63,7 +67,24 @@ export function buildServerEntry(opts = {}) {
     if (opts.devEntryPath) {
         return { command: "node", args: [opts.devEntryPath] };
     }
-    return { command: "npx", args: ["-y", "@echomem/mcp"] };
+    // Spawn the ALREADY-INSTALLED bridge directly (this node + this script's real path) instead of
+    // `npx -y @echomem/mcp`. `npx -y` re-resolves and, on a cache miss, NETWORK-fetches from the npm
+    // registry on EVERY client start — on a slow/flaky network that delays the MCP handshake past the
+    // client's timeout, so the agent hangs ("connection timed out after 30000ms") and Codex can SIGTERM.
+    // Using process.execPath (the running node) + the realpath'd entry also dodges the GUI-PATH trap:
+    // GUI/IDE-launched clients don't inherit nvm's PATH, so a bare `npx`/`echomem-mcp` may not resolve.
+    // Trade-off: the node path is version-specific under nvm — re-run `setup` after a Node upgrade.
+    try {
+        const entry = fs.realpathSync(process.argv[1] || "");
+        if (entry && fs.existsSync(entry)) {
+            return { command: process.execPath, args: [entry] };
+        }
+    }
+    catch {
+        /* couldn't resolve a local install — fall through to npx */
+    }
+    // Fallback (unresolved local install): at least drop `-y` so npx doesn't auto-INSTALL on every start.
+    return { command: "npx", args: ["@echomem/mcp"] };
 }
 /** The TOML block EchoMem adds to ~/.codex/config.toml. No secret — the bridge reads the keystore. */
 export function codexTomlBlock(entry) {
@@ -71,8 +92,12 @@ export function codexTomlBlock(entry) {
     const args = (Array.isArray(entry.args) ? entry.args : []).map((a) => JSON.stringify(String(a))).join(", ");
     return `[mcp_servers.echomem]\ncommand = ${command}\nargs = [${args}]\n`;
 }
-/** Write/merge the EchoMem entry straight into Codex's config.toml — no `codex` CLI needed. Idempotent. */
-function writeCodexConfig(configPath, entry) {
+/**
+ * Write/merge the EchoMem entry straight into Codex's config.toml — no `codex` CLI needed. Idempotent.
+ * If an `[mcp_servers.echomem]` block already exists it is REPLACED (so re-running `setup` upgrades a
+ * stale `npx -y` entry to the direct path); identical entries are left untouched.
+ */
+export function writeCodexConfig(configPath, entry) {
     let content = "";
     try {
         content = fs.readFileSync(configPath, "utf8");
@@ -80,11 +105,23 @@ function writeCodexConfig(configPath, entry) {
     catch {
         /* fresh config */
     }
-    if (/^\s*\[mcp_servers\.echomem\]/m.test(content))
-        return "exists";
+    const block = codexTomlBlock(entry).trimEnd();
+    const lines = content.split("\n");
+    const start = lines.findIndex((l) => /^\s*\[mcp_servers\.echomem\]\s*$/.test(l));
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    if (start >= 0) {
+        // The block runs from its header to the next top-level [section] (or EOF).
+        let end = start + 1;
+        while (end < lines.length && !/^\s*\[/.test(lines[end]))
+            end++;
+        if (lines.slice(start, end).join("\n").trimEnd() === block)
+            return "exists"; // already correct
+        const next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end)];
+        fs.writeFileSync(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
+        return "wrote"; // replaced a stale entry → caller tells the user to restart Codex
+    }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(configPath, sep + codexTomlBlock(entry));
+    fs.appendFileSync(configPath, sep + block + "\n");
     return "wrote";
 }
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
@@ -113,23 +150,286 @@ function openBrowser(url) {
         /* headless — caller prints the URL */
     }
 }
+function migratableFromDiscovery(disc) {
+    const eta = estimateMigrationEta(disc.pending, disc.skippedActive);
+    return {
+        pending: disc.pending.length,
+        pendingTotal: disc.pendingTotal,
+        alreadyMigrated: disc.alreadyMigrated,
+        skippedActive: disc.skippedActive,
+        limited: disc.limited,
+        eta,
+        buckets: eta.buckets,
+        totalChars: eta.totalChars,
+        approxInputTokens: eta.approxInputTokens,
+        estimatedSeconds: eta.estimatedSeconds,
+        estimatedLabel: eta.estimatedLabel,
+        accountChecked: disc.accountChecked === true,
+        accountCheckFailed: disc.accountCheckFailed === true,
+        accountCheckUnavailable: disc.accountCheckUnavailable === true,
+    };
+}
+function sessionsFromDiscovery(disc) {
+    return {
+        total: disc.sessions.length,
+        codex: disc.codexCount,
+        claudeCode: disc.claudeCount,
+    };
+}
+function migratableFromFastSummary(summary) {
+    return {
+        pending: summary.pending,
+        pendingTotal: summary.pendingTotal,
+        alreadyMigrated: summary.alreadyMigrated,
+        skippedActive: summary.skippedActive,
+        eta: summary.eta,
+        buckets: summary.eta.buckets,
+        totalChars: summary.eta.totalChars,
+        approxInputTokens: summary.eta.approxInputTokens,
+        estimatedSeconds: summary.eta.estimatedSeconds,
+        estimatedLabel: summary.eta.estimatedLabel,
+        quickEstimate: true,
+        accountChecked: summary.accountChecked === true,
+        accountCheckFailed: summary.accountCheckFailed === true,
+        accountCheckUnavailable: summary.accountCheckUnavailable === true,
+    };
+}
+function deferred() {
+    let done = false;
+    let resolveInner;
+    let rejectInner;
+    const promise = new Promise((resolve, reject) => {
+        resolveInner = resolve;
+        rejectInner = reject;
+    });
+    return {
+        promise,
+        resolve: (value) => {
+            if (done)
+                return;
+            done = true;
+            resolveInner(value);
+        },
+        reject: (reason) => {
+            if (done)
+                return;
+            done = true;
+            rejectInner(reason);
+        },
+        settled: () => done,
+    };
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            try {
+                const parsed = JSON.parse(body || "{}");
+                resolve(isObjectRecord(parsed) ? parsed : {});
+            }
+            catch {
+                reject(new Error("bad json"));
+            }
+        });
+        req.on("error", (e) => reject(e instanceof Error ? e : new Error(String(e))));
+    });
+}
+function withTimeout(promise, ms, code, onTimeout) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onTimeout?.();
+            const e = new Error(code);
+            e.code = code;
+            reject(e);
+        }, ms);
+        timer.unref?.();
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function discoverMigratableSessionsOffThread() {
+    const migrateUrl = new URL("./migrate.js", import.meta.url).href;
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { discoverMigratableSessions } from ${JSON.stringify(migrateUrl)};
+
+    try {
+      parentPort?.postMessage({ ok: true, discovery: discoverMigratableSessions() });
+    } catch (error) {
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        worker.once("message", (message) => {
+            settled = true;
+            const msg = message;
+            if (msg.ok === true && msg.discovery && typeof msg.discovery === "object") {
+                resolve(msg.discovery);
+                return;
+            }
+            const err = new Error(typeof msg.message === "string" ? msg.message : "Exact local discovery failed");
+            if (typeof msg.stack === "string")
+                err.stack = msg.stack;
+            reject(err);
+        });
+        worker.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+        worker.once("exit", (code) => {
+            // Reject on ANY unsettled exit (incl. code 0): a worker that exits without posting a result must
+            // not leave this promise pending forever (that was the "stuck at finishing local job sizing" hang).
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Exact local discovery worker exited (code ${code}) without a result`));
+        });
+    });
+}
+/** Build the local forensic "Context Doctor" report on a worker thread so the multi-file scan never
+ * blocks the bridge's event loop (the freeze postmortem: any unbounded sync work on this path is risky). */
+function buildForensicReportOffThread(onProgress) {
+    const forensicsUrl = new URL("./forensics.js", import.meta.url).href;
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { buildForensicReport } from ${JSON.stringify(forensicsUrl)};
+    try {
+      const report = buildForensicReport({ onProgress: (done, total) => parentPort?.postMessage({ progress: { done, total } }) });
+      parentPort?.postMessage({ ok: true, report });
+    } catch (error) {
+      parentPort?.postMessage({ ok: false, message: error instanceof Error ? error.message : String(error) });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        worker.on("message", (message) => {
+            const msg = message;
+            if (msg.progress) {
+                onProgress?.(msg.progress.done, msg.progress.total);
+                return;
+            }
+            settled = true;
+            if (msg.ok === true && msg.report && typeof msg.report === "object")
+                resolve(msg.report);
+            else
+                reject(new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed"));
+            void worker.terminate();
+        });
+        worker.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+        worker.once("exit", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Forensic report worker exited (code ${code}) without a result`));
+        });
+    });
+}
+export function respondMigrate(res, body, status = 200) {
+    if (res.writableEnded)
+        return;
+    res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+}
 /**
- * Start a localhost callback server. Resolves immediately with the bound `port` and a `wait` promise
- * that settles when the connect-device page delivers `{ token, key? }` — by POSTing JSON to
- * `/callback` or hitting `/callback?token=…&key=…`. Splitting port-acquisition from the token-wait
- * lets the caller build the callback URL before the user approves.
+ * Start the persistent localhost bridge used by the connect-device page. It accepts the token,
+ * serves local Wrapped stats, and holds the /migrate response until cmdLogin has created a cloud
+ * import session.
  */
 export function startCallbackServer(opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const dashboardTimeoutMs = 4 * 60 * 60 * 1000;
     const expectedNonce = opts.nonce;
     return new Promise((resolveOuter, rejectOuter) => {
-        let settle;
-        let fail;
-        const wait = new Promise((res, rej) => {
-            settle = res;
-            fail = rej;
-        });
-        const server = http.createServer((req, res) => {
+        const onToken = deferred();
+        const decision = deferred();
+        const migrateRequest = deferred();
+        let stats = null;
+        let authUrl = "";
+        let switchAccountUrl = "";
+        let connected = false;
+        let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
+        let migrateStarted = false;
+        let tokenRefreshHandler = null;
+        let logoutHandler = null;
+        let timer;
+        let closed = false;
+        let server;
+        const checkNonce = (nonce) => !expectedNonce || nonce === expectedNonce;
+        const text = (res, status, body = "") => res.writeHead(status, { "Content-Type": "text/plain" }).end(body);
+        const json = (res, status, body) => res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+        const close = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            if (closed)
+                return;
+            closed = true;
+            server.close();
+        };
+        const armTimeout = () => {
+            if (timer)
+                clearTimeout(timer);
+            const waitMs = onToken.settled() ? dashboardTimeoutMs : timeoutMs;
+            timer = setTimeout(() => {
+                if (!onToken.settled()) {
+                    onToken.reject(new Error("timed out waiting for browser approval"));
+                }
+                else if (!decision.settled()) {
+                    decision.resolve("timeout");
+                }
+                close();
+            }, waitMs);
+            timer.unref?.();
+        };
+        const handleCallback = (res, token, key, nonce) => {
+            if (!checkNonce(nonce))
+                return void text(res, 403, "bad nonce");
+            if (!token)
+                return void text(res, 400, "missing token");
+            const firstToken = !onToken.settled();
+            connected = true;
+            const setupPath = `/setup?nonce=${encodeURIComponent(nonce || "")}&connected=1`;
+            res.writeHead(200, { "Content-Type": "text/html" }).end(`<!doctype html><html><head><meta charset="utf-8"></head><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>EchoMem connected</h2><p>Returning to the local setup page...</p><p><a href="${setupPath}">Continue</a></p><script>(function(){var target=${JSON.stringify(setupPath)};try{if(window.opener&&!window.opener.closed){window.opener.postMessage({type:"echomem:connected",nonce:${JSON.stringify(nonce || "")}},window.location.origin);window.close();setTimeout(function(){window.location.href=target;},500);return;}}catch(_){}window.location.href=target;})();</script></body></html>`);
+            const callbackToken = { token, key };
+            if (firstToken) {
+                onToken.resolve(callbackToken);
+            }
+            else if (tokenRefreshHandler) {
+                Promise.resolve(tokenRefreshHandler(callbackToken)).catch((e) => {
+                    console.error(`Could not refresh local login: ${e instanceof Error ? e.message : String(e)}`);
+                });
+            }
+            armTimeout();
+        };
+        server = http.createServer((req, res) => {
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type");
             res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -138,51 +438,171 @@ export function startCallbackServer(opts = {}) {
             if (req.method === "OPTIONS")
                 return void res.writeHead(204).end();
             const url = new URL(req.url || "/", "http://127.0.0.1");
-            if (!url.pathname.startsWith("/callback"))
-                return void res.writeHead(404).end();
-            const finish = (token, key, nonce) => {
-                // Nonce gates the callback: only the page we opened (which carries the nonce) can post here.
-                if (expectedNonce && nonce !== expectedNonce)
-                    return void res.writeHead(403, { "Content-Type": "text/plain" }).end("bad nonce");
-                if (!token)
-                    return void res.writeHead(400, { "Content-Type": "text/plain" }).end("missing token");
-                res.writeHead(200, { "Content-Type": "text/html" }).end("<html><body style='font-family:system-ui;padding:3rem;text-align:center'><h2>✅ EchoMem connected</h2><p>You can close this tab and return to your editor.</p></body></html>");
-                clearTimeout(timer);
-                server.close();
-                settle({ token, key });
-            };
-            if (req.method === "GET") {
-                finish(url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
-            }
-            else {
-                let body = "";
-                req.on("data", (c) => (body += c));
-                req.on("end", () => {
+            const route = url.pathname;
+            const run = async () => {
+                if (route === "/setup" && req.method === "GET") {
+                    res.writeHead(200, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Cache-Control": "no-store",
+                    }).end(renderSetupPage());
+                    return;
+                }
+                if (route === "/config" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    json(res, 200, { connected, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true });
+                    return;
+                }
+                if (route === "/callback" && req.method === "GET") {
+                    handleCallback(res, url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
+                    return;
+                }
+                if (route === "/callback" && req.method === "POST") {
+                    let body;
                     try {
-                        const parsed = JSON.parse(body || "{}");
-                        finish(parsed.token, parsed.key, parsed.nonce);
+                        body = await readJsonBody(req);
                     }
                     catch {
-                        res.writeHead(400).end("bad json");
+                        text(res, 400, "bad json");
+                        return;
                     }
-                });
-            }
+                    handleCallback(res, asString(body.token), asString(body.key), asString(body.nonce));
+                    return;
+                }
+                if (route === "/stats" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    const payload = opts.getStats ? opts.getStats() : stats;
+                    if (payload == null)
+                        return void res.writeHead(202).end();
+                    json(res, 200, payload);
+                    return;
+                }
+                if (route === "/report" && req.method === "GET") {
+                    // Local forensic "Context Doctor" report — computed locally, served BEFORE auth (scan-first).
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    const payload = opts.getReport ? opts.getReport() : null;
+                    if (payload == null) {
+                        // 202 carries scan progress so the page can show a live "scanned N/total" indicator.
+                        const prog = opts.getReportProgress ? opts.getReportProgress() : { scanned: 0, total: 0 };
+                        return void res.writeHead(202, { "Content-Type": "application/json" }).end(JSON.stringify(prog));
+                    }
+                    json(res, 200, payload);
+                    return;
+                }
+                if (route === "/progress" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    json(res, 200, progress);
+                    return;
+                }
+                if (route === "/logout" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    if (!checkNonce(asString(body.nonce)))
+                        return void text(res, 403, "bad nonce");
+                    if (migrateStarted && (progress.status === "starting" || progress.status === "running")) {
+                        json(res, 409, { error: "MIGRATION_RUNNING", message: "Wait for extraction to finish before signing out locally." });
+                        return;
+                    }
+                    try {
+                        fs.rmSync(new KeyStore().path(), { force: true });
+                    }
+                    catch {
+                        /* already logged out locally */
+                    }
+                    connected = false;
+                    stats = null;
+                    migrateStarted = false;
+                    progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
+                    json(res, 200, { ok: true, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true });
+                    Promise.resolve()
+                        .then(() => logoutHandler?.())
+                        .catch((e) => {
+                        console.error(`Could not reset local login state: ${e instanceof Error ? e.message : String(e)}`);
+                    });
+                    return;
+                }
+                if (route === "/migrate" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    if (!checkNonce(asString(body.nonce)))
+                        return void text(res, 403, "bad nonce");
+                    if (migrateStarted)
+                        return void json(res, 409, { error: "MIGRATE_IN_PROGRESS" });
+                    migrateStarted = true;
+                    const safety = setTimeout(() => {
+                        respondMigrate(res, { error: "IMPORT_START_TIMEOUT" }, 504);
+                    }, 30_000);
+                    safety.unref?.();
+                    migrateRequest.resolve({ res });
+                    decision.resolve("migrate");
+                    return;
+                }
+                if (route === "/skip" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    if (!checkNonce(asString(body.nonce)))
+                        return void text(res, 403, "bad nonce");
+                    json(res, 200, { ok: true });
+                    decision.resolve("skip");
+                    close();
+                    return;
+                }
+                res.writeHead(404).end();
+            };
+            run().catch((e) => {
+                if (!res.writableEnded)
+                    text(res, 500, e instanceof Error ? e.message : String(e));
+            });
         });
-        const timer = setTimeout(() => {
-            server.close();
-            fail(new Error("timed out waiting for browser approval"));
-        }, timeoutMs);
+        armTimeout();
         server.on("error", (e) => rejectOuter(e));
         server.listen(0, "127.0.0.1", () => {
             const addr = server.address();
             const port = typeof addr === "object" && addr ? addr.port : 0;
             resolveOuter({
                 port,
-                wait,
-                close: () => {
-                    clearTimeout(timer);
-                    server.close();
+                onToken: onToken.promise,
+                wait: onToken.promise,
+                decision: decision.promise,
+                migrateRequest: migrateRequest.promise,
+                setTokenRefreshHandler: (handler) => {
+                    tokenRefreshHandler = handler;
+                },
+                setLogoutHandler: (handler) => {
+                    logoutHandler = handler;
                 },
+                setAuthUrl: (url, nextSwitchAccountUrl) => {
+                    authUrl = url;
+                    switchAccountUrl = nextSwitchAccountUrl || url;
+                },
+                setStats: (s) => {
+                    stats = s;
+                },
+                setProgress: (p) => {
+                    progress = p;
+                },
+                close,
             });
         });
     });
@@ -196,6 +616,42 @@ function authedAxios(token) {
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
     });
 }
+function formatVerificationError(error) {
+    if (axios.isAxiosError(error)) {
+        const status = typeof error.response?.status === "number" ? error.response.status : null;
+        const statusText = error.response?.statusText ? ` ${error.response.statusText}` : "";
+        const requestPath = typeof error.config?.url === "string" ? error.config.url : "";
+        const endpoint = requestPath
+            ? requestPath.startsWith("http")
+                ? requestPath
+                : `${API_BASE_URL}${requestPath}`
+            : API_BASE_URL;
+        const statusLabel = status ? `HTTP ${status}${statusText}` : error.code || error.message;
+        const localApi = /^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?/.test(API_BASE_URL);
+        const routeHint = status === 404 && requestPath.includes("/api/extension/account/encryption")
+            ? localApi
+                ? "That usually means ECHO_API_BASE_URL is pointing at a different local app or an older EchoMem API server."
+                : "That usually means the EchoMem API route is missing on the configured server."
+            : null;
+        const localHint = localApi ? "Start the EchoMem-Chrome Next API on that port, or unset ECHO_API_BASE_URL to use production." : null;
+        return [
+            `Could not verify this device token against ${endpoint}: ${statusLabel}.`,
+            routeHint,
+            localHint,
+        ].filter(Boolean).join(" ");
+    }
+    return `Could not verify this device token: ${error instanceof Error ? error.message : String(error)}`;
+}
+async function verifyAndPrint(input) {
+    try {
+        console.log(await verifyAndStore(input));
+        return true;
+    }
+    catch (error) {
+        console.error(`❌ ${formatVerificationError(error)}`);
+        return false;
+    }
+}
 /**
  * Verify supplied secrets and persist them. Given a token (required), and EITHER a base64 key or a
  * passphrase (optional — only for encrypted accounts), this verifies the key against the server's
@@ -203,8 +659,8 @@ function authedAxios(token) {
  */
 export async function verifyAndStore(input) {
     const store = new KeyStore();
-    store.saveToken(input.token);
     const config = await fetchEncryptionConfig(authedAxios(input.token));
+    store.saveToken(input.token);
     if (!config.enabled) {
         return input.key || input.passphrase
             ? "Token saved. (Account is not encrypted — the supplied key was ignored.)"
@@ -293,43 +749,499 @@ async function cmdSetup(flags) {
     }
     console.log("");
     await cmdLogin(flags);
-    // Onboarding reveal: show the local usage audit right after connecting (proactive trigger).
-    try {
-        console.log("\n" + (await buildReportText(true)));
-    }
-    catch {
-        /* report is best-effort — never block setup */
-    }
 }
 async function cmdLogin(flags) {
     // Manual path (also the headless path): secrets supplied as flags.
     if (typeof flags.token === "string") {
-        const msg = await verifyAndStore({
+        const ok = await verifyAndPrint({
             token: flags.token,
             key: typeof flags.key === "string" ? flags.key : undefined,
             passphrase: typeof flags.passphrase === "string" ? flags.passphrase : undefined,
         });
-        console.log(msg);
+        if (!ok)
+            process.exitCode = 1;
         return;
     }
-    // Browser path: open the connect-device page pointed at our localhost callback. The nonce gates
-    // the callback so only the page we opened can deliver the token+key.
+    // Browser path: open a localhost dashboard. It briefly leaves for hosted auth, then returns here
+    // after the web page has delivered the token+key to the callback. The nonce gates every local route.
     console.log("Opening your browser to approve this device…");
     const nonce = randomUUID();
-    const { port, wait, close } = await startCallbackServer({ nonce });
-    const callbackUrl = `http://127.0.0.1:${port}/callback`;
-    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}`;
-    openBrowser(connectUrl);
-    console.log(`If it didn't open, visit:\n  ${connectUrl}\n`);
+    let stats = null;
+    let forensicReport = null;
+    let forensicProgress = { scanned: 0, total: 0 };
+    const srv = await startCallbackServer({
+        nonce,
+        getStats: () => stats,
+        getReport: () => forensicReport,
+        getReportProgress: () => forensicProgress,
+    });
+    const callbackUrl = `http://127.0.0.1:${srv.port}/callback`;
+    const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
+    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}&return_to=${encodeURIComponent(localSetupUrl)}`;
+    const switchAccountUrl = new URL(connectUrl);
+    // The hosted connect-device page should clear its own Supabase/browser session before minting
+    // the localhost token when this hint is present. Localhost cannot safely clear yeahecho.com auth.
+    switchAccountUrl.searchParams.set("force_signout", "1");
+    switchAccountUrl.searchParams.set("prompt", "login");
+    srv.setAuthUrl(connectUrl, switchAccountUrl.toString());
+    openBrowser(localSetupUrl);
+    console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
+    // Scan-first: build the local forensic "Context Doctor" report off-thread so the page shows it
+    // BEFORE the user connects an account (the scan is local-only; nothing leaves the machine).
+    buildForensicReportOffThread((done, total) => {
+        forensicProgress = { scanned: done, total };
+    })
+        .then((r) => {
+        forensicReport = r;
+    })
+        .catch((e) => {
+        console.error(`Could not build the local report: ${e instanceof Error ? e.message : String(e)}`);
+    });
+    let token;
+    let key;
     try {
-        const { token, key } = await wait;
-        const msg = await verifyAndStore({ token, key });
-        console.log(msg);
+        ({ token, key } = await srv.onToken);
     }
     catch (e) {
-        close();
+        srv.close();
         console.error(`❌ ${e?.message || e}. You can instead run: echomem-mcp login --token ec_… [--passphrase <vault pass>]`);
         process.exitCode = 1;
+        return;
+    }
+    if (!await verifyAndPrint({ token, key })) {
+        srv.close();
+        process.exitCode = 1;
+        return;
+    }
+    let disc = null;
+    let exactDiscovery = Promise.resolve(null);
+    let refreshGeneration = 0;
+    let latestPendingEstimate = 0;
+    const resetLocalLoginState = () => {
+        refreshGeneration++;
+        stats = null;
+        disc = null;
+        exactDiscovery = Promise.resolve(null);
+        latestPendingEstimate = 0;
+        srv.setStats(null);
+        srv.setProgress({
+            status: "idle",
+            total: 0,
+            completed: 0,
+            running: 0,
+            queued: 0,
+            failed: 0,
+            extracted: 0,
+        });
+    };
+    const refreshLocalStatsForToken = async (activeToken) => {
+        const generation = ++refreshGeneration;
+        let lastProcessedImportKeys = null;
+        let importStatusUnavailable = false;
+        const quickDiscovery = discoverMigratableFastDiscovery();
+        const quick = summarizeFastMigratableDiscovery(quickDiscovery);
+        let migratable = migratableFromFastSummary(quick);
+        latestPendingEstimate = migratable.pending;
+        let sessionSummary = {
+            total: quick.sessions,
+            codex: quick.codexCount,
+            claudeCode: quick.claudeCount,
+        };
+        stats = await buildStatsPayload([], {
+            partial: true,
+            skipMemoryCount: true,
+            sessions: sessionSummary,
+            migratable,
+            discovery: { phase: "quick", exact: false },
+        });
+        if (generation !== refreshGeneration)
+            return;
+        srv.setStats(stats);
+        srv.setProgress({
+            status: "idle",
+            total: quick.pending,
+            completed: 0,
+            running: 0,
+            queued: quick.pending,
+            failed: 0,
+            extracted: 0,
+        });
+        const fastAccountController = new AbortController();
+        const fastAccountCheck = withTimeout(fetchProcessedImportKeys(activeToken, quickDiscovery.sessions, fastAccountController.signal), 8_000, "ACCOUNT_STATUS_TIMEOUT", () => fastAccountController.abort()).then(async (processedKeys) => {
+            if (generation !== refreshGeneration)
+                return;
+            lastProcessedImportKeys = processedKeys;
+            const cloudQuick = applyFastAccountImportStatus(quickDiscovery, processedKeys);
+            const currentPhase = stats?.discovery?.phase;
+            if (currentPhase !== "quick")
+                return;
+            const cloudSummary = summarizeFastMigratableDiscovery(cloudQuick);
+            migratable = migratableFromFastSummary(cloudSummary);
+            latestPendingEstimate = migratable.pending;
+            sessionSummary = {
+                total: cloudSummary.sessions,
+                codex: cloudSummary.codexCount,
+                claudeCode: cloudSummary.claudeCount,
+            };
+            const cloudPayload = await buildStatsPayload([], {
+                partial: true,
+                skipMemoryCount: true,
+                sessions: sessionSummary,
+                migratable,
+                discovery: { phase: "account", exact: false },
+            });
+            if (generation !== refreshGeneration)
+                return;
+            stats = cloudPayload;
+            srv.setStats(cloudPayload);
+            srv.setProgress({
+                status: "idle",
+                total: cloudSummary.pending,
+                completed: 0,
+                running: 0,
+                queued: cloudSummary.pending,
+                failed: 0,
+                extracted: 0,
+            });
+        }).catch(async (e) => {
+            if (generation !== refreshGeneration)
+                return;
+            if (isImportStatusUnsupported(e)) {
+                importStatusUnavailable = true;
+                const unavailableQuick = markFastAccountImportStatusUnavailable(quickDiscovery);
+                const currentPhase = stats?.discovery?.phase;
+                if (currentPhase !== "quick")
+                    return;
+                const unavailableSummary = summarizeFastMigratableDiscovery(unavailableQuick);
+                migratable = migratableFromFastSummary(unavailableSummary);
+                latestPendingEstimate = migratable.pending;
+                sessionSummary = {
+                    total: unavailableSummary.sessions,
+                    codex: unavailableSummary.codexCount,
+                    claudeCode: unavailableSummary.claudeCount,
+                };
+                const unavailablePayload = await buildStatsPayload([], {
+                    partial: true,
+                    skipMemoryCount: true,
+                    sessions: sessionSummary,
+                    migratable,
+                    discovery: { phase: "account", exact: false },
+                });
+                if (generation !== refreshGeneration)
+                    return;
+                stats = unavailablePayload;
+                srv.setStats(unavailablePayload);
+                srv.setProgress({
+                    status: "idle",
+                    total: unavailableSummary.pending,
+                    completed: 0,
+                    running: 0,
+                    queued: unavailableSummary.pending,
+                    failed: 0,
+                    extracted: 0,
+                });
+                return;
+            }
+            if (generation === refreshGeneration) {
+                console.error(`Could not check this EchoMem account's import status quickly: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+        exactDiscovery = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                void (async () => {
+                    try {
+                        // Start the local sizing pass without waiting on cloud/account status. The
+                        // account check is useful for tighter counts, but extraction can safely start
+                        // from local candidates because the import path skips true duplicates.
+                        await delay(250);
+                        resolve(await discoverMigratableSessionsOffThread());
+                    }
+                    catch (e) {
+                        reject(e instanceof Error ? e : new Error(String(e)));
+                    }
+                })();
+            }, 250);
+            timer.unref?.();
+        }).then(async (exact) => {
+            if (generation !== refreshGeneration)
+                return disc;
+            const initialExact = lastProcessedImportKeys
+                ? applyAccountImportStatus(exact, lastProcessedImportKeys)
+                : importStatusUnavailable
+                    ? markAccountImportStatusUnavailable(exact)
+                    : exact;
+            disc = initialExact;
+            migratable = migratableFromDiscovery(initialExact);
+            latestPendingEstimate = migratable.pending;
+            sessionSummary = sessionsFromDiscovery(initialExact);
+            const partialPayload = await buildStatsPayload([], {
+                partial: true,
+                skipMemoryCount: true,
+                sessions: sessionSummary,
+                migratable,
+                discovery: { phase: "exact", exact: true },
+            });
+            if (generation !== refreshGeneration)
+                return disc;
+            stats = partialPayload;
+            srv.setStats(partialPayload);
+            srv.setProgress({
+                status: "idle",
+                total: initialExact.pending.length,
+                completed: 0,
+                running: 0,
+                queued: initialExact.pending.length,
+                failed: 0,
+                extracted: 0,
+            });
+            void (async () => {
+                let reconciled = initialExact;
+                try {
+                    await fastAccountCheck;
+                    const controller = new AbortController();
+                    const processedKeys = await withTimeout(fetchProcessedImportKeys(activeToken, exact.sessions, controller.signal), 15_000, "ACCOUNT_STATUS_TIMEOUT", () => controller.abort());
+                    lastProcessedImportKeys = processedKeys;
+                    reconciled = applyAccountImportStatus(exact, processedKeys);
+                }
+                catch (e) {
+                    if (lastProcessedImportKeys) {
+                        reconciled = applyAccountImportStatus(exact, lastProcessedImportKeys);
+                        if (!isImportStatusUnsupported(e)) {
+                            console.error(`Could not refresh this EchoMem account's exact import status; keeping the last successful account check. ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                    }
+                    else if (isImportStatusUnsupported(e)) {
+                        reconciled = markAccountImportStatusUnavailable(exact);
+                    }
+                    else {
+                        reconciled = markAccountImportStatusFailed(exact);
+                        console.error(`Could not check this EchoMem account's import status: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
+                if (generation !== refreshGeneration)
+                    return;
+                disc = reconciled;
+                migratable = migratableFromDiscovery(reconciled);
+                latestPendingEstimate = migratable.pending;
+                sessionSummary = sessionsFromDiscovery(reconciled);
+                const reconciledPayload = await buildStatsPayload([], {
+                    partial: true,
+                    skipMemoryCount: true,
+                    sessions: sessionSummary,
+                    migratable,
+                    discovery: { phase: "exact", exact: true },
+                });
+                if (generation !== refreshGeneration)
+                    return;
+                stats = reconciledPayload;
+                srv.setStats(reconciledPayload);
+                srv.setProgress({
+                    status: "idle",
+                    total: reconciled.pending.length,
+                    completed: 0,
+                    running: 0,
+                    queued: reconciled.pending.length,
+                    failed: 0,
+                    extracted: 0,
+                });
+                const fullPayload = await buildStatsPayload(collect(), {
+                    sessions: sessionSummary,
+                    migratable,
+                    discovery: { phase: "full", exact: true },
+                });
+                if (generation !== refreshGeneration)
+                    return;
+                stats = fullPayload;
+                srv.setStats(fullPayload);
+            })();
+            return initialExact;
+        }).catch((e) => {
+            if (generation === refreshGeneration) {
+                console.error(`Could not finish exact local extraction estimate: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return disc;
+        });
+    };
+    srv.setLogoutHandler(resetLocalLoginState);
+    srv.setTokenRefreshHandler(async ({ token: nextToken, key: nextKey }) => {
+        if (!await verifyAndPrint({ token: nextToken, key: nextKey }))
+            return;
+        await refreshLocalStatsForToken(nextToken);
+    });
+    await refreshLocalStatsForToken(token);
+    const choice = await srv.decision;
+    if (choice === "migrate") {
+        const { res } = await srv.migrateRequest;
+        let migrateResponded = false;
+        const sendMigrate = (body, status = 200) => {
+            if (migrateResponded)
+                return;
+            migrateResponded = true;
+            respondMigrate(res, body, status);
+        };
+        let activeSessionId = "";
+        let activeJobCount = latestPendingEstimate;
+        let progressDone = 0;
+        let progressFailed = 0;
+        let progressExtracted = 0;
+        if (!disc) {
+            srv.setProgress({
+                status: "starting",
+                total: activeJobCount,
+                completed: 0,
+                running: 0,
+                queued: activeJobCount,
+                failed: 0,
+                extracted: 0,
+                latest: "Finishing local job sizing before import starts.",
+            });
+            sendMigrate({
+                status: "preparing",
+                jobCount: activeJobCount,
+                message: "Finishing local job sizing before import starts.",
+            });
+        }
+        let exact = disc;
+        if (!exact) {
+            // Off-thread sizing normally resolves in ~20s; cap the wait and fall back to an in-process pass so
+            // a stalled/contended worker can never leave extraction stuck at "finishing local job sizing".
+            exact = await withTimeout(exactDiscovery, 40_000, "SIZING_TIMEOUT").catch(() => null);
+            if (!exact) {
+                srv.setProgress({ status: "starting", total: activeJobCount, completed: 0, running: 0, queued: activeJobCount, failed: 0, extracted: 0, latest: "Sizing your sessions…" });
+                try {
+                    exact = discoverMigratableSessions();
+                }
+                catch (e) {
+                    console.error(`Direct local sizing failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+        }
+        if (!exact) {
+            srv.setProgress({
+                status: "failed",
+                total: activeJobCount,
+                completed: progressDone,
+                running: 0,
+                queued: Math.max(0, activeJobCount - progressDone - progressFailed),
+                failed: progressFailed || 1,
+                extracted: progressExtracted,
+                error: "Local session discovery did not finish.",
+            });
+            sendMigrate({ error: "IMPORT_START_FAILED", message: "Local session discovery did not finish." }, 500);
+            srv.close();
+            process.exitCode = 1;
+            return;
+        }
+        activeJobCount = exact.pending.length;
+        const updateProgress = (patch) => {
+            srv.setProgress({
+                status: "running",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
+                running: Math.min(MIGRATE_CONCURRENCY, Math.max(0, activeJobCount - progressDone - progressFailed)),
+                queued: Math.max(0, activeJobCount - progressDone - progressFailed - MIGRATE_CONCURRENCY),
+                failed: progressFailed,
+                extracted: progressExtracted,
+                ...patch,
+            });
+        };
+        try {
+            if (exact.pending.length === 0) {
+                srv.setProgress({
+                    status: "completed",
+                    total: 0,
+                    completed: 0,
+                    running: 0,
+                    queued: 0,
+                    failed: 0,
+                    extracted: 0,
+                    latest: "No unprocessed local conversations found.",
+                });
+                sendMigrate({ error: "NO_PENDING_SESSIONS" }, 409);
+                srv.close();
+                console.log("Setup complete — no unprocessed local conversations to extract.");
+                return;
+            }
+            updateProgress({ status: "starting", running: 0, queued: exact.pending.length, latest: "Creating import session." });
+            const controller = new AbortController();
+            const h = await withTimeout(startMigration({
+                pending: exact.pending,
+                signal: controller.signal,
+                onProgress: (ev) => {
+                    if (ev.error) {
+                        progressFailed += 1;
+                    }
+                    else {
+                        progressDone += 1;
+                        progressExtracted += ev.memories ?? 0;
+                    }
+                    updateProgress({
+                        latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
+                    });
+                },
+            }), 30_000, "IMPORT_START_TIMEOUT", () => controller.abort());
+            activeSessionId = h.sessionId;
+            activeJobCount = h.jobCount;
+            updateProgress({ status: "running", sessionId: h.sessionId, jobCount: h.jobCount, total: h.jobCount, capped: h.capped, latest: "Import session created." });
+            sendMigrate({ sessionId: h.sessionId, jobCount: h.jobCount, ...(h.capped ? { capped: h.capped } : {}) });
+            console.log("Migrating your history… keep this terminal open until it completes.");
+            console.log(`Migration metrics: ${h.metricsFile}`);
+            const r = await h.done;
+            srv.setProgress({
+                status: r.failed || r.stoppedReason ? "failed" : "completed",
+                sessionId: h.sessionId,
+                jobCount: h.jobCount,
+                capped: h.capped,
+                total: h.jobCount,
+                completed: r.migrated,
+                running: 0,
+                queued: 0,
+                failed: r.failed,
+                extracted: r.extracted,
+                latest: r.stoppedReason ? `Stopped: ${r.stoppedReason}` : "Import complete.",
+                ...(r.stoppedReason ? { error: r.stoppedReason } : {}),
+            });
+            console.log(`Import finished: ${r.migrated} imported, ${r.extracted} memories, ${r.failed} failed.`);
+            if (r.stoppedReason || r.failed)
+                process.exitCode = 1;
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            srv.close();
+        }
+        catch (e) {
+            srv.setProgress({
+                status: "failed",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
+                running: 0,
+                queued: Math.max(0, activeJobCount - progressDone - progressFailed),
+                failed: progressFailed || 1,
+                extracted: progressExtracted,
+                error: String(e?.message || e),
+            });
+            if (e?.code === "NOT_LOGGED_IN")
+                sendMigrate({ error: "NOT_LOGGED_IN" }, 401);
+            else if (e?.code === "FORBIDDEN_SCOPE")
+                sendMigrate({ error: "FORBIDDEN_SCOPE" }, 403);
+            else if (e?.code === "VAULT_LOCKED")
+                sendMigrate({ error: "VAULT_LOCKED" }, 409);
+            else if (e?.code === "NO_PENDING_SESSIONS")
+                sendMigrate({ error: "NO_PENDING_SESSIONS" }, 409);
+            else if (e?.code === "IMPORT_START_TIMEOUT")
+                sendMigrate({ error: "IMPORT_START_TIMEOUT" }, 504);
+            else
+                sendMigrate({ error: "IMPORT_START_FAILED", message: String(e?.message || e) }, 500);
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            srv.close();
+            process.exitCode = 1;
+        }
+    }
+    else {
+        console.log("Setup complete — run `echomem-mcp migrate` later to back-fill your history.");
+        srv.close();
     }
 }
 async function cmdUnlock(flags) {
@@ -389,10 +1301,18 @@ Usage:
   echomem-mcp logout                Remove stored credentials
   echomem-mcp report [--json]       Your AI coding memory audit (local, no login, $0)
   echomem-mcp migrate [--since D]   Import your existing Codex/Claude history into your memory
+  echomem-mcp migrate --estimate    Estimate migration size/time metadata without uploading transcripts
+  echomem-mcp migrate --max-chars N Import only sessions up to N assembled text chars
+  echomem-mcp migrate --min-chars N Import only sessions at least N assembled text chars
+  echomem-mcp migrate --largest --limit 1  Sample the largest pending session first
+  echomem-mcp migrate --include-active  Include sessions modified in the last 5 minutes
+  echomem-mcp migrate --metrics-file PATH  Write local per-session timing metadata JSONL
+  echomem-mcp sync-usage            Sync safe Codex JSONL usage summaries to EchoMem/Amplitude
 
 Manual / headless:
   echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
+  echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 `;
 /** Returns true if argv was a recognized subcommand (and was handled). */
 export async function runCli(argv) {
@@ -420,6 +1340,9 @@ export async function runCli(argv) {
         case "migrate":
             await cmdMigrate(flags);
             return true;
+        case "sync-usage":
+            await syncCodexUsage(argv.slice(1));
+            return true;
         case "help":
         case "--help":
         case "-h":