blockyard 0.1.0 → 0.1.2

package/public/js/tetrust.js

@@ -9,7 +9,7 @@
 // the same sky (drawSky). The game inherits the framework rather than imitating it.
 import { board3d } from './details3d.js';
 import { newGame, tick, move, rotate, softDrop, hardDrop, tiles, previewTiles, peekNext, gravityMs, PIECES, COLS, ROWS } from './tetris.js';
-import { loadSettings, setSetting, tetrustOptions } from './settings.js';
+import { loadSettings, setSetting, tetrustOptions, nextSky, SKY_LABELS } from './settings.js';
 import * as sound from './tetsound.js';
 
 const SCORES_KEY = 'blockyard.tetrust.scores';
@@ -173,9 +173,20 @@ function drawScores(highlightAt = null) {
 
 // THE GAME'S OWN SWITCHES (operator: "Toggle for each in the game display"): three buttons on the
 // HUD, the same settings the Display panel shows, so a flip in either place is a flip in both
-const SWITCHES = [['tetStars', 'stars'], ['tetGalaxy', 'galaxy'], ['tetMusic', 'music'], ['tetSfx', 'sfx']];
+const SWITCHES = [['tetMusic', 'music'], ['tetSfx', 'sfx']];
+/** The sky button says which sky it is on, and lights up while there is one. */
+function skyButton(id, sky) {
+  const b = el(id);
+  if (!b) return;
+  b.textContent = `\u2600 ${SKY_LABELS[sky] ?? sky}`;
+  b.classList.toggle('on', sky !== 'none');
+  b.setAttribute('aria-pressed', sky !== 'none' ? 'true' : 'false');
+}
 function drawSwitches() {
   const t = tetrustOptions(loadSettings());
+  // ONE SKY BUTTON (docs/PLAN-SKIES.md): Galaxy, Earth or none, round the ring, in place of the old
+  // star field and galaxy pair -- the same setting the Sky tab's table shows for this board
+  skyButton('tetSkySw', t.sky.sky);
   for (const [id, key] of SWITCHES) {
     const b = el(id);
     if (!b) continue;
@@ -194,7 +205,6 @@ function flip(key) {
   setSetting(loadSettings(), `tetrust.${key}`, !cur);
   sound.unlock();
   drawSwitches();
-  if (key === 'stars' || key === 'galaxy') drawSky();
   G.dirty = true;
   if (!G.running || G.paused) draw();
 }
@@ -205,9 +215,7 @@ function drawSky() {
   const t = tetrustOptions(loadSettings());
   board3d(sky, [], {
     ...SKY,
-    stars: t.stars, galaxy: t.stars && t.galaxy, galaxyAt: t.galaxyAt,
-    starDensity: t.starDensity, starBrightness: t.starBrightness,
-    nebulae: t.nebulae, galaxies: t.galaxies, dust: t.dust, clusters: t.clusters, starColours: t.starColours, starGlints: t.starGlints,
+    ...t.sky,          // which sky this board chose, and what it is made of (settings.js skyFor)
   });
 }
 
@@ -341,6 +349,7 @@ function bind() {
   document.addEventListener('visibilitychange', () => { if (document.hidden && G.running && !G.paused) pause('paused — you looked away'); });
   el('tetResume')?.addEventListener('click', () => resume());
   for (const [id, key] of SWITCHES) el(id)?.addEventListener('click', () => flip(key));
+  el('tetSkySw')?.addEventListener('click', () => { const s = loadSettings(); setSetting(s, 'tetrust.sky', nextSky(tetrustOptions(s).sky.sky)); sound.unlock(); drawSwitches(); drawSky(); draw(); });
 }
 
 export function renderTetrust(s, state, h) {

package/public/js/tetsound.js

@@ -8,7 +8,7 @@
 // the first play or key press, and nothing here throws where there is no AudioContext at all
 // (tests, or a browser with audio blocked): every call is a no-op then.
 
-const HZ = { A4: 440, B4: 493.88, C5: 523.25, D5: 587.33, E5: 659.25, F5: 698.46, G5: 783.99, A5: 880, GS4: 415.3, E4: 329.63, R: 0 };
+const HZ = { A4: 440, B4: 493.88, C5: 523.25, D5: 587.33, E5: 659.25, F5: 698.46, G5: 783.99, A5: 880, GS4: 415.3, E4: 329.63, D4: 293.66, F4: 349.23, G4: 392, BB4: 466.16, R: 0 };
 
 // Korobeiniki, A minor, one verse: [note, beats]
 export const THEME = Object.freeze([
@@ -23,6 +23,24 @@ export const THEME = Object.freeze([
 ]);
 export const BPM = 148;
 
+// SCORCHED YARD's tune (2026-09-16): a march in D minor, sixteen bars, on the same square wave --
+// a drum-less thing that keeps time between the turns and does not fight the blasts
+export const THEME_SCORCHED = Object.freeze([
+  ['D4', 1], ['D4', 0.5], ['D4', 0.5], ['F4', 1], ['A4', 1],
+  ['G4', 1], ['F4', 0.5], ['E4', 0.5], ['D4', 2],
+  ['F4', 1], ['F4', 0.5], ['F4', 0.5], ['A4', 1], ['C5', 1],
+  ['BB4', 1], ['A4', 0.5], ['G4', 0.5], ['A4', 2],
+  ['D5', 1], ['D5', 0.5], ['D5', 0.5], ['C5', 1], ['BB4', 1],
+  ['A4', 1], ['G4', 0.5], ['F4', 0.5], ['G4', 2],
+  ['A4', 1], ['BB4', 0.5], ['A4', 0.5], ['G4', 1], ['F4', 1],
+  ['E4', 1], ['E4', 0.5], ['E4', 0.5], ['D4', 2],
+  ['D4', 0.5], ['R', 0.5], ['D4', 0.5], ['R', 0.5], ['A4', 1], ['R', 1],
+  ['F4', 0.5], ['R', 0.5], ['F4', 0.5], ['R', 0.5], ['D5', 1], ['R', 1],
+  ['C5', 1], ['BB4', 1], ['A4', 1], ['G4', 1],
+  ['F4', 1], ['E4', 1], ['D4', 2],
+]);
+export const THEMES = Object.freeze({ tetrust: { notes: THEME, bpm: BPM }, scorched: { notes: THEME_SCORCHED, bpm: 112 } });
+
 // the effects: [frequency from, frequency to, seconds, wave, gain]
 export const SFX = Object.freeze({
   move: [520, 520, 0.045, 'square', 0.05],
@@ -56,6 +74,15 @@ export const SFX = Object.freeze({
   // BLOCKANOID (arkanoid.js): a silver brick RINGS rather than breaks and gold rings harder and
   // lower, so the ear learns which bricks are worth hitting before the eye does. A capsule is a
   // rising chime (it is always good news), the laser a short zap, a minion a dull pop.
+  // SCORCHED YARD (scorchedyard.js): a thump for the shot, a crack for a small blast and a rumble
+  // for a nuke, a knock for a hit, a low sweep for a death, a tick for the turn, a rustle for dirt
+  syFire: [140, 40, 0.16, 'sawtooth', 0.1],
+  syBlast: [180, 30, 0.26, 'sawtooth', 0.11],
+  syBig: [90, 18, 0.7, 'sawtooth', 0.12],
+  syHit: [520, 180, 0.09, 'square', 0.06],
+  syDeath: [400, 40, 0.9, 'sawtooth', 0.1],
+  syTurn: [880, 880, 0.04, 'square', 0.035],
+  syDirt: [260, 120, 0.12, 'triangle', 0.05],
   silver: [560, 620, 0.06, 'triangle', 0.055],
   gold: [240, 210, 0.07, 'square', 0.05],
   capsule: [620, 1560, 0.22, 'triangle', 0.075],
@@ -135,12 +162,13 @@ const TIMER_MS = 500;
 function schedule() {
   const c = S.ctx;
   if (!c || !S.music) return;
-  const beat = 60 / BPM;
+  const tune = THEMES[S.theme] ?? THEMES.tetrust;
+  const beat = 60 / tune.bpm;
   // fallen behind (the tab was hidden, the thread was held): pick the tune up from now rather
   // than cramming the missed notes into an instant
   if (S.at < c.currentTime - 0.05) S.at = c.currentTime + 0.02;
   while (S.at < c.currentTime + LOOKAHEAD_S) {
-    const [name, beats] = THEME[S.i % THEME.length];
+    const [name, beats] = tune.notes[S.i % tune.notes.length];
     const dur = beats * beat;
     const hz = HZ[name] ?? 0;
     if (hz > 0) {
@@ -153,9 +181,11 @@ function schedule() {
   S.timer = setTimeout(schedule, TIMER_MS);
 }
 
-export function setMusic(on) {
+export function setMusic(on, theme = 'tetrust') {
   const want = !!on;
-  if (want === S.music && (!want || S.timer)) return;    // already so: never restart a running tune
+  const tune = THEMES[theme] ? theme : 'tetrust';
+  if (want === S.music && (!want || S.timer) && S.theme === tune) return;    // already so: never restart a running tune
+  if (S.theme !== tune) { S.theme = tune; S.i = 0; }
   S.music = want;
   if (S.timer) { clearTimeout(S.timer); S.timer = null; }
   if (!S.music) { hush(); return; }

package/scripts/check.js

@@ -148,6 +148,52 @@ export async function runChecks(node, { rpc, fs = { existsSync, statSync, readdi
     }
   }
 
+  // ---- what KIND of node is this, and what can it do that Core cannot? ----
+  //
+  // Until 2026-09-16 there was no way to tell over RPC. The monitor says so in
+  // its own source: "both report the same non-Core subversion string. So RPC
+  // cannot tell you whether RPC is complete; only the log's build banner can."
+  // That is why `log.enabled` is a per-node setting -- identifying the node
+  // needed FILE ACCESS to a machine we can already reach by RPC.
+  //
+  // bmcgetcapabilities answers it in one call. A plain Core node does not have
+  // the method, and that is not a failure: it is how we learn this is Core.
+  // Every field it returns is LIVE STATE rather than a compile-time list, so
+  // "the node serves address history" means it is serving it now, not that the
+  // binary could if configured.
+  {
+    const caps = await one('bmcgetcapabilities', [], 5000);
+    if (!caps.ok) {
+      facts.nodeKind = 'core';
+      add('node kind', 'ok', 'Bitcoin Core (or a node without bmcgetcapabilities) — BlockYard supplies the address index itself');
+    } else {
+      const r = caps.result ?? {};
+      const x = r.extensions ?? {};
+      facts.nodeKind = r.node ?? 'bitcoinmachinecode';
+      facts.nodeBuild = r.build?.commit ?? null;
+      facts.nodeCapabilities = {
+        addrindex: Boolean(x.addrindex),
+        esploraPort: Number(x.esploraport ?? 0) || 0,
+        mempoolJournal: Boolean(x.mempooljournal?.enabled),
+        mempoolJournalCapacity: x.mempooljournal?.enabled ? Number(x.mempooljournal.capacity) : 0,
+        downloadInfo: Boolean(x.downloadinfo),
+        rpcComplete: Boolean(r.rpc_complete?.peerinfo && r.rpc_complete?.nettotals),
+      };
+      const have = [];
+      if (facts.nodeCapabilities.addrindex) have.push('address history from the node');
+      if (facts.nodeCapabilities.esploraPort) have.push(`Esplora facade on :${facts.nodeCapabilities.esploraPort}`);
+      if (facts.nodeCapabilities.mempoolJournal) have.push(`mempool departure journal (${facts.nodeCapabilities.mempoolJournalCapacity.toLocaleString()} records)`);
+      if (facts.nodeCapabilities.downloadInfo) have.push('download worker map');
+      add('node kind', 'ok',
+          `${facts.nodeKind} ${facts.nodeBuild ? `(${facts.nodeBuild}${r.build?.dirty ? ', dirty' : ''}) ` : ''}in ${caps.ms}`
+          + (have.length ? ` — ${have.join(', ')}` : ' — no extensions enabled'));
+      // The one that changes what BlockYard has to DO: with the node serving
+      // address history there is no reason to build and follow a second copy.
+      if (facts.nodeCapabilities.addrindex)
+        add('address index', 'ok', 'the node serves it (addrindex=1) — BlockYard does not need to build its own');
+    }
+  }
+
   return { ok: !checks.some((c) => c.status === 'fail'), checks, facts };
 }
 

package/scripts/index-build.js

@@ -3,7 +3,9 @@
 //
 //   node scripts/index-build.js --out <dir> [--node <id>] [--workers N] [--files 0,1,5754]
 //
-// --files builds a partial index for testing (the completeness check is skipped). Progress goes to
+// --files builds a partial index for testing (the completeness check is skipped). A build stopped part
+// way resumes when run again with the same --out (build.js, THE BUILD JOURNAL); the log line says so,
+// or says why the unfinished work was discarded. Progress goes to
 // stderr once a second; the manifest, with every phase's timings, goes to stdout at the end.
 import { loadConfig } from '../server/config.js';
 import { RpcClient } from '../server/rpc/client.js';
@@ -12,6 +14,10 @@ import path from 'node:path';
 import { progress, progressLine, strip, c, fmt } from './ui.js';
 
 const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : def; };
+// --workers must be a whole number of at least one (audit 2026-09-16, I3): `abc` or `0` made a pool with
+// no workers, and with --files that wrote a "successful" manifest of zero rows
+const workersArg = process.argv.includes('--workers') ? String(arg('workers')) : null;
+if (workersArg != null && !(/^\d+$/.test(workersArg) && Number(workersArg) >= 1 && Number.isSafeInteger(Number(workersArg)))) { console.error(`--workers must be a whole number of at least 1, not ${JSON.stringify(workersArg)}`); process.exit(2); }
 const cfg = loadConfig();
 const node = cfg.nodes.find((n) => n.id === arg('node', null)) ?? cfg.nodes.find((n) => n.datadir) ?? cfg.nodes[0];
 if (!node.datadir) { console.error(`node ${node.id} has no datadir configured; the index is built from its block files`); process.exit(2); }
@@ -25,7 +31,8 @@ const bar = progress();
 const manifest = await buildIndex({
   rpc, blocksDir: path.join(node.datadir, 'blocks'), out,
   pace: rpcPacer(rpc, { onChange: (held) => process.stderr.write(held ? '  paused while the node\'s RPC is slow or failing\n' : '  resumed\n') }),
-  workers: arg('workers', null) ? Number(arg('workers')) : undefined,
+  log: (text) => { bar.done(); process.stderr.write(`  ${text}\n`); },
+  workers: workersArg != null ? Number(workersArg) : undefined,
   files: arg('files', null) ? arg('files').split(',').map(Number) : null,
   onProgress: (p) => {
     if (p.phase !== phase) {

package/scripts/pool-map.js

@@ -16,6 +16,13 @@
 //   node scripts/pool-map.js                      # fetch and write data/pool-map.json
 //   node scripts/pool-map.js --file pools-v2.json # offline input
 //   node scripts/pool-map.js --check              # compare against what we are seeing now
+//   node scripts/pool-map.js --yes                # replace an existing data/pool-map.json without asking
+//   node scripts/pool-map.js --expect-sha256 HEX  # refuse a download that is not exactly those bytes
+//
+// Before it replaces data/pool-map.json it prints which pools the new map adds, removes and
+// changes, and writes only on --yes or a "y" at the prompt; redirects are followed to HTTPS only,
+// by both the node:https path and the curl fallback; and the coverage check asks the monitor on
+// the port and scheme its config names (2026-09-16, audit L15).
 //
 // The input shape as fetched on 2026-09-09: 35,733 bytes, 171 pools, 201 tags, keys
 // per pool: addresses, id, link, name, tags. Tags are literal fragments of the coinbase
@@ -85,14 +92,29 @@ function build(content, source) {
 // 367 ms. Pinning the family is the fix; a curl fallback is kept because a tool that
 // fetches pool labels has to work on a box whose stack is half broken.
 import https from 'node:https';
+import readline from 'node:readline/promises';
 import { execFileSync } from 'node:child_process';
+import { loadConfig } from '../server/config.js';
+
+/**
+ * Where a redirect may go (2026-09-16, audit L15): HTTPS only. A `Location: http://...` would
+ * otherwise have been followed by the curl fallback, and the labels read over plain HTTP.
+ * Returns the absolute next URL, or throws.
+ */
+export function redirectTarget(location, from) {
+  const next = new URL(location, from);
+  if (next.protocol !== 'https:') throw new Error(`refusing a redirect from ${from} to ${next.protocol}//${next.host}: HTTPS only`);
+  return next.toString();
+}
 
-function getOverHttps(url, redirectsLeft = 3, extra = {}) {
+export function getOverHttps(url, redirectsLeft = 3, extra = {}) {
   return new Promise((resolve, reject) => {
     const req = https.get(url, { family: 4, ...extra, headers: { 'user-agent': 'BlockYard pool-map/1' }, timeout: 20_000 }, (res) => {
       if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirectsLeft > 0) {
         res.resume();
-        return resolve(getOverHttps(new URL(res.headers.location, url).toString(), redirectsLeft - 1));
+        let next;
+        try { next = redirectTarget(res.headers.location, url); } catch (err) { return reject(err); }
+        return resolve(getOverHttps(next, redirectsLeft - 1));
       }
       if (res.statusCode !== 200) { res.resume(); return reject(new Error(`GET ${url} -> HTTP ${res.statusCode}`)); }
       const chunks = [];
@@ -105,53 +127,147 @@ function getOverHttps(url, redirectsLeft = 3, extra = {}) {
   });
 }
 
+/**
+ * The curl fallback's arguments. `--proto =https --proto-redir =https` (2026-09-16, audit L15):
+ * -L alone follows a redirect to any protocol curl speaks, plain http included.
+ */
+export function curlArgs(url) {
+  return ['-fsSL', '--proto', '=https', '--proto-redir', '=https', '--max-time', '25', url];
+}
+
 async function fetchContent() {
   try {
     return await getOverHttps(URL_);
   } catch (err) {
     // curl follows its own resolver order and got 200 here while node's fetch failed,
     // so a second, different path is worth one retry before declaring the fetch dead.
+    // A refused non-HTTPS redirect is not a flaky stack: it is not retried another way.
+    if (/HTTPS only/.test(err?.message ?? '')) throw err;
     try {
-      return execFileSync('curl', ['-fsSL', '--max-time', '25', URL_], { encoding: 'utf8', maxBuffer: 8 << 20 });
+      return execFileSync('curl', curlArgs(URL_), { encoding: 'utf8', maxBuffer: 8 << 20 });
     } catch {
       throw new Error(`could not fetch ${URL_}: ${err?.message ?? err}`);
     }
   }
 }
 
-const content = asFile ? fs.readFileSync(asFile, 'utf8') : await fetchContent();
-const map = build(content, asFile ? `file:${path.basename(asFile)}` : URL_);
-
-// What we are actually seeing right now, so the coverage number is measured and not
-// assumed. Read live from the running monitor if it answers; otherwise say it is unknown.
-let observed = null;
-let coverageError = null;
-try {
-  const cfgPath = path.join(ROOT, 'config', 'local.json');
-  const host = JSON.parse(fs.readFileSync(cfgPath, 'utf8'))?.server?.hosts?.[0] ?? '127.0.0.1';
-  // Same family:4 path as the fetch above, plus the box's own CA: the monitor serves TLS
-  // from a local CA that is not in the system trust store, and "could not verify" is a
-  // different fact from "could not reach".
-  const caFile = process.env.BLOCKYARD_CA_FILE ?? null;   // a CA file, only where the fetch needs a private one
-  const body = await getOverHttps(`https://${host}:8088/api/mining?node=main`, 0, fs.existsSync(caFile) ? { ca: fs.readFileSync(caFile) } : {});
-  const d = JSON.parse(body);
-  const rows = d.recent ?? [];
-  const hit = rows.filter((r) => map.matchers.some((m) => normalizeText(`${r.rawCoinbase ? Buffer.from(r.rawCoinbase, 'hex').toString('utf8') : ''} ${r.tagText || ''}`).includes(m.tagNorm))).length;
-  observed = {
-    blocks: rows.length, labelled: hit, unknown: rows.filter((r) => !r.poolLabel).length,
-    labelSource: d.labelSource ? `labels from ${d.labelSource.source} @ ${(d.labelSource.sha256 || '').slice(0, 10)}` : 'no map loaded by the monitor yet',
-  };
-} catch (err) {
-  coverageError = err?.message ?? String(err);
+/**
+ * What a refresh changes, pool by pool (2026-09-16, audit L15): the file decides which
+ * organisation the dashboard names for a block, so a rewrite is shown before it is made.
+ * `changed` is a pool whose name, link or tags differ. Keys are the maps' own pool keys.
+ */
+export function diffPoolMaps(before, after) {
+  const index = (m) => new Map((m?.pools ?? []).map((p) => [p.key, p]));
+  const a = index(before), b = index(after);
+  const same = (x, y) => x.name === y.name && (x.link ?? null) === (y.link ?? null)
+    && JSON.stringify([...(x.tags ?? [])].sort()) === JSON.stringify([...(y.tags ?? [])].sort());
+  const added = [...b.keys()].filter((k) => !a.has(k)).sort();
+  const removed = [...a.keys()].filter((k) => !b.has(k)).sort();
+  const changed = [...b.keys()].filter((k) => a.has(k) && !same(a.get(k), b.get(k))).sort();
+  return { added, removed, changed, unchanged: [...b.keys()].filter((k) => a.has(k)).length - changed.length };
+}
+
+export function formatDiff(d, name = (k) => k) {
+  const list = (ks) => (ks.length > 12 ? `${ks.slice(0, 12).map(name).join(', ')}, and ${ks.length - 12} more` : ks.map(name).join(', '));
+  const lines = [`pools: ${d.added.length} added, ${d.removed.length} removed, ${d.changed.length} changed, ${d.unchanged} unchanged`];
+  if (d.added.length) lines.push(`  + ${list(d.added)}`);
+  if (d.removed.length) lines.push(`  - ${list(d.removed)}`);
+  if (d.changed.length) lines.push(`  ~ ${list(d.changed)}`);
+  return lines.join('\n');
+}
+
+/** --expect-sha256: the download must be exactly these bytes (2026-09-16, audit L15). */
+export function checkExpectedSha(content, expected) {
+  if (expected == null) return null;
+  const want = String(expected).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(want)) throw new Error('--expect-sha256 takes 64 hex characters');
+  const got = crypto.createHash('sha256').update(content).digest('hex');
+  if (got !== want) throw new Error(`sha256 mismatch: expected ${want}, got ${got}; nothing written`);
+  return got;
+}
+
+/**
+ * The running monitor's own mining endpoint, for the coverage check (2026-09-16, audit L15): it
+ * was https://<host>:8088 whatever the config said, and the default port has been 21000 since
+ * 2026-09-13, so coverage was never measured. Port, TLS and bind address come from the loaded
+ * config (config/local.json, BLOCKYARD_PORT, BLOCKYARD_TLS); HTTPS unless TLS is turned off.
+ */
+export function coverageUrl(cfg) {
+  const server = cfg?.server ?? {};
+  let host = server.hosts?.[0] ?? server.host ?? '127.0.0.1';
+  if (Array.isArray(host)) host = host[0] ?? '127.0.0.1';
+  if (host === '0.0.0.0') host = '127.0.0.1';
+  if (host === '::') host = '::1';
+  const port = Number.isInteger(Number(server.port)) && Number(server.port) > 0 ? Number(server.port) : 21000;
+  const scheme = cfg?.tls === false || server.tls?.enabled === false ? 'http' : 'https';
+  return `${scheme}://${host.includes(':') ? `[${host}]` : host}:${port}/api/mining?node=main`;
 }
 
-console.log(`pools: ${map.pools.length}  matchers: ${map.matchers.length}  sha256: ${map.sourceSha256.slice(0, 12)}`);
-if (observed) console.log(`coverage of the ${observed.blocks} attributed blocks: ${observed.labelled} matched a curated tag, ${observed.unknown} keep their raw tag\n  ${observed.labelSource ?? ''}`);
-else console.log(`coverage: not measured (${coverageError}) -- reported as unknown rather than assumed`);
-if (checkOnly) process.exit(0);
+async function main() {
+  const argAfter = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] ?? null : null);
+  const content = asFile ? fs.readFileSync(asFile, 'utf8') : await fetchContent();
+  try { checkExpectedSha(content, argAfter('--expect-sha256')); } catch (err) { console.error(err.message); process.exit(1); }
+  const map = build(content, asFile ? `file:${path.basename(asFile)}` : URL_);
 
-fs.mkdirSync(path.dirname(OUT), { recursive: true });
-const tmp = `${OUT}.tmp`;
-fs.writeFileSync(tmp, `${JSON.stringify(map, null, 1)}\n`);
-fs.renameSync(tmp, OUT);
-console.log(`wrote ${path.relative(ROOT, OUT)}`);
+  // What we are actually seeing right now, so the coverage number is measured and not
+  // assumed. Read live from the running monitor if it answers; otherwise say it is unknown.
+  let observed = null;
+  let coverageError = null;
+  try {
+    let cfg;
+    try { cfg = loadConfig(); } catch { cfg = { server: { port: Number(process.env.BLOCKYARD_PORT) || 21000 } }; }
+    const url = coverageUrl(cfg);
+    // Same family:4 path as the fetch above, plus the box's own CA: the monitor serves TLS
+    // from a local CA that is not in the system trust store, and "could not verify" is a
+    // different fact from "could not reach".
+    const caFile = process.env.BLOCKYARD_CA_FILE ?? null;   // a CA file, only where the fetch needs a private one
+    const extra = caFile && fs.existsSync(caFile) ? { ca: fs.readFileSync(caFile) } : {};
+    const body = url.startsWith('https:') ? await getOverHttps(url, 0, extra) : await (await fetch(url)).text();
+    const d = JSON.parse(body);
+    const rows = d.recent ?? [];
+    const hit = rows.filter((r) => map.matchers.some((m) => normalizeText(`${r.rawCoinbase ? Buffer.from(r.rawCoinbase, 'hex').toString('utf8') : ''} ${r.tagText || ''}`).includes(m.tagNorm))).length;
+    observed = {
+      blocks: rows.length, labelled: hit, unknown: rows.filter((r) => !r.poolLabel).length,
+      labelSource: d.labelSource ? `labels from ${d.labelSource.source} @ ${(d.labelSource.sha256 || '').slice(0, 10)}` : 'no map loaded by the monitor yet',
+    };
+  } catch (err) {
+    coverageError = err?.message ?? String(err);
+  }
+
+  console.log(`pools: ${map.pools.length}  matchers: ${map.matchers.length}  sha256: ${map.sourceSha256}`);
+  if (observed) console.log(`coverage of the ${observed.blocks} attributed blocks: ${observed.labelled} matched a curated tag, ${observed.unknown} keep their raw tag\n  ${observed.labelSource ?? ''}`);
+  else console.log(`coverage: not measured (${coverageError}) -- reported as unknown rather than assumed`);
+
+  // THE DIFF BEFORE THE WRITE (2026-09-16, audit L15): against the file this replaces, or, when
+  // there is none yet, the shipped config/pool-map.json the monitor uses until then.
+  const shipped = path.join(ROOT, 'config', 'pool-map.json');
+  const replacing = fs.existsSync(OUT);
+  const prevFile = replacing ? OUT : fs.existsSync(shipped) ? shipped : null;
+  let prev = null;
+  if (prevFile) { try { prev = JSON.parse(fs.readFileSync(prevFile, 'utf8')); } catch { prev = null; } }
+  if (prev) {
+    const names = new Map([...(prev.pools ?? []), ...map.pools].map((p) => [p.key, p.name]));
+    console.log(`against ${path.relative(ROOT, prevFile)}${prev.sourceSha256 ? ` (sha256 ${prev.sourceSha256.slice(0, 12)})` : ''}:`);
+    console.log(formatDiff(diffPoolMaps(prev, map), (k) => names.get(k) ?? k));
+  }
+  if (checkOnly) process.exit(0);
+
+  if (replacing && !args.includes('--yes')) {
+    if (!process.stdin.isTTY) { console.log(`not written: ${path.relative(ROOT, OUT)} exists; pass --yes to replace it`); process.exit(1); }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const a = (await rl.question(`replace ${path.relative(ROOT, OUT)}? (y/N) `)).trim().toLowerCase();
+    rl.close();
+    if (!a.startsWith('y')) { console.log('not written'); process.exit(1); }
+  }
+
+  fs.mkdirSync(path.dirname(OUT), { recursive: true });
+  const tmp = `${OUT}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(map, null, 1)}\n`);
+  fs.renameSync(tmp, OUT);
+  console.log(`wrote ${path.relative(ROOT, OUT)}`);
+}
+
+// run only as a script, so the tests can import the pieces without a fetch
+if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
+  main().catch((err) => { console.error(err?.message ?? err); process.exit(1); });
+}