@echomem/mcp 1.4.19 → 1.4.21

package/dist/setup.js

@@ -2,15 +2,15 @@
  * `echomem-mcp init | setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
  *
  * Design goals from the spec:
- *   - One command → one browser approval → one reload.
+ *   - One command → one local browser setup → one reload.
  *   - Both secrets (API token + encryption key) ride a single browser flow and land in the local
  *     keystore — never in the client's MCP config, never in the agent's chat context.
  *   - Re-unlock after the key's TTL is one step, not a re-setup.
  *
- * The browser flow posts `{ token, key? }` to a localhost callback this process opens. The
- * "connect device" web page that drives it is the one piece that lives in the web app (not here);
- * until it ships, the same flow is fully usable via the manual flags (`--token`, `--key`,
- * `--passphrase`), which is also the documented headless/SSH path (spec §8).
+ * The browser flow stays on a localhost setup page. That local page collects email OTP consent and
+ * an encryption passphrase, while this process asks the hosted API to send/verify OTP and mint a
+ * device token. Secrets land in the local keystore — never in the client's MCP config, never in
+ * the agent's chat context.
  */
 import http from "node:http";
 import { randomUUID } from "node:crypto";
@@ -23,7 +23,7 @@ import readline from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
-import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.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 { syncCodexUsage } from "./codex-sync.js";
@@ -33,15 +33,111 @@ import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
 import { installHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
-// The hosted connect-device page is now only the account-auth/token courier. The dashboard itself is
-// served by this localhost bridge, where local logs and processed/unprocessed counts never leave the
-// device unless the user explicitly starts migration. Override the hosted auth origin with ECHO_WEB_URL.
-const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
+// The setup dashboard, account login, and encryption passphrase entry are all served by this
+// localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const PRICING_URL = (process.env.ECHO_PRICING_URL || "https://echoknows.com/pricing").replace(/\/$/, "");
+const CODEX_SKILL_NAMES = [
+    "echomem-search",
+    "echomem-save",
+    "echomem-forget",
+    "echomem-login",
+];
 function home(...p) {
     return path.join(os.homedir(), ...p);
 }
+function codexHome() {
+    const configured = process.env.CODEX_HOME?.trim();
+    if (!configured)
+        return home(".codex");
+    if (configured === "~")
+        return os.homedir();
+    if (configured.startsWith(`~${path.sep}`))
+        return path.join(os.homedir(), configured.slice(2));
+    return path.resolve(configured);
+}
+function filesEqual(left, right) {
+    try {
+        return fs.readFileSync(left).equals(fs.readFileSync(right));
+    }
+    catch {
+        return false;
+    }
+}
+function packagedSkillMatches(source, destination) {
+    return filesEqual(path.join(source, "SKILL.md"), path.join(destination, "SKILL.md"))
+        && filesEqual(path.join(source, "agents", "openai.yaml"), path.join(destination, "agents", "openai.yaml"));
+}
+function readSkillMetadata(skillFile) {
+    try {
+        const content = fs.readFileSync(skillFile, "utf8");
+        const frontmatter = content.match(/^---\s*\n([\s\S]*?)\n---/);
+        if (!frontmatter)
+            return null;
+        const name = frontmatter[1].match(/^name:\s*(.+)$/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "") ?? "";
+        const description = frontmatter[1].match(/^description:\s*(.+)$/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "") ?? "";
+        return name ? { name, description } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function detectCompetingMemorySkills(skillsRoot) {
+    let entries = [];
+    try {
+        entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const echoNames = new Set(CODEX_SKILL_NAMES);
+    return entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+        .map((entry) => readSkillMetadata(path.join(skillsRoot, entry.name, "SKILL.md")))
+        .filter((metadata) => Boolean(metadata))
+        .filter(({ name, description }) => {
+        if (echoNames.has(name))
+            return false;
+        const text = `${name} ${description}`;
+        return /\b(memory|memories|remember|recall)\b/i.test(text)
+            && /\b(search|save|forget|delete|login|connect|recall|remember)\b/i.test(text);
+    })
+        .map(({ name }) => name)
+        .sort();
+}
+/** Install the EchoMem-owned Codex skills bundled with this npm package. Other providers are never modified. */
+export function installCodexSkills(targetCodexHome = codexHome(), templateRoot = fileURLToPath(new URL("../templates/codex-skills/", import.meta.url))) {
+    const skillsRoot = path.join(targetCodexHome, "skills");
+    const report = {
+        skillsRoot,
+        installed: [],
+        updated: [],
+        unchanged: [],
+        competingMemorySkills: [],
+    };
+    fs.mkdirSync(skillsRoot, { recursive: true });
+    for (const skillName of CODEX_SKILL_NAMES) {
+        const source = path.join(templateRoot, skillName);
+        const destination = path.join(skillsRoot, skillName);
+        const sourceSkillFile = path.join(source, "SKILL.md");
+        if (!fs.existsSync(sourceSkillFile) || !fs.statSync(sourceSkillFile).isFile()) {
+            throw new Error(`EchoMem package is missing the ${skillName} skill template.`);
+        }
+        if (!fs.existsSync(destination)) {
+            fs.cpSync(source, destination, { recursive: true, force: true });
+            report.installed.push(skillName);
+        }
+        else if (packagedSkillMatches(source, destination)) {
+            report.unchanged.push(skillName);
+        }
+        else {
+            fs.cpSync(source, destination, { recursive: true, force: true });
+            report.updated.push(skillName);
+        }
+    }
+    report.competingMemorySkills = detectCompetingMemorySkills(skillsRoot);
+    return report;
+}
 /** Map a source entry to its compiled sibling without ever guessing outside this package. */
 export function compiledDistPathForSource(entry) {
     if (!entry.endsWith(".ts") || !path.isAbsolute(entry))
@@ -96,7 +192,7 @@ export function knownClients() {
         { id: "windsurf", label: "Windsurf", kind: "json", configPath: home(".codeium", "windsurf", "mcp_config.json") },
         { id: "claude-desktop", label: "Claude Desktop", kind: "json", configPath: path.join(appSupport, "Claude", "claude_desktop_config.json") },
         { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json echomem '<entry>'  (or add to .mcp.json)" },
-        { id: "codex", label: "Codex", kind: "command", detectDir: home(".codex"), configPath: home(".codex", "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
+        { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
 /** A client is "present" if its config dir already exists (JSON) — a cheap heuristic for detection. */
@@ -222,6 +318,7 @@ function echomemGuidanceBlock() {
         AGENTS_MD_BEGIN,
         "## Memory (EchoMem)",
         "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`.",
         "- 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.",
