memhouse 0.20.0 → 0.20.1

package/docs/releases/v0.20.1.md

@@ -0,0 +1,114 @@
+# memhouse 0.20.1 — 2026-11-02
+
+A patch release on 0.20.0, with no schema change. Install it with `memhouse update`, or
+`npm install -g memhouse`.
+
+- **An invite's password expires.** It stops working 7 days after the invite unless it is
+  installed first. A file that sits unused, or that was read where it should not have been,
+  stops working on its own.
+- **Codex gets memhouse on request.** `memhouse plugins install codex` adds a short rules block
+  to Codex's `AGENTS.md` and a `memhouse` skill with the read recipes. `plugins remove codex`
+  takes out exactly those.
+- **Clearer answers from the CLI:**
+  - `memhouse <command> --help` prints that command's help;
+  - a refused credential is named before anything is written;
+  - `share --list` also shows the shares you received;
+  - `members` tells a share from a member's own tables;
+  - `discover` and `update` stop reporting problems that belong to nobody.
+- **A new minor version's first run says so,** and names the release notes to read.
+
+## Read this before upgrading
+
+Nothing in the house changes, and there is no migration. Three things behave differently:
+
+- **Inviting: the password now expires.** `memhouse invite` sets the expiry on the new account
+  using the server's clock. The default is 7 days; `--expires <days>` takes 1 to 365. The
+  output, the invite file and `MEMHOUSE-INVITATION.md` all give the date. An invitee who
+  installs after that date is refused with "this invite expired at … ask whoever invited you
+  for a new one". To invite them again under the same name, remove the unused account first
+  with `DROP USER <name>`, as the administrator; their tables are kept and reused. Invites
+  made by 0.20.0 or earlier carry no expiry and keep working as before.
+- **The first command after moving to a new minor version prints one line** to stderr. It
+  names the version it replaces and the release notes. Patch releases, downgrades and fresh
+  installs print nothing.
+- **Codex is opt-in.** Nothing is written under `~/.codex` (or `CODEX_HOME`) unless you run
+  `memhouse plugins install codex`.
+
+```bash
+memhouse update        # then: memhouse status — every line a check mark
+```
+
+## Invites
+
+- **The expiry is set by the server**, as `VALID UNTIL` on the new account, so it holds no
+  matter what the file says. `install --env` also checks the date in the file and refuses
+  before contacting the server.
+- **Installing lifts it.** A password change removes the expiry, and so does
+  `--keep-password`, which keeps the invited password.
+- **`invite --print-sql`** prints the same `ALTER USER … VALID UNTIL` statement for an
+  administrator who runs the plan by hand. The date is left as a placeholder, so the
+  statement does not parse until a real date is put in.
+- **Re-inviting an unused name** used to fail with the install message, "give their
+  password". It now says the invite was never installed, gives its expiry, and names the
+  remedy.
+
+## Codex
+
+Codex puts `AGENTS.md` into every prompt and lists each skill by its name and description,
+reading the body only when the skill is used. memhouse uses both, and only when asked:
+
+- **The block** in `AGENTS.md` holds what must always apply:
+  - never read or print the env file or a `MEMHOUSE_*` value;
+  - `MEMHOUSE_URL` is the house and `MEMHOUSE_PORT` the dashboard;
+  - questions about past sessions go to the skill.
+
+  It sits between `<!-- memhouse:begin … -->` and `<!-- memhouse:end -->` markers. A reinstall
+  replaces it where it stands. Remove takes it out and leaves the rest of the file
+  byte-identical. A file that held only the block is deleted, unless it is a symlink: then its
+  target is emptied and the link kept.
+- **The skill**, `skills/memhouse/`, carries the read recipes:
+  - `memhouse q` for search, sessions, activity by hour, spend, models, tools and machines;
+  - `--member` for a housemate's shared sessions;
+  - `memhouse room-sql` for anything else.
+
+  It is memhouse's only if it holds `.memhouse.json`. A `skills/memhouse` without that file is
+  never replaced or removed.
+- **An instance with its own home or binary** is named in both, as `MEMHOUSE_HOME=<home>
+  <binary>`.
+- **After an upgrade,** the first command refreshes an installed copy, as it does the `/mem`
+  copies. A block you took out by hand stays out.
+- **The `/mem` skills are still for Claude Code.**
+
+## Smaller changes
+
+- **`memhouse <command> --help`** prints that command's entry. A command with no entry of its
+  own still gets the whole page. `memhouse q --help` lists the named queries.
+- **A refused credential is named up front.** When ClickHouse refuses the credential (code
+  516, or 194 for a missing password), `install`, `invite` and `deploy --local` stop before
+  writing anything, with "could not authenticate as '<user>' at <url>".
+- **`share --list` also lists the shares you received,** with the command that reads each
+  one. `--json` adds `received`.
+- **`members` tells a share from a member's own tables:**
+  - own tables;
+  - each member whose sessions this account reads, scoped or full;
+  - any other grant.
+
+  `--json` adds `own`, `shares` and `other`.
+- **`discover`** shows an unreachable `http://localhost:8123` as a plain line when nothing is
+  configured to use it, instead of a ✗.
+- **`update` on a machine with no member install** (an administrator's machine) skips the
+  schema heal and migration check, instead of printing the default member's authentication
+  failures.
+- **`doctor`** names the release channel when it says a release is the latest. Offline, it no
+  longer says the install is current.
+- **Dashboard:** a browser that refuses sessionStorage keeps the access token in memory for
+  that page load, instead of showing the "open it with `memhouse dashboard`" page.
+- **/mem skills:** the schema-2 raw-SQL recipe runs `memhouse room-sql <<'SQL'` directly. It
+  used to wrap the call in a shell function, so every call asked for approval.
+
+## Deprecated
+
+Unchanged from 0.20.0: passwords on the command line (`--password`, `--member-password`,
+`--to-password`), and `MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` as the admin for `migrate --v3-*`,
+still work with a warning and are refused from the next minor release. See
+[0.20.0's Deprecated](v0.20.0.md#deprecated).

package/memhouse/codex-plugin.js

@@ -0,0 +1,194 @@
+// `memhouse plugins install codex`: what Codex reads of memhouse, and only on request.
+//
+// Codex (0.165, checked against the request it sends) puts <codex home>/AGENTS.md into every
+// prompt in full, and lists each skill under <codex home>/skills by its name and description,
+// reading the body only when the skill is used. So the rules that must hold in every session go
+// in a short block in AGENTS.md, and the read recipes in one skill, skills/memhouse.
+//
+// The block is marker-delimited. Install puts it at the top of the file, followed by one blank
+// line, or creates the file with the block alone; a reinstall replaces it where it stands. Remove
+// takes out the block and that one line, so the rest of the file is what it was, byte for byte;
+// a file left empty is deleted, unless it is a symlink: then the target is emptied through it and
+// the link stays. The skill directory carries an ownership file (OWNER_FILE): a
+// skills/memhouse without it is somebody else's and is never replaced or removed.
+//
+// Nothing here writes under the Codex home except install, remove, and the refresh of a copy
+// that install already put there (plugin-copies.js).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL = 'memhouse';
+const OWNER_FILE = '.memhouse.json';
+const BEGIN = '<!-- memhouse:begin';
+const END = '<!-- memhouse:end -->';
+const MARKERS = /^<!-- memhouse:(begin|end)\b[^\n]*$/gm;
+
+/** The Codex home: CODEX_HOME when set, else ~/.codex. */
+function codexHome(env = process.env) {
+  return env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+const agentsFile = (cx) => path.join(cx, 'AGENTS.md');
+const skillDir = (cx) => path.join(cx, 'skills', SKILL);
+const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+/**
+ * Where the block sits in `text`: { start, end, version }, or null when there is none.
+ * Throws when the markers do not make exactly one block, so nothing is written over a file
+ * whose block was damaged by hand.
+ */
+function findBlock(text) {
+  const begins = []; const ends = [];
+  let m;
+  MARKERS.lastIndex = 0;
+  while ((m = MARKERS.exec(text))) (m[1] === 'begin' ? begins : ends).push(m.index);
+  if (!begins.length && !ends.length) return null;
+  if (begins.length !== 1 || ends.length !== 1 || ends[0] < begins[0]) {
+    throw new Error(`AGENTS.md holds ${begins.length} memhouse:begin and ${ends.length} memhouse:end markers, not one block — fix it by hand; nothing was changed`);
+  }
+  const nl = text.indexOf('\n', ends[0]);
+  const version = (/^<!-- memhouse:begin (\d+\.\d+\.\d+\S*)/.exec(text.slice(begins[0])) || [])[1] || null;
+  return { start: begins[0], end: nl === -1 ? text.length : nl + 1, version };
+}
+
+/** `text` with `block` in it: replaced where it stands, or put first with one blank line after. */
+function withBlock(text, block) {
+  const b = findBlock(text);
+  if (b) return text.slice(0, b.start) + block + text.slice(b.end);
+  return text ? `${block}\n${text}` : block;
+}
+
+/** `text` without the block, and without the blank line install put after it. */
+function withoutBlock(text) {
+  const b = findBlock(text);
+  if (!b) return text;
+  let rest = text.slice(b.end);
+  if (b.start === 0 && rest.startsWith('\n')) rest = rest.slice(1);
+  return text.slice(0, b.start) + rest;
+}
+
+/** A path for the text, with the home directory as ~. */
+function shown(p) {
+  const h = os.homedir();
+  return p === h || p.startsWith(h + path.sep) ? `~${p.slice(h.length)}` : p;
+}
+
+/** A shell word: as is when it needs no quoting, else single-quoted. */
+function shArg(s) {
+  return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/** The `memhouse` on PATH, resolved, or null. */
+function memhouseOnPath(env = process.env) {
+  for (const d of String(env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    const f = path.join(d, 'memhouse');
+    try { fs.accessSync(f, fs.constants.X_OK); return real(f); } catch { /* not here */ }
+  }
+  return null;
+}
+
+/**
+ * How the block and the skill name the command: `memhouse` for the default instance, else with
+ * MEMHOUSE_HOME and the binary spelled out, each only where it differs from the default.
+ */
+function invocation({ home, bin, defaultHome = path.join(os.homedir(), '.memhouse'), pathBin = memhouseOnPath() }) {
+  const parts = [];
+  if (home && real(home) !== real(defaultHome)) parts.push(`MEMHOUSE_HOME=${shArg(shown(home))}`);
+  parts.push(!bin || (pathBin && real(bin) === pathBin) ? 'memhouse' : shArg(shown(bin)));
+  return parts.join(' ');
+}
+
+function render(tpl, { mh, envFile }) {
+  return tpl.replace(/\{\{MH\}\}/g, mh).replace(/\{\{ENV_FILE\}\}/g, envFile);
+}
+
+function renderBlock({ deliveryDir, version, mh, envFile }) {
+  const body = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'AGENTS-BLOCK.md'), 'utf-8'), { mh, envFile }).trim();
+  return `${BEGIN} ${version} — managed by \`memhouse plugins install codex\`; \`memhouse plugins remove codex\` takes it out -->\n${body}\n${END}\n`;
+}
+
+/** The skill directory's ownership record, or null when it is not memhouse's (or absent). */
+function readOwner(dir) {
+  try {
+    const o = JSON.parse(fs.readFileSync(path.join(dir, OWNER_FILE), 'utf-8'));
+    return o && o.owner === 'memhouse' ? o : null;
+  } catch { return null; }
+}
+
+/**
+ * Write the block and the skill. Everything is checked before anything is written: a foreign
+ * skills/memhouse or a damaged block throws with the Codex home untouched.
+ * `onlyWhereInstalled`: the refresh — the block is rewritten only where it already is.
+ * @returns {{ file: string, created: boolean, block: boolean, dir: string, mh: string }}
+ */
+function install({ codexHome: cx, home, bin, version, deliveryDir, pathBin, onlyWhereInstalled = false }) {
+  const dir = skillDir(cx);
+  if (fs.existsSync(dir) && !readOwner(dir)) {
+    throw new Error(`${shown(dir)} is not memhouse's (it has no ${OWNER_FILE}) — not replacing it; move it aside and install again`);
+  }
+  const file = agentsFile(cx);
+  let text = null;
+  try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const mh = invocation({ home, bin, ...(pathBin !== undefined ? { pathBin } : {}) });
+  const envFile = shown(path.join(home, 'env'));
+  const writeBlock = !onlyWhereInstalled || (text !== null && findBlock(text) !== null);
+  const next = writeBlock ? withBlock(text || '', renderBlock({ deliveryDir, version, mh, envFile })) : text;
+  const skill = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'SKILL.md'), 'utf-8'), { mh, envFile });
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'SKILL.md'), skill);
+  fs.writeFileSync(path.join(dir, OWNER_FILE), `${JSON.stringify({ owner: 'memhouse', version, home, bin: bin || null }, null, 2)}\n`);
+  // In place, not a rename: an AGENTS.md that is a symlink (a dotfiles checkout) stays one.
+  if (writeBlock && next !== text) fs.writeFileSync(file, next);
+  return { file, created: text === null && writeBlock, block: writeBlock, dir, mh };
+}
+
+/**
+ * Take out the block and the skill — the skill only when it is memhouse's.
+ * @returns {{ block: boolean, fileDeleted: boolean, emptiedLink: boolean, skill: boolean, foreignSkill: string|null }}
+ */
+function remove({ codexHome: cx }) {
+  const res = { block: false, fileDeleted: false, emptiedLink: false, skill: false, foreignSkill: null };
+  const file = agentsFile(cx);
+  let text = null;
+  try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const next = text !== null && findBlock(text) ? withoutBlock(text) : null;
+  const dir = skillDir(cx);
+  const owned = !!readOwner(dir);
+  if (!owned && fs.existsSync(dir)) res.foreignSkill = dir;
+  if (next !== null) {
+    // Only a regular file is unlinked. Unlinking a symlink (a dotfiles checkout) would leave the
+    // block in its target, so the target is written through the link instead.
+    if (next === '' && !fs.lstatSync(file).isSymbolicLink()) { fs.rmSync(file); res.fileDeleted = true; }
+    else { fs.writeFileSync(file, next); res.emptiedLink = next === ''; }
+    res.block = true;
+  }
+  if (owned) { fs.rmSync(dir, { recursive: true }); res.skill = true; }
+  return res;
+}
+
+/** What is installed: the skill's owner record (or why not), and whether the block is there. */
+function status({ codexHome: cx }) {
+  const dir = skillDir(cx);
+  const owner = readOwner(dir);
+  let block = null; let damaged = null;
+  try { block = findBlock(fs.readFileSync(agentsFile(cx), 'utf-8')); } catch (e) { if (e.code !== 'ENOENT') damaged = e.message; }
+  return { codexHome: cx, installed: !!owner, owner, foreignSkill: !owner && fs.existsSync(dir) ? dir : null, block: !!block, blockVersion: block ? block.version : null, damaged };
+}
+
+/**
+ * The copy to refresh for `version`, or null: installed, memhouse's, bound to `home`, and older.
+ */
+function staleCopy({ codexHome: cx, home, version, compareVersions }) {
+  const owner = readOwner(skillDir(cx));
+  if (!owner || !owner.home || real(owner.home) !== real(home)) return null;
+  const c = compareVersions(owner.version, version);
+  return c === -1 || c === null ? { codexHome: cx, have: owner.version || null, home: owner.home, bin: owner.bin || null } : null;
+}
+
+module.exports = {
+  SKILL, OWNER_FILE, BEGIN, END, codexHome, agentsFile, skillDir, findBlock, withBlock, withoutBlock,
+  invocation, memhouseOnPath, renderBlock, readOwner, install, remove, status, staleCopy, shown,
+};

