memhouse 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -4,6 +4,66 @@ Versions before 0.8.0 were beta-only. Beta installs of 0.7.x and earlier should
 uninstall and reinstall — the 0.8.0 layout is new, and an in-place `update` +
 migration path is planned work, not a promise the old versions can cash.
 
+## 0.20.1 — 2026-11-02
+
+Release notes: [`docs/releases/v0.20.1.md`](docs/releases/v0.20.1.md).
+
+- **Dashboard: a browser that refuses sessionStorage still opens it.** The page keeps the token
+  in memory for that load when sessionStorage is refused; it used to show the "open it with
+  `memhouse dashboard`" page instead.
+- **doctor names the channel when it says a release is the latest.** An unpriced model's hint now
+  says "the latest release on '<channel>'", so an install pinned to another line is not told it
+  is on the newest release overall. Offline, the hint no longer claims the install is current.
+- **/mem skills: the raw-SQL recipe runs `memhouse room-sql` as written.** The reference's
+  schema-2 recipe wrapped it in a `q()` shell function, so every call asked for approval despite
+  the skills' pre-approval. It now runs `memhouse room-sql <<'SQL'` directly.
+- **install, invite and `deploy --local` name a refused credential up front.** When the server
+  refuses the credential (ClickHouse code 516, or 194 for a missing password), they now stop
+  before writing anything with "could not authenticate as '<user>' at <url>", instead of reading
+  the house as new and failing at the next step. Code 194 counts as an authentication failure
+  everywhere 516 does.
+- **`memhouse <command> --help` prints that command's help.** It used to print the whole page
+  for every command. A command with no entry of its own still gets the whole page, and
+  `memhouse q --help` lists the named queries (the same as `memhouse q list`).
+- **`memhouse share --list` also lists the shares you received.** Beside who reads your
+  sessions, it names each member whose sessions this credential can read, with the command
+  that reads them (`memhouse q recent --member <them>`); `--json` adds `received`. An
+  administrator is told it reads every member's sessions instead.
+- **`memhouse discover` flags an unreachable house only when it is this install's.** The
+  default local address (`http://localhost:8123`) is probed as a discovery; when nothing
+  answers there and nothing is configured to use it, it is a plain line, not a ✗. `--json`
+  marks each endpoint `configured`.
+- **`memhouse update` on a machine with no member install checks no house.** An
+  administrator's machine (only `MEMHOUSE_URL` and the admin variables) used to run the schema
+  heal and the migration check as the default member and print its authentication failures as
+  the house's state. It now says there is no member install here and skips those steps.
+- **`memhouse members` tells a share from a member's own tables.** Each account's line names its
+  own tables, then each member whose sessions it reads ("reads alice's sessions (a share,
+  scoped)" or "full", where the row policies can be listed), then any other grant, which
+  memhouse does not make itself. A scoped share used to read as a plain list of another
+  member's tables. `--json` adds `own`, `shares` and `other`.
+- **A new minor version's first run says so.** The first CLI call of a newer major.minor on a
+  machine prints one line to stderr, naming the version it replaces and the shipped release
+  notes to read. Patch releases, downgrades and fresh installs say nothing; a stamp in the
+  memhouse home (`version-seen`) records the last version that ran. An install from before the
+  stamp is read from its home: a 0.18 install moving to 0.20.1 is told "it ran 0.18 or
+  earlier".
+- **`memhouse plugins install codex`.** Codex gets a short, marker-delimited block in its
+  `AGENTS.md` (never read or print the env file or a `MEMHOUSE_*` value; `MEMHOUSE_URL` is the
+  house, `MEMHOUSE_PORT` the dashboard; past sessions go to the skill) and a `memhouse` skill with
+  the read recipes, under `CODEX_HOME` or `~/.codex`. `plugins remove codex` takes out exactly
+  those: the rest of `AGENTS.md` stays byte-identical, and a `skills/memhouse` that memhouse did
+  not install is left alone. Opt-in: nothing is written there unless it ran; the first run of a
+  new version refreshes a copy it finds installed. The `/mem` skills stay Claude Code's.
+- **An invite's password expires.** `memhouse invite` sets the new member's password to stop
+  working after 7 days (`--expires <days>`, 1 to 365), by the server's clock. The invite's
+  output, the invite file and `MEMHOUSE-INVITATION.md` say when. `install --env` lifts the
+  expiry when it changes the password, and when `--keep-password` keeps it. An expired invite
+  is refused at install with "this invite expired at … ask whoever invited you for a new one",
+  before anything is contacted or written. Inviting the same name again says the unused
+  account must be removed first (`DROP USER <name>`); its tables are kept and reused.
+  `invite --print-sql` prints the same expiry, with a placeholder for the date.
+
 ## 0.20.0 — 2026-10-29
 
 Release notes: [`docs/releases/v0.20.0.md`](docs/releases/v0.20.0.md). Read its "Read this

package/bin/memhouse.js

