memhouse 0.18.12 → 0.20.1

package/memhouse/shipper/ship.js

@@ -675,7 +675,7 @@ async function recordHouseState(client, rooms, host) {
  * record at all.)
  *
  * Releases before 0.10.0 never read this — for them the floor is enforced by the
- * pilot's GRANTs, not by code.
+ * user's GRANTs, not by code.
  */
 /**
  * A house from before the one-layout holds plain rooms — `messages`, not `<member>_messages`.
@@ -749,9 +749,13 @@ async function assertWriterSupported(client, rooms) {
         + '  Bring the house forward:  memhouse migrate');
   }
   if (floor > mine) {
-    throw new Error(
-      `this house requires writers at schema ${floor}+; this memhouse supports ${SUPPORTED_SCHEMAS.join(', ')}.\n`
-      + '  Update THIS machine:  memhouse update');
+    // A house fenced for schema 3 (memhouse migrate --v3-prepare): this release has the schema-3
+    // capture, so the remedy is to switch, not to update.
+    throw new Error(floor === 3
+      ? 'this house moved to schema 3 (its 0.18 rooms are fenced off and converted).\n'
+        + '  Switch THIS machine to it:  memhouse migrate --v3-switch   (then: memhouse stop && memhouse start)'
+      : `this house requires writers at schema ${floor}+; this memhouse supports ${SUPPORTED_SCHEMAS.join(', ')}.\n`
+        + '  Update THIS machine:  memhouse update');
   }
 }
 
@@ -1531,7 +1535,31 @@ async function printStats(client) {
 
 async function main() {
   const argv = process.argv.slice(2);
+  // A shipper that starts (or re-execs) on a new version refreshes the /mem skills bound to its
+  // home, as any CLI call does: an npm upgrade restarts the daemons, not `update`.
+  {
+    const root = require('path').join(__dirname, '..', '..');
+    const r = require('../plugin-copies').refreshIfStale({
+      home: process.env.MEMHOUSE_HOME || require('path').join(require('os').homedir(), '.memhouse'),
+      version: require(require('path').join(root, 'package.json')).version,
+      deliveryDir: require('path').join(root, 'memhouse', 'delivery'), repoRoot: root,
+      log: (l) => console.error(`[memhouse] ${l}`),
+    });
+    for (const e of r.errors) console.error(`[memhouse] could not refresh the /mem skills: ${e}`);
+  }
   let client = makeClient();
+  // This daemon re-read its env file: it adopted a moved house or a newer credential.
+  // `memhouse status` calls a shipper stale when the env file changed after it last read it
+  // (bin/memhouse.js shipperStale), so record when that was. Only for the daemon the pid file
+  // names: a one-shot pass adopting for itself leaves a running daemon as stale as it is.
+  const noteEnvRead = () => {
+    try {
+      const p = require('path'); const fs = require('fs');
+      const run = p.join(process.env.MEMHOUSE_HOME || p.join(require('os').homedir(), '.memhouse'), 'run');
+      if (fs.readFileSync(p.join(run, 'shipper.pid'), 'utf-8').trim() !== String(process.pid)) return;
+      fs.writeFileSync(p.join(run, 'shipper.env-read'), `${new Date().toISOString()}\n`);
+    } catch { /* no pid file: not the daemon */ }
+  };
   // The operator may have converted the house to the one layout since this env was
   // written: the member's rooms moved from <name>.* to mem.<name>_*. Adopt that here —
   // rewrite the env, point this process at `mem` — instead of refusing the old address on
