memhouse 0.4.4 → 0.7.1

package/memhouse/per-member/rooms.js

@@ -0,0 +1,252 @@
+// Room-name resolution.
+//
+// Every member owns their rooms, named TYPE-FIRST: `sessions_<member>`,
+// `messages_<member>`, `tool_calls_<member>`. Type-first is what lets the Merge rooms
+// anchor on a fixed room type (`^sessions_`) and never match themselves.
+//
+// THIS IS THE ONLY LAYOUT. There was a shared one — three rooms named `sessions`,
+// `messages`, `tool_calls`, with row policies narrowing each caller to their own rows —
+// and it is gone. A shared read is a Merge room plus a GRANT, which is strictly less
+// machinery than a policy that has to be right on every table and every read path; and
+// isolation by absent grant fails closed, where a row policy fails open the moment one is
+// missing.
+//
+// The member is never supplied by the caller — it is read back from the server with
+// currentUser(), the same value the rooms' user_id column is stamped with. A client that
+// could name its own member could write into someone else's rooms.
+//
+// `sessions_v` IS A SAVED QUERY, NOT A ROOM. It was briefly a stored view, which cost a
+// name inside the `^sessions_` namespace the Merge rooms select on (silently merged into
+// `all_sessions`, doubling every count), a fourth grant per member, and a fourth object to
+// provision, roll forward and drop. A saved query is substituted with the caller's own
+// room names and runs under the caller's credential, so it inherits their grants and
+// raises no view-ownership question at all.
+
+const ROOM_TYPES = ['sessions', 'messages', 'tool_calls'];
+
+/**
+ * What a member is granted on their own rooms. ONE definition, because there are two paths
+ * that provision a house — provision.js and `install --print-sql` — and when only the first
+ * was narrowed the second went on emitting `GRANT ALL` for a release. GRANT ALL includes
+ * CREATE TABLE **on the member's own room name**, so a member owns the name rather than the
+ * data and can replace the room with a Merge over everyone's, doubling other members' rows
+ * in the team room.
+ *
+ * ALTER UPDATE and ALTER DELETE both: `DELETE FROM` is a lightweight delete implemented as
+ * `ALTER TABLE … UPDATE _row_exists = 0`, and which of the two a server demands varies by
+ * version. ALTER ADD COLUMN for ensureSchema's rollout. Nothing that defines an object.
+ */
+const MEMBER_PRIVS = 'SELECT, INSERT, ALTER UPDATE, ALTER DELETE, ALTER ADD COLUMN, OPTIMIZE';
+
+/**
+ * Resource ceilings for a member, as a settings profile.
+ *
+ * Here for the same reason MEMBER_PRIVS is here: there are two paths that provision a
+ * house — provision.js and `install --print-sql` — and a change made to one of them and
+ * not the other has now happened eight times. Anything a member is GIVEN belongs in this
+ * file, so both paths read the same definition.
+ *
+ * MIN..MAX, not CONST and not MAX alone.
+ *
+ * A plain default is advisory — a member writes `SETTINGS max_memory_usage = …` on their
+ * query and overrides it. MAX alone is not enough either: in ClickHouse **0 means
+ * unlimited** for these, and 0 satisfies any MAX, so `SETTINGS max_memory_usage = 0`
+ * removed the ceiling entirely. MIN 1 closes that.
+ *
+ * CONST closes it too and was tried first — but CONST refuses EVERY change, including the
+ * server's own. `rawQuery` in memhouse/server/queries.js pins max_result_rows and
+ * max_execution_time to protect the dashboard from an unbounded query, and under CONST
+ * those pins were refused with Code 452, so /api/query returned an error for every input
+ * on any house provisioned after that change. A ceiling has to stop a member RAISING the
+ * limit while still letting anyone LOWER it.
+ *
+ * max_memory_usage is per QUERY; max_memory_usage_for_user bounds the member across
+ * concurrent queries, without which N parallel queries x the per-query ceiling is
+ * unbounded.
+ *
+ * Limits are generous on purpose: the point is to stop one member exhausting a shared
+ * server, not to make an honest full re-ship fail — a 20M-row scan runs inside them.
+ *
+ * KNOWN GAP, deliberately not closed here: ALTER UPDATE, ALTER DELETE and OPTIMIZE are in
+ * MEMBER_PRIVS and execute in the background merge pool, where these per-query settings do
+ * not apply. A member looping `OPTIMIZE … FINAL` on a large room can still load the box.
+ * Bounding that needs server-level merge-pool configuration, which is the operator's, not
+ * something a per-member profile can express.
+ */
+/**
+ * The global-install command that will actually work HERE.
+ *
+ * Every site that printed `npm install -g memhouse --allow-scripts=better-sqlite3` printed
+ * a line that fails with EACCES on any distro-packaged Node, because the global prefix is
+ * root-owned — measured on a clean Ubuntu machine, exit 243, including as step 1 of
+ * `prompt --install`, which advertises itself as rendered for this machine. The README
+ * learned this; eight code sites had not.
+ *
+ * `sudo` is right for exactly one of the two causes and makes the other worse, and what
+ * tells them apart is who owns the prefix — so look, rather than guess.
+ */
+function installCommand() {
+  const base = 'npm install -g memhouse --allow-scripts=better-sqlite3';
+  try {
+    const { execFileSync } = require('child_process');
+    const prefix = execFileSync('npm', ['prefix', '-g'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const st = require('fs').statSync(prefix);
+    if (st.uid !== process.getuid()) return `sudo ${base}`;
+  } catch { /* npm not on PATH, or an unreadable prefix: fall through to the plain form */ }
+  return base;
+}
+
+const MEMBER_PROFILE = 'memhouse_member';
+const MEMBER_PROFILE_SETTINGS = [
+  'max_memory_usage = 8000000000 MIN 1 MAX 8000000000',
+  'max_memory_usage_for_user = 16000000000 MIN 1 MAX 16000000000',
+  'max_execution_time = 600 MIN 1 MAX 600',
+  'max_threads = 16 MIN 1 MAX 16',
+  'max_result_rows = 10000000 MIN 1 MAX 10000000',
+  // Provenance, pinned server-side rather than trusted to every client.
+  //
+  // `user_id MATERIALIZED currentUser()` is what records who wrote a row — but a
+  // MATERIALIZED column is computed during the INSERT, and an ASYNC insert flushes
+  // outside that context: measured on 25.11.9.34, `async_insert=1` stores user_id as the
+  // EMPTY STRING while a sync insert on the same table stamps correctly. An unattributed
+  // row is invisible to every identity-bound path at once, including its own owner's
+  // `reset`.
+  //
+  // The shipper already passes async_insert=0 on every insert, so memhouse itself was
+  // never the risk. The risk is everything ELSE holding a member credential — an agent
+  // following the /memhouse:sql skill, a migration script, a psql-habit one-liner. CONST
+  // makes the house refuse (SETTING_CONSTRAINT_VIOLATION) instead of silently accepting
+  // rows nobody owns, which is the difference between a guarantee and a convention.
+  // `doctor` still checks for blank user_id — that stays, as the detector for rows
+  // written before this profile existed.
+  'async_insert = 0 CONST',
+].join(', ');
+
+// ClickHouse usernames are permissive; room names are not. Refuse anything that would
+// need quoting or could change how a Merge regex or a name-splitter reads.
+function assertUsableMember(member) {
+  if (typeof member !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(member)) {
+    throw new Error(`cannot build room names for user '${member}': expected [A-Za-z][A-Za-z0-9_]*`);
+  }
+  // The reservation lives HERE, not only in the CLI, because provision.js is the admin
+  // entry point INSTALL.md sends you to for a second member — and it went as far as
+  // creating sessions_root/messages_root/tool_calls_root before dying on the grant,
+  // leaving three orphan rooms nothing removes. Case-insensitive: Root and ROOT are the
+  // same account. `default` is deliberately NOT reserved — a poor member name, but a real
+  // one that existing houses are built on.
+  if (member.toLowerCase() === 'root') {
+    throw new Error("'root' cannot be a member: it is a container artefact, not a person");
+  }
+}
+
+/**
+ * The session rollup, as SQL text rather than a name.
+ *
+ * Two properties are load bearing: the join is a LEFT JOIN, so a session with no messages
+ * still appears with zero aggregates instead of vanishing from every count; and
+ * `join_use_nulls = 1` makes the unmatched message columns NULL so `coalesce` yields true
+ * zeros rather than counting the placeholder row.
+ *
+ * BOTH ARE NOW CARRIED BY THE TEXT ITSELF — `FINAL` on each room and a trailing
+ * `SETTINGS join_use_nulls = 1`. It used to depend on the caller passing `final=1` and
+ * `join_use_nulls=1`, on the belief that a subquery cannot carry its own SETTINGS. It can
+ * (verified on 26.7 and 25.11), and the belief was expensive: every consumer that forgot
+ * the settings silently counted each message once per undeleted ReplacingMergeTree
+ * version. Measured right after a `ship --full` — 2x, and 3x three ships later. It does
+ * not self-heal; the error grows with each pass until a merge happens to collapse the
+ * parts. `memhouse sessions-query > q.sql` lost the warning entirely, because it was
+ * printed on stderr as a SQL comment that never reached the SQL.
+ *
+ * Passing final=1 as well is harmless, so READ_SETTINGS stays as it is for direct room
+ * reads, which still need it.
+ */
+function sessionsRollup({ sessions, messages }) {
+  return `(
+    SELECT
+        s.session_id AS session_id,
+        any(s.source) AS source,
+        any(s.host) AS host,
+        any(s.name) AS name,
+        any(s.mode) AS mode,
+        any(s.folder) AS folder,
+        any(s.project) AS project,
+        any(s.git_branch) AS git_branch,
+        s.user_id AS user_id,
+        any(s.created_at) AS created_at,
+        any(s.last_updated_at) AS last_updated_at,
+        min(m.ts) AS started,
+        max(m.ts) AS ended,
+        coalesce(dateDiff('second', min(m.ts), max(m.ts)), 0) AS duration_sec,
+        count(m.seq) AS total_msgs,
+        countIf(m.role = 'user') AS user_msgs,
+        countIf(m.role = 'assistant') AS assistant_msgs,
+        countIf(m.is_subagent) AS subagent_msgs,
+        groupUniqArrayIf(m.model, m.model NOT IN ('', '<synthetic>')) AS models,
+        coalesce(sum(m.input_tokens), 0) AS input_tokens,
+        coalesce(sum(m.output_tokens), 0) AS output_tokens,
+        coalesce(sum(m.cache_read_tokens), 0) AS cache_read_tokens,
+        coalesce(sum(m.cache_write_tokens), 0) AS cache_write_tokens,
+        coalesce(sumIf(length(m.text), m.role = 'user'), 0) AS user_chars,
+        coalesce(sumIf(length(m.text), m.role = 'assistant'), 0) AS assistant_chars,
+        coalesce(substring(argMinIf(m.text, m.seq, m.role = 'user' AND m.text != ''), 1, 200), '') AS first_prompt
+    FROM ${sessions} AS s FINAL
+    LEFT JOIN ${messages} AS m FINAL ON m.session_id = s.session_id AND m.user_id = s.user_id
+    GROUP BY s.session_id, s.user_id
+    SETTINGS join_use_nulls = 1
+  )`;
+}
+
+/**
+ * The settings every read needs. `final` collapses ReplacingMergeTree versions;
+ * `join_use_nulls` is what the rollup's coalesce depends on.
+ */
+const READ_SETTINGS = { final: 1, join_use_nulls: 1 };
+
+/**
+ * Names, given the member the server reported. Shared by every caller so the two
+ * transports in the tree (@clickhouse/client and the CLI's raw fetch) cannot drift into
+ * two different naming rules.
+ *
+ * `sessions_v` is the rollup as SQL text, usable in the same `FROM ... AS c` position a
+ * view name would occupy — which is what lets the read layer treat it as just another
+ * resolved name.
+ */
+function roomNames(member, user = member) {
+  assertUsableMember(member);
+  const out = { member, user };
+  for (const t of ROOM_TYPES) out[t] = `${t}_${member}`;
+  out.sessions_v = sessionsRollup(out);
+  return out;
+}
+
+async function currentUser(client) {
+  const rs = await client.query({ query: 'SELECT currentUser() AS u', format: 'JSONEachRow' });
+  const rows = await rs.json();
+  const u = rows[0] && rows[0].u;
+  if (!u) throw new Error('could not determine currentUser()');
+  return u;
+}
+
+/**
+ * Resolve the rooms for whoever this client is connected as.
+ * Returns { sessions, messages, tool_calls, sessions_v, member, user }.
+ *
+ * `user` is the identity the server reports. Writers need the value itself, not just the
+ * name it produces — see ship.js's delete, which must BIND the user rather than call
+ * currentUser() inside a mutation, where it is not evaluated in the caller's context.
+ */
+async function resolveRooms(client) {
+  const user = await currentUser(client);
+  return roomNames(user, user);
+}
+
+/** The three Merge rooms — team-wide read paths, owner-managed. */
+function mergeRooms() {
+  return { sessions: 'all_sessions', messages: 'all_messages', tool_calls: 'all_tool_calls' };
+}
+
+module.exports = {
+  MEMBER_PRIVS, installCommand, MEMBER_PROFILE, MEMBER_PROFILE_SETTINGS,
+  ROOM_TYPES, READ_SETTINGS, assertUsableMember,
+  sessionsRollup, roomNames, currentUser, resolveRooms, mergeRooms,
+};

package/{mem-house → memhouse}/per-member/schema-member.sql.tpl

@@ -1,4 +1,4 @@
--- mem — one member's rooms. Applied per member; {{MEMBER}} is the ClickHouse username.
+-- mem — one member's rooms. Applied per member — {{MEMBER}} is the ClickHouse username.
 --
 -- Room naming is TYPE-FIRST (sessions_<m>, not <m>_sessions) so the Merge rooms
 -- can anchor on a fixed room type and never match themselves.
@@ -7,7 +7,7 @@
 -- it keeps provenance across a share and keeps the Merge rooms meaningful. Writers must
 -- use async_insert=0 or the stamp does not happen.
 --
--- ClickHouse >= 26.2 natively; 25.11 works because the shipper passes
+-- ClickHouse >= 26.2 natively — 25.11 works because the shipper passes
 -- allow_experimental_full_text_index=1 per-query when applying this file.
 
 CREATE TABLE IF NOT EXISTS sessions_{{MEMBER}}
@@ -25,23 +25,27 @@ CREATE TABLE IF NOT EXISTS sessions_{{MEMBER}}
     message_count UInt32 DEFAULT 0,
     path String DEFAULT '',
     extra JSON,
-    -- Who put this row here. The shipper CLEARS a session before re-inserting it (a
-    -- shorter re-parse must not leave a stale seq tail), and that clear used to remove
-    -- every row for the session regardless of origin -- destroying imported history the
-    -- adapters cannot reproduce. The clear now binds origin='ship', so anything imported
-    -- survives a re-ship of the same session.
-    -- IN THE SORTING KEY, and that is the load-bearing half. Guarding the DELETE alone
-    -- is not enough: ReplacingMergeTree collapses on the sorting key, so an imported row
-    -- and a shipped row sharing (session_id, user_id, seq) are the SAME row and the newer
-    -- ingested_at wins. Measured: 3 imported + 2 shipped rows became 3, and the two
-    -- imported ones the shipper happened to overlap were gone. Same loss as the
-    -- unguarded delete, reached through the merge instead.
+    -- Who put this row here. Carried on every room so a reader can tell shipped rows
+    -- from imported ones, and so the shipper's clear can bind origin='ship'.
+    --
+    -- NOTE the sorting key below does NOT include origin, and sessions is the one room
+    -- where that is correct. A session has exactly ONE metadata row: title, counts,
+    -- bounds. If origin were in the key, an imported session and its shipped twin would
+    -- be two rows, and everything that reads sessions as one-row-per-session breaks --
+    -- sessions_v joins messages twice and over-reports (measured on a real house: one
+    -- duplicate row inflated the totals by 1,764 messages and 655M tokens), and the
+    -- incremental skip cannot decide which row is current. Collapsing them is what we
+    -- want: the newer ingested_at wins, which is the shipper's row for any session that
+    -- still exists on disk. Nothing is lost -- a session the adapters no longer see is
+    -- never cleared and never re-inserted, so its imported row stands untouched.
+    --
+    -- messages and tool_calls are the opposite case and DO key on origin -- see there.
     origin LowCardinality(String) DEFAULT 'ship',
     user_id String MATERIALIZED currentUser(),
     ingested_at DateTime64(3, 'UTC') DEFAULT now64(3)
 )
 ENGINE = ReplacingMergeTree(ingested_at)
-ORDER BY (session_id, user_id, origin);
+ORDER BY (session_id, user_id);
 
 CREATE TABLE IF NOT EXISTS messages_{{MEMBER}}
 (

package/{mem-house → memhouse}/per-member/schema-merge.sql.tpl

@@ -6,13 +6,13 @@
 --
 -- Three measured properties this relies on (ClickHouse 26.7.1):
 --   * fails closed on permissions — a caller sees only the underlying rooms they hold
---     grants for, with no leak and no error, so these can be granted broadly;
---   * auto-discovers rooms created after them, so member onboarding needs no DDL here;
+--     grants for, with no leak and no error, so these can be granted broadly —
+--   * auto-discovers rooms created after them, so member onboarding needs no DDL here —
 --   * tolerates schema drift, returning a column's default for rooms lacking it — which
 --     is what makes schema rollout progressive. Merge REJECTS mutations, so a new column
 --     is added with ADD COLUMN, on the Merge room FIRST.
 --
--- {{TEMPLATE_MEMBER}} is any existing member; the Merge room borrows its column list.
+-- {{TEMPLATE_MEMBER}} is any existing member — the Merge room borrows its column list.
 
 CREATE TABLE IF NOT EXISTS all_sessions AS sessions_{{TEMPLATE_MEMBER}}
 ENGINE = Merge(currentDatabase(), '^sessions_');

package/memhouse/resume.js

@@ -0,0 +1,150 @@
+// Resume: hand the pilot back into a session memhouse only ever read.
+//
+// Nothing here needs a schema change. A stored session already carries everything a
+// resume needs: `session_id` is canonical `<source>:<native-id>` (ship.js:575) and
+// `folder` is the directory the session ran in. Resume is a read-time computation over
+// two columns.
+//
+// Two rules, both learned the hard way in this repo:
+//
+//   1. PRINT the command, never run it. A wrong cwd or a stale id does not fail — it
+//      starts a NEW session, and the transcript the pilot wanted is still lost while the
+//      tool reports success. The pilot pastes it, sees what it does, and owns the result.
+//
+//   2. Never write a flag from memory. Round 10 exists because a field name was asserted
+//      from a failed search rather than read from the source. Every entry below was read
+//      out of that CLI's own `--help` on a machine where it is installed, and the date and
+//      version are recorded with it. An editor whose flag has not been read that way is
+//      ABSENT from this table — an absent entry prints an honest refusal, a guessed entry
+//      prints a command that silently does the wrong thing.
+//
+// To add one: install the CLI, run `<cli> --help` (and `<cli> resume --help` if it is a
+// subcommand), copy the exact syntax, and record what you read it from.
+
+// Keyed by the string that is actually STORED in the `source` column, which is NOT the
+// adapter's module `name`: editors/claude.js is `const name = 'claude'` and emits
+// `source: 'claude-code'` on every chat it returns. This table was written against the
+// module names first and would have refused to resume a single Claude Code session — 508 of
+// them on the machine it was tested on. Read the values out of a real house
+// (`SELECT DISTINCT source FROM sessions_<you>`), never off the adapter's name.
+const RESUMERS = {
+  // claude --help, 2026-08-12: "-r, --resume [value]  Resume a conversation by session ID"
+  'claude-code': {
+    cli: 'claude',
+    argv: (id) => ['--resume', id],
+    verified: '2026-08-12',
+  },
+  // codex resume --help, 2026-08-12: "Usage: codex resume [OPTIONS] [SESSION_ID] [PROMPT]"
+  // — positional, and "UUIDs take precedence if it parses".
+  codex: {
+    cli: 'codex',
+    argv: (id) => ['resume', id],
+    verified: '2026-08-12',
+  },
+  // opencode --help, 2026-08-12: "-s, --session  session id to continue  [string]"
+  opencode: {
+    cli: 'opencode',
+    argv: (id) => ['--session', id],
+    verified: '2026-08-12',
+  },
+  // NOT here, deliberately, and each for a different reason:
+  //
+  //   goose, gemini-cli, cursor-agent — plausibly resumable, but not installed on the
+  //   machine this table was written on, so the flag could only have been guessed. Install
+  //   one, read its --help, add it.
+  //
+  //   everything in GUI_ONLY — no CLI entry point takes a session id there. Opening the
+  //   folder is not resuming the session and must not be dressed up as it.
+};
+
+// Surfaces with no CLI to resume into AT ALL, separated from "the flag has not been read
+// yet" so the refusal can say which of the two it is — the same reason `discover` separates
+// a skipped adapter from an editor you do not have.
+//
+// Stored `source` values again, and two corrections already: `copilot.js` emits
+// `copilot-cli` and IS a command line, so it does not belong here; and windsurf never emits
+// 'windsurf' at all — it emits its VARIANTS id, `devin` or `devin-next` — so the name this
+// list first carried matched nothing and every Devin session fell through to the wrong
+// refusal.
+//
+// Membership means: no command line takes a session id here, so no amount of checking will
+// produce one. Anything merely UNCHECKED belongs in UNVERIFIED — asserting "there is
+// nothing to resume into" about a tool nobody has looked at is the same invented fact as
+// guessing a flag.
+const GUI_ONLY = new Set([
+  'cursor', 'vscode', 'zed', 'kiro', 'copilot-jetbrains', 'antigravity',
+  'devin', 'devin-next',
+]);
+
+// A plausible CLI that nobody has verified. Listed explicitly instead of left to fall
+// through a default, so the completeness test can prove every source the adapters can emit
+// lands in exactly one bucket — which is what would have caught both corrections above
+// before they shipped.
+const UNVERIFIED = new Set([
+  'goose', 'gemini-cli', 'cursor-agent', 'copilot-cli', 'codebuff', 'commandcode', 'gsd',
+]);
+
+// A session_id is `<source>:<native-id>`. Split on the FIRST colon only: several editors
+// use colons inside their own ids, and slicing on the last one hands the CLI a truncated id
+// that resolves to nothing.
+function splitSessionId(sessionId) {
+  const i = String(sessionId).indexOf(':');
+  if (i <= 0) return null;
+  return { source: sessionId.slice(0, i), nativeId: sessionId.slice(i + 1) };
+}
+
+// Shell-quote for the line we PRINT. This never feeds an exec — it is text a human pastes
+// — but a session folder with a space in it must still paste correctly, and an id is
+// server-supplied data that has no business being read as shell syntax.
+function shq(s) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Resolve a stored session row into something the pilot can paste.
+ *
+ * @param {{session_id: string, source?: string, folder?: string, origin?: string}} row
+ * @returns {{ok: boolean, source: string, nativeId: string|null, folder: string,
+ *            command: string|null, reason: string|null}}
+ */
+function resumeFor(row) {
+  const parts = splitSessionId(row.session_id);
+  // `source` is its own column, but the id prefix is what the CLI half of the pair is keyed
+  // on; prefer the column and fall back to the prefix so a row from an older house still
+  // resolves.
+  const source = row.source || (parts && parts.source) || '';
+  const nativeId = parts ? parts.nativeId : null;
+  const folder = row.folder || '';
+  const base = { source, nativeId, folder, command: null, ok: false, reason: null };
+
+  if (!nativeId) {
+    return { ...base, reason: `'${row.session_id}' is not a canonical <source>:<id> session id` };
+  }
+  // Imported rows come from an older house, another product, or a machine that no longer
+  // exists — the whole point of the `origin` guard the shipper carries. There is no local
+  // session store behind them, so no resume command can be right, and this is checked
+  // BEFORE the source table: 502 of the 1,304 sessions on the machine this was built on are
+  // imported `claude-ai` rows, and a source-only check would have offered to resume them.
+  if (row.origin && row.origin !== 'ship') {
+    return {
+      ...base,
+      reason: `this session was imported (origin='${row.origin}'), not read from a local editor — there is nothing on this machine to resume into`,
+    };
+  }
+  const r = RESUMERS[source];
+  if (!r) {
+    return {
+      ...base,
+      reason: GUI_ONLY.has(source)
+        ? `${source} is a GUI editor — it has no CLI that takes a session id, so there is nothing to resume into`
+        : `no verified resume command for ${source} — see memhouse/resume.js for how to add one`,
+    };
+  }
+  const cmd = [r.cli, ...r.argv(nativeId)].map(shq).join(' ');
+  // The cd is half the command. Claude Code and Codex both scope their session lists by
+  // working directory, so the same id run from the wrong folder opens the picker or a new
+  // session instead of the transcript that was asked for.
+  return { ...base, ok: true, command: folder ? `cd ${shq(folder)} && ${cmd}` : cmd };
+}
+
+module.exports = { RESUMERS, GUI_ONLY, UNVERIFIED, resumeFor, splitSessionId };

package/memhouse/self-update.js

@@ -0,0 +1,150 @@
+// A daemon that keeps executing the code it booted with.
+//
+// `npm i -g memhouse@latest` replaces the files under the global prefix and does not touch
+// the running processes, so the shipper keeps parsing with the old adapters and the
+// dashboard keeps serving the old bundle. Nothing reports it: `status` prints the version
+// of the CLI you just typed, not the version the daemon is running. On macminim a shipper
+// ran 1d16h out of a directory that had been MOVED — the fix was live, the machine was not.
+//
+// npm's own `postinstall` is the obvious hook and the wrong one. Install scripts are
+// blocked by default (`--allow-scripts`), which is the very condition this product already
+// has to work around, and a package install that restarts a user's daemons is a surprise
+// even when it works.
+//
+// So the daemon notices for itself. Once per loop pass it compares what is on disk against
+// what it booted with, and when they differ it hands over:
+//
+//   supervised (systemd/launchd set MEMHOUSE_SUPERVISED=1) — exit 0 and let the supervisor
+//     start a fresh process. Re-execing under a supervisor fights it: the unit's own
+//     restart would then race the child we spawned.
+//
+//   unsupervised (`memhouse start` pidfiles) — re-exec ourselves detached, rewrite the
+//     pidfile, exit. Nothing else would ever restart it, and exiting silently would stop
+//     collecting memory, which is worse than running one pass of stale code.
+//
+// Guards, because a daemon that restarts itself wrongly is worse than one that is stale:
+// a re-exec chain is counted in the environment and capped, and there is a floor on how
+// often a restart may happen at all.
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const CHAIN_VAR = 'MEMHOUSE_REEXEC_CHAIN';
+const MAX_CHAIN = 3;
+const MIN_INTERVAL_MS = 60_000;
+
+function runDir() {
+  const home = process.env.MEMHOUSE_HOME || path.join(require('os').homedir(), '.memhouse');
+  return path.join(home, 'run');
+}
+
+// Read the version off DISK, never `require()`. require caches the first read for the
+// lifetime of the process, so a required package.json reports the version this daemon
+// booted with no matter how many times it is re-read — which is exactly the value we are
+// trying to detect a change in.
+function diskVersion(repoRoot) {
+  try { return JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf-8')).version || null; }
+  catch { return null; }
+}
+
+/**
+ * What this process is running, captured at boot.
+ * @param {string} entry absolute path of the daemon's own entry script
+ * @param {string} [repoRoot] where package.json lives; defaults two levels up from the
+ *   entry's directory, which is where both daemons sit (memhouse/<part>/<entry>.js).
+ *   Pass it explicitly rather than relying on that depth if you move an entry.
+ */
+function snapshot(entry, repoRoot = path.join(path.dirname(entry), '..', '..')) {
+  let real = null, mtimeMs = null;
+  try { real = fs.realpathSync(entry); mtimeMs = fs.statSync(real).mtimeMs; } catch { /* reported as drift */ }
+  return { entry, repoRoot, version: diskVersion(repoRoot), real, mtimeMs, at: Date.now() };
+}
+
+/**
+ * Has the installation underneath us changed?
+ * @returns {string|null} a human-readable reason, or null when nothing moved
+ */
+function driftReason(snap) {
+  const now = diskVersion(snap.repoRoot);
+  if (snap.version && now && now !== snap.version) return `version changed ${snap.version} → ${now}`;
+  let real = null, mtimeMs = null;
+  try { real = fs.realpathSync(snap.entry); mtimeMs = fs.statSync(real).mtimeMs; } catch { real = null; }
+  // The entry is gone: the directory this daemon runs out of was deleted, moved, or
+  // replaced. Reported, but NOT restartable — see maybeRestart, which refuses to re-exec a
+  // path that no longer resolves.
+  if (!real) return 'the directory this daemon runs from no longer exists';
+  if (snap.real && real !== snap.real) return `entry moved ${snap.real} → ${real}`;
+  // mtime alone, with the version unchanged, is a checkout being rebuilt or edited in
+  // place. Worth acting on for the same reason the version is: the running process is not
+  // the code on disk.
+  if (snap.mtimeMs && mtimeMs && mtimeMs !== snap.mtimeMs) return 'the entry script changed on disk';
+  return null;
+}
+
+function chainCount() {
+  const n = Number(process.env[CHAIN_VAR]);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+// Only ever rewrite a pidfile that names US. A daemon started by hand has no pidfile, and a
+// pidfile naming some other process belongs to that process — overwriting it would point
+// `memhouse stop` at ours and leave theirs running forever.
+function adoptPidfile(name, newPid, log) {
+  const file = path.join(runDir(), name + '.pid');
+  try {
+    if (Number(fs.readFileSync(file, 'utf-8').trim()) !== process.pid) return;
+    fs.writeFileSync(file, String(newPid));
+  } catch { log(`[memhouse] could not update ${file} — 'memhouse stop' may not find the new process`); }
+}
+
+/**
+ * Act on drift. Returns false when nothing was done, and does not return at all when it
+ * hands over (the process exits).
+ *
+ * @param {object} o
+ * @param {ReturnType<snapshot>} o.snap  what we booted with
+ * @param {string} o.name                daemon name, matching its pidfile ('shipper' | 'dashboard')
+ * @param {(s: string) => void} [o.log]
+ */
+function maybeRestart({ snap, name, log = console.error }) {
+  const reason = driftReason(snap);
+  if (!reason) return false;
+  if (Date.now() - snap.at < MIN_INTERVAL_MS) return false;
+
+  const supervised = process.env.MEMHOUSE_SUPERVISED === '1';
+  log(`[memhouse] ${reason} — this ${name} is running code that is no longer installed`);
+
+  if (supervised) {
+    log('[memhouse] exiting so the service manager starts the new version');
+    process.exit(0);
+  }
+  // An entry that does not resolve cannot be re-executed, and there is no supervisor to
+  // resolve a fresh one. Keep shipping with what is loaded and say so every pass: a stale
+  // daemon still collects sessions, a dead one collects nothing.
+  let real = null;
+  try { real = fs.realpathSync(snap.entry); } catch { /* handled next */ }
+  if (!real) {
+    log(`[memhouse] cannot restart — nothing to exec. Fix it with: memhouse stop && memhouse start`);
+    return false;
+  }
+  if (chainCount() >= MAX_CHAIN) {
+    log(`[memhouse] already restarted ${MAX_CHAIN} times in this chain — not restarting again. Fix it with: memhouse stop && memhouse start`);
+    return false;
+  }
+
+  const child = spawn(process.execPath, [real, ...process.argv.slice(2)], {
+    env: { ...process.env, [CHAIN_VAR]: String(chainCount() + 1) },
+    detached: true,
+    // The daemon's stdout/stderr are already the log file `memhouse start` opened, and a
+    // detached child inherits those descriptors — so the new process keeps writing to the
+    // same log with no second file to find.
+    stdio: 'inherit',
+  });
+  child.unref();
+  adoptPidfile(name, child.pid, log);
+  log(`[memhouse] restarted as pid ${child.pid}`);
+  process.exit(0);
+}
+
+module.exports = { snapshot, driftReason, maybeRestart, CHAIN_VAR, MAX_CHAIN, MIN_INTERVAL_MS };