@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/baseline-staleness.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// scripts/bongos/baseline-staleness.js — the freeze-forever detector (task 1003210,
+// goal 1000079; docs/audits/ai-dev-redteam-followup.md §9 item 2).
+//
+// THE PROBLEM. `config/fitness-baselines.json` is a SHRINK-ONLY ratchet: a metric
+// may never exceed its baseline, and lowering one is how debt gets paid down. That
+// makes regression impossible — and makes standing still invisible. The follow-up
+// audit measured the whole file at "every metric equal to baseline, 0 reduced" and
+// named the consequence exactly:
+//
+//     "A shrink-only baseline that never shrinks is indistinguishable from
+//      unmanaged debt."
+//
+// The ratchet is GREEN in that state. It is green in the state where the team is
+// actively paying down, and equally green in the state where nobody has looked in
+// a year. This check separates them by adding the one axis the ratchet has no
+// concept of: TIME.
+//
+// WHY A DECLARED FLOOR IS THE HALF THAT MATTERS. The naive version — "flag every
+// baseline that hasn't moved in N weeks" — fires on metrics that are *finished*.
+// `require_cycle_count: 4` is four deliberate lazy requires with written rationale;
+// `duplicate_window_count` cannot go below ~28 because that much duplication is
+// forced by the module boundary (ADR 0091 §2). Those will never move again, and a
+// check that nags about them weekly is a check everyone learns to skip — the same
+// alert-fatigue failure ADR 0188 §2.4 avoids in the patrol.
+//
+// So a metric may declare a FLOOR with a written reason, and a metric at its floor
+// is DONE, not stale. That converts "this is frozen forever" from silence into an
+// explicit, reviewable claim — which is the actual goal. Silence was the problem.
+//
+// TWO CHECKS, TWO SEVERITIES, ON PURPOSE:
+//
+//   • Floor-declaration rot is HERMETIC and HARD-FAILS. A floor naming a metric
+//     that no longer exists, a floor with no reason, or a floor ABOVE the metric's
+//     current value (the metric improved past the claim and nobody revisited it)
+//     are all defects in the declaration itself — cheap to detect, caused by the
+//     diff at hand, and exactly what a merge gate is for.
+//
+//   • Staleness WARNS, and is filed weekly by the patrol. Age is not a property of
+//     anybody's diff. Hard-failing a PR because ambient debt turned eight weeks old
+//     punishes whoever pushed next and gets the gate disabled. The audit asked for
+//     "the repeatable, SCHEDULED version" of its own manual review, and the patrol
+//     is that: history-wide, time-based, filed for adjudication (ADR 0158 §2).
+//
+// AGE COMES FROM GIT, NOT FROM A STORED TIMESTAMP. A `since:` field in the JSON
+// would be faster and hermetic, and it would also be the thing that silently
+// stops being updated — leaving old debt looking permanently fresh, which is a
+// worse failure than no check at all. Git history cannot be forgotten. When it is
+// unavailable (a shallow clone), this reports DID-NOT-RUN rather than a clean
+// green: the main-audit.js --require-roster doctrine.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASELINE_REL = 'config/fitness-baselines.json';
+
+// Eight weeks. Long enough that a metric someone is actively working is never
+// flagged, short enough that "we'll get to it" cannot quietly become "never".
+const DEFAULT_MAX_AGE_DAYS = Number(process.env.BASELINE_STALE_DAYS) || 56;
+const DAY_MS = 86400000;
+
+// Read the tracked file's value at every commit that touched it, newest first.
+// Committer date, not author date: the question is how long this value has been
+// LANDED, and a rebased author date answers a different one. Returns null when
+// git or the history is unavailable — the caller must treat that as did-not-run.
+function readHistory(rel = BASELINE_REL, { cwd = ROOT, exec = execFileSync } = {}) {
+  let lines;
+  try {
+    lines = exec('git', ['log', '--format=%H|%cI', '--', rel], { cwd, encoding: 'utf8', stdio: 'pipe' })
+      .trim().split('\n').filter(Boolean);
+  } catch (_) {
+    return null;
+  }
+  if (!lines.length) return null;
+  const out = [];
+  for (const line of lines) {
+    const [sha, date] = line.split('|');
+    let parsed;
+    try { parsed = JSON.parse(exec('git', ['show', `${sha}:${rel}`], { cwd, encoding: 'utf8', stdio: 'pipe' })); }
+    catch (_) { continue; } // a commit that deleted/renamed the file — skip, don't guess
+    out.push({ sha, date, metrics: (parsed && parsed.metrics) || {} });
+  }
+  return out.length ? out : null;
+}
+
+// Pure: the ISO date at which each metric's CURRENT value was first set. Walks
+// newest→oldest while the value is unchanged; the oldest commit still carrying it
+// is when it last moved. A metric absent from an older commit was introduced at
+// the one after it, and its introduction date IS its age — a baseline recorded
+// once and never revisited is precisely what this looks for.
+function lastChangedByMetric(history) {
+  const out = {};
+  if (!history || !history.length) return out;
+  for (const [name, value] of Object.entries(history[0].metrics)) {
+    let i = 0;
+    while (i + 1 < history.length && history[i + 1].metrics[name] === value) i += 1;
+    out[name] = history[i].date;
+  }
+  return out;
+}
+
+function ageDays(iso, now) {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? (now - t) / DAY_MS : null;
+}
+
+// Pure verdict — exported for the hermetic test.
+//
+// `floors[name]` is `{ value, why }`. An undeclared metric floors at 0, so a
+// metric already at 0 is never stale: it cannot shrink and there is nothing to
+// declare. `lastChanged === null` (no history) is reported as unknown, never as
+// fresh — an unmeasurable age must not read as a passing one.
+function evaluate({ metrics = {}, floors = {}, lastChanged = {}, now = 0, maxAgeDays = DEFAULT_MAX_AGE_DAYS } = {}) {
+  const violations = [];
+  const stale = [];
+  const atFloor = [];  // exempt by a WRITTEN floor claim
+  const atZero = [];   // exempt because there is nothing left to reduce
+
+  for (const [name, spec] of Object.entries(floors)) {
+    if (!(name in metrics)) {
+      violations.push(`floor declared for "${name}", which is not a metric in ${BASELINE_REL} — remove the floor or restore the metric`);
+      continue;
+    }
+    const value = spec && typeof spec === 'object' ? spec.value : spec;
+    const why = spec && typeof spec === 'object' ? spec.why : null;
+    if (!Number.isFinite(value)) {
+      violations.push(`floor for "${name}" has no numeric value — a floor is a claim about what cannot be reduced, so it must be a number`);
+      continue;
+    }
+    if (!why || String(why).trim().length < 20) {
+      violations.push(`floor for "${name}" has no reason — a floor exempts a metric from staleness forever, so it must say WHY it cannot go lower`);
+    }
+    if (metrics[name] < value) {
+      violations.push(`floor for "${name}" is ${value} but the metric is already ${metrics[name]} — the floor was passed and never revisited; lower it to the real limit`);
+    }
+  }
+
+  for (const [name, value] of Object.entries(metrics)) {
+    if (value === null || value === undefined) continue;
+    const spec = floors[name];
+    const floor = spec && typeof spec === 'object' ? spec.value : (Number.isFinite(spec) ? spec : 0);
+    if (value <= floor) { (floor > 0 ? atFloor : atZero).push(name); continue; }
+    const since = lastChanged[name];
+    if (!since) { stale.push({ name, value, floor, days: null, since: null }); continue; }
+    const days = ageDays(since, now);
+    if (days !== null && days > maxAgeDays) stale.push({ name, value, floor, days, since });
+  }
+  return { violations, stale, atFloor, atZero };
+}
+
+function readBaselineFile(rel = BASELINE_REL) {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8')) || {}; }
+  catch (_) { return {}; }
+}
+
+// One line per stale metric, in the voice the reader needs: what it is, how long
+// it has not moved, and the two legitimate ways out (reduce it, or declare a floor
+// saying why it cannot be reduced). "Do something" beats "something is wrong".
+function describe(s) {
+  const age = s.days === null ? 'age UNKNOWN (no git history here)' : `unchanged for ${Math.floor(s.days)} days`;
+  return `${s.name}=${s.value} ${age}${s.floor ? ` (floor ${s.floor})` : ''} — reduce it, or declare a floor in ${BASELINE_REL} saying why it cannot go lower`;
+}
+
+function run({ now = Date.now(), maxAgeDays = DEFAULT_MAX_AGE_DAYS } = {}) {
+  const file = readBaselineFile();
+  const history = readHistory();
+  const lastChanged = history ? lastChangedByMetric(history) : {};
+  const r = evaluate({ metrics: file.metrics || {}, floors: file.floors || {}, lastChanged, now, maxAgeDays });
+  return { ...r, historyAvailable: history !== null, maxAgeDays };
+}
+
+// The fitness.js check. Hard-fails ONLY on floor-declaration rot (hermetic, caused
+// by the diff at hand); staleness is a warning here and a filed report in the
+// weekly patrol — see the header.
+function checkBaselineFloors() {
+  const r = run();
+  const warnings = r.stale.map(describe);
+  if (!r.historyAvailable) {
+    warnings.push(`baseline age could not be measured — no git history for ${BASELINE_REL} here (shallow clone?). Reported as unknown rather than passing.`);
+  }
+  return {
+    name: 'a shrink-only baseline cannot silently freeze forever (task 1003210)',
+    ok: r.violations.length === 0,
+    hardFail: r.violations.length > 0,
+    violations: r.violations,
+    warnings,
+    note: `${Object.keys(readBaselineFile().metrics || {}).length} baseline(s): ${r.atZero.length} at zero, ${r.atFloor.length} at a declared floor (done), ${r.stale.length} unchanged for >${r.maxAgeDays}d. A floor must name a reason; age comes from git, never a stored timestamp.`,
+  };
+}
+
+// The patrol class (ADR 0188): the SCHEDULED version of the audit's manual review.
+// Severity is low — this is a prompt to look, not a defect. Returns [] when there
+// is nothing to say, so the patrol files no report on a healthy week.
+function stalenessFindings(opts = {}) {
+  const r = run(opts);
+  return r.stale.map((s) => ({ severity: 'low', item: describe(s) }));
+}
+
+function main() {
+  const r = run();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  for (const w of r.stale.map(describe)) console.warn(`⚠ ${w}`);
+  if (!r.historyAvailable) console.warn('⚠ no git history for the baseline file — age is UNKNOWN, not fresh');
+  console.log(`${r.violations.length ? 'FAIL' : 'PASS'}  ${r.atZero.length} at zero · ${r.atFloor.length} at a declared floor · ${r.stale.length} stale (>${r.maxAgeDays}d)`);
+  process.exit(r.violations.length ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkBaselineFloors, stalenessFindings, evaluate, lastChangedByMetric,
+  readHistory, run, describe, DEFAULT_MAX_AGE_DAYS, BASELINE_REL,
+};

package/scripts/bongos/bfg-principal-token.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Mint (or rotate) a session token for the BFG service principal so the 6C.2
+// routine can authenticate AS the principal to call the cross-builder write
+// endpoint (ADR 0026 §6C). Archon-run, on a box with DATABASE_URL (the droplet).
+//
+// Why a dedicated token (not the operator's Archon session): the write endpoint
+// gates on the EXACT principal identity (system_role='bfg'), and an Archon token
+// is deliberately rejected there. So the routine needs the principal's OWN
+// token. This is the one privileged bootstrap; it lives outside any self-serve
+// route (you must have DB access to run it), which is what keeps "an Archon
+// can't act as the BFG" true.
+//
+// The token is written to ~/.config/otb/bfg-principal.json (0600). The routine
+// reads it and sends `Authorization: Bearer <token>`. Re-running mints a fresh
+// token (the old one keeps working until revoked via /auth/revoke); rotate by
+// re-running then revoking the prior session id.
+//
+//   node scripts/bongos/bfg-principal-token.js          # mint + write the file
+//   node scripts/bongos/bfg-principal-token.js --print  # also echo the token to stdout
+//
+// NOTE: the write path stays DISABLED until BFG_WRITE_ENABLED=true in the
+// server env (the kill-switch, 6C.1) — minting a token does NOT enable writes.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pool } = require('../../src/bongos/pool');
+const { createSession } = require('../../src/bongos/db');
+
+async function main() {
+  const printToken = process.argv.includes('--print');
+  const { rows } = await pool.query(`SELECT id, github_login FROM builders WHERE system_role = 'bfg'`);
+  if (!rows[0]) {
+    console.error("No BFG principal found (system_role='bfg'). Apply migration 065 first, then re-run.");
+    process.exitCode = 1;
+    return;
+  }
+  const principal = rows[0];
+  const token = crypto.randomBytes(32).toString('hex'); // matches the extractToken [a-zA-Z0-9] shape
+  // No-expiry CLI-shaped session (like the operator's CLI token); revocable.
+  await createSession({ builderId: principal.id, token, source: 'cli', userAgent: 'bfg-principal-provision', expiresAt: null });
+
+  const dir = require('../../src/instance-config').configHome();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'bfg-principal.json');
+  fs.writeFileSync(
+    file,
+    JSON.stringify({ token, builder_id: principal.id, github_login: principal.github_login, minted_at: new Date().toISOString() }, null, 2),
+    { mode: 0o600 }
+  );
+  fs.chmodSync(file, 0o600); // ensure 0600 even if the file pre-existed
+
+  console.log(`Minted BFG principal session for builder #${principal.id} (${principal.github_login}).`);
+  console.log(`Wrote ${file} (0600). The 6C.2 routine reads its token from there.`);
+  console.log('Reminder: writes stay OFF until BFG_WRITE_ENABLED=true in the server env (the 6C.1 kill-switch).');
+  if (printToken) console.log(`token: ${token}`);
+}
+
+main()
+  .catch((err) => {
+    console.error('bfg-principal-token failed:', err && err.message ? err.message : err);
+    process.exitCode = 1;
+  })
+  .finally(() => pool.end().catch(() => {}));

