@elu-labs/elu 0.0.0-stage → 0.1.0

package/lib/peer/status.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import { atomic, noSymlinks, readJson, isObject } from '../util.mjs';
+import { tasks } from '../state.mjs';
+import { git } from '../git.mjs';
+import { registeredProjects } from '../projects.mjs';
+import { ABOUT_MAX, BOT_NAME, botOfKey, sharedBots } from '../bots.mjs';
+import { peerFile } from './paths.mjs';
+import { sanitize } from './peerdata.mjs';
+import { BOX, peerBox } from './settings.mjs';
+import { shares } from './shares.mjs';
+
+// Status rows (docs/peer-network.md, "Status"): one per live editing task in
+// a project shared with status on. Overlap is computed here, never asked for.
+const LIVE = ['preparing', 'running', 'ready', 'needs_input'];
+const HEX64 = /^[0-9a-f]{64}$/;
+const HANDLE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const FILES_MAX = 200, ROWS_MAX = 50;
+const firstLine = (value, max) => sanitize(String(value ?? '').split('\n')[0], max).trim();
+function changedFiles(task) {
+  const names = git(task.worktree, ['diff', '--no-ext-diff', '--no-textconv', '--name-only', '-z', task.base, '--'], { allowFailure: true });
+  const extra = git(task.worktree, ['ls-files', '--others', '--exclude-standard', '-z'], { allowFailure: true });
+  return [...new Set([names, extra].flatMap(r => r.status === 0 ? r.stdout.split('\0').filter(Boolean) : []))].sort().slice(0, FILES_MAX);
+}
+// Who is at work, as a teammate reads it. A bot the owner shares is @name; any other bot is
+// only "bot", since teammates are not told its name.
+const working = (role, shared) => { const bot = botOfKey(role); return bot === null ? role : shared.has(bot) ? `@${bot}` : 'bot'; };
+export function statusRows() {
+  const repos = registeredProjects(), rows = [];
+  let shared = new Set(); try { shared = new Set(sharedBots().map(bot => bot.name)); } catch { /* An unreadable bots file shares nothing. */ }
+  for (const share of shares().filter(row => row.status && row.repoId)) {
+    const repo = repos.find(row => row.root === share.root); if (!repo) continue;
+    let values = []; try { values = tasks(repo); } catch { continue; }
+    for (const task of values.filter(task => task.kind !== 'conversation' && LIVE.includes(task.state))) {
+      if (rows.length >= ROWS_MAX) return rows;
+      let files = []; try { files = changedFiles(task); } catch { files = []; }
+      rows.push({ repoId: share.repoId, handle: share.handle, taskId: task.id, label: firstLine(task.goal, 80), now: firstLine(task.activeRole ? `${task.state} · ${working(task.activeRole, shared)}` : task.state, 80), files });
+    }
+  }
+  return rows;
+}
+const plainFile = value => typeof value === 'string' && value.length <= 512 && !value.startsWith('/') && !/[\x00-\x1f\x7f\\]/.test(value) && !value.split('/').some(part => part === '..' || part === '.' || !part);
+// Rows from another machine: anything malformed is dropped, text is sanitized.
+export function cleanRows(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, ROWS_MAX).flatMap(row => {
+    if (!isObject(row) || !HEX64.test(row.repoId ?? '') || !HANDLE.test(row.handle ?? '') || !/^[1-9][0-9]{0,9}$/.test(String(row.taskId ?? '')) || !Array.isArray(row.files)) return [];
+    return [{ repoId: row.repoId, handle: row.handle, taskId: String(row.taskId), label: firstLine(row.label, 80), now: firstLine(row.now, 80), files: row.files.filter(plainFile).slice(0, FILES_MAX) }];
+  });
+}
+export function saveRemoteStatus(key, rows) {
+  if (!HEX64.test(key)) return;
+  atomic(peerFile('status', `${key}.json`), { at: new Date().toISOString(), rows: cleanRows(rows) });
+}
+export function remoteStatus(key) {
+  try { const file = peerFile('status', `${key}.json`); noSymlinks(file); if (!HEX64.test(key) || !fs.existsSync(file)) return null; const value = readJson(file); return { at: value.at, rows: cleanRows(value.rows) }; } catch { return null; }
+}
+// elu.status also says what the machine is called (box) and which bots its owner lets
+// teammates use (bots: [{name, about}], at most BOTS_TOLD). A build from before bots reads
+// only the rows and sends neither, which reads here as no box name and no bots.
+export const BOTS_TOLD = 20;
+// From another machine each field stands alone: a box name that is not one is null, a bot
+// with a bad name or an about that is not text is dropped, an about is cut to one plain line.
+export const cleanBox = value => typeof value === 'string' && BOX.test(value) ? value : null;
+export function cleanBots(value) {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set();
+  return value.slice(0, BOTS_TOLD).flatMap(bot => {
+    if (!isObject(bot) || typeof bot.name !== 'string' || !BOT_NAME.test(bot.name) || typeof bot.about !== 'string' || seen.has(bot.name)) return [];
+    seen.add(bot.name);
+    return [{ name: bot.name, about: sanitize(bot.about, 2000).replace(/\s+/g, ' ').trim().slice(0, ABOUT_MAX).trimEnd() }];
+  });
+}
+// This machine as teammates are told of it. A bots file that cannot be read shares none.
+export function thisMachine() {
+  let bots = []; try { bots = sharedBots(); } catch { /* Nothing is shared until the file is fixed. */ }
+  return { box: peerBox(), bots: cleanBots(bots) };
+}
+// Each teammate row gains overlap: files it shares with my live rows of the same repoId.
+export function overlaps(mine, theirs) {
+  return theirs.map(row => {
+    const local = new Set(mine.filter(m => m.repoId === row.repoId).flatMap(m => m.files));
+    return { ...row, overlap: row.files.filter(file => local.has(file)) };
+  });
+}