package/memhouse/delivery/INVITATION.md.tpl

@@ -46,7 +46,7 @@ them exist because an agent broke them:
 
 ## 0. Find your credential
 
-The install needs `{{FILE}}`, the file delivered with this page. Confirm it is here first —
+{{EXPIRY}}The install needs `{{FILE}}`, the file delivered with this page. Confirm it is here first —
 run this from the directory this page is in now, and if it prints the filename you are ready:
 
 ```

package/memhouse/delivery/codex/AGENTS-BLOCK.md

@@ -0,0 +1,11 @@
+## memhouse: past agent sessions
+
+This machine's agent sessions (Codex, Claude Code and other editors) are kept in a memhouse
+house. For a question about earlier work (what was done, when, in which hours, what it cost,
+how something was fixed), use the `memhouse` skill before saying you do not know.
+
+- Never read, print or echo `{{ENV_FILE}}`, and never print a `MEMHOUSE_*` value: they hold the
+  house's password, and this conversation may be shipped into the house. `{{MH}}` reads its
+  own configuration.
+- `MEMHOUSE_URL` is the house (ClickHouse). `MEMHOUSE_PORT` is the local dashboard's port, not
+  the house's.

package/memhouse/delivery/codex/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: memhouse
+description: "Answer from past agent sessions kept in memhouse (Codex, Claude Code and other editors): what was worked on and when, which hours or days, spend and models, tools used, how something was fixed, a past session's transcript, a housemate's shared sessions. Read-only memhouse commands. Use before saying you do not know about earlier work."
+---
+
+# memhouse: read past sessions
+
+Every command here only reads. `{{MH}}` reads its own configuration: never read or print
+`{{ENV_FILE}}` or any `MEMHOUSE_*` value.
+
+Start with `{{MH}} q schema`. The recipes below are for schema 3. On 2 (a house still on the
+0.18 rooms), `{{MH}} prompt` prints the recipes for it.
+
+## Named queries
+
+`{{MH}} q <name> --json` prints one JSON object. A session is `<harness>:<session_id>`, the
+`ref` every result carries.
+
+- Sessions about a topic (every term in one message; a "quoted phrase" as written):
+  `{{MH}} q search clickhouse "authentication failed" --json`
+- Around a hit: `{{MH}} q window <ref> --at <message_id> --json`. A whole session:
+  `{{MH}} q session <ref> --json`, paged with `--cursor`.
+- Recent sessions: `{{MH}} q recent --limit 20 --since 7d --json`
+- Which hours or days: `{{MH}} q activity --by hour --grain usage --tz <IANA zone> --json`
+  counts messages and tokens by the hour they happened; `--by day`, `--by dow`, `--by day,host`.
+- Spend and models: `{{MH}} q spend --by model --since 30d --json`, `{{MH}} q models --json`
+- Tools: `{{MH}} q tools --limit 25 --json`; one tool's calls: `{{MH}} q tool <name> --json`
+- Machines: `{{MH}} q hosts --json`. What the house holds: `{{MH}} q coverage --json`
+- Filters on most names: `--harness`, `--project`, `--folder`, `--host`, `--since`, `--until`.
+  `{{MH}} q` lists every name and flag.
+
+## A housemate's sessions
+
+Add `--member <name>` to a named query to read sessions a housemate shared with you.
+`{{MH}} share --list` names who shared with you. An empty result means nothing is visible,
+not that nothing happened.
+
+## Raw SQL, when no named query fits
+
+`{{MH}} room-sql "<SELECT …>"` runs one read-only statement. The bare names `sessions`,
+`session_parts`, `session_usage` and `calls` resolve to your tables (`--member <name>` for a
+housemate's). Read them `FINAL` with `is_deleted = 0 AND removed = 0`; a session is
+`(host, harness, harness_path, session_id, incarnation)`; take totals from `sessions`, never by
+summing parts or usage.
+
+## Answering
+
+Answer from what the commands return, cite the `ref` of each session used, and say so when a
+search finds nothing. `{{MH}} resume <ref>` prints the command that reopens a session. Cost is
+derived from token counts: an unpriced model is unknown, not free.

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

@@ -20,8 +20,8 @@ memhouse q schema      # prints 3 or 2
 - **3** — the house holds harness-sessions-sql's profile tables (`sessions`, `session_parts`,
   `session_usage`, `calls`; memhouse 0.20). Read
   [Schema 3](#schema-3--harness-sessions-sqls-profile) below and use **`memhouse q`**; nothing about
-  epochs, `seq` or the `q()` rewrite applies. Skip everything from "Connect" on unless you
-  need raw SQL, and then use `memhouse room-sql`, not `q()`.
+  epochs, `seq` or the 0.18 rooms' name rewrite applies. Skip everything from "Connect" on
+  unless you need raw SQL, and then use `memhouse room-sql`.
 - **2** — the 0.18 rooms (`messages`, `tool_calls`, `sessions`). Everything from
   "What this is" on is for you, unchanged.
 
@@ -161,8 +161,8 @@ Every member's rooms are named for them — `mem.alice_messages`, `mem.alice_ses
 `mem.alice_tool_calls` — and one grant covers exactly those: `ON mem.alice_*`. Housemates
 keep their own rooms beside yours and cannot read them, list them, or grant them onward;
 you cannot read theirs. `SHOW GRANTS` shows you the one line you hold. **A bare
