@bongos/core 1.19.1063 → 1.19.1064

package/scripts/gds/ship-land.js

@@ -46,6 +46,12 @@ const { readCheckRollup, UNIT_REPORT_CONTEXT } = require('../../modules/lifecycl
 function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
 function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
 function landBailed(reason, nextStep = null, bailId = null) { return { ok: false, pending: false, reason, nextStep, bailId }; }
+// task 1004322 (ADR 0341 D7): the FOURTH outcome, and only a page tweak reaches it.
+// Its grade passed and its branch and PR are published, but nothing is landing and
+// nothing should: the artist approves the applied page first. Not a bail (nothing
+// failed, and the card must not say "Land it") and not pending (no auto-merge is
+// armed, so it does not land on its own).
+function landHeld({ prUrl = null } = {}) { return { ok: false, pending: false, held: true, reason: null, nextStep: null, prUrl }; }
 
 // ---------- which bails a PR can still land (task 1002572, part 2) ----------
 //
@@ -79,12 +85,17 @@ function strandCommand(taskId, via) {
 
 // ciLand — dispatch the 'ci' confirmed->shipped land to the local or the
 // server-mediated path. Async because the server path awaits GDS API calls.
-async function ciLand(taskId, branch, valueSummary) {
-  console.log('  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
+// opts.hold (task 1004322): PUBLISH ONLY — push the branch and open the PR, never
+// arm auto-merge and never poll for a land. A page tweak held for its artist takes
+// it; every other caller passes nothing and gets the unchanged path.
+async function ciLand(taskId, branch, valueSummary, opts = {}) {
+  console.log(opts.hold
+    ? '  held for the artist — publishing the branch and its PR only (no auto-merge, no land)'
+    : '  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
   if (pushVia() === 'server') {
-    return ciLandServer(taskId, branch, valueSummary);
+    return ciLandServer(taskId, branch, valueSummary, opts);
   }
-  return await ciLandLocal(taskId, branch, valueSummary);
+  return await ciLandLocal(taskId, branch, valueSummary, opts);
 }
 
 // task 1001916: render a FAILED POST /tasks/:id/publish-branch for the builder.
@@ -165,7 +176,7 @@ function formatPublishFailure(data, status, branch, opts = {}) {
 // hand the branch to the GDS, which pushes it + opens the PR + auto-merges with
 // the server-side credential. Requires a RE-AUTHED (non-box) cli session — a
 // box-scoped session is 403'd by the endpoint (it must `/builder-reauth` first).
-async function ciLandServer(taskId, branch, valueSummary) {
+async function ciLandServer(taskId, branch, valueSummary, { hold = false } = {}) {
   console.log('  ci-land: server-mediated publish (this machine has no GitHub push credential)');
   const headSha = gitOk('git rev-parse HEAD');
   // Make sure origin/main is current so the THIN bundle's `origin/main..HEAD`
@@ -195,9 +206,14 @@ async function ciLandServer(taskId, branch, valueSummary) {
       console.log(`  ci-land: server publish failed — ${e}. Task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
       return landBailed(`server publish failed — ${e}`, strandCommand(taskId, 'server'));
     }
-    console.log(`  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
+    // task 1004322: the server does not arm a held page tweak (it reads the hold
+    // itself), so do not tell the builder to merge it on GitHub.
+    console.log(hold
+      ? `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge NOT armed: waiting for the artist).`
+      : `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
     const assigneeLine = prAssigneeLine(r.data.pr_assignee);
     if (assigneeLine) console.log(assigneeLine);
+    if (hold) return landHeld({ prUrl: r.data.pr_url || null });
     return pollServerPublish(taskId, branch);
   } finally {
     try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
@@ -858,7 +874,7 @@ function pushCapturing(branch, deps = {}) {
 // ciLandLocal — today's local path: this machine pushes the branch + opens the PR
 // + enables auto-merge via git + gh. async since task 1169 — it asks the server to
 // post the gate-author-trust attestation between the push and the PR open.
-async function ciLandLocal(taskId, branch, valueSummary) {
+async function ciLandLocal(taskId, branch, valueSummary, { hold = false } = {}) {
   const headSha = gitOk('git rev-parse HEAD');
 
   console.log(`  pushing ${branch} to origin...`);
@@ -924,6 +940,12 @@ async function ciLandLocal(taskId, branch, valueSummary) {
     console.log(`  ci-land: reusing open PR ${existing.url}`);
   }
 
+  // task 1004322: a held page tweak stops here — published, never armed.
+  if (hold) {
+    const pr = ghJson(['pr', 'view', branch, '--json', 'number,url,state']);
+    console.log(`  ci-land: PR ${(pr && pr.url) || 'opened'} — auto-merge NOT armed: waiting for the artist.`);
+    return landHeld({ prUrl: (pr && pr.url) || null });
+  }
   console.log('  ci-land: enabling auto-merge (lands when required checks pass)...');
   // task 1718: an enable-failure is NOT a dead-end — the PR is open and the server
   // still lands green PRs. Don't return false (which stranded the builder at
@@ -1075,6 +1097,7 @@ module.exports = {
   LAND_BAIL_NO_TASK_BRANCH,
   landBailRecoverableByPr,
   landBailed,
+  landHeld,
   landPending,
   landPendingLines,
   landPollAfterAutoMerge,

package/scripts/gds/ship-merge.js

@@ -86,6 +86,46 @@ async function autoMerge(taskId, valueSummary, opts = {}, deps = {}) {
   return await land(taskId, branch, valueSummary);
 }
 
+// regenerateShipArtifacts — every generated artifact a branch must carry fresh,
+// in the order the land has always refreshed them. Moved out of mergeLocally
+// unchanged (task 1004322) so the held publish below carries the same set.
+function regenerateShipArtifacts() {
+  regenerateDiagrams();
+  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
+  regenerateRepoMap();
+  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
+  regenerateSessionIndex();
+  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
+  regenerateFileMap();
+  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
+  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
+  // the ship path regenerated it, so the PR was born stale and CI said so.
+  regenerateCopyInventory();
+  // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
+  regenerateApiDocs();
+  // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).
+  regenerateApiClient();
+}
+
+// publishHeld — the held pass's whole "land" (task 1004322, ADR 0341 D7). A page
+// tweak whose grade passed waits at completed for its artist, and the Approval
+// queue shows the APPLIED BRANCH, so the branch and its PR must exist now: a
+// grade-parked ship otherwise never publishes, and the later approve would strand
+// at no_branch_no_tip. This publishes, in every deploy mode, through the PR path
+// (never a local merge to main) and stops: no auto-merge, no poll, no land.
+// `deps` is a test seam only.
+async function publishHeld(taskId, valueSummary, deps = {}) {
+  const branch = (deps.currentBranch || currentBranch)();
+  if (!branch || branch === 'main' || branch === 'HEAD') {
+    return landBailed(
+      `nothing to publish — this checkout is on ${branch}, not the task branch`,
+      onMainNextStep(taskId, (deps.localTaskBranchExists || localTaskBranchExists)(taskId)),
+    ); // untagged on purpose: only autoMerge routes by bail id
+  }
+  (deps.regenerate || regenerateShipArtifacts)();
+  return await (deps.ciLand || ciLand)(taskId, branch, valueSummary, { hold: true });
+}
+
 async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
   const branch = currentBranch();
   if (!branch || branch === 'main' || branch === 'HEAD') {
@@ -116,21 +156,7 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
   // Refresh the data-driven diagrams before computing commits-ahead, so a
   // diagram-only refresh still counts as something to deploy.
-  regenerateDiagrams();
-  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
-  regenerateRepoMap();
-  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
-  regenerateSessionIndex();
-  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
-  regenerateFileMap();
-  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
-  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
-  // the ship path regenerated it, so the PR was born stale and CI said so.
-  regenerateCopyInventory();
-  // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
-  regenerateApiDocs();
-  // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).
-  regenerateApiClient();
+  regenerateShipArtifacts();
 
   // Resolve the deploy mode ONCE (task 1093 / C9) — it reads config/deploy.json;
   // reused at the fetch-bail check + the ci-land branch below.
@@ -422,6 +448,8 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
 module.exports = {
   autoMerge,
+  // task 1004322: the held page tweak's publish-only path.
+  publishHeld,
   // task 1002572 (PART 2): the pure recovery command for a ship run from main —
   // exported so the "don't point back at the dead end" wording is pinned.
   onMainNextStep,

package/scripts/gds/strand-watch.js

@@ -38,6 +38,7 @@
 // Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
 
 const { apiCall, arg, hasFlag } = require('./cli-lib');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 
 // ---- thresholds -------------------------------------------------------------
 // Reasoned, not magic. Written down because a future reader will want to retune them.
@@ -132,6 +133,31 @@ function rankStrands(strands) {
   });
 }
 
+// ---- the held pass (task 1004322, ADR 0341 D7) --------------------------------
+//
+// A page tweak whose grade PASSED waits at `completed` for its artist on purpose:
+// the artist approves the applied page before it lands. It is not a strand and not
+// a failed grade, and calling it one would send someone to /grade-recover a task
+// nobody should touch. The task list carries no grade, so each completed page
+// tweak's grade is read on its own (there are a handful at most; the read is
+// bounded anyway). A read that FAILS leaves the task to the ordinary
+// classification: an unknown must stay loud, never be explained away as a hold.
+const HOLD_READ_LIMIT = 25;
+
+async function heldPageTweaks(tasks, { call, withTimeout }) {
+  const candidates = tasks.filter((t) => t && t.status === 'completed' && tweakHold.isPageTweak(t) && safeId(t.id)).slice(0, HOLD_READ_LIMIT);
+  const held = new Set();
+  await Promise.all(candidates.map(async (t) => {
+    try {
+      const res = await withTimeout(call('GET', `/api/bongos/tasks/${safeId(t.id)}?include=grade`), 'page-tweak grade');
+      const body = res && (res.data || res);
+      const grade = body && body.grade;
+      if (tweakHold.isHeldForArtist(t, grade ? grade.passed : null)) held.add(String(t.id));
+    } catch { /* unknown: classified as usual */ }
+  }));
+  return held;
+}
+
 // ---- fetch ------------------------------------------------------------------
 
 async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
@@ -157,14 +183,23 @@ async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confi
 
   const strands = [];
   const truncated = [];
+  const waiting = [];
+  const completed = (pages.find((p) => p.status === 'completed') || { tasks: [] }).tasks;
+  const held = await heldPageTweaks(completed, { call, withTimeout });
   for (const { status, tasks } of pages) {
     if (tasks.length >= PAGE_LIMIT) truncated.push(status);
     for (const t of tasks) {
+      if (status === 'completed' && held.has(String(t.id))) {
+        const updated = Date.parse(t.updated_at || '');
+        const ageMs = Number.isFinite(updated) ? nowMs - updated : NaN;
+        waiting.push({ id: safeId(t.id), status, ageMs, age: humanAge(ageMs), shape: tweakHold.HOLD_STATE });
+        continue;
+      }
       const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
       if (s) strands.push(s);
     }
   }
-  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated };
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated, waiting };
 }
 
 // ---- rendering --------------------------------------------------------------
@@ -218,6 +253,11 @@ function report(r) {
     console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
     console.log('    so strands older than the cutoff are NOT listed below.');
   }
+  // task 1004322: named, and kept apart from the strands — nobody should recover these.
+  const waiting = Array.isArray(r.waiting) ? r.waiting : [];
+  for (const w of waiting) {
+    console.log(`  task ${w.id}  waiting for the artist (${w.age}) — a page tweak whose grade passed; not a strand, leave it`);
+  }
   if (r.ok) {
     console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
     console.log('');

package/scripts/gds/task.js

@@ -13,6 +13,8 @@
 //   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
+//   bongos task visual <id> <image> --slot <name>       attach/replace a NAMED visual (task 1004322)
+//   bongos task visual <id> --slot <name> --remove      take a named one 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.
@@ -84,6 +86,7 @@ function usage() {
   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('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -174,6 +177,21 @@ async function cmdVisual(args) {
   }
   const api = await cliClient();
 
+  // task 1004322: --slot names the visual (lifecycle_013). Validated here with the
+  // server's own rule, so a bad name costs a retyped command, not an upload.
+  const slot = arg('--slot', args) || null;
+  if (slot !== null && !taskVisuals.isSafeSlot(slot)) {
+    console.error(`--slot "${slot}" is not a slot name: lowercase words joined by dashes, such as ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.`);
+    process.exit(2);
+  }
+  if (slot && hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisualsSlot({ id, slot });
+    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 the "${slot}" visual.`);
+    return;
+  }
+
   if (hasFlag('--remove', args)) {
     const r = await api.tasks.deleteTasksIdVisual({ id });
     if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
@@ -199,14 +217,14 @@ async function cmdVisual(args) {
   }
 
   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 } : {}) },
-  });
+  const body = { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) };
+  const r = slot
+    ? await api.tasks.postTasksIdVisualsSlot({ id, slot, body })
+    : await api.tasks.postTasksIdVisual({ id, body });
   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(`✓ Task #${id} now carries ${slot ? `the "${slot}" visual` : 'a visual'} (${Math.round(visual.buf.length / 1024)} KB).`);
   console.log('  It renders wherever this task\'s value summary does.');
 }
 

package/scripts/gds/tweak-renders.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/tweak-renders.js — the eight renders of a page tweak, shot and
+// attached (task 1004322 / BV2.TW11; ADR 0341 D7 and its builder pick 9).
+//
+// WHY. The artist approves the APPLIED PAGE, not a diff and not a page built from
+// the batch: the Approval queue (TW12) shows images of the applied branch, which
+// is what keeps ADR 0233's "nothing renders a task description as product copy"
+// true. So /tweak renders the page before it applies the batch and again after,
+// on a desktop (1440) and a phone (390), in light and in dark, and attaches the
+// eight pictures to the round's task under their slot names
+// (task-visuals.TWEAK_RENDER_SLOTS: before-desktop-light … after-phone-dark).
+//
+// HOW IT RENDERS. Exactly the way the page reader reads (scripts/gds/page-reader.js):
+// the hall through the hall-preview harness with the pinned fixture account, the
+// landing and status surfaces through the ui-design kit's stub, one browser from
+// the kit's launchBrowser (system Edge or Chrome; nothing is downloaded), the
+// clock pinned, the page's first state from its .states.json. A page that pins
+// one colour mode is shot in that mode for both of its "light" and "dark" slots,
+// and the run says so, rather than inventing a mode the page does not have.
+// Full-page JPEG, so a long page still fits under the store's 4 MB cap.
+//
+// Run:  node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>
+//       node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>   (every slot file in <dir>)
+//       node scripts/gds/tweak-renders.js plan --page <id>              (what would be shot; no browser)
+//
+// Exit: 0 done · 1 a render or an upload failed · 2 usage · 3 no browser.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+const { arg, cliClient, cliExit } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const EXT = 'jpg';
+const JPEG_QUALITY = 82;
+
+// ---- pure ------------------------------------------------------------------
+
+function slotName(phase, device, mode) {
+  return `${phase}-${device}-${mode}`;
+}
+
+// The shots for one phase of one page: one per device x mode, each carrying the
+// slot it fills and the mode the page will actually render in. `plan` is the
+// page's first render plan from page-reader.planRenders.
+function shotsFor(phase, plan) {
+  if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase)) throw new Error(`phase must be one of ${taskVisuals.TWEAK_RENDER_PHASES.join(', ')}`);
+  const pinned = plan && plan.pinnedMode ? plan.pinnedMode : null;
+  const out = [];
+  for (const [device, width] of Object.entries(taskVisuals.TWEAK_RENDER_DEVICES)) {
+    for (const mode of taskVisuals.TWEAK_RENDER_MODES) {
+      out.push({ slot: slotName(phase, device, mode), device, width, mode, renderMode: pinned || mode, file: `${slotName(phase, device, mode)}.${EXT}` });
+    }
+  }
+  return out;
+}
+
+// The page's first render plan, and whether its states file pins a mode. Reads
+// the inventory and the states file; no browser.
+function planForPage(pageId, { inventory, planRenders, root = REPO_ROOT }) {
+  const page = (inventory.pages || []).find((p) => p.id === pageId);
+  if (!page) return { ok: false, code: 'unknown_page', detail: { page: pageId } };
+  const plans = planRenders(page, { root });
+  const plan = plans[0];
+  let modes = null;
+  if (page.states_files && page.states_files.length) {
+    try { modes = JSON.parse(fs.readFileSync(path.join(root, page.states_files[0]), 'utf8')).modes || null; } catch { modes = null; }
+  }
+  const pinnedMode = Array.isArray(modes) && modes.length === 1 ? modes[0] : null;
+  return { ok: true, page, plan: { ...plan, pinnedMode } };
+}
+
+// Which slot files a directory holds, in slot order, and which are missing.
+function slotFilesIn(dir, { exists = (p) => fs.existsSync(p) } = {}) {
+  const found = [];
+  const missing = [];
+  for (const slot of taskVisuals.TWEAK_RENDER_SLOTS) {
+    const hit = ['jpg', 'png', 'webp'].map((e) => path.join(dir, `${slot}.${e}`)).find(exists);
+    if (hit) found.push({ slot, file: hit });
+    else missing.push(slot);
+  }
+  return { found, missing };
+}
+
+// ---- the browser half --------------------------------------------------------
+
+async function shoot({ pageId, phase, out }) {
+  const reader = require('./page-reader.js');
+  const kit = require('../../modules/ui-design/kit/lib');
+  const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+  const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+  if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+  const { page, plan } = planned;
+  const shots = shotsFor(phase, plan);
+  if (plan.pinnedMode) console.log(`tweak-renders: ${pageId} pins the ${plan.pinnedMode} mode, so both of its mode slots are shot in ${plan.pinnedMode}.`);
+  fs.mkdirSync(out, { recursive: true });
+
+  let browser;
+  try { browser = await kit.launchBrowser(); } catch (e) {
+    console.error(`tweak-renders: ${e.message}`);
+    return e instanceof kit.NoBrowserError ? 3 : 1;
+  }
+  const stoppers = [];
+  let failed = 0;
+  try {
+    let base;
+    if (page.surface === 'builders') {
+      const h = await reader.startHarness(kit);
+      stoppers.push(h.stop);
+      base = h.base;
+    } else {
+      const s = await kit.startStub({ surface: reader.SURFACE_MODULE[page.surface] || page.surface, auth: plan.auth, prefix: plan.stub.prefix, child: plan.stub.child, fixtures: plan.stub.fixtures });
+      stoppers.push(s.stop);
+      base = s.base;
+    }
+    for (const shot of shots) {
+      const [W, H] = kit.SIZES[shot.width];
+      const ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1, colorScheme: shot.renderMode });
+      try {
+        if (ctx.clock && typeof ctx.clock.setFixedTime === 'function') await ctx.clock.setFixedTime(new Date(reader.PINNED_CLOCK));
+        const p = await ctx.newPage();
+        p.setDefaultTimeout(6000);
+        p.on('dialog', (d) => { d.dismiss().catch(() => {}); });
+        await p.goto(base + kit.withMode(plan.url, shot.renderMode, plan.modeQuery), { waitUntil: 'load', timeout: 45000 });
+        await p.evaluate(() => document.fonts.ready).catch(() => {});
+        await p.waitForTimeout(kit.SETTLE_MS);
+        try { await kit.runActions(p, plan.actions); } catch (e) { console.log(`  ${shot.slot}: an action failed (${String(e.message).split('\n')[0].slice(0, 100)}); shot as it stood`); }
+        await p.screenshot({ path: path.join(out, shot.file), fullPage: true, type: 'jpeg', quality: JPEG_QUALITY });
+        const kb = Math.round(fs.statSync(path.join(out, shot.file)).size / 1024);
+        console.log(`  ${shot.slot}: ${W}px ${shot.renderMode} -> ${shot.file} (${kb} KB)`);
+      } catch (e) {
+        failed += 1;
+        console.error(`  ${shot.slot}: NOT rendered (${String(e.message).split('\n')[0].slice(0, 160)})`);
+      } finally {
+        await ctx.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    for (const stop of stoppers) stop();
+  }
+  console.log(`tweak-renders: ${shots.length - failed} of ${shots.length} ${phase} render(s) of ${pageId} in ${out}`);
+  return failed ? 1 : 0;
+}
+
+// ---- the upload half ---------------------------------------------------------
+
+async function attach({ taskId, dir }, deps = {}) {
+  const { found, missing } = slotFilesIn(dir, deps);
+  if (!found.length) { console.error(`tweak-renders: no slot files in ${dir} (expected ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.${EXT} and the rest).`); return 1; }
+  const client = deps.client || await cliClient();
+  let failed = 0;
+  for (const { slot, file } of found) {
+    const img = taskVisuals.readImageFile(file);
+    if (!img.ok) { failed += 1; console.error(`  ${slot}: ${img.message}`); continue; }
+    const r = await client.tasks.postTasksIdVisualsSlot({ id: taskId, slot, body: { image_b64: img.buf.toString('base64'), content_type: img.contentType, alt: `${slot.replace(/-/g, ' ')} render of the page` } });
+    if (r.ok) console.log(`  ${slot}: attached (${Math.round(img.buf.length / 1024)} KB)`);
+    else { failed += 1; console.error(`  ${slot}: upload failed (${r.status})`); }
+  }
+  if (missing.length) console.error(`tweak-renders: MISSING ${missing.length} slot(s): ${missing.join(', ')}. The Approval queue shows what is attached; shoot the missing phase and attach again.`);
+  console.log(`tweak-renders: ${found.length - failed} of ${taskVisuals.TWEAK_RENDER_SLOTS.length} render(s) attached to task ${taskId}.`);
+  return failed || missing.length ? 1 : 0;
+}
+
+async function main(args) {
+  const cmd = args[0];
+  if (cmd === 'shoot' || cmd === 'plan') {
+    const pageId = arg('--page', args);
+    if (!pageId) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    if (cmd === 'plan') {
+      const reader = require('./page-reader.js');
+      const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+      const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+      if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+      for (const phase of taskVisuals.TWEAK_RENDER_PHASES) for (const s of shotsFor(phase, planned.plan)) console.log(`${s.slot}\t${s.width}px\t${s.renderMode}\t${planned.plan.url}`);
+      return 0;
+    }
+    const phase = arg('--phase', args);
+    const out = arg('--out', args);
+    if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase) || !out) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    return shoot({ pageId, phase, out: path.resolve(out) });
+  }
+  if (cmd === 'attach') {
+    const taskId = Number(args[1]);
+    const dir = arg('--dir', args);
+    if (!Number.isInteger(taskId) || taskId <= 0 || !dir) { console.error('usage: node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>'); return 2; }
+    return attach({ taskId, dir: path.resolve(dir) });
+  }
+  console.error('usage: node scripts/gds/tweak-renders.js shoot|attach|plan … (see the file header)');
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => cliExit(code), (e) => { console.error(`tweak-renders: ${e.stack || e.message}`); cliExit(1); });
+}
+
+module.exports = { shotsFor, planForPage, attach };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1063'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1064'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');