package/lib/peer/taskstore.mjs

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomic, hash, noSymlinks, readJson, refuse, isObject } from '../util.mjs';
+import { canonical } from './canonical.mjs';
+import { waitLock } from '../state.mjs';
+import { peerFile, peerRepo } from './paths.mjs';
+import { isTerminal, validId, validateTask } from './a2a.mjs';
+
+// Tasks this machine serves (incoming asks), one file each, so they survive restarts.
+// A record is {task, peer, name, messageId, threadId, kind, project, root, requestId,
+// text, waiting, reply, costUsd, localTaskId, createdAt}. The idempotency index maps
+// (sender key, messageId) to the taskId that SendMessage returned the first time.
+const HEX64 = /^[0-9a-f]{64}$/;
+const INDEX_MAX = 20000;
+const dir = () => peerFile('tasks');
+const file = id => path.join(dir(), `${validId(id, 'Task id')}.json`);
+const indexFile = () => peerFile('idempotency.json');
+const locked = fn => { const release = waitLock(peerRepo(), 'tasks'); try { return fn(); } finally { release(); } };
+export function getRecord(id) {
+  let target; try { target = file(id); } catch { return null; }
+  noSymlinks(target); if (!fs.existsSync(target)) return null;
+  try { const record = readJson(target); return isObject(record) && record.task?.id === id ? record : null; } catch { return null; }
+}
+export function saveRecord(record) {
+  if (!HEX64.test(record?.peer ?? '')) refuse('A served task needs the sender key.');
+  record.task = validateTask(record.task);
+  atomic(file(record.task.id), record); return record;
+}
+// Read-modify-write of one record under the store lock; fn returns the new record or null.
+export function updateRecord(id, fn) {
+  return locked(() => { const record = getRecord(id); if (!record) return null; const next = fn(record); return next ? saveRecord(next) : record; });
+}
+export function records() {
+  noSymlinks(dir()); if (!fs.existsSync(dir())) return [];
+  return fs.readdirSync(dir()).filter(name => name.endsWith('.json')).flatMap(name => { const record = getRecord(name.slice(0, -5)); return record ? [record] : []; });
+}
+export const findByRequest = requestId => records().find(record => record.requestId === requestId) ?? null;
+function readIndex() {
+  try { noSymlinks(indexFile()); if (!fs.existsSync(indexFile())) return {}; const value = readJson(indexFile()); return isObject(value) ? value : {}; } catch { return {}; }
+}
+const indexKey = (peer, messageId) => `${peer}:${messageId}`;
+export function lookup(peer, messageId) { const row = readIndex()[indexKey(peer, messageId)]; return typeof row?.taskId === 'string' ? row.taskId : null; }
+// With replace, an entry whose record is missing (a crash after remember) is repointed.
+export function remember(peer, messageId, taskId, { replace = false } = {}) {
+  return locked(() => {
+    const index = readIndex(), key = indexKey(peer, messageId);
+    if (index[key] && !(replace && !getRecord(index[key].taskId))) return index[key].taskId;
+    index[key] = { taskId, at: Date.now() };
+    const entries = Object.entries(index);
+    // The oldest entries go first once the index is full; their tasks are long finished.
+    const kept = entries.length > INDEX_MAX ? Object.fromEntries(entries.sort((a, b) => b[1].at - a[1].at).slice(0, INDEX_MAX)) : index;
+    atomic(indexFile(), kept); return taskId;
+  });
+}
+
+// threads/<threadId>.jsonl is the audit log of a thread, both directions. Each line is
+// {at, dir, peer, kind, text, cost, prev, hash}: prev is the previous line's hash and
+// hash is sha256 over the canonical line without it, so an edited line breaks the chain.
+const THREAD = /^[A-Za-z0-9_-]{1,128}$/;
+export const THREAD_MAX = 4 * 1024 * 1024;
+// The last line of a thread file, read from its end so a long thread is never read whole.
+function lastLine(target, size) {
+  const length = Math.min(size, 2 * 1024 * 1024), buffer = Buffer.alloc(length), fd = fs.openSync(target, 'r');
+  try { fs.readSync(fd, buffer, 0, length, size - length); } finally { fs.closeSync(fd); }
+  return buffer.toString('utf8').trimEnd().split('\n').at(-1) || 'null';
+}
+// Lines are appended under the thread lock; a thread past THREAD_MAX records no more.
+export function audit(threadId, { dir: direction, peer, kind, text = '', cost = null }) {
+  if (!THREAD.test(threadId ?? '')) return null;
+  const target = peerFile('threads', `${threadId}.jsonl`);
+  const release = waitLock(peerRepo(), `thread-${threadId}`);
+  try {
+    noSymlinks(target);
+    const size = fs.existsSync(target) ? fs.statSync(target).size : 0;
+    if (size > THREAD_MAX) return null;
+    let prev = null; try { prev = size ? JSON.parse(lastLine(target, size))?.hash ?? null : null; } catch { prev = null; }
+    const line = { at: new Date().toISOString(), dir: direction, peer, kind, text: String(text).slice(0, 160000), cost, prev };
+    line.hash = hash(canonical(line));
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    fs.appendFileSync(target, `${JSON.stringify(line)}\n`, { mode: 0o600 }); return line;
+  } finally { release(); }
+}
+// Finished records and quiet threads older than RETAIN_MS are removed.
+export const RETAIN_MS = 30 * 24 * 3600 * 1000;
+export function prune(now = Date.now()) {
+  for (const record of records()) {
+    if (!isTerminal(record.task.status.state) || now - Date.parse(record.createdAt) <= RETAIN_MS) continue;
+    fs.rmSync(file(record.task.id), { force: true });
+    // The pictures a teammate sent with it (pictures.mjs) go with the record.
+    if (HEX64.test(record.peer ?? '')) fs.rmSync(peerFile('pictures', 'kept', record.peer, record.task.id), { recursive: true, force: true });
+  }
+  const folder = peerFile('threads'); noSymlinks(folder); if (!fs.existsSync(folder)) return;
+  for (const name of fs.readdirSync(folder).filter(name => THREAD.test(name.replace(/\.jsonl$/, '')))) {
+    const target = path.join(folder, name);
+    try { if (now - fs.lstatSync(target).mtimeMs > RETAIN_MS) fs.rmSync(target, { force: true }); } catch { /* Gone already. */ }
+  }
+}
+export function thread(threadId) {
+  if (!THREAD.test(threadId ?? '')) return [];
+  const target = peerFile('threads', `${threadId}.jsonl`); noSymlinks(target);
+  if (!fs.existsSync(target)) return [];
+  return fs.readFileSync(target, 'utf8').split('\n').filter(Boolean).flatMap(line => { try { return [JSON.parse(line)]; } catch { return []; } });
+}
+export function verifyThread(lines) {
+  let prev = null;
+  for (const { hash: digest, ...line } of lines) { if (line.prev !== prev || hash(canonical(line)) !== digest) return false; prev = digest; }
+  return true;
+}