@@ -39,6 +39,8 @@ const dashPort = require(path.join(REPO_ROOT, 'memhouse', 'server', 'dashboard-p
 const HOME_DIR = process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse');
 const ENV_FILE = path.join(HOME_DIR, 'env');
 const RUN_DIR = path.join(HOME_DIR, 'run');
+// How long an invite's password works unless --expires says otherwise.
+const INVITE_DAYS = 7;
 const LOG_DIR = path.join(HOME_DIR, 'logs');
 
 // ── args ────────────────────────────────────────────────────────────────────────
@@ -91,6 +93,14 @@ try {
   process.exit(2);
 }
 
+// A new minor version's first run here says so, once, with its release notes
+// (memhouse/version-notice.js). stderr only, like the skills refresh below. It runs first: it reads
+// the version that refresh records (skills-checked) before the refresh moves it.
+require(path.join(REPO_ROOT, 'memhouse', 'version-notice')).checkVersionNotice({
+  home: process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse'),
+  version: require(path.join(REPO_ROOT, 'package.json')).version, repoRoot: REPO_ROOT,
+  log: (l) => console.error(`memhouse: ${l.replace(os.homedir(), '~')}`),
+});
 // A new version's first run refreshes the /mem skills bound to this home (an npm upgrade does
 // not run `update`, which used to be the only refresh). After that, one stamp read per call.
 // stderr only, so --json output stays clean. memhouse/plugin-copies.js.
@@ -622,7 +632,9 @@ Setup        onboard              interactive wizard: discover → configure →
                                   and one grant on exactly those. Refuses a name whose rooms
                                   already hold messages; --adopt takes them over (same
                                   person, new credential). Not an admin? --print-sql prints
-                                  the plan to hand to whoever is.
+                                  the plan to hand to whoever is. The invited password
+                                  expires after --expires DAYS (default 7); install's
+                                  password change lifts it
              passwd               rotate this member's password + rewrite the env file
                                   (admin-assisted: --admin-user, password as for install)
              setup                (re)write the connection config only (--yes = no prompts)
@@ -686,6 +698,9 @@ Agents       plugins              list | install claude [--target DIR] | remove
                                   acts on EVERY Claude config dir found (~/.claude,
                                   CLAUDE_CONFIG_DIR, ~/.claude-playbooks/*), all
                                   selected by default; --yes takes them all unasked
+             plugins install codex  Codex: a block in AGENTS.md (the rules) and a
+                                  memhouse skill (the read recipes), under CODEX_HOME or
+                                  ~/.codex; plugins remove codex takes out exactly those
              prompt               print the memory system-prompt snippet
              prompt --install     print an install prompt for an agent, with this
                                   machine's state and the one route that applies
@@ -757,8 +772,13 @@ async function cmdDiscover() {
     out.adapterErrors = getAdapterErrors();
   } catch (e) { out.editorsError = e.message; }
 
-  for (const url of [...new Set([resolveConfig().url, 'http://localhost:8123'])]) {
-    const probe = { url, reachable: false };
+  // The configured house, and the default local address as a discovery. An unreachable local
+  // address that nothing is configured to use is not a failure: it was flagged ✗ on machines
+  // whose house is elsewhere, and read as something to fix.
+  const stated = resolveConfig();
+  const configuredUrl = stated.stated ? stated.url : null;
+  for (const url of [...new Set([...(configuredUrl ? [configuredUrl] : []), 'http://localhost:8123'])]) {
+    const probe = { url, reachable: false, configured: url === configuredUrl };
     try {
       const res = await fetch(url.replace(/\/$/, '') + '/ping', { signal: AbortSignal.timeout(3000) });
       probe.reachable = res.ok;
@@ -791,7 +811,7 @@ async function cmdDiscover() {
   printAdapterErrors(out.adapterErrors);
   console.log('\nClickHouse endpoints:');
   for (const p of out.clickhouse) {
-    if (!p.reachable) console.log(bad(`${p.url} — unreachable`));
+    if (!p.reachable) console.log(p.configured ? bad(`${p.url} — unreachable (this install's house)`) : `  · ${p.url} — no ClickHouse answers here; nothing is configured to use it`);
     else if (p.auth) console.log(warn(`${p.url} — reachable, credentials needed`));
     else console.log(ok(`${p.url} — v${p.version}${p.hasHouse ? ', house present' : ''}${p.kernel ? ', KERNEL detected' : ''}`));
   }
@@ -1024,7 +1044,7 @@ function handoffLines({ url, db, member, invite }) {
     `--   MEMHOUSE_DB='${db}'`,
   ];
   if (isV3(resolveConfig())) lines.push('--   MEMHOUSE_SCHEMA=3');
-  if (invite) lines.push('--   MEMHOUSE_INVITE=1');
+  if (invite) lines.push('--   MEMHOUSE_INVITE=1', "--   MEMHOUSE_INVITE_EXPIRES='<the same moment in UTC, e.g. 2026-11-06T09:00:00Z>'");
   lines.push('-- They install with:  memhouse install --env <that file>   (it deletes the file afterwards)');
   if (flags['member-password'] !== undefined) {
     lines.push('-- The --member-password you gave is not printed: use it where the placeholder stands.');
@@ -1090,6 +1110,19 @@ async function adminBootstrap(cfg, admin) {
   let password = flags['member-password'] || null;
   if (exists) {
     if (!password) {
+      // An account still carrying VALID UNTIL holds an invite nobody installed: install lifts it.
+      let pending = null;
+      try {
+        const r = await chRows(adminCfg, `SHOW CREATE USER \`${admin.member}\``, { database: '' });
+        const m = /VALID UNTIL '([^']+)'/.exec(String(r[0] ? Object.values(r[0])[0] : ''));
+        if (m && m[1] !== 'infinity') pending = m[1];
+      } catch { /* not readable: the plain refusal below */ }
+      if (pending) {
+        console.log(bad(`ClickHouse user '${admin.member}' already exists: invited, never installed (its invite password expires at ${pending}, server time)`));
+        console.log(`  To invite them again, remove that account first, as the administrator:  DROP USER \`${admin.member}\``);
+        console.log('  then run the invite again; its tables are kept and reused');
+        return null;
+      }
       console.log(bad(`ClickHouse user '${admin.member}' already exists — give their password (MEMHOUSE_MEMBER_PASSWORD, or --member-password-file) to install as them.`));
       console.log(`  Or pick another handle:  --member <name>`);
       return null;
@@ -1344,6 +1377,14 @@ async function cmdInstall({ interactive }) {
     console.log(ok(`using the invite file ${String(flags.env)} (nothing persisted until the install proves out)`));
     _inviteFileToShred = path.resolve(String(flags.env));
     _inviteWantsRotate = parsed.MEMHOUSE_INVITE === '1';
+    // An expired invite: its password no longer works (VALID UNTIL), so say that, before the
+    // server answers with a bare "authentication failed".
+    const until = Date.parse(parsed.MEMHOUSE_INVITE_EXPIRES || '');
+    if (Number.isFinite(until) && Date.now() > until) {
+      console.log(bad(`this invite expired at ${parsed.MEMHOUSE_INVITE_EXPIRES} (UTC) — ask whoever invited you for a new one; nothing was changed`));
+      _inviteFileToShred = null;
+      return 1;
+    }
   }
   let cfg = resolveConfig();
   const adminUser = flags['admin-user'];
@@ -1394,7 +1435,7 @@ async function cmdInstall({ interactive }) {
     const adminPassword = await adminPasswordFor(String(adminUser));
     if (adminPassword === null) return 1;
     {
-      const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows({ ...cfg, user: String(adminUser), password: adminPassword }, sql, { database: '' }), cfg.db, member), member);
+      const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows({ ...cfg, user: String(adminUser), password: adminPassword }, sql, { database: '' }), cfg.db, member), member, { user: String(adminUser), url: cfg.url });
       if (pick.refuse) { console.log(bad(pick.refuse)); console.log('  nothing was changed'); return 1; }
       cfg.schema = pick.schema === '3' ? '3' : '';
     }
