@pyxmate/memory 1.21.0 → 1.23.0

package/dist/cli/pyx-mem.mjs

@@ -2,7 +2,7 @@
 import {
   PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
-} from "../chunk-EZERG25I.mjs";
+} from "../chunk-QD7G23CN.mjs";
 import {
   MEMORY_PROJECT_LABEL_MAX_CHARS,
   TAXONOMY_MAX_CATEGORIES,
@@ -10,7 +10,7 @@ import {
   TAXONOMY_MAX_SAMPLE_TOPICS,
   TAXONOMY_MAX_TOP_ENTITIES
 } from "../chunk-KZKGRND2.mjs";
-import "../chunk-BUKDWHTY.mjs";
+import "../chunk-C46EE5BH.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -19,9 +19,15 @@ var EXIT = {
   USAGE: 2,
   NOT_LOGGED_IN: 3,
   CRED_UNAVAILABLE: 4,
-  PROVIDER_BROKEN: 5
+  PROVIDER_BROKEN: 5,
+  BUSY: 6,
+  CLEANUP_PENDING: 7,
+  CANCELLED: 8
 };
 
+// src/cli/lifecycle/journal.ts
+import { createHash } from "crypto";
+
 // src/cli/keychain/errors.ts
 var PLATFORM_GUIDANCE = {
   darwin: {
@@ -90,19 +96,447 @@ function causeMessage(cause) {
   return "";
 }
 
+// src/cli/lifecycle/api.ts
+var REQUEST_TIMEOUT_MS = 15e3;
+var MAX_RESPONSE_BYTES = 64 * 1024;
+var MAX_ENDPOINT_CHARS = 256;
+var REQUEST_ID_RE = /^[A-Za-z0-9_-]{43}$/;
+var PROJECT_KEY_RE = /^pyx_proj_[A-Za-z0-9_-]{16,160}$/;
+var ERROR_MESSAGES = {
+  busy: { message: "Another pyx-mem sign-in or sign-out is in progress.", retryable: true },
+  cleanup_pending: {
+    message: "Cleanup of an earlier sign-in or sign-out is still pending. Run: pyx-mem login-recovery",
+    retryable: true
+  },
+  invalid_endpoint: {
+    message: "Endpoint must be an https URL (http only for loopback) without credentials, query or fragment.",
+    retryable: false
+  },
+  untrusted_authorization_url: {
+    message: "The server returned a browser sign-in address that is not trusted for this endpoint.",
+    retryable: false
+  },
+  browser_login_unsupported: {
+    message: "This endpoint does not support browser sign-in. Use: pyx-mem login --api-key",
+    retryable: false
+  },
+  network_error: { message: "Could not reach the pyx-memory server.", retryable: true },
+  rate_limited: { message: "Too many sign-in attempts. Wait a minute and retry.", retryable: true },
+  expired: { message: "The sign-in request expired before it was completed.", retryable: true },
+  project_not_eligible: {
+    message: "That project can no longer be connected from this account.",
+    retryable: true
+  },
+  credential_changed: {
+    message: "The stored pyx-memory credential was changed by another program. Nothing was overwritten.",
+    retryable: true
+  },
+  lock_lost: {
+    message: "The sign-in was interrupted. Run: pyx-mem login-recovery",
+    retryable: true
+  },
+  credential_store_unavailable: {
+    message: "The OS credential store is unavailable.",
+    retryable: false
+  },
+  journal_invalid: {
+    message: 'The pending-cleanup record in the OS credential store is unreadable. Nothing was deleted, and pyx-memory stays blocked on this computer. To reset: revoke unexpected "Pyx CLI" keys in the dashboard, then run: pyx-mem login-recovery --discard-unreadable-journal (this signs this computer out).',
+    retryable: false
+  },
+  login_failed: { message: "Browser sign-in failed.", retryable: true }
+};
+var SERVER_CODES = {
+  rate_limited: "rate_limited",
+  cli_login_expired_or_unknown: "expired",
+  cli_login_project_not_eligible: "project_not_eligible",
+  cli_login_cancelled: "cancelled",
+  cli_login_denied: "cancelled"
+};
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]"]);
+var BROWSER_ORIGINS = {
+  "https://memory.api.pyxmate.com": "https://memory.pyxmate.com"
+};
+function parseSafeUrl(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  const secure = url.protocol === "https:" || url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (!secure || url.username !== "" || url.password !== "" || url.hash !== "") return null;
+  return url;
+}
+function parseEndpoint(input) {
+  const url = parseSafeUrl(input);
+  if (url === null || url.search !== "" || input.includes("?") || input.includes("#")) return null;
+  const normalized = url.href.replace(/\/+$/, "");
+  return normalized.length <= MAX_ENDPOINT_CHARS ? normalized : null;
+}
+function boundLabel(value, maxChars) {
+  let label = value.replace(/\p{Cc}/gu, "").slice(0, maxChars);
+  while (JSON.stringify(label).length - 2 > maxChars) label = label.slice(0, -1);
+  return label;
+}
+function isTrustedAuthorizationUrl(authorizationUrl, endpoint, requestId) {
+  const url = parseSafeUrl(authorizationUrl);
+  if (url === null) return false;
+  const api = new URL(endpoint);
+  const trustedOrigin = LOOPBACK_HOSTS.has(api.hostname) ? LOOPBACK_HOSTS.has(url.hostname) : url.origin === (BROWSER_ORIGINS[api.origin] ?? api.origin);
+  const params = [...url.searchParams];
+  return trustedOrigin && url.pathname === "/cli/authorize" && params.length === 1 && params[0]?.[0] === "request" && params[0][1] === requestId;
+}
+async function readBounded(res) {
+  const reader = res.body?.getReader();
+  if (!reader) return void 0;
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      return void 0;
+    }
+    chunks.push(value);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function field(json, key) {
+  return typeof json === "object" && json !== null ? json[key] : void 0;
+}
+function failure(status, json) {
+  const serverCode = field(field(json, "error"), "code");
+  const mapped = typeof serverCode === "string" ? SERVER_CODES[serverCode] : void 0;
+  return { ok: false, code: mapped ?? (status === 429 ? "rate_limited" : "login_failed") };
+}
+function createCliLoginApi(fetchImpl = fetch) {
+  async function post(url, body, bearer, signal) {
+    const ctl = new AbortController();
+    const abort = () => ctl.abort();
+    const timer = setTimeout(abort, REQUEST_TIMEOUT_MS);
+    signal?.addEventListener("abort", abort);
+    try {
+      if (signal?.aborted) return null;
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          ...bearer === void 0 ? {} : { Authorization: `Bearer ${bearer}` }
+        },
+        body: JSON.stringify(body),
+        // A redirect would forward the proof or the key to another origin.
+        redirect: "error",
+        signal: ctl.signal
+      });
+      return { status: res.status, json: await readBounded(res) };
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+  const base = (endpoint) => `${endpoint}/auth/cli-login`;
+  return {
+    async start(endpoint, body, signal) {
+      const res = await post(`${base(endpoint)}/start`, body, void 0, signal);
+      if (res === null) return { ok: false, code: "network_error" };
+      if (res.status === 404) return { ok: false, code: "browser_login_unsupported" };
+      if (res.status !== 201) return failure(res.status, res.json);
+      const requestId = field(res.json, "requestId");
+      const authorizationUrl = field(res.json, "authorizationUrl");
+      const expiresAt = new Date(String(field(res.json, "expiresAt")));
+      if (typeof requestId !== "string" || !REQUEST_ID_RE.test(requestId) || typeof authorizationUrl !== "string" || Number.isNaN(expiresAt.getTime())) {
+        return { ok: false, code: "login_failed" };
+      }
+      if (!isTrustedAuthorizationUrl(authorizationUrl, endpoint, requestId)) {
+        return { ok: false, code: "untrusted_authorization_url" };
+      }
+      return { ok: true, requestId, authorizationUrl, expiresAt };
+    },
+    async redeem(login, code, signal) {
+      const res = await post(
+        `${base(login.endpoint)}/${login.requestId}/redeem`,
+        { code, codeVerifier: login.codeVerifier },
+        void 0,
+        signal
+      );
+      if (res === null) return { ok: false, code: "network_error" };
+      if (res.status !== 200) return failure(res.status, res.json);
+      const credential = field(res.json, "credential");
+      const apiKey = field(credential, "apiKey");
+      const connection = field(credential, "connection");
+      const accountLabel = field(connection, "accountLabel");
+      const projectId = field(connection, "projectId");
+      const projectName = field(connection, "projectName");
+      if (typeof apiKey !== "string" || !PROJECT_KEY_RE.test(apiKey) || typeof accountLabel !== "string" || typeof projectId !== "string" || typeof projectName !== "string") {
+        return { ok: false, code: "login_failed" };
+      }
+      return {
+        ok: true,
+        apiKey,
+        // Display metadata only; bounded so the shared record fits every OS store.
+        connection: {
+          accountLabel: boundLabel(accountLabel, 254),
+          projectId: boundLabel(projectId, 64),
+          projectName: boundLabel(projectName, 128)
+        }
+      };
+    },
+    async confirm(login, signal) {
+      const res = await post(
+        `${base(login.endpoint)}/${login.requestId}/confirm`,
+        { codeVerifier: login.codeVerifier },
+        login.apiKey,
+        signal
+      );
+      if (res === null) return { ok: false, code: "network_error" };
+      if (res.status !== 200 || field(res.json, "status") !== "confirmed") {
+        return failure(res.status, res.json);
+      }
+      return { ok: true };
+    },
+    async cancel(login) {
+      const res = await post(`${base(login.endpoint)}/${login.requestId}/cancel`, {
+        codeVerifier: login.codeVerifier
+      });
+      if (res === null) return false;
+      if (res.status === 200) return field(res.json, "status") === "cancelled";
+      return res.status === 404 && field(field(res.json, "error"), "code") === "cli_login_expired_or_unknown";
+    },
+    async revoke(key) {
+      const res = await post(`${base(key.endpoint)}/revoke`, {}, key.apiKey);
+      return res !== null && res.status === 200 && field(res.json, "status") === "revoked";
+    }
+  };
+}
+
+// src/cli/lifecycle/journal.ts
+var MAX_STORE_CHARS = 1200;
+var MAX_REVOKE_ENTRIES = 8;
+var TOKEN_RE = /^[A-Za-z0-9_-]{43}$/;
+var FINGERPRINT_RE = /^[0-9a-f]{16}$/;
+var PLACEHOLDER_KEY = `pyx_proj_${"x".repeat(160)}`;
+var SERVER_CONVERGENCE_SECONDS = 30;
+var JournalInvalidError = class extends Error {
+};
+var JournalFullError = class extends Error {
+};
+function credentialFingerprint(endpoint, apiKey) {
+  return createHash("sha256").update(`${endpoint}
+${apiKey}`).digest("hex").slice(0, 16);
+}
+function isEmpty(journal) {
+  return journal.login === null && journal.logout === null && journal.revoke.length === 0;
+}
+function emptyJournal() {
+  return { schemaVersion: 1, login: null, logout: null, revoke: [] };
+}
+function convergenceSeconds(journal, now = Date.now()) {
+  if (journal.revokedAt === void 0) return null;
+  const elapsed = Math.max(now - journal.revokedAt, 0);
+  const left = Math.ceil(SERVER_CONVERGENCE_SECONDS - elapsed / 1e3);
+  return left > 0 ? left : null;
+}
+function isExactObject(value, required, optional = []) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+function isKeyRef(value) {
+  if (!isExactObject(value, ["endpoint", "apiKey"])) return false;
+  const v = value;
+  return typeof v.endpoint === "string" && parseEndpoint(v.endpoint) === v.endpoint && typeof v.apiKey === "string" && PROJECT_KEY_RE.test(v.apiKey);
+}
+function isLoginRecord(value) {
+  if (!isExactObject(
+    value,
+    ["phase", "endpoint", "requestId", "codeVerifier", "expiresAt"],
+    ["apiKey", "previous"]
+  )) {
+    return false;
+  }
+  const v = value;
+  const held = v.phase === "issued" || v.phase === "committing";
+  return (held || v.phase === "started") && typeof v.requestId === "string" && TOKEN_RE.test(v.requestId) && typeof v.codeVerifier === "string" && TOKEN_RE.test(v.codeVerifier) && Number.isSafeInteger(v.expiresAt) && (held ? isKeyRef({ endpoint: v.endpoint, apiKey: v.apiKey }) : v.apiKey === void 0 && isKeyRef({ endpoint: v.endpoint, apiKey: PLACEHOLDER_KEY })) && (v.previous === void 0 || v.phase === "committing" && isKeyRef(v.previous));
+}
+function isLogoutRecord(value) {
+  if (!isExactObject(value, ["fingerprint", "revoke"])) return false;
+  const v = value;
+  return typeof v.fingerprint === "string" && FINGERPRINT_RE.test(v.fingerprint) && (v.revoke === null || isKeyRef(v.revoke));
+}
+function isJournal(value) {
+  if (!isExactObject(value, ["schemaVersion", "login", "logout", "revoke"], ["revokedAt"])) {
+    return false;
+  }
+  const v = value;
+  return v.schemaVersion === 1 && (v.login === null || isLoginRecord(v.login)) && (v.logout === null || isLogoutRecord(v.logout)) && Array.isArray(v.revoke) && v.revoke.length <= MAX_REVOKE_ENTRIES && v.revoke.every(isKeyRef) && (v.revokedAt === void 0 || Number.isSafeInteger(v.revokedAt) && v.revokedAt >= 0);
+}
+function hasRoomForLogin(journal, endpoint, previous) {
+  const largest = {
+    ...journal,
+    login: {
+      phase: "committing",
+      endpoint,
+      requestId: "x".repeat(43),
+      codeVerifier: "x".repeat(43),
+      expiresAt: Number.MAX_SAFE_INTEGER,
+      apiKey: PLACEHOLDER_KEY,
+      ...previous ? { previous } : {}
+    },
+    revokedAt: Number.MAX_SAFE_INTEGER
+  };
+  return JSON.stringify(largest).length <= MAX_STORE_CHARS;
+}
+async function loadJournal(provider) {
+  const raw = await provider.readJournal();
+  if (raw === null) return emptyJournal();
+  if (raw.length > MAX_STORE_CHARS) throw new JournalInvalidError();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new JournalInvalidError();
+  }
+  if (!isJournal(parsed)) throw new JournalInvalidError();
+  return parsed;
+}
+async function saveJournal(provider, journal) {
+  if (isEmpty(journal) && convergenceSeconds(journal) === null) return provider.clearJournal();
+  const raw = JSON.stringify(journal);
+  if (raw.length > MAX_STORE_CHARS) throw new JournalFullError();
+  if (!isJournal(JSON.parse(raw))) throw new Error("refusing to write an invalid journal");
+  await provider.writeJournal(raw);
+}
+async function supersedeLogout(provider, endpoint, apiKey) {
+  let journal;
+  try {
+    journal = await loadJournal(provider);
+  } catch (err) {
+    if (err instanceof JournalInvalidError) return;
+    throw err;
+  }
+  if (journal.logout?.fingerprint !== credentialFingerprint(endpoint, apiKey)) return;
+  journal.logout = null;
+  await saveJournal(provider, journal);
+}
+function guardKeychain(provider) {
+  return {
+    write: (credentials) => provider.write(credentials),
+    delete: () => provider.delete(),
+    check: () => provider.check(),
+    readJournal: () => provider.readJournal(),
+    writeJournal: (raw) => provider.writeJournal(raw),
+    clearJournal: () => provider.clearJournal(),
+    acquireLock: (onLost) => provider.acquireLock(onLost),
+    isLocked: () => provider.isLocked(),
+    async read() {
+      const credentials = await provider.read();
+      if (credentials === null) return null;
+      let blocked;
+      try {
+        const { logout } = await loadJournal(provider);
+        blocked = logout?.fingerprint === credentialFingerprint(credentials.endpoint, credentials.apiKey);
+      } catch (err) {
+        if (!(err instanceof JournalInvalidError)) throw err;
+        blocked = true;
+      }
+      if (blocked) {
+        throw new KeychainError({
+          code: "logout-incomplete",
+          message: "A pyx-memory sign-out did not finish on this computer.",
+          guidance: "Run: pyx-mem login-recovery",
+          exit: EXIT.NOT_LOGGED_IN
+        });
+      }
+      return credentials;
+    }
+  };
+}
+
+// src/cli/keychain/napi-provider.ts
+import { homedir } from "os";
+import { join } from "path";
+
+// src/cli/lifecycle/lock.ts
+import { mkdir } from "fs/promises";
+import { dirname } from "path";
+import lockfile from "proper-lockfile";
+var LOCK_OPTIONS = { realpath: false, stale: 15e3 };
+function createFileLock(file) {
+  return {
+    async acquire(onLost) {
+      await mkdir(dirname(file), { recursive: true, mode: 448 });
+      let release;
+      try {
+        release = await lockfile.lock(file, { ...LOCK_OPTIONS, onCompromised: () => onLost() });
+      } catch (err) {
+        if (err.code === "ELOCKED") return null;
+        throw err;
+      }
+      return async () => {
+        try {
+          await release();
+        } catch (err) {
+          const code = err.code;
+          if (code !== "ERELEASED" && code !== "ENOTACQUIRED") throw err;
+        }
+      };
+    },
+    isLocked: () => lockfile.check(file, LOCK_OPTIONS)
+  };
+}
+var BUSY = /* @__PURE__ */ Symbol("lifecycle-lock-busy");
+var LockLostError = class extends Error {
+};
+async function releaseLifecycleLock(release) {
+  try {
+    await release();
+  } catch (err) {
+    const code = err?.code;
+    const reason = typeof code === "string" && /^[A-Z_]{1,32}$/.test(code) ? code : "unknown";
+    process.stderr.write(
+      `Warning: the pyx-mem lifecycle lock could not be released (${reason}). The reported result stands; other pyx-mem sign-in or sign-out commands may answer busy for up to ${LOCK_OPTIONS.stale / 1e3} seconds.
+`
+    );
+  }
+}
+async function withLifecycleLock(provider, fn) {
+  let lost = false;
+  const release = await provider.acquireLock(() => {
+    lost = true;
+  });
+  if (release === null) return BUSY;
+  try {
+    return await fn(() => lost);
+  } finally {
+    await releaseLifecycleLock(release);
+  }
+}
+
 // src/cli/keychain/types.ts
 var KEYCHAIN_SERVICE = "pyx-memory";
 var KEYCHAIN_ACCOUNT = "default";
 var CREDENTIAL_SCHEMA_VERSION = 1;