package/lib/peer/transport.mjs

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { atomic, noSymlinks, readJson, refuse } from '../util.mjs';
+import { peerFile } from './paths.mjs';
+
+// The binding's transport (docs/peer-network.md, "Binding"): Hyperswarm with the
+// identity seed as the Noise key pair, NDJSON frames of at most 1 MiB, and the team's
+// relay keys as an array. hyperswarm and hyperdht are optional, so they load here only.
+export const FRAME_MAX = 1024 * 1024;
+const HEX64 = /^[0-9a-f]{64}$/;
+export const MISSING = 'Peer mode needs the optional networking packages. Reinstall with optional dependencies.';
+export async function loadNetwork() {
+  try {
+    const [swarm, dht] = await Promise.all([import('hyperswarm'), import('hyperdht')]);
+    return { Hyperswarm: swarm.default, DHT: dht.default };
+  } catch { refuse(MISSING); }
+}
+export function parseBootstrap(list) {
+  if (list == null) return undefined;
+  if (!Array.isArray(list) || list.length > 32) refuse('Bootstrap nodes must be a list of host:port.');
+  return list.map(item => {
+    const match = typeof item === 'string' && /^([A-Za-z0-9.-]{1,253}|\[[0-9a-fA-F:]+\]):(\d{1,5})$/.exec(item);
+    if (!match || Number(match[2]) < 1 || Number(match[2]) > 65535) refuse('Bootstrap nodes must be a list of host:port.');
+    return { host: match[1].replace(/^\[|\]$/g, ''), port: Number(match[2]) };
+  });
+}
+function savedNodes() {
+  try {
+    const file = peerFile('routing.json'); noSymlinks(file); if (!fs.existsSync(file)) return undefined;
+    const rows = readJson(file);
+    const nodes = Array.isArray(rows) ? rows.filter(row => typeof row?.host === 'string' && row.host.length < 256 && Number.isInteger(row.port) && row.port > 0 && row.port < 65536).slice(0, 256).map(({ host, port }) => ({ host, port })) : [];
+    return nodes.length ? nodes : undefined;
+  } catch { return undefined; }
+}
+
+// Splits a stream into JSON frames. A line over FRAME_MAX, or one that is not JSON,
+// is a violation: the caller closes the connection.
+export function frames(socket, onFrame, onViolation) {
+  let chunks = [], size = 0, stopped = false;
+  const stop = reason => { if (!stopped) { stopped = true; chunks = []; onViolation(reason); } };
+  socket.on('data', data => {
+    if (stopped) return;
+    let start = 0, index;
+    while ((index = data.indexOf(10, start)) !== -1) {
+      const part = data.subarray(start, index); start = index + 1;
+      if (size + part.length > FRAME_MAX) return stop('frame too large');
+      const line = chunks.length ? Buffer.concat([...chunks, part]).toString('utf8') : part.toString('utf8');
+      chunks = []; size = 0;
+      if (!line.trim()) continue;
+      let value; try { value = JSON.parse(line); } catch { return stop('invalid JSON'); }
+      onFrame(value); if (stopped) return;
+    }
+    const rest = data.subarray(start);
+    if (size + rest.length > FRAME_MAX) return stop('frame too large');
+    if (rest.length) { chunks.push(rest); size += rest.length; }
+  });
+}
+export function writeFrame(socket, value) {
+  const line = `${JSON.stringify(value)}\n`;
+  if (Buffer.byteLength(line) > FRAME_MAX) refuse('A peer message is larger than 1 MiB.');
+  if (!socket.destroyed) socket.write(line);
+}
+
+// testing: {dht: extra DHT options, connect: extra connect options for peer dials,
+// noServerPunch} lets the relay test force relaying; production passes none of these.
+export async function createNode({ identity, bootstrap, relays = [], nodes, testing = {} } = {}) {
+  const { Hyperswarm, DHT } = await loadNetwork();
+  const keyPair = DHT.keyPair(identity.seed), relayKeys = [...new Set(relays)].filter(key => HEX64.test(key)).slice(0, 16);
+  // The DHT carries the identity key pair too, so relay connections present it and a
+  // relay can admit team members only. The node stays ephemeral: it never joins other
+  // nodes' routing tables, so strangers' lookups, announcements and connections are not
+  // routed through it, however long it runs. It still announces its key and connects.
+  const dht = new DHT({ keyPair, bootstrap: parseBootstrap(bootstrap), nodes: nodes ?? savedNodes(), ephemeral: true, ...testing.dht });
+  const node = new EventEmitter(), sockets = new Set(), connect = dht.connect.bind(dht), peers = new Set();
+  const counters = { direct: 0, relayed: 0, failed: 0 };
+  // Every socket hyperdht opens goes through here, including its own relay sockets.
+  dht.connect = (key, opts = {}) => {
+    const hex = Buffer.from(key).toString('hex'), peer = peers.has(hex);
+    const socket = connect(key, peer ? { ...opts, ...testing.connect } : opts);
+    sockets.add(socket); let opened = false;
+    socket.on('open', () => { opened = true; });
+    socket.on('error', () => { if (!opened && peer) counters.failed++; });
+    socket.on('close', () => sockets.delete(socket));
+    return socket;
+  };
+  const swarm = new Hyperswarm({ dht, keyPair, firewall: () => false, ...(relayKeys.length ? { relayThrough: relayKeys.map(key => Buffer.from(key, 'hex')) } : {}) });
+  if (testing.noServerPunch) swarm.server.holepunch = () => false;
+  // A relayed stream is connected to the same UDP socket and address as hyperdht's own
+  // socket to the relay; a direct one is not. This is re-checked on every read, because a
+  // relayed connection can later upgrade to direct.
+  const pathOf = socket => {
+    const raw = socket.rawStream; if (!raw || socket.destroyed) return null;
+    for (const other of sockets) {
+      const o = other.rawStream;
+      if (other !== socket && o && o.socket === raw.socket && o.remoteHost === raw.remoteHost && o.remotePort === raw.remotePort && other.remotePublicKey && !other.remotePublicKey.equals(socket.remotePublicKey)) return 'relayed';
+    }
+    return 'direct';
+  };
+  const connections = new Map();
+  swarm.on('connection', socket => {
+    const key = socket.remotePublicKey.toString('hex'), row = { socket, since: Date.now(), lastSeen: Date.now() };
+    Object.defineProperty(row, 'path', { enumerable: true, get: () => pathOf(socket) });
+    connections.set(key, row); counters[row.path === 'relayed' ? 'relayed' : 'direct']++;
+    socket.on('data', () => { row.lastSeen = Date.now(); });
+    socket.on('error', () => {});
+    socket.on('close', () => { if (connections.get(key) === row) connections.delete(key); });
+    node.emit('connection', socket, key);
+  });
+  Object.assign(node, {
+    key: keyPair.publicKey.toString('hex'), swarm, dht, connections, counters,
+    listen: () => swarm.listen(),
+    dial(key) { if (!HEX64.test(key) || key === node.key) return; peers.add(key); swarm.joinPeer(Buffer.from(key, 'hex')); },
+    leave(key) { if (!peers.delete(key)) return; swarm.leavePeer(Buffer.from(key, 'hex')); },
+    // After sleep: announce again and dial every peer afresh.
+    async refresh() { swarm.server?.refresh?.(); for (const key of [...peers]) { swarm.leavePeer(Buffer.from(key, 'hex')); swarm.joinPeer(Buffer.from(key, 'hex')); } },
+    saveRouting() { const rows = dht.toArray({ limit: 256 }); if (rows.length) atomic(peerFile('routing.json'), rows); },
+    async destroy() { try { node.saveRouting(); } catch { /* The cache is optional. */ } await swarm.destroy(); },
+  });
+  return node;
+}

