@bongos/core 1.19.348 → 1.19.350

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.348",
+  "version": "1.19.350",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.348",
+      "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.348",
+  "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",

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-land.js

@@ -89,12 +89,23 @@ function formatPublishFailure(data, status, branch, opts = {}) {
   const envelopeDetails = (data && data.error && typeof data.error === 'object' && data.error.details) || null;
   const details = envelopeDetails || data || {};
   const label = message || code || (data && data.message) || `HTTP ${status}`;
-  // git stderr is multi-line; this is embedded mid-sentence in one log line.
+  // Flattened ONLY for the matchers below and the one-line summary. The readable
+  // copy is printed verbatim underneath (task 1003222): the server no longer clips
+  // stderr, and git's useful line is the LAST one, so collapsing a 20-line push
+  // failure into a single run-on sentence hides the very thing that was un-hidden.
   const reason = details.reason ? String(details.reason).replace(/\s+/g, ' ').trim() : '';
   const parts = [];
   if (details.step) parts.push(`step: ${details.step}`);
-  if (reason) parts.push(`reason: ${reason}`);
+  if (details.git_exit_code != null) parts.push(`git exit ${details.git_exit_code}`);
+  if (details.github_status != null) parts.push(`GitHub HTTP ${details.github_status}`);
+  if (details.timed_out) parts.push('TIMED OUT');
+  // The one-line summary stays short and scannable; the full text follows it.
+  if (reason) parts.push(`reason: ${reason.length > 200 ? `${reason.slice(0, 200)}…` : reason}`);
   let out = parts.length ? `${label} (${parts.join('; ')})` : label;
+
+  // ORDER MATTERS: summary, then the REMEDY, then the verbatim block last. The
+  // remedy is the actionable sentence and must not end up stranded below twenty
+  // lines of git chatter where it reads as a footnote to the quote.
   if (NON_FAST_FORWARD_RE.test(reason)) {
     out += opts.localHistoryRewritten === true
       ? ` — your LOCAL history was rewritten (a rebase or amend), so ${branch} is no longer a `
@@ -104,6 +115,17 @@ function formatPublishFailure(data, status, branch, opts = {}) {
       : ` — the server already moved ${branch}: fetch origin, reset onto origin/${branch}, `
         + 're-run the generators, and re-ship so the push fast-forwards.';
   }
+
+  // The untruncated remote message, verbatim and indented so it reads as a quotation
+  // rather than as more ship output. Only when it is multi-line — a single-line
+  // stderr is already fully present in the summary above, and repeating it is noise.
+  const full = details.reason ? String(details.reason).trimEnd() : '';
+  if (full && /\n/.test(full)) {
+    out += `\n\n  --- what the remote actually said ---\n${full.split('\n').map((l) => `  ${l}`).join('\n')}\n  --- end ---`;
+    if (details.reason_bytes != null && details.reason_bytes > full.length) {
+      out += `\n  (${details.reason_bytes} bytes at the server; the middle was omitted here)`;
+    }
+  }
   return out;
 }
 

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);
   });