memhouse 0.18.10 → 0.18.11

package/editors/claude.js

@@ -74,13 +74,18 @@ function getChats() {
     } catch { /* no index */ }
 
     // Scan all .jsonl files on disk (some may not be in the index)
-    let files;
-    try { files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')); } catch { continue; }
+    let names;
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    const files = names.filter(f => f.endsWith('.jsonl'));
+    // A session with subagents also has a directory named for it; one without has none, so
+    // this listing is how the mtime check below stays free for the sessions it cannot help.
+    const sessionDirs = new Set(names.filter(f => !f.endsWith('.jsonl')));
 
     for (const file of files) {
       const sessionId = file.replace('.jsonl', '');
       const fullPath = path.join(dir, file);
       const entry = indexed.get(sessionId);
+      const subTouched = sessionDirs.has(sessionId) ? newestSubagentMtime(path.join(dir, sessionId, 'subagents')) : 0;
 
       if (entry) {
         // Use index metadata
@@ -89,7 +94,7 @@ function getChats() {
           composerId: sessionId,
           name: cleanPrompt(entry.firstPrompt),
           createdAt: entry.created ? new Date(entry.created).getTime() : null,
-          lastUpdatedAt: entry.modified ? new Date(entry.modified).getTime() : null,
+          lastUpdatedAt: latest(entry.modified ? new Date(entry.modified).getTime() : null, subTouched),
           mode: 'claude',
           folder: entry.projectPath || decodedFolder,
           encrypted: false,
@@ -107,7 +112,7 @@ function getChats() {
             composerId: sessionId,
             name: meta.firstPrompt ? cleanPrompt(meta.firstPrompt) : null,
             createdAt: meta.timestamp || stat.birthtime.getTime(),
-            lastUpdatedAt: stat.mtime.getTime(),
+            lastUpdatedAt: latest(stat.mtime.getTime(), subTouched),
             mode: 'claude',
             folder: meta.cwd || decodedFolder,
             encrypted: false,
@@ -195,7 +200,7 @@ 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, agent = null) {
+function parseSessionFile(filePath, isSubagent, agent = null, info = null) {
   const messages = [];
   let lines;
   try { lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean); } catch { return messages; }
@@ -205,7 +210,9 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
   // 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.
+  // part of the line hash. The position is not only a label any more: the shipper numbers
+  // a subagent's rows from it (seq = block + turn, see subagentSeq in ship.js), so `turn`
+  // must count exactly the turns this parse keeps, in order.
   let turn = 0;
   const stamp = (m) => { if (agent) { m._agent = { ...agent, turn: turn++ }; } return m; };
 
@@ -228,6 +235,7 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
     // time simply omit it.
     const _ts = obj.timestamp ? Date.parse(obj.timestamp) : undefined;
     const at = Number.isFinite(_ts) ? _ts : undefined;
+    if (info && info.firstTs === undefined && at !== undefined) info.firstTs = at;
 
     if (obj.type === 'user' && obj.message) {
       const content = extractContent(obj.message.content);
@@ -249,6 +257,10 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
   return messages;
 }
 
+// How long a subagent transcript without a single timestamped line may hold back its
+// session (see getMessages). A real one gets its first line within seconds.
+const SUBAGENT_STAMP_GRACE_MS = 10 * 60 * 1000;
+
 function getMessages(chat) {
   const filePath = chat._fullPath;
   if (!filePath || !fs.existsSync(filePath)) return [];
@@ -262,30 +274,76 @@ function getMessages(chat) {
   const subagentsDir = path.join(filePath.replace(/\.jsonl$/, ''), 'subagents');
   const subFiles = subagentFiles(subagentsDir);
   const named = subFiles.length ? subagentNames(filePath) : new Map();
+  const folded = [];
+  let unstamped = null;
   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);
+    const info = {};
+    const turns = parseSessionFile(file, true, agent, info);
     // 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);
+    folded.push({ key: path.relative(subagentsDir, file), firstTs: info.firstTs, turns });
+    // A subagent caught before its first line is written has no start time, so it ranks
+    // last — and when its first line lands with an EARLIER timestamp than a sibling's, it
+    // moves, renumbers every sibling after it, and the session forks and re-ships whole
+    // (GLM-F1). So a fresh one defers the whole session to the next pass, when it has a
+    // time. Bounded by age: a file that never gets a timestamped line stops deferring after
+    // SUBAGENT_STAMP_GRACE_MS and ranks last, as before.
+    if (info.firstTs === undefined && !unstamped) {
+      let age = Infinity;
+      try { age = Date.now() - fs.statSync(file).mtimeMs; } catch { /* gone: nothing to wait for */ }
+      if (age < SUBAGENT_STAMP_GRACE_MS) unstamped = path.relative(subagentsDir, file);
+    }
+  }
+  // Each subagent gets a SLOT, and the shipper numbers its rows from that slot rather than
+  // from where they happen to land in this array (see subagentSeq in ship.js). The slot is
+  // the subagent's rank by when it started — the timestamp on its transcript's first line —
+  // because that is the one order a new subagent cannot disturb: it started after every
+  // subagent already on disk, so it ranks last. The file-name order this used to fold in
+  // does not have that property: agent ids are random, so a new fork sorted into the middle
+  // and pushed every later subagent's rows down, and a session with subagents re-shipped
+  // whole on every pass (one 6,120-line session was stored 60 times in a day). A file with
+  // no timestamp yet ranks after every one that has one; the path breaks ties.
+  folded.sort((a, b) => (a.firstTs === undefined) - (b.firstTs === undefined)
+    || (a.firstTs || 0) - (b.firstTs || 0) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  folded.forEach(({ turns }, slot) => { for (const m of turns) m._agent.slot = slot; messages.push(...turns); });
+  if (unstamped) {
+    Object.defineProperty(messages, '_defer', { value: `subagent ${unstamped} has no timestamped line yet`, enumerable: false });
   }
 
   return messages;
 }
 
+/**
+ * When a session was last written, counting its subagents. The shipper's incremental skip
+ * compares `lastUpdatedAt` with what the house recorded, and a subagent writes only its own
+ * file: a background agent that runs on after its parent goes quiet left the parent's mtime
+ * (and the index's `modified`) where they were, so its turns shipped at the parent's next
+ * write, or never. Stat calls only, and only for a session that has a directory.
+ */
+function newestSubagentMtime(subagentsDir) {
+  let newest = 0;
+  for (const { file } of subagentFiles(subagentsDir)) {
+    try { newest = Math.max(newest, fs.statSync(file).mtimeMs); } catch { /* vanished mid-pass */ }
+  }
+  return Math.floor(newest);
+}
+function latest(a, b) { return b && (!a || b > a) ? b : a; }
+
 /**
  * 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.
+ * journal.jsonl and *.meta.json are bookkeeping, not transcripts. Sorted so the listing is
+ * deterministic; the fold ORDER is set by start time in getMessages, not by this.
+ * On real data the workflow layer held 100 of 165 forks and shipped none.
  */
 function subagentFiles(subagentsDir) {
   const out = [];

package/memhouse/DESIGN.md

@@ -134,8 +134,15 @@ Config file: `~/.memhouse/config.json` (`hiddenProjects`, future prefs).
 - Per-message `ts`: interpolated across the session's `[createdAt, lastUpdatedAt]`
   (adapters don't expose per-message timestamps; monotonic by `seq`; documented
   approximation, refine per-adapter later).
-- `seq` is the message index within the session (0-based). `tool_calls.idx` is the
-  call index within the session. `is_subagent` = message content begins with
+- `seq` is the message's place in the session. The session's own turns are dense from 0;
+  a folded subagent's turns are numbered from their own block,
+  `1,000,000,000 + slot × 100,000 + turn`, where `slot` is the subagent's rank by start
+  time. `tool_calls.idx` is laid out the same way (the session's own calls dense from 0,
+  a subagent's counted within its block). A row's key therefore never depends on how long
+  the parent or any other subagent is, which is what lets a session with subagents ship
+  tail-only; positional numbering moved every subagent row whenever the parent grew. A
+  parse that does not fit the blocks falls back to positional numbering. Readers order by
+  `seq` and count with `count()`; nothing may treat `seq` as dense. `is_subagent` = message content begins with
   `[subagent]` (the fold marker from the Claude adapter).
 - Incremental shipping: read existing `(session_id, last_updated_at, message_count)`
   (FINAL) and skip chats that haven't grown/changed; a full re-ship must remain

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.10",
+  "version": "0.18.11",
   "author": {
     "name": "Ramazan Polat"
   },

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

@@ -101,23 +101,35 @@ 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
+FROM messages FINAL
+WHERE session_id = '<sid>' AND user_id = '<uid>' AND is_subagent
+  AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+       WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+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
+SELECT seq, role, substring(text, 1, 2000) AS text FROM messages FINAL
+WHERE session_id = '<sid>' AND user_id = '<uid>' AND toString(extra.agent.id) = '<agent>'
+  AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+       WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+ORDER BY seq
 ```
 
+Both carry the current-epoch filter (trap 1 below). A session whose subagents were
+re-parsed holds every parse, so an unfiltered count doubles each subagent's turns, and an
+unfiltered transcript repeats them. `<uid>` is the session's `user_id`, from whatever
+query found it (trap 2).
+
 **`messages`** — one row per turn.
 
 | column | meaning |
 |---|---|
 | `session_id` | `<source>:<adapter-local id>`, e.g. `claude-code:6b1f…` |
-| `seq` | position in the session, from 0 |
+| `seq` | order within the session. The session's own turns are `0, 1, 2, …`; a subagent's turns sit in their own block, `1,000,000,000 + slot × 100,000 + turn` (slot = the subagent's rank by start time), so `seq` is **sparse** — count rows with `count()`, never `max(seq) + 1` |
 | `source` | editor: `claude-code`, `codex`, `cursor`, … |
-| `host` | the machine, `<hostname>-<8 hex>` — random per install, not derived |
+| `host` | the machine, `<hostname>-<8 hex>` — the 8 hex are derived from the OS machine id (random only where none can be read), so a reinstall keeps it and same-named machines differ |
 | `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. |
+| `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, each subagent's turns contiguous and the subagents in the order they started. 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** |

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

@@ -13,7 +13,7 @@ Two things that look alike and are not:
 - **Invite** mints a ClickHouse *user* and their own *house*. Needs an administrator.
 - **Share** grants an existing user `SELECT` on *your* house. You can do this yourself.
 
-**Read `../reference/HOUSE.md` first** for the connection block. One rule dominates
+**Read `../../reference/HOUSE.md` first** for the connection block. One rule dominates
 everything here: **a password must never enter this conversation.** memhouse ships this
 transcript into the house, and the archive is insert-only — a credential pasted here
 cannot be withdrawn.

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

@@ -12,7 +12,7 @@ A member owns a house, or rooms in one. An **administrator** owns the ClickHouse
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the traps every query
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the traps every query
 here inherits.
 
 **An admin password must never enter this conversation.** memhouse ships this transcript

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

@@ -11,7 +11,7 @@ allowed-tools: Bash
 **Invoking this IS the request. Run the report and present it; there is nothing to
 clarify.** Read-only throughout.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the epoch filter every
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the epoch filter every
 count below depends on.
 
 ## Nothing configured yet? Answer that instead

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

@@ -16,7 +16,7 @@ answer still exists.
 path — this skill retrieves rows and YOU read them. Never present a guess as a retrieval:
 if the house has nothing, say so.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the three traps
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the three traps
 (epoch filtering, `(session_id, user_id)` joins, escaping). Every query below assumes it.
 
 ## Which shape is being asked for
@@ -43,7 +43,8 @@ found 8 messages where `%clickhouse%` AND `%ttl%` found 1,461.
 ```sql
 SELECT session_id, user_id, any(folder) AS folder,
        formatDateTime(max(ts), '%Y-%m-%d') AS day, count() AS hits,
-       substring(anyIf(text, positionCaseInsensitive(text, 'NEEDLE') > 0), 1, 300) AS sample
+       min(seq) AS hit_seq,
+       substring(argMin(text, seq), 1, 300) AS sample
 FROM messages
 WHERE text_ngram LIKE '%needle%'
   AND (origin != 'ship'
@@ -55,8 +56,8 @@ ORDER BY hits DESC, max(ts) DESC
 LIMIT 8
 ```
 
-`anyIf(...)` so the sample is a line that actually matched — `any(text)` returns an
-arbitrary message from the session and misled two readers in three. **Order by `hits`,
+Every row counted here matched, so `sample` is a line that actually matched: the
+session's first hit, at `hit_seq`. Step 2 reads around that position. **Order by `hits`,
 not just recency**: a session mentioning the term 197 times outranks yesterday's passing
 reference.
 
@@ -64,15 +65,27 @@ reference.
 the match so you see the resolution, not the complaint:
 
 ```sql
-SELECT seq, role, substring(text, 1, 2000) AS text
-FROM messages
-WHERE session_id = '<sid>' AND user_id = '<uid>'
-  AND seq BETWEEN <hit_seq - 3> AND <hit_seq + 12>
+SELECT seq, role, is_subagent, substring(text, 1, 2000) AS text FROM (
+    (SELECT seq, role, is_subagent, text FROM messages FINAL
+     WHERE session_id = '<sid>' AND user_id = '<uid>' AND seq < <hit_seq>
+       AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+            WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+     ORDER BY seq DESC LIMIT 3)
+    UNION ALL
+    (SELECT seq, role, is_subagent, text FROM messages FINAL
+     WHERE session_id = '<sid>' AND user_id = '<uid>' AND seq >= <hit_seq>
+       AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+            WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+     ORDER BY seq LIMIT 13))
 ORDER BY seq
 ```
 
-Apply the epoch filter here too — an unfiltered read of a compacted session interleaves
-two parses of the same conversation.
+`<sid>`, `<uid>` and `<hit_seq>` come from step 1's row. The window is counted in rows,
+not in `seq` values: three turns before the hit and twelve after. `seq` has gaps. A
+subagent's turns are numbered in a block of their own, far above the parent's, so
+`seq BETWEEN hit_seq - 3 AND hit_seq + 12` could return the hit alone. The epoch filter
+keeps one parse: an unfiltered read of a compacted session interleaves two versions of
+the same conversation. `FINAL` collapses row versions the server has not merged yet.
 
 **3. Answer, then cite.** Lead with the answer. Under it list the sessions it came from —
 `session_id`, date, project — so the user can reopen one (`memhouse resume <session_id>`
@@ -95,13 +108,20 @@ one representative line each. Offer to read the strongest. Do not dump ten rows
 prefer it over hand-joining. For a plain list:
 
 ```sql
-SELECT session_id, name, source, host, project,
-       formatDateTime(started_at, '%Y-%m-%d %H:%i') AS started, message_count
-FROM sessions
-ORDER BY started_at DESC
+SELECT session_id, user_id, name, source, host, project,
+       formatDateTime(created_at, '%Y-%m-%d %H:%i') AS started,
+       formatDateTime(coalesce(last_updated_at, created_at), '%Y-%m-%d %H:%i') AS last_active,
+       message_count
+FROM sessions FINAL
+ORDER BY coalesce(last_updated_at, created_at) DESC
 LIMIT 20
 ```
 
+`sessions` keeps one row per session and the newest write wins, so read it `FINAL`.
+"Recent" means recently active (`last_updated_at`): a session started last month and
+worked on today is recent. The room has no `started_at`; `created_at` is when the
+session began.
+
 Narrow with `WHERE project = '…'`, `source = 'cursor'`, `host = '…'`, or a date range as
 asked. In a shared house every member's sessions are here — add `AND user_id = '<name>'`
 only when the user asks for one person's.

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

@@ -11,7 +11,7 @@ allowed-tools: Bash
 For **numbers**. When the answer is a passage from a past conversation, that is
 `/mem:recall` — this skill counts, groups and ranks.
 
-**Read `../reference/HOUSE.md` first.** Schema, connection, and the three traps. The epoch
+**Read `../../reference/HOUSE.md` first.** Schema, connection, and the three traps. The epoch
 filter in particular is not optional here: this is the skill most likely to produce a
 figure someone acts on, and omitting it over-counted a real house by **34%**.
 

package/memhouse/flags.js

@@ -75,4 +75,31 @@ function allowedFlags(cmd) {
   return new Set([...GLOBAL_FLAGS, ...known]);
 }
 
-module.exports = { GLOBAL_FLAGS, COMMAND_FLAGS, unknownFlags, allowedFlags, suggestFlag, editDistance };
+// Options that never take a value. The parser used to read `--x y` as x = "y" for every
+// option, so a switch swallowed the word after it: `update --no-install yes` set
+// no-install to "yes" (not true) and ran the npm install it was asked to skip, and
+// `share --revoke bob` revoked nobody. A switch is true when present, and the next word
+// stays a positional.
+const BOOLEAN_FLAGS = new Set([
+  'json', 'yes', 'help', 'version', 'full', 'check', 'migrate', 'no-install', 'all-origins',
+  'dry-run', 'print-sql', 'no-ship', 'keep-admin', 'ensure-schema', 'rotate-password', 'force',
+  'adopt', 'allow-local', 'local', 'down', 'credentials', 'full-removal', 'insecure-native',
+  'keep-shipper', 'guides', 'revoke', 'list', 'admin', 'install', 'all',
+]);
+
+/** argv (after the command) -> { flags, positional }. */
+function parseArgv(rest) {
+  const flags = {}; const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; }
+      else flags[key] = true;
+    } else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+module.exports = { GLOBAL_FLAGS, COMMAND_FLAGS, BOOLEAN_FLAGS, parseArgv, unknownFlags, allowedFlags, suggestFlag, editDistance };

package/memhouse/host.js

@@ -14,13 +14,18 @@
 //   * One machine splits. Rename the box and every row shipped afterwards lands under a
 //     new host, so the machine's own history appears to end and a stranger's to begin.
 //
-// A random fingerprint, written once and kept, fixes both: nothing derives it, so nothing
-// can collide with it, and nothing about the machine changing can move it.
+// So the fingerprint comes from the OS's own machine id (IOPlatformUUID, /etc/machine-id,
+// MachineGuid), hashed with a fixed salt (machineFingerprint), never from the hostname: two
+// machines cannot share it and a rename cannot move it. Since 0.18.6. Before that it was
+// random, which fixed both of the above but split a machine whenever MEMHOUSE_HOME was
+// wiped: a re-imaged laptop came back as a stranger. Where no machine id can be read it is
+// still random.
 //
-// It lives in MEMHOUSE_HOME and is deliberately NOT removed by a plain `memhouse
-// uninstall` — reinstalling on the same machine should continue that machine's history,
-// not start a second one beside it. `uninstall --full-removal` drops it, and then the
-// machine genuinely is a new host next time; that is the honest meaning of full removal.
+// It is written once to MEMHOUSE_HOME/host.json and an existing file always wins, so no
+// install changes identity under it. `uninstall --full-removal` drops the file, and the
+// next install derives the same fingerprint again from the same machine. The id also
+// carries the hostname the machine had at first install, so it comes back the same unless
+// the machine was renamed in between, or has no readable machine id.
 
 const fs = require('fs');
 const os = require('os');

package/memhouse/house/HOUSE.md

@@ -17,7 +17,7 @@ Two columns say where every row came from:
 | Column | Meaning | Comes from |
 |---|---|---|
 | `user_id` | who wrote it | `String MATERIALIZED currentUser()` — stamped by the server, unforgeable by clients. `async_insert = 0 CONST` is pinned on each user (`ADD SETTING`, which merges — a bare `SETTINGS` clause replaces the user's whole list) because an async flush stores the stamp as the empty string (measured on 25.11.9.34) |
-| `host` | which machine | the install's fingerprint (`../host.js`) — random, minted once, so two machines with the same hostname cannot collide and renaming one cannot split its history |
+| `host` | which machine | the machine's fingerprint (`../host.js`) — derived from the OS machine id (random only where none can be read), so two machines with the same hostname cannot collide and renaming one cannot split its history |
 
 `WHERE user_id = 'alice'` is one person. `WHERE host = 'macbook-4127a95b'` is one
 machine. No filter is the whole house — which is what a team dashboard wants.

package/memhouse/house/house.js

@@ -8,7 +8,7 @@
 //                                                  clients (async_insert is pinned to 0
 //                                                  on the user so the stamp cannot be
 //                                                  skipped)
-//   host     LowCardinality(String)              — the machine's fingerprint, minted once
+//   host     LowCardinality(String)              — the machine's fingerprint, derived from its OS machine id
 //                                                  per install (../host.js)
 //
 // That pair IS the provenance model.
@@ -412,6 +412,31 @@ function statRefreshStatements(rooms, at = 'now64(3)') {
     `INSERT INTO ${names[k]} SELECT ${at} AS refreshed_at, * FROM (${bodies[k].body})`);
 }
 
+/**
+ * When the shipper refreshes the stat tables (G11). After every pass that shipped something,
+ * as before — and ALSO when the newest generation is older than STATS_MAX_AGE_MS, even if
+ * nothing shipped. The tables carry a one-day TTL, so a house whose machines went quiet for
+ * a day used to lose every generation and the dashboard went empty while the rooms still
+ * held everything. `ageMs` null means "could not tell" (no table, no rights): do not refresh
+ * on age then; the read layer is already on the inline rollup.
+ */
+const STATS_MAX_AGE_MS = 60 * 60 * 1000;
+function statsNeedRefresh({ shipped, ageMs, maxAgeMs = STATS_MAX_AGE_MS }) {
+  if (shipped > 0) return true;
+  return ageMs !== null && ageMs !== undefined && ageMs > maxAgeMs;
+}
+
+/**
+ * How long a reader may keep its resolved rooms (G11). resolveRooms() decides once whether
+ * the stat tables are usable or the inline rollup must answer; a long-running dashboard that
+ * never asked again kept reading a stat table after its TTL had emptied it. Re-resolving
+ * every few minutes costs one small round trip and lets it follow the house either way.
+ */
+const ROOMS_TTL_MS = 5 * 60 * 1000;
+function roomsCacheStale(resolvedAt, now = Date.now(), ttlMs = ROOMS_TTL_MS) {
+  return !resolvedAt || now - resolvedAt > ttlMs;
+}
+
 /** 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}))`;
@@ -598,4 +623,5 @@ module.exports = {
   sessionsRollup, currentParse, createStatement, roomNames, currentUser, resolveRooms,
   SESSION_STATS, MODEL_STATS, TOOL_STATS, statTableNames, hasSessionStats, statTables,
   statCreateStatements, statRefreshStatements, latestGeneration,
+  STATS_MAX_AGE_MS, statsNeedRefresh, ROOMS_TTL_MS, roomsCacheStale,
 };

package/memhouse/invite-target.js

@@ -0,0 +1,37 @@
+// Where `invite` may send a credential — and the one place that decides it (G4).
+//
+// `--url` is the address the INVITEE will reach the house at. It goes into the invite file;
+// it is typed on a command line, so it can be a typo, a tunnel, or somebody else's server.
+// A credential this install KEEPS — the member's own, or an admin saved with --keep-admin —
+// belongs to the house it was saved for, and is only ever sent there. Before 0.18.11 the
+// stored credential was sent to `--url`: resolveConfig() lets the flag outrank the env file,
+// so `cfg.url` WAS `--url`, and the reachability probe, the grants read and the provisioning
+// all authenticated against whatever `--url` named.
+//
+// A credential given for THIS command — `--admin-user`, or an exported MEMHOUSE_ADMIN_USER,
+// with a password from a file, stdin, the environment or a prompt — was chosen by the person
+// who also typed `--url`, so it provisions there, as it always has.
+//
+// Pure, so it is unit tested.
+
+/**
+ * @param {object} o
+ * @param {string} o.url              the invitee-facing --url
+ * @param {string|null} o.storedUrl   the house this install is configured for (env or env file)
+ * @param {'flag'|'env'|'file'|'member'} o.adminUserSource
+ *        where the credential's USER came from: --admin-user, an exported MEMHOUSE_ADMIN_USER,
+ *        the env file's MEMHOUSE_ADMIN_USER, or (no admin at all) the member credential
+ * @param {string|null} [o.passwordSource]  resolveAdminPassword's `source` ('stored' = the env file)
+ * @returns {{ url: string, stored: boolean } | { error: string }}
+ */
+function provisionTarget({ url, storedUrl, adminUserSource, passwordSource = null }) {
+  const stored = adminUserSource === 'file' || adminUserSource === 'member' || passwordSource === 'stored';
+  if (!stored) return { url, stored: false };
+  if (!storedUrl) {
+    return { error: 'this install keeps no house URL to send its stored credential to — '
+      + 'give the admin for this command instead (--admin-user, password from MEMHOUSE_ADMIN_PASSWORD or --admin-password-file)' };
+  }
+  return { url: storedUrl, stored: true };
+}
+
+module.exports = { provisionTarget };

package/memhouse/server/queries.js

@@ -18,7 +18,7 @@
 
 const { createClient, ClickHouseLogLevel } = require('@clickhouse/client');
 const { calculateCost, normalizeModelName } = require('../../pricing');
-const { resolveRooms, READ_SETTINGS } = require('../house/house');
+const { resolveRooms, READ_SETTINGS, roomsCacheStale } = require('../house/house');
 
 const config = {
   url: process.env.MEMHOUSE_URL || 'http://localhost:8123',
@@ -90,11 +90,16 @@ const TZ = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
 // braces, no type.
 const ROOM_TOKEN = /\{\{([a-z_]+)\}\}/g;
 let roomsPromise = null;
+let roomsAt = 0;
 
 function rooms() {
-  // Resolved once per process. resolveRooms asks the server for currentUser(), so it is a
-  // round trip, and every dashboard request would otherwise pay for it.
-  if (!roomsPromise) {
+  // Cached, because resolveRooms asks the server for currentUser() and which stat tables
+  // are usable, and every dashboard request would otherwise pay that round trip. But not
+  // for the life of the process: whether the stat tables can answer changes — their TTL
+  // empties them on a quiet house, a refresh fills them again — and a dashboard that
+  // decided once kept reading an emptied table and showed nothing (G11).
+  if (!roomsPromise || roomsCacheStale(roomsAt)) {
+    roomsAt = Date.now();
     roomsPromise = resolveRooms(getClient()).catch((e) => { roomsPromise = null; throw e; });
   }
   return roomsPromise;