@echomem/mcp 1.4.26 → 1.4.28

package/dist/setup.js

@@ -25,13 +25,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, setupNewEncryptionKey, verifyKeyB64 } from "./encryption.js";
-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 { runReport, buildStatsPayload } from "./report.js";
+import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, 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 { parseSetupPreviewState } from "./setup-preview.js";
 import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
-import { installHooks } from "./hud/hooks.js";
+import { installHooks, installSaveCheckpointHooks } 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";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
@@ -389,17 +389,19 @@ function echomemGuidanceBlock() {
         "EchoMem is your long-term memory across all coding sessions and tools.",
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
         "- 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`.",
+        "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip it.",
+        "- For a user with a company group, call `get_group_session_sharing` near session start or after the first qualifying private save. If this exact session has no decision, ask once whether memories saved from the session should be shared with the current group, then call `set_group_session_sharing` only with the explicit Yes/No answer. A Yes decision syncs eligible memories after each private save; a No decision keeps later saves private.",
         "- 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.",
+        "- Group session sharing is scoped to the exact current MCP session and current group. Membership is rechecked for each sync. Flagged memories are withheld from automatic session sync and remain private.",
         "- 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. After joining, continue into the profile-and-publication preview instead of leaving title or responsibility blank.",
         "- 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-publication 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 and exclude already-published or exact-content duplicates. Use the candidate evidence to draft a concise title and responsibility summary for the current member, but label both as proposals rather than facts.",
-        "- Use two distinct evidence links. For the user's own source memories during search, flag review, or publication preview, preserve the Memory ID and use `https://echoknows.com/memories/timeline?memoryId=...`; this is an owner-only personal link and may require Vault unlock. For already-published results from `search_others_memories`, use `https://echoknows.com/company/memories?memoryId=...`, which requires current group access.",
+        "- Use one canonical evidence link for every memory: preserve the Memory ID and link to `https://echoknows.com/memory/<memory-id>`. The site resolves the authorized representation: an owner is sent to their private timeline, while current group/friend access opens an authorized publication snapshot or public memory. The visible Markdown label should use the memory key, not the raw URL or UUID.",
         "- If the user asks to flag memories about a sensitive topic, search their own memories first, show the exact matches with owner-only personal links, and ask them to confirm. Only then call `flag_memories_for_publication_attention`; flagging does not publish, decrypt, change visibility, or retract an existing group snapshot.",
         "- Present the proposed title/responsibility and the memory publication preview together and ask for explicit confirmation. Never save an inferred profile or publish memories before confirmation. If an unflagged candidate appears sensitive, proactively ask whether the user wants to mark its exact ID for publication attention first. Explain naturally: marking does not publish or change encryption; it means you will call it out and ask for detailed confirmation whenever a later publication includes it. Never auto-flag based on agent inference. Show already-flagged candidates in a separate warning, state that nothing has been published yet, and offer three choices: exclude them, review them separately, or first search for and mark similar sensitive owned memories for publication attention.",
         "- On confirmation, call `update_group_profile` with the confirmed title, responsibility summary, and `confirmed: true`, then call `complete_group_publication` with the exact `scanId`, selected memory IDs, and `confirmed: true`. If a flagged memory is selected, require separate explicit acknowledgement and pass its exact ID in `acknowledgedFlaggedMemoryIds`. If the user edits either proposal, use their wording. An explicit request to join and upload still requires this preview and confirmation.",
@@ -1143,6 +1145,155 @@ function discoverMigratableSessionsOffThread() {
         });
     });
 }
