memhouse 0.18.0 → 0.18.2

package/README.md

@@ -83,6 +83,7 @@ memhouse deploy --local | --down           stand up (or remove) a local house
 memhouse invite <name>                     mint a member + house, hand them one env file
 memhouse members [--db X]                  who is in a house, and what each can reach
 memhouse whoami [--admin]                  which credential is in play, and what it may do
+memhouse instance                          which memhouse this is: home, binary, house, rooms, scope, bindings
 memhouse rooms                             what your rooms are actually called
 memhouse share <user> [--only …|--revoke|--list]
                                            let a housemate read yours, in whole or in part
@@ -162,6 +163,18 @@ build sits on no tag and is never auto-updated; `update --check` says so and nam
 way forward. An invite from a house on a channel carries it, so the invitee follows it
 too.
 
+## Instances
+
+An instance is a home: an env file naming a house, the daemons shipping to it, and the
+playbooks whose sessions it ships (`MEMHOUSE_CLAUDE_ROOTS`). A machine can run several,
+each under its own `MEMHOUSE_HOME`, on different channels. `plugins install claude` from an
+instance installs into exactly the playbooks that instance ships and **binds** them: it
+writes `MEMHOUSE_HOME` and `MEMHOUSE_BIN` into each playbook's `settings.json` `env`, which
+Claude Code applies to every session there. So the `/mem:*` skills in a bound playbook read
+that instance's house and run that instance's binary, whatever the shell they were started
+from had. `plugins list` shows the binding; `plugins remove` takes it out. Everything else
+in `settings.json` is left as it was.
+
 ## Going back into a session
 
 `search` finds the conversation; `resume` hands you back into it.

package/bin/memhouse.js

@@ -273,14 +273,24 @@ function portOf(u) {
 // "not running" for every correctly service-managed install, and `doctor` fails on a
 // healthy machine. Returns { running, via }.
 function shipperHealth() {
+  // "running" is the pid; whether it is DOING anything is the log. Both, always.
+  const lastPass = (() => {
+    try {
+      const passlog = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog'));
+      const f = path.join(LOG_DIR, 'shipper.log'); const st = fs.statSync(f);
+      const fd = fs.openSync(f, 'r'); const len = Math.min(st.size, 65536); const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, st.size - len); fs.closeSync(fd);
+      return passlog.lastPass(buf.toString('utf-8'));
+    } catch { return { outcome: null }; }
+  })();
   const pid = pidOf('shipper');
-  if (pid) return { running: true, via: `daemon (pid ${pid})` };
+  if (pid) return { running: true, via: `daemon (pid ${pid})`, lastPass };
   try {
     const svc = require(path.join(REPO_ROOT, 'memhouse', 'service.js'));
     const st = svc.status();
-    if (st.installed) return { running: st.running, via: `service (${st.kind})` };
+    if (st.installed) return { running: st.running, via: `service (${st.kind})`, lastPass };
   } catch { /* no service integration on this platform */ }
-  return { running: false, via: null };
+  return { running: false, via: null, lastPass };
 }
 
 // Room routing for the CLI's own queries. The shipper and dashboard resolve rooms through
@@ -405,7 +415,9 @@ Setup        onboard              interactive wizard: discover → configure →
                                   --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 never stored.
+                                  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.
                                   --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
@@ -438,6 +450,7 @@ Data         ship                 one incremental pass (--full | --loop [sec])
              search <terms…>      full-text search across all sessions
              resume <session-id>  print the command that reopens that session in its editor
              sessions-query       print the session rollup SQL for this credential
+             instance             which memhouse this is: home, binary, house, rooms, scope, daemons, bound playbooks
              rooms                what your rooms are actually called (--json)
              members              who is in a house and what each can reach (--db, admin)
              start | stop |       shipper loop + dashboard as background daemons
@@ -968,6 +981,16 @@ function startShipperBackground(cfg) {
   console.log('  dashboard (browse / search / analyze):  memhouse start');
 }
 
