memhouse 0.15.0 → 0.17.0

package/README.md

@@ -99,7 +99,7 @@ an agent — so an agent can install its own memory unattended.
 config directory on the machine** — `~/.claude`, whatever `CLAUDE_CONFIG_DIR` points
 at, and each Kommander-style playbook under `~/.claude-playbooks/`. All are selected by
 default; answer with numbers to narrow it, or pass `--target DIR` for exactly one.
-Installing into just the default config is how `/mem:search` ends up missing from
+Installing into just the default config is how `/mem:recall` ends up missing from
 the instance you actually work in, silently, since a missing skill never announces
 itself.
 

package/bin/memhouse.js

@@ -30,6 +30,7 @@ const {
 const envfile = require(path.join(REPO_ROOT, 'memhouse', 'envfile'));
 const { consumeSecretChunk } = require(path.join(REPO_ROOT, 'memhouse', 'secret-input'));
 const { capabilitiesFrom } = require(path.join(REPO_ROOT, 'memhouse', 'capabilities'));
+const { unknownFlags, allowedFlags, suggestFlag } = require(path.join(REPO_ROOT, 'memhouse', 'flags'));
 
 const HOME_DIR = process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse');
 const ENV_FILE = path.join(HOME_DIR, 'env');
@@ -53,6 +54,22 @@ for (let i = 0; i < rest.length; i++) {
 }
 const JSON_OUT = flags.json === true;
 
+// Unknown flags stop the run — see memhouse/flags.js for why a shrug is not enough.
+(() => {
+  const bad = unknownFlags(cmd, flags);
+  if (!bad.length) return;
+  const allowed = allowedFlags(cmd);
+  for (const f of bad) {
+    const hint = suggestFlag(f, allowed);
+    console.error(`memhouse: unknown option --${f}${hint ? `  (did you mean --${hint}?)` : ''}`);
+  }
+  const list = [...allowed].sort().map((f) => `--${f}`).join(' ');
+  console.error(`  ${cmd || 'memhouse'} takes: ${list || '(no options)'}`);
+  console.error('  Nothing ran. A flag that is ignored rather than refused is how a --dry-run typo');
+  console.error('  becomes a real migration.');
+  process.exit(2);
+})();
+
 let ONBOARDING = false;
 let _inviteFileToShred = null;
 let _inviteWantsRotate = false;
@@ -382,6 +399,10 @@ Data         ship                 one incremental pass (--full | --loop [sec])
              resume <session-id>  print the command that reopens that session in its editor
              sessions-query       print the session rollup SQL for this credential
              start | stop |       shipper loop + dashboard as background daemons
+             share <user>         let someone read this house (--only project=… |
+                                  session=… | host=… | source=… | folder=… | since=… |
+                                  until=… scopes it with row policies; --revoke
+                                  withdraws and drops them; --list shows who)
              whoami               which credential is in play, and what it may do
                                   (--json; --admin reads MEMHOUSE_ADMIN_*)
              status               daemons, connection, counts, freshness (--json)
@@ -699,7 +720,7 @@ ${rooms.trim()}
 -- The whole database, WITH GRANT OPTION. ALL on your own house reaches nothing outside it
 -- — the database is the boundary — and it lets the shipper create and evolve its own
 -- tables. The grant option makes the member the real owner: they can hand on any of their
--- own data (\`/mem:share\` still opens only a read-only SELECT window, but the owner is not
+-- own data (\`/mem:access\` still opens only a read-only SELECT window, but the owner is not
 -- boxed into read-only sharing of their own house). Scoped to this db, and no CREATE USER
 -- rides with it — a member still cannot mint accounts or reach another house.
 GRANT ALL ON ${db}.* TO ${member} WITH GRANT OPTION;
@@ -714,9 +735,9 @@ GRANT ALL ON ${db}.* TO ${member} WITH GRANT OPTION;
 -- trust model, flagged by \`memhouse doctor\`, and re-asserted on every \`ship --ensure-schema\`.
 GRANT ALTER USER ON ${member} TO ${member};
 
--- See the OTHER members, read-only. SHOW USERS lets \`/mem:users\` list who is on this
+-- See the OTHER members, read-only. SHOW USERS lets \`/mem:house\` list who is on this
 -- ClickHouse (names only — no passwords, no data) so a member can find who to share with.
--- It grants no read of anyone's rows; reading a housemate's memory still needs /mem:share.
+-- It grants no read of anyone's rows; reading a housemate's memory still needs /mem:access.
 GRANT SHOW USERS ON *.* TO ${member};
 
 -- \`memhouse relocate\` runs FROM the destination, pulling the source over remoteSecure() —
@@ -791,7 +812,7 @@ async function adminBootstrap(cfg, admin) {
       password = generatePassword();
       // For a local install the password must be SHOWN — it is the user's only copy. For
       // an invite it must NOT: the caller writes it to the credential file, and printing
-      // it here would land it in the terminal and, via /mem:invite, in a transcript
+      // it here would land it in the terminal and, via /mem:access, in a transcript
       // memhouse itself ships. admin.quiet is the invite path.
       if (!admin.quiet) {
         console.log('');
@@ -822,7 +843,7 @@ async function adminBootstrap(cfg, admin) {
   // create and evolve the rooms (--ensure-schema below).
   try {
     // ALL, WITH GRANT OPTION: the database is theirs, so they may do anything with their
-    // own data AND hand any of it on. /mem:share still opens only a read-only window (it
+    // own data AND hand any of it on. /mem:access still opens only a read-only window (it
     // grants SELECT), but the owner is not boxed into read-only sharing of their own house.
     // Scoped to their db: the grant option reaches nothing outside it, and no CREATE USER
     // comes with it, so a member still cannot mint accounts or touch another house.
@@ -834,12 +855,12 @@ async function adminBootstrap(cfg, admin) {
     // self-rotation.
     try { await q(`GRANT ALTER USER ON ${admin.member} TO ${admin.member}`, { database: '' }); }
     catch { /* admin without access-management: passwd stays admin-assisted for this member */ }
-    // See the OTHER members, read-only: SHOW USERS lets `/mem:users` list who is on this
+    // See the OTHER members, read-only: SHOW USERS lets `/mem:house` list who is on this
     // ClickHouse (names only — no passwords, no data) so a member can find who to share
-    // with. It grants no read of anyone's rows; that still needs an explicit /mem:share.
+    // with. It grants no read of anyone's rows; that still needs an explicit /mem:access.
     // Best-effort like ALTER USER above — an admin without access-management just skips it.
     try { await q(`GRANT SHOW USERS ON *.* TO ${admin.member}`, { database: '' }); }
-    catch { /* no access-management: /mem:users section 4 stays admin-only for this member */ }
+    catch { /* no access-management: /mem:house section 4 stays admin-only for this member */ }
     // REMOTE: `memhouse relocate` runs FROM the destination, pulling the source over
     // remoteSecure() — a table function ClickHouse gates behind its own access type,
     // separate from any GRANT ALL on a database. Without it every relocate a member runs
@@ -1126,14 +1147,29 @@ async function cmdInstall({ interactive }) {
   // shipper or an installed service is still pointed at the old house, and rewriting the
   // file orphans it with no error anywhere.
   const prior = readEnvFile();
-  if (prior.MEMHOUSE_URL && flags.force !== true
-      && (!sameEndpoint(prior.MEMHOUSE_URL, cfg.url) || (prior.MEMHOUSE_DB && prior.MEMHOUSE_DB !== cfg.db))) {
+  const displaces = Boolean(prior.MEMHOUSE_URL)
+    && (!sameEndpoint(prior.MEMHOUSE_URL, cfg.url) || (prior.MEMHOUSE_DB && prior.MEMHOUSE_DB !== cfg.db));
+  if (displaces && flags.force !== true) {
     console.log(bad(`${ENV_FILE} already points at ${prior.MEMHOUSE_URL} / ${prior.MEMHOUSE_DB || '?'}`));
     console.log(`  installing over it would leave any running shipper or service on the old house.`);
     console.log('     memhouse setup --url … --db …     (move deliberately)');
     console.log('     memhouse install --force …        (overwrite anyway)');
     return 1;
   }
+  if (displaces) {
+    // --force used to overwrite the file and say nothing. The password inside is often
+    // the ONLY copy — an invited member cannot mint another — so replacing it silently
+    // orphans a house that still exists and still costs disk. A drill found this by
+    // taking the hatch the refusal above offers: the arriver read "already exists",
+    // reached for --force, and destroyed a working credential without being told.
+    // `relocate` already keeps the old file for the same operation; so does this now.
+    console.log(warn(`replacing the credential for ${prior.MEMHOUSE_USER || '?'}@${prior.MEMHOUSE_URL} (house '${prior.MEMHOUSE_DB || '?'}')`));
+    try {
+      fs.copyFileSync(ENV_FILE, `${ENV_FILE}.pre-install`);
+      console.log(`  previous config kept at ${`${ENV_FILE}.pre-install`.replace(os.homedir(), '~')} — it holds that password`);
+    } catch { console.log(warn('  could not keep a copy of the previous config')); }
+    console.log('  that house still exists; nothing was deleted from the server.');
+  }
   // Preflight WITHOUT selecting the house — on a fresh standalone ClickHouse the
   // database doesn't exist yet, and selecting it would fail before we can create it.
   try { await ch(cfg, 'SELECT 1', { database: '' }); }
@@ -1207,6 +1243,28 @@ async function cmdInstall({ interactive }) {
   // config file behind every failed attempt, and the next command reads it as truth.
   writeEnvFile(cfg);
   console.log(ok(`config written: ${ENV_FILE}`));
+  // A running shipper holds the OLD house until it restarts. It does not fail — it keeps
+  // shipping, to the house that is no longer configured, while `status` shows a green
+  // "shipper: running" beside a green "house: empty" and the new house stays at zero.
+  // Measured in a drill: 145 sessions "skipped" into a house holding no rows, because the
+  // skip predicate was still being evaluated against the old one. `relocate` restarts
+  // deliberately for exactly this reason; install used to do nothing at all.
+  if (displaces && shipperHealth().running) {
+    const st = (() => { try { return require(path.join(REPO_ROOT, 'memhouse', 'service.js')).status(); } catch { return null; } })();
+    const viaService = String(shipperHealth().via || '').startsWith('service');
+    if (viaService && st) {
+      const cmd = st.kind === 'systemd'
+        ? ['systemctl', ['--user', 'restart', 'memhouse-shipper']]
+        : ['launchctl', ['kickstart', '-k', `gui/${process.getuid()}/com.memhouse.shipper`]];
+      const r = spawnSync(cmd[0], cmd[1], { stdio: 'pipe', encoding: 'utf-8' });
+      console.log(r.status === 0 ? ok('shipper restarted against the new house')
+        : warn('restart the shipper yourself, or it keeps writing to the old house:  memhouse service restart'));
+    } else {
+      const pid = pidOf('shipper');
+      if (pid) { try { process.kill(pid, 'SIGTERM'); console.log(ok(`stopped the shipper (pid ${pid}) — it was pointed at the old house`)); } catch { /* raced */ } }
+      console.log('  start it against the new one:  memhouse start');
+    }
+  }
   // Mint this machine's identity here rather than leaving it to whatever runs first.
   // Installing is the moment a machine joins the member's rooms, and the id is what every
   // later `WHERE host = …` depends on — so it is worth naming once, out loud, at the point
@@ -1269,9 +1327,9 @@ function printGettingStarted(cfg) {
   console.log('     memhouse start                  dashboard + shipper loop (background daemons)');
   console.log(`       -> http://localhost:${cfg.port || 4640}       browse, search, and analyze every session`);
   console.log('     memhouse service install        or: ship at login, no terminal needed');
-  console.log('     memhouse plugins install claude give your agents /mem:hello, /mem:ask, /mem:search,');
-  console.log('                                     /mem:sessions, /mem:share, /mem:invite, /mem:sql,');
-  console.log('                                     /mem:status, /mem:users');
+  console.log('     memhouse plugins install claude give your agents /mem:house, /mem:recall,');
+  console.log('                                     /mem:recall, /mem:access, /mem:sql,');
+  console.log('                                     /mem:house');
   console.log('     memhouse search <terms>         find a past conversation right now');
   console.log('     memhouse doctor                 every line a check mark = healthy');
   console.log('  The house keeps shipping as you work; nothing else to do.');
@@ -1331,7 +1389,7 @@ async function cmdOnboard() {
   const targets = claudeTargets();
   if (targets.length) {
     console.log('');
-    console.log(`Claude Code skills: ${fs.readdirSync(path.join(DELIVERY, 'plugin', 'skills')).map((n) => `/mem:${n}`).join(', ')}`);
+    console.log(`Claude Code skills: ${skillNames().map((n) => `/mem:${n}`).join(', ')}`);
     const chosen = await chooseTargets(targets, 'Install into');
     for (const t of chosen) console.log(ok(`installed skills into ${short(installPluginInto(t.dir))}`));
     if (chosen.length) console.log('  they load next time that Claude Code starts');
@@ -2228,7 +2286,7 @@ async function cmdUpdate() {
 // A pilot rarely has one. `~/.claude` is the stock install, `CLAUDE_CONFIG_DIR` points at
 // whichever they are running right now, and Kommander-style playbooks live under
 // `~/.claude-playbooks/<name>[/playbook]`, each a complete config directory with its own
-// skills/. Installing into one and calling it done leaves /mem:search missing from
+// skills/. Installing into one and calling it done leaves /mem:recall missing from
 // every other instance the pilot uses — silently, because a missing skill does not announce
 // itself, it just never appears.
 //
@@ -2264,7 +2322,7 @@ const isPluginInstalled = (dir) => fs.existsSync(path.join(dir, PLUGIN_MARK));
 
 function installPluginInto(dir) {
   // The plugin was named `memhouse` until 0.10.0. A leftover copy under the old name
-  // would load BESIDE the new one — /memhouse:search and /mem:search both resolving, one
+  // would load BESIDE the new one — /memhouse:search and /mem:recall both resolving, one
   // of them stale forever. Remove it only when it is provably OURS (it carries our
   // plugin.json); a directory someone else named `memhouse` is not ours to delete.
   const legacy = path.join(dir, 'skills', 'memhouse');
@@ -2280,7 +2338,7 @@ function installPluginInto(dir) {
   const dst = path.join(dir, 'skills', 'mem');
   // REPLACE, not overlay. cpSync over an existing install refreshes the skills and
   // leaves anything else standing — a machine that once had a build with extra skills
-  // kept offering /mem:replay and /mem:status forever, stale, beside the real ones.
+  // kept offering /mem:replay and /mem:house forever, stale, beside the real ones.
   // Ownership means OUR MANIFEST, checked by name — "any plugin.json" would have deleted
   // an unrelated plugin that happened to pick the same directory name.
   const dstManifest = path.join(dst, '.claude-plugin', 'plugin.json');
@@ -2334,15 +2392,27 @@ async function chooseTargets(targets, verb) {
 //
 // Claude Code gives a skill a namespace only when it arrives inside a plugin: a directory
 // under <config>/skills/ containing .claude-plugin/plugin.json loads as
-// `mem@skills-dir` and its skills become /mem:search, /mem:sessions,
+// `mem@skills-dir` and its skills become /mem:recall,
 // /mem:sql. Copied in flat, the same three files register as unrelated top-level
 // skills named after their folders — which is what this used to do, while plugin.json sat
 // unread one directory away claiming the colon form. Driving a real Claude Code is what
-// caught it: `/mem:search` answered `Unknown command. Did you mean /memhouse-search?`
+// caught it: `/mem:recall` answered `Unknown command. Did you mean /memhouse-search?`
+/**
+ * The plugin's skills, by name. A directory is a skill only when it carries a SKILL.md —
+ * `plugin/` also holds `reference/`, shared prose the skills point at, and listing that
+ * as `/mem:reference` would advertise a command nobody can run.
+ */
+function skillNames() {
+  const dir = path.join(DELIVERY, 'plugin', 'skills');
+  try {
+    return fs.readdirSync(dir).filter((n) => fs.existsSync(path.join(dir, n, 'SKILL.md'))).sort();
+  } catch { return []; }
+}
+
 async function cmdPlugins() {
   const sub = positional[0] || 'list';
   const pluginSrc = path.join(DELIVERY, 'plugin');
-  const names = fs.readdirSync(path.join(pluginSrc, 'skills'));
+  const names = skillNames();   // SKILL.md-bearing dirs only — `reference/` is not a skill
   const invocations = names.map((n) => `/mem:${n}`).join(', ');
   // --target overrides the discovery rather than joining it: given one, that is the only
   // directory touched.
@@ -2932,7 +3002,7 @@ async function cmdNightly() {
  * machine's config is never touched and nothing local ships. The server half is exactly
  * adminBootstrap (create user if absent, create house, GRANT ALL + SELECT WITH GRANT
  * OPTION, async pin, then verify AS THE MEMBER), so an invited member is
- * indistinguishable from one minted by a local admin install — /mem:share works for
+ * indistinguishable from one minted by a local admin install — /mem:access works for
  * them on day one.
  *
  * The output file IS a credential. The header says so, the handoff advice names safe
@@ -2951,12 +3021,209 @@ async function cmdNightly() {
  * can ask "is there an admin credential in this environment?" without inventing a place
  * to store one. Nothing here prints or persists a password.
  */
+/**
+ * `memhouse share <user> [--only <scope>] [--revoke]`, `memhouse share --list`
+ *
+ * Full share is a GRANT and nothing else. Partial share adds one ROW POLICY per room, so
+ * the grantee reads only what the scope allows. See memhouse/share.js for why there is
+ * deliberately no permissive catch-all policy, and what was measured to rule it out.
+ */
+async function cmdShare() {
+  const share = require(path.join(REPO_ROOT, 'memhouse', 'share'));
+  const cfg = requireConfig(resolveConfig(), 'share');
+  if (!cfg.user) return 1;
+  const db = cfg.db;
+
+  // Statements, not reads: this is the one command in the read family that writes, so it
+  // does NOT go through the readonly connection the skills use.
+  const run = (sql) => ch(cfg, sql, { database: db });
+  const rows = (sql) => chRows(cfg, sql, { database: db });
+
+  // List only when asked for it, or when given nothing at all. `--only` or `--revoke`
+  // without a user is a mistake worth naming, not a reason to print the list.
+  const bare = !positional[0] && flags.only === undefined && flags.revoke === undefined;
+  if (flags.list === true || bare) return shareList(cfg, share);
+
+  const user = positional[0];
+  if (!user) { console.log(bad('usage: memhouse share <user> [--only <scope>] [--revoke]  |  memhouse share --list')); return 2; }
+  // The name is spliced into GRANT/REVOKE/CREATE POLICY unquoted, so it must be a name
+  // ClickHouse accepts bare. Refuse rather than quote: a handle you cannot type plainly
+  // is one that will be gotten wrong somewhere else.
+  try { require(path.join(REPO_ROOT, 'memhouse', 'house', 'house')).assertUsableName(user, 'user'); }
+  catch (e) { console.log(bad(e.message)); return 1; }
+  if (user === cfg.user) { console.log(bad(`'${user}' is you — you already read your own house`)); return 1; }
+
+  // ── revoke ────────────────────────────────────────────────────────────────────
+  // Dropping the grant alone leaves the policies behind, and they are NOT inert: a later
+  // re-share silently inherits the old scope. Measured — a re-granted user saw 2,121 rows
+  // instead of the whole house, with nothing on any surface explaining the filter.
+  if (flags.revoke === true) {
+    let dropped = 0;
+    for (const room of ROOM_TYPES) {
+      try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${room}`); dropped++; }
+      catch (e) { console.log(warn(`could not drop the policy on ${room}: ${e.message.split('\n')[0]}`)); }
+    }
+    try { await run(`REVOKE SELECT ON ${db}.* FROM ${user}`); }
+    catch (e) { console.log(bad(`could not revoke: ${netReason(e)}`)); return 1; }
+    await houseMeta(cfg, `share:${user}`, `revoked ${new Date().toISOString().slice(0, 10)}`);
+    console.log(ok(`revoked '${user}' — SELECT withdrawn and ${dropped} row polic${dropped === 1 ? 'y' : 'ies'} dropped`));
+    console.log('  Dropping the grant alone would have left the policies, and a later re-share');
+    console.log('  would have quietly reinherited this scope.');
+    return 0;
+  }
+
+  // ── grant ─────────────────────────────────────────────────────────────────────
+  const scopeRaw = flags.only !== undefined && flags.only !== true ? String(flags.only) : null;
+  let scope = null;
+  if (flags.only === true) { console.log(bad('--only needs a scope, e.g. --only project=memhouse or --only session=<id>')); return 1; }
+  if (scopeRaw) {
+    try { scope = share.parseScope(scopeRaw); } catch (e) { console.log(bad(e.message)); return 1; }
+  }
+
+  // A partial share only behaves if readers WITHOUT a policy still see every row. That is
+  // `users_without_row_policies_can_read_rows`, which is server config rather than a query
+  // setting and whose default has moved between versions — so measure it, do not assume.
+  if (scope) {
+    const verdict = await probePermissive(cfg, db);
+    if (verdict === false) {
+      console.log(bad('this ClickHouse hides every row from readers that have no row policy.'));
+      console.log('  Scoping one person would blindfold everyone else you have already shared with,');
+      console.log('  and yourself. Nothing was changed. Ask whoever runs the server to set:');
+      console.log('     <access_control_improvements>');
+      console.log('       <users_without_row_policies_can_read_rows>true</users_without_row_policies_can_read_rows>');
+      console.log('     </access_control_improvements>');
+      console.log('  A full share (no --only) is unaffected and works today.');
+      return 1;
+    }
+    if (verdict === null) console.log(warn('could not verify how this server treats readers without a policy — continuing'));
+  }
+
+  try { await run(`GRANT SELECT ON ${db}.* TO ${user}`); }
+  catch (e) { console.log(bad(`could not grant: ${netReason(e)}`)); return 1; }
+
+  if (!scope) {
+    // A previous partial share leaves policies that would still be filtering. Widening to
+    // a full share has to clear them or "full" is a lie.
+    let cleared = 0;
+    for (const room of ROOM_TYPES) {
+      try {
+        const had = await rows(`SELECT count() AS n FROM system.row_policies WHERE database = ${sqlStr(db)} AND short_name = ${sqlStr(share.policyName(user, room))}`);
+        if (Number(had[0] && had[0].n) > 0) { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${room}`); cleared++; }
+      } catch { /* nothing to clear */ }
+    }
+    await houseMeta(cfg, `share:${user}`, `granted ${new Date().toISOString().slice(0, 10)}`);
+    console.log(ok(`'${user}' can now read every session in '${db}'`));
+    if (cleared) console.log(warn(`cleared ${cleared} row polic${cleared === 1 ? 'y' : 'ies'} from an earlier scoped share — this is now a FULL share`));
+    console.log(`  Everything: every project, machine and editor, including anything ever pasted`);
+    console.log(`  into a session. Narrow it with:  memhouse share ${user} --only project=<name>`);
+    console.log(`  Withdraw with:                   memhouse share ${user} --revoke`);
+    return 0;
+  }
+
+  for (const room of ROOM_TYPES) {
+    const pred = share.scopePredicate(scope, room, sqlStr);
+    try { await run(`CREATE ROW POLICY OR REPLACE ${share.policyName(user, room)} ON ${db}.${room} USING ${pred} TO ${user}`); }
+    catch (e) {
+      console.log(bad(`could not scope ${room}: ${e.message.split('\n')[0]}`));
+      console.log('  PARTIALLY APPLIED — a share filtered on some rooms and not others leaks.');
+      console.log(`  Put it right with:  memhouse share ${user} --revoke`);
+      return 1;
+    }
+  }
+  await houseMeta(cfg, `share:${user}`, `granted ${new Date().toISOString().slice(0, 10)} scope=${scopeRaw}`);
+
+  // Say what they can actually reach, counted through their own filter.
+  console.log(ok(`'${user}' can read '${db}' where ${scopeRaw}`));
+  for (const room of ROOM_TYPES) {
+    try {
+      const r = await rows(`SELECT count() AS n FROM ${room} WHERE ${share.scopePredicate(scope, room, sqlStr)}`);
+      const all = await rows(`SELECT count() AS n FROM ${room}`);
+      console.log(`  ${room.padEnd(11)} ${r[0].n} of ${all[0].n} rows`);
+    } catch { /* counting is a courtesy */ }
+  }
+  console.log(`  Widen to everything:  memhouse share ${user}`);
+  console.log(`  Withdraw:             memhouse share ${user} --revoke`);
+  return 0;
+}
+
+/**
+ * Does a reader with NO row policy still see rows once a policy exists on the table?
+ *
+ * Server config decides this and SQL cannot read it, so measure: put a deny-everything
+ * policy on a scratch table aimed at everyone EXCEPT us, then read it. Rows back means
+ * unpolicied readers are unaffected. Needs no second account and no admin.
+ *
+ * true = permissive, false = restrictive, null = could not tell.
+ */
+async function probePermissive(cfg, db) {
+  const t = `_mh_probe_${process.pid}`;
+  const run = (sql) => ch(cfg, sql, { database: db });
+  try {
+    await run(`CREATE TABLE IF NOT EXISTS ${t} (x UInt8) ENGINE = MergeTree ORDER BY x`);
+    await run(`INSERT INTO ${t} VALUES (1)`, { settings: { async_insert: 0 } });
+    await run(`CREATE ROW POLICY OR REPLACE ${t}_p ON ${db}.${t} USING 0 TO ALL EXCEPT ${cfg.user}`);
+    const r = await chRows(cfg, `SELECT count() AS n FROM ${t}`, { database: db });
+    return Number(r[0] && r[0].n) === 1;
+  } catch { return null; } finally {
+    try { await run(`DROP ROW POLICY IF EXISTS ${t}_p ON ${db}.${t}`); } catch { /* nothing staged */ }
+    try { await run(`DROP TABLE IF EXISTS ${t} SYNC`); } catch { /* nothing staged */ }
+  }
+}
+
+/** Who can read this house, what they are scoped to, and any policy left behind. */
+async function shareList(cfg, share) {
+  const db = cfg.db;
+  let recorded = [];
+  try {
+    recorded = await chRows(cfg, "SELECT substring(key, 7) AS user, value AS state FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key", { database: db });
+  } catch { /* unreadable record */ }
+  let policies = [];
+  try {
+    policies = await chRows(cfg, `SELECT short_name, table, select_filter FROM system.row_policies WHERE database = ${sqlStr(db)} ORDER BY short_name`, { database: db });
+  } catch { /* members may not read system.row_policies on every server */ }
+
+  if (!recorded.length && !policies.length) {
+    console.log(ok(`nobody has been granted a read of '${db}'`));
+    console.log(`  Share it with:  memhouse share <user> [--only project=<name>]`);
+    return 0;
+  }
+  console.log(`  who can read '${db}' — memhouse's own record, not ClickHouse's grant table:`);
+  for (const r of recorded) {
+    const scoped = policies.filter((p) => String(p.short_name).startsWith(`mh_share_${r.user}_`));
+    console.log(`    ${String(r.user).padEnd(16)} ${r.state}${scoped.length ? '' : (String(r.state).startsWith('granted') ? '  (full house)' : '')}`);
+    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.');
+
+  // 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.
+  const orphans = [];
+  for (const p of policies) {
+    try {
+      const e = await chRows(cfg, `SELECT count() AS n FROM system.tables WHERE database = ${sqlStr(db)} AND name = ${sqlStr(p.table)}`, { database: db });
+      if (Number(e[0] && e[0].n) === 0) orphans.push(p);
+    } catch { /* cannot tell */ }
+  }
+  if (orphans.length) {
+    console.log('');
+    console.log(warn(`${orphans.length} row polic${orphans.length === 1 ? 'y points' : 'ies point'} at a table that no longer exists:`));
+    for (const p of orphans) console.log(`    ${p.short_name} ON ${db}.${p.table}`);
+    console.log('  Dropping a table or a house leaves its policies behind, and recreating one under');
+    console.log('  the same name silently reinherits them. Drop them:');
+    for (const p of orphans) console.log(`     DROP ROW POLICY ${p.short_name} ON ${db}.${p.table}`);
+  }
+  return 0;
+}
+
 async function cmdWhoami() {
   const cfg = resolveConfig();
   const wantAdmin = flags.admin === true;
   const au = process.env.MEMHOUSE_ADMIN_USER;
   const ap = process.env.MEMHOUSE_ADMIN_PASSWORD;
   const usingAdminEnv = wantAdmin && au;
+  // `--admin` with nothing to resolve is worth saying out loud. Silently falling back to
+  // the member credential makes `whoami --admin` and `whoami` print the same thing, and
+  // the reader is left thinking they asked a question the program never heard.
   const who = usingAdminEnv ? { ...cfg, user: au, password: ap || '' } : cfg;
 
   if (!who.url || !who.user) {
@@ -2990,10 +3257,16 @@ async function cmdWhoami() {
     console.log(JSON.stringify({
       ok: true, url: who.url, user: server, db: who.db, source, role, ...caps,
       grants_readable: grants.length > 0,
+      admin_env_present: Boolean(au),
+      admin_requested: wantAdmin,
     }, null, 2));
     return 0;
   }
   console.log(ok(`${server} at ${who.url} — ${role}`));
+  if (wantAdmin && !usingAdminEnv) {
+    console.log(warn('--admin asked for MEMHOUSE_ADMIN_USER / MEMHOUSE_ADMIN_PASSWORD; neither is set,'));
+    console.log('  so this is the ordinary configured credential.');
+  }
   console.log(`  credential from: ${source}`);
   console.log(`  house:           ${who.db || '(none set)'}`);
   console.log(`  may create users:    ${caps.canMintUsers ? 'yes' : 'no'}`);
@@ -3212,7 +3485,7 @@ async function cmdInvite() {
   console.log(`  hand it to ${name} over a channel you trust (croc, a password manager — not chat).`);
   console.log(`  they run:   memhouse install --env ${path.basename(out)}`);
   console.log(`  then they should rotate the password you now both know:  memhouse passwd`);
-  console.log(`  once installed, they are a member — sharing works both ways: /mem:share ${name}`);
+  console.log(`  once installed, they are a member — sharing works both ways: /mem:access ${name}`);
   return 0;
 }
 
@@ -3524,6 +3797,7 @@ async function cmdUninstall() {
       }
       break;
     case 'reset': process.exitCode = await cmdReset(); break;
+    case 'share': process.exitCode = await cmdShare(); break;
     case 'whoami': process.exitCode = await cmdWhoami(); break;
     case 'invite': process.exitCode = await cmdInvite(); break;
     case 'passwd': process.exitCode = await cmdPasswd(); break;

package/memhouse/delivery/AGENT-INSTALL-PROMPT.md

@@ -58,8 +58,8 @@ mark. Then tell them:
 
 - where the dashboard is (`http://localhost:{{PORT}}`) and that `memhouse start` runs it
 - that `memhouse search <terms>` searches every past session from every editor
-- that `memhouse plugins install claude` gives their agents /mem:ask, /mem:search,
-  /mem:sessions, /mem:share, /mem:sql, /mem:status, /mem:users — offer to run it
+- that `memhouse plugins install claude` gives their agents /mem:recall, /mem:sql,
+  /mem:house, /mem:access and /mem:admin — offer to run it
 - that you can now search their history yourself, and offer to try one query
 
 If `doctor` reports a failure, say which line failed and what memhouse suggested. Do not

package/memhouse/delivery/AGENT-INSTALL.md

@@ -115,8 +115,8 @@ memhouse plugins install claude
 ```
 
 Installs the memhouse plugin into `<claude-config>/skills/mem`, which loads next
-session as `mem@skills-dir` and exposes `/mem:ask`, `/mem:search`, `/mem:sessions`,
-`/mem:share`, `/mem:sql`, `/mem:status` and `/mem:users`. They read the connection from
+session as `mem@skills-dir` and exposes `/mem:recall`, `/mem:sql`, `/mem:house`,
+`/mem:access` and `/mem:admin`. They read the connection from
 `$MEMHOUSE_HOME/env` (default
 `~/.memhouse/env`), with exported `MEMHOUSE_*` vars taking precedence, and refuse to run
 rather than guessing a URL when neither is set. `memhouse plugins list` shows what is

package/memhouse/delivery/PROMPT.md

@@ -23,12 +23,18 @@ work that is not in your current context ("that session where…", "how did I so
 X before", "did we ever…", "what was I working on last week"), search memhouse
 FIRST. Only say you don't know after a search comes back empty.
 
-**How to query.** Prefer the installed skills when present: `/mem:ask` (answer a
-question from memory, with citations), `/mem:search` (full-text over messages),
-`/mem:sessions` (list/filter sessions), `/mem:sql` (free-form read-only SQL),
-`/mem:status` (what the system holds and its health), `/mem:share` and `/mem:users`
-(read-only sharing between users), `/mem:invite` (mint a new member — inviting comes
-before sharing), `/mem:hello` (introduce the system). Without skills, query directly.
+**How to query.** Prefer the installed skills when present:
+
+- `/mem:recall` — find past sessions and answer from them, with citations. This is the
+  one you want for almost every "have I seen this before" question.
+- `/mem:sql` — read-only SQL when the answer is a number: spend, model mix, tool
+  rankings, activity over time.
+- `/mem:house` — what the system is, whether it is shipping, what it holds, and who can
+  read it.
+- `/mem:access` — bring someone onto the server, or grant a housemate read-only access.
+- `/mem:admin` — server-wide administration; needs an administrator credential.
+
+Without skills, query directly.
 
 **Table names.** The house's rooms are three plain, shared tables — `messages`,
 `sessions`, `tool_calls` — in the connection's database. Everyone in the house writes
@@ -66,12 +72,12 @@ the retained epochs are the only place that content still exists.
 **Rules.**
 - Memory is READ-ONLY for you: never INSERT/ALTER/DROP the ROOMS (sessions, messages,
   tool_calls) — ingestion belongs to the memhouse shipper alone. The one exception is
-  membership administration through the `memhouse` CLI: `/mem:invite` mints a user and
-  `/mem:share` grants read access, both via the tool, not by you writing to the rooms.
+  membership administration through the `memhouse` CLI: `/mem:access` mints a user and
+  `/mem:access` grants read access, both via the tool, not by you writing to the rooms.
 - Quote retrieved content as *the user's past sessions*, and cite the session_id
   when the user may want to dig deeper.
 - Other users' HOUSES (other databases on the same server) are readable only when
-  shared with this credential (`/mem:share` on their side). Query a shared house by
+  shared with this credential (`/mem:access` on their side). Query a shared house by
   qualified names — `polat.messages` — with the same CUR filter. An empty result
   means "nothing visible", not "nothing ever happened".
 - Do not paste credentials from `{{ENV_FILE}}` into responses, commits, or logs.

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: ask, search, browse, analyze, check, share, and invite across all 17 supported editors and machines, plus administration of the ClickHouse behind it. Skills install as /mem:hello, /mem:ask, /mem:search, /mem:sessions, /mem:share, /mem:invite, /mem:sql, /mem:status, /mem:users, and /mem:admin.",
-  "version": "0.15.0",
+  "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.17.0",
   "author": {
     "name": "Ramazan Polat"
   },