@bongos/core 1.21.110 → 1.21.112

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.112",
+  "core_contract": "1.21.112",
+  "source_commit": "20d2e0bfe68101dc84b13e8322b6c1dd35abcfe3",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T17:01:53.765Z",
+  "built_at": "2026-10-09T17:32:18.946Z",
   "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": "8fb96168c1321372e872219e26f508d99b040b9ebce4ce6ca17e482c0216c0a0",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -612,7 +612,7 @@
     {
       "path": "docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md",
       "mode": "0000644",
-      "sha256": "250ee61fac1aff3aa602a769a0b6fb2dcdac9f9abe9c61381d755a1b53a0eea2"
+      "sha256": "9127ee3f769616ad16e7151cb7f5f5a461690303804ce0ee7ddf6410f101dbd0"
     },
     {
       "path": "docs/adr/0044-mediterranean-palette-replacement.md",
@@ -2352,7 +2352,7 @@
     {
       "path": "docs/canonical-permissions.md",
       "mode": "0000644",
-      "sha256": "58b05e37108c25afa2d1d61a22c6fa0419ec2e242dacc3c1f8b7f7c70bd46ae2"
+      "sha256": "453a9449ea0dc1a5f50b1d786a4d5b14086423bfd02904c9a0df5c541347d144"
     },
     {
       "path": "docs/copy-inventory.md",
@@ -2872,7 +2872,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0ee9660d1757ad8c73fd71e37250ff001b89a9ca894f8e75a01fc97e5db4e759"
+      "sha256": "c7506ded99bfae21631034eaeda8c97b705dc16fe06bbf4e2419a257f578f755"
     },
     {
       "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": "c0b56b64fd6deff145189d27a3aec0713132b1112d2545617719ee5d29f5e714"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e7ea8bae12ce6058d01dfc32e6c52c39b69d4ca1285f1246bec58b862fe190cf"
+      "sha256": "3093047c8006d903bd5348bba1b43d9cd99f8dfd9ed19bb1575c8c92035a16b0"
     },
     {
       "path": "public-docs/index.html",
@@ -10197,7 +10197,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "c78d78610bcdd0f13313e14da1dfabfb88480bc4edd1c501b6dd4d778a79766b"
+      "sha256": "15e75913ea8e573944116d52fe5e44135ca7be4bc7a338cb6ee7d36f4b2a44d3"
     },
     {
       "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": "a59fd4faf5376d371522507f8d01e336f655e2871ca2b4409f59606cccdfa28f"
     },
     {
       "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/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md

@@ -19,7 +19,7 @@ The SSH deploy failed (their box had no droplet key), but it didn't matter: the
 
 [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) put authority in `builders.rank` and enforced it **server-side per request** — but **only for `/api/gds/*` HTTP routes**. It explicitly does not cover two surfaces:
 
-1. **GitHub `main` is writable by every collaborator.** The repo is a **free-plan private repo**, so GitHub branch protection is *not available* ("Upgrade to GitHub Pro…"). All collaborators (`example-owner`, `LarsCode`, `willExample`, `IAMMASTERQUA`) have full push to `main`. The grader / confirm / rank gates live inside `ship.js` and the server — a raw `git push origin main` touches neither.
+1. **GitHub `main` is writable by every collaborator.** The repo is a **free-plan private repo**, so GitHub branch protection is *not available* ("Upgrade to GitHub Pro…"). All collaborators (`example-owner`, `LarsCode`, `willExample`, `IAMMASTERQUA`) have full push to `main`. The grader / confirm / rank gates live inside `ship.js` and the server — a raw `git push origin main` touches neither. *(As written at the time. Since 2026-08-08 `main` is protected — a pull request plus the `unit` check for every non-admin; see §"Branch-protection status" for the current probes.)*
 2. **The legit pipeline itself distributes the dangerous credentials.** `ship.js` does the merge-to-`main` and `ssh …deploy.sh` **client-side, from the builder's machine** — so the design hands every shipping builder the exact credentials needed to bypass it.
 
 A second, softer problem Lars raised: a sub-Metic builder had free rein to **read into and reason about the tiering/permission code** in the first place. Newcomers (`xenos`/`thetes`) should stay in their lane.
@@ -30,13 +30,13 @@ Two threads.
 
 ### A. Close the code-landing path (chosen: Option A now, Option B later)
 
-The protection goal is "un-graded code cannot reach prod, and a raw push to `main` is caught." Three layers, defense-in-depth, where **layer 3 is the authoritative enforcement** (the only one that survives a raw push / `--no-verify`, given GitHub can't block the push on the free plan):
+The protection goal is "un-graded code cannot reach prod, and a raw push to `main` is caught." Three layers, defense-in-depth, where **layer 3 is the authoritative enforcement** (the only one that survives a raw push / `--no-verify`, given GitHub couldn't block the push on the free plan when this was written). **Since 2026-08-08 GitHub does block a non-admin's direct push** — see §"Branch-protection status"; layer 3 stays authoritative for what branch protection does not cover (the admin's direct push, a self-merged PR with zero reviews, and *who* authored a protected path — the `unit` check passes a sub-Metic author as readily as anyone):
 
 | Layer | Mechanism | Catches | Authoritative? |
 |---|---|---|---|
 | 1 — pre-push hook | `.husky/pre-push` → `scripts/gds/hooks/pre-push.js`. Blocks a direct push to `main` (override `OTB_ALLOW_MAIN_PUSH=1`, used only by the gated `scripts/gds/push-main.js`), and blocks a sub-Metic push that touches a permission-sensitive path. | the cooperative / careless case before the push leaves the box | no — bypassable with `--no-verify` |
 | 2 — grader pre-pass | `grader.permissionPathPrePass(changedFiles, builderRank)` hard-fails the grade if a sub-Metic diff touches a protected path (mirrors the route-rank pre-pass). | the honest GDS ship flow | no — skippable with `--skip-grade` / raw push |
-| 3 — post-push main audit | `scripts/gds/main-audit.js`: reads the **real** git history + **real** builder ranks (roster API, or Postgres via `--db` on the droplet). A resolved sub-Metic author on a protected path is a hard `[BLOCKER]`. Runs nightly (`.claude/scheduled-tasks/main-audit/`) **and** as the deploy gate (`--verify-head --db` from `~/deploy.sh`, `infra/deploy-main-audit-gate.sh`). | a raw `git push origin main`, a `--no-verify`, a `--skip-grade` — anything | **yes** — independent of the builder's cooperation |
+| 3 — post-push main audit | `scripts/gds/main-audit.js`: reads the **real** git history + **real** builder ranks (roster API, or Postgres via `--db` on the droplet). A resolved sub-Metic author on a protected path is a hard `[BLOCKER]`. Runs nightly (`.claude/scheduled-tasks/main-audit/`) **and** as the deploy gate (`--verify-head --db` from `~/deploy.sh`, `infra/deploy-main-audit-gate.sh`). | a raw `git push origin main` (since 2026-08-08 only the admin's; a non-admin's is refused by GitHub), a self-merged PR, a `--no-verify`, a `--skip-grade` — anything | **yes** — independent of the builder's cooperation, and the only layer that judges the author's RANK; branch protection proves a PR + green `unit`, not who may touch a protected path |
 
 "Option A" = the merge-to-`main` + deploy move **server-side** so builders never hold main-push/droplet-SSH at all. The protections above ship now; the *full* server-side move and the credential rotation are operator steps (blockers [#15](https://example.com/builders#/blocker/15), [#16](https://example.com/builders#/blocker/16)). Until then, the legit client-side push is allowed only through `scripts/gds/push-main.js`, and the deploy gate (layer 3) is what guarantees poison never reaches prod.
 
@@ -69,7 +69,40 @@ After shipping, the fix was adversarially red-teamed (a 4-dimension panel + per-
 
 **Not yet done (finding `#7`, follow-up):** the permission-path pre-pass (layer 2) runs only client-side in `ship.js`; the server `/grade` and `/confirm` routes don't re-run it. Layer 3 is the server-side backstop today; re-running the pre-pass server-side (the server holds the live rank in `req.builder.rank`) would harden the cooperative path.
 
-## Branch-protection status: re-verified 2026-07-24 (task [#1001840](https://cloudbongos.com/builders#/task/1001840))
+## Branch-protection status: re-verified 2026-09-25 (task [1004669](https://cloudbongos.com/builders#/task/1004669))
+
+**Current. `main` IS protected — a pull request plus the `unit` check, for everyone but the admin.**
+Probed 2026-09-25 with the owner's (admin) GitHub account while checking task
+[1001433](https://cloudbongos.com/builders#/task/1001433); the protection itself landed 2026-08-08
+(task [1002619](https://cloudbongos.com/builders#/task/1002619)):
+
+| Probe | Result |
+|---|---|
+| `GET /repos/:o/:r/branches/main` | `protected: true` |
+| `GET /repos/:o/:r/branches/main/protection` | `required_status_checks.contexts: ["unit"]` (`strict: false`) · `required_pull_request_reviews` present, `required_approving_review_count: 0` · `enforce_admins: false` · `allow_force_pushes: false` · `allow_deletions: false` |
+| `GET /repos/:o/:r/rulesets` | `[]` — classic branch protection, not a ruleset |
+| Collaborators with write | four, plus the admin owner; all four are Metic or Archon on the public leaderboard |
+
+What this means for the claims above:
+
+- **No longer true:** "a raw `git push origin main` by any collaborator is accepted". A non-admin's
+  direct push is refused; their work reaches `main` only through a PR whose `unit` check is green.
+  Force-pushing and deleting `main` are refused for everyone.
+- **Still true:** the **admin** can push directly (`enforce_admins: false`); a write collaborator can
+  merge **their own** PR with zero reviews (the review count is 0 — the deliberate checks-only posture
+  of ADR 0162); and a builder **below Metic** reaches `main` only through the server's own publish
+  path (ADR 0055), never with a credential of their own.
+- **So layer 3 (`main-audit.js`) stays the authoritative rank check.** Branch protection proves a
+  change came through a PR with a green `unit` run; it says nothing about whether its author may touch
+  a protected path. Option B (blocker [17](https://cloudbongos.com/builders#/blocker/17)) is half-delivered:
+  direct push is closed for non-admins, but nothing restricts `main` to the owner plus a deploy bot.
+
+Treat this as the freshness stamp: re-run the probes above before asserting the claim has changed,
+and update this section — not the history below — when it does.
+
+## Branch-protection status: 2026-07-24 (history — superseded by the section above)
+
+_Originally headed "re-verified 2026-07-24 (task [1001840](https://cloudbongos.com/builders#/task/1001840))"; kept as written._
 
 The 2026-07-03 authority sweep reported that `main` had since gained live branch protection (required
 checks + code-owner review, direct push blocked), which would have demoted `main-audit.js` from
@@ -90,8 +123,8 @@ private repo with no protection available, and **layer 3 (`main-audit.js`) remai
 enforcement**, not a redundant second net. Option B (blocker
 [#17](https://cloudbongos.com/builders#/blocker/17)) is still open and still the durable closure.
 
-Treat this as the freshness stamp: re-run the probes above before asserting the claim has changed —
-a plan upgrade or a new ruleset would flip it, and this section is what a future sweep should update.
+This was the freshness stamp until the 2026-08-08 protection flipped it; the current stamp is the
+2026-09-25 section above.
 
 ## G-2/G-17 resolution: Layer 1 delivered; the "path bug" refuted (2026-08-08, task 1002608)
 

package/docs/canonical-permissions.md

@@ -290,12 +290,15 @@ Reading the code is not rank-gated today; what a builder can LAND is (next secti
 ADR 0016's per-request rank check covers `/api/bongos/*` only. Two surfaces it does **not** cover —
 `git push` to `main` and `ssh` to the droplet — were used in the Builder 25 incident to land an
 un-graded tiering change straight on prod `main`. **Since 2026-08-08 (task 1002619), `main` HAS
-live branch protection: the required `unit` status check blocks every direct push, so all work
-lands via PR.** The protection is *checks-only* — a code-owner review requirement was briefly
+live branch protection: a pull request plus the required `unit` status check, so a non-admin's
+direct push is refused and their work lands via PR.** Re-probed 2026-09-25 (task
+[1004669](https://cloudbongos.com/builders#/task/1004669)): `enforce_admins` is off, so the **admin**
+can still push directly; the PR needs **zero** approvals, so a write collaborator can merge their own;
+force-push and deletion of `main` are refused for everyone. The protection is *checks-only* — a code-owner review requirement was briefly
 enforced and then deliberately retired by the owner (ADR 0162, task 1002635): gates are
 rank-consistent CI checks, never a named human's approval. (The 2026-07-24 state — no protection
 at all, PR #19 merged with zero checks — is preserved in ADR 0043 §"Branch-protection status" as
-history.) `main-audit.js` remains the authoritative *post-merge* layer — it catches what any
+history, below the current 2026-09-25 probes.) `main-audit.js` remains the authoritative *post-merge* layer — it catches what any
 pre-merge gate misses, independent of the builder's cooperation:
 
 - A builder **below Metic** (`xenos`, `thetes`) may **not modify permission-sensitive paths** — the

package/docs/module-api-changelog.md

@@ -3057,5 +3057,9 @@ 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)
+  1.21.112 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.111 with no explicit bump. run 37966893511. (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.112",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.110",
+      "version": "1.21.112",
       "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.112",
   "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,17 @@
       "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"
+    }
+  ],
+  "1.21.112": [
+    {
+      "id": "1004669",
+      "text": "The security record for the main branch now says what is actually true. It used to say anyone with access could push straight to the main code line. That stopped being true in August: now every change from a regular collaborat"
+    }
   ]
 }

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