@@ -1092,9 +1189,9 @@ function publicRunningForensicProgress(value) {
     };
 }
 /**
- * Start the persistent localhost bridge used by the connect-device page. It accepts the token,
- * serves local Wrapped stats, and holds the /migrate response until cmdLogin has created a cloud
- * import session.
+ * Start the persistent localhost bridge used by the setup page. It sends/verifies OTP through the
+ * hosted API, accepts the local passphrase, serves local Wrapped stats, and holds the /migrate
+ * response until cmdLogin has created a cloud import session.
  */
 export function startCallbackServer(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 15 * 60_000;
@@ -1112,6 +1209,7 @@ export function startCallbackServer(opts = {}) {
         let authUrl = "";
         let switchAccountUrl = "";
         let connected = false;
+        let pendingLocalAuth = null;
         let reportConsentGranted = opts.requireReportConsent !== true;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
         let migrateStarted = false;
@@ -1128,6 +1226,26 @@ export function startCallbackServer(opts = {}) {
         const checkNonce = (nonce) => !expectedNonce || nonce === expectedNonce;
         const text = (res, status, body = "") => res.writeHead(status, { "Content-Type": "text/plain" }).end(body);
         const json = (res, status, body) => res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+        const revokeDeviceToken = async (token) => {
+            try {
+                await authedAxios(token).post("/api/extension/mcp/local-auth/revoke-device", {}, { timeout: 10_000 });
+                return true;
+            }
+            catch (error) {
+                console.error(`Could not revoke incomplete local login: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            }
+        };
+        const revokePendingLocalAuth = async () => {
+            const pending = pendingLocalAuth;
+            pendingLocalAuth = null;
+            if (!pending)
+                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 close = () => {
             if (timer)
                 clearTimeout(timer);
@@ -1135,6 +1253,7 @@ export function startCallbackServer(opts = {}) {
             if (closed)
                 return;
             closed = true;
+            void revokePendingLocalAuth();
             server.close();
             for (const socket of sockets)
                 socket.destroy();
@@ -1146,7 +1265,7 @@ export function startCallbackServer(opts = {}) {
             const waitMs = onToken.settled() ? dashboardTimeoutMs : timeoutMs;
             timer = setTimeout(() => {
                 if (!onToken.settled()) {
-                    onToken.reject(new Error(`browser approval did not finish in ${approvalTimeoutLabel}`));
+                    onToken.reject(new Error(`local setup did not finish in ${approvalTimeoutLabel}`));
                 }
                 else if (!decision.settled()) {
                     decision.resolve("timeout");
@@ -1166,7 +1285,7 @@ export function startCallbackServer(opts = {}) {
             }
             if (!token)
                 return void text(res, 400, "missing token");
-            console.log(`[${new Date().toISOString()}] Browser approval callback received.`);
+            console.log(`[${new Date().toISOString()}] Device token callback received.`);
             const firstToken = !onToken.settled();
             connected = true;
             const setupPath = `/setup?nonce=${encodeURIComponent(nonce || "")}&connected=1`;
@@ -1182,12 +1301,172 @@ export function startCallbackServer(opts = {}) {
             }
             armTimeout();
         };
+        const rejectIfLocalAuthBlocked = (res, nonce) => {
+            if (!checkNonce(nonce)) {
+                text(res, 403, "bad nonce");
+                return true;
+            }
+            if (opts.requireReportConsent === true && !reportConsentGranted) {
+                json(res, 403, {
+                    error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                    message: "Allow local history access in the setup page before connecting EchoMem.",
+                });
+                return true;
+            }
+            return false;
+        };
+        const resolveLocalToken = (token, key) => {
+            const firstToken = !onToken.settled();
+            connected = true;
+            pendingLocalAuth = null;
+            const callbackToken = { token, key };
+            if (firstToken) {
+                onToken.resolve(callbackToken);
+            }
+            else if (tokenRefreshHandler) {
+                Promise.resolve(tokenRefreshHandler(callbackToken)).catch((e) => {
+                    console.error(`Could not refresh local login: ${e instanceof Error ? e.message : String(e)}`);
+                });
+            }
+            armTimeout();
+        };
+        const handleLocalSendOtp = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const email = normalizeEmail(body.email);
+            if (!validEmail(email))
+                return void json(res, 400, { ok: false, error: "Invalid email address" });
+            if (!acceptedLocalTerms(body)) {
+                return void json(res, 400, {
+                    ok: false,
+                    error: "Confirm your age and accept Echo's terms before continuing.",
+                });
+            }
+            try {
+                const response = await apiAxios().post("/api/extension/mcp/local-auth/send-otp", {
+                    email,
+                    acceptedTerms: true,
+                    ageConfirmed: true,
+                }, { timeout: 10_000 });
+                json(res, 200, { ok: true, email: asString(response.data?.email) || email });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to send verification code");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
+        const handleLocalVerifyOtp = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const email = normalizeEmail(body.email);
+            const otp = asString(body.otp)?.trim() || "";
+            if (!validEmail(email))
+                return void json(res, 400, { ok: false, error: "Invalid email address" });
+            if (!/^\d{6}$/.test(otp)) {
+                return void json(res, 400, { ok: false, error: "Enter the 6-digit verification code." });
+            }
+            if (!acceptedLocalTerms(body)) {
+                return void json(res, 400, {
+                    ok: false,
+                    error: "Confirm your age and accept Echo's terms before continuing.",
+                });
+            }
+            try {
+                const response = await apiAxios().post("/api/extension/mcp/local-auth/verify-otp", {
+                    email,
+                    otp,
+                    acceptedTerms: true,
+                    ageConfirmed: true,
+                }, { timeout: 15_000 });
+                const token = asString(response.data?.api_key);
+                const userId = asString(response.data?.user_id);
+                if (!token || !userId) {
+                    return void json(res, 502, { ok: false, error: "The EchoMem API did not return a device token." });
+                }
+                let config;
+                try {
+                    config = await fetchEncryptionConfig(authedAxios(token));
+                }
+                catch (error) {
+                    await revokeDeviceToken(token);
+                    throw error;
+                }
+                await revokePendingLocalAuth();
+                pendingLocalAuth = {
+                    token,
+                    userId,
+                    email: asString(response.data?.email) || email,
+                    mode: config.enabled ? "unlock" : "setup",
+                    config: config.enabled ? config : undefined,
+                    expiresAtMs: Date.now() + 10 * 60_000,
+                };
+                json(res, 200, {
+                    ok: true,
+                    stage: "passphrase",
+                    mode: pendingLocalAuth.mode,
+                    email: pendingLocalAuth.email,
+                });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to verify code");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
+        const handleLocalPassphrase = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const passphrase = typeof body.passphrase === "string" ? body.passphrase : "";
+            if (passphrase.length < 4) {
+                return void json(res, 400, { ok: false, error: "Enter an encryption passphrase with at least 4 characters." });
+            }
+            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,
+                });
+            }
+            try {
+                if (pendingLocalAuth.mode === "unlock") {
+                    const key = pendingLocalAuth.config
+                        ? await deriveAndVerifyKey(passphrase, pendingLocalAuth.config)
+                        : null;
+                    if (!key)
+                        return void json(res, 400, { ok: false, error: "Incorrect encryption passphrase." });
+                    await completeDeviceLogin(pendingLocalAuth.token);
+                    resolveLocalToken(pendingLocalAuth.token, key);
+                    return void json(res, 200, { ok: true, connected: true });
+                }
+                const setup = await setupNewEncryptionKey(passphrase);
+                await authedAxios(pendingLocalAuth.token).post("/api/extension/account/encryption", {
+                    salt: setup.saltBase64,
+                    verification: setup.verification,
+                    iterations: setup.iterations,
+                }, {
+                    timeout: 10_000,
+                    headers: { "X-Encryption-Key": setup.keyBase64 },
+                });
+                pendingLocalAuth.mode = "unlock";
+                pendingLocalAuth.config = {
+                    enabled: true,
+                    salt: setup.saltBase64,
+                    verification: setup.verification,
+                    iterations: setup.iterations,
+                };
+                await completeDeviceLogin(pendingLocalAuth.token);
+                resolveLocalToken(pendingLocalAuth.token, setup.keyBase64);
+                json(res, 200, { ok: true, connected: true });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to unlock encrypted memory");
+                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");
             res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-            // Let the HTTPS connect-device page reach this localhost server (Chrome Private Network Access).
-            res.setHeader("Access-Control-Allow-Private-Network", "true");
             if (req.method === "OPTIONS")
                 return void res.writeHead(204).end();
             const url = new URL(req.url || "/", "http://127.0.0.1");
@@ -1231,6 +1510,7 @@ export function startCallbackServer(opts = {}) {
                         authUrl,
                         switchAccountUrl: switchAccountUrl || authUrl,
                         localOnly: true,
+                        localAuth: true,
                         workspacePath: process.cwd(),
                         consentRequired: opts.requireReportConsent === true,
                         consentGranted: reportConsentGranted,
@@ -1286,6 +1566,42 @@ export function startCallbackServer(opts = {}) {
                     handleCallback(res, asString(body.token), asString(body.key), asString(body.nonce));
                     return;
                 }
+                if (route === "/local-auth/send-otp" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalSendOtp(res, body);
+                    return;
+                }
+                if (route === "/local-auth/verify-otp" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalVerifyOtp(res, body);
+                    return;
+                }
+                if (route === "/local-auth/passphrase" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalPassphrase(res, body);
+                    return;
+                }
                 if (route === "/stats" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
@@ -1500,10 +1816,17 @@ export function startCallbackServer(opts = {}) {
                         /* already logged out locally */
                     }
                     connected = false;
+                    const revokedPendingCredential = await revokePendingLocalAuth();
                     stats = null;
                     migrateStarted = false;
                     progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
-                    json(res, 200, { ok: true, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true });
+                    json(res, 200, {
+                        ok: true,
+                        authUrl,
+                        switchAccountUrl: switchAccountUrl || authUrl,
+                        localOnly: true,
+                        revokedPendingCredential,
+                    });
                     Promise.resolve()
                         .then(() => logoutHandler?.())
                         .catch((e) => {
@@ -1627,6 +1950,34 @@ function authedAxios(token) {
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
     });
 }
+function apiAxios() {
+    return axios.create({
+        baseURL: API_BASE_URL,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function normalizeEmail(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function validEmail(value) {
+    return value.length > 0 && value.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+function acceptedLocalTerms(body) {
+    return body.acceptedTerms === true && body.ageConfirmed === true;
+}
+function publicAxiosError(error, fallback) {
+    if (axios.isAxiosError(error)) {
+        const data = error.response?.data;
+        const status = typeof error.response?.status === "number" ? error.response.status : 500;
+        const message = typeof data?.error === "string"
+            ? data.error
+            : typeof data?.message === "string"
+                ? data.message
+                : fallback;
+        return { message, status };
+    }
+    return { message: error instanceof Error ? error.message : fallback, status: 500 };
+}
 function formatVerificationError(error) {
     if (axios.isAxiosError(error)) {
         const status = typeof error.response?.status === "number" ? error.response.status : null;
@@ -1693,16 +2044,20 @@ export async function verifyAndStore(input) {
         return "Token saved, but this account is ENCRYPTED. Re-run with --passphrase to unlock the vault.";
     }
     store.saveKey(keyB64);
-    return "✅ Token + encryption key verified and saved. Reload your MCP client.";
+    return "✅ Token + encryption key verified. This device stays unlocked until you run `echomem-mcp lock` or log out. Retry EchoMem in this session — no editor restart needed.";
 }
 function prompt(question, { silent = false } = {}) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
     return new Promise((resolve) => {
         if (silent) {
             const out = process.stdout;
-            rl._writeToOutput = () => out.write("");
+            // readline renders `question` through this private writer too. Print the label first, then
+            // suppress only the user's characters; otherwise the CLI waits on a completely blank line.
+            out.write(question);
+            const silentRl = rl;
+            silentRl._writeToOutput = () => undefined;
         }
-        rl.question(question, (answer) => {
+        rl.question(silent ? "" : question, (answer) => {
             rl.close();
             if (silent)
                 process.stdout.write("\n");
@@ -1767,6 +2122,9 @@ async function cmdSetup(flags) {
     if (!flags["no-agents-md"]) {
         writeMemoryGuidanceForTargets(targets);
     }
+    if (!flags["no-codex-skills"]) {
+        writeCodexSkillsForTargets(targets);
+    }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
         // init drives login itself right after, so the "skipped" note would be misleading there.
@@ -1781,10 +2139,10 @@ async function cmdSetup(flags) {
 }
 /**
  * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
- * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), writes the AGENTS.md
- * memory guidance, logs in via the browser, and launches the context HUD — the whole product in a
- * single command. `setup`/`update` remain the granular primitives; init just picks the "do everything"
- * defaults and frames the result.
+ * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), installs EchoMem's
+ * Codex skills, writes the AGENTS.md memory guidance, logs in via the browser, and launches the
+ * context HUD — the whole product in a single command. `setup`/`update` remain the granular
+ * primitives; init just picks the "do everything" defaults and frames the result.
  */
 async function cmdInit(flags) {
     console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
@@ -1819,8 +2177,8 @@ async function cmdInit(flags) {
 function writeMemoryGuidanceForTargets(targets) {
     const files = new Map(); // path → label
     for (const t of targets) {
-        if (t.id === "codex")
-            files.set(home(".codex", "AGENTS.md"), "Codex");
+        if (t.id === "codex" && t.kind === "command")
+            files.set(path.join(t.detectDir, "AGENTS.md"), "Codex");
         if (t.id === "claude-code" || t.id === "claude-desktop")
             files.set(home(".claude", "CLAUDE.md"), "Claude");
     }
@@ -1838,6 +2196,24 @@ function writeMemoryGuidanceForTargets(targets) {
         }
     }
 }
+function writeCodexSkillsForTargets(targets) {
+    const target = targets.find((client) => client.id === "codex" && client.kind === "command");
+    if (!target)
+        return;
+    try {
+        const report = installCodexSkills(target.detectDir);
+        const changed = [...report.installed, ...report.updated];
+        if (changed.length > 0) {
+            console.log(`✅ Installed EchoMem Codex skills: ${CODEX_SKILL_NAMES.join(", ")} — start a new Codex session to load them.`);
+        }
+        if (report.competingMemorySkills.length > 0) {
+            console.log(`ℹ️  Other memory skills remain installed: ${report.competingMemorySkills.join(", ")}. EchoMem did not modify them; its global guidance now selects EchoMem by default.`);
+        }
+    }
+    catch (error) {
+        console.log(`ℹ️  Could not install EchoMem Codex skills: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function cmdUpdate(flags) {
     await cmdSetup({ ...flags, "skip-login": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
@@ -1915,9 +2291,9 @@ async function cmdLogin(flags) {
             process.exitCode = 1;
         return ok;
     }
-    // Browser path: open a localhost dashboard. It briefly leaves for hosted auth, then returns here
-    // after the web page has delivered the token+key to the callback. The nonce gates every local route.
-    console.log("Opening your browser to approve this device…");
+    // Browser path: open a localhost dashboard. Login, legal confirmation, and encryption
+    // passphrase entry all happen through this local bridge. The nonce gates every local route.
+    console.log("Opening your browser to connect this device locally…");
     const devPortRaw = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
     if (devPortRaw !== undefined && (!Number.isInteger(devPortRaw) || devPortRaw < 1024 || devPortRaw > 65535)) {
         throw new Error("--dev-port must be an integer between 1024 and 65535");
@@ -1989,18 +2365,10 @@ async function cmdLogin(flags) {
             startForensicScan();
         },
     });
-    const callbackUrl = `http://127.0.0.1:${srv.port}/callback`;
     const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
-    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}&return_to=${encodeURIComponent(localSetupUrl)}`;
-    const switchAccountUrl = new URL(connectUrl);
-    // The hosted connect-device page should clear its own Supabase/browser session before minting
-    // the localhost token when this hint is present. Localhost cannot safely clear yeahecho.com auth.
-    switchAccountUrl.searchParams.set("force_signout", "1");
-    switchAccountUrl.searchParams.set("prompt", "login");
-    srv.setAuthUrl(connectUrl, switchAccountUrl.toString());
     openBrowser(localSetupUrl);
     console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
-    console.log("Waiting for browser approval for up to 15 minutes…");
+    console.log("Waiting for local setup for up to 15 minutes…");
     const startForensicScan = () => {
         if (forensicScanStarted || forensicConsent !== "allowed")
             return;
@@ -2654,7 +3022,9 @@ async function cmdUnlock(flags) {
     let passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
     const key = typeof flags.key === "string" ? flags.key : undefined;
     if (!passphrase && !key) {
-        passphrase = await prompt("Vault passphrase: ", { silent: true });
+        console.log("This is a private, one-time unlock for this trusted device.");
+        console.log("Enter your vault passphrase below. Your typing is hidden; press Return when finished.");
+        passphrase = await prompt("Vault passphrase (typing is hidden): ", { silent: true });
     }
     const keyB64 = passphrase ? await deriveAndVerifyKey(passphrase, config) : key && (await verifyKeyB64(key, config)) ? key : null;
     if (!keyB64) {
@@ -2663,7 +3033,22 @@ async function cmdUnlock(flags) {
         return;
     }
     store.saveKey(keyB64);
-    console.log("✅ Vault unlocked. Reload your MCP client (or start a new session).");
+    console.log("✅ Vault unlocked. This device stays unlocked until you run `echomem-mcp lock` or log out.");
+    console.log("Retry the EchoMem action in your current agent session — no restart needed.");
+}
+function cmdLock() {
+    if (process.env.ECHO_ENCRYPTION_KEY) {
+        console.error("The vault key comes from ECHO_ENCRYPTION_KEY. Unset that environment variable to lock this device.");
+        process.exitCode = 1;
+        return;
+    }
+    const store = new KeyStore();
+    if (!store.getKey()) {
+        console.log("EchoMem vault is already locked.");
+        return;
+    }
+    store.clearKey();
+    console.log("🔒 EchoMem vault locked on this device. Your login remains connected.");
 }
 async function cmdStatus(flags = {}) {
     const store = new KeyStore();
@@ -2700,7 +3085,13 @@ async function cmdStatus(flags = {}) {
             console.log(`Logged in as: (could not verify — ${formatVerificationError(error)})`);
         }
     }
-    console.log(`Encryption key: ${store.getKey() ? "present" : store.isKeyExpired() ? "EXPIRED — run `echomem-mcp unlock`" : "not set"}`);
+    const key = store.getKey();
+    const keyStatus = key
+        ? process.env.ECHO_ENCRYPTION_KEY
+            ? "present — provided by environment"
+            : "present — trusted on this device until `echomem-mcp lock` or logout"
+        : "not set — open Terminal and run `echomem-mcp unlock` for encrypted accounts";
+    console.log(`Encryption key: ${keyStatus}`);
     const detected = detectClients();
     console.log(`Detected clients: ${detected.length ? detected.map((c) => c.label).join(", ") : "none auto-detected"}`);
     const reports = inspectClientConfigs(latest ?? MCP_PACKAGE_VERSION);
@@ -2729,11 +3120,13 @@ Usage:
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then log in
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
+  echomem-mcp setup --no-codex-skills  Skip installing the bundled EchoMem Codex skills
   echomem-mcp update --all          Repoint detected clients to this installed bridge; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser
   echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
-  echomem-mcp login                 Approve this device in the browser (or --token/--passphrase)
-  echomem-mcp unlock                Re-derive the encryption key after its TTL (or --passphrase)
+  echomem-mcp login                 Connect this device in the local browser page (or --token/--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/clients
   echomem-mcp doctor [--no-network] Diagnose configured client bridge versions
   echomem-mcp logout                Remove stored credentials
@@ -2777,6 +3170,9 @@ export async function runCli(argv) {
         case "unlock":
             await cmdUnlock(flags);
             return true;
+        case "lock":
+            cmdLock();
+            return true;
         case "status":
             await cmdStatus(flags);
             return true;