-`FROM messages` names nothing you have** — the `q()` below prefixes room names with your
-member name for you, and `memhouse rooms` prints what yours are called.
+`FROM messages` names nothing you have** — `memhouse room-sql` (below) prefixes room names
+with your member name for you, and `memhouse rooms` prints what yours are called.
 
 An **operator** owns the ClickHouse itself; an **admin credential** is what proves it.
 `memhouse whoami` says which you are holding.
@@ -189,13 +189,11 @@ instances on two channels; the top of this file says when to use it instead of p
 Credentials resolve **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`** (default
 `~/.memhouse/env`), and the CLI does that itself: you never source the file, and the
 password never appears in a command. Every read goes through `memhouse room-sql`, with the
-SQL on stdin:
+SQL on stdin. Run it as written, not through a shell function: the skills pre-approve
+`memhouse room-sql`, and a wrapper would ask for approval every time.
 
 ```bash
-q() {  # read-only by construction; every read path uses this
-  memhouse room-sql "$@"
-}
-q <<'SQL'
+memhouse room-sql <<'SQL'
 SELECT 1 FORMAT PrettyCompact
 SQL
 ```

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

@@ -116,7 +116,7 @@ each one:
 memhouse share <user>                          everything you own
 memhouse share <user> --only project=memhouse  just one project
 memhouse share <user> --only session=<id>      just one conversation
-memhouse share --list                          who can read it, and how much
+memhouse share --list                          who can read it, how much, and whose you can read
 memhouse share <user> --revoke                 withdraw
 ```
 