+// The store is node:sqlite, stable from Node 24. On 22 everything green-lights and the
+// SQLite-backed adapters silently ship nothing — 36 messages went out before anyone noticed.
+// doctor said so; install and onboard did not. Now they refuse, with the same sentence.
+function engineOk() {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 24) return true;
+  console.log(bad(`node ${process.versions.node} — need >= 24 — node:sqlite is stable there; the SQLite-backed adapters need it`));
+  process.exitCode = 1; return false;
+}
+
 async function cmdInstall({ interactive }) {
   // --env <file>: an INVITE intake. The file carries MEMHOUSE_URL/USER/PASSWORD/DB from
   // `memhouse invite` on the admin's machine; loading it into the environment BEFORE
@@ -984,6 +1007,10 @@ async function cmdInstall({ interactive }) {
     // this machine with a file that cannot authenticate on the invitee's.
     const missing = wanted.filter((k) => !parsed[k]);
     if (missing.length) { console.log(bad(`--env ${flags.env} is missing ${missing.join(', ')} — not a complete invite file?`)); return 1; }
+    try {
+      const h = new URL(String(parsed.MEMHOUSE_URL || '')).hostname;
+      if (/^(localhost|127\.0\.0\.1|\[?::1\]?)$/.test(h)) console.log(warn(`${parsed.MEMHOUSE_URL} is loopback — it points at THIS machine; only right if a tunnel or port-forward puts the house here`));
+    } catch { /* not a URL; the missing-fields check above already spoke */ }
     // Clear ambient MEMHOUSE_* so ONLY the file speaks (exported vars normally win over the
     // file; an invite intake is the one place they must not).
     for (const k of ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB', 'MEMHOUSE_PORT']) delete process.env[k];
@@ -1235,6 +1262,10 @@ async function cmdInstall({ interactive }) {
   // 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; } })();
+    // Same server and database, different user, is a credential swap, not a house move —
+    // "old house" reads as data loss when nothing moved. A drill flagged the conflation.
+    const sameHouse = prior.MEMHOUSE_URL && sameEndpoint(prior.MEMHOUSE_URL, cfg.url) && (!prior.MEMHOUSE_DB || prior.MEMHOUSE_DB === cfg.db);
+    const whatMoved = sameHouse ? 'old credential' : 'old house';
     const viaService = String(shipperHealth().via || '').startsWith('service');
     if (viaService && st) {
       const cmd = st.kind === 'systemd'
@@ -1242,10 +1273,10 @@ async function cmdInstall({ interactive }) {
         : ['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'));
+        : warn(`restart the shipper yourself, or it keeps writing under the ${whatMoved}:  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 */ } }
+      if (pid) { try { process.kill(pid, 'SIGTERM'); console.log(ok(`stopped the shipper (pid ${pid}) — it was running under the ${whatMoved}`)); } catch { /* raced */ } }
       console.log('  start it against the new one:  memhouse start');
     }
   }
@@ -1280,6 +1311,18 @@ async function finishInvite(cfg) {
     }
     if (go) {
       const code = await cmdPasswd({ quiet: true });
+      if (code === 0) {
+        // The rotation rewrote the env FILE. But --env hoisted the invite's values into
+        // process.env, and resolveConfig prefers process.env over the file — so the
+        // shipper spawned a few lines later got the INVITE password, which the rotation
+        // had just killed, and failed every pass with "Authentication failed" while every
+        // fresh CLI call (reading the file) worked. A drill member watched an empty house
+        // for twelve minutes. Adopt what the file now says before anything else is spawned.
+        const drift = envfile.credentialDrift(fs.readFileSync(ENV_FILE, 'utf-8'), process.env);
+        for (const k of drift.changed) process.env[k] = drift.values[k];
+        if (drift.values.MEMHOUSE_PASSWORD !== undefined && flags.password !== undefined) flags.password = drift.values.MEMHOUSE_PASSWORD;
+        if (cfg) cfg.password = process.env.MEMHOUSE_PASSWORD;
+      }
       if (code !== 0) {
         // Rotation failed and its own state may be uncertain — KEEP the invite file (it
         // still carries the password the config was just written from) so nothing is
@@ -1318,7 +1361,8 @@ function printGettingStarted(cfg) {
   console.log('                                     /mem:sql, /mem:access, /mem:admin');
   console.log(`     ${mh} search <terms>         find a past conversation right now`);
   console.log(`     ${mh} doctor                 every line a check mark = healthy`);
-  console.log('  The house keeps shipping as you work; nothing else to do.');
+  if (flags['no-ship'] === true) console.log('  Shipping is OFF (--no-ship). Start it when ready:  memhouse start');
+  else console.log('  The house keeps shipping as you work; nothing else to do.');
 }
 
 async function cmdOnboard() {
@@ -1600,7 +1644,12 @@ async function cmdStatus() {
       console.log(`     ${f.writer.padEnd(28)} ${String(f.version || '?').padEnd(8)} last ship ${fleetAge(f.ageMs)}${mark}`);
     }
   }
-  console.log(out.shipper.running ? ok(`shipper: running — ${out.shipper.via}`) : warn('shipper: not running'));
+  {
+    const fail = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).describeFailure(out.shipper.lastPass);
+    console.log(!out.shipper.running ? warn('shipper: not running')
+      : fail ? warn(`shipper: running — ${out.shipper.via} — but ${fail}`)
+      : ok(`shipper: running — ${out.shipper.via}`));
+  }
   console.log(out.daemons.dashboard ? ok(`dashboard: running (pid ${out.daemons.dashboard})`) : warn('dashboard: not running'));
   if (out.daemons.dashboard) console.log(`  dashboard → http://localhost:${runningPort(cfg)}`);
   // Exit non-zero when the house is unreachable. `status` is what a health check, a
@@ -1947,7 +1996,9 @@ async function cmdDoctor() {
       'that adapter does not extract usage; the messages are stored, the numbers are not');
   } catch { /* a house that cannot be read is already reported above */ }
   const sh = shipperHealth();
-  add(sh.running, `shipper${sh.via ? ` — ${sh.via}` : ''}`, 'memhouse start (or: memhouse service install)');
+  const shFail = require(path.join(REPO_ROOT, 'memhouse', 'shipper', 'passlog')).describeFailure(sh.lastPass);
+  add(sh.running && !shFail, `shipper${sh.via ? ` — ${sh.via}` : ''}${shFail ? ` — ${shFail}` : ''}`,
+    shFail ? (sh.lastPass.auth ? 'memhouse stop && memhouse start' : 'read: ~/.memhouse/logs/shipper.log') : 'memhouse start (or: memhouse service install)');
   add(!!pidOf('dashboard'), 'dashboard daemon', 'memhouse start');
   add(fs.existsSync(path.join(REPO_ROOT, 'public', 'index.html')), 'dashboard UI built', 'built automatically by memhouse start');
 
@@ -2417,7 +2468,19 @@ async function cmdPlugins() {
   const invocations = names.map((n) => `/mem:${n}`).join(', ');
   // --target overrides the discovery rather than joining it: given one, that is the only
   // directory touched.
-  const targets = flags.target ? [{ dir: flags.target, why: '--target' }] : claudeTargets();
+  // Targets: --target names one; otherwise an instance that ships specific playbooks
+  // (MEMHOUSE_CLAUDE_ROOTS) installs into exactly those — the plugin belongs where the
+  // sessions come from; failing both, every Claude config dir on the machine.
+  const binding = require(path.join(REPO_ROOT, 'memhouse', 'binding'));
+  const scope = require(path.join(REPO_ROOT, 'editors', 'scope'));
+  const icfg = resolveConfig();
+  const scoped = !flags.target && icfg.claudeRoots
+    ? scope.parseList(icfg.claudeRoots).map(scope.expandHome).map((d) => ({ dir: d, why: 'this instance ships it' }))
+    : null;
+  const targets = flags.target ? [{ dir: flags.target, why: '--target' }] : (scoped || claudeTargets());
+  // What the skills in a bound playbook run and read: this binary, this home.
+  const thisBin = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+  const boundLabel = (dir) => { const b = binding.boundTo(binding.readSettings(dir)); return b ? `bound to ${short(b.home)}` : 'unbound — sessions use whatever MEMHOUSE_HOME the shell has'; };
   // Whatever --target was given has to reappear in the advice, or pasting it installs
   // somewhere else than the directory just inspected.
   const self = `memhouse plugins install claude${flags.target ? ` --target ${flags.target}` : ''}`;
@@ -2427,7 +2490,7 @@ async function cmdPlugins() {
     if (!targets.length) { console.log(warn('no Claude Code config directory found')); return 0; }
     for (const t of targets) {
       console.log(isPluginInstalled(t.dir)
-        ? ok(`installed in ${short(t.dir)} (${t.why})`)
+        ? ok(`installed in ${short(t.dir)} (${t.why}) — ${boundLabel(t.dir)}`)
         : warn(`not installed in ${short(t.dir)} (${t.why})`));
     }
     if (!targets.some((t) => isPluginInstalled(t.dir))) console.log(`  install with: ${self}`);
@@ -2442,7 +2505,13 @@ async function cmdPlugins() {
     }
     const chosen = await chooseTargets(targets, 'Install');
     if (!chosen.length) { console.log(warn('nothing installed')); return 0; }
-    for (const t of chosen) console.log(ok(`installed ${names.length} skills into ${short(installPluginInto(t.dir))}`));
+    for (const t of chosen) {
+      console.log(ok(`installed ${names.length} skills into ${short(installPluginInto(t.dir))}`));
+      try {
+        binding.bind(t.dir, { home: HOME_DIR, bin: thisBin });
+        console.log(ok(`  bound: sessions under ${short(t.dir)} read ${short(HOME_DIR)} and run ${short(thisBin)}`));
+      } catch (e) { console.log(warn(`  not bound: ${e.message}`)); }
+    }
     console.log(`  loads as mem@skills-dir next session — invoke ${invocations}`);
     return 0;
   }
@@ -2458,6 +2527,8 @@ async function cmdPlugins() {
       // else's work.
       try { fs.rmdirSync(path.join(t.dir, 'skills')); } catch { /* not empty: leave it */ }
       console.log(ok(`removed ${short(path.join(t.dir, 'skills', 'mem'))}`));
+      try { if (binding.unbind(t.dir)) console.log(ok(`  unbound: MEMHOUSE_HOME/MEMHOUSE_BIN removed from ${short(path.join(t.dir, 'settings.json'))}`)); }
+      catch (e) { console.log(warn(`  could not unbind: ${e.message}`)); }
     }
     return 0;
   }
@@ -3335,6 +3406,53 @@ async function cmdWhoami() {
   return 0;
 }
 
+/**
+ * Bare `memhouse` with an invite file nearby: offer to process it. Returns null when there
+ * is nothing to offer (caller prints help), else the exit code of the install it ran or
+ * declined. Never touches the file's password: what it shows is the user, the house and
+ * the server, which the guide beside the file shows too.
+ */
+async function offerInvite() {
+  const inv = require(path.join(REPO_ROOT, 'memhouse', 'invitefile'));
+  // The current directory only. The guide says "from the directory holding the file", and
+  // reaching into ~/Downloads surfaced unrelated invitations from other houses — and could
+  // auto-join the wrong one under --yes. If they are somewhere else, they name the file.
+  const found = inv.findInvites([process.cwd()]);
+  if (!found.length) return null;
+  const described = found.map((f) => ({ ...f, ...inv.describeInvite((() => { try { return fs.readFileSync(f.file, 'utf-8'); } catch { return ''; } })()) }));
+  const usable = described.filter((d) => d.complete);
+  if (!usable.length) {
+    console.log(warn(`found ${found.length === 1 ? short(found[0].file) : `${found.length} invite files`} — not a complete invite (missing ${described[0].missing.join(', ')})`));
+    return null;
+  }
+  const cfg = resolveConfig();
+  const interactive = process.stdin.isTTY && flags.yes !== true;
+  console.log(ok(`found an invitation: ${short(usable[0].file)}${usable.length > 1 ? ` (and ${usable.length - 1} more)` : ''}`));
+  let pick = usable[0];
+  if (usable.length > 1) {
+    usable.forEach((d, i) => console.log(`  ${i + 1}) ${short(d.file)}   join ${d.url} as '${d.user}'`));
+    if (!interactive) { console.log('  several invitations here — name one:  memhouse install --env <file>'); return 1; }
+    const a = (await ask('Which one? (number, or n)', '1')).trim().toLowerCase();
+    const n = Number(a);
+    if (!Number.isInteger(n) || n < 1 || n > usable.length) { console.log('  nothing done.'); return 1; }
+    pick = usable[n - 1];
+  }
+  console.log(`  it joins ${pick.url}, house '${pick.db}', as member '${pick.user}'${pick.channel ? `, channel ${pick.channel}` : ''}.`);
+  if (cfg.stated && cfg.user) {
+    console.log(warn(`this machine already ships to ${cfg.url} as '${cfg.user}' — joining REPLACES that (the old config is kept as env.pre-install).`));
+  }
+  console.log('  Joining rotates the password to one only this machine knows, deletes the file, and starts shipping.');
+  if (!interactive) {
+    if (flags.yes === true) { flags.env = pick.file; flags.force = cfg.stated && cfg.user ? true : flags.force; return cmdInstall({ interactive: false }); }
+    console.log(`  Join with:  memhouse install --env ${path.basename(pick.file)}     (or: memhouse --yes)`);
+    return 0;
+  }
+  const a = (await ask(cfg.stated && cfg.user ? 'Replace the current house and join? (yes/no)' : 'Join now? (Y/n)', cfg.stated && cfg.user ? 'no' : 'Y')).trim().toLowerCase();
+  if (!(a === 'y' || a === 'yes' || (a === '' && !(cfg.stated && cfg.user)))) { console.log('  nothing done. Later:  memhouse install --env ' + path.basename(pick.file)); return 0; }
+  flags.env = pick.file; if (cfg.stated && cfg.user) flags.force = true;
+  return cmdInstall({ interactive: false });
+}
+
 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; }
@@ -3806,13 +3924,21 @@ async function cmdUninstall() {
   const cfg = resolveConfig();
 
   switch (cmd) {
-    case null: case 'help': console.log(HELP); break;
+    case null: {
+      // Bare `memhouse`. If an invite file is where the user is standing — or in their
+      // downloads — the likeliest reason they typed this is that they were handed it. Ask.
+      // Otherwise, the help screen as before. Nothing happens without a yes.
+      const code = await offerInvite();
+      if (code === null) console.log(HELP); else process.exitCode = code;
+      break;
+    }
+    case 'help': console.log(HELP); break;
     // `--version` and `-v` land here as flags, not as the `version` verb, so they used to
     // fall through to HELP: forty lines of help and exit 0 is not what --version means.
     case 'version': console.log(PKG.version); break;
     case 'discover': await cmdDiscover(); break;
-    case 'onboard': process.exitCode = await cmdOnboard(); break;
-    case 'install': process.exitCode = await cmdInstall({ interactive: false }); break;
+    case 'onboard': if (!engineOk()) break; process.exitCode = await cmdOnboard(); break;
+    case 'install': if (!engineOk()) break; process.exitCode = await cmdInstall({ interactive: false }); break;
     case 'setup': {
       // Dual-mode like install: --yes (with any --url/--user/--password/--db/
       // --port overrides, already resolved into cfg) skips every prompt so
@@ -3943,6 +4069,57 @@ async function cmdUninstall() {
       if (!au) console.log('  (run with --admin-user to be sure you are seeing every account)');
       break;
     }
+    case 'instance': {
+      // Which memhouse am I talking to? One screen: the instance, its binary, its house,
+      // its rooms, what it ships, its host, its daemons, and which playbooks are bound to
+      // it. A machine can run several instances; this is how they are told apart.
+      const cfg = resolveConfig();
+      const binding = require(path.join(REPO_ROOT, 'memhouse', 'binding'));
+      const scope = require(path.join(REPO_ROOT, 'editors', 'scope'));
+      const hostmod = require(path.join(REPO_ROOT, 'memhouse', 'host.js'));
+      const thisBin = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+      const name = binding.instanceName(HOME_DIR, readEnvFile().MEMHOUSE_NAME);
+      const host = (() => { try { return hostmod.read(HOME_DIR); } catch { return null; } })();
+      const daemons = { shipper: pidOf('shipper') || null, dashboard: pidOf('dashboard') || null };
+      const realHome = (() => { try { return fs.realpathSync(HOME_DIR); } catch { return HOME_DIR; } })();
+      const cands = new Map();
+      for (const d of scope.parseList(cfg.claudeRoots).map(scope.expandHome)) cands.set(d, d);
+      for (const t of claudeTargets()) cands.set(t.dir, t.dir);
+      const bound = [...cands.keys()].filter((d) => {
+        const b = binding.boundTo(binding.readSettings(d)); if (!b) return false;
+        try { return fs.realpathSync(b.home) === realHome; } catch { return b.home === HOME_DIR; }
+      });
+      let rooms = null; let counts = {};
+      if (cfg.stated && cfg.user) {
+        rooms = roomNames(cfg.user);
+        try {
+          // system.tables, not system.parts: a member holds no grant on the latter, and the
+          // former is filtered to what they may see. total_rows is approximate under merges
+          // and exact enough for "is anything in there".
+          for (const r of await chRows(cfg, `SELECT name AS table, total_rows AS n FROM system.tables WHERE database = ${sqlStr(cfg.db)} AND startsWith(name, ${sqlStr(`${cfg.user}_`)})`, { database: '' })) counts[r.table] = Number(r.n);
+        } catch { /* unreachable house: rooms still listed, counts absent */ }
+      }
+      const out = {
+        instance: name, home: HOME_DIR, envFile: ENV_FILE, binary: thisBin, version: PKG.version, channel: cfg.channel || null,
+        house: cfg.stated ? { url: cfg.url, db: cfg.db, member: cfg.user, adminCredential: !!cfg.adminUser, adminUser: cfg.adminUser || null } : null,
+        rooms: rooms ? [...ROOM_TYPES, ...META_TYPES].map((t) => ({ table: `${cfg.db}.${rooms.physical[t]}`, rows: counts[rooms.physical[t]] ?? null })) : [],
+        ships: scope.describe({ MEMHOUSE_EDITORS: cfg.editors, MEMHOUSE_CLAUDE_ROOTS: cfg.claudeRoots }),
+        host: host ? host.id : null, daemons: { ...daemons, dashboardUrl: daemons.dashboard ? `http://localhost:${cfg.port}` : null },
+        boundPlaybooks: bound,
+      };
+      if (JSON_OUT) { console.log(JSON.stringify(out, null, 2)); break; }
+      const line = (k, v) => console.log(`  ${k.padEnd(9)} ${v}`);
+      line('instance', `${name}   (${short(HOME_DIR)})`);
+      line('binary', `${short(thisBin)}   ${PKG.version}${cfg.channel ? `   channel ${cfg.channel}` : ''}`);
+      if (!out.house) { line('house', 'none configured — memhouse install'); break; }
+      line('house', `${cfg.url}   db ${cfg.db}   member ${cfg.user}   admin credential: ${cfg.adminUser ? `yes (${cfg.adminUser})` : 'no'}`);
+      line('rooms', out.rooms.map((r) => `${r.table}${r.rows === null ? '' : ` ${r.rows}`}`).join('  ·  '));
+      line('ships', out.ships);
+      line('host', host ? host.id : 'not minted yet (first ship mints it)');
+      line('daemons', `shipper ${daemons.shipper ? `running (pid ${daemons.shipper})` : 'stopped'}   dashboard ${daemons.dashboard ? `running (pid ${daemons.dashboard}) → http://localhost:${cfg.port}` : 'stopped'}`);
+      line('bound', bound.length ? bound.map(short).join(', ') : 'no playbook is bound to this instance — memhouse plugins install claude');
+      break;
+    }
     case 'rooms': {
       // What are my rooms called? One answer, in one place: named for the member, inside the
       // configured house. It resolves through roomNames(), so it cannot drift from what the

package/memhouse/binding.js

@@ -0,0 +1,81 @@
+// An instance's plugin is bound to the instance that installed it.
+//
+// A memhouse INSTANCE is a home: an env file naming a house, the daemons that ship to it,
+// and the playbooks (Claude Code config dirs) whose sessions it ships. Its /mem:* skills
+// belong in exactly those playbooks, and inside them they must read THAT house and run
+// THAT binary — a machine can carry two instances on two channels, and a bare `memhouse`
+// with a session-inherited MEMHOUSE_HOME would pick whichever the shell happened to have.
+//
+// Claude Code applies a settings.json `env` block to every session under a config dir.
+// So `plugins install` stamps two variables there, beside the skills it copies:
+//
+//   MEMHOUSE_HOME  the instance's home  — which house the skills read
+//   MEMHOUSE_BIN   the instance's binary — which memhouse the skills run
+//
+// Nothing else in the file is touched; other env keys survive; `plugins remove` takes the
+// two back out. Pure functions here, file I/O below them, both unit-tested.
+
+const fs = require('fs');
+const path = require('path');
+
+const KEYS = ['MEMHOUSE_HOME', 'MEMHOUSE_BIN'];
+
+function bindSettings(json, { home, bin }) {
+  const out = { ...(json || {}) };
+  out.env = { ...(out.env || {}), MEMHOUSE_HOME: home, MEMHOUSE_BIN: bin };
+  return out;
+}
+
+function unbindSettings(json) {
+  const out = { ...(json || {}) };
+  if (out.env) {
+    out.env = { ...out.env };
+    for (const k of KEYS) delete out.env[k];
+    if (!Object.keys(out.env).length) delete out.env;
+  }
+  return out;
+}
+
+function boundTo(json) {
+  const env = (json && json.env) || {};
+  return env.MEMHOUSE_HOME ? { home: env.MEMHOUSE_HOME, bin: env.MEMHOUSE_BIN || null } : null;
+}
+
+function settingsPath(dir) { return path.join(dir, 'settings.json'); }
+
+function readSettings(dir) {
+  try { return JSON.parse(fs.readFileSync(settingsPath(dir), 'utf-8')); } catch { return null; }
+}
+
+function writeSettings(dir, json) {
+  fs.writeFileSync(settingsPath(dir), `${JSON.stringify(json, null, 2)}\n`);
+}
+
+/** Stamp the binding into a config dir's settings.json; returns what was written. */
+function bind(dir, { home, bin }) {
+  const cur = readSettings(dir);
+  if (cur === null && fs.existsSync(settingsPath(dir))) throw new Error(`${settingsPath(dir)} is not valid JSON — not touching it`);
+  writeSettings(dir, bindSettings(cur || {}, { home, bin }));
+  return { home, bin };
+}
+
+function unbind(dir) {
+  const cur = readSettings(dir);
+  if (!cur || !boundTo(cur)) return false;
+  writeSettings(dir, unbindSettings(cur));
+  return true;
+}
+
+/**
+ * What an instance is called: MEMHOUSE_NAME if the env file sets one, else its home
+ * directory with the conventional `.memhouse-` prefix removed — `~/.memhouse-stage` is
+ * "stage", `~/.memhouse` is "default", `~/alice-sandbox/memhouse` is "memhouse".
+ */
+function instanceName(home, envName = '') {
+  if (envName) return envName;
+  const base = path.basename(String(home || '').replace(/[\/]+$/, ''));
+  if (base === '.memhouse') return 'default';
+  return base.replace(/^\.memhouse-/, '') || 'default';
+}
+
+module.exports = { bindSettings, unbindSettings, boundTo, bind, unbind, readSettings, KEYS, instanceName };

package/memhouse/delivery/INVITATION.md.tpl

@@ -8,7 +8,7 @@ You received two things:
 
 | file | what it is |
 |---|---|
-| `{{FILE}}` | **your credential.** One-time: install consumes it and deletes it. Treat it like a password until then. |
+| `{{FILE}}` | **your credential**, in this same folder. One-time: install consumes it and deletes it. Treat it like a password until then. |
 | this page | the steps. Nothing secret in here. |
 
 Do it yourself, or hand this page to your coding agent. From the directory holding both
@@ -21,21 +21,39 @@ claude "Read MEMHOUSE-INVITATION.md and follow it. Ask me before each step that
 Any agent that can run shell commands works the same way; the rules it must keep are at
 the end of this page.
 
+## 0. Find your credential
+
+The install needs `{{FILE}}`, which was sent alongside this page. Confirm it is here first —
+run this from the same directory, and if it prints the filename you are ready:
+
+```
+ls invite-*.env
+```
+
+If it is missing, it did not travel with this page; get it from whoever invited you before
+going on. Do not print its contents — the last line of it is a password.
+
 ## 1. Install memhouse
 
 {{INSTALL}}
 
 On most Linux distros the global install needs `sudo`; if `npm` says `EACCES`, that is why.
+If you handed this page to an agent and it reports that a permission classifier blocked the
+install (a global `npm install` is exactly what such classifiers stop), run this one line
+yourself in a terminal and tell the agent to continue from step 2 — that is the intended
+split: the person installs software, the agent does the rest.
 `memhouse --version` should print `{{VERSION}}`.
 
 ## 2. Join the house
 
-From the directory holding `{{FILE}}`:
+From the directory holding `{{FILE}}`, just run memhouse — it finds the invitation and asks:
 
 ```
-memhouse install --env {{FILE}}
+memhouse
 ```
 
+(or, without the question: `memhouse install --env {{FILE}}`)
+
 What that does, in order: connects to `{{URL}}` as `{{NAME}}`, **rotates your password to
 one only your machine knows**, creates your rooms, writes your config to `~/.memhouse/env`,
 deletes `{{FILE}}`, and starts shipping in the background. The password in the file stops
@@ -115,6 +133,9 @@ narrower than the one memhouse issues — ask {{INVITER}} to run `memhouse insta
 You are installing memhouse for the person who handed you this file. Five rules; three of
 them exist because an agent broke them:
 
+0. **Your credential is `{{FILE}}` in the directory this page is in.** If `Read
+   MEMHOUSE-INVITATION.md` is all you were given, `ls invite-*.env` beside it is the file
+   the steps refer to; confirm it is there before step 1.
 1. **Never print `{{FILE}}` or any `MEMHOUSE_*` value.** No `cat`, no `echo $MEMHOUSE_PASSWORD`,
    no `set -x`. This very session will be shipped into the house; a password printed here is
    a password archived.

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

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

@@ -36,6 +36,13 @@ rows, and *you* read them.
 memhouse ships back into the house — the archive is insert-only, so a leaked credential
 cannot be withdrawn.
 
+**Which memhouse.** `plugins install` stamps two variables into this config directory's
+`settings.json`, so every session here carries them: `MEMHOUSE_HOME` is the instance whose
+house these skills read, and `MEMHOUSE_BIN` is that instance's binary. **Every `memhouse …`
+command in these skills means `"${MEMHOUSE_BIN:-memhouse}"`.** A machine can run two
+instances on two channels; the bare name would be whichever the shell found first. Do not
+override either variable.
+
 Credentials resolve **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`** (default
 `~/.memhouse/env`) — the same order the CLI uses. The dance below snapshots the
 environment first, because sourcing the file would otherwise clobber an already-exported

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

@@ -26,7 +26,7 @@ This runs the `memhouse invite` CLI and nothing else. **Do not hand-run `CREATE
 `GRANT` with an admin password substituted into a command** — that burns the credential
 into a transcript on disk. The CLI passes it to one process and never echoes it.
 
-1. **Check the binary:** `command -v memhouse`. Absent → tell the user to
+1. **Check the binary:** `command -v "${MEMHOUSE_BIN:-memhouse}"`. Absent → tell the user to
    `npm install -g memhouse`. There is no in-skill fallback, on purpose.
 
 2. **Gather only two things:** the invitee's **name** (validate `[A-Za-z][A-Za-z0-9_]*`;

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

@@ -32,6 +32,22 @@ stop:
 > `memhouse deploy --local` stands one up bound to loopback. Someone invited you?
 > `memhouse install --env invite-<you>.env`.
 
+## First: which memhouse this is
+
+Before anything else, run and show verbatim:
+
+```
+"${MEMHOUSE_BIN:-memhouse}" instance
+```
+
+One screen: the instance's name and home, the binary and channel, the house (server,
+database, member, whether an admin credential is present), the five rooms with row counts,
+what this machine ships, the host identity, the daemons, and which playbooks are bound to
+this instance. A machine can run several instances on different channels; this is how the
+user tells them apart, and how you know which house every answer below comes from. If the
+instance shown is not the one the user meant, stop and say so — the fix is launching
+under the right playbook, not overriding variables.
+
 ## The report
 
 Lead with the one-line verdict — *working and current*, *working but stale*, or *not

package/memhouse/envfile.js

@@ -46,4 +46,19 @@ function assertSingleLine(env) {
   }
 }
 
-module.exports = { parse, quoteShell, quoteSystemd, assertSingleLine };
+/**
+ * Which connection values in an env file's text differ from what a process currently holds.
+ * A running shipper was spawned with one credential; `install --env` rotates the password
+ * and rewrites the file, and a member can `memhouse passwd` under a running daemon. In
+ * both cases the FILE is the truth and the process copy is stale. Pure; used by the
+ * shipper (adopt on auth failure) and by install (adopt before spawning).
+ */
+function credentialDrift(text, current = {}) {
+  const file = parse(String(text || ''));
+  const keys = ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB'];
+  const changed = keys.filter((k) => file[k] !== undefined && file[k] !== current[k]);
+  const values = Object.fromEntries(changed.map((k) => [k, file[k]]));
+  return { changed, values };
+}
+
+module.exports = { credentialDrift, parse, quoteShell, quoteSystemd, assertSingleLine };

package/memhouse/flags.js

@@ -16,7 +16,7 @@ const COMMAND_FLAGS = {
   null: [], help: [], version: [],
   whoami: ['admin'],
   share: ['only', 'revoke', 'list'],
-  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], members: ['db','admin-user','admin-password'],
+  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], instance: [], members: ['db','admin-user','admin-password'],
   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',

package/memhouse/invitefile.js

@@ -0,0 +1,38 @@
+// An invite file found where the invitee is standing.
+//
+// The guide says "from the directory holding the file, run memhouse install --env <file>".
+// A person who just downloaded `invite-alice.env` and typed `memhouse` should not be shown
+// the help screen; they should be asked whether to join. This module finds candidate files
+// and reads what they promise; the CLI decides whether to ask, and install does the work.
+// Nothing here prints a value from the file — the URL, user and database are safe to show,
+// the password never is.
+
+const fs = require('fs');
+const path = require('path');
+const envfile = require('./envfile');
+
+const REQUIRED = ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB'];
+
+/** `invite-<name>.env` files in the given directories, first directory first. */
+function findInvites(dirs) {
+  const out = [];
+  for (const dir of dirs) {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const n of names.sort()) if (/^invite-[A-Za-z0-9_]+\.env$/.test(n)) out.push({ file: path.join(dir, n), dir });
+  }
+  return out;
+}
+
+/** What the file promises, without the secret. */
+function describeInvite(text) {
+  const parsed = envfile.parse(String(text || ''));
+  const missing = REQUIRED.filter((k) => !parsed[k]);
+  return {
+    user: parsed.MEMHOUSE_USER || null, url: parsed.MEMHOUSE_URL || null, db: parsed.MEMHOUSE_DB || null,
+    channel: parsed.MEMHOUSE_CHANNEL || null, isInvite: parsed.MEMHOUSE_INVITE === '1',
+    complete: missing.length === 0, missing,
+  };
+}
+
+module.exports = { findInvites, describeInvite, REQUIRED };

package/memhouse/provision.js

@@ -61,7 +61,10 @@ function plan({ db, member, password = null }) {
     { sql: `CREATE DATABASE IF NOT EXISTS ${db}`, why: 'the house', optional: false },
   ];
   if (password !== null) {
-    steps.push({ sql: `CREATE USER IF NOT EXISTS ${member} IDENTIFIED BY ${sqlString(password)}`, why: 'the member', optional: false });
+    // No IF NOT EXISTS. The live path checks first and refuses an existing user; the printed
+    // plan used to no-op here, apply the grants, and hand out a password the server never saw —
+    // found on a realm that mints its own users. Now it fails loudly on line one instead.
+    steps.push({ sql: `CREATE USER ${member} IDENTIFIED BY ${sqlString(password)}`, why: 'the member — fails if it already exists; then this password is NOT theirs', optional: false });
   }
   steps.push(
     { sql: roomGrant(db, member), why: `their rooms — ${db}.${roomPattern(member)} — and nothing else in the house`, optional: false },

package/memhouse/shipper/passlog.js

@@ -0,0 +1,37 @@
+// What the shipper's log says about its LAST pass.
+//
+// A daemon whose every pass fails is "running" by pid. A drill member's shipper failed
+// auth for twelve minutes while `status` said "shipper: running" and `doctor` was green,
+// and she — and her agent — read an empty house as "still catching up". The log beside
+// it had the answer on every pass. This reads it. Pure; the CLI reads the file.
+//
+// Lines have no timestamps, so "last" is textual order: the later of the last success
+// line and the last failure line wins.
+
+const OK = /\[memhouse\] shipped (\d+) sessions[^\n]*?→ (\d+) msg rows/;
+const FAIL = /\[memhouse\] pass failed: ([^\n]*)/;
+
+/** @returns {{outcome:'ok'|'failed'|null, sessions?:number, rows?:number, why?:string, auth?:boolean}} */
+function lastPass(logText) {
+  const text = String(logText || '');
+  let lastOk = -1; let lastFail = -1; let okM = null; let failM = null;
+  for (const m of text.matchAll(new RegExp(OK.source, 'g'))) { lastOk = m.index; okM = m; }
+  for (const m of text.matchAll(new RegExp(FAIL.source, 'g'))) { lastFail = m.index; failM = m; }
+  if (lastOk < 0 && lastFail < 0) return { outcome: null };
+  if (lastFail > lastOk) {
+    const why = failM[1].trim();
+    return { outcome: 'failed', why, auth: /Authentication failed|ACCESS_DENIED|Not enough privileges/i.test(why) };
+  }
+  return { outcome: 'ok', sessions: Number(okM[1]), rows: Number(okM[2]) };
+}
+
+/** One line for a person: null when there is nothing to say (no passes yet, or the last one was fine). */
+function describeFailure(lp) {
+  if (!lp || lp.outcome !== 'failed') return null;
+  const why = lp.why.length > 90 ? `${lp.why.slice(0, 87)}…` : lp.why;
+  return lp.auth
+    ? `the last pass FAILED — ${why} — restart it: memhouse stop && memhouse start`
+    : `the last pass FAILED — ${why} — see: memhouse doctor`;
+}
+
+module.exports = { lastPass, describeFailure };

package/memhouse/shipper/ship.js

@@ -1251,7 +1251,7 @@ async function printStats(client) {
 
 async function main() {
   const argv = process.argv.slice(2);
-  const client = makeClient();
+  let client = makeClient();
   try {
     if (argv.includes('--ensure-schema')) {
       const n = await ensureSchema(client);
@@ -1289,6 +1289,7 @@ async function main() {
           `${r.msgRows} msg rows, ${r.toolRows} tool rows in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
       } catch (e) {
         failed = true;
+        var adoptedCredential = false;
         // A connection failure arrives as an AggregateError whose own `message` is empty,
         // so this printed "[memhouse] pass failed:" and nothing else, after 35 lines of
         // driver internals. Dig out a cause and name the fix; `status` and `doctor`
@@ -1299,7 +1300,22 @@ async function main() {
         if (/ECONNREFUSED|fetch failed|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(why + causes.join(' '))) {
           console.error(`[memhouse] ${process.env.MEMHOUSE_URL} did not answer — is the house running?`);
         } else if (/Authentication failed|ACCESS_DENIED|Not enough privileges/i.test(why)) {
-          console.error(`[memhouse] the credential in ${process.env.MEMHOUSE_HOME || '~/.memhouse'}/env was rejected by ${process.env.MEMHOUSE_URL}`);
+          // This process was spawned with one credential; the env FILE may hold a newer one
+          // — `install --env` rotates the invite password and rewrites the file, and
+          // `memhouse passwd` can run under a live daemon. Retrying the dead copy for
+          // 300s a pass while the file beside it is right is what a drill member watched
+          // for twelve minutes. Adopt the file, rebuild the client, retry now.
+          const envPath = require('path').join(process.env.MEMHOUSE_HOME || require('path').join(require('os').homedir(), '.memhouse'), 'env');
+          let drift = { changed: [] };
+          try { drift = require('../envfile').credentialDrift(require('fs').readFileSync(envPath, 'utf-8'), process.env); } catch { /* no file: nothing to adopt */ }
+          if (drift.changed.length) {
+            for (const k of drift.changed) process.env[k] = drift.values[k];
+            client = makeClient();
+            adoptedCredential = true;
+            console.error(`[memhouse] ${envPath} holds a newer ${drift.changed.map((k) => k.replace('MEMHOUSE_', '').toLowerCase()).join('/')} — adopting it and retrying now`);
+          } else {
+            console.error(`[memhouse] the credential this shipper holds was rejected by ${process.env.MEMHOUSE_URL} (and ${envPath} says the same)`);
+          }
         } else if (/does not exist|UNKNOWN_TABLE|UNKNOWN_DATABASE/i.test(why)) {
           console.error('[memhouse] the house is missing a room this pass needed');
         }
@@ -1314,7 +1330,7 @@ async function main() {
       }
       full = false; // --full applies to the first pass only; loop passes stay incremental
       if (loop) {
-        const waitMs = failed ? Math.min(retryMs, intervalSec * 1000) : intervalSec * 1000;
+        const waitMs = failed ? (adoptedCredential ? 1000 : Math.min(retryMs, intervalSec * 1000)) : intervalSec * 1000;
         if (failed) {
           console.error(`[memhouse] retrying in ${Math.round(waitMs / 1000)}s`);
           retryMs = Math.min(retryMs * 2, intervalSec * 1000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhouse",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "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": {