@joystack/cli 0.0.0-stage → 0.1.43

package/lib/history.mjs

@@ -0,0 +1,612 @@
+// A game's files as they were at an earlier commit, for the Assets page's
+// model history.
+//
+// Two questions are answered from the game's git repository:
+//
+//   which commits touched these files?   log(paths)
+//   what were the game's files at one?   extraction(commit) → a directory
+//
+// An extraction is the game's own folder at that commit, written by
+// `git archive` into a temporary directory and made read-only. Nothing is
+// checked out: the working copy, the index and HEAD are never touched, so
+// looking at an old version cannot disturb work in progress.
+//
+// ── TRUST ───────────────────────────────────────────────────────────────────
+//
+// The commit and the paths arrive from a URL, so neither reaches git as text
+// git could read as an option or a pattern:
+//   - a commit is hex only, 7 to 64 digits, and is resolved to a full object
+//     id with `rev-parse --verify <hex>^{commit}` behind `--end-of-options`;
+//     no branch names, no `HEAD~3`, nothing starting with `-`;
+//   - a path is a plain relative path inside the game's folder (no `..`, no
+//     segment starting with `.`, no backslash), passed after `--` with
+//     `--literal-pathspecs`, so `*` and `:(top)` mean nothing;
+//   - git runs through execFile/spawn with an argument list, never a shell,
+//     in the game's folder, with the variables that could point it at another
+//     repository (GIT_DIR and friends) removed.
+//
+// The archive is limited to the game's folder (`<commit>:<prefix>`), so a
+// game inside a larger repository never exposes the rest of it. The tar
+// stream is read here rather than by a `tar` program: only regular files and
+// folders are written, every name is checked to land inside the extraction,
+// and links of every kind are skipped, so nothing served from an extraction
+// can point outside it.
+
+import { execFile, spawn } from 'node:child_process';
+import {
+  chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, rmSync, writeSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, normalize, sep } from 'node:path';
+
+export const HISTORY_PATH = '/__joystack/history';
+
+// A commit as a URL may name it: lowercase hex, a short id or a full one
+// (SHA-1 is 40 digits, SHA-256 64).
+export const COMMIT_RE = /^[0-9a-f]{7,64}$/;
+// The most paths one history request may ask about, the longest path, and
+// the most commits listed (newest first). A model's modules often import a
+// game-wide file (a config, a palette) that changes far more often than the
+// model, so the list is long enough to reach back past a busy week of those.
+export const MAX_PATHS = 200;
+const MAX_PATH_LENGTH = 512;
+export const MAX_COMMITS = 200;
+// Extractions kept at once, and how long one unused is kept. A game's folder
+// at one commit is tens of megabytes for a game with sounds, so a handful is
+// plenty for comparing a few versions and stays well clear of filling a disk.
+export const MAX_EXTRACTIONS = 4;
+export const MAX_EXTRACTION_AGE_MS = 30 * 60 * 1000;
+// Bounds on one extraction: total bytes written, and files.
+const MAX_ARCHIVE_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 200_000;
+const GIT_TIMEOUT_MS = 20_000;
+const ARCHIVE_TIMEOUT_MS = 180_000;
+// The prefix of every extraction root this module creates in the temp folder.
+// The process id is part of the name so a root left behind by a server that
+// died can be told from one a running server is using (sweepAbandoned).
+const ROOT_PREFIX = 'joystack-history-';
+
+// Variables that would make git read a repository other than the one the
+// game's folder is in.
+const REPO_ENV = [
+  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR', 'GIT_NAMESPACE', 'GIT_CEILING_DIRECTORIES', 'GIT_DISCOVERY_ACROSS_FILESYSTEM',
+];
+
+function gitEnv() {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C', GIT_PAGER: 'cat' };
+  for (const k of REPO_ENV) delete env[k];
+  return env;
+}
+
+// Options placed before every git subcommand: no filesystem monitor (a
+// repository's config can name a program for it), paths printed as they
+// are, no signature check lines mixed into the log being parsed, and
+// pathspecs read literally.
+const GIT_PRE = [
+  '-c', 'core.fsmonitor=false', '-c', 'core.quotepath=false', '-c', 'log.showSignature=false', '--literal-pathspecs',
+];
+
+function git(cwd, args, { maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile('git', [...GIT_PRE, ...args], { cwd, env: gitEnv(), maxBuffer, timeout, windowsHide: true, encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        err.stderr = String(stderr ?? '').trim();
+        return reject(err);
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+// An error that carries the HTTP status the dev server answers with.
+export class HistoryError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+// The game's folder has no history to read: it is not in a git repository,
+// or git is not installed. A normal state, answered as data rather than as an
+// error.
+export class NoRepository extends HistoryError {
+  constructor(message) {
+    super(404, message);
+  }
+}
+
+// A path the page asked about, checked: relative to the game's folder,
+// forward slashes, no empty, `.` or `..` segment, nothing hidden (a segment
+// starting with `.`, which covers `.git`, `.env` and `.joystack`), no control
+// characters. Returns the path or throws a 400.
+export function checkPath(p) {
+  if (typeof p !== 'string' || !p || p.length > MAX_PATH_LENGTH) throw new HistoryError(400, 'a path must be a non-empty string');
+  if (/[\u0000-\u001f\u007f\\]/.test(p)) throw new HistoryError(400, `path ${JSON.stringify(p)} has a control character or a backslash`);
+  if (p.startsWith('/')) throw new HistoryError(400, `path ${JSON.stringify(p)} must be relative to the game's folder`);
+  for (const seg of p.split('/')) {
+    if (!seg || seg === '.' || seg === '..' || seg.startsWith('.')) {
+      throw new HistoryError(400, `path ${JSON.stringify(p)} must be a plain path inside the game's folder`);
+    }
+  }
+  return p;
+}
+
+// A commit as written in a URL, checked for shape (not yet for existence).
+export function checkCommit(text) {
+  const t = String(text ?? '').toLowerCase();
+  if (!COMMIT_RE.test(t)) throw new HistoryError(400, 'a commit is named by its hex id, 7 to 64 digits');
+  return t;
+}
+
+export function createHistory({
+  projectDir, tmpRoot = tmpdir(), maxExtractions = MAX_EXTRACTIONS, maxAgeMs = MAX_EXTRACTION_AGE_MS,
+  sweepEveryMs = 60 * 1000, log = () => {},
+}) {
+  let repoInfo = null;          // { top, prefix } once known
+  const resolved = new Map();   // commit text → full id
+  const extractions = new Map(); // full id → { dir, ready, lastUsed, busy }
+  let root = null;
+  let closed = false;
+  let queue = Promise.resolve();   // the extraction before the next one
+  let running = 0;
+  // Extractions past their age are removed on a timer too, not only when
+  // another commit is asked for. Unref'd: it never keeps the process alive.
+  const sweeper = setInterval(() => expire(), sweepEveryMs);
+  sweeper.unref?.();
+
+  // Where the game's folder sits in its repository. Asked again until it
+  // succeeds, so a folder made a repository mid-session is picked up.
+  async function repo() {
+    if (repoInfo) return repoInfo;
+    let out;
+    try {
+      out = await git(projectDir, ['rev-parse', '--show-toplevel', '--show-prefix']);
+    } catch (err) {
+      throw new NoRepository(err.code === 'ENOENT'
+        ? 'git is not installed, so this game has no history to show'
+        : 'this game\'s folder is not in a git repository, so it has no history to show. Commit it and every commit becomes a version.');
+    }
+    const [top, prefix = ''] = out.split('\n');
+    repoInfo = { top, prefix: prefix.replace(/\/+$/, '') };
+    return repoInfo;
+  }
+
+  // The commits that touched any of `paths`, newest first, each with which
+  // of them it touched, and which of them have changes not committed yet.
+  //
+  // A folder with no repository answers { git: false, reason } instead.
+  async function history(paths) {
+    if (!Array.isArray(paths) || !paths.length) throw new HistoryError(400, 'ask about at least one path');
+    if (paths.length > MAX_PATHS) throw new HistoryError(400, `ask about at most ${MAX_PATHS} paths`);
+    const list = [...new Set(paths.map(checkPath))];
+    let prefix;
+    try {
+      ({ prefix } = await repo());
+    } catch (err) {
+      if (err instanceof NoRepository) return { git: false, reason: err.message };
+      throw err;
+    }
+    let head = null;
+    try {
+      head = (await git(projectDir, ['rev-parse', '--verify', '--quiet', '--end-of-options', 'HEAD^{commit}'])).trim() || null;
+    } catch { /* a repository with no commits yet */ }
+    const commits = [];
+    if (head) {
+      const out = await git(projectDir, [
+        // Merges are left out: the commits a merge brought in are listed
+        // themselves, each with the files it changed, while the merge itself
+        // names no file and would read as a version that changed nothing.
+        'log', `-n${MAX_COMMITS + 1}`, '--no-merges', '--no-color', '--no-ext-diff', '--no-textconv',
+        '--format=%x1e%H%x1f%h%x1f%cI%x1f%an%x1f%s', '--name-only', '--relative',
+        '--end-of-options', 'HEAD', '--', ...list,
+      ]);
+      for (const rec of out.split('\x1e').slice(1)) {
+        const [first, ...rest] = rec.split('\n');
+        const [sha, short, date, author, subject] = first.split('\x1f');
+        commits.push({ sha, short, date, author, subject, files: rest.filter(Boolean) });
+      }
+    }
+    const truncated = commits.length > MAX_COMMITS;
+    if (truncated) commits.length = MAX_COMMITS;
+    // Status paths are relative to the top of the repository; the page's are
+    // relative to the game's folder.
+    const status = await git(projectDir, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', ...list]);
+    const at = prefix ? `${prefix}/` : '';
+    const changed = status.split('\0').filter(Boolean).map((e) => e.slice(3))
+      .map((p) => (at && p.startsWith(at) ? p.slice(at.length) : p));
+    return { git: true, head, commits, truncated, working: { changed } };
+  }
+
+  // A commit named by hex, as the full id of a commit in this repository.
+  async function resolve(text) {
+    const t = checkCommit(text);
+    let full = resolved.get(t) ?? '';
+    if (!full) {
+      await repo();
+      try {
+        full = (await git(projectDir, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${t}^{commit}`])).trim();
+      } catch { /* not found, or ambiguous */ }
+      if (!/^[0-9a-f]{40,64}$/.test(full)) throw new HistoryError(404, `there is no commit ${t} in this game's repository`);
+      if (resolved.size > 256) resolved.clear();
+      resolved.set(t, full);
+    }
+    // Only the history that led to what is checked out is a version. A commit
+    // on a branch never merged, or one fetched from someone else and never
+    // reviewed, is in the object store too, and its code would run in the
+    // Assets page if it could be loaded. Asked on every call, never cached:
+    // HEAD moves (a checkout, a reset) while the dev server runs, and a
+    // commit that was a version a moment ago may no longer be one.
+    try {
+      await git(projectDir, ['merge-base', '--is-ancestor', '--end-of-options', full, 'HEAD']);
+    } catch {
+      throw new HistoryError(404, `commit ${t} is not in the history of what is checked out, so it is not a version of this game`);
+    }
+    return full;
+  }
+
+  function ensureRoot() {
+    if (root) return root;
+    sweepAbandoned(tmpRoot, log);
+    root = mkdtempSync(join(tmpRoot, `${ROOT_PREFIX}${process.pid}-`));
+    return root;
+  }
+
+  // Forget extractions unused for longer than maxAgeMs, then the least
+  // recently used until there is room for one more.
+  function expire() {
+    const now = Date.now();
+    for (const [id, e] of [...extractions.entries()]) {
+      if (e.busy || now - e.lastUsed <= maxAgeMs) continue;
+      extractions.delete(id);
+      removeTree(e.dir);
+    }
+  }
+
+  function evict() {
+    const now = Date.now();
+    const idle = [...extractions.entries()].filter(([, e]) => !e.busy).sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+    for (const [id, e] of idle) {
+      if (now - e.lastUsed > maxAgeMs || extractions.size >= maxExtractions) {
+        extractions.delete(id);
+        removeTree(e.dir);
+      }
+    }
+  }
+
+  // The directory holding the game's folder at `full` (a resolved commit),
+  // extracted the first time it is asked for. Concurrent requests for the
+  // same commit share one extraction.
+  async function extraction(full) {
+    if (closed) throw new HistoryError(503, 'the dev server is stopping');
+    const have = extractions.get(full);
+    if (have) {
+      have.lastUsed = Date.now();
+      return have.ready;
+    }
+    evict();
+    const dir = join(ensureRoot(), full);
+    const e = { dir, lastUsed: Date.now(), busy: true, ready: null };
+    // One extraction at a time: each is a git process writing up to the whole
+    // game's folder, and several commits asked for at once would run them all
+    // side by side. Later ones wait their turn.
+    const turn = queue;
+    e.ready = turn.then(async () => {
+      if (closed) throw new HistoryError(503, 'the dev server is stopping');
+      running += 1;
+      try {
+        return await extract();
+      } finally {
+        running -= 1;
+      }
+    });
+    queue = e.ready.catch(() => {});
+    const extract = async () => {
+      const { top, prefix } = await repo();
+      const tree = prefix ? `${full}:${prefix}` : `${full}^{tree}`;
+      let kind = '';
+      try {
+        kind = (await git(top, ['cat-file', '-t', '--end-of-options', tree])).trim();
+      } catch { /* the folder did not exist then */ }
+      if (kind !== 'tree') throw new HistoryError(404, `the game's folder did not exist at commit ${full.slice(0, 12)}`);
+      mkdirSync(dir, { recursive: true });
+      await archiveInto(top, tree, dir);
+      // Closing removes the extractions root, but files still arriving from
+      // the archive recreate it; an extraction that outlived close() is
+      // removed here, root included.
+      if (closed) throw new HistoryError(503, 'the dev server is stopping');
+      makeReadOnly(dir);
+      return dir;
+    };
+    extractions.set(full, e);
+    try {
+      return await e.ready;
+    } catch (err) {
+      if (extractions.get(full) === e) extractions.delete(full);
+      removeTree(dir);
+      if (closed) removeTree(dirname(dir));
+      throw err;
+    } finally {
+      e.busy = false;
+    }
+  }
+
+  function close() {
+    closed = true;
+    clearInterval(sweeper);
+    extractions.clear();
+    if (root) removeTree(root);
+    root = null;
+  }
+
+  return {
+    repo, history, resolve, extraction, close,
+    // For tests: the extractions held now, by full id.
+    held: () => [...extractions.keys()],
+    // For tests: how many extractions are running right now.
+    running: () => running,
+    get root() { return root; },
+  };
+}
+
+// `git archive --format=tar <tree>` from the repository top, read as it
+// streams and written into `dir`.
+function archiveInto(top, tree, dir) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', [...GIT_PRE, 'archive', '--format=tar', '--end-of-options', tree], {
+      cwd: top, env: gitEnv(), windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const untar = createUntar(dir);
+    let stderr = '';
+    let failed = null;
+    const fail = (err) => {
+      if (failed) return;
+      failed = err;
+      child.kill();
+    };
+    const timer = setTimeout(() => fail(new HistoryError(504, 'extracting that commit took too long')), ARCHIVE_TIMEOUT_MS);
+    timer.unref?.();
+    child.stdout.on('data', (chunk) => {
+      if (failed) return;
+      try { untar.push(chunk); } catch (err) { fail(err); }
+    });
+    child.stderr.on('data', (c) => { if (stderr.length < 4000) stderr += c; });
+    child.on('error', (err) => fail(err.code === 'ENOENT' ? new HistoryError(503, 'git is not installed') : err));
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      try { untar.end(); } catch (err) { failed ??= err; }
+      if (failed) return reject(failed);
+      if (code !== 0) return reject(new HistoryError(500, `git archive failed: ${stderr.trim() || `exit ${code}`}`));
+      resolve();
+    });
+  });
+}
+
+// A streaming reader for the tar format git archive writes (POSIX ustar with
+// pax extended headers for long names). Regular files and folders are
+// written; everything else (links, devices, the global header carrying the
+// commit id) is skipped. A name that would land outside `dir` is an error.
+export function createUntar(dir) {
+  const rootDir = normalize(dir);
+  let buf = Buffer.alloc(0);
+  let state = 'header';
+  let remaining = 0;
+  let pad = 0;
+  let fd = null;
+  let paxData = null;       // collected body of an 'x' or 'L' header
+  let paxKind = null;
+  let nextName = null;      // a long name from a pax or GNU header, for the next entry
+  let written = 0;
+  let entries = 0;
+
+  const hidden = (name) => name.replace(/^\.\/+/, '').split('/').some((seg) => seg.startsWith('.'));
+  const target = (name) => {
+    const clean = name.replace(/^\.\/+/, '').replace(/\/+$/, '');
+    if (!clean) return null;
+    if (clean.includes('\0') || clean.includes('\\') || clean.startsWith('/')) throw new HistoryError(500, `the archive holds an unsafe name ${JSON.stringify(clean)}`);
+    if (clean.split('/').some((s) => s === '..' || s === '')) throw new HistoryError(500, `the archive holds an unsafe name ${JSON.stringify(clean)}`);
+    const out = normalize(join(rootDir, clean));
+    if (!out.startsWith(rootDir + sep)) throw new HistoryError(500, `the archive holds a name outside its folder ${JSON.stringify(clean)}`);
+    return out;
+  };
+
+  const octal = (b, start, len) => {
+    if (b[start] & 0x80) throw new HistoryError(500, 'the archive holds a file too large to extract');
+    const s = b.toString('latin1', start, start + len).replace(/\0.*$/s, '').trim();
+    if (s && !/^[0-7]+$/.test(s)) throw new HistoryError(500, 'the archive holds a header with an unreadable size');
+    return s ? parseInt(s, 8) : 0;
+  };
+  // The header checksum: the sum of its bytes with the checksum field read as
+  // spaces. A block that fails it is not a tar header, and reading on would
+  // treat file contents as headers.
+  const checksumOk = (h) => {
+    let sum = 0;
+    for (let i = 0; i < 512; i += 1) sum += i >= 148 && i < 156 ? 0x20 : h[i];
+    const stated = h.toString('latin1', 148, 156).replace(/[\0 ]+$/g, '').trim();
+    return /^[0-7]+$/.test(stated) && parseInt(stated, 8) === sum;
+  };
+  const str = (b, start, len) => {
+    const end = b.indexOf(0, start);
+    return b.toString('utf8', start, end >= 0 && end < start + len ? end : start + len);
+  };
+
+  function header(h) {
+    if (h.every((x) => x === 0)) return;           // an end-of-archive block
+    if (!checksumOk(h)) throw new HistoryError(500, 'the archive holds a header whose checksum does not match');
+    entries += 1;
+    if (entries > MAX_ARCHIVE_ENTRIES) throw new HistoryError(500, 'the archive holds too many files');
+    const size = octal(h, 124, 12);
+    const type = String.fromCharCode(h[156] || 0x30);
+    let name = str(h, 0, 100);
+    const prefix = h.toString('latin1', 257, 262) === 'ustar' ? str(h, 345, 155) : '';
+    if (prefix) name = `${prefix}/${name}`;
+    if (nextName != null) {
+      name = nextName;
+      nextName = null;
+    }
+    remaining = size;
+    pad = (512 - (size % 512)) % 512;
+    if (type === 'x' || type === 'L') {
+      paxKind = type;
+      paxData = [];
+      state = 'meta';
+    } else if ((type === '0' || type === '7') && !hidden(name)) {
+      const out = target(name);
+      if (!out) throw new HistoryError(500, 'the archive holds a file with no name');
+      mkdirSync(dirname(out), { recursive: true });
+      fd = openSync(out, 'wx', 0o644);
+      state = 'file';
+    } else {
+      // Links of every kind, and anything hidden (`.env`, `.joystack`, …), which
+      // the dev server never serves from history, are skipped unwritten.
+      if (type === '5' && !hidden(name)) {
+        const out = target(name);
+        if (out) mkdirSync(out, { recursive: true });
+      }
+      state = 'skip';
+    }
+    if (remaining === 0) finishBody();
+  }
+
+  function finishBody() {
+    if (state === 'file') {
+      closeSync(fd);
+      fd = null;
+    } else if (state === 'meta') {
+      const body = Buffer.concat(paxData);
+      if (paxKind === 'L') nextName = body.toString('utf8').replace(/\0.*$/s, '');
+      else {
+        // Records are "<length> <key>=<value>\n", where the length counts
+        // bytes, so the walk is over the buffer: a name with multibyte
+        // characters is shorter in characters than its stated length.
+        let i = 0;
+        while (i < body.length) {
+          const space = body.indexOf(0x20, i);
+          if (space < 0) break;
+          const len = parseInt(body.toString('latin1', i, space), 10);
+          if (!(len > 0) || i + len > body.length) break;
+          const rec = body.toString('utf8', space + 1, i + len - 1);
+          const eq = rec.indexOf('=');
+          const key = rec.slice(0, eq);
+          if (key === 'path') nextName = rec.slice(eq + 1);
+          // A size in a pax record replaces the header's, for a file over
+          // 8 GiB; no game file is that large, and reading on with the
+          // header's size would treat the file's contents as headers.
+          if (key === 'size') throw new HistoryError(500, 'the archive holds a file too large to extract');
+          i += len;
+        }
+      }
+      paxData = null;
+    }
+    state = pad ? 'pad' : 'header';
+  }
+
+  return {
+    push(chunk) {
+      buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+      let at = 0;
+      for (;;) {
+        if (state === 'header') {
+          if (buf.length - at < 512) break;
+          const h = buf.subarray(at, at + 512);
+          at += 512;
+          header(h);
+        } else if (state === 'pad') {
+          const n = Math.min(pad, buf.length - at);
+          at += n;
+          pad -= n;
+          if (pad === 0) state = 'header';
+          else break;
+        } else {
+          const n = Math.min(remaining, buf.length - at);
+          if (n === 0 && remaining > 0) break;
+          const piece = buf.subarray(at, at + n);
+          if (state === 'file') {
+            written += n;
+            if (written > MAX_ARCHIVE_BYTES) throw new HistoryError(500, 'the game\'s folder at that commit is too large to extract');
+            writeSync(fd, piece);
+          } else if (state === 'meta') {
+            if (paxData.reduce((s, b) => s + b.length, 0) + n > 1024 * 1024) throw new HistoryError(500, 'the archive holds an oversized header');
+            paxData.push(Buffer.from(piece));
+          }
+          at += n;
+          remaining -= n;
+          if (remaining === 0) finishBody();
+          else break;
+        }
+      }
+      buf = at >= buf.length ? Buffer.alloc(0) : Buffer.from(buf.subarray(at));
+    },
+    end() {
+      if (fd != null) {
+        closeSync(fd);
+        fd = null;
+      }
+      if (state === 'file' || state === 'meta' || (state === 'header' && buf.length > 0)) {
+        throw new HistoryError(500, 'the archive ended in the middle of a file');
+      }
+    },
+  };
+}
+
+// Files read-only, then folders, deepest first.
+function makeReadOnly(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = lstatSync(p);
+    if (st.isDirectory()) makeReadOnly(p);
+    else if (st.isFile()) chmodSync(p, 0o444);
+  }
+  chmodSync(dir, 0o555);
+}
+
+// Folders made writable again so their contents can be removed, then removed.
+function removeTree(dir) {
+  const writable = (d) => {
+    try {
+      const st = lstatSync(d);
+      if (!st.isDirectory()) return;
+      chmodSync(d, 0o755);
+      for (const name of readdirSync(d)) writable(join(d, name));
+    } catch { /* gone already */ }
+  };
+  writable(dir);
+  try { rmSync(dir, { recursive: true, force: true }); } catch { /* left for the next sweep */ }
+}
+
+// Remove extraction roots left in the temp folder by dev servers that are no
+// longer running (a crash, a killed terminal). Only folders this module names,
+// owned by this user, whose process id names no running process.
+export function sweepAbandoned(tmpRoot, log = () => {}) {
+  let names;
+  try {
+    names = readdirSync(tmpRoot);
+  } catch {
+    return;
+  }
+  const uid = process.getuid?.();
+  for (const name of names) {
+    const m = new RegExp(`^${ROOT_PREFIX}(\\d+)-`).exec(name);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (pid === process.pid || alive(pid)) continue;
+    const p = join(tmpRoot, name);
+    try {
+      const st = lstatSync(p);
+      if (!st.isDirectory() || (uid != null && st.uid !== uid)) continue;
+    } catch {
+      continue;
+    }
+    removeTree(p);
+    if (!existsSync(p)) log(`history: removed ${p}, left by a dev server that is no longer running`);
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}

package/lib/inbox-cmd.mjs

@@ -0,0 +1,57 @@
+// `joystack inbox reply <id> "<text>"`: the agent's answer to a report a dev
+// tool sent it, shown back in that tool. Each running dev server writes its
+// port and a bearer token to .joystack/agent-inbox/.connection-<port>
+// (owner-only), so only a process that can read the game folder can reply.
+// With several servers for one game, the reply goes to whichever took the
+// report; the others answer 404 and are skipped.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateDir } from './legacy-names.mjs';
+
+export const INBOX_HELP = `joystack inbox reply [--dir <game>] <id> "<text>"
+  Answer a report a dev tool sent you. The id and the exact command are in
+  the message the report arrived with; the text appears in the tool.`;
+
+export function connectionFile(projectDir, port) {
+  return join(stateDir(projectDir), 'agent-inbox', `.connection-${port}`);
+}
+
+function connections(dir) {
+  let names;
+  try { names = readdirSync(join(stateDir(dir), 'agent-inbox')); } catch { return []; }
+  return names.filter((name) => /^\.connection-\d+$/.test(name)).flatMap((name) => {
+    try {
+      const { port, token } = JSON.parse(readFileSync(join(stateDir(dir), 'agent-inbox', name), 'utf8'));
+      return Number.isInteger(port) && port > 0 && port < 65536 && typeof token === 'string' ? [{ port, token }] : [];
+    } catch { return []; }
+  });
+}
+
+export async function inboxReply({ dir = process.cwd(), id, text }) {
+  if (!id || !text?.trim()) throw new Error(`Usage: ${INBOX_HELP}`);
+  let reached = false;
+  for (const { port, token } of connections(dir)) {
+    let res;
+    try {
+      // Always loopback: the credential names a port, never an address.
+      res = await fetch(`http://127.0.0.1:${port}/__joystack/agent-inbox/reply`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id, text }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch { continue; } // that server has stopped
+    reached = true;
+    if (res.ok) {
+      console.log('Reply shown in the tool.');
+      return;
+    }
+    if (res.status === 404) continue; // another server's report
+    // Whatever answers on that port wrote the body; it is reported by status
+    // only, never echoed.
+    throw new Error(`The dev server on port ${port} refused the reply (HTTP ${res.status}).`);
+  }
+  throw new Error(reached
+    ? `No running 'joystack dev' for ${dir} knows report ${id}; it was taken by a server that has since restarted.`
+    : `No running 'joystack dev' has received a report for ${dir}.`);
+}