package/scripts/bongos/bug-attachment-audit.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// scripts/bongos/bug-attachment-audit.js — do the images our task descriptions
+// promise actually exist? (task 1003918)
+//
+// WHY THIS EXISTS. A re-hosted #bugs screenshot is the hardest artefact in this
+// system to get back: the Discord CDN URL it was copied from carries a signature
+// that expires in about a day. The FILE does not expire — Discord keeps it while
+// the message exists, and bug-attachment-recover.js re-fetches it by the message
+// id the filename carries (task 1004667) — but once that message or the channel
+// history is gone, our copy IS the image. They live on disk
+// under var/bug-attachments — outside Postgres, outside git — and nothing
+// noticed when all five this instance had ever stored disappeared in the
+// 2026-07-05 droplet move. The loss surfaced on 2026-09-14, two months later,
+// because somebody happened to open an old bug task and saw a broken image.
+//
+// So: read the descriptions, extract every attachment link they promise, and ask
+// the disk whether it can keep that promise. A count of broken promises is the
+// thing that should have been non-zero and visible in July.
+//
+// Usage:
+//   node scripts/bongos/bug-attachment-audit.js          # human report; exit 1 if any are missing
+//   node scripts/bongos/bug-attachment-audit.js --json   # { described, present, missing: [...] }
+//   node scripts/bongos/bug-attachment-audit.js --line   # one line, or nothing; always exit 0
+//
+// Read-only. It never writes, never deletes, and never touches Discord.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The link shape the bot embeds in a description. Deliberately matched against
+// the SERVE ROUTE's path rather than any filename found on disk: what matters is
+// what a reader will click, and a file nothing links to is not a broken promise.
+const LINK_RE = /\/api\/(?:gds|bongos)\/bug-attachments\/(bug-[a-z0-9]{1,40}-[0-9a-f]{16}\.(?:png|jpg|gif|webp))/gi;
+
+// PURE — every attachment name a body of text promises, deduped, in first-seen
+// order. Exported so the extraction is testable without a database or a disk.
+function describedAttachments(text) {
+  const out = [];
+  const seen = new Set();
+  for (const m of String(text || '').matchAll(LINK_RE)) {
+    const name = m[1];
+    if (!seen.has(name)) { seen.add(name); out.push(name); }
+  }
+  return out;
+}
+
+// PURE — split the promised names into kept and broken, given an existence test.
+// `rows` are { id, title, description }; the result names the TASK for each
+// missing file, because "three files are gone" is not actionable and "the image
+// in task N is gone" is.
+function auditRows(rows, exists) {
+  const described = [];
+  const missing = [];
+  for (const row of rows || []) {
+    for (const name of describedAttachments(row && row.description)) {
+      described.push({ name, taskId: row.id });
+      if (!exists(name)) missing.push({ name, taskId: row.id, title: row.title || '' });
+    }
+  }
+  return { described, missing, present: described.length - missing.length };
+}
+
+// EVERY status, explicitly, and paged. Two ways to get a comfortable zero here,
+// both of which I hit while building this:
+//
+//   - GET /tasks omits abandoned rows unless you ask for them. The five files this
+//     audit exists for are described in tasks that are now abandoned or shipped, so
+//     the obvious query returned '0 linked, 0 missing' — indistinguishable from
+//     'nothing is broken'.
+//   - the route clamps `limit`, so one page is not the table.
+//
+// A probe whose failure mode is a clean bill of health is worse than no probe, so
+// the status list is spelled out rather than defaulted.
+// 'claimed' is not one — claimTask sets status='active' (db-claims.js). Listing it
+// only bought a no-op query, and a comment promising EVERY status should be right.
+const TASK_STATUSES = ['backlog', 'ready', 'active', 'completed', 'confirmed', 'shipped', 'abandoned'];
+
+async function fetchRows() {
+  const { cliClient } = require('./cli-lib');
+  const { TASK_LIST_MAX_LIMIT, buildTaskPageQuery } = require('../../modules/lifecycle/task-list-limits.js');
+  const api = await cliClient();
+  const byId = new Map();
+  for (const status of TASK_STATUSES) {
+    let offset = 0;
+    for (let page = 0; page < 100; page++) {
+      const q = buildTaskPageQuery({ kind: 'bug', status, limit: TASK_LIST_MAX_LIMIT, offset });
+      const r = await api.tasks.getTasks({ query: q });
+      if (!r || !r.ok) throw new Error(`could not list ${status} tasks (${r && r.status})`);
+      const rows = (r.data && r.data.tasks) || [];
+      for (const t of rows) byId.set(String(t.id), t);
+      // A short page is the end. Compare against the limit the route HONOURED.
+      if (rows.length < q.limit) break;
+      offset += q.limit;
+    }
+  }
+  return [...byId.values()];
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const dir = require('../../modules/discord/bug-attachments.js').attachmentsDir();
+  let rows;
+  try {
+    rows = await fetchRows();
+  } catch (e) {
+    if (argv.includes('--line')) process.exit(0); // a probe never blocks a session
+    console.error(`bug-attachment-audit: undetermined — ${e.message || e}`);
+    process.exit(2);
+  }
+  // Through the serve route's OWN resolver, not a bare path.join. The name pattern
+  // already excludes slashes and dots, and a test pins that '../../etc/passwd' is
+  // never extracted — but the route that actually opens these files defends itself
+  // with a resolved-path prefix check, and a probe that reads the same store should
+  // not hold itself to a weaker rule than the thing it audits.
+  const { resolveSafe } = require('../../modules/discord/bug-attachments.js');
+  const r = auditRows(rows, (name) => {
+    const p = resolveSafe(name);
+    return Boolean(p) && fs.existsSync(p);
+  });
+
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify({ dir, described: r.described.length, present: r.present, missing: r.missing }, null, 2));
+    return;
+  }
+  if (argv.includes('--line')) {
+    if (r.missing.length) {
+      console.log(`Bug attachments: ${r.missing.length} of ${r.described.length} linked screenshot(s) are MISSING from ${dir} `
+        + '— every task describing one renders a broken image. '
+        + 'Try node scripts/bongos/bug-attachment-recover.js --missing (it re-fetches from the original Discord message while that message still exists).');
+    }
+    return;
+  }
+  console.log(`  Bug attachments: ${r.described.length} linked, ${r.present} present, ${r.missing.length} missing`);
+  console.log(`  Store: ${dir}`);
+  for (const m of r.missing) console.log(`    missing  ${m.name}  (task ${m.taskId})`);
+  if (r.missing.length) {
+    console.log('  The stored Discord URL has expired, but only its signature: the message usually still holds the file,');
+    console.log('  and each filename carries its message id. Re-fetch them to their original names with:');
+    console.log('    node scripts/bongos/bug-attachment-recover.js --missing');
+    console.log('  If the message is gone, restore from a nightly attachments archive: /var/backups/gds/<db>-attachments-*.tar.gz');
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { describedAttachments, auditRows, fetchRows, LINK_RE };

package/scripts/bongos/bug-attachment-recover.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// scripts/bongos/bug-attachment-recover.js — re-fetch a lost #bugs screenshot from
+// the Discord message it came from, back to its ORIGINAL filename (task 1004667).
+//
+// WHY THIS EXISTS. We used to say a lost re-hosted screenshot "cannot be
+// re-fetched — the Discord CDN URL has expired". Only the URL's signature
+// (`?ex=&is=&hm=`) expires. Discord keeps the attachment for as long as its
+// message exists, and GET /channels/{channel}/messages/{message} with the bot
+// token hands back a freshly-signed URL. Every stored filename already carries
+// the message id — discord-bot.js passes msg.id into `bug-<id>-<rand>.<ext>`,
+// and a numeric snowflake survives the slug filter unchanged — so every "lost"
+// file is still addressable. That false claim is what steered task 1003980 to
+// "accept the loss" without anyone trying this.
+//
+// The file is written under the name the task description ALREADY links. A
+// fresh random name would store the bytes and leave the task's image broken.
+// The download itself goes through persistImageFromUrl — same host allowlist,
+// redirect re-validation, magic-byte sniff and size cap — with only the target
+// name supplied; there is no second download path here.
+//
+// Usage (on the box that holds the store and the bot token):
+//   node scripts/bongos/bug-attachment-recover.js --missing            # every file the audit finds missing
+//   node scripts/bongos/bug-attachment-recover.js <message-id>...      # the missing files from those messages
+//   node scripts/bongos/bug-attachment-recover.js <filename>...        # exactly these names (no task lookup)
+//   flags: --channel <id>  (default DISCORD_BUGS_CHANNEL_ID, then bugs_channel_id in discord-bot.json)
+//          --dry-run       (say what would be fetched; write nothing)
+//
+// Matching. A message's k-th described file (in the order the task description
+// links them, which is the order the bot stored them) is fetched from that
+// message's k-th image attachment. Never overwrites a file that is present.
+// Exit 0 when everything asked for is recovered (or nothing was missing), 1 when
+// anything could not be, 2 when it could not even start (no token, no channel).
+
+'use strict';
+
+const fs = require('node:fs');
+
+const DISCORD_API = 'https://discord.com/api/v10';
+// A Discord snowflake: digits only. Checked before either id goes into a URL.
+const SNOWFLAKE_RE = /^\d{15,25}$/;
+const NAME_RE = /^bug-([a-z0-9]{1,40})-[0-9a-f]{16}\.(?:png|jpg|gif|webp)$/;
+
+// PURE — the message id a stored filename carries, or null when the slug is not
+// a snowflake (a name stored with the 'x' fallback, or a hand-made one).
+function messageIdFromName(name) {
+  const m = NAME_RE.exec(String(name || ''));
+  return m && SNOWFLAKE_RE.test(m[1]) ? m[1] : null;
+}
+
+// PURE — group filenames by the message they came from, keeping order within a
+// message (that order is what pairs a name with an attachment). Names with no
+// recoverable message id come back in `unaddressable`.
+function planRecovery(names) {
+  const byMessage = new Map();
+  const unaddressable = [];
+  const seen = new Set();
+  for (const name of names || []) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const id = messageIdFromName(name);
+    if (!id) { unaddressable.push(name); continue; }
+    if (!byMessage.has(id)) byMessage.set(id, []);
+    byMessage.get(id).push(name);
+  }
+  return { byMessage, unaddressable };
+}
+
+// PURE — the image attachments of a Discord REST message, in order. The same
+// test the bot applied when it first stored them (discord-bot.js
+// extractImageUrls): an image content type, or a width (Discord sets one only
+// on images). REST returns snake_case `content_type`.
+function imageAttachmentUrls(message) {
+  const out = [];
+  for (const a of (message && message.attachments) || []) {
+    const type = a.content_type || a.contentType || '';
+    if ((type.startsWith('image/') || a.width != null) && a.url) out.push(a.url);
+  }
+  return out;
+}
+
+// Fetch one message and re-host its images under the given names. Returns one
+// { name, ok, reason? } per name; never throws for an expected refusal.
+async function recoverMessage({ channelId, messageId, names, token, fetchImpl = globalThis.fetch, dir, persist }) {
+  if (!SNOWFLAKE_RE.test(String(channelId)) || !SNOWFLAKE_RE.test(String(messageId))) {
+    return names.map((name) => ({ name, ok: false, reason: 'bad_id' }));
+  }
+  let resp;
+  try {
+    resp = await fetchImpl(`${DISCORD_API}/channels/${channelId}/messages/${messageId}`, {
+      headers: { Authorization: `Bot ${token}` },
+    });
+  } catch (e) {
+    return names.map((name) => ({ name, ok: false, reason: 'fetch_failed', error: e.message }));
+  }
+  if (!resp || !resp.ok) {
+    // 404 is the case that ends recovery: the message (or the channel) is gone.
+    const reason = resp && resp.status === 404 ? 'message_gone' : `discord_status_${resp && resp.status}`;
+    return names.map((name) => ({ name, ok: false, reason }));
+  }
+  const urls = imageAttachmentUrls(await resp.json());
+  const results = [];
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i];
+    if (!urls[i]) { results.push({ name, ok: false, reason: 'no_attachment_at_index', index: i, images: urls.length }); continue; }
+    const r = await persist(urls[i], { file: name, fetchImpl, dir });
+    results.push(r.ok ? { name, ok: true, bytes: r.bytes } : { name, ok: false, reason: r.reason });
+  }
+  return results;
+}
+
+function argValue(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
+}
+
+function loadChannelId(argv) {
+  const flag = argValue(argv, '--channel');
+  if (flag) return flag;
+  if (process.env.DISCORD_BUGS_CHANNEL_ID) return process.env.DISCORD_BUGS_CHANNEL_ID;
+  try {
+    const raw = require('../../src/module-api').readConfigFileSync('discord-bot.json');
+    const cfg = raw ? JSON.parse(raw) : null;
+    if (cfg && cfg.bugs_channel_id) return String(cfg.bugs_channel_id);
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const dryRun = argv.includes('--dry-run');
+  const channelArg = argValue(argv, '--channel');
+  const positional = argv.filter((a) => !a.startsWith('--') && a !== channelArg);
+  const at = require('../../modules/discord/bug-attachments.js');
+
+  // Which names to recover. Explicit filenames need no task lookup; --missing
+  // and message ids need the audit's list of described-but-missing files.
+  let names = positional.filter((a) => NAME_RE.test(a));
+  const ids = positional.filter((a) => SNOWFLAKE_RE.test(a));
+  const junk = positional.filter((a) => !NAME_RE.test(a) && !SNOWFLAKE_RE.test(a));
+  if (junk.length) { console.error(`bug-attachment-recover: not a filename or message id: ${junk.join(', ')}`); process.exitCode = 2; return; }
+  if (argv.includes('--missing') || ids.length) {
+    const audit = require('./bug-attachment-audit.js');
+    const r = audit.auditRows(await audit.fetchRows(), (name) => {
+      const p = at.resolveSafe(name);
+      return Boolean(p) && fs.existsSync(p);
+    });
+    const missing = r.missing.map((m) => m.name);
+    if (argv.includes('--missing')) names.push(...missing);
+    for (const id of ids) {
+      const mine = missing.filter((n) => messageIdFromName(n) === id);
+      if (!mine.length) console.log(`  message ${id}: no missing file names it`);
+      names.push(...mine);
+    }
+  }
+  if (!positional.length && !argv.includes('--missing')) {
+    console.error('usage: bug-attachment-recover.js --missing | <message-id>... | <filename>... [--channel <id>] [--dry-run]');
+    process.exitCode = 2;
+    return;
+  }
+
+  const { byMessage, unaddressable } = planRecovery(names);
+  for (const n of unaddressable) console.log(`  skip     ${n}  (its name carries no Discord message id)`);
+  if (!byMessage.size) {
+    console.log('  Nothing to recover.');
+    if (unaddressable.length) process.exitCode = 1;
+    return;
+  }
+
+  const channelId = loadChannelId(argv);
+  if (!channelId) { console.error('bug-attachment-recover: no #bugs channel id — pass --channel or set DISCORD_BUGS_CHANNEL_ID'); process.exitCode = 2; return; }
+  if (dryRun) {
+    for (const [id, list] of byMessage) for (const n of list) console.log(`  would fetch  ${n}  from message ${id} in channel ${channelId}`);
+    return;
+  }
+  const token = require('../../modules/discord/auth.js').loadDiscordBotToken();
+  if (!token) { console.error('bug-attachment-recover: no Discord bot token on this box (DISCORD_BOT_TOKEN or discord-bot.json)'); process.exitCode = 2; return; }
+
+  let failed = unaddressable.length;
+  for (const [messageId, list] of byMessage) {
+    // Present files are left alone: a re-run after a partial recovery only
+    // fetches what is still missing.
+    const todo = list.filter((n) => { const p = at.resolveSafe(n); return !(p && fs.existsSync(p)); });
+    for (const n of list) if (!todo.includes(n)) console.log(`  present  ${n}`);
+    if (!todo.length) continue;
+    const results = await recoverMessage({ channelId, messageId, names: todo, token, persist: at.persistImageFromUrl });
+    for (const r of results) {
+      if (r.ok) console.log(`  restored ${r.name}  (${r.bytes} bytes)`);
+      else { failed++; console.log(`  FAILED   ${r.name}  (${r.reason})`); }
+    }
+  }
+  if (failed) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error(`bug-attachment-recover: ${e.message || e}`); process.exitCode = 2; });
+}
+
+module.exports = { messageIdFromName, planRecovery, imageAttachmentUrls, recoverMessage, SNOWFLAKE_RE };