@echomem/mcp 1.4.19 → 1.4.21

package/README.md

@@ -25,8 +25,11 @@ For **zero-knowledge accounts**, the key never leaves your machine. The bridge h
 - **writes:** the key is handed to your own backend transiently in the `X-Encryption-Key` header so
   memories are encrypted at rest (the server processes plaintext for the request only — never stores
   the key).
-- **locked state:** if the key is absent or past its TTL (7 days, matching the extension), tools
-  return a `🔒 locked` nudge to run `echomem-mcp unlock` — **ciphertext is never handed to the model**.
+- **trusted-device lifecycle:** after a verified login/unlock, the MCP key remains available until
+  the user runs `echomem-mcp lock`, logs out, or removes the local credentials. If the key is absent,
+  tools tell the user to run `echomem-mcp unlock` in their own terminal. The passphrase prompt is
+  visible while typed characters stay hidden, and the current agent session can retry immediately
+  after unlock — **ciphertext is never handed to the model**.
 
 Unencrypted accounts are unaffected. `search_memories` returns retrieved memories by default so
 your MCP client does the final answer generation; pass `includeAnswer: true` only if you need the
@@ -47,8 +50,11 @@ to the global install, but installing globally avoids the issue entirely). The c
 launch-at-login also runs from the installed path. `init` is the flagship one-liner — it wraps `setup --all --with-hud`: it writes each
 installed agent's MCP config (with **no secret** in it — credentials live in
 `~/.echomem/credentials.json`, mode 0600), adds the EchoMem memory guidance to their global
-`AGENTS.md` / `CLAUDE.md`, opens the browser to approve the device (and unlock the vault for
-encrypted accounts), then launches the context HUD. Reload your editors and you're done.
+`AGENTS.md` / `CLAUDE.md`, installs first-party `echomem-search`, `echomem-save`,
+`echomem-forget`, and `echomem-login` skills for Codex, opens the browser to approve the device
+(and unlock the vault for encrypted accounts), then launches the context HUD. EchoMem updates only
+its own skill folders; other memory-provider skills are detected and reported but never modified.
+Reload your editors and you're done.
 
 Prefer to keep it minimal? `echomem-mcp setup` configures only the auto-detected editor and skips the
 HUD; the granular commands below still work.
@@ -64,7 +70,8 @@ HUD; the granular commands below still work.
 | `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
 | `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
-| `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
+| `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 / detected clients, configured bridge versions, and update guidance |
 | `echomem-mcp doctor [--no-network]` | Diagnose configured client bridge versions |
 | `echomem-mcp logout` | Remove stored credentials |

package/dist/codex-session-files.js

@@ -35,6 +35,12 @@ function normalizedSessionId(value) {
     const trimmed = value.trim();
     return new RegExp(`^${UUID_RE.source}$`, "i").test(trimmed) ? trimmed.toLowerCase() : trimmed;
 }