@@ -1514,7 +1555,7 @@ async function cmdInstall({ interactive }) {
   // Joining a house: its schema, detected, never the default (a 0.20 client on an unconverted
   // 0.18 house stays on its rooms until the admin converts it and this machine switches).
   {
-    const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows(cfg, sql, { database: '' }), cfg.db, cfg.user), cfg.user);
+    const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows(cfg, sql, { database: '' }), cfg.db, cfg.user), cfg.user, { user: cfg.user, url: cfg.url });
     if (pick.refuse) { console.log(bad(pick.refuse)); console.log('  nothing was changed'); return 1; }
     cfg.schema = pick.schema === '3' ? '3' : '';
   }
@@ -1695,6 +1736,12 @@ async function cmdInstall({ interactive }) {
 // password must never be what happens by default. The password is kept only on an explicit
 // no (the question, or --keep-password), and then the output says who still knows it. A failed
 // rotation never fails the install: it keeps the invite file and says how to retry.
+// A member holds ALTER USER on itself, so it can lift the invite's VALID UNTIL.
+async function clearInviteExpiry(cfg) {
+  try { const c = cfg || resolveConfig(); await ch(c, `ALTER USER \`${c.user}\` VALID UNTIL 'infinity'`, { database: '' }); return true; }
+  catch { return false; }
+}
+
 async function finishInvite(cfg) {
   if (_inviteWantsRotate) {
     let go = flags['keep-password'] !== true;
@@ -1715,6 +1762,9 @@ async function finishInvite(cfg) {
         for (const k of drift.changed) process.env[k] = drift.values[k];
         if (drift.values.MEMHOUSE_PASSWORD !== undefined && flags.password !== undefined) flags.password = drift.values.MEMHOUSE_PASSWORD;
         if (cfg) cfg.password = process.env.MEMHOUSE_PASSWORD;
+        // The new password carries no expiry (a member's own ALTER USER … IDENTIFIED BY drops
+        // VALID UNTIL); say so explicitly, in case a server keeps it.
+        await clearInviteExpiry(cfg);
       }
       if (code !== 0) {
         // Rotation failed and its own state may be uncertain — KEEP the invite file (it
@@ -1725,6 +1775,8 @@ async function finishInvite(cfg) {
       }
     } else {
       console.log(warn('kept the invited password, as asked: whoever invited you still knows it. Change it with:  memhouse passwd'));
+      // Kept, so its expiry must go: the account would otherwise stop working on the invite's date.
+      if (!(await clearInviteExpiry(cfg))) console.log(warn('could not clear the invite\'s expiry: the password stops working on its date unless you change it (memhouse passwd)'));
     }
   }
   if (_inviteFileToShred) {
@@ -2297,18 +2349,17 @@ function confirmEmptyStore(value) {
 // Whether `memhouse update` helps depends on whether a newer release exists: on the latest one,
 // sending the reader to update loops (update says current, the gap stays).
 let _behind;
+// Whether a newer release is out on this install's channel, read once per doctor
+// (memhouse/release-hint.js). fetchTags returns null offline; that is "unknown", not "current".
 async function releaseBehind(cfg) {
   if (_behind === undefined) {
-    try { _behind = { known: true, up: chan.behind({ version: PKG.version, pinned: cfg.channel || null, tags: await chan.fetchTags() }) }; }
-    catch { _behind = { known: false, up: null }; }   // offline: unknown, not current
+    let tags = null;
+    try { tags = await chan.fetchTags(); } catch { /* offline: unknown, not current */ }
+    _behind = require(path.join(REPO_ROOT, 'memhouse', 'release-hint')).releaseState({ version: PKG.version, pinned: cfg.channel || null, tags });
   }
   return _behind;
 }
-function pricingHint(b) {
-  if (b.up) return `memhouse update installs ${b.up.target}, which may price it`;
-  if (b.known) return `this is the latest release (${PKG.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';
-}
+function pricingHint(b) { return require(path.join(REPO_ROOT, 'memhouse', 'release-hint')).pricingHint(b, PKG.version); }
 
 async function cmdDoctor() {
   if (flags['confirm-empty-store'] !== undefined) return confirmEmptyStore(flags['confirm-empty-store']);
@@ -3310,7 +3361,12 @@ async function cmdUpdate() {
   // the member's rooms moved from <name>.* to mem.<name>_*. Fix the env here, before the
   // shipper restarts, or its first pass refuses the old address forever.
   // (Schema 3 has no such move: its tables were created in place, under the configured house.)
-  if (!isV3(resolveConfig())) { try { await adoptMovedHouse(resolveConfig()); } catch { /* doctor will say */ } }
+  // A machine with no member install (an administrator's, with only MEMHOUSE_URL and the
+  // MEMHOUSE_ADMIN_* variables) has no house of its own to bring up to date: the steps below would
+  // connect as the default member and print its authentication failures as the house's state.
+  const memberHere = !!resolveConfig().userStated;
+  if (!memberHere) console.log(ok('no member install on this machine: no house schema or migration to check here (members and the admin do that on theirs)'));
+  if (memberHere && !isV3(resolveConfig())) { try { await adoptMovedHouse(resolveConfig()); } catch { /* doctor will say */ } }
 
   // Bring the house to the schema the NEW code expects, before any daemon restarts.
   // A release that adds rooms (0.18.3's stat tables) used to land after the restart, so
@@ -3319,7 +3375,7 @@ async function cmdUpdate() {
   // 500'd — all of it self-healing eventually, all of it alarming meanwhile. Two real
   // members hit this within an hour of each other. The new binary owns the new schema, so
   // it runs it here, in the one moment the daemons are already down.
-  {
+  if (memberHere) {
     const r = spawnSync(process.execPath, [path.join(REPO_ROOT, 'memhouse', 'shipper', 'ship.js'), '--ensure-schema'],
       { env: childEnv(resolveConfig()), encoding: 'utf-8', stdio: 'pipe', timeout: 120000 });
     const said = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').filter((l) => l.includes('[memhouse]')).pop();
@@ -3406,6 +3462,7 @@ async function cmdUpdate() {
   //   non-interactive, no flag    name it and print the command; NEVER auto-run — a cron
   //                               or CI invocation must not start a house-wide copy
   const cfg = resolveConfig();
+  if (!memberHere) return 0;
   if (cfg.url && cfg.user && isV3(cfg)) {
     // Schema 3: the 0.18 migrations are about the 0.18 rooms, which this install neither reads
     // nor writes. What it needs is its five tables, verified — ship.js --ensure-schema does that
@@ -3529,8 +3586,23 @@ async function cmdPlugins() {
   // somewhere else than the directory just inspected.
   const self = `memhouse plugins install claude${flags.target ? ` --target ${flags.target}` : ''}`;
 
+  // Codex: one block in <codex home>/AGENTS.md and one skill, opt-in (memhouse/codex-plugin.js).
+  const cxp = require(path.join(REPO_ROOT, 'memhouse', 'codex-plugin'));
+  const cxHome = cxp.codexHome();
+  const codexLine = () => {
+    const st = cxp.status({ codexHome: cxHome });
+    if (st.installed) {
+      const o = st.owner;
+      const runs = cxp.invocation({ home: o.home, bin: o.bin });
+      console.log(ok(`codex: installed in ${short(cxHome)} (${o.version || 'unknown version'}) — runs \`${runs}\`${st.block ? '' : '; the AGENTS.md block is missing'}`));
+    } else if (st.foreignSkill) console.log(warn(`codex: ${short(st.foreignSkill)} is not memhouse's — left alone`));
+    else console.log(`  codex: not installed in ${short(cxHome)} — memhouse plugins install codex`);
+    if (st.damaged) console.log(warn(`codex: ${st.damaged}`));
+  };
+
   if (sub === 'list') {
     console.log(`skills available: ${invocations}`);
+    codexLine();
     if (!targets.length) { console.log(warn('no Claude Code config directory found')); return 0; }
     for (const t of targets) {
       console.log(isPluginInstalled(t.dir)
@@ -3577,7 +3649,33 @@ async function cmdPlugins() {
     return 0;
   }
 
-  console.log('usage: memhouse plugins [list | install claude | remove claude] [--target DIR] [--yes]');
+  if (sub === 'install' && positional[1] === 'codex') {
+    try {
+      const r = cxp.install({ codexHome: cxHome, home: HOME_DIR, bin: thisBin, version: PKG.version, deliveryDir: DELIVERY });
+      console.log(ok(`codex: ${r.created ? 'created' : 'updated'} the memhouse block in ${short(r.file)}`));
+      console.log(ok(`codex: skill ${short(r.dir)} — Codex lists it as 'memhouse'`));
+      console.log(`  the block and the skill run \`${r.mh}\`; remove both with: memhouse plugins remove codex`);
+      console.log('  loads in the next Codex session');
+      return 0;
+    } catch (e) { console.log(bad(`codex: ${e.message}`)); return 1; }
+  }
+
+  if (sub === 'remove' && positional[1] === 'codex') {
+    let r;
+    try { r = cxp.remove({ codexHome: cxHome }); } catch (e) { console.log(bad(`codex: ${e.message}`)); return 1; }
+    if (r.block) {
+      const f = short(cxp.agentsFile(cxHome));
+      console.log(ok(r.fileDeleted ? `codex: removed ${f} (it held only the memhouse block)`
+        : r.emptiedLink ? `codex: removed the memhouse block from ${f}; it held only the block, so its link target is now empty and the link stays`
+          : `codex: removed the memhouse block from ${f}; the rest of the file is as it was`));
+    }
+    if (r.skill) console.log(ok(`codex: removed the skill ${short(cxp.skillDir(cxHome))}`));
+    if (r.foreignSkill) console.log(warn(`codex: ${short(r.foreignSkill)} is not memhouse's (no ${cxp.OWNER_FILE}) — left alone`));
+    if (!r.block && !r.skill) console.log(warn(`codex: nothing of memhouse's in ${short(cxHome)}`));
+    return 0;
+  }
+
+  console.log('usage: memhouse plugins [list | install claude|codex | remove claude|codex] [--target DIR] [--yes]');
   return 2;
 }
 
@@ -5017,9 +5115,41 @@ async function probePermissive(cfg, db) {
   }
 }
 
+/**
+ * Whose sessions this credential can read in the house: a share received is the housemate's
+ * tables in this same database, and system.tables lists only what a credential may read. Every
+ * member has a <name>_sessions table on either layout. Returns { all } for a credential that
+ * reads every house (an administrator: everyone would be listed), else { members }, or null when
+ * the tables cannot be listed.
+ */
+async function sharesReceived(cfg) {
+  try {
+    const caps = capabilitiesFrom(await readGrants(cfg, cfg.user));
+    if (caps.canReadEveryHouse || caps.isSuperuser) return { all: true, members: [] };
+    const rows = await chRows(cfg, `SELECT name FROM system.tables WHERE database = ${sqlStr(cfg.db)} AND endsWith(name, '_sessions')`, { database: '' });
+    const members = rows.map((r) => String(r.name).slice(0, -'_sessions'.length))
+      .filter((m) => m && m !== cfg.user && /^[A-Za-z][A-Za-z0-9_]*$/.test(m)).sort();
+    return { all: false, members };
+  } catch { return null; }
+}
+
+/** The received half of `share --list`: whose sessions this credential reads, and how. */
+function printReceived(cfg, received) {
+  console.log('');
+  if (!received) { console.log(`  whose sessions you can read: could not list the tables in '${cfg.db}'`); return; }
+  if (received.all) { console.log(`  this credential reads every member's sessions in '${cfg.db}' (it administers the server)`); return; }
+  if (!received.members.length) { console.log(`  nobody has shared their sessions with you in '${cfg.db}'`); return; }
+  console.log(`  whose sessions you can read in '${cfg.db}' (shared with you; a scoped share shows only the rows its owner chose):`);
+  for (const m of received.members) {
+    console.log(`    ${m.padEnd(16)} ${isV3(cfg) ? `memhouse q recent --member ${m}` : `memhouse room-sql "SELECT … FROM ${m}_messages …"`}`);
+  }
+}
+
 /** Who can read this house, what they are scoped to, and any policy left behind. */
 async function shareList(cfg, share) {
   const db = cfg.db;
+  const received = await sharesReceived(cfg);
+  const receivedJson = received ? (received.all ? { all: true } : received.members.map((m) => ({ member: m }))) : null;
   let recorded = [];
   try {
     recorded = await chRows(cfg, `SELECT substring(key, 7) AS user, value AS state FROM ${physicalRoom('meta', cfg.user)} FINAL WHERE key LIKE 'share:%' ORDER BY key`, { database: db });
@@ -5039,9 +5169,10 @@ async function shareList(cfg, share) {
   const covers = isV3(cfg) ? { tables: share.V3_TABLES.map((t) => `${cfg.user}_${t}`) } : { rooms: `${cfg.user}_*` };
 
   if (!recorded.length && !policies.length) {
-    if (JSON_OUT) { console.log(JSON.stringify({ database: db, ...covers, grantees: [] }, null, 2)); return 0; }
+    if (JSON_OUT) { console.log(JSON.stringify({ database: db, ...covers, grantees: [], received: receivedJson }, null, 2)); return 0; }
     console.log(ok(`nobody has been granted a read of your rooms in '${db}'`));
     console.log(`  Share it with:  memhouse share <user> [--only project=<name>]`);
+    printReceived(cfg, received);
     return 0;
   }
   // In a shared house a grantee reads YOUR ROOMS, never the database — every other member
@@ -5060,6 +5191,7 @@ async function shareList(cfg, share) {
       })),
       policies_readable: policiesReadable,
       note: "memhouse's own record, not ClickHouse's grant table — a grant made by hand does not appear here",
+      received: receivedJson,
     }, null, 2));
     return 0;
   }