+var JOURNAL_ACCOUNT = "lifecycle-journal";
 
 // src/cli/keychain/napi-provider.ts
-var cached = null;
-async function loadEntry() {
-  if (cached) return cached;
+var cached = /* @__PURE__ */ new Map();
+async function loadEntry(account = KEYCHAIN_ACCOUNT) {
+  const hit = cached.get(account);
+  if (hit) return hit;
   try {
     const mod = await import("@napi-rs/keyring");
-    cached = new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
-    return cached;
+    const entry = new mod.Entry(KEYCHAIN_SERVICE, account);
+    cached.set(account, entry);
+    return entry;
   } catch (err) {
     throw providerImportError(err);
   }
@@ -120,9 +554,16 @@ function parseRecord(raw) {
 function isValidRecord(value) {
   if (typeof value !== "object" || value === null) return false;
   const v = value;
-  return v.schemaVersion === CREDENTIAL_SCHEMA_VERSION && typeof v.endpoint === "string" && v.endpoint.length > 0 && typeof v.apiKey === "string" && v.apiKey.length > 0;
+  return v.schemaVersion === CREDENTIAL_SCHEMA_VERSION && typeof v.endpoint === "string" && v.endpoint.length > 0 && typeof v.apiKey === "string" && v.apiKey.length > 0 && (v.provenance === void 0 || v.provenance === "browser-login" && isConnection(v.connection));
+}
+function isConnection(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const c = value;
+  return typeof c.accountLabel === "string" && typeof c.projectId === "string" && typeof c.projectName === "string";
 }
 var NapiKeychainProvider = class {
+  // The lock file holds no secrets; credentials and the journal stay in the OS store.
+  lock = createFileLock(join(homedir(), ".pyx-memory", "lifecycle"));
   async read() {
     const entry = await loadEntry();
     let raw;
@@ -139,7 +580,8 @@ var NapiKeychainProvider = class {
     const payload = JSON.stringify({
       schemaVersion: CREDENTIAL_SCHEMA_VERSION,
       endpoint: credentials.endpoint,
-      apiKey: credentials.apiKey
+      apiKey: credentials.apiKey,
+      ...credentials.provenance === "browser-login" ? { connection: credentials.connection, provenance: credentials.provenance } : {}
     });
     try {
       entry.setPassword(payload);
@@ -155,6 +597,36 @@ var NapiKeychainProvider = class {
       throw platformAccessError(err);
     }
   }
+  async readJournal() {
+    const entry = await loadEntry(JOURNAL_ACCOUNT);
+    try {
+      return entry.getPassword();
+    } catch (err) {
+      throw platformAccessError(err);
+    }
+  }
+  async writeJournal(raw) {
+    const entry = await loadEntry(JOURNAL_ACCOUNT);
+    try {
+      entry.setPassword(raw);
+    } catch (err) {
+      throw platformAccessError(err);
+    }
+  }
+  async clearJournal() {
+    const entry = await loadEntry(JOURNAL_ACCOUNT);
+    try {
+      entry.deletePassword();
+    } catch (err) {
+      throw platformAccessError(err);
+    }
+  }
+  acquireLock(onLost) {
+    return this.lock.acquire(onLost);
+  }
+  isLocked() {
+    return this.lock.isLocked();
+  }
   async check() {
     try {
       const entry = await loadEntry();
@@ -172,6 +644,9 @@ var NapiKeychainProvider = class {
 
 // src/cli/keychain/index.ts
 function getDefaultKeychain() {
+  return guardKeychain(new NapiKeychainProvider());
+}
+function getLifecycleKeychain() {
   return new NapiKeychainProvider();
 }
 
@@ -511,6 +986,7 @@ async function readSurface(opts) {
       state: "error",
       endpoint: null,
       keySource: null,
+      credentialFingerprint: null,
       problem: error instanceof KeychainError ? [error.message, error.guidance].filter(Boolean).join(" ") : "The OS credential store could not be read."
     };
   }
@@ -521,9 +997,11 @@ async function readSurface(opts) {
       state: "signed_out",
       endpoint: null,
       keySource: null,
+      credentialFingerprint: null,
       problem: null
     };
   }
+  const fingerprint = credentialFingerprint(credentials.endpoint, credentials.apiKey);
   if (!isHttpUrl(credentials.endpoint)) {
     return {
       ok: false,
@@ -531,6 +1009,7 @@ async function readSurface(opts) {
       state: "error",
       endpoint: null,
       keySource: "keychain",
+      credentialFingerprint: fingerprint,
       problem: "The stored pyx-memory endpoint is invalid. Run: pyx-mem login"
     };
   }
@@ -544,6 +1023,7 @@ async function readSurface(opts) {
       opts.surface,
       response.status,
       credentials.endpoint,
+      fingerprint,
       opts.minimumServiceVersion,
       http
     );
@@ -556,12 +1036,18 @@ async function readSurface(opts) {
       state: "error",
       endpoint: credentials.endpoint,
       keySource: "keychain",
+      credentialFingerprint: fingerprint,
       problem: `pyx-memory returned an invalid ${opts.surface} response. Run: pyx-mem doctor`
     };
   }
-  return { ok: true, endpoint: credentials.endpoint, data: parsed.data };
+  return {
+    ok: true,
+    endpoint: credentials.endpoint,
+    credentialFingerprint: fingerprint,
+    data: parsed.data
+  };
 }
-async function failedSurfaceRequest(surface, status, endpoint, minimumServiceVersion, http) {
+async function failedSurfaceRequest(surface, status, endpoint, credentialFingerprint2, minimumServiceVersion, http) {
   if (status === 401) {
     return {
       ok: false,
@@ -569,6 +1055,7 @@ async function failedSurfaceRequest(surface, status, endpoint, minimumServiceVer
       state: "signed_out",
       endpoint,
       keySource: "keychain",
+      credentialFingerprint: credentialFingerprint2,
       problem: requestFailure(surface, status)
     };
   }
@@ -580,6 +1067,7 @@ async function failedSurfaceRequest(surface, status, endpoint, minimumServiceVer
     state: serviceOutdated ? "service_outdated" : "error",
     endpoint,
     keySource: "keychain",
+    credentialFingerprint: credentialFingerprint2,
     problem: serviceOutdated ? `pyx-memory ${surface} requires service ${minimumServiceVersion} or newer; the connected service reports ${serviceVersion}. Update the hosted pyx-memory service or dashboard integration, then retry.` : requestFailure(surface, status)
   };
 }
@@ -699,8 +1187,14 @@ async function insightsCommand(opts = {}) {
     keychain: opts.keychain,
     fetchImpl: opts.fetchImpl
   });
+  const withIdentity = opts.withIdentity === true;
   if (!result.ok) {
-    emit(report(result.state, result.endpoint, result.keySource, result.problem));
+    emit(
+      report(result.state, result.endpoint, result.keySource, result.problem, {
+        withIdentity,
+        credentialFingerprint: result.credentialFingerprint
+      })
+    );
     return result.exit;
   }
   emit({
@@ -708,17 +1202,22 @@ async function insightsCommand(opts = {}) {
     state: "ready",
     endpoint: result.endpoint,
     keySource: "keychain",
+    ...identityField({ withIdentity, credentialFingerprint: result.credentialFingerprint }),
     ...result.data,
     problem: null
   });
   return EXIT.OK;
 }
-function report(state, endpoint, keySource, problem) {
+function identityField(identity) {
+  return identity.withIdentity ? { credentialFingerprint: identity.credentialFingerprint } : {};
+}
+function report(state, endpoint, keySource, problem, identity) {
   return {
     schemaVersion: INSIGHTS_SCHEMA_VERSION,
     state,
     endpoint,
     keySource,
+    ...identityField(identity),
     generatedAt: null,
     scope: "connected_memory",
     coverage: null,
@@ -812,7 +1311,7 @@ async function readSingleLineFromStdin() {
 // src/cli/commands/login.ts
 var DEFAULT_ENDPOINT = "https://memory.api.pyxmate.com";
 async function loginCommand(opts = {}) {
-  const provider = opts.keychain ?? getDefaultKeychain();
+  const provider = opts.keychain ?? getLifecycleKeychain();
   const fetcher = opts.fetchImpl ?? fetch;
   const endpoint = normalizeEndpoint(
     opts.endpoint ?? await readExistingEndpoint(provider) ?? DEFAULT_ENDPOINT
@@ -844,7 +1343,16 @@ No credentials were written.
     return EXIT.NOT_LOGGED_IN;
   }
   try {
-    await provider.write({ schemaVersion: 1, endpoint, apiKey });
+    const written = await withLifecycleLock(provider, async () => {
+      await supersedeLogout(provider, endpoint, apiKey);
+      await provider.write({ schemaVersion: 1, endpoint, apiKey });
+    });
+    if (written === BUSY) {
+      process.stderr.write(
+        "Error: another pyx-mem sign-in or sign-out is in progress. Retry in a moment.\nNo credentials were written.\n"
+      );
+      return EXIT.BUSY;
+    }
   } catch (err) {
     if (err instanceof KeychainError) {
       process.stderr.write(
@@ -888,21 +1396,617 @@ function isHttpUrl2(value) {
   }
 }
 
+// src/cli/commands/login-browser.ts
+import { spawn } from "child_process";
+import { createHash as createHash3, randomBytes } from "crypto";
+import { hostname } from "os";
+import { createInterface } from "readline";
+
+// src/cli/lifecycle/callback-server.ts
+import { createHash as createHash2, timingSafeEqual } from "crypto";
+import { createServer } from "http";
+var CALLBACK_PATH = "/pyx-memory/callback";
+var CODE_RE = /^[A-Za-z0-9_-]{43}$/;
+var STYLES = `
+:root { color-scheme: dark; font-family: "Avenir Next", "Trebuchet MS", sans-serif; }
+* { box-sizing: border-box; }
+body {
+  margin: 0; min-height: 100vh; min-height: 100svh; padding: 32px 20px;
+  display: flex; color: #f7f8fb; background: #0b0b0e;
+  background-image: radial-gradient(ellipse at 50% 55%, #0071e31c, transparent 65%);
+}
+main { width: 100%; max-width: 496px; margin: auto; }
+.brand { margin: 0 0 20px 8px; font-size: 15px; font-weight: 600; letter-spacing: -.02em; }
+.brand span { margin-left: 8px; color: #a9adb8; font-weight: 400; }
+.card {
+  padding: clamp(24px, 6vw, 40px); border: 1px solid #30333c; border-radius: 28px;
+  background: #15161c; box-shadow: 0 24px 80px #0006;
+}
+.symbol {
+  display: grid; place-items: center; width: 64px; height: 64px; margin-bottom: 32px;
+  border: 1px solid #2c4059; border-radius: 20px; color: #6ab4ff; background: #12263a;
+}
+.continue .symbol { animation: arrive 360ms cubic-bezier(.22, 1, .36, 1); }
+.cancelled .symbol { color: #a9adb8; background: #20222b; border-color: #383b47; }
+.invalid .symbol { color: #f4bd7a; background: #302719; border-color: #59462d; }
+h1 {
+  margin: 0 0 20px; font-size: clamp(28px, 6vw, 40px); font-weight: 600;
+  line-height: 1.12; letter-spacing: -.035em; overflow-wrap: break-word;
+}
+p { margin: 0; color: #a9adb8; font-size: 16px; line-height: 1.65; }
+.note { margin-top: 32px; padding-top: 24px; border-top: 1px solid #30333c; font-size: 14px; }
+@keyframes arrive { from { opacity: .65; transform: translateY(4px); } }
+@media (prefers-reduced-motion: reduce) { .continue .symbol { animation: none; } }
+`;
+var PAGE_CSP = `default-src 'none'; style-src 'sha256-${createHash2("sha256").update(STYLES).digest("base64")}'; base-uri 'none'; form-action 'none'`;
+var page = (state, title, text, icon) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} \xB7 Pyx Memory</title>
+<style>${STYLES}</style>
+</head>
+<body>
+<main class="${state}">
+<div class="brand">pyx<span>Memory</span></div>
+<section class="card" aria-labelledby="title">
+<div class="symbol" aria-hidden="true"><svg width="30" height="30" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">${icon}</svg></div>
+<h1 id="title">${title}</h1>
+<p>${text}</p>
+<p class="note">You can close this tab.</p>
+</section>
+</main>
+</body>
+</html>`;
+var ACCEPTED_PAGE = page(
+  "continue",
+  "Continue in your app",
+  "Your approval was received. Return to the app that started this sign-in to finish connecting.",
+  '<path d="m9 4-5 5 5 5M4 9h10a6 6 0 0 1 0 12h-2"/>'
+);
+var DENIED_PAGE = page(
+  "cancelled",
+  "Sign-in cancelled",
+  "Return to the app that started this sign-in. You can try again there whenever you\u2019re ready.",
+  '<path d="m7 7 10 10M17 7 7 17"/>'
+);
+var REJECTED_PAGE = page(
+  "invalid",
+  "This sign-in link isn\u2019t valid",
+  "Return to the app that started this sign-in to continue or try again.",
+  '<path d="M12 6v7m0 4v.01"/><circle cx="12" cy="12" r="10"/>'
+);
+function sameSecret(a, b) {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function single(params, key) {
+  const values = params.getAll(key);
+  return values.length === 1 ? values[0] : null;
+}
+async function startCallbackServer() {
+  let expected = null;
+  let settle2 = () => {
+  };
+  const result = new Promise((resolve3) => {
+    settle2 = resolve3;
+  });
+  function accept(method, host, rawUrl) {
+    if (method !== "GET" || expected === null || host !== `127.0.0.1:${port}`) return null;
+    const url = new URL(rawUrl, `http://127.0.0.1:${port}`);
+    if (url.pathname !== CALLBACK_PATH) return null;
+    const params = url.searchParams;
+    const keys = new Set(params.keys());
+    const code = single(params, "code");
+    const error = single(params, "error");
+    if (keys.size !== 3 || single(params, "request") !== expected.requestId || !sameSecret(single(params, "state") ?? "", expected.state)) {
+      return null;
+    }
+    if (code !== null && CODE_RE.test(code)) return { code };
+    if (error === "access_denied") return { denied: true };
+    return null;
+  }
+  const server = createServer({ maxHeaderSize: 8192 }, (req, res) => {
+    const accepted = accept(req.method, req.headers.host, req.url ?? "");
+    if (accepted !== null) {
+      expected = null;
+      settle2(accepted);
+    }
+    res.writeHead(accepted === null ? 400 : 200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store",
+      "Content-Security-Policy": PAGE_CSP,
+      "Referrer-Policy": "no-referrer",
+      "X-Content-Type-Options": "nosniff",
+      Connection: "close"
+    });
+    res.end(accepted === null ? REJECTED_PAGE : "denied" in accepted ? DENIED_PAGE : ACCEPTED_PAGE);
+  });
+  server.requestTimeout = 5e3;
+  server.headersTimeout = 5e3;
+  await new Promise((resolve3, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve3);
+  });
+  const port = server.address().port;
+  return {
+    port,
+    expect(requestId, state) {
+      expected = { requestId, state };
+    },
+    result,
+    close() {
+      server.close();
+      server.closeAllConnections();
+    }
+  };
+}
+
+// src/cli/lifecycle/settle.ts
+var STARTED_EXPIRY_MARGIN_MS = 15 * 6e4;
+async function settle(keychain, api, journal, lockLost) {
+  const holdsLock = () => {
+    if (lockLost()) throw new LockLostError();
+  };
+  const save = async () => {
+    holdsLock();
+    await saveJournal(keychain, journal);
+  };
+  const readShared = () => keychain.read().catch((err) => {
+    if (err instanceof KeychainError && err.code === "credential-record-invalid") return null;
+    throw err;
+  });
+  const queueRevoke = (key) => {
+    const queued = journal.revoke.some(
+      (pending) => pending.endpoint === key.endpoint && pending.apiKey === key.apiKey
+    );
+    if (!queued) journal.revoke.push(key);
+  };
+  const login = journal.login;
+  if (login?.phase === "started") {
+    holdsLock();
+    if (Date.now() > login.expiresAt + STARTED_EXPIRY_MARGIN_MS || await api.cancel(login)) {
+      journal.login = null;
+      await save();
+    }
+  } else if (login?.apiKey !== void 0) {
+    const own = { endpoint: login.endpoint, apiKey: login.apiKey };
+    const shared = login.phase === "committing" ? await readShared() : null;
+    const committed = shared !== null && credentialFingerprint(shared.endpoint, shared.apiKey) === credentialFingerprint(own.endpoint, own.apiKey);
+    journal.login = null;
+    if (!committed) queueRevoke(own);
+    if (login.previous !== void 0 && shared?.apiKey !== login.previous.apiKey) {
+      queueRevoke(login.previous);
+    }
+    await save();
+  }
+  if (journal.logout !== null) {
+    const { fingerprint, revoke } = journal.logout;
+    const shared = await readShared();
+    if (shared !== null && credentialFingerprint(shared.endpoint, shared.apiKey) === fingerprint) {
+      holdsLock();
+      await keychain.delete();
+    }
+    journal.logout = null;
+    if (revoke !== null) queueRevoke(revoke);
+    await save();
+  }
+  for (const key of [...journal.revoke]) {
+    holdsLock();
+    if (await api.revoke(key)) {
+      journal.revoke = journal.revoke.filter((pending) => pending !== key);
+      journal.revokedAt = Date.now();
+      await save();
+    }
+  }
+  return journal;
+}
+
+// src/cli/commands/login-browser.ts
+var DEFAULT_ENDPOINT2 = "https://memory.api.pyxmate.com";
+var MAX_STDIN_LINE = 1024;
+var Stop = class extends Error {
+  constructor(outcome) {
+    super(outcome);
+    this.outcome = outcome;
+  }
+  outcome;
+};
+function stopFor(failure2) {
+  return new Stop(failure2.code === "cancelled" ? "requested" : failure2.code);
+}
+function printHuman(e) {
+  if (e.event === "awaiting_browser") {
+    process.stdout.write(`Sign in with your browser:
+${e.authorizationUrl}
+`);
+  } else if (e.event === "connecting") {
+    process.stdout.write("Finishing sign-in\u2026\n");
+  } else if (e.event === "connected") {
+    process.stdout.write(
+      `Connected to ${e.connection.projectName} as ${e.connection.accountLabel}. Run: pyx-mem doctor
+`
+    );
+  } else if (e.event === "cancelled") {
+    process.stdout.write("Sign-in cancelled. Stored credentials were not changed.\n");
+  } else {
+    process.stderr.write(`Error: ${e.message}
+`);
+  }
+  if ("cleanupPending" in e && e.cleanupPending && e.event !== "error") {
+    process.stderr.write("Server-side cleanup is pending. Run: pyx-mem login-recovery\n");
+  }
+}
+function openInBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.on("error", () => {
+    process.stderr.write(
+      "Could not open a browser automatically. Open the sign-in URL yourself.\n"
+    );
+  });
+  child.unref();
+}
+function exitFor(outcome) {
+  if (outcome === "requested" || outcome === "denied") return EXIT.CANCELLED;
+  if (outcome === "busy") return EXIT.BUSY;
+  if (outcome === "cleanup_pending") return EXIT.CLEANUP_PENDING;
+  if (outcome === "invalid_endpoint") return EXIT.USAGE;
+  return EXIT.DOCTOR_FAIL;
+}
+async function snapshot(keychain) {
+  try {
+    const credentials = await keychain.read();
+    return {
+      token: credentials === null ? "none" : credentialFingerprint(credentials.endpoint, credentials.apiKey),
+      credentials
+    };
+  } catch (err) {
+    if (err instanceof KeychainError && err.code === "credential-record-invalid") {
+      return { token: "invalid", credentials: null };
+    }
+    throw err;
+  }
+}
+async function browserLoginCommand(opts) {
+  const keychain = opts.keychain ?? getLifecycleKeychain();
+  const api = createCliLoginApi(opts.fetchImpl);
+  const emit4 = opts.json ? (e) => process.stdout.write(`${JSON.stringify(e)}
+`) : printHuman;
+  const stop = new AbortController();
+  let lockLost = false;
+  const cancel = () => stop.abort();
+  const stopped = new Promise((_, reject) => {
+    stop.signal.addEventListener("abort", () => reject(new Stop("requested")));
+  });
+  stopped.catch(() => {
+  });
+  const check = () => {
+    if (lockLost) throw new Stop("lock_lost");
+    if (stop.signal.aborted) throw new Stop("requested");
+  };
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  const lines = opts.json ? createInterface({ input: opts.input ?? process.stdin }) : null;
+  lines?.on("line", (line) => {
+    if (line.length > MAX_STDIN_LINE) return;
+    try {
+      if (JSON.parse(line)?.action === "cancel") cancel();
+    } catch {
+    }
+  });
+  if (opts.noOpen) lines?.on("close", cancel);
+  let release = null;
+  let listener = null;
+  let journal = null;
+  let connected = null;
+  let outcome = null;
+  let storeError = null;
+  try {
+    release = await keychain.acquireLock(() => {
+      lockLost = true;
+      cancel();
+    });
+    if (release === null) throw new Stop("busy");
+    journal = await settle(keychain, api, await loadJournal(keychain), () => lockLost);
+    if (journal.login !== null) throw new Stop("cleanup_pending");
+    const base = await snapshot(keychain);
+    const endpoint = parseEndpoint(opts.endpoint ?? base.credentials?.endpoint ?? DEFAULT_ENDPOINT2);
+    if (endpoint === null) throw new Stop("invalid_endpoint");
+    const replaced = base.credentials ? { endpoint: base.credentials.endpoint, apiKey: base.credentials.apiKey } : null;
+    const previous = replaced !== null && base.credentials?.provenance === "browser-login" && isKeyRef(replaced) ? replaced : void 0;
+    if (!hasRoomForLogin(journal, endpoint, previous)) throw new Stop("cleanup_pending");
+    listener = await startCallbackServer();
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const state = randomBytes(32).toString("base64url");
+    const started = await api.start(
+      endpoint,
+      {
+        codeChallenge: createHash3("sha256").update(codeVerifier).digest("base64url"),
+        callbackPort: listener.port,
+        state,
+        deviceLabel: hostname().replace(/\p{Cc}/gu, "").trim().slice(0, 64) || "this computer"
+      },
+      stop.signal
+    );
+    check();
+    if (!started.ok) throw stopFor(started);
+    const login = {
+      phase: "started",
+      endpoint,
+      requestId: started.requestId,
+      codeVerifier,
+      expiresAt: started.expiresAt.getTime()
+    };
+    journal.login = login;
+    await saveJournal(keychain, journal);
+    check();
+    listener.expect(started.requestId, state);
+    emit4({
+      event: "awaiting_browser",
+      authorizationUrl: started.authorizationUrl,
+      expiresAt: started.expiresAt.toISOString()
+    });
+    if (!opts.noOpen) (opts.openBrowser ?? openInBrowser)(started.authorizationUrl);
+    let expiry;
+    const expired = new Promise((_, reject) => {
+      const ms = Math.min(Math.max(started.expiresAt.getTime() - Date.now(), 0), 6e5);
+      expiry = setTimeout(() => reject(new Stop("expired")), ms);
+    });
+    const callback = await Promise.race([listener.result, stopped, expired]).finally(
+      () => clearTimeout(expiry)
+    );
+    check();
+    if ("denied" in callback) throw new Stop("denied");
+    emit4({ event: "connecting" });
+    const redeemed = await api.redeem(login, callback.code, stop.signal);
+    check();
+    if (!redeemed.ok) throw stopFor(redeemed);
+    const issued = { ...login, phase: "issued", apiKey: redeemed.apiKey };
+    journal.login = issued;
+    await saveJournal(keychain, journal);
+    check();
+    const confirmed = await api.confirm(issued, stop.signal);
+    check();
+    if (!confirmed.ok) throw stopFor(confirmed);
+    const current = (await loadJournal(keychain)).login;
+    if (current?.requestId !== issued.requestId || current.phase !== "issued") {
+      throw new Stop("lock_lost");
+    }
+    journal.login = { ...issued, phase: "committing", ...previous ? { previous } : {} };
+    await saveJournal(keychain, journal);
+    check();
+    if ((await snapshot(keychain)).token !== base.token) throw new Stop("credential_changed");
+    check();
+    const fingerprint = credentialFingerprint(endpoint, redeemed.apiKey);
+    try {
+      await keychain.write({
+        schemaVersion: 1,
+        endpoint,
+        apiKey: redeemed.apiKey,
+        connection: redeemed.connection,
+        provenance: "browser-login"
+      });
+    } catch (err) {
+      if ((await snapshot(keychain)).token !== fingerprint) throw err;
+    }
+    connected = { connection: redeemed.connection, fingerprint };
+  } catch (err) {
+    if (err instanceof Stop) outcome = err.outcome;
+    else if (err instanceof JournalInvalidError) outcome = "journal_invalid";
+    else if (err instanceof KeychainError) {
+      storeError = err;
+      outcome = "credential_store_unavailable";
+    } else outcome = "login_failed";
+  }
+  listener?.close();
+  lines?.close();
+  process.off("SIGINT", cancel);
+  process.off("SIGTERM", cancel);
+  let cleanupPending = outcome !== "busy";
+  if (journal !== null && !lockLost) {
+    try {
+      cleanupPending = !isEmpty(await settle(keychain, api, journal, () => lockLost));
+    } catch {
+      cleanupPending = true;
+    }
+  }
+  if (release !== null) await releaseLifecycleLock(release);
+  if (connected !== null) {
+    emit4({
+      event: "connected",
+      connection: connected.connection,
+      credentialFingerprint: connected.fingerprint,
+      cleanupPending
+    });
+    return EXIT.OK;
+  }
+  if (outcome === "requested" || outcome === "denied") {
+    emit4({ event: "cancelled", reason: outcome, cleanupPending });
+    return EXIT.CANCELLED;
+  }
+  const code = outcome ?? "login_failed";
+  emit4({
+    event: "error",
+    code,
+    message: storeError ? `${storeError.message} ${storeError.guidance}` : ERROR_MESSAGES[code].message,
+    retryable: ERROR_MESSAGES[code].retryable,
+    cleanupPending
+  });
+  return storeError?.exit ?? exitFor(code);
+}
+
 // src/cli/commands/logout.ts
+function lifecycleFailure(code, cleanupPending, err) {
+  return {
+    ok: false,
+    code,
+    // Keychain guidance is static text; any other error's text is never shown.
+    message: err instanceof KeychainError ? `${err.message} ${err.guidance}` : ERROR_MESSAGES[code].message,
+    retryable: ERROR_MESSAGES[code].retryable,
+    cleanupPending
+  };
+}
+async function cleanupPendingAfterFailure(keychain) {
+  try {
+    return !isEmpty(await loadJournal(keychain));
+  } catch {
+    return true;
+  }
+}
 async function logoutCommand(opts = {}) {
-  const provider = opts.keychain ?? getDefaultKeychain();
+  const keychain = opts.keychain ?? getLifecycleKeychain();
+  const api = createCliLoginApi(opts.fetchImpl);
+  const fail = (failure2, exit) => {
+    if (opts.json) process.stdout.write(`${JSON.stringify(failure2)}
+`);
+    else process.stderr.write(`Error: ${failure2.message}
+`);
+    return exit;
+  };
   try {
-    await provider.delete();
-    process.stdout.write("pyx-memory credentials deleted from OS credential store.\n");
-    return EXIT.OK;
+    const result = await withLifecycleLock(keychain, (lockLost) => logout(lockLost));
+    return result === BUSY ? fail(lifecycleFailure("busy", false), EXIT.BUSY) : result;
   } catch (err) {
+    const pending = await cleanupPendingAfterFailure(keychain);
     if (err instanceof KeychainError) {
-      process.stderr.write(`Error: ${err.message}
-${err.guidance}
+      return fail(lifecycleFailure("credential_store_unavailable", pending, err), err.exit);
+    }
+    if (err instanceof LockLostError) {
+      return fail(lifecycleFailure("lock_lost", pending), EXIT.DOCTOR_FAIL);
+    }
+    if (err instanceof JournalInvalidError) {
+      return fail(lifecycleFailure("journal_invalid", true), EXIT.DOCTOR_FAIL);
+    }
+    return fail(lifecycleFailure("cleanup_pending", true), EXIT.CLEANUP_PENDING);
+  }
+  async function logout(lockLost) {
+    const journal = await loadJournal(keychain);
+    const selected = await keychain.read().catch((err) => {
+      if (err instanceof KeychainError && err.code === "credential-record-invalid") {
+        return "unreadable";
+      }
+      throw err;
+    });
+    const managed = selected !== null && selected !== "unreadable" && selected.provenance === "browser-login" && isKeyRef({ endpoint: selected.endpoint, apiKey: selected.apiKey }) ? { endpoint: selected.endpoint, apiKey: selected.apiKey } : null;
+    if (selected === null || selected === "unreadable") {
+      await keychain.delete();
+    } else {
+      journal.logout = {
+        fingerprint: credentialFingerprint(selected.endpoint, selected.apiKey),
+        revoke: managed
+      };
+      await saveJournal(keychain, journal);
+    }
+    const cleanupPending = !isEmpty(await settle(keychain, api, journal, lockLost));
+    if (await keychain.read() !== null) {
+      return fail(lifecycleFailure("credential_changed", cleanupPending), EXIT.DOCTOR_FAIL);
+    }
+    if (lockLost()) throw new LockLostError();
+    const convergence = convergenceSeconds(journal);
+    const revocationPending = journal.revoke.length > 0;
+    const serverRevocation = revocationPending ? "pending" : convergence !== null ? "revoked" : "not_attempted";
+    const legacy = selected !== null && managed === null;
+    const report4 = {
+      ok: true,
+      credentialKind: selected === null ? null : managed !== null ? "browser" : "legacy",
+      localDeleted: selected !== null,
+      serverRevocation,
+      cleanupPending,
+      reconnectRequired: selected !== null || serverRevocation !== "not_attempted",
+      // Proxies older than the per-request credential check hold the key in
+      // memory. A key that is still valid on the server keeps them working.
+      pendingLegacySessions: legacy || revocationPending,
+      serverConvergenceSeconds: convergence
+    };
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(report4)}
 `);
-      return err.exit;
+    } else {
+      process.stdout.write(
+        selected === null ? "No pyx-memory credentials were stored.\n" : "pyx-memory credentials deleted from OS credential store.\n"
+      );
+      if (cleanupPending) {
+        process.stderr.write(
+          "The server-side key could not be revoked yet. Run: pyx-mem login-recovery\n"
+        );
+      } else if (report4.pendingLegacySessions) {
+        process.stdout.write(
+          "The API key itself was not revoked (other computers may use it). Restart running agents; revoke the key in the dashboard to end it everywhere.\n"
+        );
+      }
     }
+    return cleanupPending ? EXIT.CLEANUP_PENDING : EXIT.OK;
+  }
+}
+
+// src/cli/commands/login-recovery.ts
+async function signOutJournal(keychain) {
+  const journal = emptyJournal();
+  const shared = await keychain.read().catch((err) => {
+    if (err instanceof KeychainError && err.code === "credential-record-invalid") return null;
     throw err;
+  });
+  if (shared !== null) {
+    const key = { endpoint: shared.endpoint, apiKey: shared.apiKey };
+    journal.logout = {
+      fingerprint: credentialFingerprint(shared.endpoint, shared.apiKey),
+      revoke: shared.provenance === "browser-login" && isKeyRef(key) ? key : null
+    };
+  }
+  await saveJournal(keychain, journal);
+  return journal;
+}
+async function loginRecoveryCommand(opts = {}) {
+  const keychain = opts.keychain ?? getLifecycleKeychain();
+  const fail = (failure2, exit) => {
+    if (opts.json) process.stdout.write(`${JSON.stringify(failure2)}
+`);
+    else process.stderr.write(`Error: ${failure2.message}
+`);
+    return exit;
+  };
+  try {
+    const journal = await withLifecycleLock(keychain, async (lockLost) => {
+      const loaded = await loadJournal(keychain).catch((err) => {
+        if (err instanceof JournalInvalidError && opts.discardUnreadableJournal) {
+          return signOutJournal(keychain);
+        }
+        throw err;
+      });
+      const settled = await settle(keychain, createCliLoginApi(opts.fetchImpl), loaded, lockLost);
+      if (lockLost()) throw new LockLostError();
+      return settled;
+    });
+    if (journal === BUSY) return fail(lifecycleFailure("busy", true), EXIT.BUSY);
+    if (!isEmpty(journal)) {
+      return fail(lifecycleFailure("cleanup_pending", true), EXIT.CLEANUP_PENDING);
+    }
+    const convergence = convergenceSeconds(journal);
+    const report4 = {
+      ok: true,
+      cleanupPending: false,
+      serverRevocation: convergence !== null ? "revoked" : "not_attempted",
+      serverConvergenceSeconds: convergence
+    };
+    if (opts.json) process.stdout.write(`${JSON.stringify(report4)}
+`);
+    else process.stdout.write("Nothing is pending.\n");
+    return EXIT.OK;
+  } catch (err) {
+    if (err instanceof JournalInvalidError) {
+      return fail(lifecycleFailure("journal_invalid", true), EXIT.DOCTOR_FAIL);
+    }
+    const pending = await cleanupPendingAfterFailure(keychain);
+    if (err instanceof KeychainError) {
+      return fail(lifecycleFailure("credential_store_unavailable", pending, err), err.exit);
+    }
+    if (err instanceof LockLostError) {
+      return fail(lifecycleFailure("lock_lost", pending), EXIT.DOCTOR_FAIL);
+    }
+    return fail(lifecycleFailure("cleanup_pending", true), EXIT.CLEANUP_PENDING);
   }
 }
 
@@ -925,7 +2029,7 @@ function createReadCredentials(providerFactory) {
 }
 
 // src/mcp/proxy-server.ts
-import { createHash, randomUUID as randomUUID3 } from "crypto";
+import { createHash as createHash4, randomUUID as randomUUID3 } from "crypto";
 import { readFile, stat } from "fs/promises";
 import { basename, isAbsolute, resolve } from "path";
 import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
@@ -954,13 +2058,39 @@ function createMcpIdempotentFetch(fetchImpl = fetch, sessionNonce = randomUUID3(
       if (typeof body !== "string") {
         throw new Error("remote MCP POST body must be text for stable request idempotency");
       }
-      const key = createHash("sha256").update("pyx-mcp-idempotency-v1\0").update(sessionNonce).update("\0").update(body).digest("hex");
+      const key = createHash4("sha256").update("pyx-mcp-idempotency-v1\0").update(sessionNonce).update("\0").update(body).digest("hex");
       headers.set("Idempotency-Key", `mcp-${key}`);
     }
     return fetchImpl(input, { ...init, method, headers, body });
   };
   return Object.assign(wrapped, { preconnect: fetch.preconnect });
 }
+function resultText(result) {
+  return result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();
+}
+function createCredentialGuard(readCredentials, snapshot2) {
+  return async () => {
+    const read = await readCredentials();
+    if (!read.ok) {
+      throw new Error(
+        `${resultText(read.result) || "pyx-memory credentials are unavailable. Run: pyx-mem login"}
+This attempt was not sent. Then reconnect the pyx-memory MCP server.`
+      );
+    }
+    if (read.credentials.endpoint !== snapshot2.endpoint || read.credentials.apiKey !== snapshot2.apiKey) {
+      throw new Error(
+        "pyx-memory credentials changed since this MCP session started (different endpoint or account). This attempt was not sent. Reconnect the pyx-memory MCP server to use the current sign-in."
+      );
+    }
+  };
+}
+function createGuardedFetch(guard, fetchImpl = fetch) {
+  const wrapped = async (input, init) => {
+    await guard();
+    return fetchImpl(input, init);
+  };
+  return Object.assign(wrapped, { preconnect: fetch.preconnect });
+}
 function extractLocalUpload(meta) {
   if (meta === null || typeof meta !== "object") return void 0;
   const descriptor = meta[LOCAL_UPLOAD_META_KEY];
@@ -1003,24 +2133,31 @@ async function readCappedLocalFile(rawPath, descriptor) {
     };
   }
 }
-function createLocalFileUploader(credentials, fetchImpl = fetch) {
+function createLocalFileUploader(credentials, readCredentials, fetchImpl = fetch) {
+  const guard = createCredentialGuard(readCredentials, credentials);
   return async (descriptor, args) => {
-    const file = await readCappedLocalFile(args[descriptor.pathArg], descriptor);
-    if (!file.ok) return file.result;
-    const http = createHttpClient(credentials, fetchImpl);
-    const res = await http.requestMultipart({
-      path: descriptor.endpoint,
-      formData: () => {
-        const form = new FormData();
-        form.set(descriptor.fileField, new File([new Uint8Array(file.bytes)], file.name));
-        for (const key of descriptor.optionalArgs ?? []) {
-          const value = args[key];
-          if (typeof value === "string" && value.length > 0) form.set(key, value);
+    try {
+      await guard();
+      const file = await readCappedLocalFile(args[descriptor.pathArg], descriptor);
+      if (!file.ok) return file.result;
+      const http = createHttpClient(credentials, fetchImpl);
+      const res = await http.requestMultipart({
+        path: descriptor.endpoint,
+        formData: async () => {
+          await guard();
+          const form = new FormData();
+          form.set(descriptor.fileField, new File([new Uint8Array(file.bytes)], file.name));
+          for (const key of descriptor.optionalArgs ?? []) {
+            const value = args[key];
+            if (typeof value === "string" && value.length > 0) form.set(key, value);
+          }
+          return form;
         }
-        return form;
-      }
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
+      });
+      return res.ok ? mcpJson(res.data) : res.result;
+    } catch (err) {
+      return mcpText(err instanceof Error ? err.message : String(err), true);
+    }
   };
 }
 function createProxyServer(client, version, uploadLocalFile) {
@@ -1086,18 +2223,21 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.21.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.23.0" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
-    const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();
-    throw new Error(text || "pyx-memory credentials are unavailable. Run: pyx-mem login");
+    throw new Error(
+      resultText(read.result) || "pyx-memory credentials are unavailable. Run: pyx-mem login"
+    );
   }
   const { endpoint, apiKey } = read.credentials;
   const url = new URL(`${endpoint.replace(/\/+$/, "")}${REMOTE_MCP_PATH}`);
   const client = new McpClient({ name: "pyx-mem-proxy", version }, { capabilities: {} });
   const clientTransport = new StreamableHTTPClientTransport(url, {
     requestInit: { headers: { Authorization: `Bearer ${apiKey}` } },
-    fetch: createMcpIdempotentFetch()
+    fetch: createMcpIdempotentFetch(
+      createGuardedFetch(createCredentialGuard(opts.readCredentials, read.credentials))
+    )
   });
   try {
     await client.connect(clientTransport);
@@ -1108,12 +2248,18 @@ async function runMcpProxyServer(opts) {
     );
   }
   try {
-    const server = createProxyServer(client, version, createLocalFileUploader(read.credentials));
+    const server = createProxyServer(
+      client,
+      version,
+      createLocalFileUploader(read.credentials, opts.readCredentials)
+    );
     const transport = new StdioServerTransport();
     const closed = new Promise((resolve3) => {
       transport.onclose = () => resolve3();
     });
+    process.stdin.once("end", () => void transport.close());
     await server.connect(transport);
+    void opts.onConnected?.(client);
     await closed;
   } finally {
     await client.close().catch(() => {
@@ -1124,12 +2270,12 @@ async function runMcpProxyServer(opts) {
 // src/cli/commands/mcp-install.ts
 import { spawnSync as nodeSpawnSync } from "child_process";
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 
 // src/cli/commands/mcp-install-merge.ts
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
-import { dirname } from "path";
+import { dirname as dirname2 } from "path";
 function mergeWriteJsonMcpEntry(opts) {
   const { filePath, serverName, entry } = opts;
   let existingDoc = {};
@@ -1191,7 +2337,7 @@ Remove or rename the existing entry, then re-run.
   const nextDoc = { ...existingDoc, mcpServers: servers };
   const payload = `${JSON.stringify(nextDoc, null, 2)}
 `;
-  const parent = dirname(filePath);
+  const parent = dirname2(filePath);
   if (!existsSync(parent)) {
     mkdirSync(parent, { recursive: true });
   }
@@ -1244,7 +2390,7 @@ function indent(text) {
 
 // src/cli/commands/memory-rules-merge.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 var RULES_BEGIN_MARKER = "<!-- pyx-memory:begin (managed by `pyx-mem mcp install`; edit outside these markers) -->";
 var RULES_END_MARKER = "<!-- pyx-memory:end -->";
 var BEGIN_MARKER_PREFIX = "<!-- pyx-memory:begin";
@@ -1375,7 +2521,7 @@ function writeMemoryRulesFile(opts) {
 `
     };
   }
-  const parent = dirname2(filePath);
+  const parent = dirname3(filePath);
   if (!existsSync2(parent)) mkdirSync2(parent, { recursive: true });
   const mode = fileExists ? statSync(filePath).mode & 511 : 420;
   const tmpPath = `${filePath}.tmp`;
@@ -1446,18 +2592,27 @@ function mcpInstallCodexCommand(opts = {}) {
   if (!validateScope(scope)) return EXIT.USAGE;
   const remote = opts.remote ?? false;
   const spawnSync = opts._spawnSync ?? nodeSpawnSync;
-  const home = opts._homeDir ?? homedir();
+  const home = opts._homeDir ?? homedir2();
+  const codexHome = (opts._env ?? process.env).CODEX_HOME;
   const probe = spawnSync("codex", ["--version"], { stdio: "pipe" });
   if (probe.error || probe.status !== 0) {
-    printCodexManualInstructions(home, remote);
+    printCodexManualInstructions(home, remote, codexHome);
     return EXIT.OK;
   }
-  const cmd = ["mcp", "add", SERVER_NAME, "--", "pyx-mem", ...pyxMemArgs(remote)];
+  const cmd = [
+    "mcp",
+    "add",
+    SERVER_NAME,
+    ...codexHome ? ["--env", `CODEX_HOME=${codexHome}`] : [],
+    "--",
+    "pyx-mem",
+    ...pyxMemArgs(remote)
+  ];
   const res = spawnSync("codex", cmd, { stdio: "inherit" });
   if (res.status !== 0) {
     process.stderr.write(`\`codex ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
 `);
-    printCodexManualInstructions(home, remote);
+    printCodexManualInstructions(home, remote, codexHome);
     return EXIT.USAGE;
   }
   process.stdout.write(
@@ -1467,20 +2622,21 @@ Restart Codex CLI to make the tools available. No API key was written to config.
   );
   return EXIT.OK;
 }
-function printCodexManualInstructions(home, remote) {
-  const configPath = join(home, ".codex", "config.toml");
+function printCodexManualInstructions(home, remote, codexHome) {
+  const configPath = join2(codexHome ?? join2(home, ".codex"), "config.toml");
   process.stdout.write(
     [
       "The `codex` CLI is not on PATH, or the install command failed.",
       "",
       "Run this once Codex CLI is installed:",
-      `  codex mcp add ${SERVER_NAME} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
+      `  codex mcp add ${SERVER_NAME}${codexHome ? ` --env ${JSON.stringify(`CODEX_HOME=${codexHome}`)}` : ""} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
       "",
       `Or add this section manually to ${configPath}:`,
       "",
       `[mcp_servers.${SERVER_NAME}]`,
       `command = "pyx-mem"`,
       `args = ${JSON.stringify(pyxMemArgs(remote))}`,
+      ...codexHome ? [`env = { CODEX_HOME = ${JSON.stringify(codexHome)} }`] : [],
       "",
       "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
       ""
@@ -1490,8 +2646,8 @@ function printCodexManualInstructions(home, remote) {
 function mcpInstallCursorCommand(opts = {}) {
   const scope = opts.scope ?? "user";
   if (!validateScope(scope)) return EXIT.USAGE;
-  const home = opts._homeDir ?? homedir();
-  const filePath = scope === "project" ? join(process.cwd(), ".cursor", "mcp.json") : join(home, ".cursor", "mcp.json");
+  const home = opts._homeDir ?? homedir2();
+  const filePath = scope === "project" ? join2(process.cwd(), ".cursor", "mcp.json") : join2(home, ".cursor", "mcp.json");
   return writeJsonAndReport(filePath, "Cursor", mcpEntry(opts.remote ?? false));
 }
 function mcpInstallClineCommand(opts = {}) {
@@ -1522,8 +2678,8 @@ function mcpInstallContinueCommand(opts = {}) {
   const scope = opts.scope ?? "user";
   if (!validateScope(scope)) return EXIT.USAGE;
   const remote = opts.remote ?? false;
-  const home = opts._homeDir ?? homedir();
-  const yamlPath = join(home, ".continue", "mcpServers", `${SERVER_NAME}.yaml`);
+  const home = opts._homeDir ?? homedir2();
+  const yamlPath = join2(home, ".continue", "mcpServers", `${SERVER_NAME}.yaml`);
   process.stdout.write(
     [
       "Continue uses YAML config. The recommended way to add an MCP server is a",
@@ -1554,8 +2710,8 @@ function mcpInstallContinueCommand(opts = {}) {
 function mcpInstallWindsurfCommand(opts = {}) {
   const scope = opts.scope ?? "user";
   if (!validateScope(scope)) return EXIT.USAGE;
-  const home = opts._homeDir ?? homedir();
-  const filePath = join(home, ".codeium", "windsurf", "mcp_config.json");
+  const home = opts._homeDir ?? homedir2();
+  const filePath = join2(home, ".codeium", "windsurf", "mcp_config.json");
   return writeJsonAndReport(filePath, "Windsurf", mcpEntry(opts.remote ?? false));
 }
 function mcpInstallGeminiCliCommand(opts = {}) {
@@ -1563,7 +2719,7 @@ function mcpInstallGeminiCliCommand(opts = {}) {
   if (!validateScope(scope)) return EXIT.USAGE;
   const remote = opts.remote ?? false;
   const spawnSync = opts._spawnSync ?? nodeSpawnSync;
-  const home = opts._homeDir ?? homedir();
+  const home = opts._homeDir ?? homedir2();
   const probe = spawnSync("gemini", ["--version"], { stdio: "pipe" });
   if (probe.error || probe.status !== 0) {
     return writeJsonAndReport(geminiConfigPath(home, scope), "Gemini CLI", mcpEntry(remote));
@@ -1584,13 +2740,13 @@ Restart Gemini CLI to make the tools available. No API key was written to settin
   return EXIT.OK;
 }
 function geminiConfigPath(home, scope) {
-  return scope === "project" ? join(process.cwd(), ".gemini", "settings.json") : join(home, ".gemini", "settings.json");
+  return scope === "project" ? join2(process.cwd(), ".gemini", "settings.json") : join2(home, ".gemini", "settings.json");
 }
 function mcpInstallPiCommand(opts = {}) {
   const scope = opts.scope ?? "user";
   if (!validateScope(scope)) return EXIT.USAGE;
-  const home = opts._homeDir ?? homedir();
-  const filePath = scope === "user" ? join(home, ".pi", "agent", "mcp.json") : join(process.cwd(), ".pi", "mcp.json");
+  const home = opts._homeDir ?? homedir2();
+  const filePath = scope === "user" ? join2(home, ".pi", "agent", "mcp.json") : join2(process.cwd(), ".pi", "mcp.json");
   return writeJsonAndReport(filePath, "Pi", mcpEntry(opts.remote ?? false), {
     prereq: "pi has no native MCP support \u2014 install the third-party adapter once:\n  pi install npm:pi-mcp-adapter"
   });
@@ -1598,8 +2754,8 @@ function mcpInstallPiCommand(opts = {}) {
 function mcpInstallOhMyPiCommand(opts = {}) {
   const scope = opts.scope ?? "user";
   if (!validateScope(scope)) return EXIT.USAGE;
-  const home = opts._homeDir ?? homedir();
-  const filePath = scope === "user" ? join(home, ".omp", "agent", "mcp.json") : join(process.cwd(), ".omp", "mcp.json");
+  const home = opts._homeDir ?? homedir2();
+  const filePath = scope === "user" ? join2(home, ".omp", "agent", "mcp.json") : join2(process.cwd(), ".omp", "mcp.json");
   return writeJsonAndReport(filePath, "oh-my-pi", mcpEntry(opts.remote ?? false));
 }
 function mcpInstallOpenClawCommand(opts = {}) {
@@ -1697,35 +2853,49 @@ function printHermesManualInstructions(remote) {
   );
 }
 var RULES_FILE_TARGETS = {
-  "claude-code": [".claude", "CLAUDE.md"],
-  codex: [".codex", "AGENTS.md"],
-  "gemini-cli": [".gemini", "GEMINI.md"],
-  "oh-my-pi": [".omp", "agent", "RULES.md"]
+  "claude-code": { envDir: "CLAUDE_CONFIG_DIR", dir: [".claude"], file: "CLAUDE.md" },
+  codex: { envDir: "CODEX_HOME", dir: [".codex"], file: "AGENTS.md" },
+  "gemini-cli": { dir: [".gemini"], file: "GEMINI.md" },
+  "oh-my-pi": { dir: [".omp", "agent"], file: "RULES.md" }
 };
+function rulesFilePath(target, opts) {
+  if (!Object.hasOwn(RULES_FILE_TARGETS, target)) return void 0;
+  const spec = RULES_FILE_TARGETS[target];
+  const env = opts._env ?? (opts._homeDir === void 0 ? process.env : {});
+  const configDir = spec.envDir ? env[spec.envDir] : void 0;
+  return configDir ? join2(configDir, spec.file) : join2(opts._homeDir ?? homedir2(), ...spec.dir, spec.file);
+}
 function installMemoryRules(opts) {
-  const segs = RULES_FILE_TARGETS[opts.target];
-  if (!segs) return;
+  const filePath = rulesFilePath(opts.target, opts);
+  if (!filePath) return;
   if (opts.noRules) {
     process.stdout.write(
       'Skipped writing the memory rules (--no-rules). The tools are installed, but the agent will reach for memory only when you ask; add the "## Persistent Memory" rules yourself to change that.\n'
     );
     return;
   }
-  const home = opts._homeDir ?? homedir();
-  const result = writeMemoryRulesFile({
-    filePath: join(home, ...segs),
-    section: PERSISTENT_MEMORY_SECTION
-  });
+  const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
   process.stdout.write(result.message);
 }
+function installMemoryRulesOnly(target, opts = {}) {
+  if (target === void 0 || !rulesFilePath(target, opts)) {
+    process.stderr.write(
+      `Error: \`pyx-mem mcp rules\` needs a host with a known rules file: ${Object.keys(RULES_FILE_TARGETS).join(", ")}.
+`
+    );
+    return EXIT.USAGE;
+  }
+  installMemoryRules({ ...opts, target, noRules: false });
+  return EXIT.OK;
+}
 function reconcileMemoryRules(opts = {}) {
-  const home = opts._homeDir ?? homedir();
-  for (const segs of Object.values(RULES_FILE_TARGETS)) {
-    const filePath = join(home, ...segs);
+  const section = opts.section ?? PERSISTENT_MEMORY_SECTION;
+  for (const target of Object.keys(RULES_FILE_TARGETS)) {
+    const filePath = rulesFilePath(target, opts);
     try {
       if (!existsSync3(filePath)) continue;
       if (!hasPyxMemoryRules(readFileSync3(filePath, "utf8"))) continue;
-      const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
+      const result = writeMemoryRulesFile({ filePath, section });
       if (result.action !== "unchanged") {
         process.stderr.write(
           `pyx-memory: refreshed the "## Persistent Memory" rules in ${filePath}
@@ -1736,6 +2906,31 @@ function reconcileMemoryRules(opts = {}) {
     }
   }
 }
+var MAX_SERVER_RULES_BYTES = 16 * 1024;
+async function syncMemoryRulesFromServer(client, opts = {}) {
+  try {
+    const { tools } = await client.listTools();
+    if (!tools.some((tool) => tool.name === "get_memory_rules")) {
+      reconcileMemoryRules(opts);
+      return;
+    }
+    const result = await client.callTool({ name: "get_memory_rules", arguments: {} });
+    const [first] = result.content ?? [];
+    const section = first?.type === "text" ? first.text : void 0;
+    if (result.isError || !section || !isRulesSection(section)) {
+      throw new Error('the server returned no valid "## Persistent Memory" section');
+    }
+    reconcileMemoryRules({ ...opts, section });
+  } catch (err) {
+    process.stderr.write(
+      `pyx-memory: left the installed memory rules unchanged \u2014 could not fetch current rules (${err instanceof Error ? err.message : String(err)}).
+`
+    );
+  }
+}
+function isRulesSection(text) {
+  return text.startsWith("## Persistent Memory\n") && Buffer.byteLength(text, "utf8") <= MAX_SERVER_RULES_BYTES && !text.includes("<!-- pyx-memory:") && !/^\s*(```|~~~)/m.test(text);
+}
 function validateScope(scope) {
   if (VALID_SCOPES.has(scope)) return true;
   process.stderr.write(`Error: invalid --scope \`${scope}\`. Expected: local | user | project.
@@ -1765,14 +2960,12 @@ function writeJsonAndReport(filePath, agentLabel, entry, opts = {}) {
 
 // src/cli/commands/mcp.ts
 async function mcpCommand() {
-  reconcileMemoryRules();
   const readCredentials = createReadCredentials(() => getDefaultKeychain());
-  const onStdinEnd = new Promise((resolve3) => {
-    process.stdin.once("end", resolve3);
-    process.stdin.once("close", resolve3);
-  });
   try {
-    await Promise.race([runMcpProxyServer({ readCredentials }), onStdinEnd]);
+    await runMcpProxyServer({
+      readCredentials,
+      onConnected: (client) => syncMemoryRulesFromServer(client)
+    });
     return EXIT.OK;
   } catch (err) {
     process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
@@ -1869,7 +3062,7 @@ function boundedLabel(value, fallback, maxChars) {
 
 // src/cli/commands/scaffold.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
-import { basename as basename2, join as join2, resolve as resolve2 } from "path";
+import { basename as basename2, join as join3, resolve as resolve2 } from "path";
 var SERVER_IMAGE = "ghcr.io/pyx-corp/pyx-memory-v1:latest";
 var DOCKER_COMPOSE = `services:
   pyx-memory:
@@ -1998,11 +3191,11 @@ function resolveTarget(args) {
 }
 function buildFiles(targetDir, appName) {
   return [
-    { path: join2(targetDir, "docker-compose.yml"), contents: DOCKER_COMPOSE },
-    { path: join2(targetDir, ".env.example"), contents: ENV_EXAMPLE },
-    { path: join2(targetDir, "memory.ts"), contents: MEMORY_TS },
+    { path: join3(targetDir, "docker-compose.yml"), contents: DOCKER_COMPOSE },
+    { path: join3(targetDir, ".env.example"), contents: ENV_EXAMPLE },
+    { path: join3(targetDir, "memory.ts"), contents: MEMORY_TS },
     {
-      path: join2(targetDir, "PYX_MEMORY_DESIGN_GUIDE.md"),
+      path: join3(targetDir, "PYX_MEMORY_DESIGN_GUIDE.md"),
       contents: buildDesignGuide({ appName })
     }
   ];
@@ -2045,9 +3238,19 @@ function scaffoldCommand(args = {}) {
 }
 
 // src/cli/commands/status.ts
-import { createHash as createHash2 } from "crypto";
+async function readLifecycle(provider) {
+  let serverConvergenceSeconds = null;
+  try {
+    const journal = await loadJournal(provider);
+    serverConvergenceSeconds = convergenceSeconds(journal);
+    if (isEmpty(journal)) return { cleanupPending: false, serverConvergenceSeconds };
+  } catch (err) {
+    if (!(err instanceof JournalInvalidError)) throw err;
+  }
+  return { cleanupPending: !await provider.isLocked(), serverConvergenceSeconds };
+}
 async function statusCommand(opts = {}) {
-  const provider = opts.keychain ?? getDefaultKeychain();
+  const provider = opts.keychain ? guardKeychain(opts.keychain) : getDefaultKeychain();
   let report4;
   try {
     const creds = await provider.read();
@@ -2056,8 +3259,10 @@ async function statusCommand(opts = {}) {
       keyPresent: creds !== null,
       keySource: creds !== null ? "keychain" : null,
       loggedIn: creds !== null,
-      credentialFingerprint: creds === null ? null : createHash2("sha256").update(`${creds.endpoint}
-${creds.apiKey}`).digest("hex").slice(0, 16)
+      credentialFingerprint: creds === null ? null : credentialFingerprint(creds.endpoint, creds.apiKey),
+      lifecycleVersion: 1,
+      connection: creds?.provenance === "browser-login" ? creds.connection ?? null : null,
+      ...await readLifecycle(provider)
     };
   } catch (err) {
     if (err instanceof KeychainError) return emitError(err, opts.json);
@@ -2135,23 +3340,35 @@ async function taxonomyCommand(opts = {}) {
     keychain: opts.keychain,
     fetchImpl: opts.fetchImpl
   });
+  const withIdentity = opts.withIdentity === true;
   if (!result.ok) {
-    emit3(report3(result.state, result.endpoint, result.keySource, result.problem));
+    emit3(
+      report3(result.state, result.endpoint, result.keySource, result.problem, {
+        withIdentity,
+        credentialFingerprint: result.credentialFingerprint
+      })
+    );
     return result.exit;
   }
   emit3({
-    ...report3("ready", result.endpoint, "keychain", null),
+    ...report3("ready", result.endpoint, "keychain", null, {
+      withIdentity,
+      credentialFingerprint: result.credentialFingerprint
+    }),
     clusters: result.data.clusters,
     totals: result.data.totals
   });
   return EXIT.OK;
 }
-function report3(state, endpoint, keySource, problem) {
+function report3(state, endpoint, keySource, problem, identity) {
   return {
     schemaVersion: TAXONOMY_SCHEMA_VERSION,
     state,
     endpoint,
     keySource,
+    // Spread, not `undefined`: JSON.stringify would drop an undefined value,
+    // but the key must be absent from the object too so exact-shape checks hold.
+    ...identity.withIdentity ? { credentialFingerprint: identity.credentialFingerprint } : {},
     clusters: [],
     totals: { clusters: 0, unnamed: 0, nodesConsidered: 0 },
     problem
@@ -2170,11 +3387,20 @@ Usage:
 
 Commands:
   login [--endpoint <url>] [--api-key <key>]   Store endpoint and API key in OS credential store.
+  login --browser [--json] [--no-open]         Sign in with your browser; the approved project key is
+                                               stored in the same place. --json emits JSONL events
+                                               for host apps; --no-open leaves opening the URL to them.
   status [--json]                              Show endpoint, key presence, MCP config status.
   overview --json                              Read memory count and three recent safe labels.
-  insights --json                              Read body-free memory usage and coverage aggregates.
-  taxonomy --json                              Read knowledge-graph cluster composition (read-only).
-  logout                                       Delete stored pyx-memory credentials.
+  insights --json [--with-identity]            Read body-free memory usage and coverage aggregates.
+  taxonomy --json [--with-identity]            Read knowledge-graph cluster composition (read-only).
+                                               --with-identity adds credentialFingerprint (the same
+                                               value as status --json) so a host can tell which
+                                               account a read was served for. Off by default.
+  logout [--json]                              Delete stored pyx-memory credentials. A browser sign-in
+                                               key is also revoked on the server; a pasted key is not.
+  login-recovery [--json]                      Finish pending sign-in/sign-out cleanup. Never signs in.
+      [--discard-unreadable-journal]           Only if told to: replace an unreadable cleanup record; signs this computer out.
   doctor [--json]                              Diagnose keychain, credentials, backend, MCP startup.
   scaffold [--name <dir>]                      Generate Docker, env, SDK, and memory design-guide starter files.
   mcp                                          Start the stdio MCP proxy to the hosted server, so
@@ -2193,6 +3419,10 @@ Commands:
                                                your other content is preserved) so memory fires by
                                                default. Pass --no-rules to skip that write.
                                                Targets: claude-code, codex, cursor, cline, continue, windsurf, gemini-cli, pi, oh-my-pi, openclaw, hermes.
+  mcp rules <target>                           Write or refresh only the always-on rules for
+                                               claude-code, codex, gemini-cli, or oh-my-pi (no MCP
+                                               registration). Honors CLAUDE_CONFIG_DIR / CODEX_HOME;
+                                               'pyx-mem mcp' keeps them current from the server.
 
 Notes:
   - Credentials are stored only in the OS credential store (Keychain / libsecret / Credential Manager).
@@ -2296,12 +3526,43 @@ function runMcpCommand(parsed) {
       parsed.flags["no-rules"] === true
     );
   }
+  if (parsed.subcommand === "rules") {
+    if (Object.keys(parsed.flags).length > 0) {
+      process.stderr.write("Error: `pyx-mem mcp rules <host>` takes no flags.\n");
+      return EXIT.USAGE;
+    }
+    return installMemoryRulesOnly(parsed.positional[0]);
+  }
   process.stderr.write(
     `Error: unknown subcommand \`mcp ${parsed.subcommand}\`. Run \`pyx-mem --help\`.
 `
   );
   return EXIT.USAGE;
 }
+var LOGIN_FLAGS = /* @__PURE__ */ new Set(["endpoint", "api-key", "browser", "json", "no-open"]);
+function runLogin(parsed) {
+  const { flags } = parsed;
+  const browser = flags.browser === true;
+  const invalid = Object.keys(flags).some((flag) => !LOGIN_FLAGS.has(flag)) || parsed.positional.length > 0 || flags.browser !== void 0 && !browser || (flags.json !== void 0 || flags["no-open"] !== void 0) && !browser || browser && flags["api-key"] !== void 0 || flags.json !== void 0 && flags.json !== true || flags["no-open"] !== void 0 && flags["no-open"] !== true;
+  if (invalid) {
+    process.stderr.write(
+      "Error: usage: pyx-mem login [--endpoint <url>] [--api-key <key>] | pyx-mem login --browser [--json] [--no-open] [--endpoint <url>]\n"
+    );
+    return EXIT.USAGE;
+  }
+  const endpoint = typeof flags.endpoint === "string" ? flags.endpoint : void 0;
+  if (browser) {
+    return browserLoginCommand({
+      endpoint,
+      json: flags.json === true,
+      noOpen: flags["no-open"] === true
+    });
+  }
+  return loginCommand({
+    endpoint,
+    apiKey: typeof flags["api-key"] === "string" ? flags["api-key"] : void 0
+  });
+}
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (parsed.flags.help === true || parsed.flags.h === true) {
@@ -2314,10 +3575,18 @@ async function main() {
       process.stdout.write(HELP_TEXT);
       return EXIT.OK;
     case "login":
-      return loginCommand({
-        endpoint: typeof parsed.flags.endpoint === "string" ? parsed.flags.endpoint : void 0,
-        apiKey: typeof parsed.flags["api-key"] === "string" ? parsed.flags["api-key"] : void 0
+      return runLogin(parsed);
+    case "login-recovery":
+      return loginRecoveryCommand({
+        json: parsed.flags.json === true,
+        discardUnreadableJournal: parsed.flags["discard-unreadable-journal"] === true
       });
+    case "lifecycle-capabilities":
+      process.stdout.write(
+        `${JSON.stringify({ schemaVersion: 1, browserLogin: true, sharedCredentialGuard: true })}
+`
+      );
+      return EXIT.OK;
     case "status":
       return statusCommand({ json: parsed.flags.json === true });
     case "overview":
@@ -2331,15 +3600,15 @@ async function main() {
         process.stderr.write("Error: `pyx-mem insights` requires --json.\n");
         return EXIT.USAGE;
       }
-      return insightsCommand();
+      return insightsCommand({ withIdentity: parsed.flags["with-identity"] === true });
     case "taxonomy":
       if (parsed.flags.json !== true) {
         process.stderr.write("Error: `pyx-mem taxonomy` requires --json.\n");
         return EXIT.USAGE;
       }
-      return taxonomyCommand();
+      return taxonomyCommand({ withIdentity: parsed.flags["with-identity"] === true });
     case "logout":
-      return logoutCommand();
+      return logoutCommand({ json: parsed.flags.json === true });
     case "doctor":
       return doctorCommand({ json: parsed.flags.json === true });
     case "scaffold":