pi-kanban 0.3.1 → 2.0.0

package/lib/net-guard.js

@@ -0,0 +1,277 @@
+'use strict';
+
+// Network boundary for a local-only dev server.
+//
+// Binding loopback is necessary but not sufficient. Three distinct attackers:
+//
+//   * LAN peer — http://192.168.1.42:3541/api/... The loopback bind stops this
+//     outright; the handshake never completes off-box.
+//   * DNS rebinding — the victim loads evil.com, the attacker re-resolves that
+//     name to 127.0.0.1, and the page fetches http://evil.com:3541/api/...
+//     The page's origin *is* evil.com:3541, so the request is same-origin and
+//     CORS never fires; the connection is to loopback, so the bind is satisfied.
+//     The only thing that differs from a legitimate request is the Host header,
+//     which script cannot forge. A Host allowlist is the entire defense.
+//   * Plain CSRF — evil.com POSTs straight at 127.0.0.1:3541. Host is a real
+//     allowlisted value, so hostGuard passes it; this needs a separate Origin /
+//     Sec-Fetch-Site check on state-changing methods.
+//
+// There is no authentication. Exposing this to a network means trusting everyone
+// on it with the user's pi history.
+
+const LOOPBACK_HOSTS = new Set([
+  'localhost',
+  '127.0.0.1',
+  '::1',
+  '0:0:0:0:0:0:0:1',
+  '::ffff:127.0.0.1',
+]);
+
+// Hoisted: parseHostHeader runs on every request, and neither the regex nor the
+// predicate depends on the argument.
+const PORT_RE = /^[0-9]{1,5}$/;
+// The port is validated but not compared — the listen(0) fallbacks make the real
+// port dynamic, so only the host is allowlisted.
+const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
+const KEEP_ALIVE_MS = 65000;
+// A whole IPv4 literal: a prefix test would let a rebinding name like 127.evil.com through.
+const LOOPBACK_V4_RE = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+
+function isLoopbackAddress(host) {
+  if (!host) return false;
+  // An Origin or URL host carries an IPv6 literal in brackets.
+  const h = String(host).toLowerCase().replace(/^\[(.*)\]$/, '$1');
+  return LOOPBACK_HOSTS.has(h) || LOOPBACK_V4_RE.test(h);
+}
+
+// Hand-parsed rather than via new URL(), which is far more permissive than we
+// want here and happily accepts things no real client sends. Returns the bare
+// hostname, lowercased, or null if the header is malformed.
+//
+// The port is deliberately ignored: ports are dynamic in these apps because of
+// the listen(0) fallback when the default is busy, so pinning one would break
+// the fallback path.
+function parseHostHeader(value) {
+  if (typeof value !== 'string') return null;
+  const raw = value.trim();
+  if (!raw || raw.length > 259) return null;
+
+  // Reject whitespace and control characters. Written as a code-point scan rather
+  // than a character class so it cannot be misread — a stray range in a regex
+  // here would silently reject legitimate hostnames containing a dash.
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) return null;
+  }
+  if (raw.includes('@')) return null; // userinfo has no business in a Host header
+
+  let host;
+  if (raw.startsWith('[')) {
+    const end = raw.indexOf(']');
+    if (end === -1) return null;
+    host = raw.slice(1, end);
+    const rest = raw.slice(end + 1);
+    if (rest && !(rest.startsWith(':') && validPort(rest.slice(1)))) return null;
+  } else {
+    const parts = raw.split(':');
+    if (parts.length > 2) return null; // bare IPv6 without brackets, or garbage
+    host = parts[0];
+    if (parts.length === 2 && !validPort(parts[1])) return null;
+  }
+
+  if (!host) return null;
+  if (host.endsWith('.')) host = host.slice(0, -1); // one trailing root dot is legal
+  if (!host) return null;
+  return host.toLowerCase();
+}
+
+function parseList(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function getFlag(name) {
+  const idx = process.argv.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = process.argv[idx];
+  if (arg.includes('=')) return arg.slice(arg.indexOf('=') + 1);
+  const next = process.argv[idx + 1];
+  return next && !next.startsWith('--') ? next : null;
+}
+
+/**
+ * @param {{appName?: string, selfFramedPaths?: string[]}} [config]
+ */
+function createNetGuard(config = {}) {
+  const appName = config.appName || 'This app';
+
+  const BIND_HOST = getFlag('host') || process.env.HOST || '127.0.0.1';
+  const BIND_HOST_LC = BIND_HOST.toLowerCase();
+  const EXPOSED = !isLoopbackAddress(BIND_HOST);
+  const ALLOWED_HOSTS = getFlag('allowed-hosts') || process.env.ALLOWED_HOSTS || '';
+  const extraHosts = new Set(parseList(ALLOWED_HOSTS));
+
+  // Resolved only once listen() succeeds — the requested port may have been busy.
+  let actualPort = null;
+
+  function hostAllowed(host) {
+    if (!host) return false;
+    if (isLoopbackAddress(host)) return true;
+    if (extraHosts.has(host)) return true;
+    // Binding a specific non-loopback address implies that address is a valid name for us.
+    if (EXPOSED && host === BIND_HOST_LC) return true;
+    return false;
+  }
+
+  function hostGuard(req, res, next) {
+    const host = parseHostHeader(req.headers.host);
+    if (hostAllowed(host)) return next();
+    res.status(403).type('text/plain').send(
+      `403 Forbidden - unrecognized Host header: ${req.headers.host || '(none)'}\n\n` +
+      `${appName} only answers requests addressed to localhost. This protects you\n` +
+      `from DNS rebinding, where a website you visit re-points its own hostname at\n` +
+      `127.0.0.1 in order to read your local data.\n\n` +
+      `If you meant to reach this from another machine, restart with:\n` +
+      `  --host 0.0.0.0 --allowed-hosts=${host || '<your-hostname>'}\n\n` +
+      `Only do that on a network you trust - there is no authentication.\n`
+    );
+  }
+
+  // true = allow, false = block, null = no Origin header, caller decides.
+  function originVerdict(origin) {
+    if (!origin || origin === 'null') return null;
+    let parsed;
+    try { parsed = new URL(origin); } catch { return false; }
+    if (!isLoopbackAddress(parsed.hostname)) return false;
+    // Same port, any loopback spelling. A different local port is a different app
+    // and has no business driving this one.
+    if (actualPort && parsed.port && Number(parsed.port) !== Number(actualPort)) return false;
+    return true;
+  }
+
+  function originGuard(req, res, next) {
+    if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next();
+
+    const verdict = originVerdict(req.headers.origin);
+    if (verdict === true) return next();
+    if (verdict === false) {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-origin ${req.method} from ${req.headers.origin} is not allowed.\n`);
+    }
+
+    // No Origin header: a non-browser client (curl, the CLI, the pi extension).
+    // Trust it unless the browser explicitly tells us otherwise.
+    const site = req.headers['sec-fetch-site'];
+    if (site && site !== 'same-origin' && site !== 'none') {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-site ${req.method} (Sec-Fetch-Site: ${site}) is not allowed.\n`);
+    }
+    return next();
+  }
+
+  // For a WebSocket upgrade, which originGuard must not judge: the handshake is a
+  // GET, and WebSocket has no CORS, so any page can open one. Browsers always send
+  // Origin on the handshake, so a missing or `null` one is refused, not trusted.
+  // Returns null when allowed, or the reason it was refused.
+  function upgradeVerdict(req) {
+    if (!hostAllowed(parseHostHeader(req.headers.host))) return 'unrecognized Host header';
+    if (originVerdict(req.headers.origin) !== true) return 'cross-origin or missing Origin';
+    return null;
+  }
+
+  // These pages may be framed by this app's own port under its loopback names, for a page
+  // that frames itself from its other name to get its own renderer process.
+  const selfFramed = new Set(config.selfFramedPaths || []);
+
+  function frameGuard(req, res, next) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    if (selfFramed.has(req.path)) {
+      const port = req.socket.localPort;
+      res.setHeader('Content-Security-Policy', `frame-ancestors 'self' http://localhost:${port} http://127.0.0.1:${port}`);
+      return next();
+    }
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'none'");
+    res.setHeader('X-Frame-Options', 'DENY');
+    next();
+  }
+
+  /**
+   * Bind BIND_HOST, then opportunistically serve the other loopback family on the
+   * same resolved port via a second server sharing the same request handler.
+   *
+   * That second bind is what keeps `http://localhost:<port>` working no matter how
+   * the OS resolver orders A/AAAA records - binding only 127.0.0.1 breaks hosts
+   * where `localhost` resolves to ::1, and vice versa. Doing it on the *resolved*
+   * port means every existing URL, startup banner and postMessage origin is
+   * unchanged. A family the host does not have is skipped. A port that another
+   * process holds on the other family is treated as busy: the primary closes and
+   * emits EADDRINUSE (port 0 picks another random port instead), because that process would answer `localhost:<port>` (and a
+   * cross-site frame on it) in our name. onReady waits for the second bind.
+   *
+   * Returns the primary server, so callers keep attaching their own 'error'
+   * handler for the EADDRINUSE fallback.
+   *
+   * @param {any} app express app (or any http request handler)
+   * @param {number} port 0 selects a free port
+   * @param {(port: number) => void} [onReady]
+   * `onUpgrade` is attached to both servers; a caller that attached it to the
+   * returned one alone would drop every WebSocket that arrives over the other family.
+   *
+   * @param {{maxHeaderSize?: number, onUpgrade?: (req: any, socket: any, head: Buffer) => void}} [opts]
+   */
+  function listenLoopback(app, port, onReady, opts = {}) {
+    const http = require('node:http');
+    const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
+    const makeServer = (handler) => {
+      const s = http.createServer(serverOpts, handler);
+      // Node's 5 s default closes idle sockets that the browser would reuse, and a
+      // fresh loopback connect is the one that some Windows network filters drop.
+      s.keepAliveTimeout = KEEP_ALIVE_MS;
+      if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
+      return s;
+    };
+    const server = makeServer(app);
+    let secondary = null;
+    let randomTries = 0;
+
+    server.on('listening', () => {
+      const boundPort = server.address().port;
+      actualPort = boundPort;
+      // Not actualPort: several servers can listen through one guard, and another one can bind
+      // while this one waits for its second family.
+      const ready = () => { if (onReady) onReady(boundPort); };
+      if (EXPOSED) return ready();
+      const otherFamily = BIND_HOST.includes(':') ? '127.0.0.1' : '::1';
+      try {
+        secondary = makeServer(app);
+        secondary.once('listening', ready);
+        secondary.on('error', (err) => {
+          if (err.code !== 'EADDRINUSE') return ready();
+          // A caller asking for port 0 has no fallback of its own, so it gets another random port here.
+          if (port === 0 && ++randomTries < 5) return server.close(() => server.listen(0, BIND_HOST));
+          server.close();
+          server.emit('error', err);
+        });
+        secondary.listen({ host: otherFamily, port: boundPort, ipv6Only: otherFamily === '::1' });
+      } catch {
+        ready();
+      }
+    });
+    server.on('close', () => { try { if (secondary) secondary.close(); } catch { /* already gone */ } });
+
+    server.listen(port, BIND_HOST);
+    return server;
+  }
+
+  function exposureWarning() {
+    if (!EXPOSED) return null;
+    return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
+  }
+
+  return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
+}
+
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress, KEEP_ALIVE_MS };

