memhouse 0.4.3 → 0.7.0

package/memhouse/shipper/ship.js

@@ -0,0 +1,949 @@
+#!/usr/bin/env node
+// memhouse SHIPPER — parse-on-client (bet #1 in ../DESIGN.md). Runs the 17 editor
+// adapters locally and ships TYPED rows into THE CALLER'S OWN rooms — sessions_<m> /
+// messages_<m> / tool_calls_<m>, where <m> is `SELECT currentUser()` and never config
+// (../per-member/schema-member.sql.tpl, ../per-member/rooms.js). All of one member's
+// machines land in that member's rooms, told apart by the `host` column; no member
+// writes into another's. The typed evolution of agency/ingest.js: same host id,
+// same ts interpolation, same batching discipline — but rows land in physical
+// columns instead of a raw JSON blob.
+//
+// Data-plane rules (binding, see DESIGN.md):
+//   - JSONEachRow, batches <= 2000 rows, async_insert=0 on EVERY insert — the house
+//     stamps user_id MATERIALIZED currentUser(), which is empty during async flushes.
+//   - DateTime64 values travel as 'YYYY-MM-DD HH:MM:SS.mmm' UTC strings (plain
+//     format; ISO 'T'/'Z' forms parse unreliably under JSONEachRow). Nullable → null.
+//   - Int64-bound values are integer-coerced (some adapters emit fractional ms).
+//   - Re-shipping is always safe: ReplacingMergeTree(ingested_at) collapses to
+//     latest-wins at FINAL. Keyed (session_id, user_id, origin, seq) on messages and
+//     (session_id, user_id, origin, idx) on tool_calls, so an imported row and a shipped
+//     one at the same seq are two rows, not one. sessions is (session_id, user_id) with
+//     NO origin — one metadata row per session is what every read path assumes.
+//
+// CLI:  node ship.js                one incremental pass
+//       node ship.js --loop [sec]   repeat every sec seconds (default 300)
+//       node ship.js --full         ignore the incremental skip (re-ship everything)
+//       node ship.js --ensure-schema  create the caller's own rooms and exit
+//       node ship.js --stats        per-source counts from sessions_v and exit
+//
+// Env (DESIGN.md contract): MEMHOUSE_URL / MEMHOUSE_USER / MEMHOUSE_PASSWORD /
+// MEMHOUSE_DB. URL and USER are REQUIRED — there is no default house, because the old
+// one (http://localhost:8123 as memhouse_root) is a real house on many machines. DB
+// defaults to 'mem'.
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+// Named, not a raw MODULE_NOT_FOUND with a require stack. This runs as a SUBPROCESS of
+// `memhouse ship`/`install`, so its stack trace lands in the middle of the parent's
+// output and reads as a crash in the parent. Same preflight provision.js carries.
+let createClient, ClickHouseLogLevel;
+try { ({ createClient, ClickHouseLogLevel } = require('@clickhouse/client')); }
+catch {
+  console.error("[memhouse] dependency '@clickhouse/client' is not installed.");
+  console.error(`[memhouse] from a checkout:     npm install --prefix ${require('path').join(__dirname, '..', '..')}`);
+  console.error(`[memhouse] from an npm install: ${require('../per-member/rooms').installCommand()}`);
+  process.exit(2);
+}
+const { getAllChats, getAdapterErrors, getMessages, resetCaches } = require('../../editors');
+const adapterErrorSink = require('../../editors/adapter-errors');
+const selfUpdate = require('../self-update');
+// Captured at require time, which is as close to "what this process booted with" as it
+// gets. Taking it later would record whatever an upgrade had already replaced.
+const selfSnap = selfUpdate.snapshot(__filename);
+const { resolveRooms, READ_SETTINGS, ROOM_TYPES } = require('../per-member/rooms');
+
+const BATCH_ROWS = 2000;   // insert batch ceiling (binding)
+const TEXT_MAX = 50000;    // messages.text truncation
+const ARGS_MAX = 20000;    // tool_calls.args truncation
+
+// Stable host id: <shorthostname>-<8hex>, where the hex half is a fingerprint written
+// ONCE into MEMHOUSE_HOME rather than hashed out of hostname/platform/arch.
+//
+// The derived version failed in both directions, and both matter here because every
+// machine belonging to one member ships into the SAME rooms — `host` is the only column
+// separating them. Two laptops answering to the same default hostname produced one id
+// between them; renaming a machine moved its id and split its own history. See ../host.js.
+function hostId() {
+  return require('../host').identity().id;
+}
+
+// UInt64 (as decimal string) = first 8 bytes big-endian of sha256 over the row's
+// content fields. Decimal string survives JSONEachRow → UInt64 without precision loss.
+function lineHash(obj) {
+  return crypto.createHash('sha256').update(JSON.stringify(obj)).digest().readBigUInt64BE(0).toString();
+}
+
+// DateTime64(3) wire format: 'YYYY-MM-DD HH:MM:SS.mmm' in UTC (see header note).
+function chTs(ms) {
+  const d = new Date(ms);
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ` +
+    `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`;
+}
+
+// When a message was actually sent.
+//
+// Prefer the adapter's own `_ts` (epoch ms). It is optional by contract — `getMessages`
+// returns `{ role, content }` and nothing more is required — but a transcript format that
+// records a time per line should not have it thrown away. Claude Code's JSONL does, and
+// discarding it produced timestamps wrong by up to the whole span of a session: four
+// messages sent within three minutes came back spread over 08:00, 18:43, 03:27 and 12:11,
+// and the search skill reported those to the user as fact.
+//
+// Fall back to interpolating across [createdAt, lastUpdatedAt] for the adapters that
+// genuinely have nothing per message — monotonic-by-seq, so sessions_v started/ended
+// still line up with the session bounds (same approximation as agency/ingest.js;
+// documented in DESIGN.md). Real timestamps are NOT necessarily monotonic by seq — a
+// folded subagent transcript is appended after its parent's turns but ran during them.
+// Nothing depends on that: ordering is by `seq`, and started/ended are min/max.
+function messageTs(chat, seq, total, msg) {
+  const at = Number(msg && msg._ts);
+  // Seconds or milliseconds, depending on the format: goose stores seconds, Claude Code
+  // and opencode milliseconds. Real epoch-ms is > 1e12 and real epoch-seconds ~1.7e9, so
+  // the split point is unambiguous for any date this side of 1973.
+  if (Number.isFinite(at) && at > 0) return chTs(at < 1e11 ? at * 1000 : at);
+  const start = chat.createdAt || chat.lastUpdatedAt || Date.now();
+  const end = chat.lastUpdatedAt || chat.createdAt || start;
+  if (total <= 1) return chTs(start);
+  return chTs(start + Math.round((end - start) * (seq / (total - 1))));
+}
+
+/**
+ * Truncate without splitting a character.
+ *
+ * `String.prototype.slice` counts UTF-16 code units, so a boundary that lands inside an
+ * astral character (emoji, and everything else above U+FFFF) leaves a lone high surrogate
+ * at the end. `JSON.stringify` then emits "\ud83d", and ClickHouse rejects THE WHOLE
+ * INSERT:
+ *
+ *   Cannot parse escape sequence: missing second part of surrogate pair
+ *   (while reading the value of key text) … CANNOT_PARSE_ESCAPE_SEQUENCE
+ *
+ * The blast radius is not the one message. One poisoned session among ten made every pass
+ * fail and the house stayed completely empty across four passes; under `--loop` it retries
+ * forever. In another ordering the failure landed after the sessions insert, leaving
+ * session rows whose transcripts do not exist and which accumulated on every pass.
+ *
+ * Reachable on ordinary data: four messages in a real 398-session history already sit at
+ * the 50,000 ceiling, and codex folds a whole turn into one assistant message (mean 9,762
+ * chars), so it is the most exposed source. Dropping the orphaned half of a pair costs one
+ * character out of 50,000.
+ */
+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;
+}
+
+/**
+ * Drop unpaired surrogates from every string on its way into an insert.
+ *
+ * truncate() above fixes the two places THIS file cuts a string, and that was not enough:
+ * the same failure arrives by two other routes.
+ *
+ *   1. Titles. `cleanPrompt` in editors/claude.js cuts the first prompt to 120 characters,
+ *      and 120 is a far more reachable boundary than 50,000. An emoji there produced
+ *      `(while reading the value of key name)` — same total outage, different column.
+ *   2. Source data. `{"content":"before \ud83d after"}` is valid JSON that JSON.parse
+ *      accepts, so a lone surrogate can arrive already in a transcript with no truncation
+ *      involved at all.
+ *
+ * Guarding cut sites one at a time is the wrong shape — every future string field is
+ * another instance. This runs over the finished row instead, so nothing reaches ClickHouse
+ * carrying an escape it will reject. The cost is one regex over fields that almost never
+ * match; the alternative is a member whose house stops accepting rows entirely, exit 1
+ * forever under --loop, while `doctor` reports everything green.
+ */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+function scrub(row) {
+  for (const k of Object.keys(row)) {
+    const v = row[k];
+    if (typeof v === 'string') {
+      if (LONE_SURROGATE.test(v)) { LONE_SURROGATE.lastIndex = 0; row[k] = v.replace(LONE_SURROGATE, ''); }
+      LONE_SURROGATE.lastIndex = 0;
+    } else if (v && typeof v === 'object') {
+      // `extra` is a JSON column; its values travel as strings too.
+      row[k] = JSON.parse(JSON.stringify(v).replace(LONE_SURROGATE, ''));
+      LONE_SURROGATE.lastIndex = 0;
+    }
+  }
+  return row;
+}
+
+// UInt64-bound coercion: integers only, never negative, garbage → 0.
+function toInt(v) {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function makeClient() {
+  // No house-shaped default. `memhouse` spawns this with the resolved config in the
+  // environment, so a missing MEMHOUSE_URL here means the shipper was started some other
+  // way — a stale service unit, a hand-rolled cron, a copied command — and the old
+  // defaults sent it at http://localhost:8123 as memhouse_root, which on a lot of machines
+  // is a real house belonging to someone else. Writing memory into it is worse than
+  // reading from it.
+  if (!process.env.MEMHOUSE_URL || !process.env.MEMHOUSE_USER) {
+    console.error('[memhouse] no house configured: MEMHOUSE_URL and MEMHOUSE_USER are unset.');
+    console.error('[memhouse] run `memhouse install`, or set them for this process. Refusing to');
+    console.error('[memhouse] guess http://localhost:8123 as memhouse_root.');
+    process.exit(2);
+  }
+  return createClient({
+    // The driver logs a full connection-object dump and a node stack to stderr for every
+    // failed request, at ERROR level, BEFORE we get the exception. A member without
+    // CREATE TABLE then sees 23 lines of @clickhouse/client internals and the word "fatal"
+    // ahead of the handled, actionable refusal — it reads like a crash that recovered.
+    // Silence the driver; every call site already catches the throw and prints something
+    // a person can act on. MEMHOUSE_DEBUG=1 puts it back.
+    log: { level: process.env.MEMHOUSE_DEBUG ? ClickHouseLogLevel.DEBUG : ClickHouseLogLevel.OFF },
+    url: process.env.MEMHOUSE_URL,
+    username: process.env.MEMHOUSE_USER,
+    password: process.env.MEMHOUSE_PASSWORD || '',
+    database: process.env.MEMHOUSE_DB || 'mem',
+    request_timeout: 300000, // full re-ships move tens of MB; don't cut inserts short
+    clickhouse_settings: {
+      // Int64/UInt64 back as JSON numbers — our values (counts, tokens) are < 2^53.
+      output_format_json_quote_64bit_integers: 0,
+      // With a 300s request_timeout the client warns unless progress headers
+      // keep long requests alive through proxies/load balancers — enable them
+      // (also silences the startup WARN on every ship/install run).
+      // The interval MUST sit below the smallest idle timeout in the path:
+      // 60s is the default for AWS ALB and nginx proxy_read_timeout, so a
+      // longer interval emits nothing before the socket is dropped and the
+      // setting only silences the warning. 30s leaves headroom for both.
+      send_progress_in_http_headers: 1,
+      http_headers_progress_interval_ms: '30000',
+    },
+  });
+}
+
+// Create the CALLER'S OWN rooms, from ../per-member/schema-member.sql.tpl. Comments are
+// stripped BEFORE the ';' split — schema comments legitimately contain semicolons.
+//
+// This is the solo path: on a house you own, `memhouse install` mints your three rooms and
+// you are done. It creates nobody else's — the template is rendered for currentUser(), the
+// same identity the rooms' user_id is stamped with, so a client cannot name its way into
+// someone else's rooms.
+//
+// It does NOT issue grants or create the Merge rooms. A solo owner needs neither. Adding a
+// SECOND member — grants, Merge rooms, sharing — is owner work and lives in
+// ../per-member/provision.js.
+/**
+ * Refuse to write into rooms whose sorting key is wrong for `origin` — in EITHER
+ * direction. Two different houses are broken in two opposite ways:
+ *
+ *   - pre-0.4.4: no `origin` in the messages/tool_calls key, so ReplacingMergeTree
+ *     collapses an imported row against a shipped one and the import is lost.
+ *   - 0.4.4 exactly: `origin` was also put in the SESSIONS key, which gives a session
+ *     two metadata rows. sessions_v then joins messages twice and over-reports, and the
+ *     incremental skip cannot tell which row is current.
+ *
+ * Called at the top of EVERY ship pass, not just --ensure-schema: a plain `memhouse ship`
+ * never touches ensureSchema, so a guard living only there is a guard that never runs on
+ * the path that does the damage. Found exactly that way — the refusal was in place and
+ * 137 sessions shipped straight past it into a stale-key house.
+ */
+/**
+ * Refuse, legibly, when the caller's rooms are not there.
+ *
+ * Without this the first thing to touch a roomless house is loadExisting's SELECT, and the
+ * user gets `Unknown table expression identifier 'sessions_x' in scope SELECT session_id,
+ * last_updated_at, message_count, extra FROM ...` — a raw ClickHouse identifier error with
+ * no next step, from a command that may be running inside a service loop. `install` and
+ * `doctor` both handle the identical situation properly; ship was the one that did not.
+ * It is also the documented 0.3.x-upgrade symptom, which INSTALL.md claims is named.
+ */
+/**
+ * The columns each room type declares in the template, as {name, type} — the source of
+ * truth for what a room must have. Parsed from the same file that creates them, so a
+ * column added there is rolled out without anyone remembering to write a migration.
+ *
+ * MATERIALIZED and DEFAULT clauses are kept: `user_id String MATERIALIZED currentUser()`
+ * has to be added exactly that way or the identity stamp does not happen.
+ */
+function templateColumns(tpl) {
+  const out = {};
+  for (const t of ROOM_TYPES) {
+    const re = new RegExp(`CREATE TABLE IF NOT EXISTS ${t}_\\{\\{MEMBER\\}\\}\\s*\\(([\\s\\S]*?)\\n\\)`, 'm');
+    const m = tpl.match(re);
+    if (!m) continue;
+    const cols = [];
+    let depth = 0, buf = '';
+    for (const raw of m[1].split('\n')) {
+      const line = raw.replace(/--.*$/, '').trim();
+      if (!line) continue;
+      buf += (buf ? ' ' : '') + line;
+      depth += (line.match(/\(/g) || []).length - (line.match(/\)/g) || []).length;
+      if (depth > 0 || !buf.endsWith(',')) { if (depth > 0) continue; }
+      const decl = buf.replace(/,$/, '').trim();
+      buf = '';
+      // Skip index/constraint declarations — only column definitions here.
+      if (/^(INDEX|CONSTRAINT|PROJECTION|PRIMARY\s+KEY)\b/i.test(decl)) continue;
+      const sp = decl.indexOf(' ');
+      if (sp < 1) continue;
+      cols.push({ name: decl.slice(0, sp), type: decl.slice(sp + 1).trim() });
+    }
+    out[t] = cols;
+  }
+  return out;
+}
+
+/**
+ * Say so, every pass, when a room is missing a column.
+ *
+ * `ship` does not call ensureSchema — only `--ensure-schema` and `install` do — so a room
+ * that has drifted keeps accepting inserts and keeps discarding that field, silently, for
+ * as long as nobody thinks to run the healer. Measured: 85 rows shipped with the value
+ * thrown away and four surfaces reporting success.
+ *
+ * A WARNING rather than a refusal: the rows that do fit are still worth having, and
+ * refusing would stop all shipping over one column. One extra query per room per pass.
+ */
+async function warnMissingColumns(client, rooms) {
+  let tpl;
+  try { tpl = fs.readFileSync(path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl'), 'utf-8'); }
+  catch { return; }
+  const want = templateColumns(tpl);
+  const missing = [];
+  for (const t of ROOM_TYPES) {
+    try {
+      const rs = await client.query({
+        query: 'SELECT name FROM system.columns WHERE database = currentDatabase() AND table = {n:String}',
+        query_params: { n: rooms[t] }, format: 'JSONEachRow',
+      });
+      const have = new Set((await rs.json()).map((r) => r.name));
+      if (!have.size) continue;
+      for (const c of (want[t] || [])) if (!have.has(c.name)) missing.push(`${rooms[t]}.${c.name}`);
+    } catch { /* unreadable rooms are assertRoomsExist's problem */ }
+  }
+  if (missing.length) {
+    console.error(`[memhouse] WARNING: ${missing.length} column(s) missing from your rooms — those fields are being DISCARDED on every pass:`);
+    console.error(`[memhouse]   ${missing.slice(0, 8).join(', ')}${missing.length > 8 ? ` … and ${missing.length - 8} more` : ''}`);
+    console.error('[memhouse]   heal them with: memhouse ship --ensure-schema');
+  }
+}
+
+async function assertRoomsExist(client, rooms) {
+  const rs = await client.query({
+    query: `SELECT name FROM system.tables WHERE database = currentDatabase() AND name IN ({n:Array(String)})`,
+    query_params: { n: ROOM_TYPES.map((t) => rooms[t]) },
+    format: 'JSONEachRow',
+  });
+  const have = new Set((await rs.json()).map((r) => r.name));
+  const missing = ROOM_TYPES.map((t) => rooms[t]).filter((n) => !have.has(n));
+  if (!missing.length) return;
+  throw new Error(
+    `'${rooms.member}' has no ${missing.join(', ')} in this house.\n`
+    + '  Create them:  memhouse install\n'
+    + '  If you hold no CREATE TABLE here, the owner runs:\n'
+    + `    memhouse install --print-sql --member ${rooms.member}\n`
+    + '  A house from before 0.4 reaches this too — its rooms have different names.');
+}
+
+async function assertOriginKeyed(client, rooms) {
+  const wrong = [];
+  for (const t of ROOM_TYPES) {
+    const rs = await client.query({
+      query: `SELECT sorting_key FROM system.tables WHERE database = currentDatabase() AND name = {n:String}`,
+      query_params: { n: rooms[t] }, format: 'JSONEachRow',
+    });
+    const row = (await rs.json())[0];
+    const key = (row || {}).sorting_key || '';
+    // A room that EXISTS but has no sorting key is not a MergeTree — a Merge, a View, a Log
+    // engine standing where the shipper expects to DELETE and INSERT. Skipping it here let
+    // the pass sail past its own guard and die later on
+    // `DELETE query is not supported for table …`, which is exactly what this refusal is
+    // meant to prevent. (A room that does not exist at all is assertRoomsExist's job and is
+    // reported there.)
+    if (row && !key) { wrong.push(`${rooms[t]} — not a MergeTree, so it cannot be shipped to`); continue; }
+    if (!key) continue;
+    const keyed = /\borigin\b/.test(key);
+    // sessions is one row per session and must NOT key on origin; the transcript rooms
+    // hold many rows per session and must.
+    const want = t !== 'sessions';
+    if (keyed !== want) {
+      wrong.push(`${rooms[t]} (${key}) — origin ${want ? 'missing from' : 'must not be in'} the key`);
+    }
+  }
+  if (wrong.length) {
+    throw new Error(
+      'these rooms have the wrong sorting key, so a ship pass would corrupt them:\n'
+      + wrong.map((s) => `    ${s}`).join('\n')
+      + '\n  ORDER BY cannot be altered in place. Rebuild each room, then re-ship:'
+      + '\n    RENAME TABLE <room> TO <room>_old;'
+      + `\n    -- recreate from ${path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl')}`
+      + '\n    INSERT INTO <room> SELECT * FROM <room>_old;'
+      + '\n  (add `, \'ship\' AS origin` to the SELECT only if <room>_old has no origin column)'
+      + '\n  A house with no imported rows can also just be re-shipped from scratch.');
+  }
+}
+
+async function ensureSchema(client) {
+  const rooms = await resolveRooms(client);
+  const { member } = rooms;
+  const tpl = fs.readFileSync(path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl'), 'utf-8');
+  const sql = tpl.replaceAll('{{MEMBER}}', member);
+  const stripped = sql.split('\n').map((l) => l.replace(/--.*$/, '')).join('\n');
+  const stmts = stripped.split(';').map((s) => s.trim()).filter(Boolean);
+  // A MEMBER holds no CREATE TABLE — that is the point of the narrowed grant set — and
+  // ClickHouse checks the grant BEFORE it checks existence, so `IF NOT EXISTS` does not
+  // save these. Running the CREATEs in a bare loop meant `--ensure-schema` died on the
+  // FIRST statement for the very user who is told to run it, and never reached the ADD
+  // COLUMN rollout that is the whole reason to run it. Skip what we may not do and carry
+  // on; the rooms either already exist (assertRoomsExist says so) or an owner has to
+  // create them, which install already explains.
+  let denied = 0;
+  for (const q of stmts) {
+    try {
+      await client.command({
+        query: q,
+        // allow_experimental_full_text_index: on 25.x the messages text indexes
+        // are gated behind this flag (SUPPORT_IS_DISABLED without it); 26.x+
+        // accepts it as a no-op. Query-scoped, so no server config or admin
+        // rights are needed. Verified on 25.11 and 26.7.
+        clickhouse_settings: { async_insert: 0, allow_experimental_full_text_index: 1 },
+      });
+    } catch (e) {
+      const m = e && e.message ? e.message : String(e);
+      if (/Not enough privileges|ACCESS_DENIED/i.test(m)) { denied++; continue; }
+      throw e;
+    }
+  }
+  if (denied) {
+    console.error(`[memhouse] ${denied} schema statement(s) needed rights you do not hold — continuing with what you can do.`);
+    console.error('[memhouse] creating or replacing a ROOM is the house owner\'s job; adding a missing COLUMN is not.');
+  }
+  // A house created before origin existed has no such column, and the clear binds it —
+  // an unguarded DELETE there would be the old destructive behaviour, and a guarded one
+  // would error. Add it in place; ReplacingMergeTree backfills the DEFAULT, so every
+  // pre-existing row reads as 'ship', which is what it was.
+  //
+  // Deliberately NOT applied to the Merge rooms — but not for the reason this comment used
+  // to give. It claimed they "reject ALTER"; they do not, on either 26.7 or 25.11, where
+  // `ALTER TABLE all_messages ADD COLUMN …` succeeds. The real reason is that a Merge room
+  // is a VIEW over whatever `^messages_` matches: a column added to it is cosmetic, is not
+  // backed by the underlying rooms, and drifts from them the moment a member is added. It
+  // takes its structure from a member room at CREATE time, so recreating it is the only
+  // correct way to change it — and nothing reads `origin` through it anyway.
+  // EVERY column the template declares, not just `origin`.
+  //
+  // This used to add exactly one column, which meant any OTHER column missing from a room
+  // was invisible and lossy: `ship` writes the row, ClickHouse discards the field it has
+  // no column for, and the pass reports success. Measured — a room with `is_subagent`
+  // dropped shipped 85 rows with the value silently thrown away, while `ship`, `install`,
+  // `--ensure-schema` AND `doctor` all reported green. doctor's schema check counts ROOMS,
+  // not columns, so nothing anywhere noticed.
+  //
+  // It also made the grant a lie: rooms.js and INSTALL.md both say ALTER ADD COLUMN is
+  // granted "for ensureSchema's rollout", and no rollout of anything but `origin` existed.
+  const wantCols = templateColumns(tpl);
+  for (const t of ROOM_TYPES) {
+    let have = new Set();
+    try {
+      const rs = await client.query({
+        query: 'SELECT name FROM system.columns WHERE database = currentDatabase() AND table = {n:String}',
+        query_params: { n: rooms[t] }, format: 'JSONEachRow',
+      });
+      have = new Set((await rs.json()).map((r) => r.name));
+    } catch { /* unreadable: the checks above already reported why */ }
+    for (const col of (wantCols[t] || [])) {
+      if (have.size && have.has(col.name)) continue;
+      try {
+        await client.command({
+          query: `ALTER TABLE ${rooms[t]} ADD COLUMN IF NOT EXISTS ${col.name} ${col.type}`,
+          clickhouse_settings: { allow_experimental_full_text_index: 1 },
+        });
+        if (have.size) console.log(`[memhouse] added missing column ${rooms[t]}.${col.name}`);
+      } catch (e) {
+        const m = e && e.message ? e.message : String(e);
+        if (!/Not enough privileges|ACCESS_DENIED/i.test(m)) {
+          console.error(`[memhouse] could not add ${rooms[t]}.${col.name}: ${m}`);
+        }
+      }
+    }
+    try {
+      await client.command({
+        query: `ALTER TABLE ${rooms[t]} ADD COLUMN IF NOT EXISTS origin LowCardinality(String) DEFAULT 'ship'`,
+        // 25.11 refuses ANY alter on a table carrying the messages text indexes unless
+        // this is set — including an ADD COLUMN that has nothing to do with them
+        // (Code: 344, SUPPORT_IS_DISABLED). Without it the backfill fails silently and
+        // the guard ends up missing on precisely the houses that need upgrading. A no-op
+        // on 26.x, and query-scoped, so it needs no server config.
+        clickhouse_settings: { allow_experimental_full_text_index: 1 },
+      });
+    } catch (e) {
+      // No rights to alter is genuinely not fatal — a member on someone else's house
+      // cannot roll a column out and does not need to. But this used to swallow
+      // EVERYTHING, including the 25.11 Code 344 this call carries a setting to avoid, and
+      // `schema ensured` printed regardless. Name anything that is not a permissions
+      // problem, and keep going.
+      const m = e && e.message ? e.message : String(e);
+      if (!/Not enough privileges|ACCESS_DENIED/i.test(m)) {
+        console.error(`[memhouse] could not add the 'origin' column to ${rooms[t]}: ${m}`);
+        console.error('[memhouse] the room still works; a house that predates 0.4.4 needs rebuilding — memhouse doctor');
+      }
+    }
+  }
+
+  await assertRoomsExist(client, rooms);
+  await assertOriginKeyed(client, rooms);
+  await warnMissingColumns(client, rooms);
+  return stmts.length;
+}
+
+// Incremental state: what the house already holds, keyed by session_id. We compare
+// against extra.bubbleCount (the adapter's own cheap count, stored at ship time) —
+// NOT message_count — because parsed-message count and bubbleCount are different
+// units in several adapters (claude folds subagents, codex reports 0), and skipping
+// must be decidable WITHOUT calling getMessages on every chat.
+async function loadExisting(client, rooms) {
+  const rs = await client.query({
+    query: `SELECT session_id, last_updated_at, message_count, extra FROM ${rooms.sessions} FINAL WHERE user_id = currentUser()`,
+    format: 'JSONEachRow',
+  });
+  // Actual message rows per session: an interrupted re-ship (crash between the
+  // clear-DELETE and the inserts, or mid-flush on a large transcript) leaves a
+  // fresh-looking session row with a missing or PARTIAL transcript — the skip
+  // must compare the real row count against the recorded message_count, not
+  // merely check that some row exists.
+  //
+  // countIf(origin='ship'), not count(). message_count records how many rows the
+  // SHIPPER wrote; a session that also carries imported rows would never match a
+  // plain count(), so `intact` would be false forever and the session would re-ship
+  // on every pass — no data lost, but the incremental skip silently stops existing.
+  // Measured: adding one origin='import' row to a settled session made it re-ship
+  // every pass; removing it froze the session again.
+  const mr = await client.query({
+    query: `SELECT session_id, countIf(origin = 'ship') AS n FROM ${rooms.messages} FINAL WHERE user_id = currentUser() GROUP BY session_id`,
+    format: 'JSONEachRow',
+  });
+  const msgCounts = new Map();
+  for (const r of await mr.json()) msgCounts.set(r.session_id, toInt(r.n));
+  // The tool_calls room needs the same check, and used to have none. shipSession writes
+  // sessions, then messages, then tool_calls — so a pass that fails during the LAST of
+  // those three leaves a session whose message count matches perfectly. The next pass
+  // reads that as intact, skips it, and the tool calls are never written. Not a crash:
+  // exit 0, `status` and `stats` both green, and only `ship --full` ever recovers them.
+  // Reproduced by dropping the room mid-pass; any transient — a ClickHouse restart, a
+  // quota rejection, a network blip — reaches the same state.
+  const tr = await client.query({
+    query: `SELECT session_id, countIf(origin = 'ship') AS n FROM ${rooms.tool_calls} FINAL WHERE user_id = currentUser() GROUP BY session_id`,
+    format: 'JSONEachRow',
+  });
+  const toolCounts = new Map();
+  for (const r of await tr.json()) toolCounts.set(r.session_id, toInt(r.n));
+  const map = new Map();
+  for (const r of await rs.json()) {
+    // DateTime64 comes back as 'YYYY-MM-DD HH:MM:SS.mmm' — re-parse as UTC.
+    const ms = r.last_updated_at ? Date.parse(r.last_updated_at.replace(' ', 'T') + 'Z') : null;
+    const bc = toInt(r.extra && r.extra.bubbleCount);
+    const count = toInt(r.message_count);
+    // Sessions shipped before toolCallCount existed read 0 here, so any of them that do
+    // have tool calls re-ship exactly once and then record it. Self-correcting, and
+    // cheaper than a branch that has to be remembered forever.
+    const toolCount = toInt(r.extra && r.extra.toolCallCount);
+    const intact = (msgCounts.get(r.session_id) || 0) === count
+      && (toolCounts.get(r.session_id) || 0) === toolCount;
+    map.set(r.session_id, { ms, count, bc, intact });
+  }
+  return map;
+}
+
+// Regex fallback for adapters that render tool calls into text but don't expose
+// m._toolCalls: matches '[tool-call: Name(' and '[tool-call: Name]' forms.
+const TOOL_CALL_RE = /\[tool-call: ([^(\]]+)/g;
+
+// Build the typed rows for one chat. Returns null when the chat is unreadable
+// (adapter threw — e.g. a partially-written or locked session file): the caller
+// must write NOTHING for it, so the next incremental pass retries. A chat that
+// parses to zero messages still gets its session row (deliberate: the stored row
+// absorbs the incremental skip for stable-empty chats).
+function rowsForChat(chat, host) {
+  let messages;
+  try { messages = getMessages(chat) || []; }
+  catch (e) {
+    // Some readers throw instead of reporting through adapter-errors — Cursor's
+    // agent-store path on a bad blobs table, for one. Converting that to a bare
+    // `unreadable` count would leave the end-of-pass report with nothing to print,
+    // so operators would see a number rising every pass and no cause anywhere.
+    adapterErrorSink.record(chat.source, e, chat.composerId);
+    return null;
+  }
+
+  const source = chat.source;
+  // Canonical globally-unique session id: '<source>:<adapter-local id>'.
+  // composerId is only unique WITHIN one editor; two editors emitting the same
+  // id must never collide in keys, incremental state, deletes, or the API.
+  // Sources are colon-free, so the prefix parses back unambiguously.
+  const id = `${source}:${String(chat.composerId)}`;
+  const folder = chat.folder || '';
+  const project = folder ? path.basename(folder) : '';
+  const total = messages.length;
+
+  const session = {
+    session_id: id,
+    source,
+    host,
+    name: chat.name || '',
+    mode: chat.mode || '',
+    folder,
+    project,
+    git_branch: chat._gitBranch || '',
+    created_at: chat.createdAt ? chTs(chat.createdAt) : null,
+    last_updated_at: chat.lastUpdatedAt ? chTs(chat.lastUpdatedAt) : null,
+    message_count: total,
+    path: chat._fullPath || chat._dbPath || id,
+    extra: { bubbleCount: chat.bubbleCount || 0 },
+  };
+
+  const msgRows = [];
+  const toolRows = [];
+  let idx = 0; // session-wide tool-call index
+  for (let seq = 0; seq < total; seq++) {
+    const m = messages[seq];
+    const raw = typeof m.content === 'string' ? m.content : JSON.stringify(m.content) ?? '';
+    const text = truncate(raw, TEXT_MAX);
+    const ts = messageTs(chat, seq, total, m);
+    const row = {
+      session_id: id,
+      seq,
+      source,
+      host,
+      ts,
+      role: m.role || '',
+      model: m._model || '',
+      input_tokens: toInt(m._inputTokens),
+      output_tokens: toInt(m._outputTokens),
+      cache_read_tokens: toInt(m._cacheRead),
+      cache_write_tokens: toInt(m._cacheWrite),
+      text,
+      project,
+      folder,
+      is_subagent: text.startsWith('[subagent]'),
+      extra: {},
+    };
+    // Hash the content fields only (not ts — it is synthesized and may drift).
+    row.line_hash = lineHash({
+      session_id: id, seq, role: row.role, model: row.model,
+      input_tokens: row.input_tokens, output_tokens: row.output_tokens,
+      cache_read_tokens: row.cache_read_tokens, cache_write_tokens: row.cache_write_tokens,
+      text,
+    });
+    msgRows.push(row);
+
+    if (m.role !== 'assistant') continue;
+    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 match of text.matchAll(TOOL_CALL_RE)) {
+        calls.push({ name: match[1].trim(), args: {} });
+      }
+    }
+    for (const tc of calls) {
+      const args = JSON.stringify(tc.args);
+      toolRows.push({
+        session_id: id,
+        seq,
+        idx: idx++,
+        source,
+        host,
+        tool_name: tc.name,
+        args: truncate(args, ARGS_MAX),
+        ts,
+        project,
+        folder,
+      });
+    }
+  }
+  // What a complete ship of this session looks like, recorded ON the session row so the
+  // next pass can tell "finished" from "got part way". message_count already carries the
+  // message half; without the tool half a pass that dies between the messages insert and
+  // the tool_calls insert leaves a session that looks finished forever. See loadExisting.
+  session.extra.toolCallCount = toolRows.length;
+  return { session, msgRows, toolRows };
+}
+
+// One shipping pass. Incremental unless opts.full: a chat is skipped when the house
+// already has it at least as fresh (last_updated_at) and at least as large
+// (extra.bubbleCount) — both readable without parsing the chat.
+async function runShip(client, opts = {}) {
+  const { full = false } = opts;
+  const host = hostId();
+  // Always load what the house holds — even with --full. The skip decision uses it
+  // only in incremental mode, but re-shipping a KNOWN session must clear its old
+  // message/tool rows first (a shrunken re-parse leaves stale higher-seq rows
+  // otherwise: ReplacingMergeTree collapses same-key rows only).
+  const rooms = await resolveRooms(client);
+  await assertRoomsExist(client, rooms);
+  await assertOriginKeyed(client, rooms);
+  await warnMissingColumns(client, rooms);
+  const existing = await loadExisting(client, rooms);
+  const chats = getAllChats();
+
+  // An adapter that cannot load contributes zero sessions, which is indistinguishable
+  // from an editor the user does not have — so the shipper would silently ship a
+  // partial history forever. Say so on every pass.
+  // Reported once here for what the scan already knows (a dead binding is visible
+  // before any work happens, and this pass may take minutes), and again after the
+  // loop for failures that only surface while reading messages.
+  const warned = new Set();
+  reportAdapterErrors(warned);
+
+  const batches = { sessions: [], messages: [], tool_calls: [] };
+  const flush = async (table) => {
+    if (!batches[table].length) return;
+    await client.insert({
+      table: rooms[table],
+      values: batches[table],
+      format: 'JSONEachRow',
+      clickhouse_settings: { async_insert: 0 }, // binding: user_id stamping breaks otherwise
+    });
+    batches[table] = [];
+  };
+  const push = async (table, row) => {
+    batches[table].push(row);
+    if (batches[table].length >= BATCH_ROWS) await flush(table);
+  };
+
+  const seen = new Set(); // adapters must not double-ship a session id within a pass
+  let sessions = 0, skipped = 0, msgRows = 0, toolRows = 0, unreadable = 0;
+  for (const chat of chats) {
+    if (chat.encrypted) continue;
+    // Same canonical '<source>:<adapter-local id>' as rowsForChat: dedup and
+    // incremental state are per (source, id) — two editors sharing an id must
+    // not skip or overwrite each other.
+    const id = `${chat.source}:${String(chat.composerId)}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+
+    const prev = existing.get(id);
+    if (!full && prev) {
+      // floor: some adapters (codex) emit fractional-ms timestamps, but DateTime64(3)
+      // stores whole ms — without it every such session loses by <1ms and re-ships.
+      const chatLast = Math.floor(chat.lastUpdatedAt || chat.createdAt || 0);
+      const notNewer = chatLast === 0 || (prev.ms !== null && prev.ms >= chatLast);
+      // Freshness alone is not enough: the transcript must be COMPLETE (stored
+      // row count == recorded message_count) so an interrupted re-ship — even one
+      // that died mid-flush leaving a partial transcript — repairs itself on the
+      // next pass instead of being skipped forever.
+      // _countUnknown means the adapter could not determine this chat's message
+      // count, so bubbleCount is a placeholder rather than a measurement. Skipping on
+      // it would compare against a number that means nothing — `prev.bc >= 0` is
+      // trivially true — and the session would stay stale forever. Re-read instead.
+      if (notNewer && !chat._countUnknown && prev.bc >= (chat.bubbleCount || 0) && prev.intact) { skipped++; continue; }
+    }
+
+    // rowsForChat returns null only when getMessages() *throws*. An adapter that
+    // swallows its own failure returns [] instead, which would look like a session
+    // that genuinely has no messages — and for a known session the re-ship below
+    // deletes the old transcript before inserting that emptiness. So treat a
+    // failure recorded while reading THIS chat as unreadable too: write nothing,
+    // delete nothing, retry next pass.
+    const errsBefore = adapterErrorSink.recorded().length;
+    const rows = rowsForChat(chat, host);
+    const failedHere = adapterErrorSink.recorded().slice(errsBefore).some((e) => e.source === chat.source);
+    // Write nothing on a failed read, whether or not the session is already stored.
+    //
+    // Shipping a partial first read looks tempting — nothing is there to destroy —
+    // but it is a trap: message_count would be written from the partial rows, so
+    // prev.intact becomes true, prev.bc already matches the source, the timestamp is
+    // unchanged, and the skip predicate above then withholds the session forever.
+    // The truncation would become permanent AND the warning would stop, because the
+    // adapter is never asked to read it again. Withholding keeps the session out of
+    // the skip predicate entirely, so every pass retries it and re-reports it until
+    // the underlying store is readable.
+    if (!rows || failedHere) { unreadable++; continue; }
+    if (prev) {
+      // Known session being re-shipped: clear its old rows BEFORE inserting so a
+      // shorter re-parse can't leave stale seq/idx tails. A crash between the
+      // delete and the inserts is repaired by the next pass: the skip predicate
+      // refuses to skip a non-empty session whose message rows are missing.
+      // user_id is BOUND, not `= currentUser()`. A DELETE is a mutation, and a mutation
+      // does not necessarily evaluate currentUser() in the caller's context — it matches
+      // nothing at all, so the delete silently removes zero rows and the stale tail this
+      // code exists to clear survives forever. Measured on ClickHouse 25.11 —
+      // the identical predicate with the literal value deleted 2000 rows where
+      // currentUser() deleted 0. The value is the same identity either way: it is read
+      // from the server over this very connection.
+      // origin='ship' is the third bind, and it is not cosmetic. This clear exists so a
+      // shorter re-parse cannot leave a stale seq tail behind — but scoped to
+      // (session_id, user_id) alone it deletes EVERY row for the session, including rows
+      // the adapters did not write and cannot rewrite. Measured, on a real house: an
+      // import of 135,307 messages lost 27,948 of them to one ship pass, because
+      // memory-house had captured more per session than the adapters emit. The rows the
+      // shipper owns are the only rows it may remove.
+      for (const t of ['messages', 'tool_calls']) {
+        await client.command({
+          query: `DELETE FROM ${rooms[t]} WHERE session_id = {id:String} AND user_id = {uid:String} AND origin = 'ship'`,
+          query_params: { id, uid: rooms.user },
+          clickhouse_settings: { async_insert: 0 },
+        });
+      }
+    }
+    await push('sessions', scrub(rows.session));
+    sessions++;
+    for (const r of rows.msgRows) { await push('messages', scrub(r)); msgRows++; }
+    for (const r of rows.toolRows) { await push('tool_calls', scrub(r)); toolRows++; }
+  }
+  for (const table of Object.keys(batches)) await flush(table);
+  // Anything that only failed while reading messages — the sink is reset by the
+  // next getAllChats(), so unreported here means never reported at all.
+  reportAdapterErrors(warned);
+  return { sessions, skipped, msgRows, toolRows, unreadable };
+}
+
+// Warn once per adapter per pass. `warned` carries across the two call sites so a
+// dead binding is not reported twice in the same run.
+function reportAdapterErrors(warned) {
+  const errors = getAdapterErrors().filter((e) => !warned.has(e.source));
+  if (!errors.length) return;
+  for (const e of errors) warned.add(e.source);
+  const noBinding = errors.filter((e) => e.missingBinding).map((e) => e.source);
+  if (noBinding.length) {
+    console.log(`[memhouse] WARNING: ${noBinding.length} adapter(s) skipped, sessions NOT shipped — better-sqlite3 has no native binding: ${noBinding.join(', ')}`);
+    console.log(`[memhouse]          fix: ${require('../per-member/rooms').installCommand()}`);
+  }
+  for (const e of errors.filter((x) => !x.missingBinding)) {
+    console.log(`[memhouse] WARNING: ${e.source} skipped — ${e.message}`);
+  }
+}
+
+// Per-source rollup straight from sessions_v (final=1 so ReplacingMergeTree collapses).
+// The rollup resolves like the rooms do — it is a subquery over the caller's own rooms.
+async function printStats(client) {
+  const rooms = await resolveRooms(client);
+  const rs = await client.query({
+    query: `
+      SELECT source,
+             count() AS sessions,
+             sum(total_msgs) AS messages,
+             sum(input_tokens + output_tokens + cache_read_tokens + cache_write_tokens) AS tokens
+      FROM ${rooms.sessions_v}
+      GROUP BY source
+      ORDER BY sessions DESC`,
+    format: 'JSONEachRow',
+    clickhouse_settings: READ_SETTINGS,
+  });
+  const rows = await rs.json();
+  if (!rows.length) { console.log('[memhouse] house is empty'); return; }
+  const w = [Math.max(6, ...rows.map((r) => r.source.length)), 8, 8, 14];
+  const line = (a, b, c, d) =>
+    console.log(`${String(a).padEnd(w[0])}  ${String(b).padStart(w[1])}  ${String(c).padStart(w[2])}  ${String(d).padStart(w[3])}`);
+  line('source', 'sessions', 'messages', 'tokens');
+  let ts = 0, tm = 0, tt = 0;
+  for (const r of rows) {
+    line(r.source, r.sessions, r.messages, r.tokens);
+    ts += Number(r.sessions); tm += Number(r.messages); tt += Number(r.tokens);
+  }
+  line('total', ts, tm, tt);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const client = makeClient();
+  try {
+    if (argv.includes('--ensure-schema')) {
+      const n = await ensureSchema(client);
+      console.log(`[memhouse] schema ensured (${n} statements)`);
+      return;
+    }
+    if (argv.includes('--stats')) { await printStats(client); return; }
+
+    const loopIdx = argv.indexOf('--loop');
+    const loop = loopIdx !== -1;
+    let intervalSec = 300;
+    if (loop) {
+      const n = Number(argv[loopIdx + 1]);
+      if (Number.isFinite(n) && n > 0) intervalSec = n;
+    }
+    let full = argv.includes('--full');
+    // A failed pass does NOT wait the full interval. The common failure at startup is
+    // that the house is not up yet — the container is still booting — and sleeping 300s
+    // there means the first ship is
+    // five minutes late for a condition that clears in under a second. systemd's
+    // After= orders process start, not readiness, and launchd has no ordering at all, so
+    // this is the only place the race can be closed for every path at once.
+    // Backs off to the normal interval so a genuinely unreachable house is not hammered.
+    const RETRY_START_MS = 2000;
+    let retryMs = RETRY_START_MS;
+    do {
+      const t0 = Date.now();
+      let failed = false;
+      try {
+        const r = await runShip(client, { full });
+        console.log(`[memhouse] shipped ${r.sessions} sessions (${r.skipped} skipped${r.unreadable ? `, ${r.unreadable} unreadable-will-retry` : ''}) → ` +
+          `${r.msgRows} msg rows, ${r.toolRows} tool rows in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+      } catch (e) {
+        failed = true;
+        // A connection failure arrives as an AggregateError whose own `message` is empty,
+        // so this printed "[memhouse] pass failed:" and nothing else, after 35 lines of
+        // driver internals. Dig out a cause and name the fix; `status` and `doctor`
+        // already handle the same condition cleanly and `ship` was the odd one out.
+        const causes = (e && e.errors) ? e.errors.map((x) => x && x.message).filter(Boolean) : [];
+        const why = e.message || causes[0] || e.code || String(e);
+        console.error(`[memhouse] pass failed: ${why}`);
+        if (/ECONNREFUSED|fetch failed|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(why + causes.join(' '))) {
+          console.error(`[memhouse] ${process.env.MEMHOUSE_URL} did not answer — is the house running?`);
+        } else if (/Authentication failed|ACCESS_DENIED|Not enough privileges/i.test(why)) {
+          console.error(`[memhouse] the credential in ${process.env.MEMHOUSE_HOME || '~/.memhouse'}/env was rejected by ${process.env.MEMHOUSE_URL}`);
+        } else if (/does not exist|UNKNOWN_TABLE|UNKNOWN_DATABASE/i.test(why)) {
+          console.error('[memhouse] the house is missing a room this pass needed');
+        }
+        // doctor diagnoses every one of these and prints the fix, so say so ALWAYS rather
+        // than only for the one failure mode that happened to be special-cased. The line
+        // this used to end on — "MEMHOUSE_DEBUG=1 for the full error" — is a next step for
+        // filing a bug, not for fixing the house.
+        console.error('[memhouse] diagnose it with: memhouse doctor');
+        if (process.env.MEMHOUSE_DEBUG) console.error(e);
+        else console.error('[memhouse] (MEMHOUSE_DEBUG=1 for the full error)');
+        if (!loop) process.exitCode = 1;
+      }
+      full = false; // --full applies to the first pass only; loop passes stay incremental
+      if (loop) {
+        const waitMs = failed ? Math.min(retryMs, intervalSec * 1000) : intervalSec * 1000;
+        if (failed) {
+          console.error(`[memhouse] retrying in ${Math.round(waitMs / 1000)}s`);
+          retryMs = Math.min(retryMs * 2, intervalSec * 1000);
+        } else {
+          retryMs = RETRY_START_MS;
+        }
+        await new Promise((r) => setTimeout(r, waitMs));
+        resetCaches(); // adapters cache chat lists; drop them so new sessions surface
+        // Then, before the next pass, notice if the installation underneath us changed.
+        // Checked AFTER the wait rather than before it so an upgrade landing mid-sleep is
+        // acted on at the top of the next pass instead of one whole interval later — and
+        // never mid-pass, where handing over would abandon a half-shipped session.
+        // Does not return when it hands over.
+        selfUpdate.maybeRestart({ snap: selfSnap, name: 'shipper' });
+      }
+    } while (loop);
+  } finally {
+    await client.close();
+  }
+}
+
+module.exports = { runShip, ensureSchema, templateColumns };
+
+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:"
+    // first put a raw driver sentence above that refusal and made a handled case read like
+    // an unhandled one.
+    // Exit quietly ONLY where a caller is known to print the refusal itself: install and
+    // doctor both catch this condition and name both routes. Everywhere else — and
+    // `memhouse ship` is everywhere else — silence plus exit 1 is the worst possible
+    // output, and this suppression produced exactly that for a member following the
+    // advice to run `ship --ensure-schema`.
+    const m = e && e.message ? e.message : String(e);
+    if (/Not enough privileges|ACCESS_DENIED/i.test(m) && process.env.MEMHOUSE_QUIET_DENIED === '1') process.exit(1);
+    console.error(`[memhouse] ${/Not enough privileges|ACCESS_DENIED/i.test(m) ? 'refused' : 'fatal'}: ${m}`);
+    process.exit(1);
+  });
+}