+function isAutomaticCodexSource(source) {
+    if (typeof source !== "string")
+        return false;
+    const normalized = source.trim().toLowerCase().replace(/-/g, "_");
+    return normalized === "auto_review" || normalized === "guardian";
+}
 function metadataFromFile(file) {
     try {
         for (const line of initialJsonLines(file)) {
@@ -63,7 +69,7 @@ function metadataFromFile(file) {
             return {
                 id: rawId || null,
                 startedAtMs: Number.isFinite(timestamp) ? timestamp : null,
-                userInitiated: !isSubagent && !hasParent,
+                userInitiated: !isSubagent && !hasParent && !isAutomaticCodexSource(source),
             };
         }
         return { id: null, startedAtMs: null, userInitiated: null };

package/dist/crypto.js

@@ -95,6 +95,10 @@ export async function decrypt(ciphertext, key) {
     const plainBuffer = await subtle.decrypt({ name: ALGORITHM, iv }, key, data);
     return new TextDecoder().decode(plainBuffer);
 }
+/** Create a server-verifiable token for a newly configured encryption key. */
+export async function createVerification(key) {
+    return encrypt(VERIFICATION_PLAINTEXT, key);
+}
 /** Verify a key against a stored verification token (current + legacy plaintexts). */
 export async function verifyKey(key, token) {
     try {

package/dist/encryption.js

@@ -1,4 +1,5 @@
-import { deriveKey, exportKeyToBase64, importKeyFromBase64, decrypt, verifyKey, saltFromBase64 } from "./crypto.js";
+import { createVerification, deriveKey, exportKeyToBase64, generateSalt, importKeyFromBase64, decrypt, saltFromBase64, saltToBase64, verifyKey, } from "./crypto.js";
+const DEFAULT_KEY_ITERATIONS = 600_000;
 /** GET the account's encryption status from the EchoMem backend using the bridge's authed client. */
 export async function fetchEncryptionConfig(axios) {
     // Bounded: this is on the startup/tool-listing path; an unbounded call on a flaky network would hang
@@ -21,11 +22,22 @@ export async function deriveAndVerifyKey(passphrase, config) {
     if (!config.enabled || !config.salt || !config.verification)
         return null;
     const salt = saltFromBase64(config.salt);
-    const key = await deriveKey(passphrase, salt, config.iterations ?? 600_000);
+    const key = await deriveKey(passphrase, salt, config.iterations ?? DEFAULT_KEY_ITERATIONS);
     if (!(await verifyKey(key, config.verification)))
         return null;
     return exportKeyToBase64(key);
 }
+/** Create a fresh account encryption config locally. The passphrase/key never leaves the device. */
+export async function setupNewEncryptionKey(passphrase, iterations = DEFAULT_KEY_ITERATIONS) {
+    const salt = generateSalt();
+    const key = await deriveKey(passphrase, salt, iterations);
+    return {
+        keyBase64: await exportKeyToBase64(key),
+        saltBase64: saltToBase64(salt),
+        verification: await createVerification(key),
+        iterations,
+    };
+}
 /** Verify an already-exported base64 key against the server's verification token. */
 export async function verifyKeyB64(keyBase64, config) {
     if (!config.enabled || !config.verification)

package/dist/index.js

@@ -10,7 +10,7 @@ import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
 import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
 import { createHash, randomUUID } from "node:crypto";
-import { fetchEncryptionConfig, decryptMemoryFields } from "./encryption.js";
+import { fetchEncryptionConfig, decryptMemoryFields, verifyKeyB64, } from "./encryption.js";
 import { runCli } from "./setup.js";
 import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS } from "./package-metadata.js";
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
@@ -22,11 +22,9 @@ class NoTokenError extends Error {
 }
 /** Thrown when an encrypted account has no usable key — the model gets an unlock nudge, never ciphertext. */
 class LockedError extends Error {
-    expired;
-    constructor(expired) {
-        super("EchoMem vault locked");
-        this.expired = expired;
-    }
+}
+/** Thrown when the bridge cannot prove whether the account is encrypted. */
+class EncryptionStatusUnavailableError extends Error {
 }
 function stringifyErrorValue(value) {
     if (value == null) {
@@ -135,6 +133,15 @@ function formatUpgradeRequiredResult(error) {
         code ? `Reason: ${code}.` : "",
     ].filter(Boolean).join("\n");
 }
+function formatReconnectRequiredResult(error) {
+    if (!axios.isAxiosError(error) || error.response?.status !== 401)
+        return null;
+    return [
+        "🔌 EchoMem's saved login is no longer accepted (Unauthorized, HTTP 401).",
+        "Action required from the user: run `echomem-mcp login` in a terminal to reconnect this device, then retry this action.",
+        "No editor restart is needed. Keep all credentials out of chat.",
+    ].join("\n");
+}
 /** Map a thrown error to the telemetry error_kind taxonomy. */
 function classifyError(error) {
     if (error instanceof NoTokenError)
@@ -569,8 +576,8 @@ class EchoMemApiClient {
         if (!this.encConfigPromise) {
             this.encConfigPromise = fetchEncryptionConfig(this.axios).catch((error) => {
                 this.encConfigPromise = null; // allow retry next call
-                console.error(`[encryption] config fetch failed: ${describeError(error)} — proceeding as unencrypted`);
-                return { enabled: false };
+                console.error(`[encryption] config fetch failed: ${describeError(error)} — refusing memory access`);
+                throw new EncryptionStatusUnavailableError("EchoMem could not verify the account encryption state");
             });
         }
         return this.encConfigPromise;
@@ -581,18 +588,20 @@ class EchoMemApiClient {
      * handing the model ciphertext. For unencrypted accounts it returns `{ enabled: false }`.
      */
     async encState() {
-        // A stored key ONLY exists because the user unlocked an ENCRYPTED vault, so treat it as
-        // authoritative: a flaky/failed `/account/encryption` fetch (which defaults to enabled:false) must
-        // NOT downgrade an unlocked encrypted account to plaintext — that causes a 422 on save and leaks
-        // ciphertext on read. So if we hold a usable key, we're encrypted-and-unlocked, period.
-        const key = this.store.getKey();
-        if (key)
-            return { enabled: true, key };
-        // No usable key: consult the server to tell "unencrypted" apart from "encrypted but locked/expired".
         const cfg = await this.getEncryptionConfig();
-        if (cfg.enabled)
-            throw new LockedError(this.store.isKeyExpired());
-        return { enabled: false };
+        if (!cfg.enabled)
+            return { enabled: false };
+        const key = this.store.getKey();
+        if (!key)
+            throw new LockedError("EchoMem vault locked");
+        if (!(await verifyKeyB64(key, cfg))) {
+            // A file-backed stale key can be removed safely; environment-provided
+            // keys remain under the caller's control and are ignored until corrected.
+            if (!process.env.ECHO_ENCRYPTION_KEY)
+                this.store.clearKey();
+            throw new LockedError("EchoMem vault key is invalid");
+        }
+        return { enabled: true, key };
     }
     pruneDeleteConfirmations(now = Date.now()) {
         for (const [memoryId, confirmation] of this.deleteConfirmations) {
@@ -613,13 +622,6 @@ class EchoMemApiClient {
         }
         return this.whoamiCache;
     }
-    cleanMemoryDescription(desc) {
-        if (!desc)
-            return "";
-        // The tuned snapshot wraps text as "Here is a memory: …Content: <text>".
-        const idx = desc.indexOf("Content:");
-        return (idx >= 0 ? desc.slice(idx + "Content:".length) : desc).trim();
-    }
     async fetchMemoryById(id, enc) {
         try {
             const response = await this.axios.get(`/api/extension/memories/${encodeURIComponent(id)}`, {
@@ -635,34 +637,6 @@ class EchoMemApiClient {
             throw error;
         }
     }
-    async searchMemoriesRaw(query, opts, enc, retrievalOnly = false, trace) {
-        const endpoint = "/api/extension/memories/search";
-        let response;
-        try {
-            response = await this.axios.post(endpoint, {
-                query,
-                k: opts.limit,
-                similarityThreshold: opts.threshold,
-                timeFrameDays: opts.timeFrameDays,
-                requestId: opts.requestId,
-                sessionId: this.sessionId,
-            });
-            trace?.({ requestId: opts.requestId, endpoint, httpStatus: response.status });
-        }
-        catch (error) {
-            trace?.({
-                requestId: opts.requestId,
-                endpoint,
-                httpStatus: axios.isAxiosError(error) ? error.response?.status : undefined,
-                errorCode: axios.isAxiosError(error) ? errorCodeFrom(error.response?.data) : undefined,
-            });
-            throw error;
-        }
-        const data = enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
-        return retrievalOnly && isRecord(data)
-            ? { ...data, retrievalOnly: true, tuned: false }
-            : data;
-    }
     async searchMemoriesRetrieved(query, opts, enc, trace) {
         const endpoint = "/api/extension/memories/deep-search/candidates";
         let response;
@@ -737,48 +711,6 @@ class EchoMemApiClient {
             memories,
         };
     }
-    // Tuned recall. Routes through echo-mem-chrome's AUTHENTICATED deep-search proxy
-    // (the same route the Chrome extension uses): it verifies our ec_ token, derives
-    // user_id server-side, and forwards to dg-web's two-phase retriever. The bridge
-    // never hits dg-web directly, so no new auth is needed and no other caller is
-    // disrupted. NOTE: encrypted users still get server-side plaintext only; the
-    // phase-1 + bridge-local-decrypt + phase-2 flow (spec §11) is the remaining work.
-    async searchMemoriesTuned(query, requestId, trace) {
-        const endpoint = "/api/extension/memories/deep-search";
-        let response;
-        try {
-            response = await this.axios.post(endpoint, {
-                query,
-                requestId,
-                logicalRequestId: requestId,
-                sessionId: this.sessionId,
-                userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
-            });
-            trace?.({ requestId, endpoint, httpStatus: response.status });
-        }
-        catch (error) {
-            trace?.({
-                requestId,
-                endpoint,
-                httpStatus: axios.isAxiosError(error) ? error.response?.status : undefined,
-                errorCode: axios.isAxiosError(error) ? errorCodeFrom(error.response?.data) : undefined,
-            });
-            throw error;
-        }
-        const data = response.data ?? {};
-        if (data.success === false) {
-            trace?.({ requestId, endpoint, httpStatus: response.status, errorCode: errorCodeFrom(data) });
-            throw new Error(`deep-search proxy error: ${data.error || "unknown"}`);
-        }
-        const primary = (data.retrievedMemorySnapshot?.primary ?? []);
-        const memories = primary.map((m) => ({
-            key: String(m.key ?? ""),
-            description: this.cleanMemoryDescription(String(m.description ?? "")),
-            time: m.time,
-            similarity: typeof m.similarity_score === "number" ? m.similarity_score : undefined,
-        }));
-        return { success: true, tuned: true, answer: String(data.answer || data.response || "").trim(), memories };
-    }
     async searchMemories(args, trace) {
         const parsed = searchMemoriesSchema.parse(args ?? {});
         const query = parsed.query?.trim();
@@ -805,18 +737,11 @@ class EchoMemApiClient {
             timeFrameDays: parsed.timeFrameDays,
             requestId: randomUUID(),
         };
-        if (!parsed.includeAnswer) {
-            return this.searchMemoriesRetrieved(query, searchOpts, enc, trace);
-        }
-        // Encrypted account: the server can't synthesize over plaintext it doesn't hold, so use the raw
-        // retriever (returns ciphertext) and decrypt locally — zero-knowledge preserved end-to-end.
-        if (enc.enabled) {
-            return await this.searchMemoriesRaw(query, searchOpts, enc, false, trace);
-        }
-        // A synthesized answer is metered through the legacy route. Do not fall
-        // back to raw retrieval after a ledger outage: that would return a result
-        // without a durable usage fact.
-        return this.searchMemoriesTuned(query, searchOpts.requestId, trace);
+        // MCP recall is retrieval-only. `includeAnswer` remains accepted by the
+        // parser for older clients, but it must never select an EchoMem/dg-web LLM
+        // path. The MCP host model receives the ranked memories and writes the
+        // final answer itself.
+        return this.searchMemoriesRetrieved(query, searchOpts, enc, trace);
     }
     /** Decrypt the model-visible fields on a `{ memories: [...] }` response locally. */
     async decryptResult(data, key) {
@@ -1221,19 +1146,42 @@ class EchoMemMCPServer {
                         content: [
                             {
                                 type: "text",
-                                text: error.expired
-                                    ? "🔒 EchoMem vault is locked — your encryption key expired. Run `echomem-mcp unlock` in a terminal, then retry."
-                                    : "🔒 EchoMem vault is locked. Run `echomem-mcp unlock` (or `echomem-mcp login`) to provide your encryption key, then retry.",
+                                text: [
+                                    "🔒 EchoMem vault is locked.",
+                                    "This encrypted account has no usable local decryption key. Once unlocked, this trusted device stays unlocked until you explicitly lock it or log out.",
+                                    "Action required from the user: open Terminal and run `echomem-mcp unlock` yourself. Do not have the agent run this interactive command and do not send your passphrase in chat.",
+                                    "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                    "After the success message, retry this EchoMem action in the current session — no editor restart is needed.",
+                                ].join("\n"),
                             },
                         ],
                     };
                 }
+                if (error instanceof EncryptionStatusUnavailableError) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: [
+                                    "⚠️ EchoMem could not verify whether this account's vault is encrypted.",
+                                    "No memory data was returned. Retry this action after the service recovers.",
+                                ].join("\n"),
+                            }],
+                        isError: true,
+                    };
+                }
                 if (error instanceof ZodError) {
                     throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.message}`);
                 }
                 if (error instanceof McpError) {
                     throw error;
                 }
+                const reconnectRequired = formatReconnectRequiredResult(error);
+                if (reconnectRequired) {
+                    return {
+                        content: [{ type: "text", text: reconnectRequired }],
+                        isError: true,
+                    };
+                }
                 const upgradeRequired = formatUpgradeRequiredResult(error);
                 if (upgradeRequired) {
                     return {
@@ -1346,20 +1294,6 @@ class EchoMemMCPServer {
                 .join("\n\n");
             return { content: [{ type: "text", text: `Retrieved ${memories.length} memories:\n\n${formattedResults}` }] };
         }
-        // Tuned two-phase path: synthesized brief + ranked source memories.
-        if (result?.tuned) {
-            const { answer, memories } = result;
-            if (!answer && !memories?.length) {
-                return { content: [{ type: "text", text: "No relevant memories found." }] };
-            }
-            const sources = (memories || [])
-                .map((m, idx) => `[${idx + 1}] ${m.key}${typeof m.similarity === "number" ? ` (sim ${m.similarity.toFixed(3)})` : ""}\n${m.description}`)
-                .join("\n\n");
-            const text = [answer && `Recall:\n${answer}`, sources && `---\nSource memories:\n\n${sources}`]
-                .filter(Boolean)
-                .join("\n\n");
-            return { content: [{ type: "text", text }] };
-        }
         // Fallback: untuned / time-range shape.
         const { success, memories, error } = result;
         if (!success)

package/dist/keystore.js

@@ -10,13 +10,13 @@
  * Storage posture: a 0600 file in the user's home — the same on-disk trust level as the extension's
  * `chrome.storage.local`. The OS keychain (spec §8's ideal) is a drop-in for `read`/`write` later;
  * it is deliberately deferred because `keytar` is a native build that complicates `npx` distribution.
- * The encryption key carries a TTL (mirrors the extension's 7-day expiry); on expiry the bridge
- * returns LOCKED and the user re-runs `unlock`.
+ * The MCP bridge uses an explicit trusted-device lifecycle: a verified encryption key remains
+ * available until the user runs `lock`/`logout` or removes the local credentials. Interactive app
+ * session TTLs are intentionally separate from this device-bound developer workflow.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const DEFAULT_KEY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** The bridge's local config dir (`~/.echomem` or `$ECHO_CONFIG_DIR`) — home for credentials + telemetry. */
 export function echoConfigDir() {
     return process.env.ECHO_CONFIG_DIR || path.join(os.homedir(), ".echomem");
@@ -55,29 +55,19 @@ export class KeyStore {
     getToken() {
         return process.env.ECHO_API_TOKEN || readFileCreds().token;
     }
-    /** Encryption key (base64), or undefined if absent/expired. Env wins (and never expires). */
+    /** Encryption key (base64), or undefined if absent. Env wins. */
     getKey() {
         if (process.env.ECHO_ENCRYPTION_KEY)
             return process.env.ECHO_ENCRYPTION_KEY;
-        const creds = readFileCreds();
-        if (!creds.key)
-            return undefined;
-        if (creds.keyExpiresAt && Date.now() > creds.keyExpiresAt)
-            return undefined;
-        return creds.key;
-    }
-    /** True when a key is present but past its TTL — used to tell "locked (expired)" from "never set". */
-    isKeyExpired() {
-        if (process.env.ECHO_ENCRYPTION_KEY)
-            return false;
-        const creds = readFileCreds();
-        return !!(creds.key && creds.keyExpiresAt && Date.now() > creds.keyExpiresAt);
+        return readFileCreds().key;
     }
     saveToken(token) {
         writeFileCreds({ ...readFileCreds(), token });
     }
-    saveKey(keyBase64, ttlMs = DEFAULT_KEY_TTL_MS) {
-        writeFileCreds({ ...readFileCreds(), key: keyBase64, keyExpiresAt: Date.now() + ttlMs });
+    saveKey(keyBase64) {
+        const creds = readFileCreds();
+        delete creds.keyExpiresAt;
+        writeFileCreds({ ...creds, key: keyBase64 });
     }
     clearKey() {
         const creds = readFileCreds();

package/dist/migrate.js

@@ -25,7 +25,8 @@ import readline from "node:readline";
 import axios from "axios";
 import { KeyStore, echoConfigDir } from "./keystore.js";
 import { fetchEncryptionConfig } from "./encryption.js";
-import { resolveClaudeProjectsDir, resolveCodexSessionsDir } from "./local-data-paths.js";
+import { discoverCodexSessionFiles } from "./codex-session-files.js";
+import { resolveClaudeProjectsDir } from "./local-data-paths.js";
 import { walk, eachLine } from "./report.js";
 const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const RATE_MAX = 28; // stay under the import-jobs /run limit of 30 / 60s
@@ -184,20 +185,29 @@ export function normalizeCwd(cwd) {
     const m = cwd.match(/worktrees\/[^/]+\/(.+)$/);
     return m ? m[1] : cwd;
 }
-/** Discover every local session, newest first (by first-turn timestamp). */
-export function discoverSessions() {
+function userCreatedCodexFiles(codexRoot) {
+    return discoverCodexSessionFiles({
+        ...(codexRoot
+            ? { roots: [{ kind: "active", path: codexRoot, priority: 0 }] }
+            : {}),
+        includeArchived: false,
+        userInitiatedOnly: true,
+    }).files.map((file) => file.path);
+}
+function userCreatedClaudeFiles(claudeRoot) {
+    return walk(claudeRoot, (candidate) => candidate.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows").filter(isUserCreatedClaudeSessionFile);
+}
+/** Discover every user-created local session, newest first (by first-turn timestamp). */
+export function discoverSessions(opts = {}) {
     const out = [];
-    const codexRoot = resolveCodexSessionsDir();
-    if (codexRoot) {
-        for (const f of walk(codexRoot, (p) => /rollout-.*\.jsonl$/.test(p), () => false)) {
-            const s = assembleCodex(f);
-            if (s)
-                out.push(s);
-        }
+    for (const f of userCreatedCodexFiles(opts.codexRoot)) {
+        const s = assembleCodex(f);
+        if (s)
+            out.push(s);
     }
-    const claudeRoot = resolveClaudeProjectsDir();
+    const claudeRoot = opts.claudeRoot ?? resolveClaudeProjectsDir();
     if (claudeRoot) {
-        for (const f of walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows")) {
+        for (const f of userCreatedClaudeFiles(claudeRoot)) {
             const s = assembleClaude(f);
             if (s)
                 out.push(s);
@@ -250,6 +260,20 @@ function hasClaudeText(content) {
         return false;
     return content.some((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0);
 }
+function isUserCreatedClaudeSessionFile(file) {
+    return initialJsonObjects(file).some((obj) => {
+        if (!isRecord(obj) || obj.type !== "user")
+            return false;
+        if (obj.userType !== "external" || obj.isSidechain !== false || obj.parentUuid !== null)
+            return false;
+        if (obj.isMeta === true || obj.isCompactSummary === true)
+            return false;
+        if (typeof obj.agentId === "string" && obj.agentId.trim())
+            return false;
+        const message = isRecord(obj.message) ? obj.message : {};
+        return hasClaudeText(message.content);
+    });
+}
 function fastSessionInfo(file, source) {
     let conversationKey = `${source === "codex" ? "codex" : "claude-code"}:${sha16(file)}`;
     let hasTextTurn = false;
@@ -287,21 +311,18 @@ function fastSessionInfo(file, source) {
 }
 function fastSessionEntries(opts = {}) {
     const out = [];
-    const codexRoot = opts.codexRoot ?? resolveCodexSessionsDir();
-    if (codexRoot) {
-        for (const filePath of walk(codexRoot, (p) => /rollout-.*\.jsonl$/.test(p), () => false)) {
-            const stat = statSafe(filePath);
-            const info = fastSessionInfo(filePath, "codex");
-            // Include if we found text OR a real session id (big sessions can have their first text turn beyond
-            // the 1MB probe window — gating only on text dropped them entirely; exact discovery refines later).
-            // We require a real key so the fast/exact conversationKey match (no sha16 fallback mismatch).
-            if (info.hasTextTurn || info.hasRealKey)
-                out.push({ filePath, source: "codex", conversationKey: info.conversationKey, size: stat.size, mtimeMs: stat.mtimeMs });
-        }
+    for (const filePath of userCreatedCodexFiles(opts.codexRoot)) {
+        const stat = statSafe(filePath);
+        const info = fastSessionInfo(filePath, "codex");
+        // Include if we found text OR a real session id (big sessions can have their first text turn beyond
+        // the 1MB probe window — gating only on text dropped them entirely; exact discovery refines later).
+        // We require a real key so the fast/exact conversationKey match (no sha16 fallback mismatch).
+        if (info.hasTextTurn || info.hasRealKey)
+            out.push({ filePath, source: "codex", conversationKey: info.conversationKey, size: stat.size, mtimeMs: stat.mtimeMs });
     }
     const claudeRoot = opts.claudeRoot ?? resolveClaudeProjectsDir();
     if (claudeRoot) {
-        for (const filePath of walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows")) {
+        for (const filePath of userCreatedClaudeFiles(claudeRoot)) {
             const stat = statSafe(filePath);
             const info = fastSessionInfo(filePath, "claude-code");
             // Same rule as codex: include on text OR a real session id so large sessions aren't undercounted,
@@ -504,6 +525,37 @@ export async function cancelQueuedImportSession(client, sessionId) {
         throw new Error("IMPORT_SESSION_ID_REQUIRED");
     await client.patch(`/api/extension/import-sessions/${encodeURIComponent(sessionId)}`, { action: "cancel" });
 }
+async function findRecoverableImportSession(client, sessions, bareConversationId, signal) {
+    const items = sessions.map((session) => ({
+        conversationId: bareConversationId(session),
+        platform: session.source,
+        sourceDate: session.firstTs,
+    }));
+    const response = await client.post("/api/extension/import-sessions/status", { items }, signal ? { signal } : undefined);
+    const data = response.data && typeof response.data === "object"
+        ? response.data
+        : {};
+    const required = new Set(sessions.map((session) => mapKey(session.source, bareConversationId(session))));
+    for (const candidate of data.recoverableSessions ?? []) {
+        const id = typeof candidate.id === "string" ? candidate.id : "";
+        const jobs = Array.isArray(candidate.jobs)
+            ? candidate.jobs
+                .filter((job) => typeof job.id === "string"
+                && typeof job.platform === "string"
+                && typeof job.conversation_id === "string")
+                .map((job) => ({
+                id: job.id,
+                platform: job.platform,
+                conversation_id: job.conversation_id,
+            }))
+            : [];
+        const covered = new Set(jobs.map((job) => mapKey(job.platform, job.conversation_id)));
+        if (id && required.size === jobs.length && [...required].every((key) => covered.has(key))) {
+            return { id, concurrency: MIGRATE_CONCURRENCY, jobs };
+        }
+    }
+    return null;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -761,7 +813,7 @@ function authedClient(token) {
     });
 }
 export function discoverMigratableSessions(opts = {}) {
-    let sessions = discoverSessions();
+    let sessions = discoverSessions(opts);
     const since = opts.since;
     if (since)
         sessions = sessions.filter((s) => (s.firstTs || "").slice(0, 10) >= since);
@@ -963,7 +1015,13 @@ export async function startMigration(opts) {
             throw codedError("FORBIDDEN_SCOPE");
         const data = responseData(e);
         const max = Number(data.maxConversations);
-        if (responseStatus(e) === 422 && data.error === "IMPORT_LIMIT_EXCEEDED" && max > 0) {
+        if (responseStatus(e) === 409 && data.error === "IMPORT_ALREADY_IN_PROGRESS") {
+            const recovered = await findRecoverableImportSession(client, toImport, bareId, opts.signal);
+            if (!recovered)
+                throw e;
+            session = recovered;
+        }
+        else if (responseStatus(e) === 422 && data.error === "IMPORT_LIMIT_EXCEEDED" && max > 0) {
             capped = max;
             toImport = opts.pending.slice(0, max);
             try {
@@ -1076,7 +1134,7 @@ async function runJobs(args) {
             const message = responseMessage(e);
             const durationMs = Date.now() - jobStartedAt;
             if (status === 422 && errCode === "ENCRYPTION_KEY_REQUIRED") {
-                stoppedReason = "key-expired"; // the vault key expired mid-run — signal workers to stop pulling
+                stoppedReason = "vault-locked"; // no usable local vault key — signal workers to stop pulling
                 done++;
                 recordMetric(buildMigrationMetric({
                     runId: args.runId, importSessionId: args.session.id, jobId: job.id, index: done, total,
@@ -1257,8 +1315,8 @@ export async function cmdMigrate(flags) {
         console.log(c.dim(`Import session ${h.sessionId} — ${h.jobCount} jobs queued (the web dashboard can watch this live).`));
         console.log(c.dim(`Metrics: ${h.metricsFile}`));
         const r = await h.done;
-        if (r.stoppedReason === "key-expired") {
-            console.error(c.yellow(`\n⚠ Vault locked mid-run. Run \`echomem-mcp unlock\` and re-run migrate to resume (${r.migrated} done so far).`));
+        if (r.stoppedReason === "vault-locked") {
+            console.error(c.yellow(`\n⚠ Vault locked mid-run. Open Terminal, run \`echomem-mcp unlock\`, and re-run migrate to resume (${r.migrated} done so far).`));
             process.exitCode = 1;
         }
         console.log("");
@@ -1275,10 +1333,7 @@ export async function cmdMigrate(flags) {
         if (code === "NOT_LOGGED_IN")
             console.error("Not logged in. Run `echomem-mcp login` first, then re-run migrate.");
         else if (code === "VAULT_LOCKED") {
-            const store = new KeyStore();
-            console.error(store.isKeyExpired()
-                ? "Vault key expired. Run `echomem-mcp unlock`, then re-run migrate."
-                : "This account is ENCRYPTED but the vault is locked. Run `echomem-mcp unlock`, then re-run migrate.");
+            console.error("This account is encrypted but the local vault is locked. Open Terminal, run `echomem-mcp unlock`, then re-run migrate.");
         }
         else if (code === "FORBIDDEN_SCOPE") {
             console.error("This device token cannot import history. Re-connect this device with `echomem-mcp login`.");