@@ -1546,10 +1574,17 @@ async function main() {
       const rs = await probe.query({ query: `SELECT database, name FROM system.tables WHERE (database = '${db.replace(/'/g, "\\'")}' AND name IN ('messages', '${mine}')) OR (database = 'mem' AND name = '${mine}')`, format: 'JSONEachRow' });
       const rows = await rs.json(); const has = (d, n) => rows.some((r) => r.database === d && r.name === n);
       if (!has(db, mine) && !has(db, 'messages') && has('mem', mine)) {
-        const envPath = require('path').join(process.env.MEMHOUSE_HOME || require('path').join(require('os').homedir(), '.memhouse'), 'env');
-        try { const fs = require('fs'); fs.writeFileSync(envPath, require('../envfile').setKey(fs.readFileSync(envPath, 'utf-8'), 'MEMHOUSE_DB', 'mem')); } catch { /* env not writable: this process still adopts */ }
+        // --stats only reads: it adopts the move for this process and leaves the env file to
+        // a pass or `memhouse update`. The /mem skills run `memhouse stats` without asking.
+        const readOnly = argv.includes('--stats');
+        if (!readOnly) {
+          const envPath = require('path').join(process.env.MEMHOUSE_HOME || require('path').join(require('os').homedir(), '.memhouse'), 'env');
+          try { const fs = require('fs'); fs.writeFileSync(envPath, require('../envfile').setKey(fs.readFileSync(envPath, 'utf-8'), 'MEMHOUSE_DB', 'mem')); noteEnvRead(); } catch { /* env not writable: this process still adopts */ }
+        }
         process.env.MEMHOUSE_DB = 'mem'; client = makeClient();
-        console.error(`[memhouse] your rooms moved: ${db}.messages is now mem.${mine} — env now says MEMHOUSE_DB=mem`);
+        console.error(readOnly
+          ? `[memhouse] your rooms moved: ${db}.messages is now mem.${mine} — reading mem; memhouse update records it in the env`
+          : `[memhouse] your rooms moved: ${db}.messages is now mem.${mine} — env now says MEMHOUSE_DB=mem`);
       }
     }
   } catch { /* unreachable or unreadable: the pass will say */ }
