memhouse 0.14.0 → 0.16.0

package/bin/memhouse.js

@@ -29,6 +29,8 @@ const {
 } = require(path.join(REPO_ROOT, 'memhouse', 'house', 'house'));
 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');
@@ -52,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;
@@ -162,6 +180,24 @@ async function ch(cfg, sql, { database = cfg.db, settings = null, timeout = 3000
   if (!res.ok) throw new Error(text.trim().split('\n')[0]);
   return text.trim();
 }
+/**
+ * The grant lines ClickHouse reports for a user, as strings.
+ *
+ * Never pass a FORMAT here — chRows appends its own, and a statement carrying two is a
+ * syntax error. That mistake once read as "no grants at all", which refused every
+ * credential including a genuine superuser, and it was invisible on any machine whose
+ * own credential is an ordinary member.
+ *
+ * Unreadable grants come back as [] rather than throwing: a credential that cannot read
+ * its own grants is, for every decision made from this, simply not an administrator.
+ */
+async function readGrants(cfg, user) {
+  try {
+    const rows = await chRows(cfg, `SHOW GRANTS FOR ${user}`, { database: '' });
+    return rows.map((r) => Object.values(r).join(' '));
+  } catch { return []; }
+}
+
 async function chRows(cfg, sql, opts) {
   const text = await ch(cfg, sql + ' FORMAT JSONEachRow', opts);
   return text ? text.split('\n').map((l) => JSON.parse(l)) : [];
@@ -363,6 +399,8 @@ 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
+             whoami               which credential is in play, and what it may do
+                                  (--json; --admin reads MEMHOUSE_ADMIN_*)
              status               daemons, connection, counts, freshness (--json)
              doctor               diagnose the whole pipeline
 
@@ -2918,6 +2956,83 @@ async function cmdNightly() {
  * transfer, and rotation (memhouse passwd) is printed because the inviter knows this
  * password until the invitee changes it.
  */
+/**
+ * `memhouse whoami [--json] [--admin]`
+ *
+ * Which credential is in play here, and what may it actually do. Exists so nothing has
+ * to hand-roll `SHOW GRANTS` and grep the result — a skill that reasons about privileges
+ * in prose gets it subtly wrong, and the wrong answer is either "you cannot" to an
+ * administrator or "go ahead" to a member who is about to hit ACCESS_DENIED.
+ *
+ * `--admin` resolves MEMHOUSE_ADMIN_USER / MEMHOUSE_ADMIN_PASSWORD first, so an agent
+ * can ask "is there an admin credential in this environment?" without inventing a place
+ * to store one. Nothing here prints or persists a password.
+ */
+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) {
+    const msg = 'no credential configured';
+    if (JSON_OUT) console.log(JSON.stringify({ ok: false, reason: msg }, null, 2));
+    else {
+      console.log(bad(`${msg} — nothing in ${short(ENV_FILE)} and no MEMHOUSE_URL/MEMHOUSE_USER set.`));
+      if (wantAdmin) console.log('  For --admin, export MEMHOUSE_ADMIN_USER and MEMHOUSE_ADMIN_PASSWORD.');
+    }
+    return 1;
+  }
+
+  let server = null;
+  try { server = (await chRows(who, 'SELECT currentUser() AS u', { database: '' }))[0]?.u; }
+  catch (e) {
+    const reason = netReason(e);
+    if (JSON_OUT) console.log(JSON.stringify({ ok: false, url: who.url, user: who.user, reason }, null, 2));
+    else console.log(bad(`cannot reach ${who.url} as '${who.user}': ${reason}`));
+    return 1;
+  }
+
+  const grants = await readGrants(who, server);
+  const caps = capabilitiesFrom(grants);
+  const source = usingAdminEnv ? 'MEMHOUSE_ADMIN_* environment'
+    : (process.env.MEMHOUSE_USER ? 'MEMHOUSE_* environment' : short(ENV_FILE));
+  const role = caps.isSuperuser ? 'administrator'
+    : caps.canProvision ? 'can provision (users and houses)'
+      : 'member';
+
+  if (JSON_OUT) {
+    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'}`);
+  console.log(`  may create houses:   ${caps.canMintHouses ? 'yes' : 'no'}`);
+  console.log(`  may read any house:  ${caps.canReadEveryHouse ? 'yes' : 'no'}`);
+  if (!grants.length) console.log(warn('could not read its own grants — treating it as a member'));
+  if (!caps.canProvision) {
+    console.log('  Inviting and server-wide administration need an administrator; this is not one.');
+    console.log('  Supply one for this shell:  export MEMHOUSE_ADMIN_USER=… MEMHOUSE_ADMIN_PASSWORD=…');
+  }
+  return 0;
+}
+
 async function cmdInvite() {
   const name = positional[0];
   if (!name) { console.log('usage: memhouse invite <name> --url <house-url> [--admin-user … [--admin-password …]] [--db <house>] [--out <file>] [--adopt] [--print-sql]'); return 2; }
@@ -2998,20 +3113,11 @@ async function cmdInvite() {
       console.log('  before inviting, or use --print-sql and let the invitee be told the address.');
       return 1;
     }
-    let grants = '';
-    try {
-      const g = await chRows({ ...c, url }, `SHOW GRANTS FOR ${c.user}`, { database: '' });
-      grants = g.map((r) => Object.values(r).join(' ')).join('\n');
-    } catch { /* reachable but grants unreadable — treated as "not an admin" below */ }
-    // Two capabilities, and a superuser states them in more than one shape: CREATE USER
-    // may arrive as itself or under ACCESS MANAGEMENT, and the database half may be an
-    // explicit CREATE DATABASE or the umbrella CREATE on *.* — which is what
-    // `deploy --local` grants. Match the meaning, not one spelling.
-    const canMintUsers = /\bACCESS MANAGEMENT\b|\bCREATE USER\b/.test(grants);
-    const canMintHouses = /\bCREATE DATABASE\b/.test(grants)
-      || grants.split('\n').some((l) => /\bCREATE\b/.test(l) && /\bON \*\.\*/.test(l));
-    const canProvision = canMintUsers && canMintHouses;
-    if (canProvision) {
+    // What this credential may do, judged from its own grants and SCOPE-AWARE — a member
+    // holds CREATE DATABASE inside `ON <their-db>.*`, which mints no new house at all.
+    // Shared with `whoami` so the two can never disagree about who is an administrator.
+    const caps = capabilitiesFrom(await readGrants({ ...c, url }, c.user));
+    if (caps.canProvision) {
       adminUser = c.user; adminPass = c.password;
       console.log(ok(`inviting as your own credential '${c.user}' (it can create users and houses here)`));
     } else {
@@ -3444,6 +3550,7 @@ async function cmdUninstall() {
       }
       break;
     case 'reset': process.exitCode = await cmdReset(); break;
+    case 'whoami': process.exitCode = await cmdWhoami(); break;
     case 'invite': process.exitCode = await cmdInvite(); break;
     case 'passwd': process.exitCode = await cmdPasswd(); break;
     case 'nightly': process.exitCode = await cmdNightly(); break;

package/memhouse/capabilities.js

@@ -0,0 +1,75 @@
+// What a ClickHouse credential may actually DO, read from its own grants.
+//
+// This exists because asking the wrong question here is expensive and quiet. `invite`
+// used to probe with `SELECT 1 FROM system.users`: since 0.12.6 every member holds
+// SHOW USERS, so every member passed, was told it could manage users, and then died at
+// CREATE DATABASE with a raw ACCESS_DENIED. The replacement must be exact, and it must
+// live in one place — invite and /mem:admin disagreeing about who is an administrator is
+// the same class of bug wearing a different hat.
+//
+// SCOPE IS THE WHOLE POINT. A grant is `GRANT <privileges> ON <scope> TO <user>`, and a
+// privilege only means what its scope allows: an ordinary member holds CREATE DATABASE
+// inside `ON polat.*`, which lets them do nothing whatsoever about creating a NEW
+// database. Matching the privilege name anywhere in the text — which an earlier draft of
+// this did — reads that member as a server administrator. So parse the line, keep the
+// scope, and only count a privilege that is granted server-wide.
+
+/** `GRANT a, b, c ON scope TO user [WITH GRANT OPTION]` -> {privs:[…], scope} | null */
+function parseGrantLine(line) {
+  const m = /^\s*GRANT\s+(.+?)\s+ON\s+(\S+)\s+TO\s+/i.exec(String(line || ''));
+  if (!m) return null;
+  const privs = m[1].split(',').map((p) => p.trim().toUpperCase()).filter(Boolean);
+  return { privs, scope: m[2] };
+}
+
+/** Server-wide scope: `*.*` (tables everywhere) or `*` (the access/user namespace). */
+function isServerWide(scope) {
+  return scope === '*.*' || scope === '*';
+}
+
+function hasPriv(privs, name) {
+  return privs.includes(name);
+}
+
+/**
+ * Derive capabilities from the lines `SHOW GRANTS FOR <user>` returned.
+ *
+ * @param {string[]|string} grants  one string per grant line, or the whole blob
+ * @returns {{canMintUsers:boolean, canMintHouses:boolean, canProvision:boolean,
+ *            canReadEveryHouse:boolean, canSeeUsers:boolean, isSuperuser:boolean}}
+ */
+function capabilitiesFrom(grants) {
+  const lines = Array.isArray(grants) ? grants : String(grants || '').split('\n');
+  let canMintUsers = false;
+  let canMintHouses = false;
+  let canReadEveryHouse = false;
+  let canSeeUsers = false;
+
+  for (const raw of lines) {
+    const g = parseGrantLine(raw);
+    if (!g) continue;
+    const wide = isServerWide(g.scope);
+    // SHOW USERS is the one every member has — never evidence of anything.
+    if (hasPriv(g.privs, 'SHOW USERS')) canSeeUsers = true;
+    if (!wide) continue;
+    // Minting accounts. ACCESS MANAGEMENT is the umbrella; CREATE USER the specific.
+    if (hasPriv(g.privs, 'ACCESS MANAGEMENT') || hasPriv(g.privs, 'CREATE USER')) canMintUsers = true;
+    // Minting houses. `CREATE DATABASE` is the specific; bare `CREATE` is the umbrella
+    // ClickHouse hands a superuser (what `deploy --local` grants), and `ALL` covers both.
+    if (hasPriv(g.privs, 'CREATE DATABASE') || hasPriv(g.privs, 'CREATE') || hasPriv(g.privs, 'ALL')) canMintHouses = true;
+    // Reading anyone's rooms — what separates an administrator's view from a member's.
+    if (hasPriv(g.privs, 'SELECT') || hasPriv(g.privs, 'ALL')) canReadEveryHouse = true;
+  }
+
+  const canProvision = canMintUsers && canMintHouses;
+  return {
+    canMintUsers,
+    canMintHouses,
+    canProvision,
+    canReadEveryHouse,
+    canSeeUsers,
+    isSuperuser: canProvision && canReadEveryHouse,
+  };
+}
+
+module.exports = { capabilitiesFrom, parseGrantLine, isServerWide };

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

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

@@ -1,6 +1,6 @@
 ---
 name: admin
-description: Operate the memhouse ClickHouse as its administrator — list and inspect every user and house, provision or remove members, grant and revoke access, and read server-wide health (disk, parts, mutations, running queries). Use when the user asks to "do X as admin", "manage users", "drop a house", "see disk usage", "who is on this server", or when a member-scoped skill refused for want of privileges. Requires an admin credential; says so plainly when there is not one.
+description: Operate the memhouse ClickHouse as its administrator — list and inspect every user and house, provision or remove members, grant and revoke access, and read server-wide health (disk, parts, mutations, running queries). Use when the user asks to "do X as admin", "manage users", "drop a house", "see disk usage", "who is on this server", or when a member-scoped skill refused for want of privileges. Requires an administrator credential in the environment; says so plainly, and how to supply one, when there is not.
 user-invocable: true
 argument-hint: "<what you want done>"
 allowed-tools: Bash
@@ -12,61 +12,61 @@ A member owns one database. An **administrator** owns the ClickHouse: every hous
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 
-Everything here runs through the same rule as `/mem:invite`: **an admin password must
-never enter this conversation.** memhouse ships this transcript into the house you are
-administering, so a password pasted in chat is a password published to the archive.
-Resolve it from the environment or a file, never from a prompt, and never echo it.
+**An admin password must never enter this conversation.** memhouse ships this transcript
+into the house you are administering, so a password pasted here is a password published
+to the archive — and unlike a file you can delete, the archive is insert-only. Resolve
+the credential from the environment or refuse. Never ask for one in chat, never echo one,
+never write one to a file.
 
-## 1. Find an admin credential — never ask for one in chat
-
-Try these in order and stop at the first that works. **Never print any of these files or
-the variables in them** — no `cat`, no `env | grep`, no `set -x`.
-
-```bash
-MH_HOME="${MEMHOUSE_HOME:-$HOME/.memhouse}"
-# a) an explicit admin credential in the environment
-ADM_U=${MEMHOUSE_ADMIN_USER-}; ADM_P=${MEMHOUSE_ADMIN_PASSWORD-}
-# b) an admin env file kept beside the member config
-if [ -z "$ADM_U" ] && [ -f "$MH_HOME/admin.env" ]; then
-  set -a; . "$MH_HOME/admin.env"; set +a
-  ADM_U=${MEMHOUSE_ADMIN_USER:-${MEMHOUSE_USER-}}; ADM_P=${MEMHOUSE_ADMIN_PASSWORD:-${MEMHOUSE_PASSWORD-}}
-fi
-# c) the ordinary member credential — on a house the pilot stood up themselves
-#    (memhouse deploy --local) the member IS the superuser
-set -a; [ -f "$MH_HOME/env" ] && . "$MH_HOME/env"; set +a
-: "${ADM_U:=${MEMHOUSE_USER-}}"; : "${ADM_P:=${MEMHOUSE_PASSWORD-}}"
-```
-
-Then **prove** it is actually an admin rather than assuming — a member can often read
-`system.users` while holding nothing else:
+## 1. Ask the CLI what you are holding — do not work it out yourself
 
 ```bash
-curl -sS --fail-with-body --user "$ADM_U:$ADM_P" \
-  --data-binary "SHOW GRANTS FOR $ADM_U FORMAT TSV" "$MEMHOUSE_URL/"
+memhouse whoami --admin --json
 ```
 
-Admin means the grants carry `ACCESS MANAGEMENT`, or `CREATE USER`/`CREATE DATABASE` at
-`*.*` — not merely `SHOW USERS`, which every member has. If none of a/b/c qualifies,
-**stop and say so**:
-
-> This needs administrator access to the ClickHouse at `<url>`, and the credential
-> configured here is the member account `<user>` — it owns its own house and nothing
-> else. To use `/mem:admin`, put an admin credential in `~/.memhouse/admin.env`
-> (`MEMHOUSE_ADMIN_USER=` / `MEMHOUSE_ADMIN_PASSWORD=`, mode 600) or export
-> `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD`, then ask again. Whoever operates
-> the server has it; on a house from `memhouse deploy --local` it is the account already
-> in `~/.memhouse/env`.
-
-Do not offer to carry on with reduced powers, do not suggest the user paste a password
-into the chat, and do not improvise around the refusal. Say which of a/b/c you tried.
-
-## 2. Run the request
-
-Use the resolved credential for every query. `--fail-with-body` so ClickHouse's own error
-is visible; add `&readonly=1` on anything that only reads.
+That resolves `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD` when they are set and
+falls back to the configured credential, then reports what it may actually do. Read
+`role` and the capability flags; never infer privileges from a grant string yourself.
+The command prints no password.
+
+- **`"canProvision": true`** (or `"role": "administrator"`) — you have an administrator.
+  Go to §2.
+- **`"canProvision": false`** — the credential is a member. **Stop.** Do not retry, do
+  not look for a stored password, and do not ask for one. Tell the user:
+
+  > `/mem:admin` needs an administrator credential for `<url>`, and what is configured
+  > here is the member account `<user>` — it owns its own house and nothing else. If you
+  > administer that ClickHouse, put the credential in this shell's environment and ask
+  > again:
+  >
+  > ```
+  > export MEMHOUSE_ADMIN_USER=default
+  > read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD
+  > ```
+  >
+  > `read -rs` keeps it off the screen and out of your shell history. It lives only in
+  > that shell — nothing is written to disk, and memhouse never stores it.
+  >
+  > If somebody else administers the server, this is theirs to run, not yours.
+
+- **`"ok": false`** — a connection problem, not a privilege one. Report `reason` as
+  given; do not translate it into "you are not an admin".
+
+**Never suggest storing the credential** — not in `~/.memhouse/env`, not in an
+`admin.env`, not anywhere on disk. An admin credential owns the whole server, and every
+process running as this user can read a file. The environment of one shell is the whole
+supported surface. (A house from `memhouse deploy --local` is the exception that needs
+nothing: its member *is* the superuser, and `whoami` will already say so.)
+
+## 2. Do the work
+
+Use the same environment for every query. `--fail-with-body` so ClickHouse's own error is
+visible; `&readonly=1` on anything that only reads.
 
 ```bash
-adm() { curl -sS --fail-with-body --user "$ADM_U:$ADM_P" --data-binary "$1" "$MEMHOUSE_URL/${2-}"; }
+adm() { curl -sS --fail-with-body \
+  --user "$MEMHOUSE_ADMIN_USER:$MEMHOUSE_ADMIN_PASSWORD" \
+  --data-binary "$1" "$MEMHOUSE_URL/${2-}"; }
 adm "SELECT …  FORMAT PrettyCompact" "?readonly=1"
 ```
 
@@ -74,21 +74,19 @@ Reads worth knowing — reach for these before inventing SQL:
 
 | Question | Query |
 |---|---|
-| who exists | `SELECT name FROM system.users ORDER BY name` |
-| what can someone do | `SHOW GRANTS FOR <user>` |
+| who exists | `SELECT name, storage FROM system.users ORDER BY name` |
+| what someone may do | `SHOW GRANTS FOR <user>` |
 | every house and its size | `SELECT database, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows FROM system.parts WHERE active GROUP BY database ORDER BY sum(bytes_on_disk) DESC` |
 | a house's rooms | `SELECT table, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows FROM system.parts WHERE active AND database = '<db>' GROUP BY table` |
 | who writes where | `SELECT user_id, host, count() FROM <db>.messages GROUP BY user_id, host` |
 | running queries | `SELECT query_id, user, elapsed, formatReadableSize(memory_usage) AS mem, substring(query,1,120) AS q FROM system.processes` |
 | unfinished mutations | `SELECT database, table, mutation_id, command, parts_to_do, latest_fail_reason FROM system.mutations WHERE NOT is_done` |
-| merge backlog | `SELECT database, table, elapsed, progress FROM system.merges` |
 
-Writes follow the shapes memhouse itself uses, so an admin-made member is identical to an
-invited one — a member gets `GRANT ALL ON <db>.* … WITH GRANT OPTION`, plus `SHOW USERS`,
-self-scoped `ALTER USER`, `REMOTE`, and the async-insert pin. **Prefer the CLI over raw
-SQL when one exists**: `memhouse invite <name> --url …` provisions a member correctly
-(and refuses a house that already holds someone's messages); this skill is for the things
-it does not cover.
+**Prefer a CLI verb over raw SQL wherever one exists.** `memhouse invite <name> --url …`
+provisions a member correctly — right grants, right pin, refuses a house that already
+holds someone's messages — and it takes `--admin-user`/`--admin-password`, so it works
+from this environment. Hand-written `CREATE USER` skips every one of those guards. This
+skill is for what no verb covers.
 
 ## 3. Destructive work — look first, then confirm
 
@@ -99,30 +97,33 @@ editors that produced them.
 
 Before any of them:
 
-1. **Look at the target and report what is actually there** — row counts per room, who
+1. **Look at the target and report what is really there** — row counts per room, who
    wrote them, the date span, which machines. A house you expected to be empty may not
-   be.
+   be: one `ege` house looked disposable and held 3,733 messages belonging to somebody
+   else entirely.
 2. **Name the collateral.** Dropping a user stops that account's shipper on every machine
-   it runs on. Revoking a grant closes a share the other person may be mid-query on.
-   Rotating a password breaks every machine shipping under it.
-3. **Get an explicit yes for that specific object**, quoting the counts you just read.
-   A general "yes do admin things" is not consent to drop a populated house.
-4. **Verify afterwards** and say what is now true.
+   it runs on. Revoking a grant closes a share someone may be mid-query on. Rotating a
+   password breaks every machine shipping under it — and grants are per-user while the
+   fleet is per-`user@host`, so there is no way to revoke one machine.
+3. **Get an explicit yes for that specific object**, quoting the counts you just read. A
+   general "yes, do admin things" is not consent to drop a populated house.
+4. **Verify afterwards** and say what is now true, including what was destroyed.
 
 If the user has already told you exactly what to destroy and why, and the counts match
-their description, proceed — do not re-litigate a decision they have made. Report the
-outcome plainly, including the row counts destroyed.
+their description, proceed — do not re-litigate a decision they have made.
 
 ## Never
 
 Never accept an admin password typed into the conversation, and never print one — not in
-a command, not in an echo, not in an error. If a command needs it, expand a shell
-variable (`--admin-password "$ADM_P"`), so the value never appears in the transcript.
+a command, not in an echo, not in an error. Commands expand `"$MEMHOUSE_ADMIN_PASSWORD"`;
+the value never appears as literal text.
+
+Never recommend writing an admin credential to disk.
 
-Never widen a member's grants beyond what `memhouse invite` issues without the user
-asking for that specific privilege and being told what it allows. Never grant
-`ACCESS MANAGEMENT`, `CREATE USER`, or anything at `*.*` casually — those make a second
+Never widen a member's grants beyond what `memhouse invite` issues unless the user asks
+for that specific privilege and has been told what it allows. Never grant `ACCESS
+MANAGEMENT`, `CREATE USER`, or anything at `*.*` casually — those mint a second
 administrator.
 
-Never touch a house that is not the subject of the request. Never run a destructive
+Never touch a house that is not the subject of the request, and never run a destructive
 statement whose predicate you have not first run as a `SELECT`.

package/memhouse/flags.js

@@ -0,0 +1,76 @@
+// Which options each command takes, and what to say when one is not among them.
+//
+// Anything `--like-this` used to be accepted and ignored. That is quiet in the good case
+// and dangerous in the bad one: `--dryrun` for `--dry-run` does not warn, it RUNS the
+// migration; `--adopt` on a build that predates the guard is swallowed and the invite
+// proceeds into somebody else's house. A flag the program does not know is a sentence
+// the user believes they said and the program never heard.
+//
+// The tables live here rather than beside the parser so a test can hold them against the
+// flags the CLI actually reads — a flag added to one and not the other fails the suite
+// instead of being discovered by whoever typed it.
+
+const GLOBAL_FLAGS = ['json', 'yes', 'help', 'version'];
+
+const COMMAND_FLAGS = {
+  null: [], help: [], version: [],
+  whoami: ['admin'],
+  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [],
+  status: [], start: [],
+  onboard: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'target', 'house-port', 'tag', 'local'],
+  install: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'env', 'print-sql', 'member',
+    'member-password', 'admin-user', 'admin-password', 'ensure-schema', 'rotate-password', 'force'],
+  setup: ['url', 'user', 'password', 'db', 'port'],
+  ship: ['full', 'loop', 'ensure-schema'],
+  search: ['limit'],
+  resume: [],
+  update: ['check', 'migrate', 'no-install'],
+  reset: ['all-origins'],
+  invite: ['url', 'db', 'out', 'admin-user', 'admin-password', 'adopt', 'print-sql',
+    'allow-local', 'member-password'],
+  passwd: ['password', 'admin-user', 'admin-password', 'print-sql', 'member'],
+  nightly: ['out'],
+  migrate: ['dry-run'], 'migrate-rooms': ['dry-run'],
+  relocate: ['to', 'to-user', 'to-password', 'to-db', 'from-native-host', 'from-native-port',
+    'insecure-native', 'keep-shipper', 'dry-run'],
+  deploy: ['local', 'down', 'house-port', 'port', 'tag'],
+  service: ['interval'],
+  uninstall: ['credentials', 'full-removal'],
+  plugins: ['target'],
+  prompt: ['install'],
+};
+
+/** Levenshtein, small and local — this is the only caller. */
+function editDistance(a, b) {
+  const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) m[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return m[a.length][b.length];
+}
+
+/** The flag a typo most likely meant, or null when nothing is close enough to guess. */
+function suggestFlag(bad, allowed) {
+  let best = null; let bd = Infinity;
+  for (const c of allowed) { const d = editDistance(bad, c); if (d < bd) { bd = d; best = c; } }
+  return bd <= Math.max(2, Math.floor(bad.length / 3)) ? best : null;
+}
+
+/** Every option this command does not take. Unknown COMMANDS return [] — dispatch owns that. */
+function unknownFlags(cmd, flags) {
+  const known = COMMAND_FLAGS[cmd === null || cmd === undefined ? 'null' : cmd];
+  if (known === undefined) return [];
+  const allowed = allowedFlags(cmd);
+  return Object.keys(flags).filter((f) => !allowed.has(f));
+}
+
+/** The full accepted set for a command, globals included. */
+function allowedFlags(cmd) {
+  const known = COMMAND_FLAGS[cmd === null || cmd === undefined ? 'null' : cmd] || [];
+  return new Set([...GLOBAL_FLAGS, ...known]);
+}
+
+module.exports = { GLOBAL_FLAGS, COMMAND_FLAGS, unknownFlags, allowedFlags, suggestFlag, editDistance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhouse",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "memhouse \u2014 agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, kernel-agency install, and the agentlytics dashboard",
   "main": "bin/memhouse.js",
   "bin": {