@bongos/core 1.19.349 → 1.19.350

package/modules/lifecycle/routes/visuals.js

@@ -0,0 +1,216 @@
+// modules/lifecycle/routes/visuals.js — the ship-time task VISUAL, whole
+// surface (task 1003109, goal 1000072 "Human legibility").
+//
+// NAMED `visuals.js`, NOT `task-visuals.js`, and that is load-bearing:
+// tests/helpers.mjs:taskRoutesSource() concatenates `tasks.js` + every
+// `task-*.js` in this directory as "the tasks-route family" (the carve products
+// task-route-helpers.js / task-write-routes.js). A file called task-visuals.js
+// sorts FIRST in that concatenation, so its `res.status(201)` body became the one
+// tests/goal_advisory.mjs + tests/est_advisory.mjs inspect — and both failed on a
+// route that was perfectly correct. Adding a `task-*.js` route file here silently
+// hijacks those assertions; don't.
+//
+//   POST   /tasks/:id/visual    attach or replace it   (claim holder | Archon)
+//   DELETE /tasks/:id/visual    take it back off       (claim holder | Archon)
+//   GET    /task-visuals/:name  serve one              (see the audience note)
+//
+// The twin of routes/bug-attachments.js, for the image a builder attaches to
+// their own shipped task instead of one the bot pulled out of #bugs. Storage +
+// screening live in ../task-visuals.js; all three routes live here rather than
+// in the (already 1800-line) routes/tasks.js so the feature reads as one thing.
+//
+// rank: public — but CONDITIONALLY, and the condition is the whole point of the
+// file, so read this before changing the mounting.
+//
+//   A visual carries no audience of its own: it restates the task's
+//   value_summary in another medium, so it inherits that summary's audience
+//   exactly. For already-public work (shipped|confirmed, not security_sensitive)
+//   the summary is on the open web — the unauthenticated status dashboard renders
+//   it — so the image is served unauthenticated too. For anything else the image
+//   is served ONLY to an authenticated builder, via the very same
+//   auth.requireBuilder used everywhere else in the GDS.
+//
+//   That is why the gate is applied INSIDE the handler rather than as a mounted
+//   middleware: the decision needs the task the filename names. The stored
+//   filename embeds the task id (task-<id>-<hex>.<ext>) precisely so this lookup
+//   is possible without a second table. It FAILS CLOSED at every step — an
+//   unparseable name, an absent task, or a task that is not already-public all
+//   fall through to requireBuilder, never past it.
+//
+// The audience predicate itself lives once, in ../task-visuals.js
+// (isPubliclyViewable), and is mirrored in the public shipped-feed SQL.
+
+const express = require('express');
+const fs = require('node:fs/promises');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+// The feature's own two queries — kept out of the 5.8k-line ../db.js under the
+// shrink-only size ratchet; see the file header there.
+const db = require('../task-visual-db');
+const visuals = require('../task-visuals');
+// The claim-holder gate the whole ship path uses (/grade /confirm /ship
+// /publish-branch). Intra-module sibling — reused, never re-stated.
+const { gateTaskOwnership } = require('./tasks');
+const { validateOrRespond, parseId } = api;
+const log = api.logger('lifecycle');
+
+// Body caps for POST /tasks/:id/visual. Two layers, like /publish-branch: the
+// JSON limit bounds the ENCODED base64 string, and visuals.screenImage re-checks
+// the DECODED bytes against visuals.MAX_BYTES (4 MB).
+const VISUAL_BODY_LIMIT = '8mb';
+const VISUAL_B64_MAX = 7 * 1024 * 1024;
+
+module.exports = function buildTaskVisualsRouter() {
+  const router = express.Router();
+
+  // rank: public — the WIDEST path this route can take, declared honestly. It is
+  // reached only for already-public work (see isPubliclyViewable); every other
+  // request falls through to auth.requireBuilder INSIDE the handler, because the
+  // decision needs the task the filename names. Read the file header before
+  // changing this — a mounted middleware cannot express a per-row audience.
+  // GET /api/bongos/task-visuals/:name — stream one stored visual.
+  router.get('/task-visuals/:name', async (req, res, next) => {
+    const name = req.params.name;
+    const filePath = visuals.resolveSafe(name);
+    // Refuse a malformed name BEFORE any lookup — this is the path-traversal
+    // wall, and it also means the id parsed below is always well-formed.
+    if (!filePath) return res.fail('bad_name', 400);
+
+    const taskId = visuals.taskIdFromName(name);
+    let task = null;
+    try {
+      task = await db.getTaskVisualAccess(taskId);
+    } catch (err) {
+      // A lookup failure must not become an open door. Log and fall through to
+      // the authenticated path — a builder still gets the image, the open web
+      // does not.
+      log.error({ taskId, err: err && err.message }, 'task-visual access lookup failed — falling back to the authenticated path');
+    }
+
+    const send = async () => {
+      try {
+        const data = await fs.readFile(filePath);
+        res.setHeader('Content-Type', visuals.contentTypeForName(name));
+        // Never let a browser sniff a stored byte-string into something
+        // executable on our own origin, and keep it inline (it renders in the
+        // hall) but explicitly not as a download.
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Content-Disposition', 'inline');
+        res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+        // A stored file is immutable — a replacement gets a NEW random name — so
+        // it can be cached hard. Public work caches shared; everything else stays
+        // private to the builder's own browser.
+        res.setHeader(
+          'Cache-Control',
+          visuals.isPubliclyViewable(task) ? 'public, max-age=86400' : 'private, max-age=86400'
+        );
+        res.send(data);
+      } catch (err) {
+        if (err.code === 'ENOENT') return res.fail('not_found', 404);
+        log.error({ name, err: err && err.message }, 'task-visual read failed');
+        res.fail('read_failed', 500);
+      }
+    };
+
+    if (visuals.isPubliclyViewable(task)) return send();
+    // Not already-public → the ordinary builders-only GDS posture. requireBuilder
+    // owns its own 401/403 response; we only reach send() when it calls next().
+    return auth.requireBuilder(req, res, (err) => (err ? next(err) : send()));
+  });
+
+  // ==========================================================================
+  // Ship-time task VISUAL (task 1003109, goal 1000072 "Human legibility")
+  // --------------------------------------------------------------------------
+  // `value_summary` gives a reader the plain-language "what this means" line. A
+  // visual is that SAME claim in another medium — a screenshot of the surface
+  // that changed, a before/after, a diagram — so a non-engineer can SEE a change
+  // instead of reading about it (owner idea 1000400). Storage + screening live in
+  // ../task-visuals.js; the serve route above is what renders it back.
+  //
+  // ALWAYS OPTIONAL. Nothing on the ship path calls this, or blocks on it: the
+  // CLI uploads only when the builder passed --visual, and a failure there is a
+  // warning, never an abort. A task with no visual is a complete task.
+  //
+  // AUTH: requireBuilder + gateTaskOwnership — exactly the /grade /confirm /ship
+  // /publish-branch gate. Only the task's claim holder (or an Archon) may say
+  // what a task's shipped work looked like; anyone else attaching an image to
+  // someone else's ledger entry is the misattribution this closes.
+  const visualUpload = express.json({ limit: VISUAL_BODY_LIMIT });
+  // POST /tasks/:id/visual — attach (or replace) this task's ship-time visual.
+  router.post('/tasks/:id/visual', auth.requireBuilder, visualUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', maxLength: VISUAL_B64_MAX, minLength: 1 },
+      content_type: { required: true, type: 'string', maxLength: 100, minLength: 1 },
+      alt: { type: 'string', maxLength: visuals.MAX_ALT_LENGTH },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+
+    // The JSON `limit` bounds the ENCODED payload; base64 inflates ~33%, so the
+    // DECODED bytes are re-checked in screenImage (the publish-branch posture).
+    // Buffer.from never throws on malformed base64 — it drops what it can't
+    // decode — so there is no decode error to catch here: garbage in produces
+    // bytes that fail the magic-byte sniff below, which is the real gate.
+    const buf = Buffer.from(req.body.image_b64, 'base64');
+    const screened = visuals.screenImage(buf, req.body.content_type);
+    if (!screened.ok) {
+      const status = screened.reason === 'too_big' ? 413 : 400;
+      return res.fail(`visual_${screened.reason}`, status, {
+        max_bytes: visuals.MAX_BYTES,
+        accepted: Object.keys(visuals.EXT_BY_TYPE),
+      });
+    }
+
+    // Read the task (and its current visual) BEFORE writing, so a replaced image
+    // can be unlinked and a vanished task 404s rather than orphaning a file.
+    const before = await db.getTaskVisualAccess(id);
+    if (!before) return res.fail('task_not_found', 404);
+
+    try {
+      const stored = await visuals.persistImageBuffer(buf, {
+        taskId: id,
+        contentType: req.body.content_type,
+      });
+      if (!stored.ok) return res.fail(`visual_${stored.reason}`, 400);
+      const row = await db.setTaskVisual({
+        taskId: id,
+        visualUrl: stored.url,
+        visualAlt: visuals.normalizeAlt(req.body.alt),
+      });
+      // Replacing: drop the superseded file. Best-effort — a failed unlink leaves
+      // an unreferenced file, which is harmless; a failed RESPONSE would not be.
+      if (before.visual_url && before.visual_url !== stored.url) {
+        await visuals.deleteStored(before.visual_url);
+      }
+      return res.status(201).json({ ok: true, visual_url: row.visual_url, visual_alt: row.visual_alt, bytes: stored.bytes });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual upload failed');
+      return res.fail('visual_store_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE /tasks/:id/visual — remove it again. The counterpart to "always
+  // optional": a builder who attached the wrong screenshot must be able to take
+  // it back, and an image is not prose (the write-once rule of task 1003102
+  // guards a written CLAIM, not the picture beside it). Same ownership gate as
+  // the POST. Idempotent — removing an absent visual is a success.
+  router.delete('/tasks/:id/visual', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const before = await db.getTaskVisualAccess(id);
+    if (!before) return res.fail('task_not_found', 404);
+    try {
+      await db.setTaskVisual({ taskId: id, visualUrl: null, visualAlt: null });
+      if (before.visual_url) await visuals.deleteStored(before.visual_url);
+      return res.json({ ok: true, visual_url: null });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual delete failed');
+      return res.fail('visual_delete_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/lifecycle/task-visual-db.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// modules/lifecycle/task-visual-db.js — the two queries behind a task's ship-time
+// visual (task 1003109, goal 1000072 "Human legibility").
+//
+// WHY ITS OWN FILE. These belong logically in ../db.js with the rest of the
+// lifecycle data layer — but that file is already ~5,800 lines, and the size
+// ratchet (scripts/gds/fitness-ratchets.js, task 1003129) is shrink-only: an
+// oversized file may not grow. A feature's data access going into a small,
+// cohesive file next to the feature's storage lib is the shape that rule is
+// asking for, so this is the rule working rather than an exception to it.
+//
+// Both helpers are deliberately tiny and status-blind: this layer stores and
+// reads a URL. The ROUTES own who may WRITE it (the task's claim holder) and who
+// may SEE it (whoever may already read the task's value_summary — the predicate
+// is task-visuals.isPubliclyViewable).
+
+// The published doorway — a module never requires a core internal.
+const { pool } = require('../../src/module-api');
+
+// Set (or clear) a task's visual. Returns the updated row, or null when the task
+// does not exist. The caller reads the PREVIOUS visual_url through
+// getTaskVisualAccess first (it already does, to authorize) and unlinks the
+// superseded file after this returns.
+async function setTaskVisual({ taskId, visualUrl = null, visualAlt = null }) {
+  const { rows } = await pool.query(
+    `UPDATE tasks SET visual_url = $2, visual_alt = $3, updated_at = now()
+      WHERE id = $1 RETURNING id, visual_url, visual_alt`,
+    [taskId, visualUrl, visualAlt]
+  );
+  return rows[0] ?? null;
+}
+
+// The minimum a serve route needs to decide a stored image's audience: does the
+// task exist, is it already-public work, and is it security-sensitive. Kept to
+// these four columns on purpose — a gate must not be able to leak anything else
+// about a task it is about to refuse.
+async function getTaskVisualAccess(taskId) {
+  const { rows } = await pool.query(
+    `SELECT id, status, security_sensitive, visual_url FROM tasks WHERE id = $1`,
+    [taskId]
+  );
+  return rows[0] ?? null;
+}
+
+module.exports = { setTaskVisual, getTaskVisualAccess };

package/modules/lifecycle/task-visuals.js

@@ -0,0 +1,270 @@
+'use strict';
+
+// Task-visual storage — the OPTIONAL image a builder attaches to a shipped task
+// (task 1003109, goal 1000072 "Human legibility", from owner idea 1000400).
+//
+// WHY. `value_summary` already gives a reader the plain-language "what this
+// means" line at ship time. What a non-engineer still could not get is a PICTURE:
+// a screenshot of the surface that changed, a before/after, a diagram. Today the
+// only visual path is a Discord post, which sits outside the ledger and expires.
+// This is that same claim in another medium — so it is stored beside the summary,
+// rendered exactly where the summary is rendered, and is ALWAYS optional: a task
+// with no visual is complete, and nothing on the ship path blocks on its absence.
+//
+// This module is the pure-ish storage core: where files live, how a filename is
+// validated (path-traversal-safe), which task a stored name belongs to, and how
+// one uploaded buffer is screened + written. No express, no db — it unit-tests
+// with a temp dir and a Buffer.
+//
+// DELIBERATE DUPLICATION with modules/discord/bug-attachments.js (the ADR 0091 §2
+// "boundary-forced duplication is allowed + documented" rule): that lib is the
+// worked example this one follows, but it lives in a SIBLING module and ADR 0083
+// forbids requiring one module from another. So the extension allowlist, the
+// magic-byte sniff and the resolveSafe belt-and-braces are re-stated here rather
+// than imported. Same shapes on both sides; keep them in sync. The one real
+// difference is the INTAKE: bug-attachments DOWNLOADS from the Discord CDN (hence
+// its host allowlist + SSRF guard), while a visual is UPLOADED as bytes by the
+// shipping builder — so there is no outbound fetch here to defend.
+//
+// ANTI-ABUSE (the "must not become an arbitrary-file host" posture): an
+// allowlisted extension only, a magic-byte sniff so a mislabeled content-type
+// cannot smuggle a non-image onto disk, a per-image size cap, and a stored
+// filename shape the serve route validates exactly. The serve route adds
+// `nosniff` + `Content-Disposition: inline` so a stored byte-string can never be
+// interpreted as script by a browser on our own origin.
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs'); // readImageFile is the CLI's synchronous intake.
+const crypto = require('node:crypto');
+
+// ext ⇄ content-type for the formats we accept. SVG is deliberately ABSENT: it is
+// an executable document (inline <script>), and these are served from our own
+// origin.
+const EXT_BY_TYPE = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+};
+const TYPE_BY_EXT = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+};
+
+const MAX_BYTES = 4 * 1024 * 1024; // 4 MB — a screenshot, not an asset library.
+const MAX_ALT_LENGTH = 300;        // the caption/alt text stored beside it.
+
+// Stored filenames are SERVER-generated, never user-supplied: a fixed shape we
+// can validate exactly, carrying the task id so the serve route can resolve the
+// image's privacy posture from the task it belongs to without a second lookup
+// table. This regex is the whole path-traversal defense — the serve route only
+// ever opens a name that matches it.
+const NAME_RE = /^task-(\d{1,12})-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
+
+// Where visuals live. Outside the git tree (a `var/` dir) so a deploy's
+// `git reset --hard` / pull never wipes them; gitignored. Env override for tests.
+function visualsDir() {
+  return process.env.TASK_VISUALS_DIR
+    || path.join(__dirname, '..', '..', 'var', 'task-visuals');
+}
+
+// PURE — is this a well-formed, server-generated visual name?
+function isSafeName(name) {
+  return typeof name === 'string' && NAME_RE.test(name);
+}
+
+// PURE — which task does a stored name belong to? Returns the numeric id, or
+// null for any name that isn't well-formed. The serve route's privacy gate reads
+// the task's status through this, so an unparseable name fails CLOSED.
+function taskIdFromName(name) {
+  if (typeof name !== 'string') return null;
+  const m = NAME_RE.exec(name);
+  return m ? Number(m[1]) : null;
+}
+
+// PURE — resolve a name to an absolute path INSIDE visualsDir, or null if the
+// name is unsafe or would escape the dir. Belt (regex) and braces (prefix check
+// on the resolved path).
+function resolveSafe(name, { dir = visualsDir() } = {}) {
+  if (!isSafeName(name)) return null;
+  const root = path.resolve(dir);
+  const p = path.resolve(root, name);
+  if (p !== path.join(root, name)) return null;
+  if (!p.startsWith(root + path.sep)) return null;
+  return p;
+}
+
+// PURE — the content-type to serve a stored file with (from its extension).
+function contentTypeForName(name) {
+  const ext = String(name).split('.').pop().toLowerCase();
+  return TYPE_BY_EXT[ext] || 'application/octet-stream';
+}
+
+// PURE — confirm the bytes really are the claimed image format (magic bytes).
+function sniffMatches(buf, ext) {
+  if (!buf || buf.length < 12) return false;
+  switch (ext) {
+    case 'png':
+      return buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+    case 'jpg':
+      return buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff;
+    case 'gif':
+      return buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38;
+    case 'webp':
+      return (
+        buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 && // 'RIFF'
+        buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50 // 'WEBP'
+      );
+    default:
+      return false;
+  }
+}
+
+// PURE — screen one uploaded buffer against the declared content-type. Returns
+// { ok:true, ext } or { ok:false, reason } — never throws. Exported separately
+// from the write so every refusal is pinned by a DB-free, fs-free unit test.
+function screenImage(buf, contentType) {
+  const rawType = String(contentType || '').split(';')[0].trim().toLowerCase();
+  const ext = EXT_BY_TYPE[rawType];
+  if (!ext) return { ok: false, reason: 'bad_type', type: rawType };
+  if (!buf || buf.length === 0) return { ok: false, reason: 'empty' };
+  if (buf.length > MAX_BYTES) return { ok: false, reason: 'too_big', bytes: buf.length };
+  if (!sniffMatches(buf, ext)) return { ok: false, reason: 'sniff_mismatch' };
+  return { ok: true, ext };
+}
+
+// PURE — THE AUDIENCE PREDICATE. A visual has no audience of its own: it is the
+// same claim as the task's value_summary in another medium, so it is viewable by
+// whoever may already read that summary. Public work is `shipped`|`confirmed` —
+// byte-for-byte the gate src/bongos/routes/public.js:projectPublicTask uses to
+// decide whether a title/value_summary reaches the open web.
+//
+// The ONE deliberate narrowing: a security_sensitive task's image stays
+// builders-only even once shipped. A summary line is a sentence its author chose;
+// a screenshot shows whatever was on the screen, and on a security task that is
+// the wrong thing to publish by default. Anything not public here is still served
+// to any authenticated builder, so nothing is HIDDEN by this — only un-published.
+//
+// MIRRORED IN SQL: modules/lifecycle/db.js:recentShippedTasks nulls visual_url for
+// a security_sensitive row on the public feed, so the feed and this gate agree
+// (the feed never learns the flag itself). Change one, change the other.
+function isPubliclyViewable(task) {
+  if (!task) return false;
+  if (task.security_sensitive === true) return false;
+  return task.status === 'shipped' || task.status === 'confirmed';
+}
+
+// PURE — the public URL a stored file is served at. One definition, so the write
+// path and the docs cannot drift from the route.
+//
+// The CANONICAL prefix (src/bongos/api-prefix.js) is hard-coded rather than
+// imported: this lib is deliberately core-free so it unit-tests with a Buffer and
+// a temp dir, and the doorway does not publish the prefix. It is safe to hard-code
+// because BOTH prefixes are permanent — '/api/gds' is a forever alias for shipped
+// Dev Box binaries and the off-box status mirror — so a URL stored under either
+// keeps resolving, and every renderer's guard accepts both.
+const SERVE_PREFIX = '/api/bongos/task-visuals';
+function urlForName(name) {
+  return `${SERVE_PREFIX}/${name}`;
+}
+
+// PURE — normalize the caption/alt text: trimmed, length-bounded, newlines
+// flattened (it renders into an `alt` attribute). Empty → null.
+function normalizeAlt(alt) {
+  const s = String(alt == null ? '' : alt).replace(/\s+/g, ' ').trim().slice(0, MAX_ALT_LENGTH);
+  return s || null;
+}
+
+// Read one image OFF DISK and screen it — the CLI intake (`ship.js --visual`,
+// `bongos task visual`). It lives here, beside the screening it wraps, so the two
+// CLI call sites cannot drift from each other or from the upload route: what a
+// terminal accepts is exactly what the server accepts. Returns
+// { ok:true, buf, contentType } or { ok:false, message } — the message is written
+// for a person reading a terminal, not for a log.
+function readImageFile(file) {
+  const resolved = path.resolve(String(file || ''));
+  let buf;
+  try {
+    if (!fsSync.statSync(resolved).isFile()) return { ok: false, message: 'that path is not a file.' };
+    buf = fsSync.readFileSync(resolved);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: false, message: 'no such file.' };
+    return { ok: false, message: err && err.message ? err.message : 'could not be read.' };
+  }
+  const rawExt = path.extname(resolved).slice(1).toLowerCase();
+  const ext = rawExt === 'jpeg' ? 'jpg' : rawExt;
+  const contentType = TYPE_BY_EXT[ext];
+  if (!contentType) {
+    return { ok: false, message: `unsupported file type "${rawExt || '(none)'}". Accepted: ${Object.keys(TYPE_BY_EXT).join(', ')}.` };
+  }
+  const screened = screenImage(buf, contentType);
+  if (!screened.ok) {
+    const why = {
+      too_big: `it is ${Math.round(buf.length / 1024)} KB — the cap is ${Math.round(MAX_BYTES / 1024 / 1024)} MB.`,
+      empty: 'the file is empty.',
+      sniff_mismatch: `the bytes are not really a ${ext} image (the extension and the contents disagree).`,
+      bad_type: `unsupported file type "${rawExt}".`,
+    }[screened.reason] || `it was refused (${screened.reason}).`;
+    return { ok: false, message: why };
+  }
+  return { ok: true, buf, contentType };
+}
+
+// Screen + write one uploaded image. Returns { ok:true, file, url, bytes } or
+// { ok:false, reason } on a refusal (never throws on a refusal; an unexpected fs
+// error propagates for the caller to wrap).
+async function persistImageBuffer(buf, { taskId, contentType, dir = visualsDir() } = {}) {
+  const id = Number(taskId);
+  if (!Number.isInteger(id) || id <= 0 || String(id).length > 12) {
+    return { ok: false, reason: 'bad_task_id' };
+  }
+  const screened = screenImage(buf, contentType);
+  if (!screened.ok) return screened;
+  const file = `task-${id}-${crypto.randomBytes(8).toString('hex')}.${screened.ext}`;
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, file), buf, { mode: 0o640 });
+  return { ok: true, file, url: urlForName(file), bytes: buf.length };
+}
+
+// Best-effort delete of a stored file, by name or by its served URL. Used when a
+// visual is REPLACED or removed, so a superseded image doesn't linger on disk.
+// Never throws — an already-absent file is a success.
+async function deleteStored(nameOrUrl, { dir = visualsDir() } = {}) {
+  const name = String(nameOrUrl == null ? '' : nameOrUrl).split('/').pop();
+  const p = resolveSafe(name, { dir });
+  if (!p) return false;
+  try {
+    await fs.unlink(p);
+    return true;
+  } catch (err) {
+    // An already-absent file IS the desired state. Any other failure leaves an
+    // unreferenced file on disk, which is inert — the caller is best-effort and
+    // the boolean is the whole report, so this stays a silent, logger-free lib.
+    if (err && err.code === 'ENOENT') return true;
+    return false;
+  }
+}
+
+module.exports = {
+  EXT_BY_TYPE,
+  TYPE_BY_EXT,
+  MAX_BYTES,
+  MAX_ALT_LENGTH,
+  visualsDir,
+  isSafeName,
+  taskIdFromName,
+  resolveSafe,
+  contentTypeForName,
+  sniffMatches,
+  screenImage,
+  readImageFile,
+  normalizeAlt,
+  urlForName,
+  SERVE_PREFIX,
+  isPubliclyViewable,
+  persistImageBuffer,
+  deleteStored,
+};

package/modules/status-ui/public/status.js

@@ -912,6 +912,32 @@ let _shippedPage = 0;
 // in index.html is also pre-selected to "30" so the two stay aligned.
 let _shippedRange = '30';
 
+// task 1003109: build the thumbnail node for one shipped row, or null when the
+// row has no visual. Built with DOM nodes (not innerHTML) like the rest of this
+// file, and the URL is matched against the exact shape the server mints before it
+// reaches an href/src — this page renders UNAUTHENTICATED data on a public host,
+// so it treats its own API's strings as data, not as markup.
+const VISUAL_URL_RE = /^\/api\/(gds|bongos)\/task-visuals\/task-\d+-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
+function shippedVisualEl(t) {
+  const url = String((t && t.visual_url) || '');
+  if (!VISUAL_URL_RE.test(url)) return null;
+  const alt = String((t && t.visual_alt) || `Visual for task ${(t && t.id) || ''}`).trim();
+  const a = document.createElement('a');
+  // `API` is '' on the droplet (same-origin) and the droplet's origin on the
+  // off-box GitHub Pages mirror — the same prefix every fetch on this page uses.
+  a.href = `${API}${url}`;
+  a.target = '_blank';
+  a.rel = 'noopener';
+  a.title = alt;
+  const img = document.createElement('img');
+  img.className = 'shipped__visual';
+  img.src = `${API}${url}`;
+  img.alt = alt;
+  img.loading = 'lazy';
+  a.appendChild(img);
+  return a;
+}
+
 function renderShippedPage() {
   clear(els.shipped);
   const items = _shippedItems;
@@ -949,11 +975,18 @@ function renderShippedPage() {
     ver.textContent = t.version_id;
     title.appendChild(ver);
     title.append(t.value_summary || t.title);
+    // task 1003109 (goal 1000072): the optional ship-time VISUAL, beside the
+    // summary it restates. This surface is the whole reason the feature exists —
+    // an unauthenticated reader who does not read code, seeing what shipped. Only
+    // already-public, non-security-sensitive work carries one here (the server
+    // nulls the rest out of this feed), and a task without one draws nothing.
+    const thumb = shippedVisualEl(t);
     const meta = document.createElement('p');
     meta.className = 'shipped__meta';
     const by = t.display_name || t.github_login;
     meta.textContent = `${by ? `inscribed by ${by} · ` : ''}${fmtRelativeTime(t.shipped_at)}`;
     li.appendChild(title);
+    if (thumb) li.appendChild(thumb);
     li.appendChild(meta);
     els.shipped.appendChild(li);
   }

package/modules/status-ui/public/style.css

@@ -598,6 +598,20 @@ main {
   margin: 0;
 }
 
+/* task 1003109: the optional ship-time visual on a public shipped row. Small on
+   purpose — this is a scannable feed, and the thumbnail links to the full-size
+   image for anyone who wants to look properly. Absent on most rows; nothing is
+   drawn when a task has no visual. */
+.shipped__visual {
+  display: block;
+  width: 40px;
+  height: 40px;
+  object-fit: cover;
+  margin: 0 0 6px;
+  border: 1px solid var(--rule, rgba(0, 0, 0, 0.15));
+  border-radius: 3px;
+}
+
 .shipped__version {
   font-family: var(--font-display);
   font-weight: 500;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.349",
+  "version": "1.19.350",
   "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",