@echomem/mcp 1.2.0 → 1.3.1

package/dist/migrate.js

@@ -0,0 +1,945 @@
+/**
+ * `echomem-mcp migrate` — one-shot bulk back-fill of the user's EXISTING local coding-agent history
+ * (Codex + Claude Code) into their Echo cloud. The onboarding "see it instantly know my work" moment.
+ *
+ * Why this lives in the bridge (client-side): the session logs exist ONLY on the user's machine
+ * (~/.codex/sessions, ~/.claude/projects). The bridge discovers each session, assembles it into a
+ * text-turn-only `## ` transcript, and feeds it to the EXISTING durable import queue
+ * (the same one the extension uses): POST /api/extension/import-sessions creates one import_jobs row per session, then the bridge
+ * POSTs each transcript to /api/extension/import-jobs/{id}/run. The web dashboard polls
+ * GET /import-sessions/{id} for live progress — the bridge owns local-file access, the server owns the
+ * queue + status. (Headless CLI also works; it just shows progress in the terminal.)
+ *
+ * Idempotency: the queue dedups by (platform, conversationId) → source_hash (a repeat run hits a
+ * non-fatal DUPLICATE_SOURCE), and a local ledger (~/.echomem/migrate-ledger.json) skips done+unchanged
+ * files WITHOUT a round-trip. A local metrics log (~/.echomem/migrate-metrics.jsonl) records per-job
+ * timings and sizes, but never transcript text. Turns are joined with a SINGLE "\n" so the transcript
+ * stays byte-stable across runs (guarded by test/migrate.test.mjs). The run is sequential (throttled
+ * < 30/min to the /run limit) and stops cleanly if the encrypted vault's key expires mid-run.
+ * NOTE: client-pull — the queue advances only while the bridge runs; there is no server-side worker.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import readline from "node:readline";
+import axios from "axios";
+import { KeyStore, echoConfigDir } from "./keystore.js";
+import { fetchEncryptionConfig } from "./encryption.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
+const RATE_WINDOW_MS = 60_000;
+const APPROX_CHARS_PER_TOKEN = 4;
+const ACTIVE_SESSION_GRACE_MS = 5 * 60_000;
+// ---------------------------------------------------------------------------
+// Assemblers — reconstruct a `## `-turn transcript from a raw session log.
+// ---------------------------------------------------------------------------
+const sha16 = (s) => crypto.createHash("sha256").update(s).digest("hex").slice(0, 16);
+const turn = (role, ts, body) => `## ${role}${ts ? " — " + ts : ""}\n${body}`;
+const firstLine = (s) => (s.split("\n").find((l) => l.trim()) || "").trim().slice(0, 120);
+const truncate = (s, n) => (s.length > n ? s.slice(0, n) + "…" : s);
+/** Strip Codex's synthetic scaffolding blocks from a user message; "" if nothing real remains. */
+function cleanCodexUser(msg) {
+    let s = String(msg || "");
+    s = s.replace(/<(environment_context|user_instructions|permissions|app-context)>[\s\S]*?<\/\1>/g, "");
+    return s.trim();
+}
+/** Codex rollout-*.jsonl → one session. User/assistant text turns are sent; tool/process events stay local. */
+export function assembleCodex(file) {
+    let sessionId = null;
+    let cwd = null;
+    let firstTs = null;
+    let title = "";
+    const turns = [];
+    eachLine(file, (o) => {
+        if (o && o.type === "session_meta") {
+            sessionId = (o.payload && typeof o.payload.id === "string" && o.payload.id) || sessionId;
+            cwd = (o.payload && typeof o.payload.cwd === "string" && o.payload.cwd) || cwd;
+            return;
+        }
+        const p = o && typeof o.payload === "object" && o.payload ? o.payload : o;
+        if (!p || typeof p !== "object")
+            return;
+        const ts = typeof o.timestamp === "string" ? o.timestamp : "";
+        if (p.type === "user_message" && typeof p.message === "string") {
+            const body = cleanCodexUser(p.message);
+            if (!body)
+                return;
+            turns.push(turn("User", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+            if (!title)
+                title = firstLine(body);
+        }
+        else if (p.type === "agent_message" && typeof p.message === "string") {
+            const body = p.message.trim();
+            if (!body)
+                return;
+            turns.push(turn("Assistant", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+        }
+    });
+    if (!turns.length)
+        return null;
+    const stat = statSafe(file);
+    return {
+        filePath: file,
+        source: "codex",
+        conversationKey: `codex:${sessionId || sha16(file)}`,
+        cwd: normalizeCwd(cwd),
+        firstTs,
+        title: title || "Codex text turns",
+        rawData: turns.join("\n"),
+        turnCount: turns.length,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+}
+/** Claude Code <uuid>.jsonl → one session. User/assistant text turns are sent; tool calls/results/thinking stay local. */
+export function assembleClaude(file) {
+    let sessionId = null;
+    let cwd = null;
+    let firstTs = null;
+    let title = "";
+    const turns = [];
+    eachLine(file, (o) => {
+        if (!cwd && typeof o.cwd === "string")
+            cwd = o.cwd;
+        if (!sessionId && typeof o.sessionId === "string")
+            sessionId = o.sessionId;
+        const ts = typeof o.timestamp === "string" ? o.timestamp : "";
+        if (o.type === "user") {
+            const c = o.message && o.message.content;
+            let body = "";
+            if (typeof c === "string")
+                body = c.trim();
+            else if (Array.isArray(c)) {
+                // Keep only genuine user text blocks. tool_result carriers stay local.
+                body = c.filter((b) => b && b.type === "text" && b.text).map((b) => b.text).join("\n").trim();
+            }
+            if (!body)
+                return;
+            turns.push(turn("User", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+            if (!title)
+                title = firstLine(body);
+        }
+        else if (o.type === "assistant") {
+            const c = o.message && o.message.content;
+            let body = "";
+            if (Array.isArray(c)) {
+                const parts = [];
+                for (const b of c) {
+                    if (b && b.type === "text" && b.text)
+                        parts.push(b.text);
+                    // thinking and tool_use blocks are process/code noise, not assistant output.
+                }
+                body = parts.join("\n").trim();
+            }
+            else if (typeof c === "string") {
+                body = c.trim();
+            }
+            if (!body)
+                return; // thinking-only turn → no header
+            turns.push(turn("Assistant", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+        }
+        // tool_result carriers, queue-operation, attachment, ai-title, last-prompt, mode, summary, unknown → ignored
+    });
+    if (!turns.length)
+        return null;
+    const stat = statSafe(file);
+    return {
+        filePath: file,
+        source: "claude-code",
+        conversationKey: `claude:${sessionId || sha16(file)}`,
+        cwd: normalizeCwd(cwd),
+        firstTs,
+        title: title || "Claude text turns",
+        rawData: turns.join("\n"),
+        turnCount: turns.length,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+}
+function statSafe(file) {
+    try {
+        const s = fs.statSync(file);
+        return { size: s.size, mtimeMs: Math.round(s.mtimeMs) };
+    }
+    catch {
+        return { size: 0, mtimeMs: 0 };
+    }
+}
+/** Strip agent/git worktree wrappers so worktree sessions group under their real project root. */
+export function normalizeCwd(cwd) {
+    if (!cwd)
+        return null;
+    const m = cwd.match(/worktrees\/[^/]+\/(.+)$/);
+    return m ? m[1] : cwd;
+}
+/** Discover every local session, newest first (by first-turn timestamp). */
+export function discoverSessions() {
+    const out = [];
+    const codexRoot = path.join(os.homedir(), ".codex", "sessions");
+    for (const f of walk(codexRoot, (p) => /rollout-.*\.jsonl$/.test(p), () => false)) {
+        const s = assembleCodex(f);
+        if (s)
+            out.push(s);
+    }
+    const claudeRoot = path.join(os.homedir(), ".claude", "projects");
+    for (const f of walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows")) {
+        const s = assembleClaude(f);
+        if (s)
+            out.push(s);
+    }
+    out.sort((a, b) => String(b.firstTs || "").localeCompare(String(a.firstTs || "")));
+    return out;
+}
+function ledgerPath() {
+    return path.join(echoConfigDir(), "migrate-ledger.json");
+}
+function loadLedger() {
+    try {
+        return JSON.parse(fs.readFileSync(ledgerPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveLedger(l) {
+    try {
+        fs.mkdirSync(echoConfigDir(), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(ledgerPath(), JSON.stringify(l, null, 2));
+    }
+    catch {
+        /* best effort */
+    }
+}
+export function defaultMigrationMetricsPath() {
+    return path.join(echoConfigDir(), "migrate-metrics.jsonl");
+}
+function sourceMtimeIso(s) {
+    return s.mtimeMs ? new Date(s.mtimeMs).toISOString() : null;
+}
+function projectName(s) {
+    if (s.cwd)
+        return path.basename(s.cwd);
+    const parent = path.basename(path.dirname(s.filePath));
+    return parent || null;
+}
+export function buildMigrationMetric(args) {
+    const s = args.session;
+    const metric = {
+        schemaVersion: 1,
+        recordedAt: new Date().toISOString(),
+        runId: args.runId,
+        importSessionId: args.importSessionId,
+        jobId: args.jobId,
+        index: args.index,
+        total: args.total,
+        status: args.status,
+        apiBase: API_BASE,
+        source: s.source,
+        conversationKey: s.conversationKey,
+        conversationId: bareId(s),
+        firstTs: s.firstTs,
+        date: s.firstTs ? s.firstTs.slice(0, 10) : null,
+        cwd: s.cwd,
+        project: projectName(s),
+        filePath: s.filePath,
+        rawDataChars: s.rawData.length,
+        approxInputTokens: approxTokens(s.rawData.length),
+        textTurns: s.turnCount,
+        sourceFileBytes: s.size,
+        sourceMtimeMs: s.mtimeMs,
+        sourceMtimeIso: sourceMtimeIso(s),
+    };
+    if (args.durationMs !== undefined)
+        metric.durationMs = args.durationMs;
+    if (args.processingTimeMs !== undefined)
+        metric.processingTimeMs = args.processingTimeMs;
+    if (args.ttfmMs !== undefined)
+        metric.ttfmMs = args.ttfmMs;
+    if (args.memories !== undefined)
+        metric.memories = args.memories;
+    if (args.alreadyDone !== undefined)
+        metric.alreadyDone = args.alreadyDone;
+    if (args.duplicate !== undefined)
+        metric.duplicate = args.duplicate;
+    if (args.error !== undefined)
+        metric.error = truncate(args.error, 240);
+    if (args.selection)
+        metric.selection = args.selection;
+    return metric;
+}
+export function appendMigrationMetric(filePath, metric) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    fs.appendFileSync(filePath, JSON.stringify(metric) + "\n", { mode: 0o600 });
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+const color = (enabled) => {
+    const w = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+    return { bold: w("1"), dim: w("2"), red: w("31"), green: w("32"), cyan: w("36"), yellow: w("33") };
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const humanNum = (n) => Math.round(n).toLocaleString();
+function humanDuration(ms) {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return "0s";
+    const sec = Math.round(ms / 1000);
+    if (sec < 90)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    const rem = sec % 60;
+    if (min < 90)
+        return rem ? `${min}m ${rem}s` : `${min}m`;
+    const hours = Math.floor(min / 60);
+    const mins = min % 60;
+    return mins ? `${hours}h ${mins}m` : `${hours}h`;
+}
+export function formatEta(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return "complete";
+    if (seconds < 120)
+        return "under 2 minutes";
+    const minutes = Math.ceil(seconds / 60);
+    if (minutes < 60)
+        return `about ${minutes} minutes`;
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    return mins ? `about ${hours} hr ${mins} min` : `about ${hours} hr`;
+}
+function printMigrationEstimate(e, useJson) {
+    if (useJson) {
+        console.log(JSON.stringify(e, null, 2));
+        return;
+    }
+    console.log("");
+    console.log("Migration estimate (local metadata only; no transcripts uploaded)");
+    console.log(`  Sessions: ${humanNum(e.sessions)} total · ${humanNum(e.pending)} pending · ${humanNum(e.alreadyMigrated)} already processed`);
+    console.log(`  Sources: ${humanNum(e.pendingCodex)} Codex + ${humanNum(e.pendingClaudeCode)} Claude Code pending`);
+    console.log(`  Assembled transcript size: ${humanNum(e.chars.total)} chars ≈ ${humanNum(e.approxInputTokens.total)} input tokens`);
+    console.log(`  Size percentiles: p50 ${humanNum(e.chars.p50)} chars · p90 ${humanNum(e.chars.p90)} · p95 ${humanNum(e.chars.p95)} · max ${humanNum(e.chars.max)}`);
+    console.log(`  Turns: ${humanNum(e.turns.total)} total · p50 ${humanNum(e.turns.p50)} · p90 ${humanNum(e.turns.p90)} · max ${humanNum(e.turns.max)}`);
+    console.log("");
+    console.log("  Buckets:");
+    for (const b of e.buckets) {
+        console.log(`    ${b.label.padEnd(22)} ${String(b.count).padStart(4)} sessions · ${humanNum(b.chars).padStart(12)} chars · ≈${humanNum(b.approxInputTokens)} tokens`);
+    }
+    console.log("");
+    console.log(`  Queue floor from request throttle: ${humanDuration(e.queue.throttleFloorMinutes * 60_000)} (${e.queue.runRequestLimitPerMinute}/min, client-sequential).`);
+    console.log(`  Large-session risk: ${e.queue.largeSessionCount} sessions >120k chars; ${e.queue.hugeSessionCount} >${humanNum(e.queue.needsChunkingAboveChars)} chars should be chunked or sampled before full migration.`);
+    console.log("  For a measured ETA, run a small real sample: echomem-mcp migrate --limit 5 --yes");
+}
+function promptYesNo(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(!/^n/i.test(a.trim())); }));
+}
+function parsePositiveIntFlag(value, name) {
+    if (value == null)
+        return undefined;
+    if (value === true)
+        throw new Error(`${name} requires a number.`);
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`${name} must be a positive integer.`);
+    return n;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function responseStatus(e) {
+    const response = e.response;
+    return typeof response?.status === "number" ? response.status : undefined;
+}
+function responseData(e) {
+    const data = e.response?.data;
+    return isRecord(data) ? data : {};
+}
+function responseMessage(e) {
+    const data = responseData(e);
+    const message = data.message || data.error;
+    if (typeof message === "string")
+        return message;
+    return e instanceof Error ? e.message : String(e);
+}
+function codedError(code) {
+    const e = new Error(code);
+    e.code = code;
+    return e;
+}
+const bareId = (s) => s.conversationKey.slice(s.conversationKey.indexOf(":") + 1);
+const mapKey = (platform, conv) => `${platform}:${conv}`;
+const userTimeZone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+const approxTokens = (chars) => Math.ceil(chars / APPROX_CHARS_PER_TOKEN);
+const jobLockMessage = (message) => /already running|not retryable|job did not start/i.test(message);
+function sum(nums) {
+    return nums.reduce((n, x) => n + x, 0);
+}
+function percentile(nums, p) {
+    if (!nums.length)
+        return 0;
+    const s = [...nums].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor((s.length - 1) * p))] || 0;
+}
+export function estimateMigration(sessions, pending) {
+    const chars = pending.map((s) => s.rawData.length);
+    const turns = pending.map((s) => s.turnCount);
+    const pendingCodex = pending.filter((s) => s.source === "codex").length;
+    const bucketDefs = [
+        { label: "small <=10k chars", min: 0, max: 10_000 },
+        { label: "routine 10k-30k", min: 10_000, max: 30_000 },
+        { label: "medium 30k-60k", min: 30_000, max: 60_000 },
+        { label: "large 60k-120k", min: 60_000, max: 120_000 },
+        { label: "very large 120k-240k", min: 120_000, max: 240_000 },
+        { label: "huge >240k", min: 240_000, max: Number.POSITIVE_INFINITY },
+    ];
+    const buckets = bucketDefs.map((b) => {
+        const xs = pending.filter((s) => s.rawData.length > b.min && s.rawData.length <= b.max);
+        const bucketChars = sum(xs.map((s) => s.rawData.length));
+        return {
+            label: b.label,
+            count: xs.length,
+            chars: bucketChars,
+            approxInputTokens: approxTokens(bucketChars),
+        };
+    });
+    return {
+        sessions: sessions.length,
+        pending: pending.length,
+        alreadyMigrated: sessions.length - pending.length,
+        codex: sessions.filter((s) => s.source === "codex").length,
+        claudeCode: sessions.filter((s) => s.source === "claude-code").length,
+        pendingCodex,
+        pendingClaudeCode: pending.length - pendingCodex,
+        chars: {
+            total: sum(chars),
+            p50: percentile(chars, 0.5),
+            p75: percentile(chars, 0.75),
+            p90: percentile(chars, 0.9),
+            p95: percentile(chars, 0.95),
+            max: percentile(chars, 1),
+        },
+        approxInputTokens: {
+            total: approxTokens(sum(chars)),
+            p50: approxTokens(percentile(chars, 0.5)),
+            p90: approxTokens(percentile(chars, 0.9)),
+            p95: approxTokens(percentile(chars, 0.95)),
+            max: approxTokens(percentile(chars, 1)),
+        },
+        turns: {
+            total: sum(turns),
+            p50: percentile(turns, 0.5),
+            p90: percentile(turns, 0.9),
+            max: percentile(turns, 1),
+        },
+        buckets,
+        queue: {
+            mode: "client-sequential",
+            runRequestLimitPerMinute: RATE_MAX,
+            throttleFloorMinutes: pending.length ? Math.ceil(pending.length / RATE_MAX) : 0,
+            largeSessionCount: pending.filter((s) => s.rawData.length > 120_000).length,
+            hugeSessionCount: pending.filter((s) => s.rawData.length > 240_000).length,
+            needsChunkingAboveChars: 240_000,
+        },
+    };
+}
+export function estimateMigrationEta(pending, skippedActive = 0) {
+    const bucketDefs = [
+        { key: "small", label: "<=30k chars", min: 0, max: 30_000, secondsPerSession: 10 },
+        { key: "routine", label: "30k-120k", min: 30_000, max: 120_000, secondsPerSession: 16 },
+        { key: "large", label: "120k-350k", min: 120_000, max: 350_000, secondsPerSession: 16 },
+        { key: "veryLarge", label: "350k-1M", min: 350_000, max: 1_000_000, secondsPerSession: 40 },
+        { key: "huge", label: "1M-2M", min: 1_000_000, max: 2_000_000, secondsPerSession: 60 },
+        { key: "massive", label: ">2M", min: 2_000_000, max: Number.POSITIVE_INFINITY, secondsPerSession: 90 },
+    ];
+    const buckets = bucketDefs.map((b) => {
+        const xs = pending.filter((s) => s.rawData.length > b.min && s.rawData.length <= b.max);
+        const chars = sum(xs.map((s) => s.rawData.length));
+        return {
+            key: b.key,
+            label: b.label,
+            count: xs.length,
+            chars,
+            approxInputTokens: approxTokens(chars),
+            secondsPerSession: b.secondsPerSession,
+        };
+    });
+    const unbufferedSeconds = sum(buckets.map((b) => b.count * b.secondsPerSession));
+    const bufferedSeconds = Math.ceil(unbufferedSeconds * 1.25);
+    const throttleFloorSeconds = pending.length ? Math.ceil(pending.length / RATE_MAX) * 60 : 0;
+    const estimatedSeconds = Math.max(bufferedSeconds, throttleFloorSeconds);
+    const totalChars = sum(pending.map((s) => s.rawData.length));
+    return {
+        pending: pending.length,
+        skippedActive,
+        totalChars,
+        approxInputTokens: approxTokens(totalChars),
+        estimatedSeconds,
+        estimatedLabel: formatEta(estimatedSeconds),
+        throttleFloorSeconds,
+        buckets,
+    };
+}
+export function applyMigrationSelection(sessions, opts = {}) {
+    let out = [...sessions];
+    if (typeof opts.minChars === "number") {
+        out = out.filter((s) => s.rawData.length >= opts.minChars);
+    }
+    if (typeof opts.maxChars === "number") {
+        out = out.filter((s) => s.rawData.length <= opts.maxChars);
+    }
+    if (opts.largest) {
+        out.sort((a, b) => b.rawData.length - a.rawData.length || String(b.firstTs || "").localeCompare(String(a.firstTs || "")));
+    }
+    if (opts.limit && opts.limit > 0) {
+        out = out.slice(0, opts.limit);
+    }
+    return out;
+}
+export function dedupeSessionsByConversation(sessions) {
+    const byKey = new Map();
+    for (const s of sessions) {
+        const prev = byKey.get(s.conversationKey);
+        if (!prev ||
+            s.rawData.length > prev.rawData.length ||
+            (s.rawData.length === prev.rawData.length && s.mtimeMs > prev.mtimeMs)) {
+            byKey.set(s.conversationKey, s);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => String(b.firstTs || "").localeCompare(String(a.firstTs || "")));
+}
+export function isActiveMigrationSession(session, nowMs = Date.now()) {
+    return !!session.mtimeMs && nowMs - session.mtimeMs >= 0 && nowMs - session.mtimeMs < ACTIVE_SESSION_GRACE_MS;
+}
+function authedClient(token) {
+    return axios.create({
+        baseURL: API_BASE,
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    });
+}
+export function discoverMigratableSessions(opts = {}) {
+    let sessions = discoverSessions();
+    const since = opts.since;
+    if (since)
+        sessions = sessions.filter((s) => (s.firstTs || "").slice(0, 10) >= since);
+    sessions = dedupeSessionsByConversation(sessions);
+    sessions = applyMigrationSelection(sessions, { minChars: opts.minChars, maxChars: opts.maxChars, largest: opts.largest });
+    const selectableSessions = opts.includeActive ? sessions : sessions.filter((s) => !isActiveMigrationSession(s));
+    const skippedActive = sessions.length - selectableSessions.length;
+    const ledger = loadLedger();
+    const pendingAll = selectableSessions.filter((s) => {
+        const e = ledger[s.conversationKey];
+        return !e || e.size !== s.size;
+    });
+    const pending = opts.limit && opts.limit > 0 ? pendingAll.slice(0, opts.limit) : pendingAll;
+    const codexCount = sessions.filter((s) => s.source === "codex").length;
+    return {
+        sessions,
+        pending,
+        pendingTotal: pendingAll.length,
+        alreadyMigrated: selectableSessions.length - pendingAll.length,
+        skippedActive,
+        limited: pending.length < pendingAll.length,
+        codexCount,
+        claudeCount: sessions.length - codexCount,
+    };
+}
+export async function startMigration(opts) {
+    if (opts.pending.length === 0)
+        throw codedError("NO_PENDING_SESSIONS");
+    const store = new KeyStore();
+    const token = store.getToken();
+    if (!token)
+        throw codedError("NOT_LOGGED_IN");
+    const client = authedClient(token);
+    let encKey;
+    try {
+        const cfg = await fetchEncryptionConfig(client);
+        if (cfg.enabled) {
+            encKey = store.getKey();
+            if (!encKey)
+                throw codedError("VAULT_LOCKED");
+        }
+    }
+    catch (e) {
+        if (e?.code === "VAULT_LOCKED")
+            throw e;
+        /* config fetch failed → proceed as unencrypted; server enforces if actually encrypted */
+    }
+    const tz = userTimeZone();
+    let toImport = opts.pending;
+    let capped;
+    let session;
+    try {
+        session = await createImportSession(client, toImport, bareId, tz, opts.signal);
+    }
+    catch (e) {
+        if (responseStatus(e) === 403)
+            throw codedError("FORBIDDEN_SCOPE");
+        const data = responseData(e);
+        const max = Number(data.maxConversations);
+        if (responseStatus(e) === 422 && data.error === "IMPORT_LIMIT_EXCEEDED" && max > 0) {
+            capped = max;
+            toImport = opts.pending.slice(0, max);
+            try {
+                session = await createImportSession(client, toImport, bareId, tz, opts.signal);
+            }
+            catch (retryError) {
+                if (responseStatus(retryError) === 403)
+                    throw codedError("FORBIDDEN_SCOPE");
+                throw retryError;
+            }
+        }
+        else {
+            throw e;
+        }
+    }
+    const byConv = new Map(toImport.map((s) => [mapKey(s.source, bareId(s)), s]));
+    const runId = crypto.randomUUID();
+    const metricsFile = opts.metricsFile || defaultMigrationMetricsPath();
+    const done = runJobs({
+        client,
+        session,
+        byConv,
+        userTz: tz,
+        encKey,
+        onProgress: opts.onProgress,
+        runId,
+        metricsFile,
+        selection: opts.selection,
+    });
+    return { sessionId: session.id, runId, jobCount: session.jobs.length, metricsFile, ...(capped ? { capped } : {}), done };
+}
+async function runJobs(args) {
+    const ledger = loadLedger();
+    const reqTimes = [];
+    const throttle = async () => {
+        for (;;) {
+            const now = Date.now();
+            while (reqTimes.length && now - reqTimes[0] > RATE_WINDOW_MS)
+                reqTimes.shift();
+            if (reqTimes.length < RATE_MAX) {
+                reqTimes.push(Date.now());
+                return;
+            }
+            await sleep(RATE_WINDOW_MS - (now - reqTimes[0]) + 100);
+        }
+    };
+    let migrated = 0, extracted = 0, failed = 0, i = 0;
+    const recordMetric = (metric) => {
+        try {
+            appendMigrationMetric(args.metricsFile, metric);
+        }
+        catch {
+            /* best effort: metrics must never block a user migration */
+        }
+    };
+    try {
+        for (const job of args.session.jobs) {
+            const s = args.byConv.get(mapKey(job.platform, job.conversation_id));
+            if (!s)
+                continue;
+            i++;
+            const jobStartedAt = Date.now();
+            try {
+                await throttle();
+                const r = await runImportJob(args.client, job.id, s, args.userTz, args.encKey);
+                extracted += r.memories;
+                migrated++;
+                ledger[s.conversationKey] = { size: s.size, mtimeMs: s.mtimeMs, status: "done", memories: r.memories };
+                saveLedger(ledger);
+                recordMetric(buildMigrationMetric({
+                    runId: args.runId,
+                    importSessionId: args.session.id,
+                    jobId: job.id,
+                    index: i,
+                    total: args.session.jobs.length,
+                    session: s,
+                    status: "completed",
+                    memories: r.memories,
+                    durationMs: r.durationMs,
+                    processingTimeMs: r.processingTimeMs,
+                    ttfmMs: r.ttfmMs,
+                    alreadyDone: r.alreadyDone,
+                    duplicate: r.duplicate,
+                    selection: args.selection,
+                }));
+                args.onProgress?.({
+                    index: i,
+                    total: args.session.jobs.length,
+                    importSessionId: args.session.id,
+                    jobId: job.id,
+                    session: s,
+                    memories: r.memories,
+                    durationMs: r.durationMs,
+                    processingTimeMs: r.processingTimeMs,
+                    ttfmMs: r.ttfmMs,
+                    alreadyDone: r.alreadyDone,
+                    duplicate: r.duplicate,
+                });
+            }
+            catch (e) {
+                const status = responseStatus(e);
+                const errCode = responseData(e).error;
+                const message = responseMessage(e);
+                if (status === 422 && errCode === "ENCRYPTION_KEY_REQUIRED") {
+                    const durationMs = Date.now() - jobStartedAt;
+                    recordMetric(buildMigrationMetric({
+                        runId: args.runId,
+                        importSessionId: args.session.id,
+                        jobId: job.id,
+                        index: i,
+                        total: args.session.jobs.length,
+                        session: s,
+                        status: "stopped",
+                        durationMs,
+                        error: message,
+                        selection: args.selection,
+                    }));
+                    args.onProgress?.({ index: i, total: args.session.jobs.length, importSessionId: args.session.id, jobId: job.id, session: s, error: message, durationMs });
+                    return { migrated, extracted, failed, stoppedReason: "key-expired" };
+                }
+                failed++;
+                const durationMs = Date.now() - jobStartedAt;
+                recordMetric(buildMigrationMetric({
+                    runId: args.runId,
+                    importSessionId: args.session.id,
+                    jobId: job.id,
+                    index: i,
+                    total: args.session.jobs.length,
+                    session: s,
+                    status: "failed",
+                    durationMs,
+                    error: message,
+                    selection: args.selection,
+                }));
+                args.onProgress?.({ index: i, total: args.session.jobs.length, importSessionId: args.session.id, jobId: job.id, session: s, error: message, durationMs });
+            }
+        }
+    }
+    catch {
+        failed++;
+    }
+    return { migrated, extracted, failed };
+}
+export async function cmdMigrate(flags) {
+    const c = color(process.stdout.isTTY === true && !process.env.NO_COLOR && flags["no-color"] !== true);
+    // Discover + filter (pure local — discovery and --dry-run need no login).
+    const since = typeof flags.since === "string" ? flags.since : undefined;
+    let limit;
+    let minChars;
+    let maxChars;
+    try {
+        limit = parsePositiveIntFlag(flags.limit, "--limit");
+        minChars = parsePositiveIntFlag(flags["min-chars"], "--min-chars");
+        maxChars = parsePositiveIntFlag(flags["max-chars"], "--max-chars");
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exitCode = 1;
+        return;
+    }
+    if (minChars && maxChars && minChars > maxChars) {
+        console.error("--min-chars cannot be greater than --max-chars.");
+        process.exitCode = 1;
+        return;
+    }
+    const largest = flags.largest === true;
+    const includeActive = flags["include-active"] === true;
+    const selection = { since, limit, minChars, maxChars, largest, includeActive };
+    const metricsFile = typeof flags["metrics-file"] === "string" ? flags["metrics-file"] : defaultMigrationMetricsPath();
+    const { sessions, pending, pendingTotal, alreadyMigrated, skippedActive, limited, codexCount, claudeCount } = discoverMigratableSessions(selection);
+    const estimateSessions = includeActive ? sessions : sessions.filter((s) => !isActiveMigrationSession(s));
+    if (!sessions.length) {
+        console.log("No local Codex/Claude Code sessions found to migrate.");
+        return;
+    }
+    if (flags.estimate === true && flags.json === true) {
+        printMigrationEstimate(estimateMigration(limit ? pending : estimateSessions, pending), true);
+        return;
+    }
+    console.log("");
+    console.log(c.bold(c.cyan("EchoMem migration")) + c.dim(`  (${API_BASE})`));
+    const pendingText = limited
+        ? `${c.bold(String(pending.length))} of ${c.bold(String(pendingTotal))} new/changed selected`
+        : `${c.bold(String(pending.length))} new/changed to import`;
+    console.log(`Found ${c.bold(String(sessions.length))} sessions (${codexCount} Codex + ${claudeCount} Claude Code) · ${pendingText}` +
+        (alreadyMigrated ? c.dim(`, ${alreadyMigrated} already migrated`) : "") +
+        (skippedActive ? c.dim(`, ${skippedActive} active skipped`) : ""));
+    const filters = [
+        minChars ? `min ${humanNum(minChars)} chars` : "",
+        maxChars ? `max ${humanNum(maxChars)} chars` : "",
+        largest ? "largest first" : "",
+        includeActive ? "include active" : "",
+        limit ? `limit ${humanNum(limit)}` : "",
+    ].filter(Boolean).join(" · ");
+    if (filters)
+        console.log(c.dim(`Selection: ${filters}`));
+    if (flags.estimate === true) {
+        printMigrationEstimate(estimateMigration(limit ? pending : estimateSessions, pending), false);
+        return;
+    }
+    if (flags["dry-run"] === true) {
+        console.log(c.dim("\n--dry-run: discovered + assembled only, nothing sent.\n"));
+        for (const s of pending.slice(0, 50)) {
+            console.log(`  ${s.source === "codex" ? "codex " : "claude"} ${(s.firstTs || "").slice(0, 10)}  ${humanNum(s.rawData.length)} chars  ${s.turnCount} text turns`);
+        }
+        if (pending.length > 50)
+            console.log(c.dim(`  … and ${pending.length - 50} more`));
+        return;
+    }
+    if (!pending.length) {
+        console.log(c.green("\n✓ Everything is already migrated — nothing to do.\n"));
+        return;
+    }
+    // Consent: one keypress (skipped with --yes or when non-interactive).
+    if (flags.yes !== true && process.stdin.isTTY) {
+        const ok = await promptYesNo(`Import ${pending.length} session(s) into your EchoMem memory? [Y/n] `);
+        if (!ok) {
+            console.log("Aborted. Nothing was sent.");
+            return;
+        }
+    }
+    try {
+        const jobDurations = [];
+        const h = await startMigration({
+            pending,
+            metricsFile,
+            selection,
+            onProgress: (ev) => {
+                const tag = `${c.dim(`[${ev.index}/${ev.total}]`)} ${ev.session.source === "codex" ? "codex " : "claude"} ${(ev.session.firstTs || "").slice(0, 10)}`;
+                if (ev.error) {
+                    console.log(`${tag}  ${c.red("✗ failed")} ${c.dim(truncate(ev.error, 60))}` + (ev.durationMs ? c.dim(`  ${humanDuration(ev.durationMs)}`) : ""));
+                    return;
+                }
+                if (ev.durationMs)
+                    jobDurations.push(ev.durationMs);
+                const eta = jobDurations.length > 0
+                    ? humanDuration(percentile(jobDurations, 0.5) * Math.max(0, ev.total - ev.index))
+                    : null;
+                const memories = ev.memories ?? 0;
+                const note = ev.alreadyDone
+                    ? c.dim("already completed")
+                    : memories === 0
+                        ? c.dim("0 memories")
+                        : c.green(`+${memories} ${memories === 1 ? "memory" : "memories"}`);
+                const timing = ev.durationMs
+                    ? c.dim(`  ${humanDuration(ev.durationMs)}${ev.ttfmMs ? ` (first memory ${humanDuration(ev.ttfmMs)})` : ""}${eta ? ` · ETA ${eta}` : ""}`)
+                    : "";
+                console.log(`${tag}  ${note}  ${c.dim(`${humanNum(ev.session.rawData.length)} chars · ${ev.session.turnCount} turns`)}${timing}`);
+            },
+        });
+        if (h.capped)
+            console.log(c.yellow(`Your plan imports up to ${h.capped} at a time — importing the newest ${h.capped}; re-run migrate for older sessions.`));
+        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).`));
+            process.exitCode = 1;
+        }
+        console.log("");
+        console.log(c.bold("Done.") + `  ${c.green(String(r.migrated) + " imported")} · ${c.bold(String(r.extracted))} memories` +
+            (r.failed ? ` · ${c.red(String(r.failed) + " failed")}` : "") + ".");
+        if (r.extracted > 0) {
+            console.log(c.dim("Now ask your agent about a past project — it can recall it from memory.\n"));
+        }
+        if (r.failed)
+            process.exitCode = 1;
+    }
+    catch (e) {
+        const code = e?.code;
+        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.");
+        }
+        else if (code === "FORBIDDEN_SCOPE") {
+            console.error("This device token cannot import history. Re-connect this device with `echomem-mcp setup`.");
+        }
+        else {
+            console.error(c.red(`Could not start the import: ${responseMessage(e)}`));
+        }
+        process.exitCode = 1;
+    }
+}
+/** Create an import session (lightweight descriptors only — NO transcript). Returns the session id + jobs. */
+async function createImportSession(client, sessions, bareId, userTz, signal) {
+    const items = sessions.map((s) => ({
+        conversationId: bareId(s),
+        platform: s.source, // free-text label; also half of the (session, platform, conversation) key
+        title: s.title,
+        sourceDate: s.firstTs,
+        userTz,
+    }));
+    const res = await client.post("/api/extension/import-sessions", { items }, signal ? { signal } : undefined);
+    const data = res.data || {};
+    return { id: String(data.session?.id || ""), jobs: Array.isArray(data.jobs) ? data.jobs : [] };
+}
+/** Run one queued job: stream its transcript to the server, which extracts it. Retries transient locks/rate limits. */
+async function runImportJob(client, jobId, s, userTz, encKey) {
+    const startedAt = Date.now();
+    const body = {
+        rawData: s.rawData,
+        source: s.source, // NOT containing "mcp" (avoids the route's MCP title truncation)
+        title: s.title,
+        sourceDate: s.firstTs, // back-fill memories on the session's real date
+        userTz,
+        sessionType: "coding", // routes to the coding-checkpoint extraction prompt (ignored if unsupported)
+    };
+    const cfg = encKey ? { headers: { "X-Encryption-Key": encKey } } : undefined;
+    for (let attempt = 0;; attempt++) {
+        try {
+            const res = await client.post(`/api/extension/import-jobs/${jobId}/run`, body, cfg);
+            const data = res.data || {};
+            if (data.claimed === false) {
+                // Already completed on a prior run → idempotent, not an error; otherwise it didn't start.
+                if (data.job?.status === "completed") {
+                    return {
+                        memories: Number(data.job?.saved_memory_count) || 0,
+                        alreadyDone: true,
+                        duplicate: false,
+                        durationMs: Date.now() - startedAt,
+                    };
+                }
+                throw new Error(data.message || "job did not start");
+            }
+            const result = data.result || {};
+            return {
+                memories: Number(result.memoriesExtracted) || 0,
+                alreadyDone: false,
+                duplicate: !!result.duplicate,
+                durationMs: Date.now() - startedAt,
+                processingTimeMs: typeof result.processingTimeMs === "number" ? result.processingTimeMs : undefined,
+                ttfmMs: typeof result.ttfmMs === "number" ? result.ttfmMs : undefined,
+            };
+        }
+        catch (e) {
+            const status = e?.response?.status;
+            const message = e instanceof Error ? e.message : responseMessage(e);
+            if (status === 422 && e?.response?.data?.error === "ENCRYPTION_KEY_REQUIRED")
+                throw e; // not retryable
+            const lockConflict = status === 409 || jobLockMessage(message);
+            const retryable = lockConflict || status === 429 || (status >= 500 && status < 600) || e?.code === "ECONNABORTED" || !status;
+            const maxAttempts = lockConflict ? 5 : 2;
+            if (!retryable || attempt >= maxAttempts)
+                throw e;
+            const retryAfter = Number(e?.response?.headers?.["retry-after"]) || Number(e?.response?.data?.retryAfterSeconds);
+            const backoffSeconds = lockConflict
+                ? Math.min(30, 5 * (attempt + 1))
+                : Math.pow(2, attempt) * 2;
+            await sleep((status === 429 && retryAfter > 0 ? retryAfter : backoffSeconds) * 1000);
+        }
+    }
+}