@echomem/mcp 1.4.21 → 1.4.23

package/dist/setup.js

@@ -1,16 +1,17 @@
 /**
- * `echomem-mcp init | setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
+ * `echomem-mcp init | setup | login | unlock | status | logout` — local bridge lifecycle (spec §8).
  *
  * Design goals from the spec:
- *   - One command → one local browser setup → one reload.
+ *   - `login` establishes the account and trusted device only; it never reads local history.
+ *   - `init` runs one ordered flow: local-history permission/report, login, plan if needed, then extraction.
  *   - Both secrets (API token + encryption key) ride a single browser flow and land in the local
  *     keystore — never in the client's MCP config, never in the agent's chat context.
  *   - Re-unlock after the key's TTL is one step, not a re-setup.
  *
- * The browser flow stays on a localhost setup page. That local page collects email OTP consent and
- * an encryption passphrase, while this process asks the hosted API to send/verify OTP and mint a
- * device token. Secrets land in the local keystore — never in the client's MCP config, never in
- * the agent's chat context.
+ * Both browser flows stay on a localhost page. Login collects email OTP consent and an encryption
+ * passphrase; onboarding separately asks to access local coding history. This process asks the
+ * hosted API to send/verify OTP and mint a device token. Secrets land in the local keystore —
+ * never in the client's MCP config or the agent's chat context.
  */
 import http from "node:http";
 import { randomUUID } from "node:crypto";
@@ -37,6 +38,28 @@ import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "
 // localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const PRICING_URL = (process.env.ECHO_PRICING_URL || "https://echoknows.com/pricing").replace(/\/$/, "");
+function hostedBillingEndpoint(pathname) {
+    const url = new URL(PRICING_URL);
+    url.pathname = pathname;
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+function isExpectedStripeUrl(value, kind) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:")
+            return false;
+        return kind === "checkout"
+            ? url.hostname === "checkout.stripe.com"
+            : url.hostname === "billing.stripe.com";
+    }
+    catch {
+        return false;
+    }
+}
 const CODEX_SKILL_NAMES = [
     "echomem-search",
     "echomem-save",
@@ -266,6 +289,52 @@ function resolveGlobalEntry() {
     }
     return null;
 }
