@echomem/mcp 1.4.7 → 1.4.9

package/dist/setup.js

@@ -1,5 +1,5 @@
 /**
- * `echomem-mcp setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
+ * `echomem-mcp init | setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
  *
  * Design goals from the spec:
  *   - One command → one browser approval → one reload.
@@ -20,7 +20,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
@@ -28,7 +28,8 @@ import { collect, runReport, buildStatsPayload } from "./report.js";
 import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableFastDiscovery, discoverMigratableSessions, discoverPendingSessionsTargeted, 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";
-import { repoLabel } from "./forensics.js";
+import { parseSetupPreviewState } from "./setup-preview.js";
+import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
 import { installHooks } 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";
@@ -40,6 +41,50 @@ const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.
 function home(...p) {
     return path.join(os.homedir(), ...p);
 }
+/** Map a source entry to its compiled sibling without ever guessing outside this package. */
+export function compiledDistPathForSource(entry) {
+    if (!entry.endsWith(".ts") || !path.isAbsolute(entry))
+        return null;
+    const normalized = path.normalize(entry);
+    const srcSegment = `${path.sep}src${path.sep}`;
+    const srcIndex = normalized.lastIndexOf(srcSegment);
+    if (srcIndex < 0)
+        return null;
+    const packageRoot = normalized.slice(0, srcIndex) || path.parse(normalized).root;
+    const relativeSource = normalized.slice(srcIndex + srcSegment.length);
+    const candidate = path.join(packageRoot, "dist", relativeSource.replace(/\.ts$/, ".js"));
+    try {
+        const real = fs.realpathSync(candidate);
+        if (!fs.statSync(real).isFile())
+            return null;
+        fs.accessSync(real, fs.constants.R_OK);
+        return real;
+    }
+    catch {
+        return null;
+    }
+}
+function runtimeModuleUrl(name) {
+    const jsUrl = new URL(`./${name}.js`, import.meta.url);
+    if (jsUrl.protocol !== "file:")
+        return jsUrl.href;
+    const jsPath = fileURLToPath(jsUrl);
+    try {
+        if (fs.statSync(jsPath).isFile())
+            return jsUrl.href;
+    }
+    catch {
+        /* Source-mode runs do not have an adjacent .js file. */
+    }
+    const tsPath = fileURLToPath(new URL(`./${name}.ts`, import.meta.url));
+    const compiled = compiledDistPathForSource(tsPath);
+    if (compiled)
+        return pathToFileURL(compiled).href;
+    if (fs.existsSync(tsPath)) {
+        throw new Error(`The local ${name} worker is not built. Run npm --prefix packages/mcp-server run build and retry.`);
+    }
+    return jsUrl.href;
+}
 /** Known clients and where their MCP server map lives. */
 export function knownClients() {
     const appSupport = process.platform === "darwin"
@@ -81,9 +126,15 @@ export function buildServerEntry(opts = {}) {
     // 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] };
+        if (entry && fs.existsSync(entry) && !isEphemeralNpxPath(entry)) {
+            return { command: process.execPath, args: [compiledDistPathForSource(entry) ?? entry] };
         }
+        // We're running from an EPHEMERAL npx cache (`npx @echomem/mcp …` with no global install). npx GCs
+        // those `_npx/<hash>` dirs, so pinning a client to this path works until the next cleanup, then the
+        // MCP server silently vanishes. Never write it — prefer a durable global install of the same package.
+        const globalEntry = resolveGlobalEntry();
+        if (globalEntry)
+            return { command: process.execPath, args: [globalEntry] };
     }
     catch {
         /* couldn't resolve a local install — fall through to npx */
@@ -91,6 +142,33 @@ export function buildServerEntry(opts = {}) {
     // Fallback (unresolved local install): at least drop `-y` so npx doesn't auto-INSTALL on every start.
     return { command: "npx", args: ["@echomem/mcp"] };
 }
+/** True when a resolved entry lives inside npx's throwaway cache (`…/_npx/<hash>/…`). */
+function isEphemeralNpxPath(entry) {
+    return entry.split(path.sep).includes("_npx");
+}
+/**
+ * Locate a DURABLE global install of the bridge (the one `npm i -g @echomem/mcp` creates). Global
+ * modules sit next to the running node — `<node>/../lib/node_modules` (nvm/unix) or `<node>/node_modules`
+ * (Windows). Returns the realpath'd dist entry, or null when the package isn't globally installed.
+ */
+function resolveGlobalEntry() {
+    const nodeDir = path.dirname(process.execPath);
+    const pkgParts = MCP_PACKAGE_NAME.split("/"); // ["@echomem", "mcp"]
+    const candidates = [
+        path.join(nodeDir, "..", "lib", "node_modules", ...pkgParts, "dist", "index.js"),
+        path.join(nodeDir, "node_modules", ...pkgParts, "dist", "index.js"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(candidate))
+                return fs.realpathSync(candidate);
+        }
+        catch {
+            /* keep trying */
+        }
+    }
+    return null;
+}
 /** The TOML block EchoMem adds to ~/.codex/config.toml. No secret — the bridge reads the keystore. */
 export function codexTomlBlock(entry) {
     const command = JSON.stringify(String(entry.command));
@@ -129,6 +207,51 @@ export function writeCodexConfig(configPath, entry) {
     fs.appendFileSync(configPath, sep + block + "\n");
     return "wrote";
 }
+/**
+ * Write the EchoMem guidance block into the agent's GLOBAL memory file (~/.codex/AGENTS.md,
+ * ~/.claude/CLAUDE.md) so the agent treats EchoMem as its core memory tool without the tool
+ * descriptions having to over-explain "when to call me". Marker-fenced + idempotent: only our
+ * block is ever replaced; the user's own content is never touched. Project-level files are
+ * deliberately NOT written — those belong to the user.
+ */
+const AGENTS_MD_BEGIN = "<!-- echomem:begin -->";
+const AGENTS_MD_END = "<!-- echomem:end -->";
+function echomemGuidanceBlock() {
+    return [
+        AGENTS_MD_BEGIN,
+        "## Memory (EchoMem)",
+        "EchoMem is your long-term memory across all coding sessions and tools.",
+        "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
+        "- When meaningful work wraps up (a decision, a fix, a milestone) or the user asks to remember something: call `save_conversation`.",
+        "- If the user pastes a session carryover/checkpoint: it may reference `get_checkpoint_by_context` — use it to pull the checkpoint/decision trail when you need more than the snapshot.",
+        "- If the user asks to show, reopen, restart, or bring back the EchoMem HUD (the context-health overlay), run the shell command `echomem-hud app --client auto`.",
+        "- If the user wants the HUD to come back after a computer restart, run the shell command `echomem-hud autostart on --client auto`.",
+        AGENTS_MD_END,
+    ].join("\n");
+}
+export function writeAgentsMemoryGuidance(filePath) {
+    let content = "";
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        /* fresh file */
+    }
+    const block = echomemGuidanceBlock();
+    const start = content.indexOf(AGENTS_MD_BEGIN);
+    const end = content.indexOf(AGENTS_MD_END);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (start >= 0 && end > start) {
+        const current = content.slice(start, end + AGENTS_MD_END.length);
+        if (current === block)
+            return "exists";
+        fs.writeFileSync(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
+        return "updated";
+    }
+    const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
+    fs.appendFileSync(filePath, sep + block + "\n");
+    return "wrote";
+}
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
 export function writeJsonClientConfig(configPath, entry) {
     let config = {};
@@ -275,8 +398,8 @@ export function resolveServerEntryVersion(entry) {
     }
     const candidates = [...args, command].filter((value) => typeof value === "string");
     for (const candidate of candidates) {
-        if (!candidate.includes(MCP_PACKAGE_NAME) && !candidate.includes(`${path.sep}echomem-mcp`))
-            continue;
+        // Direct local/dev entries often look like ".../packages/mcp-server/dist/index.js";
+        // they do not contain the published package name, but walking upward still finds package.json.
         const resolved = packageVersionFromPath(candidate);
         if (resolved)
             return resolved;
@@ -408,11 +531,111 @@ function openBrowser(url) {
         /* headless — caller prints the URL */
     }
 }
+function openClaudeDesktop() {
+    if (process.platform !== "darwin") {
+        return { ok: false, message: "Could not auto-open Claude on this system. The prompt is copied - open Claude Desktop and paste it." };
+    }
+    const installedPath = firstExisting([
+        "/Applications/Claude.app",
+        path.join(os.homedir(), "Applications", "Claude.app"),
+    ]);
+    const attempts = [
+        ["-b", "com.anthropic.claudefordesktop"],
+        ["-a", "Claude"],
+        ...(installedPath ? [[installedPath]] : []),
+    ];
+    const failures = [];
+    for (const args of attempts) {
+        try {
+            execFileSync("open", args, { stdio: "pipe" });
+            return { ok: true, message: "Opened Claude Desktop. The prompt is copied - paste it into Claude." };
+        }
+        catch (error) {
+            failures.push(`${args.join(" ")}: ${commandFailureMessage(error)}`);
+        }
+    }
+    return {
+        ok: false,
+        message: installedPath
+            ? "Could not auto-open Claude Desktop. The prompt is copied - open Claude Desktop and paste it."
+            : "Claude Desktop was not found by macOS. The prompt is copied - open Claude manually and paste it.",
+        detail: failures.join(" | "),
+    };
+}
+const LOCAL_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// `claude --resume <id>` only finds sessions that belong to the current project directory, so
+// recover the session's original cwd from its transcript before resuming.
+function claudeSessionCwd(sessionId) {
+    try {
+        const projectsDir = path.join(os.homedir(), ".claude", "projects");
+        for (const dir of fs.readdirSync(projectsDir)) {
+            const file = path.join(projectsDir, dir, `${sessionId}.jsonl`);
+            if (!fs.existsSync(file))
+                continue;
+            const fd = fs.openSync(file, "r");
+            try {
+                const head = Buffer.alloc(65536);
+                const read = fs.readSync(fd, head, 0, head.length, 0);
+                const match = head.toString("utf8", 0, read).match(/"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+                return match ? JSON.parse(`"${match[1]}"`) : null;
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+    }
+    catch {
+        /* fall through to a plain resume */
+    }
+    return null;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function openExistingAgentSession(source, sessionId) {
+    if (process.platform !== "darwin")
+        return { ok: false, message: "Opening local agent sessions is currently available on macOS." };
+    if (!LOCAL_SESSION_ID_RE.test(sessionId))
+        return { ok: false, message: "The local session identifier is invalid." };
+    try {
+        if (source === "codex") {
+            execFileSync("open", [`codex://threads/${sessionId}`], { stdio: "pipe" });
+            return { ok: true, message: "Opened the original session in Codex." };
+        }
+        if (source === "claude-code") {
+            const claude = firstExisting(["/opt/homebrew/bin/claude", "/usr/local/bin/claude"]) || "claude";
+            const cwd = claudeSessionCwd(sessionId);
+            const resume = `${claude} --resume ${sessionId}`;
+            const command = cwd && fs.existsSync(cwd) ? `cd ${shellQuote(cwd)} && ${resume}` : resume;
+            execFileSync("osascript", [
+                "-e", "tell application \"Terminal\" to activate",
+                "-e", `tell application \"Terminal\" to do script ${JSON.stringify(command)}`,
+            ], { stdio: "pipe" });
+            return { ok: true, message: "Opened the original Claude Code session in Terminal." };
+        }
+        return { ok: false, message: "Unsupported agent session source." };
+    }
+    catch (error) {
+        return { ok: false, message: "Could not open the original local session.", detail: commandFailureMessage(error) };
+    }
+}
+function commandFailureMessage(error) {
+    const maybe = error;
+    if (Buffer.isBuffer(maybe.stderr)) {
+        const stderr = maybe.stderr.toString("utf8").trim();
+        if (stderr)
+            return stderr;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
 function migratableFromDiscovery(disc) {
     const eta = estimateMigrationEta(disc.pending, disc.skippedActive);
+    const pendingCodex = disc.pendingCodex ?? disc.pending.filter((s) => s.source === "codex").length;
     return {
         pending: disc.pending.length,
         pendingTotal: disc.pendingTotal,
+        pendingCodex,
+        pendingClaudeCode: disc.pendingClaudeCode ?? disc.pending.length - pendingCodex,
         alreadyMigrated: disc.alreadyMigrated,
         skippedActive: disc.skippedActive,
         limited: disc.limited,
@@ -438,6 +661,8 @@ function migratableFromFastSummary(summary) {
     return {
         pending: summary.pending,
         pendingTotal: summary.pendingTotal,
+        pendingCodex: summary.pendingCodex,
+        pendingClaudeCode: summary.pendingClaudeCode,
         alreadyMigrated: summary.alreadyMigrated,
         skippedActive: summary.skippedActive,
         eta: summary.eta,
@@ -557,8 +782,109 @@ function serveRepoCityAsset(reqPath, res) {
     fs.createReadStream(filePath).pipe(res);
     return true;
 }
+function hudAssetsRoot() {
+    return fileURLToPath(new URL("../assets/hud/", import.meta.url));
+}
+function serveHudAsset(reqPath, res) {
+    const root = hudAssetsRoot();
+    const rel = decodeURIComponent(reqPath.slice("/hud-assets/".length));
+    const filePath = path.resolve(root, rel);
+    const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+    if (!filePath.startsWith(rootWithSep)) {
+        res.writeHead(403).end("forbidden");
+        return true;
+    }
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    res.writeHead(200, {
+        "Content-Type": CITY_ASSET_TYPES[path.extname(filePath)] || "application/octet-stream",
+        "Cache-Control": "no-store",
+    });
+    fs.createReadStream(filePath).pipe(res);
+    return true;
+}
+function firstExisting(paths) {
+    for (const candidate of paths) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function appResourcesPath(appName) {
+    const app = firstExisting([
+        `/Applications/${appName}.app`,
+        path.join(os.homedir(), "Applications", `${appName}.app`),
+    ]);
+    return app ? path.join(app, "Contents", "Resources") : null;
+}
+function agentIconSource(id) {
+    const resources = appResourcesPath(id === "codex" ? "Codex" : "Claude");
+    if (!resources)
+        return null;
+    if (id === "codex") {
+        return firstExisting([
+            path.join(resources, "icon.png"),
+            path.join(resources, "icon-codex-dark-color.png"),
+            path.join(resources, "icon-codex-light.png"),
+            path.join(resources, "icon.icns"),
+            path.join(resources, "app.icns"),
+            path.join(resources, "electron.icns"),
+        ]);
+    }
+    return firstExisting([
+        path.join(resources, "icon.png"),
+        path.join(resources, "app.png"),
+        path.join(resources, "icon.icns"),
+        path.join(resources, "electron.icns"),
+    ]);
+}
+function convertedAgentIconPath(id, sourcePath) {
+    if (path.extname(sourcePath).toLowerCase() === ".png")
+        return sourcePath;
+    if (process.platform !== "darwin" || path.extname(sourcePath).toLowerCase() !== ".icns")
+        return null;
+    const stat = fs.statSync(sourcePath);
+    const cacheDir = path.join(os.homedir(), ".echomem", "cache", "agent-icons");
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const out = path.join(cacheDir, `${id}-${Math.round(stat.mtimeMs)}-${stat.size}.png`);
+    if (fs.existsSync(out))
+        return out;
+    try {
+        execFileSync("sips", ["-s", "format", "png", sourcePath, "--out", out], { stdio: "ignore" });
+        return fs.existsSync(out) ? out : null;
+    }
+    catch {
+        try {
+            fs.rmSync(out, { force: true });
+        }
+        catch { }
+        return null;
+    }
+}
+function serveAgentIcon(reqPath, res) {
+    const raw = decodeURIComponent(reqPath.slice("/agent-icons/".length)).replace(/\.png$/i, "");
+    const id = raw === "codex" || raw === "claude-desktop" ? raw : null;
+    if (!id) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    const source = agentIconSource(id);
+    const filePath = source ? convertedAgentIconPath(id, source) : null;
+    if (!filePath) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    res.writeHead(200, {
+        "Content-Type": "image/png",
+        "Cache-Control": "no-store",
+    });
+    fs.createReadStream(filePath).pipe(res);
+    return true;
+}
 function discoverMigratableSessionsOffThread() {
-    const migrateUrl = new URL("./migrate.js", import.meta.url).href;
+    const migrateUrl = runtimeModuleUrl("migrate");
     const code = `
     import { parentPort } from "node:worker_threads";
     import { discoverMigratableSessions } from ${JSON.stringify(migrateUrl)};
@@ -604,15 +930,29 @@ function discoverMigratableSessionsOffThread() {
         });
     });
 }
+function forensicStageLabel(stage) {
+    if (stage === "reading-transcripts")
+        return "Reading transcript files";
+    if (stage === "building-summary")
+        return "Building scan summary";
+    if (stage === "classifying-repeated-context")
+        return "Classifying repeated context";
+    if (stage === "finalizing-report")
+        return "Finalizing report";
+    return "Starting local scan";
+}
 /** 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;
+export function buildForensicReportOffThread(onProgress, options = {}) {
+    const forensicsUrl = runtimeModuleUrl("forensics");
     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 } }) });
+      const report = await buildForensicReport({
+        includeLegacyGoldenStandard: false,
+        onProgress: (done, total, stage, detail) => parentPort?.postMessage({ progress: { done, total, stage, detail } }),
+      });
       parentPort?.postMessage({ ok: true, report });
     } catch (error) {
       parentPort?.postMessage({ ok: false, message: error instanceof Error ? error.message : String(error) });
@@ -621,30 +961,50 @@ function buildForensicReportOffThread(onProgress) {
     const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
     return new Promise((resolve, reject) => {
         let settled = false;
+        const requestedTimeoutMs = options.timeoutMs ?? 15 * 60_000;
+        const timeoutMs = Number.isFinite(requestedTimeoutMs) ? Math.max(1, requestedTimeoutMs) : 15 * 60_000;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            void worker.terminate();
+            const error = new Error(`Local forensic report timed out after ${timeoutMs}ms`);
+            error.code = "REPORT_SCAN_TIMEOUT";
+            reject(error);
+        }, timeoutMs);
+        timeout.unref?.();
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            void worker.terminate();
+            if (result.ok)
+                resolve(result.report);
+            else
+                reject(result.error);
+        };
         worker.on("message", (message) => {
+            if (settled)
+                return;
             const msg = message;
             if (msg.progress) {
-                onProgress?.(msg.progress.done, msg.progress.total);
+                onProgress?.(msg.progress);
                 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();
+            if (msg.ok === true && msg.report && typeof msg.report === "object") {
+                finish({ ok: true, report: msg.report });
+                return;
+            }
+            finish({ ok: false, error: new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed") });
         });
         worker.once("error", (error) => {
-            if (settled)
-                return;
-            settled = true;
-            reject(error);
+            finish({ ok: false, error });
         });
         worker.once("exit", (code) => {
             if (settled)
                 return;
-            settled = true;
-            reject(new Error(`Forensic report worker exited (code ${code}) without a result`));
+            finish({ ok: false, error: new Error(`Forensic report worker exited (code ${code}) without a result`) });
         });
     });
 }
@@ -653,6 +1013,49 @@ export function respondMigrate(res, body, status = 200) {
         return;
     res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
 }
+function safeForensicError(error) {
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : "";
+    if (code === "REPORT_SCAN_TIMEOUT") {
+        return {
+            code,
+            message: "The local workspace scan took too long and was stopped. No backup data was substituted. Rerun setup to retry.",
+        };
+    }
+    return {
+        code: "REPORT_BUILD_FAILED",
+        message: "EchoMem could not finish the local workspace scan. No backup data was substituted. Rerun setup to retry.",
+    };
+}
+function publicRunningForensicProgress(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const progress = value;
+    if (progress.status !== "running")
+        return null;
+    const safeCount = (candidate) => (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0
+        ? Math.floor(candidate)
+        : 0);
+    const safeDuration = (candidate) => (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0
+        ? candidate
+        : 0);
+    const total = safeCount(progress.total);
+    const rawStage = typeof progress.stage === "string" ? progress.stage : "starting";
+    const stage = ["starting", "reading-transcripts", "building-summary", "classifying-repeated-context", "finalizing-report"].includes(rawStage)
+        ? rawStage
+        : "starting";
+    return {
+        status: "running",
+        scanned: total > 0 ? Math.min(safeCount(progress.scanned), total) : 0,
+        total,
+        stage,
+        label: forensicStageLabel(stage),
+        elapsedMs: safeDuration(progress.elapsedMs),
+        stageElapsedMs: safeDuration(progress.stageElapsedMs),
+        updatedAt: safeDuration(progress.updatedAt) || Date.now(),
+    };
+}
 /**
  * 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
@@ -662,6 +1065,7 @@ export function startCallbackServer(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 300_000;
     const dashboardTimeoutMs = 4 * 60 * 60 * 1000;
     const expectedNonce = opts.nonce;
+    const scanId = opts.scanId ?? randomUUID();
     return new Promise((resolveOuter, rejectOuter) => {
         const onToken = deferred();
         const decision = deferred();
@@ -677,6 +1081,10 @@ export function startCallbackServer(opts = {}) {
         let timer;
         let closed = false;
         let server;
+        // The browser setup page holds a keep-alive socket (and polls /progress). server.close() only stops
+        // accepting NEW connections and waits for existing ones to end — so without destroying these the
+        // handle never releases and the CLI hangs after migration. Track live sockets and kill them on close.
+        const sockets = new Set();
         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));
@@ -688,6 +1096,9 @@ export function startCallbackServer(opts = {}) {
                 return;
             closed = true;
             server.close();
+            for (const socket of sockets)
+                socket.destroy();
+            sockets.clear();
         };
         const armTimeout = () => {
             if (timer)
@@ -739,17 +1150,69 @@ export function startCallbackServer(opts = {}) {
                     serveRepoCityAsset(route, res);
                     return;
                 }
+                if (route.startsWith("/hud-assets/") && req.method === "GET") {
+                    serveHudAsset(route, res);
+                    return;
+                }
+                if (route.startsWith("/agent-icons/") && req.method === "GET") {
+                    serveAgentIcon(route, res);
+                    return;
+                }
                 if (route === "/setup" && req.method === "GET") {
+                    res.setHeader("Cache-Control", "no-store");
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    const hasPreview = url.searchParams.has("preview");
+                    if (hasPreview && opts.allowPreview !== true) {
+                        return void text(res, 403, "Design preview is disabled. No sample data was shown.");
+                    }
+                    const previewState = hasPreview ? parseSetupPreviewState(url.searchParams.get("preview")) : null;
+                    if (hasPreview && !previewState) {
+                        return void text(res, 400, "Unknown setup preview state.");
+                    }
                     res.writeHead(200, {
                         "Content-Type": "text/html; charset=utf-8",
                         "Cache-Control": "no-store",
-                    }).end(renderSetupPage());
+                    }).end(renderSetupPage(previewState ? { previewState } : undefined));
                     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 });
+                    json(res, 200, { connected, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true, workspacePath: process.cwd() });
+                    return;
+                }
+                if (route === "/launch-agent" && 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");
+                    const agent = asString(body.agent);
+                    if (agent !== "claude-desktop")
+                        return void json(res, 400, { ok: false, message: "Unsupported agent." });
+                    const result = openClaudeDesktop();
+                    json(res, result.ok ? 200 : 501, result);
+                    return;
+                }
+                if (route === "/open-session" && 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");
+                    const result = openExistingAgentSession(asString(body.source) || "", asString(body.sessionId) || "");
+                    json(res, result.ok ? 200 : 400, result);
                     return;
                 }
                 if (route === "/callback" && req.method === "GET") {
@@ -779,15 +1242,99 @@ export function startCallbackServer(opts = {}) {
                 }
                 if (route === "/report" && req.method === "GET") {
                     // Local forensic "Context Doctor" report — computed locally, served BEFORE auth (scan-first).
+                    res.setHeader("Cache-Control", "no-store");
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
-                    const payload = opts.getReport ? opts.getReport() : null;
+                    let payload;
+                    try {
+                        payload = opts.getReport ? opts.getReport() : null;
+                    }
+                    catch {
+                        return void json(res, 500, {
+                            schemaVersion: 1,
+                            kind: "failed",
+                            mode: "production",
+                            scanId,
+                            error: {
+                                code: "REPORT_STATE_UNAVAILABLE",
+                                message: "EchoMem could not read the local scan state. No backup data was substituted. Rerun setup to retry.",
+                            },
+                        });
+                    }
                     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));
+                        let prog;
+                        try {
+                            prog = opts.getReportProgress ? opts.getReportProgress() : {
+                                status: "running",
+                                scanned: 0,
+                                total: 0,
+                                stage: "starting",
+                                label: "Starting local scan",
+                                elapsedMs: 0,
+                                stageElapsedMs: 0,
+                                updatedAt: Date.now(),
+                            };
+                        }
+                        catch {
+                            return void json(res, 500, {
+                                schemaVersion: 1,
+                                kind: "failed",
+                                mode: "production",
+                                scanId,
+                                error: {
+                                    code: "REPORT_STATE_UNAVAILABLE",
+                                    message: "EchoMem could not read the local scan state. No backup data was substituted. Rerun setup to retry.",
+                                },
+                            });
+                        }
+                        if (prog && typeof prog === "object" && prog.status === "failed") {
+                            return void json(res, 500, {
+                                schemaVersion: 1,
+                                kind: "failed",
+                                mode: "production",
+                                scanId,
+                                error: safeForensicError(prog.error),
+                            });
+                        }
+                        const publicProgress = publicRunningForensicProgress(prog);
+                        if (!publicProgress) {
+                            return void json(res, 500, {
+                                schemaVersion: 1,
+                                kind: "failed",
+                                mode: "production",
+                                scanId,
+                                error: {
+                                    code: "REPORT_STATE_INVALID",
+                                    message: "EchoMem received an invalid local scan state. No backup data was substituted. Rerun setup to retry.",
+                                },
+                            });
+                        }
+                        return void json(res, 202, {
+                            schemaVersion: 1,
+                            kind: "scanning",
+                            mode: "production",
+                            scanId,
+                            progress: publicProgress,
+                        });
                     }
-                    json(res, 200, payload);
+                    const validation = validateForensicReportForSetup(payload);
+                    if (!validation.ok) {
+                        return void json(res, 500, {
+                            schemaVersion: 1,
+                            kind: "failed",
+                            mode: "production",
+                            scanId,
+                            error: { code: validation.code, message: validation.message },
+                        });
+                    }
+                    json(res, 200, {
+                        schemaVersion: 1,
+                        kind: validation.kind,
+                        mode: "production",
+                        scanId,
+                        report: validation.report,
+                    });
                     return;
                 }
                 if (route === "/progress" && req.method === "GET") {
@@ -874,9 +1421,13 @@ export function startCallbackServer(opts = {}) {
                     text(res, 500, e instanceof Error ? e.message : String(e));
             });
         });
+        server.on("connection", (socket) => {
+            sockets.add(socket);
+            socket.on("close", () => sockets.delete(socket));
+        });
         armTimeout();
         server.on("error", (e) => rejectOuter(e));
-        server.listen(0, "127.0.0.1", () => {
+        server.listen(opts.port ?? 0, "127.0.0.1", () => {
             const addr = server.address();
             const port = typeof addr === "object" && addr ? addr.port : 0;
             resolveOuter({
@@ -1052,9 +1603,14 @@ async function cmdSetup(flags) {
             }
         }
     }
+    if (!flags["no-agents-md"]) {
+        writeMemoryGuidanceForTargets(targets);
+    }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
-        console.log(`Skipped login; existing EchoMem credentials are unchanged. Current bridge: ${MCP_PACKAGE_LABEL}`);
+        // init drives login itself right after, so the "skipped" note would be misleading there.
+        if (!flags["init-quiet"])
+            console.log(`Skipped login; existing EchoMem credentials are unchanged. Current bridge: ${MCP_PACKAGE_LABEL}`);
     }
     else {
         await cmdLogin(flags);
@@ -1062,6 +1618,63 @@ async function cmdSetup(flags) {
     if (flags["with-hud"])
         await cmdSetupHud(flags);
 }
+/**
+ * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
+ * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), writes the AGENTS.md
+ * memory guidance, logs in via the browser, and launches the context HUD — the whole product in a
+ * single command. `setup`/`update` remain the granular primitives; init just picks the "do everything"
+ * defaults and frames the result.
+ */
+async function cmdInit(flags) {
+    console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
+    // 1. Configure every installed agent + write AGENTS.md. Hold login + HUD so we control ordering.
+    await cmdSetup({ ...flags, all: true, "skip-login": true, "with-hud": false, "init-quiet": true });
+    // 2. Bring the HUD up NOW (non-blocking) so everything is already running while onboarding proceeds.
+    if (!flags["no-hud"])
+        await cmdSetupHud(flags);
+    // 3. Start onboarding — opens the browser dashboard (scan → connect → extraction) and waits there.
+    console.log("");
+    if (!flags["skip-login"] && !flags["no-login"])
+        await cmdLogin(flags);
+    console.log("");
+    console.log("🎉 EchoMem is ready.");
+    console.log("   • MCP memory is configured for every coding agent installed on this machine.");
+    if (!flags["no-hud"]) {
+        console.log('   • The context HUD is running (top-right). Right-click it → "Show after restart" to keep it,');
+        console.log('     or just tell your agent "open the EchoMem HUD" anytime (it runs: echomem-hud app).');
+    }
+    else {
+        console.log('   • Start the context HUD anytime with: echomem-hud app');
+    }
+    console.log('   • Try it now: ask your agent — "search my EchoMem for what I\'ve been working on and recap it."');
+}
+/**
+ * For each configured client, add the EchoMem guidance block to its GLOBAL memory file so the
+ * agent knows to lean on EchoMem for recall/save. Global only (~/.codex/AGENTS.md,
+ * ~/.claude/CLAUDE.md) — project files are the user's. Skip with --no-agents-md.
+ */
+function writeMemoryGuidanceForTargets(targets) {
+    const files = new Map(); // path → label
+    for (const t of targets) {
+        if (t.id === "codex")
+            files.set(home(".codex", "AGENTS.md"), "Codex");
+        if (t.id === "claude-code" || t.id === "claude-desktop")
+            files.set(home(".claude", "CLAUDE.md"), "Claude");
+    }
+    for (const [file, label] of files) {
+        try {
+            const result = writeAgentsMemoryGuidance(file);
+            if (result === "wrote")
+                console.log(`✅ Added EchoMem memory guidance to ${label}'s global memory file: ${file}`);
+            else if (result === "updated")
+                console.log(`✅ Refreshed EchoMem memory guidance in ${file}`);
+            // "exists" → silent; nothing changed.
+        }
+        catch (error) {
+            console.log(`ℹ️  Could not write memory guidance to ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
 async function cmdUpdate(flags) {
     await cmdSetup({ ...flags, "skip-login": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
@@ -1106,9 +1719,21 @@ async function cmdSetupHud(flags) {
 }
 function resolveHudCliPath() {
     const entry = fs.realpathSync(process.argv[1] || "");
+    const compiledEntry = compiledDistPathForSource(entry);
+    if (compiledEntry) {
+        const compiledHud = path.join(path.dirname(compiledEntry), "hud", "cli.js");
+        if (fs.existsSync(compiledHud))
+            return compiledHud;
+    }
     const base = path.dirname(entry);
     const candidate = path.join(base, "hud", "cli.js");
-    return fs.existsSync(candidate) ? candidate : path.join(base, "hud", "cli.ts");
+    if (fs.existsSync(candidate))
+        return candidate;
+    const sourceCandidate = path.join(base, "hud", "cli.ts");
+    if (fs.existsSync(sourceCandidate)) {
+        throw new Error("The local HUD CLI is not built. Run npm --prefix packages/mcp-server run build and retry.");
+    }
+    return candidate;
 }
 function parseHudClient(value) {
     return value === "codex" || value === "claude-code" || value === "claude-desktop" || value === "both" || value === "auto"
@@ -1130,11 +1755,34 @@ async function cmdLogin(flags) {
     // 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 devPortRaw = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
+    if (devPortRaw !== undefined && (!Number.isInteger(devPortRaw) || devPortRaw < 1024 || devPortRaw > 65535)) {
+        throw new Error("--dev-port must be an integer between 1024 and 65535");
+    }
+    const devNonce = typeof flags["dev-nonce"] === "string" ? flags["dev-nonce"].trim() : undefined;
+    if (devNonce && devPortRaw === undefined)
+        throw new Error("--dev-nonce requires --dev-port");
+    if (devNonce && !/^[A-Za-z0-9-]{16,128}$/.test(devNonce)) {
+        throw new Error("--dev-nonce must contain 16-128 letters, numbers, or hyphens");
+    }
+    const nonce = devNonce || randomUUID();
     let stats = null;
     let forensicReport = null;
-    let forensicProgress = { scanned: 0, total: 0 };
+    const forensicStartedAt = Date.now();
+    let forensicStageStartedAt = forensicStartedAt;
+    let forensicStage = "starting";
+    let forensicProgress = {
+        status: "running",
+        scanned: 0,
+        total: 0,
+        stage: forensicStage,
+        label: forensicStageLabel(forensicStage),
+        elapsedMs: 0,
+        stageElapsedMs: 0,
+        updatedAt: forensicStartedAt,
+    };
     const srv = await startCallbackServer({
+        port: devPortRaw,
         nonce,
         getStats: () => stats,
         getReport: () => forensicReport,
@@ -1153,13 +1801,42 @@ async function cmdLogin(flags) {
     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 };
+    buildForensicReportOffThread((progress) => {
+        const now = Date.now();
+        const nextStage = progress.stage || forensicStage;
+        if (nextStage !== forensicStage) {
+            forensicStage = nextStage;
+            forensicStageStartedAt = now;
+            console.log(`Local scan: ${forensicStageLabel(forensicStage)}…`);
+        }
+        forensicProgress = {
+            status: "running",
+            scanned: progress.done,
+            total: progress.total,
+            stage: forensicStage,
+            label: forensicStageLabel(forensicStage),
+            detail: progress.detail,
+            elapsedMs: now - forensicStartedAt,
+            stageElapsedMs: now - forensicStageStartedAt,
+            updatedAt: now,
+        };
     })
         .then((r) => {
         forensicReport = r;
     })
         .catch((e) => {
+        const now = Date.now();
+        forensicProgress = {
+            status: "failed",
+            scanned: forensicProgress.scanned,
+            total: forensicProgress.total,
+            stage: "failed",
+            label: "Local scan failed",
+            elapsedMs: now - forensicStartedAt,
+            stageElapsedMs: now - forensicStageStartedAt,
+            updatedAt: now,
+            error: safeForensicError(e),
+        };
         console.error(`Could not build the local report: ${e instanceof Error ? e.message : String(e)}`);
     });
     let token;
@@ -1544,49 +2221,79 @@ async function cmdLogin(flags) {
                 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) => {
-                    let latestRepo;
-                    if (ev.error) {
-                        progressFailed += 1;
-                    }
-                    else {
-                        progressDone += 1;
-                        progressExtracted += ev.memories ?? 0;
-                        latestRepo = repoLabel(ev.session.cwd); // building this completed conversation belongs to
-                    }
-                    updateProgress({
-                        latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
-                        ...(latestRepo ? { latestRepo } : {}),
-                    });
-                },
-            }), 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 } : {}) });
+            // Plan caps limit how many conversations one import session accepts (IMPORT_LIMIT_EXCEEDED →
+            // startMigration slices to the cap). Instead of making the user re-run setup per batch (3000
+            // sessions used to mean 3 clicks), loop batches automatically until everything pending is done.
+            const onBatchProgress = (ev) => {
+                let latestRepo;
+                if (ev.error) {
+                    progressFailed += 1;
+                }
+                else {
+                    progressDone += 1;
+                    progressExtracted += ev.memories ?? 0;
+                    latestRepo = repoLabel(ev.session.cwd); // building this completed conversation belongs to
+                }
+                updateProgress({
+                    latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
+                    ...(latestRepo ? { latestRepo } : {}),
+                });
+            };
+            let remaining = exact.pending;
+            let stoppedReason;
+            let planLimitNote;
+            let batchIndex = 0;
             console.log("Migrating your history… keep this terminal open until it completes.");
-            console.log(`Migration metrics: ${h.metricsFile}`);
-            const r = await h.done;
+            for (;;) {
+                batchIndex += 1;
+                let h;
+                try {
+                    const controller = new AbortController();
+                    h = await withTimeout(startMigration({ pending: remaining, signal: controller.signal, onProgress: onBatchProgress }), 30_000, "IMPORT_START_TIMEOUT", () => controller.abort());
+                }
+                catch (batchError) {
+                    if (batchIndex === 1)
+                        throw batchError; // first batch failing = the whole import failed
+                    // A later batch could not start (e.g. plan headroom exhausted). Finish gracefully with a note.
+                    planLimitNote = `Imported ${progressDone} so far — the rest hit your plan's import limit. Re-run extraction later for the remaining ${remaining.length}.`;
+                    break;
+                }
+                activeSessionId = h.sessionId;
+                if (batchIndex === 1) {
+                    updateProgress({ status: "running", sessionId: h.sessionId, jobCount: activeJobCount, total: activeJobCount, latest: "Import session created." });
+                    sendMigrate({ sessionId: h.sessionId, jobCount: activeJobCount });
+                }
+                else {
+                    updateProgress({ latest: `Continuing automatically — batch ${batchIndex} (${remaining.length} left).` });
+                }
+                console.log(`Migration metrics (batch ${batchIndex}): ${h.metricsFile}`);
+                const r = await h.done;
+                if (r.stoppedReason) {
+                    stoppedReason = r.stoppedReason;
+                    break;
+                }
+                // startMigration sliced to the cap ⇒ more remain: continue with the next batch automatically.
+                if (h.capped && remaining.length > h.jobCount) {
+                    remaining = remaining.slice(h.jobCount);
+                    continue;
+                }
+                break;
+            }
             srv.setProgress({
-                status: r.failed || r.stoppedReason ? "failed" : "completed",
-                sessionId: h.sessionId,
-                jobCount: h.jobCount,
-                capped: h.capped,
-                total: h.jobCount,
-                completed: r.migrated,
+                status: stoppedReason ? "failed" : "completed",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
                 running: 0,
                 queued: 0,
-                failed: r.failed,
-                extracted: r.extracted,
-                latest: r.stoppedReason ? `Stopped: ${r.stoppedReason}` : "Import complete.",
-                ...(r.stoppedReason ? { error: r.stoppedReason } : {}),
+                failed: progressFailed,
+                extracted: progressExtracted,
+                latest: stoppedReason ? `Stopped: ${stoppedReason}` : planLimitNote || "Import complete.",
+                ...(stoppedReason ? { error: stoppedReason } : {}),
             });
-            console.log(`Import finished: ${r.migrated} imported, ${r.extracted} memories, ${r.failed} failed.`);
-            if (r.stoppedReason || r.failed)
+            console.log(`Import finished: ${progressDone} imported, ${progressExtracted} memories, ${progressFailed} failed.`);
+            if (stoppedReason || progressFailed)
                 process.exitCode = 1;
             await new Promise((resolve) => setTimeout(resolve, 2000));
             srv.close();
@@ -1713,6 +2420,7 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
+  echomem-mcp init                  One command: configure every installed agent + HUD + log in
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then log in
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
@@ -1749,6 +2457,9 @@ export async function runCli(argv) {
     const cmd = argv[0];
     const flags = parseFlags(argv.slice(1));
     switch (cmd) {
+        case "init":
+            await cmdInit(flags);
+            return true;
         case "setup":
             await cmdSetup(flags);
             return true;