package/lib/pictures.mjs

@@ -0,0 +1,104 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { HOME_SECRETS } from './vendors.mjs';
+import { EluCodeError, refuse } from './util.mjs';
+
+// A picture the owner names in a message, when it lies in a part of the home folder no
+// session may read. Screenshot tools save there (CleanShot keeps its captures under
+// ~/Library), so a pasted path would be refused. The picture is copied to a folder of its
+// own in the temporary directory and the message names the copy. Nothing else is opened
+// up: the file must be one the owner wrote out in full, and must really be a picture or a
+// PDF, which its first bytes show, not its name.
+
+const NAMED = /\.(png|jpe?g|gif|webp|heic|heif|bmp|tiff?|pdf)$/i, SIZE_MAX = 25 * 1024 * 1024;
+// A path in single quotes, in double quotes, or bare with its spaces escaped, as a terminal
+// pastes a dropped file.
+export const PICTURE_PATHS = /'((?:~\/|\/)[^'\n]+)'|"((?:~\/|\/)[^"\n]+)"|((?:~\/|\/)(?:\\.|[^\s\\'"])+)/g;
+
+function pictureBytes(file) {
+  const head = Buffer.alloc(12); let fd = null;
+  try { fd = fs.openSync(file, 'r'); fs.readSync(fd, head, 0, 12, 0); } catch { return false; } finally { if (fd !== null) fs.closeSync(fd); }
+  const text = head.toString('latin1');
+  return text.startsWith('\x89PNG') || text.startsWith('\xff\xd8\xff') || text.startsWith('GIF8') || text.startsWith('%PDF') || text.startsWith('BM')
+    || text.startsWith('II*\x00') || text.startsWith('MM\x00*') || text.startsWith('RIFF') && text.slice(8, 12) === 'WEBP' || text.slice(4, 8) === 'ftyp';
+}
+// The real file behind a path from a message when it is a picture no session may read, else null.
+function hidden(written, home) {
+  const given = written.startsWith('~/') ? path.join(home, written.slice(2)) : written;
+  if (!NAMED.test(given)) return null;
+  let real; try { real = fs.realpathSync(given); if (!fs.statSync(real).isFile() || fs.statSync(real).size > SIZE_MAX) return null; } catch { return null; }
+  const closed = HOME_SECRETS.map(name => path.join(home, name)).some(folder => real === folder || real.startsWith(folder + path.sep));
+  return closed && NAMED.test(real) && pictureBytes(real) ? real : null;
+}
+// The message with each such picture replaced by a copy the session can read:
+// { text, copied: [{ from, to }] }. A message that names none comes back as it was.
+export function readablePictures(text, { home = os.homedir(), folder = os.tmpdir() } = {}) {
+  const copied = [];
+  if (typeof text !== 'string' || !/[~/]/.test(text)) return { text, copied };
+  let base; try { base = fs.realpathSync(home); } catch { return { text, copied }; }
+  const out = text.replace(PICTURE_PATHS, (whole, single, double, bare) => {
+    const real = hidden(single ?? double ?? bare.replace(/\\(.)/g, '$1'), base);
+    if (!real) return whole;
+    try {
+      const target = path.join(fs.realpathSync(folder), 'elu-code-pictures'); fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+      // The temp folder can be shared with other users. A folder of that name that is a link,
+      // or someone else's, is not used: its owner could read or swap what is put there.
+      const made = fs.lstatSync(target);
+      if (!made.isDirectory() || (process.getuid && made.uid !== process.getuid())) return whole;
+      if ((made.mode & 0o777) !== 0o700) fs.chmodSync(target, 0o700);
+      const to = path.join(target, `${crypto.randomUUID().slice(0, 8)}-${path.basename(real).replace(/[^A-Za-z0-9._@-]+/g, '-')}`);
+      fs.copyFileSync(real, to, fs.constants.COPYFILE_EXCL); fs.chmodSync(to, 0o600);
+      copied.push({ from: real, to });
+      return to;
+    } catch { return whole; }
+  });
+  return { text: out, copied };
+}
+
+// The kinds of picture a teammate can be sent, told by a file's first bytes:
+// [media type, file ending], or null for anything else.
+export function pictureKind(head) {
+  const text = Buffer.from(head.subarray(0, 12)).toString('latin1');
+  if (text.startsWith('\x89PNG\r\n\x1a\n')) return ['image/png', 'png'];
+  if (text.startsWith('\xff\xd8\xff')) return ['image/jpeg', 'jpg'];
+  if (text.startsWith('GIF87a') || text.startsWith('GIF89a')) return ['image/gif', 'gif'];
+  if (text.startsWith('RIFF') && text.slice(8, 12) === 'WEBP') return ['image/webp', 'webp'];
+  return null;
+}
+// ELU Code's own pictures folder in the temporary directory: a real folder of this user,
+// closed to everyone else. null when it cannot be had.
+export function picturesRoot(folder = os.tmpdir()) {
+  try {
+    const target = path.join(fs.realpathSync(folder), 'elu-code-pictures'); fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+    const made = fs.lstatSync(target);
+    if (!made.isDirectory() || (process.getuid && made.uid !== process.getuid())) return null;
+    if ((made.mode & 0o777) !== 0o700) fs.chmodSync(target, 0o700);
+    return target;
+  } catch { return null; }
+}
+// The one folder a teammate's question run may read beside the shared project: the copies
+// of the pictures sent with that question (lib/peer/pictures.mjs). It must be a real folder
+// directly inside the pictures folder above, with no link anywhere in its path, this
+// user's and closed to others, and hold nothing but pictures under generated names.
+const RUN_FOLDER = /^q-[0-9a-f]{16}$/, RUN_FILE = /^[1-9]\.(png|jpg|gif|webp)$/;
+export function checkRunPictures(folder, { temp = os.tmpdir() } = {}) {
+  const bad = () => refuse("A teammate's pictures must be in ELU Code's own pictures folder.");
+  const closed = (stat, mode) => (!process.getuid || stat.uid === process.getuid()) && (process.platform === 'win32' || (stat.mode & 0o777) === mode);
+  if (typeof folder !== 'string' || !path.isAbsolute(folder) || !RUN_FOLDER.test(path.basename(folder))) bad();
+  try {
+    const root = path.join(fs.realpathSync(temp), 'elu-code-pictures');
+    if (path.dirname(folder) !== root || fs.realpathSync(folder) !== folder) bad();
+    for (const dir of [root, folder]) { const stat = fs.lstatSync(dir); if (!stat.isDirectory() || !closed(stat, 0o700)) bad(); }
+    const names = fs.readdirSync(folder);
+    if (!names.length || names.length > 4) bad();
+    for (const name of names) {
+      const file = path.join(folder, name), stat = fs.lstatSync(file), head = Buffer.alloc(12);
+      if (!RUN_FILE.test(name) || !stat.isFile() || !closed(stat, 0o600)) bad();
+      const fd = fs.openSync(file, 'r'); try { fs.readSync(fd, head, 0, 12, 0); } finally { fs.closeSync(fd); }
+      if (!pictureKind(head)) bad();
+    }
+  } catch (error) { if (error instanceof EluCodeError) throw error; bad(); }
+  return folder;
+}