@bongos/core 1.21.110 → 1.21.111

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.110",
-  "core_contract": "1.21.110",
-  "source_commit": "4df16a5c3d2eee37ad6572bb1be32a106bea9fd1",
+  "core_version": "1.21.111",
+  "core_contract": "1.21.111",
+  "source_commit": "a3e0196872aa25b75c2e6477c588bf9a3cc19b06",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T17:01:53.765Z",
+  "built_at": "2026-10-09T17:16:36.431Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 592,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3034,
+    "functional_verbatim": 3036,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3655,
-  "tree_sha256": "b5f9cc8c8673642d60dd789484f12cf32347f5ebad634f319e34770a77620c72",
+  "file_count": 3657,
+  "tree_sha256": "c31261294242b2cd66c134daea2ffb60526f5cfa809bbed76fee9c229436b1a9",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2872,7 +2872,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0ee9660d1757ad8c73fd71e37250ff001b89a9ca894f8e75a01fc97e5db4e759"
+      "sha256": "1665ae4a1fae5235c36e3a4d4d588de6d93817774de58ce40cd62e623e115a53"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4682,7 +4682,7 @@
     {
       "path": "modules/discord/bug-attachments.js",
       "mode": "0000644",
-      "sha256": "b773430f5abe8a742e35dc59335805c531821d0701a50f2090ed599f3c66dafe"
+      "sha256": "2a5338b89b92b3fa4d8ec7659433f5d07d424d2c6902a6497916f5a3c27f8a54"
     },
     {
       "path": "modules/discord/craft-broadcast.js",
@@ -10172,12 +10172,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e8c0e689fad7269139da1c9dd103cd1ea1c3058cffeda9799a45dcb9a79851e0"
+      "sha256": "4ba883875bbc96c1d74b3e0ad996ea707dea726f16d20989a885b07bde0a8a5b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e7ea8bae12ce6058d01dfc32e6c52c39b69d4ca1285f1246bec58b862fe190cf"
+      "sha256": "69b4ae038049ccf22290a8ab298d08d04d4e8800619f11c24a9aea97614ad535"
     },
     {
       "path": "public-docs/index.html",
@@ -10197,7 +10197,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "c78d78610bcdd0f13313e14da1dfabfb88480bc4edd1c501b6dd4d778a79766b"
+      "sha256": "aaa8e0550bc3b6b84184791498534dfe89d5accebc4c5e51220a95689c6a053e"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10452,7 +10452,12 @@
     {
       "path": "scripts/gds/bug-attachment-audit.js",
       "mode": "0000644",
-      "sha256": "959e349e988146d7be1eb872cf80eb0d25d3d4daf95bdcf1b077a0d81c0c598f"
+      "sha256": "fb9e587c2fc2d3664d1d936efd7508b364080129df082384ea1747223bf72394"
+    },
+    {
+      "path": "scripts/gds/bug-attachment-recover.js",
+      "mode": "0000644",
+      "sha256": "5127a98a6bdbe2b7ff519ae6d258bdcd13d3d95386843f5efa202d2d319ffa8d"
     },
     {
       "path": "scripts/gds/bug-triage.js",
@@ -12477,7 +12482,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a6eddfed735bb10f8d6e43b148e56c100c177cc6f98313f142401d7649ff18f1"
+      "sha256": "f10cbc790057ddb654dea27953fb735caba80cbc333d28a5b9253b44a852fd6b"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13142,12 +13147,17 @@
     {
       "path": "tests/bug_attachment_audit.mjs",
       "mode": "0000644",
-      "sha256": "995bc60d7c4d51c18c90dfe5e3e220ec884c793267f9d0403c299e7c2ecb96fa"
+      "sha256": "2c973440cf7339e716b0250c00a9045552b328851ddda09dddbb3d4ea130f5ef"
+    },
+    {
+      "path": "tests/bug_attachment_recover.mjs",
+      "mode": "0000644",
+      "sha256": "ac43b7080bd1ff9c8e98a0bdcf074a79c7a002bea935c31cfcf3dec2931020c7"
     },
     {
       "path": "tests/bug_attachments.mjs",
       "mode": "0000644",
-      "sha256": "086f4b512cf62eda827c21d5b7d28bb9d0b8de1a3e51c1419ffd7e0a955fed21"
+      "sha256": "02ab2e1b0e106b11e76f1868270c0c00e63b8ddbbf7f450343b3eba28672f56f"
     },
     {
       "path": "tests/bug_triage.mjs",

package/docs/module-api-changelog.md

@@ -3057,5 +3057,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.108 with no explicit bump. run 37962089344. (task 1002620)
   1.21.110 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.109 with no explicit bump. run 37963285770. (task 1002620)
+  1.21.111 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.110 with no explicit bump. run 37965024171. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/discord/bug-attachments.js

@@ -55,10 +55,17 @@ const NAME_RE = /^bug-[a-z0-9]{1,40}-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
 // used to be __dirname/../../var, which is the repo root in a single checkout and
 // `node_modules/@bongos/core/var` on an instance running a vendored core — where
 // every core reinstall wipes it. That is the task 1002237 shape, and these files
-// are the one thing here that cannot be regenerated: a Discord CDN URL expires in
-// about a day, so our copy IS the image. All five attachments this instance ever
-// stored are already gone (the 2026-07-05 droplet move carried the database and
-// not var/), which is what this default is meant to stop happening again.
+// are the hardest thing here to get back. What expires in about a day is the URL
+// SIGNATURE (`?ex=&is=&hm=`), not the attachment: Discord keeps the file for as
+// long as its message exists, and `GET /channels/{channel}/messages/{message}`
+// with the bot token returns a freshly-signed URL. The stored filename carries
+// the message id (`bug-<messageId>-<rand>.<ext>`), so a lost file is still
+// addressable — `scripts/gds/bug-attachment-recover.js` re-fetches it to its
+// original name (task 1004667). It stops working the day the message is deleted
+// or the channel history is gone, so our copy is still the copy to keep. All five
+// attachments this instance ever stored went missing from disk (the 2026-07-05
+// droplet move carried the database and not var/), which is what this default is
+// meant to stop happening again.
 //
 // BUG_ATTACHMENTS_DIR still wins, and on a box where the instance root is itself
 // impermanent that override is the answer — the standup recipe says so.
@@ -155,12 +162,19 @@ function sniffMatches(buf, ext) {
 // success, or { ok:false, reason } when the image is refused (never throws on a
 // refusal; throws only on an unexpected fs error the caller wraps). `messageId`
 // just seeds the (still-random) filename so attachments group readably.
+//
+// `file` (task 1004667) writes under a GIVEN name instead of a fresh one — the
+// recovery path, re-fetching a lost image back to the exact name a task
+// description already links. The name must pass isSafeName, its extension must
+// match the bytes actually fetched, and an existing file is never overwritten.
+// Same download path, same guards: recovery does not grow a second one.
 // How many manual redirect hops we'll re-validate + follow before giving up.
 // Discord CDN attachments are direct (0 redirects) in practice; a small bound
 // covers a CDN edge bounce without becoming an open redirect-follow loop.
 const MAX_REDIRECT_HOPS = 3;
 
-async function persistImageFromUrl(url, { messageId = 'x', fetchImpl = globalThis.fetch, dir = attachmentsDir() } = {}) {
+async function persistImageFromUrl(url, { messageId = 'x', fetchImpl = globalThis.fetch, dir = attachmentsDir(), file: givenFile = null } = {}) {
+  if (givenFile != null && !isSafeName(givenFile)) return { ok: false, reason: 'bad_name' };
   if (!isAllowedAttachmentHost(url)) return { ok: false, reason: 'bad_host' };
   // L3 residual (red-team 2026-06-12): fetch with redirect:'manual' and re-run
   // the host allowlist on every Location before following. With redirect:'follow'
@@ -202,10 +216,23 @@ async function persistImageFromUrl(url, { messageId = 'x', fetchImpl = globalThi
   if (buf.length > MAX_BYTES) return { ok: false, reason: 'too_big', bytes: buf.length };
   if (!sniffMatches(buf, ext)) return { ok: false, reason: 'sniff_mismatch' };
 
-  const idSlug = String(messageId).replace(/[^a-z0-9]/gi, '').slice(0, 40).toLowerCase() || 'x';
-  const file = `bug-${idSlug}-${crypto.randomBytes(8).toString('hex')}.${ext}`;
+  let file;
+  if (givenFile != null) {
+    if (path.extname(givenFile).slice(1) !== ext) return { ok: false, reason: 'ext_mismatch', type: rawType };
+    file = givenFile;
+  } else {
+    const idSlug = String(messageId).replace(/[^a-z0-9]/gi, '').slice(0, 40).toLowerCase() || 'x';
+    file = `bug-${idSlug}-${crypto.randomBytes(8).toString('hex')}.${ext}`;
+  }
   await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(path.join(dir, file), buf, { mode: 0o640 });
+  try {
+    // 'wx' only matters for a given name (a random one cannot collide): a
+    // recovery never clobbers a file that is already there.
+    await fs.writeFile(path.join(dir, file), buf, { mode: 0o640, flag: givenFile != null ? 'wx' : 'w' });
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return { ok: false, reason: 'exists' };
+    throw e;
+  }
   return { ok: true, file, url: `/api/bongos/bug-attachments/${file}`, bytes: buf.length };
 }
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.110",
+  "version": "1.21.111",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.110",
+      "version": "1.21.111",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.110",
+  "version": "1.21.111",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9518,5 +9518,11 @@
       "id": "1004678",
       "text": "The page-tweak helper can now run on its own: given one page, it applies the artist's words without asking anything, and if anything goes wrong it hands the page back with a plain note. The server enforces the safety rules its"
     }
+  ],
+  "1.21.111": [
+    {
+      "id": "1004667",
+      "text": "Lost bug screenshots can now be brought back. We used to tell people a missing screenshot from the Discord bugs channel was gone for good. That was wrong: only the link expires, and the picture stays in Discord as long as the"
+    }
   ]
 }

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

@@ -2,9 +2,12 @@
 // scripts/gds/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 one artefact in this
-// system that cannot be regenerated: the Discord CDN URL it was copied from is
-// signed and expires in about a day, so our copy IS the image. They live on disk
+// 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,
@@ -124,7 +127,8 @@ async function main() {
   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. These cannot be re-fetched (the Discord URL has expired).');
+        + '— every task describing one renders a broken image. '
+        + 'Try node scripts/gds/bug-attachment-recover.js --missing (it re-fetches from the original Discord message while that message still exists).');
     }
     return;
   }
@@ -132,12 +136,14 @@ async function main() {
   console.log(`  Store: ${dir}`);
   for (const m of r.missing) console.log(`    missing  ${m.name}  (task ${m.taskId})`);
   if (r.missing.length) {
-    console.log('  These cannot be re-fetched — the Discord CDN URL they were copied from has expired.');
-    console.log('  Restore from a nightly attachments archive: /var/backups/gds/<db>-attachments-*.tar.gz');
+    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/gds/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, LINK_RE };
+module.exports = { describedAttachments, auditRows, fetchRows, LINK_RE };

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// scripts/gds/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/gds/bug-attachment-recover.js --missing            # every file the audit finds missing
+//   node scripts/gds/bug-attachment-recover.js <message-id>...      # the missing files from those messages
+//   node scripts/gds/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 };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.110'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.111'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/bug_attachment_audit.mjs

@@ -2,9 +2,10 @@
 //
 // WHY THIS FILE EXISTS. Five re-hosted #bugs screenshots — every one this instance
 // ever stored — disappeared in the 2026-07-05 droplet move, and nobody noticed for
-// two months. They cannot be re-fetched: the Discord CDN URL they were copied from
-// is signed and expires in about a day, so our copy IS the image. The probe is what
-// should have said so in July.
+// two months. The Discord CDN URL they were copied from carries a signature that
+// expires in about a day; the file itself survives while its message does, and
+// bug-attachment-recover.js re-fetches it (task 1004667). The probe is what should
+// have said they were missing in July.
 //
 // A probe like this fails by finding nothing, and a clean bill of health looks
 // identical to working — which is exactly what happened while building it: the

package/tests/bug_attachment_recover.mjs

@@ -0,0 +1,128 @@
+// tests/bug_attachment_recover.mjs — re-fetching a lost #bugs screenshot from
+// its Discord message, back to its original filename (task 1004667).
+//
+// WHY THIS FILE EXISTS. The recovery is only worth anything if the file lands
+// under the name the task description already links — a fresh random name stores
+// the bytes and leaves the task's image broken — and if it goes through the same
+// guarded download as the bot (host allowlist, sniff, size cap). Both are pinned
+// here against the REAL persistImageFromUrl with a fake fetch: no network, no
+// Discord, a throwaway store.
+//
+// Run: node tests/bug_attachment_recover.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+const require = createRequire(import.meta.url);
+
+const TMP = path.join(os.tmpdir(), `otb-bugrecover-${process.pid}`);
+process.env.BUG_ATTACHMENTS_DIR = TMP;
+const at = require('../modules/discord/bug-attachments.js');
+const rec = require('../scripts/gds/bug-attachment-recover.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  return Promise.resolve().then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const CHANNEL = '111111111111111111';
+const MSG = '1234567890123456789';
+const A = `bug-${MSG}-0011223344556677.png`;
+const B = `bug-${MSG}-8899aabbccddeeff.png`;
+
+// One fake fetch for both legs: the Discord REST call returns `message`; a CDN
+// URL returns the PNG. Records every URL and header it was asked for.
+function fakeDiscord(message, { status = 200 } = {}) {
+  const calls = [];
+  const fetchImpl = async (url, opts = {}) => {
+    calls.push({ url, opts });
+    if (url.startsWith('https://discord.com/api/')) {
+      return { ok: status === 200, status, json: async () => message };
+    }
+    return {
+      ok: true, status: 200,
+      headers: { get: (k) => (k.toLowerCase() === 'content-type' ? 'image/png' : null) },
+      arrayBuffer: async () => PNG.buffer.slice(PNG.byteOffset, PNG.byteOffset + PNG.byteLength),
+    };
+  };
+  return { fetchImpl, calls };
+}
+
+const att = (n, extra = {}) => ({ url: `https://cdn.discordapp.com/attachments/${CHANNEL}/${n}/shot.png?ex=1&is=2&hm=3`, content_type: 'image/png', ...extra });
+
+console.log('Bug-attachment recovery (task 1004667):');
+
+await t('messageIdFromName: reads the snowflake the bot put in the name', () => {
+  assert.equal(rec.messageIdFromName(A), MSG);
+  assert.equal(rec.messageIdFromName('bug-x-0011223344556677.png'), null, 'the x fallback carries no id');
+  assert.equal(rec.messageIdFromName('bug-m42-0011223344556677.png'), null, 'a non-numeric slug is not a message id');
+  assert.equal(rec.messageIdFromName('../../etc/passwd'), null);
+});
+
+await t('planRecovery: groups by message, keeps link order, dedupes, sets aside the unaddressable', () => {
+  const { byMessage, unaddressable } = rec.planRecovery([A, 'bug-x-0011223344556677.png', B, A]);
+  assert.deepEqual([...byMessage.entries()], [[MSG, [A, B]]]);
+  assert.deepEqual(unaddressable, ['bug-x-0011223344556677.png']);
+});
+
+await t('imageAttachmentUrls: images only, in order — the same test the bot stored them by', () => {
+  const urls = rec.imageAttachmentUrls({ attachments: [att(1), { url: 'https://cdn.discordapp.com/x.txt', content_type: 'text/plain' }, att(2, { content_type: undefined, width: 10 })] });
+  assert.equal(urls.length, 2);
+  assert.ok(urls[0].includes('/1/') && urls[1].includes('/2/'));
+});
+
+await t('recoverMessage: asks Discord for the message with the bot token, then writes each image under its ORIGINAL name', async () => {
+  const { fetchImpl, calls } = fakeDiscord({ attachments: [att(1), att(2)] });
+  const out = await rec.recoverMessage({ channelId: CHANNEL, messageId: MSG, names: [A, B], token: 'tok', fetchImpl, dir: TMP, persist: at.persistImageFromUrl });
+  assert.deepEqual(out.map((r) => [r.name, r.ok]), [[A, true], [B, true]]);
+  assert.equal(calls[0].url, `https://discord.com/api/v10/channels/${CHANNEL}/messages/${MSG}`);
+  assert.equal(calls[0].opts.headers.Authorization, 'Bot tok');
+  assert.ok(calls[1].url.includes('/1/') && calls[2].url.includes('/2/'), 'k-th name ← k-th image');
+  for (const n of [A, B]) assert.equal((await fs.readFile(path.join(TMP, n))).length, PNG.length);
+  const onDisk = (await fs.readdir(TMP)).sort();
+  assert.deepEqual(onDisk, [A, B].sort(), 'no extra, randomly-named copy was written');
+});
+
+await t('recoverMessage: a deleted message is reported as message_gone, nothing written', async () => {
+  await fs.rm(TMP, { recursive: true, force: true });
+  const { fetchImpl } = fakeDiscord(null, { status: 404 });
+  const out = await rec.recoverMessage({ channelId: CHANNEL, messageId: MSG, names: [A], token: 'tok', fetchImpl, dir: TMP, persist: at.persistImageFromUrl });
+  assert.deepEqual(out.map((r) => r.reason), ['message_gone']);
+});
+
+await t('recoverMessage: more names than images → the extra name says so instead of reusing an image', async () => {
+  const { fetchImpl } = fakeDiscord({ attachments: [att(1)] });
+  const out = await rec.recoverMessage({ channelId: CHANNEL, messageId: MSG, names: [A, B], token: 'tok', fetchImpl, dir: TMP, persist: at.persistImageFromUrl });
+  assert.deepEqual(out.map((r) => r.ok || r.reason), [true, 'no_attachment_at_index']);
+});
+
+await t('recoverMessage: a non-snowflake id never reaches a URL', async () => {
+  const { fetchImpl, calls } = fakeDiscord({ attachments: [] });
+  const out = await rec.recoverMessage({ channelId: '../../users/@me', messageId: MSG, names: [A], token: 'tok', fetchImpl, dir: TMP, persist: at.persistImageFromUrl });
+  assert.deepEqual([out[0].reason, calls.length], ['bad_id', 0]);
+});
+
+await t('recoverMessage: the attachment download keeps the CDN host allowlist', async () => {
+  await fs.rm(TMP, { recursive: true, force: true });
+  const { fetchImpl } = fakeDiscord({ attachments: [{ url: 'https://evil.example/shot.png', content_type: 'image/png' }] });
+  const out = await rec.recoverMessage({ channelId: CHANNEL, messageId: MSG, names: [A], token: 'tok', fetchImpl, dir: TMP, persist: at.persistImageFromUrl });
+  assert.equal(out[0].reason, 'bad_host');
+});
+
+await t('the audit no longer claims a lost file cannot be re-fetched, and points at this tool', async () => {
+  const src = await fs.readFile(new URL('../scripts/gds/bug-attachment-audit.js', import.meta.url), 'utf8');
+  assert.ok(!/cannot be re-fetched/i.test(src));
+  assert.match(src, /bug-attachment-recover\.js --missing/);
+  const mod = await fs.readFile(new URL('../modules/discord/bug-attachments.js', import.meta.url), 'utf8');
+  assert.match(mod, /What expires in about a day is the URL\s*\n?\s*\/\/\s*SIGNATURE/);
+});
+
+await t('cleanup temp dir', async () => { await fs.rm(TMP, { recursive: true, force: true }); });
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/bug_attachments.mjs

@@ -107,6 +107,36 @@ await t('persistImageFromUrl: valid PNG → written to disk, returns durable url
   assert.equal(onDisk.length, PNG.length);
 });
 
+// ---- task 1004667: a GIVEN filename (the recovery path) ---------------------
+const GIVEN = 'bug-1234567890123456789-0011223344556677.png';
+await t('persistImageFromUrl({file}): writes under EXACTLY the given name', async () => {
+  const r = await at.persistImageFromUrl('https://cdn.discordapp.com/a.png', { file: GIVEN, fetchImpl: fakeFetch(PNG), dir: TMP });
+  assert.equal(r.ok, true);
+  assert.equal(r.file, GIVEN);
+  assert.equal((await fs.readFile(path.join(TMP, GIVEN))).length, PNG.length);
+});
+await t('persistImageFromUrl({file}): never overwrites a file that is present', async () => {
+  await fs.writeFile(path.join(TMP, GIVEN), 'KEEP');
+  const r = await at.persistImageFromUrl('https://cdn.discordapp.com/a.png', { file: GIVEN, fetchImpl: fakeFetch(PNG), dir: TMP });
+  assert.deepEqual([r.ok, r.reason], [false, 'exists']);
+  assert.equal(await fs.readFile(path.join(TMP, GIVEN), 'utf8'), 'KEEP');
+});
+await t('persistImageFromUrl({file}): an unsafe name is refused before any fetch', async () => {
+  let fetched = false;
+  const r = await at.persistImageFromUrl('https://cdn.discordapp.com/a.png', { file: '../../evil.png', fetchImpl: async () => { fetched = true; }, dir: TMP });
+  assert.deepEqual([r.ok, r.reason, fetched], [false, 'bad_name', false]);
+});
+await t('persistImageFromUrl({file}): bytes of another type than the name says → ext_mismatch, nothing written', async () => {
+  const name = 'bug-1234567890123456789-8899aabbccddeeff.jpg';
+  const r = await at.persistImageFromUrl('https://cdn.discordapp.com/a.png', { file: name, fetchImpl: fakeFetch(PNG), dir: TMP });
+  assert.deepEqual([r.ok, r.reason], [false, 'ext_mismatch']);
+  await assert.rejects(fs.access(path.join(TMP, name)));
+});
+await t('persistImageFromUrl({file}): the host allowlist still applies', async () => {
+  const r = await at.persistImageFromUrl('https://evil.example/a.png', { file: 'bug-1-8899aabbccddeeff.png', fetchImpl: fakeFetch(PNG), dir: TMP });
+  assert.equal(r.reason, 'bad_host');
+});
+
 // ---- L3 (#999): redirect:'manual' + re-validate the Location host ----------
 // A fetch that returns a 30x with the given Location on the FIRST call, then the
 // real PNG body on subsequent calls. Records the URLs it was asked to fetch.