Update check: say what the forge answered, not zlib's "incorrect header check"

A Gitea that requires a sign-in does not refuse the branch archive: it
redirects the download to its login page, which arrives as a 200 of HTML,
and the admin page then reported zlib failing to unpack it — "incorrect
header check". Both booths showed exactly that on 29 Sept once the sign-in
requirement was switched on.

The updater now names the case: "… requires a sign-in to read
michael/ProdDash@main — turn off 'require sign-in to view' in Gitea, or
make the repo readable without one". Any other answer that is not a gzip
archive says what came back instead — a web page, or the content type —
and where to look.

tools/update-check.test.js drives the check against a mock forge: the login
redirect, a bare HTML answer, an HTTP error, and a real archive that must
still parse and be offered.

Shell 1.9.3.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

README.md

@@ -325,9 +325,8 @@ below. Nothing is installed without someone clicking.
   session (Start ProdDash.command) and approve the one-time prompt; a server
   started over SSH or by bare launchd silently captures zeros. (Engine
   self-test: `node modules/propresenter-timers/ltc.selftest.js`.)
-- **PCO Plan** — Planning Center Services, as three tiles in the ＋ picker:
+- **PCO Plan** — Planning Center Services, as two tiles in the ＋ picker:
-  **Plan** (the order of service), **Teams** (who is scheduled) and **Song
+  **Plan** (the order of service) and **Teams** (who is scheduled).
-  Key** (the key of the item on screen).
 
   **Plan** shows every
   plan item with its scheduled start time, length, type, song key,
@@ -358,16 +357,6 @@ below. Nothing is installed without someone clicking.
   is switched off, or it has no host — nothing to turn off and nothing to
   explain.
 
-  **Song Key** is one value, as large as the tile allows: the key of the item
-  ProPresenter has live, with the song's name and the next key under it — both
-  switches, as is the colour. When the feed that picks the item is gone the key
-  stays up, faded, and the tile's dot says so rather than pretending to be
-  current.
-
-  Keys are written as notes wherever the module shows one: Planning Center's
-  `Bb` and `F#m` read as B♭ and F♯m, on the Plan tile's item badge and in the
-  Song Key tile alike.
-
   **Teams** shows the same plan's team and position assignments — each team
   as a band of its people, with their photo (fetched through ProdDash, never
   by the browser; initials when Planning Center has none) and a dot for

modules/pco-plan/client.js

@@ -1,8 +1,8 @@
 /* PCO Plan — client part.
 
-   The module presents three tiles and this is the entry for all of them: the
+   The module presents two tiles and this is the entry for both: the Teams
-   Teams tile (picker entry "teams") is built by teams-client.js and the Song
+   tile (picker entry "teams") is built by teams-client.js, everything below
-   Key tile ("key") by key-client.js; everything below draws the Plan tile.
+   draws the Plan tile.
 
    The server part reads Planning Center and (optionally) follows the
    ProPresenter module's live item; this tile only renders the plan it is
@@ -13,8 +13,6 @@
    the connection settings. */
 
 import createTeams from "./teams-client.js";
-import createKey from "./key-client.js";
-import { prettyKey } from "./key-notation.js";
 
 const REFRESH_SVG = '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12a9 9 0 1 1-2.64-6.36"/><path d="M21 3v6h-6"/></svg>';
 
@@ -23,9 +21,8 @@ const MINUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" st
 const PLUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>';
 
 export default function create({ root, moduleApi }) {
-  // Each picker entry carries its variant and its own settings.
+  // Tiles added as "Teams" carry that variant and have their own settings.
   if (moduleApi.variant === "teams") return createTeams({ root, moduleApi });
-  if (moduleApi.variant === "key") return createKey({ root, moduleApi });
   return createPlan({ root, moduleApi });
 }
 
