@bongos/core 1.21.109 → 1.21.111

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/scripts/gds/copy-apply.js

@@ -32,6 +32,7 @@
 //
 // Run:  node scripts/gds/copy-apply.js --batch            (a PAGE TWEAK round you hold: every line, task 1004322)
 //       node scripts/gds/copy-apply.js --batch --batch-file round.md --dry-run   (a local round; writes nothing)
+//       node scripts/gds/copy-apply.js --batch --page <id> --unattended   (the auto-pickup worker: exit 5 = wrong page; any non-zero exit releases the round, task 1004678)
 //       node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
 //       node scripts/gds/copy-apply.js --dry-run          (say what would change, write nothing)
 //       node scripts/gds/copy-apply.js --task 1234        (a claim you hold, when you hold more than one)
@@ -518,7 +519,7 @@ async function writeAppliedBlock({ taskId, description, block, api = apiCall })
 
 // The --batch command. `deps` is the test seam: every read, write, re-read and API
 // call can be replaced, so the whole path runs against a fixture round.
-async function batchMain({ taskId, batchFile, dryRun, now = () => new Date().toISOString() }, deps = {}) {
+async function batchMain({ taskId, batchFile, dryRun, pageId = null, now = () => new Date().toISOString() }, deps = {}) {
   const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
   const writeFile = deps.writeFile || ((p, s) => fs.writeFileSync(p, s));
   const api = deps.api || apiCall;
@@ -526,6 +527,12 @@ async function batchMain({ taskId, batchFile, dryRun, now = () => new Date().toI
   const loaded = await loadBatch({ taskId, batchFile, readFile, api });
   if (!loaded.ok) return refuse(loaded);
   const { batch } = loaded;
+  // --page (task 1004678, ADR 0371 D8): the unattended worker names the page it was
+  // given, and a round for any other page is refused before a file is touched.
+  if (pageId && batch.page_id !== pageId) {
+    refuse({ ok: false, code: 'wrong_page', detail: { task: taskId, expected: pageId, round_page: batch.page_id, what_this_means: 'This round belongs to a different page than the one named with --page. Nothing was written.' } });
+    return 5;
+  }
   const registry = deps.registry || JSON.parse(readFile(path.join(REPO_ROOT, 'docs', 'copy-registry.json')));
   const result = applyBatchToSources({ batch, registry, readSource: (rel) => readFile(path.join(REPO_ROOT, rel)) });
 
@@ -590,7 +597,15 @@ async function main() {
       taskId = held.taskId;
       console.log(`copy-apply --batch: the round you are holding — task ${taskId}`);
     }
-    return cliExit(await batchMain({ taskId, batchFile, dryRun }));
+    // --page <id> --unattended (task 1004678, ADR 0371 D8): never asks, and any exit
+    // that is not a clean apply releases the round with a plain note (tweak-halt.js).
+    const pageId = arg('--page') || null;
+    const code = await batchMain({ taskId, batchFile, dryRun, pageId });
+    if (hasFlag('--unattended') && code !== 0 && taskId && !batchFile && !dryRun) {
+      const halt = require('./tweak-halt');
+      halt.releaseWithNote(taskId, halt.haltForCopyApplyExit(code));
+    }
+    return cliExit(code);
   }
 
   if (!taskId && !patchFile) {

package/scripts/gds/tweak-halt.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// scripts/gds/tweak-halt.js — an unattended /tweak stops, releases its round with a
+// plain note, and exits (task 1004678 / BV2.TW19b, ADR 0371 D8).
+//
+// WHY. `/tweak --page <id> --unattended` runs with nobody to ask. Every halt it can
+// meet must end the same way: the round goes back to the queue with a sentence an
+// artist can read, and the worker exits. Writing that once here means the skill,
+// copy-apply's --unattended path and the runner's lane (TW19c) cannot each word a
+// halt differently, or leave one claimed.
+//
+// Run:  node scripts/gds/tweak-halt.js <task-id> --code <halt-code>
+//
+// The note is fixed vocabulary per code, never free text from the worker: the
+// worker is a model reading pages an artist wrote, so nothing it says rides out
+// onto the round.
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// The halts ADR 0371 D8 names, plus the copy-apply exits that mean "do not ship".
+const HALT_NOTES = Object.freeze({
+  claim_refused: 'The automatic apply could not take this round (the claim was refused). It waits for a person.',
+  nothing_applied: 'The automatic apply placed none of the lines, so there is nothing to show. Each refused line is recorded on the round.',
+  wrong_page: 'The automatic apply was pointed at a different page than this round. Nothing was changed.',
+  registry_mismatch: 'The automatic apply wrote the files but the copy registry did not read the new words back, so it stopped before shipping.',
+  reread_failed: 'The automatic apply could not re-read the page after applying it, so it stopped before shipping.',
+  ship_check_stale: 'The automatic apply stopped because the pre-ship checks named something stale it may not fix by itself.',
+  grader_unavailable: 'The quality review could not run, so the automatic apply stopped. The round waits for the next try or a person.',
+  grade_failed: 'The quality review did not pass the automatic apply. The round waits for a person.',
+  outside_page: 'The automatic apply would have changed a file outside this page, so it stopped.',
+});
+
+function haltNote(code) {
+  return HALT_NOTES[code] || null;
+}
+
+// copy-apply --batch's exit codes, as halts. 0 is not a halt. 2 is "nothing
+// applied" and also every refusal copy-apply names before writing (an unreadable
+// round): in both, nothing reached the page.
+function haltForCopyApplyExit(exit) {
+  if (exit === 0) return null;
+  return { 2: 'nothing_applied', 3: 'registry_mismatch', 4: 'reread_failed', 5: 'wrong_page' }[exit] || 'nothing_applied';
+}
+
+// Release the round with the note. `spawn` is the test seam. Returns the exit.
+function releaseWithNote(taskId, code, { spawn = spawnSync } = {}) {
+  const note = haltNote(code);
+  if (!note) throw new Error(`unknown halt code: ${code}`);
+  const r = spawn(process.execPath, [path.join(__dirname, 'release.js'), String(taskId), '--reason', `[tweak-unattended:${code}] ${note}`], { stdio: 'inherit' });
+  return r && typeof r.status === 'number' ? r.status : 1;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const taskId = argv[0];
+  const i = argv.indexOf('--code');
+  const code = i >= 0 ? argv[i + 1] : null;
+  if (!/^[1-9][0-9]*$/.test(String(taskId || '')) || !haltNote(code)) {
+    console.error(`usage: node scripts/gds/tweak-halt.js <task-id> --code <${Object.keys(HALT_NOTES).join('|')}>`);
+    return 1;
+  }
+  console.log(`tweak-halt: task ${taskId} — ${haltNote(code)}`);
+  return releaseWithNote(taskId, code);
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { HALT_NOTES, haltNote, haltForCopyApplyExit, releaseWithNote };

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.109'; // 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.