package/lib/one-line.js

@@ -0,0 +1,6 @@
+function oneLine(text, max) {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
+  return String(text ?? '').replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, max);
+}
+
+module.exports = { oneLine };

package/lib/open-editor.js

@@ -0,0 +1,173 @@
+'use strict';
+
+// Run a command without ever handing a string to a shell.
+//
+// The naive fix for command injection here — dropping `shell: true` — does not
+// work on Windows, and fails in two different ways:
+//
+//   * `spawn('code', args)` throws ENOENT, because the launcher on PATH is
+//     `code.cmd` and Node does not consult PATHEXT.
+//   * Resolving to `code.cmd` and spawning that throws EINVAL, because since the
+//     CVE-2024-27980 fix (Node 18.20.2 / 20.12.2 / 21.7.3+) a .bat/.cmd target
+//     may only be spawned with `shell: true` — the very thing we are removing.
+//
+// So on Windows we resolve the real .exe sitting behind the .cmd shim and spawn
+// that directly. Only when no such .exe exists (npm-style shims, which are node
+// scripts with no binary twin) do we fall back to cmd.exe, and that path applies
+// a character allowlist so the quoting cannot be broken out of.
+//
+// Forked from scripts/security-lib/open-editor.js in the claude-code-hub repo; this copy is
+// maintained here.
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const IS_WIN = process.platform === 'win32';
+
+// Characters that survive cmd.exe's double quotes and would let an argument
+// escape it. Inside "..." cmd treats & | < > ^ ( ) as literal, so only these
+// matter: '"' ends the quoted run, '%' triggers variable expansion whose value
+// could itself contain a quote. Neither is legal in an NTFS path anyway.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: NUL is one of the rejected characters
+const WIN_CMD_FORBIDDEN = /["%\r\n\u0000]/;
+
+function fail(message, status) {
+  return Object.assign(new Error(message), { status });
+}
+
+// The PATH walk below stats PATH.length × PATHEXT.length candidates — on a
+// typical Windows box ~1200 stats, several milliseconds. The answer cannot change
+// within a process unless PATH itself does, so it is memoized on both.
+const whichCache = new Map();
+
+// which(1). On Windows this walks PATHEXT so we learn the resolved extension —
+// that .cmd-vs-.exe distinction is what selects the launch strategy below.
+function whichSync(cmd) {
+  if (!cmd) return null;
+  if (cmd.includes('/') || cmd.includes('\\')) {
+    const abs = path.resolve(cmd);
+    try { return fs.statSync(abs).isFile() ? abs : null; } catch { return null; }
+  }
+  const key = `${process.env.PATH || ''}\u0000${process.env.PATHEXT || ''}\u0000${cmd}`;
+  if (whichCache.has(key)) return whichCache.get(key);
+  const found = whichUncached(cmd);
+  whichCache.set(key, found);
+  return found;
+}
+
+function whichUncached(cmd) {
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const exts = IS_WIN
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, cmd + ext);
+      try { if (fs.statSync(candidate).isFile()) return candidate; } catch { /* next */ }
+    }
+  }
+  return null;
+}
+
+// A native tool's .cmd shim normally lives at <install>/bin/foo.cmd next to
+// <install>/foo.exe. Returns that .exe so we can skip the shell entirely.
+// npm-installed shims have no such twin and correctly return null here.
+function exeBehindShim(shimPath) {
+  const bin = path.dirname(shimPath);
+  const root = path.dirname(bin);
+  const stem = path.basename(shimPath, path.extname(shimPath));
+  const candidates = [path.join(root, `${stem}.exe`), path.join(bin, `${stem}.exe`)];
+  for (const candidate of candidates) {
+    try { if (fs.statSync(candidate).isFile()) return candidate; } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * Validate a request-supplied path before it becomes a command argument, and
+ * return its resolved absolute form. Lives here rather than in each server so the
+ * rule cannot drift between the apps that share this helper.
+ *
+ * Deliberately not a containment check: opening an arbitrary project directory is
+ * the feature these endpoints exist for. The network boundary is the control.
+ *
+ * @param {unknown} value
+ * @param {string} label used in the error message
+ * @returns {string} resolved absolute path
+ */
+function assertOpenTarget(value, label = 'path') {
+  if (typeof value !== 'string' || !value.trim()) throw fail(`${label} must be a non-empty string`, 400);
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: NUL is one of the rejected characters
+  if (/[\r\n\u0000]/.test(value)) throw fail(`${label} contains invalid characters`, 400);
+  const resolved = path.resolve(value);
+  if (!fs.existsSync(resolved)) throw fail(`${label} does not exist`, 404);
+  return resolved;
+}
+
+/**
+ * Run a command without a shell and capture its output. On Windows a .cmd
+ * shim resolves to the real .exe behind it, with a fallback to an explicitly
+ * quoted cmd.exe line guarded by the character allowlist. Callers must still
+ * validate every argument — this stops shell metacharacters, not bad flags.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{cwd?: string, timeout?: number}} [opts]
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function execNoShell(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const resolved = whichSync(cmd);
+    if (!resolved) return reject(fail(`Command not found on PATH: ${cmd}`, 500));
+
+    let file = resolved;
+    let argv = args;
+    const spawnOpts = {
+      cwd: opts.cwd || undefined,
+      env: opts.env,
+      timeout: opts.timeout,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    };
+
+    const ext = path.extname(resolved).toLowerCase();
+    if (IS_WIN && (ext === '.cmd' || ext === '.bat')) {
+      const exe = exeBehindShim(resolved);
+      if (exe) {
+        file = exe;
+      } else {
+        for (const arg of [resolved, ...args]) {
+          if (WIN_CMD_FORBIDDEN.test(String(arg))) {
+            return reject(fail('Argument contains a character that cannot be passed safely', 400));
+          }
+        }
+        const line = [resolved, ...args].map((a) => `"${a}"`).join(' ');
+        file = process.env.ComSpec || 'cmd.exe';
+        argv = ['/d', '/s', '/c', `"${line}"`];
+        spawnOpts.windowsVerbatimArguments = true;
+      }
+    }
+
+    let child;
+    try {
+      child = spawn(file, argv, spawnOpts);
+    } catch (err) {
+      return reject(err);
+    }
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', reject);
+    child.on('close', (code, signal) => {
+      if (signal) return reject(new Error(`Command terminated by ${signal}: ${stderr.trim()}`));
+      // The claude CLI reports its own failures on stdout, so stderr alone is
+      // often empty and the caller would surface only the exit code.
+      if (code !== 0) return reject(new Error(stderr.trim() || stdout.trim() || `Command exited with code ${code}`));
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+module.exports = { assertOpenTarget, execNoShell, whichSync, exeBehindShim };

package/lib/panes.js

@@ -0,0 +1,213 @@
+// Per-session pane layout: the tabs next to Board. The file is the only copy, shared by every
+// board process on the config dir, the CLI and the agent. Which tab is on screen is each
+// browser tab's own state, not stored here. Expiry: docs/retention.md.
+
+const path = require('node:path');
+const { httpError } = require('./http-error');
+const { canonicalPath } = require('./linked-docs');
+const { isLoopbackAddress } = require('./net-guard');
+const { oneLine } = require('./one-line');
+const { pruneMap } = require('./retention');
+
+const MAX_PANES = 50;
+const MAX_TITLE = 100;
+const FILE_KINDS = new Set(['html', 'markdown', 'text', 'image']);
+const KINDS = new Set([...FILE_KINDS, 'url', 'message']);
+const MAX_MESSAGE_TARGET = 300;
+const isFileKind = (kind) => FILE_KINDS.has(kind);
+
+const portOf = (u) => Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+
+// A frame with allow-scripts plus allow-same-origin on the board's origin can reach
+// into its parent and drop its own sandbox. Every name the board is served under counts.
+function isOwnOrigin(url, { boardPort, boardHosts = [] }) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  const loopback = isLoopbackAddress(u.hostname);
+  return u.protocol === 'http:' && portOf(u) === boardPort && (loopback || boardHosts.includes(u.hostname));
+}
+
+const emptyLayout = () => ({ rev: 0, nextId: 1, panes: [], updatedAt: null });
+
+const targetKey = (kind, target) => (isFileKind(kind) ? `file:${canonicalPath(target)}` : `${kind}:${target}`);
+const paneKey = (p) => (p.companion ? `companion:${p.companion}` : targetKey(p.kind, p.target));
+
+function defaultTitle(kind, target) {
+  if (kind === 'message') return 'Message';
+  if (kind !== 'url') return path.basename(target);
+  try {
+    return new URL(target).host;
+  } catch {
+    return target;
+  }
+}
+
+const paneTitle = (kind, target, title) => oneLine(title, MAX_TITLE) || oneLine(defaultTitle(kind, target), MAX_TITLE);
+
+const idNumber = (id) => Number(id.slice(1)) || 0;
+
+function cleanLayout(raw) {
+  if (!raw || !Array.isArray(raw.panes) || !Number.isFinite(raw.updatedAt)) return null;
+  const ids = new Set();
+  const panes = raw.panes.filter((p) => {
+    const ok = p && typeof p.id === 'string' && !ids.has(p.id) && KINDS.has(p.kind) && typeof p.target === 'string' && p.target;
+    if (ok) ids.add(p.id);
+    return ok;
+  });
+  const nextId = Math.max(Number.isInteger(raw.nextId) ? raw.nextId : 1, ...panes.map((p) => idNumber(p.id) + 1));
+  const rev = Number.isInteger(raw.rev) && raw.rev > 0 ? raw.rev : 1;
+  return { rev, nextId, panes: panes.slice(0, MAX_PANES), updatedAt: raw.updatedAt };
+}
+
+const publicLayout = (l) => ({ rev: l.rev, panes: l.panes.map((p) => ({ ...p })), updatedAt: l.updatedAt });
+
+/**
+ * Every write re-reads the file first, so two boards on one config dir add to each other's
+ * layouts instead of overwriting them. The read-to-rename window is left open: both writers
+ * are one user's own board tabs and CLI calls.
+ *
+ * @param {object} o
+ * @param {() => object|null|undefined} o.load returns `{version: 2, sessions: {[id]: {rev, nextId, panes, updatedAt}}}`,
+ *   null when there is no file, or undefined when the file has not changed since the last load or save
+ * @param {(data: object) => void} o.save
+ * @param {(sessionId: string, layout: object) => void} [o.onChange] called for each layout whose rev
+ *   moved, from this store's writes and from `reload()` alike
+ */
+function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
+  let bySession = new Map();
+
+  function reload() {
+    const data = load();
+    if (data === undefined) return;
+    const next = new Map();
+    const saved = data?.sessions;
+    if (saved && typeof saved === 'object') {
+      for (const [id, raw] of Object.entries(saved)) {
+        const layout = cleanLayout(raw);
+        if (layout) next.set(id, layout);
+      }
+    }
+    const before = bySession;
+    bySession = next;
+    for (const [id, layout] of next) {
+      if (before.get(id)?.rev !== layout.rev) onChange(id, publicLayout(layout));
+    }
+  }
+  reload();
+
+  const persist = () => save({ version: 2, sessions: Object.fromEntries(bySession) });
+
+  function write(sessionId, layout) {
+    layout.rev += 1;
+    layout.updatedAt = now();
+    bySession.set(sessionId, layout);
+    persist();
+    onChange(sessionId, publicLayout(layout));
+    return publicLayout(layout);
+  }
+
+  function get(sessionId) {
+    const layout = bySession.get(sessionId);
+    return publicLayout(layout || emptyLayout());
+  }
+
+  // The same target added again returns its pane where it is, so a repeated `pane add` is harmless.
+  // `show` marks a show card's file, which the board renders with the card's theme. `companion`
+  // names the board-hosted tool a url pane shows, which the board starts again when its port is gone;
+  // a session has one pane per companion, whatever port its URL names.
+  function add(sessionId, { kind, target, title, show, companion }) {
+    if (!KINDS.has(kind)) throw httpError(400, `Unknown pane kind: ${kind}`, 'bad_kind');
+    if (kind === 'message' && target.length > MAX_MESSAGE_TARGET) {
+      throw httpError(400, `A message target holds at most ${MAX_MESSAGE_TARGET} characters`, 'bad_target');
+    }
+    reload();
+    const layout = bySession.get(sessionId) || emptyLayout();
+    const tool = kind === 'url' && companion;
+    const key = paneKey({ kind, target, companion: tool });
+    const existing = layout.panes.find((p) => paneKey(p) === key);
+    if (existing) return { pane: { ...existing }, added: false, layout: publicLayout(layout) };
+    if (layout.panes.length >= MAX_PANES) throw httpError(409, `A session holds at most ${MAX_PANES} panes`, 'pane_limit');
+    const pane = {
+      id: `p${layout.nextId++}`,
+      kind,
+      target,
+      title: paneTitle(kind, target, title),
+      ...(show && { show: true }),
+      ...(tool && { companion }),
+      addedAt: now(),
+    };
+    layout.panes.push(pane);
+    return { pane: { ...pane }, added: true, layout: write(sessionId, layout) };
+  }
+
+  // Returns the new layout, or null when the session has no such pane. An emptied layout stays
+  // until retention drops it, so its ids and rev keep counting up.
+  function remove(sessionId, paneId) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const i = layout ? layout.panes.findIndex((p) => p.id === paneId) : -1;
+    if (i < 0) return null;
+    layout.panes.splice(i, 1);
+    return write(sessionId, layout);
+  }
+
+  // Drops the show panes of these files; returns the new layout, or null when none matched.
+  function removeShow(sessionId, files) {
+    reload();
+    const layout = bySession.get(sessionId);
+    if (!layout) return null;
+    const keys = new Set(files.map((f) => targetKey('html', f)));
+    const kept = layout.panes.filter((p) => !(p.show && keys.has(targetKey(p.kind, p.target))));
+    if (kept.length === layout.panes.length) return null;
+    layout.panes = kept;
+    return write(sessionId, layout);
+  }
+
+  // An empty title gives the pane its default title back. Returns null when the session has no such pane.
+  function rename(sessionId, paneId, title) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const pane = layout?.panes.find((p) => p.id === paneId);
+    if (!pane) return null;
+    const next = paneTitle(pane.kind, pane.target, title);
+    if (next === pane.title) return get(sessionId);
+    pane.title = next;
+    return write(sessionId, layout);
+  }
+
+  // `order` is every pane id of the session, in the new tab order.
+  function reorder(sessionId, order) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const ids = layout ? layout.panes.map((p) => p.id) : [];
+    const valid = Array.isArray(order) && order.length === ids.length && new Set(order).size === ids.length;
+    if (!valid || !order.every((id) => ids.includes(id))) throw httpError(400, 'order must list every pane id once', 'bad_order');
+    if (!layout || order.every((id, i) => id === ids[i])) return get(sessionId);
+    layout.panes = order.map((id) => layout.panes.find((p) => p.id === id));
+    return write(sessionId, layout);
+  }
+
+  // Returns how many layouts went; writes only when one did.
+  function prune({ known, maxAgeMs }) {
+    reload();
+    const removed = pruneMap(bySession, (l) => l.updatedAt, { known, maxAgeMs, now: now() });
+    if (removed) persist();
+    return removed;
+  }
+
+  function fileTargets() {
+    const out = new Set();
+    for (const layout of bySession.values()) {
+      for (const p of layout.panes) if (isFileKind(p.kind)) out.add(p.target);
+    }
+    return out;
+  }
+
+  return { get, add, remove, removeShow, rename, reorder, prune, reload, fileTargets };
+}
+
+module.exports = { createPaneStore, isOwnOrigin, portOf, MAX_PANES, MAX_TITLE };