package/memhouse/flags.js

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

package/memhouse/help.js

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

package/memhouse/house/schema-choice.js

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

package/memhouse/invitation.js

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

package/memhouse/plugin-copies.js

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

package/memhouse/release-hint.js

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

package/memhouse/share.js

@@ -716,5 +716,35 @@ function parseShareRecord(value) {
   return m ? { granted: true, scopeRaw: m[1] ? m[1].trim() : null } : { granted: false, scopeRaw: null };
 }
 
+/**
+ * One account's grants from membersAccess, told apart for a reader: its own tables, the tables
+ * of each member it reads (a share), and anything else (a hand-made grant, a wildcard reaching
+ * past its own name). A table belongs to the member whose name is left after the longest
+ * memhouse table name (MEMBER_TABLES) is taken off its end. `policies` are the row policies the
+ * reading credential can list ([{ short_name, table }]); null when it cannot, and then a share's
+ * scope is unknown.
+ * @returns {{ own: string[], shares: {from:string, tables:string[], scoped:boolean|null}[], other: string[] }}
+ */
+function describeAccess({ u, list }, { policies = null } = {}) {
+  const own = []; const other = []; const shared = new Map();
+  for (const label of list || []) {
+    const bare = String(label).replace(/ \(through role [^)]*\)$/, '');
+    const name = bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare;
+    if (name === `${u}_*` || name === `${u}_`) { own.push(label); continue; }
+    const type = [...MEMBER_TABLES, 'session_units', 'session_sources'].filter((t) => name.endsWith(`_${t}`) && name.length > t.length + 1).sort((a, b) => b.length - a.length)[0];
+    const owner = type ? name.slice(0, -(type.length + 1)) : null;
+    if (owner === u) own.push(label);
+    else if (owner && !bare.includes('.') && V3_TABLES.concat(LEGACY_ROOMS).includes(type)) {
+      if (!shared.has(owner)) shared.set(owner, []);
+      shared.get(owner).push(label);
+    } else other.push(label);
+  }
+  const shares = [...shared.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([from, tables]) => ({
+    from, tables,
+    scoped: policies ? policies.some((p) => String(p.short_name).startsWith(`mh_share_${u}_`) && String(p.table).startsWith(`${from}_`)) : null,
+  }));
+  return { own, shares, other };
+}
+
 module.exports = { SCOPE_COLUMNS, parseScope, scopePredicate, policyName, V3_TABLES, scopePredicateV3, shareV3Plan, revokeV3Plan, parseShareRecord,
-  assertName, ident, qual, memberTargets, moveSharePlan, wildcardRevoke, memberCollisions, wildcardOnRevoke, holdsMemberGrant, collidingUsers, ownPolicies, showPoliciesRevokes, wildcardReachText, wildcardAdminLine, shareGate, selectTargets, rolesGranted, reachThroughRoles, revokeRoleReport, revokeCheck, classifyShare, legacyPolicyDrops, readLiveShares, membersGrantsSQL, MEMBERS_ROLE_GRANTS_SQL, membersAccess, roleDifferences, LEGACY_ROOMS };
+  assertName, ident, qual, memberTargets, moveSharePlan, wildcardRevoke, memberCollisions, wildcardOnRevoke, holdsMemberGrant, collidingUsers, ownPolicies, showPoliciesRevokes, wildcardReachText, wildcardAdminLine, shareGate, selectTargets, rolesGranted, reachThroughRoles, revokeRoleReport, revokeCheck, classifyShare, legacyPolicyDrops, readLiveShares, membersGrantsSQL, MEMBERS_ROLE_GRANTS_SQL, membersAccess, describeAccess, roleDifferences, LEGACY_ROOMS };