memhouse 0.18.12 → 0.20.1

package/memhouse/server/dashboard-auth.js

@@ -0,0 +1,181 @@
+// The dashboard's token: a per-user secret every /api request must present.
+//
+//   $MEMHOUSE_HOME/dashboard-token   64 hex characters (32 random bytes), mode 600, made by the
+//                                    first start when absent. A file group or other users can
+//                                    read or write is refused, as memhouse refuses such a password
+//                                    file (memhouse/admin-secret.js).
+//   $MEMHOUSE_HOME/dashboard.html    written by `memhouse dashboard`, mode 600: a page that
+//                                    redirects to http://127.0.0.1:<port>/#token=<token>. The
+//                                    browser is given this FILE, so the token is in no argv.
+//
+// The server reads the token from the file; it is never passed to it in argv or the environment.
+//
+// The token travels in the URL's fragment, which a browser sends to no server and puts in no
+// Referer. The page (ui/src/lib/dashboard-token.js) moves it to sessionStorage, which is scoped to
+// the exact origin, port included, strips it from the address bar, and sends it as
+// `Authorization: Bearer <token>` on every /api request. No cookie is set or accepted.
+//
+// /api/* without a valid Bearer: 401. The one exception is GET /api/proof?nonce=<hex>, which
+// answers HMAC(token, "memhouse dashboard proof:" + nonce): `memhouse dashboard` checks it before
+// it writes or opens anything, so the token is only ever handed to the server that holds it. The
+// static page itself carries no house data and needs no token. Every comparison is constant-time.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { readSecretFile } = require('../admin-secret');
+
+const TOKEN_FILE = 'dashboard-token';
+const OPENER_FILE = 'dashboard.html';
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+const NONCE_RE = /^[0-9a-f]{32,128}$/;
+const LABEL = 'the dashboard token';
+// The address the dashboard binds by default, opened literally: `localhost` can resolve to ::1
+// first, where a different listener may be.
+const LOOPBACK = '127.0.0.1';
+
+const tokenPath = (home) => path.join(home, TOKEN_FILE);
+const openerPath = (home) => path.join(home, OPENER_FILE);
+
+/** Create `file` holding `data`, mode 600, only when it does not exist. False when it already did. */
+function createExclusive(file, data) {
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, data, { mode: 0o600, flag: 'wx' });
+  try {
+    // link() fails when the name exists, so two starts at once agree on one token, and a reader
+    // never sees a half-written file.
+    try { fs.linkSync(tmp, file); return true; } catch (e) {
+      if (e.code === 'EEXIST') return false;
+      // A filesystem without hard links.
+      try { fs.writeFileSync(file, data, { mode: 0o600, flag: 'wx' }); return true; } catch (e2) {
+        if (e2.code === 'EEXIST') return false;
+        throw e2;
+      }
+    }
+  } finally { fs.rmSync(tmp, { force: true }); }
+}
+
+/**
+ * The token in `home`, checked: mode 600 (on POSIX) and 64 hex characters. Throws with the fix
+ * when it is absent, open to other users, or malformed.
+ */
+function readToken(home, io = {}) {
+  const file = tokenPath(home);
+  if (!fs.existsSync(file)) throw new Error(`${LABEL} ${file} does not exist — memhouse start creates it`);
+  const token = readSecretFile(file, io, LABEL).trim();
+  if (!TOKEN_RE.test(token)) {
+    throw new Error(`${LABEL} ${file} does not hold a token (64 hex characters) — delete it, then restart the dashboard (memhouse stop && memhouse start) to make a new one`);
+  }
+  return token;
+}
+
+/** The token in `home`, made first when there is none. Throws as readToken does. */
+function ensureToken(home, io = {}) {
+  const file = tokenPath(home);
+  if (!fs.existsSync(file)) {
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    createExclusive(file, `${crypto.randomBytes(32).toString('hex')}\n`);
+  }
+  return readToken(home, io);
+}
+
+const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest();
+/** Equal strings, in time that does not depend on where they differ (or on their lengths). */
+function tokensEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  return crypto.timingSafeEqual(sha256(a), sha256(b));
+}
+
+/** What the server holding `token` answers for `nonce` at /api/proof. */
+const proof = (token, nonce) => crypto.createHmac('sha256', token).update(`memhouse dashboard proof:${nonce}`).digest('hex');
+const newNonce = () => crypto.randomBytes(16).toString('hex');
+
+const baseUrl = (port) => `http://${LOOPBACK}:${port}`;
+const openUrl = (port, token) => `${baseUrl(port)}/#token=${token}`;
+
+/**
+ * Is this an /api request? Decided on the decoded, lower-cased path with repeated slashes folded,
+ * so no spelling the router might still match (`/API/…`, `//api/…`, `/api%2F…`) gets past it.
+ */
+function apiPath(req) {
+  let p = String(req.path || String(req.originalUrl || req.url || '/').split('?')[0]);
+  try { p = decodeURIComponent(p); } catch { /* malformed escapes: judged as written */ }
+  p = p.toLowerCase().replace(/\/{2,}/g, '/');
+  return p === '/api' || p.startsWith('/api/') ? p : null;
+}
+
+function deny(res) {
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('WWW-Authenticate', 'Bearer realm="memhouse"');
+  return res.status(401).json({ error: 'unauthorized — open the dashboard with: memhouse dashboard' });
+}
+
+/**
+ * Express middleware, ahead of every route. `token()` is read per request: until the server has
+ * read it, every /api request is refused. Paths outside /api (the page and its assets) pass.
+ */
+function middleware({ token }) {
+  return (req, res, next) => {
+    const p = apiPath(req);
+    if (!p) return next();
+    const t = token();
+    if (!t) return deny(res);
+    if (p === '/api/proof' && (req.method === 'GET' || req.method === 'HEAD')) {
+      const nonce = String((req.query && req.query.nonce) || '');
+      res.setHeader('Cache-Control', 'no-store');
+      if (!NONCE_RE.test(nonce)) return res.status(400).json({ error: 'nonce: 32 to 128 hex characters' });
+      return res.json({ proof: proof(t, nonce) });
+    }
+    const m = /^Bearer\s+(\S+)\s*$/i.exec(String(req.headers.authorization || ''));
+    if (m && tokensEqual(m[1], t)) return next();
+    return deny(res);
+  };
+}
+
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+/** The page `memhouse dashboard` opens: it redirects to `url`. Written mode 600; returns its path. */
+function writeOpener(home, url) {
+  const file = openerPath(home);
+  const u = escapeHtml(url);
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<meta http-equiv="refresh" content="0; url=${u}">
+<title>memhouse dashboard</title></head>
+<body><p><a href="${u}">Open the memhouse dashboard</a></p></body></html>
+`;
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, html, { mode: 0o600, flag: 'wx' });
+  try { fs.renameSync(tmp, file); } catch (e) { fs.rmSync(tmp, { force: true }); throw e; }
+  return file;
+}
+
+/**
+ * Ask the server on 127.0.0.1:<port> to prove it holds `token`, without sending the token.
+ * Resolves true only for the matching HMAC of a fresh nonce.
+ */
+function verifyServer(port, token, { timeoutMs = 3000 } = {}) {
+  const http = require('http');
+  const nonce = newNonce();
+  return new Promise((resolve) => {
+    const req = http.get({ host: LOOPBACK, port, path: `/api/proof?nonce=${nonce}`, timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.setEncoding('utf-8');
+      res.on('data', (d) => { if (body.length < 4096) body += d; });
+      res.on('end', () => {
+        let got = '';
+        try { got = String(JSON.parse(body).proof || ''); } catch { /* not ours */ }
+        resolve(res.statusCode === 200 && tokensEqual(got, proof(token, nonce)));
+      });
+    });
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', () => resolve(false));
+  });
+}
+
+module.exports = {
+  TOKEN_FILE, OPENER_FILE, LOOPBACK, tokenPath, openerPath, readToken, ensureToken, tokensEqual,
+  proof, newNonce, baseUrl, openUrl, apiPath, middleware, deny, writeOpener, verifyServer,
+};

package/memhouse/server/dashboard-port.js

@@ -0,0 +1,91 @@
+// The dashboard's port: which one it listens on, where that is recorded, and what `memhouse start`
+// says when the dashboard exits right after starting.
+//
+// The dashboard asks for MEMHOUSE_PORT (default 4640). When that port is in use it takes the next
+// free one, up to SPAN above it, and says which. When all of them are in use it exits, naming the
+// range and MEMHOUSE_PORT. The port it listens on is written to $MEMHOUSE_HOME/run/dashboard.port,
+// which `memhouse status`, `start` and `dashboard` read.
+
+const fs = require('fs');
+const path = require('path');
+
+const SPAN = 10;
+const DEFAULT_PORT = 4640;
+
+const portFile = (home) => path.join(home, 'run', 'dashboard.port');
+
+function recordPort(home, port) {
+  fs.mkdirSync(path.dirname(portFile(home)), { recursive: true });
+  fs.writeFileSync(portFile(home), String(port));
+}
+
+/** The port the running dashboard recorded, or null. */
+function readPort(home) {
+  try {
+    const n = parseInt(fs.readFileSync(portFile(home), 'utf-8').trim(), 10);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+  } catch { return null; }
+}
+
+const inUseNote = (wanted, got) => `port ${wanted} is in use, possibly by another account on this machine — the dashboard is on port ${got} instead (set MEMHOUSE_PORT to choose the port)`;
+const exhaustedNote = (wanted, last) => `ports ${wanted}–${last} are all in use, possibly by other accounts on this machine — set MEMHOUSE_PORT to a free port`;
+
+/**
+ * Listen on `port`, or the next free port up to `span` above it. Resolves with the port bound.
+ * Port 0 asks the system for any free port. `server` is a net/http server (or anything with the
+ * same listen/once/removeListener/address surface).
+ */
+function listen(server, { port, host, span = SPAN, log = () => {} }) {
+  const last = port === 0 ? 0 : Math.min(port + span, 65535);
+  return new Promise((resolve, reject) => {
+    const attempt = (p) => {
+      const onError = (err) => {
+        server.removeListener('listening', onListening);
+        if (err && err.code === 'EADDRINUSE' && p < last) return attempt(p + 1);
+        if (err && err.code === 'EADDRINUSE') return reject(Object.assign(new Error(exhaustedNote(port, last)), { code: 'EADDRINUSE' }));
+        return reject(err);
+      };
+      const onListening = () => {
+        server.removeListener('error', onError);
+        const a = server.address();
+        const bound = a && typeof a === 'object' ? a.port : p;
+        if (p !== port) log(inUseNote(port, bound));
+        resolve(bound);
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(p, host);
+    };
+    attempt(port);
+  });
+}
+
+// The line the dashboard prints before it exits for a reason it knows (a refused token file, every
+// port in the range in use). `memhouse start` quotes it.
+const CANNOT_START = 'cannot start:';
+
+/**
+ * What `memhouse start` says about a daemon that exited right after it was started, and whether
+ * that fails the command. The shipper is what `start` keeps running: when it exits, `start` exits 1.
+ * The dashboard is optional: when it exits, `start` warns and exits 0.
+ *
+ * @param {object} o
+ * @param {string} o.name      'shipper' | 'dashboard'
+ * @param {string} o.log       the tail of the daemon's log
+ * @param {number} o.port      the port the dashboard asked for
+ * @returns {{ fatal: boolean, why: string }}
+ */
+function earlyExit({ name, log = '', port }) {
+  const lines = String(log).split('\n').filter(Boolean).reverse();
+  const own = lines.find((l) => l.includes(`[memhouse] ${CANNOT_START}`));
+  let why = '';
+  if (own) why = own.slice(own.indexOf(CANNOT_START) + CANNOT_START.length).trim();
+  else {
+    const err = lines.find((l) => /EADDRINUSE|Error|error:/i.test(l));
+    if (/EADDRINUSE/.test(err || '')) why = `port ${port} is in use, possibly by another account on this machine — set MEMHOUSE_PORT to choose another port`;
+    else if (err) why = err.trim().slice(0, 200);
+  }
+  return { fatal: name !== 'dashboard', why };
+}
+
+module.exports = { SPAN, DEFAULT_PORT, CANNOT_START, portFile, recordPort, readPort, listen, earlyExit, inUseNote, exhaustedNote };

package/memhouse/server/queries.js

@@ -1151,7 +1151,37 @@ async function schema() {
   };
 }
 
+// ── the v3 dashboard's calls, answered on schema 2 ──────────────────────────────────
+// The SPA now loads the landing page in one request and polls cheap version tokens instead
+// of re-fetching (see ./api-v3.js). These keep one UI build working on a 0.18 house: the
+// landing composes the same five reads the page used to fan out (same cost, one HTTP call);
+// the tokens are bare `count(), max(ingested_at)` reads without FINAL — a session-key prefix
+// for one session, the small sessions room for the house. Any shipped write moves them.
+async function landing(opts = {}) {
+  const [overview, daily, stats, costs, chats, version] = await Promise.all([
+    getOverview(opts), getDailyActivity(opts), getDashboardStats(opts),
+    estimateCosts(opts), getChats({ ...opts, limit: 500, named: false }), houseVersion(),
+  ]);
+  const big = chats.filter((c) => c.bubbleCount >= 100).sort((a, b) => b.bubbleCount - a.bubbleCount);
+  return { overview, daily, stats, costs, largeContext: { total: big.length, chats: big.slice(0, 10) }, version: version.token };
+}
+
+async function houseVersion() {
+  const [row] = await q('SELECT count() AS n, toString(max(ingested_at)) AS last FROM {{sessions_raw}}', {}, { final: 0 });
+  return { token: `${row.n}:${row.last}`, sessions: Number(row.n) };
+}
+
+async function getChatVersion(id) {
+  const cut = String(id).lastIndexOf('::');
+  const sid = cut === -1 ? String(id) : String(id).slice(0, cut);
+  const uid = cut === -1 ? null : String(id).slice(cut + 2);
+  const [row] = await q(`SELECT count() AS n, toString(max(ingested_at)) AS last FROM {{messages_raw}}
+    WHERE session_id = {sid:String}${uid ? ' AND user_id = {uid:String}' : ''}`, uid ? { sid, uid } : { sid }, { final: 0 });
+  return Number(row.n) ? { version: `${row.n}:${row.last}`, messages: Number(row.n) } : null;
+}
+
 module.exports = { adoptMovedHouse,
+  landing, houseVersion, getChatVersion, schemaVersion: 2,
   getClient, config,
   getOverview, getDailyActivity, getDashboardStats,
   getChats, countChats, getChat,

package/memhouse/server/server.js

@@ -5,27 +5,48 @@
 // queries.js computes every response; this file is routing + config + stubs. Serves
 // the built SPA from the repo root's public/.
 //
+// Every /api request needs the dashboard's token as a Bearer ($MEMHOUSE_HOME/dashboard-token,
+// read from the file at start): ./dashboard-auth.js. `memhouse dashboard` opens the page with it.
+//
 //   node memhouse/server/server.js        (env: MEMHOUSE_* per DESIGN.md; port 4640)
 
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const qy = require('./queries');
-
-const PORT = parseInt(process.env.MEMHOUSE_PORT || '4640', 10);
-// Localhost by default: the dashboard exposes full transcripts and a SQL console
-// with no auth. Remote access is an explicit opt-in (MEMHOUSE_HOST=0.0.0.0).
+// MEMHOUSE_SCHEMA=3: the conversation layer of docs/design/source-identity.md (sessions /
+// turns / calls) through the named queries; otherwise the 0.18 rooms. Same routes, same shapes.
+const SCHEMA = process.env.MEMHOUSE_SCHEMA === '3' ? 3 : 2;
+const qy = SCHEMA === 3 ? require('./api-v3') : require('./queries');
+
+const dashAuth = require('./dashboard-auth');
+const dashPort = require('./dashboard-port');
+
+// The port asked for; when it is in use the server takes the next free one (./dashboard-port.js).
+const PORT = parseInt(process.env.MEMHOUSE_PORT || String(dashPort.DEFAULT_PORT), 10);
+// Localhost by default: the dashboard serves full transcripts and a SQL console. Remote
+// access is an explicit opt-in (MEMHOUSE_HOST=0.0.0.0); the token is required either way.
 const HOST = process.env.MEMHOUSE_HOST || '127.0.0.1';
 const PUBLIC_DIR = path.join(__dirname, '..', '..', 'public');
+const HOME = process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse');
 // MEMHOUSE_HOME, like every other component. childEnv() already passes it to this child;
 // this was the one place that ignored it and wrote to the real home instead. Anyone
 // running a second house under MEMHOUSE_HOME — the documented way to test, and what every
 // acceptance run is told to do — hid a project in their throwaway dashboard and had it
-// written into the PILOT'S ~/.memhouse/config.json.
-const CONFIG_PATH = path.join(process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse'), 'config.json');
+// written into the USER'S ~/.memhouse/config.json.
+const CONFIG_PATH = path.join(HOME, 'config.json');
+
+// Set when the server starts listening. Until both are set, and whenever the module is loaded
+// without being run, every request is refused.
+let TOKEN = null;
+let BOUND_PORT = null;
 
 const app = express();
+// Routes match their path exactly as written, so the token check and the router agree on what
+// an /api path is (dashboard-auth.js also folds case and slashes, on its own side).
+app.set('case sensitive routing', true);
+// First, ahead of the static files, the body parser and every route.
+app.use(dashAuth.middleware({ token: () => TOKEN }));
 app.use(express.json());
 if (fs.existsSync(PUBLIC_DIR)) app.use(express.static(PUBLIC_DIR));
 
@@ -55,14 +76,26 @@ const route = (fn) => async (req, res) => {
     // `new Error('')` — no message, no code, no own keys. An empty error is a dead end for
     // whoever is looking, so say what we do know: the class of failure and the route.
     const why = (err && err.message) || (err && err.code) || `${err && err.constructor ? err.constructor.name : 'Error'} with no message — often the server or a proxy in front of it refusing the request (URI too long, body too large, timeout)`;
+    // A bad cursor, an unknown harness:id form, an empty search: the caller's mistake, a 400.
+    if (err && err.status === 400) return res.status(400).json({ error: String(why) });
     console.error(`[memhouse] ${req.method} ${req.originalUrl} failed: ${why}`);
     res.status(500).json({ error: String(why) });
   }
 };
 
-app.get('/api/ping', (req, res) => res.json({ app: 'agentlytics', pid: process.pid }));
+app.get('/api/ping', (req, res) => res.json({ app: 'agentlytics', pid: process.pid, schema: SCHEMA }));
 app.get('/api/mode', (req, res) => res.json({ mode: 'local' }));
 
+// The landing page in ONE request: overview, daily activity, stats, costs and the large-context
+// card, plus the house version token. Replaces the five-endpoint fan-out (33–34 statements on
+// schema 2; 11 small reads of sessions FINAL on schema 3).
+app.get('/api/landing', route(async (req, res) => {
+  res.json(await qy.landing({ editor: req.query.editor || req.query.harness || null, ...parseDateOpts(req.query), hiddenFolders: hiddenFolders() }));
+}));
+
+// The house-wide change token Live polls. It never ships anything.
+app.get('/api/version', route(async (req, res) => res.json(await qy.houseVersion())));
+
 app.get('/api/overview', route(async (req, res) => {
   res.json(await qy.getOverview({ editor: req.query.editor || null, ...parseDateOpts(req.query), hiddenFolders: hiddenFolders() }));
 }));
@@ -89,18 +122,62 @@ app.get('/api/chats', route(async (req, res) => {
     ...parseDateOpts(req.query),
     hiddenFolders: hiddenFolders(),
   };
+  // Schema 3: keyset pagination — `cursor` is the opaque `nextCursor` of the previous page
+  // (offset is not supported there; no UI caller ever sent one).
+  if (qy.listChats) {
+    if (req.query.harness) opts.harness = String(req.query.harness);
+    return res.json(await qy.listChats({ ...opts, cursor: req.query.cursor || null }));
+  }
   const [total, chats] = await Promise.all([qy.countChats(opts), qy.getChats(opts)]);
   res.json({ total, chats });
 }));
 
 app.get('/api/chats/:id', route(async (req, res) => {
-  const result = await qy.getChat(req.params.id);
+  // Schema 3 returns the header and the TAIL page of turns (`prevCursor` pages back through
+  // /turns); schema 2 returns the whole session, as before.
+  const result = await qy.getChat(req.params.id, SCHEMA === 3 ? {
+    limit: clampInt(req.query.limit, 1000, 1, 5000), agent: req.query.agent ?? null,
+  } : undefined);
   if (!result) return res.status(404).json({ error: 'Chat not found' });
   res.json(result);
 }));
 
+// The sidebar poll: one point read of the session's version. The client refetches turns only
+// when it changes.
+app.get('/api/chats/:id/version', route(async (req, res) => {
+  const v = await qy.getChatVersion(req.params.id);
+  if (!v) return res.status(404).json({ error: 'Chat not found' });
+  res.json(v);
+}));
+
+// A page of turns and the calls it owns. `dir=backward` (default) pages from the end.
+app.get('/api/chats/:id/turns', route(async (req, res) => {
+  if (!qy.getChatTurns) return res.status(501).json({ error: 'paged turns need MEMHOUSE_SCHEMA=3' });
+  const page = await qy.getChatTurns(req.params.id, {
+    cursor: req.query.cursor || null, dir: req.query.dir === 'forward' ? 'forward' : 'backward',
+    limit: clampInt(req.query.limit, 500, 1, 5000), agent: req.query.agent ?? null,
+  });
+  if (!page) return res.status(404).json({ error: 'Chat not found' });
+  res.json(page);
+}));
+
+app.get('/api/search', route(async (req, res) => {
+  if (!qy.search) return res.status(501).json({ error: 'search needs MEMHOUSE_SCHEMA=3' });
+  if (!req.query.q) return res.status(400).json({ error: 'q query param required' });
+  res.json(await qy.search({
+    q: String(req.query.q), match: req.query.match === 'word' ? 'word' : 'substring',
+    harness: req.query.harness || req.query.editor || null, folder: req.query.folder || null, project: req.query.project || null,
+    limit: clampInt(req.query.limit, 20, 1, 200), ...parseDateOpts(req.query),
+  }));
+}));
+
+app.get('/api/models', route(async (req, res) => {
+  if (!qy.models) return res.status(501).json({ error: 'models need MEMHOUSE_SCHEMA=3' });
+  res.json(await qy.models({ editor: req.query.editor || req.query.harness || null, folder: req.query.folder || null, ...parseDateOpts(req.query), hiddenFolders: hiddenFolders() }));
+}));
+
 app.get('/api/chats/:id/markdown', route(async (req, res) => {
-  const result = await qy.getChat(req.params.id);
+  const result = qy.getChatAll ? await qy.getChatAll(req.params.id) : await qy.getChat(req.params.id);
   if (!result) return res.status(404).json({ error: 'Chat not found' });
   const lines = [];
   const title = result.name || 'Untitled Session';
@@ -400,16 +477,25 @@ app.put('/api/config', route(async (req, res) => {
   res.json(config);
 }));
 
-// Real refetch: run one full shipper pass, streaming SSE like the root contract.
-// POST, not GET. A full re-ship behind a GET is the easiest request on a machine to make
-// by accident — a prefetch, a link checker, a curl in a log. The dashboard calls it
-// explicitly, so nothing legitimate depended on the verb.
+// Refetch, streaming SSE like the root contract. POST, not GET: a re-ship behind a GET is the
+// easiest request on a machine to make by accident — a prefetch, a link checker, a curl in a
+// log. The dashboard calls it explicitly, so nothing legitimate depended on the verb.
+//
+// It NEVER runs a full ship (draft 5 §5). A full pass re-inserted every current-parse row
+// (~309k messages) and re-ran the stat refresh, and Live used to do it every 60 s. Schema 2
+// runs one INCREMENTAL pass; schema 3 ships nothing at all — the capture engine runs on its
+// own timer — and answers with the house version so the page knows whether to re-read.
 app.post('/api/refetch', async (req, res) => {
   res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
   try {
-    const { runShip } = require('../shipper/ship');
     res.write(`data: ${JSON.stringify({ scanned: 0, analyzed: 0, skipped: 0, total: 0 })}\n\n`);
-    const r = await runShip(qy.getClient(), { full: true });
+    if (SCHEMA === 3) {
+      const v = await qy.houseVersion();
+      res.write(`data: ${JSON.stringify({ done: true, total: v.sessions, analyzed: 0, version: v.token })}\n\n`);
+      return res.end();
+    }
+    const { runShip } = require('../shipper/ship');
+    const r = await runShip(qy.getClient(), { full: false });
     res.write(`data: ${JSON.stringify({ done: true, total: r.sessions + r.skipped, analyzed: r.sessions })}\n\n`);
   } catch (err) {
     res.write(`data: ${JSON.stringify({ error: err.message })}\n\n`);
@@ -443,15 +529,27 @@ app.get('*', (req, res) => {
 });
 
 if (require.main === module) {
+  // The token, from its file only (never argv or the environment). Made when absent; a file
+  // other users can read is refused.
+  try { TOKEN = dashAuth.ensureToken(HOME); } catch (e) {
+    console.error(`[memhouse] ${dashPort.CANNOT_START} ${e.message}`);
+    process.exit(1);
+  }
   // Before serving: has the house moved under us? (see queries.adoptMovedHouse)
   qy.adoptMovedHouse().catch(() => {});
-  app.listen(PORT, HOST, () => {
-    console.log(`[memhouse] dashboard → http://localhost:${PORT} (house '${qy.config.database}' @ ${qy.config.url.replace(/\/\/.*@/, '//')})`
-      + (HOST !== '127.0.0.1' ? ` [bound to ${HOST} — remotely reachable]` : ''));
+  const server = require('http').createServer(app);
+  dashPort.listen(server, { port: PORT, host: HOST, log: (l) => console.log(`[memhouse] ${l}`) }).then((port) => {
+    BOUND_PORT = port;
+    try { dashPort.recordPort(HOME, port); } catch (e) { console.error(`[memhouse] could not record the port in ${dashPort.portFile(HOME)}: ${e.message}`); }
+    console.log(`[memhouse] dashboard listening on ${HOST}:${port} — open it with: memhouse dashboard (house '${qy.config.database}' @ ${qy.config.url.replace(/\/\/.*@/, '//')}, schema ${SCHEMA})`
+      + (HOST !== '127.0.0.1' ? ` [bound to ${HOST} — remotely reachable; the token is required]` : ''));
+  }).catch((e) => {
+    console.error(`[memhouse] ${dashPort.CANNOT_START} ${e.code === 'EADDRINUSE' ? e.message : `listening on ${HOST}:${PORT} failed: ${e.message}`}`);
+    process.exit(1);
   });
   // An upgrade replaces public/ as well as the code, and this process holds neither: the
   // static middleware bound to the old directory at boot, so the SPA it serves stays the
-  // old bundle however many times the pilot reloads. The shipper checks once per pass; a
+  // old bundle however many times the user reloads. The shipper checks once per pass; a
   // server has no pass, so it polls. unref() so the timer never holds the process open.
   const selfUpdate = require('../self-update');
   const snap = selfUpdate.snapshot(__filename);

package/memhouse/service.js

@@ -74,7 +74,7 @@ Type=simple
 # Restart=always, not on-failure: the shipper EXITS 0 ON PURPOSE when an upgrade replaces
 # the files underneath it (self-update.js, supervised path) and counts on the supervisor
 # to start the new version. Under on-failure that handover left the service dead after
-# every npm upgrade — found on testbed, service inactive(dead) status=0/SUCCESS.
+# every npm upgrade — found on a test VM, service inactive(dead) status=0/SUCCESS.
 # RestartSec plus self-update's re-exec chain cap guard against restart loops.
 ${envLines(env)}
 ExecStart=${[node, script, ...args].map(execToken).join(' ')}