+export function needsDurableGlobalUpdate(runningEntry, durableEntry, targetVersion = MCP_PACKAGE_VERSION) {
+    if (!isEphemeralNpxPath(runningEntry))
+        return false;
+    const installedVersion = durableEntry
+        ? packageVersionFromPath(durableEntry)?.version
+        : undefined;
+    return installedVersion !== targetVersion;
+}
+function installDurableGlobalUpdate() {
+    const runningEntry = (() => {
+        try {
+            return fs.realpathSync(process.argv[1] || "");
+        }
+        catch {
+            return process.argv[1] || "";
+        }
+    })();
+    const currentGlobalEntry = resolveGlobalEntry();
+    if (!needsDurableGlobalUpdate(runningEntry, currentGlobalEntry))
+        return;
+    const packageSpec = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
+    console.log(`Installing durable ${packageSpec} before updating client configs…`);
+    const npmExecPath = process.env.npm_execpath;
+    try {
+        if (npmExecPath && fs.existsSync(npmExecPath)) {
+            execFileSync(process.execPath, [npmExecPath, "install", "-g", packageSpec], {
+                stdio: "inherit",
+            });
+        }
+        else {
+            execFileSync(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "-g", packageSpec], {
+                stdio: "inherit",
+            });
+        }
+    }
+    catch (error) {
+        throw new Error(`Could not install ${packageSpec} globally: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const installedEntry = resolveGlobalEntry();
+    const installedVersion = installedEntry
+        ? packageVersionFromPath(installedEntry)?.version
+        : undefined;
+    if (installedVersion !== MCP_PACKAGE_VERSION) {
+        throw new Error(`Global EchoMem bridge is ${installedVersion || "missing"} after update; expected ${MCP_PACKAGE_VERSION}.`);
+    }
+}
 /** 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));
@@ -322,6 +391,15 @@ function echomemGuidanceBlock() {
         "- 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.",
+        "",
+        "### Company group memory",
+        "- Use `get_group_context` when the user asks who is in their company group, what teammates are responsible for, or what work is already covered. Treat declared participant fields as facts and published-memory conclusions as evidence or inference.",
+        "- A group publication is separate from a globally public memory: publishing to a group creates a group-scoped snapshot and must not change the encrypted original or its global `is_public` setting.",
+        "- If a user asks to create a group, call `create_memory_group`; if they ask for a code to share, call `create_group_invite` and return the secret invite code only to that user. Never save the invite code to memory or include it in logs, analytics, summaries, or unrelated output.",
+        "- If a user supplies an `echo_grp_...` code and explicitly asks to join, call `join_memory_group`. Joining never authorizes publishing by itself and must not move a user out of another group.",
+        "- For requests such as “prepare my recent work memories,” “upload work from this ticket,” or “publish work since my last sync,” call `prepare_group_publication` first. This is a no-write preview. For encrypted accounts, tell the user to run `echomem-mcp unlock` locally if the tool reports that the key is required.",
+        "- After preparing, select only exact candidate memory IDs that match the user's stated scope, exclude already-published or exact-content duplicates, summarize what would be shared, and ask the user to confirm. Do not call `complete_group_publication` until the user explicitly confirms that preview.",
+        "- On confirmation, call `complete_group_publication` with the exact `scanId`, selected memory IDs, and `confirmed: true`. An explicit request to join and upload still requires the publication preview and confirmation after joining.",
         "- 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,
@@ -1201,6 +1279,11 @@ export function startCallbackServer(opts = {}) {
     const dashboardTimeoutMs = 4 * 60 * 60 * 1000;
     const expectedNonce = opts.nonce;
     const scanId = opts.scanId ?? randomUUID();
+    const flow = opts.flow ?? "onboarding";
+    const isLoginFlow = flow === "login";
+    // A login screen must not be blocked by a local-history permission. That permission belongs to
+    // onboarding and is intentionally enforced separately below.
+    const requiresReportConsent = opts.requireReportConsent === true && !isLoginFlow;
     return new Promise((resolveOuter, rejectOuter) => {
         const onToken = deferred();
         const decision = deferred();
@@ -1208,9 +1291,10 @@ export function startCallbackServer(opts = {}) {
         let stats = null;
         let authUrl = "";
         let switchAccountUrl = "";
-        let connected = false;
+        let connected = Boolean(opts.initialToken?.token);
+        let activeDeviceToken = opts.initialToken?.token || "";
         let pendingLocalAuth = null;
-        let reportConsentGranted = opts.requireReportConsent !== true;
+        let reportConsentGranted = !requiresReportConsent;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
         let migrateStarted = false;
         let tokenRefreshHandler = null;
@@ -1277,7 +1361,7 @@ export function startCallbackServer(opts = {}) {
         const handleCallback = (res, token, key, nonce) => {
             if (!checkNonce(nonce))
                 return void text(res, 403, "bad nonce");
-            if (opts.requireReportConsent === true && !reportConsentGranted) {
+            if (requiresReportConsent && !reportConsentGranted) {
                 return void json(res, 403, {
                     error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                     message: "Allow local history access in the setup page before connecting EchoMem.",
@@ -1288,6 +1372,7 @@ export function startCallbackServer(opts = {}) {
             console.log(`[${new Date().toISOString()}] Device token callback received.`);
             const firstToken = !onToken.settled();
             connected = true;
+            activeDeviceToken = token;
             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 };
@@ -1306,7 +1391,7 @@ export function startCallbackServer(opts = {}) {
                 text(res, 403, "bad nonce");
                 return true;
             }
-            if (opts.requireReportConsent === true && !reportConsentGranted) {
+            if (requiresReportConsent && !reportConsentGranted) {
                 json(res, 403, {
                     error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                     message: "Allow local history access in the setup page before connecting EchoMem.",
@@ -1318,6 +1403,7 @@ export function startCallbackServer(opts = {}) {
         const resolveLocalToken = (token, key) => {
             const firstToken = !onToken.settled();
             connected = true;
+            activeDeviceToken = token;
             pendingLocalAuth = null;
             const callbackToken = { token, key };
             if (firstToken) {
@@ -1330,6 +1416,17 @@ export function startCallbackServer(opts = {}) {
             }
             armTimeout();
         };
+        const isOnboardingOnlyRoute = (route) => [
+            "/report-consent",
+            "/report",
+            "/stats",
+            "/billing-status",
+            "/billing-checkout",
+            "/billing-portal",
+            "/progress",
+            "/migrate",
+            "/skip",
+        ].includes(route);
         const handleLocalSendOtp = async (res, body) => {
             if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
                 return;
@@ -1472,6 +1569,15 @@ export function startCallbackServer(opts = {}) {
             const url = new URL(req.url || "/", "http://127.0.0.1");
             const route = url.pathname;
             const run = async () => {
+                // Defense in depth: the login bridge never exposes the routes that can inspect or move
+                // local conversation history. The browser UI also routes around them, but the server is
+                // the authority for this privacy boundary.
+                if (isLoginFlow && isOnboardingOnlyRoute(route)) {
+                    return void json(res, 404, {
+                        error: "ONBOARDING_REQUIRED",
+                        message: "Run `echomem-mcp init` to access local-history onboarding.",
+                    });
+                }
                 if ((route === "/city" || route.startsWith("/city/")) && req.method === "GET") {
                     serveRepoCityAsset(route, res);
                     return;
@@ -1507,12 +1613,13 @@ export function startCallbackServer(opts = {}) {
                         return void text(res, 403, "bad nonce");
                     json(res, 200, {
                         connected,
+                        flow,
                         authUrl,
                         switchAccountUrl: switchAccountUrl || authUrl,
                         localOnly: true,
                         localAuth: true,
                         workspacePath: process.cwd(),
-                        consentRequired: opts.requireReportConsent === true,
+                        consentRequired: requiresReportConsent,
                         consentGranted: reportConsentGranted,
                     });
                     return;
@@ -1605,7 +1712,7 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/stats" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
-                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                    if (requiresReportConsent && !reportConsentGranted) {
                         return void json(res, 403, {
                             error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                             message: "Allow local history access before continuing setup.",
@@ -1618,15 +1725,16 @@ export function startCallbackServer(opts = {}) {
                     return;
                 }
                 if (route === "/billing-status" && req.method === "GET") {
+                    res.setHeader("Cache-Control", "no-store, max-age=0");
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
-                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                    if (requiresReportConsent && !reportConsentGranted) {
                         return void json(res, 403, {
                             error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                             message: "Allow local history access before continuing setup.",
                         });
                     }
-                    const token = new KeyStore().getToken();
+                    const token = activeDeviceToken || new KeyStore().getToken();
                     const pricingUrl = `${PRICING_URL}?source=mcp_onboarding`;
                     if (!token) {
                         json(res, 200, { plan: "free", paid: false, trialAvailable: true, trialUsed: false, pricingUrl });
@@ -1662,12 +1770,84 @@ export function startCallbackServer(opts = {}) {
                     }
                     return;
                 }
+                if ((route === "/billing-checkout" || route === "/billing-portal") && 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 (requiresReportConsent && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before managing an onboarding plan.",
+                        });
+                    }
+                    const token = activeDeviceToken || new KeyStore().getToken();
+                    if (!connected || !token) {
+                        return void json(res, 401, {
+                            error: "ECHOMEM_LOGIN_REQUIRED",
+                            message: "Connect your EchoMem account before continuing to billing.",
+                        });
+                    }
+                    const isCheckout = route === "/billing-checkout";
+                    const requestBody = { source: "mcp_onboarding" };
+                    if (isCheckout) {
+                        const plan = asString(body.plan)?.toLowerCase();
+                        if (plan !== "pro" && plan !== "power") {
+                            return void json(res, 400, {
+                                error: "INVALID_PLAN",
+                                message: "Choose Pro or Power to continue to checkout.",
+                            });
+                        }
+                        requestBody.plan = plan;
+                        requestBody.trial = body.trial === true;
+                    }
+                    else {
+                        const plan = asString(body.plan)?.toLowerCase();
+                        if (plan) {
+                            if (plan !== "pro" && plan !== "power") {
+                                return void json(res, 400, {
+                                    error: "INVALID_PLAN",
+                                    message: "Choose Pro or Power to change plans.",
+                                });
+                            }
+                            requestBody.plan = plan;
+                        }
+                    }
+                    try {
+                        const response = await axios.post(hostedBillingEndpoint(isCheckout ? "/api/billing/checkout" : "/api/billing/portal"), requestBody, {
+                            timeout: 15_000,
+                            headers: {
+                                "Content-Type": "application/json",
+                                Authorization: `Bearer ${token}`,
+                            },
+                        });
+                        const hostedUrl = response.data?.url;
+                        if (!isExpectedStripeUrl(hostedUrl, isCheckout ? "checkout" : "portal")) {
+                            return void json(res, 502, {
+                                error: "INVALID_BILLING_DESTINATION",
+                                message: "Echo billing returned an unexpected destination.",
+                            });
+                        }
+                        json(res, 200, { url: hostedUrl });
+                    }
+                    catch (error) {
+                        const detail = publicAxiosError(error, isCheckout ? "Could not start secure checkout." : "Could not open secure plan management.");
+                        json(res, detail.status, { error: "BILLING_REQUEST_FAILED", message: detail.message });
+                    }
+                    return;
+                }
                 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");
-                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                    if (requiresReportConsent && !reportConsentGranted) {
                         return void json(res, 403, {
                             error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                             message: "Allow local history access before starting the local scan.",
@@ -1768,7 +1948,7 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/progress" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
-                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                    if (requiresReportConsent && !reportConsentGranted) {
                         return void json(res, 403, {
                             error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                             message: "Allow local history access before continuing setup.",
@@ -1816,6 +1996,7 @@ export function startCallbackServer(opts = {}) {
                         /* already logged out locally */
                     }
                     connected = false;
+                    activeDeviceToken = "";
                     const revokedPendingCredential = await revokePendingLocalAuth();
                     stats = null;
                     migrateStarted = false;
@@ -1845,7 +2026,7 @@ export function startCallbackServer(opts = {}) {
                     }
                     if (!checkNonce(asString(body.nonce)))
                         return void text(res, 403, "bad nonce");
-                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                    if (requiresReportConsent && !reportConsentGranted) {
                         return void json(res, 403, {
                             error: "LOCAL_HISTORY_CONSENT_REQUIRED",
                             message: "Allow local history access before starting extraction.",
@@ -1906,6 +2087,8 @@ export function startCallbackServer(opts = {}) {
             sockets.add(socket);
             socket.on("close", () => sockets.delete(socket));
         });
+        if (opts.initialToken)
+            onToken.resolve(opts.initialToken);
         armTimeout();
         server.on("error", (e) => rejectOuter(e));
         server.listen(opts.port ?? 0, "127.0.0.1", () => {
@@ -2140,9 +2323,9 @@ async function cmdSetup(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), installs EchoMem's
- * Codex skills, 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.
+ * Codex skills, writes the AGENTS.md memory guidance, and launches the context HUD. One browser
+ * bridge then runs permission → report → login → plan if needed → extraction in that order.
+ * `setup`/`login`/`update` remain granular primitives; init picks the full product defaults.
  */
 async function cmdInit(flags) {
     console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
@@ -2151,10 +2334,10 @@ async function cmdInit(flags) {
     // 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.
+    // 3. Start one ordered onboarding bridge. A fresh device logs in only after consent + report.
     console.log("");
-    if (!flags["skip-login"] && !flags["no-login"] && !await cmdLogin(flags)) {
-        console.log("\nEchoMem is configured, but this device was not connected. Restart EchoMem and use the new page it opens.");
+    if (!flags["skip-login"] && !flags["no-login"] && !await cmdOnboarding(flags)) {
+        console.log("\nEchoMem is configured, but onboarding did not finish. Run `echomem-mcp init` again when you are ready.");
         return;
     }
     console.log("");
@@ -2215,6 +2398,8 @@ function writeCodexSkillsForTargets(targets) {
     }
 }
 async function cmdUpdate(flags) {
+    if (!flags.dev)
+        installDurableGlobalUpdate();
     await cmdSetup({ ...flags, "skip-login": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
 }
@@ -2279,6 +2464,19 @@ function parseHudClient(value) {
         ? value
         : "auto";
 }
+function localBridgeOptions(flags) {
+    const port = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
+    if (port !== undefined && (!Number.isInteger(port) || port < 1024 || port > 65535)) {
+        throw new Error("--dev-port must be an integer between 1024 and 65535");
+    }
+    const requestedNonce = typeof flags["dev-nonce"] === "string" ? flags["dev-nonce"].trim() : undefined;
+    if (requestedNonce && port === undefined)
+        throw new Error("--dev-nonce requires --dev-port");
+    if (requestedNonce && !/^[A-Za-z0-9-]{16,128}$/.test(requestedNonce)) {
+        throw new Error("--dev-nonce must contain 16-128 letters, numbers, or hyphens");
+    }
+    return { port, nonce: requestedNonce || randomUUID() };
+}
 async function cmdLogin(flags) {
     // Manual path (also the headless path): secrets supplied as flags.
     if (typeof flags.token === "string") {
@@ -2291,20 +2489,51 @@ async function cmdLogin(flags) {
             process.exitCode = 1;
         return ok;
     }
-    // Browser path: open a localhost dashboard. Login, legal confirmation, and encryption
-    // passphrase entry all happen through this local bridge. The nonce gates every local route.
+    const store = new KeyStore();
+    if (!flags.force && store.getToken() && store.getKey()) {
+        console.log("This device is already connected. Run `echomem-mcp login --force` to sign in with a different account.");
+        return true;
+    }
+    // Browser path: this bridge does only account/device authentication. It intentionally exposes
+    // no local-history routes; `init` owns scan consent, reporting, and optional extraction.
     console.log("Opening your browser to connect this device locally…");
-    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 { port, nonce } = localBridgeOptions(flags);
+    const srv = await startCallbackServer({ port, nonce, flow: "login" });
+    const localLoginUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
+    openBrowser(localLoginUrl);
+    console.log(`If it didn't open, visit:\n  ${localLoginUrl}\n`);
+    console.log("Waiting for local login for up to 15 minutes…");
+    try {
+        const credentials = await srv.onToken;
+        const ok = await verifyAndPrint(credentials);
+        srv.close();
+        if (!ok) {
+            process.exitCode = 1;
+            return false;
+        }
+        console.log("✅ This device is connected. Run `echomem-mcp init` to begin local-history onboarding.");
+        return true;
     }
-    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");
+    catch (error) {
+        srv.close();
+        console.error(`❌ ${error instanceof Error ? error.message : String(error)}. Run \`echomem-mcp login\` to retry.`);
+        process.exitCode = 1;
+        return false;
     }
-    const nonce = devNonce || randomUUID();
+}
+/**
+ * The local-history onboarding flow. Existing device credentials are reused when available; a
+ * fresh device stays in this same bridge and asks for login only after permission and report.
+ */
+async function cmdOnboarding(flags) {
+    const store = new KeyStore();
+    const savedToken = store.getToken();
+    const savedKey = store.getKey();
+    const initialToken = savedToken && savedKey
+        ? { token: savedToken, key: savedKey }
+        : undefined;
+    console.log("Opening your browser for EchoMem onboarding…");
+    const { port, nonce } = localBridgeOptions(flags);
     let stats = null;
     let forensicReport = null;
     let forensicConsent = "pending";
@@ -2323,8 +2552,10 @@ async function cmdLogin(flags) {
         updatedAt: forensicStartedAt,
     };
     const srv = await startCallbackServer({
-        port: devPortRaw,
+        port,
         nonce,
+        flow: "onboarding",
+        initialToken,
         requireReportConsent: true,
         getStats: () => stats,
         getReport: () => forensicReport,
@@ -2368,7 +2599,7 @@ async function cmdLogin(flags) {
     const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
     openBrowser(localSetupUrl);
     console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
-    console.log("Waiting for local setup for up to 15 minutes…");
+    console.log("Waiting for local-history onboarding for up to 15 minutes…");
     const startForensicScan = () => {
         if (forensicScanStarted || forensicConsent !== "allowed")
             return;
@@ -3116,15 +3347,16 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
-  echomem-mcp init                  One command: configure every installed agent + HUD + log in
+  echomem-mcp init                  One command: configure agents + HUD + login + local-history onboarding
   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 [--client X]    Detect editor, write its MCP config, then connect this device
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
   echomem-mcp setup --no-codex-skills  Skip installing the bundled EchoMem Codex skills
-  echomem-mcp update --all          Repoint detected clients to this installed bridge; no login/browser
+  echomem-mcp update --all          Install this bridge durably + repoint detected clients; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser
   echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
-  echomem-mcp login                 Connect this device in the local browser page (or --token/--passphrase)
+  echomem-mcp login                 Connect this device only; never scans or imports local history
+  echomem-mcp login --force         Reconnect this device with a different account
   echomem-mcp unlock                Privately unlock the vault on this trusted device
   echomem-mcp lock                  Remove the local vault key while keeping the device login
   echomem-mcp status                Show token/key/clients