memhouse 0.18.1 → 0.18.3

package/bin/memhouse.js

@@ -273,14 +273,24 @@ function portOf(u) {
 // "not running" for every correctly service-managed install, and `doctor` fails on a
 // healthy machine. Returns { running, via }.
 function shipperHealth() {
+  // "running" is the pid; whether it is DOING anything is the log. Both, always.
+  const lastPass = (() => {
+    try {
+      const passlog = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog'));
+      const f = path.join(LOG_DIR, 'shipper.log'); const st = fs.statSync(f);
+      const fd = fs.openSync(f, 'r'); const len = Math.min(st.size, 65536); const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, st.size - len); fs.closeSync(fd);
+      return passlog.lastPass(buf.toString('utf-8'));
+    } catch { return { outcome: null }; }
+  })();
   const pid = pidOf('shipper');
-  if (pid) return { running: true, via: `daemon (pid ${pid})` };
+  if (pid) return { running: true, via: `daemon (pid ${pid})`, lastPass };
   try {
     const svc = require(path.join(REPO_ROOT, 'memhouse', 'service.js'));
     const st = svc.status();
-    if (st.installed) return { running: st.running, via: `service (${st.kind})` };
+    if (st.installed) return { running: st.running, via: `service (${st.kind})`, lastPass };
   } catch { /* no service integration on this platform */ }
-  return { running: false, via: null };
+  return { running: false, via: null, lastPass };
 }
 
 // Room routing for the CLI's own queries. The shipper and dashboard resolve rooms through
@@ -405,7 +415,9 @@ Setup        onboard              interactive wizard: discover → configure →
                                   --print-sql            print the SQL, run it yourself
                                   with admin: --admin-user --admin-password [--member NAME]
                                   builds house + user + rooms + grants, then verifies as
