@bongos/core 1.19.349 → 1.19.350

package/scripts/gds/ship-flow.js

@@ -15,6 +15,8 @@ const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-m
 const { matchOne } = require('../../src/bongos/path-match');
 const { runShipGate } = require('./sandbox-stage');
 const { captureSurpriseLearning, promptSurprise } = require('./ship-surprise.js');
+// task 1003109: the optional `--visual` leg of a ship (goal 1000072).
+const shipVisual = require('./ship-visual.js');
 const { gitOk } = require('./ship-git.js');
 const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight } = require('./ship-preflight-steps.js');
 const { applyBaseOverride, computeChangedFiles, computeGraderBaseline, runSmokeAsync } = require('./ship-grade.js');
@@ -35,7 +37,7 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--visual <image>] [--visual-alt "caption"] [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
     console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
     process.exit(2);
   }
@@ -94,6 +96,10 @@ async function shipMain() {
     console.log(`--base: grading ${res.sha.slice(0, 9)}...HEAD — the task's real committed diff (work already on main). Graded via the rank-open path; no --allow-empty needed.`);
   }
 
+  // task 1003109: screen --visual BEFORE any heavy work, so bad input aborts with
+  // the claim STILL ACTIVE (the --base posture above). null when none was asked for.
+  const visual = shipVisual.fromArgs(args);
+
   const me = noteServerReward(await (await cliClient()).me.getMe());
   if (!me.ok) {
     console.error('failed to load profile:', me.data);
@@ -456,6 +462,10 @@ async function shipMain() {
 
   const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
   console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+  // task 1003109: attach the optional visual now the claim has resolved (the upload
+  // gate is "the task's last claim holder" — still us). Best-effort: it prints its
+  // own warning, and a failed picture never fails a successful ship.
+  await shipVisual.upload({ taskId, visual, client: await cliClient(), errorLine: apiErrorLine });
   // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
   markShipProgress('resolved', taskId);
 

package/scripts/gds/ship-visual.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// scripts/gds/ship-visual.js — the `--visual` leg of a ship (task 1003109, goal
+// 1000072 "Human legibility").
+//
+// A shipped task can carry an optional IMAGE alongside its value summary: a
+// screenshot of the surface that changed, a before/after, a diagram — so a reader
+// who does not read code can SEE what shipped instead of reading about it (owner
+// idea 1000400). ship.js owns the ship; this file owns the picture.
+//
+// Its own file, not another 60 lines inside the 4,600-line ship.js, because the
+// size ratchet (fitness-ratchets.js, task 1003129) is shrink-only — and because
+// the two things really are separable: the ship must not care whether a visual
+// came along.
+//
+// THE ONE RULE HERE: a visual never costs a builder their ship. Bad input is
+// caught BEFORE the claim resolves (a usage error, claim intact); a failed upload
+// happens AFTER it and is a warning, never a failure.
+
+const path = require('node:path');
+const { arg } = require('./cli-lib');
+// Reading + screening is the SERVER's own lib, so a terminal refuses exactly what
+// the upload route would refuse.
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+
+// Parse + screen `--visual <file> [--visual-alt "caption"]` from an argv slice.
+// Returns null when no visual was asked for, or { buf, contentType, alt, name }.
+// EXITS (code 2) on bad input: this runs before any heavy work, so a wrong path
+// costs the builder a retyped command, not a claim. Pure enough to reason about;
+// the exit is the deliberate CLI edge.
+function fromArgs(args) {
+  const file = arg('--visual', args) || '';
+  if (!file) return null;
+  const read = taskVisuals.readImageFile(file);
+  if (!read.ok) {
+    console.error(`Ship aborted: --visual ${file} — ${read.message}`);
+    console.error('Fix the path (or drop --visual: a visual is always optional). No claim resolved, no credits awarded.');
+    process.exit(2);
+  }
+  const visual = { ...read, alt: arg('--visual-alt', args) || '', name: path.basename(file) };
+  console.log(`--visual: ${visual.name} (${visual.contentType}, ${Math.round(visual.buf.length / 1024)} KB) — uploaded after the claim resolves.`);
+  return visual;
+}
+
+// Upload the screened visual to the task. BEST-EFFORT BY DESIGN: called AFTER the
+// claim has resolved, so a failure here must never fail the ship — the work
+// landed, only the picture did not. Returns true when it stuck; prints a
+// one-line, actionable warning and returns false when it did not.
+async function upload({ taskId, visual, client, errorLine }) {
+  if (!visual) return false;
+  const r = await client.tasks.postTasksIdVisual({
+    id: taskId,
+    body: {
+      image_b64: visual.buf.toString('base64'),
+      content_type: visual.contentType,
+      ...(visual.alt ? { alt: visual.alt } : {}),
+    },
+  });
+  if (r.ok) {
+    console.log("Visual attached — it renders wherever this task's value summary does.");
+    return true;
+  }
+  console.warn(`Note: the visual did not upload (${errorLine(r.data, r.status)}). The ship is unaffected — re-attach any time with:`);
+  console.warn(`  node scripts/gds/task.js visual ${taskId} <image> [--alt "caption"]`);
+  return false;
+}
+
+module.exports = { fromArgs, upload };

package/scripts/gds/task.js

@@ -11,11 +11,16 @@
 //                   [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]
 //                   [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]
 //   bongos task show <id> [--json]
+//   bongos task visual <id> <image> [--alt "caption"]   attach/replace the ship-time visual
+//   bongos task visual <id> --remove                    take it back off
 //
 // Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
 // CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
 
 const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
+// task 1003109: the ship-time VISUAL. The CLI screens the file with the SERVER's
+// own constants, so what it accepts is exactly what the upload route accepts.
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
 
 // Valid enums (mirrors the server's task-classifier vocab; a friendly client-side check
 // so an obvious typo fails before the round-trip — the server stays authoritative).
@@ -77,6 +82,8 @@ function usage() {
   console.error('                  [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]');
   console.error('                  [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]');
   console.error('  bongos task show <id> [--json]');
+  console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
+  console.error('  bongos task visual <id> --remove                    remove it again');
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -149,6 +156,60 @@ async function cmdShow(args) {
   if (task.description) console.log(`\n${task.description}`);
 }
 
+
+// ---- bongos task visual (task 1003109, goal 1000072) ------------------------
+//
+// A shipped task can carry a VISUAL alongside its value summary — a screenshot of
+// the surface that changed, a before/after, a diagram — so a reader who does not
+// read code can SEE what changed. `ship.js --visual` is the usual path; this is
+// the after-the-fact one: attach the picture you forgot, replace the wrong one,
+// or take it back off. Same server gate either way — the task's claim holder (or
+// an Archon). Always optional: no task needs one.
+async function cmdVisual(args) {
+  const id = Number(args[0]);
+  if (!Number.isInteger(id) || id <= 0) {
+    console.error('usage: bongos task visual <id> <image> [--alt "caption"]');
+    console.error('       bongos task visual <id> --remove');
+    process.exit(2);
+  }
+  const api = await cliClient();
+
+  if (hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisual({ id });
+    if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+    if (!r.ok) { console.error(`visual remove failed (${r.status}):`, r.data); process.exit(1); }
+    console.log(`✓ Task #${id} no longer carries a visual.`);
+    return;
+  }
+
+  // The image is POSITIONAL — `visual <id> <image>`. Deliberately not "the first
+  // arg that isn't a flag": with `--alt "a caption" shot.png` that heuristic
+  // picks up the caption as the filename.
+  const file = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  if (!file) {
+    console.error('usage: bongos task visual <id> <image> [--alt "caption"]');
+    process.exit(2);
+  }
+  // Reading + screening is the SERVER's own lib (shared with ship.js --visual),
+  // so a terminal refuses exactly what the upload route would refuse.
+  const visual = taskVisuals.readImageFile(file);
+  if (!visual.ok) {
+    console.error(`${file} — ${visual.message}`);
+    process.exit(2);
+  }
+
+  const alt = arg('--alt', args) || '';
+  const r = await api.tasks.postTasksIdVisual({
+    id,
+    body: { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) },
+  });
+  if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+  if (r.status === 403) { console.error(`Only task #${id}'s claim holder (or an Archon) may attach its visual.`); process.exit(1); }
+  if (!r.ok) { console.error(`visual upload failed (${r.status}):`, r.data); process.exit(1); }
+  console.log(`✓ Task #${id} now carries a visual (${Math.round(visual.buf.length / 1024)} KB).`);
+  console.log('  It renders wherever this task\'s value summary does.');
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const sub = args[0];
@@ -156,6 +217,7 @@ async function main() {
   await requireSession();
   if (sub === 'new') return cmdNew(args.slice(1));
   if (sub === 'show') return cmdShow(args.slice(1));
+  if (sub === 'visual') return cmdVisual(args.slice(1));
   console.error(`task: unknown subcommand "${sub}"\n`); usage(); process.exit(2);
 }
 

package/src/bongos/routes/public.js

@@ -43,6 +43,14 @@ function projectPublicTask(task) {
     payload.title = task.title;
     payload.value_summary = task.value_summary ?? null;
     payload.shipped_at = task.shipped_at ?? null;
+    // task 1003109: the ship-time VISUAL travels with the summary it restates —
+    // one claim, one audience, in both media. The extra `security_sensitive`
+    // narrowing is the serve route's own gate (task-visuals.isPubliclyViewable);
+    // publishing a URL this projection would then refuse to serve would be a
+    // broken image, so the two agree here.
+    const visualIsPublic = task.security_sensitive !== true;
+    payload.visual_url = visualIsPublic ? (task.visual_url ?? null) : null;
+    payload.visual_alt = visualIsPublic ? (task.visual_alt ?? null) : null;
   }
   return payload;
 }

package/src/bongos/routes.js

@@ -86,7 +86,11 @@ function buildGdsRouter() {
       req.path === '/memory/sync' ||
       req.path === '/sessions' ||
       req.path === '/llm-cache/store' ||
-      /^\/tasks\/\d+\/publish-branch$/.test(req.path)
+      /^\/tasks\/\d+\/publish-branch$/.test(req.path) ||
+      // task 1003109: the ship-time task visual — a base64 image up to ~5.3 MB
+      // encoded (4 MB decoded). Same dynamic-:id pattern as publish-branch above;
+      // modules/lifecycle/routes/task-visuals.js mounts its own 8 MB parser.
+      /^\/tasks\/\d+\/visual$/.test(req.path)
     ) return next();
     return globalJson(req, res, next);
   });

