@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

package/pipeline/scripts/learn-from-transcripts.mjs

@@ -53,20 +53,14 @@
  * Exit: 0 ok (including "nothing found") | 1 usage
  */
 
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { runMain } from "../lib/fatal.mjs";
+import { memoryExcluded } from "./_memory-policy.mjs";
+import { dropSecrets } from "./_secret-scan.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
@@ -382,41 +376,6 @@ function mine(events) {
   return found;
 }
 
-/* ----------------------------------------------------------------- privacy */
-
-/**
- * The single-source secret check. Candidates go to a temp file and through
- * pre-commit-check.sh, which owns the patterns; a hit is dropped, never written.
- */
-function dropSecrets(items) {
-  const scanner = existsSync(join(HERE, "pre-commit-check.sh"))
-    ? join(HERE, "pre-commit-check.sh")
-    : join(homedir(), ".claude", "scripts", "pre-commit-check.sh");
-  if (!existsSync(scanner)) {
-    return { kept: items, dropped: 0, scanned: false };
-  }
-  const dir = mkdtempSync(join(tmpdir(), "lft-"));
-  const kept = [];
-  let dropped = 0;
-  try {
-    for (const it of items) {
-      const f = join(dir, "candidate.txt");
-      writeFileSync(f, `${it.statement}\n${it.diagnosis || ""}\n${it.scope}\n`);
-      let clean = true;
-      try {
-        execFileSync("bash", [scanner, "--scan-file", f], { stdio: "ignore" });
-      } catch {
-        clean = false;
-      }
-      if (clean) kept.push(it);
-      else dropped++;
-    }
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-  return { kept, dropped, scanned: true };
-}
-
 /* -------------------------------------------------------------------- main */
 
 function main() {
@@ -462,12 +421,16 @@ function main() {
     uniq.push(it);
   }
 
-  const { kept, dropped, scanned } = dropSecrets(uniq);
+  const { kept, dropped, scanned } = dropSecrets(
+    uniq,
+    (it) => `${it.statement}\n${it.diagnosis || ""}\n${it.scope}`,
+  );
   const slug = repoSlug();
+  const excluded = memoryExcluded(slug);
 
   let written = 0;
   let deduped = 0;
-  if (APPLY && kept.length) {
+  if (APPLY && kept.length && !excluded) {
     const ledger = existsSync(join(HERE, "learnings-ledger.mjs"))
       ? join(HERE, "learnings-ledger.mjs")
       : join(homedir(), ".claude", "scripts", "learnings-ledger.mjs");
@@ -572,7 +535,7 @@ function main() {
   }
 
   let localFile = null;
-  if (APPLY && kept.length) localFile = writeLocalBlock(kept);
+  if (APPLY && kept.length && !excluded) localFile = writeLocalBlock(kept);
 
   // Record how many lessons the machine found, kept apart from the ones a model
   // proposed. Pooling them lets a "lessons learned" number climb while the half
@@ -595,6 +558,7 @@ function main() {
   const result = {
     status: "ok",
     repo: slug,
+    excluded,
     transcripts: files.length,
     toolResultsExamined: examined,
     candidates: uniq.length,

package/pipeline/scripts/learnings-ledger.mjs

@@ -14,7 +14,10 @@
  * run re-discovers the same structure and reviewers re-flag preferences the team
  * already rejected.
  *
- * Each line conforms to pipeline/schemas/learnings-ledger.schema.json.
+ * Each line conforms to pipeline/schemas/learnings-ledger.schema.json. Every
+ * entry passes the secret scan in _secret-scan.mjs before it is written, and
+ * `<private>` spans are removed first; a refused entry is counted in
+ * `droppedBySecretScan`.
  *
  * Subcommands:
  *   add        --kind <fact|convention|rejected-preference> --statement "..."
@@ -43,6 +46,12 @@
  *                 severity rejections are NOT distilled - a wrong rejection of a
  *                 blocking issue must never permanently suppress that class. Exit 2
  *                 when nothing new was distilled (a repeat of the same triage).
+ *   feedback   --id <id> --outcome <useful|dead_end|corrected> [--task <id>] [--repo-slug <slug>]
+ *                 Record how an injected entry fared. An entry marked corrected,
+ *                 or judged a dead end at least twice and more often than useful,
+ *                 leaves brief and profile; one useful at least twice ranks by
+ *                 its strength too (_memory-policy.mjs). Kept beside the ledger
+ *                 in learnings-feedback.jsonl.
  *   forget     [--statement "..."] [--kind <kind>] [--repo-slug <slug>]
  *                 Remove ledger entries matching the statement substring and/or
  *                 kind (rewrites the file). Use to clear a bad/stale learning.
@@ -70,7 +79,15 @@ import {
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { join, basename, dirname } from "node:path";
-import { bm25, recencyRank, rrf, tokens, shortId, recallConfig } from "./_retrieval.mjs";
+import { bm25, recencyRank, rrf, tokens, recallConfig } from "./_retrieval.mjs";
+import {
+  checkedSlug,
+  ledgerRowId,
+  memoryExcluded,
+  nearDuplicate,
+  standing,
+} from "./_memory-policy.mjs";
+import { openScanner, stripPrivate } from "./_secret-scan.mjs";
 
 const argv = process.argv.slice(2);
 const SUB = argv[0];
@@ -110,6 +127,10 @@ function die(msg, code = 1) {
 // the learning replay always miss. `--git-common-dir` points at the main
 // repository's .git for every linked worktree.
 function repoSlug() {
+  return checkedSlug(rawRepoSlug());
+}
+
+function rawRepoSlug() {
   if (flags["repo-slug"]) return String(flags["repo-slug"]);
   if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
   try {
@@ -150,6 +171,36 @@ function ledgerPath(slug) {
   );
 }
 
+function feedbackPath(slug) {
+  return join(dirname(ledgerPath(slug)), "learnings-feedback.jsonl");
+}
+
+/** id -> outcome rows recorded against it. */
+function readFeedback(slug) {
+  const p = feedbackPath(slug);
+  const byId = new Map();
+  if (!existsSync(p)) return byId;
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const f = JSON.parse(line);
+      if (!byId.has(f.id)) byId.set(f.id, []);
+      byId.get(f.id).push(f);
+    } catch {
+      /* skip corrupted line */
+    }
+  }
+  return byId;
+}
+
+/** Rows with their standing; suppressed ones dropped. */
+function standingRows(slug, rows) {
+  const fb = readFeedback(slug);
+  return rows
+    .map((r) => ({ r, s: standing(fb.get(rowId(r)) ?? []) }))
+    .filter((x) => !x.s.suppressed);
+}
+
 function ensureDir(p) {
   mkdirSync(dirname(p), { recursive: true });
 }
@@ -171,9 +222,7 @@ function normStatement(s) {
 // Stable pointer for a ledger row, from the same fields the dedup key uses.
 // Not stored on the row: an existing ledger gets ids without a migration, and a
 // re-added entry keeps the id it already had.
-function rowId(row) {
-  return shortId("L", row.kind, normStatement(row.statement));
-}
+const rowId = ledgerRowId;
 
 function readLedger(slug) {
   const p = ledgerPath(slug);
@@ -197,8 +246,22 @@ function writeRow(slug, row) {
   appendFileSync(p, JSON.stringify(row) + "\n", "utf8");
 }
 
+// One scanner per process; every write goes through it (_secret-scan.mjs).
+let scanner = null;
+const secretScan = { dropped: 0 };
+function passesSecretScan(text) {
+  if (!scanner) {
+    scanner = openScanner();
+    process.on("exit", () => scanner.close());
+  }
+  if (scanner.isClean(text)) return true;
+  secretScan.dropped++;
+  return false;
+}
+
 /** Append one entry unless an entry with the same kind + normalized statement
- *  already exists (idempotent). Returns true when written. */
+ *  already exists (idempotent), or the text fails the secret scan. Returns
+ *  true when written. */
 function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, source }, existing) {
   // One line, enforced here rather than hoped for. The schema says "the
   // knowledge itself, in one line", and both blocks render one entry per line -
@@ -206,16 +269,23 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   // `from-triage` builds statements out of model-written finding text, a
   // newline plus a plausible-looking `</repo-profile>` would break out of the
   // injected block itself. Collapsing whitespace closes both at the store.
-  const stmt = oneLine(statement);
+  const stmt = oneLine(stripPrivate(statement));
   if (!stmt) return false;
   const seenKey = `${kind}::${normStatement(stmt)}`;
   if (existing.has(seenKey)) return false;
+  const sameKind = [...existing]
+    .filter((k) => k.startsWith(`${kind}::`))
+    .map((k) => k.slice(kind.length + 2));
+  if (nearDuplicate(stmt.toLowerCase(), sameKind)) return false;
+  const diag = oneLine(stripPrivate(diagnosis));
+  const scopeText = scope || "global";
+  if (!passesSecretScan(`${stmt}\n${diag}\n${scopeText}`)) return false;
   const row = {
     v: "1.0.0",
     ts: new Date().toISOString(),
     repo_slug: slug,
     kind,
-    scope: scope || "global",
+    scope: scopeText,
     statement: stmt,
     source_task: task || null,
     confidence: CONFIDENCES.has(confidence) ? confidence : "medium",
@@ -223,7 +293,6 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   // Optional causal diagnosis (Reflexion P5): the "why it failed" behind a
   // lesson. Verbal diagnosis is what turns a detected error into a prevented
   // one; a bare outcome does not. Stored only when supplied.
-  const diag = oneLine(diagnosis);
   if (diag) row.diagnosis = diag;
   // Who found it. Optional so old rows stay valid, but written whenever the
   // caller knows: a machine-mined path correction and a model's architectural
@@ -235,11 +304,19 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   return true;
 }
 
+function refuseExcluded(slug) {
+  if (!memoryExcluded(slug)) return false;
+  process.stdout.write(JSON.stringify({ ok: true, slug, added: 0, excluded: true }) + "\n");
+  process.exitCode = 2;
+  return true;
+}
+
 function cmdAdd() {
   const kind = flags.kind;
   if (!KINDS.has(kind)) die(`--kind must be one of: ${[...KINDS].join(", ")}`, 1);
   if (!flags.statement || flags.statement === true) die('add needs --statement "..."', 1);
   const slug = repoSlug();
+  if (refuseExcluded(slug)) return;
   const existing = new Set(readLedger(slug).map((r) => `${r.kind}::${normStatement(r.statement)}`));
   const wrote = addEntry(
     slug,
@@ -256,7 +333,13 @@ function cmdAdd() {
     existing,
   );
   process.stdout.write(
-    JSON.stringify({ ok: true, slug, added: wrote ? 1 : 0, deduped: wrote ? 0 : 1 }) + "\n",
+    JSON.stringify({
+      ok: true,
+      slug,
+      added: wrote ? 1 : 0,
+      deduped: wrote || secretScan.dropped ? 0 : 1,
+      droppedBySecretScan: secretScan.dropped,
+    }) + "\n",
   );
   process.exit(wrote ? 0 : 2);
 }
@@ -267,6 +350,7 @@ function cmdFromTriage() {
   if (!existsSync(triagePath)) die(`triage file not found: ${triagePath}`, 1);
   const task = flags.task && flags.task !== true ? String(flags.task) : null;
   const slug = repoSlug();
+  if (refuseExcluded(slug)) return;
   let triage;
   try {
     triage = JSON.parse(readFileSync(triagePath, "utf8"));
@@ -311,7 +395,15 @@ function cmdFromTriage() {
       written++;
     }
   }
-  process.stdout.write(JSON.stringify({ ok: true, slug, added: written, skippedBlocking }) + "\n");
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      slug,
+      added: written,
+      skippedBlocking,
+      droppedBySecretScan: secretScan.dropped,
+    }) + "\n",
+  );
   process.exitCode = written ? 0 : 2;
   return;
 }
@@ -430,12 +522,14 @@ function compareCodepoints(a, b) {
 }
 
 function cmdBrief() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const cfg = recallConfig();
   const max = flags.max ? Math.max(1, Number(flags.max)) : 20;
   const task = flags.task && flags.task !== true ? String(flags.task) : null;
   const scope = flags.scope && flags.scope !== true ? String(flags.scope) : null;
-  const rows = readLedger(slug);
+  const scored = standingRows(slug, readLedger(slug));
+  const rows = scored.map((x) => x.r);
+  const strengthOf = new Map(scored.map((x) => [x.r, x.s.corroborated ? x.s.strength : 0]));
   if (rows.length === 0) {
     process.exit(2); // nothing to inject; caller skips silently
   }
@@ -471,8 +565,13 @@ function cmdBrief() {
     );
     const fresh = recencyRank(pool, { halfLifeDays: cfg.halfLifeDays });
     const matched = new Set(relevance.filter((x) => x.score > 0).map((x) => x.index));
-    const fused = rrf([relevance, fresh], { k: [10, 60], weights: [3, 1] }).filter((x) =>
-      matched.has(x.index),
+    // Entries recorded useful at least twice rank by their strength as well;
+    // with no feedback this list is empty and the fusion is unchanged.
+    const earned = pool
+      .map((r, index) => ({ index, score: strengthOf.get(r) || 0 }))
+      .sort((a, b) => b.score - a.score);
+    const fused = rrf([relevance, fresh, earned], { k: [10, 60, 60], weights: [3, 1, 1] }).filter(
+      (x) => matched.has(x.index),
     );
     ordered = fused.slice(0, max).map((x) => pool[x.index]);
     // A task whose words match nothing in the ledger must not silently inject an
@@ -527,10 +626,10 @@ function scopeMatches(entryScope, target) {
 // everything after it. Detail is deliberately absent; each line carries the
 // pointer that buys it back.
 function cmdProfile() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const cfg = recallConfig();
   const max = flags.max ? Math.max(1, Number(flags.max)) : 60;
-  const rows = readLedger(slug);
+  const rows = standingRows(slug, readLedger(slug)).map((x) => x.r);
   if (rows.length === 0) process.exit(2);
 
   const ordered = rows
@@ -565,7 +664,7 @@ function cmdProfile() {
 function cmdShow() {
   const id = flags.id && flags.id !== true ? String(flags.id) : null;
   if (!id) die("show needs --id <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const want = id.startsWith("L:") ? id : `L:${id}`;
   const row = readLedger(slug).find((r) => rowId(r) === want);
   if (!row) {
@@ -592,7 +691,7 @@ function cmdShow() {
 function cmdTimeline() {
   const id = flags.anchor && flags.anchor !== true ? String(flags.anchor) : null;
   if (!id) die("timeline needs --anchor <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const before = flags.before && flags.before !== true ? Math.max(0, Number(flags.before)) : 3;
   const after = flags.after && flags.after !== true ? Math.max(0, Number(flags.after)) : 3;
   const want = id.startsWith("L:") ? id : `L:${id}`;
@@ -622,15 +721,32 @@ function cmdTimeline() {
 }
 
 function cmdPath() {
-  process.stdout.write(
-    ledgerPath(flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug()) + "\n",
-  );
+  process.stdout.write(ledgerPath(repoSlug()) + "\n");
   process.exitCode = 0;
   return;
 }
 
+const OUTCOMES = new Set(["useful", "dead_end", "corrected"]);
+
+function cmdFeedback() {
+  const slug = repoSlug();
+  const raw = flags.id && flags.id !== true ? String(flags.id).replace(/^\[|\]$/g, "") : "";
+  const id = raw && !raw.startsWith("L:") ? `L:${raw}` : raw;
+  const outcome = String(flags.outcome || "");
+  if (!id || !OUTCOMES.has(outcome))
+    die("feedback needs --id <id> --outcome <useful|dead_end|corrected>", 1);
+  if (!readLedger(slug).some((r) => rowId(r) === id)) die(`no ledger entry ${id}`, 2);
+  if (refuseExcluded(slug)) return;
+  const row = { ts: new Date().toISOString(), id, outcome };
+  if (flags.task && flags.task !== true) row.task = String(flags.task);
+  ensureDir(feedbackPath(slug));
+  appendFileSync(feedbackPath(slug), JSON.stringify(row) + "\n", "utf8");
+  const s = standing(readFeedback(slug).get(id) ?? []);
+  process.stdout.write(JSON.stringify({ ok: true, slug, id, ...s }) + "\n");
+}
+
 function cmdStats() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const rows = readLedger(slug);
   const counts = { fact: 0, convention: 0, "rejected-preference": 0 };
   for (const r of rows) if (counts[r.kind] !== undefined) counts[r.kind]++;
@@ -651,6 +767,9 @@ switch (SUB) {
   case "forget":
     cmdForget();
     break;
+  case "feedback":
+    cmdFeedback();
+    break;
   case "brief":
     cmdBrief();
     break;
@@ -671,7 +790,7 @@ switch (SUB) {
     break;
   default:
     process.stderr.write(
-      "usage: learnings-ledger.mjs <add|from-triage|forget|brief|profile|show|timeline|path|stats> [flags]\n",
+      "usage: learnings-ledger.mjs <add|from-triage|feedback|forget|brief|profile|show|timeline|path|stats> [flags]\n",
     );
     process.exit(64);
 }

package/pipeline/scripts/office-build.mjs

@@ -8,7 +8,10 @@
  * strings.json) and this script inlines them into
  * pipeline/office/index.html: the list of sprite names in pipeline/office/assets
  * (served by contract-server.mjs at /office/assets/), the strings as a JSON
- * literal, the two code files in order inside one IIFE.
+ * literal, the two code files in order inside one IIFE. It also renders the
+ * pixel grids in pipeline/office-art into PNG sprites in pipeline/office/assets
+ * and writes pipeline/office/toolkit.json, the toolkit version shipped with
+ * the page; --check holds all three to their sources.
  *
  *   node pipeline/scripts/office-build.mjs          write the page
  *   node pipeline/scripts/office-build.mjs --check  exit 1 when the page on
@@ -16,7 +19,9 @@
  *                                                   sources build to
  */
 
+import { createHash } from "node:crypto";
 import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { deflateSync } from "node:zlib";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -24,8 +29,94 @@ const ROOT = join(import.meta.dirname, "..");
 const SRC = join(ROOT, "office-src");
 const OUT = join(ROOT, "office", "index.html");
 const ASSETS = join(ROOT, "office", "assets");
+const TOOLKIT = join(ROOT, "office", "toolkit.json");
+const ART = join(ROOT, "office-art");
+const FACTS = join(ROOT, "..", "docs", "facts.json");
 const PNG_SIGNATURE = "89504e470d0a1a0a";
 
+// --- the project's own sprites -----------------------------------------------
+// Each office-art/<NAME>.txt is a "size WxH" line and H rows of W letters, one
+// letter per pixel from office-art/palette.json, "." transparent. They are
+// encoded here into office/assets/<NAME>.png byte for byte the same each time
+// (no timestamp, fixed compression), so --check can hold the PNGs to their
+// text and a review reads the drawing as a diff.
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (const b of buf) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+/** An RGBA PNG, unfiltered rows, zlib level 9. */
+export function encodePng(width, height, rgba) {
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  for (let y = 0; y < height; y++) {
+    rgba.copy(raw, y * (width * 4 + 1) + 1, y * width * 4, (y + 1) * width * 4);
+  }
+  return Buffer.concat([
+    Buffer.from(PNG_SIGNATURE, "hex"),
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/** One art file as a PNG; throws on a size line, row length or letter that does not fit. */
+export function renderArt(text, colors, name = "sprite") {
+  const lines = text.replace(/\r/g, "").trimEnd().split("\n");
+  const m = /^size (\d{1,3})x(\d{1,3})$/.exec(lines[0] ?? "");
+  if (!m) throw new Error(`${name}: the first line is "size WxH"`);
+  const [w, h] = [Number(m[1]), Number(m[2])];
+  const rows = lines.slice(1);
+  if (rows.length !== h) throw new Error(`${name}: ${rows.length} rows, expected ${h}`);
+  const rgba = Buffer.alloc(w * h * 4);
+  rows.forEach((row, y) => {
+    if (row.length !== w)
+      throw new Error(`${name}: row ${y + 1} is ${row.length} wide, expected ${w}`);
+    [...row].forEach((ch, x) => {
+      if (ch === ".") return;
+      const hex = colors[ch];
+      if (!hex) throw new Error(`${name}: "${ch}" is not in the palette`);
+      const o = (y * w + x) * 4;
+      rgba[o] = parseInt(hex.slice(0, 2), 16);
+      rgba[o + 1] = parseInt(hex.slice(2, 4), 16);
+      rgba[o + 2] = parseInt(hex.slice(4, 6), 16);
+      rgba[o + 3] = 255;
+    });
+  });
+  return encodePng(w, h, rgba);
+}
+
+/** Every art sprite, name -> PNG bytes. */
+export function artSprites() {
+  const { colors } = JSON.parse(readFileSync(join(ART, "palette.json"), "utf8"));
+  const out = new Map();
+  for (const f of readdirSync(ART).sort()) {
+    if (!f.endsWith(".txt")) continue;
+    const name = basename(f, ".txt");
+    if (!/^[A-Z0-9_]{1,48}$/.test(name)) throw new Error(`${f}: sprite names are A-Z, 0-9 and _`);
+    out.set(name, renderArt(readFileSync(join(ART, f), "utf8"), colors, name));
+  }
+  return out;
+}
+
 // The sprite names the page may load from /office/assets/: every PNG beside
 // the page, checked to be one.
 function atlas() {
@@ -41,6 +132,20 @@ function atlas() {
   return out;
 }
 
+/**
+ * The toolkit version the office's Tools window starts, shipped beside the
+ * page: the version this release was checked against, from docs/facts.json.
+ * The host runs the toolkit as @latest; the panel only runs an exact version,
+ * and every pipeline update brings the newer one with it.
+ */
+export function toolkitDoc() {
+  const v = JSON.parse(readFileSync(FACTS, "utf8")).toolkitVersion;
+  if (typeof v !== "string" || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(v)) {
+    throw new Error("docs/facts.json carries no exact toolkitVersion");
+  }
+  return JSON.stringify({ toolkitVersion: v }, null, 2) + "\n";
+}
+
 export function build() {
   const read = (f) => readFileSync(join(SRC, f), "utf8");
   const strings = JSON.parse(read("strings.json"));
@@ -56,6 +161,12 @@ export function build() {
     "})();",
   ].join("\n");
   const style = read("style.css").trim();
+  // The build id the server reads back from the installed page: the page
+  // compares it with its own to tell that a newer one has been installed.
+  const hash = createHash("sha256").update(script).update(style).update(read("shell.html"));
+  // Redrawn sprites change the page too, though no source text did.
+  for (const [name, png] of artSprites()) hash.update(name).update(png);
+  const build = hash.digest("hex").slice(0, 12);
   // Text that would close the inline element early, or open an HTML comment
   // inside it, turns source into markup.
   if (/<\/script|<!--/i.test(script)) throw new Error("the script contains </script or <!--");
@@ -64,26 +175,52 @@ export function build() {
   for (const marker of ["/*STYLE*/", "/*SCRIPT*/"]) {
     if (shell.split(marker).length !== 2) throw new Error(`shell.html needs exactly one ${marker}`);
   }
-  return shell.replace("/*STYLE*/", () => style).replace("/*SCRIPT*/", () => script);
+  const stamped = script.replace('"use strict";', () => `"use strict";\nconst BUILD = "${build}";`);
+  return shell.replace("/*STYLE*/", () => style).replace("/*SCRIPT*/", () => stamped);
 }
 
 const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isMain) {
+  const art = artSprites();
+  const check = process.argv.includes("--check");
+  if (!check) for (const [name, png] of art) writeFileSync(join(ASSETS, `${name}.png`), png);
   const html = build();
-  if (process.argv.includes("--check")) {
-    let current = "";
-    try {
-      current = readFileSync(OUT, "utf8");
-    } catch {
-      // A missing page is stale by definition.
+  const toolkit = toolkitDoc();
+  if (check) {
+    for (const [name, png] of art) {
+      let on = null;
+      try {
+        on = readFileSync(join(ASSETS, `${name}.png`));
+      } catch {
+        // Missing is stale.
+      }
+      if (!on || !on.equals(png)) {
+        console.error(
+          `office/assets/${name}.png is stale: run node pipeline/scripts/office-build.mjs`,
+        );
+        process.exit(1);
+      }
     }
-    if (current !== html) {
+    const read = (f) => {
+      try {
+        return readFileSync(f, "utf8");
+      } catch {
+        // A missing file is stale by definition.
+        return "";
+      }
+    };
+    if (read(OUT) !== html) {
       console.error("office/index.html is stale: run node pipeline/scripts/office-build.mjs");
       process.exit(1);
     }
-    console.log("office/index.html matches its sources");
+    if (read(TOOLKIT) !== toolkit) {
+      console.error("office/toolkit.json is stale: run node pipeline/scripts/office-build.mjs");
+      process.exit(1);
+    }
+    console.log("office/index.html and office/toolkit.json match their sources");
   } else {
     writeFileSync(OUT, html);
-    console.log(`wrote ${OUT} (${Buffer.byteLength(html)} bytes)`);
+    writeFileSync(TOOLKIT, toolkit);
+    console.log(`wrote ${OUT} (${Buffer.byteLength(html)} bytes) and ${TOOLKIT}`);
   }
 }