aegis-desktop 0.4.5 → 0.5.1

package/lib/settings.js

@@ -186,11 +186,25 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     return decrypt(cfg.key);
   }
 
+  /**
+   * When this host last wrote its own AEGIS key (ISO string, or null).
+   *
+   * The shared credential file records the same thing, and startup compares the
+   * two so the most recently saved key wins. Without a stamp the app cannot tell
+   * "I saved this last week" from "the user ran `aegiscode login` a minute ago
+   * with a rotated key", and would silently keep presenting the stale one.
+   */
+  function aegisKeySavedAt() {
+    const cfg = load()[AEGIS_KEY_NAMESPACE] || {};
+    return cfg.savedAt || null;
+  }
+
   function setAegisKey(key) {
     const data = load();
     data[AEGIS_KEY_NAMESPACE] = {
       ...(data[AEGIS_KEY_NAMESPACE] || {}),
       key: key ? encrypt(key) : null,
+      savedAt: key ? new Date().toISOString() : null,
     };
     save(data);
     return aegisKey();
@@ -278,6 +292,7 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     maskKey,
     aegisKey,
     aegisRawKey,
+    aegisKeySavedAt,
     setAegisKey,
     migrateLegacyAegisKey,
     quickLauncherConfig,

package/lib/sync/sessions.js

@@ -1,219 +1,93 @@
 'use strict';
 
 /**
- * sessions.js — local conversation persistence (plan P1 §5.1 / P3 §7).
- * Every session (any model class) persists to <dir>/sessions.json on each
- * message with a crash-safe temp-file rename. Pure Node + injectable dir,
- * so it unit-tests without Electron.
+ * sessions.js — the desktop's session store, now a thin binding over the
+ * SHARED store in `client/session-store.js`.
+ *
+ * This file used to be the implementation. It was the desktop's private
+ * `sessions.json`, while the terminal host kept `~/.aegiscode/history.jsonl`
+ * and the MCP plugin could see neither — three hosts, one account, three
+ * disjoint views of the conversation. The implementation now lives in
+ * `client/session-store.js`, which is the tree all three hosts already bundle,
+ * and every call here forwards to it.
+ *
+ * Two things that matter are deliberately unchanged:
+ *
+ *   * the public API and its argument order (`(dir, …)` first) — `main.js`, the
+ *     sync dispatch and `test/sync-sessions.test.mjs` call it by those names;
+ *   * the record shape — `pending`, `seq`, `updatedAt`, `remoteId`,
+ *     `lastSyncedAt`, `__seq` all keep their meaning, because cloud sync and
+ *     the renderer's session list read them.
+ *
+ * The only real change is *where* `dir` points: main.js now passes the shared
+ * data dir (see `resolveStoreDir`), so a session typed in the terminal appears
+ * in the desktop's list without a network round trip.
+ *
+ * Resolution mirrors main.js's own pattern for the shared client: `client/` in
+ * a source checkout, `vendor/` in the packaged app (electron-builder cannot
+ * reach outside the app dir, so predist.mjs stages the file).
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-
-function sessionsFile(dir) {
-  return path.join(dir, 'sessions.json');
-}
-
-function load(dir) {
+const shared = (() => {
   try {
-    return JSON.parse(fs.readFileSync(sessionsFile(dir), 'utf8')) || {};
+    return require('../../../client/session-store.js');
   } catch {
-    return {};
+    return require('../../vendor/session-store.js');
   }
-}
-
-/**
- * Monotonic write counter stored in the file's `__seq` field. Every mutation
- * bumps it, so sessions written in the same millisecond still order
- * deterministically (listSessions sorts by updatedAt, then by seq).
- */
-function nextSeq(sessions) {
-  const seq = (typeof sessions.__seq === 'number' ? sessions.__seq : 0) + 1;
-  sessions.__seq = seq;
-  return seq;
-}
+})();
 
-/**
- * Normalize a remote `updated_at`/`updatedAt` to epoch milliseconds. The cloud
- * returns an ISO-8601 string (e.g. "2026-07-16T14:20:00"); the local store
- * uses `Date.now()` epoch-ms numbers. Comparing the two directly coerces the
- * string to NaN, which breaks last-write-wins ordering. ISO strings are
- * parsed; epoch-ms numbers pass through; anything else becomes 0.
- */
-function toEpochMs(value) {
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
-  if (typeof value === 'string' && value.trim()) {
-    const ms = Date.parse(value);
-    if (Number.isFinite(ms)) return ms;
+const credentials = (() => {
+  try {
+    return require('../../../client/credentials.js');
+  } catch {
+    return require('../../vendor/credentials.js');
   }
-  return 0;
-}
-
-function atomicWrite(file, data) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
-  fs.renameSync(tmp, file);
-}
-
-function save(dir, sessions) {
-  atomicWrite(sessionsFile(dir), sessions);
-}
-
-/**
- * Create or merge a full session record. Any local write (`upsertSession` /
- * `appendMessage`) marks the session `pending: true` — it has local content
- * the cloud hasn't seen yet. Only `markSynced()` clears the flag, so a push
- * that fails (offline/no key) never silently drops the session from the
- * retry queue.
- */
-function upsertSession(dir, session) {
-  const id = session && session.id;
-  if (!id) throw new Error('session.id is required');
-  const sessions = load(dir);
-  const prev = sessions[id] || { messages: [] };
-  sessions[id] = { ...prev, ...session, id, pending: true };
-  if (!sessions[id].updatedAt) sessions[id].updatedAt = Date.now();
-  sessions[id].seq = nextSeq(sessions);
-  save(dir, sessions);
-  return sessions[id];
-}
-
-/** Append one message to a session (crash-safe). */
-function appendMessage(dir, sessionId, message) {
-  if (!sessionId) throw new Error('sessionId is required');
-  const sessions = load(dir);
-  const session = sessions[sessionId] || { id: sessionId, messages: [] };
-  const messages = Array.isArray(session.messages) ? session.messages : [];
-  session.messages = messages.concat(message);
-  session.updatedAt = Date.now();
-  session.pending = true;
-  session.seq = nextSeq(sessions);
-  sessions[sessionId] = session;
-  save(dir, sessions);
-  return session;
-}
-
-function listSessions(dir) {
-  const sessions = load(dir);
-  return Object.values(sessions)
-    .filter((s) => s && s.id)
-    .sort(
-      (a, b) =>
-        (b.updatedAt || 0) - (a.updatedAt || 0) ||
-        (b.seq || 0) - (a.seq || 0)
-    );
-}
-
-function getSession(dir, id) {
-  return load(dir)[id] || null;
-}
-
-function deleteSession(dir, id) {
-  const sessions = load(dir);
-  delete sessions[id];
-  save(dir, sessions);
-  return { ok: true };
-}
-
-/** Clear the pending flag after a successful cloud push. `remote.remoteId`,
- *  when the server assigns its own conversation id, is stashed alongside. */
-function markSynced(dir, id, remote) {
-  const sessions = load(dir);
-  const session = sessions[id];
-  if (!session) return null;
-  session.pending = false;
-  session.lastSyncedAt = Date.now();
-  if (remote && remote.remoteId) session.remoteId = remote.remoteId;
-  session.seq = nextSeq(sessions);
-  sessions[id] = session;
-  save(dir, sessions);
-  return session;
-}
-
-/** Force a session back into the retry queue (e.g. a push that partially failed). */
-function markPending(dir, id) {
-  const sessions = load(dir);
-  const session = sessions[id];
-  if (!session) return null;
-  session.pending = true;
-  session.seq = nextSeq(sessions);
-  sessions[id] = session;
-  save(dir, sessions);
-  return session;
-}
-
-/** Sessions with local content the cloud hasn't confirmed yet (including
- *  sessions predating this field, which default to pending). */
-function listPending(dir) {
-  return listSessions(dir).filter((s) => s.pending !== false);
-}
+})();
 
 /**
- * Merge remote conversation-sync records into the local store (pull half of
- * sync). Last-write-wins by `updatedAt`, but a local session with unsynced
- * edits (`pending`) always wins over the remote copy — it will overwrite the
- * remote copy on the next push instead.
+ * The directory the shared store lives in: `$AEGISCODE_HOME` or `~/.aegiscode`.
+ * `legacyDir` (Electron's userData) is only used to adopt a pre-unification
+ * store, never to read sessions from afterwards.
  */