package/src/module-api.js

@@ -1128,8 +1128,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.347 with no explicit bump. run 32802746363. (task 1002620)
 //   1.19.349 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.348 with no explicit bump. run 32803276871. (task 1002620)
+//   1.19.350 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.349 with no explicit bump. run 32810944115. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.349'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.350'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/task_visual_route_gate.mjs

@@ -0,0 +1,151 @@
+// tests/task_visual_route_gate.mjs
+//
+// Route-level proof of the ONE rule behind ship-time task visuals (task 1003109,
+// ADR 0184): a visual has no audience of its own — it inherits the audience of the
+// value_summary it restates. Already-public work (shipped|confirmed, not
+// security_sensitive) serves unauthenticated; EVERYTHING else falls through to
+// auth.requireBuilder and never past it.
+//
+// The unit tests in tests/task_visuals.mjs pin the predicate. This pins the WIRING
+// — that the handler actually consults it, in the right order, and fails closed on
+// every miss. It runs the real Express router with the data layer and the auth gate
+// stubbed at the module boundary; no DB, no network, no session.
+//
+// Run:  node tests/task_visual_route_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+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-visualroute-${process.pid}`);
+process.env.TASK_VISUALS_DIR = TMP;
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const visualDb = require('../modules/lifecycle/task-visual-db.js');
+const visuals = require('../modules/lifecycle/task-visuals.js');
+
+// ---- stubs at the module boundary -----------------------------------------
+// The route reads `db.getTaskVisualAccess` and `auth.requireBuilder` off these
+// module objects at CALL time, so replacing the properties is enough — no loader
+// tricks, and the router under test is the real one.
+let taskRow = null;      // what the "DB" says about the task
+let lookupThrows = false;
+visualDb.getTaskVisualAccess = async () => {
+  if (lookupThrows) throw new Error('simulated DB outage');
+  return taskRow;
+};
+let authCalls = 0;
+api.requireBuilder = (req, res) => {
+  authCalls++;
+  // Stand in for the real gate's deny path: it owns its own response, so reaching
+  // here means the request was NOT served publicly.
+  res.status(401).json({ error: 'unauthenticated' });
+};
+
+const buildRouter = require('../modules/lifecycle/routes/visuals.js');
+
+// res.fail is composed at the kernel level in production; supply the same shape.
+const app = express();
+app.use((req, res, next) => {
+  res.fail = (code, status) => res.status(typeof status === 'number' ? status : (status && status.status) || 500).json({ error: code });
+  next();
+});
+app.use(buildRouter());
+
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const base = `http://127.0.0.1:${server.address().port}`;
+
+// A real stored file, so a successful gate actually streams bytes.
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const stored = await visuals.persistImageBuffer(PNG, { taskId: 4242, contentType: 'image/png', dir: TMP });
+const NAME = stored.file;
+
+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}`); });
+}
+async function get(name) {
+  authCalls = 0;
+  const res = await fetch(`${base}/task-visuals/${name}`);
+  return { status: res.status, authCalls, buf: Buffer.from(await res.arrayBuffer()), headers: res.headers };
+}
+
+console.log('Task-visual serve gate (task 1003109 / ADR 0184):');
+
+await t('a SHIPPED task serves its visual to an unauthenticated caller', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  const r = await get(NAME);
+  assert.equal(r.status, 200);
+  assert.equal(r.authCalls, 0, 'public work must not be sent through the auth gate');
+  assert.deepEqual(r.buf, PNG);
+  assert.equal(r.headers.get('content-type'), 'image/png');
+  assert.equal(r.headers.get('x-content-type-options'), 'nosniff');
+  assert.equal(r.headers.get('content-disposition'), 'inline');
+  assert.match(r.headers.get('cache-control'), /^public,/);
+});
+
+await t('a CONFIRMED task is public too — the same set as a public value_summary', async () => {
+  taskRow = { id: 4242, status: 'confirmed', security_sensitive: false };
+  assert.equal((await get(NAME)).status, 200);
+});
+
+await t('IN-FLIGHT work never serves publicly — it falls through to requireBuilder', async () => {
+  for (const status of ['backlog', 'ready', 'active', 'completed', 'abandoned']) {
+    taskRow = { id: 4242, status, security_sensitive: false };
+    const r = await get(NAME);
+    assert.equal(r.status, 401, status);
+    assert.equal(r.authCalls, 1, `${status} must reach the auth gate`);
+    assert.equal(r.buf.length && r.buf.includes(PNG), false, `${status} must not leak bytes`);
+  }
+});
+
+await t('a SHIPPED but security-sensitive task stays builders-only (the one narrowing)', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: true };
+  const r = await get(NAME);
+  assert.equal(r.status, 401);
+  assert.equal(r.authCalls, 1);
+});
+
+await t('an ABSENT task fails closed — no public serve, no crash', async () => {
+  taskRow = null;
+  const r = await get(NAME);
+  assert.equal(r.status, 401);
+  assert.equal(r.authCalls, 1);
+});
+
+await t('a DB outage fails closed rather than opening the door', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  lookupThrows = true;
+  const r = await get(NAME);
+  lookupThrows = false;
+  assert.equal(r.status, 401, 'a lookup failure must not be read as "public"');
+  assert.equal(r.authCalls, 1);
+});
+
+await t('a malformed name is refused BEFORE any lookup (the traversal wall)', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  for (const bad of ['..%2F..%2Fetc%2Fpasswd', 'screenshot.png', 'task-4242-0011.png', 'task-4242-0011223344556677.svg']) {
+    const r = await get(bad);
+    assert.equal(r.status, 400, bad);
+    assert.equal(r.authCalls, 0, `${bad} must not even reach the task lookup`);
+  }
+});
+
+await t('a well-formed name with no file on disk is a 404, not a 200', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  const r = await get('task-4242-ffffffffffffffff.png');
+  assert.equal(r.status, 404);
+});
+
+server.close();
+await fs.rm(TMP, { recursive: true, force: true });
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/task_visuals.mjs

@@ -0,0 +1,200 @@
+// tests/task_visuals.mjs
+//
+// Unit tests for ship-time task visuals (task 1003109, goal 1000072 "Human
+// legibility"): filename safety / path-traversal, the task-id a stored name
+// belongs to, the upload screening (type allowlist, size cap, magic-byte sniff),
+// the AUDIENCE predicate that decides whether an image is public, alt-text
+// normalization, and persist/delete against a temp dir. No network, no DB.
+//
+// Run:  node tests/task_visuals.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);
+
+// Point storage at a throwaway dir BEFORE requiring the module.
+const TMP = path.join(os.tmpdir(), `otb-taskvisual-${process.pid}`);
+process.env.TASK_VISUALS_DIR = TMP;
+const tv = require('../modules/lifecycle/task-visuals.js');
+const kit = require('../modules/hall-ui/public/hall-kit.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}`); });
+}
+
+// Minimal real headers, long enough for the sniff's 12-byte floor.
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const JPG = Buffer.from('ffd8ffe000104a46494600010101', 'hex');
+const GIF = Buffer.from('4749463839610100010080000000', 'hex');
+const WEBP = Buffer.concat([Buffer.from('RIFF'), Buffer.from([0, 0, 0, 0]), Buffer.from('WEBPVP8 ')]);
+const NOT_AN_IMAGE = Buffer.from('<?php system($_GET[0]); ?>            ');
+
+console.log('Ship-time task visuals (task 1003109):');
+
+// ---- isSafeName / resolveSafe / taskIdFromName -----------------------------
+await t('isSafeName: accepts a server-generated name, rejects junk + traversal', () => {
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.png'), true);
+  assert.equal(tv.isSafeName('task-1-aabbccddeeff0011.webp'), true);
+  // Not the minted shape: user-chosen names, wrong hex length, bad extension.
+  assert.equal(tv.isSafeName('screenshot.png'), false);
+  assert.equal(tv.isSafeName('task-1003109-00112233.png'), false);
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.svg'), false);
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.png.php'), false);
+  // Traversal, absolute paths, and a name that merely CONTAINS a valid one.
+  assert.equal(tv.isSafeName('../task-1003109-0011223344556677.png'), false);
+  assert.equal(tv.isSafeName('/etc/passwd'), false);
+  assert.equal(tv.isSafeName('a/task-1003109-0011223344556677.png'), false);
+  assert.equal(tv.isSafeName(null), false);
+  assert.equal(tv.isSafeName(42), false);
+});
+
+await t('resolveSafe: stays inside the dir, and returns null for anything unsafe', () => {
+  const p = tv.resolveSafe('task-7-0011223344556677.png', { dir: TMP });
+  assert.equal(p, path.join(path.resolve(TMP), 'task-7-0011223344556677.png'));
+  assert.equal(tv.resolveSafe('../../etc/passwd', { dir: TMP }), null);
+  assert.equal(tv.resolveSafe('task-7-0011223344556677.png/../../x', { dir: TMP }), null);
+});
+
+await t('taskIdFromName: reads the owning task, and fails closed on a bad name', () => {
+  assert.equal(tv.taskIdFromName('task-1003109-0011223344556677.png'), 1003109);
+  // Fails CLOSED: the serve route looks the task up through this, and a null id
+  // resolves to no task, which resolves to "not public" — never to open access.
+  assert.equal(tv.taskIdFromName('../secrets.png'), null);
+  assert.equal(tv.taskIdFromName(''), null);
+});
+
+// ---- screening -------------------------------------------------------------
+await t('screenImage: accepts each allowlisted format with matching bytes', () => {
+  assert.deepEqual(tv.screenImage(PNG, 'image/png'), { ok: true, ext: 'png' });
+  assert.deepEqual(tv.screenImage(JPG, 'image/jpeg'), { ok: true, ext: 'jpg' });
+  assert.deepEqual(tv.screenImage(GIF, 'image/gif'), { ok: true, ext: 'gif' });
+  assert.deepEqual(tv.screenImage(WEBP, 'image/webp'), { ok: true, ext: 'webp' });
+  // A content-type with parameters still resolves.
+  assert.deepEqual(tv.screenImage(PNG, 'image/png; charset=binary'), { ok: true, ext: 'png' });
+});
+
+await t('screenImage: refuses a type outside the allowlist (SVG is executable)', () => {
+  assert.equal(tv.screenImage(PNG, 'image/svg+xml').ok, false);
+  assert.equal(tv.screenImage(PNG, 'text/html').ok, false);
+  assert.equal(tv.screenImage(PNG, 'application/octet-stream').ok, false);
+  assert.equal(tv.screenImage(PNG, '').ok, false);
+});
+
+await t('screenImage: a mislabeled content-type cannot smuggle a non-image in', () => {
+  const r = tv.screenImage(NOT_AN_IMAGE, 'image/png');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'sniff_mismatch');
+  // Right family, wrong format: JPEG bytes claiming to be a PNG.
+  assert.equal(tv.screenImage(JPG, 'image/png').reason, 'sniff_mismatch');
+});
+
+await t('screenImage: refuses empty and over-cap payloads', () => {
+  assert.equal(tv.screenImage(Buffer.alloc(0), 'image/png').reason, 'empty');
+  const huge = Buffer.concat([PNG, Buffer.alloc(tv.MAX_BYTES)]);
+  const r = tv.screenImage(huge, 'image/png');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'too_big');
+  assert.equal(r.bytes, huge.length);
+});
+
+// ---- the audience predicate ------------------------------------------------
+await t('isPubliclyViewable: already-public work only', () => {
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped' }), true);
+  assert.equal(tv.isPubliclyViewable({ status: 'confirmed' }), true);
+  // In-flight work is builders-only, exactly like its value_summary.
+  for (const status of ['backlog', 'ready', 'active', 'completed', 'abandoned']) {
+    assert.equal(tv.isPubliclyViewable({ status }), false, status);
+  }
+});
+
+await t('isPubliclyViewable: fails closed, and narrows on security_sensitive', () => {
+  assert.equal(tv.isPubliclyViewable(null), false);
+  assert.equal(tv.isPubliclyViewable(undefined), false);
+  assert.equal(tv.isPubliclyViewable({}), false);
+  // The one deliberate narrowing vs value_summary: a shipped security task's
+  // screenshot stays builders-only.
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped', security_sensitive: true }), false);
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped', security_sensitive: false }), true);
+});
+
+// ---- alt text --------------------------------------------------------------
+await t('normalizeAlt: flattens, trims, bounds — and empty becomes null', () => {
+  assert.equal(tv.normalizeAlt('  before  and\n after '), 'before and after');
+  assert.equal(tv.normalizeAlt(''), null);
+  assert.equal(tv.normalizeAlt('   '), null);
+  assert.equal(tv.normalizeAlt(null), null);
+  assert.equal(tv.normalizeAlt('x'.repeat(1000)).length, tv.MAX_ALT_LENGTH);
+});
+
+// ---- persist / delete ------------------------------------------------------
+await t('persistImageBuffer: writes a name the serve route accepts, under the right task', async () => {
+  const r = await tv.persistImageBuffer(PNG, { taskId: 1003109, contentType: 'image/png', dir: TMP });
+  assert.equal(r.ok, true);
+  assert.equal(tv.isSafeName(r.file), true);
+  assert.equal(tv.taskIdFromName(r.file), 1003109);
+  assert.equal(r.url, `/api/bongos/task-visuals/${r.file}`);
+  // Both prefixes are permanent aliases, so a URL minted under either resolves.
+  assert.equal(kit.isTaskVisualUrl(r.url), true);
+  assert.equal(r.bytes, PNG.length);
+  const onDisk = await fs.readFile(path.join(TMP, r.file));
+  assert.deepEqual(onDisk, PNG);
+});
+
+await t('persistImageBuffer: two writes never collide (a replace keeps the old file distinct)', async () => {
+  const a = await tv.persistImageBuffer(PNG, { taskId: 5, contentType: 'image/png', dir: TMP });
+  const b = await tv.persistImageBuffer(PNG, { taskId: 5, contentType: 'image/png', dir: TMP });
+  assert.notEqual(a.file, b.file);
+});
+
+await t('persistImageBuffer: refuses without writing anything', async () => {
+  const before = (await fs.readdir(TMP)).length;
+  assert.equal((await tv.persistImageBuffer(NOT_AN_IMAGE, { taskId: 1, contentType: 'image/png', dir: TMP })).reason, 'sniff_mismatch');
+  assert.equal((await tv.persistImageBuffer(PNG, { taskId: 0, contentType: 'image/png', dir: TMP })).reason, 'bad_task_id');
+  assert.equal((await tv.persistImageBuffer(PNG, { taskId: 'x', contentType: 'image/png', dir: TMP })).reason, 'bad_task_id');
+  assert.equal((await fs.readdir(TMP)).length, before);
+});
+
+await t('deleteStored: removes by name or URL, is idempotent, refuses a traversal', async () => {
+  const r = await tv.persistImageBuffer(PNG, { taskId: 9, contentType: 'image/png', dir: TMP });
+  assert.equal(await tv.deleteStored(r.url, { dir: TMP }), true);
+  // Idempotent — removing an already-absent visual is a success, so a replace
+  // whose old file was already swept doesn't error.
+  assert.equal(await tv.deleteStored(r.url, { dir: TMP }), true);
+  assert.equal(await tv.deleteStored('../../etc/passwd', { dir: TMP }), false);
+});
+
+// ---- the client-side URL guard --------------------------------------------
+await t('hall-kit: only a server-minted visual URL is ever rendered', () => {
+  assert.equal(kit.isTaskVisualUrl('/api/gds/task-visuals/task-1003109-0011223344556677.png'), true);
+  assert.equal(kit.isTaskVisualUrl('/api/bongos/task-visuals/task-1-aabbccddeeff0011.webp'), true);
+  // Anything that is not that exact shape renders nothing — including an
+  // absolute URL to another origin, and a javascript: payload.
+  assert.equal(kit.isTaskVisualUrl('https://evil.example/x.png'), false);
+  assert.equal(kit.isTaskVisualUrl('javascript:alert(1)'), false);
+  assert.equal(kit.isTaskVisualUrl('/api/gds/task-visuals/../../secrets'), false);
+  assert.equal(kit.isTaskVisualUrl(''), false);
+  assert.equal(kit.isTaskVisualUrl(null), false);
+});
+
+await t('hall-kit: no visual renders nothing at all — never a placeholder', () => {
+  assert.equal(kit.shipVisualThumbHtml({ id: 1 }), '');
+  assert.equal(kit.shipVisualThumbHtml({ id: 1, visual_url: null }), '');
+  assert.equal(kit.shipVisualThumbHtml(null), '');
+  const html = kit.shipVisualThumbHtml({ id: 1, visual_url: '/api/gds/task-visuals/task-1-0011223344556677.png', visual_alt: 'a "before" shot' });
+  assert.ok(html.includes('ship-visual-thumb'));
+  // The caption is attacker-adjacent text (a builder wrote it) — it must be escaped.
+  assert.ok(html.includes('&quot;before&quot;'));
+  assert.ok(!html.includes('"before"'));
+});
+
+// ---- cleanup ---------------------------------------------------------------
+await fs.rm(TMP, { recursive: true, force: true });
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);