@echomem/mcp 1.4.8 → 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));
@@ -484,6 +562,63 @@ function openClaudeDesktop() {
         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)) {
@@ -749,7 +884,7 @@ function serveAgentIcon(reqPath, 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)};
@@ -795,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) });
@@ -812,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`) });
         });
     });
 }
@@ -844,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
@@ -853,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();
@@ -868,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));
@@ -879,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)
@@ -939,10 +1159,21 @@ export function startCallbackServer(opts = {}) {
                     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") {
@@ -969,6 +1200,21 @@ export function startCallbackServer(opts = {}) {
                     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") {
                     handleCallback(res, url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
                     return;
@@ -996,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") {
@@ -1091,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({
@@ -1306,7 +1640,7 @@ async function cmdInit(flags) {
     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 → "Open at login" to keep it,');
+        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 {
@@ -1385,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"
@@ -1409,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,
@@ -1432,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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.8",
-  "description": "EchoMem Cloud-First MCP Server",
+  "version": "1.4.9",
+  "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -18,10 +18,11 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
+    "predev": "npm run build",
+    "dev": "node dist/index.js",
     "smoke": "node smoke.mjs",
     "preview:extraction": "npm run build && node scripts/preview-extraction.mjs",
-    "test": "npm run build && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/tools.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
+    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {