memhouse 0.20.0 → 0.20.2

package/memhouse/flags.js

@@ -43,7 +43,7 @@ const COMMAND_FLAGS = {
   update: ['check', 'migrate', 'no-install', 'channel'],
   reset: ['all-origins'],
   invite: ['url', 'db', 'out', 'admin-user', 'admin-password-file', 'adopt', 'print-sql',
-    'allow-local', 'member-password', 'member-password-file', 'schema'],
+    'allow-local', 'member-password', 'member-password-file', 'schema', 'expires'],
   passwd: ['password', 'password-file', 'admin-user', 'admin-password-file', 'print-sql', 'member'],
   nightly: ['out'],
   migrate: ['dry-run', 'v3-prepare', 'v3-convert', 'v3-reconcile', 'v3-shares', 'v3-switch', 'member', 'batch-rows', 'force-after-dedupe',

package/memhouse/help.js

@@ -0,0 +1,37 @@
+// `memhouse <command> --help`: that command's entries from the full help (bin/memhouse.js HELP),
+// not the whole page. The full help stays the one text: an entry starts in column 13 (after the
+// section label or 13 spaces), and its continuation lines are indented further. Pure.
+
+const COL = 13;
+
+/** The entries of `help`: [{ words, lines }], `words` being the command names the entry is for. */
+function entries(help) {
+  const out = [];
+  let cur = null;
+  for (const line of String(help).split('\n')) {
+    const m = /^([A-Za-z]*)( +)(\S.*)$/.exec(line);
+    if (m && m[1].length + m[2].length === COL) {
+      // `start | stop | status   …` is one entry for three commands.
+      const name = m[3].split(/\s{2,}/)[0];
+      const words = /^[a-z][a-z-]*( \| [a-z][a-z-]*)+/.test(name)
+        ? name.split(/\s*\|\s*/).map((w) => w.split(/\s+/)[0]).filter(Boolean)
+        : [name.split(/\s+/)[0]];
+      cur = { words, lines: [`${' '.repeat(COL)}${m[3]}`] };
+      out.push(cur);
+    } else if (cur && /^ {20,}\S/.test(line)) {
+      cur.lines.push(line);
+    } else {
+      cur = null;
+    }
+  }
+  return out;
+}
+
+/** The help for `cmd`, or null when no entry names it (the caller prints the full help). */
+function helpFor(help, cmd, version) {
+  const mine = entries(help).filter((e) => e.words.includes(cmd));
+  if (!mine.length) return null;
+  return [`memhouse ${version} — ${cmd}`, '', ...mine.flatMap((e) => e.lines), '', 'Every command: memhouse --help'].join('\n');
+}
+
+module.exports = { entries, helpFor };

package/memhouse/house/q-cli.js

@@ -741,6 +741,19 @@ function hasFormat(sql) {
   return /\bFORMAT\s+[A-Za-z0-9_]+\s*$/i.test(s);
 }
 
+/**
+ * What `memhouse room-sql` sends: the statement as written, and the output format as the
+ * default_format setting. A FORMAT appended to the statement fails where the statement takes
+ * none (ClickHouse 25.11 parses no FORMAT after a bare SHOW ROW POLICIES); a setting applies to
+ * every statement, and a FORMAT the statement names itself still wins. --json picks the format,
+ * so a statement that names one is refused there.
+ */
+function roomSqlRequest(sql, { json = false } = {}) {
+  const body = String(sql).trim().replace(/;\s*$/, '');
+  if (json && hasFormat(body)) throw new QueryInputError('--json picks the format itself — drop the FORMAT clause');
+  return { body, settings: { default_format: json ? 'JSONEachRow' : 'PrettyCompact' } };
+}
+
 /** Refuse what is not a read before it leaves the machine (the server's readonly=2 refuses it too). */
 function assertRead(sql) {
   const s = String(sql).replace(/--[^\n]*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').trim();
@@ -858,6 +871,6 @@ module.exports = {
   renderSchemaBlocks,
   NAMES, ALIASES, FILTER_FLAGS, QueryInputError,
   schemaOf, httpTransport, fmtTop, fmtInner, parseWhen, filtersFrom, parseRef, parseQ, runQ, renderQ, allQFlags, canonicalName,
-  resolveRef, hitSpec, lookupSpec, withIso, rewriteRooms, hasFormat, assertRead, statsV3, renderStats, statusV3, statusSpec, machinesFolded,
+  resolveRef, hitSpec, lookupSpec, withIso, rewriteRooms, hasFormat, roomSqlRequest, assertRead, statsV3, renderStats, statusV3, statusSpec, machinesFolded,
   sessionsQueryV3, resumeSpec, table,
 };

package/memhouse/house/records-to-profile.js

@@ -9,6 +9,12 @@
 // record without content_sha and cmp_sha) on every row; on a part row, the sha of the part object
 // as it sits in its message's parts, with message_content_sha the message's. A message's header
 // row (part_id '', kind 'none') carries the message's sha in both.
+//
+// native and units (harness-sessions-sql v1.1, sessions-model §2.7): a record's `native` as
+// canonical JSON text, its `units` as (source_key, generation, unit_key) tuples. A part row carries
+// its message's (message_native, message_units) and its own part_native. A record without them
+// (an adapter older than sessions-model v1.4) leaves the columns out, so the server's defaults
+// ('' and []) stand and a row mapped before them keeps its digest.
 
 const crypto = require('crypto');
 
@@ -30,6 +36,10 @@ const str = (v) => (v == null ? '' : String(v));
 const nb = (v) => (typeof v === 'boolean' ? v : null);
 const nn = (v) => (Number.isFinite(Number(v)) && v !== null && v !== '' ? Number(v) : null);
 const tsOrNull = (v) => (v && Number.isFinite(Date.parse(v)) ? v : null);
+/** A record's native as its column holds it: canonical JSON, or undefined (the column's default) when absent. */
+const nativeText = (v) => (v != null && typeof v === 'object' ? jcs(v) : undefined);
+/** A record's units as named tuples, or undefined (the column's default) when the record states none. */
+const unitsOf = (v) => (Array.isArray(v) ? v.map(([sourceKey, generation, unitKey]) => ({ source_key: str(sourceKey), generation: Number(generation) || 0, unit_key: str(unitKey) })) : undefined);
 
 /** The part columns of one part. */
 function partColumns(p) {
@@ -39,7 +49,7 @@ function partColumns(p) {
     call_id: '', tool_name: '', args: '', server: '', is_error: null, result_status: '', output: '', output_ref: '', output_ref_sha256: '', output_ref_bytes: null,
     output_len: null, truncated: null, exit_code: null, media_type: '', inline_b64: '', ref: '', bytes_len: null, opaque: null, signature_len: null,
     replaces_form: '', replaces_value: '', error_kind: '', error_message: '', http_status: null, level: '', native_type: '',
-    part_source: str(p.source), part_state: str(p.state),
+    part_source: str(p.source), part_state: str(p.state), part_native: nativeText(p.native),
   };
   switch (p.kind) {
     case 'text': case 'notice': case 'summary': case 'reasoning':
@@ -99,7 +109,8 @@ function profileRows(records, key, { firstSeen = () => '1970-01-01T00:00:00.000Z
       source: str(m.source), to_user: nb(m.to_user), to_model: nb(m.to_model), status: str(m.status), state: str(m.state), on_active_branch: nb(m.on_active_branch),
       ts, requested_model: str(m.requested_model), served_model: str(m.served_model), effort: str(m.effort), response_id: str(m.response_id),
       message_aliases: Array.isArray(m.aliases) ? m.aliases.map((a) => ({ id: str(a.id), kind: str(a.kind) })) : [],
-      cmp_sha: str(m.cmp_sha), message_content_sha: msgSha, first_seen: firstSeen(str(m.message_id)),
+      cmp_sha: str(m.cmp_sha), message_content_sha: msgSha, message_native: nativeText(m.native), message_units: unitsOf(m.units),
+      first_seen: firstSeen(str(m.message_id)),
     };
     const ps = Array.isArray(m.parts) ? m.parts : [];
     ps.forEach((p, i) => {
@@ -159,7 +170,7 @@ function profileRows(records, key, { firstSeen = () => '1970-01-01T00:00:00.000Z
     mode: str(s.mode), kind: str(s.kind), reuse: str(s.reuse), ts_source: str(s.ts_source),
     aliases: Array.isArray(s.aliases) ? s.aliases.map((a) => ({ id: str(a.id), kind: str(a.kind) })) : [],
     fingerprint: s.fingerprint && Array.isArray(s.fingerprint.cmp_shas) ? s.fingerprint.cmp_shas.map(String) : [],
-    setup: s.setup == null ? null : jcs(s.setup), content_sha: recordSha(s),
+    setup: s.setup == null ? null : jcs(s.setup), native: nativeText(s.native), units: unitsOf(s.units), content_sha: recordSha(s),
   } : null;
   return { parts, usage, links, lifecycle, session, calls: [...calls.values()].filter((c) => c.call_id && c.tool_name !== undefined) };
 }

package/memhouse/house/schema-choice.js

@@ -6,11 +6,14 @@
 
 const sqlStr = (s) => `'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 
-// ClickHouse's AUTHENTICATION_FAILED. Told by its code, which the HTTP wrappers carry as `chCode`
-// from the X-ClickHouse-Exception-Code header (bin/memhouse.js ch(), q-cli.js httpTransport),
-// never by its prose: a credential the server refused is not a house whose tables are unreadable.
+// ClickHouse's AUTHENTICATION_FAILED, and REQUIRED_PASSWORD (a user that needs a password was
+// given none). Told by the code, which the HTTP wrappers carry as `chCode` from the
+// X-ClickHouse-Exception-Code header (bin/memhouse.js ch(), q-cli.js httpTransport), never by its
+// prose: a credential the server refused is not a house whose tables are unreadable.
 const AUTHENTICATION_FAILED = 516;
-function isAuthFailure(e) { return Number(e && e.chCode) === AUTHENTICATION_FAILED; }
+const REQUIRED_PASSWORD = 194;
+const AUTH_CODES = new Set([AUTHENTICATION_FAILED, REQUIRED_PASSWORD]);
+function isAuthFailure(e) { return AUTH_CODES.has(Number(e && e.chCode)); }
 /** What every caller says when it is one; the caller adds what to set. */
 function authFailureText(user, url) {
   return `could not authenticate${user ? ` as '${user}'` : ''}${url ? ` at ${url}` : ''}`;
@@ -88,7 +91,13 @@ function devLayoutRefusal(det, member) {
   return `the house holds ${member}_turns, the layout of memhouse 0.20's development builds, which harness-sessions-sql's profile replaces — its admin recaptures or converts '${member}' first (docs/guides/upgrade-to-0.20.md)${notice ? `. ${notice}` : ''}`;
 }
 
-function chooseSchema(stated, det, member) {
+/**
+ * @param {{user?:string, url?:string}} [who]  the credential the detection connected as, to name a refusal
+ */
+function chooseSchema(stated, det, member, who = {}) {
+  // A credential the server refused saw nothing: say that, rather than reading the house as new
+  // and letting the next step fail on the same credential.
+  if (det.authFailed) return { refuse: `${authFailureText(who.user, who.url)} — check the user and password, then run this again`, auth: true };
   // Checked before the member's own tables: an --ensure-schema that laid the profile beside
   // <m>_turns must not make the development layout look converted.
   const dev = devLayoutRefusal(det, member);
@@ -109,4 +118,4 @@ function chooseSchema(stated, det, member) {
   return { schema: '3' };   // a new house
 }
 
-module.exports = { detectHouseSchema, chooseSchema, importsNotice, importWritesProfile, devLayoutRefusal, isAuthFailure, authFailureText, AUTHENTICATION_FAILED };
+module.exports = { detectHouseSchema, chooseSchema, importsNotice, importWritesProfile, devLayoutRefusal, isAuthFailure, authFailureText, AUTHENTICATION_FAILED, REQUIRED_PASSWORD };

package/memhouse/house/schema-profile-views.sql.tpl

@@ -0,0 +1,53 @@
+-- memhouse's reading views over one member's profile tables: harness-sessions-sql v1.1 §6
+-- (schema/clickhouse-views.sql), each reading the member's own {db}.{m}_* tables. Rendered by
+-- schema-profile.js with {db} and {m}, after the tables (schema-profile.sql.tpl). Views are not
+-- tables: they are never in the column heal or the key check.
+--   * CREATE OR REPLACE, so a house created before a definition changed gets the new one at its
+--     next ensure (install, update, migrate).
+--   * SQL SECURITY INVOKER: a read runs with the reader's own grants and row policies (share.js),
+--     never the creator's, so a view shows a reader no row the tables would not.
+--   * {m}_session_turns_view, not {m}_session_turns: a table name ending in _turns reads as a 0.18
+--     member's turns room (share.js memberCollisions).
+
+-- §6, session_turns (plan): one row per turn of one session. A turn starts at a message a person
+-- sent in the main conversation (role 'user', source 'user', agent_id '') and runs to the next
+-- one; messages before the first prompt are turn 0. The session key is the view's parameters, so
+-- the filter on the sort-key prefix comes before FINAL:
+--   SELECT * FROM {db}.{m}_session_turns_view(host = '…', harness = '…', harness_path = '…',
+--                                              session_id = '…', incarnation = '')
+CREATE OR REPLACE VIEW {db}.{m}_session_turns_view SQL SECURITY INVOKER AS
+WITH
+  parts AS (
+    SELECT * FROM {db}.{m}_session_parts FINAL
+    WHERE host = {host:String} AND harness = {harness:String}
+      AND harness_path = {harness_path:String}
+      AND session_id = {session_id:String} AND incarnation = {incarnation:String}
+      AND is_deleted = 0 AND removed = 0
+      AND state = 'current' AND part_state IN ('', 'current')
+      AND ifNull(on_active_branch, true)
+  ),
+  messages AS (
+    SELECT message_id,
+           min(order_key) AS order_key,
+           toUInt32(any(role) = 'user' AND any(source) = 'user' AND any(agent_id) = '') AS is_prompt
+    FROM parts
+    GROUP BY message_id
+  ),
+  numbered AS (
+    SELECT message_id, is_prompt,
+           sum(is_prompt) OVER (ORDER BY order_key, message_id
+                                ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS turn
+    FROM messages
+  )
+SELECT n.turn                                                AS turn,
+       anyIf(p.message_id, n.is_prompt = 1)                  AS prompt_message_id,
+       min(p.ts)                                             AS started_at,
+       max(p.ts)                                             AS ended_at,
+       uniqExact(p.message_id)                               AS messages,
+       countIf(p.kind = 'tool_call')                         AS tool_calls,
+       countIf(p.kind = 'tool_result' AND ifNull(p.is_error, false)) AS tool_errors,
+       arraySort(groupUniqArrayIf(p.served_model, p.served_model != '')) AS served_models
+FROM parts AS p
+INNER JOIN numbered AS n USING (message_id)
+GROUP BY n.turn
+ORDER BY n.turn;

package/memhouse/house/schema-profile.js

@@ -8,7 +8,10 @@
 //                                       option, nothing in <db>_archive granted to anyone else
 //
 // The DDL lives in schema-profile.sql.tpl, rendered with {db} and {m}; every statement is
-// CREATE … IF NOT EXISTS. Transport-free like schema-v3.js: every entry point takes `q`.
+// CREATE … IF NOT EXISTS. The reading views (harness-sessions-sql v1.1 §6) live apart, in
+// schema-profile-views.sql.tpl, as CREATE OR REPLACE VIEW: they are not tables, so they stay out
+// of templateColumns, the column heal and the key check. Transport-free like schema-v3.js: every
+// entry point takes `q`.
 
 const fs = require('fs');
 const path = require('path');
@@ -16,6 +19,7 @@ const { assertUsableName, legacyTextIndexDialect, isTextIndexGrammarRefusal, tex
 const { stripComments, qFromClient, DDL_SETTINGS } = require('./schema-v3');
 
 const TEMPLATE = path.join(__dirname, 'schema-profile.sql.tpl');
+const VIEWS_TEMPLATE = path.join(__dirname, 'schema-profile-views.sql.tpl');
 
 // The columns retyped in harness-sessions-sql v1, which ensureProfileSchema brings an older table to:
 // adapter_ver UInt32 -> LowCardinality(String), child_stored Bool -> Nullable(Bool), orig_sha256
@@ -47,19 +51,43 @@ const SERVER_COLUMNS = ['writer', 'ingested_at', 'search_ngram', 'search_word',
 
 function archiveDb(db) { return `${db}_archive`; }
 
-/** Every fully-qualified name of one member's profile tables. */
+/** The reading views, by their name after `<m>_` (schema-profile-views.sql.tpl). */
+const VIEW_TYPES = ['session_turns_view'];
+
+/** Every fully-qualified name of one member's profile tables and views. */
 function profileNames(db, member) {
   assertUsableName(db, 'house');
   assertUsableName(member, 'member');
   const out = { db, archive: archiveDb(db), member };
   for (const t of CONVERSATION_TYPES) out[t] = `${db}.${member}_${t}`;
   for (const t of CAPTURE_TYPES) out[t] = `${archiveDb(db)}.${member}_${t}`;
+  for (const t of VIEW_TYPES) out[t] = `${db}.${member}_${t}`;
   out.meta = `${db}.${member}_meta`;
   out.events = `${db}.${member}_events`;
   return out;
 }
 
 function readTemplate() { return fs.readFileSync(TEMPLATE, 'utf-8'); }
+function readViewsTemplate() { return fs.readFileSync(VIEWS_TEMPLATE, 'utf-8'); }
+
+/** The view statements for one member, in template order: [{ type, fq, sql }]. Each reads the member's own house. */
+function renderViews(tpl, { db, member }) {
+  assertUsableName(db, 'house');
+  assertUsableName(member, 'member');
+  const body = stripComments(tpl).replaceAll('{db}', db).replaceAll('{m}', member);
+  const out = [];
+  for (const raw of body.split(';')) {
+    const sql = raw.trim();
+    if (!sql) continue;
+    const m = /^CREATE OR REPLACE VIEW ([A-Za-z0-9_]+)\.([A-Za-z0-9_]+) SQL SECURITY INVOKER AS\b/.exec(sql);
+    if (!m) throw new Error(`schema-profile views template: unexpected statement: ${sql.slice(0, 80)}`);
+    if (m[1] !== db) throw new Error(`schema-profile views template: '${m[1]}.${m[2]}' is outside the house`);
+    const type = m[2].startsWith(`${member}_`) ? m[2].slice(member.length + 1) : m[2];
+    if (!VIEW_TYPES.includes(type)) throw new Error(`schema-profile views template declares an unknown view '${m[2]}'`);
+    out.push({ type, fq: `${m[1]}.${m[2]}`, sql });
+  }
+  return out;
+}
 
 /** The CREATE statements for one member, in template order: [{ type, database, table, fq, sql }]. */
 function renderStatements(tpl, { db, member }) {
@@ -156,12 +184,12 @@ function msg(e) { return e && e.message ? e.message : String(e); }
  * Create one member's profile tables, idempotently, then verify them against PROFILE_KEYS.
  * As ensureV3Schema: a privilege denial is counted and skipped, a lost create race is success.
  */
-async function ensureProfileSchema(q, { db, member, createDatabases = false, grantCapture = false, tpl = null } = {}, ui = null) {
+async function ensureProfileSchema(q, { db, member, createDatabases = false, grantCapture = false, tpl = null, viewsTpl = null } = {}, ui = null) {
   const n = profileNames(db, member);
   const say = (m) => ui && ui.ok && ui.ok(m);
   const version = String(((await q.rows('SELECT version() AS v', { final: 0 }))[0] || {}).v || '');
   const dialect = textIndexDialectFor(version);
-  const out = { version, dialect, created: [], denied: [], unhealed: [], grants: [], grant_failures: [], tables: {}, ok: false };
+  const out = { version, dialect, created: [], denied: [], unhealed: [], grants: [], grant_failures: [], views: [], view_failures: [], tables: {}, ok: false };
   if (createDatabases) {
     for (const d of [n.db, n.archive]) {
       try { await q.sql(`CREATE DATABASE IF NOT EXISTS ${d}`, DDL_SETTINGS); } catch (e) {
@@ -257,6 +285,18 @@ async function ensureProfileSchema(q, { db, member, createDatabases = false, gra
     }
   }
   if (out.retyped.length) say(`profile tables for ${member}: retyped ${out.retyped.join(', ')}`);
+  // The reading views, over session_parts as healed above. A view is a reader's convenience, not
+  // something the capture writes: a refusal goes to `denied`, any other failure to view_failures,
+  // and neither makes the tables not ok. Not over a session_parts that is missing or lacks a column.
+  if (out.created.includes(n.session_parts) && !lacking.has('session_parts')) {
+    for (const v of renderViews(viewsTpl || readViewsTemplate(), { db, member })) {
+      try { await q.sql(v.sql, DDL_SETTINGS); out.views.push(v.fq); } catch (e) {
+        const m = msg(e);
+        if (isDenied(m)) out.denied.push(`CREATE VIEW ${v.fq}`); else out.view_failures.push(`${v.fq}: ${m.split('\n')[0]}`);
+      }
+    }
+    if (out.views.length) say(`reading views for ${member}: ${out.views.join(', ')}`);
+  }
   if (grantCapture) {
     for (const g of captureGrants(db, member)) {
       try { await q.sql(g, DDL_SETTINGS); out.grants.push(g); } catch (e) {
@@ -284,7 +324,7 @@ async function ensureProfileSchema(q, { db, member, createDatabases = false, gra
 }
 
 module.exports = {
-  TEMPLATE, CONVERSATION_TYPES, CAPTURE_TYPES, PROFILE_TYPES, PROFILE_KEYS, SERVER_COLUMNS,
-  archiveDb, profileNames, readTemplate, renderStatements, templateColumns, templateKeys, rowColumns, insertColumns,
+  TEMPLATE, VIEWS_TEMPLATE, CONVERSATION_TYPES, CAPTURE_TYPES, PROFILE_TYPES, VIEW_TYPES, PROFILE_KEYS, SERVER_COLUMNS,
+  archiveDb, profileNames, readTemplate, readViewsTemplate, renderStatements, renderViews, templateColumns, templateKeys, rowColumns, insertColumns,
   keyProblem, captureGrants, ensureProfileSchema, qFromClient,
 };

package/memhouse/house/schema-profile.sql.tpl

@@ -1,5 +1,7 @@
 -- memhouse's house tables as harness-sessions-sql's ClickHouse profile (step B1, tables and keys). The
--- tables, columns, keys and engines are harness-sessions-sql's schema/clickhouse.sql (v1.0.0);
+-- tables, columns, keys and engines are harness-sessions-sql's schema/clickhouse.sql (v1.1: v1's,
+-- with the native and units columns of §4.2 and §4.3; its reading view is
+-- schema-profile-views.sql.tpl);
 -- memhouse adds, beside them:
 --   * the member prefix {m}_ and the archive database {db}_archive (spec §3: physical names);
 --   * on session_parts: first_seen (a first-seen time, never written into ts), folder, project,
@@ -48,6 +50,8 @@ CREATE TABLE IF NOT EXISTS {db}.{m}_session_parts (
     message_aliases      Array(Tuple(id String, kind LowCardinality(String))),
     cmp_sha              FixedString(64),
     message_content_sha  FixedString(64),
+    message_native       String DEFAULT '',       -- v1.1: the message's native fields (sessions-model §2.7), canonical JSON; '' when none
+    message_units        Array(Tuple(source_key String, generation UInt32, unit_key String)),  -- v1.1: the units the message came from
     kind                 LowCardinality(String),
     text                 String DEFAULT '' CODEC(ZSTD(3)),
     call_id              String DEFAULT '',
@@ -78,6 +82,7 @@ CREATE TABLE IF NOT EXISTS {db}.{m}_session_parts (
     native_type          LowCardinality(String) DEFAULT '',
     part_source          LowCardinality(String) DEFAULT '',
     part_state           LowCardinality(String) DEFAULT '',
+    part_native          String DEFAULT '',       -- v1.1: the part's own native fields, canonical JSON; '' when none
     content_sha          FixedString(64),
     adapter              LowCardinality(String),
     adapter_ver          LowCardinality(String),
@@ -131,6 +136,8 @@ CREATE TABLE IF NOT EXISTS {db}.{m}_sessions (
     aliases          Array(Tuple(id String, kind LowCardinality(String))),
     fingerprint      Array(FixedString(64)),
     setup            Nullable(String),
+    native           String DEFAULT '',                -- v1.1: the session's native fields (sessions-model §2.7), canonical JSON; '' when none
+    units            Array(Tuple(source_key String, generation UInt32, unit_key String)),  -- v1.1: the units the session record came from
     content_sha      FixedString(64),
     adapter          LowCardinality(String),
     adapter_ver      LowCardinality(String),

package/memhouse/invitation.js

@@ -84,13 +84,19 @@ function render(tpl, values) {
  * says. `schema` is the layout the invite provisioned ('3', anything else for the 0.18 rooms);
  * `install` is step 1's block and `version` what `memhouse --version` should print.
  */
-function invitationPage({ out, name, url, db, schema, version, install, inviter, template }) {
+/** When the invite's password stops working, or '' for an invite with no expiry. */
+function expiryLine(expires, inviter) {
+  return expires ? `**This invitation expires at ${expires} (UTC).** Its password stops working then; install before that, or ask ${inviter} for a new one.\n\n` : '';
+}
+
+function invitationPage({ out, name, url, db, schema, version, install, inviter, template, expires = null }) {
   const file = path.basename(out);
   const text = render(template === undefined ? readTemplate() : template, {
     NAME: name, FILE: file, FILE_ARG: shellWord(file), URL: url, DB: db, VERSION: version,
     INSTALL: install, INVITER: inviter, JOIN: joinStep(file), OWNED: ownedTables({ db, name, schema }),
+    EXPIRY: expiryLine(expires, inviter),
   });
   return { path: path.join(path.dirname(out), PAGE), file, text };
 }
 
-module.exports = { PAGE, TEMPLATE, readTemplate, shellWord, ownedTables, joinStep, render, invitationPage };
+module.exports = { PAGE, TEMPLATE, readTemplate, shellWord, ownedTables, joinStep, expiryLine, render, invitationPage };

package/memhouse/plugin-copies.js

@@ -10,6 +10,8 @@
 //
 // Only copies BOUND TO THIS HOME are touched: a machine can run two instances on two versions,
 // and another instance's copy belongs to that instance's binary. A copy is never downgraded.
+// The Codex copy (memhouse/codex-plugin.js) is refreshed the same way, and only where
+// `plugins install codex` put it: its skill carries memhouse's ownership file and this home.
 // From a git checkout nothing happens unless MEMHOUSE_REFRESH_SKILLS=1: a checkout run with a
 // real MEMHOUSE_HOME would otherwise copy work-in-progress skills over the installed ones.
 
@@ -144,7 +146,7 @@ function fromCheckout(repoRoot) {
  * stamp already names this version. Never throws; returns what it refreshed.
  * @returns {{refreshed: {dir: string, have: string|null}[], skipped: string|null, errors: string[]}}
  */
-function refreshIfStale({ home, version, deliveryDir, repoRoot, env = process.env, targets = null, log = () => {} }) {
+function refreshIfStale({ home, version, deliveryDir, repoRoot, env = process.env, targets = null, codexHome = null, log = () => {} }) {
   const res = { refreshed: [], skipped: null, errors: [] };
   try {
     if (fromCheckout(repoRoot) && env.MEMHOUSE_REFRESH_SKILLS !== '1') { res.skipped = 'checkout'; return res; }
@@ -155,6 +157,16 @@ function refreshIfStale({ home, version, deliveryDir, repoRoot, env = process.en
       try { installInto(s.dir, { deliveryDir, version }); res.refreshed.push(s); log(`/mem skills in ${s.dir} refreshed for ${version}${s.have ? ` (were ${s.have})` : ''} — reload them in Claude Code: /reload-plugins`); }
       catch (e) { res.errors.push(`${s.dir}: ${String(e.message || e).split('\n')[0]}`); }
     }
+    const cxp = require('./codex-plugin');
+    const cx = cxp.staleCopy({ codexHome: codexHome || cxp.codexHome(env), home, version, compareVersions });
+    if (cx) {
+      try {
+        // The block is rewritten only where it still stands: one taken out by hand stays out.
+        cxp.install({ codexHome: cx.codexHome, home: cx.home, bin: cx.bin, version, deliveryDir, onlyWhereInstalled: true });
+        res.refreshed.push({ dir: cx.codexHome, have: cx.have, codex: true });
+        log(`the memhouse skill and block in ${cx.codexHome} refreshed for ${version}${cx.have ? ` (were ${cx.have})` : ''} — they load in the next Codex session`);
+      } catch (e) { res.errors.push(`${cx.codexHome}: ${String(e.message || e).split('\n')[0]}`); }
+    }
     // Stamp only when every copy is current, so a failure is tried again on the next run.
     if (!res.errors.length && fs.existsSync(home)) { try { fs.writeFileSync(stamp, `${version}\n`); } catch { /* home not writable: check again next run */ } }
   } catch (e) { res.errors.push(String(e.message || e).split('\n')[0]); }

package/memhouse/release-hint.js

@@ -0,0 +1,24 @@
+// What doctor says about a gap that a newer release might close (an unpriced model): whether a
+// newer release exists on the channel this install follows, from the registry's dist-tags.
+// Pure: the tags are given (bin/memhouse.js reads them once per doctor).
+
+const chan = require('./channel');
+
+/**
+ * @param {{version:string, pinned?:string|null, tags:Record<string,string>|null}} p
+ * @returns {{known:boolean, up:{target:string,channel:string}|null, channel:string|null}}
+ *   `known` only when the registry answered and this install follows a tag on it.
+ */
+function releaseState({ version, pinned = null, tags = null }) {
+  if (!tags) return { known: false, up: null, channel: null };
+  const channel = chan.pickChannel({ version, pinned, tags }).channel;
+  return { known: !!channel, up: chan.behind({ version, pinned, tags }), channel };
+}
+
+function pricingHint(state, version) {
+  if (state.up) return `memhouse update installs ${state.up.target} from '${state.up.channel}', which may price it`;
+  if (state.known) return `this is the latest release on '${state.channel}' (${version}) and it has no price for it: its cost stays unknown until a release adds one`;
+  return 'prices ship with each release: a newer one may add them (memhouse update), and on the latest one their cost stays unknown until a release does';
+}
+
+module.exports = { releaseState, pricingHint };

package/memhouse/share.js

@@ -195,9 +195,11 @@ function memberCollisions(member, tables) {
 }
 
 // The names memhouse gives a member's tables in the house, as the part after `<m>_`: its tables,
-// the copies migrate keeps of a 0.18 room while it moves one (`<room>__migrating`) and after
-// (`<room>_pre_epoch`), and the scratch table share's probe makes and drops (`_mh_probe_<pid>`).
-const MEMBER_TABLES = [...new Set([...V3_TABLES, ...LEGACY_ROOMS, ...DEV_ROOMS, 'meta', 'events', 'session_stats', 'session_model_stats', 'session_tool_stats',
+// its reading views (schema-profile.js VIEW_TYPES: session_turns_view, named so it does not end in
+// _turns, which memberCollisions reads as a 0.18 member's room), the copies migrate keeps of a
+// 0.18 room while it moves one (`<room>__migrating`) and after (`<room>_pre_epoch`), and the
+// scratch table share's probe makes and drops (`_mh_probe_<pid>`).
+const MEMBER_TABLES = [...new Set([...V3_TABLES, ...LEGACY_ROOMS, ...DEV_ROOMS, 'meta', 'events', 'session_stats', 'session_model_stats', 'session_tool_stats', 'session_turns_view',
   ...LEGACY_ROOMS.flatMap((r) => [`${r}_pre_epoch`, `${r}__migrating`])])];
 const isMemberTable = (rest) => MEMBER_TABLES.includes(rest) || /^_mh_probe_\d+$/.test(rest);
 const startsMemberTable = (p) => [...MEMBER_TABLES, '_mh_probe_1'].some((n) => n.startsWith(`${p}_`));
@@ -716,5 +718,35 @@ function parseShareRecord(value) {
   return m ? { granted: true, scopeRaw: m[1] ? m[1].trim() : null } : { granted: false, scopeRaw: null };
 }
 
+/**
+ * One account's grants from membersAccess, told apart for a reader: its own tables, the tables
+ * of each member it reads (a share), and anything else (a hand-made grant, a wildcard reaching
+ * past its own name). A table belongs to the member whose name is left after the longest
+ * memhouse table name (MEMBER_TABLES) is taken off its end. `policies` are the row policies the
+ * reading credential can list ([{ short_name, table }]); null when it cannot, and then a share's
+ * scope is unknown.
+ * @returns {{ own: string[], shares: {from:string, tables:string[], scoped:boolean|null}[], other: string[] }}
+ */
+function describeAccess({ u, list }, { policies = null } = {}) {
+  const own = []; const other = []; const shared = new Map();
+  for (const label of list || []) {
+    const bare = String(label).replace(/ \(through role [^)]*\)$/, '');
+    const name = bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare;
+    if (name === `${u}_*` || name === `${u}_`) { own.push(label); continue; }
+    const type = [...MEMBER_TABLES, 'session_units', 'session_sources'].filter((t) => name.endsWith(`_${t}`) && name.length > t.length + 1).sort((a, b) => b.length - a.length)[0];
+    const owner = type ? name.slice(0, -(type.length + 1)) : null;
+    if (owner === u) own.push(label);
+    else if (owner && !bare.includes('.') && V3_TABLES.concat(LEGACY_ROOMS).includes(type)) {
+      if (!shared.has(owner)) shared.set(owner, []);
+      shared.get(owner).push(label);
+    } else other.push(label);
+  }
+  const shares = [...shared.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([from, tables]) => ({
+    from, tables,
+    scoped: policies ? policies.some((p) => String(p.short_name).startsWith(`mh_share_${u}_`) && String(p.table).startsWith(`${from}_`)) : null,
+  }));
+  return { own, shares, other };
+}
+
 module.exports = { SCOPE_COLUMNS, parseScope, scopePredicate, policyName, V3_TABLES, scopePredicateV3, shareV3Plan, revokeV3Plan, parseShareRecord,
-  assertName, ident, qual, memberTargets, moveSharePlan, wildcardRevoke, memberCollisions, wildcardOnRevoke, holdsMemberGrant, collidingUsers, ownPolicies, showPoliciesRevokes, wildcardReachText, wildcardAdminLine, shareGate, selectTargets, rolesGranted, reachThroughRoles, revokeRoleReport, revokeCheck, classifyShare, legacyPolicyDrops, readLiveShares, membersGrantsSQL, MEMBERS_ROLE_GRANTS_SQL, membersAccess, roleDifferences, LEGACY_ROOMS };
+  assertName, ident, qual, memberTargets, moveSharePlan, wildcardRevoke, memberCollisions, wildcardOnRevoke, holdsMemberGrant, collidingUsers, ownPolicies, showPoliciesRevokes, wildcardReachText, wildcardAdminLine, shareGate, selectTargets, rolesGranted, reachThroughRoles, revokeRoleReport, revokeCheck, classifyShare, legacyPolicyDrops, readLiveShares, membersGrantsSQL, MEMBERS_ROLE_GRANTS_SQL, membersAccess, describeAccess, roleDifferences, LEGACY_ROOMS };

package/memhouse/shipper/capture.js

@@ -445,6 +445,18 @@ async function tombstonesFor(ctx, fc, vanished, rev, { removed = false } = {}) {
   }
   return out;
 }
+/**
+ * An adapter upgrade's rows, at a rev above every row the house holds for the file. An unchanged
+ * file re-derives at revOf(fgen, upto), the rev its last pass wrote, and at an equal rev the new
+ * version's row would win by insertion order alone. The raise is a rev or two; the next append's
+ * revOf moves on by the length of what it read.
+ */
+async function aboveHouse(ctx, ref, agentId, agentFileIds, rev, res) {
+  const floor = BigInt(await ctx.house.maxRev(ref, agentId, agentFileIds)) + 1n;
+  if (BigInt(rev) >= floor) return { rev, turns: res.turns, calls: res.calls };
+  const up = String(floor);
+  return { rev: up, turns: res.turns.map((r) => ({ ...r, rev: up })), calls: res.calls.map((r) => ({ ...r, rev: up })) };
+}
 /** Keys ({ t: [[message_id, part_id, ts]], c: [[call_id, ts]] }) the new derivation no longer produces. */
 function vanishedFrom(old, res) {
   const have = { t: new Set(res.turns.map(base.turnKey)), c: new Set(res.calls.map(base.callKey)) };
@@ -571,7 +583,10 @@ async function captureFile(ctx, f, H, C, budget) {
       const fbIds = (fb) => Object.fromEntries(Object.entries(fb || {}).filter(([k]) => k.startsWith('id:')));
       const freshState = { ...base.initialState(ad.adapter), fb: rewrite ? fbIds(state && state.fb) : ((state && state.fb) || {}) };
       const res = ad.derive({ file: fc, records, state: freshState });
-      const rev = String(base.revOf(newFgen, newUpto));
+      const at = reAdapter
+        ? await aboveHouse(ctx, refOf(f, ctx.host), f.agent_id || '', ctx.agentFileIds(f), String(base.revOf(newFgen, newUpto)), res)
+        : { rev: String(base.revOf(newFgen, newUpto)), turns: res.turns, calls: res.calls };
+      const rev = at.rev;
       const tomb = rewrite && reAdapter ? await retireBoth(ctx, f, H, state, fc, oldKeys, res, rev)
         : await tombstonesFor(ctx, fc, vanishedFrom(oldKeys, res), rev, { removed: !!rewrite });
       // A new generation is archived whole; an upgrade archives only what lies past `upto`.
@@ -580,8 +595,8 @@ async function captureFile(ctx, f, H, C, budget) {
       // an upgrade that read past the cursor appended to the one it had.
       if (rewrite) out.archive.push(manifestRow(f, newFgen, { progress: newUpto, continuity: 'reset', units: unitsOf(out.archive) }, ctx.host, base.chTs(now)));
       else if (newUpto > upto) out.archive.push(manifestRow(f, newFgen, { progress: newUpto, continuity: 'appended', units: unitsOf(out.archive) }, ctx.host, base.chTs(now)));
-      out.turns = [...res.turns, ...tomb.turns];
-      out.calls = [...res.calls, ...tomb.calls];
+      out.turns = [...at.turns, ...tomb.turns];
+      out.calls = [...at.calls, ...tomb.calls];
       const digest = prefixDigest(fd, newUpto);
       out.files = filesRow(f, ctx, {
         attr, fgen: newFgen, upto: newUpto, reparse_from: res.reparse_from, state: res.state, adapter_ver: ad.deriveVersion,
@@ -1238,9 +1253,10 @@ async function upgradeSweep(ctx, sessions, stats) {
       const res = ad.derive({ file: fc, records: recs, state: { ...base.initialState(ad.adapter), fb: (state && state.fb) || {} } });
       const S = sessions.get(skey(harness, H.session_id, H.harness_path, H.incarnation));
       const agentIds = S ? [...S.files.values()].filter((x) => x.role === 'agent').map((x) => x.agent_id) : [];
-      const tomb = await tombstonesFor(ctx, fc, vanishedFrom(await ctx.house.fileKeys(ref, f.agent_id || '', agentIds), res), String(base.revOf(H.fgen, H.upto)));
-      await ctx.house.insert('turns', [...res.turns, ...tomb.turns]);
-      await ctx.house.insert('calls', [...res.calls, ...tomb.calls]);
+      const at = await aboveHouse(ctx, ref, f.agent_id || '', agentIds, String(base.revOf(H.fgen, H.upto)), res);
+      const tomb = await tombstonesFor(ctx, fc, vanishedFrom(await ctx.house.fileKeys(ref, f.agent_id || '', agentIds), res), at.rev);
+      await ctx.house.insert('turns', [...at.turns, ...tomb.turns]);
+      await ctx.house.insert('calls', [...at.calls, ...tomb.calls]);
       const row = { ...H, reparse_from: res.reparse_from, derive_state: JSON.stringify(res.state), adapter_ver: ad.deriveVersion, contrib: JSON.stringify(res.contrib), host: ctx.host };
       delete row.ver;
       await ctx.house.insert('files', [row]);
@@ -1553,6 +1569,11 @@ function storeWhere(ref) {
   return `harness = ${sqlStr(ref.harness)} AND host = ${sqlStr(ref.host)} AND harness_path = ${sqlStr(ref.harness_path)}`
     + ` AND session_id = ${sqlStr(ref.session_id)} AND incarnation = ${sqlStr(ref.incarnation || '')}`;
 }
+/** WHERE clause for one file of a session: a sub-agent's by its id, the main file as every other id. */
+function fileWho(agentId, agentFileIds) {
+  return agentId ? `agent_id = ${sqlStr(agentId)}`
+    : (agentFileIds.length ? `agent_id NOT IN (${agentFileIds.map(sqlStr).join(', ')})` : '1');
+}
 const STORE_TUPLE = '(harness, host, harness_path, session_id, incarnation)';
 const storeTuple = (ref) => `(${[ref.harness, ref.host, ref.harness_path, ref.session_id, ref.incarnation || ''].map(sqlStr).join(', ')})`;
 /** Split a column list at its top-level commas. */
@@ -1774,17 +1795,25 @@ class HttpHouse {
   }
   /** The keys this file's shipped rows hold in the conversation layer (adapter upgrade only). */
   async fileKeys(ref, agentId, agentFileIds) {
-    const who = agentId ? `agent_id = ${sqlStr(agentId)}`
-      : (agentFileIds.length ? `agent_id NOT IN (${agentFileIds.map(sqlStr).join(', ')})` : '1');
     // Removed history (removed = 1) is never a candidate: it is what the source no longer has, not a
     // duplicate of the new derivation, and an upgrade must not erase it.
-    const where = `${storeWhere(ref)} AND ${who} AND is_deleted = 0 AND removed = 0`;
+    const where = `${storeWhere(ref)} AND ${fileWho(agentId, agentFileIds)} AND is_deleted = 0 AND removed = 0`;
     const t = await this.query(`SELECT message_id, part_id, toString(ts) AS ts FROM ${this.t.turns} FINAL
       WHERE ${where} AND origin = 'ship' AND NOT startsWith(message_id, 'legacy:')`);
     const c = await this.query(`SELECT call_id, toString(ts) AS ts FROM ${this.t.calls} FINAL
       WHERE ${where} AND NOT startsWith(call_id, 'legacy:')`);
     return { t: t.map((r) => [r.message_id, r.part_id, r.ts]), c: c.map((r) => [r.call_id, r.ts]) };
   }
+  /** The highest rev this file's shipped rows hold, tombstones and removed versions included (adapter upgrade only). */
+  async maxRev(ref, agentId, agentFileIds) {
+    const where = `${storeWhere(ref)} AND ${fileWho(agentId, agentFileIds)}`;
+    const [t] = await this.query(`SELECT toString(max(rev)) AS rev FROM ${this.t.turns}
+      WHERE ${where} AND origin = 'ship' AND NOT startsWith(message_id, 'legacy:')`);
+    const [c] = await this.query(`SELECT toString(max(rev)) AS rev FROM ${this.t.calls}
+      WHERE ${where} AND NOT startsWith(call_id, 'legacy:')`);
+    const a = BigInt((t && t.rev) || 0); const b = BigInt((c && c.rev) || 0);
+    return String(a > b ? a : b);
+  }
   /**
    * Every `legacy:` row of one session in EVERY version — no FINAL, so tombstoned rows come back
    * too (dedupe-v3 takes the newest per key: a tombstone is a full copy, it still has its text).
@@ -1957,6 +1986,7 @@ class DryHouse {
   async firstCaptured() { return new Map(); }
   async rowsByKey() { return []; }
   async fileKeys() { return { t: [], c: [] }; }
+  async maxRev() { return '0'; }
   async hasRemoved() { return false; }
   async legacyRowsAll() { return { turns: [], calls: [] }; }
   async capturedRows() { return { turns: [], calls: [] }; }