memhouse 0.18.9 → 0.18.11

package/bin/memhouse.js

@@ -42,17 +42,7 @@ const LOG_DIR = path.join(HOME_DIR, 'logs');
 const argv = process.argv.slice(2);
 const cmd = argv[0] && !argv[0].startsWith('-') ? argv[0] : null;
 const rest = cmd ? argv.slice(1) : argv;
-const flags = {};
-const positional = [];
-for (let i = 0; i < rest.length; i++) {
-  const a = rest[i];
-  if (a.startsWith('--')) {
-    const key = a.slice(2);
-    const next = rest[i + 1];
-    if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; }
-    else flags[key] = true;
-  } else positional.push(a);
-}
+const { flags, positional } = require(path.join(REPO_ROOT, 'memhouse', 'flags')).parseArgv(rest);
 const JSON_OUT = flags.json === true;
 
 // Unknown flags stop the run — see memhouse/flags.js for why a shrug is not enough.
@@ -147,7 +137,7 @@ function requireConfig(cfg, what) {
 }
 
 function childEnv(cfg, override = {}) {
-  return {
+  const env = {
     ...process.env,
     // Set only by the install path, which prints its own refusal for this case.
     ...(cfg._quietDenied ? { MEMHOUSE_QUIET_DENIED: '1' } : {}),
@@ -159,6 +149,11 @@ function childEnv(cfg, override = {}) {
       // environment would write into another member's rooms.
     ...override,
   };
+  // A daemon never needs the admin credential. Inherited from an exported shell variable
+  // it would sit in the shipper's and dashboard's environment for their whole lifetime.
+  delete env.MEMHOUSE_ADMIN_USER;
+  delete env.MEMHOUSE_ADMIN_PASSWORD;
+  return env;
 }
 
 function writeEnvFile(cfg) {
@@ -336,6 +331,22 @@ async function ask(question, dflt) {
 // reason in .cause. `✗ not connected: fetch failed` names neither the host nor the problem,
 // while `ship` prints ECONNREFUSED for the identical condition — the three commands
 // disagreed about the same event.
+// Is `url` an HTTP endpoint that answers at all? ClickHouse's /ping needs no credential, so
+// this checks an address without sending one. Any HTTP response counts — a proxy that
+// wants auth on every path still proves the address is reachable.
+async function pingUrl(url) {
+  let target;
+  try { target = new URL('ping', String(url).endsWith('/') ? String(url) : `${url}/`); }
+  catch { return { ok: false, reason: 'not a URL' }; }
+  try {
+    await fetch(target, { signal: AbortSignal.timeout(8000), redirect: 'manual' });
+    return { ok: true };
+  } catch (e) {
+    const c = e && e.cause && (e.cause.code || e.cause.message);
+    return { ok: false, reason: c || (e && e.name === 'TimeoutError' ? 'timed out' : String(e && e.message || e)) };
+  }
+}
+
 function netReason(e) {
   const cause = e && e.cause;
   const inner = cause && (cause.message || cause.code);
@@ -349,6 +360,36 @@ function netReason(e) {
 // Read without echoing. `onboard` and `setup` both prompt for the house password and
 // printed it back on the terminal — in a wizard whose whole audience is someone typing a
 // credential in front of whoever is in the room.
+// The admin password for `adminUser`: --admin-password-file (or - for stdin), then
+// --admin-password (warned), then MEMHOUSE_ADMIN_PASSWORD, then the stored credential
+// of that SAME admin, then a TTY prompt. null = none, and the caller has been told how
+// to give one without putting it on the command line. See memhouse/admin-secret.js.
+async function adminPasswordFor(adminUser, out = {}) {
+  const as = require(path.join(REPO_ROOT, 'memhouse', 'admin-secret'));
+  const file = readEnvFile();
+  let r;
+  try {
+    r = as.resolveAdminPassword({
+      adminUser, flags, stored: { user: file.MEMHOUSE_ADMIN_USER, password: file.MEMHOUSE_ADMIN_PASSWORD },
+    });
+  } catch (e) { console.log(bad(e.message)); return null; }
+  // stderr: `members --json` and friends must emit nothing but JSON on stdout.
+  if (r.source === 'flag') console.error(warn(as.ARGV_WARNING));
+  out.source = r.source;
+  if (r.password !== undefined) return r.password;
+  if (process.stdin.isTTY) {
+    const p = await askSecret(`  password for '${adminUser}'`);
+    out.source = 'prompt';
+    if (p) return p;
+    console.log(bad('no password given'));
+    return null;
+  }
+  const lines = as.missingAdminPasswordHelp(adminUser);
+  console.log(bad(lines[0]));
+  for (const l of lines.slice(1)) console.log(l);
+  return null;
+}
+
 function askSecret(label, dflt = '') {
   if (!process.stdin.isTTY) return ask(label, dflt);
   return new Promise((resolve) => {
@@ -414,22 +455,23 @@ memhouse ${PKG.version} — agent conversation memory across 17 editors
 Setup        onboard              interactive wizard: discover → configure → ship → start
              install              scriptable setup (--url --user --password --db [--yes] [--no-ship])
                                   --print-sql            print the SQL, run it yourself
-                                  with admin: --admin-user --admin-password [--member NAME]
-                                  builds house + user + rooms + grants, then verifies as
-                                  the member. The admin credential IS written to the env
-                                  file (mode 600) so invite/members need no flags; delete
-                                  those two lines if you would rather pass it each time.
+                                  with admin: --admin-user NAME [--member NAME] builds the
+                                  member + grants, then verifies as the member. The admin
+                                  password comes from MEMHOUSE_ADMIN_PASSWORD (with-secret),
+                                  --admin-password-file FILE|- (stdin), or a prompt; plain
+                                  --admin-password works but shows in ps/history. It is NOT
+                                  saved unless --keep-admin (then invite needs no flags).
                                   --env FILE installs from an invite file (see: invite)
              invite <name>        mint a member and write the env file their install needs
-                                  (--url [--db NAME] [--out FILE]; --admin-user and
-                                  --admin-password only if this install keeps no admin
+                                  (--url [--db NAME] [--out FILE]; --admin-user — password
+                                  as for install — only if this install keeps no admin
                                   credential). They get rooms named for them, <db>.<name>_*,
                                   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.
              passwd               rotate this member's password + rewrite the env file
-                                  (admin-assisted: --admin-user --admin-password)
+                                  (admin-assisted: --admin-user, password as for install)
              setup                (re)write the connection config only (--yes = no prompts)
              discover             read-only preflight: editors, sessions, reachable ClickHouses
              uninstall            stop daemons + service, clear runtime state (asks; --yes).
@@ -752,10 +794,33 @@ function generatePassword() {
  * hand produces exactly what `--admin-user` would have produced. It is rendered from the
  * same templates provision.js applies, so the two cannot drift into different houses.
  */
-function memberSql(db, member, password) {
-  // The SAME plan adminBootstrap executes, rendered. Not a second description of it.
+function memberSql(db, member) {
+  // The SAME plan adminBootstrap executes, rendered. Not a second description of it — except
+  // the password: a printed plan carries a placeholder, never a real one (G23). Printed SQL
+  // lands in terminals, scrollback and agent transcripts, and memhouse ships transcripts.
   const { plan, render } = require(path.join(REPO_ROOT, 'memhouse', 'provision'));
-  return render(plan({ db, member, password }), { db, member });
+  return render(plan({ db, member, placeholder: true }), { db, member });
+}
+
+// The handoff lines that follow a printed plan: an env file for the member, with the
+// password left as the placeholder the plan used. `invite` marks it MEMHOUSE_INVITE=1, so
+// the member's `install --env` offers to rotate it to one only they know.
+function handoffLines({ url, db, member, invite }) {
+  const { PASSWORD_PLACEHOLDER } = require(path.join(REPO_ROOT, 'memhouse', 'provision'));
+  const lines = [
+    `-- Then put these lines in a file (mode 600), with the same password where ${PASSWORD_PLACEHOLDER}`,
+    '-- stands, and hand it over a channel you trust (croc, a password manager) — not chat:',
+    `--   MEMHOUSE_URL='${url}'`,
+    `--   MEMHOUSE_USER='${member}'`,
+    `--   MEMHOUSE_PASSWORD='${PASSWORD_PLACEHOLDER}'`,
+    `--   MEMHOUSE_DB='${db}'`,
+  ];
+  if (invite) lines.push('--   MEMHOUSE_INVITE=1');
+  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.');
+  }
+  return lines.join('\n');
 }
 
 /**
@@ -813,17 +878,13 @@ async function adminBootstrap(cfg, admin) {
   } else {
     if (!password) {
       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:access, in a transcript
-      // memhouse itself ships. admin.quiet is the invite path.
-      if (!admin.quiet) {
-        console.log('');
-        console.log(`  password for '${admin.member}':  ${password}`);
-        console.log(`  Shown once. It goes into ${ENV_FILE}; to change it later:`);
-        console.log(`     ALTER USER ${admin.member} IDENTIFIED BY '…'   then: memhouse setup --password …`);
-        console.log('');
-      }
+      // Never printed, on any path (G23). It used to be shown once on an install, "the
+      // user's only copy" — but install writes it to the env file, and an invite to the
+      // credential file, so the terminal never needed it. What the terminal gets ends up in
+      // scrollback and, via /mem:access and /mem:admin, in a transcript memhouse itself
+      // ships into the house. A run that fails before the password is written down drops
+      // the user it created (below), so no account is left behind with a password nobody
+      // holds.
     }
     try { await q(`CREATE USER ${admin.member} IDENTIFIED BY '${password.replace(/'/g, "\\'")}'`, { database: '' }); }
     catch (e) {
@@ -869,9 +930,15 @@ async function adminBootstrap(cfg, admin) {
   } catch (e) {
     console.log(bad(`could not grant the house to '${admin.member}': ${e.message}`));
     if (createdUser) {
-      console.log(`  ClickHouse user '${createdUser}' WAS created before this failed.`);
-      console.log(`  Continue once fixed:  memhouse install --member ${createdUser} --member-password '<the password above>' …`);
-      console.log(`  Or undo it as the admin:  DROP USER ${createdUser}`);
+      // This run made the user and nobody holds its password (it is never printed), so the
+      // only useful state is "not there": drop it, and the same command can simply be re-run.
+      try {
+        await q(`DROP USER IF EXISTS ${createdUser}`, { database: '' });
+        console.log(`  the ClickHouse user '${createdUser}' this run created was dropped — fix the cause and re-run`);
+      } catch (e2) {
+        console.log(`  ClickHouse user '${createdUser}' WAS created and could not be dropped (${String(e2.message).split('\n')[0]}).`);
+        console.log(`  Undo it as the admin:  DROP USER ${createdUser}   — then re-run.`);
+      }
     } else {
       console.log('  nothing was written');
     }
@@ -1029,6 +1096,7 @@ async function cmdInstall({ interactive }) {
   }
   let cfg = resolveConfig();
   const adminUser = flags['admin-user'];
+  if (adminUser === true) { console.log(bad('--admin-user needs a name, e.g. --admin-user default')); return 1; }
 
   // The house name is spliced unquoted into CREATE DATABASE and GRANT ALL ON <db>.* —
   // validate it HERE, on every install mode, not only where deploy happens to choose it.
@@ -1046,17 +1114,11 @@ async function cmdInstall({ interactive }) {
   if (flags['print-sql'] === true) {
     const member = resolveMemberHandle();
     if (!member) return 1;
-    const password = flags['member-password'] || generatePassword();
-    console.log(memberSql(cfg.db, member, password));
-    console.log(`-- Then, once that has run:`);
+    console.log(memberSql(cfg.db, member));
     // Only echo a URL that was actually STATED. --print-sql is the path where the house is
     // typically someone else's, run by someone else, and cfg.url falls back to
     // http://localhost:8123 — the one address the rest of the product refuses to guess.
-    // Handing it back as a copy-paste command carrying a live credential is worse than
-    // leaving a placeholder.
-    console.log(cfg.stated
-      ? `--   memhouse install --url ${cfg.url} --db ${cfg.db} --user ${member} --password '${password}'`
-      : `--   memhouse install --url <the house this SQL was run on> --db ${cfg.db} --user ${member} --password '${password}'`);
+    console.log(handoffLines({ url: cfg.stated ? cfg.url : '<the house this SQL was run on>', db: cfg.db, member, invite: false }));
     return 0;
   }
 
@@ -1064,11 +1126,22 @@ async function cmdInstall({ interactive }) {
   if (adminUser) {
     const member = resolveMemberHandle();
     if (!member) return 1;
+    // From a file, stdin, the environment or a prompt — never REQUIRED on argv.
+    const adminPassword = await adminPasswordFor(String(adminUser));
+    if (adminPassword === null) return 1;
     const built = await adminBootstrap(cfg, {
-      user: adminUser, password: flags['admin-password'] || '', member,
+      user: adminUser, password: adminPassword, member,
     });
     if (!built) return 1;
-    cfg = built;
+    // The admin credential is used for this install and NOT saved, unless asked
+    // (--keep-admin) or this env file already keeps that same admin (an operator seat).
+    // It used to be saved every time, which the help said and every agent-facing text
+    // (the install prompt, invite's own advice, /mem:admin) contradicted — and a saved
+    // admin password ends up wherever the env file goes.
+    const keepAdmin = flags['keep-admin'] === true || readEnvFile().MEMHOUSE_ADMIN_USER === String(adminUser);
+    cfg = keepAdmin
+      ? { ...built, adminUser: String(adminUser), adminPassword }
+      : { ...built, adminUser: '', adminPassword: '' };
   // BEFORE the env file and BEFORE the ship. INSTALL.md's contract is that the config is
   // written last, "after everything above has proved out", because a config left by a
   // failed install is read as truth by the next command. Placed after the write, a
@@ -1099,8 +1172,13 @@ async function cmdInstall({ interactive }) {
       console.log(`  every machine you install as '${cfg.user}' writes into the same rooms; this is what tells them apart`);
     }
     console.log(ok('installed'));
-    console.log('  adding a housemate later — the admin credential is in your env file, so no flags:');
-    console.log(`     memhouse invite <name> --url ${cfg.url}`);
+    if (cfg.adminUser) {
+      console.log('  adding a housemate later — the admin credential is kept in your env file, so no flags:');
+      console.log(`     memhouse invite <name> --url ${cfg.url}`);
+    } else {
+      console.log(`  the admin credential was used for this install and not saved. To invite later:`);
+      console.log(`     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite <name> --url ${cfg.url} --admin-user ${adminUser}`);
+    }
     printGettingStarted(cfg);
     await finishInvite(cfg);
     // The first ship loads the whole backlog; do it in the background so install returns
@@ -1114,7 +1192,9 @@ async function cmdInstall({ interactive }) {
   // authenticating as memhouse_root instead: the three flags did nothing, --yes satisfied
   // haveAll so no prompt asked who you were, and resolveConfig's default was used AS A
   // CREDENTIAL. Refuse rather than do something else silently.
-  const adminOnly = ['member', 'member-password'].filter((k) => flags[k] !== undefined);
+  // Every flag that only means something to the admin bootstrap. Left out, it was silently
+  // ignored on a member install (`--keep-admin` was — Codex P2 on #14).
+  const adminOnly = ['member', 'member-password', 'keep-admin', 'admin-password-file', 'admin-password'].filter((k) => flags[k] !== undefined);
   if (!adminUser && adminOnly.length) {
     console.log(bad(`--${adminOnly.join(', --')} ${adminOnly.length > 1 ? 'are' : 'is'} only read with --admin-user`));
     console.log('  Those flags provision a member, which needs house admin. Without them this');
@@ -2176,15 +2256,31 @@ function installKind() {
 async function cmdUpdate() {
   const { kind, root } = installKind();
   const cfg0 = resolveConfig();
-  // --channel pins for this run AND every later one: the point of pinning is that the next
-  // person to type `memhouse update` does not have to remember it.
-  if (flags.channel && flags.channel !== true && String(flags.channel) !== cfg0.channel) {
-    writeEnvFile({ ...cfg0, channel: String(flags.channel) });
-    console.log(ok(`channel pinned in ${short(ENV_FILE)}: ${flags.channel}`));
-  }
-  const pinned = flags.channel && flags.channel !== true ? String(flags.channel) : (cfg0.channel || null);
+  const asked = flags.channel && flags.channel !== true ? String(flags.channel) : null;
+  // What is PINNED is what the env file says. resolveConfig folds --channel into cfg0, so
+  // comparing the flag with cfg0.channel compared it with itself, and the pin was never
+  // written at all.
+  const stored = readEnvFile().MEMHOUSE_CHANNEL || null;
+  const pinned = asked || cfg0.channel || null;
   const tags = await chan.fetchTags();
   const pick = chan.pickChannel({ version: PKG.version, pinned, tags });
+  // --channel pins for this run AND every later one: the point of pinning is that the next
+  // person to type `memhouse update` does not have to remember it. Only a channel the
+  // registry actually has is pinned. The pin used to be written before anything was
+  // checked, so `--channel tema` (or any typo) left every later `update` following a tag
+  // that does not exist, --no-install included, which checks no channel at all (A5).
+  if (asked && asked !== stored) {
+    if (!tags) {
+      console.log(warn(`the registry did not answer, so channel '${asked}' cannot be checked — not pinned`));
+    } else if (!tags[asked]) {
+      console.log(bad(`no channel '${asked}' on the registry — nothing pinned, nothing changed`));
+      console.log(`  channels: ${Object.keys(tags).join(', ')}`);
+      return 1;
+    } else {
+      writeEnvFile({ ...cfg0, channel: asked });
+      console.log(ok(`channel pinned in ${short(ENV_FILE)}: ${asked}`));
+    }
+  }
   const latest = pick.target;
   if (JSON_OUT && flags.check) return console.log(JSON.stringify({ kind, root, current: PKG.version, channel: pick.channel, target: pick.target, reason: pick.reason, tags }, null, 2));
   console.log(`  installed  ${PKG.version}  (${kind}: ${root})`);
@@ -2192,12 +2288,18 @@ async function cmdUpdate() {
   console.log(`  target     ${pick.target || (tags ? 'nothing to install' : 'unknown — the registry did not answer')}`);
   if (latest && latest === PKG.version && kind !== 'checkout') console.log(ok('already current'));
   if (flags.check) return 0;
-  if (!pick.channel && kind !== 'checkout') {
+  // --no-install asks for the restart and the house checks only; the files are already in
+  // place, so which channel they came from does not matter. Refusing here for want of one
+  // made the command every nightly prints for itself ("memhouse update --no-install")
+  // return 1 on exactly the builds that print it — a tarball is on no registry tag — and
+  // leave the old shipper running the old code.
+  const noInstall = flags['no-install'] === true;
+  if (!pick.channel && kind !== 'checkout' && !noInstall) {
     console.log(warn('no automatic update for this install'));
     console.log(`  ${pick.reason}`);
     return 1;
   }
-  if (pick.channel && !pick.target && kind !== 'checkout') {
+  if (pick.channel && !pick.target && kind !== 'checkout' && !noInstall) {
     console.log(bad(`channel '${pick.channel}' has no version on the registry — nothing to install, nothing changed`));
     return 1;
   }
@@ -2207,7 +2309,9 @@ async function cmdUpdate() {
     console.log('  to keep a version around: npm install -g memhouse');
     return 1;
   }
-  if (kind === 'local-dep') {
+  // --no-install installs nothing, so where the files came from does not matter: restart and
+  // check the house. The refusal used to come first and turned it away (A6).
+  if (kind === 'local-dep' && !noInstall) {
     console.log(warn('this is a project dependency, not a global install'));
     console.log(`  upgrade it where it lives: npm install memhouse@${pick.channel || 'latest'}`);
     return 1;
@@ -2220,7 +2324,7 @@ async function cmdUpdate() {
   try { svc = require(path.join(REPO_ROOT, 'memhouse', 'service.js')).status(); } catch { /* unsupported platform */ }
   const wasRunning = { shipper: !!pidOf('shipper'), dashboard: !!pidOf('dashboard') };
 
-  if (flags['no-install'] === true) {
+  if (noInstall) {
     // The files were already replaced by other means — a hand-typed `npm i -g`, a tarball,
     // a configuration manager. The npm/git half is exactly what such a pilot has already
     // done, and the half a bare install leaves undone (restart, migrations, schema heal)
@@ -2254,7 +2358,9 @@ async function cmdUpdate() {
       return 1;
     }
   }
-  console.log(ok('files updated'));
+  // Said only when something was installed. Under --no-install it claimed "files updated"
+  // for files nobody touched (A6).
+  if (!noInstall) console.log(ok('files updated'));
   // The house may have been converted to the one layout since this machine last ran:
   // 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.
@@ -3168,9 +3274,16 @@ async function cmdShare() {
   // today (the member has no grant option on the database) but with a raw ACCESS_DENIED
   // naming a privilege nobody can explain. Grant the rooms this member actually owns.
   const mine = roomNames(cfg.user);
-  // One grant on the member's own pattern: the shape the member holds, one level down
-  // (SELECT only). It reaches nothing a housemate wrote.
-  const shareTargets = [`${db}.${mine.pattern}`];
+  // A FULL share is one grant on the member's own pattern: the shape the member holds, one
+  // level down (SELECT only). It reaches nothing a housemate wrote — and, by design,
+  // everything of this member's, including the stat tables and any room added later.
+  const wildcard = `${db}.${mine.pattern}`;
+  // A SCOPED share is granted table by table: exactly the rooms its row policies filter,
+  // and nothing else. It used to take the wildcard too, and the policies covered only
+  // these three, so a grantee scoped to one project read every other project's opening
+  // prompt, folder and token totals straight out of <member>_session_stats, plus meta,
+  // events and whatever table the pattern would match next.
+  const scopedTargets = ROOM_TYPES.map((room) => `${db}.${mine.physical[room]}`);
 
   // 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.
@@ -3196,13 +3309,19 @@ async function cmdShare() {
   // 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) {
+    // Withdraw the grant FIRST, then the filters. The other order failed open: a REVOKE
+    // refused after the policies were dropped left the grantee with an unfiltered share.
+    try { for (const tgt of [wildcard, ...scopedTargets]) await run(`REVOKE SELECT ON ${tgt} FROM ${user}`); }
+    catch (e) {
+      console.log(bad(`could not revoke: ${netReason(e)}`));
+      console.log(`  Nothing else was changed: any row policies for '${user}' are still in place.`);
+      return 1;
+    }
     let dropped = 0;
     for (const room of ROOM_TYPES) {
       try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); dropped++; }
       catch (e) { console.log(warn(`could not drop the policy on ${room}: ${e.message.split('\n')[0]}`)); }
     }
-    try { for (const tgt of shareTargets) await run(`REVOKE SELECT ON ${tgt} 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');
@@ -3211,9 +3330,12 @@ async function cmdShare() {
   }
 
   // ── grant ─────────────────────────────────────────────────────────────────────
-  const scopeRaw = flags.only !== undefined && flags.only !== true ? String(flags.only) : null;
+  const scopeRaw = flags.only !== undefined && flags.only !== true ? String(flags.only).trim() : 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; }
+  // An EMPTY scope is a mistake, not a request for everything. `--only "$SCOPE"` with an
+  // unset variable used to fall through to a full share — the widest grant this command
+  // makes, from the flag whose whole purpose is to narrow it.
+  if (flags.only === true || scopeRaw === '') { 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; }
   }
@@ -3251,24 +3373,47 @@ async function cmdShare() {
         made.push(room);
       } catch (e) {
         console.log(bad(`could not scope ${room}: ${e.message.split('\n')[0]}`));
-        for (const r of made) {
-          try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, r)} ON ${db}.${mine.physical[r]}`); } catch { /* best effort */ }
-        }
-        console.log(`  NOTHING WAS GRANTED — '${user}' can read no more than before, and any`);
-        console.log('  filters this attempt created have been removed.');
+        // Do NOT drop what this attempt wrote. `OR REPLACE` may have just overwritten the
+        // filter of an EXISTING scoped share, and dropping it would leave that grantee's
+        // table grant unfiltered — failing open. A filter without a grant is inert, and the
+        // full-share and --revoke paths both clear leftovers.
+        console.log(`  NOTHING WAS GRANTED — '${user}' can read no more than before.`);
+        if (made.length) console.log(`  The filters written for ${made.join(', ')} are left in place; \`memhouse share ${user} --revoke\` clears them.`);
         return 1;
       }
     }
   }
 
-  try { for (const tgt of shareTargets) await run(`GRANT SELECT ON ${tgt} TO ${user}`); }
-  catch (e) {
+  // Full: the wildcard. Scoped: first take back any wildcard an earlier share left — it
+  // would reach straight past the filters — then grant the filtered rooms one by one.
+  // A failure part-way leaves the grantee with LESS than before, never more.
+  try {
+    if (scope) {
+      await run(`REVOKE SELECT ON ${wildcard} FROM ${user}`);
+      for (const tgt of scopedTargets) await run(`GRANT SELECT ON ${tgt} TO ${user}`);
+    } else {
+      await run(`GRANT SELECT ON ${wildcard} TO ${user}`);
+    }
+  } catch (e) {
     console.log(bad(`could not grant: ${netReason(e)}`));
-    // Filters without a grant are inert, but leaving them behind would make a later full
-    // share silently scoped — the case the widening path below exists to catch.
     if (scope) {
-      for (const room of ROOM_TYPES) {
-        try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); } catch { /* best effort */ }
+      // Withdraw the grant, and drop the filters ONLY once that is confirmed. If any REVOKE
+      // is refused — the owner lost the grant option, a transient error — the grantee may
+      // still hold a table-level SELECT from an earlier scoped share, and dropping its
+      // filter would expose every row. Leaving a filter behind costs nothing: without a
+      // grant it is inert, and the full-share and --revoke paths both clear it.
+      let withdrawn = true;
+      for (const tgt of [wildcard, ...scopedTargets]) {
+        try { await run(`REVOKE SELECT ON ${tgt} FROM ${user}`); } catch { withdrawn = false; }
+      }
+      if (withdrawn) {
+        for (const room of ROOM_TYPES) {
+          try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); } catch { /* inert without a grant */ }
+        }
+        console.log(`  '${user}' was left with no access to your rooms — nothing wider than before.`);
+      } else {
+        console.log(`  Could not confirm '${user}' lost every grant, so the filters stay in place — whatever`);
+        console.log(`  '${user}' can still reach is filtered. Retry, or: memhouse share ${user} --revoke`);
       }
     }
     return 1;
@@ -3306,6 +3451,8 @@ async function cmdShare() {
       console.log(`  ${room.padEnd(11)} ${r[0].n} of ${all[0].n} rows`);
     } catch { /* counting is a courtesy */ }
   }
+  console.log('  Not shared under a scope: the stat tables, meta and events — they carry no');
+  console.log('  per-session filter, so a scoped reader gets none of them.');
   console.log(`  Widen to everything:  memhouse share ${user}`);
   console.log(`  Withdraw:             memhouse share ${user} --revoke`);
   return 0;
@@ -3321,7 +3468,10 @@ async function cmdShare() {
  * true = permissive, false = restrictive, null = could not tell.
  */
 async function probePermissive(cfg, db) {
-  const t = `_mh_probe_${process.pid}`;
+  // Inside the member's own pattern: the one place the one-layout grant lets them create a
+  // table and put a policy on it. A bare `_mh_probe_<pid>` sat outside it, was refused on
+  // every server, and turned this check into a permanent "could not verify".
+  const t = `${cfg.user}__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`);
@@ -3576,19 +3726,11 @@ async function cmdInvite() {
   // statements adminBootstrap would run, so the person with the credential runs four
   // lines instead of installing anything. Nothing is contacted and nothing is written.
   if (flags['print-sql'] === true) {
-    const password = flags['member-password'] && flags['member-password'] !== true
-      ? String(flags['member-password']) : generatePassword();
     // memberSql prints its own header naming the house and the credential it needs; a
     // second one above it said the same thing twice, and in a shared house said the wrong
     // thing ("their own house" — they get rooms in a shared one).
-    console.log(memberSql(db, name, password));
-    console.log('-- Then send them these four lines — they are a credential, so use a channel');
-    console.log('-- you trust (croc, a password manager), not chat:');
-    console.log(`--   MEMHOUSE_URL='${url}'`);
-    console.log(`--   MEMHOUSE_USER='${name}'`);
-    console.log(`--   MEMHOUSE_PASSWORD='${password}'`);
-    console.log(`--   MEMHOUSE_DB='${db}'`);
-    console.log(`-- They install with:  memhouse install --url ${url} --user ${name} --password '…' --db ${db}`);
+    console.log(memberSql(db, name));
+    console.log(handoffLines({ url, db, member: name, invite: true }));
     return 0;
   }
 
@@ -3599,8 +3741,38 @@ async function cmdInvite() {
   // --admin-* wins. Otherwise the admin credential this install keeps beside its member
   // credential (a house you deployed or administer). Failing both, the member credential
   // itself is tried below — which works for whoever set the house up as its superuser.
-  let adminUser = flags['admin-user'] || cfg.adminUser || undefined;
-  let adminPass = flags['admin-password'] || (!flags['admin-user'] && cfg.adminPassword) || undefined;
+  if (flags['admin-user'] === true) { console.log(bad('--admin-user needs a name, e.g. --admin-user default')); return 1; }
+  let adminUser = (flags['admin-user'] ? String(flags['admin-user']) : '') || cfg.adminUser || undefined;
+  // Who named this admin decides where its credential may go (G4, memhouse/invite-target.js):
+  // one given for this command provisions at --url; one this install keeps provisions only
+  // at the house it was saved for.
+  const adminUserSource = flags['admin-user'] ? 'flag'
+    : (process.env.MEMHOUSE_ADMIN_USER ? 'env' : (adminUser ? 'file' : 'member'));
+  let adminPass;
+  const pwSource = {};
+  if (adminUser) {
+    // --admin-password-file / --admin-password / MEMHOUSE_ADMIN_PASSWORD / the stored one
+    // for this same admin / a prompt. `--admin-user` as a flag used to switch the
+    // environment off, so the only scriptable path put the password on argv.
+    adminPass = await adminPasswordFor(adminUser, pwSource);
+    if (adminPass === null) return 1;
+  }
+  const target = require(path.join(REPO_ROOT, 'memhouse', 'invite-target'))
+    .provisionTarget({ url, storedUrl: configuredUrl, adminUserSource, passwordSource: pwSource.source || null });
+  if (target.error) { console.log(bad(target.error)); return 1; }
+  // A stored credential is never sent to --url, so check that the INVITEE can reach it
+  // without one: ClickHouse answers /ping unauthenticated.
+  if (target.stored) {
+    const reach = await pingUrl(url);
+    if (!reach.ok) {
+      console.log(bad(`cannot reach ${url}: ${reach.reason}`));
+      console.log('  --url is the address the INVITEE will use, and invite checks it from here first.');
+      console.log('  A `deploy --local` house is bound to loopback on purpose, so no LAN address');
+      console.log('  reaches it and no invitee could either — publish it (tunnel, reverse proxy)');
+      console.log('  before inviting, or use --print-sql and let the invitee be told the address.');
+      return 1;
+    }
+  }
   if (!adminUser) {
     const c = requireConfig(cfg, 'invite');
     if (!c.user) return 1;
@@ -3619,20 +3791,18 @@ async function cmdInvite() {
     // unreachable host — a typo, a loopback-bound house, a tunnel that is down — come back
     // as "you are only a member", which sends the reader after a privilege they already
     // have. Caught on the testbed, where a wrong --url produced exactly that.
+    // The member credential is stored, so it is checked against the house it was saved for
+    // (target.url), never against --url; --url's reachability was checked above, unauthenticated.
     try {
-      await ch({ ...c, url }, 'SELECT 1', { database: '' });
+      await ch({ ...c, url: target.url }, 'SELECT 1', { database: '' });
     } catch (e) {
-      console.log(bad(`cannot reach ${url} as '${c.user}': ${netReason(e)}`));
-      console.log('  --url is the address the INVITEE will use, and invite checks it from here first.');
-      console.log('  A `deploy --local` house is bound to loopback on purpose, so no LAN address');
-      console.log('  reaches it and no invitee could either — publish it (tunnel, reverse proxy)');
-      console.log('  before inviting, or use --print-sql and let the invitee be told the address.');
+      console.log(bad(`cannot reach your house ${target.url} as '${c.user}': ${netReason(e)}`));
       return 1;
     }
     // 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));
+    const caps = capabilitiesFrom(await readGrants({ ...c, url: target.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)`));
@@ -3643,37 +3813,24 @@ async function cmdInvite() {
       console.log('  keeps one housemate out of another house.');
       console.log('');
       console.log('  If you RUN this ClickHouse — use the admin credential you created it with');
-      console.log('  (for a stock server that is `default`); memhouse never stores it, so pass it');
-      console.log('  per invite and it is used for one connection and discarded:');
-      console.log(`     memhouse invite ${name} --url ${url} --admin-user default`);
-      console.log('     (leave --admin-password off and it is prompted for, so it stays out of');
-      console.log('      your shell history and the process list)');
+      console.log('  (for a stock server that is `default`); memhouse does not store it, so give it');
+      console.log('  per invite — used for one connection and discarded, never on the command line:');
+      console.log(`     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite ${name} --url ${url} --admin-user default`);
+      console.log(`     memhouse invite ${name} --url ${url} --admin-user default      (prompts on a terminal)`);
       console.log('');
       console.log('  If SOMEONE ELSE runs it — you cannot invite, and no flag changes that.');
       console.log('  Print the statements and send them to whoever administers the server:');
       console.log(`     memhouse invite ${name} --url ${url} --print-sql`);
       return 1;
     }
-  } else if (adminPass === undefined) {
-    // Prompt rather than refuse. A password given as --admin-password lands in the
-    // process list for the life of the request and in shell history unless the caller
-    // remembered a leading space; asking for it keeps it in this process only.
-    // Non-TTY (an agent, CI) still gets the old refusal — there is nobody to ask.
-    if (!process.stdin.isTTY) {
-      console.log(bad('--admin-user given without --admin-password (no TTY to prompt on)'));
-      return 1;
-    }
-    adminPass = await askSecret(`  password for '${adminUser}'`);
-    if (!adminPass) { console.log(bad('no password given')); return 1; }
   }
 
-  // WHERE to connect to provision. --url is the address the INVITEE will use — it may be
-  // a LAN IP or tunnel that is not this admin's own endpoint, and sending the stored
-  // credential there would hand it to whatever answers a typo'd or hostile --url. So the
-  // stored-credential path provisions at the admin's OWN configured cfg.url; only an
-  // EXPLICIT --admin-* (where the admin typed the target themselves) provisions at --url.
-  // Either way the invite FILE carries --url, the invitee's path.
-  const provisionUrl = flags['admin-user'] ? url : cfg.url;
+  // WHERE to connect to provision: decided above by provisionTarget(). A stored credential
+  // provisions at the house it was saved for; one given for this command, at --url. Either
+  // way the invite FILE carries --url, the invitee's path. (This used to read
+  // `flags['admin-user'] ? url : cfg.url` — but cfg.url IS --url once the flag is given, so
+  // the stored credential went to whatever --url named.)
+  const provisionUrl = target.url;
 
   // Is there already a house here, with somebody's memory in it? The house is created
   // with CREATE DATABASE IF NOT EXISTS, so inviting a name whose database already exists
@@ -3844,12 +4001,15 @@ async function cmdPasswd({ quiet = false, forNext = null } = {}) {
         }
       }
     }
-    if (!adminUser || flags['admin-password'] === undefined) {
+    if (!adminUser || adminUser === true) {
       console.log(bad(`'${cfg.user}' cannot change its own password on this house (pre-0.11 member, or no access management).`));
-      console.log('  Rotate with an admin credential:  memhouse passwd --admin-user <a> --admin-password <p>');
+      console.log('  Rotate with an admin credential (password from MEMHOUSE_ADMIN_PASSWORD, --admin-password-file, or a prompt):');
+      console.log('     memhouse passwd --admin-user <a>');
       return 1;
     }
-    const via = { ...cfg, user: adminUser, password: flags['admin-password'] || '' };
+    const adminPassword = await adminPasswordFor(String(adminUser));
+    if (adminPassword === null) return 1;
+    const via = { ...cfg, user: adminUser, password: adminPassword };
     try { await ch(via, `ALTER USER \`${cfg.user}\` IDENTIFIED BY '${escPw}'`, { database: '' }); }
     catch (e) { console.log(bad(`could not rotate: ${e.message}`)); return 1; }
   }
@@ -3866,7 +4026,8 @@ async function cmdPasswd({ quiet = false, forNext = null } = {}) {
   console.log(ok(`password rotated for '${cfg.user}' and ${ENV_FILE.replace(os.homedir(), '~')} updated`));
   console.log('  restart anything that inlines the credential here:  memhouse update --no-install');
   console.log(warn('this rotated the ONE server credential — every OTHER machine you ship as'));
-  console.log(`  '${cfg.user}' now fails auth until it gets the new password (memhouse setup --password …).`);
+  console.log(`  '${cfg.user}' now fails auth until its env file gets the new password: copy the`);
+  console.log(`  MEMHOUSE_PASSWORD line from ${ENV_FILE.replace(os.homedir(), '~')} over a channel you trust.`);
   return 0;
 }
 
@@ -3929,8 +4090,10 @@ async function cmdUninstall() {
   //
   //   (default)         daemons, service, runtime state. Config and identity KEPT.
   //   --credentials     also forget the house: the env file, with its password.
-  //   --full-removal    all of MEMHOUSE_HOME, fingerprint included. The next install is a
-  //                     NEW host whose rows do not join this machine's history.
+  //   --full-removal    all of MEMHOUSE_HOME, host.json included. The next install
+  //                     derives the same fingerprint from the OS machine id (0.18.6+), so it
+  //                     is the same host unless the machine was renamed meanwhile or has no
+  //                     readable machine id (then it falls back to random: a new host).
   //
   // No tier touches the house: transcripts live in ClickHouse and re-ship from the local
   // session stores regardless.
@@ -3951,8 +4114,9 @@ async function cmdUninstall() {
     if (flags.yes !== true && process.stdin.isTTY) {
       const id = hostjs.read(HOME_DIR);
       console.log(warn(`--full-removal also discards this machine's host identity${id ? ` (${id.id})` : ''}.`));
-      console.log('  Rows already shipped keep that name, a future install gets a new one, and');
-      console.log("  this machine then reads as two. Your transcripts themselves are safe.");
+      console.log('  A reinstall derives it again from this machine\'s own id, so it normally comes');
+      console.log('  back the same — unless the machine is renamed first, or has no readable machine');
+      console.log("  id, and then it reads as two machines. Your transcripts themselves are safe.");
       const a = (await ask('Remove everything, including the host identity? (yes/no)', 'no')).toLowerCase();
       if (a !== 'yes' && a !== 'y') { console.log('aborted — daemons are stopped, nothing was removed'); return; }
     }
@@ -4100,7 +4264,8 @@ async function cmdUninstall() {
       const convert = require(path.join(REPO_ROOT, 'memhouse', 'convert'));
       const db = flags.db && flags.db !== true ? String(flags.db) : 'mem';
       const au = flags['admin-user'] && flags['admin-user'] !== true ? String(flags['admin-user']) : (cfg.adminUser || null);
-      const ap = flags['admin-password'] && flags['admin-password'] !== true ? String(flags['admin-password']) : (cfg.adminPassword || '');
+      const ap = au ? await adminPasswordFor(au) : '';
+      if (ap === null) { process.exitCode = 1; break; }
       if (!au) { console.log(bad('convert needs an admin credential: --admin-user/--admin-password (or the one this instance keeps)')); process.exitCode = 1; break; }
       const who = { ...cfg, user: au, password: ap };
       const only = flags.member && flags.member !== true ? String(flags.member) : null;
@@ -4188,7 +4353,8 @@ async function cmdUninstall() {
       // --admin-* wins; otherwise the admin credential this install keeps (a house you
       // deployed or administer). A member alone cannot read other accounts' grants.
       const au = flags['admin-user'] && flags['admin-user'] !== true ? String(flags['admin-user']) : (cfg.adminUser || null);
-      const ap = flags['admin-password'] && flags['admin-password'] !== true ? String(flags['admin-password']) : (cfg.adminPassword || '');
+      const ap = au ? await adminPasswordFor(au) : '';
+      if (ap === null) { process.exitCode = 1; break; }
       // Reading ANOTHER account's grants needs privilege; without it ClickHouse simply
       // returns fewer rows. Say so rather than presenting a short list as the whole truth.
       const who = au ? { ...cfg, user: au, password: ap } : cfg;