@bongos/core 1.19.1063 → 1.19.1064

package/tests/page_tweak_hold.mjs

@@ -0,0 +1,265 @@
+// tests/page_tweak_hold.mjs — a passed page tweak waits at completed for its
+// artist, and nothing else changes (task 1004322 / BV2.TW11; ADR 0341 D7).
+//
+// Four carriers, one per thing the TW03 builder listed:
+//   1. applyGrade does not promote a passed page tweak, and every OTHER grade
+//      sends the same SQL as before, plus exactly one read of `source`;
+//   2. publish-branch publishes a held pass without arming auto-merge;
+//   3. ship.js on a held pass publishes (never merges) and says it waits;
+//   4. strand-watch tells a held pass from a failed grade.
+// No DB, no network: fake pools, the real routers, stubbed GitHub reads.
+//
+// Run:  node tests/page_tweak_hold.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const achievements = require('../modules/economy/achievements.js');
+achievements.evaluateAfterShip = async () => [];
+achievements.evaluateAfterCreditAward = async () => [];
+achievements.evaluateAfterClaim = async () => [];
+achievements.reconcileBuilderAchievements = async () => [];
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const { applyGrade } = require('../modules/lifecycle/db.js');
+const hold = require('../modules/lifecycle/page-tweak-hold.js');
+
+const { test, summary } = makeRunner();
+
+const PASS = { score: 0.95, passed: true, threshold: 0.7, grader_kind: 'subagent', grader_version: 't', rubric_scores: {}, signals: {}, issues: [], notes_md: null };
+const FAIL = { ...PASS, score: 0.3, passed: false };
+
+function gradePool({ source }) {
+  return makeSqlAwareClient((s) => {
+    if (/SELECT id, title, status, credits_reward, kind FROM tasks/.test(s)) return { rows: [{ id: 7, title: 'x', status: 'completed', credits_reward: 30, kind: 'feature' }] };
+    if (/^SELECT source FROM tasks/.test(s)) return { rows: [{ source }] };
+    if (/SELECT builder_id FROM claims/.test(s)) return { rows: [{ builder_id: 25 }] };
+    return { rows: [] };
+  });
+}
+const flat = (q) => q.map((x) => String(x.sql).replace(/\s+/g, ' ').trim());
+
+// ---- 1. applyGrade ---------------------------------------------------------
+
+await test('a PASSED page tweak is recorded and HELD: no promotion, no merge, held=true', async () => {
+  const pool = gradePool({ source: 'page-tweak' });
+  const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool });
+  assert.equal(out.taskStatus, 'completed');
+  assert.equal(out.held, true);
+  assert.equal(out.advanceToMerge, false);
+  const q = flat(pool._client.queries);
+  assert.ok(q.some((s) => /^INSERT INTO task_grades/.test(s)), 'the grade row is still written');
+  assert.ok(!q.some((s) => /^UPDATE tasks/.test(s)), 'the task is NOT promoted to confirmed');
+});
+
+await test('an ordinary pass is promoted exactly as before: the same SQL plus ONE read of source', async () => {
+  const pool = gradePool({ source: 'planning-session' });
+  const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool });
+  assert.equal(out.taskStatus, 'confirmed');
+  assert.equal(out.held, false);
+  assert.equal(out.advanceToMerge, true);
+  const q = flat(pool._client.queries);
+  const reads = q.filter((s) => /^SELECT source FROM tasks/.test(s));
+  assert.equal(reads.length, 1, 'one extra read, and only one');
+  // The pre-change statement sequence, with that one read removed, is unchanged.
+  const legacy = q.filter((s) => !/^SELECT source FROM tasks/.test(s));
+  const pool2 = gradePool({ source: null });
+  await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool: pool2 });
+  assert.deepEqual(flat(pool2._client.queries).filter((s) => !/^SELECT source FROM tasks/.test(s)), legacy, 'a null source takes the same path');
+  assert.ok(legacy.some((s) => /^UPDATE tasks SET status = 'confirmed'/.test(s)));
+});
+
+await test('a FAILED grade never asks about the source (the hold is asked only on a pass)', async () => {
+  for (const source of ['page-tweak', 'planning-session']) {
+    const pool = gradePool({ source });
+    const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: FAIL }, { pool });
+    assert.equal(out.taskStatus, 'completed');
+    assert.equal(out.held, false);
+    assert.ok(!flat(pool._client.queries).some((s) => /^SELECT source FROM tasks/.test(s)));
+  }
+});
+
+await test('the hold predicate: only a page tweak, only at completed, only a strict pass', () => {
+  const t = (source, status) => ({ source, status });
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), true), true);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), false), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), null), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'confirmed'), true), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak-unplaced', 'completed'), true), false, 'the engineer task an unplaced line files is ordinary work');
+  assert.equal(hold.isHeldForArtist(t('copy-proposal', 'completed'), true), false);
+  assert.equal(hold.isHeldForArtist(null, true), false);
+});
+
+// ---- 2. publish-branch -----------------------------------------------------
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const db = require('../modules/lifecycle/db.js');
+const gp = require('../modules/lifecycle/github-push.js');
+const prAssign = require('../modules/lifecycle/pr-assign.js');
+const pageTweakReads = require('../modules/lifecycle/page-tweak-reads.js');
+
+let heldNow = false;
+let armCalls = 0;
+api.requireBuilder = (req, res, next) => { req.builder = { id: 1, rank: 'archon', github_login: 'the-archon' }; next(); };
+db.getLastClaimHolder = async () => ({ builder_id: 5, github_login: 'some-builder' });
+db.setClaimPublishedSha = async () => {};
+gp.isConfigured = () => true;
+gp.pushBundle = async () => ({ head_sha: 'a'.repeat(40) });
+gp.openOrFindPullRequest = async () => ({ number: 77, url: 'https://github.com/o/r/pull/77', node_id: 'N' });
+gp.enableAutoMergeDetailed = async () => { armCalls++; return { ok: true }; };
+gp.setCommitStatus = async () => true;
+prAssign.assignPullRequest = async () => ({ assigned: true });
+pageTweakReads.heldForArtistFailClosed = async () => heldNow;
+
+const app = express();
+app.use((req, res, next) => { res.fail = (code, status, extra) => res.status(typeof status === 'number' ? status : (status && status.status) || 500).json({ error: code, ...(extra || {}) }); next(); });
+app.use(require('../modules/lifecycle/routes/tasks.js')());
+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}`;
+const publish = async () => {
+  const res = await fetch(`${base}/tasks/5001/publish-branch`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ branch: 'task-5001', head_sha: 'a'.repeat(40), bundle_b64: Buffer.from('b').toString('base64'), value_summary: 'Page tweak.' }),
+  });
+  return { status: res.status, body: await res.json() };
+};
+
+await test('publish-branch on a HELD pass: the PR is opened, auto-merge is NOT armed, and the reason says why', async () => {
+  heldNow = true; armCalls = 0;
+  const r = await publish();
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.pr_url, 'https://github.com/o/r/pull/77', 'published: the Approval queue can show the branch');
+  assert.equal(r.body.auto_merge, false);
+  assert.equal(armCalls, 0, 'GitHub is never asked to arm it');
+  assert.match(r.body.auto_merge_reason, /artist/);
+});
+
+await test('publish-branch on every other task arms auto-merge exactly as before', async () => {
+  heldNow = false; armCalls = 0;
+  const r = await publish();
+  assert.equal(r.status, 201);
+  assert.equal(r.body.auto_merge, true);
+  assert.equal(armCalls, 1);
+  assert.equal(r.body.auto_merge_reason, undefined);
+});
+server.close();
+
+// ---- 3. ship.js ------------------------------------------------------------
+
+const shipMerge = require('../scripts/gds/ship-merge.js');
+const shipFinish = require('../scripts/gds/ship-finish.js');
+const shipLand = require('../scripts/gds/ship-land.js');
+
+await test('publishHeld publishes through the PR path with hold:true, after the same regeneration a land runs', async () => {
+  const calls = [];
+  const out = await shipMerge.publishHeld(5001, 'sum', {
+    currentBranch: () => 'task-5001',
+    regenerate: () => calls.push('regen'),
+    ciLand: async (id, branch, summary, opts) => { calls.push(['ciLand', id, branch, summary, opts]); return shipLand.landHeld({ prUrl: 'u' }); },
+  });
+  assert.deepEqual(calls, ['regen', ['ciLand', 5001, 'task-5001', 'sum', { hold: true }]]);
+  assert.equal(out.held, true);
+  assert.equal(out.ok, false, 'not a land');
+  assert.equal(out.pending, false, 'and not "landing automatically"');
+});
+
+await test('publishHeld on main has no branch to publish: a named bail, and nothing is pushed', async () => {
+  let pushed = false;
+  const out = await shipMerge.publishHeld(5001, 'sum', { currentBranch: () => 'main', localTaskBranchExists: () => true, regenerate: () => { pushed = true; }, ciLand: async () => { pushed = true; } });
+  assert.equal(pushed, false);
+  assert.equal(out.ok, false);
+  assert.match(out.reason, /not the task branch/);
+  assert.match(out.nextStep, /git checkout task-5001/);
+});
+
+await test('finishHeld says the page is WAITING FOR THE ARTIST, syncs the session, and never merges', async () => {
+  const printed = [];
+  const orig = console.log;
+  console.log = (m) => printed.push(String(m));
+  let synced = null;
+  try {
+    await shipFinish.finishHeld({ taskId: 5001, summary: 's', postGradeStatus: 'completed', card: null }, {
+      publishHeld: async () => shipLand.landHeld({ prUrl: 'https://github.com/o/r/pull/77' }),
+      postShipSync: async (id, status) => { synced = status; return null; },
+      printCompletionCard: async () => {},
+    });
+  } finally { console.log = orig; }
+  const text = printed.join('\n');
+  assert.match(text, /WAITING FOR THE ARTIST/);
+  assert.match(text, /pull\/77/);
+  assert.match(text, /auto-merge is NOT armed/);
+  assert.equal(synced, 'confirmed', 'the finished session is uploaded like a confirmed one');
+});
+
+await test('finishShip routes a held pass away from mergeAndDeploy (the source says so, and only when held)', async () => {
+  const fs = require('node:fs');
+  const src = fs.readFileSync(require.resolve('../scripts/gds/ship-finish.js'), 'utf8');
+  const body = src.slice(src.indexOf('async function finishShip('));
+  const holdAt = body.indexOf('if (held) return finishHeld(');
+  const mergeAt = body.indexOf('await mergeAndDeploy(');
+  assert.ok(holdAt > 0 && mergeAt > holdAt, 'the hold is decided BEFORE any merge is attempted');
+  const flow = fs.readFileSync(require.resolve('../scripts/gds/ship-flow.js'), 'utf8');
+  assert.equal((flow.match(/held = gradePost\.data\.held === true/g) || []).length, 1, 'shipMain reads the hold off the grade response');
+  assert.equal((flow.match(/held: gradePost\.data\.held === true/g) || []).length, 1, 'regradeMain does too');
+  assert.match(flow, /tweakHold\.isHeldForArtist\(task, tRes\.data\.grade/, 'a re-run of a held task re-publishes instead of re-grading');
+});
+
+// ---- 4. strand-watch -------------------------------------------------------
+
+const sw = require('../scripts/gds/strand-watch.js');
+const OLD = new Date(Date.now() - 3 * 86400000).toISOString();
+
+function fakeCall({ completed, grades, throwFor = new Set() }) {
+  const gradeReads = [];
+  const call = async (method, url) => {
+    const m = /\/tasks\/(\d+)\?include=grade/.exec(url);
+    if (m) {
+      gradeReads.push(m[1]);
+      if (throwFor.has(m[1])) throw new Error('boom');
+      return { ok: true, data: { task: {}, grade: grades[m[1]] ?? null } };
+    }
+    if (/status=completed/.test(url)) return { ok: true, data: { tasks: completed } };
+    return { ok: true, data: { tasks: [] } };
+  };
+  return { call, gradeReads };
+}
+
+await test('strand-watch: a held pass is WAITING, not a strand; a failed page tweak and ordinary work still are', async () => {
+  const completed = [
+    { id: '11', status: 'completed', source: 'page-tweak', updated_at: OLD },
+    { id: '12', status: 'completed', source: 'page-tweak', updated_at: OLD },
+    { id: '13', status: 'completed', source: 'planning-session', updated_at: OLD },
+  ];
+  const f = fakeCall({ completed, grades: { 11: { passed: true }, 12: { passed: false } } });
+  const r = await sw.check({ call: f.call });
+  assert.deepEqual(r.waiting.map((w) => w.id), ['11']);
+  assert.equal(r.waiting[0].shape, 'waiting_for_artist');
+  assert.deepEqual(r.strands.map((s) => s.id).sort(), ['12', '13']);
+  assert.deepEqual(f.gradeReads.sort(), ['11', '12'], 'grades are read for page tweaks only');
+  assert.ok(!(sw.line(r) || '').includes('task 11'), 'the session-start line never names a held pass');
+});
+
+await test('strand-watch: an unreadable grade stays LOUD (classified as usual), never explained away as a hold', async () => {
+  const f = fakeCall({ completed: [{ id: '11', status: 'completed', source: 'page-tweak', updated_at: OLD }], grades: {}, throwFor: new Set(['11']) });
+  const r = await sw.check({ call: f.call });
+  assert.deepEqual(r.waiting, []);
+  assert.deepEqual(r.strands.map((s) => s.id), ['11']);
+});
+
+await test('/grade-recover stops on a held pass instead of recovering it', () => {
+  const fs = require('node:fs');
+  const p = new URL('../.claude/skills/grade-recover/SKILL.md', import.meta.url);
+  if (!fs.existsSync(p)) return;
+  const md = fs.readFileSync(p, 'utf8');
+  assert.match(md, /waiting for the artist/);
+  assert.match(md, /page-tweak/);
+});
+
+summary();

package/tests/publish_status_branch.mjs

@@ -18,6 +18,10 @@ const require = createRequire(import.meta.url);
 
 const gp = require('../modules/lifecycle/github-push.js');
 const buildTasksRouter = require('../modules/lifecycle/routes/tasks.js');
+// task 1004322: the route asks whether the task is a page tweak held for its
+// artist before it nudges a merge. That read goes to the DB, so the harness
+// stubs it (false = an ordinary task, the case every test below was written for).
+const pageTweakReads = require('../modules/lifecycle/page-tweak-reads.js');
 
 let pass = 0;
 let fail = 0;
@@ -33,6 +37,8 @@ const CRED_KEYS = ['GITHUB_PUSH_TOKEN', 'GITHUB_APP_ID', 'GITHUB_APP_INSTALLATIO
 async function callRoute(query, stubs = {}) {
   const saved = {};
   for (const k of ['findTaskPullRequest', 'getPublishStatus', 'mergeIfGreen']) saved[k] = gp[k];
+  const savedHold = pageTweakReads.heldForArtistFailClosed;
+  pageTweakReads.heldForArtistFailClosed = async () => stubs.held === true;
   const savedEnv = CRED_KEYS.map((k) => [k, process.env[k]]);
   const calls = { findTaskPullRequest: [], getPublishStatus: [], mergeIfGreen: [] };
   gp.findTaskPullRequest = async (a) => { calls.findTaskPullRequest.push(a); return stubs.taskPr === undefined ? null : stubs.taskPr; };
@@ -58,6 +64,7 @@ async function callRoute(query, stubs = {}) {
     return { ...out, calls };
   } finally {
     Object.assign(gp, saved);
+    pageTweakReads.heldForArtistFailClosed = savedHold;
     for (const [k, v] of savedEnv) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
   }
 }
@@ -124,5 +131,21 @@ await t('a genuinely unsafe branch is still refused 400 — in a sentence, befor
   }
 });
 
+await t('a page tweak held for its artist is reported but NEVER nudged to merge (task 1004322, ADR 0341 D7)', async () => {
+  const r = await callRoute({}, { held: true, taskPr: { branch: 'task-1003747', pr_number: 673, pr_state: 'open', merged: false } });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.ok, true, 'the status is still answered: the Approval queue reads it');
+  assert.equal(r.body.pr_number, 673);
+  assert.deepEqual(r.calls.mergeIfGreen, [], 'a held pass must not be merged by a status poll');
+  assert.equal(r.body.merge_driver, null);
+});
+
+await t('the hold read failing is treated as held: fail-closed, no nudge (task 1004322)', async () => {
+  const real = pageTweakReads.heldForArtistFailClosed;
+  assert.equal(await real(1, async () => { throw new Error('db down'); }), true, 'a throwing read answers held');
+  assert.equal(await real(1, async () => ({ held: false })), false);
+  assert.equal(await real(1, async () => ({ held: true })), true);
+});
+
 console.log(`\npublish-status branch resolution (task 1003764): ${pass} passed, ${fail} failed`);
 process.exitCode = fail > 0 ? 1 : 0;

package/tests/task_visual_slots.mjs

@@ -0,0 +1,161 @@
+// tests/task_visual_slots.mjs — task visuals widened to NAMED slots, and the
+// eight page-tweak renders attached to them (task 1004322 / BV2.TW11;
+// lifecycle_013; ADR 0341 D7, builder pick 9).
+//
+// Drives the real routes/visuals.js router with the slot queries stubbed at the
+// module boundary and a temp store, then the pure halves of tweak-renders.js and
+// its attach step against a fake client. No DB, no network, no browser.
+//
+// Run:  node tests/task_visual_slots.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';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'tw11-slots-'));
+process.env.TASK_VISUALS_DIR = path.join(TMP, 'store');
+
+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');
+const renders = require('../scripts/gds/tweak-renders.js');
+
+const { test, summary } = makeRunner();
+
+// A 1x1 PNG, real enough for the magic-byte sniff.
+const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
+
+const slots = new Map(); // `${task}|${slot}` -> row
+visualDb.getTaskVisualAccess = async (id) => ({ id, status: 'completed', security_sensitive: false, visual_url: null });
+visualDb.setTaskVisualSlot = async ({ taskId, slot, visualUrl, visualAlt }) => {
+  const k = `${taskId}|${slot}`;
+  const prev = slots.get(k);
+  slots.set(k, { slot, visual_url: visualUrl, visual_alt: visualAlt, updated_at: 't' });
+  return { slot, visual_url: visualUrl, visual_alt: visualAlt, replaced_url: prev ? prev.visual_url : null };
+};
+visualDb.deleteTaskVisualSlot = async ({ taskId, slot }) => { const k = `${taskId}|${slot}`; const p = slots.get(k); slots.delete(k); return p ? p.visual_url : null; };
+visualDb.listTaskVisualSlots = async (taskId) => [...slots.entries()].filter(([k]) => k.startsWith(`${taskId}|`)).map(([, v]) => v).sort((a, b) => (a.slot < b.slot ? -1 : 1));
+let rank = 'archon';
+api.requireBuilder = (req, res, next) => { req.builder = { id: 1, rank, github_login: 'x' }; next(); };
+
+const app = express();
+app.use((req, res, next) => { res.fail = (code, status, extra) => res.status(typeof status === 'number' ? status : (status && status.status) || 500).json({ error: code, ...(extra || {}) }); next(); });
+app.use(require('../modules/lifecycle/routes/visuals.js')());
+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}`;
+const call = async (method, url, body) => {
+  const res = await fetch(base + url, { method, headers: { 'Content-Type': 'application/json' }, body: body ? JSON.stringify(body) : undefined });
+  return { status: res.status, body: await res.json() };
+};
+const png = { image_b64: PNG.toString('base64'), content_type: 'image/png' };
+const stored = () => fs.existsSync(process.env.TASK_VISUALS_DIR) ? fs.readdirSync(process.env.TASK_VISUALS_DIR) : [];
+
+await test('the eight render slots are declared once: before/after x desktop/phone x light/dark', () => {
+  assert.equal(visuals.TWEAK_RENDER_SLOTS.length, 8);
+  assert.equal(new Set(visuals.TWEAK_RENDER_SLOTS).size, 8);
+  for (const s of visuals.TWEAK_RENDER_SLOTS) assert.ok(visuals.isSafeSlot(s), s);
+  assert.deepEqual(visuals.TWEAK_RENDER_DEVICES, { desktop: 1440, phone: 390 }, 'the spec widths: 1440 and 390');
+  const sql = fs.readFileSync(new URL('../modules/lifecycle/migrations/lifecycle_013_task_visual_slots.sql', import.meta.url), 'utf8');
+  const re = new RegExp(/slot ~ '([^']+)'/.exec(sql)[1]);
+  for (const s of visuals.TWEAK_RENDER_SLOTS) assert.ok(re.test(s), `the column CHECK admits ${s}`);
+  for (const bad of ['', 'Before', '../x', 'a b', 'x'.repeat(49), 'a--b']) assert.equal(visuals.isSafeSlot(bad), false, JSON.stringify(bad));
+});
+
+await test('POST a named slot stores the image and lists it; the one ship-time visual is untouched', async () => {
+  const r = await call('POST', '/tasks/5001/visuals/after-phone-dark', png);
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.slot, 'after-phone-dark');
+  assert.match(r.body.visual_url, /^\/api\/bongos\/task-visuals\/task-5001-[0-9a-f]{16}\.png$/, 'the same store and serve path as the one visual');
+  const l = await call('GET', '/tasks/5001/visuals');
+  assert.deepEqual(l.body.slots.map((x) => x.slot), ['after-phone-dark']);
+  assert.equal(stored().length, 1);
+});
+
+await test('attaching a slot again REPLACES it and unlinks the superseded file', async () => {
+  const before = stored();
+  const r = await call('POST', '/tasks/5001/visuals/after-phone-dark', png);
+  assert.equal(r.status, 201);
+  const after = stored();
+  assert.equal(after.length, 1, 'one file per slot on disk');
+  assert.notDeepEqual(after, before);
+});
+
+await test('a bad slot name is refused before any byte is stored; a non-image is refused', async () => {
+  const n = stored().length;
+  assert.equal((await call('POST', '/tasks/5001/visuals/Not%20A%20Slot', png)).status, 400);
+  const r = await call('POST', '/tasks/5001/visuals/before-desktop-light', { image_b64: Buffer.from('<svg/>').toString('base64'), content_type: 'image/png' });
+  assert.equal(r.status, 400);
+  assert.equal(stored().length, n);
+});
+
+await test('only the claim holder or an Archon may attach (the one visual\'s own gate)', async () => {
+  rank = 'thetes';
+  const routes = require('../modules/lifecycle/routes/tasks.js');
+  const src = fs.readFileSync(require.resolve('../modules/lifecycle/routes/visuals.js'), 'utf8');
+  const post = src.slice(src.indexOf("router.post('/tasks/:id/visuals/:slot'"), src.indexOf("router.delete('/tasks/:id/visuals/:slot'"));
+  const del = src.slice(src.indexOf("router.delete('/tasks/:id/visuals/:slot'"), src.indexOf("router.get('/tasks/:id/visuals'"));
+  for (const body of [post, del]) assert.match(body, /gateTaskOwnership\(req, res, id\)/);
+  assert.ok(routes.gateTaskOwnership, 'the shared gate is the one used');
+  rank = 'archon';
+});
+
+await test('DELETE a slot removes its row and its file, and is idempotent', async () => {
+  const r = await call('DELETE', '/tasks/5001/visuals/after-phone-dark');
+  assert.equal(r.status, 200);
+  assert.equal(stored().length, 0);
+  assert.equal((await call('DELETE', '/tasks/5001/visuals/after-phone-dark')).status, 200);
+  assert.deepEqual((await call('GET', '/tasks/5001/visuals')).body.slots, []);
+});
+server.close();
+
+// ---- tweak-renders.js -------------------------------------------------------
+
+await test('shotsFor names one file per slot; a page pinning one mode is shot in it for both mode slots', () => {
+  const free = renders.shotsFor('before', { pinnedMode: null });
+  assert.deepEqual(free.map((s) => s.slot), visuals.TWEAK_RENDER_SLOTS.filter((s) => s.startsWith('before-')));
+  assert.deepEqual(free.map((s) => s.renderMode), ['light', 'dark', 'light', 'dark']);
+  const pinned = renders.shotsFor('after', { pinnedMode: 'dark' });
+  assert.deepEqual(pinned.map((s) => s.renderMode), ['dark', 'dark', 'dark', 'dark']);
+  assert.throws(() => renders.shotsFor('during', {}));
+});
+
+await test('planForPage reads the real inventory: an unknown page is refused, a known one has a url', () => {
+  const reader = require('../scripts/gds/page-reader.js');
+  const inventory = JSON.parse(fs.readFileSync(new URL('../docs/page-inventory.json', import.meta.url), 'utf8'));
+  assert.equal(renders.planForPage('nope:nope', { inventory, planRenders: reader.planRenders }).code, 'unknown_page');
+  const p = renders.planForPage(inventory.pages[0].id, { inventory, planRenders: reader.planRenders });
+  assert.equal(p.ok, true);
+  assert.ok(typeof p.plan.url === 'string' && p.plan.url.startsWith('/'));
+});
+
+await test('attach uploads every slot file in the directory to its NAMED slot, and names the missing ones', async () => {
+  const dir = path.join(TMP, 'shots');
+  fs.mkdirSync(dir, { recursive: true });
+  const present = visuals.TWEAK_RENDER_SLOTS.slice(0, 6);
+  for (const s of present) fs.writeFileSync(path.join(dir, `${s}.png`), PNG);
+  const posts = [];
+  const client = { tasks: { postTasksIdVisualsSlot: async (a) => { posts.push(a); return { ok: true, status: 201 }; } } };
+  const errs = [];
+  const origErr = console.error, origLog = console.log;
+  console.error = (m) => errs.push(String(m)); console.log = () => {};
+  let code;
+  try { code = await renders.attach({ taskId: 5001, dir }, { client }); } finally { console.error = origErr; console.log = origLog; }
+  assert.deepEqual(posts.map((p) => p.slot), present);
+  assert.ok(posts.every((p) => p.id === 5001 && p.body.content_type === 'image/png'));
+  assert.equal(code, 1, 'a missing slot is not a success');
+  assert.ok(errs.some((m) => m.includes('after-phone-light') && m.includes('after-phone-dark')), 'the missing slots are named');
+  for (const s of visuals.TWEAK_RENDER_SLOTS.slice(6)) fs.writeFileSync(path.join(dir, `${s}.png`), PNG);
+  console.log = () => {};
+  try { code = await renders.attach({ taskId: 5001, dir }, { client }); } finally { console.log = origLog; }
+  assert.equal(code, 0, 'all eight attached');
+});
+
+fs.rmSync(TMP, { recursive: true, force: true });
+summary();