-function mergeRemoteSessions(dir, remoteSessions) {
-  const list = Array.isArray(remoteSessions) ? remoteSessions : [];
-  const sessions = load(dir);
-  let merged = 0;
-  for (const remote of list) {
-    const id = remote && (remote.session_id || remote.id);
-    if (!id) continue;
-    const local = sessions[id];
-    const remoteUpdatedAt = toEpochMs(remote.updated_at ?? remote.updatedAt);
-    if (local && (local.pending || (local.updatedAt || 0) >= remoteUpdatedAt)) {
-      continue;
-    }
-    sessions[id] = {
-      id,
-      title: remote.title || (local && local.title) || '',
-      messages: Array.isArray(remote.messages) ? remote.messages : [],
-      updatedAt: remoteUpdatedAt || Date.now(),
-      pending: false,
-      lastSyncedAt: Date.now(),
-      remoteId: remote.session_id || remote.id,
-    };
-    sessions[id].seq = nextSeq(sessions);
-    merged += 1;
-  }
-  if (merged) save(dir, sessions);
-  return merged;
+function resolveStoreDir(legacyDir) {
+  const dir = credentials.aegisHome();
+  if (legacyDir && legacyDir !== dir) adopt(dir, legacyDir);
+  return dir;
 }
 
-/**
- * Markdown export (session export, plan: Save as.../Export session). Each
- * message becomes a `## Role` heading followed by its content verbatim —
- * content is never re-escaped or re-wrapped, so any code fences a message
- * already contains (assistant replies routinely have them) survive untouched
- * instead of being nested inside an outer fence.
- */
-function toMarkdown(session) {
-  const title = (session && (session.title || session.id)) || 'session';
-  const messages = (session && Array.isArray(session.messages)) ? session.messages : [];
-  const lines = [`# ${title}`, ''];
-  for (const message of messages) {
-    const role = (message && message.role) || 'unknown';
-    const heading = role.charAt(0).toUpperCase() + role.slice(1);
-    const content = (message && (message.content || message.text)) || '';
-    lines.push(`## ${heading}`, '', content, '');
-  }
-  return lines.join('\n');
-}
+const {
+  storeFile,
+  load,
+  save,
+  upsertSession,
+  appendMessage,
+  recordExchange,
+  listSessions,
+  getSession,
+  deleteSession,
+  markSynced,
+  markPending,
+  listPending,
+  mergeRemoteSessions,
+  listSummaries,
+  readTranscript,
+  adopt,
+  toMarkdown,
+  toJson,
+} = shared;
 
-/** JSON export: the session record as stored, pretty-printed. */
-function toJson(session) {
-  return JSON.stringify(session, null, 2);
-}
+/** Kept under its old name — main.js and the tests call `sessionsFile`. */
+const sessionsFile = storeFile;
 
 module.exports = {
   sessionsFile,
+  storeFile,
+  resolveStoreDir,
   load,
   save,
   upsertSession,
   appendMessage,
+  recordExchange,
   listSessions,
   getSession,
   deleteSession,
@@ -221,6 +95,9 @@ module.exports = {
   markPending,
   listPending,
   mergeRemoteSessions,
+  listSummaries,
+  readTranscript,
+  adopt,
   toMarkdown,
   toJson,
 };

package/main.js

@@ -36,6 +36,17 @@ try {
 }
 const { createClient } = sharedClient;
 
+// The shared credential store (`client/credentials.js`) — the same 0600 file
+// the terminal host writes with `aegiscode login` and the MCP plugin reads. The
+// app resolves its own account key through it, so signing in once serves all
+// three hosts; see resolveStartupKey() and persistApiKey() below.
+let credentials;
+try {
+  credentials = require('../client/credentials.js');
+} catch {
+  credentials = require('./vendor/credentials.js');
+}
+
 let electron = null;
 try {
   // In plain Node (CI smoke test, `node --check`) this either throws
@@ -666,14 +677,24 @@ function resolveUserDataDir(app) {
  * Wire the real LocalEngine registry: settings store + ollama/providers
  * transports + the shared cloud client. Transport-only — no brain logic.
  */
-function createEngine(aegis, { app, safeStorage, dir: dirOverride } = {}) {
-  const dir = dirOverride || resolveUserDataDir(app);
-  const settings = createSettingsStore({ dir, safeStorage });
+function createEngine(aegis, { app, safeStorage, dir: dirOverride, sessionsDir: sessionsOverride } = {}) {
+  // Settings (the safeStorage-encrypted key, window state, provider entries)
+  // stay in Electron's userData: they are this host's own, and the key is only
+  // readable by this process.
+  const settingsDir = dirOverride || resolveUserDataDir(app);
+  const settings = createSettingsStore({ dir: settingsDir, safeStorage });
   // Relocate a pre-fix `settings['aegis']` key into the reserved namespace so
   // it stops showing up as a provider. Ciphertext-level, so safe pre-'ready'.
   settings.migrateLegacyAegisKey();
   const engine = createLocalEngine({ aegis, settings, ollama, providers });
-  return { engine, sessionsDir: dir, settings };
+  // Sessions/memory live in the SHARED data dir ($AEGISCODE_HOME or
+  // ~/.aegiscode) — the same file the terminal host and the MCP plugin read —
+  // so a thread started in either shows up in the other without cloud sync and
+  // without a key. resolveStoreDir() also adopts a pre-unification
+  // userData/sessions.json, once, when the shared store is still empty, so an
+  // upgrade does not look like every conversation was deleted.
+  const sessionsDir = sessionsOverride || sessionStore.resolveStoreDir(settingsDir);
+  return { engine, sessionsDir, settingsDir, settings };
 }
 
 /**
@@ -1233,7 +1254,7 @@ function bootstrap() {
     else pendingDeepLink = parsed;
   });
 
-  const aegis = createClient();
+  const aegis = createClient(credentials.clientOptions());
   const dataDir = resolveUserDataDir(app);
 
   // One settings store backs both the provider settings surface and the AEGIS
@@ -1248,7 +1269,17 @@ function bootstrap() {
   // Persist the in-app AEGIS key in its own reserved namespace, encrypted —
   // never as a provider named 'aegis' (that coupling let the Settings pane's
   // "Remove" delete the AEGIS key; defect #1).
-  const persistApiKey = (key) => settings.setAegisKey(key);
+  //
+  // Mirrored into the shared 0600 store as well, so one sign-in covers this app,
+  // `aegiscode` and the MCP plugin instead of each host needing its own. The
+  // app's copy stays the encrypted one; resolveStartupKey() compares their
+  // `savedAt` stamps so whichever host wrote last is the key in force.
+  const persistApiKey = (key) => {
+    const result = settings.setAegisKey(key);
+    if (key) credentials.saveApiKey(key);
+    else credentials.clearApiKey();
+    return result;
+  };
 
   // Native "reply ready" notification: main.js is exactly where every
   // chatCompletion/model:chat call already resolves (withReplyNotify above),
@@ -1565,8 +1596,19 @@ function bootstrap() {
     // Hydrate the client from the persisted key BEFORE the renderer issues any
     // status/model call, so class/model dropdowns populate immediately when a
     // key was saved in-app (safeStorage is usable only after app ready).
-    const persistedKey = settings.aegisRawKey();
-    if (persistedKey) aegis.setApiKey(persistedKey);
+    //
+    // `$AEGIS_API_KEY` still outranks both stores: createClient() already read
+    // it, and nothing here may shadow an explicit export.
+    const envKey = credentials.normalizeApiKey(process.env[credentials.KEY_ENV]);
+    if (!envKey) {
+      const chosen = credentials.preferNewest(settings.aegisRawKey(), settings.aegisKeySavedAt());
+      if (chosen.key) {
+        aegis.setApiKey(chosen.key);
+        // The shared store is the newer write: bring this host's encrypted copy
+        // up to date so a CLI rotation does not have to be redone in Settings.
+        if (chosen.source === 'shared') settings.setAegisKey(chosen.key);
+      }
+    }
     // Apply whatever was last saved (or the default): ship the shortcut only
     // when app.isPackaged || the settings flag is on — see
     // shouldEnableGlobalShortcut — so a plain `electron .` dev run never

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",

package/vendor/credentials.js

@@ -0,0 +1,386 @@
+'use strict';
+
+/**
+ * credentials.js — the ONE AEGIS account credential store, shared by every
+ * host in this repo (terminal `aegiscode`, the MCP plugin, the desktop app).
+ *
+ * Why it lives in `client/`: this directory is the only tree all three hosts
+ * already bundle. The MCP plugin ships `mcp/` + `client/` and nothing else, so
+ * a reader placed here needs no cross-package dependency — which is what the
+ * alternative (the MCP host requiring `cli/src/credentials.js`) would have
+ * forced, and why that host used to read `AEGIS_API_KEY` from the environment
+ * alone while the CLI could save a key to disk. One login, one file, three
+ * hosts: that is the point of this module.
+ *
+ * Zero dependencies, no host imports. The data dir is resolved here
+ * (`aegisHome()`) rather than imported from the CLI's config.js, so this file
+ * runs from a bare `node client/credentials.js` inside the plugin tree.
+ *
+ * Resolution order, first hit wins:
+ *
+ *   1. `AEGIS_API_KEY` — the environment, so CI and an explicit export keep
+ *      working and nothing written here can shadow them.
+ *   2. `credentials.json` in the data dir, mode 0600. The writable store.
+ *   3. `config.json`'s `aegiscloud.api_key` / `memory.token` — the shape an
+ *      earlier AEGIS CLI left in the same data dir. Read, never written, and
+ *      never deleted: it is another product's file and the user's key is in
+ *      it. When one is found it is *also* copied into credentials.json so the
+ *      next run reads the 0600 copy, and the status line says the plaintext
+ *      copy is still there rather than silently leaving it.
+ *
+ * The key is never printed in full by anything in this repo; callers mask it.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const KEY_ENV = 'AEGIS_API_KEY';
+/** Optional override for the memory token (cloud sync's own credential). */
+const MEMORY_ENV = 'AEGIS_MEMORY_TOKEN';
+const HOME_ENV = 'AEGISCODE_HOME';
+const CREDENTIALS_FILE = 'credentials.json';
+const CONFIG_FILE = 'config.json';
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+/**
+ * The per-user AEGIS data directory: `$AEGISCODE_HOME` or `~/.aegiscode`.
+ *
+ * Every host resolves its data dir through this one function, so the CLI, the
+ * MCP plugin and the desktop app agree on where memory and credentials live
+ * instead of each keeping a private store the others cannot see. (The desktop
+ * still keeps its *settings* — the safeStorage-encrypted key, window state —
+ * in Electron's userData; only the shared memory + credential files live here.)
+ */
+function aegisHome(env) {
+  const e = env || process.env;
+  const override = e && e[HOME_ENV];
+  if (override && String(override).trim()) return path.resolve(String(override).trim());
+  return path.join(os.homedir(), '.aegiscode');
+}
+
+function credentialsPath(dir) {
+  return path.join(dir || aegisHome(), CREDENTIALS_FILE);
+}
+
+function configPath(dir) {
+  return path.join(dir || aegisHome(), CONFIG_FILE);
+}
+
+/**
+ * Accept the key in the shapes a user actually pastes it.
+ *
+ * Copy-paste from a dashboard, a `.env` line, a shell profile or a chat message
+ * are all realistic — and pasting `AEGIS_API_KEY=aegis_…` or `"aegis_…"` into a
+ * prompt that stores the literal string produces an auth failure the user
+ * cannot see the cause of, because the key *looks* right in the status line.
+ */
+function normalizeApiKey(raw) {
+  let s = String(raw == null ? '' : raw).trim();
+  if (!s) return '';
+  s = s.replace(/^export\s+/i, '').trim();
+  const assignment = /^[A-Za-z_][A-Za-z0-9_]*\s*=\s*(.+)$/s.exec(s);
+  if (assignment) s = assignment[1].trim();
+  s = s.replace(/^["']|["']$/g, '').trim();
+  s = s.replace(/^Bearer\s+/i, '').trim();
+  return s;
+}
+
+/**
+ * Shape check only — no network. Catches the two mistakes that are structural
+ * (an empty paste, and a wrapped/truncated multi-line paste) so the caller can
+ * refuse before spending a verification round trip.
+ */
+function validateApiKey(raw) {
+  const key = normalizeApiKey(raw);
+  if (!key) return { ok: false, key, reason: 'empty', message: 'no key given' };
+  if (/\s/.test(key)) {
+    return {
+      ok: false,
+      key,
+      reason: 'whitespace',
+      message: 'that looks like more than one word — paste just the key',
+    };
+  }
+  if (key.length < 16) {
+    return {
+      ok: false,
+      key,
+      reason: 'too short',
+      message: `that key is ${key.length} characters — AEGIS keys are longer than that`,
+    };
+  }
+  return { ok: true, key, reason: null, message: null };
+}
+
+/** The stored credential object, or {} — never throws on a missing/corrupt file. */
+function readCredentials(dir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(dir), 'utf8'));
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch {}
+  return {};
+}
+
+/**
+ * Merge a patch into the store, creating it 0600 (and tightening an existing
+ * file that is wider — a key file that a previous run left 0644 is exactly the
+ * leak this file exists to avoid).
+ */
+function writeCredentials(patch, dir) {
+  const target = credentialsPath(dir);
+  const next = { ...readCredentials(dir), ...patch, version: 1 };
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: DIR_MODE });
+    const tmp = target + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: FILE_MODE });
+    fs.renameSync(tmp, target);
+    try {
+      fs.chmodSync(target, FILE_MODE);
+    } catch {}
+  } catch (e) {
+    if (process.env.AEGIS_HIST_DEBUG) console.error('[credentials] write failed:', e);
+    return { ok: false, error: e, credentials: next };
+  }
+  return { ok: true, credentials: next };
+}
+
+/**
+ * The key an earlier AEGIS CLI wrote into config.json (the `aegiscloud` /
+ * `memory` blocks are not ours). Read-only.
+ */
+function readLegacyConfig(dir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath(dir), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return {};
+    const cloud = parsed.aegiscloud && typeof parsed.aegiscloud === 'object' ? parsed.aegiscloud : {};
+    const memory = parsed.memory && typeof parsed.memory === 'object' ? parsed.memory : {};
+    return {
+      apiKey: normalizeApiKey(cloud.api_key),
+      memoryToken: String(memory.token || '').trim(),
+      syncConversations: cloud.syncConversations === true ? true : undefined,
+      lastVerified: cloud.lastVerified || null,
+      memorySubscribed: memory.subscribed === true ? true : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** True when config.json still carries a plaintext copy of the account key. */
+function legacyKeyOnDisk(dir) {
+  return !!readLegacyConfig(dir).apiKey;
+}
+
+/**
+ * Copy a legacy key/token into the 0600 store, once, without touching the file
+ * it came from. Returns which fields were adopted so the caller can say so.
+ */
+function adoptLegacy(dir) {
+  const legacy = readLegacyConfig(dir);
+  const creds = readCredentials(dir);
+  const patch = {};
+  if (legacy.apiKey && !creds.aegisApiKey) patch.aegisApiKey = legacy.apiKey;
+  if (legacy.memoryToken && !creds.memoryToken) patch.memoryToken = legacy.memoryToken;
+  if (!Object.keys(patch).length) return { adopted: [] };
+  const written = writeCredentials({ ...patch, adoptedFrom: configPath(dir) }, dir);
+  if (!written.ok) return { adopted: [] };
+  return { adopted: Object.keys(patch) };
+}
+
+/**
+ * The key to use, and where it came from.
+ *
+ * @returns {{key:string, source:'env'|'credentials'|'config'|'none', from:string}}
+ */
+function resolveApiKey(o = {}) {
+  const env = o.env || process.env;
+  const dir = o.dir;
+  const fromEnv = normalizeApiKey(env && env[KEY_ENV]);
+  if (fromEnv) return { key: fromEnv, source: 'env', from: KEY_ENV };
+
+  const creds = readCredentials(dir);
+  const stored = normalizeApiKey(creds.aegisApiKey);
+  if (stored) return { key: stored, source: 'credentials', from: credentialsPath(dir) };
+
+  const legacy = readLegacyConfig(dir).apiKey;
+  if (legacy) return { key: legacy, source: 'config', from: configPath(dir) };
+
+  return { key: '', source: 'none', from: '' };
+}
+
+/** Whether any credential is available (env, store or legacy config). */
+function hasApiKey(o = {}) {
+  return !!resolveApiKey(o).key;
+}
+
+/**
+ * Persist a key.
+ *
+ * @returns {{ok:boolean, key:string, path:string, error?:Error, message?:string}}
+ */
+function saveApiKey(raw, dir) {
+  const v = validateApiKey(raw);
+  if (!v.ok) return { ok: false, key: v.key, path: credentialsPath(dir), message: v.message };
+  const written = writeCredentials({ aegisApiKey: v.key, savedAt: new Date().toISOString() }, dir);
+  if (!written.ok) {
+    return {
+      ok: false,
+      key: v.key,
+      path: credentialsPath(dir),
+      error: written.error,
+      message: `could not write ${credentialsPath(dir)}`,
+    };
+  }
+  return { ok: true, key: v.key, path: credentialsPath(dir) };
+}
+
+/**
+ * Remove the stored key (and nothing else — the memory token stays, since a
+ * key rotation should not silently unsubscribe cloud memory). config.json is
+ * never touched: another product writes it.
+ */
+function clearApiKey(dir) {
+  const had = !!normalizeApiKey(readCredentials(dir).aegisApiKey);
+  const written = writeCredentials({ aegisApiKey: '', adoptedFrom: '' }, dir);
+  return { cleared: had, ok: written.ok, path: credentialsPath(dir) };
+}
+
+/** The memory token cloud sync authenticates with, from store or legacy. */
+function resolveMemoryToken(o = {}) {
+  const env = o.env || process.env;
+  const dir = o.dir;
+  const fromEnv = String((env && env[MEMORY_ENV]) || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const creds = readCredentials(dir);
+  const stored = String(creds.memoryToken || '').trim();
+  if (stored) return { token: stored, source: 'credentials' };
+  const legacy = readLegacyConfig(dir).memoryToken;
+  if (legacy) return { token: legacy, source: 'config' };
+  return { token: '', source: 'none' };
+}
+
+function saveMemoryToken(token, extra = {}, dir) {
+  return writeCredentials({ memoryToken: String(token || '').trim(), ...extra }, dir);
+}
+
+function clearMemoryToken(dir) {
+  return writeCredentials({ memoryToken: '', memorySubscribed: false }, dir);
+}
+
+/**
+ * Everything a status screen or a `doctor` line needs about the credential,
+ * without ever exposing the key itself.
+ */
+function keyStatus(o = {}) {
+  const dir = o.dir;
+  const { key, source, from } = resolveApiKey(o);
+  const creds = readCredentials(dir);
+  let mode = null;
+  try {
+    mode = fs.statSync(credentialsPath(dir)).mode & 0o777;
+  } catch {}
+  return {
+    configured: !!key,
+    key,
+    source,
+    from,
+    path: credentialsPath(dir),
+    fileMode: mode == null ? null : '0' + mode.toString(8),
+    stored: !!normalizeApiKey(creds.aegisApiKey),
+    legacyPlaintext: legacyKeyOnDisk(dir),
+    verifiedAt: creds.verifiedAt || null,
+    account: creds.account || null,
+    memoryToken: !!resolveMemoryToken(o).token,
+    memorySource: resolveMemoryToken(o).source,
+  };
+}
+
+/**
+ * Client options for `createClient`: the resolved key plus the stored memory
+ * token, so a restart does not re-exchange for a token it already has.
+ */
+function clientOptions(o = {}) {
+  const { key } = resolveApiKey(o);
+  const { token } = resolveMemoryToken(o);
+  const opts = {};
+  if (key) opts.apiKey = key;
+  if (token) opts.memoryToken = token;
+  return opts;
+}
+
+/** Human label for a resolution source, for status lines. */
+const SOURCE_LABEL = {
+  env: `${KEY_ENV}`,
+  credentials: 'saved key file',
+  config: 'config.json (aegis CLI)',
+  none: 'not set',
+};
+
+function sourceLabel(source) {
+  return SOURCE_LABEL[source] || SOURCE_LABEL.none;
+}
+
+/**
+ * Prefer the most recently saved key between a host's own copy and this file.
+ *
+ * The desktop keeps its key encrypted via Electron safeStorage, which is a
+ * better place for it than a 0600 file — but only one of the two can be in
+ * force, and picking wrong is silent: the user rotates their key with
+ * `aegiscode login`, the app keeps presenting an old string it saved last week,
+ * and every call 401s with a key that looks right in Settings.
+ *
+ * Both sides stamp `savedAt`, so the rule is simply "the newest write wins",
+ * with the host's own copy breaking a tie (it is encrypted). A missing stamp on
+ * either side loses to a present one; equal keys always resolve to the host's.
+ *
+ * @returns {{key:string, source:'host'|'shared'|'none', sharedAt:number, hostAt:number}}
+ */
+function preferNewest(storedKey, storedAt, o = {}) {
+  const ownKey = normalizeApiKey(storedKey);
+  const ownAt = Date.parse(storedAt || '') || 0;
+  const shared = readCredentials(o.dir);
+  const sharedKey = normalizeApiKey(shared.aegisApiKey);
+  const sharedAt = Date.parse(shared.savedAt || '') || 0;
+
+  if (!sharedKey) return { key: ownKey, source: ownKey ? 'host' : 'none', sharedAt, hostAt: ownAt };
+  if (!ownKey) return { key: sharedKey, source: 'shared', sharedAt, hostAt: ownAt };
+  if (ownKey === sharedKey) return { key: ownKey, source: 'host', sharedAt, hostAt: ownAt };
+  return sharedAt > ownAt
+    ? { key: sharedKey, source: 'shared', sharedAt, hostAt: ownAt }
+    : { key: ownKey, source: 'host', sharedAt, hostAt: ownAt };
+}
+
+/** One line telling the user how to supply a key, used by every error path. */
+const HOW_TO_SET = 'run `aegiscode login` (or /key inside a session) to save one';
+
+module.exports = {
+  KEY_ENV,
+  MEMORY_ENV,
+  HOME_ENV,
+  CREDENTIALS_FILE,
+  CONFIG_FILE,
+  aegisHome,
+  credentialsPath,
+  configPath,
+  normalizeApiKey,
+  validateApiKey,
+  readCredentials,
+  writeCredentials,
+  readLegacyConfig,
+  legacyKeyOnDisk,
+  adoptLegacy,
+  resolveApiKey,
+  hasApiKey,
+  saveApiKey,
+  clearApiKey,
+  resolveMemoryToken,
+  saveMemoryToken,
+  clearMemoryToken,
+  keyStatus,
+  clientOptions,
+  preferNewest,
+  sourceLabel,
+  HOW_TO_SET,
+};

package/vendor/session-store.js

@@ -0,0 +1,514 @@
+'use strict';
+
+/**
+ * session-store.js — the ONE local session/memory store shared by every AEGIS
+ * host.
+ *
+ * Before this module the repo had two private stores:
+ *
+ *   CLI      ~/.aegiscode/history.jsonl   one line per exchange
+ *   desktop  <userData>/sessions.json     one record per session
+ *
+ * Both hosts pushed "the same wire shape" to the cloud, so a session started in
+ * the GUI reached the terminal only after a network round trip — and a CLI
+ * session could not reach the GUI at all unless the account had cloud sync on.
+ * Offline, or on an account with no key, the two hosts simply could not see each
+ * other's work.
+ *
+ * This module is the single store they now both read and write:
+ *
+ *   <dir>/sessions.json   { __seq, "<id>": { id, title, messages[], ... } }
+ *
+ * `dir` is resolved by `aegisHome()` (client/credentials.js) — `$AEGISCODE_HOME`
+ * or `~/.aegiscode` — so the desktop's *sessions* now live beside the CLI's and
+ * the MCP plugin's view of the same account, while the desktop keeps its
+ * settings (safeStorage-encrypted key, window state) in Electron's userData
+ * where they belong.
+ *
+ * The record shape is the desktop's, extended — not replaced. Every field the
+ * existing store wrote (`pending`, `seq`, `updatedAt`, `remoteId`,
+ * `lastSyncedAt`, `__seq`) keeps its meaning, because the sync surface and the
+ * renderer's session list read them.
+ *
+ * Pure Node + injectable dir, so it unit-tests without Electron or a network.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { aegisHome } = require('./credentials.js');
+
+const STORE_FILE = 'sessions.json';
+const STORE_VERSION = 2;
+/** Bound on a single session's transcript, so one runaway session cannot make
+ *  every later load of the store O(huge). Oldest messages drop first. */
+const MAX_MESSAGES_PER_SESSION = 2000;
+
+/** Where the store lives when the caller doesn't name a dir. */
+function storeDir(dir) {
+  return dir || aegisHome();
+}
+
+function storeFile(dir) {
+  return path.join(storeDir(dir), STORE_FILE);
+}
+
+/**
+ * Monotonic write counter stored in the file's `__seq` field. Every mutation
+ * bumps it, so sessions written in the same millisecond still order
+ * deterministically (listSessions sorts by updatedAt, then by seq).
+ */
+function nextSeq(sessions) {
+  const seq = (typeof sessions.__seq === 'number' ? sessions.__seq : 0) + 1;
+  sessions.__seq = seq;
+  return seq;
+}
+
+/**
+ * Normalize a remote `updated_at`/`updatedAt` to epoch milliseconds. The cloud
+ * returns an ISO-8601 string (e.g. "2026-07-16T14:20:00"); the local store
+ * uses `Date.now()` epoch-ms numbers. Comparing the two directly coerces the
+ * string to NaN, which breaks last-write-wins ordering. ISO strings are
+ * parsed; epoch-ms numbers pass through; anything else becomes 0.
+ */
+function toEpochMs(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim()) {
+    const ms = Date.parse(value);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return 0;
+}
+
+function load(dir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storeFile(dir), 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch {}
+  return {};
+}
+
+/**
+ * Sessions as a JSON object without the `__seq` bookkeeping key. Callers that
+ * iterate the store (the renderer's list, `/resume`) must not meet `__seq` as
+ * if it were a session with an undefined id.
+ */
+function atomicWrite(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  // 0600: a transcript is private conversation content, and this file now holds
+  // every host's sessions in one place.
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {}
+}
+
+/** How long a lock may be held before another writer treats it as abandoned. */
+const LOCK_STALE_MS = 2000;
+/** Total time a writer will wait for the lock before proceeding unlocked. */
+const LOCK_WAIT_MS = 500;
+
+function lockFile(dir) {
+  return `${storeFile(dir)}.lock`;
+}
+
+/**
+ * Best-effort advisory lock around the read-modify-write in `mutate()`.
+ *
+ * A private store owned by one process did not need this. A *shared* one does:
+ * the desktop app and a terminal session are two long-lived processes that both
+ * rewrite this file wholesale, and interleaved read-modify-write would drop
+ * whichever turn lost the race. The lock is deliberately soft — a crash must
+ * not wedge every future write, so a lock older than LOCK_STALE_MS is stolen,
+ * and a writer that cannot get it in LOCK_WAIT_MS proceeds anyway (losing at
+ * worst the same race that exists today, rather than refusing to save).
+ *
+ * @returns {boolean} whether the lock was acquired
+ */
+function acquireLock(dir) {
+  const file = lockFile(dir);
+  // The lock is taken *before* the write that used to create the directory, so
+  // this is now the first thing to touch it — a first run (or a fresh
+  // AEGISCODE_HOME) would otherwise spin here forever waiting on a lock it can
+  // never create.
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+  } catch {
+    return false;
+  }
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  // Bounded, so no combination of "lock vanished" / "lock unreadable" can spin
+  // this loop: a writer that cannot decide always proceeds unlocked instead.
+  const MAX_ATTEMPTS = 200;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      let age = null;
+      try {
+        age = Date.now() - fs.statSync(file).mtimeMs;
+      } catch {
+        // Released between the open and the stat — try immediately.
+        continue;
+      }
+      if (age > LOCK_STALE_MS) {
+        try {
+          fs.unlinkSync(file);
+        } catch {}
+        continue;
+      }
+      if (Date.now() >= deadline) return false;
+      // Busy-wait: the critical section is a few hundred microseconds of
+      // stringify + rename, so sleeping the event loop would cost more than it
+      // saves, and this path is not on the streaming critical path.
+      const until = Date.now() + 5;
+      while (Date.now() < until) {
+        /* spin a few ms */
+      }
+    }
+  }
+  return false;
+}
+
+function releaseLock(dir) {
+  try {
+    fs.unlinkSync(lockFile(dir));
+  } catch {}
+}
+
+/**
+ * Read-modify-write the whole store under the lock. Every mutation goes through
+ * here so the locking is one behaviour, not a thing each caller must remember.
+ */
+function mutate(dir, mutator) {
+  const locked = acquireLock(dir);
+  try {
+    const sessions = load(dir);
+    const result = mutator(sessions);
+    save(dir, sessions);
+    return result;
+  } finally {
+    if (locked) releaseLock(dir);
+  }
+}
+
+function save(dir, sessions) {
+  atomicWrite(storeFile(dir), sessions);
+}
+
+function trimMessages(messages) {
+  if (!Array.isArray(messages)) return [];
+  if (messages.length <= MAX_MESSAGES_PER_SESSION) return messages;
+  return messages.slice(messages.length - MAX_MESSAGES_PER_SESSION);
+}
+
+/**
+ * Create or merge a full session record. Any local write (`upsertSession` /
+ * `appendMessage` / `recordExchange`) marks the session `pending: true` — it has
+ * local content the cloud hasn't seen yet. Only `markSynced()` clears the flag,
+ * so a push that fails (offline/no key) never silently drops the session from
+ * the retry queue.
+ */
+function upsertSession(dir, session) {
+  const id = session && session.id;
+  if (!id) throw new Error('session.id is required');
+  return mutate(dir, (sessions) => {
+    const prev = sessions[id] || { messages: [] };
+    sessions[id] = { ...prev, ...session, id, version: STORE_VERSION };
+    if (session.pending !== false) sessions[id].pending = true;
+    if (!sessions[id].updatedAt) sessions[id].updatedAt = Date.now();
+    sessions[id].seq = nextSeq(sessions);
+    return sessions[id];
+  });
+}
+
+/** Append one message to a session (crash-safe). */
+function appendMessage(dir, sessionId, message) {
+  if (!sessionId) throw new Error('sessionId is required');
+  return mutate(dir, (sessions) => {
+    const session = sessions[sessionId] || { id: sessionId, messages: [] };
+    const messages = Array.isArray(session.messages) ? session.messages : [];
+    session.messages = trimMessages(messages.concat(message));
+    session.updatedAt = Date.now();
+    session.pending = true;
+    session.seq = nextSeq(sessions);
+    sessions[sessionId] = session;
+    return session;
+  });
+}
+
+/**
+ * Record one finished exchange (the CLI's unit of work) as a session with a
+ * user/assistant message pair. This is what makes a terminal turn visible to
+ * the desktop, which lists sessions out of this same file.
+ *
+ * `pending` defaults to **false** here, unlike `appendMessage`: the CLI keeps
+ * its own sync ledger (`cli/src/cloudsync.js` derives pending from
+ * `sync-state.json`) and pushes through `/sync`. Marking these pending would
+ * enrol every terminal session in the *desktop's* push queue as a side effect
+ * of typing in a shell, spending the account's synced-token quota without being
+ * asked. `origin` records which host wrote the record so either side can filter.
+ *
+ * @returns {object|null} the session record, or null on unwritable storage
+ */
+function recordExchange(dir, exchange) {
+  const e = exchange || {};
+  if (!e.sessionId) return null;
+  const id = e.sessionId;
+  return mutate(dir, (sessions) => {
+    const session = sessions[id] || { id, messages: [] };
+    const messages = Array.isArray(session.messages) ? session.messages : [];
+    const ts = e.ts || new Date().toISOString();
+    const userMessage = { role: 'user', content: e.prompt == null ? '' : String(e.prompt), ts };
+    const assistantMessage = { role: 'assistant', content: e.reply == null ? '' : String(e.reply), ts };
+    if (e.tokens) assistantMessage.tokens = e.tokens;
+    if (typeof e.costUsd === 'number') assistantMessage.costUsd = e.costUsd;
+    if (e.status) assistantMessage.status = e.status;
+    if (e.origin) {
+      userMessage.origin = e.origin;
+      assistantMessage.origin = e.origin;
+    }
+    session.messages = trimMessages(messages.concat([userMessage, assistantMessage]));
+    session.title = session.title || String(e.prompt || '').slice(0, 60);
+    if (e.cwd) session.cwd = e.cwd;
+    session.origin = e.origin || session.origin || 'unknown';
+    session.updatedAt = Date.now();
+    // Explicit, not merely "leave it unset": `listPending` treats an absent flag
+    // as pending (sessions predating the field default to queued), so an
+    // undefined here would quietly enrol every terminal session in the desktop's
+    // push queue — the exact thing the `pending: false` default is for.
+    session.pending = e.pending === true ? true : false;
+    session.seq = nextSeq(sessions);
+    sessions[id] = session;
+    return session;
+  });
+}
+
+function listSessions(dir) {
+  const sessions = load(dir);
+  return Object.values(sessions)
+    .filter((s) => s && s.id)
+    .sort(
+      (a, b) =>
+        (b.updatedAt || 0) - (a.updatedAt || 0) ||
+        (b.seq || 0) - (a.seq || 0)
+    );
+}
+
+function getSession(dir, id) {
+  return load(dir)[id] || null;
+}
+
+function deleteSession(dir, id) {
+  return mutate(dir, (sessions) => {
+    delete sessions[id];
+    return { ok: true };
+  });
+}
+
+/** Clear the pending flag after a successful cloud push. `remote.remoteId`,
+ *  when the server assigns its own conversation id, is stashed alongside. */
+function markSynced(dir, id, remote) {
+  return mutate(dir, (sessions) => {
+    const session = sessions[id];
+    if (!session) return null;
+    session.pending = false;
+    session.lastSyncedAt = Date.now();
+    if (remote && remote.remoteId) session.remoteId = remote.remoteId;
+    session.seq = nextSeq(sessions);
+    return session;
+  });
+}
+
+/** Force a session back into the retry queue (e.g. a push that partially failed). */
+function markPending(dir, id) {
+  return mutate(dir, (sessions) => {
+    const session = sessions[id];
+    if (!session) return null;
+    session.pending = true;
+    session.seq = nextSeq(sessions);
+    return session;
+  });
+}
+
+/** Sessions with local content the cloud hasn't confirmed yet (including
+ *  sessions predating this field, which default to pending). */
+function listPending(dir) {
+  return listSessions(dir).filter((s) => s.pending !== false);
+}
+
+/**
+ * Merge remote conversation-sync records into the local store (pull half of
+ * sync). Last-write-wins by `updatedAt`, but a local session with unsynced
+ * edits (`pending`) always wins over the remote copy — it will overwrite the
+ * remote copy on the next push instead.
+ */
+function mergeRemoteSessions(dir, remoteSessions) {
+  const list = Array.isArray(remoteSessions) ? remoteSessions : [];
+  if (!list.length) return 0;
+  return mutate(dir, (sessions) => {
+    let merged = 0;
+    for (const remote of list) {
+      const id = remote && (remote.session_id || remote.id);
+      if (!id) continue;
+      const local = sessions[id];
+      const remoteUpdatedAt = toEpochMs(remote.updated_at ?? remote.updatedAt);
+      if (local && (local.pending || (local.updatedAt || 0) >= remoteUpdatedAt)) {
+        continue;
+      }
+      sessions[id] = {
+        id,
+        title: remote.title || (local && local.title) || '',
+        messages: Array.isArray(remote.messages) ? remote.messages : [],
+        updatedAt: remoteUpdatedAt || Date.now(),
+        pending: false,
+        lastSyncedAt: Date.now(),
+        remoteId: remote.session_id || remote.id,
+        origin: remote.source || (local && local.origin) || 'cloud',
+        version: STORE_VERSION,
+      };
+      sessions[id].seq = nextSeq(sessions);
+      merged += 1;
+    }
+    return merged;
+  });
+}
+
+/**
+ * Compact listing for a picker (`/resume`, the desktop's session list). Same
+ * field names `history.js`'s readOwnSessions produced, so the two can be
+ * concatenated without either side having to know which store a row came from.
+ */
+function listSummaries(dir, limit = 8) {
+  return listSessions(dir)
+    .slice(0, limit)
+    .map((s) => {
+      const messages = Array.isArray(s.messages) ? s.messages : [];
+      const first = messages.find((m) => m && m.role === 'user');
+      return {
+        id: s.id,
+        cwd: (s.cwd || '').split(/[\\/]/).filter(Boolean).pop() || '~',
+        summary: String((first && first.content) || s.title || '').slice(0, 60),
+        time: new Date(s.updatedAt || Date.now()).toISOString(),
+        own: true,
+        origin: s.origin || 'unknown',
+        messages: messages.length,
+        pending: s.pending === true,
+        dir: String(s.cwd || ''),
+      };
+    });
+}
+
+/** Rebuild a transcript (user/assistant pairs) for a session, oldest first. */
+function readTranscript(dir, sessionId) {
+  const session = getSession(dir, sessionId);
+  if (!session) return [];
+  return (Array.isArray(session.messages) ? session.messages : [])
+    .filter((m) => m && (m.role === 'user' || m.role === 'assistant'))
+    .map((m) => ({ role: m.role, text: m.content == null ? '' : String(m.content) }));
+}
+
+/**
+ * Import a legacy store from another directory, ONE way and one time.
+ *
+ * The desktop wrote `<userData>/sessions.json` before this store existed. On an
+ * upgrade that file is the user's entire GUI history, so the shared store
+ * adopts it — but only when the shared store has nothing to lose (missing, or
+ * empty), and only by copying: the legacy file is left where it is, so a user
+ * who downgrades still finds their sessions.
+ *
+ * @returns {{adopted:boolean, sessions:number, from:string, reason?:string}}
+ */
+function adopt(dir, fromDir) {
+  const from = storeFile(fromDir);
+  const exists = (() => {
+    try {
+      return fs.existsSync(from);
+    } catch {
+      return false;
+    }
+  })();
+  if (!exists) return { adopted: false, sessions: 0, from, reason: 'no legacy store' };
+  const legacy = (() => {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(from, 'utf8'));
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+  const incoming = Object.values(legacy).filter((s) => s && s.id);
+  if (!incoming.length) return { adopted: false, sessions: 0, from, reason: 'legacy store empty' };
+  if (listSessions(dir).length) {
+    return { adopted: false, sessions: 0, from, reason: 'store already has sessions' };
+  }
+  mutate(dir, (sessions) => {
+    for (const s of incoming) {
+      // Adopted sessions keep their own history; they are already local content.
+      sessions[s.id] = { ...s, adoptedFrom: from, version: STORE_VERSION };
+      sessions[s.id].seq = nextSeq(sessions);
+    }
+    sessions.__seq = Math.max(sessions.__seq || 0, legacy.__seq || 0);
+    sessions.version = STORE_VERSION;
+    return null;
+  });
+  return { adopted: true, sessions: incoming.length, from };
+}
+
+/**
+ * Markdown export (session export, plan: Save as.../Export session). Each
+ * message becomes a `## Role` heading followed by its content verbatim —
+ * content is never re-escaped or re-wrapped, so any code fences a message
+ * already contains (assistant replies routinely have them) survive untouched
+ * instead of being nested inside an outer fence.
+ */
+function toMarkdown(session) {
+  const title = (session && (session.title || session.id)) || 'session';
+  const messages = (session && Array.isArray(session.messages)) ? session.messages : [];
+  const lines = [`# ${title}`, ''];
+  for (const message of messages) {
+    const role = (message && message.role) || 'unknown';
+    const heading = role.charAt(0).toUpperCase() + role.slice(1);
+    const content = (message && (message.content || message.text)) || '';
+    lines.push(`## ${heading}`, '', content, '');
+  }
+  return lines.join('\n');
+}
+
+/** JSON export: the session record as stored, pretty-printed. */
+function toJson(session) {
+  return JSON.stringify(session, null, 2);
+}
+
+module.exports = {
+  STORE_FILE,
+  STORE_VERSION,
+  MAX_MESSAGES_PER_SESSION,
+  storeDir,
+  storeFile,
+  lockFile,
+  LOCK_STALE_MS,
+  LOCK_WAIT_MS,
+  toEpochMs,
+  load,
+  save,
+  upsertSession,
+  appendMessage,
+  recordExchange,
+  listSessions,
+  getSession,
+  deleteSession,
+  markSynced,
+  markPending,
+  listPending,
+  mergeRemoteSessions,
+  listSummaries,
+  readTranscript,
+  adopt,
+  toMarkdown,
+  toJson,
+};