@@ -5073,6 +5205,7 @@ async function shareList(cfg, share) {
     for (const p of scoped) console.log(`      ${String(p.table).padEnd(11)} ${p.select_filter}`);
   }
   console.log('  A grant made by hand does not appear here — this list is what memhouse recorded.');
+  printReceived(cfg, received);
 
   // Policies whose room is gone: dropping a house does NOT drop its policies, and a house
   // later recreated under the same name silently inherits them. Listing them takes a credential
@@ -5237,9 +5370,15 @@ async function offerInvite() {
 
 async function cmdInvite() {
   const name = positional[0];
-  if (!name) { console.log('usage: memhouse invite <name> --url <house-url> [--admin-user … [--admin-password-file FILE|-]] [--db <house>] [--out <file>] [--adopt] [--schema 2|3] [--print-sql]'); return 2; }
+  if (!name) { console.log('usage: memhouse invite <name> --url <house-url> [--admin-user … [--admin-password-file FILE|-]] [--db <house>] [--out <file>] [--adopt] [--schema 2|3] [--expires DAYS] [--print-sql]'); return 2; }
   try { require(path.join(REPO_ROOT, 'memhouse', 'house', 'house')).assertUsableName(name, 'member'); }
   catch (e) { console.log(bad(e.message)); return 1; }
+  // How long the invite's password works (VALID UNTIL): checked before anything is contacted.
+  const expiresDays = flags.expires === undefined ? INVITE_DAYS : flags.expires === true ? NaN : Number(flags.expires);
+  if (!Number.isInteger(expiresDays) || expiresDays < 1 || expiresDays > 365) {
+    console.log(bad(`--expires takes a whole number of days, 1 to 365 (default ${INVITE_DAYS}); got '${flags.expires === true ? '' : flags.expires}'`));
+    return 2;
+  }
   const cfg = resolveConfig();
   // The URL must be STATED and must work from the INVITEE's machine. cfg.url falls back
   // to localhost:8123 — dead, or worse, someone else's house, on every other machine.
@@ -5291,6 +5430,9 @@ async function cmdInvite() {
     console.log(memberSql(db, name));
     // Nothing is contacted, so nothing is detected: schema 3 unless stated, as install --print-sql.
     if (statedSchema !== '2') console.log(memberSqlV3(db, name));
+    // The same expiry a run of invite sets. A placeholder, like the password's: the statement
+    // does not parse until a quoted moment in the server's time zone stands in its place.
+    console.log(`-- The invited password expires, as \`memhouse invite\` sets it: put the moment ${expiresDays} day${expiresDays === 1 ? '' : 's'}\n-- from now, quoted, in the server's time zone, where <valid-until> stands. install lifts it.\nALTER USER \`${name}\` VALID UNTIL <valid-until>;`);
     console.log(handoffLines({ url, db, member: name, invite: true }));
     return 0;
   }
@@ -5410,7 +5552,7 @@ async function cmdInvite() {
   // The house decides, as for an install: a new house is schema 3, one on the 0.18 rooms
   // keeps them, and an ambiguous one is refused.
   {
-    const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows(adminCfg, sql, { database: '' }), db, name), name);
+    const pick = schemaChoice.chooseSchema(statedSchema, await schemaChoice.detectHouseSchema((sql) => chRows(adminCfg, sql, { database: '' }), db, name), name, { user: adminCfg.user, url: adminCfg.url });
     if (pick.refuse) { console.log(bad(pick.refuse)); console.log('  nothing was changed'); return 1; }
     cfg.schema = pick.schema === '3' ? '3' : '';
   }
@@ -5447,6 +5589,19 @@ async function cmdInvite() {
   if (built) built.url = url; // the invitee reaches the house at --url, not the admin's endpoint
   if (!built) return 1;
 
+  // The invite's password expires: a file that sits unused, or was read where it should not
+  // have been, stops working on its own. The server's own clock sets the date (VALID UNTIL is
+  // read in its time zone); install's rotation clears it, as does --keep-password.
+  let expires = null;
+  try {
+    const adminCfg = { ...cfg, url: provisionUrl, db, user: adminUser, password: adminPass || '' };
+    const r = (await chRows(adminCfg, `SELECT toString(now() + toIntervalDay(${expiresDays})) AS lit, toUnixTimestamp(now() + toIntervalDay(${expiresDays})) AS ts`, { database: '' }))[0];
+    await ch(adminCfg, `ALTER USER \`${name}\` VALID UNTIL ${sqlStr(r.lit)}`, { database: '' });
+    expires = new Date(Number(r.ts) * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  } catch (e) {
+    console.log(warn(`could not set the invite's expiry (${String(e.message).split('\n')[0]}): its password works until install changes it`));
+  }
+
   const out = path.resolve(flags.out && flags.out !== true ? String(flags.out) : `invite-${name}.env`);
   const sq = envfile.quoteShell;
   const body = [
@@ -5465,6 +5620,8 @@ async function cmdInvite() {
     '# Issued by an invitation (no admin access here): install changes it so the inviter',
     '# no longer knows it.',
     'MEMHOUSE_INVITE=1',
+    ...(expires ? [`# The password above stops working at ${expires} (UTC): install before then, or ask for a new invite.`,
+      `MEMHOUSE_INVITE_EXPIRES=${sq(expires)}`] : []),
     '',
   ].join('\n');
   // Atomic + private + no symlink follow: write a fresh temp with O_EXCL at 0600, then
@@ -5506,11 +5663,12 @@ async function cmdInvite() {
     const page = require(path.join(REPO_ROOT, 'memhouse', 'invitation')).invitationPage({
       out, name, url, db: built.db, schema: isV3(cfg) ? '3' : '', install,
       version: prerelease ? `${base}-…` : PKG.version,
-      inviter: cfg.user || require('os').userInfo().username,
+      inviter: cfg.user || require('os').userInfo().username, expires,
     });
     fs.writeFileSync(page.path, page.text);
     console.log(ok(`guide written:  ${page.path}`));
   } catch (e) { console.log(warn(`could not write the invitation guide: ${e.message}`)); }
+  if (expires) console.log(ok(`the invite expires at ${expires} (UTC), in ${expiresDays} day${expiresDays === 1 ? '' : 's'} (--expires <days> sets it); after that, invite again`));
   console.log(`  send ${name} BOTH files over a channel you trust (croc, a password manager — not chat):`);
   console.log(`     ${path.basename(out)}   their credential — one-time, install deletes it`);
   console.log(`     MEMHOUSE-INVITATION.md  the steps, nothing secret`);
@@ -5737,8 +5895,14 @@ async function cmdUninstall() {
   // invite, uninstall and friends act on first call with no separate confirm step, so a
   // --help that fell through to the default branch would DO the thing instead of
   // describing it. One check ahead of the switch, for every command, is the whole fix.
+  // The command's own entries, not the whole page (memhouse/help.js); `q` lists its named queries.
   if (cmd && (flags.help === true || process.argv.slice(2).some((a) => a === '-h' || a === '--help'))) {
-    console.log(HELP); return;
+    if (cmd === 'q') {
+      const schema = isV3(resolveConfig()) ? 3 : 2;
+      for (const l of qc().renderQ('list', await qc().runQ(null, null, qc().parseQ([], {}), { schema }))) console.log(l);
+      return;
+    }
+    console.log(require(path.join(REPO_ROOT, 'memhouse', 'help')).helpFor(HELP, cmd, PKG.version) || HELP); return;
   }
   const cfg = resolveConfig();
 
@@ -6027,15 +6191,21 @@ async function cmdUninstall() {
           console.error(warn(`could not read who holds which role (${String(e.message).split('\n')[0]}): access held through a role is not shown`));
         }
         rows = share.membersAccess({ grants, roleGrants, db });
+        // Whether a share is scoped: its row policies, where this credential can list them.
+        try { rows.policies = await chRows(who, `SELECT short_name, table FROM system.row_policies WHERE database = ${sqlStr(db)}`, { database: '' }); }
+        catch { rows.policies = null; }
       } catch (e) {
         console.log(bad(`could not read the grant table: ${e.message}`));
         console.log('  Pass an admin credential:  memhouse members --admin-user <a>   (its password from MEMHOUSE_ADMIN_PASSWORD, or --admin-password-file -)');
         process.exitCode = 1; break;
       }
+      const share = require(path.join(REPO_ROOT, 'memhouse', 'share'));
+      const described = (r) => share.describeAccess(r, { policies: rows.policies });
       if (JSON_OUT) {
-        console.log(JSON.stringify({ database: db, roles_read: !rolesUnread, members: rows.map((r) => ({
+        console.log(JSON.stringify({ database: db, roles_read: !rolesUnread, policies_read: rows.policies !== null, members: rows.map((r) => ({
           name: r.u, scope: Number(r.db_wide) === 1 ? 'database' : 'rooms',
           rooms: Number(r.db_wide) === 1 ? null : r.list,
+          ...(Number(r.db_wide) === 1 ? {} : described(r)),
         })) }, null, 2));
         break;
       }
@@ -6047,9 +6217,19 @@ async function cmdUninstall() {
       }
       const owners = rows.filter((r) => Number(r.db_wide) === 1);
       console.log(`  '${db}' — ${rows.length} member(s):`);
+      // Each account's own tables, the members it reads (a share: scoped or full where the row
+      // policies can be listed), and anything else, which memhouse does not grant itself.
       for (const r of rows) {
-        if (Number(r.db_wide) === 1) console.log(`    ${String(r.u).padEnd(16)} the whole database`);
-        else console.log(`    ${String(r.u).padEnd(16)} ${String(r.tables || '(none)')}`);
+        if (Number(r.db_wide) === 1) { console.log(`    ${String(r.u).padEnd(16)} the whole database`); continue; }
+        const d = described(r);
+        const pad = ' '.repeat(21);
+        const lines = [];
+        if (d.own.length) lines.push(`own: ${d.own.join(', ')}`);
+        for (const s of d.shares) lines.push(`reads ${s.from}'s sessions (a share${s.scoped === null ? '' : s.scoped ? ', scoped' : ', full'}): ${s.tables.join(', ')}`);
+        if (d.other.length) lines.push(`other grants (not memhouse's own shape — check them): ${d.other.join(', ')}`);
+        if (!lines.length) lines.push('(none)');
+        console.log(`    ${String(r.u).padEnd(16)} ${lines[0]}`);
+        for (const l of lines.slice(1)) console.log(`${pad}${l}`);
       }
       if (owners.length && rows.length > 1) {
         console.log('');
@@ -6506,7 +6686,7 @@ async function cmdUninstall() {
         // grants. The superuser is at hand here, so they are built now, and the member install
         // below finds them ready. Without this, deploy --local on 0.20 stopped at the install.
         const pick = schemaChoice.chooseSchema(flags.schema && flags.schema !== true ? String(flags.schema) : '',
-          await schemaChoice.detectHouseSchema((sql) => chRows(adminCfg, sql, { database: '' }), targetDb, houseUser), houseUser);
+          await schemaChoice.detectHouseSchema((sql) => chRows(adminCfg, sql, { database: '' }), targetDb, houseUser), houseUser, { user: adminCfg.user, url: adminCfg.url });
         if (pick.refuse) { console.log(bad(pick.refuse)); process.exitCode = 1; break; }
         if (pick.schema === '3') {
           const v3 = require(path.join(REPO_ROOT, 'memhouse', 'house', 'schema-profile'));

package/docs/guides/install.md

@@ -128,3 +128,6 @@ The path proves nothing on its own: Homebrew's prefix is `/usr/local` on Intel a
 - `memhouse plugins install claude`: the `/mem:*` skills, for Claude Code only. Codex and the
   other editors' sessions ship all the same; an agent there reads the house with the CLI
   (`memhouse q`, `memhouse room-sql`). See [Search, resume and skills](search-and-resume.md).
+- `memhouse plugins install codex`: for Codex, a short block in its `AGENTS.md` (the rules) and
+  a `memhouse` skill (the read recipes). Nothing is written under the Codex home unless you run
+  it. See [Codex](search-and-resume.md#codex).

package/docs/guides/invite.md

@@ -27,6 +27,13 @@ memhouse invite alice --url https://house.example.com
 - **Alice installs with `memhouse install --env invite-alice.env`.** It offers to rotate
   the password to one only she knows, which works because she is granted `ALTER USER` on
   herself. Then it deletes the file. Once she rotates, the password you saw stops working.
+- **The invite expires.** The password in the file stops working 7 days after the invite
+  (`--expires <days>` sets 1 to 365), counted by the server's clock. The output, the file and
+  the invitation page say when. Installing lifts the expiry, whether she changes the password
+  or keeps it with `--keep-password`. After the date, `install` refuses the file and tells her
+  to ask for a new invite. Her account is still there, so remove it first (`DROP USER alice`, as
+  the administrator; `invite` says so when it meets it), then invite her again. Her tables are
+  kept and reused.
 
 ## Which admin credential
 

package/docs/guides/search-and-resume.md

@@ -99,6 +99,36 @@ missing skill never announces itself.
 For an agent that does not use Claude Code skills, `memhouse prompt` prints a snippet for
 its system prompt: where memory lives and how to query it.
 
+### Codex
+
+The `/mem` skills are for Claude Code. For Codex:
+
+```bash
+memhouse plugins install codex      # under CODEX_HOME, or ~/.codex
+memhouse plugins list               # shows the codex copy and the command it runs
+memhouse plugins remove codex
+```
+
+It writes two things, and only when you run it:
+
+- **A block at the top of `AGENTS.md`**, between `<!-- memhouse:begin … -->` and
+  `<!-- memhouse:end -->`. Codex puts this file in every prompt, so the block holds only what must
+  always hold: never read or print `~/.memhouse/env` or a `MEMHOUSE_*` value; `MEMHOUSE_URL` is the
+  house and `MEMHOUSE_PORT` the dashboard; questions about past sessions go to the `memhouse`
+  skill. The file is created if it is missing. Installing again replaces the block where it
+  stands. Removing takes out the block and the blank line after it, so the rest of the file is
+  what it was, byte for byte; a file that held only the block is deleted, or, when `AGENTS.md`
+  is a symlink, its target is emptied and the link kept. Leave the markers
+  alone: with one of them missing, install and remove refuse and change nothing.
+- **A skill, `skills/memhouse/`**, with the read recipes: `memhouse q`, `--member` for a
+  housemate's sessions, `memhouse room-sql`. Codex lists it by name and description and reads
+  the rest when it uses it. The directory carries `.memhouse.json`; a `skills/memhouse` without
+  it is someone else's, and install refuses to replace it and remove leaves it.
+
+For an instance with its own home or binary, both name it: `MEMHOUSE_HOME=<home> <binary> q …`.
+After an upgrade, the first `memhouse` command refreshes both, as it does the `/mem` copies; a
+block you took out by hand stays out.
+
 ## Writing your own queries
 
 On schema 3 (0.20), the tables are `mem.<you>_session_parts` (one row per part of a message:

package/docs/guides/share.md

@@ -106,6 +106,10 @@ included. A grant someone made by hand in SQL does not appear there. A member ca
 `system.grants` or `system.row_policies`; an administrator can, with `SHOW GRANTS FOR <user>`
 and the queries in [Operate](operate.md#who-is-here).
 
+It also lists the other direction: each member whose sessions your credential can read, with
+the command that reads them. A scoped share shows only the rows its owner chose, and its filter
+is the owner's to see.
+
 ## Reading what was shared with you
 
 Shared tables sit in the same database as yours, under the other member's name, for

package/docs/releases/README.md

@@ -5,6 +5,7 @@ do, how to upgrade, what is deprecated and when it goes, and what was deferred.
 
 | version | date | headline |
 |---|---|---|
+| [0.20.1](v0.20.1.md) | 2026-11-02 | invites expire; `memhouse plugins install codex`; per-command help and clearer CLI answers |
 | [0.20.0](v0.20.0.md) | 2026-10-29 | schema 3: a session is its store, nothing cut or lost, forks billed once, ten editors through normalisers; Apache-2.0 |
 | [0.18.11](v0.18.11.md) | 2026-10-10 | sessions with subagents stop re-shipping; security: no stored credential sent to `invite --url` |
 | [0.18.10](v0.18.10.md) | 2026-10-08 | security: the admin password never on argv; no member password printed; a scoped share reaches only its scope |