-                                  the member. The admin credential is never stored.
+                                  the member. The admin credential IS written to the env
+                                  file (mode 600) so invite/members need no flags; delete
+                                  those two lines if you would rather pass it each time.
                                   --env FILE installs from an invite file (see: invite)
              invite <name>        mint a member and write the env file their install needs
                                   (--url [--db NAME] [--out FILE]; --admin-user and
@@ -969,6 +981,16 @@ function startShipperBackground(cfg) {
   console.log('  dashboard (browse / search / analyze):  memhouse start');
 }
 
+// The store is node:sqlite, stable from Node 24. On 22 everything green-lights and the
+// SQLite-backed adapters silently ship nothing — 36 messages went out before anyone noticed.
+// doctor said so; install and onboard did not. Now they refuse, with the same sentence.
+function engineOk() {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 24) return true;
+  console.log(bad(`node ${process.versions.node} — need >= 24 — node:sqlite is stable there; the SQLite-backed adapters need it`));
+  process.exitCode = 1; return false;
+}
+
 async function cmdInstall({ interactive }) {
   // --env <file>: an INVITE intake. The file carries MEMHOUSE_URL/USER/PASSWORD/DB from
   // `memhouse invite` on the admin's machine; loading it into the environment BEFORE
@@ -985,6 +1007,10 @@ async function cmdInstall({ interactive }) {
     // this machine with a file that cannot authenticate on the invitee's.
     const missing = wanted.filter((k) => !parsed[k]);
     if (missing.length) { console.log(bad(`--env ${flags.env} is missing ${missing.join(', ')} — not a complete invite file?`)); return 1; }
+    try {
+      const h = new URL(String(parsed.MEMHOUSE_URL || '')).hostname;
+      if (/^(localhost|127\.0\.0\.1|\[?::1\]?)$/.test(h)) console.log(warn(`${parsed.MEMHOUSE_URL} is loopback — it points at THIS machine; only right if a tunnel or port-forward puts the house here`));
+    } catch { /* not a URL; the missing-fields check above already spoke */ }
     // Clear ambient MEMHOUSE_* so ONLY the file speaks (exported vars normally win over the
     // file; an invite intake is the one place they must not).
     for (const k of ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB', 'MEMHOUSE_PORT']) delete process.env[k];
@@ -1285,6 +1311,18 @@ async function finishInvite(cfg) {
     }
     if (go) {
       const code = await cmdPasswd({ quiet: true });
+      if (code === 0) {
+        // The rotation rewrote the env FILE. But --env hoisted the invite's values into
+        // process.env, and resolveConfig prefers process.env over the file — so the
+        // shipper spawned a few lines later got the INVITE password, which the rotation
+        // had just killed, and failed every pass with "Authentication failed" while every
+        // fresh CLI call (reading the file) worked. A drill member watched an empty house
+        // for twelve minutes. Adopt what the file now says before anything else is spawned.
+        const drift = envfile.credentialDrift(fs.readFileSync(ENV_FILE, 'utf-8'), process.env);
+        for (const k of drift.changed) process.env[k] = drift.values[k];
+        if (drift.values.MEMHOUSE_PASSWORD !== undefined && flags.password !== undefined) flags.password = drift.values.MEMHOUSE_PASSWORD;
+        if (cfg) cfg.password = process.env.MEMHOUSE_PASSWORD;
+      }
       if (code !== 0) {
         // Rotation failed and its own state may be uncertain — KEEP the invite file (it
         // still carries the password the config was just written from) so nothing is
@@ -1323,7 +1361,8 @@ function printGettingStarted(cfg) {
   console.log('                                     /mem:sql, /mem:access, /mem:admin');
   console.log(`     ${mh} search <terms>         find a past conversation right now`);
   console.log(`     ${mh} doctor                 every line a check mark = healthy`);
-  console.log('  The house keeps shipping as you work; nothing else to do.');
+  if (flags['no-ship'] === true) console.log('  Shipping is OFF (--no-ship). Start it when ready:  memhouse start');
+  else console.log('  The house keeps shipping as you work; nothing else to do.');
 }
 
 async function cmdOnboard() {
@@ -1605,7 +1644,12 @@ async function cmdStatus() {
       console.log(`     ${f.writer.padEnd(28)} ${String(f.version || '?').padEnd(8)} last ship ${fleetAge(f.ageMs)}${mark}`);
     }
   }
-  console.log(out.shipper.running ? ok(`shipper: running — ${out.shipper.via}`) : warn('shipper: not running'));
+  {
+    const fail = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).describeFailure(out.shipper.lastPass);
+    console.log(!out.shipper.running ? warn('shipper: not running')
+      : fail ? warn(`shipper: running — ${out.shipper.via} — but ${fail}`)
+      : ok(`shipper: running — ${out.shipper.via}`));
+  }
   console.log(out.daemons.dashboard ? ok(`dashboard: running (pid ${out.daemons.dashboard})`) : warn('dashboard: not running'));
   if (out.daemons.dashboard) console.log(`  dashboard → http://localhost:${runningPort(cfg)}`);
   // Exit non-zero when the house is unreachable. `status` is what a health check, a
@@ -1952,7 +1996,9 @@ async function cmdDoctor() {
       'that adapter does not extract usage; the messages are stored, the numbers are not');
   } catch { /* a house that cannot be read is already reported above */ }
   const sh = shipperHealth();
-  add(sh.running, `shipper${sh.via ? ` — ${sh.via}` : ''}`, 'memhouse start (or: memhouse service install)');
+  const shFail = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).describeFailure(sh.lastPass);
+  add(sh.running && !shFail, `shipper${sh.via ? ` — ${sh.via}` : ''}${shFail ? ` — ${shFail}` : ''}`,
+    shFail ? (sh.lastPass.auth ? 'memhouse stop && memhouse start' : 'read: ~/.memhouse/logs/shipper.log') : 'memhouse start (or: memhouse service install)');
   add(!!pidOf('dashboard'), 'dashboard daemon', 'memhouse start');
   add(fs.existsSync(path.join(REPO_ROOT, 'public', 'index.html')), 'dashboard UI built', 'built automatically by memhouse start');
 
@@ -3891,8 +3937,8 @@ async function cmdUninstall() {
     // fall through to HELP: forty lines of help and exit 0 is not what --version means.
     case 'version': console.log(PKG.version); break;
     case 'discover': await cmdDiscover(); break;
-    case 'onboard': process.exitCode = await cmdOnboard(); break;
-    case 'install': process.exitCode = await cmdInstall({ interactive: false }); break;
+    case 'onboard': if (!engineOk()) break; process.exitCode = await cmdOnboard(); break;
+    case 'install': if (!engineOk()) break; process.exitCode = await cmdInstall({ interactive: false }); break;
     case 'setup': {
       // Dual-mode like install: --yes (with any --url/--user/--password/--db/
       // --port overrides, already resolved into cfg) skips every prompt so

package/editors/claude.js

@@ -195,11 +195,19 @@ function cleanPrompt(prompt) {
 // Parse one Claude session .jsonl into the adapter's message shape. When
 // `isSubagent` is set, each message is tagged `[subagent]` so folded subagent turns
 // are clearly attributed in the transcript.
-function parseSessionFile(filePath, isSubagent) {
+function parseSessionFile(filePath, isSubagent, agent = null) {
   const messages = [];
   let lines;
   try { lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean); } catch { return messages; }
   const tag = isSubagent ? '[subagent] ' : '';
+  // A folded subagent turn used to carry only the `[subagent]` tag: the house held the
+  // turns but not WHICH subagent said them, so one fork's transcript could not be isolated,
+  // cited, or told apart from a sibling's. An agent looking for the fork as its own session
+  // concluded it was never shipped. Every turn now carries the agent's id, the description
+  // the parent gave it, and its position within that subagent — in `extra`, which is not
+  // part of the line hash, so nothing already shipped is re-shipped for this.
+  let turn = 0;
+  const stamp = (m) => { if (agent) { m._agent = { ...agent, turn: turn++ }; } return m; };
 
   for (const line of lines) {
     let obj;
@@ -223,19 +231,19 @@ function parseSessionFile(filePath, isSubagent) {
 
     if (obj.type === 'user' && obj.message) {
       const content = extractContent(obj.message.content);
-      if (content) messages.push({ role: 'user', content: tag + content, _ts: at });
+      if (content) messages.push(stamp({ role: 'user', content: tag + content, _ts: at }));
     } else if (obj.type === 'assistant' && obj.message) {
       const { text, toolCalls } = extractAssistantContent(obj.message.content);
       const usage = obj.message.usage;
-      if (text) messages.push({
+      if (text) messages.push(stamp({
         role: 'assistant', content: tag + text, _model: obj.message.model,
         _inputTokens: usage?.input_tokens, _outputTokens: usage?.output_tokens,
         _cacheRead: usage?.cache_read_input_tokens, _cacheWrite: usage?.cache_creation_input_tokens,
         _toolCalls: toolCalls, _ts: at,
-      });
+      }));
     } else if (obj.type === 'system') {
       const text = typeof obj.message?.content === 'string' ? obj.message.content : '';
-      if (text) messages.push({ role: 'system', content: tag + text, _ts: at });
+      if (text) messages.push(stamp({ role: 'system', content: tag + text, _ts: at }));
     }
   }
   return messages;
@@ -252,14 +260,86 @@ function getMessages(chat) {
   // after the parent's turns, so nothing is lost and subagents are never
   // double-counted as standalone sessions.
   const subagentsDir = path.join(filePath.replace(/\.jsonl$/, ''), 'subagents');
-  try {
-    const files = fs.readdirSync(subagentsDir).filter(f => f.endsWith('.jsonl')).sort();
-    for (const f of files) messages.push(...parseSessionFile(path.join(subagentsDir, f), true));
-  } catch { /* no subagents for this session */ }
+  const subFiles = subagentFiles(subagentsDir);
+  const named = subFiles.length ? subagentNames(filePath) : new Map();
+  for (const { file, workflow } of subFiles) {
+    const id = path.basename(file).replace(/^agent-/, '').replace(/\.jsonl$/, '');
+    const meta = named.get(id) || {};
+    const agent = { id, description: meta.description || '', type: meta.type || (workflow ? 'workflow-subagent' : ''), file: path.basename(file) };
+    if (workflow) agent.workflow = workflow;
+    const turns = parseSessionFile(file, true, agent);
+    // A fork the parent never named (a Workflow-run agent, or a parent from before the
+    // ids were reported) is described by its own first prompt — what it was told to do.
+    if (!agent.description) {
+      const first = turns.find((m) => m.role === 'user');
+      if (first) { const d = String(first.content).replace(/^\[subagent\] /, '').replace(/\s+/g, ' ').trim().slice(0, 160); for (const m of turns) m._agent.description = d; }
+    }
+    messages.push(...turns);
+  }
 
   return messages;
 }
 
+/**
+ * Every subagent transcript under a session, wherever Claude Code put it:
+ *   <session>/subagents/agent-<id>.jsonl                       — Agent tool forks
+ *   <session>/subagents/workflows/wf_<id>/agent-<id>.jsonl     — Workflow-run agents
+ * journal.jsonl and *.meta.json are bookkeeping, not transcripts. Sorted for a stable
+ * fold order. On real data the workflow layer held 100 of 165 forks and shipped none.
+ */
+function subagentFiles(subagentsDir) {
+  const out = [];
+  let names = [];
+  try { names = fs.readdirSync(subagentsDir); } catch { return out; }
+  for (const f of names.sort()) if (f.startsWith('agent-') && f.endsWith('.jsonl')) out.push({ file: path.join(subagentsDir, f), workflow: null });
+  const wfDir = path.join(subagentsDir, 'workflows');
+  let wfs = [];
+  try { wfs = fs.readdirSync(wfDir).filter((d) => d.startsWith('wf_')).sort(); } catch { return out; }
+  for (const wf of wfs) {
+    let files = [];
+    try { files = fs.readdirSync(path.join(wfDir, wf)); } catch { continue; }
+    for (const f of files.sort()) if (f.startsWith('agent-') && f.endsWith('.jsonl')) out.push({ file: path.join(wfDir, wf, f), workflow: wf });
+  }
+  return out;
+}
+
+/**
+ * What the parent called each subagent. The parent's `Agent` tool_use carries the
+ * description and subagent_type; the tool_result that answers it names the agentId
+ * ("agentId: <id>"). Join the two through tool_use_id → a map agentId → {description, type}.
+ * Best effort: a parent that predates the ids, or a truncated line, just yields no name.
+ */
+function subagentNames(parentFile) {
+  const byToolUse = new Map(); const out = new Map();
+  let lines = [];
+  try { lines = fs.readFileSync(parentFile, 'utf-8').split('\n').filter(Boolean); } catch { return out; }
+  for (const line of lines) {
+    let obj; try { obj = JSON.parse(line); } catch { continue; }
+    const content = obj.message && Array.isArray(obj.message.content) ? obj.message.content : [];
+    for (const c of content) {
+      if (c && c.type === 'tool_use' && c.name === 'Agent' && c.id) {
+        byToolUse.set(c.id, { description: String((c.input && c.input.description) || ''), type: String((c.input && c.input.subagent_type) || '') });
+      } else if (c && c.type === 'tool_result' && c.tool_use_id && byToolUse.has(c.tool_use_id)) {
+        const text = typeof c.content === 'string' ? c.content : (Array.isArray(c.content) ? c.content.map((x) => (x && x.text) || '').join('\n') : '');
+        const m = /agentId:\s*([0-9a-f]{6,})/i.exec(text);
+        if (m) out.set(m[1], byToolUse.get(c.tool_use_id));
+      }
+    }
+    // A background subagent reports through a task notification instead — a user-role
+    // line whose text carries <task-id>agentId</task-id> and <tool-use-id>toolu_…</tool-use-id>.
+    // On real data 30 of 65 forks were named only this way.
+    const flat = typeof (obj.message && obj.message.content) === 'string' ? obj.message.content
+      : content.map((x) => (x && typeof x.text === 'string') ? x.text : '').join('\n');
+    if (flat.includes('<task-notification>')) {
+      for (const block of flat.split('<task-notification>').slice(1)) {
+        const t = /<task-id>([0-9a-f]{6,})<\/task-id>/i.exec(block); const u = /<tool-use-id>(toolu_[A-Za-z0-9]+)<\/tool-use-id>/.exec(block);
+        if (t && u && byToolUse.has(u[1]) && !out.has(t[1])) out.set(t[1], byToolUse.get(u[1]));
+      }
+    }
+  }
+  return out;
+}
+
 function extractContent(content) {
   if (typeof content === 'string') return content;
   if (!Array.isArray(content)) return '';
@@ -420,4 +500,4 @@ function getMCPServers() {
 // answer to a different question: where this pilot's Claude Code instances live. Two
 // implementations of "find every CLAUDE_CONFIG_DIR" would drift the first time a playbook
 // layout changes, and this is the copy exercised on every single ship.
-module.exports = { name, labels, getChats, getMessages, getUsage, getArtifacts, getMCPServers, discoverClaudeRoots };
+module.exports = { name, labels, getChats, getMessages, getUsage, getArtifacts, getMCPServers, discoverClaudeRoots, subagentNames, subagentFiles };

package/memhouse/delivery/INVITATION.md.tpl

@@ -38,6 +38,10 @@ going on. Do not print its contents — the last line of it is a password.
 {{INSTALL}}
 
 On most Linux distros the global install needs `sudo`; if `npm` says `EACCES`, that is why.
+If you handed this page to an agent and it reports that a permission classifier blocked the
+install (a global `npm install` is exactly what such classifiers stop), run this one line
+yourself in a terminal and tell the agent to continue from step 2 — that is the intended
+split: the person installs software, the agent does the rest.
 `memhouse --version` should print `{{VERSION}}`.
 
 ## 2. Join the house

package/memhouse/delivery/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mem",
   "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: recall past sessions and answer from them, run analytics, check the house, bring people in, and administer the server. Skills install as /mem:recall, /mem:sql, /mem:house, /mem:access, and /mem:admin.",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "author": {
     "name": "Ramazan Polat"
   },

package/memhouse/delivery/plugin/reference/HOUSE.md

@@ -92,6 +92,21 @@ wrong rooms. Say whose memory an answer came from.
 
 ## Schema
 
+**Subagents (forks) live inside their parent session.** Claude Code writes them to
+`<session>/subagents/agent-<id>.jsonl` (Agent tool) and
+`<session>/subagents/workflows/wf_<id>/agent-<id>.jsonl` (Workflow runs); the shipper folds them into the parent with
+`is_subagent = 1` and stamps *which* one in `extra.agent`. Looking for a fork as its own
+session finds nothing — look inside the parent:
+
+```sql
+-- the subagents a session spawned
+SELECT toString(extra.agent.id) AS agent, any(toString(extra.agent.description)) AS asked_to, count() AS turns
+FROM messages WHERE session_id = '<sid>' AND is_subagent GROUP BY agent   -- toString: a JSON path cannot be a GROUP BY key
+-- one subagent's transcript, in order
+SELECT seq, role, substring(text, 1, 2000) FROM messages
+WHERE session_id = '<sid>' AND extra.agent.id = '<agent>' ORDER BY seq
+```
+
 **`messages`** — one row per turn.
 
 | column | meaning |
@@ -102,6 +117,8 @@ wrong rooms. Say whose memory an answer came from.
 | `host` | the machine, `<hostname>-<8 hex>` — random per install, not derived |
 | `ts` | when the turn happened (`DateTime64(3,'UTC')`) |
 | `role` | `user`, `assistant`, `system` |
+| `is_subagent` | 1 for a turn that a Claude Code **subagent** (a fork) produced; folded into the parent session after the parent's own turns. Subagents are never separate sessions. |
+| `extra` | JSON. For a subagent turn: `extra.agent.id`, `extra.agent.description` (what the parent asked it to do, else the fork's own first prompt), `extra.agent.type` (`general-purpose`, `workflow-subagent`, …), `extra.agent.turn` (position within that subagent), and `extra.agent.workflow` (`wf_…`) when a Workflow run spawned it. Empty `{}` otherwise, and on rows shipped before 0.18.3. |
 | `model`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` | usage; **empty for several adapters** — see below |
 | `text` | the turn, **truncated at 50,000 chars** |
 | `text_ngram`, `text_word` | `MATERIALIZED lower(text)`, carrying the text indexes |

package/memhouse/delivery/plugin/skills/recall/SKILL.md

@@ -112,6 +112,11 @@ Beyond the three in the reference:
 
 - **Ranking is yours.** There is no relevance score in the store. `hits` plus recency is
   the whole of it — say so rather than implying the top row is "the best match".
+- **A subagent (fork) is not a session.** Its turns are inside the parent session with
+  `is_subagent = 1` and `extra.agent.id` / `extra.agent.description` saying which one; the
+  reference has the two queries. "Find the fork that did X" → search `messages` as usual,
+  then group the hits by `toString(extra.agent.id)` — never conclude it was not shipped because no
+  session carries its name.
 - **Tool *results* are not stored.** "What did that command print" is unanswerable from
   the house; only the invocation and its arguments survive.
 - **`memhouse search`** exists as a CLI, but it joins your terms into ONE literal phrase

package/memhouse/envfile.js

@@ -46,4 +46,19 @@ function assertSingleLine(env) {
   }
 }
 
-module.exports = { parse, quoteShell, quoteSystemd, assertSingleLine };
+/**
+ * Which connection values in an env file's text differ from what a process currently holds.
+ * A running shipper was spawned with one credential; `install --env` rotates the password
+ * and rewrites the file, and a member can `memhouse passwd` under a running daemon. In
+ * both cases the FILE is the truth and the process copy is stale. Pure; used by the
+ * shipper (adopt on auth failure) and by install (adopt before spawning).
+ */
+function credentialDrift(text, current = {}) {
+  const file = parse(String(text || ''));
+  const keys = ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB'];
+  const changed = keys.filter((k) => file[k] !== undefined && file[k] !== current[k]);
+  const values = Object.fromEntries(changed.map((k) => [k, file[k]]));
+  return { changed, values };
+}
+
+module.exports = { credentialDrift, parse, quoteShell, quoteSystemd, assertSingleLine };

package/memhouse/house/house.js

@@ -306,6 +306,117 @@ function sessionsRollup({ sessions, messages }) {
   )`;
 }
 
+// The precomputed rollups' table names. One place, because the shipper that fills them,
+// the runtime probe and the read layer must all agree.
+const SESSION_STATS = 'session_stats';
+const MODEL_STATS = 'session_model_stats';
+const TOOL_STATS = 'session_tool_stats';
+// One-layout: like every room, a stat table is named for its member — `<member>_session_stats`
+// — so it sits under the same `<db>.<member>_*` grant the member already holds. No
+// database-level privilege exists in this layout, and none is needed.
+function statTableNames(member) {
+  return {
+    session_stats: physicalRoom(SESSION_STATS, member),
+    model_stats: physicalRoom(MODEL_STATS, member),
+    tool_stats: physicalRoom(TOOL_STATS, member),
+  };
+}
+
+/**
+ * The precomputed rollups — the tables the dashboard reads instead of rebuilding the
+ * session rollup on every query. Measured on a 714k-message house: 1,413,624 rows read
+ * per query became ~1,250, and a page load went from 4–10 seconds to ~250 ms.
+ *
+ * REFRESHED BY THE SHIPPER, NOT BY A MATERIALIZED VIEW — and that is forced, not chosen.
+ * The obvious tool is a refreshable materialized view (`REFRESH EVERY 5 MINUTE TO t`),
+ * which is exactly what the 0.17 line uses. It cannot exist in this layout: a refreshable
+ * view swaps its target atomically through a temporary table with a generated name, so
+ * ClickHouse demands `SELECT, INSERT, CREATE TABLE, DROP TABLE ON <db>.*` — the whole
+ * database — and a one-layout member holds `<db>.<member>_*` and nothing else, on
+ * purpose. Measured on 25.8: the CREATE is refused with exactly that message, and the
+ * grant that would satisfy it is the one this layout exists to withhold.
+ *
+ * (An ordinary insert-trigger MV is wrong for a different reason: it counts every
+ * ReplacingMergeTree version the merge has not collapsed yet, cannot see the epoch
+ * filter, and cannot join.)
+ *
+ * So the shipper runs the rollup itself, once at the end of every pass — the same
+ * cadence a view would have had — and INSERTs the result stamped with one
+ * `refreshed_at`. Every insert is a complete snapshot, a GENERATION; the read layer
+ * takes only the newest generation. Nothing is deleted, nothing is swapped, nothing
+ * needs a privilege beyond INSERT and SELECT on the member's own rooms. A TTL of one day
+ * keeps old generations from accumulating (288 a day at the default cadence), and the
+ * sorting key leads with `refreshed_at` so reading the newest one is one index range,
+ * not a scan.
+ *
+ * Built from the SAME rollup text the read layer would otherwise run, so the two
+ * cannot drift; column types are inferred with EMPTY AS for the same reason.
+ */
+const STAT_TTL = 'TTL toDateTime(refreshed_at) + INTERVAL 1 DAY';
+
+function statBodies(rooms) {
+  // sessionsRollup wraps itself in parentheses for the FROM position; strip them.
+  const rollup = sessionsRollup(rooms).replace(/^\s*\(/, '').replace(/\)\s*$/, '');
+  return {
+    session_stats: {
+      key: '(refreshed_at, session_id, user_id)',
+      body: rollup,
+    },
+    // One row per (session, user, model) with the message count and the four token sums.
+    // Every model/cost aggregate the dashboard runs is a sum or argMax over these rows —
+    // a few thousand — instead of a scan of the full messages room. The read layer's
+    // any-token predicates survive unchanged: a zero-token row contributes zero to every
+    // sum, so filtering before summing and summing over everything agree.
+    model_stats: {
+      key: '(refreshed_at, session_id, user_id, model)',
+      body: `SELECT session_id, user_id, any(source) AS source, any(folder) AS folder, model,
+       count() AS msgs,
+       sum(input_tokens) AS input_tokens, sum(output_tokens) AS output_tokens,
+       sum(cache_read_tokens) AS cache_read_tokens, sum(cache_write_tokens) AS cache_write_tokens
+FROM ${rooms.messages} AS m
+GROUP BY session_id, user_id, model`,
+    },
+    // One row per (session, user, tool_name) with the call count. NOTE the epoch source:
+    // rooms.tool_calls is currentParse(tool_calls, 'messages') — the tool room takes its
+    // epoch from MESSAGES, because a parse that keeps its messages but emits no tool calls
+    // writes nothing at the new epoch, and this room's own max(epoch) would resurrect the
+    // superseded parse's calls.
+    tool_stats: {
+      key: '(refreshed_at, session_id, user_id, tool_name)',
+      body: `SELECT session_id, user_id, any(source) AS source, any(folder) AS folder, tool_name,
+       count() AS calls
+FROM ${rooms.tool_calls} AS tc
+GROUP BY session_id, user_id, tool_name`,
+    },
+  };
+}
+
+/** The CREATE statements — additive, idempotent, run by ensureSchema. */
+function statCreateStatements(rooms) {
+  const names = statTableNames(rooms.member);
+  const bodies = statBodies(rooms);
+  return Object.keys(bodies).map((k) =>
+    `CREATE TABLE IF NOT EXISTS ${names[k]} ENGINE = MergeTree ORDER BY ${bodies[k].key} ${STAT_TTL} `
+    + `EMPTY AS SELECT now64(3) AS refreshed_at, * FROM (${bodies[k].body})`);
+}
+
+/**
+ * The refresh — one INSERT per table, one generation per call. All three carry the same
+ * `refreshed_at` so a reader never mixes a session_stats generation with a model_stats
+ * one. Run by the shipper after every pass and by --ensure-schema.
+ */
+function statRefreshStatements(rooms, at = 'now64(3)') {
+  const names = statTableNames(rooms.member);
+  const bodies = statBodies(rooms);
+  return Object.keys(bodies).map((k) =>
+    `INSERT INTO ${names[k]} SELECT ${at} AS refreshed_at, * FROM (${bodies[k].body})`);
+}
+
+/** The read-side source for one stat table: its newest generation, and nothing else. */
+function latestGeneration(table) {
+  return `(SELECT * FROM ${table} WHERE refreshed_at = (SELECT max(refreshed_at) FROM ${table}))`;
+}
+
 /**
  * The settings every read needs. `final` collapses ReplacingMergeTree versions;
  * `join_use_nulls` is what the rollup's coalesce depends on.
@@ -381,8 +492,67 @@ async function currentUser(client) {
 }
 
 /** Resolve the rooms for whoever this client is connected as. */
+/**
+ * The precomputed rollup, when the house has one.
+ *
+ * `sessions_v` is a SAVED QUERY that rebuilds the whole rollup — sessions FINAL joined
+ * to the current parse of messages, grouped over the entire house — on every call. A
+ * house that has run the session_stats migration carries the same rows as a flat table,
+ * refreshed on a timer, and the read layer can name that instead. Measured on a 714k
+ * message house: 1,413,624 rows read per query becomes 1,230, and p50 query time 68ms
+ * becomes 4ms.
+ *
+ * Resolved at RUNTIME rather than by version, and that is the point: one binary has to
+ * serve a migrated house, a house whose migration has not run, and a friend's house
+ * shared read-only that was never migrated at all. Asking the server what exists is the
+ * only answer that is correct in all three.
+ */
+async function statTables(client, member) {
+  const names = statTableNames(member);
+  const wanted = Object.values(names);
+  try {
+    const rs = await client.query({
+      query: `SELECT name FROM system.tables
+              WHERE database = currentDatabase()
+                AND name IN (${wanted.map((n) => `'${n}'`).join(', ')})`,
+      format: 'JSONEachRow',
+    });
+    const present = (await rs.json()).map((r) => r.name);
+    // Present is not enough: a table exists from the moment ensureSchema creates it and
+    // holds nothing until the first refresh lands. A dashboard reading it then would show
+    // a house with no sessions at all (caught by house-test the first time). An empty
+    // stat table reads as absent, so the inline rollup answers until the table can.
+    const usable = new Set();
+    for (const name of present) {
+      try {
+        const c = await client.query({ query: `SELECT count() AS n FROM ${name}`, format: 'JSONEachRow' });
+        const rows = await c.json();
+        if (Number(rows[0] && rows[0].n) > 0) usable.add(name);
+      } catch { /* unreadable: treat as absent */ }
+    }
+    return usable;
+  } catch {
+    // No grant on system.tables is not an error — it means "assume none", and the
+    // subquery path is always correct.
+    return new Set();
+  }
+}
+
+async function hasSessionStats(client, member) {
+  return (await statTables(client, member)).has(statTableNames(member).session_stats);
+}
+
 async function resolveRooms(client) {
-  return roomNames(await currentUser(client));
+  const rooms = roomNames(await currentUser(client));
+  const names = statTableNames(rooms.member);
+  const have = await statTables(client, rooms.member);
+  if (have.has(names.session_stats)) rooms.sessions_v = latestGeneration(names.session_stats);
+  // Null when absent: the read layer branches to the legacy scan-the-room SQL. Never a
+  // token substitution, because the legacy SQL has a different shape, not just a
+  // different table name.
+  rooms.model_stats = have.has(names.model_stats) ? latestGeneration(names.model_stats) : null;
+  rooms.tool_stats = have.has(names.tool_stats) ? latestGeneration(names.tool_stats) : null;
+  return rooms;
 }
 
 /**
@@ -426,4 +596,6 @@ module.exports = {
   READ_SETTINGS, MEMBER_PIN,
   installCommand, assertUsableName,
   sessionsRollup, currentParse, createStatement, roomNames, currentUser, resolveRooms,
+  SESSION_STATS, MODEL_STATS, TOOL_STATS, statTableNames, hasSessionStats, statTables,
+  statCreateStatements, statRefreshStatements, latestGeneration,
 };

package/memhouse/provision.js

@@ -61,7 +61,10 @@ function plan({ db, member, password = null }) {
     { sql: `CREATE DATABASE IF NOT EXISTS ${db}`, why: 'the house', optional: false },
   ];
   if (password !== null) {
-    steps.push({ sql: `CREATE USER IF NOT EXISTS ${member} IDENTIFIED BY ${sqlString(password)}`, why: 'the member', optional: false });
+    // No IF NOT EXISTS. The live path checks first and refuses an existing user; the printed
+    // plan used to no-op here, apply the grants, and hand out a password the server never saw —
+    // found on a realm that mints its own users. Now it fails loudly on line one instead.
+    steps.push({ sql: `CREATE USER ${member} IDENTIFIED BY ${sqlString(password)}`, why: 'the member — fails if it already exists; then this password is NOT theirs', optional: false });
   }
   steps.push(
     { sql: roomGrant(db, member), why: `their rooms — ${db}.${roomPattern(member)} — and nothing else in the house`, optional: false },