@@ -370,8 +367,7 @@ function createPlan({ root, moduleApi }) {
       if (on('showKey') && item.keyName) {
         const key = document.createElement('span');
         key.className = 'pp-key';
-        // B♭, F♯m — the same notation the Song Key tile uses.
+        key.textContent = item.keyName;
-        key.textContent = prettyKey(item.keyName);
         titleLine.appendChild(key);
       }
       if (on('showNowIndicator')) {

modules/pco-plan/key-client.js

@@ -1,181 +0,0 @@
-/* PCO Plan — the Song Key tile.
-
-   One thing, big: the key of the plan item on screen. It reads the same
-   streamed state the Plan tile does, so it needs no connection of its own;
-   which item is current comes from the ProPresenter module, as ever. */
-
-import { parseKey, prettyKey } from "./key-notation.js";
-
-export default function createKey({ root, moduleApi }) {
-  let state = null;
-  let stream = null;
-  let feedOffline = false;
-
-  root.innerHTML = `
-    <div class="pk-wrap">
-      <div class="pk-key"></div>
-      <div class="pk-name"></div>
-      <div class="pk-next"></div>
-    </div>`;
-
-  const wrap = root.querySelector('.pk-wrap');
-  const keyEl = root.querySelector('.pk-key');
-  const nameEl = root.querySelector('.pk-name');
-  const nextEl = root.querySelector('.pk-next');
-
-  const cfg = () => moduleApi.instanceSettings || {};
-  const on = (key) => cfg()[key] !== false; // unset = shown
-
-  /* ── the item on screen, and the one after it ───────────────────── */
-
-  function items() {
-    return Array.isArray(state?.items) ? state.items : [];
-  }
-
-  function currentItem() {
-    const id = state?.live?.following ? state.live.currentItemId : '';
-    return id ? items().find((it) => it.id === id) || null : null;
-  }
-
-  /** The next item that actually has a key — a talk between two songs is skipped. */
-  function nextKeyed(after) {
-    const list = items();
-    const from = after ? list.findIndex((it) => it.id === after.id) + 1 : 0;
-    if (from <= 0) return null;
-    for (let i = from; i < list.length; i += 1) {
-      if (list[i].keyName) return list[i];
-    }
-    return null;
-  }
-
-  function titleOf(item) {
-    return item ? (item.song?.title || item.title || '') : '';
-  }
-
-  /* ── render ─────────────────────────────────────────────────────── */
-
-  function renderStatus() {
-    if (feedOffline) return moduleApi.setStatus('error', 'ProdDash server unreachable — reconnecting…');
-    if (!state) return moduleApi.setStatus('connecting', 'Connecting…');
-    if (!state.configured) return moduleApi.setStatus('error', 'No Planning Center credentials — add them in Admin');
-    if (!state.serviceTypeSet) return moduleApi.setStatus('error', 'No service type selected — pick one in Admin');
-    if (!state.reachable) {
-      return moduleApi.setStatus(state.lastFetched ? 'error' : 'connecting', state.lastError || 'Reading the plan…');
-    }
-    const item = currentItem();
-    if (!state.live?.following) return moduleApi.setStatus('ok', 'Not following ProPresenter — no item is current');
-    // The key on screen stays — the band still needs it — but a tile must
-    // never look confidently live while the feed that chose it is gone.
-    if (!state.live.available) {
-      return moduleApi.setStatus('error', `${state.live.reason || 'ProPresenter feed unavailable'} — showing the last item`);
-    }
-    if (!state.live.ppReachable) return moduleApi.setStatus('error', 'ProPresenter unreachable — showing the last item');
-    if (!item) return moduleApi.setStatus('ok', 'Waiting for an item to go live');
-    moduleApi.setStatus('ok', `${titleOf(item)}${item.keyName ? ` — ${prettyKey(item.keyName)}` : ' — no key in the plan'}`);
-  }
-
-  /**
-   * A key is a note, so it is worth setting properly: "Bb" and "F#m" read
-   * better with the accidental raised and the minor kept small.
-   */
-  function drawKey(text) {
-    keyEl.innerHTML = '';
-    const parts = parseKey(text);
-    if (!parts) {
-      keyEl.textContent = text;
-      return;
-    }
-    keyEl.appendChild(document.createTextNode(parts.note));
-    if (parts.accidental) {
-      const acc = document.createElement('span');
-      acc.className = 'pk-accidental';
-      acc.textContent = parts.accidental;
-      keyEl.appendChild(acc);
-    }
-    if (parts.quality) {
-      const tail = document.createElement('span');
-      tail.className = 'pk-quality';
-      tail.textContent = parts.quality;
-      keyEl.appendChild(tail);
-    }
-  }
-
-  function render() {
-    wrap.classList.toggle('is-offline', feedOffline);
-    const live = state?.live;
-    wrap.classList.toggle('is-stale', Boolean(live?.following && (!live.available || !live.ppReachable)));
-    const color = String(cfg().keyColor || '').trim();
-    wrap.style.setProperty('--pk-color', /^[#a-zA-Z0-9(),.%\s-]+$/.test(color) && color ? color : '#4ea1ff');
-    renderStatus();
-
-    const item = currentItem();
-    const key = item?.keyName || '';
-    wrap.classList.toggle('has-key', Boolean(key));
-
-    if (!state || !state.configured || !state.serviceTypeSet) {
-      drawKey('—');
-      nameEl.textContent = state ? 'Set up PCO Plan in Admin' : 'Connecting…';
-      nextEl.textContent = '';
-      return;
-    }
-    if (!item) {
-      drawKey('—');
-      nameEl.textContent = state.live?.following ? 'Nothing live' : 'Not following ProPresenter';
-      nextEl.textContent = '';
-      return;
-    }
-
-    drawKey(key || '—');
-    nameEl.textContent = on('showSongName') ? titleOf(item) : '';
-    nameEl.hidden = !nameEl.textContent;
-
-    const next = on('showNextKey') ? nextKeyed(item) : null;
-    nextEl.textContent = next ? `Next: ${prettyKey(next.keyName)} · ${titleOf(next)}` : '';
-    nextEl.hidden = !nextEl.textContent;
-  }
-
-  /* ── live feed ──────────────────────────────────────────────────── */
-
-  function accept(payload) {
-    if (!payload || typeof payload !== 'object' || !payload.state) return;
-    state = payload.state;
-    feedOffline = false;
-    render();
-  }
-
-  function connect() {
-    stream = moduleApi.sse('/stream', {
-      open() { feedOffline = false; render(); },
-      error() { feedOffline = true; render(); },
-      events: {
-        state(ev) {
-          try {
-            accept(JSON.parse(ev.data));
-          } catch { /* a bad frame is not fatal */ }
-        },
-      },
-    });
-  }
-
-  /* ── lifecycle ──────────────────────────────────────────────────── */
-
-  return {
-    start() {
-      moduleApi.setStatus('connecting', 'Connecting…');
-      moduleApi.fetch('/state')
-        .then((res) => (res.ok ? res.json() : null))
-        .then((body) => { if (body && !state) accept(body); })
-        .catch(() => { /* the stream will cover it */ });
-      connect();
-      render();
-    },
-    stop() {
-      stream?.close();
-      stream = null;
-      root.innerHTML = '';
-    },
-    onConfigChange() {
-      // Admin holds the connection only; the server re-inits and re-sends.
-    },
-  };
-}

modules/pco-plan/key-notation.js

@@ -1,25 +0,0 @@
-/* PCO Plan — how a song key is written.
-
-   Planning Center stores keys as typed: "Bb", "F#m", "Ab". Every tile in this
-   module shows them as notes instead — B♭, F♯m, A♭ — so the plan, the badge
-   on an item and the Song Key tile all agree. Shared rather than repeated
-   because the day one of them changes, they all should. */
-
-/** "F#m" → { note: 'F', accidental: '♯', quality: 'm' }; anything odd → null. */
-export function parseKey(raw) {
-  const match = /^([A-G])\s*([#b♯♭]?)\s*(.*)$/.exec(String(raw || '').trim());
-  if (!match) return null;
-  const [, note, accidental, quality] = match;
-  return {
-    note,
-    accidental: accidental === '#' ? '♯' : accidental === 'b' ? '♭' : accidental,
-    quality: quality.trim(),
-  };
-}
-
-/** The same thing as one string, for a badge or a caption. */
-export function prettyKey(raw) {
-  const parts = parseKey(raw);
-  if (!parts) return String(raw || '').trim();
-  return `${parts.note}${parts.accidental}${parts.quality}`;
-}

modules/pco-plan/module.json

@@ -1,9 +1,9 @@
 {
   "id": "pco-plan",
   "name": "PCO Plan",
-  "version": "1.9.0",
+  "version": "1.8.0",
   "proddash": ">=1.4.0",
-  "description": "Order of service, team assignments and the song key from Planning Center Services",
+  "description": "Order of service and team assignments from Planning Center Services",
   "provides": [
     "timers"
   ],
@@ -621,36 +621,6 @@
           "columns": 2
         }
       }
-    },
-    {
-      "id": "key",
-      "name": "Song Key",
-      "description": "The key of the item on screen, big",
-      "defaultSize": {
-        "w": 2,
-        "h": 2
-      },
-      "minSize": {
-        "w": 1,
-        "h": 1
-      },
-      "instanceSchema": {
-        "keyColor": {
-          "type": "color",
-          "label": "Key",
-          "default": "#4ea1ff"
-        },
-        "showSongName": {
-          "type": "boolean",
-          "label": "Song name",
-          "default": true
-        },
-        "showNextKey": {
-          "type": "boolean",
-          "label": "Next key",
-          "default": true
-        }
-      }
     }
   ]
 }

modules/pco-plan/style.css

@@ -206,9 +206,7 @@
 
 [data-module="pco-plan"] .pp-now-tag {
   display: none;
-  /* Optically centred like the section chips: uppercase has no descenders,
+  padding: 0.05em 0.45em;
-     so the capitals sat 0.59px low in the pill. */
-  padding: 0.018em 0.45em 0.082em;
   border-radius: 999px;
   background: var(--pp-current);
   color: var(--bg);
@@ -637,110 +635,25 @@
 
 [data-module="pco-plan"] .pp-abs-sec {
   flex: none;
-  /* Uppercase text has no descenders, so the font's descent allowance below
+  padding: 0.1em 0.5em;
-     the baseline leaves the caps sitting high in the box — measured at 0.9px
+  border-radius: 999px;
-     too much headroom. The padding is a touch shallower on top and deeper
+  border: 1px solid var(--border);
-     below to centre the letters themselves; in em, so it holds at any text
-     size. */
-  padding: 0.095em 0.55em 0.185em;
-  /* The same rounded square, tinted ground and transparent border the AbleSet
-     module gives its own section pills, so the two read as one family. */
-  border-radius: 0.35em;
-  border: 1px solid transparent;
-  background: color-mix(in srgb, var(--text) 8%, var(--panel));
   font-size: 0.72em;
   font-weight: 700;
   letter-spacing: 0.04em;
   text-transform: uppercase;
   white-space: nowrap;
   color: var(--muted);
-  transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+  transition: color 0.2s ease, border-color 0.2s ease;
 }
 [data-module="pco-plan"] .pp-abs-sec.is-done { opacity: 0.45; }
 
 /* The section now playing fills left to right as it goes, like the row. */
-/* The section playing keeps its own ground and fills across it, so the
-   progress reads against the chip rather than against the row behind it. */
 [data-module="pco-plan"] .pp-abs-sec.is-now {
   color: var(--text);
   border-color: color-mix(in srgb, var(--pp-current) 60%, transparent);
   background:
     linear-gradient(90deg,
-      color-mix(in srgb, var(--pp-current) 45%, var(--panel)) var(--pp-sec-fill, 0%),
+      color-mix(in srgb, var(--pp-current) 40%, transparent) var(--pp-sec-fill, 0%),
-      color-mix(in srgb, var(--text) 8%, var(--panel)) var(--pp-sec-fill, 0%));
+      transparent var(--pp-sec-fill, 0%));
 }
-
-/* ── the Song Key tile ────────────────────────────────────────────────
-   One value, as large as the tile allows. Sizes come from the tile itself
-   (container units), like the AbleSet module's single readouts, so a small
-   tile and a wall-sized one both read properly. */
-
-[data-module="pco-plan"] .pk-wrap {
-  --pk-color: #4ea1ff;
-  position: absolute;
-  inset: 0;
-  container-type: size;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 0.2em;
-  padding: 4%;
-  text-align: center;
-  user-select: none;
-}
-
-[data-module="pco-plan"] .pk-key {
-  font-size: clamp(18px, 46cqmin, 260px);
-  font-weight: 800;
-  line-height: 1;
-  letter-spacing: -0.01em;
-  color: var(--muted);
-  white-space: nowrap;
-}
-[data-module="pco-plan"] .pk-wrap.has-key .pk-key { color: var(--pk-color); }
-
-/* A key is a note, but it has to read as one word at a glance from the back
-   of a room: the accidental and the quality sit on the same line as the
-   letter, only smaller. Raising the accidental looked like two stacked
-   characters at tile sizes. */
-[data-module="pco-plan"] .pk-accidental {
-  font-size: 0.68em;
-  margin-left: 0.01em;
-}
-[data-module="pco-plan"] .pk-quality {
-  font-size: 0.5em;
-  font-weight: 700;
-  margin-left: 0.05em;
-  opacity: 0.85;
-}
-
-[data-module="pco-plan"] .pk-name {
-  max-width: 100%;
-  font-size: clamp(9px, 9cqmin, 30px);
-  font-weight: 600;
-  line-height: 1.2;
-  color: var(--text);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-[data-module="pco-plan"] .pk-name[hidden] { display: none; }
-
-[data-module="pco-plan"] .pk-next {
-  max-width: 100%;
-  font-size: clamp(8px, 6.5cqmin, 20px);
-  font-weight: 600;
-  color: var(--muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-[data-module="pco-plan"] .pk-next[hidden] { display: none; }
-
-[data-module="pco-plan"] .pk-wrap.is-offline { opacity: 0.6; }
-/* The feed that picks the item is gone: the key stays readable, but faded,
-   so nobody trusts it as current without looking at the status dot. */
-[data-module="pco-plan"] .pk-wrap.is-stale .pk-key { opacity: 0.55; }
-[data-module="pco-plan"] .pk-wrap.is-stale .pk-name,
-[data-module="pco-plan"] .pk-wrap.is-stale .pk-next { opacity: 0.6; }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "proddash",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "private": true,
   "description": "Modular production dashboard for Waters Church \u2014 zero-dependency Node server + vanilla client",
   "license": "UNLICENSED",

server.js

@@ -910,9 +910,21 @@ async function fetchArchive() {
     signal: AbortSignal.timeout(30000),
     headers: { 'User-Agent': `ProdDash/${SHELL_VERSION}` },
   });
-  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${REPO.owner}/${REPO.repo}@${REPO.branch}`);
+  const where = `${REPO.owner}/${REPO.repo}@${REPO.branch}`;
+  // A forge that wants a sign-in does not refuse: it redirects the download
+  // to its login page, which arrives as a 200 of HTML. Say that, not
+  // zlib's "incorrect header check".
+  if (res.redirected && /\/user\/login\b|\/login\b/.test(new URL(res.url).pathname)) {
+    throw new Error(`${FORGE.base} requires a sign-in to read ${where} — turn off "require sign-in to view" in Gitea, or make the repo readable without one`);
+  }
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${where}`);
   const gz = Buffer.from(await res.arrayBuffer());
   if (gz.length > MAX_ARCHIVE_BYTES) throw new Error('archive is unexpectedly large');
+  if (gz.length < 2 || gz[0] !== 0x1f || gz[1] !== 0x8b) {
+    const type = String(res.headers.get('content-type') || 'unknown type').split(';')[0].trim();
+    const looksHtml = /^\s*<(!doctype|html)/i.test(gz.subarray(0, 64).toString('utf8'));
+    throw new Error(`${FORGE.base} answered with ${looksHtml ? 'a web page' : type} instead of the ${where} archive — check the forge address and that the repo is readable without a sign-in`);
+  }
   const { files, comment } = parseTar(zlib.gunzipSync(gz));
   const stripped = new Map(); // drop the archive's single top-level folder
   for (const [p, data] of files) {

tools/update-check.test.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * The update check against a forge that misbehaves: the admin page must say
+ * what went wrong in words, never zlib's "incorrect header check".
+ *
+ *   node tools/update-check.test.js
+ *
+ * Plain Node, no dependencies. Starts a mock forge whose answer to the
+ * branch-archive download can be switched at runtime, starts server.js on a
+ * spare port pointed at it, and reads the shell status the admin page shows
+ * after each kind of answer:
+ *
+ *   - a Gitea that requires a sign-in redirects the download to its login
+ *     page (a 200 of HTML) — the case that hit both booths on 2026-09-29;
+ *   - a captive portal or a wrong address answers HTML outright;
+ *   - a plain HTTP error;
+ *   - and a real archive, which must still parse and offer the update.
+ *
+ * Exits non-zero on the first failure and always stops what it started.
+ */
+
+const assert = require('node:assert/strict');
+const { spawn, execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+    probe.on('error', reject);
+  });
+}
+
+async function waitFor(url, ms = 15000) {
+  const deadline = Date.now() + ms;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return;
+      last = 'HTTP ' + r.status;
+    } catch (err) {
+      last = err.message;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error('server did not come up: ' + last);
+}
+
+/** A branch archive the way a forge would build one: one top-level folder. */
+function buildArchive(dir) {
+  const top = path.join(dir, 'ProdDash-main');
+  fs.mkdirSync(path.join(top, 'modules', 'demo'), { recursive: true });
+  fs.writeFileSync(path.join(top, 'package.json'), JSON.stringify({ name: 'proddash', version: '9.9.9' }));
+  fs.writeFileSync(path.join(top, 'modules', 'demo', 'module.json'), JSON.stringify({ id: 'demo', name: 'Demo', version: '1.0.0', client: 'client.js' }));
+  fs.writeFileSync(path.join(top, 'modules', 'demo', 'client.js'), 'export default function () {}\n');
+  const out = path.join(dir, 'main.tar.gz');
+  execFileSync('tar', ['-czf', out, '-C', dir, 'ProdDash-main']);
+  return fs.readFileSync(out);
+}
+
+(async () => {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'proddash-update-test-'));
+  const dataDir = path.join(work, 'data');
+  fs.mkdirSync(dataDir);
+  const archive = buildArchive(path.join(work, 'forge'));
+
+  // ── the mock forge ──
+  let mode = 'ok';
+  const LOGIN_PAGE = '<!DOCTYPE html>\n<html><head><title>Sign in</title></head><body>Sign in to continue</body></html>';
+  const forge = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://forge.invalid');
+    if (url.pathname === '/user/login') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      return res.end(LOGIN_PAGE);
+    }
+    if (url.pathname !== '/michael/ProdDash/archive/main.tar.gz') {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('not here');
+    }
+    switch (mode) {
+      case 'login-redirect':
+        res.writeHead(303, { Location: '/user/login?redirect_to=' + encodeURIComponent(url.pathname) });
+        return res.end();
+      case 'html':
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        return res.end('<html><body>You must log in to this network first</body></html>');
+      case 'notfound':
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        return res.end('no such branch');
+      default:
+        res.writeHead(200, { 'Content-Type': 'application/gzip' });
+        return res.end(archive);
+    }
+  });
+  const forgePort = await freePort();
+  await new Promise((r) => forge.listen(forgePort, '127.0.0.1', r));
+  const forgeBase = `http://127.0.0.1:${forgePort}`;
+
+  // ── ProdDash, pointed at it ──
+  const port = await freePort();
+  const child = spawn(process.execPath, ['server.js'], {
+    cwd: ROOT,
+    env: {
+      ...process.env,
+      PRODDASH_DATA_DIR: dataDir,
+      PORT: String(port),
+      PRODDASH_FORGE: forgeBase,
+      PRODDASH_REPO: 'michael/ProdDash',
+      PRODDASH_NO_REMOTE_CHECK: '1',
+      PRODDASH_LAUNCHER: '1',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let log = '';
+  child.stdout.on('data', (d) => { log += d; });
+  child.stderr.on('data', (d) => { log += d; });
+  const base = `http://127.0.0.1:${port}`;
+
+  /** What the admin page shows after a forced check. Admin is open: a fresh data dir has no PIN. */
+  const check = async (m) => {
+    mode = m;
+    const r = await fetch(base + '/api/admin/catalog?refresh=1');
+    assert.equal(r.status, 200, `catalog: HTTP ${r.status}`);
+    const body = await r.json();
+    return body.shell;
+  };
+
+  let failed = false;
+  try {
+    await waitFor(base + '/api/theme');
+
+    let shell = await check('login-redirect');
+    assert.match(shell.remote.error, /requires a sign-in/, 'a login redirect is named as such: ' + shell.remote.error);
+    assert.match(shell.remote.error, /require sign-in to view/, 'and the Gitea setting to look at is named');
+    assert.doesNotMatch(shell.remote.error, /header check/, 'never zlib\'s words');
+    assert.equal(shell.updateAvailable, false);
+
+    shell = await check('html');
+    assert.match(shell.remote.error, /answered with a web page instead of the michael\/ProdDash@main archive/, shell.remote.error);
+
+    shell = await check('notfound');
+    assert.match(shell.remote.error, /HTTP 404 fetching michael\/ProdDash@main/, shell.remote.error);
+
+    shell = await check('ok');
+    assert.equal(shell.remote.error, '', 'a real archive clears the error: ' + shell.remote.error);
+    assert.equal(shell.remote.version, '9.9.9', 'and is read');
+    assert.equal(shell.updateAvailable, true, 'and offered');
+
+    // Back to a broken forge: the last good read is not mistaken for a current one.
+    shell = await check('login-redirect');
+    assert.match(shell.remote.error, /requires a sign-in/);
+
+    console.log('update check: every check passed');
+  } catch (err) {
+    failed = true;
+    console.error('FAIL:', err.message);
+    console.error('--- last of the server log ---\n' + log.slice(-2000));
+  } finally {
+    child.kill('SIGTERM');
+    forge.close();
+    await new Promise((r) => setTimeout(r, 400));
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+  process.exit(failed ? 1 : 0);
+})();