@@ -1618,6 +1653,7 @@ async function main() {
             for (const k of drift.changed) process.env[k] = drift.values[k];
             client = makeClient();
             adoptedCredential = true;
+            noteEnvRead();
             console.error(`[memhouse] ${envPath} holds a newer ${drift.changed.map((k) => k.replace('MEMHOUSE_', '').toLowerCase()).join('/')} — adopting it and retrying now`);
           } else {
             console.error(`[memhouse] the credential this shipper holds was rejected by ${process.env.MEMHOUSE_URL} (and ${envPath} says the same)`);
@@ -1660,7 +1696,54 @@ async function main() {
 
 module.exports = { runShip, ensureSchema, refreshStats, templateColumns, decideEpoch, tailRows, tailSafe, rowsForChat, buildRows, SUBAGENT_SEQ_BASE, SUBAGENT_SEQ_STRIDE };
 
-if (require.main === module) {
+// Schema v3 (docs/design/source-identity.md): the capture engine replaces this shipper's pass.
+// `--v3`, or MEMHOUSE_SCHEMA=3 in the environment, hands the whole run to capture.js — except
+// the two non-shipping modes the CLI runs through this entry point, which must NOT turn into a
+// capture pass on a schema-3 install (`memhouse update` runs --ensure-schema with a 120 s
+// timeout; `memhouse stats` runs --stats):
+//   --ensure-schema   create what this credential may of the member's eight profile tables
+//                     (harness-sessions-sql), then verify all eight (keys included); exit 1 when any is
+//                     missing or wrong
+//   --stats           per-harness counts from sessions FINAL
+const V3 = require.main === module && (process.argv.includes('--v3') || process.env.MEMHOUSE_SCHEMA === '3');
+async function v3NonShipping(argv) {
+  const env = process.env;
+  const { httpTransport, statsV3, renderStats } = require('../house/q-cli');
+  let password = env.MEMHOUSE_PASSWORD || '';
+  if (!password && env.MEMHOUSE_PASSWORD_FILE) password = require('fs').readFileSync(env.MEMHOUSE_PASSWORD_FILE, 'utf-8').replace(/\r?\n$/, '');
+  const db = env.MEMHOUSE_DB || 'mem';
+  const t = httpTransport({ url: env.MEMHOUSE_URL || 'http://localhost:8123', user: env.MEMHOUSE_USER || 'default', password, db: '', timeout: 110000 });
+  const member = env.MEMHOUSE_MEMBER || (await t.q.rows('SELECT currentUser() AS u'))[0].u;
+  if (argv.includes('--stats')) {
+    const Q = require('../house/queries-v3');
+    for (const l of renderStats(await statsV3(t.exec, Q.v3Rooms(member, db)))) console.log(l);
+    return 0;
+  }
+  // A member on the 0.20 development layout is moved by its admin, never by laying the profile
+  // beside <m>_turns here (`memhouse update` runs this): that would make it look converted.
+  const sc = require('../house/schema-choice');
+  const dev = sc.devLayoutRefusal(await sc.detectHouseSchema((sql) => t.q.rows(sql), db, member), member);
+  if (dev) { console.error(`[memhouse] --ensure-schema: ${dev}`); return 1; }
+  const sp = require('../house/schema-profile');
+  const s = await sp.ensureProfileSchema(t.q, { db, member });
+  const bad = Object.values(s.tables).filter((x) => x.problem);
+  if (s.unhealed.length && env.MEMHOUSE_QUIET_DENIED !== '1') console.error(`[memhouse] ${member}: ${s.unhealed.join(', ')} — capture writes the old types until an admin retypes them (memhouse install --schema 3 --admin-user …)`);
+  if (!bad.length) { console.log(`[memhouse] schema ensured (schema 3, harness-sessions-sql's profile: ${Object.values(s.tables).map((x) => x.fq).join(', ')})`); return 0; }
+  if (env.MEMHOUSE_QUIET_DENIED !== '1') {
+    console.error(`[memhouse] schema-3 tables not ready for ${member}: ${bad.map((x) => `${x.fq} ${x.problem}`).join('; ')}`);
+    if (s.denied.length) console.error(`[memhouse] not permitted for ${member}: ${s.denied.join('; ')} — an admin creates them (memhouse install --schema 3 --admin-user …)`);
+  }
+  return 1;
+}
+if (V3 && (process.argv.includes('--ensure-schema') || process.argv.includes('--stats'))) {
+  v3NonShipping(process.argv.slice(2)).then((code) => { process.exitCode = code; },
+    (e) => { console.error(`[memhouse] fatal: ${e.message}`); process.exit(1); });
+} else if (V3) {
+  // The capture loop checks for an upgrade after every interval, as the 0.18 loop does below.
+  require('./capture').main(process.argv.slice(2).filter((a) => a !== '--v3'), {
+    afterSleep: () => selfUpdate.maybeRestart({ snap: selfSnap, name: 'shipper' }),
+  }).catch((e) => { console.error(`[memhouse] fatal: ${e.message}`); process.exit(1); });
+} else if (require.main === module) {
   main().catch((e) => {
     // A permissions failure here is not a crash — the CALLER (install, doctor) catches the
     // same condition and prints a refusal naming both routes. Printing "[memhouse] fatal:"

package/memhouse/shipper/snapshots.js

@@ -0,0 +1,193 @@
+'use strict';
+// Snapshots: the source side of the bridge (editors/bridge.js). Every editor without a
+// transcript-file capture keeps its 0.18 reader; this module runs those readers and writes each
+// session they return as a snapshot log, $MEMHOUSE_HOME/snapshots/<harness>/<session>.jsonl,
+// which the capture engine then reads like any transcript.
+//
+// The log stays append-only whenever the session only grew: a message already written keeps its
+// line byte for byte (and so its timestamp), new messages are appended, and a changed name or
+// folder is appended as a new meta line. Only when the editor's own history changed (a message
+// edited, removed or reordered) is the file rewritten — atomically, through a temp file — and the
+// engine sees a rewrite: new fgen, vanished keys tombstoned.
+//
+// A session is re-read only when its editor reports a different lastUpdatedAt or message count
+// than the last pass recorded (index.json beside the logs), so a pass over unchanged editors costs
+// one getChats() per editor.
+
+const fs = require('fs');
+const path = require('path');
+const { fileNameFor } = require('../../editors/bridge');
+
+const TEXT_MAX = 50000;    // as 0.18's messages.text, so dedupe compares like with like
+const TOOL_CALL_RE = /\[tool-call: ([^(\]]+)/g;
+const NATIVE = new Set(['claude', 'codex']);   // adapters with their own file capture
+
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  const cut = s.slice(0, max);
+  const last = cut.charCodeAt(cut.length - 1);
+  return (last >= 0xD800 && last <= 0xDBFF) ? cut.slice(0, -1) : cut;
+}
+function ownTs(m) { const at = Number(m && m._ts); return Number.isFinite(at) && at > 0 ? (at < 1e11 ? at * 1000 : at) : null; }
+function interpTs(chat, pos, total) {
+  const start = chat.createdAt || chat.lastUpdatedAt || Date.now();
+  const end = chat.lastUpdatedAt || chat.createdAt || start;
+  if (total <= 1) return start;
+  return start + Math.round((end - start) * (pos / (total - 1)));
+}
+function num(v) { const x = Math.trunc(Number(v)); return Number.isFinite(x) && x > 0 ? x : 0; }
+
+/** The snapshot line for message `pos` of a parse — the same text and calls 0.18's buildRows produced. */
+function messageLine(chat, m, pos, total) {
+  const raw = typeof m.content === 'string' ? m.content : (JSON.stringify(m.content) ?? '');
+  const text = truncate(raw, TEXT_MAX);
+  const own = ownTs(m);
+  const line = { k: 'msg', i: pos, role: String(m.role || ''), text, ts: own ?? interpTs(chat, pos, total), tsk: own ? 'own' : 'interp' };
+  if (m._model) line.model = String(m._model);
+  const tok = { in: num(m._inputTokens), out: num(m._outputTokens), cr: num(m._cacheRead), cw: num(m._cacheWrite) };
+  if (tok.in || tok.out || tok.cr || tok.cw) line.tok = tok;
+  if (m.role === 'assistant') {
+    let calls;
+    if (Array.isArray(m._toolCalls) && m._toolCalls.length) calls = m._toolCalls.map((tc) => ({ name: String(tc.name || 'unknown'), args: tc.args || {} }));
+    else { calls = []; for (const x of text.matchAll(TOOL_CALL_RE)) calls.push({ name: x[1].trim(), args: {} }); }
+    if (calls.length) line.tools = calls;
+  }
+  return line;
+}
+function metaOf(chat) {
+  return { k: 'meta', name: chat.name || '', mode: chat.mode || '', folder: chat.folder || '', created: Number(chat.createdAt) || 0, updated: Number(chat.lastUpdatedAt) || 0, branch: chat._gitBranch || '' };
+}
+const sameMeta = (a, b) => a && b && a.name === b.name && a.mode === b.mode && a.folder === b.folder && a.branch === b.branch;
+
+function readLines(file) {
+  let s;
+  try { s = fs.readFileSync(file, 'utf-8'); } catch { return null; }
+  const out = [];
+  for (const l of s.split('\n')) { if (!l) continue; try { out.push({ raw: l, o: JSON.parse(l) }); } catch { return null; } }
+  return out;
+}
+
+/**
+ * Bring one session's snapshot up to date. Returns 'new' | 'append' | 'rewrite' | 'same'.
+ */
+function writeSession(file, chat, messages) {
+  const total = messages.length;
+  const old = readLines(file);
+  const oldMsgs = old ? old.filter((x) => x.o.k === 'msg') : [];
+  const lastMeta = old ? [...old].reverse().find((x) => x.o.k === 'meta') : null;
+  // Keep every already-written message line whose content is unchanged (text, role, model,
+  // tokens, calls): its timestamp was fixed when it was first written.
+  const fresh = messages.map((m, pos) => messageLine(chat, m, pos, total));
+  let keep = 0;
+  while (keep < oldMsgs.length && keep < fresh.length) {
+    const a = oldMsgs[keep].o, b = fresh[keep];
+    const same = a.role === b.role && a.text === b.text && (a.model || '') === (b.model || '')
+      && JSON.stringify(a.tok || null) === JSON.stringify(b.tok || null) && JSON.stringify(a.tools || null) === JSON.stringify(b.tools || null);
+    if (!same) break;
+    keep++;
+  }
+  const meta = metaOf(chat);
+  if (old && keep === oldMsgs.length) {
+    // Only grew (or nothing changed): append new messages, and a meta line if the session's name,
+    // mode, folder or branch changed. New messages without an own time are dated by the span now.
+    const add = [];
+    if (!sameMeta(lastMeta && lastMeta.o, meta)) add.push(JSON.stringify(meta));
+    for (let i = keep; i < fresh.length; i++) add.push(JSON.stringify(fresh[i]));
+    if (!add.length) return 'same';
+    fs.appendFileSync(file, add.map((l) => `${l}\n`).join(''));
+    return 'append';
+  }
+  // New, or the editor's history changed: write the whole log, keeping the lines that still hold.
+  const lines = [JSON.stringify(meta)];
+  for (let i = 0; i < fresh.length; i++) lines.push(i < keep ? oldMsgs[i].raw : JSON.stringify(fresh[i]));
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, lines.map((l) => `${l}\n`).join(''));
+  fs.renameSync(tmp, file);
+  return old ? 'rewrite' : 'new';
+}
+
+/**
+ * Run every bridged editor's reader and update the snapshot logs.
+ * @param {object} o
+ * @param {string} o.home          $MEMHOUSE_HOME
+ * @param {object[]} [o.adapters]  0.18 adapters (default: editors/index.js, narrowed by MEMHOUSE_EDITORS)
+ * @param {string} [o.editors]     the MEMHOUSE_EDITORS value to narrow by (default: the environment's)
+ * @param {Function} [o.getMessages]
+ * @returns {{ dir, harnesses: string[], stats }}
+ */
+function materialize(o = {}) {
+  const dir = path.join(o.home, 'snapshots');
+  const idx = o.adapters ? null : require('../../editors/index');
+  let adapters = o.adapters;
+  if (!adapters) {
+    const scope = require('../../editors/scope');
+    adapters = scope.selectEditors(idx.editors, o.editors !== undefined ? o.editors : process.env.MEMHOUSE_EDITORS);
+  }
+  adapters = adapters.filter((a) => !NATIVE.has(a.name) && !(a.capture && !a.capture.bridged));
+  const getMessages = o.getMessages || (idx ? idx.getMessages : (chat) => chat._adapter.getMessages(chat));
+  const indexFile = path.join(dir, 'index.json');
+  let index = {};
+  try { index = JSON.parse(fs.readFileSync(indexFile, 'utf-8')) || {}; } catch { index = {}; }
+  const stats = { editors: 0, chats: 0, read: 0, new: 0, append: 0, rewrite: 0, same: 0, errors: 0, ms: 0 };
+  const t0 = Date.now();
+  const seen = new Set();
+  for (const a of adapters) {
+    let chats = [];
+    try { chats = a.getChats() || []; } catch (e) { stats.errors++; (o.log || (() => {}))(`[memhouse] bridge: ${a.name}: ${e.message}`); continue; }
+    if (chats.length) stats.editors++;
+    // One session id reported twice (the same chat under two roots or stores): keep the longer,
+    // then the newer — as discover() does for a file under two roots. Otherwise the two would
+    // overwrite each other's log on every pass.
+    const best = new Map();
+    for (const chat of chats) {
+      const k = `${chat.source || a.name}\t${chat.composerId}`;
+      const b = best.get(k);
+      const better = !b || (Number(chat.bubbleCount) || 0) > (Number(b.bubbleCount) || 0)
+        || ((Number(chat.bubbleCount) || 0) === (Number(b.bubbleCount) || 0) && (Number(chat.lastUpdatedAt) || 0) > (Number(b.lastUpdatedAt) || 0));
+      if (b) stats.duplicates = (stats.duplicates || 0) + 1;
+      if (better) best.set(k, chat);
+    }
+    for (const chat of best.values()) {
+      const harness = String(chat.source || a.name);
+      if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(harness) || chat.composerId == null) continue;
+      stats.chats++;
+      const k = `${harness}\t${chat.composerId}`;
+      seen.add(harness);
+      const hdir = path.join(dir, harness);
+      const file = path.join(hdir, fileNameFor(chat.composerId));
+      const prev = index[k];
+      if (prev && prev.updated === (Number(chat.lastUpdatedAt) || 0) && prev.count === (Number(chat.bubbleCount) || 0) && fs.existsSync(file)) { stats.same++; continue; }
+      let messages;
+      try { messages = (o.adapters ? a.getMessages(chat) : getMessages(chat)) || []; } catch (e) { stats.errors++; continue; }
+      if (messages._defer) continue;
+      stats.read++;
+      fs.mkdirSync(hdir, { recursive: true });
+      const r = writeSession(file, chat, messages);
+      stats[r]++;
+      index[k] = { updated: Number(chat.lastUpdatedAt) || 0, count: Number(chat.bubbleCount) || 0 };
+    }
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${indexFile}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(index));
+  fs.renameSync(tmp, indexFile);
+  // Every harness with a snapshot directory is a root, including one whose editor returned nothing
+  // this pass: its logs stay captured (nothing is deleted here).
+  let harnesses = [];
+  try { harnesses = fs.readdirSync(dir).filter((n) => { try { return fs.statSync(path.join(dir, n)).isDirectory(); } catch { return false; } }); } catch { /* none */ }
+  stats.ms = Date.now() - t0;
+  return { dir, harnesses, stats };
+}
+
+/** The capture roots and adapters for the snapshot directories under `dir`. */
+function bridgeRoots(dir, harnesses) {
+  const { bridgeCapture } = require('../../editors/bridge');
+  // harness_path: the editor's data folder (editors/harness-paths.js), the same store key its v4
+  // normaliser will use, so switching a harness off the bridge keeps its sessions' keys.
+  const { dataFolder } = require('../../editors/harness-paths');
+  const roots = harnesses.map((h) => ({ harness: h, name: 'default', dir: path.join(dir, h), harness_path: dataFolder(h, { fallback: path.join(dir, h) }) }));
+  const adapters = Object.fromEntries(harnesses.map((h) => [h, bridgeCapture(h)]));
+  return { roots, adapters };
+}
+
+module.exports = { materialize, bridgeRoots, writeSession, messageLine, metaOf, NATIVE };

package/memhouse/shipper/source-roots.js

@@ -0,0 +1,111 @@
+// The default MEMHOUSE_SOURCE_ROOTS — what the schema-3 capture reads when nothing names it.
+//
+// The rule: exactly what the 0.18 shipper reads on this machine, for the two harnesses the
+// capture engine has adapters for. Two scopes that disagreed would make a schema-3 install
+// silently ship less (or more) than the same machine shipped the day before.
+//
+//   claude-code  every Claude Code config dir the legacy adapter finds
+//                (editors/claude.js discoverClaudeRoots: ~/.claude, each
+//                ~/.claude-playbooks/<name>[/playbook]; MEMHOUSE_CLAUDE_ROOTS REPLACES that
+//                list, as it does for the legacy shipper) — only those holding a projects/
+//                dir, since that is where the transcripts are. Each root is named by its
+//                directory (`default` for ~/.claude, the playbook name otherwise), the same
+//                rule the conversion uses for `root`.
+//   codex        <codex home>/sessions and <codex home>/archived_sessions, whichever exist.
+//                The codex home is MEMHOUSE_CODEX_ROOTS, else CODEX_HOME, else ~/.codex —
+//                the legacy adapter's order.
+//
+// MEMHOUSE_EDITORS narrows it the same way it narrows the legacy shipper: `claude` and
+// `codex` are the adapter names; an editors list that names neither yields no roots.
+//
+// Pure apart from the filesystem reads; `home`/`env` are injectable so a test can point it
+// at a synthetic tree (the Claude discovery itself is the adapter's, which reads $HOME).
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+function parseList(v) { return String(v || '').split(',').map((s) => s.trim()).filter(Boolean); }
+function expandHome(p, home) { return p === '~' ? home : p.startsWith('~/') ? path.join(home, p.slice(2)) : p; }
+
+/** ~/.claude is `default`; a playbook install is its own name (draft 5 §3 `root`). */
+function claudeRootName(configDir) {
+  const b = path.basename(configDir);
+  if (b === '.claude' || b === 'claude') return 'default';
+  if (b === 'playbook') return path.basename(path.dirname(configDir));
+  return b.replace(/^\./, '') || 'default';
+}
+
+/**
+ * The Claude Code config dirs, as the legacy adapter finds them. `discover` is injectable
+ * for tests; by default it is editors/claude.js, so the two cannot drift.
+ */
+function claudeConfigDirs({ discover = null } = {}) {
+  const fn = discover || require('../../editors/claude').discoverClaudeRoots;
+  return fn();
+}
+
+function codexHome({ env = process.env, home = os.homedir() } = {}) {
+  const override = parseList(env.MEMHOUSE_CODEX_ROOTS).map((p) => expandHome(p, home));
+  if (override.length) return override[0];
+  if (env.CODEX_HOME && env.CODEX_HOME.trim()) return path.resolve(env.CODEX_HOME.trim());
+  return path.join(home, '.codex');
+}
+
+/**
+ * @returns {{ roots: [{harness, dir, name}], spec: string, skipped: [{dir, why}] }}
+ *   `roots` is what capture.js reads (the shape parseSourceRoots returns); `spec` the same as
+ *   a MEMHOUSE_SOURCE_ROOTS value, for display and for pinning it in an env file.
+ */
+function defaultSourceRoots({ env = process.env, home = os.homedir(), discover = null } = {}) {
+  const editors = parseList(env.MEMHOUSE_EDITORS);
+  const want = (name) => !editors.length || editors.includes(name) || (name === 'claude' && editors.includes('claude-code'));
+  const roots = [];
+  const skipped = [];
+  const seen = new Set();
+  const add = (r) => {
+    let rp; try { rp = fs.realpathSync(r.dir); } catch { rp = r.dir; }
+    if (seen.has(rp)) return;
+    seen.add(rp);
+    roots.push(r);
+  };
+  if (want('claude')) {
+    for (const d of claudeConfigDirs({ discover })) {
+      const projects = path.join(d, 'projects');
+      if (!isDir(projects)) { skipped.push({ dir: d, why: 'no projects/ (history.jsonl only)' }); continue; }
+      add({ harness: 'claude-code', dir: projects, name: claudeRootName(d) });
+    }
+  }
+  if (want('codex')) {
+    const ch = codexHome({ env, home });
+    for (const sub of ['sessions', 'archived_sessions']) {
+      const d = path.join(ch, sub);
+      if (isDir(d)) add({ harness: 'codex', dir: d, name: 'default' });
+    }
+  }
+  const spec = roots.map((r) => `${r.harness === 'codex' ? 'codex' : 'claude'}:${r.name}=${r.dir}`).join(',');
+  return { roots, spec, skipped };
+}
+
+/**
+ * The roots a schema-3 capture will read under this environment: MEMHOUSE_SOURCE_ROOTS when
+ * set (parsed by capture.js's own parser), the default otherwise.
+ * @returns {{ roots, spec, defaulted: boolean, error: string|null }}
+ */
+function effectiveSourceRoots({ env = process.env, home = os.homedir(), discover = null } = {}) {
+  if (env.MEMHOUSE_SOURCE_ROOTS) {
+    try {
+      const { parseSourceRoots } = require('./capture');
+      return { roots: parseSourceRoots(env.MEMHOUSE_SOURCE_ROOTS), spec: env.MEMHOUSE_SOURCE_ROOTS, defaulted: false, error: null };
+    } catch (e) { return { roots: [], spec: env.MEMHOUSE_SOURCE_ROOTS, defaulted: false, error: e.message }; }
+  }
+  try {
+    const d = defaultSourceRoots({ env, home, discover });
+    return { roots: d.roots, spec: d.spec, defaulted: true, error: null, skipped: d.skipped };
+  } catch (e) { return { roots: [], spec: '', defaulted: true, error: e.message }; }
+}
+
+module.exports = { defaultSourceRoots, effectiveSourceRoots, claudeRootName, codexHome, claudeConfigDirs };

package/memhouse/version-notice.js

@@ -0,0 +1,66 @@
+// A new minor (or major) version's first run says so, once, and points at its release notes.
+//
+// `npm install -g memhouse` never runs `update`, so nothing told a machine that crossed a minor
+// version (0.20 is a different house layout from 0.18) what had changed or what to do. A stamp in
+// the home records the last version that ran here; when the line (major.minor) is newer, the
+// first CLI call prints one notice to stderr (so --json stays clean) and moves the stamp. A patch
+// release and a downgrade move the stamp silently.
+//
+// Versions before this notice wrote no stamp, so with none the previous version is inferred:
+//   skills-checked   the version 0.20.0's /mem skills refresh recorded (memhouse/plugin-copies.js);
+//                    read before that refresh moves it, so this runs first
+//   the env file     MEMHOUSE_SCHEMA=3 means a 0.20 install; any other install ran 0.18 or earlier
+//   neither          a fresh install: stamped silently, there is nothing to compare with
+
+const fs = require('fs');
+const path = require('path');
+
+const STAMP = 'version-seen';
+const SKILLS_STAMP = 'skills-checked';
+const lineOf = (v) => { const m = /^(\d+)\.(\d+)/.exec(String(v || '')); return m ? `${m[1]}.${m[2]}` : null; };
+const lineNum = (l) => l.split('.').map(Number);
+
+/**
+ * The notice for going from `seen` to `version`, or null: only for a newer major.minor. `seenLabel`
+ * is how the previous version is named when it was inferred ("0.18 or earlier"). Pure.
+ */
+function noticeFor({ seen, version, notesPath = null, seenLabel = null }) {
+  const a = lineOf(seen); const b = lineOf(version);
+  if (!a || !b || a === b || seen === version) return null;
+  const [am, an] = lineNum(a); const [bm, bn] = lineNum(b);
+  if (bm < am || (bm === am && bn < an)) return null;   // a downgrade is not news about a release
+  return `memhouse ${version} is new on this machine (it ran ${seenLabel || seen} before). What changed and what to do: ${notesPath || `docs/releases/v${version}.md`}`;
+}
+
+/** The version that ran here before, when no stamp says it: { seen, label } or null (fresh). */
+function inferPrevious(home) {
+  try { const v = fs.readFileSync(path.join(home, SKILLS_STAMP), 'utf-8').trim(); if (lineOf(v)) return { seen: v, label: null }; } catch { /* none */ }
+  let env;
+  try { env = fs.readFileSync(path.join(home, 'env'), 'utf-8'); } catch { return null; }
+  if (/^MEMHOUSE_SCHEMA=['"]?3['"]?\s*$/m.test(env)) return { seen: '0.20.0', label: '0.20' };
+  return { seen: '0.18.0', label: '0.18 or earlier' };
+}
+
+/**
+ * Check, print once, and stamp. `home` is the memhouse home; nothing happens when it does not
+ * exist (no install here) or from a git checkout. Never throws.
+ */
+function checkVersionNotice({ home, version, repoRoot, log = () => {} }) {
+  try {
+    if (!home || !fs.existsSync(home)) return null;
+    // From a git checkout, nothing: a development run must not stamp a real home with its version.
+    if (repoRoot && fs.existsSync(path.join(repoRoot, '.git'))) return null;
+    const stamp = path.join(home, STAMP);
+    let prev = null;
+    try { const v = fs.readFileSync(stamp, 'utf-8').trim(); if (v) prev = { seen: v, label: null }; } catch { /* none yet */ }
+    if (!prev) prev = inferPrevious(home);
+    if (prev && prev.seen === version) return null;
+    const notes = repoRoot ? path.join(repoRoot, 'docs', 'releases', `v${String(version).split('-')[0]}.md`) : null;
+    const msg = prev ? noticeFor({ seen: prev.seen, version, seenLabel: prev.label, notesPath: notes && fs.existsSync(notes) ? notes : null }) : null;
+    if (msg) log(msg);
+    try { fs.writeFileSync(stamp, `${version}\n`); } catch { /* not writable: asked again next run */ }
+    return msg;
+  } catch { return null; }
+}
+
+module.exports = { STAMP, SKILLS_STAMP, lineOf, noticeFor, inferPrevious, checkVersionNotice };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memhouse",
-  "version": "0.18.12",
-  "description": "memhouse \u2014 agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, kernel-agency install, and the agentlytics dashboard",
+  "version": "0.20.1",
+  "description": "memhouse — agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, and the agentlytics dashboard",
   "main": "bin/memhouse.js",
   "bin": {
     "memhouse": "./bin/memhouse.js"
@@ -9,6 +9,9 @@
   "files": [
     "bin/",
     "memhouse/",
+    "!memhouse/DESIGN.md",
+    "!memhouse/COMPETITION.md",
+    "!memhouse/RESUME-AND-UPDATE.md",
     "misc/syntax-check.js",
     "pricing.js",
     "pricing.json",
@@ -18,9 +21,12 @@
     "ui/package.json",
     "ui/package-lock.json",
     "ui/vite.config.js",
+    "ui/third-party-notices.js",
     "ui/eslint.config.js",
     "public/",
     "README.md",
+    "NOTICE",
+    "LICENSES/",
     "docs/README.md",
     "docs/tutorials/",
     "docs/guides/",
@@ -34,7 +40,7 @@
     "start": "node bin/memhouse.js",
     "build": "cd ui && npm install && npm run build",
     "dev": "cd ui && npm run dev",
-    "test": "node misc/syntax-check.js && node misc/unit-test.js && node misc/env-guard-test.js && node misc/skill-allowlist-test.js",
+    "test": "node misc/syntax-check.js && node misc/unit-test.js && node misc/v3-read-unit.js && node misc/v3-cli-unit.js && node misc/capture-test.js && node misc/dedupe-test.js && node misc/dedupe-profile-test.js && node misc/profile-edges-test.js && node misc/profile-routing-test.js && node misc/log-adapter-test.js && node misc/bridge-test.js && node misc/layout32-test.js && node misc/v4-opencode-test.js && node misc/normalise/run-all.js && node misc/maintenance-test.js && node misc/no-credentials-test.js && node misc/kav-test.js && node misc/publish-guard-test.js && node misc/records-to-rows-test.js && node misc/adapter-capture-test.js && node misc/import-claude-ai-test.js && node misc/records-to-profile-test.js && node misc/profile-capture-twin-test.js && node misc/profile-vanished-test.js && node misc/env-guard-test.js && node misc/skill-allowlist-test.js && node misc/plugin-copies-test.js && node misc/codex-plugin-test.js && node misc/host-alias-test.js && node misc/registry-test.js && node misc/doctor-tail-test.js && node misc/dashboard-auth-test.js",
     "test:house": "node misc/house-test.js",
     "prepack": "cd ui && npm install --no-audit --no-fund && npm run build",
     "prepublishOnly": "node misc/publish-guard.js"
@@ -51,15 +57,16 @@
     "memhouse"
   ],
   "author": "Ramazan Polat (built on agentlytics by fkadev)",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "engines": {
     "node": ">=24.0.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/agent-realm/memhouse"
+  "homepage": "https://memhouse.io",
+  "bugs": {
+    "email": "security@memhouse.io"
   },
   "dependencies": {
+    "@agent-realm/harness-session-adapters": "1.0.0",
     "@clickhouse/client": "^1.23.1",
     "express": "^4.22.1"
   }

package/public/THIRD_PARTY_NOTICES.txt

@@ -1578,7 +1578,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ========================================================================
-react-router 7.18.1 — MIT
+react-router 7.18.4 — MIT
 https://github.com/remix-run/react-router
 ------------------------------------------------------------------------
 MIT License
@@ -1606,7 +1606,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ========================================================================
-react-router-dom 7.18.1 — MIT
+react-router-dom 7.18.4 — MIT
 https://github.com/remix-run/react-router
 ------------------------------------------------------------------------
 MIT License