+export function discoverMigratableFastOffThread(opts = {}) {
+    const migrateUrl = runtimeModuleUrl("migrate");
+    const serializedOpts = JSON.stringify(opts);
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { discoverMigratableFastDiscovery } from ${JSON.stringify(migrateUrl)};
+
+    try {
+      parentPort?.postMessage({ ok: true, discovery: discoverMigratableFastDiscovery(${serializedOpts}) });
+    } catch (error) {
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        worker.once("message", (message) => {
+            settled = true;
+            const msg = message;
+            if (msg.ok === true && msg.discovery && typeof msg.discovery === "object") {
+                resolve(msg.discovery);
+                return;
+            }
+            const err = new Error(typeof msg.message === "string" ? msg.message : "Quick local discovery failed");
+            if (typeof msg.stack === "string")
+                err.stack = msg.stack;
+            reject(err);
+        });
+        worker.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+        worker.once("exit", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Quick local discovery worker exited (code ${code}) without a result`));
+        });
+    });
+}
+/** Build the full local-history dashboard payload away from the callback server's event loop.
+ * `collect()` can synchronously parse hundreds of JSONL files for tens of seconds; doing that on
+ * the bridge thread prevents even localhost actions such as account switch from receiving a reply. */
+export function buildCollectedStatsPayloadOffThread(inject) {
+    const reportUrl = runtimeModuleUrl("report");
+    const serializedInject = JSON.stringify(inject);
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { collect, buildStatsPayload } from ${JSON.stringify(reportUrl)};
+
+    try {
+      const payload = await buildStatsPayload(collect(), ${serializedInject});
+      parentPort?.postMessage({ ok: true, payload });
+    } catch (error) {
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            void worker.terminate();
+            if (result.ok)
+                resolve(result.payload);
+            else
+                reject(result.error);
+        };
+        worker.once("message", (message) => {
+            const msg = message;
+            if (msg.ok === true) {
+                finish({ ok: true, payload: msg.payload });
+                return;
+            }
+            const error = new Error(typeof msg.message === "string" ? msg.message : "Full local stats worker failed");
+            if (typeof msg.stack === "string")
+                error.stack = msg.stack;
+            finish({ ok: false, error });
+        });
+        worker.once("error", (error) => {
+            finish({ ok: false, error });
+        });
+        worker.once("exit", (code) => {
+            if (settled)
+                return;
+            finish({ ok: false, error: new Error(`Full local stats worker exited (code ${code}) without a result`) });
+        });
+    });
+}
+export function createLocalDiscoveryCache(loaders = {}) {
+    const loadQuick = loaders.loadQuick ?? (() => discoverMigratableFastOffThread());
+    const loadExact = loaders.loadExact ?? (() => discoverMigratableSessionsOffThread());
+    let quick = null;
+    let quickPromise = null;
+    let exact = null;
+    let exactPromise = null;
+    return {
+        getQuick() {
+            if (quick)
+                return Promise.resolve(quick);
+            if (quickPromise)
+                return quickPromise;
+            quickPromise = loadQuick()
+                .then((discovery) => {
+                quick = discovery;
+                return discovery;
+            })
+                .catch((error) => {
+                quickPromise = null;
+                throw error;
+            });
+            return quickPromise;
+        },
+        getExact() {
+            if (exact)
+                return Promise.resolve(exact);
+            if (exactPromise)
+                return exactPromise;
+            exactPromise = loadExact()
+                .then((discovery) => {
+                exact = discovery;
+                return discovery;
+            })
+                .catch((error) => {
+                exactPromise = null;
+                throw error;
+            });
+            return exactPromise;
+        },
+        peekExact() {
+            return exact;
+        },
+        pendingExact() {
+            return exactPromise;
+        },
+    };
+}
 function forensicStageLabel(stage) {
     if (stage === "reading-transcripts")
         return "Reading transcript files";
@@ -1164,7 +1315,9 @@ export function buildForensicReportOffThread(onProgress, options = {}) {
     try {
       const report = await buildForensicReport({
         includeLegacyGoldenStandard: false,
-        onProgress: (done, total, stage, detail) => parentPort?.postMessage({ progress: { done, total, stage, detail } }),
+        onProgress: (done, total, stage, detail, overall, stageDone, stageTotal) => parentPort?.postMessage({
+          progress: { done, total, stage, detail, overall, stageDone, stageTotal },
+        }),
       });
       parentPort?.postMessage({ ok: true, report });
     } catch (error) {
@@ -1253,7 +1406,11 @@ function publicRunningForensicProgress(value) {
     const safeDuration = (candidate) => (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0
         ? candidate
         : 0);
+    const safeFraction = (candidate) => (typeof candidate === "number" && Number.isFinite(candidate)
+        ? Math.min(1, Math.max(0, candidate))
+        : 0);
     const total = safeCount(progress.total);
+    const stageTotal = safeCount(progress.stageTotal);
     const rawStage = typeof progress.stage === "string" ? progress.stage : "starting";
     const stage = ["starting", "reading-transcripts", "building-summary", "classifying-repeated-context", "finalizing-report"].includes(rawStage)
         ? rawStage
@@ -1264,6 +1421,9 @@ function publicRunningForensicProgress(value) {
         total,
         stage,
         label: forensicStageLabel(stage),
+        stageDone: stageTotal > 0 ? Math.min(safeCount(progress.stageDone), stageTotal) : 0,
+        stageTotal,
+        overall: safeFraction(progress.overall),
         elapsedMs: safeDuration(progress.elapsedMs),
         stageElapsedMs: safeDuration(progress.stageElapsedMs),
         updatedAt: safeDuration(progress.updatedAt) || Date.now(),
@@ -1289,6 +1449,7 @@ export function startCallbackServer(opts = {}) {
     const requiresReportConsent = opts.requireReportConsent === true && !isLoginFlow;
     return new Promise((resolveOuter, rejectOuter) => {
         const onToken = deferred();
+        const setupExit = deferred();
         const decision = deferred();
         const migrateRequest = deferred();
         let stats = null;
@@ -1296,6 +1457,7 @@ export function startCallbackServer(opts = {}) {
         let switchAccountUrl = "";
         let connected = Boolean(opts.initialToken?.token);
         let activeDeviceToken = opts.initialToken?.token || "";
+        let activeAccountEmail = "";
         let pendingLocalAuth = null;
         let reportConsentGranted = !requiresReportConsent;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
@@ -1330,8 +1492,8 @@ export function startCallbackServer(opts = {}) {
                 return false;
             return revokeDeviceToken(pending.token);
         };
-        const completeDeviceLogin = async (token) => {
-            await authedAxios(token).post("/api/extension/mcp/local-auth/complete-device", {}, { timeout: 10_000 });
+        const completeDeviceLogin = async (token, encryptionPreference = "maximum") => {
+            await authedAxios(token).post("/api/extension/mcp/local-auth/complete-device", { encryptionPreference }, { timeout: 10_000 });
         };
         const close = () => {
             if (timer)
@@ -1407,6 +1569,7 @@ export function startCallbackServer(opts = {}) {
             const firstToken = !onToken.settled();
             connected = true;
             activeDeviceToken = token;
+            activeAccountEmail = pendingLocalAuth?.email || activeAccountEmail;
             pendingLocalAuth = null;
             const callbackToken = { token, key };
             if (firstToken) {
@@ -1425,6 +1588,7 @@ export function startCallbackServer(opts = {}) {
             "/stats",
             "/billing-status",
             "/billing-checkout",
+            "/billing-checkout-sync",
             "/billing-portal",
             "/progress",
             "/migrate",
@@ -1563,6 +1727,38 @@ export function startCallbackServer(opts = {}) {
                 json(res, detail.status, { ok: false, error: detail.message });
             }
         };
+        const handleLocalSkipEncryption = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            if (!pendingLocalAuth || pendingLocalAuth.expiresAtMs <= Date.now()) {
+                await revokePendingLocalAuth();
+                return void json(res, 409, {
+                    ok: false,
+                    error: "This local login expired. Send a new verification code.",
+                    reset: true,
+                });
+            }
+            if (pendingLocalAuth.mode !== "setup") {
+                return void json(res, 409, {
+                    ok: false,
+                    error: "This account already uses encrypted memory. Enter the vault passphrase to continue.",
+                });
+            }
+            try {
+                await completeDeviceLogin(pendingLocalAuth.token, "standard");
+                resolveLocalToken(pendingLocalAuth.token, undefined);
+                json(res, 200, {
+                    ok: true,
+                    connected: true,
+                    encryptionEnabled: false,
+                    encryptionPreference: "standard",
+                });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to continue without encryption");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
         server = http.createServer((req, res) => {
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type");
@@ -1627,6 +1823,18 @@ export function startCallbackServer(opts = {}) {
                     });
                     return;
                 }
+                if (route === "/local-auth/skip-encryption" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalSkipEncryption(res, body);
+                    return;
+                }
                 if (route === "/launch-agent" && req.method === "POST") {
                     let body;
                     try {
@@ -1740,7 +1948,18 @@ export function startCallbackServer(opts = {}) {
                     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 });
+                        json(res, 200, {
+                            plan: "free",
+                            paid: false,
+                            trialAvailable: true,
+                            trialUsed: false,
+                            subscriptionStatus: null,
+                            trialStartedAt: null,
+                            trialEndedAt: null,
+                            currentPeriodEnd: null,
+                            cancelAtPeriodEnd: false,
+                            pricingUrl,
+                        });
                         return;
                     }
                     try {
@@ -1752,24 +1971,84 @@ export function startCallbackServer(opts = {}) {
                         const plan = (asString(response.data?.plan) || "free").toLowerCase();
                         const trialUsed = response.data?.billing?.trialUsed === true;
                         const trialAvailable = response.data?.billing?.trialAvailable !== false;
+                        const accountEmail = asString(profileResponse?.data?.email) || activeAccountEmail;
+                        if (accountEmail)
+                            activeAccountEmail = accountEmail;
                         json(res, 200, {
                             plan,
                             paid: ["pro", "power", "team", "enterprise"].includes(plan),
                             trialAvailable,
                             trialUsed,
+                            subscriptionStatus: asString(response.data?.billing?.subscriptionStatus) || null,
+                            trialStartedAt: asString(response.data?.billing?.trialStartedAt) || null,
+                            trialEndedAt: asString(response.data?.billing?.trialEndedAt) || null,
+                            currentPeriodEnd: asString(response.data?.billing?.currentPeriodEnd) || null,
+                            cancelAtPeriodEnd: response.data?.billing?.cancelAtPeriodEnd === true,
                             historicalConversationQuota: response.data?.historicalConversationQuota ?? null,
                             memoryProcessingQuota: response.data?.memoryProcessingQuota ?? null,
                             memorySearchQuota: response.data?.memorySearchQuota ?? null,
-                            account: profileResponse ? {
-                                displayName: asString(profileResponse.data?.displayName) || "EchoMem user",
-                                email: asString(profileResponse.data?.email) || "",
-                                avatarUrl: asString(profileResponse.data?.avatarUrl) || "",
+                            activation: response.data?.activation ?? null,
+                            account: accountEmail ? {
+                                email: accountEmail,
+                                avatarUrl: asString(profileResponse?.data?.avatarUrl) || "",
                             } : null,
                             pricingUrl,
                         });
                     }
                     catch {
-                        json(res, 200, { plan: "unknown", paid: false, trialAvailable: true, trialUsed: false, pricingUrl });
+                        json(res, 200, {
+                            plan: "unknown",
+                            paid: false,
+                            trialAvailable: false,
+                            trialUsed: false,
+                            subscriptionStatus: null,
+                            trialStartedAt: null,
+                            trialEndedAt: null,
+                            currentPeriodEnd: null,
+                            cancelAtPeriodEnd: false,
+                            pricingUrl,
+                        });
+                    }
+                    return;
+                }
+                if (route === "/billing-checkout-sync" && 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 sessionId = asString(body.sessionId);
+                    if (!sessionId || !/^cs_(?:test_|live_)?[A-Za-z0-9_]+$/.test(sessionId)) {
+                        return void json(res, 400, {
+                            error: "INVALID_CHECKOUT_SESSION",
+                            message: "Checkout session is missing or invalid.",
+                        });
+                    }
+                    const token = activeDeviceToken || new KeyStore().getToken();
+                    if (!connected || !token) {
+                        return void json(res, 401, {
+                            error: "ECHOMEM_LOGIN_REQUIRED",
+                            message: "Connect your EchoMem account before syncing checkout.",
+                        });
+                    }
+                    try {
+                        const response = await axios.post(hostedBillingEndpoint("/api/billing/checkout/sync"), { sessionId }, {
+                            timeout: 15_000,
+                            headers: {
+                                "Content-Type": "application/json",
+                                Authorization: `Bearer ${token}`,
+                            },
+                        });
+                        json(res, 200, { ok: response.data?.ok === true });
+                    }
+                    catch (error) {
+                        const detail = publicAxiosError(error, "Checkout is still syncing.");
+                        json(res, detail.status, { error: "BILLING_SYNC_PENDING", message: detail.message });
                     }
                     return;
                 }
@@ -1837,7 +2116,12 @@ export function startCallbackServer(opts = {}) {
                                 message: "Echo billing returned an unexpected destination.",
                             });
                         }
-                        json(res, 200, { url: hostedUrl });
+                        json(res, 200, {
+                            url: hostedUrl,
+                            ...(isCheckout && typeof response.data?.sessionId === "string"
+                                ? { sessionId: response.data.sessionId }
+                                : {}),
+                        });
                     }
                     catch (error) {
                         const detail = publicAxiosError(error, isCheckout ? "Could not start secure checkout." : "Could not open secure plan management.");
@@ -1931,6 +2215,7 @@ export function startCallbackServer(opts = {}) {
                     }
                     const validation = validateForensicReportForSetup(payload);
                     if (!validation.ok) {
+                        console.error(`[echomem] local report validation failed: ${validation.code} — ${validation.message}`);
                         return void json(res, 500, {
                             schemaVersion: 1,
                             kind: "failed",
@@ -2000,22 +2285,25 @@ export function startCallbackServer(opts = {}) {
                     }
                     connected = false;
                     activeDeviceToken = "";
+                    activeAccountEmail = "";
                     const revokedPendingCredential = await revokePendingLocalAuth();
                     stats = null;
                     migrateStarted = false;
                     progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
+                    try {
+                        await logoutHandler?.();
+                    }
+                    catch (e) {
+                        console.error(`Could not reset local login state: ${e instanceof Error ? e.message : String(e)}`);
+                    }
                     json(res, 200, {
                         ok: true,
+                        connected: false,
                         authUrl,
                         switchAccountUrl: switchAccountUrl || authUrl,
                         localOnly: true,
                         revokedPendingCredential,
                     });
-                    Promise.resolve()
-                        .then(() => logoutHandler?.())
-                        .catch((e) => {
-                        console.error(`Could not reset local login state: ${e instanceof Error ? e.message : String(e)}`);
-                    });
                     return;
                 }
                 if (route === "/migrate" && req.method === "POST") {
@@ -2075,6 +2363,9 @@ export function startCallbackServer(opts = {}) {
                         }
                     }
                     json(res, 200, { ok: true });
+                    if (!onToken.settled()) {
+                        setupExit.resolve("skip");
+                    }
                     decision.resolve("skip");
                     close();
                     return;
@@ -2101,6 +2392,7 @@ export function startCallbackServer(opts = {}) {
                 port,
                 onToken: onToken.promise,
                 wait: onToken.promise,
+                setupExit: setupExit.promise,
                 decision: decision.promise,
                 migrateRequest: migrateRequest.promise,
                 setTokenRefreshHandler: (handler) => {
@@ -2311,6 +2603,9 @@ async function cmdSetup(flags) {
     if (!flags["no-codex-skills"]) {
         writeCodexSkillsForTargets(targets);
     }
+    if (flags["install-save-hooks"]) {
+        writeSaveCheckpointHooksForTargets(targets);
+    }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
         // init drives login itself right after, so the "skipped" note would be misleading there.
@@ -2333,7 +2628,14 @@ async function cmdSetup(flags) {
 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 });
+    await cmdSetup({
+        ...flags,
+        all: true,
+        "skip-login": true,
+        "with-hud": false,
+        "init-quiet": true,
+        "install-save-hooks": flags["no-save-hooks"] !== true,
+    });
     // 2. Bring the HUD up NOW (non-blocking) so everything is already running while onboarding proceeds.
     if (!flags["no-hud"])
         await cmdSetupHud(flags);
@@ -2400,6 +2702,23 @@ function writeCodexSkillsForTargets(targets) {
         console.log(`ℹ️  Could not install EchoMem Codex skills: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+function writeSaveCheckpointHooksForTargets(targets) {
+    const clients = new Set();
+    if (targets.some((target) => target.id === "codex"))
+        clients.add("codex");
+    if (targets.some((target) => target.id === "claude-code"))
+        clients.add("claude-code");
+    if (clients.size === 0) {
+        console.log("ℹ️  No hook-capable Codex or Claude Code client was detected; private-save checkpoint hooks were not installed.");
+        return;
+    }
+    const mode = clients.size === 2 ? "both" : [...clients][0];
+    const paths = installSaveCheckpointHooks(mode);
+    console.log(`✅ Installed EchoMem private-save checkpoint hooks:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
+    if (clients.has("codex")) {
+        console.log("   Codex: start a new session and run /hooks once to review and trust the hook.");
+    }
+}
 async function cmdUpdate(flags) {
     if (!flags.dev)
         installDurableGlobalUpdate();
@@ -2544,12 +2863,16 @@ async function cmdOnboarding(flags) {
     const forensicStartedAt = Date.now();
     let forensicStageStartedAt = forensicStartedAt;
     let forensicStage = "starting";
+    let forensicOverall = 0;
     let forensicProgress = {
         status: "running",
         scanned: 0,
         total: 0,
         stage: forensicStage,
         label: forensicStageLabel(forensicStage),
+        stageDone: 0,
+        stageTotal: 0,
+        overall: 0,
         elapsedMs: 0,
         stageElapsedMs: 0,
         updatedAt: forensicStartedAt,
@@ -2562,7 +2885,18 @@ async function cmdOnboarding(flags) {
         requireReportConsent: true,
         getStats: () => stats,
         getReport: () => forensicReport,
-        getReportProgress: () => forensicProgress,
+        getReportProgress: () => {
+            if (forensicProgress.status !== "running")
+                return forensicProgress;
+            const now = Date.now();
+            const sinceWorkerUpdate = Math.max(0, now - forensicProgress.updatedAt);
+            return {
+                ...forensicProgress,
+                elapsedMs: forensicProgress.elapsedMs + sinceWorkerUpdate,
+                stageElapsedMs: forensicProgress.stageElapsedMs + sinceWorkerUpdate,
+                updatedAt: now,
+            };
+        },
         onReportConsent: (allowed) => {
             if (!allowed) {
                 forensicConsent = "declined";
@@ -2572,6 +2906,9 @@ async function cmdOnboarding(flags) {
                     total: 0,
                     stage: "failed",
                     label: "Local scan skipped",
+                    stageDone: 0,
+                    stageTotal: 0,
+                    overall: 0,
                     elapsedMs: Date.now() - forensicStartedAt,
                     stageElapsedMs: Date.now() - forensicStageStartedAt,
                     updatedAt: Date.now(),
@@ -2586,12 +2923,16 @@ async function cmdOnboarding(flags) {
             const now = Date.now();
             forensicStage = "starting";
             forensicStageStartedAt = now;
+            forensicOverall = 0;
             forensicProgress = {
                 status: "running",
                 scanned: 0,
                 total: 0,
                 stage: forensicStage,
                 label: forensicStageLabel(forensicStage),
+                stageDone: 0,
+                stageTotal: 0,
+                overall: 0,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: 0,
                 updatedAt: now,
@@ -2616,6 +2957,8 @@ async function cmdOnboarding(flags) {
                 forensicStageStartedAt = now;
                 console.log(`Local scan: ${forensicStageLabel(forensicStage)}…`);
             }
+            // Latched, so a caller that ever reports a smaller fraction cannot walk the bar backwards.
+            forensicOverall = Math.max(forensicOverall, typeof progress.overall === "number" && Number.isFinite(progress.overall) ? progress.overall : 0);
             forensicProgress = {
                 status: "running",
                 scanned: progress.done,
@@ -2623,6 +2966,13 @@ async function cmdOnboarding(flags) {
                 stage: forensicStage,
                 label: forensicStageLabel(forensicStage),
                 detail: progress.detail,
+                stageDone: typeof progress.stageDone === "number" && Number.isFinite(progress.stageDone)
+                    ? Math.max(0, Math.floor(progress.stageDone))
+                    : 0,
+                stageTotal: typeof progress.stageTotal === "number" && Number.isFinite(progress.stageTotal)
+                    ? Math.max(0, Math.floor(progress.stageTotal))
+                    : 0,
+                overall: forensicOverall,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: now - forensicStageStartedAt,
                 updatedAt: now,
@@ -2639,6 +2989,9 @@ async function cmdOnboarding(flags) {
                 total: forensicProgress.total,
                 stage: "failed",
                 label: "Local scan failed",
+                stageDone: forensicProgress.stageDone,
+                stageTotal: forensicProgress.stageTotal,
+                overall: forensicOverall,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: now - forensicStageStartedAt,
                 updatedAt: now,
@@ -2650,7 +3003,16 @@ async function cmdOnboarding(flags) {
     let token;
     let key;
     try {
-        ({ token, key } = await srv.onToken);
+        const authResult = await Promise.race([
+            srv.onToken.then((credentials) => ({ kind: "token", credentials })),
+            srv.setupExit.then(() => ({ kind: "skip" })),
+        ]);
+        if (authResult.kind === "skip") {
+            srv.close();
+            console.log("Vault setup deferred. Your local coding history is unchanged; run `echomem-mcp init` when you are ready to continue.");
+            return false;
+        }
+        ({ token, key } = authResult.credentials);
     }
     catch (e) {
         srv.close();
@@ -2667,13 +3029,22 @@ async function cmdOnboarding(flags) {
     let exactDiscovery = Promise.resolve(null);
     let refreshGeneration = 0;
     let latestPendingEstimate = 0;
+    // Local discovery is account-independent. Keep one snapshot for this onboarding process and
+    // overlay each connected account's processed keys instead of rereading every JSONL on switch.
+    const localDiscovery = createLocalDiscoveryCache({
+        loadExact: async () => {
+            // Publish the quick metadata result before starting the heavier exact worker.
+            await delay(250);
+            return discoverMigratableSessionsOffThread();
+        },
+    });
     // The account's already-imported keys, shared so the /migrate sizing can assemble ONLY pending sessions.
     let lastProcessedImportKeys = null;
     const resetLocalLoginState = () => {
         refreshGeneration++;
         stats = null;
         disc = null;
-        exactDiscovery = Promise.resolve(null);
+        exactDiscovery = localDiscovery.pendingExact() ?? Promise.resolve(localDiscovery.peekExact());
         latestPendingEstimate = 0;
         lastProcessedImportKeys = null;
         srv.setStats(null);
@@ -2691,7 +3062,9 @@ async function cmdOnboarding(flags) {
         const generation = ++refreshGeneration;
         lastProcessedImportKeys = null; // shared with /migrate so it can assemble only the pending sessions
         let importStatusUnavailable = false;
-        const quickDiscovery = discoverMigratableFastDiscovery();
+        const quickDiscovery = await localDiscovery.getQuick();
+        if (generation !== refreshGeneration)
+            return;
         const quick = summarizeFastMigratableDiscovery(quickDiscovery);
         let migratable = migratableFromFastSummary(quick);
         latestPendingEstimate = migratable.pending;
@@ -2799,23 +3172,7 @@ async function cmdOnboarding(flags) {
                 console.error(`Could not check this EchoMem account's import status quickly: ${e instanceof Error ? e.message : String(e)}`);
             }
         });
-        exactDiscovery = new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                void (async () => {
-                    try {
-                        // Start the local sizing pass without waiting on cloud/account status. The
-                        // account check is useful for tighter counts, but extraction can safely start
-                        // from local candidates because the import path skips true duplicates.
-                        await delay(250);
-                        resolve(await discoverMigratableSessionsOffThread());
-                    }
-                    catch (e) {
-                        reject(e instanceof Error ? e : new Error(String(e)));
-                    }
-                })();
-            }, 250);
-            timer.unref?.();
-        }).then(async (exact) => {
+        exactDiscovery = localDiscovery.getExact().then(async (exact) => {
             if (generation !== refreshGeneration)
                 return disc;
             const initialExact = lastProcessedImportKeys
@@ -2897,7 +3254,7 @@ async function cmdOnboarding(flags) {
                     failed: 0,
                     extracted: 0,
                 });
-                const fullPayload = withCandidateSessions(await buildStatsPayload(collect(), {
+                const fullPayload = withCandidateSessions(await buildCollectedStatsPayloadOffThread({
                     sessions: sessionSummary,
                     migratable,
                     discovery: { phase: "full", exact: true },
@@ -3380,7 +3737,8 @@ Manual / headless:
   ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
   ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
-  echomem-mcp setup --with-hud --install-hud-hooks --client codex [--hud-client auto]
+  echomem-mcp setup --with-hud --install-hud-hooks --install-save-hooks --client codex [--hud-client auto]
+  echomem-mcp setup --install-save-hooks --all  Install proactive private-save completion checks
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 
 Current bridge version: ${MCP_PACKAGE_VERSION}